# Orchestrator

Map of `.agents/`, and how to pick who does what.

## Layout

```
.agents/
  ORCHESTRATOR.md      you are here
  context/             how things are — read before deciding
  rules/               how things must be — binding
  checklists/          gates to run before you claim done
  skills/              procedures an agent loads on demand
  agents/              specialist agent definitions
  templates/           component and page starting points
  scripts/             deterministic helpers (prefer these over prose)
```

`context/` describes reality, `rules/` constrain change. When they disagree,
reality won — update the rule and say so.

## Specialists

Each agent has one responsibility, one set of rules, and its own worktree. Full
definitions in [`agents/`](agents/).

| Agent                                                      | Owns                                                | Loads skills                           |
| ---------------------------------------------------------- | --------------------------------------------------- | -------------------------------------- |
| [`astro-architect`](agents/astro-architect.md)             | project scaffold, config, routing, layouts          | `astro-page`                           |
| [`design-system-keeper`](agents/design-system-keeper.md)   | tokens, the single palette, type scale              | `design-tokens`                        |
| [`component-builder`](agents/component-builder.md)         | one component per task, from templates              | `astro-component`, `design-tokens`     |
| [`page-migrator`](agents/page-migrator.md)                 | one page per task, HTML → `.astro`                  | `astro-page`, `content-migration`      |
| [`motion-designer`](agents/motion-designer.md)             | transitions, islands with animation                 | `motion`                               |
| [`content-i18n-migrator`](agents/content-i18n-migrator.md) | strings out of `app.js` into content collections    | `content-migration`                    |
| [`verification-engineer`](agents/verification-engineer.md) | keeping `verify.mjs` meaningful across the refactor | `verify-contract`, `visual-regression` |
| [`reviewer`](agents/reviewer.md)                           | merge gate; reads diffs, never writes features      | all                                    |

## Working agreement

1. **One task, one worktree, one agent.** See
   [`rules/git-worktrees.md`](rules/git-worktrees.md).
2. **Read `context/` first.** Especially `design-system.md` and
   `verification.md`. Most wrong answers here come from assuming the CSS is
   already coherent.
3. **Templates over invention.** `templates/components/` and `templates/pages/`
   exist so ten parallel agents produce one house style, not ten.
4. **The gate is `pnpm run verify` plus the relevant checklist.** Green tests
   with deleted assertions is a failed task.
5. **Report what you did not do.** Partial work with an honest boundary is
   useful; silent narrowing is not.

## Task flow

```
plans/astro-refactor/task-NN.md   ← the brief
        ↓
git worktree add ../af-task-NN    ← isolation
        ↓
agent loads .agents/agents/<role>.md + its skills
        ↓
checklists/before-*.md            ← self-gate
        ↓
pnpm run verify                    ← hard gate
        ↓
reviewer agent on the diff        ← merge gate
```