adrozdenko/soleri-parallel-execute

Parallel Execute — Subagent-Driven Plan Execution

Execute plan tasks in parallel by dispatching independent tasks to separate subagents. The controller agent (you) never implements — you dispatch, review, and integrate.

Announce at start: "I'm using the parallel-execute skill to run independent tasks concurrently."

<HARD-GATE> You MUST have an approved, split plan before using this skill. If no plan exists or it has no tasks, stop and use the writing-plans skill first. </HARD-GATE>

When to Use

• Plan has 3+ tasks
• At least 2 tasks have no dependency overlap (can run simultaneously)
• Tasks touch different files/modules (low merge conflict risk)

Do NOT use when:

• All tasks are sequential (each depends on the previous)
• Tasks modify the same files (high conflict risk)
• Plan has fewer than 3 tasks (use executing-plans instead)

Model Selection

Pick a model per subagent at dispatch. Mixed tiers across a fan-out wave are expected and correct — a wave is never "all Opus" or "all Haiku." Each task gets the model that fits its work.

Tier rubric

| Tier | Model | Subagent purpose — trigger patterns | | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | simple | haiku | Exploration, file/symbol lookup, pattern search, single-fact retrieval, dedup detection, quick classification, data extraction from known formats | | standard | sonnet | Code implementation, refactors, test writing, documentation, migrations, data transformation, routine reviews, general research | | complex | opus | Architecture review, deep-review, plan creation, grading/scoring, critical bug diagnosis, cross-cutting design decisions, ambiguity resolution, nuanced writing |

Fallback chain

• Opus unavailable → Sonnet with a warning, proceed
• Sonnet unavailable → Haiku only if task is clearly simple; otherwise pause and report
• Haiku unavailable → pause and report, don't escalate upward

Never silently fall back upward. Downward only.

Override contract

User pin always wins over rubric: "Run wave 2 on Opus" or "Use Haiku for task-5" — honor it.

Example fan-out

A 3-way wave with mixed tiers:

| Task | Purpose | Model | Tier | | ------ | --------------------------------------- | -------- | -------- | | task-1 | Scan repo for unused exports | haiku | simple | | task-3 | Refactor parser into module | sonnet | standard | | task-5 | Review cross-module contract for safety | opus | complex |

All three dispatched in the same Agent tool call batch, each with its own model arg.

Dispatch decision log

Before each Agent call in a wave, state one line:

Dispatching <description> on <model> (tier=<simple|standard|complex>, reason=<pattern match>).

Overrides stated explicitly:

Dispatching "..." on opus (tier=standard, overridden by user).

The Process

Step 1: Load Plan and Build Dependency Graph

YOUR_AGENT_core op:get_plan
YOUR_AGENT_core op:plan_list_tasks params:{ planId: "<id>" }

Map out which tasks are independent by checking dependsOn for each task. Group tasks into waves — sets of tasks that can run in parallel:

• Wave 1: All tasks with no dependencies (or whose dependencies are already complete)
• Wave 2: Tasks whose dependencies are all in Wave 1
• Wave N: Tasks whose dependencies are all in prior waves

Present the wave plan to the user before starting:

## Execution Waves

| Wave | Tasks | Parallel? |
|------|-------|-----------|
| 1 | task-1, task-3, task-5 | Yes (3 subagents) |
| 2 | task-2 (depends on task-1) | Solo |
| 3 | task-4 (depends on task-2, task-3) | Solo |

Step 2: Dispatch a Wave

For each task in the current wave:

1. Check readiness:

   YOUR_AGENT_core op:plan_dispatch params:{ planId: "<id>", taskId: "<taskId>" }
   

   Only dispatch tasks where ready: true.

2. Mark as in_progress:

   YOUR_AGENT_core op:update_task params:{ planId: "<id>", taskIndex: <n>, status: "in_progress" }
   

3. Gather vault context for the task:

   YOUR_AGENT_core op:search params:{ query: "<task topic>", mode: "scan" }
   

4. Launch all ready tasks as parallel Agent calls in a single message. Each subagent gets:

You are implementing a single task from a plan. Work autonomously.

## Task
- **ID**: {taskId}
- **Title**: {title}
- **Description**: {description}
- **Acceptance Criteria**: {criteria}

## Context
- **Plan Objective**: {planObjective}
- **Vault Patterns to Follow**: {relevantPatterns}
- **Files Likely Involved**: {fileHints}

## Rules
- Implement ONLY this task — do not touch files outside your scope
- Run tests after implementation
- If blocked, report the blocker and stop — do not guess
- Do not commit — the controller handles commits
- When done, report: files changed, tests passing, any concerns

## Self-Review Checklist
Before reporting completion, verify:
- [ ] All acceptance criteria met
- [ ] Tests pass
- [ ] No files modified outside task scope
- [ ] No console.log or debug code left behind
- [ ] No raw colors or hardcoded values (use semantic tokens)

Use the Agent tool with isolation: "worktree" when tasks touch nearby files to prevent conflicts.

Step 3: Collect Results

As subagents complete, collect their results. For each completed task:

