# 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`](../../.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. **OpenSpec-style delta artifacts.** Each in-flight feature gets a `.specify/features/<name>/`
   directory holding `spec.md`, `design.md`, optional `api-contract.yaml` / `threat-model.md`
   / feature-local ADRs, `tasks.md`, and `checklist-results.md`. Artifacts are deltas focused
   on one change, archived when the feature ships.
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`; `.gitea/workflows/sdd-gate.yml`
   lints spec structure, validates contracts, and checks traceability (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 + delta artifacts + AGENTS.md), integrated with existing docs | Adds requirement rigor & machine-readability; reuses ADR archive and personas; 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](../../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/constitution.md), [.specify/AGENTS.md](../../.specify/AGENTS.md)
- [SPEC_DRIVEN_DEVELOPMENT.md](../../SPEC_DRIVEN_DEVELOPMENT.md)
- [COLLABORATING.md](../../COLLABORATING.md), [CONTRIBUTING.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.