incitaciones 0.2.0 → 0.3.0

package/README.md

@@ -1,5 +1,8 @@
 # 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
@@ -87,6 +90,51 @@ The repository includes checked-in pi package resources under `pi-package/`, and
 
 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
@@ -113,6 +161,15 @@ Everything lives in `content/` with descriptive filenames:
 - `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

package/content/distilled/close/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: close
+description: "End-of-session wrap-up. Summarizes what was done, logs it to the daily journal, commits, pushes, and clears context. Trigger when the user says '/close', 'close session', or 'wrap up session'."
+tools: Read, Write, Edit, Glob, Bash
+---
+
+# Close Session
+
+End the current session: log what was done, update tasks, route durable knowledge to `~/.whisper/`, commit and push, clear context.
+
+Uses `$JOURNAL_PATH` (defaults to `~/dev/status`) for the daily log, and `~/.whisper/` for accumulated operational knowledge.
+
+## Steps
+
+1. Pull the journal repo:
+   ```bash
+   JOURNAL="${JOURNAL_PATH:-$HOME/dev/status}"
+   cd "$JOURNAL" && git pull
+   ```
+
+2. Get today's date and time (`date +%Y-%m-%d`, `date +%H:%M`).
+   Derive the log path: `$JOURNAL/log/YYYY/YYYY-MM/YYYY-MM-DD.md`
+
+3. If the log file does not exist, create it with the daily log template.
+
+4. Review the full conversation history and write a concise session summary covering:
+   - What was worked on (key topics, files, repos)
+   - Decisions made
+   - Tasks completed or created
+   - Any unresolved items or next steps
+
+5. Append the summary to the `## Log` section of today's daily log:
+   ```
+   ### Session:HH:MM (<context>)
+   - bullet point summary entries
+   - **Next:** what to pick up next time (if applicable)
+   ```
+
+6. Update project/area files if tasks were completed or created:
+   - Mark completed tasks `[x]`
+   - Add new tasks as `[ ]`
+   - Add/update `[~]` waiting items
+   - Update `## Notes` with decisions
+
+7. If any tasks or follow-ups came up that aren't in a project/area, add them to `inbox.md`.
+
+8. **Route durable knowledge to `~/.whisper/`.** Scan the session for anything worth keeping and route by scope (skip this step entirely if nothing durable was learned):
+   - **Branch-specific finding** → `bd note <beads-epic>` or `~/.whisper/repos/<repo>/branches/<slug>/notes.md`
+   - **Repo-wide infra fact** → `~/.whisper/repos/<repo>/env.md`
+   - **Universal agent behavior rule** → `bd remember` or `~/.whisper/rules.md`
+   - **Worktree setup fact** → `~/.whisper/repos/<repo>/worktrees/<name>/env.md`
+   - **No secrets anywhere:** never write tokens, keys, or PII
+   - **Extend, don't duplicate:** append to existing notes rather than creating new ones
+
+9. Commit and push. Stage only the files this session touched, explicitly by name:
+   ```bash
+   cd "$JOURNAL" && git add <log-file> [<files>] && git commit -m "log: YYYY-MM-DD session notes" && git push
+   ```
+
+10. As the very last step, run `/clear` to reset the conversation context.
+
+## Rules
+
+- Do NOT ask the user any questions. Summarize automatically from conversation context.
+- Keep the summary concise — bullet points, not paragraphs.
+- If today's log already has content, append to it; never overwrite existing entries.
+- Always pull before reading and push after committing.

package/content/distilled/create-issues/SKILL.md

@@ -54,6 +54,16 @@ You are a Technical Project Manager. Translate a plan, spec, or PRD into thin en
    - Apply tracker labels such as `needs-triage` when the project uses them.
    - Wire dependencies using actual captured identifiers or explicit body references.
    - Verify each creation step succeeded before continuing.
+   - **After each successful creation**, extract the `**Files / Systems:**` bullet list from
+     the issue description and store it as structured metadata:
+     ```bash
+     bd update <id> --metadata '{"files": ["path/to/file1.py", "path/to/file2.py"]}'
+     ```
+     This enables automated file-conflict detection by concurrent agents (see `renew` skill
+     **Claiming work** section). If the Files/Systems section is empty or contains only
+     subsystem names without concrete paths, **stop and ask the user for specific file paths
+     before publishing the ticket** — a ticket without concrete paths cannot participate in
+     conflict detection and is incomplete.
 
 7. **Final report:**
    - Summarize the approved slice set, created issues, labels, and dependency links.

