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

Raw Blame History

Rule: quality gates

Three tiers. Each is scoped so that many agents committing in parallel worktrees stay fast — the whole point is that a gate you are tempted to skip is not a gate.

Tier	Hook	Scope	Budget	Runs
1	`pre-commit`	staged files only (lint-staged)	< 3s	every commit
2	`pre-push`	whole project: build + verify + audit	< 90s	every push
3	CI (Gitea Actions)	tier 2 + visual regression	minutes	every push to `main`

Tier 1 must stay under a few seconds. If it creeps, move the check to tier 2. An agent that waits 40s per commit will start passing --no-verify, and then you have no gate at all.

Tier 1 — pre-commit (lint-staged)

Formats and lints only what you staged. Scoped by construction, so ten parallel worktrees do ten small jobs, not ten full-project sweeps.

Prettier + ESLint on *.{js,mjs,ts,astro}
Prettier + Stylelint on *.css
check-tokens.mjs on changed .astro/.css — catches raw hex before it lands
Prettier on *.{json,md}

Tier 2 — pre-push

The real gate:

astro check        types
astro build        it compiles
verify.mjs         42 content assertions — count must not fall
audit-ui.mjs       no external runtime dependencies
check-tokens.mjs   full sweep

Tier 3 — CI

Tier 2 plus screenshot comparison against .agents/snapshots/. Only CI has the budget for it.

Bypassing

--no-verify is allowed exactly once: a work-in-progress commit on your own task branch that you will rebase away. It is never allowed on a commit you intend to merge, and the pre-push gate has no bypass.

If a gate is wrong, fix the gate in its own commit. Do not route around it.

Parallelism

Hooks are per-worktree. Git's index.lock is per-worktree, so parallel commits do not contend.
The heavy tier-2 gate takes a lock (.git/af-gate.lock, shared across worktrees) so ten agents pushing at once do not run ten concurrent builds and thrash the machine. Waiters queue; they do not fail.
npm ci in a fresh worktree should use --prefer-offline to avoid registry contention when several spin up at once.

The silent-failure mode you must know about

Husky sets core.hooksPath to .husky/_, and .husky/_ is generated by npm install, not committed. A fresh git worktree add therefore has hooks configured but the directory missing — so hooks silently do not run. Every commit passes. Nothing is checked.

.agents/scripts/worktree.sh start runs the install and then verifies. Check manually any time you did not use it:

.agents/scripts/verify-hooks.sh

Run this first in any worktree you did not create with the script.

2.7 KiB Raw Blame History