familienarchiv/docs/adr/041-sdd-adoption.md

ADR-041 — Adopt Spec-Driven Development (SDD)

Status: Accepted Date: 2026-06-13 Issue: SDD integration (docs/sdd-integration branch)

This is the "ADR-000" the SDD scaffold refers to, numbered 041 to fit the existing archive sequence rather than starting a parallel one. See .specify/adrs/README.md.

Context

The project already runs a lightweight, multi-persona review loop: feature work is tracked as dense Gitea issues, and the review-issue / review-pr / deliver-issue skills dispatch the character personas in .claude/personas/ (requirements engineer, developer, security, devops, ui, architect, tester) to comment on issues and PRs. COLLABORATING.md already mandates a Research → Plan → Implement → Validate cycle, red/green TDD, and a User-Journey + E2E-Scenario section on every feature issue. Decisions are captured in this ADR archive.

What is missing is a machine-readable, uniform front-end to that workflow:

• Requirements are written in free prose, so two readers (and an AI agent) can interpret the same issue differently. There is no enforced requirement grammar and no stable requirement identifier to trace from spec → code → test.
• There is no single short file an AI coding agent reads on every invocation; the rules are spread across CLAUDE.md, COLLABORATING.md, CODESTYLE.md, and CONTRIBUTING.md.
• Persona review is valuable but ad-hoc — there is no per-role checklist that gates a spec before implementation, so blind spots surface during PR review instead of at spec time.
• There is no living traceability record and no CI signal that a spec is well-formed.

The project is solo + LLM-driven; spec density and machine-readability are exactly the leverage points that make agent output reliable.

Decision

Adopt Spec-Driven Development, layered on top of the existing workflow, not replacing it:

1. EARS requirements. Every feature requirement is written in one of the five EARS patterns and carries a per-feature REQ-NNN id. (constitution §3; templates/feature-spec.md)
2. The spec lives in the Gitea issue body — issue-only, no committed spec.md. A feature's spec (EARS requirements, acceptance criteria, scope) is authored and reviewed in the Gitea issue, the single source of truth (consistent with the established "issue body is the source of truth / don't commit standalone spec files" practice). The only per-feature artifact in git is the RTM row (REQ-ID → issue # → test). Durable design decisions still get a docs/adr/ ADR; an OpenAPI contract or STRIDE threat model is drafted inline in the issue using the .specify/templates/ as writing aids. .specify/features/_example/ is a committed template/reference, not a live feature.
3. A constitution + AGENTS.md. .specify/constitution.md records the few non-negotiable rules (semantically versioned); .specify/AGENTS.md is the short machine-readable file AI agents read every invocation, cross-referencing the constitution rather than duplicating it.
4. Persona checklists. .specify/personas/*.md turn the existing rich personas into concise, EARS-aware, pass/fail spec-review checklists that gate a spec before code.
5. Living RTM + CI gate. .specify/rtm.md traces every REQ-NNN to its issue and test; .gitea/workflows/sdd-gate.yml validates any committed OpenAPI contract, lints any committed spec (e.g. the _example), reports constitution-change impact, and surfaces RTM drift (non-blocking initially).
6. Reuse, don't duplicate. ADRs stay in docs/adr/; persona checklists reference .claude/personas/; the Gitea issue templates mirror the feature-spec template.

Alternatives Considered

Option	Pros	Cons	Reason rejected
Adopt SDD (EARS requirements in the issue + AGENTS.md + constitution), integrated with existing docs	Adds requirement rigor & machine-readability; reuses ADR archive, personas, and the issue-as-spec practice; incremental	Per-feature spec authoring overhead	Chosen
No change (keep free-prose issues + persona review)	Zero new process	Ambiguous requirements; no traceability; no single agent-facing file; blind spots found late	Leaves the exact gaps that hurt agent output
Full GitHub Spec Kit	Mature, opinionated tooling	Heavy, opinionated structure that fights the existing Gitea/skill/persona workflow; redundant ADR/persona machinery	Too much to retrofit; conflicts with what already works
BMAD-METHOD	Rich agent-role framework	Large conceptual surface for a solo project; overlaps the existing persona system	Over-engineered for this team size

Consequences

• Cost: ~30–60 min of spec authoring + structured persona review per feature, before implementation begins.
• Gains: unambiguous, testable requirements; a stable spec→code→test trace; one authoritative agent-facing rules file; review blind spots caught at spec time; better and more consistent AI-agent output (the project's primary delivery mechanism).
• Obligations created:
  • The constitution is semantically versioned; any change triggers its Sync Impact review.
  • A new feature follows the workflow in SPEC_DRIVEN_DEVELOPMENT.md.
  • rtm.md is kept in sync as requirements land (CI warns on drift).
  • The SDD CI jobs start non-blocking and flip to blocking once adoption settles (TODO noted in the workflow).
• Non-disruptive: the existing Gitea-issue, branch/PR, TDD, and persona-review practices are unchanged in spirit — SDD formalises their inputs, it does not replace them.

References

• .specify/constitution.md, .specify/AGENTS.md
• SPEC_DRIVEN_DEVELOPMENT.md
• COLLABORATING.md, CONTRIBUTING.md
• EARS: Mavin et al., "Easy Approach to Requirements Syntax" (2009)

Revision log

• 2026-06-13 — constitution v1.0.0 ratified with this ADR.