handbook

Propose a Conventional Commit message for the staged changes, then commit only after confirmation.

Creates an implementation plan from a PRD or a task description. Researches codebase context, clarifies ambiguities, and outputs a phased plan with vertical slices and acceptance criteria. Use when the user wants to plan a feature, break down a PRD, create an implementation plan, or mentions "tracer bullets".

Creates a PRD through structured clarification, codebase exploration, and module design, then saves it as a local Markdown file. Use when user wants to write a PRD, create a product requirements document, or plan a new feature.

Dispatches multiple subagents in parallel for 2+ confirmed-independent, each-substantial failures or investigation targets that share no state or sequential dependency. Use when the work splits cleanly and each part is big enough to justify a separate agent.

Decides how to integrate a finished branch — merge, pull request, keep, or discard — once tests pass. Use when implementation work on a branch is complete and you need to decide what happens to it next.

Acts on code-review feedback (from a human, a PR comment, or an AI reviewer) by verifying each item against the codebase before implementing, and asking when items are unclear. Use when receiving code review comments, PR feedback, or suggestions from another reviewer — before implementing any of them.

Investigates a bug, test failure, or unexpected behavior root-cause-first before proposing a fix. Use when a test fails, an error shows up in logs or CI, or something behaves unexpectedly and the next step would otherwise be guessing at a patch.

Creates or reuses an isolated git worktree for feature work, a risky refactor, or unattended agent runs. Use when starting work that shouldn't touch the current checkout, before executing a multi-step plan, or when running an agent unattended and it needs its own branch and directory.

Reviews code changes for clean code principles, design patterns, and anti-patterns. Use on recent changes (staged, unstaged, last commit) or a specific area (module, route, component, page). Reports findings with concrete suggestions, applies fixes after confirmation. Integrates AI slop detection, architecture boundary checks, and readability review. Triggers: "cleanup", "clean up", "review code quality", "check principles", "readability review", "code cleanup", "deslop", "remove slop", "clean up AI code", "review for slop", "remove AI writing".

Prevents the agent from making assumptions by forcing structured clarifying questions before acting. Use when the user wants thorough spec-gathering, disambiguation, or wants the agent to ask before assuming. Applies to any task type.

Guides a developer step-by-step through implementing a user story or plan phase — without writing any code. The agent acts as navigator: it explores the codebase, breaks work into small vertical steps, explains what to do and why, and waits for the developer to implement each step. Use when the user wants coaching, guided coding, mentored implementation, or pair programming where they write all the code themselves.

Works through the next open phase of a plan, implementing toward its acceptance criteria and checking each off as it is verified. Use when the user wants to execute an existing implementation plan one phase at a time.

Drives development with a red-green-refactor loop, one test at a time. Use when the user wants to build a feature or fix a bug using TDD, mentions "red-green-refactor", or asks for test-first development.

Reviews and refactors an existing test suite. Use when the user wants to reduce test count, remove implementation-detail tests, improve test readability, or clean up a test suite that has grown noisy or brittle.

Extracts a DDD-style ubiquitous language glossary from the current conversation, flagging ambiguities and proposing canonical terms. Saves to docs/UBIQUITOUS_LANGUAGE.md. Use when user wants to define domain terms, build a glossary, harden terminology, create a ubiquitous language, or mentions "domain model" or "DDD".

Explores a codebase deeply to build a human's mental model. Use when the user wants to understand a specific part of the codebase holistically — database schema, API, function, domain model, business logic, frontend component, architecture, or any other concept. Invoke with one or more references to the code in question (file paths, function names, module names).

Reviews a frontend for mobile UX, UI consistency, workflow friction, and terminology drift. Use when the user wants a UX audit of a mobile-first web app or needs to find usability problems on small screens.

Researches companies, jobs, or tools from live sources and records structured findings, with strict verification. Delegates to the web-researcher agent.