Implementing Features with Spec-Driven Development

specs/features/task-filtering.md

# Feature: Task filtering on GET /api/tasks

## What it does
Adds query parameter support to GET /api/tasks so the frontend can
request a filtered subset of tasks instead of always getting all of them.

## Why we need it
As the project grows, returning every task on every page load will
become slow. Filtering by state and assigned_role lets the frontend
fetch only what it needs for the current view.

## Behaviour

### GET /api/tasks (no params): unchanged
Returns all tasks. Existing behaviour preserved exactly.

### GET /api/tasks?state=editing
Returns tasks where state == "editing".
Invalid state values → 400 with body: {"detail": "invalid state: <value>"}

### GET /api/tasks?assigned_role=Editor
Returns tasks where assigned_role == "Editor".
Invalid role values → 400 with body: {"detail": "invalid role: <value>"}

### GET /api/tasks?state=editing&assigned_role=Editor
Both filters applied (AND).

## Acceptance criteria
- Existing GET /api/tasks calls continue to return all tasks
- Invalid state or role returns 400 with a clear error message
- Valid filter returns 200 with the filtered list (empty array allowed)
- Per-task response shape is unchanged, the frontend code does NOT change
- The route remains in backend/app/api/v1/tasks.py

## Out of scope
- Pagination (separate spec)
- Sorting (separate spec)
- Date range filtering (separate spec)

## Smoke test (all must pass)
curl -s "http://localhost:8000/api/tasks?state=editing" | python -m json.tool
curl -s "http://localhost:8000/api/tasks?state=invalid" -w "\nStatus: %{http_code}\n"
curl -s "http://localhost:8000/api/tasks?assigned_role=Editor" | python -m json.tool
curl -s "http://localhost:8000/api/tasks" | python -m json.tool   # must still return all

.claude/skills/implement-spec/SKILL.md

---
description: Implement a feature described in a markdown spec file anywhere under specs. Reads the spec, builds the feature end-to-end across schemas, service, and routes, and runs the smoke tests from the spec. Use when the user provides a spec file path.
argument-hint: <path-to-spec-file>
disable-model-invocation: true
allowed-tools: Read Write Edit Grep Glob Bash(curl *) Bash(uv run *) Bash(git diff *)
---

You are implementing a feature from a markdown specification.

## Input
The spec file path is in $ARGUMENTS.
Example: /implement-spec specs/features/task-filtering.md

## Required reading
1. The spec file at $ARGUMENTS. This is your source of truth
2. CLAUDE.md: project conventions
3. backend/app/api/v1/tasks.py: existing endpoint patterns
4. backend/app/services/task_service.py: service patterns
5. backend/app/schemas/task.py: schema patterns
6. specs/api-contract.md: the overall contract

## Steps

### 1. Restate the spec
Print one line: "Implementing <feature-name>: <one-line behaviour>"
This proves you read the spec, not guessed it.

### 2. Extract acceptance criteria
List them. These are your tests.
If the spec has no acceptance criteria section, STOP. Tell the user
the spec needs acceptance criteria before implementation.

### 3. Extract out-of-scope items
List them. These are NOT part of this work.
Do not implement them even if they seem like natural additions.

### 4. Implement
Touch only the files needed. Match existing patterns in each file.
Pydantic v2. Async SQLAlchemy. snake_case Python. CLAUDE.md conventions.

### 5. Run smoke tests from the spec
Skip this step by default. Only run if the user explicitly passes `--test` in the arguments.

If `--test` is passed: execute every curl command in the spec's smoke test section,
show actual output for each, and PASS or FAIL each against the spec's expectation.

### 6. Report
Output markdown with:
- Spec implemented (path)
- Files modified (one line each)
- Smoke test results (pass/fail per test, with actual output)
- Acceptance criteria items that could NOT be tested via curl, flagged for human review

## Hard rules
- The spec is the source of truth. Do not add behaviour the spec does not describe.
- Do not modify the spec file itself.
- Do not modify frontend/ unless the spec explicitly says so.
- If the spec is ambiguous, STOP and ask the user to clarify and update the spec.

/implement-spec specs/features/task-filtering.md --test

/diff

# Feature: <short name>

## What it does
One or two sentences.

## Why we need it
The problem it solves.

## Behaviour
### <request or action>
Exact inputs, outputs, status codes and error bodies.

## Acceptance criteria
- Testable statement 1
- Testable statement 2

## Out of scope
- Thing we are deliberately not building (separate spec)

## Smoke test (all must pass)
curl ...