SDD DevFlow

Spec-Driven Development workflow for AI-assisted coding.

A complete development methodology for Claude Code and Gemini that combines specialized AI agents, workflow orchestration with human checkpoints, and institutional memory. Works with new and existing TypeScript/JavaScript projects.

Quick Start

New Project

npx create-sdd-project my-app

The interactive wizard asks about your stack, AI tools, and autonomy level:

🚀 Create SDD DevFlow Project

── Step 1: Project Basics ──────────────────────
  Project name: my-app
  Brief project description: Task management API

── Step 3: Project Type & Tech Stack ──────────
  1) Backend + Frontend (monorepo)  ← default
  2) Backend only
  3) Frontend only

── Step 4: AI Tools ────────────────────────────
  1) Claude Code + Gemini  ← default
  2) Claude Code only
  3) Gemini only

── Step 5: Workflow Configuration ──────────────
  Autonomy level:
  1) L1 Full Control — Human approves every checkpoint
  2) L2 Trusted — Human reviews plans + merges only  ← default
  3) L3 Autopilot — Human only approves merges
  4) L4 Full Auto — No human checkpoints, CI/CD gates only
  5) L5 PM Autonomous — PM Agent orchestrates features end-to-end

For defaults (fullstack Express+Next.js, L2 autonomy):

npx create-sdd-project my-app --yes

Existing Project

cd your-existing-project
npx create-sdd-project --init

The scanner detects your stack and installs adapted SDD files:

🔍 Scanning project...

    Project:       my-api
    Language:      TypeScript
    Backend:       Express + Mongoose + MongoDB
    Frontend:      Not detected
    Architecture:  Layered (controllers + handlers + managers)
    Tests:         Jest (3 test files)
    Monorepo:      No

Adding SDD DevFlow to my-api...

  ✓ Installing Claude Code config (agents, skills, commands, hooks)
  ✓ Installing Gemini config (agents, skills, commands)
  ✓ Creating ai-specs/specs/ (4 standards files)
  ✓ Creating docs/project_notes/ (product tracker, memory)
  ✓ Creating AGENTS.md
  ✓ Setting autonomy level: L2 (Trusted)

Done! Next steps:
  git add -A && git commit -m "chore: add SDD DevFlow to existing project"
  # Open in your AI coding tool and run: add feature "your first feature"

Never modifies existing code or overwrites existing files.

Upgrade

When a new version of SDD DevFlow is released, upgrade your project's template files:

cd your-existing-project
npx create-sdd-project@latest --upgrade

