@jaggerxtrm/specialists 3.10.0 → 3.12.0

package/config/skills/using-specialists-v2/SKILL.md

@@ -8,7 +8,7 @@ description: >
   work without drift. Trigger for code review, debugging, implementation,
   planning, test generation, doc sync, multi-chain epics, and any question about
   specialist orchestration.
-version: 1.0
+version: 1.4
 ---
 
 # Specialists V2
@@ -17,6 +17,22 @@ You are the orchestrator. Your job is to specify the work, choose the right spec
 
 Use this skill for substantial work: codebase exploration, debugging, implementation, review, testing, documentation sync, planning, specialist authoring, and multi-chain orchestration. Do small deterministic edits directly when the scope is already clear and delegation would add ceremony.
 
+For one-shot synchronous specialist invocations from services or scripts (template + variables, READ_ONLY, JSON out), use `using-script-specialists` instead. That runtime (`sp script` / `sp serve`) is unrelated to bead-first orchestration.
+
+## Update Awareness On Skill Load
+
+On first activation in a session, before substantial work, check whether the local specialists install is current:
+
+```bash
+LOCAL=$(node -p "require('./package.json').version" 2>/dev/null)
+LATEST=$(git ls-remote --tags --refs origin 2>/dev/null | grep -oE 'v[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -1 | sed 's/^v//')
+[ -n "$LATEST" ] && [ "$LOCAL" != "$LATEST" ] && echo "specialists v$LOCAL is local; v$LATEST published — consider /update-specialists before substantial work."
+```
+
+Skip the check entirely when `SPECIALISTS_OFFLINE=1` is set, when stdin is not a TTY (specialist-spawned subagent context), or when the previous turn already surfaced this notice. Surface at most one line — never block, never spam, never auto-update. The operator decides whether to run `/update-specialists`.
+
+When the local version is behind, the latest CHANGELOG entry can be summarized via `head -50 CHANGELOG.md` to anchor what changed; cross-link to the `update-specialists` skill for the actual reconcile flow.
+
 ## Hard Rules
 
 1. `--bead` is the prompt for tracked work.
@@ -24,14 +40,32 @@ Use this skill for substantial work: codebase exploration, debugging, implementa
 3. Never use `--prompt` to supplement tracked work. Update bead notes instead.
 4. Use explorer only when the implementation path is unknown.
 5. Use executor only after scope, constraints, and validation are clear enough to act.
-6. Edit-capable specialists use `--worktree` for the first implementation job.
-7. Reviewer gets its own bead and enters the executor workspace with `--job <exec-job>`.
-8. Use `--context-depth 2` for chained work unless there is a specific reason not to.
+6. Edit-capable specialists with `--bead` auto-provision a worktree. `--worktree` is still accepted for clarity but not required (the deprecated `--no-worktree` flag is gone).
+7. Reviewer gets its own bead and enters the executor workspace with `--job <exec-job>`. `--job` auto-resolves the bead if `--bead` is omitted.
+8. `--context-depth` defaults to 3 (parent task + predecessor + own bead). Override only when the chain needs less or more upstream context.
 9. Keep executor/debugger jobs alive through review so they can be resumed.
 10. Merge specialist branches with `sp merge` or `sp epic merge`, never manual `git merge`.
 11. Specialists must not perform destructive or irreversible actions.
 12. If a specialist fails, inspect feed/result and either steer, resume, rerun with a better bead, or report the blocker.
 13. Drive chains autonomously. Do not ask the operator to approve routine stage transitions. Escalate only on critical events (see Autonomous Drive section).
