feat(skills): add /spec for writing feature specs (#700)

.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/<feature-slug>/
+└── 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: <name>
+---
+
+# <Feature Name>
+
+## 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** <state>, **WHEN** <action>, **THEN** <observable outcome>
+
+## 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".
+

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/<slug>/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/<slug>/plan.md`.
 
 ### Backend
 - Provider pattern for DI; stderr for logs, stdout for ACP only

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)_ | — | — | — |