From 982a437523e91bca79955720ef8dd6ccef4c87e9 Mon Sep 17 00:00:00 2001 From: Marcel Date: Sat, 13 Jun 2026 11:56:25 +0200 Subject: [PATCH] docs(adr): adopt Spec-Driven Development (ADR-041) Records the decision to layer SDD (EARS requirements, OpenSpec-style delta artifacts, a versioned constitution, and AGENTS.md) on top of the existing Gitea-issue + multi-persona-review workflow. Numbered 041 to extend the existing docs/adr/ archive rather than starting a parallel one. Co-Authored-By: Claude Opus 4.8 --- docs/adr/041-sdd-adoption.md | 87 ++++++++++++++++++++++++++++++++++++ 1 file changed, 87 insertions(+) create mode 100644 docs/adr/041-sdd-adoption.md diff --git a/docs/adr/041-sdd-adoption.md b/docs/adr/041-sdd-adoption.md new file mode 100644 index 00000000..e414a418 --- /dev/null +++ b/docs/adr/041-sdd-adoption.md @@ -0,0 +1,87 @@ +# 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//` + 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.