run-plan

Run the IMPLEMENTATION PLAN phase-by-phase for a tracked change. Mark each task as completed and perform a Conventional Commit (via `/commit`) after every finished phase (or per task if directed). Automatically resumes from first incomplete phase on subsequent invocations. User invocation: /run-plan [plain text directives] Examples: /run-plan PDEV-123 /run-plan GH-456 execute next 3 phases and then ask for review /run-plan PDEV-123 execute all remaining phases /run-plan GH-456 execute phase 5 only /run-plan PDEV-123 execute all remaining phases no review /run-plan GH-456 dry run execute next 2 phases /run-plan PDEV-123 execute phase 3 commit per task workItemRef='$1' — Tracker reference (e.g., `PDEV-123`, `GH-456`). Uppercase prefix + hyphen + digits. directives='$ARGUMENTS' — Full arguments; if same as workItemRef, no directives.

<discovery_rules> Locate change folder: search doc/changes/**/*--<workItemRef>--*/ If not found, search for spec file: doc/changes/**/chg-<workItemRef>-spec.md Plan file: chg-<workItemRef>-plan.md inside the change folder. Spec file: chg-<workItemRef>-spec.md for change.type and slug validation. Folder pattern: doc/changes/YYYY-MM/YYYY-MM-DD--<workItemRef>--<slug>/ Never reference doc/changes/current/ in edits or evidence. </discovery_rules>

<branch_rules> <change.type>/<workItemRef>/<slug> 1. If current branch matches pattern → keep. 2. Else attempt checkout existing branch. 3. Else create new branch. 4. Abort if dirty working tree contains unrelated staged changes. </branch_rules>

<directive_parsing> Supported (case-insensitive):

• "execute next N phases" → run current incomplete phase + N−1 subsequent.
• "execute all remaining phases" → run all incomplete phases.
• "execute phase N" → run only phase N (must be incomplete).
• "ask for review" / "and then ask for review" → pause after requested phases (default).
• "no review" / "continue without review" → do not pause.
• "dry run" → simulate; no edits/commits.
• "commit per task" → commit after each task instead of per phase.

Defaults (no directive): phasesToRun=1; askForReview=true; commitMode=per-phase. </directive_parsing>

<plan_parsing_rules> Phase header regex: /^### Phase (\d+):/ Tasks: checkboxes under "Tasks:" until blank line or "Acceptance Criteria:" Unchecked: - [ ]; Completed: - [x] Completion: replace token only, append note e.g. (done: added config & tests) Acceptance criteria: lines start with "- Must:" or "- Should:"; append (PASSED: <summary>) or (FAILED: <summary>) Execution Log: header "## Execution Log"; append if missing </plan_parsing_rules>

<core_principles> Determinism: parsing & updates never reorder tasks or phases. Minimality: edit only necessary lines; avoid broad formatting changes. Traceability: every edit tied to task completion; commits atomic. Autonomy: proceed without prompting unless blocked. Idempotence: re-running resumes cleanly without duplicating evidence. </core_principles>

<phase_execution_rules> For each selected phase:

1. Identify pending tasks (unchecked). If none but acceptance evidence missing, treat as completion-only phase.
2. For each pending task: a. Form internal contract (goal, inputs, outputs, success checks). b. Discover relevant files in: src/, app/, packages/, modules/, lib/, services/, infra/, config/, scripts/, tests/, static/, doc/. c. Implement minimal edits; avoid unrelated refactors. d. Add/adjust tests when functional behavior changes. e. Run quick validations (typecheck/build/test subset). f. Mark task completed with concise evidence note. g. If commitMode=per-task: stage only task changes + plan update, then /commit.
3. After tasks complete: a. Run full quality gates; capture PASS/FAIL summaries. b. Append evidence to acceptance criteria lines (once only). c. Append Execution Log entry. d. If commitMode=per-phase: /commit.
4. Stop after phasesToRun. If askForReview=true, pause with summary. </phase_execution_rules>

<commit_rules> Use /commit for Conventional Commit generation. Per-phase default; per-task if directive present. Ensure no unrelated changes bleed across commits. Tasks with no code changes: mark completed; commit with other changes. </commit_rules>

<partial_failure_policy> After 3 fix attempts: mark task as (done: partial; deferred X). Do not mark acceptance criteria PASSED if behaviors deferred. Commit partial progress; pause and request guidance (override for blocking failure). </partial_failure_policy>

<quality_gates> Auto-detect once per invocation (cache for subsequent phases):

• build: scripts/, package.json ("build" script), Makefile, CI configs.
• test: package.json ("test" script), scripts/test.*, make test, pytest, go test.
• typecheck: tsc --noEmit if tsconfig; mypy if pyproject; go vet. If detection fails: record attempts and skip with evidence. </quality_gates>

<dry_run_behavior> No file edits, no commits. Output structured summary: starting phase, phasesToRun, task counts, detected commands, commit plan, next resume command. </dry_run_behavior>

<output_contract> Update plan file with task completion, acceptance evidence, Execution Log (unless dry run). Produce commits per commit_rules. Emit concise summary: phases executed, tasks completed, gates status, deferrals, next phase. On all phases complete: announce completion. </output_contract>

1. Parse $ARGUMENTS: first token → workItemRef; remainder → directives. 2. Validate workItemRef format (uppercase prefix + hyphen + digits). 3. Locate spec & plan via discovery_rules; derive slug & change.type; validate presence. 4. Validate plan structure (at least one phase with Tasks section). 5. Ensure correct branch per branch_rules. 6. Parse directives; decide phasesToRun, commitMode, askForReview, dryRun. 7. Identify start phase (earliest with unchecked task or missing acceptance evidence). 8. If dryRun: output summary; STOP. 9. Detect quality gate commands (cache). 10. Loop phases applying phase_execution_rules & partial_failure_policy. 11. Perform commits per policy. 12. Summarize; if askForReview=true and remaining phases exist → pause. 13. If all phases complete → final summary.

<plan_update_rules> Modify only: task checkbox lines; acceptance criteria lines; Execution Log section. Keep original line order & spacing (no reflow). Evidence parenthetical ≤ 80 chars; lowercase verbs; avoid redundancy. If Execution Log missing → append canonical section before first update. </plan_update_rules>

<error_handling> Capture stderr snippet (5-10 lines) for gate failures; summarize root cause. Retry up to 3 focused fixes; if persists, log deferral & proceed if non-blocking. Blocking failure → phase abort + partial commit; require review. </error_handling>

Fail fast if: - Spec or plan missing. - slug or change.type not derivable. - Target phase invalid or already complete. - No tasks and no acceptance criteria in targeted phase. Produce clear error; no edits/commits. 1) /run-plan PDEV-123 → Executes next incomplete phase; commits once; asks for review. 2) /run-plan GH-456 execute next 3 phases no review → Runs 3 phases without pausing. 3) /run-plan PDEV-123 execute phase 4 commit per task → Jumps to phase 4; commits per task. 4) /run-plan GH-456 dry run execute all remaining phases → Simulates; outputs plan. Plan produced by `/write-plan` template structure. `/commit` handles Conventional Commit formatting automatically.