# Incitaciones 🤖

[![npm](https://img.shields.io/npm/v/incitaciones)](https://www.npmjs.com/package/incitaciones)
[![Publish to npm](https://github.com/charly-vibes/incitaciones/actions/workflows/npm-publish.yml/badge.svg)](https://github.com/charly-vibes/incitaciones/actions/workflows/npm-publish.yml)

A collection of reusable prompts and best practices for CLI LLM tools.

## Quick Install

### Via npm / npx (recommended)

```bash
# Install as pi package (native skills, best UX):
pi install npm:incitaciones

# Or install across all tools (pi, Claude Code, Amp, Gemini CLI, etc.):
npx incitaciones install

# Install only the essentials bundle:
npx incitaciones install --bundle essentials

# List available skills:
npx incitaciones list

# Show skill details:
npx incitaciones info commit
```

### From git

Clone and install prompts as skills for pi CLI, Claude Code, Amp, Gemini CLI, and other tools:

```bash
git clone https://github.com/charly-vibes/incitaciones.git
cd incitaciones
./install.sh
```

**Install options:**

```bash
./install.sh --bundle essentials    # Core prompts only
./install.sh --bundle planning      # Planning workflows
./install.sh --bundle reviews       # Review prompts
./install.sh --bundle documentation # Documentation tools
./install.sh --format commands      # Legacy flat-file format for other tools
./install.sh --disable-model-invocation # Require explicit /skill:name usage
./install.sh --list                 # Show available prompts
./install.sh --help                 # Show all options
```

**After installation:**
```
# pi CLI native skill invocation
/skill:commit
/skill:debug
/skill:create-plan

# pi CLI prompt-template shortcuts
/commit
/debug
/create-plan

# Other compatible tools
/debug
/create-plan
/code-review
```

For non-pi tools, exact command syntax depends on the harness, but slash-command usage like the examples above is the common case.

Skills are installed to `~/.agents/skills/` (or project `.agents/skills/`) and copied to tool-specific directories when detected. For pi, skills are discovered from `.agents/skills/` / `~/.agents/skills/`, and the installer also writes prompt templates to `~/.pi/agent/prompts/` or project `.pi/prompts/` so pi users can invoke either `/skill:<name>` or the shorter `/<name>` template command.

### Native pi package install

This repository is published as an npm package with a `pi` manifest, so pi can install it directly:

```bash
pi install npm:incitaciones
# or from git
pi install git:github.com/charly-vibes/incitaciones
# or from a local clone
pi install .
```

The repository includes checked-in pi package resources under `pi-package/`, and the generation step can refresh them when content changes:

- `pi-package/skills/` — Agent Skills with pi-compatible frontmatter
- `pi-package/prompts/` — prompt templates for slash-command shortcuts

After changing distilled content or manifest entries, run `just generate-pi-resources` and commit the updated `pi-package/` files.

### Publishing a new version

```bash
npm version patch   # bumps to 0.2.1, creates a git tag
npm version minor   # bumps to 0.3.0
npm version major   # bumps to 1.0.0

git push --tags     # triggers CI → auto-publishes to npm
```

CI workflow: `.github/workflows/npm-publish.yml` — runs on `v*` tags, generates pi resources, then publishes.

## Top 10 Most Used Skills

Based on analysis of 621 pi sessions across 43 repositories:

| Skill | Invocations | Repos | What it does |
|-------|:-----------:|:-----:|-------------|
| **commit** | 513 | 41 | Create well-structured, atomic git commits with clear intent |
| **rule-of-5-universal** | 254 | 35 | 5-stage review for any artifact (Steve Yegge's method) |
| **tdd** | 168 | 28 | Test-driven development workflow |
| **issue-review** | 158 | 31 | Review issues for completeness and dependencies |
| **debug** | 94 | 27 | 7-step diagnostic workflow for debugging issues |
| **create-issues** | 44 | 19 | Generate trackable issues from implementation plans |
| **create-handoff** | 31 | 10 | Generate context documents for session continuity |
| **grill-me** | 28 | 12 | Interview the user relentlessly about a plan or design |
| **doc-link-verifier** | 27 | 9 | Audit documentation for broken links |
| **review-documentation** | 27 | 9 | Review docs for cognitive scannability and AI-readiness |

## Session Lifecycle & Knowledge Management

Workflow skills that form a complete session lifecycle with persistent operational knowledge:

| Skill | When | What it does |
|-------|------|-------------|
| **whisper** | Start of project/branch | Manage `~/.whisper/` — global, tiered knowledge directory (init, check, status, link, decommission) |
| **next** | Quick context switch | Rapid snapshot to `~/.whisper/` — no git, no tickets, just stash |
| **park** | Thorough context switch | Log to journal, release ticket claims, record to beads epic |
| **close** | End of day | Log to journal, route knowledge to `~/.whisper/`, commit, clear |
| **renew** | Start of session | Load journal + whisper + beads context, claim tickets with file conflict detection |

Uses `$JOURNAL_PATH` (default `~/dev/status`) for the daily log. See [`content/references-whisper-workflow.md`](content/references-whisper-workflow.md) for the full reference.

Full analysis: [`content/research-finding-skill-usage-analysis.md`](content/research-finding-skill-usage-analysis.md)

## Quick Start

```bash
# Browse content
ls content/

# Find prompts about a topic
just find refactoring

# Create new prompt scaffold
just new prompt "Your Task Name"

# Interactive search with fzf
just search
```

## Structure

Everything lives in `content/` with descriptive filenames:

- `prompt-*.md` - Reusable prompts (source)
- `distilled/` - Optimized prompts for agent consumption (single file or multi-file)
- `research-*.md` - Experiments and findings
- `example-*.md` - Real-world examples
- `template-*.md` - Templates for new content

Key infrastructure files:

- `package.json` — npm package with `pi` manifest and `bin` entry for npx CLI
- `scripts/cli.mjs` — npx CLI entry point (`npx incitaciones install` / `list` / `info`)
- `scripts/generate-pi-resources.mjs` — generates `pi-package/` from manifest
- `pi-package/` — generated pi-compatible skills and prompt templates (gitignored)
- `.github/workflows/npm-publish.yml` — CI: auto-publishes to npm on `v*` tags
- `.github/workflows/pages.yml` — CI: deploys GitHub Pages site

See [AGENTS.md](AGENTS.md) for detailed structure and [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## Commands

```bash
just --list              # Show all commands
just new [type] [name]   # Create new content
just find [term]         # Search content
just search              # Interactive fzf search
just validate            # Check metadata
just stats               # Show statistics

# Skills installation
just install                  # Run ./install.sh with any flags you pass through
just generate-pi-resources    # Build pi package skills + prompt templates
just validate-pi-package      # Verify pi package resources match the manifest
just list-distilled           # List all distilled prompts
just validate-distilled       # Validate distilled prompts
just list-bundles             # Show available bundles
just sync-manifest            # Validate manifest references and update content/manifest.json version
just generate-skill NAME      # Preview SKILL.md output for a prompt
just nucleus-roundtrip NAME   # Use pi to compile+decompile a prompt via Nucleus lambda
just compare-nucleus NAME     # Diff a Nucleus roundtrip against the canonical distilled prompt
just analyze-traces PATH      # Analyze trace exports from agent tools
just analyze-traces-auto      # Auto-detect local CLI history locations
just trace-insights           # Process traces and write insight artifacts
```

## Trace Analysis

You can analyze exported traces from Claude, Gemini, Codex, AmpCode, and OpenCode with:

```bash
just analyze-traces examples/trace-analysis
```

If your histories live in the default local CLI directories, use auto-detection:

```bash
just analyze-traces-auto
```

Or directly:

```bash
node scripts/analyze-traces.js --auto-detect --format markdown
```

For the simplest workflow, use the wrapper command:

```bash
just trace-insights
```

That will:

- auto-detect local trace sources
- print a readable markdown summary
- write `.cache/trace-insights/latest-report.json`
- write `.cache/trace-insights/session-records.jsonl`
- write `.cache/trace-insights/label-queue.jsonl`

The analyzer now uses an incremental cache at `.cache/trace-analysis-cache.json`.
Unchanged files are reused automatically on later runs. Use `--no-cache` if you want a full recomputation.

It can also emit normalized session records and join manual labels:

```bash
node scripts/analyze-traces.js \
  --auto-detect \
  --session-records-out /tmp/session-records.jsonl \
  --label-queue-out /tmp/label-queue.jsonl
```

To join labels back into the analysis:

```bash
node scripts/analyze-traces.js \
  --auto-detect \
  --labels examples/trace-analysis/labels-sample.jsonl \
  --format markdown
```

Or with the wrapper:

```bash
just trace-insights --labels examples/trace-analysis/labels-sample.jsonl
```

This scans JSON, JSONL, NDJSON, log, text, and markdown exports, then reports:

- provider mix
- prompt references matched against `content/manifest.json`
- skill format counts (`single-file` vs `progressive-disclosure`)
- progressive-disclosure reference mentions and stage hints
- slash commands
- tool and model usage
- prompt-to-tool pairs
- workflow transitions
- heuristic session outcomes
- rough conclusions across the analyzed traces

For raw JSON output:

```bash
node scripts/analyze-traces.js examples/trace-analysis --format json
```

The new session-level signals are heuristic, not authoritative:

- `prompt -> tool` pairs estimate when a prompt mention actually led to tool execution
- `workflow transitions` show common session shapes like `prompt -> tool` or `user -> assistant`
- `outcomes` classify sessions as `succeeded`, `failed`, `needs_input`, or `unknown` from assistant language

This is strongest for comparative usage analysis, not for hard evaluation of prompt quality.

Normalized session records include fields such as:

- `session_id`
- `provider`
- `model`
- `task_type`
- `prompts_used`
- `skill_formats`
- `progressive_skills_used`
- `references_used`
- `stage_hints`
- `tools_used`
- `tests_run_or_mentioned`
- `verification_present`
- `commit_created`
- `tokens_total`
- `turn_count`
- `outcome_guess`
- `first_user_excerpt`
- `last_assistant_excerpt`

The label queue is intended for manual annotation. Each queued record includes suggested questions so you can build a labeled evaluation set over time.

For progressive-disclosure skills, the analyzer now reads optional manifest metadata such as `skill_format`, `eval.stages`, and `eval.references`. That makes it possible to compare not just prompt usage, but also which stages and reference files were actually involved in successful sessions.

The aggregate report now separates adoption from evidence:

- `Top Skills By Session` and `Skill Formats By Session` count each skill at most once per session.
- `Top References By Session` and `Top Stages By Session` count whether a reference or stage appeared in a session.
- `Skill Evidence Hits`, `Top Reference Evidence Hits`, and `Top Stage Evidence Hits` count repeated detections across messages and tool inputs.

Use the session-level sections for effectiveness comparisons. Use the evidence-hit sections to understand how often the analyzer observed supporting signals.

Current auto-detected sources include common local paths such as:

- `~/.claude/projects`
- `~/.gemini/tmp/**/chats/session-*.json`
- `~/.codex/history.jsonl`
- `~/.codex/log/codex-tui.log`

AmpCode and OpenCode are only included when conversation-like files are found.

---

## Meta Prompt for LLMs

> **Use this prompt when asking other LLMs to help you organize prompts in your projects**

```
I want to organize prompts and AI instructions for my project. Please help me set up a system based on these principles:

STRUCTURE:
- Single flat directory (e.g., "prompts/" or ".ai/")
- Slugified filenames with type prefixes:
  - prompt-task-{name}.md for specific tasks
  - prompt-system-{name}.md for agent configurations
  - prompt-workflow-{name}.md for multi-step processes
  - instructions-{context}.md for project-specific instructions

METADATA:
Every file should have YAML frontmatter:
---
title: Human Readable Title
type: prompt|instruction|workflow
tags: [relevant, searchable, tags]
tools: [claude-code, cursor, aider]
status: draft|tested|verified
created: YYYY-MM-DD
updated: YYYY-MM-DD
version: 1.0.0
related: [other-file.md]
source: where-this-came-from
---

CONTENT STRUCTURE:
1. ## When to Use - Context for applying this prompt
2. ## The Prompt - The actual prompt text in a code block
3. ## Example - At least one concrete usage example
4. ## Expected Results - What success looks like
5. ## Variations - Alternative approaches
6. ## References - Links to sources or research
7. ## Notes - Caveats or additional context

WORKFLOW:
1. Create content from templates
2. Test with real AI tools
3. Update status: draft → tested → verified
4. Link related files in frontmatter
5. Track changes in CHANGELOG.md

AUTOMATION:
Create a justfile or Makefile with commands:
- new: Create from template
- find: Search by tag or keyword
- search: Interactive fzf browser
- validate: Check metadata completeness
- stats: Show repository statistics

Please analyze my project at [path] and:
1. Propose which existing prompts/instructions to capture
2. Suggest an appropriate directory name
3. Create initial template files
4. Set up basic automation commands
5. Draft 2-3 initial prompt files based on current usage

Focus on simplicity and discoverability over complex organization.
```

## Examples

**Creating a new task prompt:**
```bash
just new prompt "Incremental Refactoring"
# Edit content/prompt-task-incremental-refactoring.md
# Edit content/distilled/incremental-refactoring.md (or create a directory for multi-file)
# Add prompt text, examples, and distilled runtime form
# Register the prompt in content/manifest.json
# Run just validate-distilled && just sync-manifest
# Test it with Claude Code
# Mark as tested and commit
```

**Finding related content:**
```bash
just find refactoring
# Shows all files tagged with 'refactoring'

just search
# Opens fzf to interactively browse and preview content
```

**Validating content:**
```bash
just validate
# Checks required metadata, status values, and related links
# Reports any issues
```

**Experimenting with Nucleus lambda roundtrips:**
```bash
just nucleus-roundtrip distill-prompt
# Uses pi -p to compile the distilled prompt to lambda and decompile it back to prose
# Writes content/compiled/nucleus/distill-prompt.lambda.md
# Writes content/compiled/nucleus/distill-prompt.roundtrip.md
just compare-nucleus distill-prompt
# Diffs the roundtrip prose against the canonical distilled prompt
```

Pass extra pi flags through when needed:
```bash
just nucleus-roundtrip distill-prompt --model sonnet:high
```

The `content/compiled/nucleus/` directory is experimental. It is intentionally kept outside `content/distilled/` so these comparison artifacts do not affect installation or packaged skills.

## What Goes Here?

✅ **Good candidates:**
- Prompts you use repeatedly
- Task patterns that work well
- Tool-specific configurations
- Research on what works
- Real examples of successful interactions

❌ **Don't include:**
- Project-specific code
- Sensitive information
- One-off experiments without documentation
- Incomplete drafts without context

## Philosophy

**Flat structure** - One directory, easy to find everything
**Rich metadata** - Searchable, relatable, trackable
**Tested content** - Everything should have real usage examples
**Source attribution** - Credit where ideas come from
**Version control** - Track evolution of prompts over time

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for:
- File naming conventions
- Metadata requirements
- Quality standards
- Submission process

## Tools

This repository is designed to work with:
- **Claude Code** - Anthropic's CLI
- **Aider** - AI pair programming
- **Cursor** - AI-first editor
- **Gemini CLI** - Google's CLI
- Any other LLM CLI tool

The prompts are tool-agnostic where possible, with tool-specific variations noted.

## License

[To be determined]

## Related Projects

- [Awesome Prompts](https://github.com/f/awesome-chatgpt-prompts)
- [Anthropic Prompt Library](https://docs.anthropic.com/claude/prompt-library)
- [OpenAI Prompt Engineering Guide](https://platform.openai.com/docs/guides/prompt-engineering)


---

## A note on authorship

All the code in this repository was generated by a large language model. This is not a confession, nor an apology. It's a fact, like the one that says water boils at a hundred degrees at sea level: neutral, technical, and with consequences one discovers later.

What the human did is what tends to happen before and after things come into existence: thinking. Reviewing requirements, arguing about edge cases, understanding what needs to be built and why, deciding how the system should behave when reality —which is capricious and does not read documentation— confronts it with situations nobody anticipated. The hours of planning, of design, of reading specifications until exhaustion dissolves the boundary between understanding and hallucination.

The LLM writes. The human knows what it should say.

There is a distinction, even if looking at the commit history makes it hard to find. The distinction is that a machine can produce correct code without understanding anything, the same way a calculator can solve an integral without knowing what time is. Understanding what that integral is *for*, whether it actually solves the problem, whether the problem was the right problem to begin with — that remains human territory. For now.

[Leer en español](https://charly-vibes.github.io/charly-vibes/)