package/content/distilled/issue-review/SKILL.md

@@ -9,15 +9,16 @@ Read `references/setup.md` for tracker-specific collection commands before revie
 ## Procedure
 
 1. Gather the issue set to review plus the source plan/spec/parent issue when available.
-2. Run the passes in order:
+2. For Beads trackers, run PASS 0 pre-flight checks first: `references/pass-0-preflight.md`
+3. Run the content passes in order:
    - Pass 1: `references/pass-1-clarity.md`
    - Pass 2: `references/pass-2-scope.md`
    - Pass 3: `references/pass-3-dependencies.md`
    - Pass 4: `references/pass-4-alignment.md`
    - Pass 5: `references/pass-5-executability.md`
-3. After each pass starting with pass 2, evaluate convergence using `references/convergence.md`.
-4. If converged, stop.
-5. Produce the final report using `references/final-report.md`.
+4. After each pass starting with pass 2, evaluate convergence using `references/convergence.md`.
+5. If converged, stop.
+6. Produce the final report using `references/final-report.md`.
 
 ## Review Lens
 

package/content/distilled/issue-review/references/pass-0-preflight.md

@@ -0,0 +1,37 @@
+# PASS 0: Pre-flight (Beads only)
+
+Run before all content passes. Mechanical checks that don't require reading issue bodies.
+
+**Check 1 — metadata.files coverage:**
+```bash
+bd list --format json | python3 -c "
+import json, sys
+issues = json.load(sys.stdin)
+missing = [i['id'] for i in issues
+           if not (i.get('metadata') or {}).get('files')]
+if missing: print('Missing metadata.files:', missing)
+"
+```
+Flag `[PRE-001] MEDIUM` for each ticket missing `metadata.files`.
+Fix: `bd update <id> --set-metadata 'files=["path/to/file.py"]'`
+
+**Check 2 — shared-file architecture smell:**
+```bash
+bd list --format json | python3 -c "
+import json, sys
+from collections import defaultdict
+issues = json.load(sys.stdin)
+owners = defaultdict(list)
+for i in issues:
+    for f in (i.get('metadata') or {}).get('files', []):
+        owners[f].append(i['id'])
+for f, ids in owners.items():
+    if len(ids) >= 3: print(f, '->', ids)
+"
+```
+Flag `[PRE-002] LOW` for any file claimed by 3+ open tickets.
+Recommendation: consider a decomposition ticket to split `<file>` before these
+tickets run (see navari-a3cv pattern). If not decomposing now, add a
+co-modification note to all affected tickets.
+
+**Prefix:** PRE-001, PRE-002, etc.

package/content/distilled/next/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: next
+description: "Rapid session snapshot to ~/.whisper/ — no full close ceremony. Trigger when the user says '/next', 'snap', 'quick save', 'stash session', or 'moving on'."
+tools: Read, Write, Edit, Bash
+---
+
+# Next
+
+Snapshot the current session to `~/.whisper/` and move on. Fast — no project file updates, no inbox triage, no ticket operations. Pure stash.
+
+## Steps
+
+1. Get timestamp: `date +%Y-%m-%d` and `date +%H:%M`.
+
+2. Detect repo and branch:
+   ```bash
+   repo_url=$(git remote get-url origin 2>/dev/null | sed 's|https://||;s|git@||;s|\.git$||')
+   branch=$(git rev-parse --abbrev-ref HEAD)
+   branch_slug=$(echo "$branch" | sed 's|/|--|g')
+   notes_path=~/.whisper/repos/"${repo_url}"/branches/"${branch_slug}"/notes.md
+   ```
+
+3. If `~/.whisper/` doesn't exist or the branch slot doesn't exist, run `/w check` first (which will offer to init). If the user declines, skip and warn.
+
+4. Scan the last portion of the conversation and write a 2–5 bullet snapshot:
+   - What was worked on (files, topics)
+   - Key decisions or changes made
+   - **Next:** the most logical continuation point
+
+5. Append the snapshot to `notes.md`:
+   ```
+   ### YYYY-MM-DD HH:MM — snap
+   - what was worked on
+   - decisions made
+   - **Next:** continuation point
+   ```
+
+6. No commit, no push, no ticket operations. Just write the file.
+
+## Output
+
+```
+✓ Snapped to ~/.whisper/repos/<repo>/branches/<slug>/notes.md
+
+Use `/renew` later to pick this back up.
+```
+
+## Rules
+
+- Do NOT ask questions — summarize automatically from conversation context.
+- Keep it brief — 2–5 bullets, not paragraphs.
+- Do NOT commit or push anything.
+- Do NOT update project files, inbox, or tickets.
+- Do NOT run `/clear`.