+14. Stale-base guard: dispatch refuses to provision a worktree when sibling epic chains have unmerged substantive commits. Override only with explicit `--force-stale-base` and a reason. Merge-time rebase happens automatically.
+15. Auto-checkpoint: executor and debugger commit substantive worktree changes on `waiting` by default (`auto_commit: checkpoint_on_waiting`). Noise paths (`.xtrm/`, `.wolf/`, `.specialists/jobs/`, `.beads/`) are filtered.
+16. Per-turn output appends to the input bead notes for **all** specialists on every `run_complete`, with `[WAITING — more output may follow]` or `[DONE]` headers. `bd show <bead-id>` is a valid path to read intermediate output.
+17. Specialist jobs do not orchestrate nested specialist chains. The top-level orchestrator dispatches specialists, collects results, and advances the workflow.
+18. Treat test failures as evidence to classify against the bead scope. Validate whether failures are in-scope, pre-existing, or infrastructure-related before sending an executor into a fix loop.
+
+## Canonical Runtime State
+
+These are current operating facts, not migration notes:
+
+- **Asset ownership:** Cat A runtime assets — specialists, mandatory-rules, catalog, and nodes — resolve live from the specialists package after project tiers. Cat B filesystem assets — skills and hooks — are owned by xtrm-tools under `.xtrm/skills/default` and `.xtrm/hooks/default`.
+- **Resolution precedence:** project/user tiers win over managed defaults; package-live is the final fallback. Mandatory-rule indexes are not stacked across tiers; per-id mandatory-rule files may fall through to package canonical when absent locally.
+- **Drift surface:** use `sp doctor --check-drift` to inspect stale managed defaults and `sp prune-stale-defaults --dry-run` to preview cleanup.
+- **Source verification:** resolver/catalog changes in a worktree are verified with `sp config show <name> --resolved --from-source` so evidence comes from the checked-out source, not an installed dist.
+- **Worktree publication:** edit-capable specialists produce worktree branches. Before review or merge, verify the branch diff and status from that worktree.
+- **Epic publication:** epics are the merge-gated identity. Publish through `sp epic merge`; use `sp epic abandon` to deliberately close failed or cancelled epic bookkeeping.
+- **CLI safety:** command help paths are side-effect free. New commands must parse `--help`/`-h` before action and have a no-write help test.
+- **Release context:** changelog-keeper receives xt report context through the `releasing` skill's helper. Release-range logic supports annotated tags.
 
 ## Autonomous Drive
 
@@ -72,7 +106,7 @@ Do not busy-loop `sp ps` in tight intervals. One sleep + one confirmation poll i
 
 ```bash
 # Dispatch
-JOB=$(sp run <specialist> --bead <bead-id> --context-depth 2 --background 2>&1 | tail -1)
+JOB=$(sp run <specialist> --bead <bead-id> --context-depth 3 --background 2>&1 | tail -1)
 
 # Sleep for median
 sleep 180
@@ -180,19 +214,24 @@ Run `specialists list` if you need the live registry. Choose by task, not by hab
 | Planning/decomposition | `planner` | You need beads, dependencies, file scopes, or sequencing. |
 | Design/tradeoffs | `overthinker` | The approach is risky, ambiguous, or needs critique. |
 | Implementation | `executor` | The contract is clear enough to write code or docs. |
-| Compliance/code review | `reviewer` | An executor/debugger produced changes that need a verdict. |
+| Compliance/code review | `reviewer` | An executor/debugger produced changes that need the final PASS/PARTIAL/FAIL verdict. |
+| Implementation sanity | `code-sanity` | You want a cheap READ_ONLY smell pass for simplicity, type safety, dead code, brittle async/error handling, or maintainability before reviewer. |
+| Security/dependency audit | `security-auditor` | You need threat modeling, secure-code review, package advisory triage, or agent/config security scanning. LOW: scan/read/recommend only. |
 | Multiple review perspectives | `parallel-review` | A critical diff needs independent review passes. |
 | Test execution | `test-runner` | You need suites run and failures interpreted. |
 | Docs audit/sync | `sync-docs` | Docs may be stale or need targeted synchronization. |
-| External/live research | `researcher` | Current library/docs/media lookup is needed. |
+| External/live research | `researcher` | Current non-security library/docs/media lookup is needed. |
 | Specialist config | `specialists-creator` | Creating or changing specialist JSON/config. |
+| Release publication (end-to-end) | `changelog-keeper` | A new tag is being cut. MEDIUM specialist: drafts CHANGELOG section from xt reports, bumps package.json, rebuilds dist, commits, tags, pushes. Use the `releasing` skill to dispatch. |
 
 Selection rules:
 
 - Explorer is READ_ONLY and should answer specific questions.
 - Debugger is better than explorer for failures because it traces causes and remediation.
 - Executor does not own full test validation; use reviewer/test-runner for that phase.
-- Reviewer always uses its own bead plus `--job <executor-job>`.
+- Code-sanity is optional and non-blocking by default: use it when a diff smells overcomplicated or type-risky, then resume executor with concrete findings. It is not a merge gate.
+- Security-auditor may run safe local audit commands and web/source research, but must not edit files, update dependencies, exfiltrate secrets, or run destructive/live-target exploit tests. Executor applies any recommended fixes in a separate bead.
+- Reviewer always uses its own bead plus `--job <executor-job>` and remains the final merge gate.
 - Sync-docs is for audit/sync; executor is for heavy doc rewrites.
 - Specialists-creator should precede specialist config/schema edits.
 
@@ -202,15 +241,21 @@ Daily commands:
 
 ```bash
 specialists list
