A specification-driven development CLI where Copilot plans and Claude CLI implements.

AI plans, Claude codes.

This tool brings spec-driven development to GitHub Copilot with one foundational rule: AI plans, Claude CLI implements from planning artifacts. Specifications drive development. AI produces specs, plans, task breakdowns, and reviews -- all in prose. Claude CLI implements everything from the planning artifacts.

The result is a disciplined workflow where every feature starts with a specification, gets planned in prose, becomes a Claude CLI task checklist, and gets reviewed against the spec after Claude CLI builds it.

# Install globally via uv
uv tool install claude-sdd-cli --from git+https://github.com/Lucas-Frazao/claude-sdd-cli.git

# Or for development
git clone https://github.com/Lucas-Frazao/claude-sdd-cli.git
cd claude-sdd-cli
uv pip install -e ".[dev]"

csdd init my-project

This creates:

• .csdd/ directory with constitution, templates, and scripts
• .github/agents/ with Copilot agent commands (csdd.*.agent.md)
• .github/prompts/ with companion prompt files
• .github/copilot-instructions.md with project context
• .vscode/settings.json with prompt file recommendations

Open the project in VS Code and use Copilot Chat with these commands:

  /csdd.vision --> /csdd.tech-stack --> /csdd.architecture --> /csdd.roadmap --> For EACH feature:
      /csdd.specify --> /csdd.clarify --> /csdd.plan --> /csdd.tasks --> CLAUDE CLI IMPLEMENTS --> /csdd.review

1. Vision: Define the product vision -- what it is, who it's for, and why.
2. Tech Stack: Define the technology stack -- languages, frameworks, databases, and tooling.
3. Architecture: Define the application architecture -- structure, layers, components, and data flow.
4. Roadmap: Define ALL features needed to build the product.
5. For each feature from the roadmap:
   1. Specify: Describe the feature. AI creates a structured spec.
   2. Clarify: AI finds ambiguity and contradictions in the spec.
   3. Plan: AI generates research, data models, contracts -- all in prose, no code.
   4. Tasks: AI creates a sequenced, traceable checklist for Claude CLI.
   5. Claude CLI Implements: Claude CLI implements from planning artifacts. That's the point.
   6. Review: AI compares the implementation against the spec. Produces follow-up tasks, not patches.

After csdd init, your project looks like:

my-project/
├── .csdd/
│   ├── memory/
│   │   ├── constitution.md          # The 8 Articles
│   │   ├── product-vision.md        # Product vision document
│   │   ├── tech-stack.md            # Technology stack decisions
│   │   ├── architecture.md          # Application architecture
│   │   └── feature-roadmap.md       # Feature roadmap
│   ├── templates/
│   │   ├── spec-template.md
│   │   ├── plan-template.md
│   │   ├── tasks-template.md
│   │   ├── constitution-template.md
│   │   ├── review-template.md
│   │   └── research-template.md
│   ├── scripts/
│   │   └── bash/
│   │       ├── common.sh
│   │       ├── create-new-feature.sh
│   │       └── setup-plan.sh
│   └── init-options.json
├── .github/
│   ├── skills/
│   │   ├── csdd-vision/SKILL.md
│   │   ├── csdd-tech-stack/SKILL.md
│   │   ├── csdd-architecture/SKILL.md
│   │   ├── csdd-roadmap/SKILL.md
│   │   ├── csdd-specify/SKILL.md
│   │   ├── csdd-plan/SKILL.md
│   │   ├── csdd-tasks/SKILL.md
│   │   ├── csdd-clarify/SKILL.md
│   │   ├── csdd-review/SKILL.md
│   │   ├── csdd-trace/SKILL.md
│   │   └── csdd-constitution/SKILL.md
│   └── copilot-instructions.md
├── .vscode/
│   └── settings.json
└── specs/
    └── 001-feature-name/
        ├── spec.md
        ├── plan.md
        ├── research.md
        ├── data-model.md
        ├── quickstart.md
        ├── tasks.md
        ├── review.md
        ├── traceability.md
        └── contracts/

Every project gets a constitution with 8 non-negotiable articles:

1. Specification-First -- Specs before code.
2. Claude CLI Implementation -- Claude CLI implements all code from planning artifacts.
3. AI Planning-Only -- AI clarifies, researches, plans, and reviews.
4. Ambiguity Marking -- Unclear requirements get [NEEDS CLARIFICATION].
5. Traceability -- Tasks map to requirements, reviews map to specs.
6. Review Over Regeneration -- Gaps produce follow-up tasks, not code.
7. No Executable Planning AI Output -- Code fences and snippets are rejected from planning artifacts.
8. Transparency -- Audit trail for all AI interactions.

csdd init <project-name>   # Initialize a new project
csdd init --here            # Initialize in current directory
csdd vision                 # Define the product vision
csdd tech-stack             # Define the technology stack
csdd architecture           # Define the application architecture
csdd roadmap                # Define the feature roadmap
csdd specify                # Create a feature specification
csdd clarify                # Analyze specs for ambiguity
csdd plan                   # Generate a technical plan
csdd tasks                  # Create a Claude CLI execution checklist
csdd review                 # Review implementation against spec
csdd trace                  # Map requirements to tasks
csdd integrate copilot      # Re-run Copilot integration
csdd check                  # Verify project setup
csdd version                # Show version

Specifications should drive development. When coupled with structured planning artifacts, Claude CLI can implement features with full context -- specifications, data models, contracts, and task breakdowns all guide the implementation.

This tool preserves the strongest idea from SDD -- that specifications should drive development -- while ensuring structured, traceable implementation from planning artifacts.

Built for:

• Solo developers who want strong planning support with Claude CLI implementation
• Students who want to learn architecture and implementation deeply
• Engineers who want an auditable, specification-first workflow
• Teams experimenting with AI-assisted planning where Claude CLI implements from structured artifacts

git clone https://github.com/Lucas-Frazao/claude-sdd-cli.git
cd claude-sdd-cli
uv pip install -e ".[dev]"
pytest

Contributions are welcome. See CONTRIBUTING.md for guidelines.

This project will not accept contributions that generate executable code or bypass the constitution.

MIT