40 lines
1.9 KiB
Markdown
40 lines
1.9 KiB
Markdown
# 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`.
|