+specialists list-rules                          # rule × specialist matrix
 specialists doctor
-specialists run <name> --bead <id> --context-depth 2 --background
-specialists run executor --worktree --bead <impl-bead> --context-depth 2 --background
-specialists run reviewer --bead <review-bead> --job <exec-job> --context-depth 2 --keep-alive --background
+specialists doctor --check-drift                 # inspect stale .specialists/default snapshots
+sp prune-stale-defaults --dry-run                # preview redundant default snapshots
+specialists run <name> --bead <id> --background
+specialists run executor --bead <impl-bead> --background       # worktree auto-provisioned
+specialists run code-sanity --bead <sanity-bead> --job <exec-job> --keep-alive --background
+specialists run security-auditor --bead <security-bead> --job <exec-job> --keep-alive --background
+specialists run reviewer --bead <review-bead> --job <exec-job> --keep-alive --background
 specialists ps
 specialists ps <job-id>
 specialists feed <job-id>
 specialists feed -f
-specialists result <job-id>
+specialists result <job-id>                     # works on done/error/waiting
+specialists result <job-id> --wait --timeout 600
 specialists steer <job-id> "new direction"
 specialists resume <job-id> "next task"
 specialists stop <job-id>
@@ -223,20 +268,25 @@ sp merge <chain-root-bead>
 sp epic status <epic-id>
 sp epic sync <epic-id> --apply
 sp epic merge <epic-id>
+sp epic abandon <epic-id> --reason "..."
 sp end
 ```
 
-Avoid `specialists status --job` for normal monitoring; prefer `sp ps <job-id>`.
+`sp result <job-id>` returns the most recent completed turn for `waiting` jobs with a `Session is waiting for your input` footer — use it to inspect a keep-alive job before deciding whether to resume. For `running` jobs, `sp feed <job-id>` is the right tool; `sp poll` is deprecated. Avoid `specialists status --job` for normal monitoring; prefer `sp ps <job-id>`.
 
 ## Flag Semantics
 
 `--bead <id>` is the task prompt and tracked work identity.
 
-`--context-depth N` controls parent/ancestor bead context. Use `--context-depth 2` for chains so the specialist sees its own bead, predecessor output, and parent task context.
+`--context-depth N` controls parent/ancestor bead context. Default is **3** (own bead + predecessor + parent task). Lower it when the chain is shallow or the parent context is noisy.
+
+`--worktree` provisions a new isolated workspace and branch for edit-capable work. Optional when `--bead` is provided to an edit-capable specialist — a worktree is auto-provisioned. Pass `--worktree` explicitly only when you want it without a bead, or for emphasis. The deprecated `--no-worktree` flag is removed and now errors out.
 
-`--worktree` provisions a new isolated workspace and branch for edit-capable work. Use it for the first executor/debugger job that writes files.
+`--job <id>` reuses an existing job's workspace. Use it for reviewer and fix passes. If `--bead` is omitted, bead_id is inferred from the target job's status; explicit `--bead` always wins.
 
-`--job <id>` reuses an existing job's workspace. Use it for reviewer and fix passes. The caller's own `--bead` remains authoritative; `--job` only selects the workspace.
+`--force-job` overrides the concurrency lock that blocks edit-capable specialists from entering an owner workspace while it is `starting`/`running`. Use only when you accept the write race; prefer `sp stop` on dead jobs first.
+
+`--force-stale-base` bypasses the dispatch-time stale-base guard that blocks `--worktree` provisioning when sibling epic chains have unmerged substantive commits. Use only with a clear reason; the guard prevents merge-conflict cascades.
 
 `--epic <id>` explicitly associates a job with an epic. Use it for prep jobs whose parent is not the epic but should appear in epic status/readiness.
 
@@ -273,7 +323,7 @@ CONSTRAINTS: READ_ONLY; cite files/symbols.
 VALIDATION: Findings include recommended executor scope and risks.
 OUTPUT: Evidence-backed implementation plan."
 bd dep add <explore> <task>
-specialists run explorer --bead <explore> --context-depth 2 --background
+specialists run explorer --bead <explore> --context-depth 3 --background
 specialists result <explore-job>
 ```
 
@@ -289,10 +339,46 @@ CONSTRAINTS: Keep telemetry names stable; avoid broad refactor.
 VALIDATION: npm run lint, npx tsc --noEmit, targeted auth tests if available.
 OUTPUT: Diff summary, checks run, follow-up risks."
 bd dep add <impl> <explore-or-task>
