First commit, phased 1 and 2 created but untested

2026-10-20 07:40:35 +11:00
commit 7a3e408ffc
66 changed files with 5639 additions and 0 deletions
@@ -0,0 +1,39 @@
+# 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`.