SKILL.md
Two execution modes, same plan, same post-conditions. Always ask the user which mode — never auto-select.
Announce at Start
“I’m using codi-plan-execution. Before I start: how should I execute this plan — INLINE (I work through each task sequentially with checkpoints) or SUBAGENT (I dispatch a fresh subagent per task with two-stage review)?”
Wait for the user’s choice before proceeding. Do not pick a default.
Mode Comparison (for the user)
| Dimension | INLINE | SUBAGENT |
|---|---|---|
| Who writes the code | Primary agent (you watch) | Dispatched subagents (isolated) |
| Context | Plan stays in main context | Fresh context per task |
| Review stages | 1 — verification + TDD per step | 2 — spec compliance + code quality |
| Best for | Watch-along execution, single-file tasks, when you want to be involved each step | Multi-file tasks, complex coordination, keeping main context clean |
| Reviewer subagent | No | Yes (codi-code-reviewer) |
Skip When
- No approved plan yet — run codi-brainstorming → codi-plan-writer first
- Exploratory or single-file edit that does not warrant a plan — edit directly
- Bug investigation without a fix plan — use codi-debugging
- Parallel dispatch across INDEPENDENT failure domains — use codi-dispatching-parallel-agents (SUBAGENT mode here is sequential by contract)
- Baseline test suite is already failing — fix the baseline first, never execute on red
Prerequisites (both modes)
- A plan document in
docs/(from codi-plan-writer) - codi-worktrees has set up a clean workspace or branch
- Baseline tests confirmed passing
Shared Discipline (both modes)
No Improvisation
If a task says “add X to file Y”, add ONLY X to file Y. Do not also refactor Y. Do not fix a nearby issue you noticed. Do not add imports not specified. Execute the plan as written.
If the plan has a mistake: stop, report it, ask the user to update the plan before continuing.
Stopping Conditions
STOP IMMEDIATELY and seek clarification when:
- A required file does not exist
- A test fails unexpectedly and it is not the intended failing test
- A verification command fails
- An instruction is ambiguous
- A dependency is missing
Do not proceed past a blocker. Report what you were doing, what happened, and what you need to continue.
Mode: INLINE
Use when the user picks inline sequential execution with checkpoints.
Step 1 — Load and Review the Plan
Read the plan document completely. Check for any concerns or blockers. If questions exist: raise them with the user BEFORE starting. Create a task list from the plan tasks using TaskCreate.
Step 2 — Execute Each Task (in order)
- Mark task in_progress in the task list
- Execute each step in the task precisely as written
- Do not improvise or add steps not in the task
- Apply codi-tdd for each implementation step
- Run the task’s verification command
- Apply codi-verification before marking the task complete
- Commit as specified in the task
- Mark task completed
Revisiting Earlier Steps (INLINE)
Return to Step 1 when:
- The user updates the plan based on your feedback
- The fundamental approach needs rethinking
Do not force through blockers — stop and ask.
Mode: SUBAGENT
Use when the user picks subagent orchestration with two-stage review.
Core pattern: Fresh subagent per task + two-stage review (spec compliance first, then code quality) = high quality, fast iteration. Each subagent gets only what it needs: its specific task, the relevant design spec section, and no session history.
Step 1 — Prepare Task Context
Extract the complete task text from the plan. Spec compliance reviewers need the original requirements, not your summary.
Step 2 — Dispatch Implementer Subagent
Use ${CLAUDE_SKILL_DIR}[[/references/implementer-prompt.md]] as the base for the implementer subagent prompt.
Dispatch via the Agent tool with a prompt that includes:
- The exact task text from the plan (complete, word for word)
- The design spec section relevant to this task
- The branch and worktree path
- Explicit instruction: “Use codi-tdd. Write the test first, verify it fails, then implement.”
- Explicit instruction: “Use codi-verification before reporting completion.”
- What to report back: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED
Step 3 — Handle Implementer Status
| Status | Response |
|---|---|
| DONE | Proceed to spec review |
| DONE_WITH_CONCERNS | Note the concern, proceed to spec review, include concern in review context |
| NEEDS_CONTEXT | Provide the missing information, re-dispatch the same task |
| BLOCKED | Assess root cause: (1) context problem: provide more context, re-dispatch same model; (2) needs more reasoning: re-dispatch with more capable model; (3) task too large: break into smaller pieces; (4) plan is wrong: escalate to user |
Step 4 — Spec Compliance Review
Use ${CLAUDE_SKILL_DIR}[[/references/spec-reviewer-prompt.md]] for the spec reviewer prompt.
Dispatch a spec reviewer subagent:
- Provide: the original task requirements, the design spec section, the git diff of changes made
- Ask: “Do the changes fully satisfy the task requirements? Yes/No. If no, what is missing?”
- If reviewer finds gaps: dispatch implementer again with specific gap description. Re-review.
Step 5 — Code Quality Review
Use ${CLAUDE_SKILL_DIR}[[/references/quality-review-prompt.md]] for the quality reviewer prompt.
Dispatch the codi-code-reviewer agent:
- Provide: the git diff, the task context
- Severity-ranked findings (CRITICAL / HIGH / MEDIUM / LOW)
- CRITICAL and HIGH findings must be fixed before proceeding
- MEDIUM noted; LOW noted
Step 6 — Mark Task Complete
Update task tracking. Move to the next task.
Model Selection (SUBAGENT)
Choose model complexity based on task:
- Simple, isolated changes (1 file, clear spec): faster model
- Integration changes (multiple files, coordination): standard model
- Architecture or design decisions: most capable model available
What Never to Do (SUBAGENT)
- Never dispatch multiple implementer subagents in parallel (review is sequential; feedback loops require order — for parallel dispatch across INDEPENDENT failure domains, use codi-dispatching-parallel-agents instead)
- Never skip a review stage because “the task was simple”
- Never proceed with DONE_WITH_CONCERNS without including the concern in review context
- Never let subagents read plan files directly — extract and provide the specific task text
- Never start code quality review before spec compliance is done (wrong order)
- Never move to the next task while either review has open issues
- Never let implementer self-review replace actual review (both stages required)
- Never reuse a subagent from a previous task (fresh context is essential)
- Never give the implementer access to the full plan (only the specific task)
- Never accept DONE_WITH_CONCERNS without noting the concern in the review context
- Never let review cycles run more than 3 iterations without escalating or decomposing the task
After All Tasks (both modes)
- Run full test suite via codi-verification: report pass/fail with counts
- SUBAGENT mode only: dispatch codi-code-reviewer agent for the complete changeset
- Invoke codi-branch-finish for cleanup and merge options
Integration
- Requires: codi-worktrees (workspace), codi-plan-writer (plan)
- Iron-law gates (wrap every task, both modes): codi-tdd (RED-GREEN-REFACTOR per task — failing test before any production code) and codi-verification (fresh evidence before claiming a task done — no weasel words)
- On task failure: codi-debugging (Phases 1-5) for root-cause investigation; never apply a second fix without completing Phase 1
- SUBAGENT-mode review: codi-code-reviewer agent for the per-task quality gate (two-stage review)
- Invokes after all tasks: codi-branch-finish (merge / PR / keep / discard)
- Never starts implementation on main/master without explicit user consent
- Parallel sibling: codi-dispatching-parallel-agents — for fan-out across INDEPENDENT failure domains (this skill’s SUBAGENT mode is sequential by contract)