🔄 SDD DevFlow Upgrade

  Current version:  0.4.2
  New version:      0.5.0
  AI tools:         Claude Code + Gemini
  Project type:     backend

  Will replace:
    ✓ .claude/ (agents, skills, hooks)
    ✓ .gemini/ (agents, skills, commands)
    ✓ AGENTS.md, CLAUDE.md / GEMINI.md
    ✓ .env.example

  Will preserve:
    ⊘ .claude/settings.local.json (personal settings)
    ⊘ docs/project_notes/* (project memory)
    ⊘ docs/specs/* (your specs)
    ⊘ docs/tickets/* (your tickets)
    ⊘ .gitignore

  Standards:
    ✓ ai-specs/specs/base-standards.mdc — unchanged, will update
    ⚠ ai-specs/specs/backend-standards.mdc — modified by you, preserved

  Proceed? (y/N)

What gets upgraded:

• Agent definitions, skills, hooks, and commands
• AGENTS.md, CLAUDE.md, GEMINI.md, .env.example
• Standards files (.mdc) — only if you haven't customized them

What is always preserved:

• Your project documentation (docs/project_notes/, docs/specs/, docs/tickets/)
• Custom agents you added to .claude/agents/ or .gemini/agents/
• Custom commands in .claude/commands/
• Personal settings (.claude/settings.local.json)
• Your .gitignore
• Autonomy level setting

For non-interactive upgrades (CI/scripts): npx create-sdd-project@latest --upgrade --yes

Doctor (Diagnose Installation)

Check that your SDD installation is healthy:

cd your-project
npx create-sdd-project --doctor

🩺 SDD DevFlow Doctor

  ✓ SDD installed (v0.5.0)
  ✓ Version up to date (0.5.0)
  ✓ AI tools: Claude Code + Gemini
  ✓ Top-level configs present (AGENTS.md, CLAUDE.md, GEMINI.md)
  ✓ Agents: 8/8 present
  ✓ Project type coherence: OK (fullstack)
  ✓ Cross-tool consistency: Claude and Gemini in sync
  ✓ Standards: 4/4 present
  ✓ Hooks: quick-scan.sh executable, jq installed, settings.json valid
  ✓ Project memory: 4/4 files present

  Overall: HEALTHY

What it checks: SDD files present, version, agents for your project type, no stray frontend agents in backend projects (and vice versa), Claude and Gemini agents in sync, standards files, hooks and dependencies (jq), settings.json integrity, project memory files.

Exit code 1 if errors found — useful for CI pipelines.

Eject (Uninstall SDD)

Cleanly remove all SDD DevFlow files from your project:

cd your-project
npx create-sdd-project --eject

🗑️  SDD DevFlow Eject

  Installed version:  0.7.0
  AI tools:           Claude Code + Gemini
  Project type:       backend

  Will remove:
    ✗ .claude/agents/           template agents
    ✗ .claude/skills/
    ✗ .claude/hooks/
    ✗ .claude/settings.json
    ✗ .gemini/                  entire directory
    ✗ ai-specs/                 standards
    ✗ AGENTS.md
    ✗ CLAUDE.md / GEMINI.md
    ✗ .env.example
    ✗ .sdd-version
    ✗ .github/workflows/ci.yml  (SDD-generated)

  Will preserve:
    ⊘ .claude/agents/my-agent.md   (custom agent)
    ⊘ .claude/settings.local.json  (personal settings)
    ⊘ docs/                        (project notes, specs, tickets)

  Proceed? (y/N)

What gets removed: All SDD-generated files (agents, skills, hooks, standards, configs, CI workflow).

What is always preserved: Custom agents, custom commands, personal settings, project documentation (docs/), customized CI workflows (without SDD marker).

For non-interactive eject: npx create-sdd-project --eject --yes

Preview what would be removed: npx create-sdd-project --eject --diff

To re-install later: npx create-sdd-project --init

Preview Changes (--diff)

See what --init, --upgrade, or --eject would do without modifying anything:

cd your-existing-project
npx create-sdd-project --init --diff      # Preview init
npx create-sdd-project --upgrade --diff   # Preview upgrade
npx create-sdd-project --eject --diff    # Preview eject

Shows detected stack, files that would be created/replaced/preserved, and standards status — zero filesystem writes.

CI/CD (Auto-Generated)

Every project gets a GitHub Actions CI workflow at .github/workflows/ci.yml, adapted to your stack:

• PostgreSQL projects get a postgres:16 service with health checks
• MongoDB projects get a mongo:7 service with health checks
• Frontend-only projects get a lightweight workflow without DB services
• GitFlow projects trigger on both main and develop branches

Customize the generated workflow as your project grows.

After Setup

Open your project in Claude Code or Gemini and start building:

Single feature (L1-L4):

add feature "user authentication with JWT"
start task F001
show progress
next task

Autonomous multi-feature (L5):

start pm

The PM Orchestrator reads your product tracker, presents features for batch classification, then develops them sequentially — spec, plan, implement, review, merge — with all quality gates enforced.

The workflow skill guides you through each step — from spec writing to implementation to code review — with checkpoints based on your autonomy level.

What is SDD?

SDD DevFlow combines three proven practices:

1. Spec-Driven Development — Write specifications before code. Specs are the contract between planning and implementation.
2. Test-Driven Development — Red-Green-Refactor cycle for every feature.
3. Human-in-the-Loop — Strategic checkpoints with configurable autonomy levels that reduce human intervention as trust increases.

Why use SDD DevFlow?

• AI agents work better with structure. Without guardrails, AI coding assistants produce inconsistent results. SDD provides the methodology, standards, and workflow that make AI output predictable and high-quality.
• Institutional memory across sessions. Product tracker, bug logs, and decision records survive context compaction and session boundaries.
• Scales from solo to team. Start at L1 (full control) while learning, scale to L4 (full auto) for repetitive tasks.
• Works with your stack. Not opinionated about frameworks — detects and adapts to Express, Fastify, NestJS, Next.js, Nuxt, Vue, Angular, and many more.

What's Included

10 Specialized Agents

| Agent | Role | Step | |-------|------|------| | spec-creator | Draft/update specifications | 0 | | ui-ux-designer | Design guidelines, feature design notes | 0 (optional) | | backend-planner / frontend-planner | Create implementation plans | 2 | | backend-developer / frontend-developer | TDD implementation | 3 | | production-code-validator | Pre-commit quality scan | 4 | | code-review-specialist | Pre-merge code review | 5 | | qa-engineer | Edge cases, spec verification | 5 | | database-architect | Schema design, optimization | Any |

5 Skills (Workflow Orchestration)

| Skill | Trigger | What it does | |-------|---------|-------------| | development-workflow | start task F001, next task, add feature | Orchestrates the complete 7-step workflow | | bug-workflow | report bug, fix bug, hotfix needed | Bug triage, investigation, and resolution | | project-memory | set up project memory, log a bug fix | Maintains institutional knowledge | | health-check | health check, project health | Quick scan: tests, build, specs sync, secrets, docs freshness | | pm-orchestrator | start pm, continue pm, stop pm | L5: Autonomous sequential multi-feature execution with guardrails |

5 Custom Commands

| Command | What it does | |---------|-------------| | /review-spec | Cross-model spec review — runs automatically after self-review when external CLIs are available; catches requirement gaps, ambiguity, and architectural inconsistencies | | /review-plan | Cross-model plan review — runs automatically after plan self-review when external CLIs are available; catches implementation blind spots | | /context-prompt | Generates a context recovery prompt after /compact with Workflow Recovery to prevent checkpoint skipping | | /review-project | Comprehensive project-level review using up to 3 AI models in parallel — 6 domains, audit context, consolidated report with action plan | | /audit-merge | Automated compliance audit — 13 structural pre-merge checks (ticket, tracker, evidence, merge base, working tree, data files, CI state via gh pr checks, MCE Action 9 + Audit Merge Output) + 17 advisory drift patterns. Auto-fixes issues. |

Spec & Plan Quality

Every Standard/Complex feature spec goes through a built-in self-review (Step 0.4) where the agent critically re-reads its own spec checking for completeness, edge cases, API contract clarity, and architectural consistency. Then /review-spec automatically sends the spec plus project context (key_facts.md, decisions.md) to external AI models for independent critique — catching requirement-level blind spots before any planning begins.

Every plan then goes through its own built-in self-review (Step 2.4) followed by automatic /review-plan for external critique — catching implementation-level blind spots that same-model review misses.

Cross-model reviews only trigger when at least one external CLI is available (Gemini CLI, Codex CLI). If no CLIs are detected, the step is skipped — the self-review is sufficient.

Workflow (Steps 0–6)

0. SPEC      → spec-creator drafts + self-review + cross-model review → Spec Approval
1. SETUP     → Branch, ticket, product tracker                       → Ticket Approval
2. PLAN      → Planner creates plan + self-review + cross-model review → Plan Approval
3. IMPLEMENT → Developer agent, TDD
4. FINALIZE  → Tests/lint/build, validator       → Commit Approval
5. REVIEW    → PR, code review, QA              → Merge Approval
6. COMPLETE  → Clean up, update tracker

By complexity:

• Simple (bug fixes, small tweaks): 1 → 3 → 4 → 5 → 6
• Standard (features): 0 → 1 → 2 → 3 → 4 → 5 (+QA) → 6
• Complex (architectural changes): 0 → 1 (+ADR) → 2 → 3 → 4 → 5 (+QA) → 6

5 Autonomy Levels

| Level | Name | Human Checkpoints | Best For | |-------|------|-------------------|----------| | L1 | Full Control | All 5 | First feature, learning SDD | | L2 | Trusted | Plan + Merge | Normal development (default) | | L3 | Autopilot | Merge only | Well-defined, repetitive tasks | | L4 | Full Auto | None (CI/CD gates only) | Bulk simple tasks | | L5 | PM Autonomous | None + auto feature sequencing | Multi-feature batch execution via start pm |

Quality gates (tests, lint, build, validators) always run regardless of level.

PM Orchestrator (L5 — Autonomous Multi-Feature)

At L5, the PM Orchestrator skill develops multiple features sequentially without manual intervention:

> start pm

PM Orchestrator — Batch Classification

These features are ready to develop:

| # | Feature              | Type    | Priority | Dependencies   |
|---|----------------------|---------|----------|----------------|
| 1 | F014 — User Roles    | backend | High     | F006 (done)    |
| 2 | F015 — Email Alerts  | backend | Medium   | none           |

Classify complexity for each (Simple / Standard / Complex):

After classification, the loop runs autonomously: spec → plan → implement → review → merge for each feature, with all quality gates enforced.

11 guardrails prevent runaway execution: max 5 features/session, mandatory compact after 2 features, target-branch baseline check, intra-batch dependency check, circuit breaker (3 failures → stop), kill switch (stop pm), session lock, post-merge sanity check (npm test), rolling batch (1-3 features at a time), clean workspace validation, quality gates always on (/audit-merge included).

Recovery: after /compact or terminal restart, run continue pm — the session state in pm-session.md tracks exactly where you left off.

Merge Checklist (B+D Mechanism)

Every ticket includes a ## Merge Checklist Evidence table that the agent must fill before requesting merge approval. This mechanism:

• Survives context compaction — the ticket is always re-read via product tracker, so the empty evidence table acts as a persistent reminder
• Forces sequential execution — agent must read references/merge-checklist.md, execute 11 actions (0–10), and record evidence
• Works at all tiers — Simple tasks get a lite ticket with the same evidence table

Validated across 16+ features with 87% first-attempt pass rate (failures led to iterative improvements in v0.8.7–v0.9.8).

Project Memory

Tracks institutional knowledge across sessions in docs/project_notes/:

• product-tracker.md — Feature backlog + Active Session (context recovery after compaction)
• bugs.md — Bug log with solutions and prevention notes
• decisions.md — Architectural Decision Records (ADRs)
• key_facts.md — Project configuration, ports, URLs, branching strategy

Automated Hooks (Claude Code)

• Quick Scan — After developer agents finish, a fast grep-based scan (~2s, no API calls) checks for debug code, secrets, and TODOs
• Compaction Recovery — After context compaction, injects a reminder to read the product tracker for context recovery

Multi-Tool Support

| Tool | Support Level | |------|--------------| | Claude Code | Full — agents, skills, hooks, settings (.claude/) | | Gemini | Full — agents, skills, commands, settings (.gemini/) | | Other AI tools | AGENTS.md provides universal instructions (Cursor, Copilot, Windsurf, etc.) |

--init Stack Detection

When running --init on an existing project, the scanner automatically detects:

| Category | Detected | |----------|----------| | Backend frameworks | Express, Fastify, Koa, NestJS, Hapi, AdonisJS | | ORMs | Prisma, Mongoose, TypeORM, Sequelize, Drizzle, Knex, MikroORM, Objection.js | | Databases | PostgreSQL, MySQL, SQLite, MongoDB, SQL Server, CockroachDB (from Prisma schema, .env, or dependencies) | | Frontend frameworks | Next.js, Nuxt, Remix, Astro, SolidJS, React, Vue, Angular, Svelte | | Styling | Tailwind CSS, styled-components, Emotion, Sass | | Component libraries | Radix UI, Headless UI, Material UI, Chakra UI, Ant Design | | State management | Zustand, Redux, Jotai, TanStack Query, Recoil, Pinia, MobX | | Testing | Jest, Vitest, Mocha (unit) + Playwright, Cypress (e2e) | | Architecture | MVC, DDD, feature-based, handler-based, layered, flat | | Project type | Monorepo (workspaces, Lerna, Turbo, pnpm) or single-package |

Standards files are adapted to match your actual architecture — not generic defaults.

Template Structure

project/
├── AGENTS.md                            # Universal AI instructions (all tools)
├── CLAUDE.md                            # Claude Code config (autonomy, recovery)
├── GEMINI.md                            # Gemini config (autonomy)
├── .env.example                         # Environment variables template
│
├── .github/
│   └── workflows/ci.yml                 # CI pipeline (adapted to your stack)
│
├── .claude/
│   ├── agents/                          # 10 specialized agents
│   ├── skills/
│   │   ├── development-workflow/        # Main task workflow (Steps 0-6)
│   │   │   └── references/              # Templates, guides, examples
│   │   ├── bug-workflow/                # Bug triage and resolution
│   │   ├── health-check/               # Project health diagnostics
│   │   ├── pm-orchestrator/             # L5: Autonomous multi-feature loop
│   │   └── project-memory/              # Memory system setup
│   ├── commands/                        # Custom slash commands
│   │   ├── review-spec.md              # Cross-model spec review (pre-plan)
│   │   ├── review-plan.md              # Cross-model plan review
│   │   ├── context-prompt.md           # Post-compact context recovery
│   │   ├── review-project.md           # Multi-model project review
│   │   └── audit-merge.md             # Pre-merge compliance audit
│   ├── hooks/quick-scan.sh              # Post-developer quality scan
│   └── settings.json                    # Shared hooks (git-tracked)
│
├── .gemini/
│   ├── agents/                          # 10 agents (Gemini format)
│   ├── skills/                          # Same 5 skills
│   ├── commands/                        # Slash commands (workflow + review + context + project review)
│   └── settings.json                    # Gemini configuration
│
│
├── ai-specs/specs/
│   ├── base-standards.mdc              # Constitution + methodology
│   ├── backend-standards.mdc           # Backend patterns
│   ├── frontend-standards.mdc          # Frontend patterns
│   └── documentation-standards.mdc     # Documentation rules
│
└── docs/
    ├── project_notes/                   # Project memory
    │   ├── product-tracker.md
    │   ├── key_facts.md
    │   ├── bugs.md
    │   └── decisions.md
    ├── specs/                           # API, UI, and design specs
    └── tickets/                         # Task tickets (workflow-generated)

Default Tech Stack

Configurable via the wizard or <!-- CONFIG --> comments in template files:

• Backend: Node.js + Express + Prisma + PostgreSQL
• Frontend: Next.js (App Router) + Tailwind CSS + Radix UI + Zustand
• Shared Types: Validation schemas with TypeScript type inference
• Testing: Jest (unit) + Playwright (e2e)
• Methodology: TDD + DDD + Spec-Driven Development

Constitution (Immutable Principles)

These 6 principles apply to ALL tasks, ALL agents, ALL complexity levels:

1. Spec First — No implementation without an approved specification
2. Small Tasks — Work in baby steps, one at a time
3. Test-Driven Development — Write tests before implementation
4. Type Safety — Strict TypeScript, no any, runtime validation at boundaries
5. English Only — All code, comments, docs, commits, and tickets in English
6. Reuse Over Recreate — Always check existing code before proposing new files

Prerequisites

• Claude Code and/or Gemini
• Node.js 18+
• jq (for quick-scan hook): brew install jq (macOS) or apt install jq (Linux)

Manual Setup

If you prefer manual configuration over the CLI wizard, copy the template directory and look for <!-- CONFIG: ... --> comments in the files to customize:

cp -r node_modules/create-sdd-project/template/ /path/to/your-project/

Roadmap

• Agent Teams: Intra-feature parallelism (e.g., spec review + plan review in parallel)
• Monorepo improvements: Better support for pnpm workspaces and Turbo
• Retrofit Testing: Automated test generation for existing projects with low coverage
• Plugin system: Custom agents and skills marketplace

Contributing

Found a bug or have a suggestion? Open an issue on GitHub.

License

MIT