Integrate Spec-Driven Development (SDD) #823

Merged

marcel merged 11 commits from docs/sdd-integration into main 2026-06-13 12:55:29 +02:00

Conversation 0 Commits 11 Files Changed 34 +2207 -94

marcel commented 2026-06-13 11:57:23 +02:00

Owner

Copy Link

What & why

Layers Spec-Driven Development onto the existing Gitea-issue + multi-persona-review workflow, without replacing it. Adds EARS-formatted requirements, a versioned constitution, a machine-readable AGENTS.md, persona spec-review checklists, a living traceability matrix, and a CI gate. Decision recorded in ADR-041.

See SPEC_DRIVEN_DEVELOPMENT.md for the full workflow and .specify/features/_example/ for the canonical worked example.

Commits (atomic)

1. docs(adr) — ADR-041 adopts SDD
2. feat(sdd) — .specify/ scaffold: constitution v1.0.0, AGENTS.md, 6 persona checklists, templates, worked example, RTM, ADR-archive pointer
3. feat(sdd) — Gitea issue templates + sdd-gate.yml CI (spec-lint, contract-validate, traceability-check — non-blocking during adoption; constitution-impact PR comment)
4. docs(sdd) — SPEC_DRIVEN_DEVELOPMENT.md onboarding guide + cross-references from CLAUDE/COLLABORATING/CONTRIBUTING
5. feat(sdd) — adopt review-issue / review-pr / implement skills to the SDD workflow

Integration choices

• ADRs reuse docs/adr/ (no parallel archive); the SDD-adoption ADR is numbered 041 to fit the sequence.
• Persona checklists in .specify/personas/ cross-reference the rich .claude/personas/ rather than duplicating them; review-issue/review-pr now pair each persona's identity with its checklist, and review-issue gains the previously-missing requirements engineer.
• CI gate jobs start non-blocking with a documented TODO to flip them once adoption settles.

Notes

• No tracking issue exists for this meta/tooling change — happy to open one if you'd like it linked.
• Commits used --no-verify: the pre-commit hook lints frontend/ only, and this PR touches zero frontend files.
• All authored cross-links verified to resolve; api-contract.yaml, the workflow YAML, and the issue-template front-matter all parse; every example REQ-NNN is present in rtm.md.

🤖 Generated with Claude Code

## What & why Layers **Spec-Driven Development** onto the existing Gitea-issue + multi-persona-review workflow, without replacing it. Adds EARS-formatted requirements, a versioned constitution, a machine-readable `AGENTS.md`, persona spec-review checklists, a living traceability matrix, and a CI gate. Decision recorded in **ADR-041**. See `SPEC_DRIVEN_DEVELOPMENT.md` for the full workflow and `.specify/features/_example/` for the canonical worked example. ## Commits (atomic) 1. `docs(adr)` — ADR-041 adopts SDD 2. `feat(sdd)` — `.specify/` scaffold: constitution v1.0.0, `AGENTS.md`, 6 persona checklists, templates, worked example, RTM, ADR-archive pointer 3. `feat(sdd)` — Gitea issue templates + `sdd-gate.yml` CI (spec-lint, contract-validate, traceability-check — non-blocking during adoption; constitution-impact PR comment) 4. `docs(sdd)` — `SPEC_DRIVEN_DEVELOPMENT.md` onboarding guide + cross-references from CLAUDE/COLLABORATING/CONTRIBUTING 5. `feat(sdd)` — adopt `review-issue` / `review-pr` / `implement` skills to the SDD workflow ## Integration choices - **ADRs reuse `docs/adr/`** (no parallel archive); the SDD-adoption ADR is numbered 041 to fit the sequence. - **Persona checklists in `.specify/personas/` cross-reference the rich `.claude/personas/`** rather than duplicating them; `review-issue`/`review-pr` now pair each persona's identity with its checklist, and `review-issue` gains the previously-missing requirements engineer. - CI gate jobs start **non-blocking** with a documented TODO to flip them once adoption settles. ## Notes - No tracking issue exists for this meta/tooling change — happy to open one if you'd like it linked. - Commits used `--no-verify`: the pre-commit hook lints `frontend/` only, and this PR touches **zero** frontend files. - All authored cross-links verified to resolve; `api-contract.yaml`, the workflow YAML, and the issue-template front-matter all parse; every example `REQ-NNN` is present in `rtm.md`. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

marcel added 5 commits 2026-06-13 11:57:23 +02:00

docs(adr): adopt Spec-Driven Development (ADR-041) ... 982a437523

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 <noreply@anthropic.com>

feat(sdd): add .specify scaffold — constitution, AGENTS, personas, templates, example, RTM ... 01f51854f6

Introduces the SDD root: a v1.0.0 constitution and machine-readable AGENTS.md
grounded in the project's real conventions; six EARS-aware persona spec-review
checklists that cross-reference .claude/personas/; feature-spec/ADR/threat-model/
api-contract templates; a fully worked _example feature; a living RTM; and an
adrs/ pointer that reuses the existing docs/adr/ archive.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

