Marcos Paulo
aae4d42229
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>
49 lines
1.7 KiB
Markdown
49 lines
1.7 KiB
Markdown
# 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.
|