Orch Spec

---
name: orch-spec
description: Use when an architecture under docs/arch/ needs to become dispatchable work for orch (step 3 of orch-plan). Writes specs/fN-<slug>.md in the exact markdown format orch atomize parses — phase, package and task headers with Model, Estimate, Reason, Dependencies and Files — one agent-sized task per header. Never edits tasks.json.
---

# orch-spec — architecture → atomizable spec

Third stage of **PRD → ARCH → SPEC → TASKS**. A spec is the one document that
is both read by a human and parsed by a program: `orch atomize` turns every
task header in it into a `tasks.json` entry, and when orch dispatches that task
the agent's prompt carries its title, its description, its `Files` as
*Files you may write*, and a *Spec ref (READ FIRST)* pointing back at this very
section. **Write each task as the complete brief for an agent that has read
nothing else.**

## Inputs

- The architecture: `docs/arch/NNN-<slug>.md`, especially *Work breakdown* and
  *Interfaces*. No architecture → run `orch-arch` first.
- The model routes: `.orchestrator/model_router.yaml`. Every `Model` you write
  should be one of its top-level keys, spelled exactly. A project scaffolded
  without a template starts with no routes; then use the `<backend>/<model>`
  form the router expects (`claude/sonnet`,
  `codex/gpt-5.6`, `opencode/...`) and `orch-tasks` adds the routes.
- The existing task ids: `orch tasks` and every file already in `specs/`.
- The project id for the frontmatter: the first line of `orch explain`
  (`Project <id>`). A different `project_id` makes atomize warn on every run.

## Where it goes

`specs/f<N>-<slug>.md`, **one file per phase**. `specs/` is the project's
`spec_root` (from `.orchestrator/config.yaml`; check it if the project changed
it). `orch atomize` walks that directory and computes each task's `specRef` as
the file's path relative to it, so do not nest specs somewhere else.

## Format

The parser is line-based and forgiving: **anything that does not match is
dropped without an error**, so a typo loses a task silently. Follow this
shape exactly.

```markdown
---
type: spec
project_id: sample-project
phase: 1
version: 0.1
depends_on:
  - docs/arch/001-auth.md
consumed_by:
  - orch-atomizer
generated_by: orch-spec
generated_at: 2026-09-13
title: Sign-in
---

# F1 — Sign-in

A user signs in with email and password and gets a session: milestone M1 of
docs/prd/001-auth.md, built as one vertical slice.

## F1.1 — Package: skeleton

### F1.1.T1 — Sign-in walking skeleton

Wire POST /session end to end before any real logic: the User and Session
types exactly as the Interfaces section of docs/arch/001-auth.md fixes them,
an in-memory user store seeded with one user, the route registered in the
router, and a handler that answers the JSON body the Interfaces section
describes. The password check is a plain comparison and the types have no
validation yet; F1.2 and F1.3 replace those stubs.

Done when: these tests pass in `src/api/session.test.ts` — the seeded user's
credentials answer 200 with a session; any other credentials answer 401.

- **Model**: claude/sonnet
- **Estimate**: 3h
- **Reason**: Wiring across every layer; standard tier is enough.
- **Dependencies**:
- **Files**:
  - `src/auth/types.ts`
  - `src/auth/store.ts`
  - `src/api/router.ts`
  - `src/api/session.ts`
  - `src/api/session.test.ts`

## F1.2 — Package: domain

### F1.2.T1 — User and Session validation

Add validation to the User and Session types from F1.1.T1, as the Interfaces
section of docs/arch/001-auth.md states it. No persistence, no HTTP.

Done when: these tests pass in `src/auth/types.test.ts` — an empty email is
rejected; an expired session is rejected; a valid user and session are
accepted.

- **Model**: claude/sonnet
- **Estimate**: 2h
- **Reason**: Plain validation; standard tier is enough.
- **Dependencies**: F1.1.T1
- **Files**:
  - `src/auth/types.ts`
  - `src/auth/types.test.ts`

## F1.3 — Package: api

### F1.3.T1 — Password hashing and uniform 401

Replace the skeleton's plain comparison in POST /session with a password-hash
check. Wrong credentials answer 401 with no hint of which part was wrong.

Done when: these tests pass in `src/api/session.test.ts` — the right password
answers 200 with a session; a wrong password answers 401; an unknown email
answers 401 with the same body as a wrong password.

- **Model**: claude/sonnet
- **Estimate**: 4h
- **Reason**: Auth logic with security edge cases.
- **Dependencies**: F1.1.T1
- **Files**:
  - `src/auth/password.ts`
  - `src/api/session.ts`
  - `src/api/session.test.ts`
```

### Headers