package/content/distilled/park/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: park
+description: "Snapshot current work before switching context. Logs what was done and what's next without ending the day. Trigger when the user says '/park', 'park this', 'switching to', 'pause this', or 'context switch'."
+tools: Read, Write, Edit, Bash
+---
+
+# Park
+
+Snapshot the current session's work on a project/area before switching context. This is NOT end-of-day — just a context switch.
+
+Uses `$JOURNAL_PATH` (defaults to `~/dev/status`) for the daily log, and `~/.whisper/` for accumulated operational knowledge.
+
+## Steps
+
+1. Get today's date and current time (`date +%Y-%m-%d`, `date +%H:%M`).
+   ```bash
+   JOURNAL="${JOURNAL_PATH:-$HOME/dev/status}"
+   ```
+
+2. Read today's log: `$JOURNAL/log/YYYY/YYYY-MM/YYYY-MM-DD.md`
+   If it doesn't exist, create it with the daily log template.
+
+3. Review the conversation history to determine:
+   - What project/area was being worked on
+   - What was accomplished in this session
+   - What the logical next step is
+   - Any new tasks, decisions, or blockers discovered
+
+4. Append a session entry to today's log under `## Log`:
+   ```
+   ### Session:HH:MM (<project/area context>)
+   - what was done
+   - decisions made
+   - **Next:** what to do when resuming
+   ```
+
+5. Update the relevant project/area file if needed:
+   - Mark completed tasks `[x]`
+   - Add new tasks discovered during the session
+   - Add/update `[~]` waiting items with context
+   - Update `## Notes` with any decisions
+
+6. If there are uncommitted changes in the project's git worktree, note them in the log entry.
+
+7. **Release any in-progress ticket claim if leaving mid-work.**
+   Check whether a ticket was claimed for this session:
+   ```bash
+   BRANCH=$(git branch --show-current 2>/dev/null)
+   bd list --status in_progress --label branch:$BRANCH 2>/dev/null
+   ```
+   For each in-progress ticket that is NOT complete:
+   - **If meaningful work was committed:** keep the claim and append a progress note:
+     ```bash
+     bd note <id> "Session parked $(date +%H:%M). Done: <brief>. Safe to resume from: <last commit>."
+     ```
+   - **If nothing was committed:** release the claim so another agent can pick it up:
+     ```bash
+     bd update <id> --assignee "" --status open
+     ```
+
+8. **Record snapshot to `~/.whisper/`.** If `~/.whisper/` exists and a beads-epic is linked, append a note to the epic:
+   ```bash
+   repo_url=$(git remote get-url origin 2>/dev/null | sed 's|https://||;s|git@||;s|\.git$||')
+   branch_slug=$(git rev-parse --abbrev-ref HEAD | sed 's|/|--|g')
+   context_path=~/.whisper/repos/"${repo_url}"/branches/"${branch_slug}"/context.md
+   beads_epic=$(grep '^beads-epic:' "$context_path" 2>/dev/null | sed 's/^beads-epic: *//')
+   if [ -n "$beads_epic" ]; then
+     bd note "$beads_epic" "Parked $(date +%H:%M). Done: <what was accomplished>. Next: <the logical continuation>."
+   fi
+   ```
+
+9. Do NOT commit/push the journal repo yet — that happens at `/close`. Just write the files.
+
+## Output format
+
+```
+---
+**Parked: <project/area name>**
+
+**Session summary**
+- what was accomplished
+
+**Next step** *(for when you /renew)*
+- the logical continuation
+
+**Updated**
+- files modified in status repo (log, project file, etc.)
+
+*Ready to switch context. Use `/renew <slug>` to pick up something else.*
+```
+
+## Rules
+
+- Do NOT ask questions — summarize automatically from conversation context.
+- Keep it brief — this is a quick snapshot, not a full report.
+- Do NOT commit or push the journal repo.
+- Do NOT run `/clear` — the user may continue working in this session.

