MoonSpec

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

1. Keep useful docs accurate in the same change; the current task and applicable AGENTS.md set requirements
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. Keep constitution-like guidance in AGENTS.md
9. 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.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 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

Both projection entrypoints check for retired files in the bundle's skill and command namespaces; --write removes them while preserving custom assets outside those namespaces. Output scopes must be real directories within the consumer. MoonMind's wrapper adds its consumer-specific 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.