| Level | Syntax | Becomes |
| --- | --- | --- |
| Phase | `# F<n> — <title>` | `phase` of every task below it |
| Package | `## F<n>.<pkg> — <title>` | grouping only |
| Task | `### F<n>.<pkg>.T<n> — <title>` | one task, id `F<n>.<pkg>.T<n>` |

Integers without padding (`F1`, never `F01`). The separator may be `—`, `–`
or `-`.

### Fields

Bullets under the task, labels in bold, English or Spanish
(`Model`/`Modelo`, `Estimate`/`Estimación`, `Reason`/`Razón`,
`Dependencies`/`Deps`, `Files`/`Archivos`). Any other label is warned about
and ignored — so a `Done when` line goes in the description, **not** as a
field.

- **Estimate** accepts `2h`, `1.5h`, `30m`, `2d` (a day is 8h). It is not
  decoration: orch derives the dispatch timeout from it
  (`estimateHours × default_timeout_multiplier`), so an estimate that is far
  too low gets the agent killed mid-task.
- **Dependencies**: task ids separated by `,` or `;`. Leave the value empty
  when there are none.
- **Files**: backticked paths as sub-bullets. They are the files the agent is
  told it may write, and what orch uses to keep concurrent tasks apart.

Everything between the task header and its first field bullet is the
**description**, multiline.

## Rules for good tasks

- **A phase is a vertical slice; its first task is the skeleton.** The
  phase delivers one PRD milestone end to end. Its first task wires the
  thinnest path through every layer and owns the files the slice shares;
  the other tasks depend on it and fill in one layer each, in parallel, as
  F1.2.T1 and F1.3.T1 do above. Never a phase of only models or only
  endpoints.
- **One task = one agent session = one PR.** Aim for 1–4h, never above 8h.
  Split anything bigger along the architecture's interfaces.
- **The description is the whole brief.** What to build, which contract to
  honour (cite the architecture section), and a *Done when* an agent can check
  by running something. "Implement auth" is not a task.
- **Done when is a list of tests.** Name each behaviour that proves the task —
  one test per behaviour, edge cases included — and the test file they go in,
  and list that file under **Files**. With `dispatch.tdd` on, the agent writes
  them first (the `orch-tdd` skill) and the local verify sends back a change
  that touches no test file. A task with nothing to test (docs, config) says
  so instead.
- **Dependencies are real, and only real.** A task depends on another only if
  it needs that task's output to start. Missing ones make orch run tasks in
  the wrong order; spurious ones serialise work that could run in parallel.
  `orch validate` rejects unknown ids and cycles.
- **Two tasks that can run at the same time never share a file.** If they
  must, make one depend on the other.
- **Pick the cheapest model that will get it right.** Each route in
  `model_router.yaml` has a `tier` (`premium`, `standard`, `cheap`): premium
  for design-heavy or security-sensitive work, cheap for boilerplate, docs and
  mechanical edits. Say why in `Reason`.
- **Never renumber a task that has been atomized.** `orch atomize` merges by
  id: a renumbered task becomes a new task *plus* an orphan of the old one,
  with its status and history left behind. Append new ids instead
  (`F1.1.T4`), even out of order.
- **Nothing field-like inside code fences.** The parser skips fenced blocks
  entirely — a task written inside one is not imported.


## End-to-end tests for a phase with screens

A phase that ships something a person clicks through ends with **one E2E
task**, in its own package, depending on the tasks that build those screens.
Its agent brings the app up, explores it in a browser and leaves Playwright
specs (the `orch-e2e` skill); orch's local verify then runs those specs on
every later task.

```markdown
## F2.9 — Package: e2e

### F2.9.T1 — E2E: checkout flows

Cover the checkout flows docs/prd/002-checkout.md promises, in a real browser
against the running app, following the orch-e2e skill.

Done when: these tests pass in `tests/e2e/checkout.spec.ts` — a cart shows
its items and total; paying with a valid card shows the receipt; a declined
card shows the decline and keeps the cart.

- **Model**: claude/sonnet
- **Estimate**: 3h
- **Reason**: Browser exploration and flaky-free specs need a capable model.
- **Dependencies**: F2.2.T1, F2.3.T1
- **Files**:
  - `tests/e2e/checkout.spec.ts`
  - `playwright.config.ts`
```

One E2E task per phase, not per screen: the flows cross screens, and one agent
holding the whole phase writes fewer, steadier tests. A phase with no UI (an
API, a CLI) gets none — its integration tests are its tasks' own.
## Check before handing off

```bash
orch atomize --file specs/f1-<slug>.md --list    # what the parser sees
```

Compare the listed ids with the tasks you meant to write, and read every
warning — each one is a line the parser dropped or misread. Fix and re-run
until the list is exactly your tasks and there are no warnings. Then hand off
to `orch-tasks`; do not run `--apply` from this skill.