Task 07 wrote px font sizes as the `font:` shorthand in two components
because check-tokens.mjs only matches `font-size:`. Green branch, two
hardcoded values. Make the expectation explicit: report the gap, stop.
Also fixes gates.md telling agents to rebase WIP commits away, which
git-worktrees.md forbids outright.
The build-skill-review.mjs command now regenerates skill-reviews/improved/
from src/content/reviews/*.md, not from skills-review/catalog.js. Update the
essential-commands line in AGENTS.md and the review desk footer in
skills-review/index.html to match. Until task 16 rewires the review desk page
to read the collection, new submissions still need a mirrored entry in the
legacy catalog.js — the footer spells that out explicitly.
Co-Authored-By: Claude Code <noreply@anthropic.com>
Move all 24 review entries from skills-review/catalog.js +
skills-review/submitted-catalog.js into a typed Astro content collection at
src/content/reviews/. Each entry is a Markdown file with frontmatter for the
review metadata (id, author, focus, wins, improve, extras, name, description)
and a body that holds the 'improved' SKILL.md content.
Re-point scripts/build-skill-review.mjs at the new collection. The generator
reads each .md file, parses its YAML frontmatter, and writes
skill-reviews/improved/{id}/SKILL.md in the same shape the legacy catalog
produced — verified byte-identical via 'git diff --exit-code skill-reviews/'.
The 'name' field is preserved separately from 'id' because two entries
renamed the skill during review (id angular-accessibility-root → name
angular-accessibility; id confectionary-skill-hub → name confectionery-orders).
Without it the generator output would drift on those two files.
Does not yet delete skills-review/catalog.js or submitted-catalog.js —
verify.mjs and the legacy review-desk page both still read them, so they
stay as a mirror until task 16 rewires the page to the collection. Adding a
new submission today requires editing both the .md file (new source of
truth) and the legacy catalog.js (until task 16).
Done-when:
- 24 entries under src/content/reviews/ ✓
- verify.mjs's id:' count assertion still passes ✓
- git diff --exit-code skill-reviews/ clean after regenerating ✓
- astro check passes (22 files: 0 errors, 0 warnings, 2 hints) ✓
Co-Authored-By: Claude Code <noreply@anthropic.com>
Migrate the bilingual copy in app.js (phases, handsOnPrompts, modelGuide,
skillSources, skillInstallPrompts) into per-collection data files under
src/content/, one folder per collection: phases/, providers/, efforts/,
skillSources/, handsOnPrompts/, skillInstallPrompts/. Strings copied
mechanically; the diff between the canonical extract-strings.mjs over a
flattened baseline of these guide blocks and the same extractor over the
new content directory is empty (56 strings total, 28 en + 28 pt).
efforts, handsOnPrompts, and skillInstallPrompts previously held arrays
of strings joined at runtime with .join('\n'); the new schema stores
them as plain strings, so canonical extract-strings.mjs cannot reach them
in their source shape. Verified byte-identical with /tmp/verify-nested.mjs
and /tmp/verify-install.mjs: every english/portuguese string in source
matches the migrated value, char-for-char.
What I did not do:
- delete the matching literals from app.js — task 15 removes them once
the page consumes the collection
- touch config.ts — the schema for these collections was set up in task 04
- move catalog.js, submitted-catalog.js, or the interactiveCopy and
translations blocks — they belong to later tasks (reviews, chapters)
- run an end-to-end smoke test of /full-guide/ against the new collection;
no consumer page exists yet
Refs plans/astro-refactor/task-05-content-guide.md.
The real-host smoke test was the migration's #1 production-only failure mode and
had never run. It has now run, without taking the site down: the Astro dist was
published to `pages` additively under two previously-unused paths (`_astro/` and
`_verify/summary/`), so all ten live pages stayed up, then force-pushed away.
Astro's base-prefixed absolute asset URLs resolve on the Pages Server — that was
the actual risk, and it is now proven rather than assumed. Trailing-slash
redirects match `trailingSlash: 'always'`.
Also corrects two things the guide got wrong:
- a `?v=$(git rev-parse --short HEAD)` cache-busting idiom. The Pages Server
caches for ten minutes keyed on path, so a query string never busted it; the
guide was telling operators to trust a check that could not work. A file you
just deleted keeps serving 200 until the cache expires.
- the claim that a push to `main` publishes. It no longer does, and must not
until cutover.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Task 03 rebased its branch onto task 01 and flattened the merge into four
duplicate commits — but the rule file was *telling* it to: "Before you start:
git rebase origin/main". Replaced with merge-based guidance and an explicit
prohibition, since a rewritten task branch is the same divergent-history trap
that broke the pages branch.
Also corrects gates.md tier 3, which promised screenshot comparison in CI that
is not wired in and cannot be until visual-regression.mjs grows a compare mode.
HANDOVER.md now reflects 01-04 merged, pnpm, and carries forward the review
findings that were noted but deliberately not fixed.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Ten git worktrees each carried their own 225 MB node_modules (1.1 GB across
five) and paid 11s per `npm ci`. pnpm hardlinks from a shared store: the same
five worktrees cost ~250 MB total, and a fresh install is 4s.
What changed beyond the mechanical rename:
- `overrides` moved to `pnpm-workspace.yaml`. pnpm 11 does not read the `pnpm`
field in package.json *or* npm's top-level `overrides`, and it fails silently
— the vite/defu/language-server pins would have quietly stopped applying.
- Build scripts are blocked by default in pnpm; esbuild and sharp are allowed
explicitly via `allowBuilds` (renamed from `onlyBuiltDependencies` in 11).
- `packageManager` + `engines` pin the toolchain.
- gate.sh rejects a package-lock.json/yarn.lock/bun.lock outright, so an agent
running `npm install` out of habit fails loudly instead of building a second,
divergent dependency tree.
- CI bootstraps pnpm with `npm install --global pnpm@11.25.0` rather than
corepack (unbundled as of Node 25) or pnpm/action-setup (this self-hosted
act-runner has never run a job; fetching a third-party action is not
something to discover on the first one).
Two pre-existing CI bugs fixed while in the file:
- the gate installed with `npm install --package-lock=false`, which discarded
the lockfile the previous session had just fixed.
- the visual-regression step imported `playwright`, which is not a dependency,
and `visual-regression.mjs` has no compare mode anyway — in CI it overwrote
its own baselines and passed unconditionally. Removed with a comment; it
comes back when it can diff.
The `publish` job is now manual (`workflow_dispatch`). During the migration
dist/ holds three HTML files against the live pages branch's ten, so publishing
on every push to main would take the site down to a stub. Restore at task 20.
HANDOVER.md's incident log still says npm where it describes what happened at
the time; that is history, not a missed rename.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Four task branches are green and unmerged, nothing is pushed, and three plan
bugs plus three agent mistakes were fixed along the way. Written so the next
session can pick up without re-deriving any of it.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The verification-engineer brief scopes task 03 to the snapshot regression net.
It also rewrote scripts/audit-ui.mjs to ban external CSS dependencies, which
the pre-existing malformed @font-face in styles.css violates, leaving the gate
red for every downstream task.
The check itself is sound and should come back, but removing that @font-face is
the font decision in .agents/context/design-system.md — task 02's call, and a
human one. Snapshot net kept intact.
Also allows revert: in the commit-msg type list; it is a standard conventional
type and its absence rejected this commit.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Capture rendered-text and visual baselines before route migration, and detect external CSS dependencies. Do not change verify.mjs assertions; task 02 must remove the known legacy font URL before the audit can pass.
- Created `src/styles/tokens.css` establishing the canonical 10-color palette, 5 designated breakpoints, and the 6-step typography scale.
- Created `src/styles/base.css` to import the root variables for Astro components.
- Wrote down decisions regarding the `--blue` palette canonicalization and the font stack simplification in the task brief.
- These tokens will power the Astro component refactors in parallel tasks.
Add src/content/config.ts with strict { en, pt } schema and eight
typed collections matching the shapes in app.js and
skills-review/catalog.js: phases, providers, efforts, skillSources,
handsOnPrompts, skillInstallPrompts, chapters, reviews.
Both locales are required on every localized field. A deliberately
missing pt fails the build with InvalidContentEntryDataError, proved
with a probe entry and reverted. Silent English fallback is what turns
a bilingual site monolingual; the schema must not allow it.
Did not move any content yet. Tasks 05 and 06 fill the entries
against the shape defined here, in parallel.
Also records the language-switching decision in the task brief:
client-side swap, both locales in the payload, html lang tracks the
active language. Behaviour parity, schema fit, and tiny payload
size beat the SEO upside of route-based i18n for this site.
astro check: 0 errors, 0 warnings. npm run verify: green. No
assertion count change.
Co-Authored-By: Claude Code <noreply@anthropic.com>
The launcher read the agent out of each brief with [a-z-]*, which cannot match
content-i18n-migrator. Tasks 04, 05 and 06 silently fell back to
astro-architect. Now also fails loudly if the name is missing or has no agent
definition, rather than launching the wrong specialist.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The first lockfile was reconstructed from a node_modules tree installed with
--package-lock=false, so its entries carried no resolved or integrity fields
and npm ci could not fetch from it. Regenerated from a clean install.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Standard conventional type, and its absence rejected a legitimate lockfile
commit during task 01.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The scaffold shipped with installs pinned to --package-lock=false, on a
misreading of AGENTS.md that has since been corrected. npm ci needs this file,
and npm ci is how every task worktree spins up.
Also adds 'build' to the commit-msg type list; it is a standard conventional
type and its absence rejected this very commit.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
AGENTS.md listed package-lock.json under 'Never touch', meaning never
hand-edit. Task 01's agent read it as never create, and shipped the scaffold
with no lockfile and installs pinned to --package-lock=false. That breaks the
parallel worktree setup outright: worktree.sh and launch.sh both spin up with
npm ci, which requires a lockfile.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The pre-existing root package.json has two scripts and no dependencies, and
there is no package-lock.json until task 01 scaffolds Astro, so every launch
died on `npm ci` before reaching the agent.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Routes each task to its CLI per MODEL-ROUTING.md (Codex for 01/03/15/16/19,
Gemini for 02/18, MiniMax for the rest), creates the worktree, installs the
toolchain once task 01 has produced a package.json, and runs the agent headless
with permission prompts disabled — these run unattended, and a blocked edit
would just hang.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
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>
`merge --ff-only main` cannot work: the histories diverged some time ago, so
the step fails with `Not possible to fast-forward` and the publish stalls.
Document the normal merge the branch's own history already uses, the stale
local `pages` fast-forward that has to happen first, the take-main-wholesale
conflict resolution, and the tree-equality check that is the real invariant.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The skills-review desk is static, so "which draft would you ship?" needs a
stateful counterpart. vote-service is a small Go API on its own pod backed by
a JSON file on a ReadWriteOnce PVC, with one active vote per skill per source
IP as the anti-abuse rule and CORS (ALLOWED_ORIGIN) as the caller boundary.
Deployment notes that differ from the obvious path, all confirmed against the
live cluster: the image is side-loaded with `ctr image import` plus
`imagePullPolicy: Never` because kubelet has no credentials for the Nexus ref;
the pod is pinned to `kubernets` because the hostpath PV takes a nodeAffinity
for whichever node first binds it; and public exposure is Caddy on the VPS,
not the cloudflared tunnel.
The ingress controller runs with `use-forwarded-headers` off, so nginx
overwrites X-Forwarded-For with its own peer — every visitor would collapse
into one voter and each skill would cap at one vote overall. Caddy stamps the
true remote address into X-Client-IP, which nginx forwards untouched, and
clientIP() reads that first. Scoped to this app rather than flipping the
global flag, which would change client-IP handling for every other ingress.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
- Add 'Source on Gitea' link next to every 'Open the X lab' link,
pointing to https://git.marcospaulo.dev.br/netcracker/ai-for-dummies/...
- Same download links added to both SilverBullet guides (Preview +
Source on Gitea) under Path A and Path B.
- Tighten standalone verify rule: only block external <script src> and
<link rel=stylesheet href>. Plain <a href=https://...> hyperlinks are
not runtime dependencies.
- Unslop pass across all deck text, SilverBullet EN/PT, hands-on/rules
header/label/README: kill triplets, dramatic single-word sentences,
'matrix below / looks good / cuts the opposite failure' rhetoric.
Header subtitle now reads 'Toggle rules. Same task, different
coverage.' (was 'different leash').
verify: all six checks pass.
- New section 'Verification' between hands-on and sources.
- Three evidence layers (static / behavior / integration), each with its
own exit-code-printing gate snippet.
- Four anti-pattern cards (pipe, swallow, cache, skip integration).
- 'Run it yourself' block links to /hands-on/starter and /hands-on/rules.
- Topnav gains 08 verify anchor.
- Companion SilverBullet pages (EN + PT) written under Guides/:
* 'AI For Dummies Verification and Evidence.md'
* 'AI For Dummies Verificação e Evidência.md'
- Both pages reference all 7 existing deck sections and the two labs.
Verify pass: content, interaction, and standalone for presentation, plus
the three rules-page checks.
- New hands-on/rules/ interactive page: five toggleable rule sources
(AGENTS.md, gate-discipline skill, Husky pre-commit, check-ui-contract
enforcer, commitlint) rebuild a ruled prompt live against a naive prompt.
- Visual system mirrors hands-on/starter (same palette, vanilla JS).
- index.html hands-on section now links both labs.
- docs/operations-guide.md gains a 'Hands-on rules lab' subsection.
- README project structure lists the new lab.
- verify.mjs passes content, interaction, and standalone checks for both labs.
Marcos Paulo