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:
Lex Christopherson
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
|
||||
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>"
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Write
|
||||
- Edit
|
||||
- Bash
|
||||
- Glob
|
||||
- Grep
|
||||
- Bash
|
||||
- Task
|
||||
- TaskOutput
|
||||
- TodoWrite
|
||||
- AskUserQuestion
|
||||
- SlashCommand
|
||||
---
|
||||
|
||||
<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.
|
||||
Spawns background agents for parallel execution, each agent commits its own tasks atomically.
|
||||
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.
|
||||
|
||||
**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
|
||||
Context budget: ~15% orchestrator, 100% fresh per subagent.
|
||||
</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
|
||||
@~/.claude/get-shit-done/templates/subagent-task-prompt.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
Phase number: $ARGUMENTS (required)
|
||||
Phase: $ARGUMENTS
|
||||
|
||||
@.planning/ROADMAP.md
|
||||
@.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
|
||||
1. **Validate phase exists**
|
||||
- Find phase directory matching argument
|
||||
- Count PLAN.md files
|
||||
- Error if no plans found
|
||||
|
||||
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>
|
||||
|
||||
<execution_strategies>
|
||||
**Strategy A: Fully Autonomous** (no checkpoints)
|
||||
<wave_execution>
|
||||
**Parallel spawning:**
|
||||
|
||||
- Spawn subagent to execute entire plan
|
||||
- Subagent creates SUMMARY.md and commits
|
||||
- Main context: orchestration only (~5% usage)
|
||||
Spawn all plans in a wave with a single message containing multiple Task calls:
|
||||
|
||||
**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
|
||||
- Subagent for autonomous segments
|
||||
- Main context for checkpoints
|
||||
- Aggregate results → SUMMARY → commit
|
||||
All three run in parallel. Task tool blocks until all complete.
|
||||
|
||||
**Strategy C: Decision-Dependent** (has decision checkpoints)
|
||||
**No polling.** No background agents. No TaskOutput loops.
|
||||
</wave_execution>
|
||||
|
||||
- Execute in main context
|
||||
- Decision outcomes affect subsequent tasks
|
||||
- Quality maintained through small scope (2-3 tasks per plan)
|
||||
</execution_strategies>
|
||||
<checkpoint_detection>
|
||||
Before adding a plan to a parallel wave, scan for checkpoints:
|
||||
|
||||
<deviation_rules>
|
||||
During execution, handle discoveries automatically:
|
||||
```bash
|
||||
grep -c 'type="checkpoint' {plan_path}
|
||||
```
|
||||
|
||||
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
|
||||
**If checkpoints > 0:**
|
||||
- Plan requires user interaction
|
||||
- Execute in main context OR as solo subagent (not parallel)
|
||||
- User interaction flows through normally
|
||||
|
||||
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>
|
||||
**If checkpoints = 0:**
|
||||
- Fully autonomous
|
||||
- Safe for parallel wave execution
|
||||
</checkpoint_detection>
|
||||
|
||||
<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
|
||||
- [ ] All incomplete plans in phase executed
|
||||
- [ ] Each plan has SUMMARY.md
|
||||
- [ ] STATE.md reflects phase completion
|
||||
- [ ] ROADMAP.md updated
|
||||
- [ ] User informed of next steps
|
||||
</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