/milestone-runner

name: milestone-runner
description: 'Use when asked to "run milestones", "execute EXECUTION_PROMPTS.md", "run this /goal", "continue the milestone sequence", "run independent milestones in parallel", "merge the stack", or "reconcile M5" after prior work changes the current design. Not for generating a new plan; use plan-prompts. Not for repairing one stack; use stacked-prs.'
metadata:
  version: 3.1.0
  category: development
  tags: [milestones, orchestration, adaptive-planning, stacked-prs, ci, release-management, execution-prompts, subagents]
  difficulty: advanced
  phase: ship
  complements:
    - plan-prompts
    - stacked-prs
    - ship-workflow

Milestone Runner

Run approved milestones from `.docs/EXECUTION_PROMPTS.md` (or an authorized path), or an explicitly supplied small `/goal`, until their user-visible outcomes work, pass applicable gates and merge. Execute the authorized destination, not a new plan; materialize ready prompts as described below. Use `stacked-prs` only for justified stacks, `ship-workflow` for landing/cleanup and `release-captain` for authorized release trains.

Stay on the goal

The project destination is the north star; the current milestone is a contribution, not the whole project.

• Before each active milestone, carry the concise PROJECT destination/workflow, GOAL contribution, NON-GOALS and DONE WHEN from the current plan or explicitly supplied small `/goal`. Historical conversation and lane preferences are not authority.
• Apply necessary-now: implement enablers/architecture only for current acceptance, safety/current correctness, mandatory rules or irreversible constraints. Mere relevance to the vision is insufficient; defer optional work with a concrete revisit condition. Preserve maintainability and affordable change, not speculative universal abstractions.
• Required provider checks, repository mandates and explicit owner gates remain required. Unavailable optional evidence (credentials, spend, human-only review) is a reported follow-up, not an invented blocker or authorization to spend.
• Reuse passing evidence unless its code, configuration, head/base or required context changed; repository/`ship-workflow` freshness rules control.
• Once the observed outcome, applicable checks, substantive review and merge are complete, move on.

Modes

| Mode | Trigger | Behavior | | --- | --- | --- | | Sequential | "run milestones", "one after another" | Default. Run the next dependency-ready milestone through the loop below, merge, continue. | | Parallel | "run independent milestones in parallel" | Only for milestones with no dependency and no shared files. Run design checks serially, then launch each in its own worktree. | | Resume / status | "continue the milestone sequence", "where are we", "is CI green" | Rebuild state from the plan, merged and open PRs with their branches, CI and current code, not from checkboxes or notes. Resume in-progress PRs instead of duplicating them. Report what the user can do now, what is merged, what is open, what remains. Continue with the next ready milestone only when asked to continue; a status or CI question is read-only. | | Merge and clean | "merge the stack", "merge and clean up" | Requires an explicit merge request. Verify gates, delegate landing and cleanup to `ship-workflow` (step 5), check release readiness. |

Milestone loop

1. Inspect

1. Read the plan and active prompt with preconditions. An explicit small `/goal` supplies authority: no plan files. For a ready rolling-wave item without a prompt, use `plan-prompts`' active format: express its approved outcome as binary `Done when`, carry existing acceptance constraints and choose routine file/check/PR detail from the current repo. Save in the existing prompt file (create the canonical execution file if absent) with the first implementation commit. This needs no owner round-trip; adding/changing outcome or acceptance requirements or resolving an owner decision does. 2. Confirm predecessors merged using provider state. A stable unmerged interface dependency is usable only with explicit owner or approved-plan authority naming it; confirm its current interface and affected revisions, keep landing order/gates intact and invalidate affected evidence on change. Stability alone grants no exception. 3. Confirm a clean canonical workspace before any branch, merge, rebase or cleanup. Keep unready roadmap items deferred, not blocked for missing prompts or checks; when no actionable work remains, report the roadmap constraint and stop.

Report a short table before launching:

| Milestone | Depends on | Release | Status | Runnable now | | --- | --- | --- | --- | --- |

2. Design check

One check per active milestone before code: does it match the repo, contribute to the project destination and include only necessary-now work?

• `DESIGN GO` — matches. Proceed with one cohesive PR by default; a shallow stack needs a real review, integration or dependency benefit.
• `DESIGN GO — PLAN UPDATE: <what>` — routine detail or small drift (renamed module, moved interface, obsolete step). Update existing plan/prompt in the first implementation commit; for a small chat goal, state the refinement in chat, not synthetic files.
• `DESIGN NO-GO — REASON: <evidence>` — outcome/acceptance would change or an unauthorized/broken dependency prevents work. Stop that milestone and dependents for the owner's decision; independent milestones may continue.

Re-run the design check only when the milestone's inputs change, including a predecessor merge or authorized unmerged interface revision.

3. Implement

• Small milestone: implement in this session or one subagent.
• Large or parallel milestone: launch an independent headless session in its own worktree. Write the rendered prompt to `$WORKTREE/.milestone-prompt.md`, then run:

  claude -p --output-format stream-json --verbose --strict-mcp-config \
    --permission-mode bypassPermissions "$(cat "$WORKTREE/.mil