incitaciones 0.2.0 → 0.3.0

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

@@ -0,0 +1,53 @@
+# Decommission
+
+Safely wind down a worktree or branch: defer open work under the branch epic, record a final note, then print the removal command.
+
+## Steps
+
+1. Run **check** first. Confirm slot exists before decommissioning.
+
+2. 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')
+   branch_dir=~/.whisper/repos/"${repo_url}"/branches/"${branch_slug}"
+   context_path="$branch_dir/context.md"
+   ```
+
+3. Read `beads-epic:` from `context.md`.
+
+4. If beads is available, get all open work under that epic:
+   ```bash
+   bd children <epic-id> --json 2>/dev/null
+   ```
+
+5. If any open children found, defer them:
+   ```bash
+   bd defer <id>
+   ```
+
+6. Defer the epic itself:
+   ```bash
+   bd defer <epic-id>
+   ```
+
+7. Record the decommission as a note on the epic:
+   ```bash
+   bd note <epic-id> "Decommissioned: branch <branch> on <date>. State: <summary>. Resume via: /w init on branch <branch> — bd search '<branch>' will find this epic."
+   ```
+
+8. Print the removal command — do NOT run it:
+   ```
+   Ready to remove worktree. Run:
+     git worktree remove <path>
+
+   Deferred epic <epic-id> and <n> children. To find them later:
+     bd list --status deferred --label branch:<branch>
+   ```
+
+## Rules
+
+- Never run `git worktree remove` automatically — always print the command.
+- Never close beads issues during decommission — only defer. Closing is intentional.
+- Branch slots in `~/.whisper/` are not automatically removed when a branch is merged. The slot serves as an archive; the epic (found via `bd search`) can be reused if the same branch name comes back.

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

@@ -0,0 +1,103 @@
+# Init
+
+Create `~/.whisper/` and the current workspace slot.
+
+## Steps
+
+1. Get context:
+   ```bash
+   pwd
+   git rev-parse --abbrev-ref HEAD
+   basename $(git rev-parse --show-toplevel 2>/dev/null)   # repo name
+   git rev-parse --git-common-dir 2>/dev/null              # confirms worktree vs main
+   date +%Y-%m-%d
+   ```
+
+2. Create `~/.whisper/` if it doesn't exist:
+   ```bash
+   mkdir -p ~/.whisper/repos
+   ```
+
+3. Compute the repo path 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')
+   ```
+
+4. Create the repo & branch directory:
+   ```bash
+   mkdir -p ~/.whisper/repos/"${repo_url}"/branches/"${branch_slug}"
+   wk_dir=$(basename "$(git rev-parse --git-common-dir 2>/dev/null || echo '.git')" | sed 's|\.git$||')
+   [ -n "$wk_dir" ] && mkdir -p ~/.whisper/repos/"${repo_url}"/worktrees/"${wk_dir}"
+   ```
+
+5. Create `~/.whisper/rules.md` if it doesn't exist:
+   ```markdown
+   # Global Agent Rules
+
+   > Standing instructions for the agent, independent of any repo or branch.
+   > Append here for rules that apply everywhere.
+   ```
+
+6. Create the repo `env.md` if it doesn't exist:
+   ```markdown
+   # Environment — <repo-name>
+
+   > Repo-wide setup knowledge. True regardless of which branch or worktree.
+   > Deploy commands, gateway limits, auth quirks that apply everywhere.
+   > Worktree-specific setup (ports, venvs, local creds) goes in worktrees/<name>/env.md
+   ```
+
+7. Create the worktree `env.md` if it doesn't exist:
+   ```markdown
+   # Worktree — <worktree-name>
+
+   > Worktree-specific setup. Credentials, ports, venv/docker specifics for THIS checkout only.
+   ```
+
+8. Create `context.md`:
+   ```markdown
+   # Workspace Context — <full-branch-name>
+
+   repo: <repo-url>
+   branch: <full-branch-name>
+   worktree: <worktree-dir-name>
+   path: <absolute-path>
+   created: <YYYY-MM-DD>
+   beads-epic:
+   ```
+
+9. Create `plan.md` stub:
+   ```markdown
+   # Plan — <full-branch-name>
+
+   > No plan yet. Write a plan here, then run `/w link` to create beads issues.
+   ```
+
+10. Create `notes.md` stub:
+    ```markdown
+    # Notes — <full-branch-name>
+    ```
+
+11. If beads is available, find or create the branch epic:
+    ```bash
+    bd search "<branch>" --status all 2>/dev/null
+    ```
+    - If an epic already matches, reuse its ID and update `beads-epic:` in `context.md`.
+    - If the work is substantial enough, create one: `bd create "<branch>" --type epic --label "branch:<branch>" --silent`
+    - For a single-ticket fix, skip the epic and let the ticket ID stand in for `beads-epic:`.
+
+12. Confirm:
+    ```
+    ✓ ~/.whisper/ initialized
+
+    Repo:  <repo-url>
+    Branch: <branch> → branches/<slug>/
+    Epic:  <id | none — will be created by /w link>
+    rules.md:     [created | exists]
+    env.md:       [created | exists]
+    worktree/env.md: [created | exists]
+
+    Run `/w link` after writing a plan.
+    ```

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

