add build development phases

2026-06-28 21:59:59 +03:30
parent 1df3cd9f64
commit 53a40dc51d
52 changed files with 12379 additions and 0 deletions
@@ -0,0 +1,30 @@
+# `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.