-specialists run executor --worktree --bead <impl> --context-depth 2 --background
+specialists run executor --worktree --bead <impl> --context-depth 3 --background
 specialists result <exec-job>
 ```
 
+Optional code-sanity pass for implementation smell checks (use when the diff is non-trivial or likely to accumulate agent-code complexity):
+
+```bash
+bd create --title "Code sanity check token refresh retry" --type task --priority 3 \
+  --description "PROBLEM: Cheap READ_ONLY sanity pass for executor implementation quality before final review.
+SUCCESS: Identify concrete simplicity/type-safety/maintainability findings, or return OK.
+SCOPE: executor job <exec-job>, implementation diff only.
+NON_GOALS: No requirements verdict, no security audit, no test execution, no edits.
+CONSTRAINTS: At most 5 concrete findings; cite files/symbols/lines where possible.
+VALIDATION: Findings are suitable to paste into specialists resume <exec-job>.
+OUTPUT: OK/FINDINGS/BLOCKED with handoff."
+bd dep add <sanity> <impl>
+specialists run code-sanity --bead <sanity> --job <exec-job> --context-depth 3 --keep-alive --background
+specialists result <sanity-job>
+```
+
+If code-sanity returns `FINDINGS`, resume executor with those concrete instructions, then rerun code-sanity only if the fixes were substantive. Do not treat code-sanity `OK` as reviewer PASS.
+
+Optional security pass when the task touches auth, secrets, input handling, dependency updates, package advisories, agent config, hooks, or exposed endpoints:
+
+```bash
+bd create --title "Security audit token refresh retry" --type task --priority 2 \
+  --description "PROBLEM: Scoped security/dependency/config audit for executor changes.
+SUCCESS: Identify evidence-backed security findings or return no findings.
+SCOPE: executor job <exec-job>, changed files, relevant manifests/config only.
+NON_GOALS: No edits, no package updates, no destructive scans, no live exploit testing.
+CONSTRAINTS: LOW permission; recommendations only. HN/social signals are not authoritative proof.
+VALIDATION: Findings cite local evidence or OSV/GHSA/NVD/vendor/package-audit sources.
+OUTPUT: Security audit summary, findings, dependency triage, residual risk."
+bd dep add <security> <impl>
+specialists run security-auditor --bead <security> --job <exec-job> --context-depth 3 --keep-alive --background
+specialists result <security-job>
+```
+
+If security-auditor recommends code or dependency changes, create/resume an executor fix bead. Do not let security-auditor apply updates.
+
 Create review bead:
 
 ```bash
@@ -305,7 +391,7 @@ CONSTRAINTS: Findings first with file/line references.
 VALIDATION: Inspect diff and available checks.
 OUTPUT: PASS/PARTIAL/FAIL verdict with required fixes."
 bd dep add <review> <impl>
-specialists run reviewer --bead <review> --job <exec-job> --context-depth 2 --keep-alive --background
+specialists run reviewer --bead <review> --job <exec-job> --context-depth 3 --keep-alive --background
 specialists result <review-job>
 ```
 
@@ -353,7 +439,7 @@ CONSTRAINTS: READ_ONLY; produce dependency plan.
 VALIDATION: Plan names file scopes and merge order.
 OUTPUT: Parallel track plan."
 bd dep add <plan> <epic>
-specialists run planner --bead <plan> --epic <epic> --context-depth 2 --background
+specialists run planner --bead <plan> --epic <epic> --context-depth 3 --background
 ```
 
 Create independent implementation beads only when write scopes are disjoint:
@@ -383,8 +469,8 @@ bd dep add <impl-docs> <plan>
 Run parallel executors only if scopes are disjoint:
 
 ```bash
-specialists run executor --worktree --bead <impl-cli> --context-depth 2 --background
-specialists run executor --worktree --bead <impl-docs> --context-depth 2 --background
+specialists run executor --worktree --bead <impl-cli> --context-depth 3 --background
+specialists run executor --worktree --bead <impl-docs> --context-depth 3 --background
 ```
 
 Review each chain with its own review bead and `--job`.