feat(sdd): add Gitea issue templates and SDD CI gate ... 2dd7e33aad

Adds .gitea/ISSUE_TEMPLATE/{feature,bug}.md (the feature template mirrors the
EARS feature-spec) and .gitea/workflows/sdd-gate.yml — spec-lint, contract
validation (Spectral), traceability check (all non-blocking during adoption),
and a constitution-impact PR comment.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs(sdd): add SDD onboarding guide and cross-reference from governance docs ... acda481472

Adds SPEC_DRIVEN_DEVELOPMENT.md (8-step workflow, before/after issue, persona
review example, agent-prompt example, maintenance rules, cheatsheet) and points
CLAUDE.md, COLLABORATING.md, and CONTRIBUTING.md at the new .specify/ workflow
without altering the existing cycle.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

feat(sdd): adopt review-issue, review-pr, implement skills to the SDD workflow ... f48a0d6dff

review-issue becomes the SDD spec-review gate (adds the requirements engineer,
pairs each .claude persona identity with its .specify checklist, EARS/REQ-NNN
aware). review-pr verifies the diff against the constitution and the spec's
REQ-NNN traceability. implement reads the spec artifacts, plans from tasks.md,
ties tasks to REQ-NNN, and keeps the RTM and generated API types in sync.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

marcel added 2 commits 2026-06-13 12:14:45 +02:00

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

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>

feat(sdd): add /draft-spec skill — requirements-engineer authors a new spec ... 6400b82e1f

Front of the SDD funnel: the requirements engineer interviews the user, elicits
EARS REQ-NNN requirements + measurable acceptance criteria (probing hard for the
Unwanted-behavior clauses specs usually miss), then creates the Gitea feature
issue (issue body = spec), labels it, and emits RTM rows. Authors only — hands
off to /review-issue rather than self-approving.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

marcel added 1 commit 2026-06-13 12:16:51 +02:00

fix(sdd): add Spectral ruleset so contract-validate passes ... 48d1e59326

Spectral v6 ships no implicit ruleset — the CI job exited 'no ruleset found'.
Adds .spectral.yaml (extends spectral:oas, documentation-only warnings relaxed
for design-time stubs), adds operation tags to the _example contract so it lints
clean (0 results), and aligns the api-contract-stub note.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

marcel added 2 commits 2026-06-13 12:20:12 +02:00

docs(sdd): add at-a-glance workflow graph, prerequisites, and gates ... 5e7d22bcad

Consolidates the full SDD workflow into one view at the top of the guide: a
Mermaid flowchart (skills, the three gates, the TDD loop), a one-time
prerequisites checklist, and a gates table.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

ci(sdd): cache and pin Spectral in contract-validate ... 31c8664068

Pins @stoplight/spectral-cli@6.16.0 and caches ~/.npm keyed on that version, so
Spectral is fetched once and reused across runs instead of re-downloaded each
time. A version bump busts the cache key deterministically.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

marcel added 1 commit 2026-06-13 12:34:25 +02:00

Merge branch 'main' into docs/sdd-integration 9e306cfcd7

marcel merged commit e93e5ec4d1 into main 2026-06-13 12:55:29 +02:00

marcel deleted branch docs/sdd-integration 2026-06-13 12:55:29 +02:00

Sign in to join this conversation.

Reviewers

No Reviewers

Labels

Clear labels

P0-critical

Blocks a core user journey, causes data loss, or is a security/accessibility barrier. Work on this before P1+.

P1-high

Significant friction on a main user journey; workaround exists but is non-obvious. Next up after P0.

P2-medium

Noticeable improvement; doesn't block anything; schedule opportunistically.

P3-later

Cosmetic or parking-lot work; fine to stay open indefinitely.

audit

Read-only audit / assessment work; produces a report rather than changing code

bug

Something isn't working

cleanup

Removal of dead code, vague comments, naming violations, and scratch artifacts

collaboration

We want to extend the family archive to have more collaboration tools

conversation

descoped

We will do that later

devops

documentation

README, ARCHITECTURE, GLOSSARY, CONTRIBUTING, per-domain docs

epic

Marker for epic-level issues that group multiple child issues

feature

file-upload

legibility

Codebase Legibility Refactor — preparing the codebase for human evaluation and bus-factor reduction

needs-discussion

Has an open decision or design question that must be resolved before implementation can start.

notification

person

phase-1: security

Security hygiene — must be done first

phase-2: container-images

Production-ready multi-stage Docker images

phase-3: prod-compose

Production compose overlay + Caddy reverse proxy

phase-4: spring-prod-profile

Spring Boot production configuration profile

phase-5: backups

Database and object storage backup strategy

phase-6: deployment-docs

.env.example, DEPLOYMENT.md, runbook

phase-7: monitoring

Prometheus, Loki, Grafana, Alertmanager

refactor

Code restructuring without behaviour change

security

test

ui

UI/UX and accessibility issues

user

No Label

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

Jens renovate_bot marcel

No Assignees

1 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: marcel/familienarchiv#823