package/content/distilled/renew/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: renew
+description: "Resume work on a specific project or area. Loads focused context for continuing where you left off. When no name is given, infers the project/area from the current repo and git branch. Trigger when the user says '/renew', '/renew <name>', 'pick up <project>', 'continue <project>', or 'back to <project>'."
+tools: Read, Write, Edit, Glob, Bash, Grep
+---
+
+# Renew
+
+Load focused context for a specific project or area to continue work.
+
+Uses `$JOURNAL_PATH` (defaults to `~/dev/status`) for the daily log, and `~/.whisper/` for accumulated operational knowledge.
+
+## Steps
+
+1. Pull the journal repo:
+   ```bash
+   JOURNAL="${JOURNAL_PATH:-$HOME/dev/status}"
+   cd "$JOURNAL" && git pull
+   ```
+
+2. Identify the target.
+
+   **If a `<slug>` is provided:** The user says `/renew <slug>`.
+
+   **If no slug is provided:** Infer from the current workspace context:
+   - Get the repo name: `basename $(git rev-parse --show-toplevel 2>/dev/null)`
+   - Get the branch name: `git branch --show-current 2>/dev/null`
+   - Extract a candidate slug from the branch (strip prefix like `ak/`, `feature/`, etc.)
+   - Use both the repo name and branch-derived slug as candidates
+
+   **Match candidates** against:
+   - `$JOURNAL/projects/*.md` — check filenames and grep for repo/branch references
+   - `$JOURNAL/areas/*.md` — same
+   - Try exact match, then partial/substring match
+   - If multiple matches found, list them and ask the user to pick
+   - If no match found, list available projects/areas and ask
+
+3. Read the matched project or area file.
+
+4. Read today's log (`$JOURNAL/log/YYYY/YYYY-MM/YYYY-MM-DD.md`).
+   If it doesn't exist, create it with the daily log template.
+   Scan for any earlier session entries related to this project/area today.
+
+5. Search recent logs for context (last 3 days):
+   ```bash
+   grep -rl "<slug>" "$JOURNAL"/log/YYYY/YYYY-MM/ 2>/dev/null | tail -3
+   ```
+   Read any matches to understand recent session history.
+
+6. Search inbox for related items:
+   ```bash
+   grep -i "<slug>" "$JOURNAL"/inbox.md
+   ```
+
+7. **Check `~/.whisper/` for accumulated knowledge.**
+   If `~/.whisper/` exists, load context:
+   ```bash
+   repo_url=$(git remote get-url origin 2>/dev/null | sed 's|https://||;s|git@||;s|\.git$||')
+   branch_slug=$(git rev-parse --abbrev-ref HEAD | sed 's|/|--|g')
+   whisper_dir=~/.whisper/repos/"${repo_url}"/branches/"${branch_slug}"
+   ```
+   - Read `context.md` if it exists (extract beads-epic, status)
+   - Read `plan.md` if it has real content
+   - Read `notes.md` if it has real content
+   - Read `env.md` at repo level for infra facts
+   - If beads is available, fetch open issues:
+     ```bash
+     bd list --label branch:<branch> 2>/dev/null
+     bd list --status in_progress --label branch:<branch> 2>/dev/null
+     ```
+     Surface any `in_progress` tickets prominently. The **Suggested next step** must only reference tickets NOT currently `in_progress`.
+
+8. If the project/area has a worktree or repo path noted in its file, gather git context:
+   - `cd <worktree-path> && git branch --show-current`
+   - `git log --oneline -5`
+   - `git status --short`
+   - `git log --oneline origin/main..HEAD`
+
+## Output format
+
+```
+---
+**Resuming: Project/Area Name**
+
+**Status**: brief one-line summary of where things stand
+
+**Last session** *(from most recent log entry)*
+- what was done last time
+
+**Open tasks**
+- [ ] task list from the project/area file
+
+**Waiting**
+- [~] any blocked items and who/what they're waiting on
+
+**Related inbox items** *(if any)*
+- items that mention this project
+
+**Whisper context** *(if ~/.whisper/ exists)*
+- Plan: summary of current plan
+- Notes: key findings
+- Beads issues: <n> open, <n> in_progress
+
+**⚠ Active in flight** *(omit if none)*
+- ◐ `<id>` — <title> [started: <date>]
+- *(If your intended ticket is listed here, see **Claiming work** below.)*
+
+**Workspace**
+- Worktree: path, branch, status
+- Commits ahead of main, uncommitted changes, etc.
+
+**Suggested next step**
+- what makes sense to do next — only suggest tickets NOT currently in_progress
+```
+
+Then ask: *"Ready to continue, or want to adjust the plan?"*
+
+---
+
+## Claiming work
+
+Before writing any code, claim the ticket atomically and check for file conflicts.
+
+### Steps
+
+1. **Claim atomically:**
+   ```bash
+   bd update <ticket-id> --claim
+   ```
+
+2. **Check for file-level conflicts** with other in-progress tickets:
+   ```bash
+   bd list --status in_progress --label branch:<branch> --json 2>/dev/null \
+     | python3 -c "
+   import json, sys
+   issues = json.loads(sys.stdin.read() or '[]')
+   for i in issues:
+       files = (i.get('metadata') or {}).get('files', [])
+       for f in files:
+           print(i['id'] + '\t' + f)
+   "
+   ```
+   Cross-reference against the claimed ticket's own `metadata.files`.
+   If overlap found, surface a warning:
+   ```
+   ⚠ File conflict detected:
+     services/api.py is also claimed by ticket-abc (in_progress)
+
+   Options:
+     A) Gate this ticket until the blocker closes
+     B) Coordinate merge order
+     C) Proceed — accept the conflict (reconcile at merge time)
+   ```
+
+3. **If backing off** (chose option A):
+   ```bash
+   bd update <ticket-id> --assignee "" --status open
+   bd gate create <ticket-id> --type bead --await-id <blocking-id>
+   ```
+
+### Metadata coverage warning
+
+File conflict detection only works when both tickets have `metadata.files` populated (set by `create-issues` or `/w link` at ticket creation time). Tickets created before this convention was adopted have no metadata. For those tickets, **"no conflict found" means unknown, not safe**.