@@ -406,6 +492,12 @@ Standard loop:
 ```text
 executor --worktree --bead impl
   -> waiting after turn
+optional code-sanity --bead sanity --job exec-job
+  -> OK: continue
+  -> FINDINGS: resume executor with exact sanity findings
+optional security-auditor --bead security --job exec-job
+  -> no findings: continue
+  -> findings: create/resume executor fix bead; auditor never edits
 reviewer --bead review --job exec-job
   -> PASS: verify commit, publish, stop members if needed
   -> PARTIAL: resume executor with exact findings
@@ -414,7 +506,7 @@ reviewer --bead review --job exec-job
 
 Prefer `sp resume <exec-job>` over a new fix executor when the original job is waiting and context is healthy. Use a new fix bead with `--job <exec-job>` only when the original executor is dead, context exhausted, or a separate audit trail is required.
 
-Reviewer output must be consumed before publishing. Do not treat job completion as equivalent to acceptance.
+Code-sanity and security-auditor outputs are advisory inputs to the chain; reviewer output must still be consumed before publishing. Do not treat job completion, code-sanity OK, or security no-findings as equivalent to reviewer acceptance.
 
 ## Dependency Mapping
 
@@ -454,11 +546,20 @@ Use `sp ps` instead of ad-hoc polling.
 sp ps
 sp ps <job-id>
 sp ps --follow
+sp ps --running                       # only starting/running/waiting jobs
+sp ps --bead <bead-id>                # only jobs linked to one bead
+sp ps --since 30m                     # only jobs started in the last 30 minutes
+sp ps --mine                          # only jobs whose bead is assigned to you
+sp ps --include-terminal              # include merged/abandoned epics (hidden by default)
 sp feed <job-id>
 sp result <job-id>
 ```
 
-Read results at every stage. For READ_ONLY specialists, output also appends to the input bead notes. If result is empty, inspect feed and rerun or switch specialists before relying on it.
+Filter flags compose: `sp ps --running --bead <id>` is the canonical way to inspect "what's actively working on this issue right now". By default `sp ps` hides epics in `merged` or `abandoned` state to keep the snapshot focused; use `--include-terminal` (or `--all`) to bring them back.
+
+When dead epics pile up in `failed` state (sibling-chain conflicts, manual stops), recover with `sp epic abandon <epic-id> --reason "<text>"`. The `failed -> abandoned` transition is allowed specifically for cleanup; live members still require `--force`.
+
+Read results at every stage. Every specialist (not just READ_ONLY) auto-appends per-turn output to the input bead notes on each `run_complete`, with `[WAITING]` or `[DONE]` headers — `bd show <bead-id>` shows the full handoff trail. `sp result <job-id>` works on `waiting` jobs and returns the most recent turn plus a "Session is waiting for your input" footer; use it to decide whether to resume. If result is empty, inspect feed and rerun or switch specialists before relying on it.
 
 Context percentage in `sp ps`/feed is an action signal:
 
@@ -467,6 +568,8 @@ Context percentage in `sp ps`/feed is an action signal:
 - 65-80%: steer toward conclusion.
 - Above 80%: finish, summarize, or replace the job.
 
+Do not confuse raw token totals with context percentage. `sp ps` may show raw token counts around 50k-100k for large-context models; that alone is not a stop signal. Use the context percentage when available, plus stalls, repeated edit failures, or scope drift.
+
 ## Steering And Resume
 
 Use `steer` for running jobs:
@@ -506,6 +609,28 @@ Rules:
 - Merge between stages only when later stages need the code on the main line.
 - Run or confirm required gates before closing the root bead or epic.
 
+## Release Publication
+
+Tagged releases go through the `releasing` skill, which dispatches the
+`changelog-keeper` MEDIUM specialist. The specialist reads xt session
+reports via the releasing skill's `xt-reports.ts` helper, drafts the new
+section into `CHANGELOG.md`, bumps `package.json`, rebuilds `dist/`, commits
+with `release: vX.Y.Z`, tags, and pushes `--follow-tags`. Optional
+`gh release create` if the bead requests it.
+
+Operator gate: a single `git diff --stat HEAD~1 HEAD` after the specialist
+finishes. Must show only `CHANGELOG.md`, `package.json`, `dist/`. Anything
+else means scope was violated — revert and refile.
+
+The `changelog-keeper-scope` mandatory rule enforces the edit whitelist at
+the specialist level. See `config/skills/releasing/SKILL.md` for the bead
+template, dispatch command, and recovery commands.
+
+Release helper contract:
+
+- Report extraction is provided by the `releasing` skill, so consumer repos do not need repo-local release helper scripts.
+- Release ranges support annotated tags and should be validated through the same path used by tagged releases.
+
 ## Epic Lifecycle
 
 Epics are merge-gated identities with a persisted state machine:
@@ -550,7 +675,7 @@ Override with `--force-job` only when the caller explicitly accepts the write
 race (e.g. emergency fix into a stalled-but-not-terminal executor):
 
 ```bash
-sp run executor --bead <fix-bead> --job <stalled-exec-job> --force-job --context-depth 2 --background
+sp run executor --bead <fix-bead> --job <stalled-exec-job> --force-job --context-depth 3 --background
 ```
 
 Do not use `--force-job` as a routine unblock. Inspect `sp ps <job-id>` and
