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

Raw Blame History

name, description

name	description
astro-component	Build one Astro component for the ai-for-dummies site from the project templates. Use when creating a primitive, block, or island, or when splitting existing markup into a component.

Building an Astro component

Decide it should exist

Three occurrences, or a name a person says out loud. Two is not enough — see ../../rules/componentization.md.

Then place it:

primitives/ — no domain knowledge (Eyebrow, Rule, Callout, CodeBlock)
blocks/ — composed, page-agnostic, takes props (RouteCard, PhasePanel)
islands/ — interactive, justified, a leaf

Start from a template

cp .agents/templates/components/static-block.astro src/components/blocks/RouteCard.astro
# interactive? use island.astro instead

Templates exist so ten parallel agents produce one house style. Do not start from a blank file.

Write it

---
interface Props {
  number: string;
  title: string;
  summary: string;
  href: string;
}
const { number, title, summary, href } = Astro.props;
---
<article class="card">
  <b>{number}</b>
  <h2>{title}</h2>
  <p>{summary}</p>
  <a href={href}>Open chapter →</a>
</article>

<style>
  .card { display: grid; gap: 10px; padding: 22px; background: var(--paper); }
  b { color: var(--accent); font: var(--font-eyebrow); }
</style>

Rules that bite most often here:

No raw hex. Tokens only. check-tokens.mjs will fail you.
No client:* unless it is genuinely interactive, and say why in the PR.
Keep the gap:1px over a coloured parent trick where the original used it — it is the house style, not a bug.
Preserve every ARIA attribute from the markup you are replacing.

Prove it

Render it at 560 / 800 / 1100 / 1600 px.
Tab to it. Focus ring visible (outline: 3px solid #a7483f).
Diff its rendered text against the markup it replaced.
Run ../../checklists/before-component.md.
npm run verify — green, with no assertion deleted.

2.0 KiB Raw Blame History