majiayu000 Executing Plans
Overview
Execute implementation plans by dispatching fresh builder agents per task, with two-stage review after each: spec compliance review first, then code quality review. Can also run as batch execution with human checkpoints.
Core principle: Fresh agent per task + two-stage review (spec then quality) = high quality, fast iteration.
Announce at start: "I'm using the executing-plans skill to implement this plan."
When to Use
digraph when_to_use {
"Have implementation plan?" [shape=diamond];
"Tasks mostly independent?" [shape=diamond];
"Stay in this session?" [shape=diamond];
"Agent-driven execution" [shape=box];
"Batch execution with checkpoints" [shape=box];
"Manual execution or brainstorm first" [shape=box];
"Have implementation plan?" -> "Tasks mostly independent?" [label="yes"];
"Have implementation plan?" -> "Manual execution or brainstorm first" [label="no"];
"Tasks mostly independent?" -> "Stay in this session?" [label="yes"];
"Tasks mostly independent?" -> "Manual execution or brainstorm first" [label="no - tightly coupled"];
"Stay in this session?" -> "Agent-driven execution" [label="yes"];
"Stay in this session?" -> "Batch execution with checkpoints" [label="no - parallel session"];
}
The Process
Step 1: Load and Review Plan
- Read plan file
- Review critically - identify any questions or concerns about the plan
- If concerns: Raise them with your human partner before starting
- If no concerns: Create TodoWrite and proceed
Step 2: Execute Tasks
Agent-Driven Mode (preferred):
For each task, dispatch a fresh builder agent:
digraph process {
rankdir=TB;
subgraph cluster_per_task {
label="Per Task";
"Dispatch builder agent" [shape=box];
"Builder asks questions?" [shape=diamond];
"Answer questions, provide context" [shape=box];
"Builder implements, tests, commits, self-reviews" [shape=box];
"Dispatch spec reviewer agent" [shape=box];
"Spec reviewer confirms code matches spec?" [shape=diamond];
"Builder fixes spec gaps" [shape=box];
"Dispatch code quality reviewer agent" [shape=box];
"Code quality reviewer approves?" [shape=diamond];
"Builder fixes quality issues" [shape=box];
"Mark task complete" [shape=box];
}
"Read plan, extract all tasks, create TodoWrite" [shape=box];
"More tasks remain?" [shape=diamond];
"Dispatch final reviewer for entire implementation" [shape=box];
"Use shipyard:git-workflow to complete" [shape=box style=filled fillcolor=lightgreen];
"Read plan, extract all tasks, create TodoWrite" -> "Dispatch builder agent";
"Dispatch builder agent" -> "Builder asks questions?";
"Builder asks questions?" -> "Answer questions, provide context" [label="yes"];
"Answer questions, provide context" -> "Dispatch builder agent";
"Builder asks questions?" -> "Builder implements, tests, commits, self-reviews" [label="no"];
"Builder implements, tests, commits, self-reviews" -> "Dispatch spec reviewer agent";
"Dispatch spec reviewer agent" -> "Spec reviewer confirms code matches spec?";
"Spec reviewer confirms code matches spec?" -> "Builder fixes spec gaps" [label="no"];
"Builder fixes spec gaps" -> "Dispatch spec reviewer agent" [label="re-review"];
"Spec reviewer confirms code matches spec?" -> "Dispatch code quality reviewer agent" [label="yes"];
"Dispatch code quality reviewer agent" -> "Code quality reviewer approves?";
"Code quality reviewer approves?" -> "Builder fixes quality issues" [label="no"];
"Builder fixes quality issues" -> "Dispatch code quality reviewer agent" [label="re-review"];
"Code quality reviewer approves?" -> "Mark task complete" [label="yes"];
"Mark task complete" -> "More tasks remain?";
"More tasks remain?" -> "Dispatch builder agent" [label="yes"];
"More tasks remain?" -> "Dispatch final reviewer for entire implementation" [label="no"];
"Dispatch final reviewer for entire implementation" -> "Use shipyard:git-workflow to complete";
}
Batch Mode (separate session):
Default: First 3 tasks per batch.
For each task:
- Mark as in_progress
- Follow each step exactly (plan has bite-sized steps)
- Run verifications as specified
- Mark as completed
When batch complete:
- Show what was implemented
- Show verification output
- Say: "Ready for feedback."
Based on feedback:
- Apply changes if needed
- Execute next batch
- Repeat until complete
Two-Stage Review Pattern
Stage 1: Spec Compliance Review
- Does the code match the plan's specification?
- Are all requirements met?
- Is there anything extra that wasn't requested?
- Are verification criteria satisfied?
Stage 2: Code Quality Review
- Is the code well-structured?
- Are there any bugs or edge cases missed?
- Is naming clear and consistent?
- Are tests comprehensive?
IMPORTANT: Always complete spec compliance before code quality. Wrong order wastes time reviewing quality of code that doesn't meet spec.
Step 3: Complete Development
After all tasks complete and verified:
- Announce: "I'm using the git-workflow skill to complete this work."
- REQUIRED SUB-SKILL: Use shipyard:git-workflow
- Follow that skill to verify tests, present options, execute choice
When to Stop and Ask for Help
STOP executing immediately when:
- Hit a blocker mid-batch (missing dependency, test fails, instruction unclear)
- Plan has critical gaps preventing starting
- You don't understand an instruction
- Verification fails repeatedly
Ask for clarification rather than guessing.
Builder Agent Guidelines
Builder agents should:
- Follow TDD naturally (shipyard:shipyard-tdd)
- Ask questions before AND during work if unclear
- Self-review before handing off to reviewers
- Commit after each task
Red Flags
Never:
- Skip reviews (spec compliance OR code quality)
- Proceed with unfixed issues
- Dispatch multiple builder agents in parallel (conflicts)
- Make agent read plan file (provide full text instead)
- Skip scene-setting context (agent needs to understand where task fits)
- Ignore agent questions (answer before letting them proceed)
- Accept "close enough" on spec compliance
- Skip review loops (reviewer found issues = builder fixes = review again)
- Let builder self-review replace actual review (both are needed)
- Start code quality review before spec compliance is approved (wrong order)
- Move to next task while either review has open issues
If builder asks questions:
- Answer clearly and completely
- Provide additional context if needed
- Don't rush them into implementation
If reviewer finds issues:
- Builder (same agent) fixes them
- Reviewer reviews again
- Repeat until approved
- Don't skip the re-review
If agent fails task:
- Dispatch fix agent with specific instructions
- Don't try to fix manually (context pollution)
Integration
Required workflow skills:
- shipyard:shipyard-writing-plans - Creates the plan this skill executes
- shipyard:git-workflow - Complete development after all tasks
Agents should use:
- shipyard:shipyard-tdd - Agents follow TDD for each task
Remember
- Review plan critically first
- Follow plan steps exactly
- Don't skip verifications
- Reference skills when plan says to
- Between batches: just report and wait
- Stop when blocked, don't guess