refactor(execute-phase): wave-based blocking execution
Replace background agents + polling with blocking Task calls. Orchestrator stays lean (~15% context), subagents load full workflow. - Archive old execute-phase command and workflow - Add subagent-task-prompt.md template (orchestrator→subagent contract) - Rewrite execute-phase with wave-based parallelization - Dependency analysis groups plans into execution waves - Parallel Task calls within waves, sequential across waves - No TaskOutput polling - Task blocks until completion Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
120
commands/gsd/_archive/execute-phase.md
Normal file
120
commands/gsd/_archive/execute-phase.md
Normal file
@@ -0,0 +1,120 @@
|
|||||||
|
---
|
||||||
|
name: gsd:execute-phase
|
||||||
|
description: Execute all plans in a phase with intelligent parallelization
|
||||||
|
argument-hint: "<phase-number>"
|
||||||
|
allowed-tools:
|
||||||
|
- Read
|
||||||
|
- Write
|
||||||
|
- Edit
|
||||||
|
- Bash
|
||||||
|
- Glob
|
||||||
|
- Grep
|
||||||
|
- Task
|
||||||
|
- TaskOutput
|
||||||
|
- AskUserQuestion
|
||||||
|
- SlashCommand
|
||||||
|
---
|
||||||
|
|
||||||
|
<objective>
|
||||||
|
Execute all unexecuted plans in a phase with parallel agent spawning.
|
||||||
|
|
||||||
|
Analyzes plan dependencies to identify independent plans that can run concurrently.
|
||||||
|
Spawns background agents for parallel execution, each agent commits its own tasks atomically.
|
||||||
|
|
||||||
|
**Critical constraint:** One subagent per plan, always. This is for context isolation, not parallelization. Even strictly sequential plans spawn separate subagents so each starts with fresh 200k context at 0%.
|
||||||
|
|
||||||
|
Use this command when:
|
||||||
|
- Phase has 2+ unexecuted plans
|
||||||
|
- Want "walk away, come back to completed work" execution
|
||||||
|
- Plans have clear dependency boundaries
|
||||||
|
</objective>
|
||||||
|
|
||||||
|
<execution_context>
|
||||||
|
@~/.claude/get-shit-done/workflows/execute-plan.md
|
||||||
|
@~/.claude/get-shit-done/workflows/execute-phase.md
|
||||||
|
@~/.claude/get-shit-done/templates/summary.md
|
||||||
|
@~/.claude/get-shit-done/references/checkpoints.md
|
||||||
|
@~/.claude/get-shit-done/references/tdd.md
|
||||||
|
</execution_context>
|
||||||
|
|
||||||
|
<context>
|
||||||
|
Phase number: $ARGUMENTS (required)
|
||||||
|
|
||||||
|
@.planning/STATE.md
|
||||||
|
@.planning/config.json
|
||||||
|
</context>
|
||||||
|
|
||||||
|
<process>
|
||||||
|
1. Validate phase exists in roadmap
|
||||||
|
2. Find all PLAN.md files without matching SUMMARY.md
|
||||||
|
3. If 0 or 1 plans: suggest /gsd:execute-plan instead
|
||||||
|
4. If 2+ plans: follow execute-phase.md workflow
|
||||||
|
5. Monitor parallel agents until completion
|
||||||
|
6. Present results and next steps
|
||||||
|
</process>
|
||||||
|
|
||||||
|
<execution_strategies>
|
||||||
|
**Strategy A: Fully Autonomous** (no checkpoints)
|
||||||
|
|
||||||
|
- Spawn subagent to execute entire plan
|
||||||
|
- Subagent creates SUMMARY.md and commits
|
||||||
|
- Main context: orchestration only (~5% usage)
|
||||||
|
|
||||||
|
**Strategy B: Segmented** (has verify-only checkpoints)
|
||||||
|
|
||||||
|
- Execute in segments between checkpoints
|
||||||
|
- Subagent for autonomous segments
|
||||||
|
- Main context for checkpoints
|
||||||
|
- Aggregate results → SUMMARY → commit
|
||||||
|
|
||||||
|
**Strategy C: Decision-Dependent** (has decision checkpoints)
|
||||||
|
|
||||||
|
- Execute in main context
|
||||||
|
- Decision outcomes affect subsequent tasks
|
||||||
|
- Quality maintained through small scope (2-3 tasks per plan)
|
||||||
|
</execution_strategies>
|
||||||
|
|
||||||
|
<deviation_rules>
|
||||||
|
During execution, handle discoveries automatically:
|
||||||
|
|
||||||
|
1. **Auto-fix bugs** - Fix immediately, document in Summary
|
||||||
|
2. **Auto-add critical** - Security/correctness gaps, add and document
|
||||||
|
3. **Auto-fix blockers** - Can't proceed without fix, do it and document
|
||||||
|
4. **Ask about architectural** - Major structural changes, stop and ask user
|
||||||
|
5. **Log enhancements** - Nice-to-haves, log to ISSUES.md, continue
|
||||||
|
|
||||||
|
Only rule 4 requires user intervention.
|
||||||
|
</deviation_rules>
|
||||||
|
|
||||||
|
<commit_rules>
|
||||||
|
**Per-Task Commits:**
|
||||||
|
|
||||||
|
After each task completes:
|
||||||
|
1. Stage only files modified by that task
|
||||||
|
2. Commit with format: `{type}({phase}-{plan}): {task-name}`
|
||||||
|
3. Types: feat, fix, test, refactor, perf, chore
|
||||||
|
4. Record commit hash for SUMMARY.md
|
||||||
|
|
||||||
|
**Plan Metadata Commit:**
|
||||||
|
|
||||||
|
After all tasks complete:
|
||||||
|
1. Stage planning artifacts only: PLAN.md, SUMMARY.md, STATE.md, ROADMAP.md
|
||||||
|
2. Commit with format: `docs({phase}-{plan}): complete [plan-name] plan`
|
||||||
|
3. NO code files (already committed per-task)
|
||||||
|
|
||||||
|
**NEVER use:**
|
||||||
|
- `git add .`
|
||||||
|
- `git add -A`
|
||||||
|
- `git add src/` or any broad directory
|
||||||
|
|
||||||
|
**Always stage files individually.**
|
||||||
|
</commit_rules>
|
||||||
|
|
||||||
|
<success_criteria>
|
||||||
|
- [ ] All independent plans executed in parallel
|
||||||
|
- [ ] Dependent plans executed after dependencies complete
|
||||||
|
- [ ] Each task committed individually (feat/fix/test/refactor)
|
||||||
|
- [ ] All SUMMARY.md files created
|
||||||
|
- [ ] Metadata committed by orchestrator
|
||||||
|
- [ ] Phase progress updated
|
||||||
|
</success_criteria>
|
||||||
@@ -1,120 +1,113 @@
|
|||||||
---
|
---
|
||||||
name: gsd:execute-phase
|
name: gsd:execute-phase
|
||||||
description: Execute all plans in a phase with intelligent parallelization
|
description: Execute all plans in a phase with wave-based parallelization
|
||||||
argument-hint: "<phase-number>"
|
argument-hint: "<phase-number>"
|
||||||
allowed-tools:
|
allowed-tools:
|
||||||
- Read
|
- Read
|
||||||
- Write
|
|
||||||
- Edit
|
|
||||||
- Bash
|
|
||||||
- Glob
|
- Glob
|
||||||
- Grep
|
- Grep
|
||||||
|
- Bash
|
||||||
- Task
|
- Task
|
||||||
- TaskOutput
|
- TodoWrite
|
||||||
- AskUserQuestion
|
- AskUserQuestion
|
||||||
- SlashCommand
|
|
||||||
---
|
---
|
||||||
|
|
||||||
<objective>
|
<objective>
|
||||||
Execute all unexecuted plans in a phase with parallel agent spawning.
|
Execute all plans in a phase using wave-based parallel execution.
|
||||||
|
|
||||||
Analyzes plan dependencies to identify independent plans that can run concurrently.
|
Orchestrator stays lean: discover plans, analyze dependencies, group into waves, spawn subagents, collect results. Each subagent loads the full execute-plan context and handles its own plan.
|
||||||
Spawns background agents for parallel execution, each agent commits its own tasks atomically.
|
|
||||||
|
|
||||||
**Critical constraint:** One subagent per plan, always. This is for context isolation, not parallelization. Even strictly sequential plans spawn separate subagents so each starts with fresh 200k context at 0%.
|
Context budget: ~15% orchestrator, 100% fresh per subagent.
|
||||||
|
|
||||||
Use this command when:
|
|
||||||
- Phase has 2+ unexecuted plans
|
|
||||||
- Want "walk away, come back to completed work" execution
|
|
||||||
- Plans have clear dependency boundaries
|
|
||||||
</objective>
|
</objective>
|
||||||
|
|
||||||
<execution_context>
|
<execution_context>
|
||||||
@~/.claude/get-shit-done/workflows/execute-plan.md
|
|
||||||
@~/.claude/get-shit-done/workflows/execute-phase.md
|
@~/.claude/get-shit-done/workflows/execute-phase.md
|
||||||
@~/.claude/get-shit-done/templates/summary.md
|
@~/.claude/get-shit-done/templates/subagent-task-prompt.md
|
||||||
@~/.claude/get-shit-done/references/checkpoints.md
|
|
||||||
@~/.claude/get-shit-done/references/tdd.md
|
|
||||||
</execution_context>
|
</execution_context>
|
||||||
|
|
||||||
<context>
|
<context>
|
||||||
Phase number: $ARGUMENTS (required)
|
Phase: $ARGUMENTS
|
||||||
|
|
||||||
|
@.planning/ROADMAP.md
|
||||||
@.planning/STATE.md
|
@.planning/STATE.md
|
||||||
@.planning/config.json
|
|
||||||
</context>
|
</context>
|
||||||
|
|
||||||
<process>
|
<process>
|
||||||
1. Validate phase exists in roadmap
|
1. **Validate phase exists**
|
||||||
2. Find all PLAN.md files without matching SUMMARY.md
|
- Find phase directory matching argument
|
||||||
3. If 0 or 1 plans: suggest /gsd:execute-plan instead
|
- Count PLAN.md files
|
||||||
4. If 2+ plans: follow execute-phase.md workflow
|
- Error if no plans found
|
||||||
5. Monitor parallel agents until completion
|
|
||||||
6. Present results and next steps
|
2. **Discover plans**
|
||||||
|
- List all *-PLAN.md files in phase directory
|
||||||
|
- Check which have *-SUMMARY.md (already complete)
|
||||||
|
- Build list of incomplete plans
|
||||||
|
|
||||||
|
3. **Analyze dependencies**
|
||||||
|
- Read each plan's `<context>` section
|
||||||
|
- Detect cross-references to other plans' outputs
|
||||||
|
- Build dependency graph
|
||||||
|
|
||||||
|
4. **Group into waves**
|
||||||
|
- Wave 1: Plans with no dependencies
|
||||||
|
- Wave N: Plans depending only on earlier waves
|
||||||
|
- Report wave structure to user
|
||||||
|
|
||||||
|
5. **Execute waves**
|
||||||
|
For each wave:
|
||||||
|
- Fill subagent-task-prompt template for each plan
|
||||||
|
- Spawn all agents in wave simultaneously (parallel Task calls)
|
||||||
|
- Wait for completion (Task blocks)
|
||||||
|
- Verify SUMMARYs created
|
||||||
|
- Proceed to next wave
|
||||||
|
|
||||||
|
6. **Aggregate results**
|
||||||
|
- Collect summaries from all plans
|
||||||
|
- Report phase completion status
|
||||||
|
- Update ROADMAP.md
|
||||||
|
|
||||||
|
7. **Offer next steps**
|
||||||
|
- More phases → `/gsd:plan-phase {next}`
|
||||||
|
- Milestone complete → `/gsd:complete-milestone`
|
||||||
</process>
|
</process>
|
||||||
|
|
||||||
<execution_strategies>
|
<wave_execution>
|
||||||
**Strategy A: Fully Autonomous** (no checkpoints)
|
**Parallel spawning:**
|
||||||
|
|
||||||
- Spawn subagent to execute entire plan
|
Spawn all plans in a wave with a single message containing multiple Task calls:
|
||||||
- Subagent creates SUMMARY.md and commits
|
|
||||||
- Main context: orchestration only (~5% usage)
|
|
||||||
|
|
||||||
**Strategy B: Segmented** (has verify-only checkpoints)
|
```
|
||||||
|
Task(prompt=filled_template_for_plan_01, subagent_type="general-purpose")
|
||||||
|
Task(prompt=filled_template_for_plan_02, subagent_type="general-purpose")
|
||||||
|
Task(prompt=filled_template_for_plan_03, subagent_type="general-purpose")
|
||||||
|
```
|
||||||
|
|
||||||
- Execute in segments between checkpoints
|
All three run in parallel. Task tool blocks until all complete.
|
||||||
- Subagent for autonomous segments
|
|
||||||
- Main context for checkpoints
|
|
||||||
- Aggregate results → SUMMARY → commit
|
|
||||||
|
|
||||||
**Strategy C: Decision-Dependent** (has decision checkpoints)
|
**No polling.** No background agents. No TaskOutput loops.
|
||||||
|
</wave_execution>
|
||||||
|
|
||||||
- Execute in main context
|
<checkpoint_detection>
|
||||||
- Decision outcomes affect subsequent tasks
|
Before adding a plan to a parallel wave, scan for checkpoints:
|
||||||
- Quality maintained through small scope (2-3 tasks per plan)
|
|
||||||
</execution_strategies>
|
|
||||||
|
|
||||||
<deviation_rules>
|
```bash
|
||||||
During execution, handle discoveries automatically:
|
grep -c 'type="checkpoint' {plan_path}
|
||||||
|
```
|
||||||
|
|
||||||
1. **Auto-fix bugs** - Fix immediately, document in Summary
|
**If checkpoints > 0:**
|
||||||
2. **Auto-add critical** - Security/correctness gaps, add and document
|
- Plan requires user interaction
|
||||||
3. **Auto-fix blockers** - Can't proceed without fix, do it and document
|
- Execute in main context OR as solo subagent (not parallel)
|
||||||
4. **Ask about architectural** - Major structural changes, stop and ask user
|
- User interaction flows through normally
|
||||||
5. **Log enhancements** - Nice-to-haves, log to ISSUES.md, continue
|
|
||||||
|
|
||||||
Only rule 4 requires user intervention.
|
**If checkpoints = 0:**
|
||||||
</deviation_rules>
|
- Fully autonomous
|
||||||
|
- Safe for parallel wave execution
|
||||||
<commit_rules>
|
</checkpoint_detection>
|
||||||
**Per-Task Commits:**
|
|
||||||
|
|
||||||
After each task completes:
|
|
||||||
1. Stage only files modified by that task
|
|
||||||
2. Commit with format: `{type}({phase}-{plan}): {task-name}`
|
|
||||||
3. Types: feat, fix, test, refactor, perf, chore
|
|
||||||
4. Record commit hash for SUMMARY.md
|
|
||||||
|
|
||||||
**Plan Metadata Commit:**
|
|
||||||
|
|
||||||
After all tasks complete:
|
|
||||||
1. Stage planning artifacts only: PLAN.md, SUMMARY.md, STATE.md, ROADMAP.md
|
|
||||||
2. Commit with format: `docs({phase}-{plan}): complete [plan-name] plan`
|
|
||||||
3. NO code files (already committed per-task)
|
|
||||||
|
|
||||||
**NEVER use:**
|
|
||||||
- `git add .`
|
|
||||||
- `git add -A`
|
|
||||||
- `git add src/` or any broad directory
|
|
||||||
|
|
||||||
**Always stage files individually.**
|
|
||||||
</commit_rules>
|
|
||||||
|
|
||||||
<success_criteria>
|
<success_criteria>
|
||||||
- [ ] All independent plans executed in parallel
|
- [ ] All incomplete plans in phase executed
|
||||||
- [ ] Dependent plans executed after dependencies complete
|
- [ ] Each plan has SUMMARY.md
|
||||||
- [ ] Each task committed individually (feat/fix/test/refactor)
|
- [ ] STATE.md reflects phase completion
|
||||||
- [ ] All SUMMARY.md files created
|
- [ ] ROADMAP.md updated
|
||||||
- [ ] Metadata committed by orchestrator
|
- [ ] User informed of next steps
|
||||||
- [ ] Phase progress updated
|
|
||||||
</success_criteria>
|
</success_criteria>
|
||||||
|
|||||||
61
get-shit-done/templates/subagent-task-prompt.md
Normal file
61
get-shit-done/templates/subagent-task-prompt.md
Normal file
@@ -0,0 +1,61 @@
|
|||||||
|
# Subagent Task Prompt Template
|
||||||
|
|
||||||
|
Template for spawning plan execution subagents from execute-phase orchestrator.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Template
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
<objective>
|
||||||
|
Execute plan {plan_number} of phase {phase_number}-{phase_name}.
|
||||||
|
|
||||||
|
Commit each task atomically. Create SUMMARY.md. Update STATE.md.
|
||||||
|
</objective>
|
||||||
|
|
||||||
|
<execution_context>
|
||||||
|
@~/.claude/get-shit-done/workflows/execute-plan.md
|
||||||
|
@~/.claude/get-shit-done/templates/summary.md
|
||||||
|
@~/.claude/get-shit-done/references/checkpoints.md
|
||||||
|
@~/.claude/get-shit-done/references/tdd.md
|
||||||
|
</execution_context>
|
||||||
|
|
||||||
|
<context>
|
||||||
|
Plan: @{plan_path}
|
||||||
|
Project state: @.planning/STATE.md
|
||||||
|
Config: @.planning/config.json (if exists)
|
||||||
|
</context>
|
||||||
|
|
||||||
|
<success_criteria>
|
||||||
|
- [ ] All tasks executed
|
||||||
|
- [ ] Each task committed individually
|
||||||
|
- [ ] SUMMARY.md created in plan directory
|
||||||
|
- [ ] STATE.md updated with position and decisions
|
||||||
|
</success_criteria>
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Placeholders
|
||||||
|
|
||||||
|
| Placeholder | Source | Example |
|
||||||
|
|-------------|--------|---------|
|
||||||
|
| `{phase_number}` | Phase directory name | `01` |
|
||||||
|
| `{phase_name}` | Phase directory name | `foundation` |
|
||||||
|
| `{plan_number}` | Plan filename | `01` |
|
||||||
|
| `{plan_path}` | Full path to PLAN.md | `.planning/phases/01-foundation/01-01-PLAN.md` |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Usage
|
||||||
|
|
||||||
|
Orchestrator fills placeholders and passes to Task tool:
|
||||||
|
|
||||||
|
```python
|
||||||
|
Task(
|
||||||
|
prompt=filled_template,
|
||||||
|
subagent_type="general-purpose"
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
Subagent reads @-references, loads full workflow context, executes plan.
|
||||||
899
get-shit-done/workflows/_archive/execute-phase.md
Normal file
899
get-shit-done/workflows/_archive/execute-phase.md
Normal file
@@ -0,0 +1,899 @@
|
|||||||
|
<purpose>
|
||||||
|
Execute all plans in a phase with intelligent parallelization.
|
||||||
|
Analyzes plan dependencies to identify independent plans that can run in parallel.
|
||||||
|
|
||||||
|
**Critical constraint:** One subagent per plan, always. This is for context isolation, not parallelization. Even strictly sequential plans spawn separate subagents so each starts with fresh 200k context at 0%. Quality degrades above 50% context - executing multiple plans in one subagent defeats the entire segmentation model.
|
||||||
|
</purpose>
|
||||||
|
|
||||||
|
<when_to_use>
|
||||||
|
Use /gsd:execute-phase when:
|
||||||
|
- Phase has multiple unexecuted plans (2+)
|
||||||
|
- Want "walk away, come back to completed work" execution
|
||||||
|
- Plans have clear dependency boundaries
|
||||||
|
|
||||||
|
Use /gsd:execute-plan when:
|
||||||
|
- Executing a single specific plan
|
||||||
|
- Want sequential, interactive execution
|
||||||
|
- Need checkpoint interactions
|
||||||
|
</when_to_use>
|
||||||
|
|
||||||
|
<required_reading>
|
||||||
|
Read STATE.md before any operation to load project context.
|
||||||
|
</required_reading>
|
||||||
|
|
||||||
|
<process>
|
||||||
|
|
||||||
|
<step name="load_project_state" priority="first">
|
||||||
|
Before any operation, read project state:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cat .planning/STATE.md 2>/dev/null
|
||||||
|
```
|
||||||
|
|
||||||
|
**If file exists:** Parse and internalize:
|
||||||
|
|
||||||
|
- Current position (phase, plan, status)
|
||||||
|
- Accumulated decisions (constraints on this execution)
|
||||||
|
- Deferred issues (context for deviations)
|
||||||
|
- Blockers/concerns (things to watch for)
|
||||||
|
|
||||||
|
**If file missing but .planning/ exists:**
|
||||||
|
|
||||||
|
```
|
||||||
|
STATE.md missing but planning artifacts exist.
|
||||||
|
Options:
|
||||||
|
1. Reconstruct from existing artifacts
|
||||||
|
2. Continue without project state (may lose accumulated context)
|
||||||
|
```
|
||||||
|
|
||||||
|
**If .planning/ doesn't exist:** Error - project not initialized.
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step name="identify_phase">
|
||||||
|
**Identify the phase to execute from argument or roadmap.**
|
||||||
|
|
||||||
|
**1. Parse phase argument:**
|
||||||
|
```bash
|
||||||
|
# From command argument: /gsd:execute-phase 10
|
||||||
|
# Or: /gsd:execute-phase .planning/phases/10-parallel-execution/
|
||||||
|
PHASE_ARG="$1"
|
||||||
|
```
|
||||||
|
|
||||||
|
**2. Find phase directory:**
|
||||||
|
```bash
|
||||||
|
# If numeric: find matching directory
|
||||||
|
if [[ "$PHASE_ARG" =~ ^[0-9]+(\.[0-9]+)?$ ]]; then
|
||||||
|
PHASE_DIR=$(ls -d .planning/phases/${PHASE_ARG}-* 2>/dev/null | head -1)
|
||||||
|
else
|
||||||
|
PHASE_DIR="$PHASE_ARG"
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Verify exists
|
||||||
|
if [ ! -d "$PHASE_DIR" ]; then
|
||||||
|
echo "Error: Phase directory not found: $PHASE_DIR"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
```
|
||||||
|
|
||||||
|
**3. List all PLAN.md files:**
|
||||||
|
```bash
|
||||||
|
PLANS=($(ls "$PHASE_DIR"/*-PLAN.md 2>/dev/null | sort))
|
||||||
|
echo "Found ${#PLANS[@]} plans in phase"
|
||||||
|
```
|
||||||
|
|
||||||
|
**4. Identify unexecuted plans:**
|
||||||
|
```bash
|
||||||
|
UNEXECUTED=()
|
||||||
|
for plan in "${PLANS[@]}"; do
|
||||||
|
summary="${plan//-PLAN.md/-SUMMARY.md}"
|
||||||
|
if [ ! -f "$summary" ]; then
|
||||||
|
UNEXECUTED+=("$plan")
|
||||||
|
fi
|
||||||
|
done
|
||||||
|
echo "Unexecuted: ${#UNEXECUTED[@]} plans"
|
||||||
|
```
|
||||||
|
|
||||||
|
**5. Check if parallelization is appropriate:**
|
||||||
|
|
||||||
|
| Condition | Action |
|
||||||
|
|-----------|--------|
|
||||||
|
| 0 unexecuted plans | "All plans complete. Nothing to execute." |
|
||||||
|
| 1 unexecuted plan | "Single plan - use /gsd:execute-plan instead" |
|
||||||
|
| 2+ unexecuted plans | Proceed to dependency analysis |
|
||||||
|
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step name="analyze_plan_dependencies">
|
||||||
|
**Analyze plan dependencies to determine parallelization.**
|
||||||
|
|
||||||
|
**1. Find all unexecuted plans:**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
UNEXECUTED=()
|
||||||
|
for plan in .planning/phases/${PHASE}-*/*-PLAN.md; do
|
||||||
|
summary="${plan//-PLAN.md/-SUMMARY.md}"
|
||||||
|
[ ! -f "$summary" ] && UNEXECUTED+=("$plan")
|
||||||
|
done
|
||||||
|
echo "Found ${#UNEXECUTED[@]} unexecuted plans"
|
||||||
|
```
|
||||||
|
|
||||||
|
**2. For each plan, extract dependency info:**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Initialize associative arrays for tracking
|
||||||
|
declare -A PLAN_REQUIRES # plan -> required plans (from depends_on or inferred)
|
||||||
|
declare -A PLAN_FILES # plan -> files modified
|
||||||
|
declare -A PLAN_CHECKPOINTS # plan -> has checkpoints
|
||||||
|
|
||||||
|
for plan in "${UNEXECUTED[@]}"; do
|
||||||
|
plan_id=$(basename "$plan" -PLAN.md)
|
||||||
|
|
||||||
|
# Check for depends_on frontmatter
|
||||||
|
DEPENDS_ON=$(awk '/^---$/,/^---$/' "$plan" | grep "^depends_on:" | sed 's/depends_on: \[//' | sed 's/\]//' | tr -d ' "')
|
||||||
|
|
||||||
|
# Check for files_modified frontmatter
|
||||||
|
FILES_MODIFIED=$(awk '/^---$/,/^---$/' "$plan" | grep "^files_modified:" | sed 's/files_modified: \[//' | sed 's/\]//' | tr -d ' "')
|
||||||
|
|
||||||
|
# Use frontmatter if present
|
||||||
|
if [ -n "$DEPENDS_ON" ]; then
|
||||||
|
PLAN_REQUIRES["$plan_id"]="$DEPENDS_ON"
|
||||||
|
else
|
||||||
|
# Fall back to inference from old frontmatter format
|
||||||
|
REQUIRES=$(awk '/^---$/,/^---$/' "$plan" | grep -E "^\s*-\s*phase:" | grep -oP '\d+' | tr '\n' ',')
|
||||||
|
PLAN_REQUIRES["$plan_id"]="${REQUIRES%,}"
|
||||||
|
|
||||||
|
# Check for SUMMARY references in @context (implies dependency)
|
||||||
|
SUMMARY_REFS=$(grep -oP '@[^@]*\d+-\d+-SUMMARY\.md' "$plan" | grep -oP '\d+-\d+' | tr '\n' ',')
|
||||||
|
if [ -n "$SUMMARY_REFS" ]; then
|
||||||
|
PLAN_REQUIRES["$plan_id"]="${PLAN_REQUIRES[$plan_id]},${SUMMARY_REFS%,}"
|
||||||
|
fi
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Use files_modified frontmatter if present, else extract from <files> elements
|
||||||
|
if [ -n "$FILES_MODIFIED" ]; then
|
||||||
|
PLAN_FILES["$plan_id"]="$FILES_MODIFIED"
|
||||||
|
else
|
||||||
|
FILES=$(grep -oP '(?<=<files>)[^<]+(?=</files>)' "$plan" | tr '\n' ',' | tr -d ' ')
|
||||||
|
PLAN_FILES["$plan_id"]="${FILES%,}"
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Check for checkpoint tasks
|
||||||
|
if grep -q 'type="checkpoint' "$plan"; then
|
||||||
|
PLAN_CHECKPOINTS["$plan_id"]="true"
|
||||||
|
else
|
||||||
|
PLAN_CHECKPOINTS["$plan_id"]="false"
|
||||||
|
fi
|
||||||
|
done
|
||||||
|
```
|
||||||
|
|
||||||
|
**Dependency detection:**
|
||||||
|
|
||||||
|
1. **If `depends_on` frontmatter exists:** Use it directly
|
||||||
|
2. **If no frontmatter:** Fall back to inference:
|
||||||
|
- Parse `requires` from old frontmatter format
|
||||||
|
- Check for SUMMARY references in @context
|
||||||
|
3. **File conflicts:** Detected separately in step 4
|
||||||
|
|
||||||
|
**3. Build dependency graph:**
|
||||||
|
|
||||||
|
For each plan, determine:
|
||||||
|
- `requires`: Prior phases/plans this depends on
|
||||||
|
- `files_modified`: Files from `<files>` elements
|
||||||
|
- `has_checkpoints`: Contains checkpoint tasks
|
||||||
|
|
||||||
|
```
|
||||||
|
Example dependency graph:
|
||||||
|
┌─────────┬───────────────────────┬─────────────────────────────┬──────────────┐
|
||||||
|
│ Plan │ Requires │ Files Modified │ Checkpoints │
|
||||||
|
├─────────┼───────────────────────┼─────────────────────────────┼──────────────┤
|
||||||
|
│ 10-01 │ [] │ [workflows/execute-plan.md] │ false │
|
||||||
|
│ 10-02 │ [10-01] │ [workflows/execute-phase.md]│ false │
|
||||||
|
│ 10-03 │ [10-02] │ [commands/execute-phase.md] │ false │
|
||||||
|
│ 10-04 │ [] │ [templates/agent-history.md]│ false │
|
||||||
|
└─────────┴───────────────────────┴─────────────────────────────┴──────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
**4. Detect file conflicts:**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Build file-to-plan mapping
|
||||||
|
declare -A FILE_TO_PLANS
|
||||||
|
|
||||||
|
for plan_id in "${!PLAN_FILES[@]}"; do
|
||||||
|
IFS=',' read -ra files <<< "${PLAN_FILES[$plan_id]}"
|
||||||
|
for file in "${files[@]}"; do
|
||||||
|
[ -n "$file" ] && FILE_TO_PLANS["$file"]="${FILE_TO_PLANS[$file]},$plan_id"
|
||||||
|
done
|
||||||
|
done
|
||||||
|
|
||||||
|
# Detect conflicts (same file modified by multiple plans)
|
||||||
|
declare -A CONFLICTS
|
||||||
|
for file in "${!FILE_TO_PLANS[@]}"; do
|
||||||
|
plans="${FILE_TO_PLANS[$file]}"
|
||||||
|
plan_count=$(echo "$plans" | tr ',' '\n' | grep -c .)
|
||||||
|
if [ "$plan_count" -gt 1 ]; then
|
||||||
|
CONFLICTS["$file"]="${plans#,}"
|
||||||
|
fi
|
||||||
|
done
|
||||||
|
|
||||||
|
# Add conflict dependencies (later plan depends on earlier)
|
||||||
|
for file in "${!CONFLICTS[@]}"; do
|
||||||
|
IFS=',' read -ra conflict_plans <<< "${CONFLICTS[$file]}"
|
||||||
|
for ((i=1; i<${#conflict_plans[@]}; i++)); do
|
||||||
|
# Each plan depends on previous one in conflict set
|
||||||
|
prev="${conflict_plans[$((i-1))]}"
|
||||||
|
curr="${conflict_plans[$i]}"
|
||||||
|
PLAN_REQUIRES["$curr"]="${PLAN_REQUIRES[$curr]},${prev}"
|
||||||
|
done
|
||||||
|
done
|
||||||
|
```
|
||||||
|
|
||||||
|
**File conflict rules:**
|
||||||
|
- If Plan A and Plan B both modify same file → B depends on A (ordered by plan number)
|
||||||
|
- If Plan B reads file created by Plan A → B depends on A
|
||||||
|
- If Plan B references Plan A's SUMMARY in @context → B depends on A
|
||||||
|
|
||||||
|
**5. Categorize plans:**
|
||||||
|
|
||||||
|
| Category | Criteria | Action |
|
||||||
|
|----------|----------|--------|
|
||||||
|
| independent | Empty `depends_on` AND no file conflicts | Can run in parallel (Wave 1) |
|
||||||
|
| dependent | Has `depends_on` OR file conflicts with earlier plan | Wait for dependency |
|
||||||
|
| has_checkpoints | Contains checkpoint tasks | Foreground or skip checkpoints |
|
||||||
|
|
||||||
|
**6. Build execution waves (topological sort):**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Calculate wave for each plan
|
||||||
|
declare -A PLAN_WAVE
|
||||||
|
|
||||||
|
calculate_wave() {
|
||||||
|
local plan="$1"
|
||||||
|
[ -n "${PLAN_WAVE[$plan]}" ] && echo "${PLAN_WAVE[$plan]}" && return
|
||||||
|
|
||||||
|
local max_dep_wave=0
|
||||||
|
|
||||||
|
# Check depends_on (from frontmatter or inferred)
|
||||||
|
if [ -n "${PLAN_REQUIRES[$plan]}" ]; then
|
||||||
|
IFS=',' read -ra dep_array <<< "${PLAN_REQUIRES[$plan]}"
|
||||||
|
for dep in "${dep_array[@]}"; do
|
||||||
|
[ -z "$dep" ] && continue
|
||||||
|
# Only consider deps in current phase (unexecuted)
|
||||||
|
if [[ " ${!PLAN_FILES[*]} " =~ " $dep " ]]; then
|
||||||
|
dep_wave=$(calculate_wave "$dep")
|
||||||
|
[ "$dep_wave" -gt "$max_dep_wave" ] && max_dep_wave="$dep_wave"
|
||||||
|
fi
|
||||||
|
done
|
||||||
|
fi
|
||||||
|
|
||||||
|
PLAN_WAVE[$plan]=$((max_dep_wave + 1))
|
||||||
|
echo "${PLAN_WAVE[$plan]}"
|
||||||
|
}
|
||||||
|
|
||||||
|
# Calculate waves for all plans
|
||||||
|
for plan_id in "${!PLAN_FILES[@]}"; do
|
||||||
|
calculate_wave "$plan_id" > /dev/null
|
||||||
|
done
|
||||||
|
|
||||||
|
# Group by wave
|
||||||
|
declare -A WAVES
|
||||||
|
for plan_id in "${!PLAN_WAVE[@]}"; do
|
||||||
|
wave="${PLAN_WAVE[$plan_id]}"
|
||||||
|
WAVES[$wave]="${WAVES[$wave]} $plan_id"
|
||||||
|
done
|
||||||
|
|
||||||
|
# Output wave structure
|
||||||
|
echo "Execution waves:"
|
||||||
|
for wave in $(echo "${!WAVES[@]}" | tr ' ' '\n' | sort -n); do
|
||||||
|
plans="${WAVES[$wave]}"
|
||||||
|
checkpoint_note=""
|
||||||
|
frontmatter_note=""
|
||||||
|
for p in $plans; do
|
||||||
|
[ "${PLAN_CHECKPOINTS[$p]}" = "true" ] && checkpoint_note=" (has checkpoints)"
|
||||||
|
[ "${PLAN_HAS_FRONTMATTER[$p]}" = "true" ] && frontmatter_note=" [frontmatter]"
|
||||||
|
done
|
||||||
|
echo " Wave $wave:$plans$checkpoint_note$frontmatter_note"
|
||||||
|
done
|
||||||
|
```
|
||||||
|
|
||||||
|
**Example output:**
|
||||||
|
```
|
||||||
|
Execution waves:
|
||||||
|
Wave 1: 10-01 10-04
|
||||||
|
Wave 2: 10-02
|
||||||
|
Wave 3: 10-03
|
||||||
|
```
|
||||||
|
|
||||||
|
**7. Handle checkpoints in parallel context:**
|
||||||
|
|
||||||
|
Plans with checkpoints require special handling:
|
||||||
|
- `checkpoint_handling: "foreground"` → Run in main context (not parallel)
|
||||||
|
- `checkpoint_handling: "skip"` → Skip checkpoints during parallel (not recommended)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Separate checkpoint plans
|
||||||
|
PARALLEL_PLANS=()
|
||||||
|
FOREGROUND_PLANS=()
|
||||||
|
|
||||||
|
for plan_id in "${!PLAN_CHECKPOINTS[@]}"; do
|
||||||
|
if [ "${PLAN_CHECKPOINTS[$plan_id]}" = "true" ]; then
|
||||||
|
FOREGROUND_PLANS+=("$plan_id")
|
||||||
|
else
|
||||||
|
PARALLEL_PLANS+=("$plan_id")
|
||||||
|
fi
|
||||||
|
done
|
||||||
|
|
||||||
|
if [ ${#FOREGROUND_PLANS[@]} -gt 0 ]; then
|
||||||
|
echo "Plans requiring foreground execution: ${FOREGROUND_PLANS[*]}"
|
||||||
|
fi
|
||||||
|
```
|
||||||
|
|
||||||
|
**8. Safety rule:**
|
||||||
|
If dependency detection is uncertain (e.g., complex file patterns, unclear requires), default to sequential execution within that wave.
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step name="parallelization_config">
|
||||||
|
**Read parallelization configuration.**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cat .planning/config.json 2>/dev/null
|
||||||
|
```
|
||||||
|
|
||||||
|
**Config schema (parallelization section):**
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"parallelization": {
|
||||||
|
"enabled": true,
|
||||||
|
"max_concurrent_agents": 3,
|
||||||
|
"checkpoint_handling": "foreground",
|
||||||
|
"commit_strategy": "orchestrator"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Config options:**
|
||||||
|
|
||||||
|
| Option | Values | Default | Description |
|
||||||
|
|--------|--------|---------|-------------|
|
||||||
|
| enabled | true/false | true | Enable parallel execution |
|
||||||
|
| max_concurrent_agents | 1-5 | 3 | Max simultaneous background agents |
|
||||||
|
| checkpoint_handling | "foreground"/"skip" | "foreground" | How to handle plans with checkpoints |
|
||||||
|
| commit_strategy | "orchestrator"/"agent" | "orchestrator" | Who commits changes |
|
||||||
|
|
||||||
|
**If parallelization.enabled is false:**
|
||||||
|
- Fall back to sequential execution
|
||||||
|
- Use /gsd:execute-plan for each plan in order
|
||||||
|
|
||||||
|
**Checkpoint handling modes:**
|
||||||
|
- `foreground`: Plans with checkpoints run in foreground (not parallel)
|
||||||
|
- `skip`: Skip checkpoints during parallel execution (not recommended)
|
||||||
|
|
||||||
|
**Commit strategy:**
|
||||||
|
- `orchestrator`: Agents don't commit. Orchestrator collects all changes and commits.
|
||||||
|
- `agent`: Each agent commits its own changes (may cause conflicts)
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step name="spawn_parallel_agents">
|
||||||
|
**Spawn independent plans as parallel background agents.**
|
||||||
|
|
||||||
|
**1. Record pre-spawn git state:**
|
||||||
|
```bash
|
||||||
|
PRE_SPAWN_COMMIT=$(git rev-parse HEAD)
|
||||||
|
echo "All agents start from commit: $PRE_SPAWN_COMMIT"
|
||||||
|
```
|
||||||
|
|
||||||
|
**2. Generate parallel group ID:**
|
||||||
|
```bash
|
||||||
|
PARALLEL_GROUP="pg-$(date +%Y%m%d%H%M%S)-$(openssl rand -hex 4)"
|
||||||
|
```
|
||||||
|
|
||||||
|
**3. Initialize tracking:**
|
||||||
|
```bash
|
||||||
|
# Ensure agent-history.json exists
|
||||||
|
if [ ! -f .planning/agent-history.json ]; then
|
||||||
|
echo '{"version":"1.2","max_entries":50,"entries":[]}' > .planning/agent-history.json
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Initialize tracking arrays
|
||||||
|
declare -a RUNNING_AGENTS=()
|
||||||
|
declare -a QUEUED_PLANS=()
|
||||||
|
declare -A AGENT_TO_PLAN=()
|
||||||
|
```
|
||||||
|
|
||||||
|
**4. Spawn Wave 1 plans (no dependencies):**
|
||||||
|
|
||||||
|
```
|
||||||
|
For each plan in Wave 1:
|
||||||
|
# Check concurrent agent limit
|
||||||
|
if len(RUNNING_AGENTS) >= max_concurrent_agents:
|
||||||
|
QUEUED_PLANS.append(plan)
|
||||||
|
continue
|
||||||
|
|
||||||
|
# Use Task tool to spawn background agent
|
||||||
|
Task(
|
||||||
|
description="Execute {plan_id} (parallel)",
|
||||||
|
prompt="[Agent prompt below]",
|
||||||
|
subagent_type="general-purpose",
|
||||||
|
run_in_background=true
|
||||||
|
)
|
||||||
|
|
||||||
|
# After Task returns, capture agent_id
|
||||||
|
RUNNING_AGENTS.append(agent_id)
|
||||||
|
AGENT_TO_PLAN[agent_id] = plan_id
|
||||||
|
|
||||||
|
# Record to agent-history.json
|
||||||
|
add_entry_to_history(...)
|
||||||
|
```
|
||||||
|
|
||||||
|
**Agent spawn prompt (for plans WITHOUT checkpoints):**
|
||||||
|
|
||||||
|
```xml
|
||||||
|
<parallel_agent_instructions>
|
||||||
|
You are executing plan: {plan_path} as part of a PARALLEL phase execution.
|
||||||
|
|
||||||
|
<critical_rules>
|
||||||
|
1. Execute ALL tasks in the plan following deviation rules from execute-plan.md
|
||||||
|
2. Commit each task atomically (standard task_commit protocol)
|
||||||
|
3. Create SUMMARY.md in the phase directory when complete
|
||||||
|
4. Report files modified and commit hashes when done
|
||||||
|
</critical_rules>
|
||||||
|
|
||||||
|
<plan_context>
|
||||||
|
@{plan_path}
|
||||||
|
Read the plan for full context, tasks, and deviation rules.
|
||||||
|
</plan_context>
|
||||||
|
|
||||||
|
<execution_protocol>
|
||||||
|
1. Read plan file and context files
|
||||||
|
2. Execute each task in order
|
||||||
|
3. For each task:
|
||||||
|
- Implement the action
|
||||||
|
- Run verification
|
||||||
|
- Track files modified
|
||||||
|
- Track any deviations
|
||||||
|
4. After all tasks: create SUMMARY.md
|
||||||
|
</execution_protocol>
|
||||||
|
|
||||||
|
<report_format>
|
||||||
|
When complete, output this exact format:
|
||||||
|
|
||||||
|
PARALLEL_AGENT_COMPLETE
|
||||||
|
plan_id: {phase}-{plan}
|
||||||
|
tasks_completed: [count]/[total]
|
||||||
|
task_commits:
|
||||||
|
- task_1: abc123f
|
||||||
|
- task_2: def456g
|
||||||
|
files_modified:
|
||||||
|
- path/to/file1.ts
|
||||||
|
- path/to/file2.md
|
||||||
|
deviations:
|
||||||
|
- [Rule X] description
|
||||||
|
summary_path: .planning/phases/{phase-dir}/{phase}-{plan}-SUMMARY.md
|
||||||
|
issues: [none or list]
|
||||||
|
END_REPORT
|
||||||
|
</report_format>
|
||||||
|
|
||||||
|
<forbidden_actions>
|
||||||
|
- git push (orchestrator may push after all complete)
|
||||||
|
- Modifying files outside plan scope
|
||||||
|
- Running long-blocking network operations
|
||||||
|
</forbidden_actions>
|
||||||
|
</parallel_agent_instructions>
|
||||||
|
```
|
||||||
|
|
||||||
|
**5. Record spawn in agent-history.json:**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Read current entries
|
||||||
|
ENTRIES=$(jq '.entries' .planning/agent-history.json)
|
||||||
|
|
||||||
|
# Create new entry
|
||||||
|
NEW_ENTRY=$(cat <<EOF
|
||||||
|
{
|
||||||
|
"agent_id": "$AGENT_ID",
|
||||||
|
"task_description": "Parallel: Execute ${PHASE}-${PLAN}-PLAN.md",
|
||||||
|
"phase": "$PHASE",
|
||||||
|
"plan": "$PLAN",
|
||||||
|
"parallel_group": "$PARALLEL_GROUP",
|
||||||
|
"granularity": "plan",
|
||||||
|
"wave": $WAVE_NUM,
|
||||||
|
"depends_on": $(echo "${PLAN_REQUIRES[$PLAN]}" | jq -R 'split(",") | map(select(. != ""))'),
|
||||||
|
"timestamp": "$(date -u +"%Y-%m-%dT%H:%M:%SZ")",
|
||||||
|
"status": "spawned",
|
||||||
|
"files_modified": [],
|
||||||
|
"completion_timestamp": null,
|
||||||
|
"deviations": []
|
||||||
|
}
|
||||||
|
EOF
|
||||||
|
)
|
||||||
|
|
||||||
|
# Append and write back
|
||||||
|
echo "$ENTRIES" | jq ". += [$NEW_ENTRY]" > /tmp/entries.json
|
||||||
|
jq --argjson entries "$(cat /tmp/entries.json)" '.entries = $entries' .planning/agent-history.json > /tmp/history.json
|
||||||
|
mv /tmp/history.json .planning/agent-history.json
|
||||||
|
```
|
||||||
|
|
||||||
|
**6. Queue remaining plans:**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Queue Wave 2+ plans
|
||||||
|
for wave in $(seq 2 $MAX_WAVE); do
|
||||||
|
for plan in ${WAVES[$wave]}; do
|
||||||
|
QUEUED_PLANS+=("$plan:$wave")
|
||||||
|
done
|
||||||
|
done
|
||||||
|
|
||||||
|
echo "Spawned: ${#RUNNING_AGENTS[@]} agents"
|
||||||
|
echo "Queued: ${#QUEUED_PLANS[@]} plans"
|
||||||
|
```
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step name="monitor_parallel_completion">
|
||||||
|
**Poll for agent completion and spawn dependents.**
|
||||||
|
|
||||||
|
**1. Polling loop implementation:**
|
||||||
|
|
||||||
|
```
|
||||||
|
declare -A COMPLETED_AGENTS=()
|
||||||
|
declare -A FAILED_AGENTS=()
|
||||||
|
|
||||||
|
while [ ${#RUNNING_AGENTS[@]} -gt 0 ] || [ ${#QUEUED_PLANS[@]} -gt 0 ]; do
|
||||||
|
|
||||||
|
# Check each running agent
|
||||||
|
for agent_id in "${RUNNING_AGENTS[@]}"; do
|
||||||
|
|
||||||
|
# Use TaskOutput to check status (non-blocking)
|
||||||
|
TaskOutput(
|
||||||
|
task_id=agent_id,
|
||||||
|
block=false,
|
||||||
|
timeout=5000
|
||||||
|
)
|
||||||
|
|
||||||
|
if result.status == "completed":
|
||||||
|
# Parse agent's completion report
|
||||||
|
files_modified = parse_report_files(result.output)
|
||||||
|
deviations = parse_report_deviations(result.output)
|
||||||
|
plan_id = AGENT_TO_PLAN[agent_id]
|
||||||
|
|
||||||
|
# Update agent-history.json
|
||||||
|
update_history_entry(
|
||||||
|
agent_id,
|
||||||
|
status="completed",
|
||||||
|
files_modified=files_modified,
|
||||||
|
deviations=deviations,
|
||||||
|
completion_timestamp=now()
|
||||||
|
)
|
||||||
|
|
||||||
|
# Track completion
|
||||||
|
COMPLETED_AGENTS[agent_id] = plan_id
|
||||||
|
RUNNING_AGENTS.remove(agent_id)
|
||||||
|
|
||||||
|
echo "✓ Agent $agent_id completed plan $plan_id"
|
||||||
|
echo " Files: ${#files_modified[@]}"
|
||||||
|
echo " Deviations: ${#deviations[@]}"
|
||||||
|
|
||||||
|
# Check if dependents can now spawn
|
||||||
|
check_and_spawn_dependents()
|
||||||
|
|
||||||
|
elif result.status == "failed":
|
||||||
|
plan_id = AGENT_TO_PLAN[agent_id]
|
||||||
|
|
||||||
|
# Log failure
|
||||||
|
update_history_entry(
|
||||||
|
agent_id,
|
||||||
|
status="failed",
|
||||||
|
error=result.error,
|
||||||
|
completion_timestamp=now()
|
||||||
|
)
|
||||||
|
|
||||||
|
FAILED_AGENTS[agent_id] = plan_id
|
||||||
|
RUNNING_AGENTS.remove(agent_id)
|
||||||
|
|
||||||
|
echo "✗ Agent $agent_id FAILED on plan $plan_id"
|
||||||
|
echo " Error: ${result.error}"
|
||||||
|
|
||||||
|
# Continue monitoring - don't abort batch
|
||||||
|
|
||||||
|
# else: still running, check next agent
|
||||||
|
done
|
||||||
|
|
||||||
|
# Brief pause between polls
|
||||||
|
sleep 10
|
||||||
|
|
||||||
|
done
|
||||||
|
```
|
||||||
|
|
||||||
|
**2. Parse agent completion report:**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
parse_report_files() {
|
||||||
|
local output="$1"
|
||||||
|
# Extract files from PARALLEL_AGENT_COMPLETE block
|
||||||
|
echo "$output" | \
|
||||||
|
sed -n '/^files_modified:/,/^[a-z_]*:/p' | \
|
||||||
|
grep '^\s*-' | \
|
||||||
|
sed 's/^\s*-\s*//'
|
||||||
|
}
|
||||||
|
|
||||||
|
parse_report_deviations() {
|
||||||
|
local output="$1"
|
||||||
|
echo "$output" | \
|
||||||
|
sed -n '/^deviations:/,/^[a-z_]*:/p' | \
|
||||||
|
grep '^\s*-' | \
|
||||||
|
sed 's/^\s*-\s*//'
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**3. Spawn ready dependents:**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
check_and_spawn_dependents() {
|
||||||
|
# Get completed plan IDs
|
||||||
|
local completed_plans=$(printf '%s\n' "${COMPLETED_AGENTS[@]}")
|
||||||
|
|
||||||
|
for i in "${!QUEUED_PLANS[@]}"; do
|
||||||
|
local queued="${QUEUED_PLANS[$i]}"
|
||||||
|
local plan_id="${queued%%:*}"
|
||||||
|
local wave="${queued##*:}"
|
||||||
|
|
||||||
|
# Get this plan's dependencies
|
||||||
|
local deps="${PLAN_REQUIRES[$plan_id]}"
|
||||||
|
|
||||||
|
# Check if all dependencies are in completed list
|
||||||
|
local all_deps_met=true
|
||||||
|
IFS=',' read -ra dep_array <<< "$deps"
|
||||||
|
for dep in "${dep_array[@]}"; do
|
||||||
|
[ -z "$dep" ] && continue
|
||||||
|
if ! echo "$completed_plans" | grep -q "^$dep$"; then
|
||||||
|
all_deps_met=false
|
||||||
|
break
|
||||||
|
fi
|
||||||
|
done
|
||||||
|
|
||||||
|
if [ "$all_deps_met" = true ]; then
|
||||||
|
# Check concurrent limit
|
||||||
|
if [ ${#RUNNING_AGENTS[@]} -lt $MAX_CONCURRENT ]; then
|
||||||
|
# Remove from queue
|
||||||
|
unset 'QUEUED_PLANS[$i]'
|
||||||
|
|
||||||
|
# Spawn agent
|
||||||
|
spawn_plan_agent "$plan_id" "$wave"
|
||||||
|
|
||||||
|
echo "→ Spawned dependent: $plan_id (wave $wave)"
|
||||||
|
fi
|
||||||
|
fi
|
||||||
|
done
|
||||||
|
|
||||||
|
# Rebuild array to remove gaps
|
||||||
|
QUEUED_PLANS=("${QUEUED_PLANS[@]}")
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**4. Handle failures:**
|
||||||
|
|
||||||
|
| Failure Type | Action |
|
||||||
|
|--------------|--------|
|
||||||
|
| Agent crash | Log status="failed", continue batch |
|
||||||
|
| Plan error | Same as crash - logged, batch continues |
|
||||||
|
| All dependents | Plans depending on failed agent also fail |
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# When agent fails, mark its dependents as blocked
|
||||||
|
mark_dependents_blocked() {
|
||||||
|
local failed_plan="$1"
|
||||||
|
|
||||||
|
for i in "${!QUEUED_PLANS[@]}"; do
|
||||||
|
local queued="${QUEUED_PLANS[$i]}"
|
||||||
|
local plan_id="${queued%%:*}"
|
||||||
|
local deps="${PLAN_REQUIRES[$plan_id]}"
|
||||||
|
|
||||||
|
if echo "$deps" | grep -q "$failed_plan"; then
|
||||||
|
echo "⚠ Plan $plan_id blocked (depends on failed $failed_plan)"
|
||||||
|
# Mark in history as blocked
|
||||||
|
update_history_entry("queued-$plan_id", status="blocked", blocked_by="$failed_plan")
|
||||||
|
fi
|
||||||
|
done
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**5. Completion conditions:**
|
||||||
|
|
||||||
|
```
|
||||||
|
while true:
|
||||||
|
if RUNNING_AGENTS is empty AND QUEUED_PLANS is empty:
|
||||||
|
break # All done
|
||||||
|
|
||||||
|
if RUNNING_AGENTS is empty AND QUEUED_PLANS is not empty:
|
||||||
|
# All queued plans are blocked by failed dependencies
|
||||||
|
echo "All remaining plans blocked by failures"
|
||||||
|
break
|
||||||
|
|
||||||
|
poll_and_check()
|
||||||
|
```
|
||||||
|
|
||||||
|
**6. Progress display:**
|
||||||
|
|
||||||
|
```
|
||||||
|
During execution, show:
|
||||||
|
|
||||||
|
═══════════════════════════════════════════════════
|
||||||
|
Parallel Execution Status
|
||||||
|
═══════════════════════════════════════════════════
|
||||||
|
Running: [agent-1: 10-01] [agent-2: 10-04]
|
||||||
|
Queued: 10-02, 10-03
|
||||||
|
Complete: 0
|
||||||
|
Failed: 0
|
||||||
|
═══════════════════════════════════════════════════
|
||||||
|
|
||||||
|
[Update periodically as agents complete]
|
||||||
|
```
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step name="orchestrator_commit">
|
||||||
|
**Commit metadata after all agents complete.**
|
||||||
|
|
||||||
|
Agents commit their own task code (per-task atomic commits). The orchestrator only commits metadata.
|
||||||
|
|
||||||
|
**1. Verify all agents committed successfully:**
|
||||||
|
```bash
|
||||||
|
# Check git log for expected commits from each agent
|
||||||
|
for agent in $(jq -r ".entries[] | select(.parallel_group==\"$PARALLEL_GROUP\" and .status==\"completed\") | .agent_id" .planning/agent-history.json); do
|
||||||
|
PLAN=$(jq -r ".entries[] | select(.agent_id==\"$agent\") | .plan" .planning/agent-history.json)
|
||||||
|
# Verify commits exist for this plan
|
||||||
|
git log --oneline --grep="(${PHASE}-${PLAN}):" | head -5
|
||||||
|
done
|
||||||
|
```
|
||||||
|
|
||||||
|
**2. Stage and commit metadata:**
|
||||||
|
```bash
|
||||||
|
# Stage all SUMMARY.md files created by agents
|
||||||
|
git add .planning/phases/${PHASE_DIR}/*-SUMMARY.md
|
||||||
|
|
||||||
|
# Stage STATE.md and ROADMAP.md
|
||||||
|
git add .planning/STATE.md
|
||||||
|
git add .planning/ROADMAP.md
|
||||||
|
|
||||||
|
# Commit metadata
|
||||||
|
git commit -m "docs(${PHASE}): complete phase via parallel execution
|
||||||
|
|
||||||
|
Plans executed: ${#COMPLETED[@]}
|
||||||
|
Parallel group: $PARALLEL_GROUP
|
||||||
|
|
||||||
|
Agents:
|
||||||
|
$(for a in "${COMPLETED[@]}"; do echo "- $a"; done)"
|
||||||
|
```
|
||||||
|
|
||||||
|
**3. Generate timing stats:**
|
||||||
|
```bash
|
||||||
|
START_TIME=$(jq -r ".entries[] | select(.parallel_group==\"$PARALLEL_GROUP\") | .timestamp" .planning/agent-history.json | sort | head -1)
|
||||||
|
END_TIME=$(jq -r ".entries[] | select(.parallel_group==\"$PARALLEL_GROUP\") | .completion_timestamp" .planning/agent-history.json | sort -r | head -1)
|
||||||
|
|
||||||
|
echo "Parallel execution stats:"
|
||||||
|
echo "- Plans executed: ${#COMPLETED[@]}"
|
||||||
|
echo "- Wall clock time: $(time_diff $START_TIME $END_TIME)"
|
||||||
|
echo "- Sequential estimate: $(sum of individual plan durations)"
|
||||||
|
echo "- Time saved: ~X%"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Note on merge conflicts:**
|
||||||
|
Since agents commit independently, git will catch conflicts at commit time if they occur.
|
||||||
|
The dependency analysis step should prevent this, but if an agent fails to commit due to conflict:
|
||||||
|
- That agent's status will be "failed"
|
||||||
|
- Other agents continue normally
|
||||||
|
- User can resolve and retry the failed plan with /gsd:execute-plan
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step name="create_phase_summary">
|
||||||
|
**Aggregate results into phase-level summary.**
|
||||||
|
|
||||||
|
After all plans complete, create a phase summary that aggregates:
|
||||||
|
|
||||||
|
**1. Collect individual SUMMARY.md files:**
|
||||||
|
```bash
|
||||||
|
SUMMARIES=($(ls "$PHASE_DIR"/*-SUMMARY.md | sort))
|
||||||
|
```
|
||||||
|
|
||||||
|
**2. Update STATE.md:**
|
||||||
|
- Update Current Position
|
||||||
|
- Add any decisions from individual summaries
|
||||||
|
- Update session continuity
|
||||||
|
|
||||||
|
**3. Update ROADMAP.md:**
|
||||||
|
- Mark phase as complete
|
||||||
|
- Add completion date
|
||||||
|
- Update progress table
|
||||||
|
|
||||||
|
**4. Report completion:**
|
||||||
|
```
|
||||||
|
═══════════════════════════════════════════════════
|
||||||
|
Phase {X}: {Phase Name} Complete (Parallel Execution)
|
||||||
|
═══════════════════════════════════════════════════
|
||||||
|
|
||||||
|
Plans executed: {N}
|
||||||
|
- {phase}-01: [name] - {duration}
|
||||||
|
- {phase}-02: [name] - {duration}
|
||||||
|
- {phase}-03: [name] - {duration}
|
||||||
|
|
||||||
|
Execution mode: Parallel ({max_concurrent} agents)
|
||||||
|
Wall clock time: {total_duration}
|
||||||
|
Estimated sequential time: {sum_of_durations}
|
||||||
|
Time saved: ~{percent}%
|
||||||
|
|
||||||
|
Files modified: {total_count}
|
||||||
|
Commits created: {commit_count}
|
||||||
|
```
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step name="offer_next">
|
||||||
|
**Present next steps after phase completion.**
|
||||||
|
|
||||||
|
Read ROADMAP.md to determine milestone status.
|
||||||
|
|
||||||
|
**If more phases remain in milestone:**
|
||||||
|
```
|
||||||
|
## ✓ Phase {X}: {Phase Name} Complete
|
||||||
|
|
||||||
|
All {N} plans finished via parallel execution.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ▶ Next Up
|
||||||
|
|
||||||
|
**Phase {X+1}: {Next Phase Name}** — {Goal from ROADMAP.md}
|
||||||
|
|
||||||
|
`/gsd:plan-phase {X+1}`
|
||||||
|
|
||||||
|
<sub>`/clear` first → fresh context window</sub>
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Also available:**
|
||||||
|
- `/gsd:verify-work {X}` — manual acceptance testing
|
||||||
|
- `/gsd:discuss-phase {X+1}` — gather context first
|
||||||
|
```
|
||||||
|
|
||||||
|
**If milestone complete:**
|
||||||
|
```
|
||||||
|
🎉 MILESTONE COMPLETE!
|
||||||
|
|
||||||
|
All {N} phases finished.
|
||||||
|
|
||||||
|
`/gsd:complete-milestone`
|
||||||
|
```
|
||||||
|
</step>
|
||||||
|
|
||||||
|
</process>
|
||||||
|
|
||||||
|
<error_handling>
|
||||||
|
|
||||||
|
**Agent failure during parallel execution:**
|
||||||
|
- Log failure but continue with other agents
|
||||||
|
- Failed plans can be retried individually with /gsd:execute-plan
|
||||||
|
- Do not automatically retry (may cause cascade failures)
|
||||||
|
|
||||||
|
**Merge conflict detected:**
|
||||||
|
- Stop orchestrator_commit
|
||||||
|
- Present conflicting files to user
|
||||||
|
- Options:
|
||||||
|
1. Manual resolution
|
||||||
|
2. Re-run sequential with /gsd:execute-plan
|
||||||
|
|
||||||
|
**Max concurrent limit reached:**
|
||||||
|
- Queue excess plans
|
||||||
|
- Spawn as agents complete
|
||||||
|
- First-in-first-out ordering within each wave
|
||||||
|
|
||||||
|
**Config.json missing:**
|
||||||
|
- Use defaults: enabled=true, max_concurrent=3, orchestrator commits
|
||||||
|
|
||||||
|
</error_handling>
|
||||||
|
|
||||||
|
<success_criteria>
|
||||||
|
- All plans in phase executed
|
||||||
|
- All agents completed (no failures)
|
||||||
|
- Commits created for all plans
|
||||||
|
- STATE.md updated
|
||||||
|
- ROADMAP.md updated
|
||||||
|
- No merge conflicts
|
||||||
|
</success_criteria>
|
||||||
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user