diff --git a/.agents/skills/spec/SKILL.md b/.agents/skills/spec/SKILL.md new file mode 100644 index 0000000000..5a5ed856cf --- /dev/null +++ b/.agents/skills/spec/SKILL.md @@ -0,0 +1,100 @@ +--- +name: spec +description: Write a feature spec — the "what & why" of a kandev product feature, before coding. Use when the user says "let's spec X" or starts a new product feature. +--- + +# Writing a Spec + +A spec captures **what** a feature does and **why**, before deciding **how**. + +## What a spec is (and isn't) + +A spec **is**: +- The user-visible behavior of one feature +- A short, testable definition that the team agrees on before writing code +- The source of truth for "is this feature done?" + +A spec **is not**: +- An architecture or design document +- A task list +- A retrospective of work already done + +## Where it lives + +``` +docs/specs// +└── spec.md +``` + +- Slug is kebab-case, descriptive: `kanban-task-queue`, `host-utility-agentctl`. Avoid sequential numbering (`feature-1`, `feature-2`); numbers that are part of a technology name (`http2-proxy`, `oauth2-integration`) are fine. +- One folder per feature. + +## Template + +```markdown +--- +status: draft # draft | approved | building | shipped | archived +created: YYYY-MM-DD +owner: +--- + +# + +## Why +1-3 sentences. The user problem and who feels it. No solution yet. + +## What +- Bullet list of must-have behaviors. +- Use SHALL/MUST sparingly — only for hard requirements. + +## Scenarios +- **GIVEN** , **WHEN** , **THEN** + +## Out of scope +- What this feature deliberately is not doing. + +## Open questions +- (Delete this section when empty.) +``` + +## How to write each section + +### Why +Frame the **user problem**, not the solution. "Users can't resume a stopped session, so they lose context across restarts" — not "add a session/resume endpoint". One to three sentences. If you can't state the problem in three sentences, the feature is too big and should be split. + +### What +Bullet list of must-have behaviors, written as **observable outcomes**. Reserve `SHALL`/`MUST` for hard requirements that would break the feature if removed; everything else is plain prose. Avoid implementation verbs ("call the API", "store in SQLite") — those belong elsewhere. + +Good: "Stopped sessions resume into the last active turn." +Bad: "Add a `/sessions/:id/resume` POST endpoint that restores the ACP session." + +### Scenarios +At least one `GIVEN`/`WHEN`/`THEN` for the golden path. Add edge cases **only when they change the design** — not for every error path. Each scenario should be observable from outside the system (UI state, API response, log line) so QA can verify it. + +```markdown +- **GIVEN** a stopped session with a pending tool call, **WHEN** the user clicks Resume, **THEN** the agent re-runs the tool call and continues the turn. +``` + +### Out of scope +List explicit non-goals. Highest-value section for killing feature creep. Leave it in even when short — "no Windows support in this iteration" is a useful line. + +### Open questions +Park unresolved decisions here while drafting. Each one blocks the spec from being approved. Delete the section once empty. + +## Right-sizing + +The spec should be proportional to the feature. A small feature gets a 20-line spec; a large one rarely needs more than a page. If a spec is growing past one screen: + +- Split into multiple specs (one feature per slug) +- Drop "how" content — a spec describes behavior, not implementation +- Drop scenarios that don't change the design + +A padded spec is worse than a short one — it hides the requirements behind ceremony. + +## Style notes + +- **Symbols in code font.** File paths, packages, types: `internal/agent/lifecycle`, `TaskSession`. +- **Cross-link, don't duplicate.** Reference ADRs (`../../decisions/NNNN-...md`) and architecture docs rather than restating them. +- **Specs rarely need diagrams.** A user-flow mermaid is acceptable when it clarifies a multi-step interaction. Architectural diagrams do not belong here. +- **Present tense, active voice.** "The agent resumes the turn" — not "the turn will be resumed by the agent". + diff --git a/AGENTS.md b/AGENTS.md index e5a6db4484..ee9b2877b1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -293,8 +293,9 @@ Static analysis runs in CI and pre-commit. New code **must** stay within these l Every code change must include tests for new or changed logic. Backend: `*_test.go` files alongside the source. Frontend: `*.test.ts` files for utility functions, hooks, API clients, and store slices. Exceptions: config files, generated code, React component markup. Use `/tdd` for test-driven development. ### Knowledge +- **Specs:** Feature specs live in `docs/specs//spec.md` — the "what & why" of a feature, written before coding. Optional siblings: `plan.md` (how), `notes.md` (post-ship). Use `/spec` to write or update a spec. See `docs/specs/INDEX.md`. - **Decisions:** Architecture decisions are recorded in `docs/decisions/`. Read `docs/decisions/INDEX.md` for an overview. When making significant architectural choices, create a new ADR via `/record decision`. -- **Plans:** Implementation plans are stored in `docs/plans/`. Save completed feature designs via `/record plan`. +- **Plans:** Retrospective implementation plans live in `docs/plans/` (created via `/record plan`). A forward-looking plan tied to a spec goes at `docs/specs//plan.md`. ### Backend - Provider pattern for DI; stderr for logs, stdout for ACP only diff --git a/docs/specs/INDEX.md b/docs/specs/INDEX.md new file mode 100644 index 0000000000..28defc158a --- /dev/null +++ b/docs/specs/INDEX.md @@ -0,0 +1,9 @@ +# Feature Specs + +Specs for kandev product features. Each feature gets a folder with `spec.md` (what & why), optionally `plan.md` (how), and optionally `notes.md` (post-ship). + +See `.agents/skills/spec/SKILL.md` for the workflow. + +| Slug | Status | Created | PR | +|------|--------|---------|----| +| _(no specs yet)_ | — | — | — |