moonspec-orchestrate

name	moonspec-orchestrate
description	Orchestrate the full MoonSpec lifecycle from a preselected single-story feature request or active feature directory through specification, planning, TDD task generation, artifact alignment, implementation, and final verification. Use when the user asks for an end-to-end MoonSpec run and the input has already been routed to one independently testable story, or when Codex needs to coordinate `moonspec-specify`, `moonspec-plan`, `moonspec-tasks`, `moonspec-align`, `moonspec-implement`, and `moonspec-verify` without manual analyze/remediation prompts.
metadata	{"required-capabilities":["git"]}

MoonSpec Orchestrate

Use this skill to coordinate the MoonSpec workflow end to end.

Scope

Orchestrate downstream MoonSpec skills instead of reimplementing their detailed workflows:

• moonspec-specify: create one-story specs from a single feature request.
• moonspec-assess: assess source acceptance evidence into a bounded backlog.
• moonspec-plan: create implementation planning artifacts.
• moonspec-tasks: create a TDD-first executable task breakdown.
• moonspec-align: analyze and remediate artifact drift before implementation.
• moonspec-implement: implement the task breakdown with TDD.
• moonspec-verify: perform final read-only verification.
• moonspec-doc-reconcile: update the owning canonical document when verified discoveries show it is impossible, unclear, or inconsistent, or escalate instead of editing.

MoonSpec skill IDs and command IDs use moonspec-* and /moonspec.*.

Inputs

• Required: a preselected single-story feature request or active feature directory.
• Optional: implementation constraints, testing constraints, scope boundaries, source design paths, target story, or verification focus.
• If no request or active feature context is available, ask once for the missing input before starting.
• Inputs that still need story splitting are out of scope for this skill. Route them through a higher-level workflow such as moonspec-breakdown before starting MoonSpec Orchestrate.

Default intent is runtime: production code plus tests must be delivered. Use docs intent only when the user explicitly asks for documentation-only work.

Core Rules

• MoonSpec uses one independently testable story per spec.md.
• Before starting downstream stages, validate that the input is already exactly one independently testable story or an active feature directory with an existing one-story spec.md.
• If the input is a broad design, names multiple stories/features, asks to split or implement all stories, or otherwise cannot be bounded to one independently testable story without selection, stop immediately and report that a higher-level workflow must route it through moonspec-breakdown or another upstream selector first.
• Single-story requests go through moonspec-specify.
• Run moonspec-assess after moonspec-specify when source acceptance evidence exists. Preserve the original source acceptance matrix, the bounded backlog, and any note that a single story may span multiple implementation surfaces.
• TDD is the default strategy.
• Unit tests and integration tests are both expected.
• The original request or source design preserved in spec.md **Input** is the final alignment source, interpreted against the canonical source document per docs/Workflows/MoonSpecDocumentModel.md. When a derived artifact conflicts with its canonical source document, the canonical document wins unless verified evidence shows the document itself is impossible, unclear, or inconsistent — then the conflict goes to doc reconciliation, never silent override.
• moonspec-align replaces the old multi-step analyze remediation sequence.
• Do not synthesize user approvals, scripted user responses, or pretend an analyze report exists.
• Resume from existing artifacts when they pass gates; do not regenerate by default.
• Preserve unrelated user changes in the worktree.

Resume Model

Before running a stage, inspect the active feature state:

• spec.md
• plan.md
• research.md
• data-model.md
• contracts/
• quickstart.md
• tasks.md
• relevant production code and tests
• previous verification report when available in the conversation

Resume from the first incomplete stage. If artifacts are inconsistent, use moonspec-align when spec.md, plan.md, and tasks.md exist; otherwise stop and report the missing artifact that prevents safe alignment.

Do not overwrite later-stage artifacts unless:

• the user requested regeneration, or
• moonspec-align determines conservative artifact edits are required, or
• an upstream artifact changed and downstream artifacts must be regenerated to remain coherent.

Artifact Gates

Use these gates before advancing:

• Specify gate:
  • spec.md exists.
  • It contains exactly one user story.
  • The original request or source design is preserved in **Input**.
  • Requirements are testable and contain no unresolved story-critical clarification.
• Plan gate:
  • plan.md exists.
  • research.md and quickstart.md exist.
  • data-model.md exists when the story involves data.
  • contracts/ exists when the story exposes an API, CLI, UI contract, event, parser, library surface, or external interface.
  • Unit and integration test strategies are identified.
• Tasks gate:
  • tasks.md exists.
  • It covers exactly one story.
  • It includes unit test tasks, integration test tasks, red-first confirmation tasks, implementation tasks, story validation, and final /moonspec.verify.
  • Source design or original request mappings have task coverage.
• Align gate:
  • moonspec-align has run after tasks.md generation unless the user explicitly skipped alignment.
  • Any artifact changes from alignment have been validated or propagated.
• Implement gate:
  • Required implementation work is done.
  • Completed tasks are marked [X].
  • Unit and integration tests have been run or blocked with exact reasons.
• Verify gate:
  • moonspec-verify produced a concrete report for the active spec.md.
  • Verdict is not NO_DETERMINATION or BLOCKED.
  • Completion is claimed only when verdict is FULLY_IMPLEMENTED.
• Doc Reconcile gate:
  • moonspec-doc-reconcile has run after a FULLY_IMPLEMENTED verdict when at least one canonical source candidate exists: spec.md records a canonical source document, the breakdown sourceReference.path points under docs/, or the orchestration step provides a source design path under docs/.
  • An escalate-only invocation triggered by documentation-type verification gaps is also valid; it must produce escalated or no_update_required without document edits.
  • Its result is exactly one of updated, no_update_required, or escalated, with rationale.

