tfm_ainventory/.agent/workflows/superpowers-execute-plan-parallel.md

description

description
Execute an approved plan with parallel execution for independent steps. Spawns isolated subagents. Consolidates results.

Superpowers Execute Plan (Parallel Mode)

Overview

This workflow executes an approved plan by identifying independent steps and running them in parallel using isolated subagents.

When to use parallel mode

• Plan has 2+ steps that don't depend on each other
• Steps operate on different files or independent modules
• You want faster execution (parallel > sequential)

When NOT to use parallel mode

• Steps have dependencies (Step 2 needs Step 1's output)
• All steps modify the same file
• Plan has < 2 steps
• You want simpler debugging (sequential is easier to debug)

If unsure, use /superpowers-execute-plan (sequential) instead.

---

Preconditions (do not skip)

1. The user must have replied APPROVED to a written plan
2. The approved plan must exist at: artifacts/superpowers/plan.md

If artifacts/superpowers/plan.md does not exist:

• Stop immediately
• Tell the user to run /superpowers-write-plan first
• Do not continue

---

Load and analyze the plan

1. Read artifacts/superpowers/plan.md
2. Parse all plan steps
3. Identify dependencies between steps:
   • Does Step 2 modify files created/changed by Step 1?
   • Does Step 2 need Step 1's verification to pass first?
   • Do they modify the same files?
4. Group steps into execution batches:
   • Batch 1: All independent steps (no dependencies)
   • Batch 2: Steps that depend on Batch 1 completing
   • Batch 3: Steps that depend on Batch 2 completing
   • etc.

---

Execution strategy

For each batch:

1. Spawn subagents in parallel for all steps in the batch:

# Example: Batch 1 has 3 independent steps
python .agent/skills/superpowers-workflow/scripts/spawn_subagent.py \
  --skill tdd \
  --task "Step 1: Add retry logic to sync.py with exponential backoff" &

python .agent/skills/superpowers-workflow/scripts/spawn_subagent.py \
  --skill rest-automation \
  --task "Step 2: Add pagination handling to fetch_items()" &

python .agent/skills/superpowers-workflow/scripts/spawn_subagent.py \
  --skill python-automation \
  --task "Step 3: Update CLI args to support --max-retries flag" &

# Wait for all to complete
wait

2. Collect results from each subagent:

   • Check log files in artifacts/superpowers/subagents/
   • Extract final results from each
   • Check success/failure status

3. Verify batch completion:

   • Run verification commands for all steps in the batch
   • If ANY step fails:
     • Stop execution
     • Switch to /superpowers-debug for the failed step
     • Do NOT continue to next batch

4. Append to execution log:

   • Write batch summary to artifacts/superpowers/execution.md:

     ## Batch N (Parallel Execution)
     - Step X: [SUCCESS/FAILED] - Files: [...] - Duration: Xs
     - Step Y: [SUCCESS/FAILED] - Files: [...] - Duration: Ys
     
     Verification:
     - Step X: [command] -> [result]
     - Step Y: [command] -> [result]
     

5. Move to next batch (if all steps passed)

---

Skill selection for subagents

Choose the appropriate skill for each step:

Step Type	Skill to Use
Add tests, TDD cycle	tdd
Fix bugs, investigate failures	debug
Code review, quality check	review
REST API work	rest-automation
Python tooling/scripts	python-automation
General implementation	tdd (default)

---

Consolidation phase

After all batches complete:

1. Integration verification:

   • Run full test suite (not just individual step tests)
   • Verify all changes work together
   • Check for conflicts between parallel changes

2. Conflict resolution:

   • If parallel steps modified related code:
     • Review for integration issues
     • Run combined tests
     • Fix any conflicts

3. Final artifacts:

   • Update artifacts/superpowers/execution.md with:
     • Total batches executed
     • Total steps completed
     • Total time saved vs sequential
     • All verification results
   • Write artifacts/superpowers/finish.md with:
     • Summary of changes
     • Integration test results
     • Follow-up items (if any)

---

Example: 5-step plan with 2 batches

Plan:

1. Add retry logic to sync.py (independent)
2. Add pagination to API client (independent)
3. Update CLI args (independent)
4. Add integration test (depends on 1, 2, 3)
5. Update docs (depends on 4 passing)

Execution:

Batch 1 (parallel):

• Spawn 3 subagents for steps 1, 2, 3
• Wait for all to complete (~5 min instead of ~15 min sequential)
• Verify each step

Batch 2 (sequential):

• Step 4: Add integration test (needs 1+2+3 complete)
• Verify test passes

Batch 3 (sequential):

• Step 5: Update docs (needs 4 complete)
• Verify docs are accurate

Total time: ~10 min vs ~25 min sequential = 60% time savings

---

Troubleshooting

Subagent spawn fails

• Check that gemini is in PATH (verify with: gemini --version)
• Verify skill exists: .agent/skills/superpowers-{skill}/SKILL.md
• Check subagent logs in artifacts/superpowers/subagents/

Steps conflict

• Falls back to sequential execution for conflicting steps
• Mark dependent steps explicitly in plan to avoid conflicts

Verification fails after parallel execution

• Check integration - parallel steps may work individually but conflict
• Run /superpowers-debug to investigate
• Consider re-running in sequential mode: /superpowers-execute-plan

---

Persist (mandatory)

Write execution notes to disk:

• Append batch summaries to: artifacts/superpowers/execution.md
• Write final summary to: artifacts/superpowers/finish.md

Ensure artifacts/superpowers/ exists. Confirm files exist by listing artifacts/superpowers/ when done.

---

Finish

After all steps complete:

1. Run /superpowers-review (or inline review pass)
2. Generate final summary with time savings metrics
3. List all changed files
4. Provide any manual validation steps

Stop after completing the finish step.