You are executing ONE step of a phased implementation plan. Previous steps were executed in sessions you cannot see; later steps depend on what you do and document. The protocol below is ordered — do not skip phases, do not reorder them.
Companion skills: load handoff-protocol before Phase 1 (you must READ a handoff correctly) and keep it loaded for Phase 8 (you must WRITE one). Load verification-gates for Phase 6. The plan schema is defined in plan-authoring.
Phase 1 - Orient
- Read the previous step's handoff (
plans/handoffs/, highest step number below yours). If none exists, you are step 1. - Read the current step plan (
plans/steps/). Note itsdepends_on— confirm those steps' handoffs exist and report success. If a dependency failed or is missing, STOP and escalate viauser__ask. - Read
plans/NOTES.mdfor durable facts discovered by earlier steps. - Apply anything the previous handoff directed at your step (approved plan updates, warnings).
- Set the plan's frontmatter
status: in-progress.
Phase 2 - Staleness check (BEFORE any edit)
The plan was written before steps 1..N-1 changed the codebase. Verify its assumptions still hold:
- Grep the symbols the plan references — do they still exist, with the claimed signatures?
- Read the plan's Context snippets at their claimed locations — has the code drifted?
- Confirm the Test commands still work.
Discrepancies are deviations — handle them via Phase 5's protocol BEFORE implementing. Executing a stale plan literally is the primary failure mode of phased work.
Phase 3 - Checklist
todo__init with the step objective, then one todo__add per task in the plan's Tasks section, in order. Append the protocol's own gates as todos: edge-case sweep, verify, review, handoff. Mark items done with todo__done as you go — never batch. The checklist is what survives context compression; keep it truthful.
When you spawn an agent whose session you may need to resume, embed its session_id in the corresponding todo item text ("Implement task 3 (coder <session_id>)"). A fix or follow-up to a child's work resumes that child's session_id; a fresh spawn is for new work. If your context gets compressed mid-step, the plan repo tells you WHAT the step is and the todo list tells you WHERE you are and WHICH sessions to resume; re-orient from those, not from the summary's recollection.
Phase 4 - Implement
- Implement ONLY what the plan's Tasks and Objective ask. Out of scope means out of scope.
- Follow the patterns pasted in the plan's Context. When plan and current codebase disagree, the codebase wins — record the deviation.
- Write tests from the plan's Acceptance criteria, not from your implementation. Criteria-first tests catch what tautological tests cannot.
- While in the code, note (do not fix) anything the planning exploration missed — feed it to Phase 5.
Phase 5 - Edge-case sweep and deviations
Edge cases. For each edge case you discovered: if it belongs to THIS step, handle it (or punt explicitly in the handoff with a reason). If it belongs to a LATER step, check that step's plan — if the plan already covers it, done; if not, add it to that plan's Edge cases section and record the addition in your handoff.
Deviations. Classify each:
| Class | Definition | Action |
|---|---|---|
| Minor | Same objective and scope, mechanics differ (renamed symbol, moved file, extra helper) | Resolve it, document in handoff |
| Major | Changes scope, approach, interfaces, or invalidates a later step's assumptions | Do NOT silently proceed. Either escalate via user__ask, or write a proposed downstream-plan diff into the handoff per handoff-protocol |
Never rewrite a later step's Objective, Tasks, or Out of scope directly — edge-case annotations are the only direct downstream edit you may make.
Phase 6 - Verify (order matters)
- Formatter (if configured) — format BEFORE collecting evidence, so evidence reflects final code.
- Linter (if configured) — fix findings your change introduced.
- Build/typecheck — exit code 0.
- FULL test suite — not just your new tests; regressions in untouched code are your problem if your change caused them.
Capture commands and exit codes verbatim — they go in the handoff as evidence. Pre-existing failures: note explicitly, don't fix, don't hide. Apply the 3-strike rule: after 3 failed fix attempts, stop, revert to working state, escalate.
Phase 7 - Review
Self-review the diff with code-review + ai-slop-remover loaded. For broad steps (5+ files or crossing architectural boundaries), request an independent pass (code-reviewer agent) instead. Fix blockers; re-run Phase 6 after any fix.
Phase 8 - Handoff
Gate: every todo is either done or explicitly deferred with a reason. No silent drops.
Write the handoff per handoff-protocol — schema, pasted evidence, deviations, downstream updates, notes for the next step. Append durable, step-independent facts to plans/NOTES.md. Set the plan's frontmatter status: complete.
Phase 9 - User approval
Present: what was done, deviations, downstream plan changes (made or proposed), evidence summary, handoff location. Then STOP — do not begin the next step. If the user requests changes, address them, re-run Phase 6, update the handoff, and present again.
Anti-patterns
- Editing code before the staleness check — the primary source of mid-step surprises
- Implementing "while I'm here" improvements outside the plan's scope
- Tests derived from the implementation instead of the acceptance criteria
- Collecting build/test evidence BEFORE formatting/linting, then shipping different bytes
- Running only your new tests and claiming "tests pass"
- Silently absorbing a major deviation instead of escalating or proposing a plan diff
- Rewriting downstream plan scope directly instead of proposing per
handoff-protocol - Starting the next step without user approval
