Marcos Paulo
48c31dc1b3
Ten git worktrees each carried their own 225 MB node_modules (1.1 GB across five) and paid 11s per `npm ci`. pnpm hardlinks from a shared store: the same five worktrees cost ~250 MB total, and a fresh install is 4s. What changed beyond the mechanical rename: - `overrides` moved to `pnpm-workspace.yaml`. pnpm 11 does not read the `pnpm` field in package.json *or* npm's top-level `overrides`, and it fails silently — the vite/defu/language-server pins would have quietly stopped applying. - Build scripts are blocked by default in pnpm; esbuild and sharp are allowed explicitly via `allowBuilds` (renamed from `onlyBuiltDependencies` in 11). - `packageManager` + `engines` pin the toolchain. - gate.sh rejects a package-lock.json/yarn.lock/bun.lock outright, so an agent running `npm install` out of habit fails loudly instead of building a second, divergent dependency tree. - CI bootstraps pnpm with `npm install --global pnpm@11.25.0` rather than corepack (unbundled as of Node 25) or pnpm/action-setup (this self-hosted act-runner has never run a job; fetching a third-party action is not something to discover on the first one). Two pre-existing CI bugs fixed while in the file: - the gate installed with `npm install --package-lock=false`, which discarded the lockfile the previous session had just fixed. - the visual-regression step imported `playwright`, which is not a dependency, and `visual-regression.mjs` has no compare mode anyway — in CI it overwrote its own baselines and passed unconditionally. Removed with a comment; it comes back when it can diff. The `publish` job is now manual (`workflow_dispatch`). During the migration dist/ holds three HTML files against the live pages branch's ten, so publishing on every push to main would take the site down to a stub. Restore at task 20. HANDOVER.md's incident log still says npm where it describes what happened at the time; that is history, not a missed rename. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
67 lines
3.3 KiB
Markdown
67 lines
3.3 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 `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
|
|
```
|