spellbook

Use when deciding whether to dispatch subagents, when to stay in main context, or when facing 2+ independent parallel tasks. Triggers: 'should I use a subagent', 'parallelize', 'multiple independent tasks', 'run these at the same time', 'split this up', 'do both at once', 'dispatch template', 'context minimization'.

Use when writing or de-slopping outward-facing prose: newsletters, blog posts, announcements, marketing or landing copy, emails, release notes, doc intros. Triggers: 'make this sound human', 'this reads like AI', 'de-slop this', 'remove the AI tells', 'make it less AI', 'why does this sound like ChatGPT', 'help me draft this piece', 'write a newsletter', 'write a blog post', 'polish this copy', 'tighten this'. Composes with a personal voice skill (for example my-voice-skill) that supplies identity and register; this skill is voice-neutral and supplies the writing process plus the anti-slop catalog. NOT for: code logic or code review (use code-review), project doc structure (use documenting-projects), READMEs (use write-readme / polish-repo), or a specific person's voice (use their voice skill).

Use when building, creating, modifying, or planning any code change. Triggers: "implement X", "build Y", "add feature Z", "create X", "change how X works", "modify Y", "update the Z", "refactor X", "rework Y", "restructure Z", "make X do Y", "let's plan how to", "plan the implementation", "how should we implement", "how would you build", "what's the best way to implement", "I want to...", "We need...", "Would be great to...", "Can we add...", "Let's add...", "Let's build...", "Let's make...", "start a new project". Also for: new projects, repos, templates, greenfield development, refactoring, migrations, multi-file modifications, any code change requiring planning. PREFER THIS OVER plan mode or ad-hoc implementation for ANY substantive code change. NOT for: bug fixes (use debugging), pure research (use deep-research), questions about existing code without intent to change it, or test-only fixes (use fixing-tests).

Algorithmically estimate engineering tickets, JIRA cards, test cards, or feature requests. Produces well-scoped, AI-productivity-adjusted, PERT-buffered estimates with 80/90/95% confidence intervals for single and multi-engineer execution. Triggers - "estimate this ticket", "estimate this card", "estimate this test card", "size this", "story point this", "/estimate", "how long will this take", "T-shirt this", "point this story", "planning poker", "PERT estimate", "give me a timeline", "scope this work".

Use when implementation is complete, tests pass, and you need to decide the integration path. Also use when asked to prepare a branch for release: 'update changelog', 'bump version', 'bump patch version', 'make sure changelog is correct', 'make sure version is correct'. Triggers: 'done with this branch', 'ready to merge', 'ship it', 'wrap this up', 'how should I integrate this', 'what next after implementation'. NOT for: PR creation mechanics (use creating-issues-and-pull-requests) or deciding whether to merge (use finishing-a-development-branch first).

Use when an operator decision belongs on a browser page rather than a terminal prompt. Triggers: "present a decision in the browser", "ask via a canvas page", "interactive decision page", "let me decide in the browser", "render the choice visually". Also invoked by develop when the decision-surface preference is `canvas` (feature-config Question 8). NOT for: quick yes/no with no context (use terminal `AskUserQuestion`), read-only presentation (use `canvas`), or subagent-internal choices with no operator (decide in-context).

Use when the user wants to present rendered output (diagrams, plans, charts, status, side-by-side options) outside the terminal. Triggers: 'open a canvas', '/canvas', 'put this in a canvas', 'visualize this', 'render this in the browser', 'canvas name', 'close the canvas'. NOT for: live-editable artifacts where the browser writes (use a2a for that), persisted documents (use ~/.local/spellbook/docs/), or anything requiring SSR.

Use when the user wants two or more Claude/agent sessions to talk to each other via the filesystem. Triggers: 'your name for inter-agent chat is X', 'your a2a name is X', 'listen for messages', 'open as X', 'talk to the session named Y', 'send a message to session Y', 'check the inbox', 'reply to that session', 'inter-agent chat', 'inter-agent messaging', 'agent2agent', 'a2a', 'agent bus', 'message another session', 'tell session Y to', 'ask session Y'. NOT for: dispatching subagents within one session (use the Task tool), or pub-sub between non-Claude processes (use a real broker like Redis).

Use when scattered Claude Code sessions need to be found, grouped by effort, relocated to the right worktree's resume picker, or reopened together. Triggers: 'round up my sessions', 'find my worktree sessions', 'reopen my claude sessions by worktree', 'reorient sessions', 'relaunch sessions', 'resume my recent sessions grouped by worktree', 'my sessions are scattered', 'open all sessions for this effort'. NOT for: relocating a project's sessions because the CODE moved (use move-project); creating worktrees (use using-git-worktrees).

Use when consolidating overlapping instruction files, auditing skills for duplicated guidance, or pruning paraphrased prose across a markdown corpus. Triggers: 'dedupe these skills', 'dedupe these instructions', 'find duplicate instructions', 'consolidate instruction files', 'find paraphrased prose', 'collapse redundant skills', 'are these saying the same thing'.

