---
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.
