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.3 KiB

Raw Blame History

Rule: git worktrees

This project teaches worktrees. It should use them properly.

One task, one worktree, one agent

# from the main checkout
git worktree add ../af-task-07 -b refactor/task-07-route-cards
cd ../af-task-07
npm ci

Naming: directory ../af-task-NN, branch refactor/task-NN-<slug>. Both derived from the task file so the mapping is never ambiguous.

Why isolation matters here

The migration runs many agents in parallel over the same small set of files (tokens.css, verify.mjs, astro.config.mjs are contended). Worktrees give each agent its own working directory over one object store — cheap, and no agent can see another's half-finished state.

The failure mode without them: two agents both "fix" verify.mjs, and the second overwrites the first's assertions.

Contended files

These are touched by many tasks. Whoever owns them per the plan is the only writer; everyone else opens an issue in their task report instead of editing:

File	Owner
`src/styles/tokens.css`	`design-system-keeper`
`scripts/verify.mjs`	`verification-engineer`
`astro.config.mjs`, `package.json`	`astro-architect`
`src/content/config.ts`	`content-i18n-migrator`

Before you start

git fetch origin && git rebase origin/main — start from current main.
Read your task file end to end before writing anything.
Confirm your task's dependencies are merged. Task files list them.

Before you finish

npm run verify green — without deleting assertions.
The relevant checklist in ../checklists/ complete.
git rebase origin/main again, resolve conflicts in your worktree.
Task report: what changed, what you verified, what you did not do.

Cleanup

cd -                                    # back to the main checkout
git worktree remove ../af-task-07
git branch -d refactor/task-07-route-cards

Stale worktrees hold locks and confuse the next agent. git worktree list should be short.

Never

Never work directly on main.
Never force-push a shared branch. The pages branch is the sole exception, and only if CI owns it (see ../context/publishing.md).
Never git add -A from the repository root. This repo has untracked local scratch (.serena/, scripts/inspect.py) that must not be swept into a commit.

2.3 KiB Raw Blame History