execute-plan

---

name: execute-plan description: Execute a PLAN.md file argument-hint: "[path-to-PLAN.md]" allowed-tools:

• Read
• Glob
• Grep
• Bash
• Task
• TodoWrite
• AskUserQuestion

---

Orchestrator stays lean: validate plan, spawn subagent, handle checkpoints, report completion. The ag4-executor has all execution logic baked in.

Context budget: ~15% orchestrator, 100% fresh for subagent.

<execution_context> @~/.claude/ag4one/references/principles.md </execution_context>

@.planning/STATE.md @.planning/config.json (if exists)

1. Check if already executed

   • Derive SUMMARY path from plan path (replace PLAN.md with SUMMARY.md)
   • If SUMMARY exists: "Plan already executed. SUMMARY: {path}"
   • Offer: re-execute or exit

2. Parse plan identifiers Extract from path like .planning/phases/03-auth/03-02-PLAN.md:

   • phase_number: 03
   • phase_name: auth
   • plan_number: 02
   • plan_path: full path

3. Pre-execution summary (interactive mode only) Check config.json for mode. Skip this step if mode=yolo.

   Parse PLAN.md to extract:

   • objective: First sentence or line from <objective> element
   • task_count: Count of <task elements
   • files: Collect unique file paths from <files> elements within tasks

   Display friendly summary before spawning:

   Copy════════════════════════════════════════
   EXECUTING: {phase_number}-{plan_number} {phase_name}
   ════════════════════════════════════════
   
   Building: {objective one-liner}
   Tasks: {task_count}
   Files: {comma-separated file list}
   
   Full plan: {plan_path}
   ════════════════════════════════════════
   

   No confirmation needed. Proceed to spawn after displaying.

   In yolo mode, display abbreviated version:

   Copy⚡ Executing {phase_number}-{plan_number}: {objective one-liner}
   

