Files

T

Marcos Paulo aae4d42229 docs: add .agents workspace and the Astro refactor plan

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>

2026-09-05 01:18:27 +00:00

2.8 KiB

Raw Blame History

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/.

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

Working agreement

One task, one worktree, one agent. See rules/git-worktrees.md.
Read context/ first. Especially design-system.md and verification.md. Most wrong answers here come from assuming the CSS is already coherent.
Templates over invention. templates/components/ and templates/pages/ exist so ten parallel agents produce one house style, not ten.
The gate is npm run verify plus the relevant checklist. Green tests with deleted assertions is a failed task.
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

2.8 KiB Raw Blame History