Emberfall/docs/WORKFLOW.md

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.