# `dev/` — the Balinyaar build workspace

This folder is the **plan for building Balinyaar**, not application code. It takes the repo from its
current *starter + auth* baseline to the MVP described in [`product/`](../product/), as a chain of
agent-runnable prompt files split into two parallel tracks.

| Folder | What it is |
| --- | --- |
| [`phases/`](phases/README.md) | The prompt chain — `backend/` (b0–b15) and `frontend/` (f0–f15), plus the shared rules/template in `phases/_shared/`. **Start at [`phases/README.md`](phases/README.md).** |
| [`contracts/`](contracts/README.md) | The shared API/flow contract between the two independent projects. Backend writes, frontend reads. |
| [`shared-working-context/`](shared-working-context/README.md) | The parallel-agent handoff + per-phase reports + the mock registry. Each lane writes only its own files. |

## How to use it

1. Read [`phases/README.md`](phases/README.md) — the roadmap and dependency graph.
2. To run a phase, point a fresh agent at one phase file (e.g. *"Execute `dev/phases/backend/backend-phase-2.md`"*).
   The phase file tells it what to read, what to build, and how to close out.
3. Run the two tracks **in parallel** with two agents if you like: a frontend phase named
   `frontend-phase-N-bM.md` only needs **backend phase bM** merged first; everything else about the two
   tracks is decoupled through `contracts/` and `shared-working-context/` (which are designed so the two
   agents never touch the same files).

## Non-negotiables (every phase enforces them)

- Follow the project rules in the relevant `CLAUDE.md` / `CONVENTIONS.md` and the
  [shared operating rules](phases/_shared/agent-operating-rules.md).
- Mock external services **behind DI seams** and record them in
  [`shared-working-context/reports/mocks-registry.md`](shared-working-context/reports/mocks-registry.md).
- Finish each phase with: updated docs, a written contract (backend), a handoff note, a phase report,
  and saved memory.