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

Raw Blame History

name, description

name	description
content-migration	Move bilingual copy out of app.js and catalog.js into typed Astro content collections without losing or altering a single string. Use for any task that relocates user-visible text.

Content migration

What you are moving

app.js — ~50 { en, pt } keys across phases, handsOnPrompts, modelGuide, skillSources, skillInstallPrompts
skills-review/catalog.js + submitted-catalog.js — 24 entries with id, author, title, status, focus, wins[], improve[], extras, improved (full markdown)

These are hand-written translations with deliberate tone. Copy them. Never retype them. Retyping introduces drift you will not notice.

Schema

// src/content/config.ts
import { defineCollection, z } from 'astro:content';

const localized = z.object({ en: z.string(), pt: z.string() });

const guide = defineCollection({
  type: 'data',
  schema: z.object({
    id: z.string(),
    model: localized,
    title: localized,
    copy: localized,
    code: localized,
  }),
});

Both locales required. A missing pt must be a build error — silent English fallback is how a bilingual site quietly becomes monolingual.

Procedure

Extract the literals mechanically (script, not by hand).
Write them into the collection.
Diff extracted-before against extracted-after. Must be empty.

node .agents/scripts/extract-strings.mjs app.js          > /tmp/before.json
node .agents/scripts/extract-strings.mjs src/content/    > /tmp/after.json
diff /tmp/before.json /tmp/after.json

Only then delete the source literals.

The generator trap

skill-reviews/improved/**/SKILL.md is generated from catalog.js improved fields by scripts/build-skill-review.mjs, and the output is committed to the repo. If you move catalog.js, that generator breaks silently — it will still run, just against nothing.

Either keep the generator pointed at the new collection, or replace it and update package.json, README.md, docs/operations-guide.md, and the review desk footer, all of which reference it.

Markdown

The improved fields are full Markdown rendered client-side today. Move them to real .md files in the collection and let Astro render at build time. That deletes the hand-rolled renderer and improves fidelity — but re-check the review desk's diff view, which compares original and improved source text and needs the raw string, not just rendered HTML.

2.4 KiB Raw Blame History