baya-monorepo/dev/shared-working-context/README.md

Shared working context — the parallel-agent handoff

This folder lets a backend agent and a frontend agent work at the same time without ever editing the same file. It is the running, append-only record of what each side has done and what it needs from the other. (Stable API shapes live in ../contracts/; this folder is the running coordination on top of them.)

Lane ownership — the one rule that keeps it safe

Each lane writes only its own files. Neither lane edits the other's.

Lane	Writes (only)	Reads
Backend	backend/STATUS.md, backend/handoff/after-backend-phase-N.md (new file per phase), reports/backend-phase-N-report.md, reports/mocks-registry.md	frontend/requests/for-backend.md, prior backend handoffs
Frontend	frontend/STATUS.md, frontend/requests/for-backend.md (append), reports/frontend-phase-N-report.md	backend/handoff/*, ../contracts/*, prior frontend reports

Because each handoff is a new file per phase and each STATUS/requests file is append-only, two agents can run concurrently and only ever append — no merge conflicts, no clobbering.

Layout

shared-working-context/
├── backend/
│   ├── STATUS.md                          # append: one block per backend phase (what shipped, gate status)
│   └── handoff/
│       └── after-backend-phase-N.md       # "context for frontend after backend phase N" (one per phase)
├── frontend/
│   ├── STATUS.md                          # append: one block per frontend phase
│   └── requests/
│       └── for-backend.md                 # append: contract gaps / shape requests the backend should fulfil
└── reports/
    ├── README.md                          # the per-phase report template
    ├── mocks-registry.md                  # master list of every mock/seam + how to make it real (backend-owned)
    ├── backend-phase-N-report.md          # what was built / testable / mocked (one per backend phase)
    └── frontend-phase-N-report.md         # one per frontend phase

The handoff note (backend → frontend), per phase

backend/handoff/after-backend-phase-N.md should answer, for the frontend agent:

• Which endpoints/contracts are now live (link the contracts/domains/* doc + the swagger snapshot).
• What the frontend can now build because of this phase.
• What is mocked server-side (so the frontend knows responses are fake-but-shaped) and what's real.
• Any auth/enum/format detail the frontend must mirror.
• Open questions / things the frontend should not assume yet.

The request note (frontend → backend)

frontend/requests/for-backend.md is where the frontend appends: missing endpoints, fields it needs, shape mismatches, pagination/filter needs — anything that should land in a later backend change. The backend agent reads this at the start of each phase. The frontend never edits backend code to "fix" it.