spec.md

SDD Framework: The Spec is the Solution.

spec.md is a zero-ceremony, AI-native Spec-Driven Development (SDD) framework. It guides AI agents from intention to implementation using a strict 3-stage pipeline and the A-B-C documentation flow.

Quick start

npx @godrix/spec.md init cursor-agent

Then in your agent:

1. "Initialize spec.md" — generate AGENTS.md from your repo
2. "Create task [name]" — draft A-B-C specs (no app code)
3. "Approve task" — implement with TDD in the same turn
4. Review at Review Gate, then "Complete task" to archive

Pipeline

drafts/ → (Approve) → active/ → Review Gate → (Complete) → archive/

A-B-C flow

| Doc | Role | | ---------------------- | ----------------------------------- | | APPROACH.md | How — immutable execution plan | | BUSINESS_CONTEXT.md | Why — acceptance criteria for TDD | | COMPLETION_REPORT.md | Evidence — status and execution log |

Installation alternatives

CLI (recommended):

npx @godrix/spec.md init <agent>

Available agents: cursor-agent, claude, copilot, opencode, cline, and more — run npx @godrix/spec.md --help.

Manual skill install (retrocompat):

mkdir -p .cursor/skills/spec.md
cp -R spec.md/. .cursor/skills/spec.md/

Commands

| Command | Trigger | | ------------------------------- | ---------------------------------- | | /spec.md.init | Initialize spec.md | | /spec.md.create-task | Create draft task | | /spec.md.approve-task | Approve + execute | | /spec.md.discard-task | Discard draft | | /spec.md.complete-task | Archive after Review Gate | | /spec.md.revise-task | Review Rounds | | /spec.md.list | List tasks by stage | | /spec.md.repair | Repair tracking map | | /spec.md.map-codebase | Refresh AGENTS.md from repo scan | | /spec.md.diagram-architecture | Mermaid ARCHITECTURE.md per task | | /spec.md.interview | One-question approach refinement |

Optional per-task artifact: ARCHITECTURE.md (diagrams on demand). The VS Code extension shows Execution Plan progress from APPROACH.md reconciled with COMPLETION_REPORT.md.

Repository layout (this repo)

spec/commands/     # operational prompts
spec/templates/    # A-B-C templates
src/               # CLI + hooks (TypeScript)
spec.md/         # orchestrator skill
.spec.md/         # dogfooded instance

License

MIT — see LICENSE.

Docs: godrix.github.io/spec.md