Files

T

Marcos Paulo f5631acb2c fix: say the lockfile is committed, not untouchable

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>

2026-09-05 02:08:08 +00:00

4.0 KiB

Raw Blame History

AGENTS.md

Entry point for any AI agent or new engineer working in this repository. Read this file, then follow the links you need. Full map: .agents/ORCHESTRATOR.md.

What is this project?

"AI For Dummies" — a bilingual (EN/PT-BR) presentation and workshop about working with coding agents: model routing, subagents, git worktrees, skills, rules, and verification. It is published as a static site on a self-hosted Gitea Pages Server, and it doubles as its own teaching artifact: the hands-on labs are dependency-free HTML/CSS/JS that workshop attendees point an agent at.

Current stack: hand-written HTML + CSS + ES modules, no build step, no dependencies
Target stack: Astro (see plans/astro-refactor/) — migration in progress
Languages: English and Brazilian Portuguese, toggled client-side
Companion service: vote-service/ (Go + Kubernetes) — separate lifecycle, see its own README

Essential commands

npm run verify     # content + interaction contracts (scripts/verify.mjs) — the gate
node scripts/audit-ui.mjs          # responsive / no-external-dependency audit
node scripts/build-skill-review.mjs # regenerate skill-reviews/improved/ from catalog.js
npm run serve      # python3 -m http.server 4173

npm run verify is not a formality. It is a set of ~42 string-token assertions that pin the site's real content and interactions. A refactor that "passes" by deleting assertions has failed. See .agents/context/verification.md.

Publishing

main is the source of truth. The pages branch is what the Gitea Pages Server actually serves, and its tree must end up identical to main's. The full procedure — including why merge --ff-only does not work here — is in docs/operations-guide.md.

Adding a build step changes this contract. Read .agents/context/publishing.md before doing so.

Never touch

hands-on/starter/ and hands-on/rules/ — lab fixtures. The exercise is that they are dependency-free vanilla HTML/CSS/JS an attendee can hand to an agent. Componentizing them destroys the lesson. They ship as static assets.
submitted-skills/ — other people's submitted work, reproduced verbatim
skill-reviews/improved/ — generated; edit skills-review/catalog.js instead
vote-service/ — separate deploy lifecycle; do not fold into the site build
dist/, node_modules/ — build output, never committed
package-lock.json — committed, but never hand-edited. Change it only as a side effect of npm install. Every worktree spins up with npm ci, which fails outright without it.

Rules

Binding. Read the one that covers what you are about to do.

Rule	When
`astro.md`	any `.astro` file
`theming.md`	any colour, font, or spacing value
`componentization.md`	creating or splitting a component
`animation.md`	any motion, transition, or transform
`accessibility.md`	any interactive element
`content-i18n.md`	any user-visible string
`code-style.md`	always
`git-worktrees.md`	starting or finishing a task

The one thing to understand first

This site's styling is not a design system today. Three near-duplicate palettes have drifted apart (--ink exists as #172f42, #122534, and #173044), and the @font-face rule in styles.css:1 is malformed, so the intended Manrope/DM Mono typography has never actually rendered. "Maintain the same styles" therefore needs a deliberate decision, not a copy-paste. Read .agents/context/design-system.md before touching any CSS.

4.0 KiB Raw Blame History