package/content/distilled/whisper/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: whisper
+description: "Manage the ~/.whisper/ knowledge workspace: init, check, status, link plan to beads, decommission, and knowledge routing. Trigger when the user says '/whisper', '/w', 'init workspace', 'check workspace', 'workspace status', 'link plan', or 'decommission worktree'."
+tools: Read, Write, Edit, Bash
+---
+
+# Whisper — Accumulated Operational Knowledge
+
+Manage `~/.whisper/` — a global, tiered knowledge directory that accumulates operational knowledge and planning context across all your work. Works with or without beads issue tracking.
+
+## Directory Layout
+
+```
+~/.whisper/
+  rules.md                          ← Global agent behavior rules (bd remember equiv)
+
+  repos/
+    github.com/user/repo/
+      env.md                        ← Repo-wide: deploy commands, infra facts, auth quirks
+      branches/
+        branch-slug/                ← One slot per branch (/ in name → -- in slug)
+          context.md                ← Branch anchor: repo, branch, beads epic ID, status
+          plan.md                   ← Narrative implementation plan
+          notes.md                  ← Free-form scratch and findings
+          agents/                   ← Optional sub-agent files when work is split across agents
+      worktrees/
+        worktree-name/              ← One slot per worktree (basename of worktree path)
+          env.md                    ← Worktree-specific: ports, venvs, credentials, local-only setup
+```
+
+**Branch slug rule:** `git rev-parse --abbrev-ref HEAD | sed 's|/|--|g'`
+
+**Worktree slot rule:** `basename $(git rev-parse --git-common-dir 2>/dev/null)` (the `.git` worktree dir name), or `basename $(pwd)` when not in a worktree.
+
+## Knowledge Routing
+
+When a session learns something worth keeping, route it by scope:
+
+| Scope | Test | Destination |
+|---|---|---|
+| **Global** | True for every repo and every project | `~/.whisper/rules.md` — append, don't overwrite |
+| **Repo-wide infra** | True regardless of which branch or feature you're on (deploy behavior, gateway/timeout limits, log retention, auth quirks) | `~/.whisper/repos/<host>/<repo>/env.md` — create or extend |
+| **Branch-specific** | Only matters for the work on *this* epic/branch | `~/.whisper/repos/<host>/<repo>/branches/<slug>/notes.md`, or `bd note <epic-id>` if beads is available |
+| **Worktree setup** | Credentials, service IDs, ports, venv/docker specifics for *this checkout* | `~/.whisper/repos/<host>/<repo>/worktrees/<name>/env.md` |
+| **Universal agent rule** | A standing instruction for how the agent should behave, independent of any branch or repo | `bd remember` if available, else `~/.whisper/rules.md` |
+
+**Rules:**
+- **No secrets anywhere.** Never write tokens, keys, passwords, or PII into `~/.whisper/`.
+- **Extend, don't duplicate.** Append to or correct an existing note rather than creating a new one that says the same thing.
+- **Search first.** Before creating a new entry, check if one already exists for the same topic.
+- If `bd` is not available, everything falls back to `~/.whisper/` files — there's no beads-backed alternative.
+
+## Modes
+
+Determine mode from how the skill is triggered:
+
+| Trigger | Mode |
+|---|---|
+| `/w init` or `~/.whisper/` does not exist | **init** |
+| `/w` or `/w status` | **status** |
+| `/w check` or called by `renew` | **check** |
+| `/w link [<path>]` or "link plan" | **link** |
+| `/w decommission` | **decommission** |
+
+See each reference file for the full procedure:
+
+- `references/init.md`
+- `references/check.md`
+- `references/status.md`
+- `references/link.md`
+- `references/decommission.md`
+
+## Rules
+
+- Never run `git worktree remove` automatically — always print the command for the user to execute.
+- Never close beads issues during decommission — only defer. Closing is intentional.
+- **One epic per branch, children via `--parent`, not flat siblings.**
+- **`env.md` is shared and immutable across branch switches.** Never overwrite it during init or check — only create if absent.
+- **Branch slug sanitization is mandatory.** Always run `sed 's|/|--|g'` on the branch name before using it as a directory path.
+- **Worktree reuse across branches is normal, not an edge case.** Expect multiple slots to accumulate in `branches/` over time.
+- **Legacy layout is still the common case.** Most worktrees never needed multiple branch slots — only migrate when a mismatch is detected.
+- This skill is self-contained. Do not rely on `create-plan`, `park`, or `create-handoff` having `~/.whisper/` awareness.
+- If `bd` is not initialized in the repo, skip beads steps gracefully and note what was skipped.

