DeepSpec

SDD Framework: The Spec is the Solution.

DeepSpec 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 deep-spec init cursor-agent

Then in your agent:

1. "Initialize DeepSpec" — 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 deep-spec init <agent>

Available agents: cursor-agent, claude, copilot, opencode, cline, and more — run npx deep-spec --help.

Manual skill install (retrocompat):

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

Commands

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

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)
deep-spec/         # orchestrator skill
.deepspec/         # dogfooded instance

License

MIT — see LICENSE.

Docs: godrix.github.io/DeepSpec