@@ -598,10 +723,13 @@ Do not silently fall back to doing substantial specialist work yourself unless t
 Dead or zombie process:
 
 ```bash
-sp stop <job-id>
-specialists clean --processes
+sp stop <job-id>                                # explicit single-job stop
+sp clean --processes --dry-run                  # preview stale non-terminal cancellations (PID-dead OR > --stale-after, default 24h)
+sp clean --processes                            # apply: cancel stale rows in observability.db
 ```
 
+`sp clean --processes` reads from `observability.db` (DB-first) and uses PID liveness as the primary gate — alive PIDs are never cancelled regardless of age. The `--stale-after <hours>` fallback applies only when a row has no recorded PID. `sp clean` with no flags purges terminal rows older than `SPECIALISTS_JOB_TTL_DAYS` (7d default); `--all` purges all terminals; `--keep <n>` retains the N most recent.
+
 Epic state unclear:
 
 ```bash
@@ -609,13 +737,17 @@ sp epic status <epic-id>
 sp epic sync <epic-id> --apply
 ```
 
-Specialist missing or config skipped:
+Specialist missing, config skipped, or stale default snapshots:
 
 ```bash
 specialists list
 specialists doctor
+specialists doctor --check-drift
+sp prune-stale-defaults --dry-run
 ```
 
+`sp prune-stale-defaults` is intentionally operator-facing. Always run `--dry-run` first unless the bead explicitly asks to apply cleanup.
+
 Worktree already exists:
 
 ```text
@@ -628,6 +760,8 @@ Reviewer cannot enter job workspace:
 Check target job status with sp ps. MEDIUM/HIGH jobs are blocked from entering a running write-capable workspace unless forced.
 ```
 