package/content/distilled/whisper/references/check.md

@@ -0,0 +1,33 @@
+# Check
+
+Validate the workspace before starting work. Detects stale branch slots and worktree reuse. Called automatically by `renew` when `~/.whisper/` exists.
+
+## Steps
+
+1. Get repo URL and branch slug:
+   ```bash
+   repo_url=$(git remote get-url origin 2>/dev/null | sed 's|https://||;s|git@||;s|\.git$||')
+   branch=$(git rev-parse --abbrev-ref HEAD)
+   branch_slug=$(echo "$branch" | sed 's|/|--|g')
+   context_path=~/.whisper/repos/"${repo_url}"/branches/"${branch_slug}"/context.md
+   ```
+
+2. **If `~/.whisper/` doesn't exist:** offer full init:
+   ```
+   ⚠ ~/.whisper/ not found. Run `/w init` to create the workspace.
+   ```
+
+3. **If `context.md` exists:** output one confirmation line and return.
+   ```
+   ✓ Workspace active: ~/.whisper/repos/<repo>/branches/<slug>/
+   ```
+
+4. **If the branch directory doesn't exist:**
+   ```
+   ⚠ No workspace slot for branch: <branch>
+     ~/.whisper/repos/<repo>/branches/<slug>/ does not exist yet.
+
+   Activate new slot? [Y/n]
+   ```
+   - Y → run **init** for the current branch.
+   - N → print "Staying without a slot. Run `/w init` when ready." and stop.