Executing an Implementation Plan
Execute plan phase-by-phase, loading each phase just-in-time to minimize context usage.
Core principle: Read one phase → execute all tasks → review → move to next phase. Never load all phases upfront.
REQUIRED SKILL: requesting-code-review - The review loop (dispatch, fix, re-review until zero issues)
Overview
When NOT to use:
- No implementation plan exists yet (use writing-implementation-plans first)
- Plan needs revision (brainstorm first)
MANDATORY: Human Transparency
The human cannot see what subagents return. You are their window into the work.
Do not use nested subagents. This workflow may dispatch first-level task, review, bug-fix, and librarian subagents. Those subagents must not dispatch additional subagents; they must do their assigned work directly and report back to this caller.
After EVERY subagent completes (task-implementor, bug-fixer, code-reviewer), you MUST:
- Print the subagent's full response to the user before taking any other action
- Do not summarize or paraphrase - show them what the subagent actually said
- Include all details: test counts, issue lists, commit hashes, error messages
Before dispatching any subagent:
- Briefly explain (2-3 sentences) what you're asking the agent to do
- State which phase this covers
Why this matters: When you silently process subagent output without showing the user, they lose visibility into their own codebase. They can't catch errors, learn from the process, or intervene when needed. Transparency is not optional.
Red flag: If you find yourself thinking "I'll just move on to the next step" without printing the subagent's response, STOP. Print it first.
REQUIRED: Implementation Plan Path
DO NOT GUESS. If the user has not provided a path to an implementation plan directory, you MUST ask for it.
Use AskUserQuestion:
Question: "Which implementation plan should I execute?"
Options:
- [list any plan directories you find in docs/implementation-plans/]
- "Let me provide the path"
If docs/implementation-plans/ doesn't exist or is empty, ask the user to provide the path directly.
Never assume, infer, or guess which plan to execute. The user must explicitly tell you.
The Process
1. Discover Phases
DO NOT read the full phase files yet. List them and read only the header and task markers.
# List phase files
ls [plan-directory]/phase_*.md
# For each file, get the header (first 10 lines include title and Goal)
head -10 [plan-directory]/phase_01.md
# Get task/subcomponent structure without reading full content
grep -E "START_TASK_|START_SUBCOMPONENT_" [plan-directory]/phase_01.md
The header includes the title (# [Phase Title]) and **Goal:** line. Extract the title for the task entry.
The grep output shows the task structure, e.g.:
<!-- START_TASK_1 -->
<!-- START_TASK_2 -->
<!-- START_SUBCOMPONENT_A (tasks 3-5) -->
<!-- START_TASK_3 -->
<!-- START_TASK_4 -->
<!-- START_TASK_5 -->
Examples of headers you might see:
# Document Infrastructure Implementation Plan— Phase 1 implied# Phase 4: Link Resolution— Phase number explicit
Check for implementation guidance:
After discovering phases, check if .ed3d/implementation-plan-guidance.md exists in the project root:
# Check for implementation guidance (note the absolute path for later use)
ls [project-root]/.ed3d/implementation-plan-guidance.md
If the file exists, note its absolute path for use during code reviews. If it doesn't exist, proceed without it—do not pass a nonexistent path to reviewers.
Check for test requirements:
Check if test-requirements.md exists in the plan directory:
# Check for test requirements (note the absolute path for later use)
ls [plan-directory]/test-requirements.md
If the file exists, note its absolute path for use during final review. The test requirements document specifies what automated tests must exist for each acceptance criterion.
Create a session-isolated scratchpad directory:
# Extract slug from plan directory name (last path component, without trailing slash)
SLUG=$(basename "[plan-directory]")
# Generate unique session ID
SESSION_ID=$(printf '%04x%04x' $RANDOM $RANDOM)
# Create scratchpad path
SCRATCHPAD_DIR="/tmp/exec-${SLUG}-${SESSION_ID}"
mkdir -p "${SCRATCHPAD_DIR}"
echo "${SCRATCHPAD_DIR}"
This scratchpad ensures isolation when multiple execution sessions run in parallel. Pass it to code-reviewer invocations.
2. Create Phase-Level Task List
Use TaskCreate to create three task entries per phase (or TodoWrite in older Claude Code versions). Include the title from the header:
- [ ] Phase 1a: Read /absolute/path/to/phase_01.md — Document Infrastructure Implementation Plan
- [ ] Phase 1b: Execute tasks
- [ ] Phase 1c: Code review
- [ ] Phase 2a: Read /absolute/path/to/phase_02.md — API Integration
- [ ] Phase 2b: Execute tasks
- [ ] Phase 2c: Code review
...
Why absolute paths in task entries: After compaction, context may be summarized. The absolute path in the task entry ensures you always know exactly which file to read.
Why include the title: Gives visibility into what each phase covers without loading full content.
3. Execute Each Phase
For each phase, follow this cycle:
3a. Read Phase File (just-in-time)
Mark "Phase Na: Read [path]" as in_progress.
Read ONLY that phase file now. Extract:
- List of tasks in this phase
- Working directory
- Any phase-specific context
Mark "Phase Na: Read" as complete.
3b. Execute All Tasks
Mark "Phase Nb: Execute tasks" as in_progress.
Before dispatching, verify test coverage for functionality tasks:
If a functionality task (code that does something) has no tests specified:
- Check if a subsequent task in the same phase provides tests
- If no tests exist anywhere for this functionality → STOP
- This is a plan gap. Surface to user: "Task N implements [functionality] but no corresponding tests exist in the plan. This needs tests before implementation."
Do NOT implement functionality without tests. Missing tests = plan gap, not something to skip.
Execute all tasks in sequence. For each task, dispatch task-implementor-fast with the phase file path:
<invoke name="Task">
<parameter name="subagent_type">ed3d-plan-and-execute:task-implementor-fast</parameter>
<parameter name="description">Implementing Phase X, Task Y: [description]</parameter>
<parameter name="prompt">
Implement Task N from the phase file.
Phase file: [absolute path to phase file]
Task number: N
Read the phase file and implement Task N (look for `<!-- START_TASK_N -->`).
Your job is to:
1. Read the phase file to understand context
2. Apply all relevant skills, such as (if available) ed3d-house-style:coding-effectively
3. Implement exactly what Task N specifies
4. Verify with tests/build/lint
5. Commit your work
6. Report back with evidence
7. Do not dispatch or invoke any subagents.
Work from: [directory]
Provide complete report per your agent instructions.
</parameter>
</invoke>
For subcomponents (grouped tasks), dispatch once for all tasks in the subcomponent:
<invoke name="Task">
<parameter name="subagent_type">ed3d-plan-and-execute:task-implementor-fast</parameter>
<parameter name="description">Implementing Phase X, Subcomponent A (Tasks 3-5): [description]</parameter>
<parameter name="prompt">
Implement Subcomponent A (Tasks 3, 4, 5) from the phase file.
Phase file: [absolute path to phase file]
Tasks: 3, 4, 5 (look for `<!-- START_SUBCOMPONENT_A -->`)
Read the phase file and implement all tasks in this subcomponent.
Your job is to:
1. Read the phase file to understand context
2. Apply all relevant skills, such as (if available) ed3d-house-style:coding-effectively
3. Implement all tasks in sequence
4. Verify with tests/build/lin