incitaciones 0.9.0 → 0.10.0

package/README.md

@@ -7,7 +7,22 @@ A collection of reusable prompts and best practices for CLI LLM tools.
 
 ## Quick Install
 
-### Via npm / npx (recommended)
+### Via skills.sh (works with any agent)
+
+```bash
+# Browse & install interactively (pick individual skills):
+npx skills add incitaciones
+
+# Install everything:
+npx skills add incitaciones --skill '*' --all
+
+# Install only a specific skill:
+npx skills add incitaciones --skill commit
+```
+
+The skills.sh catalog (committed `skills/` directory) is generated from `content/manifest.json` — compat pointers are marked `metadata.internal: true` and hidden from discovery there.
+
+### Via npm / npx (pi + multi-tool installers)
 
 ```bash
 # Install as pi package (native skills, best UX):
@@ -89,6 +104,13 @@ After changing distilled content or manifest entries, you don't need to touch `p
 
 ### Publishing a new version
 
+Before publishing — and on every **model or provider change** — rerun the skill
+evals; a model upgrade can silently break an unchanged skill:
+
+```bash
+just skill-eval commit   # add more skills as fixtures land (scripts/skill-eval-fixtures/)
+```
+
 ```bash
 npm version patch   # bumps to 0.5.1, creates a git tag
 npm version minor   # bumps to 0.6.0
@@ -153,7 +175,7 @@ just search
 Everything lives in `content/` with descriptive filenames:
 
 - `prompt-*.md` - Reusable prompts (source)
-- `distilled/` - Optimized prompts for agent consumption (single file or multi-file)
+- `distilled/` - Optimized prompts for agent consumption (single file, multi-file, or router + references/ — see AGENTS.md "Distilled Formats")
 - `research-*.md` - Experiments and findings
 - `example-*.md` - Real-world examples
 - `template-*.md` - Templates for new content

package/content/distilled/diagnostician/SKILL.md

@@ -0,0 +1,32 @@
+# Diagnostician Router
+
+Advisory-only diagnostic evaluation of a codebase, product, or document. Each mode detects a family of pathologies and maps findings to named refactoring/remediation patterns. **Do not modify files in any mode — output findings and recommendations only.**
+
+## Modes
+
+| Question the user is asking | Mode | Read |
+|---|---|---|
+| Is it tangled? coupling, cohesion, cycles, God Objects | modularity-diagnostician | `references/modularity-diagnostician.md` |
+| Is change resisted? inheritance rigidity, OCP violations | rigidity-diagnostician | `references/rigidity-diagnostician.md` |
+| Is mutable state pathological? side-effect entanglement | mutability-diagnostician | `references/mutability-diagnostician.md` |
+| Can invalid states be represented? primitive obsession, boolean blindness | invalid-states-diagnostician | `references/invalid-states-diagnostician.md` |
+| Does it compose? type mismatches, missed endomorphisms, algebra gaps | composability-diagnostician | `references/composability-diagnostician.md` |
+| How does it fail? detection, classification, recovery, learning | error-handling-diagnostician | `references/error-handling-diagnostician.md` |
+| Why is Julia slow? type instability, allocation floods, dispatch | julia-performance-diagnostician | `references/julia-performance-diagnostician.md` |
+| Is the product usable? HEART, SPACE/DX Core 4, CLI/API heuristics, Diátaxis | ux-dx-evaluation-diagnostician | `references/ux-dx-evaluation-diagnostician/SKILL.md` |
+| Is the spec verifiable/buildable? | testability-implementability-evaluator | `references/testability-implementability-evaluator.md` |
+| Is this document true? factual errors, unsupported claims, provenance | verification-diagnostician | `references/verification-diagnostician.md` |
+| Is the specification complete/correct/coherent? (ISO 29148) | specification-evaluation-diagnostician | `references/specification-evaluation-diagnostician.md` |
+| Why did this fail? root cause analysis, method selection, corrective actions | rca-diagnostician | `references/rca-diagnostician/SKILL.md` |
+
+## Mode notes
+
+- The diagnostician modes are **mutually exclusive by design** — each SKILL.md opens with a GUARD naming its neighbors. Read the GUARD before running a diagnosis; redirect when the symptom belongs to another mode.
+- Formal-verification readiness (paradigm assessment, safety/liveness properties, toolchain scoping) is its own skill — `formal-verification-evaluator` — outside this router; redirect there when the question is about proof-readiness rather than build/test-readiness.
+- Multi-file modes (`rca-diagnostician`, `ux-dx-evaluation-diagnostician`) carry their templates in their own `references/` subdirectory.
+
+## Procedure
+
+1. Pick the mode whose *question* matches (not merely whose keyword matches).
+2. Read the referenced file; follow its INPUT → PROTOCOL pipeline and report template.
+3. Rank corrective actions by strength as the mode specifies; never auto-apply them.

package/content/distilled/doc-link-verifier/SKILL.md

@@ -93,90 +93,19 @@ Group results by source file so the user can see which docs are worst-hit.
 
 ### Step 4 — Contextual correctness (the hard part)
 
-A link can pass Step 3 (it resolves, the anchor exists) and still be wrong — pointing at an outdated version of a page, at the wrong section, at a page whose title/subject no longer matches what the surrounding prose promises. This is what the user means by "correct in context."
+A link can resolve cleanly and still be wrong: pointing at an outdated page, the wrong section, or a page whose subject no longer matches the surrounding prose.
 
-**Shallow check (default).** For each `ok` link, compare the link text (and a sentence of surrounding context) to the target's identifying label:
-- External link, deep mode was run: compare to `<title>` and H1.
-- Relative link to another repo file: compare to the file's first H1, or to the heading just under the fragment if one is present. You can read the file directly — this is cheap.
-- Anchor-only link: compare the link text to the heading itself.
+- **Shallow check (default):** compare link text plus surrounding context to the target's identifying label (title, H1, or heading at the anchor). Flag specific mismatches; don't flag generic link text — note it instead.
+- **Deep check (on request, or for suspicious cases):** fetch/read the target's actual content and ask whether the context's claim holds up.
+- Escalate shallow→deep when the shallow check flagged a specific mismatch, the context makes a specific technical claim, or the user asked for a thorough audit. Don't escalate for generic link text or huge link counts.
 
-Shallow check mismatches worth flagging:
-- Link text says "the API reference" but the target's title is "Installation Guide."
-- Link text says "see the v2 migration notes" but the target page is titled "v3 migration notes."
-- Link text references a specific concept ("rate limiting") and the target page is about something unrelated ("authentication").
-
-Shallow misses are usually false alarms when the link text is generic ("see here", "this page", "click here"). Don't flag those — instead, note in the report that generic link text makes contextual verification impossible and suggest more descriptive text if the user cares.
-
-**Deep check (on request, or for suspicious cases).** Fetch the target page's content and read it. For external links, this means re-running `check_links.py` with `--deep` to pull titles/headings, and for the most suspicious cases, using `web_fetch` yourself to read the full page. For relative links, just read the target file.
-
-Then ask: does the surrounding context's claim hold up when you look at what the target actually says?
-
-**Example — shallow pass, deep fail:**
-
-> "For rate limiting details, see the [API guide](https://example.com/api)."
-
-Shallow: link text "API guide", target title "API Guide" → match, passes.
-Deep: page is about endpoints and auth; there's no rate limiting section anywhere → contextual mismatch.
-
-**Example — deep pass:**
-
-> "See [issue #42](https://github.com/org/repo/issues/42) for the discussion of the memory leak."
-
-Deep: fetch the issue, confirm the title/body talk about a memory leak → context is correct.
-
-When to escalate from shallow to deep automatically:
-- The shallow check flagged a mismatch, but the link text is specific enough that it's worth verifying before reporting.
-- The surrounding context makes a specific technical claim ("as shown in X"), and the user has asked for a thorough audit.
-- The user explicitly asked for a deep check.
-
-When NOT to escalate:
-- The link text is generic ("here", "this", "docs").
-- The repo has thousands of external links (the network cost is too high; ask the user if they want to narrow the scope).
+Full criteria, examples (shallow-pass/deep-fail and deep-pass), and escalation rules: read `references/contextual-correctness.md`.
 
 ### Step 5 — Produce the report
 
-The report has a consistent structure so users can skim or drill in:
-
-```markdown
-# Link audit: <repo>
-
-## Summary
-- Scanned N files, found M links
-- ✅ ok: X · ⚠️ redirected: Y · ❌ broken: Z · ❓ anchor-missing: W · ⏭ skipped: V
-- Contextual mismatches flagged: K
-
-## Broken links (❌)
-Grouped by source file. For each:
-- File + line number
-- Link text and URL
-- What went wrong (HTTP status / "file not found" / etc.)
-- Suggested fix if one is obvious
-
-## Missing anchors (❓)
-For each:
-- File + line, link text, URL
-- Available headings in the target (from the check result)
-- Best-guess replacement
-
-## Redirects worth updating (⚠️)
-Only include notable ones — permanent URL changes, org renames, etc.
-Don't flood the report with trivial http→https redirects unless the user asked.
-
-## Contextual mismatches
-The judgment calls from Step 4. Each one shows:
-- The source line with context
-- The link
-- What the target actually contains
-- Why it's a mismatch
-- Suggested fix or "needs human review"
-
-## Generic link text
-Links whose text is too generic to verify contextually ("here", "this", "click here").
-Not a bug; a quality suggestion.
-```
+Use the fixed report structure (summary with ok/redirected/broken/anchor-missing/skipped counts, then Broken links, Missing anchors, Redirects worth updating, Contextual mismatches, Generic link text) so users can skim or drill in. The exact template: read `references/report-template.md`.
 
 Keep the report in a file (`link-audit.md` in the repo root, or wherever the user prefers) and **also** surface the top issues inline so the user sees them without opening the file.
-
 ### Step 6 — Fixes (opt-in, confirmation required)
 
 After presenting the report, offer to fix things. Never apply fixes without confirmation — users have strong opinions about their docs and some "broken" links are intentional (internal-only URLs, placeholder URLs in templates, etc.).

package/content/distilled/doc-link-verifier/references/contextual-correctness.md

@@ -0,0 +1,41 @@
+# Contextual correctness — full criteria
+
+A link can pass Step 3 (it resolves, the anchor exists) and still be wrong — pointing at an outdated version of a page, at the wrong section, at a page whose title/subject no longer matches what the surrounding prose promises. This is what the user means by "correct in context."
+
+**Shallow check (default).** For each `ok` link, compare the link text (and a sentence of surrounding context) to the target's identifying label:
+- External link, deep mode was run: compare to `<title>` and H1.
+- Relative link to another repo file: compare to the file's first H1, or to the heading just under the fragment if one is present. You can read the file directly — this is cheap.
+- Anchor-only link: compare the link text to the heading itself.
+
+Shallow check mismatches worth flagging:
+- Link text says "the API reference" but the target's title is "Installation Guide."
+- Link text says "see the v2 migration notes" but the target page is titled "v3 migration notes."
+- Link text references a specific concept ("rate limiting") and the target page is about something unrelated ("authentication").
+
+Shallow misses are usually false alarms when the link text is generic ("see here", "this page", "click here"). Don't flag those — instead, note in the report that generic link text makes contextual verification impossible and suggest more descriptive text if the user cares.
+
+**Deep check (on request, or for suspicious cases).** Fetch the target page's content and read it. For external links, this means re-running `check_links.py` with `--deep` to pull titles/headings, and for the most suspicious cases, using `web_fetch` yourself to read the full page. For relative links, just read the target file.
+
+Then ask: does the surrounding context's claim hold up when you look at what the target actually says?
+
+**Example — shallow pass, deep fail:**
+
+> "For rate limiting details, see the [API guide](https://example.com/api)."
+
+Shallow: link text "API guide", target title "API Guide" → match, passes.
+Deep: page is about endpoints and auth; there's no rate limiting section anywhere → contextual mismatch.
+
+**Example — deep pass:**
+
+> "See [issue #42](https://github.com/org/repo/issues/42) for the discussion of the memory leak."
+
+Deep: fetch the issue, confirm the title/body talk about a memory leak → context is correct.
+
+When to escalate from shallow to deep automatically:
+- The shallow check flagged a mismatch, but the link text is specific enough that it's worth verifying before reporting.
+- The surrounding context makes a specific technical claim ("as shown in X"), and the user has asked for a thorough audit.
+- The user explicitly asked for a deep check.
+
+When NOT to escalate:
+- The link text is generic ("here", "this", "docs").
+- The repo has thousands of external links (the network cost is too high; ask the user if they want to narrow the scope).

package/content/distilled/doc-link-verifier/references/report-template.md

@@ -0,0 +1,39 @@
+# Link audit report template
+
+```markdown
+# Link audit: <repo>
+
+## Summary
+- Scanned N files, found M links
+- ✅ ok: X · ⚠️ redirected: Y · ❌ broken: Z · ❓ anchor-missing: W · ⏭ skipped: V
+- Contextual mismatches flagged: K
+
+## Broken links (❌)
+Grouped by source file. For each:
+- File + line number
+- Link text and URL
+- What went wrong (HTTP status / "file not found" / etc.)
+- Suggested fix if one is obvious
+
+## Missing anchors (❓)
+For each:
+- File + line, link text, URL
+- Available headings in the target (from the check result)
+- Best-guess replacement
+
+## Redirects worth updating (⚠️)
+Only include notable ones — permanent URL changes, org renames, etc.
+Don't flood the report with trivial http→https redirects unless the user asked.
+
+## Contextual mismatches
+The judgment calls from Step 4. Each one shows:
+- The source line with context
+- The link
+- What the target actually contains
+- Why it's a mismatch
+- Suggested fix or "needs human review"
+
+## Generic link text
+Links whose text is too generic to verify contextually ("here", "this", "click here").
+Not a bug; a quality suggestion.
+```

package/content/distilled/documentation/SKILL.md

@@ -0,0 +1,22 @@
+# Documentation Router
+
+Route documentation work to the right mode, then read that mode's instructions before acting.
+
+## Modes
+
+| Task signal | Mode | Read |
+|---|---|---|
+| audit existing docs or plan a new documentation suite | research-documentation | `references/research-documentation/SKILL.md` |
+| write documentation using Diátaxis, Info Mapping, EPPO principles | implement-documentation | `references/implement-documentation/SKILL.md` |
+| review docs for cognitive scannability and AI-readiness | review-documentation | `references/review-documentation/SKILL.md` |
+
+## Selection rules
+
+- No docs or restructuring from scratch → **research-documentation** first; its report feeds implementation.
+- Writing or rewriting content → **implement-documentation**. Judging existing content quality → **review-documentation**.
+- Broken links or link-text/target mismatches are the complaint → use the `doc-link-verifier` skill instead; this router is about architecture and content quality.
+
+## Procedure
+
+1. Identify the mode from the table above.
+2. Read the referenced file (resolve paths against this skill's directory); follow its checklists, templates, and report formats.

package/content/distilled/grill-me.md

@@ -9,12 +9,12 @@ You are an exacting design interviewer. Interview the user relentlessly about a
 1. Walk each branch of the design tree.
 2. Resolve dependencies between decisions one by one.
 3. For every question, provide your recommended answer.
-4. Ask questions one at a time.
-5. If a question can be answered by exploring the codebase, inspect the codebase instead of asking.
+4. Ask questions **one at a time**. Exactly ONE question per turn — bundling several questions into a single turn violates this skill. If several decisions are queued, pick the highest-leverage one, answer the rest with your recommendation, and note they are queued for later turns.
+5. If a question can be answered by exploring the codebase, inspect the codebase instead of asking — in simulations, state which path you would inspect and what you would look for rather than asking the user.
 6. Continue until major branches are resolved or explicitly marked open.
 
 **OUTPUT PER TURN**
-- **Question:** one focused question
+- **Question:** exactly one focused question (never a bundle)
 - **Recommended answer:** best current recommendation
 - **Why this matters:** brief rationale
 

package/content/distilled/issues/SKILL.md

@@ -0,0 +1,21 @@
+# Issues Router
+
+Route issue-tracking work to the right mode, then read that mode's instructions before acting. Both modes assume a tracker CLI (beads `bd` by default) — check the project's AGENTS.md for the tracker in use.
+
+## Modes
+
+| Task signal | Mode | Read |
+|---|---|---|
+| turn an implementation plan into trackable issues | create-issues | `references/create-issues/SKILL.md` |
+| review existing issues for completeness, dependencies, executability | issue-review | `references/issue-review/SKILL.md` |
+
+## Selection rules
+
+- Plan approved and needs to become work items → **create-issues**.
+- Issues exist and someone asks "are these ready/good/covered?" → **issue-review** (multi-pass: clarity, scope, dependencies, alignment, executability).
+- Creating issues from a plan that has not been reviewed? Suggest a plan review first.
+
+## Procedure
+
+1. Identify the mode from the table above.
+2. Read the referenced file (resolve paths against this skill's directory); follow its templates, pass structure, and output format.

package/content/distilled/{create-issues → issues/references/create-issues}/SKILL.md

@@ -1,4 +1,4 @@
-<!-- skill: create-issues, version: 1.4.0, status: verified -->
+<!-- skill: create-issues, version: 1.4.1, status: verified -->
 # Tracer-Bullet Issue Creation from Plan
 
 Break a reviewed plan into independently grabbable issues using tracer-bullet vertical slices.
@@ -26,8 +26,10 @@ You are a Technical Project Manager. Translate a plan, spec, or PRD into thin en
      - **AFK** — can be implemented and merged without human intervention.
      - **HITL** — requires a human decision, approval, design review, copy review, policy signoff, etc.
    - Avoid tickets like “build backend”, “add UI”, or “refactor models first” unless the work is genuinely standalone.
+   - **Title lint (hard rule — run on every drafted title before presenting):** a title must name a user-visible outcome (“CSV export works end-to-end”), not a layer. If a title names a layer or artifact — backend, frontend, API, route, button, serializer, schema, tests-only, docs-only, refactor-only — merge it into the outcome slice it serves. Layers differing is never sufficient reason to split: split by capability, never by layer.
 
 4. **Review the proposed breakdown with the user:**
+   - Re-run the title lint on every drafted title; merge any layer-named ticket into its outcome slice before presenting.
    - Present a numbered list before creating anything.
    - For each slice include:
      - **Title**

package/content/distilled/planning/SKILL.md

@@ -0,0 +1,23 @@
+# Planning Router
+
+Route planning work to the right mode, then read that mode's instructions before acting.
+
+## Modes
+
+| Task signal | Mode | Read |
+|---|---|---|
+| design a phased implementation plan (TDD-oriented) from a goal | create-plan | `references/create-plan/SKILL.md` |
+| execute an existing plan phase by phase | implement-plan | `references/implement-plan/SKILL.md` |
+| review an implementation plan for gaps, risks, sequencing | plan-review | `references/plan-review/SKILL.md` |
+| refine an existing plan from feedback or new constraints | iterate-plan | `references/iterate-plan/SKILL.md` |
+
+## Selection rules
+
+- No plan exists yet → **create-plan**. Plan exists and work is approved → **implement-plan**.
+- Plan exists but is under critique → **plan-review**; under revision → **iterate-plan**. Review first when feedback is vague, iterate when it is specific.
+- These modes chain: create-plan → plan-review → iterate-plan → implement-plan.
+
+## Procedure
+
+1. Identify the mode from the table above.
+2. Read the referenced file (resolve paths against this skill's directory); follow its templates and verification steps.

package/content/distilled/pointers/close.md

@@ -0,0 +1,7 @@
+# Moved: close
+
+This skill was consolidated into the **session** skill (router + references/ layout).
+
+Use `/close` no more: invoke `/skill:session` and follow its mode table — this task is the **close** mode, which reads `references/close/SKILL.md`.
+
+This pointer exists so old invocations keep working; it will be removed in a future release. Update your notes and configs to `/skill:session`.

package/content/distilled/pointers/create-handoff.md

@@ -0,0 +1,7 @@
+# Moved: create-handoff
+
+This skill was consolidated into the **session** skill (router + references/ layout).
+
+Use `/create-handoff` no more: invoke `/skill:session` and follow its mode table — this task is the **create-handoff** mode, which reads `references/create-handoff/SKILL.md`.
+
+This pointer exists so old invocations keep working; it will be removed in a future release. Update your notes and configs to `/skill:session`.

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

@@ -0,0 +1,7 @@
+# Moved: create-issues
+
+This skill was consolidated into the **issues** skill (router + references/ layout).
+
+Use `/create-issues` no more: invoke `/skill:issues` and follow its mode table — this task is the **create-issues** mode, which reads `references/create-issues/SKILL.md`.
+
+This pointer exists so old invocations keep working; it will be removed in a future release. Update your notes and configs to `/skill:issues`.

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

@@ -0,0 +1,7 @@
+# Moved: issue-review
+
+This skill was consolidated into the **issues** skill (router + references/ layout).
+
+Use `/issue-review` no more: invoke `/skill:issues` and follow its mode table — this task is the **issue-review** mode, which reads `references/issue-review/SKILL.md`.
+
+This pointer exists so old invocations keep working; it will be removed in a future release. Update your notes and configs to `/skill:issues`.

package/content/distilled/pointers/next.md

@@ -0,0 +1,7 @@
+# Moved: next
+
+This skill was consolidated into the **session** skill (router + references/ layout).
+
+Use `/next` no more: invoke `/skill:session` and follow its mode table — this task is the **next** mode, which reads `references/next/SKILL.md`.
+
+This pointer exists so old invocations keep working; it will be removed in a future release. Update your notes and configs to `/skill:session`.

package/content/distilled/pointers/park.md

@@ -0,0 +1,7 @@
+# Moved: park
+
+This skill was consolidated into the **session** skill (router + references/ layout).
+
+Use `/park` no more: invoke `/skill:session` and follow its mode table — this task is the **park** mode, which reads `references/park/SKILL.md`.
+
+This pointer exists so old invocations keep working; it will be removed in a future release. Update your notes and configs to `/skill:session`.

package/content/distilled/pointers/renew.md

@@ -0,0 +1,7 @@
+# Moved: renew
+
+This skill was consolidated into the **session** skill (router + references/ layout).
+
+Use `/renew` no more: invoke `/skill:session` and follow its mode table — this task is the **renew** mode, which reads `references/renew/SKILL.md`.
+
+This pointer exists so old invocations keep working; it will be removed in a future release. Update your notes and configs to `/skill:session`.

package/content/distilled/pointers/rule-of-5-universal.md

@@ -0,0 +1,7 @@
+# Moved: rule-of-5-universal
+
+This skill was consolidated into the **review** skill (router + references/ layout).
+
+Use `/rule-of-5-universal` no more: invoke `/skill:review` and follow its mode table — this task is the **rule-of-5-universal** mode, which reads `references/rule-of-5-universal/SKILL.md`.
+
+This pointer exists so old invocations keep working; it will be removed in a future release. Update your notes and configs to `/skill:review`.

package/content/distilled/prompt-meta/SKILL.md

@@ -0,0 +1,21 @@
+# Prompt-Meta Router
+
+Route prompt-engineering work on this repository's own content to the right mode, then read that mode's instructions before acting.
+
+## Modes
+
+| Task signal | Mode | Read |
+|---|---|---|
+| a successful interaction should become a reusable prompt | extract-prompt | `references/extract-prompt.md` |
+| an existing prompt is too long; produce a lean token-efficient distilled version | distill-prompt | `references/distill-prompt/SKILL.md` |
+| check a distilled prompt preserved the original's essential instructions | verify-prompt | `references/verify-prompt/SKILL.md` |
+
+## Selection rules
+
+- Nothing exists yet → **extract-prompt**. Source exists, needs shrinking → **distill-prompt**. Distilled exists → **verify-prompt** against the source.
+- The pipeline is extract → distill → verify; never skip verify when the distilled form will be installed.
+
+## Procedure
+
+1. Identify the mode from the table above.
+2. Read the referenced file (resolve paths against this skill's directory); follow its criteria and templates.

package/content/distilled/review/SKILL.md

@@ -0,0 +1,27 @@
+# Review Router
+
+Route a review request to the right review method, then read that method's instructions before acting.
+
+## Modes
+
+| Task signal | Mode | Read |
+|---|---|---|
+| "review this code/PR/change" — general multi-pass review | code-review | `references/code-review/SKILL.md` |
+| iterate any artifact (code, plan, spec, docs, research) through 5 editorial stages to convergence | rule-of-5-universal | `references/rule-of-5-universal/SKILL.md` |
+| high-stakes change needing parallel agent review waves | parallel-review | `references/parallel-review/SKILL.md` |
+| coordinate multiple agents for comprehensive review coverage | multi-agent-review | `references/multi-agent-review.md` |
+| adversarial pass hunting logic bugs, failure modes, security, deployment risk | red-team-review | `references/red-team-review.md` |
+| review that teaches the human the change and surrounding code | guided-review | `references/guided-review.md` |
+
+## Selection rules
+
+- Default code-review requests → **code-review**. Explicitly iterative/editorial refinement of any artifact → **rule-of-5-universal**.
+- "break it", "find vulnerabilities", "what could fail in production" → **red-team-review**.
+- More than one reviewer perspective is requested or stakes are high → **parallel-review** (agent waves) or **multi-agent-review** (coordination pattern).
+- The user wants to learn, not just fix → **guided-review**.
+
+## Procedure
+
+1. Identify the mode from the table above.
+2. Read the referenced file (resolve paths against this skill's directory). Multi-file modes have their own `references/` — follow their cross-references.
+3. Apply the mode's output format and convergence rules.

package/content/distilled/session/SKILL.md

@@ -0,0 +1,26 @@
+# Session Lifecycle Router
+
+Route a session-lifecycle task to the right mode, then read that mode's instructions before acting. Do not improvise a lifecycle ritual from memory — each mode encodes a specific, tested procedure.
+
+## Modes
+
+| Task signal | Mode | Read |
+|---|---|---|
+| "wrap up", "close session", end-of-session summary + commit + push + context clear | close | `references/close/SKILL.md` |
+| switch context now, will return later; stash work + release claims | park | `references/park/SKILL.md` |
+| fast snapshot, no ceremony; resume later via `/renew` | next | `references/next/SKILL.md` |
+| resume work on a project/area; load journal, whisper, beads context; claim work | renew | `references/renew/SKILL.md` |
+| generate a context/handoff document for session continuity | create-handoff | `references/create-handoff/SKILL.md` |
+| continue from a previous session's handoff document | resume-handoff | `references/resume-handoff/SKILL.md` |
+
+## Selection rules
+
+- Full ceremony with journal routing and push → **close**. Quick stash without ceremony → **next**. Context switch mid-session → **park**.
+- The user asks *how to continue later* → **create-handoff**; the user asks *to continue* from an existing handoff → **resume-handoff**.
+- "renew" always means resuming; "close" always means ending. When unsure whether the user wants to stop or stash, ask one clarifying question.
+
+## Procedure
+
+1. Identify the mode from the table above.
+2. Read the referenced file (resolve paths against this skill's directory).
+3. Follow that file's instructions exactly — they handle non-interactive shell quirks, `$JOURNAL_PATH` resolution, and beads/git state.

package/content/distilled/{close → session/references/close}/SKILL.md

@@ -1,8 +1,4 @@
----
-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
----
+**Tools:** Read, Write, Edit, Glob, Bash
 
 # Close Session
 

package/content/distilled/{next → session/references/next}/SKILL.md

@@ -1,8 +1,4 @@
----
-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
----
+**Tools:** Read, Write, Edit, Bash
 
 # Next
 

package/content/distilled/{park → session/references/park}/SKILL.md

@@ -1,8 +1,4 @@
----
-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
----
+**Tools:** Read, Write, Edit, Bash
 
 # Park
 

package/content/distilled/{renew → session/references/renew}/SKILL.md

@@ -1,8 +1,4 @@
----
-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
----
+**Tools:** Read, Write, Edit, Glob, Bash, Grep
 
 # Renew
 

package/content/distilled/whisper/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: whisper
-description: "Deterministic knowledge workspace management: init, check, status, link plan, decommission, and knowledge routing. Delegates the mechanical steps to the turu CLI (whisper-vibes) when installed; manual fallbacks otherwise. Trigger when the user says '/whisper', '/w', 'init workspace', 'check workspace', 'workspace status', 'link plan', or 'decommission'."
+description: "Knowledge workspace management: init, check, status, link plan, decommission, routing. Delegates to the turu CLI when installed."
 tools: Read, Write, Edit, Bash
 ---