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

1.7 KiB

Raw Blame History

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:

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

1.7 KiB Raw Blame History