Todo REST API

You do:

mkdir todo-api && cd todo-api
git init
cp -r /path/to/agile/* .claude/

Claude Code now reads .claude/CLAUDE.md automatically. All /agile-* commands are available.

🏗️ @arch responds with a scoring matrix (example):

## /agile-explore-brainstorm — Results

### Problem Statement
REST API for personal todo management. Constraints:
lightweight, easy to test, simple CRUD, local-first.

### Scoring Matrix

| Approach          | Feasibility | Maintainability | Performance | Risk | Total |
|-------------------|------------|-----------------|-------------|------|-------|
| Express + SQLite  | 9/10       | 8/10            | 7/10        | 9/10 | 33    |
| Fastify + SQLite  | 8/10       | 8/10            | 9/10        | 8/10 | 33    |
| Go + net/http     | 7/10       | 9/10            | 10/10       | 6/10 | 32    |
| Python Flask      | 9/10       | 7/10            | 6/10        | 9/10 | 31    |

### Recommendation
Express + SQLite or Fastify + SQLite — both score equally.
Express has larger ecosystem; Fastify has better performance.

### What Would Change This
- If performance is critical → Fastify or Go
- If you prefer Python → Flask is viable

🔄 @sm + 🏗️ @arch + ⌨️ @dev scan results:

## /agile-setup-init — Results

| Memory File             | Status       | Confidence |
|-------------------------|-------------|------------|
| semantic/project.md     | ✅ Populated | 95%        |
| semantic/architecture.md| ✅ Populated | 90%        |
| semantic/conventions.md | ✅ Populated | 85%        |
| semantic/codebase.md    | ✅ Populated | 95%        |
| semantic/testing.md     | ✅ Populated | 90%        |

### Detected Stack
- Language: JavaScript (Node.js 20)
- Framework: Express 4.x
- Database: SQLite via better-sqlite3
- Test Framework: Jest + Supertest
- Package Manager: npm

/agile-setup-onboard    → Generates coding rules from detected conventions
/agile-setup-health     → Verifies everything is green (✅ All checks pass)

📋 @po responds:

## /agile-story-create — Story Created

### Story US-001
**As a** todo user,
**I want** to create a new task with a title and optional description,
**so that** I can track things I need to do.

### Acceptance Criteria

**AC-1: Happy path — create task with title and description**
- **Given** the API is running
- **When** I send POST /tasks with {"title": "Buy groceries",
  "description": "Milk, eggs, bread"}
- **Then** I receive 201 with the created task including an ID,
  title, description, and status "pending"

**AC-2: Edge case — create task with title only**
- **Given** the API is running
- **When** I send POST /tasks with {"title": "Call dentist"}
  (no description)
- **Then** I receive 201 with description as null or empty string

**AC-3: Error case — missing title**
- **Given** the API is running
- **When** I send POST /tasks with {} (no title)
- **Then** I receive 400 with an error message
  "title is required"

### INVEST Check
| Criterion   | Status |
|-------------|--------|
| Independent | ✅     |
| Negotiable  | ✅     |
| Valuable    | ✅     |
| Estimable   | ✅     |
| Small       | ✅     |
| Testable    | ✅     |

### Metadata
- **Status**: Unrefined
- **Created**: 2026-04-05

> Added to: .memory/backlog/product.md

💬 /agile-story-create I need to list all my tasks,
   with the ability to filter by status (pending, done)

   → @po creates US-002: "List and filter tasks"

💬 /agile-story-create I need to mark a task as done
   and also be able to delete tasks I no longer need

   → @po creates US-003: "Update task status and delete tasks"

## /agile-story-estimate — Results

| Story  | Title                 | Points | Rationale                          |
|--------|-----------------------|--------|------------------------------------|
| US-001 | Create a task         | 3      | CRUD + validation + DB schema      |
| US-002 | List and filter tasks | 2      | Read-only + query params           |
| US-003 | Update and delete     | 3      | Two operations but straightforward |

**Total backlog**: 8 points

🔄 @sm facilitates:

## Sprint Planning Output

### Sprint Goal
"Deliver a working CRUD API for task management"

### Sprint Backlog
| Story  | Title                 | Points | Priority |
|--------|-----------------------|--------|----------|
| US-001 | Create a task         | 3      | P1       |
| US-002 | List and filter tasks | 2      | P1       |
| US-003 | Update and delete     | 3      | P1       |

### Capacity Check
- Team velocity (first sprint): 8 points (conservative)
- Committed this sprint: 8 points
- Capacity utilization: 100%

### Risks
- First sprint — no historical velocity to compare against

⌨️ @dev: Branch created
- Branch: feature/US-001-create-task
- From: develop (up to date)
- Linked to: US-001

👨‍💻 @lead: Implementation Plan for US-001

Phase 1: Database schema
- Create tasks table (id, title, description, status, created_at)

Phase 2: Route + handler
- POST /tasks route
- Request validation (title required)
- Insert into database
- Return created task with 201

Phase 3: Error handling
- 400 for missing title
- 500 for database errors

Confidence: 9/10 — straightforward CRUD

🔴 RED — Write failing test for AC-1

// test/tasks.test.js
test('POST /tasks creates a task with title and description', async () => {
  const res = await request(app)
    .post('/tasks')
    .send({ title: 'Buy groceries', description: 'Milk, eggs' });

  expect(res.status).toBe(201);
  expect(res.body).toHaveProperty('id');
  expect(res.body.title).toBe('Buy groceries');
  expect(res.body.status).toBe('pending');
});

// Result: ❌ FAIL — route doesn't exist yet

🟢 GREEN — Write minimum code to pass

// src/routes/tasks.js
router.post('/', (req, res) => {
  const { title, description } = req.body;
  const task = db.prepare(
    'INSERT INTO tasks (title, description, status) VALUES (?, ?, ?)'
  ).run(title, description || null, 'pending');

  res.status(201).json({
    id: task.lastInsertRowid,
    title, description, status: 'pending'
  });
});

// Result: ✅ PASS

🔵 REFACTOR — Clean up while tests stay green

// Extract DB logic to a repository (Clean Code)
// Tests still pass ✅

🚀 @devops: CI Pipeline Results
  Build:    ✅
  Tests:    ✅ 6/6 passing
  Lint:     ✅ 0 errors
  Security: ✅ No vulnerabilities

⌨️ @dev: Commit created
  feat(tasks): add create task endpoint

  - POST /tasks with title and optional description
  - Returns 201 with created task including ID
  - Validates title is required (400 if missing)

  Ref: US-001

⌨️ @dev: PR created
  Title: feat(tasks): add create task endpoint (#US-001)
  Branch: feature/US-001-create-task → develop
  CI: ✅ Green

👨‍💻 @lead: PR Review

| # | Severity | File          | Finding                    | Fix                      |
|---|----------|---------------|----------------------------|--------------------------|
| 1 | 🟡 S2   | routes/tasks.js:8 | Magic string 'pending' | Extract to constant      |
| 2 | 🔵 S3   | routes/tasks.js:3 | Missing JSDoc on handler | Add function description |

Score: 8/10
Verdict: ✅ APPROVED (no S0/S1 findings)

⌨️ @dev: Merge complete
  Strategy: Squash merge (feature → develop)
  Branch feature/US-001-create-task deleted
  CI on develop: ✅ Green

🧪 @qa: Definition of Done — US-001

| # | Criterion              | Status |
|---|------------------------|--------|
| 1 | All ACs covered by tests | ✅   |
| 2 | CI pipeline green        | ✅   |
| 3 | Code reviewed by @lead   | ✅   |
| 4 | No S0/S1 findings open   | ✅   |
| 5 | Merged to develop        | ✅   |
| 6 | Test coverage ≥ 80%      | ✅ 94%|

Verdict: ✅ DONE — ready for acceptance

📋 @po: Acceptance Review — US-001

| AC   | Description           | Status |
|------|-----------------------|--------|
| AC-1 | Create with title+desc | ✅    |
| AC-2 | Create with title only | ✅    |
| AC-3 | Error on missing title | ✅    |

Verdict: ✅ ACCEPTED
Story counts toward sprint velocity: 3 points

US-002: List and filter tasks (2 pts)

/agile-code-branch feature US-002 list-tasks
/agile-story-plan US-002
/agile-code-tdd US-002
  🔴 Test: GET /tasks returns all tasks → ❌
  🟢 Implement handler → ✅
  🔴 Test: GET /tasks?status=done filters → ❌
  🟢 Add query param filtering → ✅
/agile-code-ci           → ✅ All green
/agile-code-commit       → feat(tasks): add list and filter endpoints
/agile-code-pr           → PR created
/agile-code-pr-review    → ✅ Approved (no findings)
/agile-code-merge        → Squash merged to develop
/agile-story-dod         → ✅ DONE
/agile-story-accept      → ✅ ACCEPTED (2 points)

US-003: Update and delete tasks (3 pts)

/agile-code-branch feature US-003 update-delete
/agile-story-plan US-003
/agile-code-tdd US-003
  🔴 Test: PUT /tasks/:id updates status → ❌
  🟢 Implement update handler → ✅
  🔴 Test: DELETE /tasks/:id removes task → ❌
  🟢 Implement delete handler → ✅
  🔴 Test: PUT /tasks/999 returns 404 → ❌
  🟢 Add not-found check → ✅
/agile-code-ci           → ✅ All green
/agile-code-commit       → feat(tasks): add update and delete endpoints
/agile-code-pr           → PR created
/agile-code-pr-review    → ✅ Approved
  (🟡 S2: suggest extracting "not found" check to middleware)
/agile-code-merge        → Squash merged to develop
/agile-story-dod         → ✅ DONE
/agile-story-accept      → ✅ ACCEPTED (3 points)

## Sprint Review Report

### Sprint Goal: "Deliver a working CRUD API for task management"
### Sprint Goal Met: ✅ Yes

| Story  | Title                 | Points | Status     |
|--------|-----------------------|--------|------------|
| US-001 | Create a task         | 3      | ✅ Accepted |
| US-002 | List and filter tasks | 2      | ✅ Accepted |
| US-003 | Update and delete     | 3      | ✅ Accepted |

### Velocity
- Committed: 8 points
- Completed: 8 points (100%)
- First sprint — this becomes the baseline

## Retrospective Report

### What Went Well
- TDD caught the missing validation early (AC-3)
- All stories accepted on first pass

### What To Improve
- Could extract common error handling to middleware
- Should set up integration tests for the full request cycle

### Action Items
| Action                            | Owner | Due        |
|-----------------------------------|-------|------------|
| Extract error middleware          | @dev  | Sprint 2   |
| Add integration test template     | @qa   | Sprint 2   |

🔄 @sm: Learnings captured
  → Saved to: .memory/episodic/learnings.md
  - Sprint 1 velocity baseline: 8 points
  - TDD effectiveness: all stories accepted first pass
  - Action items tracked for Sprint 2

## Changelog: v1.0.0 — 2026-04-05

### Added
- POST /tasks — create a task with title and description (US-001)
- GET /tasks — list all tasks with status filter (US-002)
- PUT /tasks/:id — update task status (US-003)
- DELETE /tasks/:id — delete a task (US-003)

🚀 @devops: Release v1.0.0
  Branch: release/v1.0.0 from develop
  CI: ✅ Green
  Merged to main ✅
  Tagged: v1.0.0 ✅
  Back-merged to develop ✅

🚀 @devops: Deployed v1.0.0
  Smoke tests: ✅ All endpoints responding
  Health check: ✅