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>
This commit is contained in:
@@ -0,0 +1,48 @@
|
||||
# Rule: code style
|
||||
|
||||
## Match what is there
|
||||
|
||||
This codebase has a real voice: dense one-liner CSS, terse ES modules, comments
|
||||
that explain *why* and never *what*. Do not reformat it into someone else's
|
||||
house style as a side effect of a task.
|
||||
|
||||
The one exception is CSS minification-by-hand — `styles.css` is single-line and
|
||||
unreadable. Component `<style>` blocks should be normally formatted. That is an
|
||||
improvement, not a style disagreement.
|
||||
|
||||
## Comments
|
||||
|
||||
Write the comment that stops the next person from making a mistake. The existing
|
||||
codebase does this well:
|
||||
|
||||
```js
|
||||
// The cluster's nginx ingress runs with `use-forwarded-headers` off, so it
|
||||
// *overwrites* X-Forwarded-For with its own downstream peer — the VPS's
|
||||
// tailnet address — which would collapse every visitor into a single voter.
|
||||
```
|
||||
|
||||
That comment earns its place. `// set the colour` does not.
|
||||
|
||||
## Naming
|
||||
|
||||
- Components `PascalCase.astro`; everything else `kebab-case`.
|
||||
- Booleans read as assertions: `isOpen`, `hasVoted`, not `open`, `voted`.
|
||||
- No abbreviations that are not already in the codebase's vocabulary.
|
||||
|
||||
## TypeScript
|
||||
|
||||
Astro brings TS. Use it: typed props, typed collections, `strict` on. Never
|
||||
`any` — if the type is genuinely unknown, `unknown` plus a narrow.
|
||||
|
||||
## Dead code
|
||||
|
||||
Delete it. Do not comment it out, do not leave it behind a flag. Git remembers.
|
||||
|
||||
This matters here specifically: `responsive.css` is 30 KB of accumulated
|
||||
overrides, and the temptation during migration will be to port it wholesale
|
||||
"just in case". Prove each rule is needed or drop it.
|
||||
|
||||
## Commits
|
||||
|
||||
Present tense, lowercase, `type: subject`, matching the existing log
|
||||
(`feat:`, `fix:`, `docs:`). The body explains why, and states what you did not do.
|
||||
Reference in New Issue
Block a user