Roach is a research-first workflow. Eighteen skills, one disciplined loop: understand before you plan, plan before you build, verify before you claim done. This guide maps every skill — when it fires, what it leaves behind, where to reset context, and which pair up.
Every skill announces the one that comes after it. Brainstorming hands off to planning; planning offers two ways to execute; execution feeds verification, review, then commit. The rail below is that sequence. Numbered phases are the spine; dashed markers are where you reset context.
The bootstrap. Injected at the start of every session. Its one rule: if there's even a 1% chance a skill applies, invoke it. Process skills (brainstorming, debugging) come before implementation skills. Never touch EnterPlanMode / ExitPlanMode — roach manages its own planning flow.
Before any code exists. Learn the terrain (existing code) and shape the idea (design). This is a hard gate — no implementation until a design is written and approved.
Turns a vague idea into an approved design spec through one-question-at-a-time dialogue. Mandatory before any creative work.
Documents how existing code works — as-is, no critiques or improvement proposals — by fanning out parallel research sub-agents.
Interviews you relentlessly, one question at a time, walking the decision tree until every branch is resolved.
Translate the approved design into an executable, step-by-step plan. Runs in an isolated Explore fork, so your main session stays clean.
Explores the codebase to pin exact file paths, writes a numbered implementation plan, and runs it through a plan-reviewer loop before returning.
.tasks.json carries the state across).
Build the plan, task by task. Same session or fresh session — the plan is identical, only the isolation model differs.
Dispatches a fresh subagent per task, then runs a two-stage review (spec compliance, then code quality) on each before moving on.
Loads the plan into a new session, executes in batches of ~3, and stops at a checkpoint after each batch for your review.
Red → Green → Refactor. Write the failing test, watch it fail, write the minimum to pass.
Four phases: investigate → analyse patterns → single hypothesis → implement one fix. Especially under time pressure.
Sends 2+ genuinely independent tasks to parallel subagents, then integrates and runs the full suite.
Before the word "done" is allowed to appear.
Identify the verification command, run it fresh, read the full output and exit code, and only then make the claim — attaching the evidence.
A second pair of eyes, then a rigorous response to them. Request runs in an isolated fork and returns a report.
Dispatches a senior review against the requirements, returning strengths and issues bucketed Critical / Important / Minor with a go/no-go verdict.
Read → understand → verify → evaluate → respond → implement, one item at a time. No performative "You're absolutely right!"
Once verification passes.
Analyses changes (explicit files or auto-discovered), proposes a logical commit grouping, and lands them after you confirm.
Not the end of the line — a lever you pull whenever context runs long. Preserve state richly, then pick it back up in a fresh session.
Writes a rich handoff doc — tasks, learnings, artifacts, next steps — so a new session loses nothing. Prefer this over auto-compaction.
Reads the handoff yourself first, verifies current state with parallel research, confirms with you, then builds an adapted action plan.
These aren't phases — they activate whenever their trigger appears, at any point in the flow.
READMEs, changelogs, docs, summaries, even skill content. Reads the Elements of Style reference first, then writes.
TDD applied to process docs: run a pressure scenario without the skill (RED), write the minimal skill (GREEN), then close loopholes (REFACTOR).
Some transitions are hard-wired (brainstorming → writing-plans). Others are optional overlays you reach for when you want more rigor. Amber = optional; green = built into the flow.
Present the design, then invite grill-me to attack its assumptions before you commit to a plan.
Interrogate the plan itself — resolve every branch of the decision tree before execution starts.
Not optional — brainstorming's terminal state is invoking writing-plans. Nothing else runs in between.
The plan offers exactly two exits: subagent-driven (this session) or executing-plans (a new one).
Verification-before-completion follows any task, in any phase, before you claim it's done.
Request a review for a fresh perspective on any significant chunk of work.
TDD and systematic-debugging activate on their own the moment you write code or hit a bug.
Reach for dispatching-parallel-agents when 2+ tasks share no state and can run at once.
No roach skill literally prints /clear. Instead it keeps context clean four different ways. Knowing which one is in play tells you whether you need to reset, or whether roach already handled it.
You open a fresh window. The big one — Path B execution and resuming a handoff both start clean here.
writing-plans & requesting-code-review run in an isolated Explore fork, then return just the result.
Path A spawns a fresh subagent per task — it inherits nothing but the brief you hand it.
create-handoff serialises rich state to disk so a new session rebuilds context from a file, not scrollback.
Each discipline skill is built on one rule it will not let you rationalize your way around.
EnterPlanMode / ExitPlanMode — traps the sessiongit add then git commit — use git commit <files>thoughts/shared/research/<domain>/thoughts/shared/plans/<domain>/thoughts/shared/handoffs/<domain>/<plan>.tasks.json (cross-session)