If a gate fails, stop or run the appropriate upstream skill. Do not continue on a claimed success without artifacts or evidence.

Workflow

1. Create Or Select Spec

Use the provided input as a preselected single-story request or active feature directory:

1. Validate the single-story precondition before running moonspec-specify.
2. Stop immediately if the input still needs story splitting or upstream story selection.
3. Run moonspec-specify if spec.md does not already exist.
4. Verify the specify gate.
5. Do not run moonspec-breakdown or create more than one spec from this workflow.

2. Plan

For the selected spec:

1. Run moonspec-plan if the plan gate is incomplete.
2. Verify generated artifacts.
3. Stop if planning requires unresolved user input.

3. Generate Tasks

1. Run moonspec-tasks if the tasks gate is incomplete or upstream artifacts changed.
2. Verify tasks.md format, single-story focus, TDD order, unit/integration coverage, source traceability, and final /moonspec.verify.

4. Align Artifacts

1. Run moonspec-align after task generation.
2. Let moonspec-align make conservative artifact edits without asking for follow-up responses.
3. If moonspec-align changes spec.md, plan.md, design artifacts, or tasks.md, re-check downstream gates.
4. Regenerate only the downstream artifact that is now stale; do not restart the full pipeline automatically.

This replaces the old manual analyze remediation flow. Do not provide scripted "yes", "continue", or other user responses to get through analyze limitations.

5. Implement

1. Run moonspec-implement when implementation work remains.
2. Require TDD execution: unit tests and integration tests are written and confirmed failing before production code.
3. Require completed work to be marked [X] in tasks.md.
4. Preserve story scope; do not add hidden scope to make verification easier.

6. Verify

1. Run moonspec-verify as the final gate unless an up-to-date verification report already covers the current code and artifacts.
2. If verdict is FULLY_IMPLEMENTED, report success.
3. If verdict is ADDITIONAL_WORK_NEEDED, use the verification report as the remaining-work list:
   • run moonspec-implement for bounded code or test gaps,
   • rerun targeted unit/integration validation,
   • rerun moonspec-verify.
4. If the remaining work is dominated by documentation-type gaps — the canonical document, not the code, blocks completion, for example because it demands something that cannot be satisfied as written — do not spend remediation cycles on it: run moonspec-doc-reconcile in escalate-only mode so the document problem becomes a tracked escalation, then stop and report that outcome.
5. Run at most two verification-remediation cycles unless the user explicitly asks to keep going.
6. If verdict is NO_DETERMINATION, stop and report the exact missing evidence, commands, or context.
7. If verdict is BLOCKED, stop and report the environment diagnostic and minimum repair; do not count it as a remediation cycle.

7. Reconcile Declarative Docs

Run only when the final verdict is FULLY_IMPLEMENTED and at least one canonical source candidate exists: spec.md records a canonical source document, the breakdown sourceReference.path points under docs/, or the orchestration step provides a source design path under docs/. (The escalate-only invocation from the Verify stage is the one exception; it never edits documents.)

1. Run moonspec-doc-reconcile with the canonical document path(s), the latest verification report (including its Source Document Drift section), and artifacts/doc-discoveries/<feature>.json when present.
2. Accept exactly one outcome: updated (canonical doc edited), no_update_required (gate not met), or escalated (a tracker issue when integration exists, otherwise a full escalation record in the structured output and report).
3. escalated does not retroactively fail verification; report the issue key or escalation record alongside the outcome.
4. Skip this stage with outcome no_update_required when no canonical source candidate exists.

Multi-Spec Designs

Multi-spec orchestration is out of scope for this skill. A higher-level workflow must split, order, and select stories before invoking MoonSpec Orchestrate for each individual story.

Commit And PR Behavior

Do not create commits or pull requests unless the user explicitly asks or the current orchestration environment requires that output.

If commit or PR creation is requested but cannot complete because of missing authentication, remote configuration, branch state, or permissions, report the exact blocker and the minimum manual command needed.

Final Report

Return a concise report:

## MoonSpec Orchestration

Feature:
- [active spec path]

Stages:
- Specify: PASS/FAIL/SKIPPED
- Plan: PASS/FAIL/SKIPPED
- Tasks: PASS/FAIL/SKIPPED
- Align: PASS/FAIL/SKIPPED
- Implement: PASS/FAIL/SKIPPED
- Verify: FULLY_IMPLEMENTED/ADDITIONAL_WORK_NEEDED/NO_DETERMINATION/BLOCKED/SKIPPED
- Doc Reconcile: updated/no_update_required/escalated/SKIPPED

Changed files:
- [paths]

Tests:
- [command]: [PASS/FAIL/NOT RUN]

Remaining risks:
- [risk or "None"]

Next action:
- [only if work remains]

Mention source design coverage and DOC-REQ-*/DESIGN-REQ-* status when present.

Key Rules

• Use moonspec-* skills for downstream work.
• Use moonspec-align, not the old analyze prompt workaround.
• Do not invent user approvals or fake intermediate outputs.
• Do not run moonspec-breakdown or perform story routing from inside this workflow.
• Enforce one story per spec.
• Keep TDD, unit tests, integration tests, and /moonspec.verify in the pipeline.
• Treat verification as the final authority for completion.
• Run doc reconciliation after a FULLY_IMPLEMENTED verdict when a canonical source candidate exists; use escalate-only mode when documentation-type gaps block verification. Never let derived artifacts silently override canonical docs.