execute-plan

<purpose> Execute a phase prompt (PLAN.md) and create the outcome summary (SUMMARY.md). </purpose> <required_reading> Read STATE.md before any operation to load project context. Read config.json for planning behavior settings. ../../instructions/git-integration.instructions.md </required_reading> <process> <step name="resolve_model_profile" priority="first"> Read model profile for agent spawning: ```bash MODEL_PROFILE=$(cat .gsd/config.json 2>/dev/null | grep -o '"model_profile"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"' || echo "balanced") ``` Default to "balanced" if not set. **Model lookup table:** | Agent | quality | balanced | budget | | ------------ | ------- | -------- | ------ | | gsd-executor | opus | sonnet | sonnet | Store resolved model for use in Task calls below. </step> <step name="load_project_state"> Before any operation, read project state: ```bash cat .gsd/STATE.md 2>/dev/null ``` **If file exists:** Parse and internalize: - Current position (phase, plan, status) - Accumulated decisions (constraints on this execution) - Blockers/concerns (things to watch for) - Brief alignment status **If file missing but .gsd/ exists:** ``` STATE.md missing but planning artifacts exist. Options: 1. Reconstruct from existing artifacts 2. Continue without project state (may lose accumulated context) ``` **If .gsd/ doesn't exist:** Error - project not initialized. This ensures every execution has full project context. **Load planning config:** ```bash # Check if planning docs should be committed (default: true) COMMIT_PLANNING_DOCS=$(cat .gsd/config.json 2>/dev/null | grep -o '"commit_docs"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true") # Auto-detect gitignored (overrides config) git check-ignore -q .gsd 2>/dev/null && COMMIT_PLANNING_DOCS=false ``` Store `COMMIT_PLANNING_DOCS` for use in git operations. </step> <step name="identify_plan"> Find the next plan to execute: - Check roadmap for "In progress" phase - Find plans in that phase directory - Identify first plan without corresponding SUMMARY ```bash cat .gsd/ROADMAP.md # Look for phase with "In progress" status # Then find plans in that phase ls .gsd/phases/XX-name/*-PLAN.md 2>/dev/null | sort ls .gsd/phases/XX-name/*-SUMMARY.md 2>/dev/null | sort ``` **Logic:** - If `01-01-PLAN.md` exists but `01-01-SUMMARY.md` doesn't → execute 01-01 - If `01-01-SUMMARY.md` exists but `01-02-SUMMARY.md` doesn't → execute 01-02 - Pattern: Find first PLAN file without matching SUMMARY file **Decimal phase handling:** Phase directories can be integer or decimal format: - Integer: `.gsd/phases/01-foundation/01-01-PLAN.md` - Decimal: `.gsd/phases/01.1-hotfix/01.1-01-PLAN.md` Parse phase number from path (handles both formats): ```bash # Extract phase number (handles XX or XX.Y format) PHASE=$(echo "$PLAN_PATH" | grep -oE '[0-9]+(\.[0-9]+)?-[0-9]+') ``` SUMMARY naming follows same pattern: - Integer: `01-01-SUMMARY.md` - Decimal: `01.1-01-SUMMARY.md` Confirm with user if ambiguous. <config-check> ```bash cat .gsd/config.json 2>/dev/null ``` </config-check> <if mode="yolo"> ``` ⚡ Auto-approved: Execute {phase}-{plan}-PLAN.md [Plan X of Y for Phase Z] Starting execution... ``` Proceed directly to parse_segments step. </if> <if mode="interactive" OR="custom with gates.execute_next_plan true"> Present: ``` Found plan to execute: {phase}-{plan}-PLAN.md [Plan X of Y for Phase Z] Proceed with execution? ```` Wait for confirmation before proceeding. </if> </step> <step name="record_start_time"> Record execution start time for performance tracking: ```bash PLAN_START_TIME=$(date -u +"%Y-%m-%dT%H:%M:%SZ") PLAN_START_EPOCH=$(date +%s) ```` Store in shell variables for duration calculation at completion. </step> <step name="parse_segments"> **Intelligent segmentation: Parse plan into execution segments.** Plans are divided into segments by checkpoints. Each segment is routed to optimal execution context (subagent or main). **1. Check for checkpoints:** ```bash # Find all checkpoints and their types grep -n "type=\"checkpoint" .gsd/phases/XX-name/{phase}-{plan}-PLAN.md ``` **2. Analyze execution strategy:** **If NO checkpoints found:** - **Fully autonomous plan** - spawn single subagent for entire plan - Subagent gets fresh 200k context, executes all tasks, creates SUMMARY, commits - Main context: Just orchestration (~5% usage) **If checkpoints found, parse into segments:** Segment = tasks between checkpoints (or start→first checkpoint, or last checkpoint→end) **For each segment, determine routing:** ``` Segment routing rules: IF segment has no prior checkpoint: → SUBAGENT (first segment, nothing to depend on) IF segment follows checkpoint:human-verify: → SUBAGENT (verification is just confirmation, doesn't affect next work) IF segment follows checkpoint:decision OR checkpoint:human-action: → MAIN CONTEXT (next tasks need the decision/result) ``` **3. Execution pattern:** **Pattern A: Fully autonomous (no checkpoints)** ``` Spawn subagent → execute all tasks → SUMMARY → commit → report back ``` **Pattern B: Segmented with verify-only checkpoints** ``` Segment 1 (tasks 1-3): Spawn subagent → execute → report back Checkpoint 4 (human-verify): Main context → you verify → continue Segment 2 (tasks 5-6): Spawn NEW subagent → execute → report back Checkpoint 7 (human-verify): Main context → you verify → continue Aggregate results → SUMMARY → commit ``` **Pattern C: Decision-dependent (must stay in main)** ``` Checkpoint 1 (decision): Main context → you decide → continue in main Tasks 2-5: Main context (need decision from checkpoint 1) No segmentation benefit - execute entirely in main ``` **4. Why segment:** Fresh context per subagent preserves peak quality. Main context stays lean (~15% usage). **5. Implementation:** **For fully autonomous plans:** ``` 1. Run init_agent_tracking step first (see step below) 2. Use Task tool with subagent_type="gsd-executor" and model="{executor_model}": Prompt: "Execute plan at .gsd/phases/{phase}-{plan}-PLAN.md This is an autonomous plan (no checkpoints). Execute all tasks, create SUMMARY.md in phase directory, commit with message following plan's commit guidance. Follow all deviation rules and authentication gate protocols from the plan. When complete, report: plan name, tasks completed, SUMMARY path, commit hash." 3. After Task tool returns with agent_id: a. Write agent_id to current-agent-id.txt: echo "[agent_id]" > .gsd/current-agent-id.txt b. Append spawn entry to agent-history.json: { "agent_id": "[agent_id from Task response]", "task_description": "Execute full plan {phase}-{plan} (autonomous)", "phase": "{phase}", "plan": "{plan}", "segment": null, "timestamp": "[ISO timestamp]", "status": "spawned", "completion_timestamp": null } 4. Wait for subagent to complete 5. After subagent completes successfully: a. Update agent-history.json entry: - Find entry with matching agent_id - Set status: "completed" - Set completion_timestamp: "[ISO timestamp]" b. Clear current-agent-id.txt: rm .gsd/current-agent-id.txt 6. Report completion to user ``` **For segmented plans (has verify-only checkpoints):** ``` Execute segment-by-segment: For each autonomous segment: Spawn subagent with prompt: "Execute tasks [X-Y] from plan at .gsd/phases/{phase}-{plan}-PLAN.md. Read the plan for full context and deviation rules. Do NOT create SUMMARY or commit - just execute these tasks and report results." Wait for subagent completion For each checkpoint: Execute in main context Wait for user interaction Continue to next segment After all segments complete: Aggregate all results Create SUMMARY.md Commit with all changes ``` **For decision-dependent plans:** ``` Execute in main context (standard flow below) No subagent routing Quality maintained through small scope (2-3 tasks per plan) ``` See step name="segment_execution" for detailed segment execution loop. </step> <step name="init_agent_tracking"> **Initialize agent tracking for subagent resume capability.** Before spawning any subagents, set up tracking infrastructure: **1. Create/verify tracking files:** ```bash # Create agent history file if doesn't exist if [ ! -f .gsd/agent-history.json ]; then echo '{"version":"1.0","max_entries":50,"entries":[]}' > .gsd/agent-history.json fi # Clear any stale current-agent-id (from interrupted sessions) # Will be populated when subagent spawns rm -f .gsd/current-agent-id.txt ``` **2. Check for interrupted agents (resume detection):** ```bash # Check if current-agent-id.txt exists from previous interrupted session if [ -f .gsd/current-agent-id.txt ]; then INTERRUPTED_ID=$(cat .gsd/current-agent-id.txt) echo "Found interrupted agent: $INTERRUPTED_ID" fi ``` **If interrupted agent found:** - The agent ID file exists from a previous session that didn't complete - This agent can potentially be resumed using Task tool's `resume` parameter - Present to user: "Previous session was interrupted. Resume agent [ID] or start fresh?" - If resume: Use Task tool with `resume` parameter set to the interrupted ID - If fresh: Clear the file and proceed normally **3. Prune old entries (housekeeping):** If agent-history.json has more than `max_entries`: - Remove oldest entries with status "completed" - Never remove entries with status "spawned" (may need resume) - Keep file under size limit for fast reads **When to run this step:** - Pattern A (fully autonomous): Before spawning the single subagent - Pattern B (segmented): Before the segment execution loop - Pattern C (main context): Skip - no subagents spawned </step> <step name="segment_execution"> **Detailed segment execution loop for segmented plans.** **This step applies ONLY to segmented plans (Pattern B: has checkpoints, but they're verify-only).** For Pattern A (fully autonomous) and Pattern C (decision-dependent), skip this step. **Execution flow:** ```` 1. Parse plan to identify segments: - Read plan file - Find checkpoint locations: grep -n "type=\"checkpoint" PLAN.md - Identify checkpoint types: grep "type=\"checkpoint" PLAN.md | grep -o 'checkpoint:[^"]*' - Build segment map: * Segment 1: Start → first checkpoint (tasks 1-X) * Checkpoint 1: Type and location * Segment 2: After checkpoint 1 → next checkpoint (tasks X+1 to Y) * Checkpoint 2: Type and location * ... continue for all segments 2. For each segment in order: A. Determine routing (apply rules from parse_segments): - No prior checkpoint? → Subagent - Prior checkpoint was human-verify? → Subagent - Prior checkpoint was decision/human-action? → Main context B. If routing = Subagent: ``` Spawn Task tool with subagent_type="gsd-executor" and model="{executor_model}": Prompt: "Execute tasks [task numbers/names] from plan at [plan path]. **Context:** - Read the full plan for objective, context files, and deviation rules - You are executing a SEGMENT of this plan (not the full plan) - Other segments will be executed separately **Your responsibilities:** - Execute only the tasks assigned to you - Follow all deviation rules and authentication gate protocols - Track deviations for later Summary - DO NOT create SUMMARY.md (will be created after all segments complete) - DO NOT commit (will be done after all segments complete) **Report back:** - Tasks completed - Files created/modified - Deviations encountered - Any issues or blockers" **After Task tool returns with agent_id:** 1. Write agent_id to current-agent-id.txt: echo "[agent_id]" > .gsd/current-agent-id.txt 2. Append spawn entry to agent-history.json: { "agent_id": "[agent_id from Task response]", "task_description": "Execute tasks [X-Y] from plan {phase}-{plan}", "phase": "{phase}", "plan": "{plan}", "segment": [segment_number], "timestamp": "[ISO timestamp]", "status": "spawned", "completion_timestamp": null } Wait for subagent to complete Capture results (files changed, deviations, etc.) **After subagent completes successfully:** 1. Update agent-history.json entry: - Find entry with matching agent_id - Set status: "completed" - Set completion_timestamp: "[ISO timestamp]"