marcel/familienarchiv
1
0
Fork 0
Code Issues 108 Pull Requests 1 Actions 2 Packages Projects Releases Wiki Activity

refactor(sdd): make the feature spec issue-only (no committed spec.md)

Browse Source 
The Gitea issue body is the single source of truth for a spec; the only
per-feature artifact in git is the RTM row (REQ-ID -> issue # -> test). Drops
per-feature spec.md/tasks.md/checklist files from the workflow (the _example
stays as a template/reference). Updates the guide, ADR-041, AGENTS.md, CLAUDE.md,
templates, the RTM (adds an Issue column), the implement/review-pr skills, and
replaces the file-spec CI jobs with an rtm-check.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Marcel
2026-06-13 12:14:32 +02:00
parent f48a0d6dff
commit 40c1bba113
13 changed files with 178 additions and 202 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
docs/adr/041-sdd-adoption.md
View File

@@ -36,17 +36,23 @@ Adopt Spec-Driven Development, layered **on top of** the existing workflow, not
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.
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`; `.gitea/workflows/sdd-gate.yml`
lints spec structure, validates contracts, and checks traceability (non-blocking initially).
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.
@@ -54,7 +60,7 @@ Adopt Spec-Driven Development, layered **on top of** the existing workflow, not
| 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** |
| 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 |