Use when performing thorough code review with historical context tracking. Triggers: 'thorough review', 'deep review', 'review this branch in detail', 'full code review with report', 'branch code review', 'review this branch', 'review the changes', 'review what's on this branch', 'do a code review of the branch'. More heavyweight than code-review; for quick review, use code-review instead. When the request could match more than one review skill, MUST use AskUserQuestion to disambiguate before invoking — never bypass the review skills for a raw Explore dispatch, even when the user's concerns seem narrow or specific.

Use when evaluating skill effectiveness or comparing skill versions. Triggers: 'how are skills performing', 'skill metrics', 'which skills fire correctly', 'skill invocation analysis', 'compare skill versions', 'analyze skill usage'. Also invoked by skill improvement workflows.

DEPRECATED: This skill has been absorbed into the develop skill. Use develop instead. The capabilities of autonomous-roundtable (project decomposition, roundtable gating, reflexion on ITERATE) are now available through develop's dialectic_mode and token_enforcement preferences. Set dialectic_mode to "roundtable" in Phase 0.4 for equivalent behavior.

Use when reviewing code. Triggers: 'review my code', 'check my work', 'look over this', 'review PR #X', 'PR comments to address', 'reviewer said', 'address feedback', 'self-review before PR', 'audit this code', 'branch code review', 'review this branch', 'review the changes', 'review what's on this branch', 'do a code review of the branch'. For heavyweight multi-phase analysis, use advanced-code-review instead. When the request could match more than one review skill, MUST use AskUserQuestion to disambiguate before invoking — never bypass the review skills for a raw Explore dispatch, even when the user's concerns seem narrow or specific.

Use when debugging bugs, test failures, or unexpected behavior. Triggers: 'why isn't this working', 'this doesn't work', 'X is broken', 'something's wrong', 'getting an error', 'exception in', 'stopped working', 'regression', 'crash', 'hang', 'flaky test', 'intermittent failure', or when user pastes a stack trace/error output. NOT for: test quality issues (use fixing-tests), adding new behavior (use develop).

DEPRECATED: The sub-orchestrator (CEO/Manager) execution mode has been removed. Spellbook now supports single-orchestrator dispatch only (direct / delegated). Nested subagent dispatch proved unreliable because dispatched subagents do not reliably have the Task tool, so a "Manager" sub-orchestrator could not dispatch its own gate sub-subagents. Use develop's single-orchestrator delegated mode instead; for very large efforts, checkpoint the `develop_gate_ledger` and hand off to a fresh session. The original body is preserved in ARCHIVE.md.

Use when about to claim discovery during debugging. Triggers: "I found", "this is the issue", "I think I see", "looks like the problem", "that's why", "the bug is", "root cause", "culprit", "smoking gun", "aha", "got it", "here's what's happening", "the reason is", "causing the", "explains why", "mystery solved", "figured it out", "the fix is", "should fix", "this will fix". Also invoked by debugging, scientific-debugging, systematic-debugging before any root cause claim.

Use when dispatching a subagent to re-check work against external feedback (PR review comments, audit findings, multi-comment review cycles, 'did I really address X' verifications). Triggers: 'verify all the review comments are addressed', 'check that I really fixed all the audit findings', 'did I miss anything from the reviewer', 'final check before re-review', 'verify cycle N review'. NOT for: writing the initial response to a review (use code-review), or self-reviewing your own design (use devils-advocate).

Use when verifying technical claims in code, docs, or comments before merge. Triggers: 'is this claim correct', 'verify this', 'fact check', 'is this accurate', 'check these assertions', 'are these comments true'. NOT for: checking if AI hallucinated references (use dehallucination).

Use when user explicitly requests test-driven development. Triggers: 'TDD', 'write tests first', 'red green refactor', 'test-first', 'start with the test'. Also invoked by develop and executing-plans for implementation tasks. NOT for: full feature work (use develop, which includes TDD internally).

Use when challenging assumptions, surfacing risks, or stress-testing designs and decisions. Triggers: 'challenge this', 'play devil's advocate', 'what could go wrong', 'poke holes', 'find the flaws', 'what am I missing', 'is this solid', 'red team this', 'what are the weaknesses', 'risk assessment', 'sanity check'. Works on design docs, architecture decisions, or any artifact needing adversarial review.

Use when seeding the project's `permissions.allow` list from observed YOLO sessions. Triggers: 'find safe commands to allow', 'review past transcripts for permissions', 'seed the allow list from YOLO sessions', 'propose permissions allow list', 'reduce permission prompts from transcripts'. NOT for: live permission grants during a session (use `/permissions`) or settings.json edits (use update-config).

Use when generating, improving, or auditing project documentation. Triggers: 'document this project', 'write docs', 'generate documentation', 'docs are outdated', 'need a README', 'create tutorials', 'API reference docs', 'doc audit', 'documentation review', '/document-project'. Standalone README: use /write-readme. NOT for: code changes (use develop), code review (use code-review), or research (use deep-research).