@@ -0,0 +1,70 @@
+# Link
+
+Attach a plan file to the workspace and create beads issues for each phase, as children of the branch epic. Run this after writing or generating a plan.
+
+This mode is self-contained — it does NOT require `create-plan` to have been used. The plan can come from anywhere: manually written, generated by any tool, or copied in.
+
+## Steps
+
+1. Run **check** first to confirm the slot exists.
+
+2. 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')
+   branch_dir=~/.whisper/repos/"${repo_url}"/branches/"${branch_slug}"
+   context_path="$branch_dir/context.md"
+   plan_path="$branch_dir/plan.md"
+   ```
+
+3. Determine the plan file path:
+   - If the user provided a path (`/w link path/to/plan.md`): use that.
+   - Otherwise: use `plan.md`.
+   - If neither exists: tell the user to write a plan first and stop.
+
+4. If the source path is not `plan.md`, copy it in:
+   ```bash
+   cp <source-path> "$branch_dir/plan.md"
+   ```
+
+5. Read `plan.md` and extract phase headings.
+
+6. Ensure the branch epic exists:
+   - If `context.md`'s `beads-epic:` is already set, use it.
+   - If blank and the plan has more than one phase: create it.
+   - If blank and the plan is a single task: skip the epic.
+
+7. For each phase/task, create a beads issue as a child of the branch epic:
+   ```bash
+   bd create "<phase-title>" --type task --parent <epic-id>
+   ```
+
+8. Only if phases are genuinely sequential, chain dependencies:
+   ```bash
+   bd dep <id-N> --blocks <id-N+1>
+   ```
+
+9. Update `context.md` — set `beads-epic:` to the epic (or single-ticket) ID.
+
+10. **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. If the Files/Systems section is empty or contains only subsystem names without concrete paths, **stop and ask for specific file paths** — a ticket without concrete paths cannot participate in conflict detection.
+
+11. Confirm:
+    ```
+    Linked plan to workspace: branches/<slug>/
+    Epic: <epic-id> — <branch>
+    Created <n> child issues:
+      <id>  Phase 1: ...
+    ```
+
+### Relinking
+
+If `context.md` already has a `beads-epic:` set, ask before creating new children:
+```
+context.md already links epic <id> with <n> children.
+Add new phases as more children of the same epic? [Y/n]
+```

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

@@ -0,0 +1,49 @@
+# Status
+
+Show the state of the current workspace.
+
+## 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 `context.md` doesn't exist, delegate to **check** mode and stop.
+
+3. Read `context.md` and extract: repo, branch, path, beads-epic.
+
+4. Show `env.md` info:
+   ```bash
+   date -r ~/.whisper/repos/"${repo_url}"/env.md "+%Y-%m-%d %H:%M" 2>/dev/null
+   ```
+
+5. Show the branch epic's tree if beads is available:
+   ```bash
+   bd children <beads-epic> --pretty 2>/dev/null
+   ```
+
+6. Show plan status: is `plan.md` a stub or does it have real content?
+
+7. Show all active branch slots for this repo (most recently modified first):
+   ```bash
+   ls -t ~/.whisper/repos/"${repo_url}"/branches/ 2>/dev/null
+   ```
+
+### Output format
+
+```
+── Whisper: <repo> ──
+Branch:    <branch>  (branches/<slug>/)
+Plan:      [exists | stub]
+Epic:      <id> — <n> issues (<open> open)   [or: none linked yet]
+
+Active branch slots:
+  <ls output>
+
+Epic tree:
+  <bd children --pretty output, or "none">
+```

package/content/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "2026-05-22",
+  "version": "2026-07-27",
   "schema_version": "1.1",
   "prompts": [
     {
@@ -3021,6 +3021,93 @@
         ]
       }
     },
+    {
+      "name": "whisper",
+      "type": "workflow",
+      "title": "Whisper — Accumulated Operational Knowledge",
+      "description": "Manage the ~/.whisper/ knowledge workspace: init, check, status, link plan, decommission, and knowledge routing",
+      "source": "content/prompt-workflow-whisper.md",
+      "distilled": "content/distilled/whisper/SKILL.md",
+      "skill_format": "progressive-disclosure",
+      "tags": [
+        "workflow",
+        "knowledge",
+        "planning",
+        "beads"
+      ],
+      "bundles": [
+        "essentials",
+        "workflow"
+      ]
+    },
+    {
+      "name": "close",
+      "type": "workflow",
+      "title": "Close Session",
+      "description": "End-of-session wrap-up. Summarizes, logs to daily journal, routes knowledge to ~/.whisper/, commits, and clears context",
+      "source": "content/prompt-workflow-close.md",
+      "distilled": "content/distilled/close/SKILL.md",
+      "skill_format": "single-file",
+      "tags": [
+        "workflow",
+        "session",
+        "journal"
+      ],
+      "bundles": [
+        "workflow"
+      ]
+    },
+    {
+      "name": "park",
+      "type": "workflow",
+      "title": "Park Session",
+      "description": "Snapshot current work before switching context. Logs to daily journal, releases ticket claims, records to ~/.whisper/",
+      "source": "content/prompt-workflow-park.md",
+      "distilled": "content/distilled/park/SKILL.md",
+      "skill_format": "single-file",
+      "tags": [
+        "workflow",
+        "session",
+        "context-switch"
+      ],
+      "bundles": [
+        "workflow"
+      ]
+    },
+    {
+      "name": "renew",
+      "type": "workflow",
+      "title": "Renew Session",
+      "description": "Resume work on a project or area. Loads context from journal, ~/.whisper/, and beads. Supports claiming work with file conflict detection",
+      "source": "content/prompt-workflow-renew.md",
+      "distilled": "content/distilled/renew/SKILL.md",
+      "skill_format": "single-file",
+      "tags": [
+        "workflow",
+        "session",
+        "context"
+      ],
+      "bundles": [
+        "workflow"
+      ]
+    },
+    {
+      "name": "next",
+      "type": "workflow",
+      "title": "Next — Rapid Session Snapshot",
+      "description": "Rapid session snapshot to ~/.whisper/ — no full close ceremony. Fast stash for later resumption via /renew",
+      "source": "content/prompt-workflow-next.md",
+      "distilled": "content/distilled/next/SKILL.md",
+      "skill_format": "single-file",
+      "tags": [
+        "workflow",
+        "session",
+        "snapshot"
+      ],
+      "bundles": [
+        "workflow"
+      ]
+    },
     {
       "name": "project-status-report",
       "type": "task",
@@ -3127,7 +3214,8 @@
         "code-review",
         "research-codebase",
         "create-handoff",
-        "resume-handoff"
+        "resume-handoff",
+        "whisper"
       ]
     },
     "planning": {
@@ -3210,6 +3298,16 @@
         "doc-link-verifier"
       ]
     },
+    "workflow": {
+      "description": "Session lifecycle and workspace knowledge management",
+      "prompts": [
+        "whisper",
+        "close",
+        "park",
+        "renew",
+        "next"
+      ]
+    },
     "all": {
       "description": "Complete collection of all prompts",
       "prompts": [
@@ -3217,4 +3315,4 @@
       ]
     }
   }
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "incitaciones",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Reusable prompts and skills for CLI LLM tools, with native pi package support.",
   "repository": {
     "type": "git",
@@ -27,6 +27,7 @@
     "content/manifest.json",
     "pi-package/",
     "scripts/cli.mjs",
+    "scripts/generate-pi-resources.mjs",
     "LICENSE",
     "README.md"
   ],

package/pi-package/prompts/close.md

@@ -0,0 +1,10 @@
+---
+description: "Shortcut for the close skill. End-of-session wrap-up. Summarizes, logs to daily journal, routes knowledge to ~/.whisper/, commits, and clears context"
+---
+<!-- installed-from: incitaciones -->
+
+Use the installed `close` skill for this task.
+
+If the skill is not automatically loaded, invoke `/skill:close` and follow it.
+
+User context: $@

package/pi-package/prompts/next.md

@@ -0,0 +1,10 @@
+---
+description: "Shortcut for the next skill. Rapid session snapshot to ~/.whisper/ — no full close ceremony. Fast stash for later resumption via /renew"
+---
+<!-- installed-from: incitaciones -->
+
+Use the installed `next` skill for this task.
+
+If the skill is not automatically loaded, invoke `/skill:next` and follow it.
+
+User context: $@

package/pi-package/prompts/park.md

@@ -0,0 +1,10 @@
+---
+description: "Shortcut for the park skill. Snapshot current work before switching context. Logs to daily journal, releases ticket claims, records to ~/.whisper/"
+---
+<!-- installed-from: incitaciones -->
+
+Use the installed `park` skill for this task.
+
+If the skill is not automatically loaded, invoke `/skill:park` and follow it.
+
+User context: $@

package/pi-package/prompts/renew.md

@@ -0,0 +1,10 @@
+---
+description: "Shortcut for the renew skill. Resume work on a project or area. Loads context from journal, ~/.whisper/, and beads. Supports claiming work with file conflict detection"
+---
+<!-- installed-from: incitaciones -->
+
+Use the installed `renew` skill for this task.
+
+If the skill is not automatically loaded, invoke `/skill:renew` and follow it.
+
+User context: $@

package/pi-package/prompts/whisper.md

@@ -0,0 +1,10 @@
+---
+description: "Shortcut for the whisper skill. Manage the ~/.whisper/ knowledge workspace: init, check, status, link plan, decommission, and knowledge routing"
+---
+<!-- installed-from: incitaciones -->
+
+Use the installed `whisper` skill for this task.
+
+If the skill is not automatically loaded, invoke `/skill:whisper` and follow it.
+
+User context: $@

package/pi-package/skills/close/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: close
+description: "End-of-session wrap-up. Summarizes, logs to daily journal, routes knowledge to ~/.whisper/, commits, and clears context"
+metadata:
+  installed-from: "incitaciones"
+---
+---
+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/pi-package/skills/create-issues/SKILL.md

@@ -60,6 +60,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/pi-package/skills/issue-review/SKILL.md

@@ -15,15 +15,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/pi-package/skills/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.