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>
90 lines
3.9 KiB
Markdown
90 lines
3.9 KiB
Markdown
<!--
|
||
Feature Spec template — copy this into a Gitea issue body (or .specify/features/<name>/spec.md).
|
||
Replace every <placeholder>. Delete this comment block before submitting.
|
||
EARS = Easy Approach to Requirements Syntax. Every requirement uses one of the five patterns
|
||
shown in ## Requirements and carries a unique REQ-NNN id (three-digit, scoped to THIS feature).
|
||
Companion artifacts live beside this file: design.md, api-contract.yaml, threat-model.md,
|
||
adr-NNN-*.md, tasks.md, checklist-results.md.
|
||
-->
|
||
|
||
# <Feature title — match the Gitea issue: "As a <role> I want <capability> so <reason>">
|
||
|
||
## Context & Why
|
||
|
||
<Business motivation in 2–4 sentences: who needs this and why now.>
|
||
|
||
Constitution principles this feature depends on:
|
||
- [§<n> <principle name>](../../constitution.md#<anchor>) — <why it applies>
|
||
|
||
Related: <links to prior issues / ADRs / specs>.
|
||
|
||
## User Journey
|
||
|
||
<Plain-prose steps the user takes to get value, from the user's perspective — per COLLABORATING.md. Anything not in this journey is out of scope.>
|
||
|
||
## Requirements
|
||
|
||
> One requirement per line, each with a `REQ-NNN` id and one EARS pattern. Include the
|
||
> patterns the feature actually needs — do not force all five, but a mutating feature almost
|
||
> always needs at least one Event-driven and one Unwanted-behavior requirement.
|
||
|
||
- **REQ-001** (Ubiquitous) — The `<system component>` shall `<always-true behavior>`.
|
||
- **REQ-002** (Event-driven) — When `<trigger / endpoint receives X>`, the `<system component>` shall `<response>`.
|
||
- **REQ-003** (State-driven) — While `<system is in state X>`, the `<system component>` shall `<behavior>`.
|
||
- **REQ-004** (Optional-feature) — Where `<the caller has Permission.X / a feature flag is set>`, the `<system component>` shall `<behavior>`.
|
||
- **REQ-005** (Unwanted-behavior) — If `<undesired condition, e.g. caller is unauthenticated / input invalid>`, then the `<system component>` shall `<safe response, e.g. return 401 / ErrorCode.X>`.
|
||
|
||
## Acceptance Criteria
|
||
|
||
> One measurable criterion per REQ-NNN. Numbers, limits, status codes — never adjectives.
|
||
|
||
- **REQ-001** — <measurable, e.g. "the response always includes a non-null `id` (UUID)">.
|
||
- **REQ-002** — <measurable, e.g. "POST returns 201 and the persisted row within the same request">.
|
||
- **REQ-003** — <measurable>.
|
||
- **REQ-004** — <measurable, e.g. "a caller without Permission.X receives 403 with ErrorCode.FORBIDDEN">.
|
||
- **REQ-005** — <measurable, e.g. "an unauthenticated request receives 401 and nothing is persisted">.
|
||
|
||
## Out of Scope
|
||
|
||
- <Explicit boundary statement — the nearest tempting scope creep, named and excluded.>
|
||
- <…>
|
||
|
||
## API / Contract Stub
|
||
|
||
<Inline stub OR link to `./api-contract.yaml`. Name the new/changed paths, methods, request/response shapes, status codes, and `@RequirePermission`.>
|
||
|
||
## Data Model Changes
|
||
|
||
<Entity/schema delta: new tables/columns, constraints, the next free Flyway `V<n>`, and the rollback note. Write "none" if not applicable.>
|
||
|
||
## Security Considerations
|
||
|
||
<STRIDE categories touched (Spoofing/Tampering/Repudiation/Information disclosure/DoS/Elevation). For AI-agent/tool features, also ASTRIDE. Link to `./threat-model.md` if the feature has a non-trivial attack surface.>
|
||
|
||
## Open Questions
|
||
|
||
> Each item is a BLOCKER until resolved. Empty this list before implementation starts.
|
||
|
||
- [ ] <question> — owner: <name>
|
||
- [ ] <question> — owner: <name>
|
||
|
||
## Traceability
|
||
|
||
| REQ-ID | Task ID(s) | Test ID(s) | Status |
|
||
|---|---|---|---|
|
||
| REQ-001 | <T-1> | <test name> | Planned |
|
||
| REQ-002 | <T-2> | <test name> | Planned |
|
||
|
||
<Mirror these rows into [.specify/rtm.md](../../rtm.md). Fill Task/Test IDs as work progresses.>
|
||
|
||
## Persona Review Results
|
||
|
||
| Persona | Status | Key Findings | Resolved |
|
||
|---|---|---|---|
|
||
| Requirements Engineer | PENDING | | |
|
||
| Developer | PENDING | | |
|
||
| Security | PENDING | | |
|
||
| DevOps | PENDING | | |
|
||
| UI/UX | PENDING | | |
|
||
| Architect | PENDING | | |
|