Use when instruction files (skills, prompts, CLAUDE.md) are too long or need token reduction while preserving capability. Triggers: 'optimize instructions', 'reduce tokens', 'compress skill', 'make this shorter', 'too verbose', 'this skill is too big', 'over the line limit', 'trim this down'.

Reference for OS notification configuration. Auto-loads when notifications are enabled (session_init reports notifications active). Also triggered by: 'mute', 'unmute', 'notify', 'notification settings', '/notify', 'notification', 'audio feedback'.

Use when reviewing PRs to triage, categorize, or summarize changes requiring human attention. Triggers: 'summarize this PR', 'what changed in PR #X', 'triage PR', 'which files need review', 'PR overview', 'categorize changes', or pasting a PR URL. Also matches ambiguous branch-review phrasing: 'branch code review', 'review this branch', 'review the changes', 'review what's on this branch', 'do a code review of the branch'. NOT for: deep code analysis (use advanced-code-review) or quick review (use code-review). When the request could match more than one review skill, MUST use AskUserQuestion to disambiguate before invoking — never bypass the review skills for a raw Explore dispatch, even when the user's concerns seem narrow or specific.

Use when deeply exploring uncertainty, systematically decomposing complex questions, or gaining certainty about multi-faceted problems. Triggers: 'think deeply about', 'explore this recursively', 'I need certainty about', 'decompose this question', 'what am I missing'. Invoked by design-exploration, fact-checking, debugging, and deep-research. NOT for: simple questions with known answers or linear task execution.

Session resume protocol and session repairs handling. Loaded when spellbook_session_init returns resume_available: true, or when session_init returns a repairs array. Triggers: 'resume', 'continue', 'where were we', session resume, session repairs.

Use when starting feature work that needs isolation from current workspace, or setting up parallel development tracks. Triggers: 'worktree', 'separate branch', 'isolate this work', 'don't mess up current work', 'work on two things at once', 'parallel workstreams', 'new branch for this', 'keep my current work safe'.

Meta-audit skill for spellbook development. Spawns parallel subagents to factcheck docs, optimize instructions, find token savings, and identify MCP candidates. Produces actionable report.

Use when entering unfamiliar domains, modeling complex business logic, or when terms/concepts are unclear. Triggers: 'what are the domain concepts', 'define the entities', 'model this domain', 'DDD', 'ubiquitous language', 'bounded context'. Also invoked by develop during research phase.

Use when preparing context for subagent dispatch or managing token budgets. Triggers: 'prepare context for', 'assemble context', 'token budget', 'context package', 'what context does the subagent need'. Also invoked by develop during planning and execution phases.

Use when researching complex topics, evaluating technologies, investigating domains, or answering multi-faceted questions requiring web research. Triggers: 'research X', 'investigate Y', 'evaluate options for Z', 'what are the best approaches to', 'help me understand', 'deep dive into', 'compare alternatives', 'look into', 'find out about'. NOT for: exploring design approaches (use design-exploration) or domain modeling (use analyzing-domains).

Use when verifying that AI-generated claims, references, or assertions are grounded in reality. Triggers: 'does this actually exist', 'is this real', 'did you hallucinate', 'verify these references', 'check if this is fabricated', 'reality check', 'ground truth'. Invoked as quality gate by develop and deep-research. NOT for: verifying technical claims in code (use fact-checking).

Use when exploring design approaches, evaluating alternatives, or making architectural decisions. Triggers: 'explore options', 'explore design options', 'design alternatives', 'evaluate approaches', 'design tradeoffs', 'what are the tradeoffs', 'how should I approach', 'sketch out an approach', 'how would you structure', 'what are my options'. Also invoked by develop when design decisions are needed.

System skill loaded at session start to initialize skill routing. Not invoked directly by users. Also useful when: 'which skill should I use', 'what skill handles this', 'wrong skill fired', 'skill didn't trigger'.

Use when writing JavaScript or TypeScript code with asynchronous operations, fixing promise-related bugs, or converting callback/promise patterns to async/await. Triggers: 'promise chain', 'unhandled rejection', 'race condition in JS', 'callback hell', 'Promise.all', 'sequential vs parallel async', 'missing await'. Enforces async/await discipline over raw promises.

Use when auditing whether tests genuinely catch failures, or when user expresses doubt about test quality. Triggers: 'are these tests real', 'do tests catch bugs', 'tests pass but I don't trust them', 'test quality audit', 'green mirage', 'shallow tests', 'tests always pass suspiciously', 'would this test fail if code was broken'. NOT for: fixing broken tests (use fixing-tests).

Triggers: 'branch diff', 'what changed on this branch', 'merge base', 'stacked branches', 'branch-context.sh', 'what does this branch do', 'PR description', 'changelog', 'branch comparison', 'diff since', 'what work is on this branch'. Also relevant during PR creation and finishing-a-development-branch workflows.

Use when creating GitHub pull requests or issues with template compliance. Triggers: 'create a PR', 'open a pull request', 'file an issue', 'create issue'. Also invoked by finishing-a-development-branch. NOT for: deciding whether to merge or PR (use finishing-a-development-branch).