Marcos Paulo
aae4d42229
Adds the agent-facing workspace and a 20-task plan for migrating the site to Astro. Nothing here implements the refactor; these are briefs, rules and templates that the task agents read. - .agents/ holds context, rules, checklists, skills, specialist agents, component/page/config templates and gate scripts. It is vendor-neutral so MiniMax, Gemini and Codex can all read it; CLAUDE.md just points at AGENTS.md. - .husky/ plus .lintstagedrc.json wire the three gate tiers. gate.sh locks on the shared git-common-dir so parallel worktrees serialise, and guards the assertion count in scripts/verify.mjs against a coverage drop. - plans/astro-refactor/ carries the phase graph, per-task briefs and the model-routing recommendation. These files must be tracked before fanning out: a worktree only checks out tracked files, so an untracked plan is invisible to every agent working in one. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
65 lines
2.8 KiB
Markdown
65 lines
2.8 KiB
Markdown
# 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 `npm 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
|
|
↓
|
|
npm run verify ← hard gate
|
|
↓
|
|
reviewer agent on the diff ← merge gate
|
|
```
|