Orch Arch

---
name: orch-arch
description: Use when an accepted PRD under docs/prd/ needs a technical architecture before specs are written (step 2 of orch-plan). Reads the code and the PRD, writes docs/arch/NNN-<slug>.md with components, contracts, decisions and the phase/package split orch-spec turns into tasks. Never writes code, specs or tasks.json.
---

# orch-arch — PRD → architecture

Second stage of **PRD → ARCH → SPEC → TASKS**. The architecture decides *how*
the PRD gets built and, just as important for orch, **how the work splits**:
the phases and packages you name here become the `# F<n>` and `## F<n>.<pkg>`
headers of the specs, and every task in `tasks.json` hangs off one of them.

## Inputs

0. `docs/arch/000-discovery.md`, when the repository has one (`orch-discover`):
   what the code is, with evidence. Build on its facts; a design that
   contradicts one says so explicitly and why, as with earlier architecture.
1. The PRD: `docs/prd/NNN-<slug>.md`. If there is none, stop and run
   `orch-prd` first — an architecture without requirements has nothing to be
   right about.
2. The code that exists. Read the layout, the dependency manifests and the
   modules the PRD touches **before** proposing anything; a design that ignores
   the stack already in the repo is a rewrite nobody asked for.
3. Earlier architecture under `docs/arch/` — extend or supersede it
   explicitly, never contradict it silently.

If the PRD still has open questions that change the design, ask them now,
in one batch. Questions that do not change the design can stay open.

## Where it goes

`docs/arch/NNN-<slug>.md`, reusing the PRD's `NNN-<slug>` when it covers one
PRD. **Never under `specs/`** — `orch atomize` walks the spec root and warns
about any non-spec file it meets.

```yaml
---
type: arch
project_id: <same as the PRD>
version: 0.1
depends_on:
  - docs/prd/NNN-<slug>.md
generated_by: orch-arch
generated_at: <YYYY-MM-DD>
title: <Feature name> — architecture
---
```

## Sections

```markdown
# <Feature name> — architecture

## Context
What exists today and what the PRD changes about it, in a paragraph.

## Components
One subsection per component: responsibility, what it owns, what it calls.

## Data model
Entities, key fields, ownership, and migrations if storage already exists.

## Interfaces
The contracts between components: routes, events, function signatures,
file formats. Precise enough that two agents working in parallel on either
side of one agree without talking.

## Decisions
- **D1 — <decision>.** Chosen: <option>. Rejected: <option> because <reason>.

## Risks
- <what could sink it>, *mitigation:* <what the plan does about it>.

## Requirement coverage
| Requirement | Component(s) |
| --- | --- |
| FR-1 | ... |

## Work breakdown
### F1 — <milestone M1 from the PRD>
- **F1.1 — skeleton**: the thinnest end-to-end path of M1, plus every file
  the slice shares (routes, schema, wiring). Files/dirs: `<path>`, `<path>`.
- **F1.2 — <package>**: <scope>. Files/dirs: `<path>`. Depends on: F1.1.
- **F1.3 — <package>**: <scope>. Files/dirs: `<path>`. Depends on: F1.1.
```

## Rules

- **Every FR and NFR appears in *Requirement coverage*.** A requirement with no
  component is either out of scope — say so — or a hole in the design.
- **One phase is one milestone of the PRD: a vertical slice.** Each phase
  ends in something a user can do end to end, never in a layer ("all the
  models", "all the endpoints"). Layers built apart pass their own tests and
  break when they meet; a slice is integrated from its first task.
- **Every phase starts with a skeleton package.** One task that wires the
  thinnest path of the slice through every layer — a stub where the real
  logic will go, a test that crosses the whole path — and creates the files
  the slice shares (route registration, schema, migrations). The other
  packages depend on it and fill in the layers in parallel without touching
  the shared files. A phase small enough to be one task is its own skeleton.
- **Phases are ordered delivery, packages are parallel work.** Packages in the
  same phase should be buildable at the same time by different agents; put a
  package in a later phase, or name its dependency, when it cannot be. orch
  dispatches ready tasks concurrently, so a hidden dependency here becomes two
  agents editing the same thing at once.
- **Name the files and directories each package owns.** `orch-spec` copies
  them into each task's `Files` list, and orch uses those lists to keep
  concurrent tasks off the same files.
- **Interfaces before implementations.** When two packages meet, the contract
  goes in *Interfaces* and belongs to the earlier phase, so the later tasks can
  start from something fixed.
- **Decisions show the alternative.** A decision with no rejected option is an
  assumption; list it as one.
- **Match the phase numbering already in `specs/`.** If `F0` and `F1` exist,
  new work starts at the next free phase — task ids are how `orch atomize`
  merges, and reusing a phase number collides with tasks already in
  `tasks.json`.

## Hand-off

Show the path, the phase/package list and any decision the user should
confirm. The next step is `orch-spec`, one spec file per phase.