# Moonshot Phase Executor

> Skill-level phase execution adapter that routes prepared phase work to in-session coordinator execution, with delegated-terminal kept as legacy compatibility only.

- Skill: `munlucky/moonshot-phase-executor` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add munlucky/moonshot-phase-executor`
- Raw SKILL.md: https://api.skillmd.com/api/skills/munlucky/moonshot-phase-executor/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: munlucky (https://skillmd.com/u/munlucky)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/munlucky/moonshot-phase-executor

---


# Moonshot Phase Executor

## Role

Serve as the skill-first execution boundary after `moonshot-phase-runner`.
Users should not need to run command adapters directly. This skill consumes `phaseRunnerResult`, then routes execution to:
- `moonshot-in-session-coordinator` as the default active execution path
- `moonshot-phase-dispatch.mjs` / `agent-loop.mjs` only for explicit legacy/headless compatibility maintenance

This is an internal execution handoff, not a primary public workflow entrypoint.
Users should normally start from `moonshot-phase-runner`, not this skill.

## Legacy Adapter Policy

`delegated-terminal`, `moonshot-phase-dispatch.mjs`, `agent-loop.mjs`, and their shell wrappers are legacy adapters. They are not installed as part of the active runtime workflow payload and must not be selected automatically. Use them only when all of the following are true:
- the user or maintainer explicitly asks to validate or repair the legacy adapter path
- the local checkout has the legacy scripts available
- the run records `legacyAdapterReason`
- the result is treated as compatibility evidence, not the default phase-runner contract

## Inputs

```yaml
phaseRunnerResult:
  prepared: true
  executionMode: "in-session-coordinator" # delegated-terminal is legacy only
  planDir: "${MOONSHOT_RELAY_HOME:-~/.moonshot-relay}/state/projects/<projectId>/planning/packages/<plan-slug>"
  phaseStatusFile: ".moonshot-relay/docs/phase-status.yaml"
  executionRoot: "${MOONSHOT_RELAY_HOME:-~/.moonshot-relay}/state/projects/<projectId>/execution/.../plans/<plan-slug>/runs/<runId>/execution"
  worksetTemplate: "<MOONSHOT_RELAY_HOME>/templates/execution/WORKSET.template.md"
  executionRuntime: "auto"            # auto | claude | codex
  prepareOnly: false
  autoStartExecution: true
  legacyAdapterReason: ""             # required when executionMode == delegated-terminal
```

## Workflow

### 1. Respect prepare-only mode

If `prepareOnly == true`:
- do not execute anything
- surface the prepared status and optional adapter command

### 2. Route by execution mode

Before routing, confirm `phaseRunnerResult.projectKnowledgeContext` exists. If missing, run `knowledge-context-build.mjs --stage execute --json` from the current project root and pass only `projectKnowledgeContext.promptBlock` plus status-only metadata to the execution path.

If `executionMode == in-session-coordinator`:
- invoke `/moonshot-in-session-coordinator`
- pass through `phaseRunnerResult`
- when the active runtime cannot reliably keep spawning fresh attempts, stop with a concrete blocker or ask for a runtime change; do not silently fall back to delegated-terminal
- a current-session direct attempt is allowed only when `phaseRunnerResult.allowCurrentSessionAttempt == true`; record that downgrade in closeout evidence
- ensure each active slice can initialize `WORKSET.md` from `<MOONSHOT_RELAY_HOME>/templates/execution/WORKSET.template.md`
- do not stop after a completed phase while the active plan directory still has another actionable phase
- do not treat a review-pending or finish-pending slice as complete; record it as carry-forward evidence, keep the final completion gate closed, and continue the next independent phase when the phase plan still has actionable work
- if an independent review returns `REJECT`, record it as a worsened eval or blocking runtime event, then continue non-dependent phases instead of ending the whole run

If `executionMode == delegated-terminal`:
- require non-empty `legacyAdapterReason`
- confirm the local checkout has `moonshot-phase-dispatch.mjs` / `agent-loop.mjs`
- run it only as a legacy compatibility check or explicit maintainer repair path
- do not present the result as the default phase-runner execution contract

### 3. Runtime handling

- `executionRuntime == auto`
  - prefer Codex when available
  - otherwise use Claude
- `executionRuntime == claude`
  - run Claude-compatible path
- `executionRuntime == codex`
  - run Codex-compatible path

### 4. Result handling

Return summarized execution status only:

```yaml
phaseExecutionResult:
  started: true
  mode: "in-session-coordinator"
  runtime: "codex"
  status: "running"   # running | completed | failed | prepared_only
  nextBoundary: "moonshot-in-session-coordinator"
```

## Contract

- This skill is the internal phase execution handoff behind `moonshot-phase-runner`.
- Apply `docs/public/guidelines/memorygraph-workflow.md` before dispatching execution.
- Do not pass raw MemoryGraph/KG/ontology records to dispatcher/agent-loop/coordinator inputs; pass summarized `projectKnowledgeContext` only.
- Use one compact MemoryGraph/CodeReviewGraph recall per stage by default; repeat only for missing owner/date/path/API/schema/failure facts, then stop when answerable.
- Default `modelEffortProfile` is `standard`; `deep` and `max` require a concrete `Effort escalation reason` in QA and workflow evidence.
- Do not ask the user to choose a model. The provider-neutral model router selects per-stage runtime model/effort and records the selected provider/model/effort in execution evidence.
- Preserve assistant-item `phase` values when replaying assistant history (`commentary` for progress, `final_answer` only after completion); never add phase metadata to user messages.
- Legacy scripts are compatibility adapters only and must stay behind explicit maintainer intent.
- `moonshot-phase-runner` should auto-start this skill by default unless `prepareOnly == true`.
- Do not ask the user to manually run `moonshot-phase-dispatch.mjs` in the default path.
- Do not auto-select `delegated-terminal` as a fallback from the active path.
- `review pending`, `workflow-review-bundle-missing`, `finish-closeout-incomplete`, or placeholder closeout artifacts are not valid completion states, but they are carry-forward blockers rather than automatic whole-plan stop conditions while independent phases remain.
- The valid success boundary is plan-directory completion: every actionable phase completed or an explicit loop stop condition recorded.

## References

- `/moonshot-phase-runner`
- `/moonshot-in-session-coordinator`
- `archive/scripts/legacy-phase-adapters/agent-loop.mjs` as a legacy compatibility adapter
- `archive/scripts/legacy-phase-adapters/moonshot-phase-dispatch.mjs` as a legacy compatibility adapter
- `archive/scripts/legacy-phase-adapters/agent-loop.sh` / `archive/scripts/legacy-phase-adapters/moonshot-phase-dispatch.sh` as legacy wrappers
- `<MOONSHOT_RELAY_HOME>/templates/execution/WORKSET.template.md`

## Project Knowledge Context Contract

Before routing to in-session coordinator or forked-agent execution, confirm `phaseRunnerResult.projectKnowledgeContext` exists. If missing, run `knowledge-context-build.mjs --stage execute --json` and pass only `projectKnowledgeContext.promptBlock` and status-only metadata.

This executor must not bypass the context builder. Coordinator and attempt manifests may record only knowledge status metadata, never raw MemoryGraph/KG/ontology/log/transcript payloads. Legacy dispatcher/agent-loop runs must follow the same summary-only knowledge rule when explicitly used.