4. Spawn ag4-executor subagent

   CopyTask(
     prompt="Execute plan at {plan_path}
   

Plan: @{plan_path} Project state: @.planning/STATE.md Config: @.planning/config.json (if exists)", subagent_type="ag4-executor", description="Execute {phase}-{plan}" )

Copy
The `ag4-executor` subagent has all execution logic baked in:
- Deviation rules (auto-fix bugs, critical gaps, blockers; ask for architectural)
- Checkpoint protocols (human-verify, decision, human-action)
- Commit formatting (per-task atomic commits)
- Summary creation
- State updates

6. **Handle subagent return**
- If contains "## CHECKPOINT REACHED": Execute checkpoint_handling
- If contains "## PLAN COMPLETE": Verify SUMMARY exists, report success

7. **Report completion and offer next steps**
- Show SUMMARY path
- Show commits from subagent return
- Route to next action (see `<offer_next>`)
</process>

<offer_next>
**MANDATORY: Present copy/paste-ready next command.**

After plan completes, determine what's next:

**Step 1: Count plans vs summaries in current phase**
```bash
ls -1 .planning/phases/[phase-dir]/*-PLAN.md 2>/dev/null | wc -l
ls -1 .planning/phases/[phase-dir]/*-SUMMARY.md 2>/dev/null | wc -l

Step 2: Route based on counts

Step 2.5: Verify phase goal (only when phase complete)

When summaries = plans, verify the phase achieved its GOAL before proceeding:

CopyTask(
  prompt="Verify phase {phase_number} goal achievement

Phase: {phase_number} - {phase_name}
Phase goal: {phase_goal_from_roadmap}
Phase directory: @.planning/phases/{phase_dir}/

Project context:
@.planning/ROADMAP.md
@.planning/REQUIREMENTS.md (if exists)",
  subagent_type="ag4-verifier",
  description="Verify phase {phase_number}"
)

Handle verification result:

• If passed: Continue to Step 2.6 (update requirements)
• If gaps_found: Create fix plans, execute them, re-verify (max 3 cycles)
• If human_needed: Present items to user, collect response

Step 2.6: Update requirements (only when verification passes)

When summaries = plans, update REQUIREMENTS.md before presenting completion:

1. Get phase number from completed plan path
2. Read ROADMAP.md, find the phase's Requirements: line (e.g., "AUTH-01, AUTH-02")
3. Read REQUIREMENTS.md traceability table
4. For each REQ-ID in this phase: change Status from "Pending" to "Complete"
5. Write updated REQUIREMENTS.md
6. Stage for commit: git add .planning/REQUIREMENTS.md

Skip if: REQUIREMENTS.md doesn't exist, or phase has no Requirements line in ROADMAP.md.

---

Route A: More plans remain in phase

Find next PLAN.md without matching SUMMARY.md. Present:

CopyPlan {phase}-{plan} complete.
Summary: .planning/phases/{phase-dir}/{phase}-{plan}-SUMMARY.md

{Y} of {X} plans complete for Phase {Z}.

---

## ▶ Next Up

**{phase}-{next-plan}: [Plan Name]** — [objective from PLAN.md]

`/ag4:execute-plan .planning/phases/{phase-dir}/{phase}-{next-plan}-PLAN.md`

<sub>`/clear` first → fresh context window</sub>

---

---

Step 3: Check milestone status (only when phase complete)

Read ROADMAP.md. Find current phase number and highest phase in milestone.

---

Route B: Phase complete, more phases remain

Copy## ✓ Phase {Z}: {Name} Complete

All {Y} plans finished.

---

## ▶ Next Up

**Phase {Z+1}: {Name}** — {Goal from ROADMAP.md}

`/ag4:plan-phase {Z+1}`

<sub>`/clear` first → fresh context window</sub>

---

---

Route C: Milestone complete

Copy🎉 MILESTONE COMPLETE!

## ✓ Phase {Z}: {Name} Complete

All {N} phases finished.

---

## ▶ Next Up

`/ag4:complete-milestone`

<sub>`/clear` first → fresh context window</sub>

---

</offer_next>

<checkpoint_handling> When ag4-executor returns with checkpoint:

1. Parse return:

The subagent returns a structured checkpoint:

Copy## CHECKPOINT REACHED

**Type:** [human-verify | decision | human-action]
**Plan:** {phase}-{plan}
**Progress:** {completed}/{total} tasks complete

### Completed Tasks
| Task | Name | Commit | Files |
|------|------|--------|-------|
| 1 | [task name] | [hash] | [files] |

### Current Task
**Task {N}:** [name]
**Status:** [blocked | awaiting verification | awaiting decision]
**Blocked by:** [specific blocker]

### Checkpoint Details
[Type-specific content for user]

### Awaiting
[What user needs to provide]

2. Present checkpoint to user:

Display rich formatted checkpoint based on type:

For human-verify:

Copy╔═══════════════════════════════════════════════════════╗
║  CHECKPOINT: Verification Required                    ║
╚═══════════════════════════════════════════════════════╝

Progress: {X}/{Y} tasks complete
Task: {task name}

Built: {what-built from checkpoint details}

How to verify:
  {numbered verification steps}

────────────────────────────────────────────────────────
→ YOUR ACTION: Type "approved" or describe issues
────────────────────────────────────────────────────────

For human-action (auth gate):

Copy╔═══════════════════════════════════════════════════════╗
║  CHECKPOINT: Action Required                          ║
╚═══════════════════════════════════════════════════════╝

Progress: {X}/{Y} tasks complete
Task: {task name}

Attempted: {automation attempted}
Error: {error encountered}

What you need to do:
  {numbered instructions}

I'll verify: {verification}

────────────────────────────────────────────────────────
→ YOUR ACTION: Type "done" when complete
────────────────────────────────────────────────────────

For decision:

Copy╔═══════════════════════════════════════════════════════╗
║  CHECKPOINT: Decision Required                        ║
╚═══════════════════════════════════════════════════════╝

Progress: {X}/{Y} tasks complete
Task: {task name}

Decision: {what's being decided}

Context: {why this matters}

Options:
  1. {option-a} - {name}
     Pros: {benefits}
     Cons: {tradeoffs}

  2. {option-b} - {name}
     Pros: {benefits}
     Cons: {tradeoffs}

────────────────────────────────────────────────────────
→ YOUR ACTION: Select option-a or option-b
────────────────────────────────────────────────────────

3. Collect response: Wait for user input:

• human-verify: "approved" or description of issues
• decision: option selection
• human-action: "done" when complete

4. Spawn fresh continuation agent:

Spawn fresh ag4-executor with continuation context:

CopyTask(
  prompt="Continue executing plan at {plan_path}

<completed_tasks>
{completed_tasks_table from checkpoint return}
</completed_tasks>

<resume_point>
Resume from: Task {N} - {task_name}
User response: {user_response}
{resume_instructions based on checkpoint type}
</resume_point>

Plan: @{plan_path}
Project state: @.planning/STATE.md",
  subagent_type="ag4-executor",
  description="Continue {phase}-{plan}"
)

The ag4-executor has continuation handling baked in — it will verify previous commits and resume correctly.

Why fresh agent, not resume: Task tool resume fails after multiple tool calls (presenting to user, waiting for response). Fresh agent with state handoff is the correct pattern.

5. Repeat: Continue handling returns until "## PLAN COMPLETE" or user stops. </checkpoint_handling>

<success_criteria>

• Plan executed (SUMMARY.md created)
• All checkpoints handled
• If phase complete: Phase goal verified (ag4-verifier spawned, VERIFICATION.md created)
• If phase complete: REQUIREMENTS.md updated (phase requirements marked Complete)
• User informed of completion and next steps </success_criteria>