A spec-driven development (SDD) workspace template for
Claude Code: register any repository — or
several — and the factory clones, indexes and maps it, then takes every
requirement through a full lifecycle where the spec is the contract,
humans approve at six permission-backed gates, failing tests are committed
before code, and every document or metric is derived from the real sources.
git clone https://github.com/mmaripanguec/dev-sdd-kit.git my-system && cd my-system
./scripts/init-system.sh my-system # instantiate the template
claude # launch from the root
/repo-add https://github.com/your-org/your-repo.git # onboard your first repo
/spec-create my-feature what you need, in plain words # specify with gates
📐 Architecture & usage guide (EN) ·
Documento de arquitectura (ES) — generated
from the live workspace, always current.
🧭 Living AS-IS architecture as agent context (new) — after every
/repo-add indexing, the factory generates an arc42 + C4 architecture
document (Markdown and a self-contained HTML twin with Mermaid diagrams)
into knowledge/architecture/. Agents load it through the
<prefix>-architecture skill and answer from the docs; the code is
consulted only for undocumented gaps — so context is kept without re-indexing
or re-reading the codebase on every question. Setup & modes (direct engine vs
fleet/Postgres facade) in
docs/codebase-memory-setup.md.
⭐ If this approach resonates, a star helps other teams find it.
Why this exists
AI agents write code fast; what breaks teams is everything around it:
requirements lost in chat, decisions nobody recorded, docs that lie, agents
shipping unchecked. Industry research is consistent about what separates
high performers — and this factory encodes it:
- DORA 2024–2025: AI raises throughput but lowers stability unless
engineering discipline gets stronger, not weaker.
- McKinsey, State of AI 2025: the practices most correlated with impact
are full workflow redesign (55% of high performers vs 20%) and formal
human-in-the-loop validation (65% vs 23%).
- Anthropic / Thoughtworks: curated context as infrastructure and
spec-anchored development — the spec persists and evolves; code is still
the authority, verified against it.
Every mechanism here maps to those findings: 10 phases (F0 triage → F9
operations), six human gates enforced by tool permissions (agents cannot
approve their own work or touch production), strict TDD with untouchable
tests, and derived artifacts with provenance seals that say "no data"
before they ever make something up.
How it compares
Honest differences — each of these tools is good at what it targets:
| dev-sdd-kit | GitHub spec-kit | AWS Kiro | OpenSpec |
|---|
| Lifecycle coverage | F0–F9: triage → operations (CAB, postmortems, DORA) | spec → implement | spec → implement (IDE) | change proposals |
| Multi-repo systems | Core design (repos.yaml registry, deploy order, cross-repo specs) | single-repo focus | single-repo focus | single-repo focus |
| Brownfield grounding | Derived as-is map + code graph + arc42/C4 architecture doc (agent context) + context packs with executable assertions | greenfield-first; existing code is context you supply | IDE-side codebase context (steering files); no derived as-is artifact | delta-based (good) |
| Human gates | Permission-backed (agents lack credentials; approvals recorded per commit) | constitution self-checked by the LLM | agent hooks | review-based |
| TDD | Mandatory, tests untouchable | optional ("only if requested") | optional | optional |
| Derived docs & metrics | arc42+C4 architecture (MD+HTML) as agent context, architecture guide (EN/ES), as-is, DORA — generated, sealed, CI-checked | — | — | — |
| Agent ecosystem | Claude Code | 30+ agents | Kiro IDE | several |
| Maturity / community | Young | 122k★, huge ecosystem | AWS-backed | growing |
If you want a lightweight spec→code flow with any agent, spec-kit is
excellent. If you run systems of several existing repositories and need
the whole lifecycle governed — this is what dev-sdd-kit was built for.
Architecture at a glance
A requirement flows through 10 phases with six human gates. Phases F0–F4
write the SPEC — the living contract at the center — which governs design,
construction and certification; operations feeds knowledge back into the
next feature:
Full detail — every phase, gate, mechanism and the live catalog — in the
architecture document.
dev-sdd-kit/
├── README.md · CONTRIBUTING.md · CHANGELOG.md · LICENSE
├── CLAUDE.md # Shared context — loaded every session
├── repos.yaml # System topology (created by ./scripts/init-system.sh)
│
├── .claude/
│ ├── skills/ # 15 slash commands (one SKILL.md each)
│ │ ├── spec-create/ spec-review/ clarify/ consistency/
│ │ ├── implement-task/ converge/ harness-init/ orchestrate/
│ │ ├── repo-add/ repo-map/ system-map/ context-report/
│ │ └── as-is/ as-is-sync/ as-is-learn/
│ ├── agents/ # 7 phase agents
│ │ ├── requirements.md estimation.md analysis.md architecture.md
│ │ └── quality.md release.md operations.md
│ └── rules/ # 6 rule sets
│ ├── code-style.md testing.md security.md
│ └── api-design.md observability.md domain-banking.md
│
├── specs/ # The contracts (every feature starts here)
│ ├── _template.md # 12-section spec template
│ └── 2026-07-customer-assistant-adk.md # Example spec: the demo's new-app flow
│
├── knowledge/ # The system's memory
│ ├── business-rules.md # Business rules in force (RN-xx)
│ ├── standards.md # Standard → file map
│ ├── usage.md # DORA metrics (derived — do not hand-edit)
│ ├── decisions/_template-adr.md # Architecture Decision Records
│ ├── incidents/_template-postmortem.md # Blameless postmortems
│ ├── as-is/ INDEX.md · system.md # Derived as-is map
│ └── architecture/ <system>.md · .html # AS-IS architecture doc (arc42+C4, generated)
│
├── docs/
│ ├── index.html # Landing page (GitHub Pages)
│ ├── architecture.en.html · arquitectura.html # Generated architecture docs
│ ├── demo-assistant.md # Demo walkthrough (ADK + Gemini assistant)
│ ├── guia-operativa.md # Full operating guide (ES)
│ ├── instructivo-repo-existente.md # Repo onboarding walkthrough (ES)
│ ├── codebase-memory-setup.md # Code-graph MCP setup
│ ├── architecture-documentation-standard.md # AI-consumable architecture doc standard
│ └── assets/ banner.svg · demo.svg · architecture.svg
│
├── templates/ # What the factory instantiates
│ ├── CLAUDE.repo.md pack-repo.md pack-system.md pack-index.md
│ ├── docs-arquitectura.html docs-architecture.en.html
│ ├── knowledge-architecture.md · .html · .narrative.md # AS-IS arch templates
│ ├── skill-architecture.md # <prefix>-architecture context skill
│ └── github-actions-as-is.yml
│
├── scripts/ # Automation + 7 self-test suites (178 asserts) in scripts/tests/
│ ├── generate-architecture.sh # AS-IS architecture doc (.md + .html)
│ ├── codebase-memory.sh # Code-graph indexing: fleet seed + .mcp.json
│ └── afirmaciones.sh · frescura.sh · init-sistema.sh # ES aliases (exec the EN script)
├── harness/ claude-progress.md # Multi-session agent harness
└── .github/ # Issue & PR templates
Documentation
| Document | Language | Purpose |
|---|
| docs/architecture.en.html | English | Architecture, technical spec, model & usage guide (generated) |
| docs/codebase-memory-setup.md | English | Code-graph MCP setup: direct engine vs fleet/Postgres facade, indexing & troubleshooting |
| docs/architecture-documentation-standard.md | English | The AI-consumable architecture documentation standard (arc42 + C4 + 42010 + TOGAF/DDD/SRE): sections, views, ADR format, traceability, metadata |
| docs/arquitectura.html | Español | Same document in the factory's working language (generated) |
| docs/guia-operativa.md | Español | Complete operating guide: installation, auth per provider, E2E cycle, governance |
| docs/instructivo-repo-existente.md | Español | Step-by-step: onboarding an existing repo up to the first spec |
| CHANGELOG.md | English | Release history |
A note on language: the factory itself — skills, agents, rules,
templates and knowledge scaffolding — is fully in English, and command
names are always English. Your team picks its working language at
init-system.sh (en/es) and the factory keeps specs and interactions in
it. The Spanish-language guides under docs/ are the ES editions of the
documentation; the example spec (customer-assistant) is in English.
Contributing
See CONTRIBUTING.md — every change follows the factory's
own process: spec first, human gates, failing tests before code, one commit
per task, all seven self-test suites green. Issues and PRs come with templates.
License
MIT © 2026 Marcos Maripangue
