# Feature specs

Each markdown file in this folder is a self-contained spec for a feature on `platform-api`. Specs are the source of truth for what to build; the implementation flows from the spec, not the other way round.

## Workflow

1. **Author a spec.** Copy `.claude/skills/implement-spec/templates/SPEC_TEMPLATE.md` to `docs/specs/<slug>.md` and fill it in. Set `status: ready` once acceptance criteria are concrete and testable.
2. **Hand it to Claude.** In Claude Code, run:

   ```
   /implement-spec docs/specs/<slug>.md
   ```

   Claude reads the spec, plans the surgical edits, implements them, writes matching unit/e2e tests, runs the relevant tests, updates the spec's frontmatter to `status: done`, and reports back.
3. **Review the diff.** The spec's `files:` frontmatter lists every file Claude is allowed to touch (plus their corresponding test files). Anything outside that list should not appear in the diff.
4. **Commit.** Specs are versioned alongside the implementation so the "why" lives next to the "what".

## Status values

| `status:`     | Meaning                                                           |
| ------------- | ----------------------------------------------------------------- |
| `draft`       | Still being written. Claude will ask before implementing.         |
| `ready`       | Acceptance criteria are testable; safe to implement.              |
| `in-progress` | Claude is currently implementing.                                 |
| `done`        | Implemented, tests pass. The decisions log captures any choices.  |

## Anatomy of a good spec

- A one-paragraph **Goal** that anyone can read.
- **Behavior changes** stated in observable terms (URLs, params, response codes), not implementation details.
- **Acceptance criteria** as bullets that map 1:1 to tests.
- An explicit **Out of scope** section so reviewers know what not to ask for.
- A **Test plan** with the exact `npm test --grep` and `npm run test:e2e:file` commands.

`EXAMPLE-add-issue-status-filter.md` is a fully-written reference spec — use it as a model for shape and detail level.