diff --git a/.claude/skills/implement/SKILL.md b/.claude/skills/implement/SKILL.md index a7b76109..47019d78 100644 --- a/.claude/skills/implement/SKILL.md +++ b/.claude/skills/implement/SKILL.md @@ -54,12 +54,11 @@ Mark each concern with its source: reviewer name + comment excerpt. Also read: - `CLAUDE.md` for project conventions -- **The feature's SDD artifacts**, if a spec exists for this issue: `.specify/features//spec.md` - (the `REQ-NNN` requirements + acceptance criteria), `tasks.md` (the red/green task list), - `api-contract.yaml` (the API shape), and `threat-model.md` (security obligations). If the - issue is a well-formed SDD spec but no `.specify/features//` directory exists yet, - create one from [the templates](../../../.specify/templates/) and mirror the spec into it. -- [`.specify/rtm.md`](../../../.specify/rtm.md) — note each `REQ-NNN`'s current Status +- **The issue body — it IS the spec** (issue-only; there is no committed `spec.md`). Extract its + `REQ-NNN` requirements, acceptance criteria, API stub, data-model delta, and any inline + STRIDE/threat notes. These are your contract. +- [`.specify/rtm.md`](../../../.specify/rtm.md) — note each `REQ-NNN`'s current Status (rows are + keyed by this issue number) - Any relevant existing source files mentioned in the issue/comments - The current branch state (`git status`, `git log --oneline -10`) @@ -101,9 +100,9 @@ Wait for the user to answer before continuing. ## Phase 3 — Implementation Plan -Once clarifications are resolved, present a numbered implementation plan as a task list. **If -the spec has a `tasks.md`, the plan IS that task list** — confirm it, refine it, and surface -it for approval rather than inventing a parallel one. Each item must be: +Once clarifications are resolved, present a numbered implementation plan as a task list, +**derived from the issue's `REQ-NNN` requirements** (one or more tasks per requirement, in +red/green order). Each item must be: - A single atomic unit of work (one behavior, one file change, one migration) - Written as a sentence that implies the test name: "Tag detail page returns 404 when tag does not exist" diff --git a/.claude/skills/review-pr/SKILL.md b/.claude/skills/review-pr/SKILL.md index da715ec6..1907c3e9 100644 --- a/.claude/skills/review-pr/SKILL.md +++ b/.claude/skills/review-pr/SKILL.md @@ -8,7 +8,7 @@ description: Multi-persona SDD code review of a Gitea PR. Each persona pairs its You will perform a thorough multi-persona code review of the given PR and post each persona's findings as a **separate comment**. Under SDD, the review verifies the diff against two contracts: the project [constitution](../../../.specify/constitution.md) and the feature's -spec (`spec.md` — every `REQ-NNN` must be implemented **and** covered by a test). +spec (the linked **Gitea issue body** — every `REQ-NNN` must be implemented **and** covered by a test). ## Argument @@ -22,9 +22,8 @@ Parse it to extract `owner`, `repo`, and `pull_number`. Read before reviewing: - [`.specify/constitution.md`](../../../.specify/constitution.md) — rules the code must obey (esp. §4 Do-Not-Touch) - [`.specify/AGENTS.md`](../../../.specify/AGENTS.md) — constraints -- The feature's spec, if the PR references one: `.specify/features//spec.md`, plus its - `api-contract.yaml`, `threat-model.md`, and `tasks.md`. Find the `REQ-NNN` ids it claims to - satisfy (from the PR description, `Closes #n`, or the spec's Traceability table). +- The feature's spec — the **Gitea issue** the PR closes (`Closes #n`). Read its body for the + `REQ-NNN` requirements, acceptance criteria, inline API stub, and any STRIDE/threat notes. - [`.specify/rtm.md`](../../../.specify/rtm.md) — the requirement→test→status matrix ## Step 1 — Gather PR context diff --git a/.gitea/ISSUE_TEMPLATE/feature.md b/.gitea/ISSUE_TEMPLATE/feature.md index 50cd8b5e..a9d56b09 100644 --- a/.gitea/ISSUE_TEMPLATE/feature.md +++ b/.gitea/ISSUE_TEMPLATE/feature.md @@ -9,10 +9,9 @@ assignees: [] --- ## Context & Why @@ -46,7 +45,7 @@ assignees: [] ## API / Contract Stub -/api-contract.yaml. Name new paths/methods/status codes and the @RequirePermission on each mutating endpoint.> + ## Data Model Changes diff --git a/.gitea/workflows/sdd-gate.yml b/.gitea/workflows/sdd-gate.yml index 9b0483cc..6763ddbc 100644 --- a/.gitea/workflows/sdd-gate.yml +++ b/.gitea/workflows/sdd-gate.yml @@ -1,78 +1,64 @@ name: SDD Gate -# Spec-Driven Development quality gate. Runs on PRs and validates the SDD artifacts that -# the PR touches. The first three jobs are NON-BLOCKING for now (continue-on-error) so the -# team can adopt the workflow without CI immediately failing. +# Spec-Driven Development quality gate. Runs on PRs. # -# TODO: flip spec-lint, contract-validate, and traceability-check to BLOCKING -# (remove `continue-on-error: true`) once SDD adoption has settled — target: after the -# first 5 real features have shipped through the .specify/ workflow. Tracked in ADR-041. +# This project is ISSUE-ONLY: a feature's spec lives in its Gitea issue body, not a committed +# spec.md (see ADR-041). So CI cannot lint the spec text itself — instead it validates the SDD +# artifacts that DO live in git: the RTM, any committed OpenAPI contract, and the constitution. +# +# The first two jobs are NON-BLOCKING for now (continue-on-error) so the team can adopt the +# workflow without CI immediately failing. +# +# TODO: flip rtm-check and contract-validate to BLOCKING (remove `continue-on-error: true`) +# once SDD adoption has settled — target: after the first 5 features have shipped through +# the workflow. Tracked in ADR-041. on: pull_request: jobs: - # ─── Spec structure lint ────────────────────────────────────────────────────── - # Every modified .specify/features/*/spec.md must contain the required SDD sections - # and at least one REQ-NNN requirement. Pure grep — no external tooling. - spec-lint: - name: Spec Lint + # ─── RTM check ──────────────────────────────────────────────────────────────── + # The Requirements Traceability Matrix is the one per-feature SDD artifact in git. Every + # data row must point at a Gitea issue (`#n`) and name at least one test. Warn otherwise. + # Pure awk — no external tooling. Columns: | REQ-ID | Summary | Issue | Feature | Impl | Test | Status | + rtm-check: + name: RTM Check runs-on: ubuntu-latest continue-on-error: true # TODO: remove to make blocking (see header) steps: - uses: actions/checkout@v4 - with: - fetch-depth: 0 - - name: Lint changed spec.md files + - name: Validate .specify/rtm.md rows shell: bash run: | set -uo pipefail - base="origin/${{ github.event.pull_request.base.ref }}" - git fetch --no-tags --depth=1 origin "${{ github.event.pull_request.base.ref }}" || true + rtm=".specify/rtm.md" + test -f "$rtm" || { echo "::error::$rtm is missing"; exit 1; } - required=( - "## Context & Why" - "## Requirements" - "## Acceptance Criteria" - "## Out of Scope" - "## Security Considerations" - "## Traceability" - ) + # Self-test: a good row passes, a row with an empty Issue or Test is flagged. + check_row() { awk -F'|' '{ + issue=$4; test_col=$7; + gsub(/^[ \t]+|[ \t]+$/,"",issue); gsub(/^[ \t]+|[ \t]+$/,"",test_col); + if (issue !~ /#/ || test_col=="") exit 1; else exit 0 }'; } + echo '| REQ-001 | x | #42 | f | impl | SomeTest#works | Done |' | check_row \ + || { echo "FAIL: rtm-check self-test rejected a valid row"; exit 1; } + echo '| REQ-002 | x | | f | impl | | Planned |' | check_row \ + && { echo "FAIL: rtm-check self-test accepted an empty row"; exit 1; } - # Self-test: a fixture with all sections + a REQ id must pass the section check. - fixture="$(mktemp)" - { for s in "${required[@]}"; do echo "$s"; done; echo "- **REQ-001** (Ubiquitous) — The x shall y."; } > "$fixture" - for s in "${required[@]}"; do - grep -qF "$s" "$fixture" || { echo "FAIL: spec-lint self-test missing '$s'"; exit 1; } - done - - changed="$(git diff --name-only "$base"...HEAD -- '.specify/features/*/spec.md' || true)" - if [ -z "$changed" ]; then - echo "No spec.md files changed — nothing to lint." - exit 0 - fi - - rc=0 - for f in $changed; do - [ -f "$f" ] || continue # deleted file - echo "── linting $f" - for s in "${required[@]}"; do - if ! grep -qF "$s" "$f"; then - echo "::error file=$f::missing required section '$s'" - rc=1 - fi - done - if ! grep -qE 'REQ-[0-9]{3}' "$f"; then - echo "::error file=$f::no REQ-NNN requirement found" - rc=1 - fi - done - exit $rc + bad=0 + while IFS= read -r line; do + echo "$line" | check_row || { + req=$(echo "$line" | awk -F'|' '{gsub(/^[ \t]+|[ \t]+$/,"",$2); print $2}') + echo "::warning file=$rtm::row $req is missing an Issue (#n) or a Test" + bad=$((bad+1)) + } + done < <(grep -E '^\| REQ-[0-9]{3} ' "$rtm") + echo "$bad RTM row(s) incomplete (warning only)." # ─── Contract validation ────────────────────────────────────────────────────── - # Validate any modified api-contract.yaml with Spectral (OpenAPI 3.1). REST stack — - # no GraphQL. Skips cleanly when no contract changed. + # Validate any committed OpenAPI contract with Spectral (OpenAPI 3.1). REST stack — no + # GraphQL. Contracts are optional and ride a feature branch when present; the _example one + # is always linted. Skips cleanly when none changed. contract-validate: name: Contract Validate runs-on: ubuntu-latest @@ -92,9 +78,10 @@ jobs: set -uo pipefail base="origin/${{ github.event.pull_request.base.ref }}" git fetch --no-tags --depth=1 origin "${{ github.event.pull_request.base.ref }}" || true - changed="$(git diff --name-only "$base"...HEAD -- '.specify/features/*/api-contract.yaml' || true)" + # Any *.yaml under .specify/ or any file named like a contract. + changed="$(git diff --name-only "$base"...HEAD -- '.specify/**/*.yaml' '**/api-contract.yaml' '**/*.openapi.yaml' || true)" if [ -z "$changed" ]; then - echo "No api-contract.yaml changed — nothing to validate." + echo "No OpenAPI contract changed — nothing to validate." exit 0 fi rc=0 @@ -105,39 +92,6 @@ jobs: done exit $rc - # ─── Traceability check ─────────────────────────────────────────────────────── - # Warn (non-blocking) when a changed spec.md references a REQ-NNN that is absent from - # .specify/rtm.md. Keeps the matrix honest without hard-failing during adoption. - traceability-check: - name: Traceability Check - runs-on: ubuntu-latest - continue-on-error: true # TODO: remove to make blocking (see header) - steps: - - uses: actions/checkout@v4 - with: - fetch-depth: 0 - - - name: Cross-check spec REQ-IDs against rtm.md - shell: bash - run: | - set -uo pipefail - base="origin/${{ github.event.pull_request.base.ref }}" - git fetch --no-tags --depth=1 origin "${{ github.event.pull_request.base.ref }}" || true - changed="$(git diff --name-only "$base"...HEAD -- '.specify/features/*/spec.md' || true)" - [ -z "$changed" ] && { echo "No spec.md changed."; exit 0; } - test -f .specify/rtm.md || { echo "::warning::.specify/rtm.md missing"; exit 0; } - missing=0 - for f in $changed; do - [ -f "$f" ] || continue - for req in $(grep -oE 'REQ-[0-9]{3}' "$f" | sort -u); do - if ! grep -qF "$req" .specify/rtm.md; then - echo "::warning file=$f::$req is not present in .specify/rtm.md" - missing=$((missing+1)) - fi - done - done - echo "$missing REQ-ID(s) missing from rtm.md (warning only)." - # ─── Constitution change impact ─────────────────────────────────────────────── # When .specify/constitution.md is modified, list every file that references it (and so # may need a Sync Impact update) and post it as a PR comment. Best-effort: if no token is @@ -164,7 +118,6 @@ jobs: fi echo "changed=true" >> "$GITHUB_OUTPUT" echo "Files referencing constitution.md (review for Sync Impact):" - # rg-free: grep recursively, excluding the file itself and VCS/build dirs. grep -rIl --exclude-dir=.git --exclude-dir=node_modules --exclude-dir=target \ -e 'constitution.md' -e 'constitution §' . \ | grep -v '^\./.specify/constitution.md$' | sort > /tmp/refs.txt || true @@ -183,7 +136,6 @@ jobs: if: steps.impact.outputs.changed == 'true' shell: bash env: - # Gitea Actions exposes the repo token as GITHUB_TOKEN; the API is Gitea-compatible. TOKEN: ${{ secrets.GITHUB_TOKEN }} SERVER: ${{ github.server_url }} REPO: ${{ github.repository }} diff --git a/.specify/AGENTS.md b/.specify/AGENTS.md index 0f52319a..1b2a4df3 100644 --- a/.specify/AGENTS.md +++ b/.specify/AGENTS.md @@ -69,8 +69,9 @@ App port `8080`; management port `8081`. Backend app id: `org.raddatz.familienar ## Spec-Driven Development -Before implementing a feature, read its spec at `.specify/features//spec.md` and its -contract at `.specify/features//api-contract.yaml` if present. The spec's EARS -requirements (`REQ-NNN`) are the contract; each maps to a test. Worked reference: -[`.specify/features/_example/`](./features/_example/). Full workflow: +A feature's spec is its **Gitea issue body** — there is no committed `spec.md`. The issue's +EARS requirements (`REQ-NNN`) and acceptance criteria are the contract; each maps to a test, +traced in [`.specify/rtm.md`](./rtm.md) (`REQ-ID → issue # → test`). Read the issue before +implementing. The committed [`.specify/features/_example/`](./features/_example/) is a +template/reference showing the full artifact set, not a live feature. Full workflow: [SPEC_DRIVEN_DEVELOPMENT.md](../SPEC_DRIVEN_DEVELOPMENT.md). diff --git a/.specify/personas/developer.md b/.specify/personas/developer.md index 94481b72..45ef8f4d 100644 --- a/.specify/personas/developer.md +++ b/.specify/personas/developer.md @@ -19,12 +19,12 @@ structures or hand-wave the hard integration points. 4. Are new error conditions expressed as named `ErrorCode`s, with the four-site update (`ErrorCode.java`, `errors.ts`, `getErrorMessage()`, `messages/{de,en,es}.json`) called out as tasks? 5. Does every entity/DTO field the spec adds get `@Schema(requiredMode = REQUIRED)` where always-populated, and is `npm run generate:api` listed as a task after backend changes? 6. Are frontend changes inside the correct `$lib//` boundary, with any cross-domain import either pre-allowed in `eslint.config.js` or flagged for an explicit allow-entry? -7. Does each `REQ-NNN` map to a concrete test at the right level (unit / `@WebMvcTest` slice / Playwright E2E per COLLABORATING.md's table) in `tasks.md`? +7. Does each `REQ-NNN` imply a concrete test at the right level (unit / `@WebMvcTest` slice / Playwright E2E per COLLABORATING.md's table) — i.e. is it specified concretely enough to write that test? 8. Is lazy-loading handled — does any returned entity with a lazy collection get a view (ADR-036) instead of being serialized raw? 9. Does the design avoid premature abstraction (KISS over DRY) — no new base class/util introduced before a third caller exists? 10. Are data-model changes expressed as a single forward-only Flyway migration with the next free `V` number verified against disk? 11. Does the spec avoid backwards-compat shims for code paths that have no existing callers? -12. Is the `tasks.md` decomposition red/green-ordered — a failing test task precedes each implementation task? +12. Are the requirements decomposable into a red/green-ordered task list — each behavior small enough that a failing test can precede its implementation? ## EARS patterns to watch for diff --git a/.specify/rtm.md b/.specify/rtm.md index c3d589b7..d03e7758 100644 --- a/.specify/rtm.md +++ b/.specify/rtm.md @@ -1,19 +1,22 @@ # Requirements Traceability Matrix (RTM) -> Living document. One row per `REQ-NNN` across all in-flight and shipped features. It links -> a requirement to the design that realises it, the code that implements it, and the -> test(s) that prove it — so any requirement can be traced end to end, and any orphan -> (a requirement with no test, or a test with no requirement) is visible. +> Living document. One row per `REQ-NNN` across all in-flight and shipped features. The spec +> itself lives in the **Gitea issue** (issue-only — there is no committed `spec.md`); this +> matrix is the part of the spec that *is* committed: it links each requirement to its issue, +> the code that implements it, and the test(s) that prove it — so any requirement traces end +> to end, and any orphan (a requirement with no test) is visible on `main`. ## How to update -1. When a `spec.md` is approved, copy its `## Traceability` rows here with `Status: Planned`. -2. As tasks land, fill `Implementation File(s)` and flip `Status` → `In progress` → `Done`. -3. `REQ-ID`s are **scoped per feature**, so always qualify with the Feature column — `REQ-001` - in *avatar* is not `REQ-001` in another feature. -4. The `sdd-gate.yml` CI job (`traceability-check`) warns (non-blocking, for now) when a - `spec.md` contains a `REQ-NNN` that does not appear in this file. Keep it in sync to keep - the warning quiet; it flips to blocking once adoption settles (see the workflow's TODO). +1. When a feature's issue is approved (via `/review-issue`), add one row per `REQ-NNN` with the + `Issue` set to the Gitea issue number and `Status: Planned`. Commit these rows on the feature + branch (they merge with the feature's PR). +2. As tasks land, fill `Implementation File(s)` + `Test(s)` and flip `Status` → + `In progress` → `Done`. +3. `REQ-ID`s are **scoped per feature**, so always read them together with the `Issue` column — + `REQ-001` for issue #142 is not `REQ-001` for issue #150. +4. The `sdd-gate.yml` CI job (`rtm-check`) warns (non-blocking, for now) when a row is missing + its `Issue` or `Test(s)`. It flips to blocking once adoption settles (see the workflow's TODO). ## Status legend @@ -21,16 +24,16 @@ ## Matrix -| REQ-ID | Requirement Summary | Feature | Design Artifact | Implementation File(s) | Test(s) | Status | +| REQ-ID | Requirement Summary | Issue | Feature | Implementation File(s) | Test(s) | Status | |---|---|---|---|---|---|---| -| REQ-001 | Store avatar at `avatars/{userId}`, overwrite | profile-picture-upload (_example) | features/_example/design.md; adr-001 | `UserService` (planned) | `UserServiceAvatarTest#storesUnderUserKey`, `#replaceLeavesNoOrphan` | Planned | -| REQ-002 | Upload self avatar → 200 + avatarUrl | profile-picture-upload (_example) | features/_example/design.md; api-contract.yaml | `UserAvatarController`, `UserService` (planned) | `UserAvatarControllerTest#uploadReturnsAvatarUrl` | Planned | -| REQ-003 | Delete self avatar → avatarUrl null | profile-picture-upload (_example) | features/_example/api-contract.yaml | `UserAvatarController` (planned) | `UserAvatarControllerTest#deleteClearsAvatar` | Planned | -| REQ-004 | No avatar → null + initials placeholder | profile-picture-upload (_example) | features/_example/design.md | `UserProfileView`, avatar component (planned) | `avatar-placeholder.svelte.spec.ts` | Planned | -| REQ-005 | ADMIN_USER may delete others' avatar | profile-picture-upload (_example) | features/_example/api-contract.yaml | `UserAvatarController` (planned) | `UserAvatarControllerTest#adminDeletesOthersAvatar` | Planned | -| REQ-006 | Unauthenticated → 401, store nothing | profile-picture-upload (_example) | features/_example/threat-model.md | `SecurityConfig`, controller (planned) | `UserAvatarControllerTest#unauthenticatedReturns401` | Planned | -| REQ-007 | Non-image → 400 UNSUPPORTED_FILE_TYPE | profile-picture-upload (_example) | features/_example/design.md | `UserService` (planned) | `UserAvatarControllerTest#rejectsNonImage` | Planned | -| REQ-008 | Over 2 MB → 400 AVATAR_TOO_LARGE | profile-picture-upload (_example) | features/_example/design.md | `UserService`, `ErrorCode` (planned) | `UserAvatarControllerTest#rejectsOversize` | Planned | -| REQ-009 | Non-admin on others → 403 FORBIDDEN | profile-picture-upload (_example) | features/_example/threat-model.md | `UserAvatarController` (planned) | `UserAvatarControllerTest#nonAdminForbiddenOnOthers` | Planned | +| REQ-001 | Store avatar at `avatars/{userId}`, overwrite | #example | profile-picture-upload (_example) | `UserService` (planned) | `UserServiceAvatarTest#storesUnderUserKey`, `#replaceLeavesNoOrphan` | Planned | +| REQ-002 | Upload self avatar → 200 + avatarUrl | #example | profile-picture-upload (_example) | `UserAvatarController`, `UserService` (planned) | `UserAvatarControllerTest#uploadReturnsAvatarUrl` | Planned | +| REQ-003 | Delete self avatar → avatarUrl null | #example | profile-picture-upload (_example) | `UserAvatarController` (planned) | `UserAvatarControllerTest#deleteClearsAvatar` | Planned | +| REQ-004 | No avatar → null + initials placeholder | #example | profile-picture-upload (_example) | `UserProfileView`, avatar component (planned) | `avatar-placeholder.svelte.spec.ts` | Planned | +| REQ-005 | ADMIN_USER may delete others' avatar | #example | profile-picture-upload (_example) | `UserAvatarController` (planned) | `UserAvatarControllerTest#adminDeletesOthersAvatar` | Planned | +| REQ-006 | Unauthenticated → 401, store nothing | #example | profile-picture-upload (_example) | `SecurityConfig`, controller (planned) | `UserAvatarControllerTest#unauthenticatedReturns401` | Planned | +| REQ-007 | Non-image → 400 UNSUPPORTED_FILE_TYPE | #example | profile-picture-upload (_example) | `UserService` (planned) | `UserAvatarControllerTest#rejectsNonImage` | Planned | +| REQ-008 | Over 2 MB → 400 AVATAR_TOO_LARGE | #example | profile-picture-upload (_example) | `UserService`, `ErrorCode` (planned) | `UserAvatarControllerTest#rejectsOversize` | Planned | +| REQ-009 | Non-admin on others → 403 FORBIDDEN | #example | profile-picture-upload (_example) | `UserAvatarController` (planned) | `UserAvatarControllerTest#nonAdminForbiddenOnOthers` | Planned | - + diff --git a/.specify/templates/api-contract-stub.md b/.specify/templates/api-contract-stub.md index cf3d1f75..dac59a5b 100644 --- a/.specify/templates/api-contract-stub.md +++ b/.specify/templates/api-contract-stub.md @@ -6,19 +6,21 @@ TypeScript client from it with `npm run generate:api` (`openapi-typescript` → `frontend/src/lib/generated/api.ts`). There is no GraphQL in this stack. > **The live spec is generated from the Java controllers — it is the source of truth.** A -> hand-written contract under `.specify/features//api-contract.yaml` is a *design -> artifact*: it pins the intended shape during spec review and is checked against the -> generated spec once the endpoint exists. Keep it OpenAPI **3.1**, and keep -> `@Schema(requiredMode = REQUIRED)` on the Java side as the real driver of `required`. +> hand-written stub is a *design artifact*: it pins the intended shape during spec review. +> Issue-only: paste the stub inline into the issue's `## API / Contract Stub` section. Keep it +> OpenAPI **3.1**, and keep `@Schema(requiredMode = REQUIRED)` on the Java side as the real +> driver of `required`. ## How to use this stub -1. Copy the skeleton below to `.specify/features//api-contract.yaml`. -2. Fill in the paths/methods/schemas your feature adds. Every mutating path documents the - `403`/`401` responses and the `cookieAuth` security requirement (matching the real - `@RequirePermission` gate). -3. The `sdd-gate.yml` CI job lints any changed `api-contract.yaml` with Spectral - (`npx @stoplight/spectral-cli lint`). Run it locally the same way before pushing. +1. Fill in the skeleton below with the paths/methods/schemas your feature adds, and paste it + into the issue's `## API / Contract Stub` section. +2. Every mutating path documents the `403`/`401` responses and the `cookieAuth` security + requirement (matching the real `@RequirePermission` gate). +3. If you prefer a standalone, lintable file (e.g. for a large contract), commit it on the + **feature branch** as `.openapi.yaml` — the `sdd-gate.yml` CI job lints any + committed OpenAPI contract with Spectral (`npx @stoplight/spectral-cli lint`). It never + needs to predate the issue. 4. After the endpoint ships, run `npm run generate:api` and diff the generated types against this contract; reconcile any drift (the generated spec wins — update the contract). diff --git a/.specify/templates/feature-spec.md b/.specify/templates/feature-spec.md index 4eb61303..1c611df4 100644 --- a/.specify/templates/feature-spec.md +++ b/.specify/templates/feature-spec.md @@ -1,10 +1,10 @@ # I want so "> @@ -13,10 +13,10 @@ -Constitution principles this feature depends on: -- [§ ](../../constitution.md#) — +Constitution principles this feature depends on (see `.specify/constitution.md`): +- § — -Related: . +Related: . ## User Journey @@ -51,7 +51,7 @@ Related: . ## API / Contract Stub - + ## Data Model Changes @@ -59,7 +59,7 @@ Related: . ## Security Considerations - + ## Open Questions @@ -75,7 +75,7 @@ Related: . | REQ-001 | | | Planned | | REQ-002 | | | Planned | - + ## Persona Review Results diff --git a/.specify/templates/threat-model.md b/.specify/templates/threat-model.md index db063555..6934a3a0 100644 --- a/.specify/templates/threat-model.md +++ b/.specify/templates/threat-model.md @@ -1,12 +1,14 @@ # Threat Model — -**Feature spec:** [./spec.md](./spec.md) +**Feature spec:** Gitea issue # **Date:** **Author:** diff --git a/CLAUDE.md b/CLAUDE.md index 1181c41c..b424a47f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -18,7 +18,7 @@ See [CODESTYLE.md](./CODESTYLE.md) for coding standards: Clean Code, DRY/KISS tr ## Spec-Driven Development -This project uses Spec-Driven Development. **Before implementing a feature, read [`.specify/AGENTS.md`](./.specify/AGENTS.md)** (the short, machine-readable agent rules) and obey the [`.specify/constitution.md`](./.specify/constitution.md) it references. A feature's contract is its `.specify/features//spec.md` (EARS `REQ-NNN` requirements) plus any `api-contract.yaml`. Full workflow: [SPEC_DRIVEN_DEVELOPMENT.md](./SPEC_DRIVEN_DEVELOPMENT.md); worked example: [`.specify/features/_example/`](./.specify/features/_example/). The LLM reminders below restate constitution rules — the constitution and AGENTS.md are authoritative if they ever diverge. +This project uses Spec-Driven Development. **Before implementing a feature, read [`.specify/AGENTS.md`](./.specify/AGENTS.md)** (the short, machine-readable agent rules) and obey the [`.specify/constitution.md`](./.specify/constitution.md) it references. A feature's contract is its **Gitea issue body** (EARS `REQ-NNN` requirements) — there is no committed `spec.md`; the RTM ([`.specify/rtm.md`](./.specify/rtm.md)) traces each `REQ-ID → issue # → test`. Full workflow: [SPEC_DRIVEN_DEVELOPMENT.md](./SPEC_DRIVEN_DEVELOPMENT.md); template/reference: [`.specify/features/_example/`](./.specify/features/_example/). The LLM reminders below restate constitution rules — the constitution and AGENTS.md are authoritative if they ever diverge. --- diff --git a/SPEC_DRIVEN_DEVELOPMENT.md b/SPEC_DRIVEN_DEVELOPMENT.md index 1440bb52..ac942538 100644 --- a/SPEC_DRIVEN_DEVELOPMENT.md +++ b/SPEC_DRIVEN_DEVELOPMENT.md @@ -17,17 +17,28 @@ multi-persona review → red/green TDD). It does not replace any of that — see | # | Step | Who | Artifacts created / touched | |---|---|---|---| | 1 | **Idea → Gitea issue** using the Feature template | author | Gitea issue (labels `spec-required`, `needs-review`) from `.gitea/ISSUE_TEMPLATE/feature.md` | -| 2 | **Write the spec** — Context, User Journey, EARS `REQ-NNN` requirements, measurable acceptance criteria, Out of Scope | author | issue body **and** `.specify/features//spec.md` | -| 3 | **Add design artifacts** as needed | author | `design.md`; `api-contract.yaml` (any new endpoint); `threat-model.md` (uploads / new mutating endpoint / AI tool); feature-local `adr-NNN-*.md` or a `docs/adr/` entry for project-wide decisions | -| 4 | **Persona spec review** — the six checklists gate the spec | RE, Developer, Security, DevOps, UI/UX, Architect | `checklist-results.md` + the `## Persona Review Results` table; findings folded into the spec | -| 5 | **Resolve Open Questions & blocking FAILs** — spec does not proceed while any remain | author | spec updated; `Open Questions` emptied | -| 6 | **Decompose into tasks** in red/green order; seed the RTM | author | `tasks.md`; rows added to [`.specify/rtm.md`](./.specify/rtm.md) (`Status: Planned`) | -| 7 | **Implement** in a worktree, TDD per task (failing test → green → refactor → commit); agent reads `AGENTS.md` + `spec.md` + `api-contract.yaml` | implementer (often an AI agent) | code + tests; `npm run generate:api` after backend changes; RTM `Status` → `Done` | -| 8 | **PR → multi-persona PR review → merge**; archive the feature | reviewers | PR (`Closes #n`); on merge, move the feature dir under `.specify/features/_archive//` (or tag it shipped) | +| 2 | **Write the spec _in the issue body_** — Context, User Journey, EARS `REQ-NNN` requirements, measurable acceptance criteria, Out of Scope | author | the Gitea issue body **is** the spec (single source of truth — no committed `spec.md`) | +| 3 | **Capture durable design decisions** as needed | author | a `docs/adr/` ADR for any project-wide/irreversible decision; an OpenAPI contract and a STRIDE threat model inline in the issue (use the `.specify/templates/` as the writing aid) | +| 4 | **Persona spec review** — the six checklists gate the spec | RE, Developer, Security, DevOps, UI/UX, Architect | `/review-issue` posts each persona's checklist verdict as a Gitea comment; findings folded into the issue body | +| 5 | **Resolve Open Questions & blocking FAILs** — spec does not proceed while any remain | author | issue body updated; `Open Questions` emptied | +| 6 | **Seed the RTM** — one row per `REQ-NNN`, pointing at the issue | author | rows added to [`.specify/rtm.md`](./.specify/rtm.md) (`Issue: #n`, `Status: Planned`) — committed with the feature branch | +| 7 | **Implement** in a worktree, TDD per task (failing test → green → refactor → commit); agent reads `AGENTS.md` + the **issue body** (the spec) | implementer (often an AI agent) | code + tests; `npm run generate:api` after backend changes; RTM `Status` → `Done` | +| 8 | **PR → multi-persona PR review → merge** | reviewers | PR (`Closes #n`); the closed issue is the archived spec, the RTM rows record what shipped | -The personas at step 4 review the **spec**; the same personas at step 8 (via the existing -`review-pr` / `deliver-issue` skills) review the **code**. Step 4 catches at spec time what -used to surface only at step 8. +The personas at step 4 review the **spec (the issue)**; the same personas at step 8 (via the +existing `review-pr` / `deliver-issue` skills) review the **code**. Step 4 catches at spec time +what used to surface only at step 8. + +**Skills that drive this:** `/draft-spec` (requirements engineer authors steps 1–2 → creates +the issue) → `/review-issue` (step 4 gate) → `/implement` (steps 6–7) → `/review-pr` (step 8). +`/deliver-issue` runs review → discuss → implement → review-loop end-to-end. + +> **Why issue-only?** The Gitea issue body is the single source of truth for a spec — there is +> no committed per-feature `spec.md` to drift out of sync with it. The only SDD artifact that +> lives in git per feature is the RTM row (`REQ-ID → issue # → test`). The worked example under +> [`.specify/features/_example/`](./.specify/features/_example/) is a **template/reference**, not +> a live feature — it shows the full artifact set in one place; real features keep the spec in +> the issue. ## 2. How a Gitea issue becomes a spec @@ -63,7 +74,7 @@ measurable acceptance criterion. See the full version in ## 3. How to run a persona review Each persona reads the spec, walks its checklist in `.specify/personas/.md`, and -posts a Gitea comment (or fills `checklist-results.md`) with **PASS / FAIL / QUESTION** per +posts a Gitea comment with **PASS / FAIL / QUESTION** per item and a verdict. A `FAIL` from Security or Architect is a hard block. Concrete example: > ### Security — Spec Review @@ -86,15 +97,16 @@ empties the finding, and the persona re-reviews until `APPROVE`. This mirrors th Once the spec is `APPROVE`d and tasks are seeded, the implementer points the agent at the artifacts. Example prompt: -> Implement `.specify/features/profile-picture-upload/`. Read `.specify/AGENTS.md` and obey -> the constitution it references. The contract is `spec.md` (REQ-001…REQ-009) and -> `api-contract.yaml`. Work through `tasks.md` in order, red/green TDD — write the failing -> test named in each task first, confirm it fails, then make it pass. After backend model -> changes run `npm run generate:api`. Each REQ has a test in the Traceability table; do not -> mark a task done until its test is green. Update `.specify/rtm.md` Status as you go. +> Implement Gitea issue #142 (profile picture upload). Read `.specify/AGENTS.md` and obey the +> constitution it references. The contract is the issue body — its EARS requirements +> REQ-001…REQ-009 and acceptance criteria. Build a red/green task list from them, write the +> failing test for each REQ first, confirm it fails, then make it pass. After backend model +> changes run `npm run generate:api`. Do not mark a REQ done until its test is green; flip its +> row in `.specify/rtm.md` to Done as you go. -The agent now has: the rules (`AGENTS.md` → constitution), the exact requirements with ids, -the API shape, and a test-first task list — so its output is bounded and verifiable. +The agent now has: the rules (`AGENTS.md` → constitution) and the exact requirements with ids +from the issue — so its output is bounded and verifiable. (The `/implement` skill fetches the +issue body for you via the Gitea API.) ## 5. Maintenance rules @@ -105,13 +117,14 @@ the API shape, and a test-first task list — so its output is bounded and verif in ADR-041's revision log (or a superseding ADR for MAJOR). - **AGENTS.md** — keep it under 200 lines. It cross-references the constitution; it must never duplicate or contradict it. -- **ADRs** — project-wide decisions go in [`docs/adr/`](./docs/adr/) (next free `NNN`, verify - on disk). Immutable once `Accepted`; supersede, don't edit. Feature-local decisions stay - beside the feature spec. -- **Feature specs** — archive on merge: move `.specify/features//` to - `.specify/features/_archive//`. The spec stays as the record of what shipped. -- **RTM** ([`.specify/rtm.md`](./.specify/rtm.md)) — append rows when a spec is approved; - flip `Status` as tests go green; never delete a shipped requirement's row. CI warns on drift. +- **ADRs** — project-wide/irreversible decisions go in [`docs/adr/`](./docs/adr/) (next free + `NNN`, verify on disk). Immutable once `Accepted`; supersede, don't edit. +- **Feature specs** — the spec is the Gitea issue body; there is no committed `spec.md`. + "Archiving" is just closing the issue (`Closes #n` on merge). The closed issue + the RTM + rows are the record of what shipped. +- **RTM** ([`.specify/rtm.md`](./.specify/rtm.md)) — append one row per `REQ-NNN` when a spec + is approved, each pointing at its issue (`#n`); flip `Status` as tests go green; never delete + a shipped requirement's row. - **Personas** — update `.specify/personas/*.md` checklists when a recurring blind spot appears; keep them aligned with the richer `.claude/personas/`. @@ -133,11 +146,11 @@ the API shape, and a test-first task list — so its output is bounded and verif |---|---| | Non-negotiable rules | `.specify/constitution.md` | | Agent rules (read every time) | `.specify/AGENTS.md` | -| Templates | `.specify/templates/{feature-spec,adr,threat-model,api-contract-stub}.md` | +| Templates (writing aids) | `.specify/templates/{feature-spec,adr,threat-model,api-contract-stub}.md` | | Persona checklists | `.specify/personas/*.md` | -| In-flight feature | `.specify/features//{spec,design,tasks,checklist-results}.md` + `api-contract.yaml` + `threat-model.md` | -| Worked example | `.specify/features/_example/` | -| Traceability matrix | `.specify/rtm.md` | +| In-flight feature spec | the **Gitea issue body** (not a committed file) | +| Worked example (template/reference) | `.specify/features/_example/` | +| Traceability matrix | `.specify/rtm.md` (`REQ-ID → issue # → test`) | | ADR archive | `docs/adr/NNN-*.md` | | Issue templates | `.gitea/ISSUE_TEMPLATE/{feature,bug}.md` | | CI gate | `.gitea/workflows/sdd-gate.yml` | @@ -149,8 +162,8 @@ the API shape, and a test-first task list — so its output is bounded and verif **Commands:** ```bash -# validate a contract locally (same as CI) -npx @stoplight/spectral-cli lint .specify/features//api-contract.yaml +# validate an OpenAPI contract locally (if you drafted one — same as CI) +npx @stoplight/spectral-cli lint .yaml # regenerate the TS client after a backend model/endpoint change cd frontend && npm run generate:api # backend must run with --spring.profiles.active=dev diff --git a/docs/adr/041-sdd-adoption.md b/docs/adr/041-sdd-adoption.md index e414a418..a93d31bb 100644 --- a/docs/adr/041-sdd-adoption.md +++ b/docs/adr/041-sdd-adoption.md @@ -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//` - 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 |