Let's run one. Not a demonstration — an actual phase from the beginning. You'll write the spec entry, define the completion criterion, write the Command, run Build, and close the Review. By the end, the Spec File has a Review Record and you can explain everything that shipped.
The requirement
The project is a small API. A support request has surfaced a gap: users who forget their password have no recovery path. The Product Owner writes it up.
Password Reset
Users who forget their password are permanently locked out.
Support is handling these manually which doesn't scale.
Required:
–Users can request a reset link sent to their registered email
–The link takes them to a form to set a new password
–Links must expire (security requirement — 1 hour)
–Flow must work without support intervention
Out of scope: social login recovery, SMS fallback
The ticket
The Product Owner creates a ticket from the requirement. That's too large for one phase — it covers generating the token, sending the email, and handling the reset itself. The Developer decomposes it into phases before writing a single line.
Password reset flow
Description
Allow users to request a password reset link and use it to set a new password.
Acceptance criteria
- —POST /auth/forgot-password stores a signed, 1-hour-expiry reset token and returns 200
- —Endpoint sends an email containing the reset link to the user's registered address
- —POST /auth/reset-password validates the token, updates the password, and invalidates the token
- —Reset links expire after 1 hour; expired tokens are rejected
Phase 1: Writing the spec entry
Before writing any code, write the Spec File entry for Phase 1. It needs three things: what the phase is, the completeness criterion, and any constraints.
Phase 1: Generate and store reset token
Ticket: PROJ-88
Status: Spec
Criterion: POST /auth/forgot-password stores a signed, 1-hour-expiry token against the user record and returns 200.
Constraints:
–Token must be cryptographically random (crypto.randomBytes)
–Expiry enforced server-side, not by the token format
–Store hashed token, not plaintext
Product Owner signs off on the scope. Phase 1 is approved. Now write the Command.
Phase 1: Writing the Command
The Command tells the agent its role for this session — who it is, what it's building, and where to stop. If it's hard to write, the spec entry needs more work.
Build Command — PROJ-88 Phase 1
You are a developer on this team. Your job is to build Phase 1 of PROJ-88.
Phase: Generate and store reset token
Spec: SPEC.md § Phase 1
Ticket: PROJ-88
Criterion:
POST /auth/forgot-password stores a signed, 1-hour-expiry token against the user record and returns 200.
Constraints:
–Use crypto.randomBytes for token generation
–Store hashed token (bcrypt), not plaintext
–Expiry is a timestamp stored alongside the hash
–User model lives in src/models/User.ts
When the criterion is met:
1. Update SPEC.md Phase 1 status to 'In Review'
2. Stop. Do not begin Phase 2.
3. Lead the Review.
Phase 1: Build and Review
You run the Command. The agent builds. Then it stops and leads the Review. Watch the ticket update as the session progresses.
Password reset flow
Description
Allow users to request a password reset link and use it to set a new password.
Acceptance criteria
- —POST /auth/forgot-password stores a signed, 1-hour-expiry reset token and returns 200
- —Endpoint sends an email containing the reset link to the user's registered address
- —POST /auth/reset-password validates the token, updates the password, and invalidates the token
- —Reset links expire after 1 hour; expired tokens are rejected
What just happened
The Spec File now has a Review Record for Phase 1. Every question the agent asked has an answer in writing. The cross-phase dependency — Phase 3 handles expiry validation — is documented. Nobody has to remember it.
The Review Record is the difference between code you shipped and code you own.
The anchor file
Phase 1 is closed. Now write the anchor entry — which files were touched, who owns this phase, and what the acceptance criteria were. This can be written by hand, generated by the agent at phase close, or maintained by editor tooling. The format is open.
Open src/routes/auth.ts six months from now — the anchor entry tells you which ticket owns it, who was assigned, and why the endpoint returns 200 for unknown emails. No Jira hunting, no asking whoever last touched it. The answer is in the file.
Phase 2 is next. You already know what it needs: the spec entry is written, the criterion is clear, and there's an open question from the ticket that Phase 2's Review will likely surface — whether to return 200 or 404 for unknown emails in the send-email step. That one will go to the Product Owner.
Run it the same way. Spec, Command, Build, Review. That's the loop.