1. Run spec review — spawn a reviewer subagent:

   YOUR_AGENT_core op:plan_review_spec params:{ planId: "<id>", taskId: "<taskId>" }
   

   Use the returned prompt to launch a spec-review Agent that reads the ACTUAL code changes (not the implementer's self-report).

2. Record spec review outcome:

   YOUR_AGENT_core op:plan_review_outcome params:{
     planId: "<id>", taskId: "<taskId>",
     reviewType: "spec", reviewer: "spec-reviewer",
     outcome: "approved|rejected|needs_changes",
     comments: "<specific file:line references>"
   }
   

3. If spec passes, run quality review:

   YOUR_AGENT_core op:plan_review_quality params:{ planId: "<id>", taskId: "<taskId>" }
   

   Launch a quality-review Agent with the returned prompt.

4. Record quality review outcome:

   YOUR_AGENT_core op:plan_review_outcome params:{
     planId: "<id>", taskId: "<taskId>",
     reviewType: "quality", reviewer: "quality-reviewer",
     outcome: "approved|rejected|needs_changes",
     comments: "<severity-tagged feedback>"
   }
   

5. Handle outcomes:

| Spec | Quality | Action | | ---- | ----------------- | ----------------------------------------------------------- | | Pass | Pass | Mark task completed | | Fail | — | Dispatch fix subagent with failure feedback (max 2 retries) | | Pass | Critical issues | Dispatch targeted fix subagent (max 2 retries) | | Pass | Minor issues only | Mark completed, note issues for later |

1. Mark completed:

   YOUR_AGENT_core op:update_task params:{ planId: "<id>", taskIndex: <n>, status: "completed" }
   

Step 4: Advance to Next Wave

After all tasks in a wave are complete (or failed after retries):

1. Report wave results to the user:

   ## Wave N Complete
   
   | Task | Status | Review | Notes |
   |------|--------|--------|-------|
   | task-1 | Completed | Spec: Pass, Quality: Pass | — |
   | task-3 | Completed | Spec: Pass, Quality: Minor issues | Noted for cleanup |
   | task-5 | Failed | Spec: Fail (2 retries exhausted) | Escalated |
   

2. Wait for user acknowledgment before proceeding to the next wave.

3. Check which tasks in the next wave are now ready (dependencies met).

4. Repeat from Step 2.

Step 5: Final Integration Review

After all waves complete:

1. Spawn a final review subagent that checks cross-cutting concerns:

   • Consistency across all task implementations
   • Integration points between tasks
   • No conflicting patterns or duplicate code
   • Tests pass together (not just individually)

2. Report to user with full execution summary.

Step 6: Complete Plan Lifecycle

Same as executing-plans — reconcile, capture knowledge, archive:

YOUR_AGENT_core op:plan_reconcile params:{
  planId: "<id>",
  actualOutcome: "<what happened>",
  driftItems: [{ type: "...", description: "...", impact: "...", rationale: "..." }]
}

YOUR_AGENT_core op:plan_complete_lifecycle params:{
  planId: "<id>",
  patterns: ["<patterns discovered>"],
  antiPatterns: ["<anti-patterns discovered>"]
}

YOUR_AGENT_core op:session_capture params:{
  summary: "<execution summary with parallel metrics>"
}

Subagent Isolation Rules

| Situation | Isolation | | -------------------------------------------- | ----------------------------------------- | | Tasks touch completely different directories | No isolation needed | | Tasks touch files in the same package | Use isolation: "worktree" | | Tasks modify the same file | Do NOT parallelize — run sequentially |

When using worktree isolation, the controller must merge worktree changes back after review passes, then immediately delete the local branch:

git branch -D <subagent/taskId>

Worktree branches are local-only — never push them to remote. Branch cleanup is mandatory after every merge.

Failure Handling

| Failure | Response | | ---------------------------- | ----------------------------------------------- | | Subagent reports blocker | Pause that task, continue others in the wave | | Spec review fails | Dispatch fix subagent with feedback (retry 1/2) | | Second retry fails | Mark task as failed, escalate to user | | Merge conflict from worktree | Resolve manually, then re-run quality review | | All tasks in wave fail | Stop execution, report to user |

Capture Learnings

During execution, capture insights about parallelization:

YOUR_AGENT_core op:capture_quick params:{
  title: "<what you learned about parallel execution>",
  description: "<context: which tasks parallelized well, which conflicted>"
}

When to Fall Back to Sequential

Switch to executing-plans skill mid-execution when:

• Subagents keep conflicting on shared files
• Merge resolution is taking longer than the parallelization saves
• User requests sequential execution

Agent Tools Reference

| Op | When to Use | | ------------------------- | ------------------------------------------- | | get_plan | Load tracked plan | | plan_list_tasks | List all tasks with dependencies | | plan_dispatch | Check task readiness (dependencies met?) | | update_task | Mark tasks in_progress / completed / failed | | plan_review_spec | Generate spec compliance review prompt | | plan_review_quality | Generate code quality review prompt | | plan_review_outcome | Record review pass/fail result | | plan_reconcile | Post-execution drift analysis | | plan_complete_lifecycle | Extract knowledge, archive | | session_capture | Save session context | | capture_quick | Capture mid-execution learnings | | search | Vault lookup for task context |

Integration

Required skills:

• writing-plans — Creates the plan this skill executes
• verification-before-completion — Verify work before claiming completion
• executing-plans — Fallback for sequential execution