+When resolver/catalog changes are under review inside a worktree, run `sp config show <name> --resolved --from-source` so reviewer sees local source behavior, not installed dist.
+
 Explorer produced empty output:
 
 ```text

package/config/skills/using-specialists-v3/SKILL.md

@@ -0,0 +1,284 @@
+---
+name: using-specialists-v3
+description: >
+  Canonical specialist orchestration skill. Use proactively for substantial work
+  that should be delegated, tracked, reviewed, fixed, tested, or merged through
+  specialists: code review, debugging, implementation, planning, doc sync,
+  security checks, multi-step chains, and questions about specialist workflow.
+version: 3.1
+---
+
+# Using Specialists v3
+
+You are the orchestrator. Your job is to turn user intent into a clear bead contract, choose the right specialist from the live registry, launch the chain, monitor it, consume results, drive fixes, and publish through the specialist merge path.
+
+Keep this skill practical. It should contain the core behavior needed to orchestrate well; use live commands for volatile details instead of embedding a static catalog.
+
+## When To Delegate
+
+Use specialists for substantial work: codebase exploration, debugging, implementation, review, test execution, planning, documentation sync, security/config audit, release publication, and multi-chain epics.
+
+Do small deterministic edits directly when the scope is already obvious and delegation would add ceremony. Do not self-investigate or self-implement a substantial task just because you can read files faster; the audit trail and specialist review are part of the workflow.
+
+## Non-Negotiable Rules
+
+1. `--bead` is the prompt for tracked work.
+2. Do not dispatch until the bead is a usable task contract.
+3. Never use `--prompt` to supplement tracked work. Update the bead instead.
+4. Choose by task shape, not by habit. Check `specialists list --full` when roles may have changed.
+5. Explorer/debugger answer uncertainty before executor writes code.
+6. Executor starts only when scope, constraints, and validation are clear.
+7. Reviewer uses its own bead and the executor workspace via `--job <exec-job>`.
+8. Keep executor/debugger jobs alive through review so they can be resumed.
+9. Merge specialist-owned work with `sp merge` or `sp epic merge`, not manual `git merge`.
+10. Specialists must not perform destructive or irreversible operations.
+11. Treat tests as evidence: classify failures as in-scope, pre-existing, or infrastructure before starting a fix loop.
+12. Drive routine stages autonomously once the task is clear. Escalate only for human judgment, destructive actions, repeated crashes, or reviewer `FAIL`.
+
+## Live Registry And Help
+
+Use the live registry for role details, permissions, current models, and skills:
+
+```bash
+specialists list --full
+```
+
+Use help for command flags and subcommands:
+
+```bash
+sp help
+sp run --help
+sp ps --help
+sp feed --help
+sp result --help
+sp resume --help
+sp merge --help
+sp epic --help
+```
+
+Do not rely on stale remembered flags when help is available.
+
+## Role Selection
+
+Common routing:
+
+| Need | Specialist |
+| --- | --- |
+| Unknown architecture, call flow, dependencies, implementation options | `explorer` |
+| Symptom, stack trace, regression, flaky/failing test, root cause | `debugger` |
+| Broad feature decomposition, bead board, dependencies, sequencing | `planner` |
+| Risky design choice, tradeoff, premortem, critique | `overthinker` |
+| Clear implementation or scoped doc edit | `executor` |
+| Cheap implementation-quality smell pass before final review | `code-sanity` |
+| Security/config/dependency audit with recommendations only | `security-auditor` |
+| Final compliance verdict on executor/debugger diff | `reviewer` |
+| Run checks and interpret failures without fixing | `test-runner` |
+| Exactly one doc needs drift-aware sync | `sync-docs` |
+| Current external docs/API/ecosystem research | `researcher` |
+| Create or fix specialist config/schema | `specialists-creator` |
+| Release changelog/package/dist/tag publication | `changelog-keeper` through the `releasing` skill |
+
+Selection rules:
+
+- Use `explorer` when you need evidence before deciding what to change.
+- Use `debugger` instead of explorer when there is a failure symptom.
+- Use `executor` only after the task can name target files/symbols or a bounded discovery result.
+- Use `reviewer` as the merge gate; code-sanity and security-auditor are advisory.
+- Use `test-runner` for running/classifying tests; it does not implement fixes.
+- Use `specialists-creator` before changing specialist definitions.
+
+## Bead Contract
+
+Every specialist-bound bead must be a usable prompt. Title-only beads are not acceptable.
+
+Required structure:
+
+```text
+PROBLEM: What is wrong or needed.
+SUCCESS: Observable completion criteria.
+SCOPE: Files, symbols, commands, docs, or discovery area.
+NON_GOALS: Explicitly out of scope.
+CONSTRAINTS: Safety, compatibility, style, permissions, sequencing.
+VALIDATION: Checks/tests/review expected before closure.
+OUTPUT: Expected handoff format.
+```
+
+If the existing issue is vague, update it before dispatch:
+
+```bash
+bd update <id> --notes "CONTRACT: ..."
+```
+
+Contract tuning by role:
+
+- Explorer: ask specific questions; require citations to files/symbols/flows; forbid implementation.
+- Debugger: include symptom, reproduction, expected/actual behavior, logs/tests; ask for root cause and minimal fix path.
+- Executor: name target files/symbols and do-not-touch boundaries; require verification evidence.
+- Reviewer: reference the executor job, diff, acceptance criteria, constraints, and required verdict format.
+- Test-runner: name exact commands/suites and expected classification of failures.
+- Sync-docs: exactly one doc in scope.
+
+## Canonical Single-Chain Flow
+
+Use this for one implementation branch.
+
+```bash
+# 1. Create or claim root task bead with complete contract
+bd create --title "..." --type task --priority 2 --description "PROBLEM: ..."
+bd update <task> --claim
+
+# 2. Optional discovery when path is unknown
+bd create --title "Explore ..." --type task --priority 2 --description "PROBLEM: ... OUTPUT: evidence-backed plan."
+bd dep add <explore> <task>
+specialists run explorer --bead <explore> --context-depth 3
+specialists result <explore-job>
+
+# 3. Implementation
+bd create --title "Implement ..." --type task --priority 2 --description "PROBLEM: ... VALIDATION: ..."
+bd dep add <impl> <explore-or-task>
+specialists run executor --bead <impl> --context-depth 3
+specialists result <exec-job>
+
+# 4. Optional advisory passes
+specialists run code-sanity --bead <sanity-bead> --job <exec-job> --context-depth 3
+specialists run security-auditor --bead <security-bead> --job <exec-job> --context-depth 3
+
+# 5. Final review
+bd create --title "Review ..." --type task --priority 2 --description "PROBLEM: Verify executor output ... OUTPUT: PASS/PARTIAL/FAIL."
+bd dep add <review> <impl>
+specialists run reviewer --bead <review> --job <exec-job> --context-depth 3
+specialists result <review-job>
+
+# 6. Publish after reviewer PASS
+sp merge <impl>
+bd close <task> --reason "Reviewer PASS; merged."
+```
+
+Edit-capable specialists with `--bead` auto-provision a worktree. `--worktree` is accepted for clarity but is usually unnecessary. Use `--job <exec-job>` for reviewer/fix passes that must enter the existing executor workspace.
+
+## Review And Fix Loop
+
+A chain stays alive until it is merged or abandoned.
+
+```text
+executor/debugger -> waiting
+optional code-sanity/security-auditor -> advisory findings
+reviewer -> PASS | PARTIAL | FAIL
+```
+
+- `PASS`: verify expected commit/diff, then publish.
+- `PARTIAL`: resume the same executor/debugger with exact findings, then re-review.
+- `FAIL`: stop and decide whether to replace the chain, re-scope the bead, or ask the operator if judgment is required.
+
+Prefer resume over spawning a new fix executor when the original job is waiting and context is healthy:
+
+```bash
+sp resume <exec-job> "Reviewer PARTIAL. Fix only these findings: ..."
+```
+
+Do not treat job completion, code-sanity OK, or security no-findings as equivalent to reviewer PASS.
+
+## Monitoring And Steering
+
+Use `sp ps` for state and `sp result` for completed turns.
+
+```bash
+sp ps
+sp ps <job-id>
+sp ps --bead <bead-id>
+sp feed <job-id>          # live/running output
+sp result <job-id>        # done/error/waiting result
+```
+
+If a job is running, use `sp feed`. If it is waiting, use `sp result` and decide whether to resume, review, merge, or stop. Avoid tight polling; sleep based on task size, then check once.
+
+Use `steer` for running jobs and `resume` for waiting jobs:
+
+```bash
+sp steer <job-id> "Stop broad audit. Answer only the three bead questions."
+sp resume <job-id> "Continue with the next scoped fix. Do not refactor."
+```
+
+Context usage is an action signal when available:
+
+- 0-40%: healthy.
+- 40-65%: monitor.
+- 65-80%: steer toward conclusion.
+- Above 80%: finish, summarize, or replace the job.
+
+Raw token totals are not context percentages.
+
+## Merge And Publication
+
+Standalone chain:
+
+```bash
+sp merge <chain-root-bead>
+```
+
+Epic-owned chains:
+
+```bash
+sp epic status <epic-id>
+sp epic merge <epic-id>
+```
+
+Rules:
+
+- Merge only after reviewer PASS unless the operator explicitly accepts a draft for follow-up work.
+- Use `sp epic merge` for unresolved epic chains; `sp merge` refuses those by design.
+- Do not manually `git merge` specialist branches.
+- If merge refuses because a chain job is still `waiting`, consume the result and either resume/stop/finalize that job deliberately.
+- If merge reports a dirty worktree, inspect that worktree. Revert generated noise only when it is clearly unrelated; otherwise ask or re-dispatch.
+- Run or confirm required gates before closing the root bead or epic.
+
+## Multi-Chain Epic Flow
+
+Use an epic when multiple implementation chains publish together.
+
+1. Create an epic bead with complete contract.
+2. Use planner/explorer for shared prep if needed.
+3. Create independent implementation beads with disjoint file scopes.
+4. Dispatch executors in parallel only when scopes are provably disjoint.
+5. Review each chain with its own review bead and `--job`.
+6. After every chain has reviewer PASS, publish with `sp epic merge <epic-id>`.
+
+Use `--epic <id>` when a job belongs to an epic but its bead is not a direct child. Avoid parallel executors on the same file; sequence them or consolidate the work.
+
+## Failure Recovery
+
+When something fails:
+
+```bash
+sp ps <job-id>
+sp feed <job-id>
+sp result <job-id>
+sp doctor
+```
+
+Then choose one action:
+
+- Steer a running job back to scope.
+- Resume a waiting job with exact next instructions.
+- Stop a dead or obsolete job.
+- Rerun with a better bead contract.
+- Switch specialist if the selected role was wrong.
+- Report blocker if destructive/high-risk/manual action is required.
+
+Common recovery commands:
+
+```bash
+sp stop <job-id>
+sp clean --processes --dry-run
+sp epic status <epic-id>
+sp epic sync <epic-id> --apply
+sp epic abandon <epic-id> --reason "..."
+specialists doctor --check-drift
+sp prune-stale-defaults --dry-run
+```
+
+Do not silently take over substantial specialist work yourself unless the operator agrees or the remaining change is genuinely small and deterministic.
+
+## What Stays Out Of This Skill
+
+Do not embed the full specialist catalog, all CLI help, release mechanics, stale incident reports, or historical gotchas. Keep volatile detail in `specialists list --full`, `sp help`, bead notes, and focused skills such as `releasing`, `using-nodes`, or `specialists-creator`.