MoonSpec

MoonSpec is a fork of GitHub Spec Kit with an opinionated approach to Spec-Driven Development:

1. Maintain declarative, desired-state documents as the primary source of truth
2. Breakdown declarative documents into one or more stories
3. Implement one story at a time (not 3+)
4. Generate imperative plans and tasks only as temporary artifacts
5. Implement code using Test-Driven Development (TDD)
6. Aim to create both integration tests and unit tests
7. Use the verify skill to enable a corrective loop with a quality gate
8. Use the doc-reconcile skill when the document is impossible, unclear, or inconsistent
9. Keep constitution-like guidance in AGENTS.md
10. Chain all of the implementation steps with an orchestrate skill

Note that for chaining steps, an orchestration tool like MoonMind is recommended because it improves context management and the resilience of failed steps.

Workflow Identity

Canonical skill IDs use moonspec-*.

Canonical slash commands use /moonspec.*.

The main lifecycle is:

1. /moonspec.breakdown when a broad design must be split into one-story candidates.
2. /moonspec.specify for one-story specs.
3. /moonspec.plan for planning artifacts.
4. /moonspec.tasks for TDD-first implementation tasks.
5. /moonspec.align for artifact consistency repair.
6. /moonspec.implement for implementation.
7. /moonspec.verify as the final read-only completion gate.
8. /moonspec.doc-reconcile after successful verification when canonical docs need updates.
9. /moonspec.orchestrate to coordinate the lifecycle for a preselected one-story request.

Bundle Layout

The repository packages the assets that consumers need to run the MoonSpec lifecycle:

• agent skills under bundle/skills/
• command wrappers under bundle/commands/
• spec, plan, task, checklist, and agent templates under bundle/templates/
• helper scripts under bundle/scripts/
• portable preset definitions under bundle/presets/
• bundle docs and projection recipes under bundle/docs/ and bundle/projections/

bundle/
  moonspec.bundle.yaml
  skills/
  templates/
  commands/
    gemini/
    markdown/
  scripts/
    bash/
  presets/
  docs/
  projections/

bundle/moonspec.bundle.yaml is the authoritative manifest. Consumers should read the manifest and the relevant projection recipe instead of hardcoding individual files.

Validation

Run:

python tools/validate_bundle.py
pytest

The validator checks exported file existence, skill front matter, OpenAI wrappers, preset skill references, command/skill consistency, projection recipes, script references, and legacy terminology.

Projection

MoonMind consumes this repository as a pinned git submodule at vendor/moonspec.

For a consumer checkout, project the bundle with:

python tools/project_bundle.py --target /path/to/consumer --projection moonmind --write
python tools/project_bundle.py --target /path/to/consumer --projection moonmind --check

MoonMind has its own wrapper around this projection so it can add generated-file headers and enforce consumer-specific drift checks.

CLI

The Python package is intentionally thin. The bundle is the product.

moonspec bundle-path
moonspec validate
moonspec project --target /path/to/consumer --projection moonmind --check

Authoring

See bundle/docs/AuthoringGuide.md for adding or changing bundle assets and bundle/docs/BundleIntegration.md for consumer integration rules.