execute-plan-parallel

name	execute-plan-parallel
description	Execute a markdown implementation plan by spawning parallel subagents for unblocked tasks, then integrate results and validate. Triggers on explicit "/execute-plan-parallel <plan.md> [optional selector]".

Execute Plan (Parallel)

Run an existing plan by delegating independent tasks to parallel subagents, then integrating and validating the combined result.

Contract

Prereqs:

• A plan file exists (markdown) with clear task breakdown and dependencies.
• You can spawn and monitor multiple subagents.
• The repo has a way to validate changes (tests, lint, build, or a manual checklist).
• plan-tooling available on PATH for parsing/linting (install via brew install nils-cli).

Inputs:

• Plan file path (required).
• Optional: sprint/phase/task selector (e.g., "sprint 2", "phase 1"). Selectors intentionally narrow the target scope; when absent, use the whole plan as the target scope.

Outputs:

• Code changes implementing the target scope: the whole plan by default, or a selector/confirmed staged execution window when explicitly narrowed.
• A concise execution summary: completed tasks, blocked tasks, files changed, and validation performed.

Exit codes:

• N/A (multi-step workflow skill)

Failure modes:

• Plan parsing fails (unexpected heading structure) or sprint not found.
• Tasks conflict in the same files and require sequential execution/merge resolution.
• A task is underspecified or blocked (missing access, unclear acceptance criteria).
• Whole-plan execution is unsuitable for the current run and the user has not confirmed staged execution or a narrower execution window.

Test-First Evidence Gate

• For any production behavior task, require the implementing subagent to provide failing-test evidence or an explicit waiver before editing production behavior.
• This gate applies before editing production behavior.
• Require each implementation report to include Change classification, Failing test before fix, Final validation, and Waiver reason when applicable.
• Accept waivers for docs-only, generated-only, formatting-only, visual-only, or no-harness tasks when substitute validation is stated.

Workflow

1. Parse the request

• Identify the plan file path.
• Determine target scope from the request. No selector means whole-plan target scope.
• Treat sprint, phase, task, priority, validation, or stop-condition selectors as explicit narrowing controls.

1. Read and parse the plan

• Prefer using repo tooling (avoid parsing drift):
  • Lint: plan-tooling validate --file <plan.md>
  • Parse JSON for the target: plan-tooling to-json --file <plan.md> [--sprint <n>]
  • Compute batches per selected sprint: plan-tooling batches --file <plan.md> --sprint <n>
• Locate all sprint/phase sections in the target scope; when no selector is present, include the whole plan.
• Extract tasks (e.g., ### Task 1.1:).
• For each task, capture:
  • ID/name
  • Location(s)
  • Acceptance criteria
  • Validation
  • Dependencies / blockers

1. Assess whole-plan suitability

• Before dispatching subagents, assess whether the target scope can be executed in the current run.
• For whole-plan target scope, consider plan size, dependency graph, same-file overlap, dirty worktree overlap, validation availability, credentials, migrations, external side effects, rollback risk, and expected runtime.
• If full-plan execution is unsuitable for one run, summarize the risks and ask the user to confirm either whole-plan target with staged checkpoints or an agreed narrower execution window with acceptance gates.
• Do not silently narrow the request to Sprint 1 or any other local default.

1. Launch parallel subagents for unblocked tasks

• Batch-launch subagents for tasks that have no unmet dependencies (use plan-tooling batches output when available).
• The main agent owns plan-wide scope, dispatch, integration, validation, and final synthesis.
• Provide each subagent the task text, relevant context, and strict scope: "implement this task only".
• Require each subagent to report:
  • Files modified/created
  • What changed
  • How acceptance criteria are met
  • What validation ran (or why not)

1. Integrate results and resolve conflicts

• Apply changes, resolve overlapping edits, and keep diffs minimal.
• If the plan implies commits, follow the repo’s commit policy (do not run git commit directly).

1. Repeat

• Mark completed tasks.
• Launch the next batch of unblocked tasks until the target scope is done, blocked, unsafe, validation fails, or a confirmed checkpoint is reached.

1. Validate

• Run the plan’s validation commands (or the closest available repo commands).
• If validation fails, fix within scope or mark the task blocked with the failure reason.

1. Report

• Summarize: completed vs blocked tasks, files changed, and validation status.