Moonshot Phase Runner

Execution modes:

• delegated-terminal: use the concrete autonomous loop backed by agent-loop.sh; prefer this when the user expects uninterrupted end-to-end execution
• in-session-coordinator: the current session coordinates the loop, but each attempt must run as a fresh fork/sub-agent round; treat this as an interactive thin-coordinator mode, not the default autonomous runtime

Execution start policy:

• default: auto-start execution immediately after preparation
• --prepare-only: stop after seeding state and return prepared execution metadata without executing it

Intent interpretation:

• Treat requests such as "continue", "proceed with the improvement work", "go ahead", "execute the phase", or equivalent user wording as execution intent, not packaging intent.
• Unless the user explicitly asks for planning/package-only behavior or passes --prepare-only, the runner must set prepareOnly: false and autoStartExecution: true.
• For Codex or other runtimes where uninterrupted completion is the goal, prefer delegated-terminal unless the user explicitly wants interactive coordination or the runtime can only satisfy the request through in-session-coordinator.

Plan-directory completion rule:

• In default auto-start runs, the execution boundary is the entire active plan directory, not the current phase.
• If any phase in phase-status.yaml remains pending, in_progress, or retryable failed, the run must keep going through the delegated-terminal loop or the in-session coordinator loop.
• A completed phase boundary is never a valid stop boundary by itself.

Channel / return-boundary rule:

• While phase-status.yaml reports activeExecutionStatus: active, user-facing updates must stay in progress/commentary form.
• Do not emit a final answer, closeout phrasing, or any wording that implies the run/session ended until assert-return-allowed passes or an explicit stop condition is recorded.
• A phase milestone, refreshed execution artifacts, or a just-started next phase is not a valid terminal-response boundary.

Review and finish gate rule:

• The phase package may not be treated as complete until the required review and finish-closeout steps have actually run.
• For code-changing phases, codex-review-code must appear in applied workflow evidence before clean_finish is allowed.
• QA_REPORT.md may not claim Next path: clean_finish while Review completed is still no.
• HANDOFF.md and closeout fields may not remain seeded or placeholder-shaped when the phase is being closed.
• If review or closeout evidence is missing, the run must stay inside the active plan-directory loop and remediate the missing steps instead of returning a summary.

Usage

# Auto-resolve an existing plan or create one at docs/implementation
/moonshot-phase-runner

# Specify plan directory
/moonshot-phase-runner docs/implementation/

# Autonomous mode (skip Q&A)
/moonshot-phase-runner docs/implementation/ --autonomous

# Keep coordination in the current session
/moonshot-phase-runner docs/implementation/ --execution-mode in-session-coordinator

# Prepare only, do not auto-start execution
/moonshot-phase-runner docs/implementation/ --prepare-only

Workflow

/moonshot-phase-runner [<plan-dir>] [--autonomous] [--execution-mode <mode>] [--prepare-only]
    │
    ├─ 1. Plan Directory Resolution
    │      ├─ Reuse explicit `<plan-dir>` when provided
    │      ├─ Else reuse existing active plan directory if exactly one safe candidate exists
    │      └─ Else run `moonshot-plan-writer` to create `docs/implementation`
    │
    ├─ 2. Plan Directory Validation
    │      └─ Verify master plan + phase docs exist
    │
    ├─ 3. Create/Update phase-status.yaml
    │      └─ Initialize each phase status
    │
    ├─ 4. Seed execution bridge artifacts
    │      └─ Prepare `execution/<phase>/SPRINT_CONTRACT.md`
    │         and placeholders for `QA_REPORT.md`, `HANDOFF.md`, `SCORECARD.md`
    │
    ├─ 5. Plan Review (unless --autonomous)
    │      └─ Detect uncertainties → Q&A → planConfirmed: true
    │
    ├─ 6. Resolve Execution Mode
    │      ├─ delegated-terminal -> build dispatcher command
    │      └─ in-session-coordinator -> build fresh-attempt command
    │
    ├─ 7. Auto-Start Execution Skill (default)
    │      └─ Execute `moonshot-phase-executor` in the current session
    │         unless `--prepare-only` was requested
    │
    ├─ 8. Enforce Review / Finish Gates
    │      └─ A phase may advance only after review evidence, completion evidence,
    │         and finish-closeout artifacts are consistent
    │
    └─ 9. Emit Handoff Summary
           └─ Orchestrator-readable phaseRunnerResult after the active plan directory is actually done

Step 1: Plan Directory Resolution

When <plan-dir> is omitted, resolve it in this order:

1. Reuse the active plan from .claude/docs/phase-status.yaml if it points to an existing master plan.
2. Reuse docs/implementation if it already contains exactly one valid master plan and phase files.
3. Reuse another single valid implementation-plan directory only if exactly one safe candidate exists.
4. Otherwise run /moonshot-plan-writer and create or refresh docs/implementation.

Archived phase docs under <plan-dir>/close/ are history, not active phase candidates.

Safety rule:

• If multiple candidate plan directories exist and there is no clear active one, stop and ask the user instead of guessing.

Resolution output:

planResolution:
  source: "phase-status"   # explicit | phase-status | discovered | plan-writer
  planDir: "docs/implementation"
  masterPlan: "docs/implementation/00-master-plan-v1.md"

Step 2: Plan Directory Validation