# 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/`](../contracts/README.md); 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.