with one click
moonshot-orchestrator
// Use for bounded implementation work that already has enough context and does not need the phase harness.
// Use for bounded implementation work that already has enough context and does not need the phase harness.
[HINT] Download the complete skill directory including SKILL.md and all related files
| name | moonshot-orchestrator |
| description | Use for bounded implementation work that already has enough context and does not need the phase harness. |
Run PM analysis skills in sequence, resolve execution plane and workflow profile, then build the final agent chain.
This orchestrator is the build control plane.
Use it directly when:
{tasksRoot}/{feature-name}/product/Do not treat it as the primary entry point for raw idea shaping.
If the request is still in product-definition mode and no product package exists, redirect upstream to product-orchestrator.
If the work is large, long-running, or organized around phase documents, redirect upstream to moonshot-phase-runner.
/moonshot-orchestrator <user-request>
/moonshot-orchestrator <user-request> --use-teams
/moonshot-orchestrator <user-request> --use-teams=review-team
/moonshot-orchestrator <user-request> --use-teams --team-pattern=fanout-fanin
Available teams: review-team, research-team, verify-team, planning-team, quality-team, analysis-team, fix-team, impl-team, cross-layer-team, debug-team. Details in
moonshot-teams-runner/SKILL.md.
When team mode is enabled, prefer choosing a collaboration pattern first, then the concrete team preset.
moonshot-phase-runner.pre-flight-check when the direct skill may edit files.Automatically collected:
userMessage, gitBranch, gitStatus, recentCommits, openFilesResolve executionRuntime before orchestration:
claude-code: use Claude tool routing (Skill, Task, Plugin, Bash, AskUserQuestion).codex: execute the same chain with native tools while keeping the current Codex session as the coordinator boundary.
Task (fork) must preserve isolation by passing minimal input and merging summarized output only.codex-validate-plan (planning) and codex-review-code (post-implementation) outputs first.SPRINT_CONTRACT.md policy anchors rather than assuming chat memory survives across rounds.toolLookupEvidence; if lookup still fails, classify the result as mcp_unavailable, tool_unavailable, or runtime_unavailable instead of a generic harness or product failure.economy: parity smoke, narrow read-only checks, latency-sensitive workstandard: simple/local bounded workdeep: phase work, agentic coding, review, high-risk or user-visible changesmax: exceptional long-horizon or ambiguous hard problems only-m plus model_reasoning_effort; Claude Code receives --model plus --effort.commands/hooks are optional adapters and must only route to skills.When executionRuntime == codex, do not assume .claude/rules/** is preloaded.
Apply these rule files explicitly through the orchestrator and downstream artifact contracts:
.claude/rules/basic-principles.md.claude/rules/workflow.md.claude/rules/context-management.md.claude/rules/communication.md.claude/rules/output-format.mdFor meta_harness work, also apply:
.claude/rules/skills/skill-definition.md when touching .claude/skills/**.claude/rules/agents/agent-definition.md and .claude/rules/agents/agent-delegation.md when touching .claude/agents/**.claude/rules/docs/documentation.md when touching .claude/docs/**.claude/docs/guidelines/external-skill-pattern-transfer.md when adopting or comparing external skills/harnessesCRITICAL: Protect main session context from pollution.
analysisContext, never paste file contents.codex-review-code output.Initialize from the canonical contract:
.claude/schemas/analysis-context.schema.yamlResolve these fields before bundle selection:
request.userMessagesignals.executionPlanesignals.workflowProfilephasecomplexitydecisions.bundleChaindecisions.skillChainartifacts.tasksRootartifacts.executionRootworkflowEvidence.selectedBundlesworkflowEvidence.requiredSkillsworkflowEvidence.stageOrderworkflowEvidence.selectedHarnessComponentsworkflowEvidence.skippedHarnessComponentsworkflowEvidence.selectionReasonworkflowEvidence.runtimeIsolationworkflowEvidence.modelEffortProfileContract rules:
.claude/schemas/analysis-context.schema.yaml as the single source of truth for field layout and defaults.analysisContext to .claude/docs/moonshot-analysis.yaml.Follow .claude/docs/guidelines/document-memory-policy.md:
userMessage > 2000 words -> summarize to specification.md, archive originalsubtasks/subtask-NN/ with independent context.mdcontext.md under tokenBudget.contextMaxTokensSet signals.executionPlane before task classification:
read_only
product_project
meta_harness
.claude/skills, .claude/rules, .claude/agents, installer/distribution logic, or harness scriptssignals.allowIndeterminate to true.indeterminate), continue by recording pass_with_warning by default.allowIndeterminate=false), treat indeterminate as blocking.signals.workflowProfile to standard.strict if one of the following is true:
executionPlane == meta_harness and the task edits core workflow files.workflowProfile == strict:
signals.allowIndeterminate = false.design-approval-gate) for downstream product changes.workspace-isolation-gate).verification-evidence-gate).Run
project-memory-agentas fork subagent to prevent context pollution. Apply.claude/docs/guidelines/memorygraph-workflow.md; default mode is read-only and.claude/docs/ko/is excluded.
Task tool: project-memory-agent (subagent_type: general-purpose)
Input: { projectId, stage, changedFiles, taskType, userRequest, memoryMode: "read_only" }
Returns: projectMemoryContext -> merge into analysisContext.projectMemory
Run stage-scoped recalls before delegating work:
stage=intake: before classification/bundle selection.stage=plan: before requirements/context/plan validation tasks.stage=execute: before implementation delegation; pass summarized deltas only.stage=verify: before final verification.stage=finish: before handoff/logging.Do not merge MemoryGraph entries that duplicate system, developer, AGENTS.md, .claude/rules/**, or workflow hard rules; record them in projectMemory.omitted.duplicatedSystemRules.
Apply .claude/docs/guidelines/code-review-graph-workflow.md when code structure analysis can reduce broad file reads or review context.
Activate analysisContext.codeReviewGraph when:
signals.executionPlane is product_project or meta_harnessFor read_only, activate only when the user explicitly asks for code analysis, review context, impact radius, architecture overview, or similar structure analysis.
Stage behavior:
plan: before broad file reads, check graph status and use minimal context or architecture overview when available.execute: before implementation, use target/impact summaries to narrow files and dependencies.review: for changed files, use change detection, review context, and impact radius as the default review context source.verify: do not build a new graph; if CRG was used earlier, record evidence presence and stale/unavailable warnings only.finish: persist summary-only evidence and never store raw graph output.Failure policy:
codeReviewGraph.graphStatus=unavailable, add a short warning, and continue the workflow unless another gate fails.watch, crg-daemon start, and raw graph duplication into MemoryGraph.code-review-graph in workflowEvidence.selectedHarnessComponents.code-review-graph in workflowEvidence.skippedHarnessComponents with a concrete reason.Before normal build planning, detect whether upstream product-definition artifacts already exist.
Detection targets:
PRODUCT_INTENT.mdPRD.mdSOLUTION.mdSPEC.mdPLAN.mdtasks/*.mdMerge signals:
hasProductIntenthasPrdhasSolutionhasSpechasExecutionPlanproductPackageReadyimplementationReadyplanningReadyexecutionReadyRouting rule:
productDefinitionRequest == true and productPackageReady == false, hand off to product-orchestratorproductPackageReady == true, skip upstream planning stages and use the handoff package as the implementation baselinereadiness.planningReady as the canonical "package is routable" signalreadiness.executionReady as the canonical "active slice may execute now" signalWhen signals.useAgentTeams == true, resolve the collaboration pattern before selecting a concrete team preset.
Pattern-first routing order:
fanout-faninproducer-reviewersupervisorhierarchical-delegationpipeline.claude/templates/agent-teams-config.yamlteamSelectionDefault mapping:
fanout-faninproducer-reviewersupervisorhierarchical-delegationpipeline for future sequential stage teams; do not force-fit an existing parallel team into this patternFor product_project work, treat execution artifacts as first-class state:
SPRINT_CONTRACT.md defines the current slice goal, non-goals, done checks, and evaluator focusSPRINT_CONTRACT.md records contract review, selected harness components, runtime isolation, and model effort profile before implementation beginsQA_REPORT.md records verifier findings and feeds the next remediation roundHANDOFF.md captures resumable state when the run is interrupted, retried, or context pressure is highSCORECARD.md is the objective completion scoreboard for the active slicegeneric, saas, api-backend, frontend, or platformREQUIREMENTS_TRACEABILITY.md and SCENARIO_MATRIX.md exist, rebalance only the combined REQ + SCN score budget from detected REQ-* / SCN-* counts; keep VER / CLOSE at the preset baselinePolicy:
meta_harness phase work must keep policy anchors and required verification commands current in the active sprint contractQA_REPORT.md whenever they runSCORECARD.md with objective checklist status, current score, unmet items, and verdictsignals.handoffRequired = trueworkflowEvidence current in .claude/docs/moonshot-analysis.yamlworkflowEvidence must include selectedBundles, requiredSkills, and stageOrderworkflowEvidence must include selectedHarnessComponents, skippedHarnessComponents, selectionReason, runtimeIsolation, and modelEffortProfilecode-review-graph as selected or skipped according to .claude/docs/guidelines/code-review-graph-workflow.mdcodex-review-code evidence before final verification is treated as stablecode-simplifier was applied or explicitly skipped with a reasondoc-auto-sync evidence before completion is claimedsession-logger evidence before completion is claimedfailure-analyzer; use session-logger only when session/handoff logging is already required or solution promotion is justifiedFor product_project work, treat these project docs as first-class references when present:
workflow/README.mddocs/design/README.mddocs/glossary/README.mddocs/daily/README.mdTEST_GUIDE.mddocs/analysis/README.md and relevant docs/analysis/*.mdPolicy:
pre-flight-check and prefer project-md-refreshRun /moonshot-classify-task -> merge patch (taskType, keywords, signals)
Run /moonshot-evaluate-complexity -> merge patch (complexity, estimates)
Run pre-flight-check when the task may edit files.
signals.projectContractReadysignals.contextReadysignals.verificationContractReadysignals.executionPlane when the initial heuristic was weaksignals.shouldEscalateStrictRun /moonshot-detect-uncertainty -> merge patch (missingInfo)
If missingInfo is not empty:
analysisContext.If implementation evidence, review findings, or verification output shows the selected plan is invalid:
analysisContext.notes and QA_REPORT.md when presentRun /moonshot-decide-sequence -> merge patch (phase, bundleChain, skillChain, parallelGroups)
Normalize the selected chain against the repo stage model:
read_only:
product_project, simple:
plan -> ready/isolate -> execute -> review -> verify -> finish/handoffproduct_project, medium/complex:
plan -> ready/isolate -> execute -> review -> verify -> finish/handoffmoonshot-phase-runner, then preserve the same downstream stage order inside each phaseNever collapse review -> verify -> finish into a single undifferentiated closeout step when code changed meaningfully.
Run decisions.skillChain in order.
Allowed steps:
| Step | Type | Notes |
|---|---|---|
pre-flight-check | Skill | emits readiness signals |
teach-impeccable | Skill | design-context bootstrap for UI work |
frontend-design | Skill | visual direction and anti-pattern guard for UI implementation |
audit | Skill (fork) | review-only UI quality audit |
normalize | Skill | align UI work to existing design system |
polish | Skill | final UI finishing pass |
product-orchestrator | Skill | upstream redirect only |
project-contract-gate | Skill | downstream bootstrap gate |
context-readiness-gate | Skill | downstream task-context gate |
verification-contract-gate | Skill | downstream verification gate |
project-memory-agent | Task (fork) | context isolation |
project-memory-check | Task (fork) | pre-implementation boundary check |
requirements-analyzer | Task | |
context-builder | Task | |
codex-validate-plan | Skill | |
design-approval-gate | Skill | strict profile design approval gate |
workspace-isolation-gate | Skill | strict profile branch/workspace isolation gate |
karpathy-execution-gate | Skill | pre-implementation discipline gate |
implementation-runner | Task | |
code-simplifier | Skill | post-implementation simplification pass |
completion-verifier | Skill (fork) | contract-aware verification |
verification-evidence-gate | Skill | strict profile evidence-before-completion gate |
doc-auto-sync | Skill | auto-docs update & bootstrap |
codex-review-code | Skill (fork) | |
project-memory-reviewer | Task (fork) | context isolation |
vercel-react-best-practices | Skill | when reactProject=true |
security-reviewer | Skill (fork) | |
build-error-resolver | Skill | |
browser-verifier | Skill (fork) | runtime check for web projects |
web-design-guidelines | Skill (fork) | guideline-based UI review |
verify-runtime.sh | Bash | runtime URL/E2E verifier |
verify-changes.sh | Bash | verdict-emitting project verifier |
efficiency-tracker | Archived deprecated skill | Historical reporting only; not loaded in default chains |
session-logger | Skill | |
moonshot-phase-runner | Skill | |
moonshot-phase-executor | Skill | |
moonshot-in-session-coordinator | Skill | |
moonshot-teams-runner | Skill | |
team-leader-agent | Task (fork) | teams coordination |
failure-analyzer | Skill (fork) | system failure analysis |
workflow-self-improver | Archived deprecated skill | Historical workflow reflection only; not loaded in default chains |
commit-moonshot | Skill |
Agent mapping:
| Agent | subagent_type | Notes |
|---|---|---|
project-memory-agent | general-purpose | fork, before 2.1 |
project-memory-check | general-purpose | fork, check-only mode before implementation (.claude/agents/project-memory-check.md) |
requirements-analyzer | general-purpose | |
context-builder | context-builder | |
implementation-runner | implementation-agent | |
phase-attempt-agent | general-purpose | fork, single phase attempt via coordinator |
project-memory-reviewer | general-purpose | fork, after codex-review-code |
team-leader-agent | general-purpose | fork, --use-teams |
Execution rules:
parallelGroups)claude-code: Skill → Skill tool, Agent → Task tool, Plugin → Plugin tool, Script → Bash toolcodex: run equivalent logic in-session with native tools/shell while preserving step contractsTask (fork) semantics and read-only review/verification skills with context: fork, keep context isolation (minimal input, summarized return only) in both runtimesdocument-memory-policy.mdproduct-orchestrator is selected, treat it as a redirect/handoff boundary and do not continue the build chain in the same pass unless a product package is returnedsignals.phaseLoopInSession == true, keep the main session as a thin coordinator and do not perform direct multi-round implementation work in that session.Execution bridge contract:
implementation-runner in medium/complex product_project work, materialize artifacts.sprintContractPathimplementation-runner in medium/complex product_project work, materialize artifacts.scorecardPathimplementation-runner must treat SPRINT_CONTRACT.md as the round-level source of truth for code editsimplementation-runner and subsequent remediation rounds must keep SCORECARD.md currentcompletion-verifier, verify-runtime.sh, and verify-changes.sh should update artifacts.qaReportPathverify-changes.sh score output is the preferred completion score source when availabledoc-auto-sync must run before completion is claimedartifacts.handoffPathReview cadence contract:
Finish / handoff contract:
finish-bundle is entered only after the active review/verify verdict is stabledonedoc-auto-syncsession-logger when resumable state or decision history mattersblocked, interrupted, context_limit, user_pause, or deferred_verificationQA_REPORT.mdHANDOFF.mdcommit-moonshot when the user asked for memory update plus commitPhase-runner execution-mode contract:
moonshot-phase-runner returns phaseRunnerResult.prepareOnly == true, stop after surfacing prepared execution metadata.moonshot-phase-runner returns phaseRunnerResult.autoStartExecution == true, execute phaseRunnerResult.executionSkill immediately and pass through phaseRunnerResult.phaseRunnerResult.executionMode == delegated-terminal, the execution path must launch phaseRunnerResult.executionCommand and remain attached to the dispatcher/agent loop until that loop exits.pending, in_progress, or retryable failed phases.phase-run-lease attached to the run and require assert-return-allowed to pass before any success summary can escape the dispatcher boundary.moonshot-phase-runner returns phaseRunnerResult.executionMode == in-session-coordinator:
signals.phaseLoopInSession = truemoonshot-in-session-coordinator as the phase execution boundaryphaseDoc, SPRINT_CONTRACT.md, latest QA_REPORT.md, optional HANDOFF.md)attemptResult onlyattemptResult.status == completed as valid only when the underlying verifier state is passed, evidenceFresh == true, and required checks are completeMemory-step separation contract:
project-memory-agent: read-only MemoryGraph recall at each stage boundary; write only when memoryMode: write_requestedproject-memory-check: pre-implementation boundary check (check-only, no memory mutation, use .claude/agents/project-memory-check.md)project-memory-reviewer: post-review boundary compliance verificationAgent Teams Integration (--use-teams):
signals.useAgentTeams = trueteamSelection.selectedPattern before choosing teamSelection.selectedTeamteam-leader-agent with the selected team config (see moonshot-teams-runner/SKILL.md for team details)teamReport into analysisContext.notesselectedPattern, selectedTeam, and selectionReason in notes or workflow evidenceselectedHarnessComponents, skippedHarnessComponents, runtimeIsolation, and modelEffortProfile in the same evidence block[!CAUTION] Agent Teams: ~13K tokens (2-member) / ~20K tokens (3-member). Use for critical reviews or complex implementations only.
Fork-based agents (project-memory-agent, project-memory-check, project-memory-reviewer, team-leader-agent):
| Signal | Trigger | Action |
|---|---|---|
projectContractReady=false | executionPlane == product_project | Insert project-contract-gate before planning |
contextReady=false | executionPlane == product_project | Insert context-readiness-gate before implementation |
verificationContractReady=false | executionPlane == product_project | Insert verification-contract-gate before verification |
executionBridgeNeeded | executionPlane == product_project && complexity != simple | Ensure session-logger is present and require SPRINT_CONTRACT.md before first code edit |
implementationComplete=true | meaningful file edits detected | Ensure doc-auto-sync is present after verification and before completion |
buildFailed | verify-changes.sh exit 1 | Insert build-error-resolver, retry (max 2) |
testFailed | verify-changes.sh exit 2 | Re-enter implementation-runner with test-first remediation, then rerun verification |
runtimeUnavailable | verify-runtime.sh exit 1 | Request server/runtime readiness fix, rerun browser-verifier (max 1) |
e2eFailed | verify-runtime.sh exit 2 | Apply same policy as testFailed |
browserFlowFailed | verify-runtime.sh exit 3 | Re-enter runtime/browser remediation path, then rerun browser-verifier |
reviewRequired | meaningful code changes or medium+ complexity | Insert codex-review-code before final verification |
codeAnalysisNeeded | code work needs broad file reads, impact analysis, architecture overview, or review context reduction | Apply the Code Review Graph stage gate and record selected/skipped component evidence |
verificationFailed | completion-verifier or runtime verifier fails | Update QA_REPORT.md, re-enter implementation with contract-linked findings |
planInvalidated | review, runtime evidence, or implementation findings contradict the selected plan | Stop the current tactic, update notes/QA evidence, and re-enter uncertainty handling plus sequence decision |
finishRequired | meaningful file edits with stable verifier state | Insert doc-auto-sync and session-logger before final completion statement |
docStale | pre-flight-check detects stale doc | Insert doc-auto-sync at start of chain, but still keep final doc-ops after implementation |
securityConcern | changed files contain .env/auth/token/secret | Add security-reviewer after codex-review-code |
coverageLow | completion-verifier: coverage < 80% | Log warning, request additional tests |
contractReviewMissing | medium/complex/phase work has no evaluator contract review | Update SPRINT_CONTRACT.md and QA_REPORT.md; do not start implementation as a clean standard path |
criticalScenarioSmokeOnly | critical SCN-* has only smoke/page-load evidence | Warn or retry; block clean finish until open -> act -> mutate -> persist -> recover evidence exists |
repeatedFailureClass | same failure class appears twice | Choose partial_redesign or stop_and_handoff; continuing the same tactic requires explicit evidence |
reactProject | .tsx/.jsx files or React keywords | Insert frontend-design before implementation-runner |
reactProject | .tsx/.jsx files or React keywords | Insert vercel-react-best-practices after codex-review-code |
implementationComplete | implementation-runner completed with meaningful code changes | Insert code-simplifier before completion-verifier |
docStale | pre-flight-check detects stale doc | Insert doc-auto-sync at start of chain |
phasePlanDetected | master plan + phase docs found | Insert moonshot-phase-runner before implementation-runner |
phaseAutoStart | phaseRunnerResult.autoStartExecution == true | Execute phaseRunnerResult.executionSkill immediately with phaseRunnerResult as input |
phaseLoopInSession | phaseRunnerResult.executionMode == in-session-coordinator | Insert moonshot-in-session-coordinator and keep each round in a fresh fork/sub-agent attempt |
handoffRequired | retry loop, interruption, or context budget warning | Update HANDOFF.md through session-logger before pausing |
strictProfile | workflowProfile == strict and no evidence step | Insert verification-evidence-gate after completion-verifier or verify-changes.sh |
multipleFailures | notes contain > 2 errors/failures | Append failure-analyzer; escalate to replan when the same failure class repeats |
userCorrection | user correction reveals a repeatable workflow or quality mistake | Append failure-analyzer; use session-logger only for active session/handoff logging or solution promotion |
read_only
product_project
meta_harness
After implementation-runner:
completion-verifier exists in decisions.skillChain, call it.completion-verifier is absent (simple flow), use verify-changes.sh (and browser-verifier for web projects) as completion gate.completionStatus.verificationState == passedcompletionStatus.evidenceFresh == true when a contract-backed verdict is expectedcompletionStatus.requiredChecks.missing is empty when required checks applycompletionStatus.verificationState == indeterminate:
pass_with_warningcompletionStatus.verificationState == passed but fresh evidence is missing or required checks are incomplete:
verificationFailed, update QA_REPORT.md, and re-enter remediation/retry flowartifacts.qaReportPath with verdict, failed criteria, and next-round input.verification-evidence-gate before any completion statement.artifacts.handoffPath.| Verifier state | Transition |
|---|---|
passed + fresh evidence + required checks complete | eligible for completion |
passed without fresh evidence or with missing required checks | reclassify to remediation/retry; no completion claim |
indeterminate | strict=failed, standard=pass_with_warning |
failed | retry or fail |
Save final analysisContext to .claude/docs/moonshot-analysis.yaml.
When the run is bounded-direct and edits code, keep QA_REPORT.md workflow evidence current, then record the boundary through bash .claude/scripts/workflow-enforcement.sh record-bounded --analysis-path .claude/docs/moonshot-analysis.yaml.
record-bounded normalizes workflowEvidence in the analysis file, fills canonical bundles/required skills/stage order, and syncs applied/skipped evidence from QA_REPORT.md when that artifact is provided.
AskUserQuestion on Claude runtime; on Codex runtime, prioritize codex-validate-plan/codex-review-code outputs and ask user only for unresolved blockersproduct-orchestrator instead of inventing product artifacts inside the build chainPLAN.md + tasks/*.md exist, treat them as the planning source of truth and skip requirements-analyzer / context-builderproduct_project work must keep SPRINT_CONTRACT -> QA_REPORT -> HANDOFF artifacts synchronized with the active sliceHANDOFF.md remains the human resume artifact, not the only machine-readable state.moonshot-orchestrator, set signals.phaseAttemptMode = true and skip recursive moonshot-phase-runner insertiondocument-memory-policy.md