# WORKFLOW.md — How the agent should work

## The loop (repeat for every step)
1. **Orient:** read `STATUS.md` → find the next unchecked step.
2. **Scope:** read only the docs named in that phase heading.
3. **Plan:** write a 3–6 line plan (files to create/edit, what to test).
4. **Build small:** one file or function at a time. Don't write the whole phase in one go.
5. **Verify:** run `npm test`, and start the server and hit the endpoint with `curl` (or a test) before moving on.
6. **Record:** tick the step, update Project Health, add a Session Log line, list new Known Issues.
7. **Re-orient:** go back to 1.

## Definition of Done (per step)
- [ ] Code is in the right folder per ARCHITECTURE.md
- [ ] Inputs validated; errors return the standard error shape (API.md)
- [ ] At least one test covers the happy path and one covers a failure path
- [ ] `npm test` is green
- [ ] No leftover `console.log` debugging; no commented-out code blocks
- [ ] STATUS.md updated

## When something breaks
1. Read the **full** error message and stack trace.
2. Reproduce with the smallest possible command or test.
3. Change **one** thing at a time. Re-run.
4. If stuck after 3 genuine attempts: log it under Known Issues with what you tried, then move to a step that isn't blocked.

## Things that waste time — avoid
- Rewriting working files "to clean them up".
- Adding libraries to dodge writing 10 lines of code.
- Building UI polish before the API works.
- Inventing game mechanics not in GAME_DESIGN.md (add to Stretch Goals instead).
- Editing earlier migrations after they've been run. **Add a new migration.**

## Editing files
- Prefer targeted edits over regenerating whole files.
- After editing, re-read the changed region to confirm it is what you intended.
- Never delete the user's `data/*.db` unless a step says to.

## Commit style (if git is in use)
`phase.step: short description` — e.g. `1.2: add authService register/login`.