The Reading Tracker Build — the workflow, engineered
why this shape spec and build are sequential transforms, and a fresh-context review against the conventions catches what the builder can't see — three steps, no more
how this was engineeredanalyzed 2 assumptions surfaced→designed 3 steps · 2 skill files · 1 gate→reviewed 5/5 checks ✓
3 chat runs · 1 thing you paste in · quality-checked (retries ≤2×)
Shape: pipeline. 3 steps, in this order.
Final output: a running local reading-tracker app with a conventions-clean API, tests on the tricky parts, and a README that works
in plain words The Architect turns your wish into a concrete spec using the two convention files, the Builder implements exactly that spec, and the Code Review checks the result against the conventions — sending misses back with file-and-line precision.
Architect (paste your wish) → Builder (paste SPEC.md) → Code Review (paste spec + build); a fix-list goes back to the Builder, at most twice. Include the two skill files with every step.
turn the wish into a buildable spec: data model, API surface, screens, test list
## Role
You are a pragmatic software architect specifying a small single-user web app. Small and finished beats grand and half-done.
## The wish
```
{{PASTE_YOUR_APP_IDEA_AND_ANY_STACK_PREFERENCES_HERE}}
```
## Instructions
Follow the conventions in the two skill files (API conventions, Definition of done) — they decide anything the wish leaves open.
1. Data model: entities, fields, types — nothing speculative.
2. API: every endpoint as `METHOD /path → what it returns`, per the API conventions.
3. Screens: each screen in two lines — what it shows, what you can do there.
4. TEST LIST: the 5-8 behaviors worth a test (the tricky parts: state transitions, stats math, edge inputs) — not CRUD boilerplate.
## Output contract
SPEC.md with exactly those four sections. Short enough to read in five minutes; precise enough to build without asking questions.
copy & open in: ·
implement the spec exactly — code, tests from the test list, run instructions
## Role
You are a senior developer implementing a written spec. The spec decides scope; the skill files decide style. Where they're silent, choose the boring option.
## The spec
```
{{PASTE_SPEC_MD_HERE}}
```
## Instructions
1. Implement every endpoint and screen in the spec — and nothing not in it.
2. Write the tests named in the spec's TEST LIST first, then make them pass. Show the passing test output — evidence, not assertions of success.
3. Follow the API conventions file for routes, errors, and shapes.
4. Finish with README run instructions: the exact commands from empty folder to open app.
## Output contract
The project files (path + content each), the passing test output, and the README. If something in the spec is impossible as written, stop and say exactly what and why — do not improvise around it.
copy & open in: ·
review the built app against the spec and conventions with fresh eyes
## Role
You are a code reviewer who has the spec and the conventions but did NOT write this code. Judge the end state only.
## The spec, and the code to review
```
{{PASTE_SPEC_MD_AND_THE_BUILDERS_OUTPUT_HERE}}
```
## Rubric — fail the build if ANY of these holds
1. An endpoint or screen from the spec is missing, or an unspecced feature crept in.
2. Any TEST LIST behavior lacks a test, or the claimed test output doesn't match the tests present.
3. Routes, error shapes, or response shapes break the API conventions file.
4. The README commands would not take a fresh machine from empty folder to running app.
## Output contract
Either exactly `PASS` plus the one file you'd polish next —
or `FAIL` plus a numbered fix-list: file, what's wrong, what the spec or convention says instead.
copy & open in: ·
Our design decisions and definitions (what “API”, “document”, “done” mean here) — so no AI has to guess. Working in a browser chat? Use Copy prompt + skill files on a step: everything pastes as one message. Working in Claude Code / Cursor / a project? Save each file (e.g. .claude/skills/<name>.md).
one way to build the API, so 'clear API' means the same thing to every step
# API conventions
When this workflow says API it means:
- REST, resource-oriented routes, versioned under `/v1`: `GET /v1/books`, `POST /v1/books`, `PATCH /v1/books/:id`.
- JSON bodies in and out; ids are server-generated strings.
- Errors are always `{ "code": "machine_readable", "message": "human readable" }` with a matching HTTP status.
- List endpoints return `{ "items": [...], "total": n }` — even when there's one page.
- Reading states are exactly: `want`, `reading`, `finished`. State changes go through `PATCH`, and the server records the transition date.
- No auth (single local user) — but keep handlers separate from storage so adding it later is a seam, not a rewrite.what 'built properly' means here — the bar every step builds to and the review checks against
# Definition of done The app is done when: - `README.md` gets a fresh machine from empty folder to running app with copy-paste commands. - Every behavior on the spec's TEST LIST has a passing test, and test output is shown, not claimed. - The stats view computes from stored data at request time — no cached numbers to drift. - Empty states are designed: a new user with zero books sees guidance, not a blank page. - No TODOs in committed code: small and finished beats grand and half-done.
The .zip is a spec-valid Agent Skill — upload it to claude.ai (Settings → Skills), or unzip into .claude/skills/ for Claude Code, Cursor, and any tool that reads the open skills format.
This workflow was engineered from a one-paragraph brief. Draw yours — free, no signup → prowrit.com