moonspec-plan

name	moonspec-plan
description	Generate a MoonSpec implementation plan and design artifacts from a single-story spec. Use when the user asks to run or reproduce `/moonspec.plan`, create or update `plan.md`, produce `research.md`, `data-model.md`, `contracts/`, or `quickstart.md`, evaluate repo principles, define separate unit and integration test strategies, and perform repo-aware gap analysis before `/moonspec.tasks`.
metadata	{"required-capabilities":["git"]}

MoonSpec Plan

Use this skill after a feature spec exists and the user wants implementation planning artifacts for exactly one independently testable story.

When To Use

Use this skill when the user wants to:

• Run or reproduce /moonspec.plan.
• Create or update a feature plan.md.
• Generate research.md, data-model.md, contracts/, or quickstart.md.
• Resolve technical unknowns before task generation.
• Define unit and integration testing strategy for a single-story MoonSpec.
• Determine, from the current repo, whether each in-scope requirement needs code changes, tests only, or no new work.

Do not use this skill to create a spec from a request. Use moonspec-specify or moonspec-breakdown first.

Inputs

• Treat the user's text as optional planning guidance.
• Work from the active feature directory resolved by the setup script.
• The feature spec must contain exactly one independently testable user story.
• If the spec is missing, contains multiple user stories, or has unresolved story-critical clarifications after research, stop with an error.
• Use absolute paths in reports.
• Treat spec.md as the desired behavior contract. Do not remove a requirement from the story because similar behavior already exists in the codebase.
• plan.md and its design artifacts are imperative, temporary execution artifacts (see docs/Workflows/MoonSpecDocumentModel.md). Never copy their content into canonical docs/ files.

Pre-Plan Hooks

Before setup, check for extension hooks:

1. If .specify/extensions.yml exists, read it and look for hooks.before_plan.
2. If the YAML cannot be parsed or is invalid, skip hook checking silently.
3. Ignore hooks where enabled is explicitly false; hooks without enabled are enabled.
4. Do not evaluate non-empty condition expressions. Treat hooks with no condition, null condition, or empty condition as executable. Skip hooks with non-empty conditions.
5. For each executable hook:
   • Optional hook (optional: true): print

## Extension Hooks

**Optional Pre-Hook**: {extension}
Command: `/{command}`
Description: {description}

Prompt: {prompt}
To execute: `/{command}`

• Mandatory hook (optional: false): print

## Extension Hooks

**Automatic Pre-Hook**: {extension}
Executing: `/{command}`
EXECUTE_COMMAND: {command}

Wait for the result of the hook command before proceeding to the Outline.

If no hooks are registered or .specify/extensions.yml does not exist, skip silently.

Setup

Run the setup script from the repository root and parse its JSON output:

.specify/scripts/bash/setup-plan.sh --json

Parse:

• FEATURE_SPEC
• IMPL_PLAN
• SPECS_DIR
• BRANCH
• HAS_GIT

The setup script creates the feature directory when needed and copies templates/plan-template.md to IMPL_PLAN.

For shell arguments containing single quotes, use shell-safe escaping such as 'I'\''m Groot', or double quotes when possible.

Load Context

Read:

• FEATURE_SPEC
• artifacts/moonspec/source-acceptance.json and artifacts/moonspec/acceptance-assessment.json when present and their featureId matches the active feature. Treat VERIFIED source acceptance rows as regression constraints and use the matching assessment backlog for planned work.
• AGENTS.md when present, especially project principles, testing discipline, and repo constraints
• IMPL_PLAN
• Relevant implementation files, tests, contracts, fixtures, migrations, and public interfaces for the story

Validate before planning:

• FEATURE_SPEC has exactly one ## User Story - ... section.
• The story has a Summary, Goal, Independent Test, Acceptance Scenarios, Requirements, and Success Criteria.
• Source design mappings such as DESIGN-REQ-* are preserved when present.
• Source packet provenance is preserved when present: source document path, document class, viewpoint, owning surface, stable claim IDs, temporary-adapter role, and issue traceability such as MM-933 / MM-927.
• Relevant AGENTS.md principles, testing discipline, and MUST constraints are reflected in the plan when present.
• In-scope requirement IDs and scenario IDs can be identified for planning and traceability.

Fill plan.md

Follow templates/plan-template.md structure and preserve its headings.

Fill:

• Branch, Date, and Spec
• Input as the single-story spec path
• Summary: primary requirement, technical approach, test strategy, and repo gap-analysis outcome
• Technical Context:
  • Language/version
  • Primary dependencies
  • Storage
  • Unit testing tool
  • Integration testing tool
  • Target platform
  • Project type
  • Performance goals
  • Constraints
  • Scale/scope
• Principles Check: derive relevant checks from AGENTS.md project principles, testing discipline, and repo constraints when present
• Project Structure: replace placeholder trees with the actual repository layout for the feature
• Complexity Tracking: fill only when principle conflicts or unjustified complexity must be justified

Add a ## Requirement Status section after ## Summary with one row per in-scope item that materially affects delivery:

• stable source claim IDs from ## Source Packet, such as CLAIM-*, DESIGN-REQ-*, or DOC-REQ-*
• FR-*
• acceptance scenarios or SCN-*
• measurable success criteria or SC-* when they drive implementation or testing
• in-scope DESIGN-REQ-* or DOC-REQ-*

Use this table shape:

ID	Status	Evidence	Planned Work	Required Tests
FR-001	missing	none found	add code and tests	unit + integration
SCN-001	implemented_unverified	src/..., no scenario test	add verification tests first, with implementation contingency if they fail	integration
DESIGN-REQ-004	implemented_verified	src/..., tests/...	no new implementation	none beyond final verify

