Turn an idea into production-ready software — one command at a time. A complete, opinionated SDLC kit for Claude Code: specialized agents, slash-command workflows, mandatory engineering rules, and quality gates that keep AI honest from
/specto/deploy.
This is not an application. It is a .claude/ configuration kit you drop into any project so that Claude Code stops being a clever autocomplete and starts behaving like a disciplined engineering team.
Instead of asking the AI to "build me an app" and hoping for the best, you drive a 12-step pipeline where each step:
- is owned by a specialized agent (Business Analyst, Architect, Backend Dev, Security Auditor, …),
- produces a concrete artifact (
specs/,architecture/,plans/,src/,tests/,reports/…), - and must pass a quality gate before the next step begins.
The result is the same discipline you'd expect from a real software team — requirements before code, tests before implementation, security before deploy — but executed by AI agents you orchestrate with a single slash command.
In short, the kit is a harness — a layer of explicit rules and verification loops that forces every SDLC command to follow the same standards and stay reproducible, instead of the model improvising differently on each run.
💡 Inspired by the agentic-workflow philosophy of BMAD-METHOD, adapted into a strict, gate-driven SDLC for C# / ASP.NET Core 8 (with first-class Node.js / Next.js overrides).
| Without the kit | With the kit |
|---|---|
| "Build me a bookmark app" → a wall of code, no plan | /spec → User Stories & Acceptance Criteria you approve first |
| AI invents its own structure each time | Every project follows the same Clean Architecture rules |
| Tests written last (or never) | TDD enforced — failing test first, ≥80% coverage gate |
| Security is an afterthought | STRIDE threat model before code, OWASP scan before deploy |
| "It works on my machine" | /verify runs against the exact artifact that ships |
| Inconsistent code style across sessions | 17 mandatory rules applied to every line |
PHASE 1 — REQUIREMENTS & DESIGN PHASE 2 — DEVELOPMENT & QUALITY PHASE 3 — SECURITY & DEPLOY
┌─────────────────────────────┐ ┌──────────────────────────┐ ┌───────────────────────────────────┐
│ /spec → Business Analyst │ │ /build → Frontend/Backend│ │ /scan → Security Auditor │
│ /arch → Systems Architect │ ──▶ │ /test → Test Engineer │ ──▶ │ /infra → Backend Developer │
│ /plan → Project Manager │ │ /review→ Code Reviewer │ │ /docs → Technical Writer │
│ /secure→ Security Auditor │ │ │ │ /verify → Test Engineer │
└─────────────────────────────┘ └──────────────────────────┘ │ /deploy → Release Manager │
specs/ architecture/ src/ tests/ reports/ └───────────────────────────────────┘
plans/ security/ security/ docker/ docs/ reports/
Each arrow is a quality gate. You can't promote a build that fails its tests, and you shouldn't /deploy an artifact /verify never blessed. (Optional steps are marked in the docs; security gates are blocking.)
# Option A — start a brand-new project from this kit
git clone https://github.com/dinhnguyenngoc/spec-driven-claude-code.git my-new-project
cd my-new-project
rm -rf .git && git init # make it your own
# Option B — copy the kit into an existing project
cp -r path/to/spec-driven-claude-code/.claude my-existing-project/.claudeThe only thing that matters is that the .claude/ folder sits at your project root. Open the folder in Claude Code (CLI, VS Code, or JetBrains) and you're ready.
/spec I want to build LinkVault — a personal bookmark manager where a user
can register, save bookmarks (URL, title, tags), search them, and mark favorites.
The Business Analyst agent will ask clarifying questions, then write specs/SPEC.md with User Stories and Acceptance Criteria. Review and approve it before moving on.
Run the commands in order, reviewing each artifact as you go:
/arch → system design, ADRs, API contracts → architecture/
/plan → tasks broken into vertical slices → plans/todo.md
/secure → STRIDE threat model (optional) → security/
/build → TDD implementation → src/ + web/ + tests/
/test → real-dependency QA gate → tests/
/review → five-axis code review → reports/
/scan → vulnerability scan → security/
/infra → Docker setup → docker/ + docker-compose.yml
/docs → documentation → docs/
/verify → exercise the real artifact → reports/VERIFY_REPORT.md
/deploy → stage the verified artifact → STAGED (production promote = manual, RUNBOOK §8)
That's the whole loop. For a quick prototype you can run just
/spec → /plan → /build → /test. For production, walk the full 12 steps.
Open plans/todo.md anytime to see what's done (- [x]) and what's next. The orchestrator ticks tasks only after they're verified.
| # | Command | Agent | What it does | Output |
|---|---|---|---|---|
| 1 | /spec |
Business Analyst | User Stories & Acceptance Criteria before code | specs/ |
| 2 | /arch |
Systems Architect | Architecture, diagrams, ADRs, API contracts | architecture/ |
| 3 | /plan |
Project Manager | Decompose into small, dependency-ordered tasks | plans/ |
| 4 | /secure ⃰ |
Security Auditor | Pre-dev threat model (STRIDE) | security/PRE_DEV_REVIEW |
| 5 | /build |
Frontend/Backend Dev | Implement with TDD, vertical slices | src/, web/, tests/ |
| 6 | /test |
Test Engineer | QA with real dependencies (TestContainers) | tests/ |
| 7 | /review ⃰ |
Code Reviewer | Five-Axis review of the change | reports/CODE_REVIEW |
| 8 | /scan ⃰ |
Security Auditor | Post-dev vulnerability scan | security/SCAN_REPORT |
| 9 | /infra |
Backend Developer | Docker + docker-compose for local dev | docker/ |
| 10 | /docs ⃰ |
Technical Writer | Getting-started, API, deployment docs | docs/ |
| 11 | /verify ⃰ |
Test Engineer | Exercise every feature on the real artifact | reports/VERIFY_REPORT |
| 12 | /deploy |
Release Manager | Stage the verified artifact — production promote is a manual step (RUNBOOK §8) | Staging (STAGED) |
⃰ = optional step, but blocking if run (security gates are non-negotiable).
Optional parameters (so you know they exist):
/spec— for UI products, ASCII wireframes are produced by default; add--prototype(or say "with prototype") to also generate a clickable HTML prototype for stakeholder click-through sign-off./arch— Rejection ADRs (intentionally-excluded stack components) default to one consolidated table; add--adr=per-component(or say "a separate ADR per component") to emit one full ADR per excluded component (e.g. audit/compliance).
| Command | Purpose |
|---|---|
/discover |
Brownfield onboarding — survey an existing codebase, verify build/run, generate the Project Profile |
/discover-system |
Multi-repo — aggregate per-repo discovery into a system-wide map (service catalog, call-graph, cross-service journeys); read-only, one-way docs |
/inspect |
Query current state — answer "does feature X exist / how is Y configured?" with 3 evidence tiers (records → code → live); read-only, no gate |
/debug |
Systematic debugging — find the root cause, not the symptom |
/simplify |
Reduce complexity without changing behavior |
/fix-issue |
Analyze and fix a reported bug during the dev cycle (ends at /review) |
/hotfix |
Restore a live system — triage rollback vs fix-forward, patch, re-verify, redeploy |
Each command invokes a specialist with its own playbook (in .claude/agents/):
| Agent | Specialty |
|---|---|
| 📊 Business Analyst | Requirements, user stories, acceptance criteria |
| 🏗️ Systems Architect | Scalable architecture, ADRs, API design |
| 📋 Project Manager | Sprint planning, task decomposition |
| 🔒 Security Auditor | Threat modeling (STRIDE), vulnerability assessment |
| 🔧 Backend Developer | ASP.NET Core, EF Core, SQL Server, Redis, REST |
| 🖥️ Frontend Developer | Next.js, React, TypeScript, modern UI |
| 🎨 UI/UX Designer | Intuitive, accessible user experiences |
| 🧪 Test Engineer | Test strategy, TDD, coverage, TestContainers, E2E |
| 👀 Code Reviewer | Five-axis review (Correctness, Readability, Architecture, Security, Performance) |
| 📝 Technical Writer | API references, runbooks, troubleshooting |
| 🚀 Release Manager | Build, staged rollout, versioning, release notes |
The kit auto-detects which situation you're in (see the ## Project Profile block in .claude/CLAUDE.md):
| Mode | When | How to start |
|---|---|---|
| 🌱 Greenfield | Building from scratch, no code yet | /spec <your idea> → walk the 12 steps |
| 🏚️ Brownfield | Legacy code already exists / runs in production | /discover first → reverse-/spec → reverse-/arch → then iterate |
Brownfield discipline (auto-activated): characterization tests before touching untested legacy code, backward-compatibility by default, ADR required to change architecture, and the strangler-fig pattern for upgrades. See .claude/rules/brownfield.md.
Every line of code obeys the mandatory rules in .claude/rules/. Highlights:
- Clean Architecture —
Api → Core ← Infrastructure, no cross-layer leaks - Clean Code & SOLID — ≤3 params, single-purpose methods, no flag params, async correctness
- TDD — failing test first, ≥80% line / ≥75% branch coverage
- Security first — no hardcoded secrets, parameterized queries, JWT discipline, OWASP checks
- RFC 7807 errors, REST conventions, structured logging with correlation IDs
- Docker baseline — multi-stage build, non-root user, health checks, resource limits, image scanning
/spec → /arch PRD approved · every story has acceptance criteria
/arch → /plan architecture reviewed · ADRs documented · API contracts defined
/build → /test all unit tests pass · code compiles
/test → /review coverage ≥ 80% · all tests pass
/scan → /infra no critical/high vulnerabilities (if /scan run)
/infra → /docs docker builds · compose up healthy
/verify → /deploy artifact tested == artifact promoted (if /verify run)
The kit ships with a default stack (C# 12 + ASP.NET Core 8 + EF Core 8 + SQL Server + Next.js). To use a different peripheral technology, edit the ## Project Profile in .claude/CLAUDE.md and the matching override kicks in automatically:
| Want… | Declare in Profile | Override file |
|---|---|---|
| PostgreSQL / MySQL / Oracle / MongoDB | Database: PostgreSQL |
.claude/rules/overrides/database-*.md |
| Node.js backend (Express/NestJS/Fastify) | Core: Node.js + … |
.claude/rules/overrides/lang-nodejs.md |
| ELK observability | Observability: ELK |
.claude/rules/overrides/monitoring-elk.md |
Overrides only replace the dialect/backend-specific parts — all agnostic principles (parameterized queries, structured logging, TDD…) stay the same.
.claude/
├── CLAUDE.md # The brain — pipeline, gates, Project Profile, rules index
├── commands/ # 19 slash-command workflows (/spec, /arch, /build, …)
├── agents/ # 11 specialized agent playbooks
├── rules/ # 17 mandatory engineering rules
│ └── overrides/ # 8 stack-specific overrides (Postgres, Node.js, ELK, …)
├── skills/ # Reusable techniques (tdd, code-review, …)
├── references/ # 10 references/checklists (security, testing, docker, a11y, multi-repo, …)
├── templates/ # fill-only templates: STRIDE · OWASP · TEST_REPORT · VERIFY_REPORT · CODE_REVIEW · RUNBOOK_RELEASE · wireframes
├── hooks/ # Lifecycle hooks (command stats)
└── scripts/ # Security scanners (dotnet, nodejs, python, docker)
# Generated as you work:
specs/ architecture/ plans/ security/ src/ web/ tests/ reports/ docker/ docs/
📖 The single source of truth for the whole workflow is .claude/CLAUDE.md — start there if you want the deep dive.
This kit ships with a sample brief, README1.txt, for LinkVault — a personal bookmark manager (auth, bookmark CRUD, tags, search, simple web UI). It's the perfect first run:
/spec # paste the LinkVault requirements from README1.txt
/arch # design the Clean Architecture solution + API
/plan # break it into buildable slices
/build # implement, test-first
/test # prove it with real dependencies
By the end you'll have a working, tested, documented ASP.NET Core + Next.js app — and a feel for how the whole pipeline flows.
Do I have to run all 12 steps?
No. Required steps are /spec, /arch, /plan, /build, /test, /infra, /deploy. The rest (/secure, /review, /scan, /docs, /verify) are optional — but if you run them, their gates are blocking. For production, running them all is strongly recommended.
Can I use it for languages other than C#? Yes — the kit has Node.js / TypeScript overrides today, and the architecture is designed so peripheral tech (DB, observability) swaps via the Project Profile.
Where do I change the default model or behavior? .claude/settings.json (model, permission mode, hooks).
What's the difference between /fix-issue and /hotfix?
/fix-issue fixes code during the dev cycle (not yet released). /hotfix restores something that's already live — it adds rollback triage, re-verification, and an incident runbook.
This project is licensed under the MIT License — see the LICENSE file for details.
The workflow philosophy draws inspiration from BMAD-METHOD.