When a row originates from a stable source claim, include the claim ID in the ID cell or in the evidence text so /moonspec.tasks can map every implementation task back to stable claim provenance. If no stable source claim applies, write No stable source claim applies: <reason> in the evidence text.

Allowed Status values:

• missing: no adequate implementation evidence found
• partial: some implementation exists, but the requirement is not fully satisfied
• implemented_unverified: behavior appears present, but required proof is missing or insufficient
• implemented_verified: behavior is already present and sufficiently covered by existing tests or other evidence

Rules:

• Existing code changes planned work, not story scope.
• Prefer implemented_unverified over implemented_verified unless current evidence is strong.
• Do not mark implemented_verified unless the current code and current tests together satisfy the requirement and its acceptance evidence.
• When uncertain, do not use implemented_verified.

Mark technical unknowns as NEEDS CLARIFICATION only when they block defensible planning and cannot be resolved from the repo, spec, or conventional project patterns.

Principles Check

Evaluate relevant AGENTS.md principles, testing discipline, and repo constraints before Phase 0 research.

Rules:

• Error on unjustified principle conflicts.
• Record justified conflicts in Complexity Tracking with the reason and mitigation.
• Do not continue with unresolved hard gate failures.
• Re-check relevant principles after Phase 1 design artifacts are generated.

Phase 0: Research And Repo Gap Analysis

Generate research.md in SPECS_DIR.

Research and resolve:

• Every NEEDS CLARIFICATION from Technical Context
• Dependency choices and best practices
• Integration patterns
• Test tooling choices, with unit and integration test tools identified separately
• Any source design or repo-principle constraint that affects architecture
• Current repo coverage for each in-scope requirement or scenario

For each in-scope item, inspect relevant code and tests, then classify it:

• missing -> requires tests and implementation
• partial -> requires tests and implementation changes
• implemented_unverified -> requires tests or verification first, plus an explicit implementation contingency to execute if verification exposes a gap
• implemented_verified -> requires no new implementation work, but must remain traceable in the plan and final verification

Use this format for each topic in research.md:

## [Topic or Requirement ID]

Decision: [choice, status, and/or planned work]
Evidence: [relevant file paths, tests, or contracts]
Rationale: [why this choice or status was chosen]
Alternatives considered: [what else was evaluated]
Test implications: [unit, integration, both, or none beyond final verify]

After research.md is complete:

• Update plan.md so no unresolved planning NEEDS CLARIFICATION remains.
• Update ## Requirement Status to match the research.
• Keep all in-scope requirements visible even when already implemented.

Phase 1: Design And Contracts

Generate design artifacts in SPECS_DIR:

• data-model.md: entities, fields, relationships, validation rules, and state transitions when the story involves data
• contracts/: public interfaces the project exposes to users or other systems
• quickstart.md: test-first validation scenarios and commands for the planned implementation

Contract guidance:

• Use the contract format appropriate for the project type.
• Examples include API contracts, CLI command schemas, library public API specs, parser grammars, UI interaction contracts, or event/message contracts.
• Skip contracts/ only when the feature is purely internal and has no meaningful public or integration surface.

Quickstart guidance:

• Include the intended unit test command.
• Include the intended integration test command.
• Include any service, fixture, environment, or migration setup needed for integration tests.
• Describe how to verify the single story end to end.
• Reflect requirement status decisions:
  • missing and partial: tests first, then implementation
  • implemented_unverified: verification tests first, then a planned implementation contingency if those tests fail
  • implemented_verified: final verification only unless the user asks for stronger coverage

Agent Context

After Phase 1 artifacts are generated and plan.md is updated, run the agent context update script:

.specify/scripts/bash/update-agent-context.sh __AGENT__

Replace __AGENT__ with the active integration key when known. If unknown, run the script without an agent argument so it updates existing agent files.

The script should:

• Parse the current plan.md
• Add only new technology from the current plan
• Preserve manual additions between managed markers

Stop Point

This skill stops after planning and design artifacts. Do not generate tasks.md or implementation code.

Report:

• Branch
• IMPL_PLAN path
• Generated artifacts
• Unit test strategy
• Integration test strategy
• Principles check result
• Requirement status summary by ID and count
• Which items need code changes
• Which items need tests only
• Which items are already verified
• Readiness for /moonspec.tasks

Post-Plan Hooks

After reporting, check .specify/extensions.yml for hooks.after_plan using the same parsing, filtering, and condition rules as pre-plan hooks. For each executable hook:

• Optional hook (optional: true): print

## Extension Hooks

**Optional Hook**: {extension}
Command: `/{command}`
Description: {description}

Prompt: {prompt}
To execute: `/{command}`

• Mandatory hook (optional: false): print

## Extension Hooks

**Automatic Hook**: {extension}
Executing: `/{command}`
EXECUTE_COMMAND: {command}

If no hooks are registered or .specify/extensions.yml does not exist, skip silently.

Key Rules

• Use absolute paths.
• Plan exactly one user story.
• Keep TDD as the default strategy.
• Identify unit and integration testing separately.
• Use plan to decide whether work is code + tests, tests only, or no new implementation.
• Existing code never removes a requirement from spec.md; it only changes the planned work.
• Prefer verification tests before implementation when behavior appears to already exist, but include fallback implementation work for implemented_unverified items when verification fails.
• Resolve all planning clarifications through research.md.
• Error on unjustified principle conflicts, multiple user stories, or unresolved clarifications.
• Generate design artifacts only; leave task generation to /moonspec.tasks.
• tasks.md should consume ## Requirement Status when deciding whether to emit implementation tasks, verification-only tasks, or no new work for already-verified items.