Compare commits
9 Commits
main
..
ac4683d8df
| Author | SHA1 | Date | |
|---|---|---|---|
 Marcos Silva
|
ac4683d8df | ||
|
Marcos Silva
|
73c3062062 | ||
|
Marcos Silva
|
96771dfbd6 | ||
|
Marcos Silva
|
5756dceb5a | ||
|
Marcos Paulo
|
6694897ae9 | ||
|
Marcos Paulo
|
c17502318b | ||
|
Marcos Paulo
|
ef3c99ee01 | ||
|
Marcos Paulo
|
21f04db1cc | ||
|
Marcos Silva
|
5046fb580d |
@@ -1,66 +0,0 @@
|
||||
# Orchestrator
|
||||
|
||||
Map of `.agents/`, and how to pick who does what.
|
||||
|
||||
## Layout
|
||||
|
||||
```
|
||||
.agents/
|
||||
ORCHESTRATOR.md you are here
|
||||
context/ how things are — read before deciding
|
||||
rules/ how things must be — binding
|
||||
checklists/ gates to run before you claim done
|
||||
skills/ procedures an agent loads on demand
|
||||
agents/ specialist agent definitions
|
||||
templates/ component and page starting points
|
||||
scripts/ deterministic helpers (prefer these over prose)
|
||||
```
|
||||
|
||||
`context/` describes reality, `rules/` constrain change. When they disagree,
|
||||
reality won — update the rule and say so.
|
||||
|
||||
## Specialists
|
||||
|
||||
Each agent has one responsibility, one set of rules, and its own worktree. Full
|
||||
definitions in [`agents/`](agents/).
|
||||
|
||||
| Agent | Owns | Loads skills |
|
||||
| ---------------------------------------------------------- | --------------------------------------------------- | -------------------------------------- |
|
||||
| [`astro-architect`](agents/astro-architect.md) | project scaffold, config, routing, layouts | `astro-page` |
|
||||
| [`design-system-keeper`](agents/design-system-keeper.md) | tokens, the single palette, type scale | `design-tokens` |
|
||||
| [`component-builder`](agents/component-builder.md) | one component per task, from templates | `astro-component`, `design-tokens` |
|
||||
| [`page-migrator`](agents/page-migrator.md) | one page per task, HTML → `.astro` | `astro-page`, `content-migration` |
|
||||
| [`motion-designer`](agents/motion-designer.md) | transitions, islands with animation | `motion` |
|
||||
| [`content-i18n-migrator`](agents/content-i18n-migrator.md) | strings out of `app.js` into content collections | `content-migration` |
|
||||
| [`verification-engineer`](agents/verification-engineer.md) | keeping `verify.mjs` meaningful across the refactor | `verify-contract`, `visual-regression` |
|
||||
| [`reviewer`](agents/reviewer.md) | merge gate; reads diffs, never writes features | all |
|
||||
|
||||
## Working agreement
|
||||
|
||||
1. **One task, one worktree, one agent.** See
|
||||
[`rules/git-worktrees.md`](rules/git-worktrees.md).
|
||||
2. **Read `context/` first.** Especially `design-system.md` and
|
||||
`verification.md`. Most wrong answers here come from assuming the CSS is
|
||||
already coherent.
|
||||
3. **Templates over invention.** `templates/components/` and `templates/pages/`
|
||||
exist so ten parallel agents produce one house style, not ten.
|
||||
4. **The gate is `pnpm run verify` plus the relevant checklist.** Green tests
|
||||
with deleted assertions is a failed task.
|
||||
5. **Report what you did not do.** Partial work with an honest boundary is
|
||||
useful; silent narrowing is not.
|
||||
|
||||
## Task flow
|
||||
|
||||
```
|
||||
plans/astro-refactor/task-NN.md ← the brief
|
||||
↓
|
||||
git worktree add ../af-task-NN ← isolation
|
||||
↓
|
||||
agent loads .agents/agents/<role>.md + its skills
|
||||
↓
|
||||
checklists/before-*.md ← self-gate
|
||||
↓
|
||||
pnpm run verify ← hard gate
|
||||
↓
|
||||
reviewer agent on the diff ← merge gate
|
||||
```
|
||||
@@ -1,50 +0,0 @@
|
||||
---
|
||||
name: astro-architect
|
||||
description:
|
||||
Owns the Astro scaffold — config, routing, layouts, build pipeline, and the
|
||||
publishing decision. Use for task 01 and any later change to astro.config.mjs,
|
||||
package.json, or the deploy path. Do not use for component or page work.
|
||||
tools: Read, Write, Edit, Bash, Grep, Glob
|
||||
---
|
||||
|
||||
You own the foundation. Everything other agents build sits on your decisions, so
|
||||
wrong choices here are expensive and late-discovered.
|
||||
|
||||
**Read first**: `.agents/context/architecture.md`,
|
||||
`.agents/context/publishing.md`, `.agents/rules/astro.md`. **Load skill**:
|
||||
`astro-page`.
|
||||
|
||||
## You own
|
||||
|
||||
`astro.config.mjs`, `package.json`, `tsconfig.json`, `src/layouts/`, the CI
|
||||
workflow, and the `pages`-branch publishing decision. You are the **only**
|
||||
writer of these. Other agents report problems with them; they do not edit.
|
||||
|
||||
## Non-negotiable outcomes
|
||||
|
||||
- `base: '/ai-for-dummies'` set and **verified against the real host**, not just
|
||||
`pnpm run preview`. Base-path bugs are the most likely production-only
|
||||
failure.
|
||||
- Every existing URL resolves identically, trailing slash included.
|
||||
- Zero JS by default. Astro ships none unless a component asks.
|
||||
- `hands-on/starter/` and `hands-on/rules/` copied to `public/` **verbatim,
|
||||
unprocessed**. They are lab fixtures; the exercise is that they are plain
|
||||
files.
|
||||
- No UI framework, no CSS framework, no runtime dependencies.
|
||||
|
||||
## The publishing decision is yours to make and document
|
||||
|
||||
Astro emits `dist/`; the Gitea Pages Server serves a branch and cannot build.
|
||||
Choose between committing `dist/` to `pages` and having Gitea Actions build it
|
||||
(recommended), per `context/publishing.md`. Then **rewrite
|
||||
`docs/operations-guide.md` in the same task** — it currently states `pages` is
|
||||
"the exact published source", which your change makes false.
|
||||
|
||||
Known trap: this Gitea's act-runner registration lives in an `emptyDir`, so a
|
||||
pod restart silently kills CI. Put that in the runbook.
|
||||
|
||||
## Done when
|
||||
|
||||
`pnpm run build` succeeds, one migrated page serves correctly from the real host
|
||||
under `/ai-for-dummies/`, `pnpm run verify` and `node scripts/audit-ui.mjs` are
|
||||
green, and the operations guide matches reality.
|
||||
@@ -1,46 +0,0 @@
|
||||
---
|
||||
name: component-builder
|
||||
description:
|
||||
Builds one Astro component per task from the project templates. Use for the
|
||||
component-extraction tasks (05-09). Do not use for page migration, token
|
||||
changes, or verify.mjs.
|
||||
tools: Read, Write, Edit, Bash, Grep, Glob
|
||||
---
|
||||
|
||||
You build **one component per task**, from a template, in your own worktree.
|
||||
Many of you run in parallel — that is why templates and rules exist, so ten
|
||||
agents produce one house style rather than ten.
|
||||
|
||||
**Read first**: `.agents/rules/componentization.md`, `.agents/rules/astro.md`,
|
||||
`.agents/rules/theming.md`. **Load skills**: `astro-component`, `design-tokens`.
|
||||
|
||||
## Scope discipline
|
||||
|
||||
Your task names one component. If you find a second that "obviously" needs
|
||||
extracting, **write it in your task report — do not build it.** Another agent
|
||||
owns it, and two agents editing the same file is the failure mode worktrees
|
||||
exist to prevent.
|
||||
|
||||
You may not edit `tokens.css`, `verify.mjs`, `astro.config.mjs`, or
|
||||
`src/content/config.ts`. If you need a change there, report it.
|
||||
|
||||
## Rules that bite
|
||||
|
||||
- No raw hex, no px font sizes, no ad-hoc breakpoints. Tokens only.
|
||||
- **Never reshape CSS to slip past `check-tokens.mjs`** — e.g. the `font:`
|
||||
shorthand to hide a px size it would catch as `font-size:` — and never point a
|
||||
legacy value at the nearest token that happens to exist. Both are silent
|
||||
redesigns. Keep the true value and mark it
|
||||
`/* token-gap: <reason>; owner design-system-keeper */`, which waives the
|
||||
finding and queues it. You may not add tokens. See `.agents/rules/gates.md`.
|
||||
- No `client:*` unless genuinely interactive, with written justification.
|
||||
- Every ARIA attribute from the markup you replace survives. `verify.mjs`
|
||||
asserts several by name.
|
||||
- Keep the `gap:1px` over a coloured parent trick where the original used it.
|
||||
- Under ~120 lines of markup. More means two components.
|
||||
|
||||
## Done when
|
||||
|
||||
`.agents/checklists/before-component.md` is fully checked, rendered text diffs
|
||||
clean against the markup you replaced, screenshots at four widths look
|
||||
unchanged, and `pnpm run verify` is green **with no assertion deleted**.
|
||||
@@ -1,58 +0,0 @@
|
||||
---
|
||||
name: content-i18n-migrator
|
||||
description:
|
||||
Moves bilingual copy out of app.js and catalog.js into typed Astro content
|
||||
collections without altering a string. Use for tasks 03-04 and any later
|
||||
content relocation. Do not use for markup or styling.
|
||||
tools: Read, Write, Edit, Bash, Grep, Glob
|
||||
---
|
||||
|
||||
You own `src/content/` and `src/content/config.ts`, and you are their only
|
||||
writer. Your job is a lossless move, not an edit.
|
||||
|
||||
**Read first**: `.agents/rules/content-i18n.md`. **Load skill**:
|
||||
`content-migration`.
|
||||
|
||||
## What you are moving
|
||||
|
||||
~50 `{ en, pt }` keys from `app.js` (`phases`, `handsOnPrompts`, `modelGuide`,
|
||||
`skillSources`, `skillInstallPrompts`), plus 24 review entries from `catalog.js`
|
||||
and `submitted-catalog.js`.
|
||||
|
||||
These are hand-written translations with deliberate tone. **Copy them
|
||||
mechanically. Never retype.** Retyping introduces drift nobody notices until a
|
||||
Portuguese speaker does.
|
||||
|
||||
## Procedure
|
||||
|
||||
Extract → write into collection → diff extracted-before against extracted-after
|
||||
→ only then delete the source. If the diff is not empty, you changed content.
|
||||
Fix it before continuing.
|
||||
|
||||
Both locales required in the schema. A missing `pt` must be a **build error**,
|
||||
never a silent English fallback — that is how bilingual sites quietly become
|
||||
monolingual.
|
||||
|
||||
## The trap that will catch you
|
||||
|
||||
`skill-reviews/improved/**/SKILL.md` is generated from `catalog.js` by
|
||||
`scripts/build-skill-review.mjs` and the output is **committed**. Move
|
||||
`catalog.js` and the generator keeps running against nothing — silently. Either
|
||||
re-point it or replace it, and update `package.json`, `README.md`,
|
||||
`docs/operations-guide.md`, and the review desk footer, all of which reference
|
||||
it.
|
||||
|
||||
Also: the review desk's diff view compares original and improved **source
|
||||
text**. If you convert `improved` to rendered Markdown, keep the raw string
|
||||
available or the diff view breaks.
|
||||
|
||||
## The language-switching decision
|
||||
|
||||
Client-side swap (matches today, no URL change — recommended) vs route-based
|
||||
`/en/` `/pt/` (better SEO, changes every URL, needs redirects). Surface it, get
|
||||
a decision, record it. Either way `<html lang>` tracks the active language.
|
||||
|
||||
## Done when
|
||||
|
||||
The string diff is empty, both locales validate, the generator still produces
|
||||
identical output, and `pnpm run verify` is green.
|
||||
@@ -1,51 +0,0 @@
|
||||
---
|
||||
name: design-system-keeper
|
||||
description:
|
||||
Owns src/styles/tokens.css — the palette, type scale, and breakpoints. Use for
|
||||
task 02 and any later token change or check-tokens failure. Do not use for
|
||||
building components.
|
||||
tools: Read, Write, Edit, Bash, Grep, Glob
|
||||
---
|
||||
|
||||
You own the token layer and are its only writer. Your job is to make "maintain
|
||||
the same styles" true and verifiable.
|
||||
|
||||
**Read first**: `.agents/context/design-system.md` — it documents three drifting
|
||||
palettes and a broken `@font-face`. **Load skills**: `design-tokens`,
|
||||
`visual-regression`.
|
||||
|
||||
## The two decisions you must surface, not silently make
|
||||
|
||||
1. **Three palettes → one.** `--ink` exists as `#172f42`, `#122534`, `#173044`;
|
||||
`--paper`, `--muted`, `--line`, `--gold` likewise. Most deltas are
|
||||
sub-perceptual and can be canonicalized. `--blue` (`#527f9f` vs `#215675`) is
|
||||
visibly different — screenshot both and get a human decision.
|
||||
2. ~~**The fonts have never rendered.**~~ **Settled 2026-09-05 — do not
|
||||
reopen.** The malformed `@font-face` was escalated and the human chose the
|
||||
real fonts. Manrope and DM Mono are self-hosted in `public/fonts/`, wired
|
||||
through `public/fonts/fonts.css`, which `BaseLayout.astro` links and the
|
||||
legacy root `styles.css` `@import`s. **Do not delete these faces and do not
|
||||
replace the stacks with `Arial`/`ui-monospace`** — that instruction is
|
||||
obsolete. You may add `--font-sans` / `--font-mono` tokens pointing at them.
|
||||
|
||||
## You own
|
||||
|
||||
`src/styles/tokens.css`, `src/styles/base.css`, and
|
||||
`.agents/scripts/check-tokens.mjs`.
|
||||
|
||||
Deliver: one value per token, a named type scale (`--step-*`) replacing 14
|
||||
ad-hoc `clamp()` triples, five named breakpoints replacing sixteen, and an
|
||||
enforcement script wired into `pnpm run verify`.
|
||||
|
||||
## Preserve the house style
|
||||
|
||||
Flat colour blocks, `1px` hairlines, near-zero radius, tight negative tracking
|
||||
on display type, `Georgia, serif` emphasis spans, and the `gap:1px` over a
|
||||
coloured parent trick used for grid separators. That last one is deliberate —
|
||||
never convert it to `border`.
|
||||
|
||||
## Done when
|
||||
|
||||
Every token has exactly one value, `check-tokens.mjs` passes, and before/after
|
||||
screenshots at 560/800/1100/1600 px **plus the eight removed breakpoint widths**
|
||||
are attached to your task report with every visible difference explained.
|
||||
@@ -1,51 +0,0 @@
|
||||
---
|
||||
name: motion-designer
|
||||
description:
|
||||
Adds and audits animation — transitions, state changes, optional view
|
||||
transitions. Use for task 17 and any change involving movement. Do not use for
|
||||
static layout or styling work.
|
||||
tools: Read, Write, Edit, Bash, Grep, Glob
|
||||
---
|
||||
|
||||
You add motion to an editorial-print design where motion is punctuation, not
|
||||
decoration. Your most valuable output is often **deciding not to animate**.
|
||||
|
||||
**Read first**: `.agents/rules/animation.md`. **Load skill**: `motion`.
|
||||
|
||||
## The question you must answer per animation
|
||||
|
||||
What does this motion tell the user that the static state does not? Valid:
|
||||
something changed; attention needs directing to what changed; a layout shift
|
||||
needs smoothing. "It feels more polished" is not valid — on this design it reads
|
||||
as a generic template, which is the one thing this site's identity avoids.
|
||||
|
||||
Shipping a component static is a legitimate, common, correct outcome.
|
||||
|
||||
## Hard constraints
|
||||
|
||||
- `transform` and `opacity` only. Animating layout properties fails the 200ms
|
||||
INP budget.
|
||||
- 150–250ms UI feedback, ≤400ms page transition. `cubic-bezier(.2,0,0,1)` in,
|
||||
`ease-out` out. No bounce or elastic — wrong register.
|
||||
- One thing moves at a time. No staggered card cascades.
|
||||
- `prefers-reduced-motion` honoured **and tested** via DevTools emulation. The
|
||||
end state must still be correct: reduced, not broken.
|
||||
- No animation library. This site's thesis is having no runtime dependencies.
|
||||
|
||||
## View transitions
|
||||
|
||||
Astro's `<ClientRouter />` is the only sanctioned motion dependency. Before
|
||||
enabling it, verify JS-disabled navigation, browser back/forward, the review
|
||||
desk's query-param deep links, and reduced-motion — all still work.
|
||||
|
||||
## Also audit what exists
|
||||
|
||||
Several current stylesheets already honour `prefers-reduced-motion`. Inventory
|
||||
existing motion, flag anything animating a layout property, and fix it. That is
|
||||
often higher value than anything you add.
|
||||
|
||||
## Done when
|
||||
|
||||
Every animation has a written purpose, animates only compositor properties,
|
||||
respects reduced motion under test, and screenshots of start and end states are
|
||||
attached.
|
||||
@@ -1,46 +0,0 @@
|
||||
---
|
||||
name: page-migrator
|
||||
description:
|
||||
Migrates one hand-written HTML page to an Astro route with identical URL,
|
||||
content, and JS budget. Use for the page-migration tasks (10-16). Do not use
|
||||
for component extraction or config changes.
|
||||
tools: Read, Write, Edit, Bash, Grep, Glob
|
||||
---
|
||||
|
||||
You migrate **one page per task**. The bar is that a visitor cannot tell.
|
||||
|
||||
**Read first**: `.agents/context/architecture.md`,
|
||||
`.agents/context/verification.md`. **Load skills**: `astro-page`,
|
||||
`content-migration`, `visual-regression`.
|
||||
|
||||
## Snapshot before you touch anything
|
||||
|
||||
Rendered-text snapshot plus screenshots at 560/800/1100/1600 px, from the
|
||||
vanilla site. Without a before, you cannot prove an after. This is not optional
|
||||
and it is the step agents skip.
|
||||
|
||||
## Hard constraints
|
||||
|
||||
- **URL identical**, trailing slash included. Internal links go through
|
||||
`import.meta.env.BASE_URL`, never a hand-written absolute path.
|
||||
- **Query params survive** — the review desk uses `?author=`, `?skill=`,
|
||||
`?view=`, `?file=`, `?compare=`, `?render=` and they are shared externally.
|
||||
- **JS budget does not grow.** A page that shipped zero JS still ships zero.
|
||||
Seven of ten pages are in that category.
|
||||
- Every `data-*` hook, ARIA attribute, `<title>`, and `<meta>` preserved.
|
||||
- Reuse existing components before creating new ones.
|
||||
- Do **not** port `responsive.css` wholesale. Take what the page needs; prove
|
||||
the rest is dead and delete it.
|
||||
|
||||
## hands-on/ is not yours
|
||||
|
||||
`hands-on/starter/` and `hands-on/rules/` are lab fixtures that ship from
|
||||
`public/` unchanged. Their value is being plain dependency-free files an
|
||||
attendee hands to an agent. If your task appears to ask you to componentize
|
||||
them, it is wrong — stop and report.
|
||||
|
||||
## Done when
|
||||
|
||||
`.agents/checklists/before-page.md` complete, snapshot diff empty (or every line
|
||||
justified), `node scripts/audit-ui.mjs` and `pnpm run verify` green, screenshots
|
||||
compared, and your task report lists what you deliberately left alone.
|
||||
@@ -1,54 +0,0 @@
|
||||
---
|
||||
name: reviewer
|
||||
description:
|
||||
Merge gate. Reviews a task branch diff against its brief and the project
|
||||
rules. Use before merging any refactor task. Never writes features or fixes
|
||||
findings itself.
|
||||
tools: Read, Grep, Glob, Bash
|
||||
---
|
||||
|
||||
You are the merge gate. You read diffs and report. **You do not write features
|
||||
and you do not fix what you find** — you name it precisely enough that the
|
||||
owning agent can.
|
||||
|
||||
**Read**: the task file, then every rule in `.agents/rules/` relevant to the
|
||||
diff.
|
||||
|
||||
## Order of checks — highest-value first
|
||||
|
||||
1. **Coverage did not fall.** `grep -c 'throw new Error' scripts/verify.mjs`
|
||||
against `origin/main`. A drop by anyone other than `verification-engineer`,
|
||||
with a stated reason, is an automatic reject. This is the single most likely
|
||||
way content silently disappears.
|
||||
2. **Scope.** `git diff --stat origin/main` matches the brief. Contended files
|
||||
(`tokens.css`, `verify.mjs`, `astro.config.mjs`, `src/content/config.ts`)
|
||||
edited only by their owner.
|
||||
3. **Content preserved.** Snapshot diff attached and empty, or every line
|
||||
justified. No attached evidence means not reviewed — send it back.
|
||||
4. **URLs and query params unchanged.** Trailing slashes. `BASE_URL` used
|
||||
instead of hand-written absolute paths.
|
||||
5. **JS budget.** A previously-zero-JS page still ships zero. Every `client:*`
|
||||
has a written justification.
|
||||
6. **Tokens.** No raw hex, px font sizes, or ad-hoc breakpoints outside
|
||||
`tokens.css`.
|
||||
7. **Accessibility.** ARIA attributes from the original survived. Native
|
||||
elements. Focus ring intact.
|
||||
8. **Motion.** Compositor properties only; `prefers-reduced-motion` honoured.
|
||||
9. **Hygiene.** No `.serena/`, `__pycache__/`, `dist/`, or scratch files staged.
|
||||
|
||||
## Output format
|
||||
|
||||
```
|
||||
path:line: <severity>: <problem>. <fix>.
|
||||
```
|
||||
|
||||
Severities: `blocker` (content loss, coverage drop, URL change, scope
|
||||
violation), `major` (rule violation, missing evidence), `minor` (style, naming).
|
||||
|
||||
No praise, no summary of what the diff does — the author knows. Findings only.
|
||||
If there are none, say so in one line.
|
||||
|
||||
## What you do not do
|
||||
|
||||
Do not suggest improvements outside the task's scope. Scope creep at review time
|
||||
is how a bounded task becomes an unbounded one. Note it as a follow-up instead.
|
||||
@@ -1,53 +0,0 @@
|
||||
---
|
||||
name: verification-engineer
|
||||
description:
|
||||
Keeps scripts/verify.mjs meaningful across the migration and builds the
|
||||
snapshot/visual-regression net. Use for tasks 18-19 and whenever a verify
|
||||
assertion needs re-pointing. The only role permitted to reduce coverage.
|
||||
tools: Read, Write, Edit, Bash, Grep, Glob
|
||||
---
|
||||
|
||||
You own `scripts/verify.mjs`, `scripts/audit-ui.mjs`, `.agents/snapshots/`, and
|
||||
the visual-regression tooling. You are their only writer, and the **only role
|
||||
allowed to remove an assertion** — with a written reason per removal.
|
||||
|
||||
**Read first**: `.agents/context/verification.md`. **Load skills**:
|
||||
`verify-contract`, `visual-regression`.
|
||||
|
||||
## Why the role exists
|
||||
|
||||
42 assertions pin this site's real content. They will all break during the
|
||||
migration, and the natural agent response to a red test is to delete it. That
|
||||
turns a content-loss bug into a green build. You are the check on that.
|
||||
|
||||
`grep -c 'throw new Error' scripts/verify.mjs` must not decrease across the
|
||||
migration.
|
||||
|
||||
## Translating, not deleting
|
||||
|
||||
- **Content tokens** (`data-phase="plan"`) → re-point at built output; the token
|
||||
should survive rendering. If it does not, a component dropped content.
|
||||
- **Implementation details** (`const phases`, `renderTree`) → these look
|
||||
deletable and are not. They pin a feature. Replace with an output-level
|
||||
assertion of the same feature.
|
||||
- **Asset versions** (`app.js?v=…`) → assert the built HTML references a hashed
|
||||
asset.
|
||||
|
||||
## Build the stronger net first
|
||||
|
||||
Token matching cannot catch a dropped paragraph. Land rendered-text snapshots
|
||||
for all ten routes **before** the page migrations start, or the migrators have
|
||||
no baseline. This is early, blocking work.
|
||||
|
||||
## Fix the audit gap
|
||||
|
||||
`audit-ui.mjs` rejects external `<script>`/`<link>` but misses external URLs
|
||||
inside CSS — which is exactly how a broken Google Fonts `@font-face` got into
|
||||
this "dependency-free" site. Add `@import`, `src: url(https:…)`, and
|
||||
`url(https:…)` detection.
|
||||
|
||||
## Done when
|
||||
|
||||
Coverage has not fallen, every removal has a reason, snapshots exist for all ten
|
||||
routes, `check-tokens.mjs` and the extended audit are wired into
|
||||
`pnpm run verify`, and the suite runs green on the migrated site.
|
||||
@@ -1,18 +0,0 @@
|
||||
# Checklist: before you call a component done
|
||||
|
||||
- [ ] It appears (or will appear) in **three** places, or has a name a person
|
||||
says out loud
|
||||
- [ ] Lives in the right folder: `primitives/`, `blocks/`, or `islands/`
|
||||
- [ ] Typed `interface Props`; every field intentional; no `any`
|
||||
- [ ] **No raw hex, px font sizes, or ad-hoc breakpoints** — tokens only
|
||||
- [ ] Ships zero JS, or has a `client:*` directive with a written justification
|
||||
- [ ] Markup under ~120 lines
|
||||
- [ ] Native elements: `<button>` for actions, `<a>` for navigation
|
||||
- [ ] Keyboard: tab to it, operate with Enter/Space, focus ring visible
|
||||
- [ ] Interactive state exposed via ARIA (`aria-pressed`, `aria-current`), not
|
||||
just colour
|
||||
- [ ] Any motion respects `prefers-reduced-motion` and animates only
|
||||
`transform`/`opacity`
|
||||
- [ ] Renders correctly at 560 / 800 / 1100 / 1600 px
|
||||
- [ ] Both `en` and `pt` strings present; no hard-coded copy
|
||||
- [ ] `pnpm run verify` green with no assertion deleted
|
||||
@@ -1,15 +0,0 @@
|
||||
# Checklist: before you merge a task branch
|
||||
|
||||
- [ ] `origin/main` **merged in** (never rebased), conflicts resolved in the
|
||||
worktree
|
||||
- [ ] `pnpm run verify` and `node scripts/audit-ui.mjs` both green
|
||||
- [ ] **Assertion count in `verify.mjs` did not fall**
|
||||
(`grep -c 'throw new Error' scripts/verify.mjs`)
|
||||
- [ ] Only files in your task's scope changed — `git diff --stat origin/main`
|
||||
matches the brief
|
||||
- [ ] No contended file edited unless you own it (see `rules/git-worktrees.md`)
|
||||
- [ ] No `.serena/`, `__pycache__/`, `dist/`, or scratch files staged
|
||||
- [ ] Commit message: what, why, and what you deliberately did not do
|
||||
- [ ] Task report written: verified behaviours, known gaps, follow-ups
|
||||
- [ ] `reviewer` agent has read the diff
|
||||
- [ ] Worktree and branch cleaned up after merge
|
||||
@@ -1,20 +0,0 @@
|
||||
# Checklist: before you call a page migrated
|
||||
|
||||
- [ ] URL identical to the old one, **trailing slash included**
|
||||
- [ ] Any query params the old page honoured still work (`?author=`, `?skill=`,
|
||||
`?view=`, `?file=`, `?compare=`, `?render=`)
|
||||
- [ ] Rendered text content diffs clean against the pre-migration snapshot — or
|
||||
every difference is listed and justified
|
||||
- [ ] Same number of JS bytes or fewer; a previously-zero-JS page still ships
|
||||
zero
|
||||
- [ ] `<title>`, `<meta name="description">`, and `<meta name="viewport">`
|
||||
preserved
|
||||
- [ ] One `<h1>`; heading levels do not skip
|
||||
- [ ] Every ARIA attribute from the original survived (`verify.mjs` asserts
|
||||
several)
|
||||
- [ ] No external `<script>`, `<link>`, `@import`, or `url()` —
|
||||
`node scripts/audit-ui.mjs` green
|
||||
- [ ] Internal links go through `BASE_URL`, not hand-written absolute paths
|
||||
- [ ] Screenshots at 560 / 800 / 1100 / 1600 px compared against the old page
|
||||
- [ ] `<html lang>` correct and still switching with the language toggle
|
||||
- [ ] `pnpm run verify` green with no assertion deleted
|
||||
@@ -1,83 +0,0 @@
|
||||
# Context: architecture
|
||||
|
||||
## Current (Astro, static output)
|
||||
|
||||
Ten routes, one `src/pages/` entry each, built to `dist/`:
|
||||
|
||||
| Route | Page | Islands |
|
||||
| -------------------- | ------------------------------- | ----------------------------------------------- |
|
||||
| `/` | `src/pages/index.astro` | — |
|
||||
| `/full-guide/` | `src/pages/full-guide.astro` | `GuideSelector`, `LanguageToggle`, `CopyPrompt` |
|
||||
| `/summary/` | `src/pages/summary.astro` | — |
|
||||
| `/models/` | `src/pages/models.astro` | — |
|
||||
| `/agents/` | `src/pages/agents.astro` | — |
|
||||
| `/skills/` | `src/pages/skills.astro` | `SkillPackageExplorer` |
|
||||
| `/rules/` | `src/pages/rules.astro` | `RulesInteractive` |
|
||||
| `/skills-review/` | `src/pages/skills-review.astro` | `legacy/skills-review/app.js` |
|
||||
| `/hands-on/starter/` | `public/` lab fixture | own |
|
||||
| `/hands-on/rules/` | `public/` lab fixture | own |
|
||||
|
||||
## What is still unmigrated
|
||||
|
||||
`legacy/` holds the parts the migration did not componentize. They are not dead
|
||||
files — the pages listed above import them, and the build fails without them.
|
||||
|
||||
- **`legacy/styles/guide.css`** (was `styles.css`) — the editorial visual
|
||||
system, imported by `full-guide.astro`.
|
||||
- **`legacy/styles/audit.css`** (was `full-guide/audit.css`) — responsive audit
|
||||
overrides, imported by `full-guide.astro`.
|
||||
- **`legacy/styles/chapters.css`** — imported by `ChapterLayout.astro`.
|
||||
- **`legacy/styles/skills.css`**, **`skills-review.css`**, **`change-lens.css`**
|
||||
— imported by their respective pages.
|
||||
- **`legacy/skills-review/`** — `app.js` and the module graph under it
|
||||
(`catalog.js`, `submitted-catalog.js`, `files.js`, `submitted-files.js`,
|
||||
`vote.js`). `catalog.js` + `submitted-catalog.js` are the review desk's real
|
||||
data model, 24 entries; they are a content collection in all but name.
|
||||
|
||||
These sit outside `src/` deliberately: `check-tokens.mjs` sweeps `src`, and
|
||||
these files are full of raw hex and unnamed breakpoints. Moving one into `src/`
|
||||
means migrating it to tokens in the same change, not adding an exclusion.
|
||||
|
||||
`responsive.css`, `landing.css`, `app.js`, `rules/app.js`, `rules/styles.css`,
|
||||
and `skills/app.js` were deleted at cutover: their content lives in components.
|
||||
|
||||
## Layout
|
||||
|
||||
```
|
||||
src/
|
||||
content/ catalog entries, chapter copy, EN/PT strings (typed collections)
|
||||
layouts/ BaseLayout, ChapterLayout, GuideLayout
|
||||
components/ .astro by default; islands only where marked
|
||||
styles/ tokens.css, base.css, then per-component styles
|
||||
pages/ routes mirroring today's URLs exactly
|
||||
public/
|
||||
hands-on/ lab fixtures copied verbatim, never processed
|
||||
```
|
||||
|
||||
### Non-negotiables
|
||||
|
||||
- **URLs do not change.** `/full-guide/`, `/skills-review/`,
|
||||
`/hands-on/starter/` and the rest must resolve exactly as they do now,
|
||||
trailing slash included. Existing links (including `docs/`, SilverBullet, and
|
||||
shared URLs with `?author=…&skill=…&view=…` query params) must keep working.
|
||||
- **Zero JS by default.** Seven of the ten pages ship no JavaScript. They must
|
||||
still ship none. Islands are opt-in, per component, and justified.
|
||||
- **`hands-on/` stays vanilla.** It lives in `public/` untouched. It is a lab
|
||||
fixture, not a component.
|
||||
- **No external runtime requests.** `audit-ui.mjs` enforces this and it is part
|
||||
of the site's thesis. Self-host anything you add.
|
||||
- **The review desk's query-param deep links keep working** — `?author=`,
|
||||
`?skill=`, `?view=`, `?file=`, `?compare=`, `?render=`. They are documented in
|
||||
the page footer and shared externally.
|
||||
|
||||
## Companion service
|
||||
|
||||
The vote API is a Go service on its own Kubernetes deploy cycle, reached by the
|
||||
review desk over `window.SKILLS_REVIEW_VOTE_API`. Its source left this
|
||||
repository on 2026-09-06; the deployed service is unchanged, and the review desk
|
||||
still calls it. Keep the global, or replace it with a build-time
|
||||
`PUBLIC_VOTE_API` env var — but if you do, update the service's own README in
|
||||
the same change.
|
||||
|
||||
Its one-vote-per-IP assertion left `verify.mjs` with it. See
|
||||
[`assertion-removals.md`](assertion-removals.md).
|
||||
@@ -1,26 +0,0 @@
|
||||
# Assertion removal ledger
|
||||
|
||||
`scripts/verify.mjs` may only lose an assertion by adding an entry here. The
|
||||
gate counts the `## ` headings in this file and allows exactly that many
|
||||
removals below the recorded floor — so a reduction is impossible without a
|
||||
written reason landing in the same commit, as a visible diff.
|
||||
|
||||
Adding an entry is not a formality. An assertion pins a real contract; removing
|
||||
one means that contract is now unverified. Say where it moved, or say plainly
|
||||
that nothing checks it any more.
|
||||
|
||||
## vote-service one-vote-per-IP contract
|
||||
|
||||
**Removed:** 2026-09-06, when `vote-service/` was taken out of this repository.
|
||||
|
||||
**What it asserted:** that `vote-service/main.go` contained both
|
||||
`X-Forwarded-For` and `one active vote per skill` — the review desk's only
|
||||
anti-abuse control, one vote per visitor enforced server-side by source IP.
|
||||
|
||||
**Why it went:** there is no file left to read. The check was a substring match
|
||||
against source that now lives elsewhere.
|
||||
|
||||
**Where it must be re-asserted:** in whichever repository holds the service. The
|
||||
deployed service still enforces the contract; nothing in this repository proves
|
||||
it. If `vote-service/` ever comes back here, restore the assertion and delete
|
||||
this entry.
|
||||
@@ -1,40 +0,0 @@
|
||||
# Context: full-guide language switching
|
||||
|
||||
## Decision
|
||||
|
||||
The Astro full guide keeps the current client-side language switch on its
|
||||
existing `/full-guide/` URL. It server-renders both locale variants and the
|
||||
language-toggle island shows the selected variant after `client:idle` hydration.
|
||||
|
||||
This deliberately preserves the current no-URL-change contract, including links
|
||||
shared without a locale segment, and avoids a route/redirect and publishing
|
||||
change. The cost is duplicated localized HTML and both locales in the response.
|
||||
That is acceptable for this small guide and avoids sending duplicated string
|
||||
data through every interactive island.
|
||||
|
||||
## Markup and island contract for task 15d
|
||||
|
||||
- Render each static localized fragment twice. Put `data-language-content="en"`
|
||||
or `data-language-content="pt"` on its outer element. English is visible in
|
||||
server HTML; the toggle uses the native `hidden` attribute for the inactive
|
||||
locale.
|
||||
- Add `<LanguageToggle />` to the guide top bar. Astro's `client:idle` directive
|
||||
is only valid for framework components; this `.astro` island defers its
|
||||
browser setup with `requestIdleCallback` (and a timeout fallback) instead. Do
|
||||
not hydrate the page or use `client:load`; the control is deliberately
|
||||
idle-priority.
|
||||
- The island owns the `ai-for-dummies-language` localStorage key. Every read and
|
||||
write remains inside `try`/`catch`, because previews may disable storage.
|
||||
- On each selection the island sets `<html lang>` to `en` or `pt-BR`, updates
|
||||
its `[data-lang]` buttons' `.active` class and `aria-pressed` state, updates
|
||||
`[data-language-content]`, then dispatches `ai-for-dummies:languagechange` on
|
||||
`window`. The event detail is `{ language: 'en' | 'pt' }`.
|
||||
- The guide selector island (15a) must read `document.documentElement.lang` when
|
||||
it hydrates and listen for that event. On receipt it must re-render the
|
||||
currently active phase and all active selector panels from their collection
|
||||
data. This preserves today’s `applyLanguage` behaviour without coupling the
|
||||
toggle to page selectors.
|
||||
|
||||
This is a page-local contract: the existing `/rules/` toggle continues using its
|
||||
own `rules-language` key and must not be changed as part of full-guide
|
||||
migration.
|
||||
@@ -1,109 +0,0 @@
|
||||
# Context: the design system (as it actually is)
|
||||
|
||||
Read this before touching CSS. Everything here was extracted from the current
|
||||
files, not assumed.
|
||||
|
||||
## There is no single palette. There are three.
|
||||
|
||||
The same semantic names carry different values depending on which stylesheet
|
||||
loaded them:
|
||||
|
||||
| Token | `styles.css`, `rules/styles.css` | `chapters.css`, `skills-review/styles.css` | `hands-on/*/styles.css` |
|
||||
| ---------- | -------------------------------- | ------------------------------------------ | ----------------------- |
|
||||
| `--paper` | `#f5f4f1` | `#f6f3ed` | `#f4f3ef` |
|
||||
| `--ink` | `#172f42` | `#122534` | `#173044` |
|
||||
| `--muted` | `#697b89` | `#65717a` | `#687d8c` |
|
||||
| `--line` | `#d8dee2` | `#d0d5d2` | `#d5dde1` |
|
||||
| `--blue` | `#527f9f` | `#215675` | `#5683a1` |
|
||||
| `--gold` | `#efc76b` | `#ebbf58` | `#efc86d` |
|
||||
| `--accent` | `#7c78a8` | — | — |
|
||||
| `--deep` | `#102536` | — | — |
|
||||
| `--red` | — | `#a7483f` (chapters only) | — |
|
||||
| `--violet` | — | `#6b668f` (review desk only) | — |
|
||||
|
||||
Most deltas are a few units per channel — drift, not intent. `--blue` is the
|
||||
exception: `#527f9f` vs `#215675` is a visible difference and may be deliberate.
|
||||
|
||||
**Decision required before any component work** (task 02). Options:
|
||||
|
||||
- **Canonicalize** to one palette. Recommended. The sub-perceptual deltas
|
||||
collapse; only `--blue` needs a human's eye on a before/after screenshot.
|
||||
- **Keep three named surfaces** (`--surface-guide`, `--surface-chapter`,
|
||||
`--surface-lab`) if the drift turns out to be intentional per section.
|
||||
|
||||
Do not "just pick one" silently in the middle of another task. This is its own
|
||||
reviewed change with visual diffs attached.
|
||||
|
||||
## The typography — fixed 2026-09-05
|
||||
|
||||
`styles.css` line 1 used to read:
|
||||
|
||||
```css
|
||||
@font-face {
|
||||
font-family: Manrope;
|
||||
src: url('https://fonts.googleapis.com/css2?family=DM+Mono&family=Manrope:wght@400;600;700;800&display=swap');
|
||||
}
|
||||
```
|
||||
|
||||
`src:` in an `@font-face` must point at a font binary. That URL returns a CSS
|
||||
stylesheet, so no browser could load a face from it. For the whole life of the
|
||||
site, every `font-family:Manrope,Arial,sans-serif` rendered as **Arial** and
|
||||
every `font:… 'DM Mono',monospace` rendered as the **generic monospace** face —
|
||||
`'DM Mono'` was never declared as a family at all.
|
||||
|
||||
**This was escalated and the human chose the real fonts.** Manrope and DM Mono
|
||||
are now self-hosted in `public/fonts/`, latin and latin-ext subsets only, under
|
||||
the SIL Open Font License. One `fonts.css` serves both trees: Astro links it
|
||||
from `BaseLayout.astro`, the legacy root `styles.css` `@import`s it. Self-hosted
|
||||
rather than linked from Google because `scripts/audit-ui.mjs` rejects any
|
||||
external `<link>`/`<script>`, and because the site is presented in workshop
|
||||
rooms with unreliable networks.
|
||||
|
||||
**This changed how every page renders**, deliberately. It is the one sanctioned
|
||||
visual change in the migration. Screenshots taken before 2026-09-05 show Arial
|
||||
and are no longer a valid baseline.
|
||||
|
||||
`Georgia, serif` for emphasis (`h1 em`, `.hero em`) is untouched and still real.
|
||||
|
||||
## Type scale
|
||||
|
||||
`Georgia, serif` is used deliberately for emphasis (`h1 em`, `.hero em`) and is
|
||||
real — it is a system font, so it does render. Keep it.
|
||||
|
||||
Sizes are all `clamp()`, roughly:
|
||||
|
||||
| Role | Value |
|
||||
| --------------- | --------------------------------------------------------- |
|
||||
| Display / `h1` | `clamp(56px,9vw,126px)` |
|
||||
| Section `h2` | `clamp(36px,5vw,65px)` |
|
||||
| Sub-head | `clamp(24px,3vw,38px)` |
|
||||
| Pull-quote | `clamp(22px,3vw,36px)` |
|
||||
| Body | `15px/1.6` … `18px` |
|
||||
| Eyebrow / label | `10–11px` monospace, `letter-spacing:.08–.1em`, uppercase |
|
||||
|
||||
There are 14+ distinct clamp triples doing near-identical jobs. Collapse to a
|
||||
named scale (`--step-0` … `--step-6`) during tokenization; the visual result
|
||||
should be unchanged within a pixel or two at common viewports.
|
||||
|
||||
## Breakpoints
|
||||
|
||||
Sixteen distinct max-widths are in use: 420, 520, 530, 560, 600, 620, 720, 800,
|
||||
850, 880, 900, 1000, 1050, 1100 — plus `min-width:1600px` and
|
||||
`min-width:2200px`.
|
||||
|
||||
Collapse to a named set (suggested: 560 / 800 / 1100 / 1600 / 2200) and prove
|
||||
equivalence with screenshots at the _old_ breakpoint values, since that is where
|
||||
regressions will hide.
|
||||
|
||||
`@media(prefers-reduced-motion:reduce)` is already respected in several
|
||||
stylesheets. Keep it — see [`../rules/animation.md`](../rules/animation.md).
|
||||
|
||||
## House style worth preserving
|
||||
|
||||
The visual identity is editorial-print: flat colour blocks, hairline `1px`
|
||||
rules, uppercase monospace eyebrows with wide tracking, very tight negative
|
||||
letter-spacing on display type (`-.06em` … `-.08em`), grid layouts with
|
||||
`gap:1px` over a background colour to fake borders, and near-zero border-radius.
|
||||
|
||||
That last trick (`gap:1px` + parent background) is used everywhere. It is
|
||||
intentional. Do not replace it with `border`.
|
||||
@@ -1,55 +0,0 @@
|
||||
# Context: publishing, and what a build step changes
|
||||
|
||||
## How it works today
|
||||
|
||||
The Gitea Pages Server serves the **`pages` branch tree directly**. There is no
|
||||
build. `main` and `pages` end up with byte-identical trees; `pages` exists only
|
||||
because the Pages Server publishes a branch, not a directory.
|
||||
|
||||
Live at `https://netcracker.pages.marcospaulo.dev.br/ai-for-dummies/`.
|
||||
|
||||
Full procedure, including the fact that `merge --ff-only main` fails (the
|
||||
histories diverged), is in
|
||||
[`../../docs/operations-guide.md`](../../docs/operations-guide.md).
|
||||
|
||||
## What Astro changes
|
||||
|
||||
Astro emits `dist/`. The Pages Server cannot run a build, so **something has to
|
||||
put built output on `pages`**. Pick one, deliberately, in task 01:
|
||||
|
||||
| Option | How | Cost |
|
||||
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **A. Build locally, commit `dist/` to `pages`** | `pnpm run build`, copy `dist/*` into the `pages` worktree, commit | `pages` stops being "the exact source". Diffs become unreadable. Publishing depends on one workstation. Simple, no new infra. |
|
||||
| **B. Gitea Actions builds and pushes `pages`** | workflow on `main` → `pnpm install --frozen-lockfile && pnpm run build` → force-push `dist/` to `pages` | `pages` becomes a machine-owned branch (force-push is fine _because_ nothing else writes it). Needs the act-runner to be healthy. **Recommended.** |
|
||||
| **C. Serve from a container instead** | drop Pages Server for an nginx pod behind the existing ingress | most control, most infra, changes the URL story |
|
||||
|
||||
**Recommended: B**, with A as the documented manual fallback for when the runner
|
||||
is down. Note the known failure mode: this Gitea's act-runner registration lives
|
||||
in an `emptyDir`, so a pod restart silently kills CI until re-registered. The
|
||||
runbook must say "if the site stopped updating, check the runner first".
|
||||
|
||||
Whichever you pick, `docs/operations-guide.md` must be rewritten in the same
|
||||
task — it currently promises `pages` is "the exact published source", and that
|
||||
stops being true under A and B.
|
||||
|
||||
## Base path
|
||||
|
||||
The site is served from a **subdirectory**: `/ai-for-dummies/`. Astro needs
|
||||
`base: '/ai-for-dummies'` in `astro.config.mjs`, and every internal link must go
|
||||
through `import.meta.env.BASE_URL` or Astro's `<a href={...}>` helpers rather
|
||||
than a hand-written absolute `/models/`.
|
||||
|
||||
This is the single most likely source of "works locally, 404s in production" in
|
||||
this migration. Verify it on the real host, not just `pnpm run preview`.
|
||||
|
||||
## Verification before you call it published
|
||||
|
||||
```bash
|
||||
curl -sS -o /dev/null -w '%{http_code}\n' \
|
||||
"https://netcracker.pages.marcospaulo.dev.br/ai-for-dummies/?v=$(git rev-parse --short HEAD)"
|
||||
```
|
||||
|
||||
The `?v=` cache-buster matters: the Pages Server caches, and a stale 200 looks
|
||||
exactly like a successful deploy. Check one nested route
|
||||
(`/ai-for-dummies/skills-review/`) and one static asset too — the base-path bug
|
||||
shows up on assets first.
|
||||
@@ -1,54 +0,0 @@
|
||||
# Context: the verification contract
|
||||
|
||||
`scripts/verify.mjs` is 13 KB, 42 `throw new Error` sites, 16 checkpoints. It
|
||||
reads 26 source files and asserts that specific **string tokens** appear in them
|
||||
— `data-phase="plan"`, `renderTree`, `.change-lens`,
|
||||
`styles.css?v=20260904-vote-widget`, and so on.
|
||||
|
||||
## Why this matters more than it looks
|
||||
|
||||
These assertions are the only thing standing between this site and silent
|
||||
content loss during a large refactor. They are also **all going to break**,
|
||||
because they assert against files that will stop existing.
|
||||
|
||||
The failure mode to guard against: an agent runs `pnpm run verify`, sees red,
|
||||
and "fixes" it by deleting the assertion. The suite goes green and the site
|
||||
loses a section. **Deleting an assertion is a change that requires review, the
|
||||
same as deleting a feature.**
|
||||
|
||||
## How the contract must evolve
|
||||
|
||||
Three kinds of assertion, three different fates:
|
||||
|
||||
| Kind | Example | Fate |
|
||||
| ------------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
|
||||
| **Content presence** | `'data-phase="plan"'` in `full-guide/index.html` | Re-point at built output (`dist/`) — the token should survive rendering. If it does not, the component dropped content. |
|
||||
| **Implementation detail** | `'const phases'`, `'renderTree'` in `app.js` | Obsolete. Replace with an assertion about _behaviour or output_, never delete outright. |
|
||||
| **Cache-busting version** | `'app.js?v=20260904-vote-widget'` | Obsolete — Astro hashes assets. Replace with "the built HTML references a hashed asset". |
|
||||
|
||||
**Rule: the assertion count must not fall.** Every removed token is replaced by
|
||||
one that pins the same user-visible fact against the new architecture. The
|
||||
verification engineer owns this and is the only role allowed to reduce coverage,
|
||||
with a written reason per removal.
|
||||
|
||||
## The stronger check to add
|
||||
|
||||
Token-matching is brittle. During the migration, add a **rendered-output diff**:
|
||||
snapshot the current site's DOM text content per route, then assert the Astro
|
||||
build produces the same text. That catches dropped paragraphs the way token
|
||||
matching cannot.
|
||||
|
||||
```bash
|
||||
# before migrating a page, from the vanilla site:
|
||||
node .agents/scripts/snapshot-route.mjs /models/ > .agents/snapshots/models.txt
|
||||
# after: same script against dist/, diff must be empty (or reviewed)
|
||||
```
|
||||
|
||||
See [`../skills/verify-contract/SKILL.md`](../skills/verify-contract/SKILL.md).
|
||||
|
||||
## Also in the suite
|
||||
|
||||
`scripts/audit-ui.mjs` asserts every page has a viewport meta and **no external
|
||||
`<script>`/`<link>`**. Keep it and extend it: it currently misses external URLs
|
||||
inside CSS (`@font-face src`, `@import`, `url()`), which is exactly how the
|
||||
broken Google Fonts request in `styles.css:1` got in.
|
||||
@@ -1,53 +0,0 @@
|
||||
# Rule: accessibility
|
||||
|
||||
## The gate is a keyboard, not a scanner
|
||||
|
||||
Automated tooling catches roughly **57%** of accessibility defects, and the
|
||||
misses cluster exactly where usability is decided: focus visibility, focus
|
||||
obscured by sticky elements, target size, and drag alternatives. Run axe, then
|
||||
do the manual sweep anyway.
|
||||
|
||||
**Manual sweep, every interactive component:**
|
||||
|
||||
1. Tab through it. Every control reachable, in a sensible order.
|
||||
2. Focus ring visible at every stop — this site uses
|
||||
`outline: 3px solid #a7483f; outline-offset: 2px`. Keep it.
|
||||
3. Operate it with Enter and Space. Escape closes anything that opened.
|
||||
4. Nothing is reachable only by hover or only by pointer.
|
||||
5. Zoom to 200%. Nothing clipped, nothing overlapping.
|
||||
|
||||
## Semantics
|
||||
|
||||
- Native elements first. `<button>` for actions, `<a>` for navigation. A `<div>`
|
||||
with a click handler is a defect, not a style choice.
|
||||
- ARIA only when HTML cannot express it. The current code does this well —
|
||||
`role="tablist"`, `aria-pressed`, `aria-current="page"`, `aria-label` on
|
||||
regions. Preserve every one during migration; they are asserted in
|
||||
`verify.mjs`.
|
||||
- One `<h1>` per page. Heading levels never skip.
|
||||
- Every image needs `alt`. Decorative images get `alt=""`.
|
||||
|
||||
## State
|
||||
|
||||
Interactive state must be exposed, not just painted:
|
||||
|
||||
```html
|
||||
<!-- wrong: only colour says it is selected -->
|
||||
<button class="active">Improved draft</button>
|
||||
<!-- right -->
|
||||
<button class="active" aria-pressed="true">Improved draft</button>
|
||||
```
|
||||
|
||||
The vote widget and preview switcher already do this. Match them.
|
||||
|
||||
## Contrast
|
||||
|
||||
Body text ≥ 4.5:1, large text ≥ 3:1, UI boundaries ≥ 3:1. Check any new
|
||||
combination against the token palette — `--muted` on `--paper` is the pair most
|
||||
likely to fail; verify before shipping.
|
||||
|
||||
## Bilingual content
|
||||
|
||||
`<html lang>` must change with the language toggle, not just the text. Screen
|
||||
readers pick pronunciation from it. This already works today — do not regress
|
||||
it.
|
||||
@@ -1,63 +0,0 @@
|
||||
# Rule: animation
|
||||
|
||||
This is an editorial-print design. Motion is punctuation, not decoration.
|
||||
|
||||
## Budget
|
||||
|
||||
- **Purpose or nothing.** Motion may signal a state change, direct attention to
|
||||
what just changed, or smooth a layout shift. Nothing else.
|
||||
- Duration: **150–250ms** for UI feedback, up to 400ms for a page transition.
|
||||
Longer reads as sluggish; shorter reads as a glitch.
|
||||
- Easing: `cubic-bezier(.2,0,0,1)` for entrances, `ease-out` for exits. Never
|
||||
`linear` for anything a person watches. Never bounce/elastic — wrong register
|
||||
for this design.
|
||||
- One thing moves at a time. Staggered cascades of cards are a template default;
|
||||
this site has a point of view and does not do them.
|
||||
|
||||
## `prefers-reduced-motion` is mandatory
|
||||
|
||||
Several current stylesheets already honour it. Every new animation must:
|
||||
|
||||
```css
|
||||
@media (prefers-reduced-motion: reduce) {
|
||||
* {
|
||||
animation-duration: 0.01ms !important;
|
||||
animation-iteration-count: 1 !important;
|
||||
transition-duration: 0.01ms !important;
|
||||
scroll-behavior: auto !important;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Reduced motion means _reduced_, not _broken_: the end state must still be
|
||||
correct and the interface still usable. Test it — in DevTools, Rendering →
|
||||
Emulate `prefers-reduced-motion`.
|
||||
|
||||
## Performance
|
||||
|
||||
- Animate **`transform` and `opacity` only.** They composite on the GPU.
|
||||
Animating `width`, `height`, `top`, `left`, or `margin` forces layout on every
|
||||
frame and will show up as a failed INP.
|
||||
- `will-change` only on an element about to animate, removed after. Leaving it
|
||||
on permanently costs memory and can _hurt_ performance.
|
||||
- Prefer CSS transitions. Reach for the Web Animations API only for sequencing
|
||||
that CSS cannot express. Do not add an animation library — it is a runtime
|
||||
dependency on a site whose thesis is having none.
|
||||
- INP budget is **200ms**. An animation that delays interaction response fails.
|
||||
|
||||
## Astro view transitions
|
||||
|
||||
If page transitions are wanted, use Astro's `<ClientRouter />`. It is the only
|
||||
sanctioned motion dependency, and it must:
|
||||
|
||||
- degrade cleanly with JS disabled (it does — full navigation)
|
||||
- respect `prefers-reduced-motion`
|
||||
- not break the review desk's query-param deep links or browser back/forward
|
||||
|
||||
## Accessibility
|
||||
|
||||
- Never animate anything that conveys information on its own. Motion is
|
||||
redundant reinforcement.
|
||||
- Nothing flashes more than three times per second.
|
||||
- Focus must stay visible throughout a transition, and focus order must not
|
||||
change because of one.
|
||||
@@ -1,75 +0,0 @@
|
||||
# Rule: Astro
|
||||
|
||||
Binding for every `.astro` file.
|
||||
|
||||
## Zero JS is the default
|
||||
|
||||
A component ships no JavaScript unless it has a `client:*` directive. Seven of
|
||||
this site's ten pages ship no JS today and must continue to.
|
||||
|
||||
- Never add `client:load` without justifying it in the PR description.
|
||||
- Prefer, in order: no JS → `client:visible` → `client:idle` → `client:load`.
|
||||
- An island is a **leaf**, not a wrapper. Hydrate the tab panel, not the page.
|
||||
|
||||
## Islands in this project
|
||||
|
||||
Only these need interactivity. Anything else claiming island status is wrong:
|
||||
|
||||
| Island | Why | Directive |
|
||||
| --------------------------------- | ---------------------------------- | ---------------- |
|
||||
| Guide phase/tab switchers | click-driven panel swap | `client:visible` |
|
||||
| Review desk catalog + file viewer | search, filter, fetch source files | `client:load` |
|
||||
| Vote widget | talks to the vote API | `client:visible` |
|
||||
| Language toggle | swaps EN/PT across the page | `client:idle` |
|
||||
|
||||
## Structure
|
||||
|
||||
```astro
|
||||
---
|
||||
// 1. imports
|
||||
// 2. Props interface
|
||||
// 3. destructure Astro.props
|
||||
// 4. derived values — no side effects, no fetch in components
|
||||
---
|
||||
|
||||
<!-- markup -->
|
||||
<style>
|
||||
/* component-scoped */
|
||||
</style>
|
||||
```
|
||||
|
||||
- Typed props always: `interface Props { … }`, then `const { … } = Astro.props`.
|
||||
- Data loading belongs in `src/content/` collections or the page frontmatter,
|
||||
not inside a component.
|
||||
- No barrel files (`index.ts` re-export hubs). They cost tree-shaking and invite
|
||||
cycles.
|
||||
|
||||
## Content collections
|
||||
|
||||
All copy lives in `src/content/`, typed with a Zod schema in
|
||||
`src/content/config.ts`. The review desk's `catalog.js` maps onto a collection
|
||||
almost one-to-one — do that rather than importing a 27 KB JS file.
|
||||
|
||||
## Styles
|
||||
|
||||
- Component styles go in the component's `<style>` block. Astro scopes them.
|
||||
- Only tokens and true resets live in global CSS.
|
||||
- Do not port `responsive.css` verbatim. It is an override layer whose reason
|
||||
for existing disappears once layout is componentized. Port what a component
|
||||
needs, prove the rest is dead, delete it.
|
||||
|
||||
## URLs and the base path
|
||||
|
||||
The site is served from `/ai-for-dummies/`. Set `base` in `astro.config.mjs` and
|
||||
never hand-write an absolute internal path. Use `import.meta.env.BASE_URL`.
|
||||
|
||||
Existing routes are load-bearing and must not change, including trailing slashes
|
||||
and the review desk's query params.
|
||||
|
||||
## Never
|
||||
|
||||
- No UI framework (React/Vue/Svelte) unless a task brief explicitly calls for
|
||||
it. Astro components plus a little vanilla JS cover everything here.
|
||||
- No CSS framework. This site has a hand-built visual identity — see
|
||||
[`theming.md`](theming.md).
|
||||
- No external runtime requests. Self-host. `audit-ui.mjs` enforces it.
|
||||
@@ -1,48 +0,0 @@
|
||||
# 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:
|
||||
|
||||
```js
|
||||
// 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,54 +0,0 @@
|
||||
# Rule: componentization
|
||||
|
||||
## When to make a component
|
||||
|
||||
Extract when the same markup appears **three times**, or when a block has a name
|
||||
a person would use out loud ("the eyebrow", "the route card", "the phase
|
||||
panel").
|
||||
|
||||
Do not extract on the second occurrence. Two similar blocks often diverge; the
|
||||
premature abstraction costs more than the duplication.
|
||||
|
||||
## Sizes
|
||||
|
||||
- A component that exceeds ~120 lines of markup is doing two jobs. Split it.
|
||||
- A page that is a bare list of components with no markup of its own has been
|
||||
over-split. Pages are allowed to contain layout.
|
||||
|
||||
## Boundaries
|
||||
|
||||
```
|
||||
src/components/
|
||||
primitives/ Eyebrow, Rule, Callout, CodeBlock — no domain knowledge
|
||||
blocks/ RouteCard, PhasePanel, HandoffTable, SkillPackage — composed, page-agnostic
|
||||
islands/ interactive only; each one justified per rules/astro.md
|
||||
```
|
||||
|
||||
- Primitives never import blocks.
|
||||
- Blocks never import page-specific data; they take props.
|
||||
- Islands are leaves. An island must not wrap static children that could have
|
||||
been server-rendered.
|
||||
|
||||
## Props
|
||||
|
||||
- Typed `interface Props`, every field. No `any`, no untyped rest spread.
|
||||
- Required by default. Optional props need a default and a reason.
|
||||
- Pass data, not markup. If you find yourself passing an HTML string, you want a
|
||||
`<slot>`.
|
||||
|
||||
## Named exports, no barrels
|
||||
|
||||
Import the file you need. Barrel `index.ts` files break tree-shaking and create
|
||||
import cycles; bulletproof-react advises against them and so do we.
|
||||
|
||||
## The catalog is data, not components
|
||||
|
||||
The 24 review-desk entries are content, not 24 components. One
|
||||
`SkillReviewCard.astro` iterating a typed collection. If you are writing the
|
||||
25th near-identical component, stop and model the data.
|
||||
|
||||
## Do not componentize
|
||||
|
||||
`hands-on/starter/` and `hands-on/rules/` are lab fixtures. Their whole value is
|
||||
being flat, dependency-free files an attendee hands to an agent. They ship from
|
||||
`public/` unchanged.
|
||||
@@ -1,59 +0,0 @@
|
||||
# Rule: content and i18n
|
||||
|
||||
## Every user-visible string is content
|
||||
|
||||
No hard-coded copy in components. Strings live in `src/content/`, typed with
|
||||
Zod, and reach components as props or collection entries.
|
||||
|
||||
## The existing shape
|
||||
|
||||
`app.js` already stores content as `{ en: '…', pt: '…' }` objects across
|
||||
`phases`, `handsOnPrompts`, `modelGuide`, `skillSources`, and
|
||||
`skillInstallPrompts` — about 50 `en:` keys. That shape is fine and should be
|
||||
carried across, not redesigned:
|
||||
|
||||
```ts
|
||||
// src/content/config.ts
|
||||
const localized = z.object({ en: z.string(), pt: z.string() });
|
||||
```
|
||||
|
||||
Both locales are **required**. A missing `pt` must be a build error, not a
|
||||
silent English fallback — that is how bilingual sites quietly become
|
||||
monolingual.
|
||||
|
||||
## Migrating strings
|
||||
|
||||
Copy, do not retype. These are hand-written translations with specific tone
|
||||
(`'Transforme ambiguidade em trabalho'`). Retyping introduces typos and drift.
|
||||
Move the literal, then diff the extracted content against the original file to
|
||||
prove nothing changed:
|
||||
|
||||
```bash
|
||||
node .agents/scripts/extract-strings.mjs app.js > /tmp/before.json
|
||||
node .agents/scripts/extract-strings.mjs src/content/guide/ > /tmp/after.json
|
||||
diff /tmp/before.json /tmp/after.json
|
||||
```
|
||||
|
||||
## Language switching
|
||||
|
||||
Today the toggle swaps text client-side and updates `<html lang>`. Two options
|
||||
for Astro, decide in task 03:
|
||||
|
||||
- **Keep client-side swap.** Both languages ship in the payload. Zero routing
|
||||
change, matches today exactly, no URL work. Recommended — the content is small
|
||||
and the current behaviour is already what people link to.
|
||||
- **Route-based (`/en/`, `/pt/`).** Better SEO, more correct, but it changes
|
||||
every existing URL. Only do this with an explicit decision plus redirects.
|
||||
|
||||
Whichever you pick, `<html lang>` must track the active language.
|
||||
|
||||
## Rendered content
|
||||
|
||||
Markdown in `catalog.js` entries (the `improved` field) should become real
|
||||
Markdown files in the collection, rendered at build time rather than by a
|
||||
hand-rolled client-side renderer. That deletes code and improves fidelity.
|
||||
|
||||
Careful: `skill-reviews/improved/**/SKILL.md` is **generated** from those
|
||||
entries by `scripts/build-skill-review.mjs`, and the generated files are
|
||||
committed. Keep that generator working, or replace it and update every reference
|
||||
to it.
|
||||
@@ -1,123 +0,0 @@
|
||||
# Rule: quality gates
|
||||
|
||||
Three tiers. Each is scoped so that **many agents committing in parallel
|
||||
worktrees stay fast** — the whole point is that a gate you are tempted to skip
|
||||
is not a gate.
|
||||
|
||||
| Tier | Hook | Scope | Budget | Runs |
|
||||
| ---- | ------------------ | ------------------------------------- | ------- | -------------------- |
|
||||
| 1 | `pre-commit` | **staged files only** (lint-staged) | < 3s | every commit |
|
||||
| 2 | `pre-push` | whole project: build + verify + audit | < 90s | every push |
|
||||
| 3 | CI (Gitea Actions) | tier 2 + lint, on a clean install | minutes | every push to `main` |
|
||||
|
||||
Tier 1 must stay under a few seconds. If it creeps, move the check to tier 2. An
|
||||
agent that waits 40s per commit will start passing `--no-verify`, and then you
|
||||
have no gate at all.
|
||||
|
||||
## Tier 1 — pre-commit (lint-staged)
|
||||
|
||||
Formats and lints **only what you staged**. Scoped by construction, so ten
|
||||
parallel worktrees do ten small jobs, not ten full-project sweeps.
|
||||
|
||||
- Prettier + ESLint on `*.{js,mjs,ts,astro}`
|
||||
- Prettier + Stylelint on `*.css`
|
||||
- `check-tokens.mjs` on changed `.astro`/`.css` — catches raw hex before it
|
||||
lands
|
||||
- Prettier on `*.{json,md}`
|
||||
|
||||
## Tier 2 — pre-push
|
||||
|
||||
The real gate:
|
||||
|
||||
```
|
||||
astro check types
|
||||
astro build it compiles
|
||||
verify.mjs 42 content assertions — count must not fall
|
||||
audit-ui.mjs no external runtime dependencies
|
||||
check-tokens.mjs full sweep
|
||||
```
|
||||
|
||||
## Tier 3 — CI
|
||||
|
||||
Tier 2 plus `pnpm run lint`, run against a clean
|
||||
`pnpm install --frozen-lockfile` — which is the part a local worktree cannot
|
||||
prove.
|
||||
|
||||
Screenshot comparison against `.agents/snapshots/` is **not** wired in yet.
|
||||
`visual-regression.mjs` can only capture baselines, not diff them, so running it
|
||||
in CI would overwrite the baselines and pass unconditionally. It also needs
|
||||
Playwright, which is not a project dependency. Add the step back when the script
|
||||
grows a compare mode.
|
||||
|
||||
## Bypassing
|
||||
|
||||
`--no-verify` is allowed exactly once: a work-in-progress commit **on your own
|
||||
task branch that you will amend or squash away**. It is never allowed on a
|
||||
commit you intend to merge, and the pre-push gate has no bypass.
|
||||
|
||||
If a gate is wrong, fix the gate in its own commit. Do not route around it.
|
||||
|
||||
## Never restructure code to slip past a checker
|
||||
|
||||
A checker is a proxy for a rule. Passing the proxy while breaking the rule is
|
||||
worse than failing, because failure is visible and this is not.
|
||||
|
||||
`check-tokens.mjs` matches `font-size: Npx`. Writing the same value as the
|
||||
`font:` shorthand passes it. Task 07 did exactly that, in **two** components,
|
||||
with a comment saying so. Both hardcoded values survived into a "green" branch.
|
||||
|
||||
### Do not substitute a near-miss token either
|
||||
|
||||
The second way to break this is subtler, and both tasks 10 and 11 did it: keep
|
||||
the gate happy by pointing a legacy value at the closest token that already
|
||||
exists. `#e5eeeb` became `var(--paper)`. Diff-**added** green became
|
||||
`var(--accent)` — purple. `12px` and `14px` both became `var(--step-1)`, 15px.
|
||||
|
||||
That is a silent redesign, and it is _worse_ than leaving the raw value in,
|
||||
because a raw hex is at least honest about being unresolved.
|
||||
|
||||
### What to do instead: mark the gap
|
||||
|
||||
`tokens.css` has one owner (`design-system-keeper`) so that "add a token" is a
|
||||
decision, not a side effect. You may not add one. You **can** keep the true
|
||||
value and stay green — mark it:
|
||||
|
||||
```css
|
||||
/* token-gap: no --step-* covers 12px; owner design-system-keeper */
|
||||
font-size: 12px;
|
||||
```
|
||||
|
||||
The marker waives that one finding. It needs a real reason after the colon; a
|
||||
bare `token-gap:` is rejected. Every marked value is listed on each run, so the
|
||||
debt stays visible rather than disappearing.
|
||||
|
||||
Write it in your task report as well: selector, legacy value, owning file.
|
||||
Marking a gap is not resolving it — it keeps the site truthful until whoever
|
||||
owns the token layer decides.
|
||||
|
||||
## Parallelism
|
||||
|
||||
- Hooks are **per-worktree**. Git's `index.lock` is per-worktree, so parallel
|
||||
commits do not contend.
|
||||
- The heavy tier-2 gate takes a **lock** (`.git/af-gate.lock`, shared across
|
||||
worktrees) so ten agents pushing at once do not run ten concurrent builds and
|
||||
thrash the machine. Waiters queue; they do not fail.
|
||||
- `pnpm install --frozen-lockfile` in a fresh worktree is cheap: pnpm hardlinks
|
||||
from the shared content-addressable store, so a second worktree costs seconds
|
||||
and almost no disk instead of another 225 MB. No `--prefer-offline` needed.
|
||||
|
||||
## The silent-failure mode you must know about
|
||||
|
||||
Husky sets `core.hooksPath` to `.husky/_`, and **`.husky/_` is generated by
|
||||
`pnpm install`, not committed**. A fresh `git worktree add` therefore has hooks
|
||||
configured but the directory missing — so **hooks silently do not run**. Every
|
||||
commit passes. Nothing is checked.
|
||||
|
||||
`.agents/scripts/worktree.sh start` runs the install and then verifies. Check
|
||||
manually any time you did not use it:
|
||||
|
||||
```bash
|
||||
.agents/scripts/verify-hooks.sh
|
||||
```
|
||||
|
||||
Run this first in any worktree you did not create with the script.
|
||||
@@ -1,85 +0,0 @@
|
||||
# Rule: git worktrees
|
||||
|
||||
This project teaches worktrees. It should use them properly.
|
||||
|
||||
## One task, one worktree, one agent
|
||||
|
||||
```bash
|
||||
# from the main checkout
|
||||
git worktree add ../af-task-07 -b refactor/task-07-route-cards
|
||||
cd ../af-task-07
|
||||
pnpm install --frozen-lockfile
|
||||
```
|
||||
|
||||
Naming: directory `../af-task-NN`, branch `refactor/task-NN-<slug>`. Both
|
||||
derived from the task file so the mapping is never ambiguous.
|
||||
|
||||
## Why isolation matters here
|
||||
|
||||
The migration runs many agents in parallel over the same small set of files
|
||||
(`tokens.css`, `verify.mjs`, `astro.config.mjs` are contended). Worktrees give
|
||||
each agent its own working directory over one object store — cheap, and no agent
|
||||
can see another's half-finished state.
|
||||
|
||||
The failure mode without them: two agents both "fix" `verify.mjs`, and the
|
||||
second overwrites the first's assertions.
|
||||
|
||||
## Contended files
|
||||
|
||||
These are touched by many tasks. Whoever owns them per the plan is the **only**
|
||||
writer; everyone else opens an issue in their task report instead of editing:
|
||||
|
||||
| File | Owner |
|
||||
| ---------------------------------- | ----------------------- |
|
||||
| `src/styles/tokens.css` | `design-system-keeper` |
|
||||
| `scripts/verify.mjs` | `verification-engineer` |
|
||||
| `astro.config.mjs`, `package.json` | `astro-architect` |
|
||||
| `src/content/config.ts` | `content-i18n-migrator` |
|
||||
|
||||
## Never rebase a task branch
|
||||
|
||||
Not onto `main`, not onto another task branch, not "just to tidy up". A rebase
|
||||
rewrites every commit with a new SHA, so a branch that others branched from — or
|
||||
that has already been merged — turns into a duplicate history that no longer
|
||||
shares an ancestor with the original. Task 03 did this and flattened task 01's
|
||||
merge into four look-alike commits; it is the same divergent-history trap that
|
||||
broke the `pages` branch.
|
||||
|
||||
To pick up new work from `main`, **merge it in**: `git merge origin/main`. The
|
||||
extra merge commit is the price of a history that stays true, and it is cheap.
|
||||
|
||||
## Before you start
|
||||
|
||||
1. `git fetch origin` — then branch from the ref your task file names as its
|
||||
base. Do not assume that base is `main`.
|
||||
2. Read your task file end to end before writing anything.
|
||||
3. Confirm your task's dependencies are merged. Task files list them.
|
||||
|
||||
## Before you finish
|
||||
|
||||
1. `pnpm run verify` green — without deleting assertions.
|
||||
2. The relevant checklist in [`../checklists/`](../checklists/) complete.
|
||||
3. `git fetch origin && git merge origin/main`, resolve conflicts in your
|
||||
worktree. **Merge — never rebase.**
|
||||
4. Task report: what changed, what you verified, **what you did not do**.
|
||||
|
||||
## Cleanup
|
||||
|
||||
```bash
|
||||
cd - # back to the main checkout
|
||||
git worktree remove ../af-task-07
|
||||
git branch -d refactor/task-07-route-cards
|
||||
```
|
||||
|
||||
Stale worktrees hold locks and confuse the next agent. `git worktree list`
|
||||
should be short.
|
||||
|
||||
## Never
|
||||
|
||||
- Never work directly on `main`.
|
||||
- Never force-push a shared branch. The `pages` branch is the sole exception,
|
||||
and only if CI owns it (see
|
||||
[`../context/publishing.md`](../context/publishing.md)).
|
||||
- Never `git add -A` from the repository root. This repo has untracked local
|
||||
scratch (`.serena/`, `scripts/inspect.py`) that must not be swept into a
|
||||
commit.
|
||||
@@ -1,81 +0,0 @@
|
||||
# Rule: theming
|
||||
|
||||
Binding for every colour, font size, spacing value, and breakpoint.
|
||||
|
||||
**Read [`../context/design-system.md`](../context/design-system.md) first.** The
|
||||
current CSS has three drifting palettes and a broken `@font-face`. This rule
|
||||
describes the target; that file describes what you are migrating from.
|
||||
|
||||
## One token layer
|
||||
|
||||
Every value comes from `src/styles/tokens.css`. If a component needs a value
|
||||
that is not a token, either it is a genuine one-off (justify it in a comment) or
|
||||
the token layer is missing something (add it there, not inline).
|
||||
|
||||
```css
|
||||
/* forbidden */
|
||||
color: #172f42;
|
||||
color: rgba(23, 47, 66, 0.6);
|
||||
|
||||
/* required */
|
||||
color: var(--ink);
|
||||
color: var(--muted);
|
||||
```
|
||||
|
||||
No raw hex outside `tokens.css`. `.agents/scripts/check-tokens.mjs` enforces it;
|
||||
wire it into `pnpm run verify`.
|
||||
|
||||
## Semantic names, not literal ones
|
||||
|
||||
`--ink`, `--paper`, `--muted`, `--line`, `--accent`, `--gold`, `--blue`,
|
||||
`--deep` are the existing vocabulary. Keep it — it is already semantic and the
|
||||
team reads it fluently. Do not rename to `--color-neutral-900`.
|
||||
|
||||
If a genuine second surface is needed, extend semantically (`--surface-lab`,
|
||||
`--ink-inverse`), never numerically.
|
||||
|
||||
## Type scale
|
||||
|
||||
Replace the 14 ad-hoc `clamp()` triples with named steps:
|
||||
|
||||
```css
|
||||
--step-display: clamp(56px, 9vw, 126px); /* h1 */
|
||||
--step-6: clamp(36px, 5vw, 65px); /* section h2 */
|
||||
--step-5: clamp(24px, 3vw, 38px); /* sub-head */
|
||||
--step-4: clamp(22px, 3vw, 36px); /* pull-quote */
|
||||
--step-1: 15px; /* body */
|
||||
--step-0: 11px; /* eyebrow / label */
|
||||
```
|
||||
|
||||
The eyebrow treatment (`10–11px` monospace, `letter-spacing:.08–.1em`,
|
||||
uppercase) is a signature of this design. Make it one class, not fifteen
|
||||
repetitions.
|
||||
|
||||
## Breakpoints
|
||||
|
||||
Five named widths replace the current sixteen:
|
||||
|
||||
```css
|
||||
--bp-sm: 560px;
|
||||
--bp-md: 800px;
|
||||
--bp-lg: 1100px;
|
||||
--bp-xl: 1600px;
|
||||
--bp-2xl: 2200px;
|
||||
```
|
||||
|
||||
When collapsing a component's old breakpoint onto a named one, screenshot at the
|
||||
**old** value. That is where the regression will be.
|
||||
|
||||
## Preserve the house style
|
||||
|
||||
- Flat colour blocks, hairline `1px` rules, near-zero border-radius.
|
||||
- Tight negative tracking on display type (`-.06em` … `-.08em`).
|
||||
- Grid separators built as `gap:1px` over a coloured parent background. This is
|
||||
deliberate. Do not "fix" it into `border`.
|
||||
- `Georgia, serif` for emphasis spans (`h1 em`). It renders today; keep it.
|
||||
|
||||
## Fonts
|
||||
|
||||
Do not add a webfont without an explicit decision recorded in the task. The
|
||||
intended Manrope/DM Mono has never rendered; introducing it is a visual
|
||||
redesign, not a refactor. Default: match what renders today.
|
||||
@@ -1,149 +0,0 @@
|
||||
#!/usr/bin/env node
|
||||
// Fails when a raw colour, px font-size, or ad-hoc breakpoint appears outside
|
||||
// the token layer. A rule nobody checks is a suggestion — wire this into
|
||||
// `pnpm run verify`.
|
||||
//
|
||||
// ESCAPE HATCH — `token-gap:`. Some legacy values have no token yet, and only
|
||||
// `design-system-keeper` may add one. Without an escape, an agent told both
|
||||
// "keep the site identical" and "get the gate green" has to break one of them,
|
||||
// and tasks 10 and 11 both broke the first: `#e5eeeb` became `var(--paper)`,
|
||||
// diff-added green became `var(--accent)` purple. Substituting a near-miss
|
||||
// token is a silent redesign; it is worse than a raw value, because the raw
|
||||
// value is at least honest about what it is.
|
||||
//
|
||||
// So: mark the line, keep the true value, stay green.
|
||||
//
|
||||
// /* token-gap: no --step-* covers 12px; owner design-system-keeper */
|
||||
// font-size: 12px;
|
||||
//
|
||||
// Marked values are counted and listed on every run — they are a visible debt
|
||||
// queue, not a way to make the finding disappear. The marker needs a reason;
|
||||
// a bare `token-gap:` does not count.
|
||||
//
|
||||
// Usage: node .agents/scripts/check-tokens.mjs [srcDir]
|
||||
|
||||
import { readdirSync, readFileSync, statSync } from 'node:fs';
|
||||
import { join, extname } from 'node:path';
|
||||
|
||||
// lint-staged appends staged file paths; a bare run sweeps `src`.
|
||||
const ARGS = process.argv.slice(2);
|
||||
const TOKEN_FILES = ['tokens.css', 'base.css'];
|
||||
const ALLOWED_BREAKPOINTS = ['560px', '800px', '1100px', '1600px', '2200px'];
|
||||
|
||||
const walk = (dir) =>
|
||||
readdirSync(dir).flatMap((name) => {
|
||||
const path = join(dir, name);
|
||||
return statSync(path).isDirectory() ? walk(path) : [path];
|
||||
});
|
||||
|
||||
const targets = ARGS.length
|
||||
? ARGS.flatMap((arg) => (statSync(arg).isDirectory() ? walk(arg) : [arg]))
|
||||
: walk('src');
|
||||
|
||||
const findings = [];
|
||||
const gaps = [];
|
||||
|
||||
// A finding is waived when its own line, or the line above it, carries a
|
||||
// `token-gap:` marker with a reason after the colon.
|
||||
const MARKER = /token-gap:([^\n]*)/;
|
||||
// The reason is what is left after the marker once the comment terminator and
|
||||
// punctuation are stripped. `/* token-gap: */` is not a reason.
|
||||
const reason = (line) => {
|
||||
const found = MARKER.exec(line ?? '');
|
||||
if (!found) return null;
|
||||
const text = found[1]
|
||||
.replace(/\*\/\s*$/, '')
|
||||
.replace(/[\s*/]+$/, '')
|
||||
.trim();
|
||||
return /[a-z0-9]/i.test(text) ? [null, text] : null;
|
||||
};
|
||||
const waiver = (lines, index) =>
|
||||
reason(lines[index]) || (index > 0 ? reason(lines[index - 1]) : null);
|
||||
|
||||
for (const path of targets) {
|
||||
if (!['.astro', '.css'].includes(extname(path))) continue;
|
||||
if (TOKEN_FILES.some((allowed) => path.endsWith(allowed))) continue;
|
||||
|
||||
const lines = readFileSync(path, 'utf8').split('\n');
|
||||
lines.forEach((line, index) => {
|
||||
const at = `${path}:${index + 1}`;
|
||||
const waived = waiver(lines, index);
|
||||
const record = (finding) => {
|
||||
if (waived) gaps.push(`${at}: ${finding.slice(at.length + 2)} [${waived[1]}]`);
|
||||
else findings.push(finding);
|
||||
};
|
||||
|
||||
// Raw hex — the drifted-palette failure mode this whole layer exists to stop.
|
||||
const hex = line.match(/#[0-9a-fA-F]{3,8}\b/g);
|
||||
if (hex) record(`${at}: raw hex ${hex.join(', ')} — use a token from tokens.css`);
|
||||
|
||||
// rgb()/hsl() literals are the same problem wearing a different hat.
|
||||
if (/\b(rgba?|hsla?)\(\s*\d/.test(line)) record(`${at}: raw colour function — use a token`);
|
||||
|
||||
// Hard-coded font sizes bypass the type scale.
|
||||
const fontSize = line.match(/font-size:\s*\d+(\.\d+)?px/);
|
||||
if (fontSize) record(`${at}: hard-coded ${fontSize[0]} — use var(--step-*)`);
|
||||
|
||||
// Ad-hoc breakpoints are how sixteen of them accumulated last time.
|
||||
const media = line.match(/@media[^{]*?\(\s*(?:max|min)-width:\s*(\d+px)/);
|
||||
if (media && !ALLOWED_BREAKPOINTS.includes(media[1]))
|
||||
record(
|
||||
`${at}: breakpoint ${media[1]} is not a named one (${ALLOWED_BREAKPOINTS.join(', ')})`,
|
||||
);
|
||||
});
|
||||
}
|
||||
|
||||
if (gaps.length) {
|
||||
console.log(`token check: ${gaps.length} marked token-gap(s) awaiting design-system-keeper:\n`);
|
||||
gaps.forEach((gap) => console.log(` ${gap}`));
|
||||
console.log('');
|
||||
}
|
||||
|
||||
if (findings.length) {
|
||||
console.error(`token check failed — ${findings.length} finding(s):\n`);
|
||||
findings.forEach((finding) => console.error(` ${finding}`));
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
import { existsSync } from 'node:fs';
|
||||
import { basename } from 'node:path';
|
||||
|
||||
if (existsSync('dist')) {
|
||||
const builtCss = walk('dist').filter((p) => p.endsWith('.css'));
|
||||
const tokensBuilt = builtCss.find((p) => /[\\/]tokens\.[^\\/]+\.css$/.test(p));
|
||||
|
||||
if (!tokensBuilt) {
|
||||
console.error('token check failed — tokens.css was not built into dist/');
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
const tokensContent = readFileSync(tokensBuilt, 'utf8');
|
||||
if (!tokensContent.includes('#527f9f')) {
|
||||
console.error(
|
||||
'token check failed — built tokens.css does not contain the canonical --blue value #527f9f',
|
||||
);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
const htmlFiles = walk('dist').filter(
|
||||
(p) =>
|
||||
p.endsWith('.html') &&
|
||||
!p.includes('/hands-on/') &&
|
||||
!p.includes('\\hands-on\\') &&
|
||||
!p.includes('/submitted-skills/') &&
|
||||
!p.includes('\\submitted-skills\\'),
|
||||
);
|
||||
|
||||
const tokenChunkName = basename(tokensBuilt);
|
||||
for (const html of htmlFiles) {
|
||||
const content = readFileSync(html, 'utf8');
|
||||
if (!content.includes(tokenChunkName)) {
|
||||
console.error(
|
||||
`token check failed — ${html} does not load the token layer (${tokenChunkName})`,
|
||||
);
|
||||
process.exit(1);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
console.log('token check passed');
|
||||
@@ -1,173 +0,0 @@
|
||||
#!/usr/bin/env node
|
||||
// Compare the *computed* styles of a legacy page against its Astro
|
||||
// replacement, at several viewport widths.
|
||||
//
|
||||
// node .agents/scripts/computed-style-diff.mjs full-guide
|
||||
// node .agents/scripts/computed-style-diff.mjs full-guide --widths 560,880,1050
|
||||
//
|
||||
// Why this exists: a ported media query can sit in the built stylesheet,
|
||||
// match the viewport, and still do nothing. Astro scopes a component's rules
|
||||
// as `.tree-node[data-astro-cid-lsutp3lb]` (specificity 0,2,0); a rule ported
|
||||
// verbatim as `.tree-node` (0,1,0) loses to it and never applies. Task 15e
|
||||
// attempt 4 shipped exactly that: `@media (max-width: 1050px) .tree-node
|
||||
// { width: 145px }` was present in dist and the node stayed 180px wide.
|
||||
//
|
||||
// Checking that the breakpoint *appears* in the built CSS cannot catch this.
|
||||
// Only asking the browser what it actually computed can.
|
||||
import { spawn } from 'node:child_process';
|
||||
import { cpSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
|
||||
import { createServer } from 'node:net';
|
||||
import { tmpdir } from 'node:os';
|
||||
import { join } from 'node:path';
|
||||
import { chromium } from 'playwright';
|
||||
|
||||
const route = process.argv[2];
|
||||
if (!route) {
|
||||
console.error('usage: computed-style-diff.mjs <route> [--widths a,b,c]');
|
||||
process.exit(2);
|
||||
}
|
||||
|
||||
const widthsArg = process.argv.indexOf('--widths');
|
||||
const widths =
|
||||
widthsArg === -1
|
||||
? [520, 560, 600, 620, 720, 800, 880, 1050, 1100, 1600]
|
||||
: process.argv[widthsArg + 1].split(',').map(Number);
|
||||
|
||||
// The selectors worth checking are the ones the responsive layer moves at a
|
||||
// breakpoint, so read them out of the legacy stylesheet's @media blocks only.
|
||||
// Taking every class in the file buries the signal under generic ones like
|
||||
// `.active`, whose state the islands own anyway.
|
||||
const responsive = readFileSync(new URL('../../responsive.css', import.meta.url), 'utf8');
|
||||
const mediaBlocks = [];
|
||||
for (const match of responsive.matchAll(/@media[^{]*\{/g)) {
|
||||
let depth = 0;
|
||||
for (let i = match.index; i < responsive.length; i += 1) {
|
||||
if (responsive[i] === '{') depth += 1;
|
||||
else if (responsive[i] === '}') {
|
||||
depth -= 1;
|
||||
if (depth === 0) {
|
||||
mediaBlocks.push(responsive.slice(match.index + match[0].length, i));
|
||||
break;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
const selectors = [...new Set(mediaBlocks.join('\n').match(/\.[a-z][a-z0-9-]*/g) || [])].sort();
|
||||
|
||||
// Properties a responsive rule actually moves. Comparing every property would
|
||||
// drown the signal in font stacks and inherited colour.
|
||||
const PROPERTIES = [
|
||||
'display',
|
||||
'grid-template-columns',
|
||||
'grid-template-rows',
|
||||
'flex-direction',
|
||||
'width',
|
||||
'height',
|
||||
'max-width',
|
||||
'padding',
|
||||
'margin',
|
||||
'gap',
|
||||
'font-size',
|
||||
'position',
|
||||
'inset',
|
||||
'overflow',
|
||||
];
|
||||
|
||||
// The legacy pages were deleted at cutover; run this from a pre-cutover
|
||||
// worktree, or the legacy side will 404.
|
||||
const legacyPath = route === 'index' ? 'index.html' : `${route}/index.html`;
|
||||
const astroPath = route === 'index' ? '' : `${route}/`;
|
||||
|
||||
const staging = mkdtempSync(join(tmpdir(), 'af-csd-'));
|
||||
cpSync('dist', join(staging, 'ai-for-dummies'), { recursive: true });
|
||||
|
||||
const freePort = () =>
|
||||
new Promise((resolve, reject) => {
|
||||
const probe = createServer();
|
||||
probe.on('error', reject);
|
||||
probe.listen(0, '127.0.0.1', () => {
|
||||
const { port } = probe.address();
|
||||
probe.close(() => resolve(port));
|
||||
});
|
||||
});
|
||||
|
||||
const legacyPort = await freePort();
|
||||
const astroPort = await freePort();
|
||||
const serve = (dir, port) =>
|
||||
spawn('python3', ['-m', 'http.server', String(port), '-d', dir], { stdio: 'ignore' });
|
||||
const servers = [serve('.', legacyPort), serve(staging, astroPort)];
|
||||
const stop = () => {
|
||||
servers.forEach((s) => s.kill());
|
||||
rmSync(staging, { recursive: true, force: true });
|
||||
};
|
||||
|
||||
// Every element matching each selector, so a rule that applies to the first
|
||||
// node and not the rest cannot pass.
|
||||
const collect = ([selectors, properties]) => {
|
||||
const out = {};
|
||||
for (const selector of selectors) {
|
||||
const nodes = [...document.querySelectorAll(selector)];
|
||||
out[selector] = nodes.map((node) => {
|
||||
const style = getComputedStyle(node);
|
||||
return properties
|
||||
.map((property) => `${property}:${style.getPropertyValue(property)}`)
|
||||
.join(';');
|
||||
});
|
||||
}
|
||||
return out;
|
||||
};
|
||||
|
||||
let failures = 0;
|
||||
try {
|
||||
const browser = await chromium.launch();
|
||||
const read = async (url, width) => {
|
||||
const page = await browser.newPage({ viewport: { width, height: 900 } });
|
||||
const response = await page.goto(url, { waitUntil: 'load' });
|
||||
if (!response || !response.ok()) {
|
||||
throw new Error(`${url} returned ${response ? response.status() : 'no response'}`);
|
||||
}
|
||||
await page.waitForTimeout(1500);
|
||||
const styles = await page.evaluate(collect, [selectors, PROPERTIES]);
|
||||
await page.close();
|
||||
return styles;
|
||||
};
|
||||
|
||||
for (const width of widths) {
|
||||
const legacy = await read(`http://localhost:${legacyPort}/${legacyPath}`, width);
|
||||
const astro = await read(`http://localhost:${astroPort}/ai-for-dummies/${astroPath}`, width);
|
||||
|
||||
for (const selector of selectors) {
|
||||
const before = legacy[selector];
|
||||
const after = astro[selector];
|
||||
if (before.length === 0 && after.length === 0) continue;
|
||||
if (before.length !== after.length) {
|
||||
console.log(
|
||||
`${width}px ${selector} legacy ${before.length} nodes, astro ${after.length}`,
|
||||
);
|
||||
failures += 1;
|
||||
continue;
|
||||
}
|
||||
let reported = 0;
|
||||
before.forEach((expected, index) => {
|
||||
if (expected === after[index]) return;
|
||||
failures += 1;
|
||||
// Three examples is enough to identify a rule that did not apply.
|
||||
reported += 1;
|
||||
if (reported > 3) return;
|
||||
const differing = expected
|
||||
.split(';')
|
||||
.filter((pair, i) => pair !== after[index].split(';')[i]);
|
||||
const got = after[index].split(';').filter((pair, i) => pair !== expected.split(';')[i]);
|
||||
console.log(`${width}px ${selector}[${index}]`);
|
||||
console.log(` legacy ${differing.join(' ')}`);
|
||||
console.log(` astro ${got.join(' ')}`);
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
await browser.close();
|
||||
console.log(failures === 0 ? 'computed styles match' : `${failures} computed-style differences`);
|
||||
process.exitCode = failures === 0 ? 0 : 1;
|
||||
} finally {
|
||||
stop();
|
||||
}
|
||||
@@ -1,45 +0,0 @@
|
||||
#!/usr/bin/env node
|
||||
// Mechanically extract every { en, pt } string pair from a file or directory,
|
||||
// sorted and normalised, so a content migration can be proven lossless:
|
||||
//
|
||||
// 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
|
||||
//
|
||||
// A non-empty diff means you altered content. These are hand-written
|
||||
// translations with deliberate tone — copy them, never retype them.
|
||||
|
||||
import { readdirSync, readFileSync, statSync } from 'node:fs';
|
||||
import { join } from 'node:path';
|
||||
|
||||
const target = process.argv[2];
|
||||
if (!target) {
|
||||
console.error('usage: extract-strings.mjs <file|dir>');
|
||||
process.exit(2);
|
||||
}
|
||||
|
||||
const walk = (dir) =>
|
||||
readdirSync(dir).flatMap((name) => {
|
||||
const path = join(dir, name);
|
||||
return statSync(path).isDirectory() ? walk(path) : [path];
|
||||
});
|
||||
|
||||
const files = statSync(target).isDirectory() ? walk(target) : [target];
|
||||
|
||||
// Matches `en: '…'` / "en": "…" and the pt counterpart, single or double quoted,
|
||||
// tolerating escaped quotes inside.
|
||||
const PAIR = /["']?\b(en|pt)\b["']?\s*:\s*(['"])((?:\\.|(?!\2)[\s\S])*)\2/g;
|
||||
|
||||
const strings = [];
|
||||
for (const file of files) {
|
||||
const source = readFileSync(file, 'utf8');
|
||||
for (const match of source.matchAll(PAIR)) {
|
||||
strings.push({ lang: match[1], value: match[3] });
|
||||
}
|
||||
}
|
||||
|
||||
// Sort so file ordering and structure changes do not show up as content changes.
|
||||
strings.sort((a, b) => (a.lang + a.value).localeCompare(b.lang + b.value));
|
||||
|
||||
console.log(JSON.stringify(strings, null, 2));
|
||||
console.error(`extracted ${strings.length} strings from ${files.length} file(s)`);
|
||||
@@ -1,94 +0,0 @@
|
||||
#!/usr/bin/env bash
|
||||
# Tier 2 gate: types, build, content contracts, dependency audit, tokens.
|
||||
# Invoked by .husky/pre-push, and safe to run by hand at any time.
|
||||
#
|
||||
# Parallel-safe: takes a lock in the SHARED git dir, so ten agents pushing from
|
||||
# ten worktrees queue instead of running ten concurrent Astro builds and
|
||||
# thrashing the machine. Waiters block; they do not fail.
|
||||
set -euo pipefail
|
||||
|
||||
root=$(git rev-parse --show-toplevel)
|
||||
cd "$root"
|
||||
|
||||
# --git-common-dir resolves to the ONE shared .git across all worktrees, which
|
||||
# is exactly the scope we want the lock to cover.
|
||||
common=$(git rev-parse --git-common-dir)
|
||||
lock="$common/af-gate.lock"
|
||||
|
||||
exec 9>"$lock"
|
||||
if ! flock -n 9; then
|
||||
echo "gate: another worktree is running the gate — waiting for it…"
|
||||
flock 9
|
||||
fi
|
||||
|
||||
started=$(date +%s)
|
||||
step() { printf '\n\033[1m▸ %s\033[0m\n' "$1"; }
|
||||
|
||||
# Fail loudly rather than passing vacuously when the toolchain is not installed.
|
||||
if [ ! -d node_modules ]; then
|
||||
echo "gate: node_modules missing — run 'pnpm install --frozen-lockfile' first" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# This project is pnpm-only. An agent that runs `npm install` out of habit gets
|
||||
# a second, divergent dependency tree and a lockfile nobody reads — the same
|
||||
# class of failure that cost two sessions during phase 0. Catch it here.
|
||||
if [ -f package-lock.json ] || [ -f yarn.lock ] || [ -f bun.lock ] || [ -f bun.lockb ]; then
|
||||
echo "gate: a non-pnpm lockfile is present. This project uses pnpm only." >&2
|
||||
echo " Delete it, then run 'pnpm install --frozen-lockfile'." >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
step "types"
|
||||
pnpm exec astro check
|
||||
|
||||
step "build"
|
||||
# `astro build` exits 0 even when vite fails to resolve an asset: the cutover
|
||||
# left a stale `@import` in a moved stylesheet and every gate stayed green for
|
||||
# it. Treat a logged error as a failed build.
|
||||
build_log=$(mktemp)
|
||||
if ! pnpm run build 2>&1 | tee "$build_log"; then
|
||||
rm -f "$build_log"
|
||||
exit 1
|
||||
fi
|
||||
if grep -q '\[ERROR\]' "$build_log"; then
|
||||
echo "gate: astro build logged an error and still exited 0. See above." >&2
|
||||
rm -f "$build_log"
|
||||
exit 1
|
||||
fi
|
||||
rm -f "$build_log"
|
||||
|
||||
step "content contracts"
|
||||
pnpm run verify
|
||||
|
||||
# The assertion count is the thing agents are most tempted to "fix" downward.
|
||||
# Compare against origin/main and refuse a silent reduction.
|
||||
step "assertion coverage"
|
||||
# Task 19 restored the 42 legacy facts and added ten output snapshots: 84 is the
|
||||
# floor, in addition to whatever origin/main currently requires.
|
||||
#
|
||||
# A removal is allowed only by writing a reason into the ledger. The gate counts
|
||||
# its entries and lowers the bar by exactly that many, so the bar cannot move
|
||||
# without a visible diff explaining why. Deleting an entry to buy headroom is
|
||||
# the same offence as deleting the assertion was.
|
||||
ledger=.agents/context/assertion-removals.md
|
||||
current=$(grep -c 'throw new Error' scripts/verify.mjs)
|
||||
allowed=$(grep -c '^## ' "$ledger" 2>/dev/null || echo 0)
|
||||
baseline=$(git show origin/main:scripts/verify.mjs 2>/dev/null | grep -c 'throw new Error' || echo 0)
|
||||
if [ "$baseline" -lt 84 ]; then baseline=84; fi
|
||||
baseline=$((baseline - allowed))
|
||||
if [ "$current" -lt "$baseline" ]; then
|
||||
echo "gate: verify.mjs coverage fell from $baseline to $current assertions." >&2
|
||||
echo " Only verification-engineer may reduce it, with a reason per removal." >&2
|
||||
echo " See .agents/context/verification.md" >&2
|
||||
exit 1
|
||||
fi
|
||||
echo " $current assertions (baseline $baseline)"
|
||||
|
||||
step "runtime dependency audit"
|
||||
node scripts/audit-ui.mjs
|
||||
|
||||
step "design tokens"
|
||||
node .agents/scripts/check-tokens.mjs
|
||||
|
||||
printf '\n\033[32mgate passed\033[0m in %ss\n' "$(( $(date +%s) - started ))"
|
||||
@@ -1,29 +0,0 @@
|
||||
#!/usr/bin/env bash
|
||||
# `.agents/` is the vendor-neutral home for this project's rules, skills, and
|
||||
# agent definitions — MiniMax, Gemini, and Codex all read plain files from it.
|
||||
#
|
||||
# Claude Code, however, discovers subagents and skills at fixed paths. This
|
||||
# symlinks them so there is exactly ONE copy of every definition and no drift.
|
||||
#
|
||||
# .agents/scripts/install-claude-agents.sh
|
||||
set -euo pipefail
|
||||
|
||||
root="$(git rev-parse --show-toplevel)"
|
||||
cd "$root"
|
||||
|
||||
mkdir -p .claude
|
||||
|
||||
for target in agents skills; do
|
||||
link=".claude/$target"
|
||||
if [ -e "$link" ] && [ ! -L "$link" ]; then
|
||||
echo "refusing: $link exists and is not a symlink — move it aside first" >&2
|
||||
exit 1
|
||||
fi
|
||||
ln -sfn "../.agents/$target" "$link"
|
||||
echo "linked $link -> .agents/$target"
|
||||
done
|
||||
|
||||
echo
|
||||
echo "Claude Code will now load:"
|
||||
ls -1 .agents/agents/*.md | sed 's|.*/| agent: |;s|\.md$||'
|
||||
ls -1d .agents/skills/*/ | sed 's|.*/skills/| skill: |;s|/$||'
|
||||
@@ -1,138 +0,0 @@
|
||||
#!/usr/bin/env bash
|
||||
# Launch one refactor task in its own worktree, on the CLI its brief routes it to.
|
||||
#
|
||||
# .agents/scripts/launch.sh 01 scaffold
|
||||
# .agents/scripts/launch.sh 02 tokens --base refactor/task-01-scaffold
|
||||
# .agents/scripts/launch.sh 07 primitives --cli mm --fg
|
||||
#
|
||||
# Routing comes from plans/astro-refactor/MODEL-ROUTING.md. Override with --cli.
|
||||
# All four CLIs are launched with their permission prompts disabled: these run
|
||||
# unattended inside a worktree, and a blocked edit or bash call just hangs.
|
||||
set -euo pipefail
|
||||
|
||||
cd "$(git rev-parse --show-toplevel)"
|
||||
|
||||
number=${1:?usage: launch.sh <task-number> <slug> [--base ref] [--cli codex|agy|mm|oc] [--fg]}
|
||||
slug=${2:?slug, e.g. scaffold}
|
||||
shift 2
|
||||
|
||||
base="main"
|
||||
cli=""
|
||||
foreground=0
|
||||
while [ $# -gt 0 ]; do
|
||||
case "$1" in
|
||||
--base) base=$2; shift 2 ;;
|
||||
--cli) cli=$2; shift 2 ;;
|
||||
--fg) foreground=1; shift ;;
|
||||
*) echo "unknown flag: $1" >&2; exit 2 ;;
|
||||
esac
|
||||
done
|
||||
|
||||
# Model routing. Codex takes the long iterate-until-green loops, Gemini the two
|
||||
# tasks that need whole-corpus context plus visual judgement, MiniMax the rest.
|
||||
if [ -z "$cli" ]; then
|
||||
case "$number" in
|
||||
01|03|15|16|19) cli=codex ;;
|
||||
02|18) cli=agy ;;
|
||||
*) cli=mm ;;
|
||||
esac
|
||||
fi
|
||||
|
||||
dir="../af-task-${number}"
|
||||
branch="refactor/task-${number}-${slug}"
|
||||
plan="plans/astro-refactor/task-${number}-${slug}.md"
|
||||
log="$(pwd)/.agents/logs/task-${number}-${slug}.log"
|
||||
|
||||
[ -f "$plan" ] || { echo "no plan at $plan — check the number and slug" >&2; exit 1; }
|
||||
mkdir -p .agents/logs
|
||||
|
||||
# The brief names its own agent; pull it out so the prompt can point at the file.
|
||||
# [a-z0-9-] not [a-z-]: content-i18n-migrator has digits in it.
|
||||
agent=$(sed -n 's/.*\*\*Agent\*\*: `\([a-z0-9-]*\)`.*/\1/p' "$plan" | head -1)
|
||||
[ -n "$agent" ] || { echo "could not read the agent name out of $plan" >&2; exit 1; }
|
||||
[ -f ".agents/agents/${agent}.md" ] || { echo "no such agent: .agents/agents/${agent}.md" >&2; exit 1; }
|
||||
|
||||
if [ -d "$dir" ]; then
|
||||
echo "worktree $dir already exists — reusing it"
|
||||
else
|
||||
git worktree add "$dir" -b "$branch" "$base"
|
||||
fi
|
||||
|
||||
# pnpm install works only once task 01 has produced a lockfile. The pre-existing root
|
||||
# package.json carries two scripts and no dependencies, so before task 01 there
|
||||
# is no toolchain to install and no hooks to verify.
|
||||
if [ -f "$dir/pnpm-lock.yaml" ]; then
|
||||
( cd "$dir" && pnpm install --frozen-lockfile && .agents/scripts/verify-hooks.sh )
|
||||
fi
|
||||
|
||||
prompt=$(cat <<PROMPT
|
||||
You are the \`${agent}\` specialist on the ai-for-dummies Astro refactor.
|
||||
You are working alone in the git worktree at $(cd "$dir" && pwd), on branch ${branch}.
|
||||
|
||||
Read these, in this order, before you write anything:
|
||||
|
||||
1. AGENTS.md — project entry point and the "never touch" list
|
||||
2. .agents/agents/${agent}.md — your role, what you own, what you must not do
|
||||
3. ${plan} — your task brief: scope, steps, done-when, do-not
|
||||
4. every file the brief and your agent definition tell you to read
|
||||
(.agents/context/*, .agents/rules/*, .agents/skills/*, .agents/checklists/*)
|
||||
|
||||
Then do the task. Rules that override your own judgement:
|
||||
|
||||
- Stay inside the scope in the brief. Do not do work belonging to another task.
|
||||
- Honour every "Do not" line in the brief and in your agent definition.
|
||||
- The site must look and read exactly as it does today. This is a refactor,
|
||||
not a redesign. If you find something that looks like a bug in the current
|
||||
design, write it down in the final report — do not fix it.
|
||||
- Never delete or weaken an assertion in scripts/verify.mjs to make a suite
|
||||
green. Only the verification-engineer may reduce assertion count, with a
|
||||
written reason per removal.
|
||||
- Commit as you go with conventional-commit messages. The commit-msg and
|
||||
pre-commit hooks are live; if a hook rejects you, fix the cause, never
|
||||
bypass with --no-verify.
|
||||
- Work through the done-when checklist at the end and actually run each check.
|
||||
|
||||
Finish by printing: what you changed, which done-when boxes are genuinely
|
||||
ticked, which are not and why, and anything the next task needs to know.
|
||||
PROMPT
|
||||
)
|
||||
|
||||
echo "task : ${number} ${slug}"
|
||||
echo "agent : ${agent}"
|
||||
echo "cli : ${cli}"
|
||||
echo "worktree: ${dir} (branch ${branch}, from ${base})"
|
||||
echo "log : ${log}"
|
||||
echo
|
||||
|
||||
run() {
|
||||
case "$cli" in
|
||||
codex)
|
||||
codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check \
|
||||
-C "$dir" "$prompt"
|
||||
;;
|
||||
agy)
|
||||
( cd "$dir" && agy --dangerously-skip-permissions \
|
||||
--model gemini-3.1-pro-high --print-timeout 4h -p "$prompt" )
|
||||
;;
|
||||
mm)
|
||||
( cd "$dir" && mm --dangerously-skip-permissions \
|
||||
--model opus -p "$prompt" )
|
||||
;;
|
||||
oc)
|
||||
# Claude Code against a local-Ollama-backed model, through the headroom
|
||||
# hub. Unproven on this repo — give it the task whose failure is cheapest.
|
||||
( cd "$dir" && OLLAMA_CLAUDE_MODEL="${OC_MODEL:-glm-5.3:cloud}" \
|
||||
ollama-claude --dangerously-skip-permissions -p "$prompt" )
|
||||
;;
|
||||
*) echo "unknown cli: $cli" >&2; exit 2 ;;
|
||||
esac
|
||||
}
|
||||
|
||||
if [ "$foreground" = 1 ]; then
|
||||
run 2>&1 | tee "$log"
|
||||
else
|
||||
export cli dir prompt
|
||||
nohup bash -c "$(declare -f run); run" >"$log" 2>&1 &
|
||||
echo "launched in background, pid $!"
|
||||
echo "follow: tail -f $log"
|
||||
fi
|
||||
@@ -1,123 +0,0 @@
|
||||
#!/usr/bin/env bash
|
||||
# Build the site and publish it to the `pages` branch.
|
||||
#
|
||||
# .agents/scripts/publish-pages.sh # publish
|
||||
# .agents/scripts/publish-pages.sh --dry-run # build and report, push nothing
|
||||
# .agents/scripts/publish-pages.sh --pending X # main is *about* to become X
|
||||
#
|
||||
# `--pending` exists for the pre-push hook. Git has no post-push hook, so the
|
||||
# hook necessarily runs before main lands on the remote and the usual "HEAD must
|
||||
# equal origin/main" check cannot hold yet. The caller asserts the SHA the push
|
||||
# will create, and the hook only asserts it after confirming the push is a
|
||||
# fast-forward.
|
||||
#
|
||||
# `pages` is what the Gitea Pages Server actually serves. Publishing overwrites
|
||||
# the live site. There is no staging environment between here and visitors.
|
||||
#
|
||||
# This never checks `pages` out. It writes a tree straight from `dist/` with
|
||||
# plumbing (`write-tree` + `commit-tree`), so your working tree is untouched and
|
||||
# a failure halfway through leaves nothing behind. The commit is parented on the
|
||||
# current `pages`, so the branch keeps its history and rollback is one push.
|
||||
set -euo pipefail
|
||||
|
||||
cd "$(git rev-parse --show-toplevel)"
|
||||
|
||||
dry_run=0
|
||||
pending=''
|
||||
while [ $# -gt 0 ]; do
|
||||
case "$1" in
|
||||
--dry-run) dry_run=1 ;;
|
||||
--pending)
|
||||
shift
|
||||
pending="${1:-}"
|
||||
;;
|
||||
*)
|
||||
echo "publish-pages: unknown argument '$1'" >&2
|
||||
exit 2
|
||||
;;
|
||||
esac
|
||||
shift
|
||||
done
|
||||
|
||||
fail() {
|
||||
echo "publish-pages: $1" >&2
|
||||
exit 1
|
||||
}
|
||||
|
||||
# Publishing a build made from uncommitted work means the live site shows
|
||||
# something no commit describes, and nobody can reproduce it later.
|
||||
[ -z "$(git status --porcelain)" ] || fail 'working tree is dirty; commit or stash first'
|
||||
|
||||
branch=$(git rev-parse --abbrev-ref HEAD)
|
||||
[ "$branch" = 'main' ] || fail "publishing from '$branch'; only main is publishable"
|
||||
|
||||
git fetch --quiet origin pages
|
||||
head=$(git rev-parse HEAD)
|
||||
if [ -n "$pending" ]; then
|
||||
[ "$head" = "$(git rev-parse "$pending")" ] ||
|
||||
fail "HEAD is $head but the pending push is $pending"
|
||||
else
|
||||
git fetch --quiet origin main
|
||||
[ "$head" = "$(git rev-parse origin/main)" ] ||
|
||||
fail 'HEAD is not origin/main; push main first so the site matches a pushed commit'
|
||||
fi
|
||||
|
||||
previous=$(git rev-parse origin/pages)
|
||||
|
||||
echo "publish-pages: building $head"
|
||||
# `astro build` exits 0 even when vite fails to resolve an asset, so the exit
|
||||
# code alone is not enough to know the build is whole. The gate greps for this
|
||||
# too; repeat it here because this script is also run by hand.
|
||||
build_log=$(mktemp)
|
||||
trap 'rm -f "$build_log"' EXIT
|
||||
pnpm run build >"$build_log" 2>&1 || {
|
||||
cat "$build_log" >&2
|
||||
fail 'astro build failed'
|
||||
}
|
||||
if grep -q '\[ERROR\]' "$build_log"; then
|
||||
cat "$build_log" >&2
|
||||
fail 'astro build logged an error and still exited 0; refusing to publish'
|
||||
fi
|
||||
|
||||
# A build can succeed and still emit a stub -- that is exactly how this site
|
||||
# would go down. Check the routes exist before overwriting anything live.
|
||||
for route in index full-guide/index summary/index models/index agents/index \
|
||||
skills/index rules/index skills-review/index \
|
||||
hands-on/starter/index hands-on/rules/index; do
|
||||
[ -s "dist/$route.html" ] || fail "dist/$route.html missing or empty; refusing to publish"
|
||||
done
|
||||
|
||||
# GIT_INDEX_FILE must name a path that does not exist yet: git reads an existing
|
||||
# empty file as a truncated index and dies with "index file smaller than
|
||||
# expected". mktemp -d gives a private directory to put that path in.
|
||||
index_dir=$(mktemp -d)
|
||||
index="$index_dir/index"
|
||||
trap 'rm -rf "$index_dir"; rm -f "$build_log"' EXIT
|
||||
# `--force` because the repository .gitignore lists `dist`; here `dist` *is* the
|
||||
# work tree, so those rules would otherwise exclude everything we mean to ship.
|
||||
GIT_INDEX_FILE="$index" git --work-tree=dist add --all --force .
|
||||
tree=$(GIT_INDEX_FILE="$index" git write-tree)
|
||||
|
||||
if [ "$tree" = "$(git rev-parse "$previous^{tree}")" ]; then
|
||||
echo "publish-pages: dist is identical to the published tree; nothing to do"
|
||||
exit 0
|
||||
fi
|
||||
|
||||
subject="chore: publish $(git rev-parse --short "$head")"
|
||||
commit=$(git commit-tree "$tree" -p "$previous" -m "$subject
|
||||
|
||||
Built from main $head
|
||||
$(git log -1 --format=%s "$head")")
|
||||
|
||||
if [ "$dry_run" -eq 1 ]; then
|
||||
echo "publish-pages: would push $commit to pages (previous $previous)"
|
||||
echo "publish-pages: dry run, nothing pushed"
|
||||
exit 0
|
||||
fi
|
||||
|
||||
echo "publish-pages: rollback point is $previous"
|
||||
echo " git push --force origin $previous:refs/heads/pages"
|
||||
|
||||
# AF_PUBLISHING stops the pre-push hook recursing into this script.
|
||||
AF_PUBLISHING=1 git push --force origin "$commit:refs/heads/pages"
|
||||
echo "publish-pages: published $commit"
|
||||
@@ -1,185 +0,0 @@
|
||||
#!/usr/bin/env node
|
||||
// Compare the *rendered* text of a legacy page against its Astro replacement.
|
||||
//
|
||||
// node .agents/scripts/rendered-text-diff.mjs full-guide
|
||||
// node .agents/scripts/rendered-text-diff.mjs full-guide --pt
|
||||
//
|
||||
// Why this exists: scripts/verify.mjs reads the legacy files, so a migrated
|
||||
// page can drop half its content and still pass the gate. Task 15d shipped
|
||||
// /full-guide/ missing 86 rendered spans -- the entire verification section,
|
||||
// the hands-on exercise brief, and both "Clone from Gitea" links -- and every
|
||||
// check was green.
|
||||
//
|
||||
// Static HTML comparison is useless here: the guide's tab panels are injected
|
||||
// by an island at runtime, so half the legacy page's markup has no static
|
||||
// counterpart. This walks the live DOM instead and skips anything the browser
|
||||
// is not painting -- which also drops the hidden Portuguese half of each
|
||||
// bilingual pair, so the two sides line up.
|
||||
//
|
||||
// Requires playwright (devDependency) and two static servers; it starts both.
|
||||
//
|
||||
// The legacy pages were deleted at cutover, so this needs a pre-cutover tree:
|
||||
// git worktree add /tmp/vanilla <pre-cutover-sha>
|
||||
// and run from there, or run it from a checkout that still has them.
|
||||
import { spawn } from 'node:child_process';
|
||||
import { cpSync, mkdtempSync, rmSync } from 'node:fs';
|
||||
import { tmpdir } from 'node:os';
|
||||
import { join } from 'node:path';
|
||||
import { createServer } from 'node:net';
|
||||
import { chromium } from 'playwright';
|
||||
|
||||
// `index` is the landing page: it lives at the repository root, not in a
|
||||
// directory of its own, so it needs a different path on the legacy side.
|
||||
const route = process.argv[2];
|
||||
if (!route) {
|
||||
console.error('usage: rendered-text-diff.mjs <route> [--pt] e.g. full-guide, or index');
|
||||
process.exit(2);
|
||||
}
|
||||
|
||||
// `--pt` clicks the language toggle on both pages first. English parity is
|
||||
// only half the contract: a page can render every English string and still
|
||||
// leave a restored block untranslated, because the Portuguese half is a
|
||||
// separate set of nodes. Only /full-guide/ and /rules/ have a toggle.
|
||||
const portuguese = process.argv.includes('--pt');
|
||||
const legacyPath = route === 'index' ? 'index.html' : `${route}/index.html`;
|
||||
const astroPath = route === 'index' ? '' : `${route}/`;
|
||||
|
||||
// The built site expects to be served under the configured base path.
|
||||
const staging = mkdtempSync(join(tmpdir(), 'af-rtd-'));
|
||||
cpSync('dist', join(staging, 'ai-for-dummies'), { recursive: true });
|
||||
|
||||
// Ask the kernel for a free port rather than pinning one. Back-to-back runs
|
||||
// used to collide: the previous run's server was still holding the fixed port
|
||||
// while its staging directory had already been deleted, so every page came
|
||||
// back as a 404 and the diff reported the whole route missing.
|
||||
const freePort = () =>
|
||||
new Promise((resolve, reject) => {
|
||||
const probe = createServer();
|
||||
probe.on('error', reject);
|
||||
probe.listen(0, '127.0.0.1', () => {
|
||||
const { port } = probe.address();
|
||||
probe.close(() => resolve(port));
|
||||
});
|
||||
});
|
||||
|
||||
const legacyPort = await freePort();
|
||||
const astroPort = await freePort();
|
||||
|
||||
const serve = (dir, port) =>
|
||||
spawn('python3', ['-m', 'http.server', String(port), '-d', dir], { stdio: 'ignore' });
|
||||
const servers = [serve('.', legacyPort), serve(staging, astroPort)];
|
||||
const stop = () => {
|
||||
servers.forEach((s) => s.kill());
|
||||
rmSync(staging, { recursive: true, force: true });
|
||||
};
|
||||
|
||||
// Visible text nodes, in document order, whitespace collapsed.
|
||||
const visibleText = () => {
|
||||
const out = [];
|
||||
const walk = (node) => {
|
||||
for (const child of node.childNodes) {
|
||||
if (child.nodeType === Node.TEXT_NODE) {
|
||||
const text = child.textContent.replace(/\s+/g, ' ').trim();
|
||||
if (text) out.push(text);
|
||||
continue;
|
||||
}
|
||||
if (child.nodeType !== Node.ELEMENT_NODE) continue;
|
||||
if (child.tagName === 'SCRIPT' || child.tagName === 'STYLE') continue;
|
||||
const style = getComputedStyle(child);
|
||||
if (child.hidden || style.display === 'none' || style.visibility === 'hidden') continue;
|
||||
walk(child);
|
||||
}
|
||||
};
|
||||
walk(document.body);
|
||||
return out;
|
||||
};
|
||||
|
||||
try {
|
||||
await new Promise((r) => setTimeout(r, 1500));
|
||||
const browser = await chromium.launch();
|
||||
const grab = async (url) => {
|
||||
const page = await browser.newPage({ viewport: { width: 1400, height: 1000 } });
|
||||
const response = await page.goto(url, { waitUntil: 'load' });
|
||||
// A 404 renders as four spans of python's error page and the diff then
|
||||
// reports the entire route as missing, which reads exactly like a real
|
||||
// regression. Fail loudly instead.
|
||||
if (!response || !response.ok()) {
|
||||
throw new Error(`${url} returned ${response ? response.status() : 'no response'}`);
|
||||
}
|
||||
// The islands hydrate and render their initial panel on load; without this
|
||||
// every panel's copy reads as missing.
|
||||
await page.waitForTimeout(1200);
|
||||
if (portuguese) {
|
||||
const toggle = await page.$('[data-lang="pt"]');
|
||||
if (!toggle) throw new Error(`no language toggle on ${url}`);
|
||||
await toggle.click();
|
||||
await page.waitForTimeout(1200);
|
||||
}
|
||||
// Islands hydrate at their own pace, and the language toggle repaints in
|
||||
// more than one frame. A single read after a fixed wait is flaky, so read
|
||||
// until two consecutive reads agree.
|
||||
let spans = await page.evaluate(visibleText);
|
||||
for (let i = 0; i < 10; i += 1) {
|
||||
await page.waitForTimeout(300);
|
||||
const next = await page.evaluate(visibleText);
|
||||
if (next.length === spans.length && next.every((span, j) => span === spans[j])) {
|
||||
spans = next;
|
||||
break;
|
||||
}
|
||||
spans = next;
|
||||
}
|
||||
await page.close();
|
||||
return spans;
|
||||
};
|
||||
|
||||
const legacy = await grab(`http://localhost:${legacyPort}/${legacyPath}`);
|
||||
const astro = await grab(`http://localhost:${astroPort}/ai-for-dummies/${astroPath}`);
|
||||
await browser.close();
|
||||
|
||||
// Count occurrences, not membership. A set comparison reports zero when a
|
||||
// string the legacy page paints four times is painted three times here --
|
||||
// exactly the kind of near-miss that got past the earlier checks.
|
||||
const tally = (spans) => {
|
||||
const counts = new Map();
|
||||
for (const span of spans) counts.set(span, (counts.get(span) || 0) + 1);
|
||||
return counts;
|
||||
};
|
||||
|
||||
const legacyCounts = tally(legacy);
|
||||
const astroCounts = tally(astro);
|
||||
|
||||
const missing = [];
|
||||
for (const [span, count] of legacyCounts) {
|
||||
const short = count - (astroCounts.get(span) || 0);
|
||||
for (let i = 0; i < short; i += 1) missing.push(span);
|
||||
}
|
||||
|
||||
// Both directions. A string the Astro page paints and the legacy page does
|
||||
// not is just as wrong: it means a translation was invented, or an English
|
||||
// string was left standing where the legacy page swaps it.
|
||||
const extra = [];
|
||||
for (const [span, count] of astroCounts) {
|
||||
const over = count - (legacyCounts.get(span) || 0);
|
||||
for (let i = 0; i < over; i += 1) extra.push(span);
|
||||
}
|
||||
|
||||
// Order counts too. Both pages can paint the same strings while a block
|
||||
// sits in the wrong place -- the Portuguese eyebrow, or a reordered card
|
||||
// deck -- and a count-only comparison calls that clean.
|
||||
const firstOutOfOrder = legacy.findIndex((span, i) => astro[i] !== span);
|
||||
|
||||
const mode = portuguese ? 'pt' : 'en';
|
||||
console.log(
|
||||
`${mode} · legacy ${legacy.length} spans · astro ${astro.length} spans · missing ${missing.length} · extra ${extra.length}`,
|
||||
);
|
||||
for (const span of missing) console.log(` - ${span}`);
|
||||
for (const span of extra) console.log(` + ${span}`);
|
||||
if (firstOutOfOrder !== -1) {
|
||||
console.log(` order diverges at span ${firstOutOfOrder}`);
|
||||
console.log(` legacy: ${legacy[firstOutOfOrder]}`);
|
||||
console.log(` astro: ${astro[firstOutOfOrder]}`);
|
||||
}
|
||||
process.exitCode = missing.length === 0 && extra.length === 0 && firstOutOfOrder === -1 ? 0 : 1;
|
||||
} finally {
|
||||
stop();
|
||||
}
|
||||
@@ -1,41 +0,0 @@
|
||||
#!/usr/bin/env node
|
||||
// Rendered-text snapshot of one route. This is the migration's regression net:
|
||||
// token matching in verify.mjs cannot catch a dropped paragraph, this can.
|
||||
//
|
||||
// Usage:
|
||||
// node .agents/scripts/snapshot-route.mjs http://localhost:4173/models/
|
||||
// node .agents/scripts/snapshot-route.mjs dist/models/index.html
|
||||
//
|
||||
// Take a snapshot from the vanilla site BEFORE migrating, then diff the built
|
||||
// output against it. An empty diff is the proof that nothing was lost.
|
||||
|
||||
import { readFileSync } from 'node:fs';
|
||||
|
||||
const target = process.argv[2];
|
||||
if (!target) {
|
||||
console.error('usage: snapshot-route.mjs <url|path>');
|
||||
process.exit(2);
|
||||
}
|
||||
|
||||
const html = target.startsWith('http')
|
||||
? await (await fetch(target)).text()
|
||||
: readFileSync(target, 'utf8');
|
||||
|
||||
const text = html
|
||||
// Drop anything that is not user-visible prose.
|
||||
.replace(/<script[\s\S]*?<\/script>/gi, '')
|
||||
.replace(/<style[\s\S]*?<\/style>/gi, '')
|
||||
.replace(/<!--[\s\S]*?-->/g, '')
|
||||
.replace(/<[^>]+>/g, '\n')
|
||||
.replace(/&/g, '&')
|
||||
.replace(/</g, '<')
|
||||
.replace(/>/g, '>')
|
||||
.replace(/"/g, '"')
|
||||
.replace(/�?39;/g, "'")
|
||||
.replace(/ /g, ' ')
|
||||
.split('\n')
|
||||
.map((line) => line.trim())
|
||||
.filter(Boolean)
|
||||
.join('\n');
|
||||
|
||||
console.log(text);
|
||||
@@ -1,51 +0,0 @@
|
||||
#!/usr/bin/env bash
|
||||
# Guards the silent-failure mode described in .agents/rules/gates.md.
|
||||
#
|
||||
# Husky points core.hooksPath at `.husky/_`, but that directory is GENERATED by
|
||||
# `pnpm install` and is NOT committed. A fresh `git worktree add` therefore has
|
||||
# hooks configured and the directory missing — so every hook silently does
|
||||
# nothing and every commit passes unchecked.
|
||||
#
|
||||
# Run this in any worktree you did not create with worktree.sh.
|
||||
set -euo pipefail
|
||||
|
||||
cd "$(git rev-parse --show-toplevel)"
|
||||
fail=0
|
||||
|
||||
path=$(git config --get core.hooksPath || true)
|
||||
if [ -z "$path" ]; then
|
||||
echo "✗ core.hooksPath is unset — husky was never installed here"
|
||||
fail=1
|
||||
else
|
||||
echo "✓ core.hooksPath = $path"
|
||||
fi
|
||||
|
||||
if [ ! -d "${path:-.husky/_}" ]; then
|
||||
echo "✗ ${path:-.husky/_}/ does not exist — HOOKS ARE NOT RUNNING"
|
||||
fail=1
|
||||
else
|
||||
echo "✓ ${path} exists"
|
||||
fi
|
||||
|
||||
for hook in pre-commit commit-msg pre-push; do
|
||||
if [ -f ".husky/$hook" ]; then
|
||||
echo "✓ .husky/$hook present"
|
||||
else
|
||||
echo "✗ .husky/$hook missing"
|
||||
fail=1
|
||||
fi
|
||||
done
|
||||
|
||||
if [ ! -d node_modules ]; then
|
||||
echo "✗ node_modules missing — lint-staged and astro check cannot run"
|
||||
fail=1
|
||||
fi
|
||||
|
||||
if [ "$fail" -ne 0 ]; then
|
||||
echo
|
||||
echo "Fix: pnpm install --frozen-lockfile (its prepare script regenerates .husky/_)"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo
|
||||
echo "hooks are live in this worktree"
|
||||
@@ -1,58 +0,0 @@
|
||||
#!/usr/bin/env node
|
||||
// Keep vanilla screenshots before a page changes; compare them against the
|
||||
// migrated preview when a visual diff needs investigation.
|
||||
|
||||
import { mkdirSync } from 'node:fs';
|
||||
|
||||
const routes = [
|
||||
'/',
|
||||
'/full-guide/',
|
||||
'/summary/',
|
||||
'/models/',
|
||||
'/agents/',
|
||||
'/skills/',
|
||||
'/rules/',
|
||||
'/skills-review/',
|
||||
'/hands-on/starter/',
|
||||
'/hands-on/rules/',
|
||||
];
|
||||
const widths = [560, 800, 1100, 1600];
|
||||
const hasReducedMotion = process.argv.includes('--reduced-motion');
|
||||
const base = process.env.VISUAL_BASE_URL ?? 'http://localhost:4173';
|
||||
const output =
|
||||
process.env.VISUAL_OUTPUT_DIR ??
|
||||
`.agents/snapshots/${hasReducedMotion ? 'before-reduced-motion' : 'before'}`;
|
||||
|
||||
mkdirSync(output, { recursive: true });
|
||||
|
||||
let chromium;
|
||||
try {
|
||||
({ chromium } = await import('playwright'));
|
||||
} catch {
|
||||
throw new Error(
|
||||
'visual regression requires Playwright; install its project dependency and run pnpm exec playwright install chromium',
|
||||
);
|
||||
}
|
||||
|
||||
const browser = await chromium.launch({
|
||||
headless: true,
|
||||
...(process.env.VISUAL_BROWSER_PATH ? { executablePath: process.env.VISUAL_BROWSER_PATH } : {}),
|
||||
});
|
||||
try {
|
||||
for (const route of routes) {
|
||||
for (const width of widths) {
|
||||
const page = await browser.newPage({ viewport: { width, height: 900 } });
|
||||
if (hasReducedMotion) await page.emulateMedia({ reducedMotion: 'reduce' });
|
||||
// The legacy site intentionally calls optional services that may be down;
|
||||
// visual capture is about the rendered page, not their network lifetime.
|
||||
await page.goto(new URL(route, base).toString(), { waitUntil: 'domcontentloaded' });
|
||||
const name = route.replace(/^\/+|\/+$/g, '').replaceAll('/', '_') || 'index';
|
||||
await page.screenshot({ path: `${output}/${name}-${width}.png`, fullPage: true });
|
||||
await page.close();
|
||||
}
|
||||
}
|
||||
} finally {
|
||||
await browser.close();
|
||||
}
|
||||
|
||||
console.log(`captured ${routes.length * widths.length} screenshots in ${output}`);
|
||||
@@ -1,50 +0,0 @@
|
||||
#!/usr/bin/env bash
|
||||
# Spin up (or tear down) an isolated worktree for one refactor task.
|
||||
#
|
||||
# .agents/scripts/worktree.sh start 07 route-cards
|
||||
# .agents/scripts/worktree.sh finish 07 route-cards
|
||||
#
|
||||
# One task, one worktree, one agent. See .agents/rules/git-worktrees.md
|
||||
set -euo pipefail
|
||||
|
||||
action=${1:?usage: worktree.sh <start|finish> <task-number> <slug>}
|
||||
number=${2:?task number, e.g. 07}
|
||||
slug=${3:?slug, e.g. route-cards}
|
||||
|
||||
dir="../af-task-${number}"
|
||||
branch="refactor/task-${number}-${slug}"
|
||||
plan="plans/astro-refactor/task-${number}-${slug}.md"
|
||||
|
||||
case "$action" in
|
||||
start)
|
||||
[ -f "$plan" ] || echo "warning: no plan at $plan — check the task number" >&2
|
||||
git fetch origin
|
||||
git worktree add "$dir" -b "$branch" origin/main
|
||||
|
||||
# Not optional. `.husky/_` is generated by install and is NOT committed, so
|
||||
# a fresh worktree has hooks configured but absent — every commit would pass
|
||||
# unchecked. --prefer-offline keeps ten parallel spin-ups off the registry.
|
||||
( cd "$dir" && pnpm install --frozen-lockfile && .agents/scripts/verify-hooks.sh )
|
||||
|
||||
echo
|
||||
echo "worktree : $dir"
|
||||
echo "branch : $branch"
|
||||
echo "brief : $plan"
|
||||
echo
|
||||
echo "next: cd $dir && read the brief end to end before writing anything"
|
||||
;;
|
||||
finish)
|
||||
# Never remove a worktree with uncommitted work in it.
|
||||
if [ -n "$(git -C "$dir" status --porcelain)" ]; then
|
||||
echo "refusing: $dir has uncommitted changes" >&2
|
||||
git -C "$dir" status --short >&2
|
||||
exit 1
|
||||
fi
|
||||
git worktree remove "$dir"
|
||||
echo "removed $dir — branch $branch kept; delete it after the merge lands"
|
||||
;;
|
||||
*)
|
||||
echo "unknown action: $action (expected start|finish)" >&2
|
||||
exit 2
|
||||
;;
|
||||
esac
|
||||
@@ -1,81 +0,0 @@
|
||||
---
|
||||
name: astro-component
|
||||
description:
|
||||
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`](../../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
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```astro
|
||||
---
|
||||
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
|
||||
|
||||
1. Render it at 560 / 800 / 1100 / 1600 px.
|
||||
2. Tab to it. Focus ring visible (`outline: 3px solid #a7483f`).
|
||||
3. Diff its rendered text against the markup it replaced.
|
||||
4. Run
|
||||
[`../../checklists/before-component.md`](../../checklists/before-component.md).
|
||||
5. `pnpm run verify` — green, with no assertion deleted.
|
||||
@@ -1,73 +0,0 @@
|
||||
---
|
||||
name: astro-page
|
||||
description:
|
||||
Migrate one hand-written HTML page of the ai-for-dummies site to an Astro
|
||||
route without changing its URL, content, or JS budget. Use for any page-level
|
||||
migration task.
|
||||
---
|
||||
|
||||
# Migrating a page to Astro
|
||||
|
||||
## Snapshot first, migrate second
|
||||
|
||||
The snapshot is the only objective evidence that no content was lost.
|
||||
|
||||
The vanilla site was deleted at cutover. To compare against it, check the
|
||||
pre-cutover tree out into a scratch worktree first:
|
||||
|
||||
```bash
|
||||
git worktree add /tmp/vanilla <pre-cutover-sha>
|
||||
(cd /tmp/vanilla && python3 -m http.server 4173) &
|
||||
node .agents/scripts/snapshot-route.mjs http://localhost:4173/models/ \
|
||||
> .agents/snapshots/models.txt
|
||||
```
|
||||
|
||||
Screenshot the same route at 560 / 800 / 1100 / 1600 px as well.
|
||||
|
||||
## Migrate
|
||||
|
||||
```bash
|
||||
cp .agents/templates/pages/chapter.astro src/pages/models.astro
|
||||
```
|
||||
|
||||
Then, in order:
|
||||
|
||||
1. Move markup into the layout + components. Reuse existing components before
|
||||
creating new ones.
|
||||
2. Move copy into `src/content/`. Both `en` and `pt`, copied literally — never
|
||||
retyped.
|
||||
3. Move page CSS into component `<style>` blocks. Do **not** port
|
||||
`responsive.css` wholesale; take what this page needs and prove the rest
|
||||
dead.
|
||||
4. Keep every `data-*` hook. `verify.mjs` asserts many of them by name
|
||||
(`data-phase`, `data-tree`, `data-route`, `data-model-provider`, …).
|
||||
5. Keep every ARIA attribute and the `<title>` / `<meta name="description">`.
|
||||
|
||||
## The URL must not change
|
||||
|
||||
Served from `/ai-for-dummies/`, so `base` is set in `astro.config.mjs`. Never
|
||||
hand-write an internal absolute path; use `import.meta.env.BASE_URL`.
|
||||
|
||||
Trailing slashes matter. `/models/` must not become `/models`.
|
||||
|
||||
If the page honours query params (the review desk uses `?author=`, `?skill=`,
|
||||
`?view=`, `?file=`, `?compare=`, `?render=`), they must still work — they are
|
||||
documented in the page footer and shared externally.
|
||||
|
||||
## Prove it
|
||||
|
||||
```bash
|
||||
pnpm run build
|
||||
node .agents/scripts/snapshot-route.mjs dist/models/index.html > /tmp/after.txt
|
||||
diff .agents/snapshots/models.txt /tmp/after.txt # empty, or justify every line
|
||||
node scripts/audit-ui.mjs
|
||||
pnpm run verify
|
||||
```
|
||||
|
||||
Then screenshots at the same four widths, and
|
||||
[`../../checklists/before-page.md`](../../checklists/before-page.md).
|
||||
|
||||
## JS budget
|
||||
|
||||
A page that shipped zero JS must still ship zero. Check the build output. If
|
||||
your migration added a `client:load` to a static page, you did it wrong.
|
||||
@@ -1,76 +0,0 @@
|
||||
---
|
||||
name: content-migration
|
||||
description:
|
||||
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
|
||||
|
||||
```ts
|
||||
// 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
|
||||
|
||||
1. Extract the literals mechanically (script, not by hand).
|
||||
2. Write them into the collection.
|
||||
3. Diff extracted-before against extracted-after. Must be empty.
|
||||
|
||||
```bash
|
||||
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
|
||||
```
|
||||
|
||||
4. 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.
|
||||
@@ -1,76 +0,0 @@
|
||||
---
|
||||
name: design-tokens
|
||||
description:
|
||||
Extract, name, and enforce the design token layer for the ai-for-dummies site.
|
||||
Use when touching any colour, font size, spacing value, or breakpoint, when
|
||||
consolidating the three drifted palettes, or when a check-tokens failure needs
|
||||
resolving.
|
||||
---
|
||||
|
||||
# Design tokens
|
||||
|
||||
## Before anything
|
||||
|
||||
Read [`../../context/design-system.md`](../../context/design-system.md). This
|
||||
site has **three drifting palettes** and a **broken `@font-face`**. Both are
|
||||
traps. If you have not read that file, you will "preserve the styles" by copying
|
||||
a bug.
|
||||
|
||||
## Extracting
|
||||
|
||||
```bash
|
||||
python3 - <<'PY'
|
||||
import re
|
||||
files=['legacy/styles/guide.css','legacy/styles/chapters.css','legacy/styles/skills.css',
|
||||
'legacy/styles/skills-review.css','legacy/styles/change-lens.css',
|
||||
'legacy/styles/audit.css','public/hands-on/starter/styles.css',
|
||||
'public/hands-on/rules/styles.css']
|
||||
seen={}
|
||||
for f in files:
|
||||
for m in re.finditer(r'--([a-z-]+):\s*([^;}]+)', open(f).read()):
|
||||
seen.setdefault(m.group(1),{}).setdefault(m.group(2).strip(),[]).append(f)
|
||||
for k,v in sorted(seen.items()):
|
||||
print(f"--{k}:")
|
||||
for val,fs in v.items(): print(f" {val:12} <- {', '.join(fs)}")
|
||||
PY
|
||||
```
|
||||
|
||||
Re-run this after any consolidation. Every token should print exactly one value.
|
||||
|
||||
## Consolidating a drifted token
|
||||
|
||||
1. List every value and where it is used (above).
|
||||
2. Compute the perceptual delta. Sub-perceptual (a few units per channel) →
|
||||
canonicalize freely. Visible (`--blue`: `#527f9f` vs `#215675`) → screenshot
|
||||
both, get a human decision, record it in the task file.
|
||||
3. Pick the canonical value. Prefer the one used on the most-visited surface.
|
||||
4. Replace, then screenshot every affected page at 560/800/1100/1600 px.
|
||||
5. Attach before/after images to the task report. "It looked fine to me" is not
|
||||
evidence.
|
||||
|
||||
## Naming
|
||||
|
||||
Semantic, matching the existing vocabulary — `--ink`, `--paper`, `--muted`,
|
||||
`--line`, `--accent`, `--gold`, `--blue`, `--deep`. Never numeric scales. New
|
||||
surfaces extend semantically: `--surface-lab`, `--ink-inverse`.
|
||||
|
||||
## Type scale and breakpoints
|
||||
|
||||
Collapse the 14 ad-hoc `clamp()` triples to named steps and the 16 breakpoints
|
||||
to five, per [`../../rules/theming.md`](../../rules/theming.md). When collapsing
|
||||
a breakpoint, **screenshot at the old value** — that is where the regression is.
|
||||
|
||||
## Enforcing
|
||||
|
||||
```bash
|
||||
node .agents/scripts/check-tokens.mjs # fails on raw hex outside tokens.css
|
||||
```
|
||||
|
||||
Wire it into `pnpm run verify`. A rule nobody checks is a suggestion.
|
||||
|
||||
## The font decision
|
||||
|
||||
Do not self-host Manrope/DM Mono as part of a refactor task. The intended fonts
|
||||
have never rendered, so adopting them is a visual redesign. Default to matching
|
||||
what renders today (Arial / generic monospace) and delete the dead `@font-face`.
|
||||
If a human wants the real fonts, that is its own task with its own screenshots.
|
||||
@@ -1,79 +0,0 @@
|
||||
---
|
||||
name: motion
|
||||
description:
|
||||
Add or review animation on the ai-for-dummies site — transitions, state
|
||||
changes, view transitions. Use when any element moves, fades, or transforms,
|
||||
or when auditing existing motion for performance and reduced-motion support.
|
||||
---
|
||||
|
||||
# Motion
|
||||
|
||||
This is an editorial-print design. Motion is punctuation. Read
|
||||
[`../../rules/animation.md`](../../rules/animation.md) — it is binding; this is
|
||||
the procedure.
|
||||
|
||||
## Decide it should move
|
||||
|
||||
Answer out loud: **what does this motion tell the user that the static state
|
||||
does not?** Valid answers: something changed, attention needs directing to what
|
||||
changed, a layout shift needs smoothing. "It feels more polished" is not an
|
||||
answer — on this design it reads as generic.
|
||||
|
||||
If there is no answer, ship it static. That is a legitimate, common outcome.
|
||||
|
||||
## Build it
|
||||
|
||||
```css
|
||||
.panel {
|
||||
transition:
|
||||
opacity 180ms cubic-bezier(0.2, 0, 0, 1),
|
||||
transform 180ms cubic-bezier(0.2, 0, 0, 1);
|
||||
}
|
||||
.panel[data-state='entering'] {
|
||||
opacity: 0;
|
||||
transform: translateY(6px);
|
||||
}
|
||||
```
|
||||
|
||||
- **`transform` and `opacity` only.** Animating `width`/`height`/`top`/`left`
|
||||
forces layout every frame and shows up as a failed INP (budget: 200ms).
|
||||
- 150–250ms for UI feedback; up to 400ms for a page transition.
|
||||
- One thing moves at a time. No staggered card cascades.
|
||||
- `will-change` only immediately before animating, removed after.
|
||||
- No animation library. This site's thesis is having no runtime dependencies.
|
||||
|
||||
## Reduced motion is not optional
|
||||
|
||||
```css
|
||||
@media (prefers-reduced-motion: reduce) {
|
||||
* {
|
||||
animation-duration: 0.01ms !important;
|
||||
animation-iteration-count: 1 !important;
|
||||
transition-duration: 0.01ms !important;
|
||||
scroll-behavior: auto !important;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Then **test it**: DevTools → Rendering → Emulate
|
||||
`prefers-reduced-motion: reduce`. The end state must still be correct and the UI
|
||||
still usable. Reduced, not broken.
|
||||
|
||||
## Page transitions
|
||||
|
||||
Astro's `<ClientRouter />` is the only sanctioned motion dependency. Before
|
||||
enabling it, verify:
|
||||
|
||||
- JS disabled → full navigation still works
|
||||
- browser back/forward still works
|
||||
- the review desk's query-param deep links survive
|
||||
- `prefers-reduced-motion` is honoured
|
||||
|
||||
## Audit an existing animation
|
||||
|
||||
```bash
|
||||
grep -rn "transition\|animation\|@keyframes\|transform" src/ --include="*.astro" --include="*.css"
|
||||
```
|
||||
|
||||
For each hit ask: does it animate a layout property? does it respect reduced
|
||||
motion? is there a stated purpose? Three questions, three possible fixes.
|
||||
@@ -1,67 +0,0 @@
|
||||
---
|
||||
name: verify-contract
|
||||
description:
|
||||
Evolve scripts/verify.mjs across the Astro migration without losing coverage.
|
||||
Use whenever a verify assertion fails because of a refactor, or when adding
|
||||
checks for new architecture.
|
||||
---
|
||||
|
||||
# The verification contract
|
||||
|
||||
Read [`../../context/verification.md`](../../context/verification.md) first.
|
||||
|
||||
`verify.mjs` has 42 assertions pinning real content and interactions. They are
|
||||
the only thing preventing silent content loss during this migration, and they
|
||||
will all break, because they assert against files that stop existing.
|
||||
|
||||
## The rule
|
||||
|
||||
**A failing assertion is a question, not a bug to delete.**
|
||||
|
||||
```
|
||||
assertion fails
|
||||
↓
|
||||
does the user-visible fact it pins still exist?
|
||||
├── yes → re-point the assertion at the new location
|
||||
└── no → you deleted content. Put it back, or get sign-off.
|
||||
```
|
||||
|
||||
`grep -c 'throw new Error' scripts/verify.mjs` must not decrease. If it must,
|
||||
the `verification-engineer` writes a one-line reason per removal in the task
|
||||
report. Nobody else may reduce coverage.
|
||||
|
||||
## Translating assertions
|
||||
|
||||
| Kind | Old | New |
|
||||
| --------------------- | ------------------------------------ | ----------------------------------------------------------------------------- |
|
||||
| Content presence | `html.includes('data-phase="plan"')` | same token, read from `dist/full-guide/index.html` |
|
||||
| Implementation detail | `js.includes('renderTree')` | assert the rendered output has the tree UI, not that a function is named that |
|
||||
| Asset version | `'app.js?v=20260904-vote-widget'` | assert the built HTML references a hashed asset |
|
||||
|
||||
Implementation-detail assertions are the dangerous ones: they _look_ deletable.
|
||||
They are pinning a feature. Replace with an output-level assertion of the same
|
||||
feature; never drop.
|
||||
|
||||
## Add the stronger check
|
||||
|
||||
Token matching cannot catch a dropped paragraph. Add rendered-text snapshots:
|
||||
|
||||
```bash
|
||||
# before migrating
|
||||
node .agents/scripts/snapshot-route.mjs http://localhost:4173/models/ > .agents/snapshots/models.txt
|
||||
# after
|
||||
node .agents/scripts/snapshot-route.mjs dist/models/index.html | diff .agents/snapshots/models.txt -
|
||||
```
|
||||
|
||||
Commit the snapshots. They are the migration's regression net.
|
||||
|
||||
## Extend audit-ui.mjs
|
||||
|
||||
It rejects external `<script>`/`<link>` but **misses external URLs inside CSS**
|
||||
— which is exactly how the broken Google Fonts `@font-face` in `styles.css:1`
|
||||
got into a "dependency-free" site. Add:
|
||||
|
||||
```js
|
||||
if (/@import|src:\s*url\(['"]?https?:|url\(['"]?https?:/i.test(css))
|
||||
throw new Error(`${file} has an external CSS dependency`);
|
||||
```
|
||||
@@ -1,74 +0,0 @@
|
||||
---
|
||||
name: visual-regression
|
||||
description:
|
||||
Prove a refactor did not change how the site looks. Use before and after any
|
||||
page migration, token consolidation, or breakpoint change on ai-for-dummies.
|
||||
---
|
||||
|
||||
# Visual regression
|
||||
|
||||
"Maintain the same styles" is a testable claim. Test it.
|
||||
|
||||
## Capture
|
||||
|
||||
The repo already has a Playwright pattern (`scripts/inspect.py`). Extend it
|
||||
rather than inventing one.
|
||||
|
||||
```python
|
||||
from playwright.sync_api import sync_playwright
|
||||
ROUTES = ['/', '/full-guide/', '/summary/', '/models/', '/agents/',
|
||||
'/skills/', '/rules/', '/skills-review/',
|
||||
'/hands-on/starter/', '/hands-on/rules/']
|
||||
WIDTHS = [560, 800, 1100, 1600]
|
||||
|
||||
with sync_playwright() as p:
|
||||
browser = p.chromium.launch(headless=True)
|
||||
for route in ROUTES:
|
||||
for w in WIDTHS:
|
||||
page = browser.new_page(viewport={'width': w, 'height': 900})
|
||||
page.goto(f'{BASE}{route}', wait_until='networkidle')
|
||||
page.screenshot(path=f'{OUT}/{route.strip("/").replace("/","_") or "index"}-{w}.png',
|
||||
full_page=True)
|
||||
page.close()
|
||||
browser.close()
|
||||
```
|
||||
|
||||
Run once against `pnpm run preview`. To compare against the vanilla site, serve
|
||||
a pre-cutover worktree on :4173 first — those files are no longer on `main`.
|
||||
Keep both sets.
|
||||
|
||||
## Compare
|
||||
|
||||
```bash
|
||||
for f in before/*.png; do
|
||||
compare -metric AE "$f" "after/$(basename $f)" null: 2>&1 # ImageMagick
|
||||
echo " <- $(basename $f)"
|
||||
done
|
||||
```
|
||||
|
||||
Pixel-exact is not the bar — antialiasing differs. Judge by eye where the metric
|
||||
is non-trivial, and attach the pair to the task report.
|
||||
|
||||
## The three widths that catch the most
|
||||
|
||||
- **560px** — where the 16 ad-hoc breakpoints collapse to `--bp-sm`. Highest
|
||||
risk in the whole migration.
|
||||
- **800px** — the most common existing breakpoint; layout flips here.
|
||||
- **1600px** — `min-width` rules that only fire on large screens are the ones
|
||||
nobody notices are broken.
|
||||
|
||||
Also screenshot at the **old** breakpoint values you removed (520, 530, 600,
|
||||
620, 720, 850, 880, 900), not just the new ones. Regressions hide exactly there.
|
||||
|
||||
## What a real difference looks like
|
||||
|
||||
Expect and accept: sub-pixel text shifts, antialiasing.
|
||||
|
||||
Investigate: anything that moves by more than ~2px, any colour change (that is a
|
||||
token bug), any element that appears or disappears (that is content loss — stop
|
||||
and check the snapshot diff).
|
||||
|
||||
## Reduced motion
|
||||
|
||||
Capture one pass with `prefers_reduced_motion='reduce'`. Animations must land in
|
||||
their correct end state, not vanish.
|
||||
@@ -1,40 +0,0 @@
|
||||
AI For Dummies — Agents and trees
|
||||
← ROUTE MAP
|
||||
02 / AGENTS & TREES
|
||||
field guide ↗
|
||||
Subagent workflow
|
||||
One branch
|
||||
per
|
||||
hand.
|
||||
Agents work when roles, files, and evidence are bounded. A worktree gives each worker its own checkout while the orchestrator protects intent.
|
||||
The tree
|
||||
Split at
|
||||
the
|
||||
seam.
|
||||
MAIN / ORCHESTRATOR
|
||||
├── agent/ui → components + visual states · ├── agent/tests → acceptance + regressions · └── agent/docs → guide + examples · merge after each leaf returns a diff and evidence
|
||||
FRAME
|
||||
Orchestrator
|
||||
Owns scope, task graph, boundaries, and integration.
|
||||
HAND OFF
|
||||
Worker
|
||||
Owns one coherent slice and one worktree.
|
||||
PROVE
|
||||
Verifier
|
||||
Re-runs gates and reports remaining gaps.
|
||||
Handoff
|
||||
Context that
|
||||
can
|
||||
travel.
|
||||
01
|
||||
Brief
|
||||
Goal, owned files, dependencies, non-goals, acceptance.
|
||||
02
|
||||
Isolation
|
||||
One branch and worktree per independent change.
|
||||
03
|
||||
Evidence
|
||||
Commands, result, changed files, screenshots, gaps.
|
||||
Previous: models →
|
||||
Rules case study →
|
||||
Try the rules lab →
|
||||
@@ -1,303 +0,0 @@
|
||||
{
|
||||
"colors": [
|
||||
"#081621",
|
||||
"#0b1b27",
|
||||
"#0c1a25",
|
||||
"#0f2230",
|
||||
"#102536",
|
||||
"#102837",
|
||||
"#102b3a",
|
||||
"#112a3b",
|
||||
"#122534",
|
||||
"#123042",
|
||||
"#132b3b",
|
||||
"#172f42",
|
||||
"#173046",
|
||||
"#173245",
|
||||
"#173b4f",
|
||||
"#18364a",
|
||||
"#19364a",
|
||||
"#1a4b42",
|
||||
"#1c425a",
|
||||
"#1d455b",
|
||||
"#1f3a4b",
|
||||
"#215675",
|
||||
"#244760",
|
||||
"#29455a",
|
||||
"#2a4150",
|
||||
"#315f80",
|
||||
"#344c5d",
|
||||
"#41596b",
|
||||
"#426070",
|
||||
"#466274",
|
||||
"#486175",
|
||||
"#496274",
|
||||
"#527085",
|
||||
"#527f9f",
|
||||
"#557080",
|
||||
"#572f32",
|
||||
"#596f9a",
|
||||
"#5b7098",
|
||||
"#65717a",
|
||||
"#697b89",
|
||||
"#6b668f",
|
||||
"#6c6898",
|
||||
"#7c78a8",
|
||||
"#80c69a",
|
||||
"#80c69a20",
|
||||
"#80c69a22",
|
||||
"#8ca1af",
|
||||
"#91aab7",
|
||||
"#9ba7a5",
|
||||
"#9bcba7",
|
||||
"#9eabb4",
|
||||
"#9eb0bb",
|
||||
"#a7483f",
|
||||
"#a9b6be",
|
||||
"#a9bcc8",
|
||||
"#a9e3ae",
|
||||
"#aebbc3",
|
||||
"#aebfc7",
|
||||
"#aebfc9",
|
||||
"#afbec7",
|
||||
"#b0bac1",
|
||||
"#b5c0c7",
|
||||
"#b7c7d1",
|
||||
"#b8c8d2",
|
||||
"#b9c8d0",
|
||||
"#b9c8d1",
|
||||
"#bed0dc",
|
||||
"#bfccd4",
|
||||
"#c1d1d8",
|
||||
"#c4cdd3",
|
||||
"#c6d2d7",
|
||||
"#c9d5dc",
|
||||
"#cbd9e1",
|
||||
"#d0d5d2",
|
||||
"#d4dfe3",
|
||||
"#d5dde2",
|
||||
"#d5f1d6",
|
||||
"#d6e1e4",
|
||||
"#d8dee2",
|
||||
"#e5e3ef",
|
||||
"#e5eeeb",
|
||||
"#e89a8e",
|
||||
"#e8ecee",
|
||||
"#e9ecee",
|
||||
"#e9eeed",
|
||||
"#ebbf58",
|
||||
"#eceaf5",
|
||||
"#eceff0",
|
||||
"#edf0f1",
|
||||
"#eeedf6",
|
||||
"#efc76b",
|
||||
"#efc76b18",
|
||||
"#f0eef8",
|
||||
"#f1f0f7",
|
||||
"#f5f4f1",
|
||||
"#f6f3ed",
|
||||
"#ffb5a8",
|
||||
"#ffd7d0",
|
||||
"#fff",
|
||||
"#ffffff05",
|
||||
"#ffffff06",
|
||||
"#ffffff1f",
|
||||
"#ffffff2b",
|
||||
"#ffffff2d",
|
||||
"#ffffff30",
|
||||
"#ffffff32",
|
||||
"#ffffff40",
|
||||
"#ffffff42",
|
||||
"#ffffff50",
|
||||
"#ffffff66",
|
||||
"rgb(255 255 255 / 14.1176%)",
|
||||
"rgb(255 255 255 / 22.7451%)",
|
||||
"rgb(255 255 255 / 25.098%)",
|
||||
"rgb(255 255 255 / 31.3725%)"
|
||||
],
|
||||
"sizes": [
|
||||
"01em",
|
||||
"1em",
|
||||
"1px",
|
||||
"1.2em",
|
||||
"1.45em",
|
||||
"1.5em",
|
||||
"1.8em",
|
||||
"02em",
|
||||
"2px",
|
||||
"2.4vw",
|
||||
"2.5vw",
|
||||
"2.6vw",
|
||||
"3em",
|
||||
"3px",
|
||||
"3vw",
|
||||
"3.3vw",
|
||||
"3.4vw",
|
||||
"04em",
|
||||
"4px",
|
||||
"4vw",
|
||||
"05em",
|
||||
"5em",
|
||||
"5px",
|
||||
"5vw",
|
||||
"5.6vw",
|
||||
"06em",
|
||||
"6px",
|
||||
"6vw",
|
||||
"07em",
|
||||
"7px",
|
||||
"7vw",
|
||||
"08em",
|
||||
"8px",
|
||||
"8vw",
|
||||
"8.3vw",
|
||||
"09em",
|
||||
"9em",
|
||||
"9px",
|
||||
"9vw",
|
||||
"10px",
|
||||
"10.5px",
|
||||
"11px",
|
||||
"12em",
|
||||
"12px",
|
||||
"12vh",
|
||||
"13px",
|
||||
"14px",
|
||||
"15px",
|
||||
"16px",
|
||||
"17px",
|
||||
"17vw",
|
||||
"18px",
|
||||
"19px",
|
||||
"20px",
|
||||
"22px",
|
||||
"23px",
|
||||
"24px",
|
||||
"25px",
|
||||
"26px",
|
||||
"27px",
|
||||
"28px",
|
||||
"30px",
|
||||
"32px",
|
||||
"34px",
|
||||
"35em",
|
||||
"35px",
|
||||
"36px",
|
||||
"38px",
|
||||
"40px",
|
||||
"42px",
|
||||
"44px",
|
||||
"045em",
|
||||
"45px",
|
||||
"46px",
|
||||
"48px",
|
||||
"50px",
|
||||
"52px",
|
||||
"54px",
|
||||
"55px",
|
||||
"56px",
|
||||
"58px",
|
||||
"60px",
|
||||
"62px",
|
||||
"64px",
|
||||
"65px",
|
||||
"70px",
|
||||
"72px",
|
||||
"075em",
|
||||
"75px",
|
||||
"76px",
|
||||
"78px",
|
||||
"80px",
|
||||
"82px",
|
||||
"85px",
|
||||
"90px",
|
||||
"92px",
|
||||
"95px",
|
||||
"96px",
|
||||
"100px",
|
||||
"105px",
|
||||
"108px",
|
||||
"110px",
|
||||
"112px",
|
||||
"120px",
|
||||
"126px",
|
||||
"130px",
|
||||
"135px",
|
||||
"140px",
|
||||
"145px",
|
||||
"148px",
|
||||
"150px",
|
||||
"160px",
|
||||
"164px",
|
||||
"170px",
|
||||
"175px",
|
||||
"180px",
|
||||
"190px",
|
||||
"200px",
|
||||
"210px",
|
||||
"220px",
|
||||
"230px",
|
||||
"240px",
|
||||
"255px",
|
||||
"260px",
|
||||
"270px",
|
||||
"280px",
|
||||
"290px",
|
||||
"300px",
|
||||
"305px",
|
||||
"320px",
|
||||
"330px",
|
||||
"340px",
|
||||
"360px",
|
||||
"380px",
|
||||
"390px",
|
||||
"410px",
|
||||
"420px",
|
||||
"440px",
|
||||
"460px",
|
||||
"500px",
|
||||
"520px",
|
||||
"530px",
|
||||
"540px",
|
||||
"560px",
|
||||
"570px",
|
||||
"600px",
|
||||
"620px",
|
||||
"650px",
|
||||
"680px",
|
||||
"700px",
|
||||
"720px",
|
||||
"730px",
|
||||
"750px",
|
||||
"780px",
|
||||
"800px",
|
||||
"850px",
|
||||
"880px",
|
||||
"900px",
|
||||
"950px",
|
||||
"1000px",
|
||||
"1040px",
|
||||
"1050px",
|
||||
"1100px",
|
||||
"1400px",
|
||||
"1420px",
|
||||
"1500px",
|
||||
"1600px",
|
||||
"1840px",
|
||||
"1920px",
|
||||
"1960px",
|
||||
"2200px",
|
||||
"2880px"
|
||||
],
|
||||
"breakpoints": [
|
||||
"520px",
|
||||
"560px",
|
||||
"600px",
|
||||
"800px",
|
||||
"880px",
|
||||
"1050px",
|
||||
"1100px",
|
||||
"1600px",
|
||||
"2200px"
|
||||
]
|
||||
}
|
||||
@@ -1,104 +0,0 @@
|
||||
[
|
||||
"01 frota",
|
||||
"02 worktrees",
|
||||
"03 modelos",
|
||||
"04 skills",
|
||||
"05 criar",
|
||||
"06 kit de campo",
|
||||
"07 prática",
|
||||
"ENGENHARIA DE IA <i></i> 01 / 2026",
|
||||
"Uma apresentação para quem entrega software",
|
||||
"Você não precisa de um exército de modelos. Precisa de um sistema: uma mente para enquadrar o trabalho, várias mãos para executá-lo e uma fronteira clara entre cada tarefa.",
|
||||
"NOTA DE CAMPO / 001",
|
||||
"Entregue o<br /><em>sistema.</em>",
|
||||
"Skills · agentes · worktrees · evidências",
|
||||
"modelo forte<br />para ambiguidade",
|
||||
"workers delimitados<br />em paralelo",
|
||||
"iterações<br />com evidências",
|
||||
"Leia isto como um mapa de rota, não como uma receita de prompt.",
|
||||
"REGRA ZERO",
|
||||
"Modelo forte para ambiguidade.<br />Modelo leve para trabalho delimitado.",
|
||||
"Uma pequena frota",
|
||||
"coordenação antes do paralelismo",
|
||||
"ORQUESTRADOR",
|
||||
"Decide o que<br />precisa acontecer.",
|
||||
"Componentes e estados visuais",
|
||||
"Casos de aceitação",
|
||||
"Guia e exemplos",
|
||||
"O orquestrador preserva a intenção, escreve pequenos contratos e reúne resultados verificáveis. Ele não precisa digitar cada linha.",
|
||||
"Por que a fronteira importa",
|
||||
"uma tarefa vaga / três falhas previsíveis",
|
||||
"Sopa de contexto",
|
||||
"Cada worker lê tudo. Ninguém sabe quais fatos são essenciais.",
|
||||
"Colisão de branches",
|
||||
"Dois agentes usam o mesmo checkout. O caminho mais rápido vira resolução de conflitos.",
|
||||
"Desvio confiante",
|
||||
"O diff parece ótimo, mas ninguém verifica se resolveu o problema original.",
|
||||
"O ciclo de subagentes",
|
||||
"Clique em uma fase.<br /><em>Veja a passagem.</em>",
|
||||
"Delegar é mover uma tarefa delimitada para um contexto menor — não abrir mão da responsabilidade.",
|
||||
"O que atravessa contextos",
|
||||
"brief → diff → evidência",
|
||||
"Pacote",
|
||||
"Contém",
|
||||
"Por que importa",
|
||||
"Git worktrees",
|
||||
"Uma branch<br />por <em>mão.</em>",
|
||||
"Um worktree é outro diretório ligado ao mesmo repositório. Cada agente recebe seu próprio checkout e índice; o histórico continua compartilhado.",
|
||||
"Selecione um nó para inspecionar checkout, responsável e próxima ação.",
|
||||
"topologia do repositório",
|
||||
"<i></i> 4 checkouts",
|
||||
"RAIZ",
|
||||
"AGENTE DE UI",
|
||||
"AGENTE DE TESTES",
|
||||
"AGENTE DE DOCS",
|
||||
"● limpo",
|
||||
"3 arquivos · trabalhando",
|
||||
"8 verificações · pronto",
|
||||
"2 páginas · revisão",
|
||||
"Roteamento de modelos",
|
||||
"Não pague por<br />raciocínio onde precisa<br />de <em>ritmo.</em>",
|
||||
"Escolha um trabalho para entender por que o perfil do modelo muda.",
|
||||
"Trabalho",
|
||||
"Perfil",
|
||||
"Formato do prompt",
|
||||
"Planejar",
|
||||
"Construir",
|
||||
"Explorar",
|
||||
"Revisar",
|
||||
"Skills",
|
||||
"Escreva do jeito certo<br /><em>uma vez.</em>",
|
||||
"Uma skill é um procedimento reutilizável. Ela pode carregar instruções, referências, scripts e assets. Não é memória mágica e não substitui critérios de aceitação.",
|
||||
"01 / defina o gatilho",
|
||||
"02 / carregue detalhes sob demanda",
|
||||
"03 / devolva evidências",
|
||||
"PACOTE DE SKILL",
|
||||
"Skills comuns",
|
||||
"escolha o comportamento antes do modelo",
|
||||
"O kit de campo",
|
||||
"Trabalhos diferentes.<br />Instintos <em>diferentes.</em>",
|
||||
"Uma skill muda como o agente aborda o trabalho. Algumas moldam a comunicação. Outras impõem pesquisa, diagnóstico, revisão ou disciplina de conclusão. Selecione uma para inspecionar sua regra operacional.",
|
||||
"SIMPLIFICAR",
|
||||
"código mínimo que funciona",
|
||||
"COMUNICAR",
|
||||
"sinal sem excesso",
|
||||
"CONCLUIR",
|
||||
"gates e evidências",
|
||||
"INVESTIGAR",
|
||||
"fontes primárias primeiro",
|
||||
"DIAGNOSTICAR",
|
||||
"ciclo curto de feedback",
|
||||
"REVISAR",
|
||||
"padrões × especificação",
|
||||
"ECONOMIZAR",
|
||||
"comprima saídas ruidosas",
|
||||
"UM LOADOUT PRÁTICO",
|
||||
"<b>PLANEJAR</b> unlazy <i>→</i> <b>CONSTRUIR</b> ponytail-lite <i>→</i> <b>DIAGNOSTICAR</b> diagnosing-bugs <i>→</i> <b>REPORTAR</b> caveman",
|
||||
"O PAPEL HUMANO",
|
||||
"O agente pode ser autônomo na execução. Intenção, limites e evidências continuam sendo seus.",
|
||||
"COMECE AQUI",
|
||||
"Comece com um agente e uma skill. Adicione paralelismo apenas quando as tarefas forem realmente independentes.",
|
||||
"Continue aprendendo",
|
||||
"12 novas leituras + documentação primária",
|
||||
"Aprofunde com documentação oficial, casos de produção, Medium e fluxos de praticantes. <a href=\"rules/\">Estudo de caso sobre regras e enforcement →</a> <a href=\"docs/references/README.md\">Referências primárias →</a> <a href=\"docs/references/additional-reading.md\">Trilha com 12 leituras →</a>"
|
||||
]
|
||||
@@ -1,754 +0,0 @@
|
||||
AI For Dummies — Field Guide
|
||||
A
|
||||
field guide
|
||||
01 fleet
|
||||
01 frota
|
||||
02 worktrees
|
||||
02 worktrees
|
||||
03 models
|
||||
03 modelos
|
||||
04 skills
|
||||
04 skills
|
||||
05 create
|
||||
05 criar
|
||||
06 field kit
|
||||
06 kit de campo
|
||||
07 hands-on
|
||||
07 prática
|
||||
08 verify
|
||||
review submissions ↗
|
||||
EN
|
||||
/
|
||||
PT
|
||||
AI ENGINEERING
|
||||
01 / 2026
|
||||
ENGENHARIA DE IA
|
||||
01 / 2026
|
||||
A presentation for humans who ship
|
||||
Uma apresentação para quem entrega software
|
||||
AI for
|
||||
dummies.
|
||||
You do not need an army of models. You need a system: one mind to frame the work,
|
||||
several hands to execute it, and a clean boundary between every task.
|
||||
Você não precisa de um exército de modelos. Precisa de um sistema: uma mente para
|
||||
enquadrar o trabalho, várias mãos para executá-lo e uma fronteira clara entre cada
|
||||
tarefa.
|
||||
FIELD NOTE / 001
|
||||
NOTA DE CAMPO / 001
|
||||
Ship the
|
||||
system.
|
||||
Entregue o
|
||||
sistema.
|
||||
Skills · agents · worktrees · proof
|
||||
Skills · agentes · worktrees · evidências
|
||||
Uma apresentação para quem entrega software
|
||||
AI for
|
||||
dummies.
|
||||
Você não precisa de um exército de modelos. Precisa de um sistema: uma mente para
|
||||
enquadrar o trabalho, várias mãos para executá-lo e uma fronteira clara entre cada tarefa.
|
||||
NOTA DE CAMPO / 001
|
||||
Entregue o
|
||||
sistema.
|
||||
Skills · agentes · worktrees · evidências
|
||||
01
|
||||
strong model
|
||||
for ambiguity
|
||||
modelo forte
|
||||
para ambiguidade
|
||||
03
|
||||
bounded workers
|
||||
in parallel
|
||||
workers delimitados
|
||||
em paralelo
|
||||
∞
|
||||
iterations
|
||||
with evidence
|
||||
iterações
|
||||
com evidências
|
||||
Read this as a route map, not a prompt recipe.
|
||||
Leia isto como um mapa de rota, não como uma receita de prompt.
|
||||
01
|
||||
modelo forte
|
||||
para ambiguidade
|
||||
03
|
||||
workers delimitados
|
||||
em paralelo
|
||||
∞
|
||||
iterações
|
||||
com evidências
|
||||
Leia isto como um mapa de rota, não como uma receita de prompt.
|
||||
RULE ZERO
|
||||
REGRA ZERO
|
||||
Strong model for ambiguity.
|
||||
Light model for bounded work.
|
||||
Modelo forte para ambiguidade.
|
||||
Modelo leve para trabalho delimitado.
|
||||
THINK
|
||||
MAKE
|
||||
REGRA ZERO
|
||||
Modelo forte para ambiguidade.
|
||||
Modelo leve para trabalho delimitado.
|
||||
THINK
|
||||
MAKE
|
||||
A small fleet
|
||||
Uma pequena frota
|
||||
coordination before parallelism
|
||||
coordenação antes do paralelismo
|
||||
ORCHESTRATOR
|
||||
ORQUESTRADOR
|
||||
Decides what
|
||||
needs to happen.
|
||||
Decide o que
|
||||
precisa acontecer.
|
||||
Opus / reasoning
|
||||
→
|
||||
UI
|
||||
Component and visual states
|
||||
Componentes e estados visuais
|
||||
agent/ui
|
||||
TEST
|
||||
Acceptance cases
|
||||
Casos de aceitação
|
||||
agent/tests
|
||||
DOCS
|
||||
Guide and examples
|
||||
Guia e exemplos
|
||||
agent/docs
|
||||
Interface worker
|
||||
Receives: component contract + visual states
|
||||
Returns: focused diff + viewport evidence
|
||||
The orchestrator preserves intent, writes small contracts, and gathers results that can
|
||||
be verified. It does not need to type every line.
|
||||
O orquestrador preserva a intenção, escreve pequenos contratos e reúne resultados
|
||||
verificáveis. Ele não precisa digitar cada linha.
|
||||
Why the boundary matters
|
||||
Por que a fronteira importa
|
||||
one vague task / three predictable failures
|
||||
uma tarefa vaga / três falhas previsíveis
|
||||
01
|
||||
Context soup
|
||||
Sopa de contexto
|
||||
Every worker reads everything. Nobody knows which facts are load-bearing.
|
||||
Cada worker lê tudo. Ninguém sabe quais fatos são essenciais.
|
||||
02
|
||||
Branch collision
|
||||
Colisão de branches
|
||||
Two agents touch the same checkout. The fastest path becomes conflict resolution.
|
||||
Dois agentes usam o mesmo checkout. O caminho mais rápido vira resolução de
|
||||
conflitos.
|
||||
03
|
||||
Confident drift
|
||||
Desvio confiante
|
||||
The diff is polished, but no one checks whether it solved the original problem.
|
||||
O diff parece ótimo, mas ninguém verifica se resolveu o problema original.
|
||||
The subagent loop
|
||||
O ciclo de subagentes
|
||||
Click a phase.
|
||||
See the handoff.
|
||||
Clique em uma fase.
|
||||
Veja a passagem.
|
||||
Delegation means moving one bounded task into a smaller context—not giving away
|
||||
responsibility.
|
||||
Delegar é mover uma tarefa delimitada para um contexto menor — não abrir mão da
|
||||
responsabilidade.
|
||||
01
|
||||
PLAN
|
||||
02
|
||||
BUILD
|
||||
03
|
||||
REVIEW
|
||||
OPUS / REASONING
|
||||
context: isolated
|
||||
Turn ambiguity into work
|
||||
Inspect the repository, choose the architecture, split the request, and write acceptance criteria.
|
||||
plan → decompose → define acceptance
|
||||
What crosses contexts
|
||||
O que atravessa contextos
|
||||
brief → diff → evidence
|
||||
brief → diff → evidência
|
||||
Package
|
||||
Pacote
|
||||
Contains
|
||||
Contém
|
||||
Why it matters
|
||||
Por que importa
|
||||
Brief
|
||||
goal, files, boundaries
|
||||
stops the worker inventing the problem
|
||||
Worktree
|
||||
branch and isolated checkout
|
||||
parallel edits do not collide
|
||||
Checks
|
||||
tests, build, criteria
|
||||
turns “looks good” into evidence
|
||||
Diff
|
||||
small, reviewable change
|
||||
integration and discard stay cheap
|
||||
Git worktrees
|
||||
Git worktrees
|
||||
One branch
|
||||
per
|
||||
hand.
|
||||
Uma branch
|
||||
por
|
||||
mão.
|
||||
A worktree is another directory linked to the same repository. Each agent gets its own
|
||||
checkout and index; history remains shared.
|
||||
Um worktree é outro diretório ligado ao mesmo repositório. Cada agente recebe seu
|
||||
próprio checkout e índice; o histórico continua compartilhado.
|
||||
Select a node to inspect its checkout, owner, and next action.
|
||||
Selecione um nó para inspecionar checkout, responsável e próxima ação.
|
||||
repository topology
|
||||
topologia do repositório
|
||||
4 checkouts
|
||||
4 checkouts
|
||||
ROOT
|
||||
RAIZ
|
||||
main
|
||||
● clean
|
||||
● limpo
|
||||
UI AGENT
|
||||
AGENTE DE UI
|
||||
agent/ui
|
||||
3 files · working
|
||||
3 arquivos · trabalhando
|
||||
TEST AGENT
|
||||
AGENTE DE TESTES
|
||||
agent/tests
|
||||
8 checks · ready
|
||||
8 verificações · pronto
|
||||
DOCS AGENT
|
||||
AGENTE DE DOCS
|
||||
agent/docs
|
||||
2 pages · review
|
||||
2 páginas · revisão
|
||||
OWNER
|
||||
Orchestrator
|
||||
CHECKOUT
|
||||
./project
|
||||
Shared history and integration point. Workers never edit here.
|
||||
git worktree list
|
||||
Model routing
|
||||
Roteamento de modelos
|
||||
Do not pay for
|
||||
reasoning where
|
||||
you need
|
||||
rhythm.
|
||||
Não pague por
|
||||
raciocínio onde precisa
|
||||
de
|
||||
ritmo.
|
||||
Choose a job to see why the model profile changes.
|
||||
Escolha um trabalho para entender por que o perfil do modelo muda.
|
||||
Work
|
||||
Trabalho
|
||||
Profile
|
||||
Perfil
|
||||
Prompt shape
|
||||
Formato do prompt
|
||||
Plan
|
||||
Planejar
|
||||
strong / broad
|
||||
What changes? What can break?
|
||||
Build
|
||||
Construir
|
||||
fast / focused
|
||||
Implement this slice. Run these checks.
|
||||
Explore
|
||||
Explorar
|
||||
read-only / light
|
||||
Find where this contract is used.
|
||||
Review
|
||||
Revisar
|
||||
independent
|
||||
Does the diff satisfy the brief?
|
||||
REASONING LOAD · 92
|
||||
High ambiguity
|
||||
Architecture and decomposition have a wide error surface. Spend reasoning here.
|
||||
Model gearbox
|
||||
Câmbio de modelos
|
||||
capability tier × thinking effort
|
||||
nível de capacidade × esforço de raciocínio
|
||||
Two separate knobs
|
||||
Dois controles separados
|
||||
Choose the engine.
|
||||
Then choose the
|
||||
gear.
|
||||
Escolha o motor.
|
||||
Depois escolha a
|
||||
marcha.
|
||||
A stronger model changes the capability ceiling. Higher reasoning effort gives that
|
||||
model more room to work. Start with the lightest combination that passes your real
|
||||
checks, then move one knob at a time.
|
||||
Um modelo mais forte muda o teto de capacidade. Mais esforço de raciocínio dá mais
|
||||
espaço para esse modelo trabalhar. Comece com a combinação mais leve que passa seus
|
||||
checks e mova um controle por vez.
|
||||
OPENAI
|
||||
CLAUDE
|
||||
GEMINI
|
||||
OpenAI
|
||||
OFFICIAL SOURCE ↗
|
||||
Sol · Terra · Luna
|
||||
GPT-5.6 separates capability tier from reasoning effort. Sol is flagship, Terra balances performance and cost, and Luna targets efficient high-volume work.
|
||||
REASONING / THINKING
|
||||
RACIOCÍNIO / PENSAMENTO
|
||||
LOW
|
||||
BAIXO
|
||||
bounded + fast
|
||||
delimitado + rápido
|
||||
MEDIUM
|
||||
MÉDIO
|
||||
default start
|
||||
ponto inicial
|
||||
HIGH
|
||||
ALTO
|
||||
complex + costly
|
||||
complexo + custoso
|
||||
MEDIUM
|
||||
Balanced starting point for normal implementation, tests, and review. Measure before moving up.
|
||||
reasoning: { effort: "medium" }
|
||||
ROUTING RULE
|
||||
REGRA DE ROTEAMENTO
|
||||
Use strong models for ambiguity and judgment. Use lighter models for bounded execution.
|
||||
Raise effort only when evaluation shows a gain.
|
||||
Use modelos fortes para ambiguidade e julgamento. Use modelos leves para execução
|
||||
delimitada. Aumente o esforço apenas quando a avaliação mostrar ganho.
|
||||
Skills
|
||||
Uma skill é um procedimento reutilizável. Ela pode carregar instruções, referências,
|
||||
scripts e assets. Não é memória mágica e não substitui critérios de aceitação.
|
||||
Write the right way
|
||||
once.
|
||||
Escreva do jeito certo
|
||||
uma vez.
|
||||
A skill is a reusable procedure. It can carry instructions, references, scripts, and
|
||||
assets. It is not magical memory, and it does not replace acceptance criteria.
|
||||
Uma skill é um procedimento reutilizável. Ela pode carregar instruções, referências,
|
||||
scripts e assets. Não é memória mágica e não substitui critérios de aceitação.
|
||||
01 / trigger clearly
|
||||
01 / defina o gatilho
|
||||
02 / load detail on demand
|
||||
02 / carregue detalhes sob demanda
|
||||
03 / return evidence
|
||||
03 / devolva evidências
|
||||
SKILL PACKAGE
|
||||
PACOTE DE SKILL
|
||||
SKILL.md
|
||||
procedure and limits
|
||||
references/
|
||||
facts to consult
|
||||
scripts/
|
||||
repeatable checks
|
||||
assets/
|
||||
templates and examples
|
||||
◇
|
||||
SKILL.md
|
||||
Trigger, procedure, constraints, and the exact evidence the agent must return.
|
||||
select another file to explore
|
||||
name: review-ui · check focus, mobile, reduced motion · run verification · return evidence
|
||||
Create a skill
|
||||
Criar uma skill
|
||||
repeatable pain → reusable judgment
|
||||
atrito repetido → julgamento reutilizável
|
||||
The skill forge
|
||||
A forja de skills
|
||||
Teach the decision.
|
||||
Keep the context
|
||||
light.
|
||||
Ensine a decisão.
|
||||
Mantenha o contexto
|
||||
leve.
|
||||
Do not package everything you know. Capture the non-obvious choices that repeatedly
|
||||
improve an outcome, then prove the skill changes behavior.
|
||||
Não empacote tudo o que você sabe. Capture as escolhas não óbvias que melhoram
|
||||
resultados repetidamente e prove que a skill muda o comportamento.
|
||||
01
|
||||
Observe
|
||||
Observar
|
||||
find repeated friction
|
||||
encontre atrito repetido
|
||||
02
|
||||
Define trigger
|
||||
Definir gatilho
|
||||
route precisely
|
||||
roteie com precisão
|
||||
03
|
||||
Choose anatomy
|
||||
Escolher anatomia
|
||||
only needed files
|
||||
apenas arquivos necessários
|
||||
04
|
||||
Write guidance
|
||||
Escrever orientação
|
||||
decisions, not trivia
|
||||
decisões, não trivialidades
|
||||
05
|
||||
Validate
|
||||
Validar
|
||||
test real behavior
|
||||
teste comportamento real
|
||||
01
|
||||
QUESTION
|
||||
Start from repeated friction
|
||||
Which non-obvious decision keeps being rediscovered?
|
||||
ACTION
|
||||
Collect two or three realistic requests. Separate durable judgment from one project’s temporary details.
|
||||
ARTIFACT
|
||||
A narrow capability and concrete examples.
|
||||
PROOF
|
||||
Without the skill, agents repeatedly make the same avoidable mistake.
|
||||
OUTPUT / SKILL PACKAGE
|
||||
SAÍDA / PACOTE DE SKILL
|
||||
review-ui/
|
||||
├── SKILL.md
|
||||
├── agents/
|
||||
│ └── openai.yaml
|
||||
├── references/
|
||||
│ └── accessibility.md
|
||||
└── scripts/
|
||||
└── verify.mjs
|
||||
VALIDATE
|
||||
VALIDAR
|
||||
quick_validate.py ./review-ui
|
||||
AFTER REAL USE
|
||||
APÓS USO REAL
|
||||
observe failure
|
||||
→
|
||||
sharpen one rule
|
||||
→
|
||||
retest behavior
|
||||
→
|
||||
keep it narrow
|
||||
observar falha
|
||||
→
|
||||
refinar uma regra
|
||||
→
|
||||
retestar comportamento
|
||||
→
|
||||
manter estreita
|
||||
Common skills
|
||||
Skills comuns
|
||||
choose behavior before model
|
||||
escolha o comportamento antes do modelo
|
||||
The field kit
|
||||
O kit de campo
|
||||
Different jobs.
|
||||
Different
|
||||
instincts.
|
||||
Trabalhos diferentes.
|
||||
Instintos
|
||||
diferentes.
|
||||
A skill changes how an agent approaches work. Some shape communication. Others enforce
|
||||
research, debugging, review, or completion discipline. Select one to inspect its
|
||||
operating rule and verified source.
|
||||
Uma skill muda como o agente aborda o trabalho. Algumas moldam a comunicação. Outras
|
||||
impõem pesquisa, diagnóstico, revisão ou disciplina de conclusão. Selecione uma para
|
||||
inspecionar sua regra operacional.
|
||||
SIMPLIFY
|
||||
SIMPLIFICAR
|
||||
ponytail-lite
|
||||
minimum code that holds
|
||||
código mínimo que funciona
|
||||
COMMUNICATE
|
||||
COMUNICAR
|
||||
caveman
|
||||
signal without filler
|
||||
sinal sem excesso
|
||||
COMPLETE
|
||||
CONCLUIR
|
||||
unlazy
|
||||
gates and evidence
|
||||
gates e evidências
|
||||
INVESTIGATE
|
||||
INVESTIGAR
|
||||
research
|
||||
primary sources first
|
||||
fontes primárias primeiro
|
||||
DIAGNOSE
|
||||
DIAGNOSTICAR
|
||||
diagnosing-bugs
|
||||
tight feedback loop
|
||||
ciclo curto de feedback
|
||||
REVIEW
|
||||
REVISAR
|
||||
code-review
|
||||
standards × spec
|
||||
padrões × especificação
|
||||
ECONOMIZE
|
||||
ECONOMIZAR
|
||||
token-saver
|
||||
compress noisy output
|
||||
comprima saídas ruidosas
|
||||
01
|
||||
SIMPLIFICATION INSTINCT
|
||||
ponytail-lite
|
||||
Stop at the first rung that holds.
|
||||
WHEN TO USE
|
||||
Use when a request invites frameworks, dependencies, abstractions, or speculative scaffolding. It checks reuse, standard library, and native platform features before adding code.
|
||||
EXAMPLE
|
||||
Date picker? Start with <input type="date">.
|
||||
WATCH OUT
|
||||
Never simplify away security, accessibility, validation, or real edge cases.
|
||||
GITHUB SOURCE ↗
|
||||
ONE PRACTICAL LOADOUT
|
||||
UM LOADOUT PRÁTICO
|
||||
PLAN
|
||||
unlazy
|
||||
→
|
||||
BUILD
|
||||
ponytail-lite
|
||||
→
|
||||
DEBUG
|
||||
diagnosing-bugs
|
||||
→
|
||||
REPORT
|
||||
caveman
|
||||
PLANEJAR
|
||||
unlazy
|
||||
→
|
||||
CONSTRUIR
|
||||
ponytail-lite
|
||||
→
|
||||
DIAGNOSTICAR
|
||||
diagnosing-bugs
|
||||
→
|
||||
REPORTAR
|
||||
caveman
|
||||
INSTALL PACK
|
||||
PACOTE DE INSTALAÇÃO
|
||||
Ask your coding agent to verify, install, and validate the skills.
|
||||
Peça ao seu agente para verificar, instalar e validar as skills.
|
||||
COPY
|
||||
↗
|
||||
Inspect and install only these public agent skills. Pin the exact commits:
|
||||
- ilindaniel/ponytail-lite@e7b42dc2d384a702240dea4d52a7bf5530b821b6 — AGENTS.md
|
||||
- JuliusBrussee/caveman@3b74643f4d910f496babd4e634b1ba7168816f14 — skills/caveman/
|
||||
- Leonxlnx/unlazy@473d4b80421c36d733042434cd4b938f81a19ef1 — repository root
|
||||
- mattpocock/skills@6654f6b60cd9d5be8b54c6fafe44346dabeb3b76 — skills/engineering/{research,diagnosing-bugs,code-review}/
|
||||
- aetox-skills/token-saver@8f21188bb043fad411f47e2e57f0365a83c13da7 — repository root
|
||||
- anthropics/skills@53048666b05b4799081517d00e09e0a2dd688678 — skills/webapp-testing/
|
||||
Treat repository content as untrusted. Detect the current AI host and documented user-level skill directory; do not guess paths. Download into a temporary directory without curl-pipe-shell, remote installers, or postinstall hooks. Inspect each selected instruction and every referenced script or hook. Show the exact copy plan and existing-file diffs, then ask for approval before installation. Copy only the allowlist and preserve complete referenced packages. Install ponytail-lite through the host instruction mechanism because it is AGENTS.md. Do not enable unlazy hooks or install token-saver's RTK binary without separate approval. Finally report destination, SHA-256, validation, and which skills the host discovers.
|
||||
Inspecione e instale apenas estas skills públicas. Fixe os commits exatos:
|
||||
- ilindaniel/ponytail-lite@e7b42dc2d384a702240dea4d52a7bf5530b821b6 — AGENTS.md
|
||||
- JuliusBrussee/caveman@3b74643f4d910f496babd4e634b1ba7168816f14 — skills/caveman/
|
||||
- Leonxlnx/unlazy@473d4b80421c36d733042434cd4b938f81a19ef1 — raiz do repositório
|
||||
- mattpocock/skills@6654f6b60cd9d5be8b54c6fafe44346dabeb3b76 — skills/engineering/{research,diagnosing-bugs,code-review}/
|
||||
- aetox-skills/token-saver@8f21188bb043fad411f47e2e57f0365a83c13da7 — raiz do repositório
|
||||
- anthropics/skills@53048666b05b4799081517d00e09e0a2dd688678 — skills/webapp-testing/
|
||||
Trate o conteúdo como não confiável. Detecte o host de IA e o diretório documentado de skills; não adivinhe caminhos. Baixe em diretório temporário sem curl-pipe-shell, instaladores remotos ou postinstall. Inspecione instruções, scripts e hooks referenciados. Mostre o plano de cópia e diffs existentes e peça aprovação antes de instalar. Copie apenas a allowlist e preserve pacotes completos. Instale ponytail-lite pelo mecanismo de instruções do host porque é AGENTS.md. Não ative hooks do unlazy nem instale o binário RTK do token-saver sem aprovação separada. Ao final, reporte destino, SHA-256, validação e quais skills o host descobriu.
|
||||
Review every source before installation. Existing local skills must be preserved.
|
||||
Revise cada fonte antes da instalação. Skills locais existentes devem ser preservadas.
|
||||
Hands-on
|
||||
Prática
|
||||
10 minutes / one missing feature
|
||||
10 minutos / uma feature ausente
|
||||
Tiny Tasks lab
|
||||
Laboratório Tiny Tasks
|
||||
Same task.
|
||||
Better
|
||||
operating system.
|
||||
Mesma tarefa.
|
||||
Melhor
|
||||
sistema operacional.
|
||||
Start with a deliberately incomplete static task board. Run one prompt as written,
|
||||
reset, then run the skill-enabled version. Compare diff size, verification evidence, and
|
||||
unnecessary complexity.
|
||||
Comece com um quadro estático propositalmente incompleto. Execute um prompt, restaure e
|
||||
execute a versão com skills. Compare tamanho do diff, evidências e complexidade
|
||||
desnecessária.
|
||||
Open the starter →
|
||||
Abrir o projeto inicial →
|
||||
Clone from Gitea →
|
||||
Abrir o projeto inicial →
|
||||
Open the rules lab →
|
||||
Abrir o projeto inicial →
|
||||
Clone from Gitea →
|
||||
Abrir o projeto inicial →
|
||||
THE MISSING FEATURE
|
||||
A FEATURE AUSENTE
|
||||
Add All / Open / Done filters that survive reload and browser navigation.
|
||||
Adicione filtros Todos / Abertos / Concluídos que sobrevivem reload e navegação.
|
||||
STACK
|
||||
HTML · CSS · JavaScript
|
||||
DEPENDENCIES
|
||||
none
|
||||
FILES
|
||||
3
|
||||
STACK
|
||||
HTML · CSS · JavaScript
|
||||
DEPENDÊNCIAS
|
||||
nenhuma
|
||||
ARQUIVOS
|
||||
3
|
||||
RUN A
|
||||
Good prompt
|
||||
Bom prompt
|
||||
COPY
|
||||
↗
|
||||
Work only in hands-on/starter. It is dependency-free HTML, CSS, and JavaScript.
|
||||
Add an All / Open / Done filter to Tiny Tasks.
|
||||
Requirements:
|
||||
- derive counts and visible tasks from the existing tasks array
|
||||
- expose filter buttons with a visible active state and aria-pressed
|
||||
- store status in ?status=all|open|done
|
||||
- reload and browser back/forward must restore the selected filter
|
||||
- show a useful empty state when no task matches
|
||||
- preserve the visual style and mobile layout
|
||||
- add no dependencies and change no unrelated files
|
||||
Verify app.js syntax and exercise every filter plus URL navigation.
|
||||
Return changed files, checks run, results, and remaining risk.
|
||||
Trabalhe apenas em hands-on/starter. É HTML, CSS e JavaScript sem dependências.
|
||||
Adicione um filtro Todos / Abertos / Concluídos ao Tiny Tasks.
|
||||
Requisitos:
|
||||
- derive contagens e tarefas visíveis do array tasks existente
|
||||
- use botões com estado ativo visível e aria-pressed
|
||||
- salve o status em ?status=all|open|done
|
||||
- reload e voltar/avançar devem restaurar o filtro
|
||||
- mostre estado vazio quando nenhuma tarefa corresponder
|
||||
- preserve o visual e layout mobile
|
||||
- não adicione dependências nem altere arquivos não relacionados
|
||||
Verifique a sintaxe de app.js e teste filtros e navegação por URL.
|
||||
Retorne arquivos alterados, checks, resultados e risco restante.
|
||||
Clear context · constraints · acceptance · evidence
|
||||
Contexto claro · restrições · aceitação · evidência
|
||||
RUN B
|
||||
Good prompt + skills
|
||||
Bom prompt + skills
|
||||
COPY
|
||||
↗
|
||||
Use $ponytail-lite and $webapp-testing.
|
||||
Work only in hands-on/starter. It is dependency-free HTML, CSS, and JavaScript.
|
||||
Add an All / Open / Done filter to Tiny Tasks.
|
||||
Apply $ponytail-lite: inspect first, reuse the current render flow, prefer native URL and button APIs, and avoid dependencies or abstractions.
|
||||
Apply $webapp-testing: verify all filters, aria-pressed, reload, browser back/forward, empty state, and one mobile viewport.
|
||||
Acceptance:
|
||||
- counts and visible tasks come from the existing tasks array
|
||||
- ?status=all|open|done is the source of truth
|
||||
- invalid status falls back safely to all
|
||||
- style remains consistent; unrelated files remain untouched
|
||||
Return the smallest working diff and concrete verification evidence.
|
||||
Use $ponytail-lite e $webapp-testing.
|
||||
Trabalhe apenas em hands-on/starter. É HTML, CSS e JavaScript sem dependências.
|
||||
Adicione um filtro Todos / Abertos / Concluídos ao Tiny Tasks.
|
||||
Aplique $ponytail-lite: inspecione primeiro, reutilize o render atual, prefira APIs nativas de URL e button e evite dependências ou abstrações.
|
||||
Aplique $webapp-testing: verifique filtros, aria-pressed, reload, voltar/avançar, estado vazio e um viewport mobile.
|
||||
Aceitação:
|
||||
- contagens e tarefas visíveis vêm do array tasks existente
|
||||
- ?status=all|open|done é a fonte de verdade
|
||||
- status inválido volta com segurança para all
|
||||
- estilo consistente; nenhum arquivo não relacionado alterado
|
||||
Retorne o menor diff funcional e evidências concretas de verificação.
|
||||
Same contract · explicit working methods · stronger proof
|
||||
Mesmo contrato · métodos explícitos · prova mais forte
|
||||
COMPARE THE RUNS
|
||||
COMPARE AS EXECUÇÕES
|
||||
01
|
||||
Files changed
|
||||
Arquivos alterados
|
||||
02
|
||||
New dependencies
|
||||
Novas dependências
|
||||
03
|
||||
Checks actually run
|
||||
Checks executados
|
||||
04
|
||||
Evidence returned
|
||||
Evidências retornadas
|
||||
THE HUMAN JOB
|
||||
O PAPEL HUMANO
|
||||
The agent may be autonomous in execution. Intent, boundaries, and evidence remain yours.
|
||||
O agente pode ser autônomo na execução. Intenção, limites e evidências continuam sendo
|
||||
seus.
|
||||
START HERE
|
||||
COMECE AQUI
|
||||
Begin with one agent and one skill. Add parallelism only when the tasks are truly
|
||||
independent.
|
||||
Comece com um agente e uma skill. Adicione paralelismo apenas quando as tarefas forem
|
||||
realmente independentes.
|
||||
Verification
|
||||
run each gate separately
|
||||
Checks become evidence
|
||||
Three layers.
|
||||
Run each one alone.
|
||||
Run a gate on its own line, print its exit code, attach the output. The result is the
|
||||
deliverable.
|
||||
01 · STATIC
|
||||
Lint and types
|
||||
Format, lint, type-check. Fast and scoped to one file. Run on every save.
|
||||
pnpm lint; echo "lint=$?" pnpm typecheck; echo "typecheck=$?"
|
||||
02 · BEHAVIOR
|
||||
Unit and contract
|
||||
Tests that repeat. Run before claiming done.
|
||||
pnpm test; echo "test=$?" cd services/api && go test ./...
|
||||
03 · INTEGRATION
|
||||
Real UI and API
|
||||
Drive the actual UI, API, or browser. Slower and flakier — only this catches mobile
|
||||
overflow and a missing 404.
|
||||
pnpm check:ui; echo "ui=$?" TURBO_FORCE=true pnpm e2e
|
||||
FOUR WAYS A GREEN REPORT IS FALSE
|
||||
1
|
||||
Pipe a gate
|
||||
tail, grep, or head hide the real exit code — a pipeline returns the last command's
|
||||
status.
|
||||
2
|
||||
Swallow a rejection
|
||||
A silent
|
||||
.catch(() => {})
|
||||
hides a panic, an upstream limit, or a partial
|
||||
failure.
|
||||
3
|
||||
Trust the cache
|
||||
Turbo caches results. A gate that "passes" may not have run — use
|
||||
TURBO_FORCE=true
|
||||
.
|
||||
4
|
||||
Skip the third layer
|
||||
Lint and unit can both be green while the page breaks on mobile and the API never
|
||||
returns 404.
|
||||
RUN IT YOURSELF · two labs, under 10 minutes each
|
||||
Path A · verification lab
|
||||
Fill the four-row comparison strip on the starter. Run A naively, Run B with
|
||||
$gate-discipline
|
||||
and
|
||||
$webapp-testing
|
||||
.
|
||||
Open the starter →
|
||||
Clone ↗
|
||||
git.marcospaulo.dev.br/.../src/branch/pages/hands-on/starter
|
||||
Path B · rules lab
|
||||
Toggle every rule off, run the prompt. Toggle every rule on, run it again. Compare
|
||||
diff size, gate invocations, and the names of checks the agent names back.
|
||||
Open the rules lab →
|
||||
Open the rules lab →
|
||||
Clone ↗
|
||||
git.marcospaulo.dev.br/.../src/branch/pages/hands-on/rules
|
||||
Keep learning
|
||||
Continue aprendendo
|
||||
12 new readings + primary docs
|
||||
12 novas leituras + documentação primária
|
||||
Go deeper with official documentation, production case studies, Medium, and practitioner
|
||||
workflows.
|
||||
Rules and enforcement case study →
|
||||
Skills review desk →
|
||||
Primary references →
|
||||
12-part reading path →
|
||||
Aprofunde com documentação oficial, casos de produção, Medium e fluxos de praticantes.
|
||||
Estudo de caso sobre regras e enforcement →
|
||||
Referências primárias →
|
||||
Trilha com 12 leituras →
|
||||
Navigate by idea
|
||||
short chapters / one system
|
||||
Prefer a focused chapter? Start with the
|
||||
route map
|
||||
, then
|
||||
jump directly to
|
||||
models
|
||||
,
|
||||
agents and worktrees
|
||||
,
|
||||
skill creation
|
||||
,
|
||||
rules
|
||||
, or
|
||||
the
|
||||
skills review desk
|
||||
.
|
||||
@@ -1,14 +0,0 @@
|
||||
Guardrails — Hands-on Rules
|
||||
HANDS-ON / RULES
|
||||
Guardrails
|
||||
Toggle rules. Same task, different coverage.
|
||||
Rule sources
|
||||
0 / 5 active
|
||||
Prompt diff
|
||||
EN
|
||||
PT
|
||||
NAIVE
|
||||
Plain prompt
|
||||
RULED
|
||||
With guardrails
|
||||
Copy ruled prompt
|
||||
@@ -1,5 +0,0 @@
|
||||
Tiny Tasks — Hands-on Starter
|
||||
HANDS-ON / STARTER
|
||||
Tiny Tasks
|
||||
Three tasks. One missing filter.
|
||||
Today
|
||||
@@ -1,37 +0,0 @@
|
||||
AI For Dummies — Start here
|
||||
AI FOR DUMMIES
|
||||
00 / START HERE
|
||||
review desk ↗
|
||||
The short route
|
||||
Ship the
|
||||
system.
|
||||
Start with the map. Then open the one chapter that matches the decision in front of you: model, agent, worktree, skill, rule, or proof.
|
||||
Take the full field guide
|
||||
→
|
||||
01
|
||||
Models
|
||||
Capability and effort are separate knobs.
|
||||
Open chapter →
|
||||
02
|
||||
Agents & trees
|
||||
Bound roles, handoffs, and worktrees.
|
||||
Open chapter →
|
||||
03
|
||||
Skills
|
||||
Capture repeatable decisions in small packages.
|
||||
Open chapter →
|
||||
04
|
||||
Rules
|
||||
Connect guidance to enforcement.
|
||||
Open chapter →
|
||||
05
|
||||
Hands-on
|
||||
Compare a strong prompt with skill-enabled work.
|
||||
Open lab →
|
||||
06
|
||||
Review desk
|
||||
Browse original packages, references, scripts, and improvements.
|
||||
Open desk →
|
||||
THE THREAD
|
||||
Frame uncertainty → isolate execution → preserve judgment → verify the change.
|
||||
The route map is now the default entry. The full guide remains available whenever you want the whole narrative.
|
||||
@@ -1,37 +0,0 @@
|
||||
AI For Dummies — Models
|
||||
← ROUTE MAP
|
||||
01 / MODELS
|
||||
field guide ↗
|
||||
Model routing
|
||||
Choose the
|
||||
engine.
|
||||
A model has a capability ceiling. Effort controls how much room it gets to reason. Route by uncertainty and verification cost.
|
||||
LOW
|
||||
Bounded rhythm
|
||||
Lookup, small edits, formatting, and transformations with clear checks.
|
||||
MEDIUM
|
||||
Default work
|
||||
Normal implementation where the contract is clear but context matters.
|
||||
HIGH
|
||||
Ambiguity
|
||||
Planning, architecture, security judgment, and hard failures.
|
||||
Two knobs
|
||||
Capability
|
||||
× effort
|
||||
ROUTING RULE
|
||||
strong model + high effort → frame ambiguity · light model + low effort → bounded execution · raise one knob at a time → compare evidence
|
||||
Sequence
|
||||
Spend judgment
|
||||
where it
|
||||
compounds.
|
||||
01
|
||||
Plan
|
||||
Strong model: scope, risks, acceptance, and worktree split.
|
||||
02
|
||||
Build
|
||||
Focused worker: smallest context and lightest model that can pass.
|
||||
03
|
||||
Review
|
||||
Independent pass when missed issues cost more than the call.
|
||||
Next: agents & trees →
|
||||
Rules case study →
|
||||
@@ -1,118 +0,0 @@
|
||||
Rules That Survive the Prompt — AI For Dummies
|
||||
A
|
||||
field guide
|
||||
Pipeline
|
||||
Skills
|
||||
Examples
|
||||
EN
|
||||
/
|
||||
PT
|
||||
A real repository case study
|
||||
Rules that
|
||||
survive the
|
||||
prompt.
|
||||
Prompts ask for behavior. Repositories preserve it. The interview project combines written context, reusable skills, executable checks, commit hooks, and independent review so the rule is still present when the conversation is gone.
|
||||
CASE / NETCRACKER
|
||||
interview
|
||||
8 skills · 3 agents · 4 enforcement layers
|
||||
THE SHORT VERSION
|
||||
A prompt is advice for one run. A repository rule is reusable context plus an executable boundary.
|
||||
Enforcement pipeline
|
||||
select a checkpoint
|
||||
From intent to evidence
|
||||
Five places
|
||||
a rule can
|
||||
hold.
|
||||
Not every rule belongs in a hook. Put guidance where an agent can discover it, deterministic policy in a command, cheap checks at commit time, and independent judgment at review.
|
||||
01
|
||||
CONTEXT
|
||||
AGENTS.md
|
||||
→
|
||||
02
|
||||
SKILLS
|
||||
.agents/skills
|
||||
→
|
||||
03
|
||||
CLI
|
||||
check:ui
|
||||
→
|
||||
04
|
||||
COMMIT
|
||||
Husky
|
||||
→
|
||||
05
|
||||
REVIEW
|
||||
pragent
|
||||
Project-local skills
|
||||
procedures born from repeated friction
|
||||
Small instruction packages
|
||||
Teach the trap.
|
||||
Name the
|
||||
trigger.
|
||||
These skills are not downloaded magic. They are repository-specific procedures under
|
||||
.agents/skills/
|
||||
, distilled from mistakes, commands, and architectural decisions that kept recurring.
|
||||
gate-discipline
|
||||
prove green is real
|
||||
parallel-agents
|
||||
worktree per task
|
||||
repo-db
|
||||
query before crawling
|
||||
tech-debt
|
||||
separate line of work
|
||||
skill-writer
|
||||
repeat twice, encode once
|
||||
frontend / go-api
|
||||
stack-specific traps
|
||||
Concrete examples
|
||||
open the source, then adapt
|
||||
CLI RATCHET
|
||||
Debt may go down.
|
||||
Never silently up.
|
||||
pnpm check:ui
|
||||
# raw buttons
|
||||
# swallowed catches
|
||||
# pages without h1
|
||||
# hardcoded colours
|
||||
Read the checker →
|
||||
HUSKY / PRE-COMMIT
|
||||
Fast checks before history.
|
||||
pnpm exec lint-staged
|
||||
node scripts/check-ui-contract.mjs
|
||||
Read the hook →
|
||||
COMMIT MESSAGE
|
||||
Intent has a grammar.
|
||||
pnpm exec commitlint --edit $1
|
||||
feat: add interview timer
|
||||
fix(api): scope session query
|
||||
Read commitlint config →
|
||||
INDEPENDENT REVIEW
|
||||
A second reader checks intent.
|
||||
.pr-review.json
|
||||
├── focus
|
||||
├── exclude_paths
|
||||
├── languages
|
||||
└── instructions
|
||||
Read review policy →
|
||||
COPY / ADAPT
|
||||
Ask your agent to map the enforcement stack.
|
||||
Use this in the interview repository or adapt the path names to another project.
|
||||
COPY PROMPT
|
||||
↗
|
||||
GO DEEPER
|
||||
Read the implementation, not just this summary.
|
||||
01
|
||||
Repository context
|
||||
AGENTS.md
|
||||
02
|
||||
Skill catalog
|
||||
.agents/skills/
|
||||
03
|
||||
Design skills
|
||||
skills/
|
||||
03
|
||||
Specialist agents
|
||||
.claude/agents/
|
||||
04
|
||||
Staged-file policy
|
||||
.lintstagedrc.cjs
|
||||
@@ -1,52 +0,0 @@
|
||||
Submitted Skills — Review Desk
|
||||
← field guide
|
||||
SUBMITTED SKILLS / REVIEW DESK
|
||||
submissions
|
||||
A friendly path from draft to dependable
|
||||
Every skill deserves
|
||||
a clear job.
|
||||
Read the original, understand what already works, and compare a safer, leaner draft. Nothing here overwrites a submission; revisions live in their own review output.
|
||||
01
|
||||
Discoverable
|
||||
A precise description tells an agent when to load the skill.
|
||||
02
|
||||
Useful in context
|
||||
Core workflow stays short; conditional detail loads only when needed.
|
||||
03
|
||||
Safe by design
|
||||
Commands, secrets, and shared systems have explicit boundaries.
|
||||
04
|
||||
Proven in use
|
||||
Real prompts and observable checks turn a draft into a reliable tool.
|
||||
How to use this desk
|
||||
Compare.
|
||||
Then choose.
|
||||
Select a submission, or open an author URL.
|
||||
Read the gentle review before judging the draft.
|
||||
Choose
|
||||
Preview Markdown
|
||||
in the file toolbar to render either version.
|
||||
Copy or download the version you want, then vote for the draft you would ship.
|
||||
The catalog
|
||||
Find a skill
|
||||
Why these reviews look this way
|
||||
The recommendations follow the open Agent Skills format: valid frontmatter for discovery, progressive disclosure for context economy, deterministic scripts for fragile repeated mechanics, and behavioral evaluation rather than a checklist of pretty headings.
|
||||
Format specification ↗
|
||||
Writing practices ↗
|
||||
Evaluation loop ↗
|
||||
Scripts guide ↗
|
||||
Share an author with
|
||||
?author=Name
|
||||
, or one review with
|
||||
?author=Name&skill=skill-id&view=improved
|
||||
. To add a submission later: drop a package under
|
||||
submitted-skills/
|
||||
, add an entry under
|
||||
src/content/reviews/{new-id}.md
|
||||
(and mirror it into
|
||||
skills-review/catalog.js
|
||||
which the desk still reads), then run
|
||||
node scripts/build-skill-review.mjs
|
||||
. Votes call a separate service — see
|
||||
vote-service/
|
||||
— one per visitor, tracked by network source.
|
||||
@@ -1,45 +0,0 @@
|
||||
AI For Dummies — Skills
|
||||
← ROUTE MAP
|
||||
03 / SKILLS
|
||||
review desk ↗
|
||||
Reusable judgment
|
||||
Teach the
|
||||
decision.
|
||||
A skill changes behavior. Keep the trigger precise, put the workflow in
|
||||
SKILL.md
|
||||
, and move conditional facts, scripts, and examples into focused files.
|
||||
Package anatomy
|
||||
One job.
|
||||
More than
|
||||
one
|
||||
file.
|
||||
Choose a file to see why it belongs in the package.
|
||||
REVIEW-UI / SKILL PACKAGE
|
||||
├── SKILL.md
|
||||
trigger + workflow
|
||||
├── references/
|
||||
conditional facts
|
||||
├── scripts/
|
||||
deterministic checks
|
||||
└── assets/
|
||||
templates + examples
|
||||
Create a skill
|
||||
Observe →
|
||||
trigger →
|
||||
validate
|
||||
01
|
||||
Observe friction
|
||||
Find a repeated decision or failure.
|
||||
02
|
||||
Define the trigger
|
||||
Say when it should load and when it should stay out.
|
||||
03
|
||||
Choose anatomy
|
||||
Use references for facts and scripts for deterministic mechanics.
|
||||
04
|
||||
Evaluate behavior
|
||||
Test realistic prompts, edge cases, safety, and evidence.
|
||||
Agents & trees →
|
||||
Rules case study →
|
||||
Review submitted skills →
|
||||
Full guide: skill forge →
|
||||
@@ -1,35 +0,0 @@
|
||||
AI For Dummies — Route map
|
||||
← AI FOR DUMMIES
|
||||
00 / ROUTE MAP
|
||||
review desk ↗
|
||||
Start here
|
||||
Ship the
|
||||
system.
|
||||
This guide turns AI work into a shape: frame the problem, choose the model and agent, isolate changes, teach repeatable decisions, and verify the result.
|
||||
01
|
||||
Models
|
||||
Capability and effort are separate knobs.
|
||||
Open chapter →
|
||||
02
|
||||
Agents & trees
|
||||
Bound roles, handoffs, and worktrees.
|
||||
Open chapter →
|
||||
03
|
||||
Skills
|
||||
Capture repeatable decisions.
|
||||
Open chapter →
|
||||
04
|
||||
Rules
|
||||
Connect guidance to enforcement.
|
||||
Open chapter →
|
||||
05
|
||||
Practice
|
||||
Compare prompts and skill-enabled runs.
|
||||
Open lab →
|
||||
06
|
||||
Review desk
|
||||
Browse original files and improved drafts.
|
||||
Open desk →
|
||||
Full field guide
|
||||
Operations guide
|
||||
Each chapter stands alone; the order follows a real task becoming a reliable change.
|
||||
@@ -1,41 +0,0 @@
|
||||
---
|
||||
// Grid-group template — for a set of sibling cards separated by hairlines.
|
||||
//
|
||||
// Note the separator technique: `gap: 1px` over a coloured parent background.
|
||||
// That is DELIBERATE house style throughout this site, not a workaround.
|
||||
// Do not "fix" it into `border`.
|
||||
|
||||
interface Props {
|
||||
label: string;
|
||||
/** Number of columns at the widest breakpoint. */
|
||||
columns?: number;
|
||||
}
|
||||
|
||||
const { label, columns = 3 } = Astro.props;
|
||||
---
|
||||
|
||||
<section class="group" aria-label={label}>
|
||||
<div class="grid" style={`--columns: ${columns}`}>
|
||||
<slot />
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<style>
|
||||
.grid {
|
||||
display: grid;
|
||||
grid-template-columns: repeat(var(--columns), 1fr);
|
||||
gap: 1px; /* hairline separators, drawn by the parent background */
|
||||
background: var(--line);
|
||||
}
|
||||
|
||||
/* Children paint their own background, which is what makes the 1px show. */
|
||||
.grid > :global(*) {
|
||||
background: var(--paper);
|
||||
}
|
||||
|
||||
@media (max-width: 800px) {
|
||||
.grid {
|
||||
grid-template-columns: 1fr;
|
||||
}
|
||||
}
|
||||
</style>
|
||||
@@ -1,110 +0,0 @@
|
||||
---
|
||||
// Interactive island template. Use ONLY when the component genuinely needs
|
||||
// client-side behaviour, and write the justification in your PR description.
|
||||
//
|
||||
// Islands are LEAVES. Do not wrap static children that could have been
|
||||
// server-rendered — hydrate the tab panel, not the page.
|
||||
//
|
||||
// Hydration preference, in order:
|
||||
// (none) → client:visible → client:idle → client:load
|
||||
//
|
||||
// Usage: <Island client:visible items={items} />
|
||||
|
||||
interface Props {
|
||||
items: { id: string; label: string; body: string }[];
|
||||
initialId?: string;
|
||||
}
|
||||
|
||||
const { items, initialId = items[0]?.id } = Astro.props;
|
||||
---
|
||||
|
||||
<div class="island" data-initial={initialId}>
|
||||
<div class="tabs" role="tablist" aria-label="Sections">
|
||||
{
|
||||
items.map((item) => (
|
||||
<button
|
||||
role="tab"
|
||||
id={`tab-${item.id}`}
|
||||
aria-controls={`panel-${item.id}`}
|
||||
aria-selected={item.id === initialId}
|
||||
data-tab={item.id}
|
||||
>
|
||||
{item.label}
|
||||
</button>
|
||||
))
|
||||
}
|
||||
</div>
|
||||
{
|
||||
items.map((item) => (
|
||||
<div
|
||||
role="tabpanel"
|
||||
id={`panel-${item.id}`}
|
||||
aria-labelledby={`tab-${item.id}`}
|
||||
data-panel={item.id}
|
||||
hidden={item.id !== initialId}
|
||||
>
|
||||
{item.body}
|
||||
</div>
|
||||
))
|
||||
}
|
||||
</div>
|
||||
|
||||
<script>
|
||||
// Scoped to this island's own root so multiple instances never collide.
|
||||
document.querySelectorAll<HTMLElement>('.island').forEach((root) => {
|
||||
const tabs = root.querySelectorAll<HTMLButtonElement>('[data-tab]');
|
||||
const select = (id: string) => {
|
||||
tabs.forEach((tab) => tab.setAttribute('aria-selected', String(tab.dataset.tab === id)));
|
||||
root.querySelectorAll<HTMLElement>('[data-panel]').forEach((panel) => {
|
||||
panel.hidden = panel.dataset.panel !== id;
|
||||
});
|
||||
};
|
||||
tabs.forEach((tab) => tab.addEventListener('click', () => select(tab.dataset.tab!)));
|
||||
|
||||
// Arrow-key navigation is required for role="tablist" — see
|
||||
// .agents/rules/accessibility.md
|
||||
root.querySelector('[role="tablist"]')?.addEventListener('keydown', (event) => {
|
||||
const key = (event as KeyboardEvent).key;
|
||||
if (key !== 'ArrowRight' && key !== 'ArrowLeft') return;
|
||||
const list = [...tabs];
|
||||
const current = list.findIndex((tab) => tab.getAttribute('aria-selected') === 'true');
|
||||
const next = list[(current + (key === 'ArrowRight' ? 1 : -1) + list.length) % list.length];
|
||||
select(next.dataset.tab!);
|
||||
next.focus();
|
||||
});
|
||||
});
|
||||
</script>
|
||||
|
||||
<style>
|
||||
.tabs {
|
||||
display: grid;
|
||||
gap: 8px;
|
||||
}
|
||||
|
||||
button {
|
||||
padding: 12px;
|
||||
color: var(--ink);
|
||||
background: transparent;
|
||||
border: 1px solid var(--line);
|
||||
text-align: left;
|
||||
cursor: pointer;
|
||||
/* transform/opacity only — never animate layout properties */
|
||||
transition: background 180ms cubic-bezier(0.2, 0, 0, 1);
|
||||
}
|
||||
|
||||
button[aria-selected='true'] {
|
||||
color: var(--paper);
|
||||
background: var(--ink);
|
||||
}
|
||||
|
||||
button:focus-visible {
|
||||
outline: 3px solid var(--red);
|
||||
outline-offset: 2px;
|
||||
}
|
||||
|
||||
@media (prefers-reduced-motion: reduce) {
|
||||
button {
|
||||
transition-duration: 0.01ms;
|
||||
}
|
||||
}
|
||||
</style>
|
||||
@@ -1,76 +0,0 @@
|
||||
---
|
||||
// Static block template — the default. Ships zero JavaScript.
|
||||
// Copy to src/components/blocks/<Name>.astro and replace everything marked TODO.
|
||||
//
|
||||
// Before using this, confirm the block earns extraction: it appears three times,
|
||||
// or it has a name a person says out loud. See .agents/rules/componentization.md
|
||||
|
||||
interface Props {
|
||||
/** TODO: describe each prop. Required by default; optional needs a reason. */
|
||||
eyebrow: string;
|
||||
title: string;
|
||||
body: string;
|
||||
href?: string;
|
||||
}
|
||||
|
||||
const { eyebrow, title, body, href } = Astro.props;
|
||||
---
|
||||
|
||||
<article class="block">
|
||||
<span class="eyebrow">{eyebrow}</span>
|
||||
<h2>{title}</h2>
|
||||
<p>{body}</p>
|
||||
{href && <a href={href}>Open →</a>}
|
||||
<slot />
|
||||
</article>
|
||||
|
||||
<style>
|
||||
/* Tokens only. No raw hex, no px font sizes, no ad-hoc breakpoints.
|
||||
.agents/scripts/check-tokens.mjs enforces this. */
|
||||
.block {
|
||||
display: grid;
|
||||
gap: 10px;
|
||||
padding: 22px;
|
||||
background: var(--paper);
|
||||
color: var(--ink);
|
||||
}
|
||||
|
||||
/* The house eyebrow: uppercase monospace, wide tracking. One class, not
|
||||
fifteen repetitions. */
|
||||
.eyebrow {
|
||||
color: var(--accent);
|
||||
font: var(--font-eyebrow);
|
||||
letter-spacing: 0.1em;
|
||||
text-transform: uppercase;
|
||||
}
|
||||
|
||||
h2 {
|
||||
margin: 0;
|
||||
font-size: var(--step-5);
|
||||
line-height: 1.05;
|
||||
letter-spacing: -0.06em; /* tight display tracking is a signature of this design */
|
||||
}
|
||||
|
||||
p {
|
||||
margin: 0;
|
||||
color: var(--muted);
|
||||
line-height: 1.65;
|
||||
}
|
||||
|
||||
a {
|
||||
color: var(--blue);
|
||||
font-weight: 700;
|
||||
text-decoration: none;
|
||||
}
|
||||
|
||||
a:focus-visible {
|
||||
outline: 3px solid var(--red);
|
||||
outline-offset: 2px;
|
||||
}
|
||||
|
||||
@media (max-width: 800px) {
|
||||
.block {
|
||||
padding: 18px;
|
||||
}
|
||||
}
|
||||
</style>
|
||||
@@ -1,7 +0,0 @@
|
||||
dist
|
||||
node_modules
|
||||
public/hands-on
|
||||
submitted-skills
|
||||
skill-reviews
|
||||
vote-service
|
||||
.agents/snapshots
|
||||
@@ -1,11 +0,0 @@
|
||||
{
|
||||
"printWidth": 100,
|
||||
"singleQuote": true,
|
||||
"semi": true,
|
||||
"trailingComma": "all",
|
||||
"plugins": ["prettier-plugin-astro"],
|
||||
"overrides": [
|
||||
{ "files": "*.astro", "options": { "parser": "astro" } },
|
||||
{ "files": "*.md", "options": { "proseWrap": "always", "printWidth": 80 } }
|
||||
]
|
||||
}
|
||||
@@ -1,18 +0,0 @@
|
||||
{
|
||||
"extends": ["stylelint-config-standard"],
|
||||
"ignoreFiles": ["dist/**", "public/hands-on/**", "submitted-skills/**"],
|
||||
"rules": {
|
||||
"custom-property-pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*$",
|
||||
"declaration-property-value-disallowed-list": {
|
||||
"/^transition/": ["/width/", "/height/", "/^top/", "/^left/", "/margin/"],
|
||||
"/^animation/": ["/width/", "/height/"]
|
||||
},
|
||||
"media-feature-name-no-unknown": true,
|
||||
"no-descending-specificity": null,
|
||||
"selector-class-pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*$"
|
||||
},
|
||||
"_comments": {
|
||||
"declaration-property-value-disallowed-list": "Animating layout properties forces reflow every frame and fails the 200ms INP budget. transform and opacity only — see .agents/rules/animation.md",
|
||||
"ignoreFiles": "hands-on/ is a lab fixture and submitted-skills/ is other people's work; neither is ours to restyle"
|
||||
}
|
||||
}
|
||||
@@ -1,26 +0,0 @@
|
||||
// Flat config (ESLint 9+). Copy to the repository root in task 01.
|
||||
import js from '@eslint/js';
|
||||
import astro from 'eslint-plugin-astro';
|
||||
|
||||
export default [
|
||||
js.configs.recommended,
|
||||
...astro.configs.recommended,
|
||||
{
|
||||
ignores: [
|
||||
'dist/**',
|
||||
'public/hands-on/**', // lab fixtures ship verbatim — linting them would
|
||||
// invite "fixes" that break the exercise
|
||||
'submitted-skills/**', // other people's work, reproduced as submitted
|
||||
'skill-reviews/**', // generated from skills-review/catalog.js
|
||||
'vote-service/**', // Go service, separate lifecycle
|
||||
],
|
||||
},
|
||||
{
|
||||
rules: {
|
||||
'no-console': ['warn', { allow: ['warn', 'error'] }],
|
||||
eqeqeq: ['error', 'always'],
|
||||
'no-var': 'error',
|
||||
'prefer-const': 'error',
|
||||
},
|
||||
},
|
||||
];
|
||||
@@ -1,39 +0,0 @@
|
||||
# Tier 3 gate. Copy to .gitea/workflows/verify.yml in task 01.
|
||||
#
|
||||
# Known trap: this Gitea's act-runner registration lives in an emptyDir, so a
|
||||
# pod restart silently kills CI. If the site stops updating, check the runner
|
||||
# BEFORE debugging the workflow.
|
||||
name: verify
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
pull_request:
|
||||
|
||||
jobs:
|
||||
gate:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
with:
|
||||
fetch-depth: 0 # gate.sh compares assertion counts against origin/main
|
||||
|
||||
- uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: 22
|
||||
cache: npm
|
||||
|
||||
- run: npm ci --prefer-offline
|
||||
- run: npm run lint
|
||||
- run: ./.agents/scripts/gate.sh
|
||||
|
||||
# Tier 3 only: too slow for pre-push, essential before publishing.
|
||||
- name: visual regression
|
||||
run: |
|
||||
npx playwright install --with-deps chromium
|
||||
node .agents/scripts/visual-regression.mjs
|
||||
|
||||
- uses: actions/upload-artifact@v4
|
||||
if: failure()
|
||||
with:
|
||||
name: screenshots
|
||||
path: .agents/snapshots/diff/
|
||||
@@ -1,27 +0,0 @@
|
||||
{
|
||||
"_note": "Merge these into package.json in task 01. `prepare` is what installs husky; without it every hook is inert.",
|
||||
"scripts": {
|
||||
"dev": "astro dev",
|
||||
"build": "astro build",
|
||||
"preview": "astro preview",
|
||||
"check": "astro check",
|
||||
"lint": "eslint . --max-warnings=0 && stylelint '**/*.css' --max-warnings=0",
|
||||
"format": "prettier --write .",
|
||||
"verify": "node scripts/verify.mjs && node scripts/audit-ui.mjs && node .agents/scripts/check-tokens.mjs",
|
||||
"gate": "./.agents/scripts/gate.sh",
|
||||
"snapshot": "node .agents/scripts/snapshot-route.mjs",
|
||||
"prepare": "husky"
|
||||
},
|
||||
"devDependencies": {
|
||||
"astro": "^5",
|
||||
"@eslint/js": "^9",
|
||||
"eslint": "^9",
|
||||
"eslint-plugin-astro": "^1",
|
||||
"husky": "^9",
|
||||
"lint-staged": "^16",
|
||||
"prettier": "^3",
|
||||
"prettier-plugin-astro": "^0.14",
|
||||
"stylelint": "^16",
|
||||
"stylelint-config-standard": "^39"
|
||||
}
|
||||
}
|
||||
@@ -1,70 +0,0 @@
|
||||
---
|
||||
// Chapter page template — for the numbered chapters (models, agents, skills,
|
||||
// rules). These ship ZERO JavaScript today and must continue to.
|
||||
//
|
||||
// Copy to src/pages/<slug>.astro. The route must match the existing URL
|
||||
// exactly, trailing slash included.
|
||||
|
||||
import ChapterLayout from '../layouts/ChapterLayout.astro';
|
||||
import GridGroup from '../components/blocks/GridGroup.astro';
|
||||
import StaticBlock from '../components/blocks/StaticBlock.astro';
|
||||
import { getEntry } from 'astro:content';
|
||||
|
||||
// Content comes from a collection, never hard-coded in the page.
|
||||
// Both `en` and `pt` are required by the schema.
|
||||
const chapter = await getEntry('chapters', 'models');
|
||||
const lang = 'en'; // TODO: wire to the language toggle decision (task 03)
|
||||
---
|
||||
|
||||
<ChapterLayout
|
||||
number={chapter.data.number}
|
||||
title={chapter.data.title[lang]}
|
||||
description={chapter.data.description[lang]}
|
||||
>
|
||||
<section class="hero">
|
||||
<p class="eyebrow">{chapter.data.eyebrow[lang]}</p>
|
||||
<h1 set:html={chapter.data.heading[lang]} />
|
||||
<p class="lede">{chapter.data.lede[lang]}</p>
|
||||
</section>
|
||||
|
||||
<GridGroup label="Chapter sections" columns={3}>
|
||||
{
|
||||
chapter.data.sections.map((section) => (
|
||||
<StaticBlock
|
||||
eyebrow={section.eyebrow[lang]}
|
||||
title={section.title[lang]}
|
||||
body={section.body[lang]}
|
||||
/>
|
||||
))
|
||||
}
|
||||
</GridGroup>
|
||||
</ChapterLayout>
|
||||
|
||||
<style>
|
||||
/* Page-level layout only. Anything reusable belongs in a component. */
|
||||
.hero {
|
||||
max-width: 780px;
|
||||
padding: clamp(75px, 12vh, 145px) 0 85px;
|
||||
}
|
||||
|
||||
h1 {
|
||||
margin: 16px 0 24px;
|
||||
font-size: var(--step-display);
|
||||
line-height: 0.86;
|
||||
letter-spacing: -0.08em;
|
||||
}
|
||||
|
||||
/* Georgia is a real system font and DOES render — unlike Manrope/DM Mono.
|
||||
See .agents/context/design-system.md */
|
||||
h1 :global(em) {
|
||||
color: var(--blue);
|
||||
font-family: Georgia, serif;
|
||||
font-weight: 400;
|
||||
}
|
||||
|
||||
.lede {
|
||||
max-width: 570px;
|
||||
color: var(--muted);
|
||||
line-height: 1.65;
|
||||
}
|
||||
</style>
|
||||
@@ -1,56 +0,0 @@
|
||||
---
|
||||
// Interactive page template — for pages that genuinely need client-side
|
||||
// behaviour (the full guide, the review desk).
|
||||
//
|
||||
// The page itself is still server-rendered. Only the islands hydrate.
|
||||
// If you are copying this for a page that has no interaction, use
|
||||
// chapter.astro instead.
|
||||
|
||||
import BaseLayout from '../layouts/BaseLayout.astro';
|
||||
import Island from '../components/islands/Island.astro';
|
||||
import { getCollection } from 'astro:content';
|
||||
|
||||
const entries = await getCollection('guide');
|
||||
const lang = 'en'; // TODO: wire to the language toggle decision (task 03)
|
||||
|
||||
const items = entries.map((entry) => ({
|
||||
id: entry.id,
|
||||
label: entry.data.title[lang],
|
||||
body: entry.data.copy[lang],
|
||||
}));
|
||||
---
|
||||
|
||||
<BaseLayout title="Full field guide" description="TODO">
|
||||
<!-- Static content is server-rendered. No hydration cost. -->
|
||||
<section class="hero">
|
||||
<p class="eyebrow">The full guide</p>
|
||||
<h1>Ship the <em>system.</em></h1>
|
||||
</section>
|
||||
|
||||
<!--
|
||||
client:visible, not client:load — this is below the fold and the page must
|
||||
stay interactive-free until it matters. Justification belongs in the PR:
|
||||
"tab panel requires click-driven state; no server equivalent."
|
||||
-->
|
||||
<Island client:visible items={items} />
|
||||
|
||||
<!-- More static content after the island. Islands are leaves, not wrappers. -->
|
||||
<slot />
|
||||
</BaseLayout>
|
||||
|
||||
<style>
|
||||
.hero {
|
||||
max-width: 780px;
|
||||
padding: clamp(75px, 12vh, 145px) 0 85px;
|
||||
}
|
||||
h1 {
|
||||
font-size: var(--step-display);
|
||||
line-height: 0.86;
|
||||
letter-spacing: -0.08em;
|
||||
}
|
||||
h1 em {
|
||||
color: var(--blue);
|
||||
font-family: Georgia, serif;
|
||||
font-weight: 400;
|
||||
}
|
||||
</style>
|
||||
@@ -1,68 +0,0 @@
|
||||
# Tier 3 gate and publication. The act-runner registration is stored in an
|
||||
# emptyDir: after a runner pod restart, re-register it before debugging CI.
|
||||
name: verify-and-publish
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
pull_request:
|
||||
# Publication is deliberately manual for the duration of the Astro migration.
|
||||
# See the `publish` job below for why.
|
||||
workflow_dispatch:
|
||||
inputs:
|
||||
publish:
|
||||
description: 'Force-push dist/ to the pages branch'
|
||||
type: boolean
|
||||
default: false
|
||||
|
||||
jobs:
|
||||
gate:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
with:
|
||||
fetch-depth: 0
|
||||
- uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: 22
|
||||
# Node 25 dropped the bundled corepack, and this self-hosted act-runner
|
||||
# is not a good place to discover whether it can fetch a third-party
|
||||
# action. Bootstrapping pnpm with npm needs neither. Keep the version in
|
||||
# step with package.json's `packageManager`.
|
||||
- run: npm install --global pnpm@11.25.0
|
||||
- run: pnpm install --frozen-lockfile
|
||||
- run: pnpm run lint
|
||||
- run: ./.agents/scripts/gate.sh
|
||||
# The visual-regression step is intentionally absent. `visual-regression.mjs`
|
||||
# only *captures* baselines — it has no compare mode — so in CI it would
|
||||
# overwrite .agents/snapshots/before/ and pass unconditionally. It also
|
||||
# imports `playwright`, which is not a dependency of this project. Wire it
|
||||
# back in once it can actually diff. See task 03's report.
|
||||
|
||||
publish:
|
||||
# `dist/` now holds all ten routes, so the stub hazard that forced this to
|
||||
# manual dispatch is gone. It stays manual anyway: the step below is a
|
||||
# force-push over the live `pages` branch, and making it fire on every push
|
||||
# to main means every merge republishes with no human in the loop. Flipping
|
||||
# it to `push` on main is a deliberate decision, not a leftover TODO.
|
||||
if: github.event_name == 'workflow_dispatch' && inputs.publish
|
||||
needs: gate
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: 22
|
||||
- run: npm install --global pnpm@11.25.0
|
||||
- run: pnpm install --frozen-lockfile
|
||||
- run: pnpm run build
|
||||
- name: Publish generated site to pages
|
||||
run: |
|
||||
git config user.name 'gitea-actions[bot]'
|
||||
git config user.email 'gitea-actions[bot]@users.noreply.local'
|
||||
git switch --orphan pages
|
||||
git rm -rf .
|
||||
cp -a dist/. .
|
||||
git add --all
|
||||
git commit -m 'chore: publish site'
|
||||
git push --force origin HEAD:pages
|
||||
-24
@@ -1,24 +0,0 @@
|
||||
# Tooling caches, not part of the published site.
|
||||
.serena/
|
||||
__pycache__/
|
||||
|
||||
# Build + toolchain (Astro migration).
|
||||
node_modules/
|
||||
dist/
|
||||
.astro/
|
||||
.husky/_/
|
||||
|
||||
# Visual-regression working output. Baselines in .agents/snapshots/ ARE tracked;
|
||||
# the per-run captures and diffs are not.
|
||||
.agents/snapshots/after/
|
||||
.agents/snapshots/diff/
|
||||
|
||||
# agent run logs
|
||||
.agents/logs/
|
||||
|
||||
# pnpm-only project. A stray npm/yarn/bun run here is a bug the gate rejects;
|
||||
# ignoring the artefacts keeps one from being committed by accident.
|
||||
package-lock.json
|
||||
yarn.lock
|
||||
bun.lock
|
||||
bun.lockb
|
||||
@@ -1,26 +0,0 @@
|
||||
# Conventional commits, matching this repository's existing log
|
||||
# (feat:, fix:, docs:, refactor:, chore:, test:, style:, ci:).
|
||||
#
|
||||
# Deliberately a plain regex rather than a commitlint dependency: this project's
|
||||
# thesis is having no unnecessary dependencies, and one regex is legible to
|
||||
# every agent that has to satisfy it.
|
||||
|
||||
message_file=$1
|
||||
first_line=$(head -n1 "$message_file")
|
||||
|
||||
# Allow merge and revert commits through untouched.
|
||||
case "$first_line" in
|
||||
"Merge "*|"Revert "*) exit 0 ;;
|
||||
esac
|
||||
|
||||
if ! printf '%s' "$first_line" | grep -qE '^(feat|fix|docs|refactor|chore|test|style|ci|perf|build|revert)(\([a-z0-9 -]+\))?: .{1,}$'; then
|
||||
echo "commit-msg: subject must be '<type>: <subject>' (lowercase type)." >&2
|
||||
echo " types: feat fix docs refactor chore test style ci perf build revert" >&2
|
||||
echo " got: $first_line" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
if [ "${#first_line}" -gt 72 ]; then
|
||||
echo "commit-msg: subject is ${#first_line} chars; keep it under 72." >&2
|
||||
exit 1
|
||||
fi
|
||||
@@ -1,10 +0,0 @@
|
||||
# Tier 1: staged files only. Budget < 3s — see .agents/rules/gates.md
|
||||
#
|
||||
# Husky v9+: no `husky.sh` sourcing (deprecated in v9, removed in v10).
|
||||
|
||||
# Guard the silent-failure mode: if hooks are configured but .husky/_ is
|
||||
# missing (fresh worktree that never ran `pnpm install`), this file would not
|
||||
# execute at all. Nothing we can do from inside it — so verify-hooks.sh exists
|
||||
# and worktree.sh runs it at creation time.
|
||||
|
||||
pnpm exec lint-staged
|
||||
@@ -1,40 +0,0 @@
|
||||
# Tier 2: the real gate. Whole project. Budget < 90s.
|
||||
# Takes a cross-worktree lock so parallel agents queue instead of thrashing.
|
||||
|
||||
# The publish step below re-enters git push. Without this, that inner push would
|
||||
# fire this hook again, run the gate again, and publish again, forever.
|
||||
if [ "${AF_PUBLISHING:-0}" = '1' ]; then
|
||||
exit 0
|
||||
fi
|
||||
|
||||
.agents/scripts/gate.sh || exit 1
|
||||
|
||||
# Publishing to `pages` overwrites the live site. It happens here, on a push of
|
||||
# main to origin, and nowhere else.
|
||||
#
|
||||
# Set AF_NO_PUBLISH=1 to push main without republishing:
|
||||
# AF_NO_PUBLISH=1 git push
|
||||
[ "${AF_NO_PUBLISH:-0}" = '1' ] && exit 0
|
||||
|
||||
remote_name=$1
|
||||
[ "$remote_name" = 'origin' ] || exit 0
|
||||
|
||||
# stdin gives one line per ref being pushed:
|
||||
# <local ref> <local sha> <remote ref> <remote sha>
|
||||
zero='0000000000000000000000000000000000000000'
|
||||
while read -r local_ref local_sha remote_ref remote_sha; do
|
||||
[ "$remote_ref" = 'refs/heads/main' ] || continue
|
||||
# A deletion has no build to publish.
|
||||
[ "$local_sha" = "$zero" ] && continue
|
||||
|
||||
# This hook runs before the push lands, so `pages` would go live ahead of
|
||||
# `main` if the push then failed. Publish only when the push cannot be
|
||||
# rejected as a non-fast-forward: the remote tip must already be an ancestor.
|
||||
if [ "$remote_sha" != "$zero" ] && ! git merge-base --is-ancestor "$remote_sha" "$local_sha"; then
|
||||
echo "pre-push: main is not a fast-forward; not publishing." >&2
|
||||
echo " Push main first, then run .agents/scripts/publish-pages.sh" >&2
|
||||
continue
|
||||
fi
|
||||
|
||||
.agents/scripts/publish-pages.sh --pending "$local_sha" || exit 1
|
||||
done
|
||||
@@ -1,6 +0,0 @@
|
||||
{
|
||||
"*.{js,mjs,ts,astro}": ["prettier --write", "eslint --fix --max-warnings=0 --no-warn-ignored"],
|
||||
"*.css": ["prettier --write", "stylelint --fix --max-warnings=0 --allow-empty-input"],
|
||||
"src/**/*.{astro,css}": ["node .agents/scripts/check-tokens.mjs"],
|
||||
"*.{json,md,yml,yaml}": ["prettier --write"]
|
||||
}
|
||||
@@ -1,17 +0,0 @@
|
||||
dist
|
||||
hands-on
|
||||
node_modules
|
||||
public/hands-on
|
||||
submitted-skills
|
||||
skill-reviews
|
||||
vote-service
|
||||
.agents/snapshots
|
||||
pnpm-lock.yaml
|
||||
public/submitted-skills
|
||||
|
||||
# Unmigrated legacy sources, kept verbatim under `legacy/`. These are
|
||||
# hand-written files with very long lines; prettier re-wraps them into hundreds
|
||||
# of changed lines the moment any agent stages one. Task 15 touched the old
|
||||
# app.js to add four lines and produced an 829-line diff. A reformat here is
|
||||
# churn at best.
|
||||
/legacy/
|
||||
@@ -1,11 +0,0 @@
|
||||
{
|
||||
"printWidth": 100,
|
||||
"singleQuote": true,
|
||||
"semi": true,
|
||||
"trailingComma": "all",
|
||||
"plugins": ["prettier-plugin-astro"],
|
||||
"overrides": [
|
||||
{ "files": "*.astro", "options": { "parser": "astro" } },
|
||||
{ "files": "*.md", "options": { "proseWrap": "always", "printWidth": 80 } }
|
||||
]
|
||||
}
|
||||
@@ -1,22 +0,0 @@
|
||||
dist
|
||||
node_modules
|
||||
hands-on
|
||||
public/hands-on
|
||||
submitted-skills
|
||||
public/submitted-skills
|
||||
skill-reviews
|
||||
vote-service
|
||||
|
||||
# Unmigrated legacy stylesheets, kept verbatim under `legacy/`. Same list and
|
||||
# same reasoning as .prettierignore: these are minified, single-line
|
||||
# stylesheets. stylelint's `declaration-block-single-line-max-declarations`
|
||||
# fires once per rule in them — ~180 errors for `guide.css` alone — so staging
|
||||
# one to change a single declaration blocks the commit outright. The rule is
|
||||
# about hand-written source readability and says nothing useful about minified
|
||||
# legacy output. Migrating one of these into `src/` means bringing it up to the
|
||||
# design system in the same change, at which point it gets linted like any
|
||||
# other source file.
|
||||
#
|
||||
# `public/fonts/fonts.css` is deliberately NOT here: it is new, hand-written,
|
||||
# and must stay linted.
|
||||
/legacy/
|
||||
@@ -1,20 +0,0 @@
|
||||
{
|
||||
"extends": ["stylelint-config-standard"],
|
||||
"ignoreFiles": [
|
||||
"dist/**",
|
||||
"hands-on/**",
|
||||
"public/hands-on/**",
|
||||
"submitted-skills/**",
|
||||
"skill-reviews/**"
|
||||
],
|
||||
"rules": {
|
||||
"custom-property-pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*$",
|
||||
"declaration-property-value-disallowed-list": {
|
||||
"/^transition/": ["/width/", "/height/", "/^top/", "/^left/", "/margin/"],
|
||||
"/^animation/": ["/width/", "/height/"]
|
||||
},
|
||||
"media-feature-name-no-unknown": true,
|
||||
"no-descending-specificity": null,
|
||||
"selector-class-pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*$"
|
||||
}
|
||||
}
|
||||
@@ -1,96 +0,0 @@
|
||||
# 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`](.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.
|
||||
|
||||
- **Stack**: Astro, static output, no runtime dependencies. The migration
|
||||
recorded in [`plans/astro-refactor/`](plans/astro-refactor/README.md) is
|
||||
complete; the hand-written pages it replaced are gone. What remains unmigrated
|
||||
is the editorial CSS and the review-desk modules under `legacy/`, still
|
||||
imported by the pages that need them.
|
||||
- **Languages**: English and Brazilian Portuguese, toggled client-side
|
||||
- **Companion service**: a Go + Kubernetes vote API, reached over
|
||||
`window.SKILLS_REVIEW_VOTE_API`. Its source is no longer in this repository
|
||||
|
||||
## Essential commands
|
||||
|
||||
```bash
|
||||
pnpm run dev # http://localhost:4321/ai-for-dummies/
|
||||
pnpm run build # writes dist/ — every check below reads it
|
||||
bash .agents/scripts/gate.sh # the full gate: check, build, verify, audit, tokens
|
||||
pnpm run verify # content + interaction contracts (scripts/verify.mjs)
|
||||
node scripts/audit-ui.mjs # responsive / no-external-dependency audit
|
||||
node scripts/build-skill-review.mjs # regenerate skill-reviews/improved/ from src/content/reviews/
|
||||
```
|
||||
|
||||
`pnpm run verify` is not a formality. It is a set of 84 string-token assertions
|
||||
that pin the site's real content and interactions, read from the built output.
|
||||
**A refactor that "passes" by deleting assertions has failed.** See
|
||||
[`.agents/context/verification.md`](.agents/context/verification.md).
|
||||
|
||||
## Publishing
|
||||
|
||||
`main` is the source of truth. The `pages` branch is what the Gitea Pages Server
|
||||
actually serves, and it now carries **build output**, not a copy of `main`'s
|
||||
tree.
|
||||
|
||||
**Pushing `main` republishes the live site.** The `pre-push` hook runs the gate,
|
||||
then `.agents/scripts/publish-pages.sh`, which builds and force-pushes `dist/`
|
||||
to `pages`. Use `AF_NO_PUBLISH=1 git push` to land a commit without publishing.
|
||||
`pages` keeps its history, so rollback is a single force-push to an earlier tip;
|
||||
`pages-backup-2026-09-06` is the last commit of the hand-written site. The full
|
||||
procedure is in [`docs/operations-guide.md`](docs/operations-guide.md); read
|
||||
[`.agents/context/publishing.md`](.agents/context/publishing.md) before changing
|
||||
it.
|
||||
|
||||
## Never touch
|
||||
|
||||
- `public/hands-on/starter/` and `public/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 `src/content/reviews/*.md` instead
|
||||
- `dist/`, `node_modules/` — build output, never committed
|
||||
- `pnpm-lock.yaml` — **committed, but never hand-edited.** Change it only as a
|
||||
side effect of `pnpm install`. Every worktree spins up with
|
||||
`pnpm install --frozen-lockfile`, which fails outright without it.
|
||||
- This project is **pnpm-only** (`packageManager` in `package.json` pins the
|
||||
version). Never run `npm install` or `bun install` here — the gate rejects a
|
||||
`package-lock.json`, `yarn.lock`, or `bun.lock` outright. pnpm settings live
|
||||
in `pnpm-workspace.yaml`, **not** in a `pnpm` field in `package.json`; pnpm 11
|
||||
ignores that field silently.
|
||||
|
||||
## Rules
|
||||
|
||||
Binding. Read the one that covers what you are about to do.
|
||||
|
||||
| Rule | When |
|
||||
| ---------------------------------------------------------- | ------------------------------------ |
|
||||
| [`astro.md`](.agents/rules/astro.md) | any `.astro` file |
|
||||
| [`theming.md`](.agents/rules/theming.md) | any colour, font, or spacing value |
|
||||
| [`componentization.md`](.agents/rules/componentization.md) | creating or splitting a component |
|
||||
| [`animation.md`](.agents/rules/animation.md) | any motion, transition, or transform |
|
||||
| [`accessibility.md`](.agents/rules/accessibility.md) | any interactive element |
|
||||
| [`content-i18n.md`](.agents/rules/content-i18n.md) | any user-visible string |
|
||||
| [`code-style.md`](.agents/rules/code-style.md) | always |
|
||||
| [`git-worktrees.md`](.agents/rules/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`](.agents/context/design-system.md) before
|
||||
touching any CSS.
|
||||
@@ -1,41 +1,23 @@
|
||||
# Gates: review desk privacy and improved-draft audit
|
||||
|
||||
OWNS: src/pages/skills-review.astro, src/components/blocks/{ReviewDetail,
|
||||
ChangeLens,VoteWidget,PreviewPane,FileTabs}.astro, legacy/skills-review/**,
|
||||
submitted-skills/Anonymous Operational Submission/**,
|
||||
skill-reviews/improved/ndo-repro/**, scripts/verify.mjs
|
||||
OWNS: skills-review/**, submitted-skills/Anonymous Operational Submission/**, skill-reviews/improved/ndo-repro/**, scripts/verify.mjs
|
||||
|
||||
The gate commands below now read `dist/`; run `pnpm run build` before them.
|
||||
Scope: Redact the operational submission's identity and URLs from the published review desk, keep package files usable in either preview mode, and explain each improved draft as a concrete diff.
|
||||
|
||||
Scope: Redact the operational submission's identity and URLs from the published
|
||||
review desk, keep package files usable in either preview mode, and explain each
|
||||
improved draft as a concrete diff.
|
||||
- [x] G1: the published operational submission contains no personal name, original source URL, email address, or host-specific path
|
||||
CHECK: node scripts/verify.mjs
|
||||
EXPECT: review privacy verification passed
|
||||
EVIDENCE: exit=0; shell=/bin/sh; cwd=/home/marcos/Projects/ai-for-dummies; path=d3551337f830/34 entries; EXPECT=matched; output-sha256=180e8cd0d18968e2a4244ede959c3459b5ce80b836fc5a0df00961907e5d15a1; output-bytes=481
|
||||
|
||||
- [x] G1: the published operational submission contains no personal name,
|
||||
original source URL, email address, or host-specific path CHECK: node
|
||||
scripts/verify.mjs EXPECT: review privacy verification passed EVIDENCE:
|
||||
exit=0; shell=/bin/sh; cwd=/home/marcos/Projects/ai-for-dummies;
|
||||
path=d3551337f830/34 entries; EXPECT=matched;
|
||||
output-sha256=180e8cd0d18968e2a4244ede959c3459b5ce80b836fc5a0df00961907e5d15a1;
|
||||
output-bytes=481
|
||||
- [x] G2: every package file remains selectable in Original and Improved draft modes without resetting the selected preview
|
||||
CHECK: node scripts/verify.mjs
|
||||
EXPECT: review file-mode verification passed
|
||||
EVIDENCE: exit=0; shell=/bin/sh; cwd=/home/marcos/Projects/ai-for-dummies; path=d3551337f830/34 entries; EXPECT=matched; output-sha256=180e8cd0d18968e2a4244ede959c3459b5ce80b836fc5a0df00961907e5d15a1; output-bytes=481
|
||||
|
||||
- [x] G2: every package file remains selectable in Original and Improved draft
|
||||
modes without resetting the selected preview CHECK: node
|
||||
scripts/verify.mjs EXPECT: review file-mode verification passed EVIDENCE:
|
||||
exit=0; shell=/bin/sh; cwd=/home/marcos/Projects/ai-for-dummies;
|
||||
path=d3551337f830/34 entries; EXPECT=matched;
|
||||
output-sha256=180e8cd0d18968e2a4244ede959c3459b5ce80b836fc5a0df00961907e5d15a1;
|
||||
output-bytes=481
|
||||
- [x] G3: every improved draft has an interactive change lens that explains changed guidance and its rationale
|
||||
CHECK: node scripts/verify.mjs
|
||||
EXPECT: review change-lens verification passed
|
||||
EVIDENCE: exit=0; shell=/bin/sh; cwd=/home/marcos/Projects/ai-for-dummies; path=d3551337f830/34 entries; EXPECT=matched; output-sha256=180e8cd0d18968e2a4244ede959c3459b5ce80b836fc5a0df00961907e5d15a1; output-bytes=481
|
||||
|
||||
- [x] G3: every improved draft has an interactive change lens that explains
|
||||
changed guidance and its rationale CHECK: node scripts/verify.mjs EXPECT:
|
||||
review change-lens verification passed EVIDENCE: exit=0; shell=/bin/sh;
|
||||
cwd=/home/marcos/Projects/ai-for-dummies; path=d3551337f830/34 entries;
|
||||
EXPECT=matched;
|
||||
output-sha256=180e8cd0d18968e2a4244ede959c3459b5ce80b836fc5a0df00961907e5d15a1;
|
||||
output-bytes=481
|
||||
|
||||
- [x] G4: the review desk works at mobile, Full HD, and 4K widths without page
|
||||
errors or horizontal overflow EVIDENCE: Playwright audit on 2026-09-04:
|
||||
320, 390, 1280, 1920, and 3840px passed with Improved Draft and Change
|
||||
lens rendered; no horizontal overflow or page errors.
|
||||
- [x] G4: the review desk works at mobile, Full HD, and 4K widths without page errors or horizontal overflow
|
||||
EVIDENCE: Playwright audit on 2026-09-04: 320, 390, 1280, 1920, and 3840px passed with Improved Draft and Change lens rendered; no horizontal overflow or page errors.
|
||||
|
||||
@@ -3,108 +3,78 @@
|
||||
A lightweight, presentation-style field guide to AI-assisted engineering.
|
||||
|
||||
It explains how to combine a strong planning/review model with faster workers,
|
||||
reusable skills, subagent handoffs, Git worktrees, and explicit verification. An
|
||||
interactive field kit compares common behavior skills such as `ponytail-lite`,
|
||||
`caveman`, `unlazy`, research, debugging, and review. The skill-forge workflow
|
||||
covers discovery, triggers, package anatomy, progressive instructions,
|
||||
structural validation, and behavioral iteration. The hands-on lab provides a
|
||||
tiny starter project and copy-ready baseline and skill-enabled prompts for a
|
||||
short side-by-side exercise. An interactive model gearbox separates capability
|
||||
tier from reasoning effort across OpenAI, Claude, and Gemini, and every featured
|
||||
skill links to a pinned source with an approval-first installation prompt.
|
||||
reusable skills, subagent handoffs, Git worktrees, and explicit verification.
|
||||
An interactive field kit compares common behavior skills such as
|
||||
`ponytail-lite`, `caveman`, `unlazy`, research, debugging, and review.
|
||||
The skill-forge workflow covers discovery, triggers, package anatomy,
|
||||
progressive instructions, structural validation, and behavioral iteration.
|
||||
The hands-on lab provides a tiny starter project and copy-ready baseline and
|
||||
skill-enabled prompts for a short side-by-side exercise.
|
||||
An interactive model gearbox separates capability tier from reasoning effort
|
||||
across OpenAI, Claude, and Gemini, and every featured skill links to a pinned
|
||||
source with an approval-first installation prompt.
|
||||
|
||||
## Run locally
|
||||
|
||||
This is an Astro static site. It builds to `dist/` and ships no runtime
|
||||
dependencies.
|
||||
This is a dependency-free static site:
|
||||
|
||||
```bash
|
||||
pnpm install
|
||||
pnpm run dev # http://localhost:4321/ai-for-dummies/
|
||||
pnpm run build # writes dist/
|
||||
pnpm run preview # serves the built output
|
||||
python3 -m http.server 4173
|
||||
```
|
||||
|
||||
Then open <http://localhost:4173>.
|
||||
|
||||
Verify the content and interaction contracts with:
|
||||
|
||||
```bash
|
||||
pnpm run verify # reads dist/, so build first
|
||||
```
|
||||
|
||||
The full gate — `astro check`, `astro build`, `verify.mjs`, `audit-ui.mjs`,
|
||||
`check-tokens.mjs`, and the assertion-count floor — runs as:
|
||||
|
||||
```bash
|
||||
bash .agents/scripts/gate.sh
|
||||
npm run verify
|
||||
```
|
||||
|
||||
## Project structure
|
||||
|
||||
- `src/pages/` — one file per route: the landing route map, the complete
|
||||
bilingual `full-guide`, the chapter pages, `rules`, `skills`, and
|
||||
`skills-review`
|
||||
- `src/components/` — blocks and islands; the interactive diagrams, selectors,
|
||||
and the language toggle
|
||||
- `src/content/` — the content collections every page renders from
|
||||
- `src/styles/tokens.css` — the design tokens
|
||||
- `legacy/` — the editorial visual system and the review-desk modules, not yet
|
||||
migrated into components. Still imported by the pages that need them; see
|
||||
`.agents/context/architecture.md`
|
||||
- `public/` — assets copied to the site root verbatim: fonts, the hands-on labs,
|
||||
and `submitted-skills/`
|
||||
- `index.html` — default route map and focused chapter navigation
|
||||
- `full-guide/` — the complete bilingual presentation, with responsive audit overrides
|
||||
- `styles.css` / `app.js` — editorial visual system and bilingual field-guide interactions
|
||||
- `responsive.css` — interactive diagrams and Full HD-to-4K adaptations
|
||||
- `docs/references/` — bundled research sources and notes
|
||||
- `docs/operations-guide.md` — canonical SilverBullet operations and skills
|
||||
guide
|
||||
- `public/hands-on/starter/` — dependency-free Tiny Tasks exercise
|
||||
- `public/hands-on/rules/` — dependency-free Guardrails lab; toggles rule
|
||||
sources into the prompt
|
||||
- `skills/` — reusable design and rules-case-study skills
|
||||
- `docs/operations-guide.md` — canonical SilverBullet operations and skills guide
|
||||
- `hands-on/starter/` — dependency-free Tiny Tasks exercise
|
||||
- `hands-on/rules/` — dependency-free Guardrails lab; toggles rule sources into the prompt
|
||||
- `rules/` — bilingual case study of skills, CLI ratchets, Husky, and PR review
|
||||
- `skills/` — reusable design and rules-case-study skills, plus an interactive package anatomy explorer
|
||||
- `GATES.md` — acceptance ledger for the project
|
||||
|
||||
## Publishing
|
||||
|
||||
The Gitea instance has a Pages Server configured to publish a repository’s
|
||||
`pages` branch under `pages.marcospaulo.dev.br`. `pages` now carries the
|
||||
**built** site — the contents of `dist/` — not a copy of `main`. The intended
|
||||
site address is:
|
||||
`pages` branch under `pages.marcospaulo.dev.br`. The intended site address is:
|
||||
|
||||
<https://netcracker.pages.marcospaulo.dev.br/ai-for-dummies/>
|
||||
|
||||
If the URL is not available yet, verify that the `pages` branch exists and that
|
||||
the repository’s `pages` branch exists. Gitea itself does not provide a built-in
|
||||
Pages server; this setup uses the instance’s separate Pages Server and Actions
|
||||
deployment path.
|
||||
the repository’s `pages` branch exists. Gitea itself does not
|
||||
provide a built-in Pages server; this setup uses the instance’s separate Pages
|
||||
Server and Actions deployment path.
|
||||
|
||||
For the complete authoring, verification, publication, rollback, worktree, and
|
||||
skill workflow, see [docs/operations-guide.md](docs/operations-guide.md).
|
||||
|
||||
## Reader voting on the skills-review desk
|
||||
|
||||
`skills-review/` is static, so its "which draft would you ship?" vote widget
|
||||
calls a separate stateful service — a small Go API on its own pod, one vote per
|
||||
visitor enforced server-side by IP (a MAC address is never visible to a server
|
||||
across the internet, so it cannot be used). Its source no longer lives in this
|
||||
repository; the deployed service is unchanged. `src/pages/skills-review.astro`
|
||||
sets `window.SKILLS_REVIEW_VOTE_API` to point at it.
|
||||
|
||||
## Research
|
||||
|
||||
See [docs/references/README.md](docs/references/README.md) for official Claude,
|
||||
Codex, and Git documentation. The
|
||||
[additional reading path](docs/references/additional-reading.md) bundles 12
|
||||
verified articles and guides, including Medium and practitioner sources. See
|
||||
[model routing](docs/references/model-routing.md) for current provider controls
|
||||
and [verified skill sources](docs/references/skill-sources.md) for commit-pinned
|
||||
provenance.
|
||||
Codex, and Git documentation. The [additional reading path](docs/references/additional-reading.md)
|
||||
bundles 12 verified articles and guides, including Medium and practitioner sources.
|
||||
See [model routing](docs/references/model-routing.md) for current provider controls
|
||||
and [verified skill sources](docs/references/skill-sources.md) for commit-pinned provenance.
|
||||
|
||||
## Rules and enforcement case study
|
||||
|
||||
Open `/rules/` for a concise walkthrough grounded in the `netcracker/interview`
|
||||
repository. It shows how `AGENTS.md`, project-local skills, machine-readable
|
||||
repo ledgers, a UI contract ratchet, lint-staged, Husky, commitlint, specialist
|
||||
verifier agents, and PR review reinforce one another. Every example links to its
|
||||
source file in Gitea, and the page includes a copy-ready prompt for mapping the
|
||||
same layers in another repository.
|
||||
Open `/rules/` for a concise walkthrough grounded in the
|
||||
`netcracker/interview` repository. It shows how `AGENTS.md`, project-local
|
||||
skills, machine-readable repo ledgers, a UI contract ratchet, lint-staged,
|
||||
Husky, commitlint, specialist verifier agents, and PR review reinforce one
|
||||
another. Every example links to its source file in Gitea, and the page includes
|
||||
a copy-ready prompt for mapping the same layers in another repository.
|
||||
|
||||
The implementation patterns are also packaged as project-local skills in
|
||||
[skills/](skills/README.md). Use `editorial-playbook` when adding chapters or
|
||||
|
||||
@@ -0,0 +1 @@
|
||||
<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>AI For Dummies — Agents and trees</title><link rel="stylesheet" href="../chapters.css"></head><body><main><header class="top"><a href="../summary/">← ROUTE MAP</a><span>02 / AGENTS & TREES</span><a href="../full-guide/">field guide ↗</a></header><section class="hero"><p class="eyebrow">Subagent workflow</p><h1>One branch<br>per <em>hand.</em></h1><p>Agents work when roles, files, and evidence are bounded. A worktree gives each worker its own checkout while the orchestrator protects intent.</p></section><section class="pipeline"><div><p class="eyebrow">The tree</p><h2>Split at<br>the <em>seam.</em></h2></div><div class="panel"><strong>MAIN / ORCHESTRATOR</strong><code>├── agent/ui → components + visual states · ├── agent/tests → acceptance + regressions · └── agent/docs → guide + examples · merge after each leaf returns a diff and evidence</code></div></section><section class="grid"><article class="card"><b>FRAME</b><h2>Orchestrator</h2><p>Owns scope, task graph, boundaries, and integration.</p></article><article class="card"><b>HAND OFF</b><h2>Worker</h2><p>Owns one coherent slice and one worktree.</p></article><article class="card"><b>PROVE</b><h2>Verifier</h2><p>Re-runs gates and reports remaining gaps.</p></article></section><section class="practice"><div><p class="eyebrow">Handoff</p><h2>Context that<br>can <em>travel.</em></h2></div><div class="steps"><article><b>01</b><div><strong>Brief</strong><span>Goal, owned files, dependencies, non-goals, acceptance.</span></div></article><article><b>02</b><div><strong>Isolation</strong><span>One branch and worktree per independent change.</span></div></article><article><b>03</b><div><strong>Evidence</strong><span>Commands, result, changed files, screenshots, gaps.</span></div></article></div></section><nav class="links"><a href="../models/">Previous: models →</a><a href="../rules/">Rules case study →</a><a href="../hands-on/rules/">Try the rules lab →</a></nav></main></body></html>
|
||||
@@ -0,0 +1,411 @@
|
||||
const phases = {
|
||||
plan: { model: { en: 'OPUS / REASONING', pt: 'OPUS / RACIOCÍNIO' }, title: { en: 'Turn ambiguity into work', pt: 'Transforme ambiguidade em trabalho' }, copy: { en: 'Inspect the repository, choose the architecture, split the request, and write acceptance criteria.', pt: 'Inspecione o repositório, escolha a arquitetura, divida o pedido e escreva critérios de aceitação.' }, code: { en: 'plan → decompose → define acceptance', pt: 'planejar → decompor → definir aceitação' } },
|
||||
build: { model: { en: 'SONNET, HAIKU, OR EQUIVALENT', pt: 'SONNET, HAIKU OU EQUIVALENTE' }, title: { en: 'Execute one bounded slice', pt: 'Execute uma fatia delimitada' }, copy: { en: 'Give each worker enough context, one responsibility, and its own worktree. Less context; less collision.', pt: 'Dê a cada worker contexto suficiente, uma responsabilidade e seu próprio worktree. Menos contexto; menos colisões.' }, code: { en: 'brief + worktree → implement → test', pt: 'brief + worktree → implementar → testar' } },
|
||||
review: { model: { en: 'STRONG MODEL OR HUMAN', pt: 'MODELO FORTE OU HUMANO' }, title: { en: 'Reconnect result to intent', pt: 'Reconecte o resultado à intenção' }, copy: { en: 'Check the diff against the original brief, run the checks, then merge, request changes, or discard.', pt: 'Compare o diff com o brief original, execute as verificações e então faça merge, peça mudanças ou descarte.' }, code: { en: 'diff + checks → review → merge / iterate', pt: 'diff + verificações → revisar → merge / iterar' } }
|
||||
};
|
||||
|
||||
const handsOnPrompts = {
|
||||
en: {
|
||||
basic: [
|
||||
'Work only in hands-on/starter. It is dependency-free HTML, CSS, and JavaScript.',
|
||||
'',
|
||||
'Add an All / Open / Done filter to Tiny Tasks.',
|
||||
'',
|
||||
'Requirements:',
|
||||
'- derive counts and visible tasks from the existing tasks array',
|
||||
'- expose filter buttons with a visible active state and aria-pressed',
|
||||
'- store status in ?status=all|open|done',
|
||||
'- reload and browser back/forward must restore the selected filter',
|
||||
'- show a useful empty state when no task matches',
|
||||
'- preserve the visual style and mobile layout',
|
||||
'- add no dependencies and change no unrelated files',
|
||||
'',
|
||||
'Verify app.js syntax and exercise every filter plus URL navigation.',
|
||||
'Return changed files, checks run, results, and remaining risk.'
|
||||
].join('\n'),
|
||||
skills: [
|
||||
'Use $ponytail-lite and $webapp-testing.',
|
||||
'Work only in hands-on/starter. It is dependency-free HTML, CSS, and JavaScript.',
|
||||
'',
|
||||
'Add an All / Open / Done filter to Tiny Tasks.',
|
||||
'',
|
||||
'Apply $ponytail-lite: inspect first, reuse the current render flow, prefer native URL and button APIs, and avoid dependencies or abstractions.',
|
||||
'Apply $webapp-testing: verify all filters, aria-pressed, reload, browser back/forward, empty state, and one mobile viewport.',
|
||||
'',
|
||||
'Acceptance:',
|
||||
'- counts and visible tasks come from the existing tasks array',
|
||||
'- ?status=all|open|done is the source of truth',
|
||||
'- invalid status falls back safely to all',
|
||||
'- style remains consistent; unrelated files remain untouched',
|
||||
'',
|
||||
'Return the smallest working diff and concrete verification evidence.'
|
||||
].join('\n')
|
||||
},
|
||||
pt: {
|
||||
basic: [
|
||||
'Trabalhe apenas em hands-on/starter. É HTML, CSS e JavaScript sem dependências.',
|
||||
'',
|
||||
'Adicione um filtro Todos / Abertos / Concluídos ao Tiny Tasks.',
|
||||
'',
|
||||
'Requisitos:',
|
||||
'- derive contagens e tarefas visíveis do array tasks existente',
|
||||
'- use botões com estado ativo visível e aria-pressed',
|
||||
'- salve o status em ?status=all|open|done',
|
||||
'- reload e voltar/avançar devem restaurar o filtro',
|
||||
'- mostre estado vazio quando nenhuma tarefa corresponder',
|
||||
'- preserve o visual e layout mobile',
|
||||
'- não adicione dependências nem altere arquivos não relacionados',
|
||||
'',
|
||||
'Verifique a sintaxe de app.js e teste filtros e navegação por URL.',
|
||||
'Retorne arquivos alterados, checks, resultados e risco restante.'
|
||||
].join('\n'),
|
||||
skills: [
|
||||
'Use $ponytail-lite e $webapp-testing.',
|
||||
'Trabalhe apenas em hands-on/starter. É HTML, CSS e JavaScript sem dependências.',
|
||||
'',
|
||||
'Adicione um filtro Todos / Abertos / Concluídos ao Tiny Tasks.',
|
||||
'',
|
||||
'Aplique $ponytail-lite: inspecione primeiro, reutilize o render atual, prefira APIs nativas de URL e button e evite dependências ou abstrações.',
|
||||
'Aplique $webapp-testing: verifique filtros, aria-pressed, reload, voltar/avançar, estado vazio e um viewport mobile.',
|
||||
'',
|
||||
'Aceitação:',
|
||||
'- contagens e tarefas visíveis vêm do array tasks existente',
|
||||
'- ?status=all|open|done é a fonte de verdade',
|
||||
'- status inválido volta com segurança para all',
|
||||
'- estilo consistente; nenhum arquivo não relacionado alterado',
|
||||
'',
|
||||
'Retorne o menor diff funcional e evidências concretas de verificação.'
|
||||
].join('\n')
|
||||
}
|
||||
};
|
||||
|
||||
const modelGuide = {
|
||||
providers: {
|
||||
openai: {
|
||||
label: 'OpenAI', source: 'https://developers.openai.com/api/docs/guides/latest-model',
|
||||
title: { en: 'Sol · Terra · Luna', pt: 'Sol · Terra · Luna' },
|
||||
copy: { en: 'GPT-5.6 separates capability tier from reasoning effort. Sol is flagship, Terra balances performance and cost, and Luna targets efficient high-volume work.', pt: 'O GPT-5.6 separa o nível de capacidade do esforço de raciocínio. Sol é flagship, Terra equilibra desempenho e custo, e Luna atende trabalho eficiente em alto volume.' },
|
||||
tiers: [
|
||||
['STRONG', 'Sol', { en: 'orchestration + hard judgment', pt: 'orquestração + julgamento difícil' }],
|
||||
['BALANCED', 'Terra', { en: 'normal implementation', pt: 'implementação normal' }],
|
||||
['FAST', 'Luna', { en: 'bounded, high-volume work', pt: 'trabalho delimitado e volumoso' }]
|
||||
],
|
||||
config: 'reasoning: { effort: "medium" }'
|
||||
},
|
||||
claude: {
|
||||
label: 'Claude', source: 'https://docs.anthropic.com/en/docs/claude-code/model-config',
|
||||
title: { en: 'Opus · Sonnet · Haiku', pt: 'Opus · Sonnet · Haiku' },
|
||||
copy: { en: 'Claude Code exposes memorable aliases. Opus handles complex reasoning, Sonnet everyday coding, and Haiku simple fast work. The opusplan alias can plan with Opus and execute with Sonnet.', pt: 'Claude Code oferece aliases fáceis de lembrar. Opus cuida de raciocínio complexo, Sonnet do código cotidiano e Haiku de trabalho simples e rápido. O alias opusplan pode planejar com Opus e executar com Sonnet.' },
|
||||
tiers: [
|
||||
['STRONG', 'Opus', { en: 'planning + architecture', pt: 'planejamento + arquitetura' }],
|
||||
['BALANCED', 'Sonnet', { en: 'everyday coding', pt: 'código cotidiano' }],
|
||||
['FAST', 'Haiku', { en: 'simple, fast tasks', pt: 'tarefas simples e rápidas' }]
|
||||
],
|
||||
config: '/model opus · /model sonnet · /model haiku'
|
||||
},
|
||||
gemini: {
|
||||
label: 'Gemini', source: 'https://ai.google.dev/gemini-api/docs/thinking',
|
||||
title: { en: 'Pro · Flash · Flash-Lite', pt: 'Pro · Flash · Flash-Lite' },
|
||||
copy: { en: 'Gemini uses model families rather than interchangeable aliases. Pro targets complex reasoning, Flash balances capability and throughput, and Flash-Lite prioritizes latency and cost.', pt: 'Gemini usa famílias de modelos, não aliases intercambiáveis. Pro mira raciocínio complexo, Flash equilibra capacidade e throughput, e Flash-Lite prioriza latência e custo.' },
|
||||
tiers: [
|
||||
['STRONG', 'Pro', { en: 'complex reasoning', pt: 'raciocínio complexo' }],
|
||||
['BALANCED', 'Flash', { en: 'capability + throughput', pt: 'capacidade + throughput' }],
|
||||
['FAST', 'Flash-Lite', { en: 'latency + cost', pt: 'latência + custo' }]
|
||||
],
|
||||
config: 'thinkingConfig: { thinkingLevel: "MEDIUM" }'
|
||||
}
|
||||
},
|
||||
efforts: {
|
||||
low: { en: ['LOW', 'Use for formatting, lookup, narrow edits, and well-specified worker tasks. Optimize for fast feedback.', 'bounded task → low'], pt: ['BAIXO', 'Use para formatação, consulta, edições estreitas e tarefas de worker bem especificadas. Otimize para feedback rápido.', 'tarefa delimitada → baixo'] },
|
||||
medium: { en: ['MEDIUM', 'Balanced starting point for normal implementation, tests, and review. Measure before moving up.', 'normal build → medium'], pt: ['MÉDIO', 'Ponto inicial equilibrado para implementação normal, testes e revisão. Meça antes de subir.', 'build normal → médio'] },
|
||||
high: { en: ['HIGH', 'Use for architecture, orchestration, hard debugging, and consequential review where added latency is justified.', 'ambiguity + risk → high'], pt: ['ALTO', 'Use para arquitetura, orquestração, diagnóstico difícil e revisão importante quando a latência extra se justifica.', 'ambiguidade + risco → alto'] }
|
||||
}
|
||||
};
|
||||
|
||||
const skillSources = {
|
||||
ponytail: 'https://github.com/ilindaniel/ponytail-lite/blob/e7b42dc2d384a702240dea4d52a7bf5530b821b6/AGENTS.md',
|
||||
caveman: 'https://github.com/JuliusBrussee/caveman/blob/3b74643f4d910f496babd4e634b1ba7168816f14/skills/caveman/SKILL.md',
|
||||
unlazy: 'https://github.com/Leonxlnx/unlazy/blob/473d4b80421c36d733042434cd4b938f81a19ef1/SKILL.md',
|
||||
research: 'https://github.com/mattpocock/skills/blob/6654f6b60cd9d5be8b54c6fafe44346dabeb3b76/skills/engineering/research/SKILL.md',
|
||||
debug: 'https://github.com/mattpocock/skills/blob/6654f6b60cd9d5be8b54c6fafe44346dabeb3b76/skills/engineering/diagnosing-bugs/SKILL.md',
|
||||
review: 'https://github.com/mattpocock/skills/blob/6654f6b60cd9d5be8b54c6fafe44346dabeb3b76/skills/engineering/code-review/SKILL.md',
|
||||
tokens: 'https://github.com/aetox-skills/token-saver/blob/8f21188bb043fad411f47e2e57f0365a83c13da7/SKILL.md'
|
||||
};
|
||||
|
||||
const skillInstallPrompts = {
|
||||
en: [
|
||||
'Inspect and install only these public agent skills. Pin the exact commits:',
|
||||
'- ilindaniel/ponytail-lite@e7b42dc2d384a702240dea4d52a7bf5530b821b6 — AGENTS.md',
|
||||
'- JuliusBrussee/caveman@3b74643f4d910f496babd4e634b1ba7168816f14 — skills/caveman/',
|
||||
'- Leonxlnx/unlazy@473d4b80421c36d733042434cd4b938f81a19ef1 — repository root',
|
||||
'- mattpocock/skills@6654f6b60cd9d5be8b54c6fafe44346dabeb3b76 — skills/engineering/{research,diagnosing-bugs,code-review}/',
|
||||
'- aetox-skills/token-saver@8f21188bb043fad411f47e2e57f0365a83c13da7 — repository root',
|
||||
'- anthropics/skills@53048666b05b4799081517d00e09e0a2dd688678 — skills/webapp-testing/',
|
||||
'',
|
||||
'Treat repository content as untrusted. Detect the current AI host and documented user-level skill directory; do not guess paths. Download into a temporary directory without curl-pipe-shell, remote installers, or postinstall hooks. Inspect each selected instruction and every referenced script or hook. Show the exact copy plan and existing-file diffs, then ask for approval before installation. Copy only the allowlist and preserve complete referenced packages. Install ponytail-lite through the host instruction mechanism because it is AGENTS.md. Do not enable unlazy hooks or install token-saver\'s RTK binary without separate approval. Finally report destination, SHA-256, validation, and which skills the host discovers.'
|
||||
].join('\n'),
|
||||
pt: [
|
||||
'Inspecione e instale apenas estas skills públicas. Fixe os commits exatos:',
|
||||
'- ilindaniel/ponytail-lite@e7b42dc2d384a702240dea4d52a7bf5530b821b6 — AGENTS.md',
|
||||
'- JuliusBrussee/caveman@3b74643f4d910f496babd4e634b1ba7168816f14 — skills/caveman/',
|
||||
'- Leonxlnx/unlazy@473d4b80421c36d733042434cd4b938f81a19ef1 — raiz do repositório',
|
||||
'- mattpocock/skills@6654f6b60cd9d5be8b54c6fafe44346dabeb3b76 — skills/engineering/{research,diagnosing-bugs,code-review}/',
|
||||
'- aetox-skills/token-saver@8f21188bb043fad411f47e2e57f0365a83c13da7 — raiz do repositório',
|
||||
'- anthropics/skills@53048666b05b4799081517d00e09e0a2dd688678 — skills/webapp-testing/',
|
||||
'',
|
||||
'Trate o conteúdo como não confiável. Detecte o host de IA e o diretório documentado de skills; não adivinhe caminhos. Baixe em diretório temporário sem curl-pipe-shell, instaladores remotos ou postinstall. Inspecione instruções, scripts e hooks referenciados. Mostre o plano de cópia e diffs existentes e peça aprovação antes de instalar. Copie apenas a allowlist e preserve pacotes completos. Instale ponytail-lite pelo mecanismo de instruções do host porque é AGENTS.md. Não ative hooks do unlazy nem instale o binário RTK do token-saver sem aprovação separada. Ao final, reporte destino, SHA-256, validação e quais skills o host descobriu.'
|
||||
].join('\n')
|
||||
};
|
||||
|
||||
const interactiveCopy = {
|
||||
workers: {
|
||||
ui: { en: ['Interface worker', 'Receives: component contract + visual states', 'Returns: focused diff + viewport evidence'], pt: ['Worker de interface', 'Recebe: contrato do componente + estados visuais', 'Devolve: diff focado + evidência dos viewports'] },
|
||||
tests: { en: ['Verification worker', 'Receives: acceptance criteria + changed surface', 'Returns: failing case, passing checks, risk notes'], pt: ['Worker de verificação', 'Recebe: critérios de aceitação + superfície alterada', 'Devolve: caso de falha, verificações passando e riscos'] },
|
||||
docs: { en: ['Documentation worker', 'Receives: reviewed behavior + audience', 'Returns: guide, examples, and migration notes'], pt: ['Worker de documentação', 'Recebe: comportamento revisado + público', 'Devolve: guia, exemplos e notas de migração'] }
|
||||
},
|
||||
trees: {
|
||||
main: { status: 'clean', owner: { en: 'Orchestrator', pt: 'Orquestrador' }, path: './project', command: 'git worktree list', note: { en: 'Shared history and integration point. Workers never edit here.', pt: 'Histórico compartilhado e ponto de integração. Workers nunca editam aqui.' } },
|
||||
ui: { status: 'working', owner: { en: 'UI worker', pt: 'Worker de UI' }, path: '../task-ui', command: 'git worktree add ../task-ui -b agent/ui', note: { en: 'Own checkout and index. Safe to change presentation files in parallel.', pt: 'Checkout e índice próprios. Seguro para alterar a apresentação em paralelo.' } },
|
||||
tests: { status: 'ready', owner: { en: 'Test worker', pt: 'Worker de testes' }, path: '../task-tests', command: 'git diff main...agent/tests', note: { en: 'Checks are green. Review the diff before merging into main.', pt: 'Verificações passaram. Revise o diff antes do merge em main.' } },
|
||||
docs: { status: 'review', owner: { en: 'Docs worker', pt: 'Worker de docs' }, path: '../task-docs', command: 'git merge --no-ff agent/docs', note: { en: 'Review requested. Merge, request changes, or discard without touching another checkout.', pt: 'Revisão solicitada. Faça merge, peça mudanças ou descarte sem tocar em outro checkout.' } }
|
||||
},
|
||||
routes: {
|
||||
plan: { score: 92, label: { en: 'High ambiguity', pt: 'Alta ambiguidade' }, why: { en: 'Architecture and decomposition have a wide error surface. Spend reasoning here.', pt: 'Arquitetura e decomposição têm grande superfície de erro. Invista raciocínio aqui.' } },
|
||||
build: { score: 38, label: { en: 'Bounded execution', pt: 'Execução delimitada' }, why: { en: 'The brief already removed ambiguity. Optimize for speed and tight feedback.', pt: 'O brief já removeu a ambiguidade. Otimize para velocidade e feedback curto.' } },
|
||||
explore: { score: 22, label: { en: 'Read-only discovery', pt: 'Descoberta somente leitura' }, why: { en: 'Search, map, and report. A lightweight model can return facts without editing.', pt: 'Busque, mapeie e reporte. Um modelo leve devolve fatos sem editar.' } },
|
||||
review: { score: 74, label: { en: 'Independent judgment', pt: 'Julgamento independente' }, why: { en: 'Reconnect the diff to intent with fresh context and adversarial attention.', pt: 'Reconecte o diff à intenção com contexto novo e atenção crítica.' } }
|
||||
},
|
||||
skillFiles: {
|
||||
skill: { icon: '◇', title: 'SKILL.md', en: 'Trigger, procedure, constraints, and the exact evidence the agent must return.', pt: 'Gatilho, procedimento, restrições e a evidência exata que o agente deve devolver.' },
|
||||
references: { icon: '≡', title: 'references/', en: 'Stable facts loaded only when the procedure needs them. Keep the main instruction lean.', pt: 'Fatos estáveis carregados apenas quando o procedimento precisa. Mantenha a instrução principal enxuta.' },
|
||||
scripts: { icon: '›_', title: 'scripts/', en: 'Deterministic checks and repeated operations. Prefer executable proof over prose.', pt: 'Verificações determinísticas e operações repetidas. Prefira prova executável a prosa.' },
|
||||
assets: { icon: '▧', title: 'assets/', en: 'Templates and examples the agent can copy without reinventing the expected shape.', pt: 'Templates e exemplos que o agente pode copiar sem reinventar o formato esperado.' }
|
||||
},
|
||||
skillWorkflow: {
|
||||
observe: { number: '01', title: { en: 'Start from repeated friction', pt: 'Comece pelo atrito repetido' }, question: { en: 'Which non-obvious decision keeps being rediscovered?', pt: 'Qual decisão não óbvia continua sendo redescoberta?' }, action: { en: 'Collect two or three realistic requests. Separate durable judgment from one project’s temporary details.', pt: 'Colete dois ou três pedidos realistas. Separe julgamento durável dos detalhes temporários de um projeto.' }, output: { en: 'A narrow capability and concrete examples.', pt: 'Uma capacidade estreita e exemplos concretos.' }, proof: { en: 'Without the skill, agents repeatedly make the same avoidable mistake.', pt: 'Sem a skill, agentes repetem o mesmo erro evitável.' } },
|
||||
trigger: { number: '02', title: { en: 'Make discovery precise', pt: 'Torne a descoberta precisa' }, question: { en: 'When should this load—and when should it stay out?', pt: 'Quando isto deve carregar — e quando deve ficar de fora?' }, action: { en: 'Choose a short action-oriented name. Write a discriminating description that names the task and meaningful boundary.', pt: 'Escolha um nome curto orientado à ação. Escreva uma descrição discriminante que nomeie a tarefa e seu limite.' }, output: { en: 'YAML name + description in SKILL.md.', pt: 'Nome + descrição YAML em SKILL.md.' }, proof: { en: 'Relevant prompts select it; nearby unrelated prompts do not.', pt: 'Prompts relevantes selecionam; prompts próximos mas não relacionados, não.' } },
|
||||
scaffold: { number: '03', title: { en: 'Choose only useful anatomy', pt: 'Escolha apenas a anatomia útil' }, question: { en: 'What must be instructions, executable, consulted, or copied?', pt: 'O que deve ser instrução, executável, consultado ou copiado?' }, action: { en: 'Keep shared guidance in SKILL.md. Add scripts for repeated deterministic work, references for conditional facts, and assets for generated output.', pt: 'Mantenha orientação comum em SKILL.md. Adicione scripts para trabalho determinístico, referências para fatos condicionais e assets para saída.' }, output: { en: 'Smallest folder structure that supports the workflow.', pt: 'A menor estrutura de pastas que sustenta o fluxo.' }, proof: { en: 'Every file has a real caller; no placeholder directories.', pt: 'Cada arquivo tem um consumidor real; nenhuma pasta placeholder.' } },
|
||||
write: { number: '04', title: { en: 'Write what changes decisions', pt: 'Escreva o que muda decisões' }, question: { en: 'What would a capable agent still get wrong?', pt: 'O que um agente capaz ainda erraria?' }, action: { en: 'State outcome, non-obvious constraints, routing, and stopping conditions. Remove generic advice, duplicate facts, and speculative rules.', pt: 'Declare resultado, restrições não óbvias, roteamento e condições de parada. Remova conselhos genéricos, fatos duplicados e regras especulativas.' }, output: { en: 'Lean SKILL.md with progressive links.', pt: 'SKILL.md enxuto com links progressivos.' }, proof: { en: 'Another agent can act correctly without loading irrelevant detail.', pt: 'Outro agente consegue agir corretamente sem carregar detalhes irrelevantes.' } },
|
||||
validate: { number: '05', title: { en: 'Test behavior, then sharpen', pt: 'Teste comportamento, depois refine' }, question: { en: 'Did the skill improve a realistic outcome?', pt: 'A skill melhorou um resultado realista?' }, action: { en: 'Run structural validation, execute every new script, and forward-test realistic requests. Fix observed failures with the narrowest rule.', pt: 'Execute validação estrutural, rode cada script novo e teste pedidos realistas. Corrija falhas observadas com a regra mais estreita.' }, output: { en: 'Validated package plus evidence from real use.', pt: 'Pacote validado mais evidência de uso real.' }, proof: { en: 'quick_validate passes and behavior improves without unrelated side effects.', pt: 'quick_validate passa e o comportamento melhora sem efeitos colaterais.' } }
|
||||
},
|
||||
commonSkills: {
|
||||
ponytail: { number: '01', kind: { en: 'SIMPLIFICATION INSTINCT', pt: 'INSTINTO DE SIMPLIFICAÇÃO' }, title: 'ponytail-lite', rule: { en: 'Stop at the first rung that holds.', pt: 'Pare no primeiro degrau que sustenta.' }, use: { en: 'Use when a request invites frameworks, dependencies, abstractions, or speculative scaffolding. It checks reuse, standard library, and native platform features before adding code.', pt: 'Use quando um pedido convida frameworks, dependências, abstrações ou scaffolding especulativo. Verifica reúso, biblioteca padrão e recursos nativos antes de adicionar código.' }, example: { en: 'Date picker? Start with <input type="date">.', pt: 'Seletor de data? Comece com <input type="date">.' }, caution: { en: 'Never simplify away security, accessibility, validation, or real edge cases.', pt: 'Nunca simplifique segurança, acessibilidade, validação ou casos extremos reais.' } },
|
||||
caveman: { number: '02', kind: { en: 'COMMUNICATION STYLE', pt: 'ESTILO DE COMUNICAÇÃO' }, title: 'caveman', rule: { en: 'Signal first. Drop filler.', pt: 'Sinal primeiro. Corte o excesso.' }, use: { en: 'Use for routine status, handoffs, and technical summaries where speed matters. Short fragments make actions and evidence easy to scan.', pt: 'Use em status, handoffs e resumos técnicos rotineiros onde velocidade importa. Fragmentos curtos facilitam localizar ações e evidências.' }, example: { en: 'Built. Tests pass. Published.', pt: 'Feito. Testes passaram. Publicado.' }, caution: { en: 'Drop the style for security warnings, irreversible actions, and sequences where terse wording can be misread.', pt: 'Abandone o estilo em alertas de segurança, ações irreversíveis e sequências onde concisão pode causar erro.' } },
|
||||
unlazy: { number: '03', kind: { en: 'COMPLETION DISCIPLINE', pt: 'DISCIPLINA DE CONCLUSÃO' }, title: 'unlazy', rule: { en: 'Define observable gates. Finish against evidence.', pt: 'Defina gates observáveis. Termine com evidências.' }, use: { en: 'Use for substantial autonomous builds, audits, and parallel work where quiet omissions are expensive. It turns “done” into runnable acceptance checks.', pt: 'Use em builds autônomos grandes, auditorias e trabalho paralelo onde omissões custam caro. Transforma “pronto” em verificações executáveis.' }, example: { en: 'Gate: language toggle persists. Check: browser reload. Expect: pt-BR.', pt: 'Gate: idioma persiste. Check: recarregar navegador. Esperado: pt-BR.' }, caution: { en: 'Too heavy for trivial edits or factual answers.', pt: 'Pesado demais para edições triviais ou respostas factuais.' } },
|
||||
research: { number: '04', kind: { en: 'SOURCE DISCIPLINE', pt: 'DISCIPLINA DE FONTES' }, title: 'research', rule: { en: 'Trace claims to owners.', pt: 'Leve afirmações até suas fontes.' }, use: { en: 'Use when APIs, standards, architecture facts, or current behavior must be verified. Capture findings in a cited note, prioritizing primary sources.', pt: 'Use quando APIs, padrões, fatos de arquitetura ou comportamento atual precisam ser verificados. Registre achados citados, priorizando fontes primárias.' }, example: { en: 'Git behavior → git-scm.com docs, not a remembered blog summary.', pt: 'Comportamento do Git → documentação git-scm.com, não memória de um blog.' }, caution: { en: 'Practitioner articles add context; they do not override official behavior.', pt: 'Artigos de praticantes dão contexto; não substituem comportamento oficial.' } },
|
||||
debug: { number: '05', kind: { en: 'DIAGNOSTIC LOOP', pt: 'CICLO DE DIAGNÓSTICO' }, title: 'diagnosing-bugs', rule: { en: 'No red-capable loop, no theory.', pt: 'Sem ciclo capaz de falhar, sem teoria.' }, use: { en: 'Use for hard bugs, flakes, and regressions. First build a fast deterministic reproduction, then minimize, rank hypotheses, instrument, and fix the root cause.', pt: 'Use para bugs difíceis, flakes e regressões. Primeiro crie reprodução rápida e determinística; depois minimize, ranqueie hipóteses, instrumente e corrija a causa raiz.' }, example: { en: 'One command reproduces the exact symptom before any fix.', pt: 'Um comando reproduz o sintoma exato antes de qualquer correção.' }, caution: { en: 'Do not jump from error message straight to a patch.', pt: 'Não pule da mensagem de erro direto para um patch.' } },
|
||||
review: { number: '06', kind: { en: 'INDEPENDENT REVIEW', pt: 'REVISÃO INDEPENDENTE' }, title: 'code-review', rule: { en: 'Check standards and intent separately.', pt: 'Verifique padrões e intenção separadamente.' }, use: { en: 'Use on a branch or PR. One axis checks repository standards; another checks whether the change actually satisfies its originating specification.', pt: 'Use em branch ou PR. Um eixo verifica padrões do repositório; outro verifica se a mudança realmente satisfaz a especificação original.' }, example: { en: 'Clean code can still solve the wrong problem.', pt: 'Código limpo ainda pode resolver o problema errado.' }, caution: { en: 'Pin the comparison point and source specification before reviewing.', pt: 'Fixe o ponto de comparação e a especificação antes de revisar.' } },
|
||||
tokens: { number: '07', kind: { en: 'CONTEXT ECONOMY', pt: 'ECONOMIA DE CONTEXTO' }, title: 'token-saver', rule: { en: 'Keep signal. Strip command noise.', pt: 'Mantenha sinal. Corte ruído de comandos.' }, use: { en: 'Use around verbose tests, builds, Git output, and logs. Filtering preserves context for reasoning while retaining full failure output for recovery.', pt: 'Use em testes, builds, saídas Git e logs verbosos. Filtragem preserva contexto para raciocínio e mantém falhas completas para recuperação.' }, example: { en: '200 passing-test lines → one result; failures keep their trace.', pt: '200 linhas de testes passando → um resultado; falhas mantêm o trace.' }, caution: { en: 'Read raw output when exact wording or full diffs matter.', pt: 'Leia saída bruta quando texto exato ou diffs completos importarem.' } }
|
||||
}
|
||||
};
|
||||
|
||||
const translations = {
|
||||
pt: {
|
||||
'.chapter-links a:nth-child(1)': '01 frota', '.chapter-links a:nth-child(2)': '02 worktrees', '.chapter-links a:nth-child(3)': '03 modelos', '.chapter-links a:nth-child(4)': '04 skills', '.chapter-links a:nth-child(5)': '05 criar', '.chapter-links a:nth-child(6)': '06 kit de campo', '.chapter-links a:nth-child(7)': '07 prática', '.edition': 'ENGENHARIA DE IA <i></i> 01 / 2026',
|
||||
'.hero .eyebrow': 'Uma apresentação para quem entrega software', '.lede': 'Você não precisa de um exército de modelos. Precisa de um sistema: uma mente para enquadrar o trabalho, várias mãos para executá-lo e uma fronteira clara entre cada tarefa.', '.hero-index span': 'NOTA DE CAMPO / 001', '.hero-index strong': 'Entregue o<br /><em>sistema.</em>', '.hero-index small': 'Skills · agentes · worktrees · evidências',
|
||||
'.hero-stats div:nth-child(1) span': 'modelo forte<br />para ambiguidade', '.hero-stats div:nth-child(2) span': 'workers delimitados<br />em paralelo', '.hero-stats div:nth-child(3) span': 'iterações<br />com evidências', '.hero-stats p': 'Leia isto como um mapa de rota, não como uma receita de prompt.',
|
||||
'.thesis span': 'REGRA ZERO', '.thesis strong': 'Modelo forte para ambiguidade.<br />Modelo leve para trabalho delimitado.', '.fleet .section-label span:nth-child(1)': 'Uma pequena frota', '.fleet .section-label span:nth-child(2)': 'coordenação antes do paralelismo', '.captain span': 'ORQUESTRADOR', '.captain h2': 'Decide o que<br />precisa acontecer.', '.worker-card[data-worker="ui"] strong': 'Componentes e estados visuais', '.worker-card[data-worker="tests"] strong': 'Casos de aceitação', '.worker-card[data-worker="docs"] strong': 'Guia e exemplos', '.caption': 'O orquestrador preserva a intenção, escreve pequenos contratos e reúne resultados verificáveis. Ele não precisa digitar cada linha.',
|
||||
'.failure-map .section-label span:nth-child(1)': 'Por que a fronteira importa', '.failure-map .section-label span:nth-child(2)': 'uma tarefa vaga / três falhas previsíveis', '.failure-grid article:nth-child(1) strong': 'Sopa de contexto', '.failure-grid article:nth-child(1) p': 'Cada worker lê tudo. Ninguém sabe quais fatos são essenciais.', '.failure-grid article:nth-child(2) strong': 'Colisão de branches', '.failure-grid article:nth-child(2) p': 'Dois agentes usam o mesmo checkout. O caminho mais rápido vira resolução de conflitos.', '.failure-grid article:nth-child(3) strong': 'Desvio confiante', '.failure-grid article:nth-child(3) p': 'O diff parece ótimo, mas ninguém verifica se resolveu o problema original.',
|
||||
'.workflow .eyebrow': 'O ciclo de subagentes', '#workflow-title': 'Clique em uma fase.<br /><em>Veja a passagem.</em>', '.workflow .copy > p:last-child': 'Delegar é mover uma tarefa delimitada para um contexto menor — não abrir mão da responsabilidade.', '.handoff .section-label span:nth-child(1)': 'O que atravessa contextos', '.handoff .section-label span:nth-child(2)': 'brief → diff → evidência', '.handoff thead th:nth-child(1)': 'Pacote', '.handoff thead th:nth-child(2)': 'Contém', '.handoff thead th:nth-child(3)': 'Por que importa',
|
||||
'.worktrees .eyebrow': 'Git worktrees', '.worktrees h2': 'Uma branch<br />por <em>mão.</em>', '.worktree-intro > p:nth-of-type(2)': 'Um worktree é outro diretório ligado ao mesmo repositório. Cada agente recebe seu próprio checkout e índice; o histórico continua compartilhado.', '.worktree-intro .interaction-hint': 'Selecione um nó para inspecionar checkout, responsável e próxima ação.', '.tree-toolbar > span:first-child': 'topologia do repositório', '.tree-live': '<i></i> 4 checkouts', '.tree-node.root span': 'RAIZ', '.tree-node.ui span': 'AGENTE DE UI', '.tree-node.tests span': 'AGENTE DE TESTES', '.tree-node.docs span': 'AGENTE DE DOCS', '.tree-node.root small': '● limpo', '.tree-node.ui small': '3 arquivos · trabalhando', '.tree-node.tests small': '8 verificações · pronto', '.tree-node.docs small': '2 páginas · revisão', '.routing .eyebrow': 'Roteamento de modelos', '.routing h2': 'Não pague por<br />raciocínio onde precisa<br />de <em>ritmo.</em>', '.routing .interaction-hint': 'Escolha um trabalho para entender por que o perfil do modelo muda.', '.route-table .head span:nth-child(1)': 'Trabalho', '.route-table .head span:nth-child(2)': 'Perfil', '.route-table .head span:nth-child(3)': 'Formato do prompt', '.route-table [data-route="plan"] strong': 'Planejar', '.route-table [data-route="build"] strong': 'Construir', '.route-table [data-route="explore"] strong': 'Explorar', '.route-table [data-route="review"] strong': 'Revisar', '.skills .eyebrow': 'Skills', '.skills h2': 'Escreva do jeito certo<br /><em>uma vez.</em>', '.skills > div:first-child > p': 'Uma skill é um procedimento reutilizável. Ela pode carregar instruções, referências, scripts e assets. Não é memória mágica e não substitui critérios de aceitação.',
|
||||
'.skill-principles span:nth-child(1)': '01 / defina o gatilho', '.skill-principles span:nth-child(2)': '02 / carregue detalhes sob demanda', '.skill-principles span:nth-child(3)': '03 / devolva evidências', '.skill-package > span': 'PACOTE DE SKILL', '.skill-catalog .section-label span:nth-child(1)': 'Skills comuns', '.skill-catalog .section-label span:nth-child(2)': 'escolha o comportamento antes do modelo', '.catalog-intro .eyebrow': 'O kit de campo', '.catalog-intro h2': 'Trabalhos diferentes.<br />Instintos <em>diferentes.</em>', '.catalog-intro > p': 'Uma skill muda como o agente aborda o trabalho. Algumas moldam a comunicação. Outras impõem pesquisa, diagnóstico, revisão ou disciplina de conclusão. Selecione uma para inspecionar sua regra operacional.', '[data-common-skill="ponytail"] span': 'SIMPLIFICAR', '[data-common-skill="ponytail"] small': 'código mínimo que funciona', '[data-common-skill="caveman"] span': 'COMUNICAR', '[data-common-skill="caveman"] small': 'sinal sem excesso', '[data-common-skill="unlazy"] span': 'CONCLUIR', '[data-common-skill="unlazy"] small': 'gates e evidências', '[data-common-skill="research"] span': 'INVESTIGAR', '[data-common-skill="research"] small': 'fontes primárias primeiro', '[data-common-skill="debug"] span': 'DIAGNOSTICAR', '[data-common-skill="debug"] small': 'ciclo curto de feedback', '[data-common-skill="review"] span': 'REVISAR', '[data-common-skill="review"] small': 'padrões × especificação', '[data-common-skill="tokens"] span': 'ECONOMIZAR', '[data-common-skill="tokens"] small': 'comprima saídas ruidosas', '.skill-loadout > span': 'UM LOADOUT PRÁTICO', '.skill-loadout > div': '<b>PLANEJAR</b> unlazy <i>→</i> <b>CONSTRUIR</b> ponytail-lite <i>→</i> <b>DIAGNOSTICAR</b> diagnosing-bugs <i>→</i> <b>REPORTAR</b> caveman', '.rule span': 'O PAPEL HUMANO', '.rule strong': 'O agente pode ser autônomo na execução. Intenção, limites e evidências continuam sendo seus.', '.callout span': 'COMECE AQUI', '.callout strong': 'Comece com um agente e uma skill. Adicione paralelismo apenas quando as tarefas forem realmente independentes.', '.sources .section-label span:nth-child(1)': 'Continue aprendendo', '.sources .section-label span:nth-child(2)': '12 novas leituras + documentação primária', '.sources p': 'Aprofunde com documentação oficial, casos de produção, Medium e fluxos de praticantes. <a href="rules/">Estudo de caso sobre regras e enforcement →</a> <a href="docs/references/README.md">Referências primárias →</a> <a href="docs/references/additional-reading.md">Trilha com 12 leituras →</a>'
|
||||
}
|
||||
};
|
||||
|
||||
Object.assign(translations.pt, {
|
||||
'.model-gearbox .section-label span:nth-child(1)': 'Câmbio de modelos', '.model-gearbox .section-label span:nth-child(2)': 'nível de capacidade × esforço de raciocínio',
|
||||
'.gearbox-intro .eyebrow': 'Dois controles separados', '.gearbox-intro h2': 'Escolha o motor.<br />Depois escolha a <em>marcha.</em>',
|
||||
'.gearbox-intro > p': 'Um modelo mais forte muda o teto de capacidade. Mais esforço de raciocínio dá mais espaço para esse modelo trabalhar. Comece com a combinação mais leve que passa seus checks e mova um controle por vez.',
|
||||
'.effort-rail > span': 'RACIOCÍNIO / PENSAMENTO', '[data-effort="low"] b': 'BAIXO', '[data-effort="low"] small': 'delimitado + rápido', '[data-effort="medium"] b': 'MÉDIO', '[data-effort="medium"] small': 'ponto inicial', '[data-effort="high"] b': 'ALTO', '[data-effort="high"] small': 'complexo + custoso',
|
||||
'.gearbox-rule span': 'REGRA DE ROTEAMENTO', '.gearbox-rule strong': 'Use modelos fortes para ambiguidade e julgamento. Use modelos leves para execução delimitada. Aumente o esforço apenas quando a avaliação mostrar ganho.',
|
||||
'.skill-builder .section-label span:nth-child(1)': 'Criar uma skill',
|
||||
'.skill-builder .section-label span:nth-child(2)': 'atrito repetido → julgamento reutilizável',
|
||||
'.builder-intro .eyebrow': 'A forja de skills',
|
||||
'.builder-intro h2': 'Ensine a decisão.<br />Mantenha o contexto <em>leve.</em>',
|
||||
'.builder-intro > p': 'Não empacote tudo o que você sabe. Capture as escolhas não óbvias que melhoram resultados repetidamente e prove que a skill muda o comportamento.',
|
||||
'[data-skill-step="observe"] span': 'Observar', '[data-skill-step="observe"] small': 'encontre atrito repetido',
|
||||
'[data-skill-step="trigger"] span': 'Definir gatilho', '[data-skill-step="trigger"] small': 'roteie com precisão',
|
||||
'[data-skill-step="scaffold"] span': 'Escolher anatomia', '[data-skill-step="scaffold"] small': 'apenas arquivos necessários',
|
||||
'[data-skill-step="write"] span': 'Escrever orientação', '[data-skill-step="write"] small': 'decisões, não trivialidades',
|
||||
'[data-skill-step="validate"] span': 'Validar', '[data-skill-step="validate"] small': 'teste comportamento real',
|
||||
'.artifact-head span': 'SAÍDA / PACOTE DE SKILL', '.artifact-command span': 'VALIDAR',
|
||||
'.builder-loop > span': 'APÓS USO REAL',
|
||||
'.builder-loop > div': '<b>observar falha</b><i>→</i><b>refinar uma regra</b><i>→</i><b>retestar comportamento</b><i>→</i><b>manter estreita</b>',
|
||||
'.install-skills header span': 'PACOTE DE INSTALAÇÃO', '.install-skills header strong': 'Peça ao seu agente para verificar, instalar e validar as skills.',
|
||||
'.install-skills footer': 'Revise cada fonte antes da instalação. Skills locais existentes devem ser preservadas.',
|
||||
'.hands-on .section-label span:nth-child(1)': 'Prática', '.hands-on .section-label span:nth-child(2)': '10 minutos / uma feature ausente',
|
||||
'.hands-intro .eyebrow': 'Laboratório Tiny Tasks', '.hands-intro h2': 'Mesma tarefa.<br />Melhor <em>sistema operacional.</em>',
|
||||
'.hands-intro > div:last-child > p': 'Comece com um quadro estático propositalmente incompleto. Execute um prompt, restaure e execute a versão com skills. Compare tamanho do diff, evidências e complexidade desnecessária.',
|
||||
'.starter-link': 'Abrir o projeto inicial →', '.exercise-brief > span': 'A FEATURE AUSENTE',
|
||||
'.exercise-brief > strong': 'Adicione filtros Todos / Abertos / Concluídos que sobrevivem reload e navegação.',
|
||||
'.exercise-brief > div': '<b>STACK</b> HTML · CSS · JavaScript <b>DEPENDÊNCIAS</b> nenhuma <b>ARQUIVOS</b> 3',
|
||||
'.prompt-card:first-child header strong': 'Bom prompt', '.prompt-card.enhanced header strong': 'Bom prompt + skills',
|
||||
'.prompt-card:first-child footer': 'Contexto claro · restrições · aceitação · evidência', '.prompt-card.enhanced footer': 'Mesmo contrato · métodos explícitos · prova mais forte',
|
||||
'.comparison-strip > span': 'COMPARE AS EXECUÇÕES', '.comparison-strip > div:nth-child(2)': '<b>01</b> Arquivos alterados', '.comparison-strip > div:nth-child(3)': '<b>02</b> Novas dependências', '.comparison-strip > div:nth-child(4)': '<b>03</b> Checks executados', '.comparison-strip > div:nth-child(5)': '<b>04</b> Evidências retornadas'
|
||||
});
|
||||
|
||||
const panel = document.querySelector('#phase-panel');
|
||||
const buttons = document.querySelectorAll('[data-phase]');
|
||||
const originals = new Map();
|
||||
let currentLanguage = 'en';
|
||||
|
||||
function setText(selector, value) {
|
||||
const nodes = document.querySelectorAll(selector);
|
||||
if (!nodes.length) return;
|
||||
if (!originals.has(selector)) originals.set(selector, [...nodes].map((node) => node.innerHTML));
|
||||
nodes.forEach((node) => { node.innerHTML = value; });
|
||||
}
|
||||
|
||||
function render(id) {
|
||||
const phase = phases[id];
|
||||
panel.innerHTML = `<div class="phase-meta"><span>${phase.model[currentLanguage]}</span><small>${currentLanguage === 'pt' ? 'contexto: isolado' : 'context: isolated'}</small></div><h3>${phase.title[currentLanguage]}</h3><p>${phase.copy[currentLanguage]}</p><code>${phase.code[currentLanguage]}</code>`;
|
||||
buttons.forEach((button) => { const active = button.dataset.phase === id; button.classList.toggle('active', active); button.setAttribute('aria-selected', String(active)); });
|
||||
}
|
||||
|
||||
function selectButtons(selector, activeValue, key) {
|
||||
document.querySelectorAll(selector).forEach((button) => {
|
||||
const active = button.dataset[key] === activeValue;
|
||||
button.classList.toggle('active', active);
|
||||
button.setAttribute(button.hasAttribute('aria-selected') ? 'aria-selected' : 'aria-pressed', String(active));
|
||||
});
|
||||
}
|
||||
|
||||
function renderWorker(id) {
|
||||
const item = interactiveCopy.workers[id][currentLanguage];
|
||||
document.querySelector('#worker-detail').innerHTML = `<span>${item[0]}</span><strong>${item[1]}</strong><small>${item[2]}</small>`;
|
||||
selectButtons('[data-worker]', id, 'worker');
|
||||
}
|
||||
|
||||
function renderTree(id) {
|
||||
const item = interactiveCopy.trees[id];
|
||||
const language = currentLanguage;
|
||||
document.querySelector('#tree-detail').innerHTML = `<div><span>${language === 'pt' ? 'RESPONSÁVEL' : 'OWNER'}</span><strong>${item.owner[language]}</strong></div><div><span>CHECKOUT</span><strong>${item.path}</strong></div><p>${item.note[language]}</p><code>${item.command}</code>`;
|
||||
selectButtons('[data-tree]', id, 'tree');
|
||||
}
|
||||
|
||||
function renderRoute(id) {
|
||||
const item = interactiveCopy.routes[id];
|
||||
const language = currentLanguage;
|
||||
document.querySelector('#route-detail').innerHTML = `<div class="route-meter"><span style="--score:${item.score}%"></span></div><div><small>${language === 'pt' ? 'CARGA DE RACIOCÍNIO' : 'REASONING LOAD'} · ${item.score}</small><strong>${item.label[language]}</strong><p>${item.why[language]}</p></div>`;
|
||||
selectButtons('[data-route]', id, 'route');
|
||||
}
|
||||
|
||||
function renderModelProvider(id) {
|
||||
const item = modelGuide.providers[id];
|
||||
const language = currentLanguage;
|
||||
const sourceLabel = language === 'pt' ? 'FONTE OFICIAL ↗' : 'OFFICIAL SOURCE ↗';
|
||||
const kindLabels = language === 'pt' ? { STRONG: 'FORTE', BALANCED: 'EQUILÍBRIO', FAST: 'RÁPIDO' } : {};
|
||||
const tiers = item.tiers.map(([kind, name, note]) => `<div><span>${kindLabels[kind] || kind}</span><strong>${name}</strong><small>${note[language]}</small></div>`).join('');
|
||||
document.querySelector('#provider-detail').innerHTML = `<header><span>${item.label}</span><a href="${item.source}" target="_blank" rel="noopener">${sourceLabel}</a></header><h3>${item.title[language]}</h3><p>${item.copy[language]}</p><div class="model-ladder">${tiers}</div>`;
|
||||
selectButtons('[data-model-provider]', id, 'modelProvider');
|
||||
}
|
||||
|
||||
function renderEffort(id) {
|
||||
const item = modelGuide.efforts[id][currentLanguage];
|
||||
const provider = modelGuide.providers[document.querySelector('[data-model-provider].active')?.dataset.modelProvider || 'openai'];
|
||||
document.querySelector('#effort-detail').innerHTML = `<span>${item[0]}</span><p>${item[1]}</p><code>${provider.config}</code>`;
|
||||
selectButtons('[data-effort]', id, 'effort');
|
||||
}
|
||||
|
||||
function renderSkillFile(id) {
|
||||
const item = interactiveCopy.skillFiles[id];
|
||||
document.querySelector('#skill-detail').innerHTML = `<span>${item.icon}</span><div><strong>${item.title}</strong><p>${item[currentLanguage]}</p><small>${currentLanguage === 'pt' ? 'clique em outro arquivo para explorar' : 'select another file to explore'}</small></div>`;
|
||||
selectButtons('[data-skill-file]', id, 'skillFile');
|
||||
}
|
||||
|
||||
function renderSkillWorkflow(id) {
|
||||
const item = interactiveCopy.skillWorkflow[id];
|
||||
const language = currentLanguage;
|
||||
const labels = language === 'pt'
|
||||
? ['PERGUNTA', 'AÇÃO', 'ARTEFATO', 'PROVA']
|
||||
: ['QUESTION', 'ACTION', 'ARTIFACT', 'PROOF'];
|
||||
document.querySelector('#builder-detail').innerHTML = `<header><span>${item.number}</span><small>${labels[0]}</small></header><h3>${item.title[language]}</h3><blockquote>${item.question[language]}</blockquote><div class="builder-action"><span>${labels[1]}</span><p>${item.action[language]}</p></div><footer><div><span>${labels[2]}</span><strong>${item.output[language]}</strong></div><div><span>${labels[3]}</span><strong>${item.proof[language]}</strong></div></footer>`;
|
||||
selectButtons('[data-skill-step]', id, 'skillStep');
|
||||
}
|
||||
|
||||
function renderCommonSkill(id) {
|
||||
const item = interactiveCopy.commonSkills[id];
|
||||
const language = currentLanguage;
|
||||
const labels = language === 'pt'
|
||||
? ['QUANDO USAR', 'EXEMPLO', 'CUIDADO']
|
||||
: ['WHEN TO USE', 'EXAMPLE', 'WATCH OUT'];
|
||||
const sourceLabel = language === 'pt' ? 'FONTE NO GITHUB ↗' : 'GITHUB SOURCE ↗';
|
||||
document.querySelector('#common-skill-detail').innerHTML = `<header><span>${item.number}</span><small>${item.kind[language]}</small></header><h3>${item.title}</h3><blockquote>${item.rule[language]}</blockquote><div class="common-skill-notes"><div><span>${labels[0]}</span><p>${item.use[language]}</p></div><div><span>${labels[1]}</span><p>${item.example[language]}</p></div><div><span>${labels[2]}</span><p>${item.caution[language]}</p></div></div><a class="skill-source" href="${skillSources[id]}" target="_blank" rel="noopener">${sourceLabel}</a>`;
|
||||
selectButtons('[data-common-skill]', id, 'commonSkill');
|
||||
}
|
||||
|
||||
function renderHandsOn() {
|
||||
document.querySelector('#prompt-basic').textContent = handsOnPrompts[currentLanguage].basic;
|
||||
document.querySelector('#prompt-skills').textContent = handsOnPrompts[currentLanguage].skills;
|
||||
document.querySelector('#prompt-install-skills').textContent = skillInstallPrompts[currentLanguage];
|
||||
document.querySelectorAll('[data-copy-target] span').forEach((label) => { label.textContent = currentLanguage === 'pt' ? 'COPIAR' : 'COPY'; });
|
||||
}
|
||||
|
||||
async function copyPrompt(button) {
|
||||
const text = document.querySelector(`#${button.dataset.copyTarget}`).textContent;
|
||||
let copied = false;
|
||||
try {
|
||||
await navigator.clipboard.writeText(text);
|
||||
copied = true;
|
||||
} catch (error) {
|
||||
const helper = document.createElement('textarea');
|
||||
helper.value = text;
|
||||
helper.setAttribute('readonly', '');
|
||||
helper.style.position = 'fixed';
|
||||
helper.style.opacity = '0';
|
||||
document.body.appendChild(helper);
|
||||
helper.select();
|
||||
copied = document.execCommand('copy');
|
||||
helper.remove();
|
||||
}
|
||||
const status = document.querySelector('#copy-status');
|
||||
status.textContent = copied
|
||||
? (currentLanguage === 'pt' ? 'Prompt copiado. Cole em uma nova sessão de agente.' : 'Prompt copied. Paste it into a fresh agent session.')
|
||||
: (currentLanguage === 'pt' ? 'Não foi possível copiar. Selecione o texto manualmente.' : 'Copy unavailable. Select the text manually.');
|
||||
if (copied) {
|
||||
button.classList.add('copied');
|
||||
button.querySelector('span').textContent = currentLanguage === 'pt' ? 'COPIADO' : 'COPIED';
|
||||
window.setTimeout(() => { button.classList.remove('copied'); button.querySelector('span').textContent = currentLanguage === 'pt' ? 'COPIAR' : 'COPY'; }, 1800);
|
||||
}
|
||||
}
|
||||
|
||||
function renderInteractive() {
|
||||
renderWorker(document.querySelector('[data-worker].active')?.dataset.worker || 'ui');
|
||||
renderTree(document.querySelector('[data-tree].active')?.dataset.tree || 'main');
|
||||
renderRoute(document.querySelector('[data-route].active')?.dataset.route || 'plan');
|
||||
renderModelProvider(document.querySelector('[data-model-provider].active')?.dataset.modelProvider || 'openai');
|
||||
renderEffort(document.querySelector('[data-effort].active')?.dataset.effort || 'medium');
|
||||
renderSkillFile(document.querySelector('[data-skill-file].active')?.dataset.skillFile || 'skill');
|
||||
renderSkillWorkflow(document.querySelector('[data-skill-step].active')?.dataset.skillStep || 'observe');
|
||||
renderCommonSkill(document.querySelector('[data-common-skill].active')?.dataset.commonSkill || 'ponytail');
|
||||
renderHandsOn();
|
||||
}
|
||||
|
||||
function applyLanguage(language) {
|
||||
currentLanguage = language === 'pt' ? 'pt' : 'en';
|
||||
document.documentElement.lang = currentLanguage === 'pt' ? 'pt-BR' : 'en';
|
||||
if (currentLanguage === 'pt') Object.entries(translations.pt).forEach(([selector, value]) => setText(selector, value));
|
||||
else originals.forEach((values, selector) => document.querySelectorAll(selector).forEach((node, index) => { node.innerHTML = values[index]; }));
|
||||
document.querySelectorAll('[data-lang]').forEach((button) => { const active = button.dataset.lang === currentLanguage; button.classList.toggle('active', active); button.setAttribute('aria-pressed', String(active)); });
|
||||
render(document.querySelector('[data-phase].active')?.dataset.phase || 'plan');
|
||||
renderInteractive();
|
||||
try { localStorage.setItem('ai-for-dummies-language', currentLanguage); } catch (error) { /* previews may disable storage */ }
|
||||
}
|
||||
|
||||
buttons.forEach((button) => button.addEventListener('click', () => render(button.dataset.phase)));
|
||||
document.querySelectorAll('[data-lang]').forEach((button) => button.addEventListener('click', () => applyLanguage(button.dataset.lang)));
|
||||
document.querySelectorAll('[data-worker]').forEach((button) => button.addEventListener('click', () => renderWorker(button.dataset.worker)));
|
||||
document.querySelectorAll('[data-tree]').forEach((button) => button.addEventListener('click', () => renderTree(button.dataset.tree)));
|
||||
document.querySelectorAll('[data-route]').forEach((button) => button.addEventListener('click', () => renderRoute(button.dataset.route)));
|
||||
document.querySelectorAll('[data-model-provider]').forEach((button) => button.addEventListener('click', () => { renderModelProvider(button.dataset.modelProvider); renderEffort(document.querySelector('[data-effort].active')?.dataset.effort || 'medium'); }));
|
||||
document.querySelectorAll('[data-effort]').forEach((button) => button.addEventListener('click', () => renderEffort(button.dataset.effort)));
|
||||
document.querySelectorAll('[data-skill-file]').forEach((button) => button.addEventListener('click', () => renderSkillFile(button.dataset.skillFile)));
|
||||
document.querySelectorAll('[data-skill-step]').forEach((button) => button.addEventListener('click', () => renderSkillWorkflow(button.dataset.skillStep)));
|
||||
document.querySelectorAll('[data-common-skill]').forEach((button) => button.addEventListener('click', () => renderCommonSkill(button.dataset.commonSkill)));
|
||||
document.querySelectorAll('[data-copy-target]').forEach((button) => button.addEventListener('click', () => copyPrompt(button)));
|
||||
window.addEventListener('scroll', () => { const height = document.documentElement.scrollHeight - window.innerHeight; document.querySelector('.reading-progress span').style.width = `${height > 0 ? (window.scrollY / height) * 100 : 0}%`; }, { passive: true });
|
||||
|
||||
let savedLanguage = 'en';
|
||||
try { savedLanguage = localStorage.getItem('ai-for-dummies-language') || 'en'; } catch (error) { /* previews may disable storage */ }
|
||||
render('plan');
|
||||
applyLanguage(savedLanguage);
|
||||
@@ -1,6 +0,0 @@
|
||||
import { defineConfig } from 'astro/config';
|
||||
|
||||
export default defineConfig({
|
||||
base: '/ai-for-dummies',
|
||||
trailingSlash: 'always',
|
||||
});
|
||||
@@ -0,0 +1 @@
|
||||
:root{--ink:#122534;--paper:#f6f3ed;--line:#d0d5d2;--muted:#65717a;--blue:#215675;--gold:#ebbf58;--red:#a7483f}*{box-sizing:border-box}body{margin:0;color:var(--ink);background:var(--paper);font:16px/1.6 Arial,sans-serif}main{max-width:1400px;margin:auto;padding:0 5vw}.top{display:flex;justify-content:space-between;gap:20px;padding:24px 0;border-bottom:1px solid var(--line);font:700 11px monospace;letter-spacing:.08em;text-transform:uppercase}.top a{color:var(--ink);text-decoration:none}.hero{padding:100px 0 70px;max-width:950px}.eyebrow{color:var(--red);font:700 11px monospace;letter-spacing:.12em;text-transform:uppercase}.hero h1{margin:16px 0;font-size:clamp(52px,9vw,126px);line-height:.9;letter-spacing:-.07em}.hero h1 em,h2 em{font:400 .9em Georgia,serif;color:var(--red)}.hero p{max-width:680px;color:var(--muted);font-size:20px}.grid{display:grid;grid-template-columns:repeat(3,1fr);gap:1px;background:var(--line);border:1px solid var(--line);margin-bottom:100px}.card{min-height:220px;padding:28px;background:var(--paper)}.card b{color:var(--red);font:24px monospace}.card h2{margin:18px 0 8px;font-size:25px;letter-spacing:-.04em}.card p{margin:0 0 14px;color:var(--muted)}.card a{color:var(--blue);font-weight:700}.model,.pipeline,.practice{display:grid;grid-template-columns:1fr 2fr;gap:50px;padding:80px 0;border-top:1px solid var(--line)}.model h2,.pipeline h2,.practice h2{margin:0;font-size:clamp(34px,5vw,70px);line-height:.95;letter-spacing:-.06em}.panel{padding:28px;background:var(--ink);color:var(--paper)}.panel strong{display:block;color:var(--gold);font:700 12px monospace;letter-spacing:.1em}.panel code{display:block;margin-top:18px;color:#d6e1e4;font:14px/1.8 ui-monospace,monospace;white-space:pre-wrap}.steps{display:grid;gap:1px;background:var(--line)}.steps article{display:grid;grid-template-columns:70px 1fr;gap:20px;padding:20px;background:var(--paper)}.steps b{color:var(--red);font:20px monospace}.steps strong{display:block}.steps span{color:var(--muted)}.links{display:flex;flex-wrap:wrap;gap:10px;margin:28px 0 70px}.links a{padding:10px 13px;color:var(--ink);border:1px solid var(--ink);text-decoration:none;font:11px monospace;text-transform:uppercase}.links a:hover{color:var(--paper);background:var(--ink)}footer{padding:30px 0 70px;color:var(--muted);font-size:13px}@media(max-width:800px){.grid,.model,.pipeline,.practice{grid-template-columns:1fr}.hero{padding:65px 0 45px}.model,.pipeline,.practice{gap:25px;padding:55px 0}}@media(max-width:520px){main{padding:0 16px}.top span{display:none}.hero h1{font-size:56px}.hero p{font-size:17px}.card{min-height:0}.steps article{grid-template-columns:45px 1fr}}
|
||||
+103
-213
@@ -19,55 +19,44 @@ worktree practices taught by the presentation fit together.
|
||||
## Quick links
|
||||
|
||||
| Resource | Location |
|
||||
| :--------------------- | :------------------------------------------------------------------------------------------------------------------------- |
|
||||
| :--- | :--- |
|
||||
| Live presentation | [https://netcracker.pages.marcospaulo.dev.br/ai-for-dummies/](https://netcracker.pages.marcospaulo.dev.br/ai-for-dummies/) |
|
||||
| Gitea repository | [https://git.marcospaulo.dev.br/netcracker/ai-for-dummies](https://git.marcospaulo.dev.br/netcracker/ai-for-dummies) |
|
||||
| Local checkout | `/home/marcos/Projects/ai-for-dummies` |
|
||||
| Source branch | `main` |
|
||||
| Published branch | `pages` |
|
||||
| Local verification | `pnpm run verify` |
|
||||
| Local verification | `npm run verify` |
|
||||
| SilverBullet page | `Guides/AI For Dummies Presentation` |
|
||||
| Skills-review vote API | separate pod; source is outside this repo, runbook in `docs/vote-service.md` |
|
||||
|
||||
## How the site is built
|
||||
|
||||
The presentation is authored in Astro. `main` holds source; the Gitea Pages
|
||||
Server still serves a branch directly, so the `pages` branch holds generated
|
||||
`dist/` output and is not a source branch.
|
||||
The presentation is deliberately dependency-free. Gitea Pages serves the
|
||||
repository files directly; there is no bundler or generated `dist/` folder.
|
||||
|
||||
| File | Responsibility |
|
||||
| :---------------------------- | :--------------------------------------------------------- |
|
||||
| `src/` | Astro routes, layouts, components, and source styles |
|
||||
| `public/hands-on/` | Verbatim vanilla lab fixtures; Astro does not process them |
|
||||
| `astro.config.mjs` | Static build with `base: '/ai-for-dummies'` |
|
||||
| :--- | :--- |
|
||||
| `index.html` | Default route map and focused chapter navigation |
|
||||
| `full-guide/index.html` | Complete bilingual field guide, controls, labels, and English source copy |
|
||||
| `styles.css` | Base editorial visual system |
|
||||
| `responsive.css` | Interactive diagrams and Full HD, 4K, tablet, and mobile adaptations |
|
||||
| `app.js` | Interactions, state, and Portuguese translations |
|
||||
| `scripts/verify.mjs` | Content and interaction contract checks |
|
||||
| `.gitea/workflows/verify.yml` | Gate, build, and machine-owned publication to `pages` |
|
||||
| `docs/references/` | Primary documentation and additional reading |
|
||||
|
||||
Astro ships no JavaScript by default. Interactive islands opt in per component;
|
||||
the bilingual behaviour remains a client-side concern until its dedicated
|
||||
migration task.
|
||||
The English HTML is the fallback when JavaScript is unavailable. Portuguese
|
||||
copy is applied by `app.js`; the language preference is stored in
|
||||
`localStorage`, and the document language changes to `pt-BR`.
|
||||
|
||||
## Normal edit and publish workflow
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
E[Edit main] --> V[pnpm run gate]
|
||||
E[Edit main] --> V[npm run verify]
|
||||
V --> C[Commit]
|
||||
C --> P[git push main]
|
||||
P --> H[pre-push hook: gate, then publish-pages.sh]
|
||||
H --> B[Build + force-push dist to pages]
|
||||
B --> S[Gitea Pages Server]
|
||||
C --> M[Push main]
|
||||
M --> P[Fast-forward pages]
|
||||
P --> S[Gitea Pages Server]
|
||||
S --> L[Live URL]
|
||||
P -.also.-> G[Gitea Actions: gate]
|
||||
G -.manual dispatch.-> B
|
||||
```
|
||||
|
||||
**A push of `main` republishes the live site.** The `pre-push` hook runs the
|
||||
gate and then `.agents/scripts/publish-pages.sh`. There is no staging step
|
||||
between your push and visitors. To push without publishing:
|
||||
|
||||
```bash
|
||||
AF_NO_PUBLISH=1 git push
|
||||
```
|
||||
|
||||
### 1. Start from current `main`
|
||||
@@ -79,34 +68,41 @@ git pull --ff-only
|
||||
git status --short --branch
|
||||
```
|
||||
|
||||
Do not overwrite unrelated local changes.
|
||||
Do not overwrite unrelated local changes. The untracked
|
||||
`scripts/inspect.py` and `scripts/__pycache__/` are local visual-test artifacts
|
||||
and are intentionally not part of the published site.
|
||||
|
||||
### 2. Preview locally
|
||||
|
||||
```bash
|
||||
pnpm run dev
|
||||
python3 -m http.server 4173
|
||||
```
|
||||
|
||||
Open
|
||||
[http://localhost:4321/ai-for-dummies/](http://localhost:4321/ai-for-dummies/).
|
||||
Check English and Portuguese, keyboard focus, the interactive panels, and at
|
||||
least one desktop and one mobile viewport. The production site is under the
|
||||
`/ai-for-dummies/` base path, so do not test only root-relative URLs.
|
||||
Open [http://localhost:4173](http://localhost:4173). Check English and
|
||||
Portuguese, keyboard focus, the interactive panels, and at least one desktop
|
||||
and one mobile viewport.
|
||||
|
||||
### 3. Verify before committing
|
||||
|
||||
```bash
|
||||
pnpm run gate
|
||||
npm run verify
|
||||
node --check app.js
|
||||
node scripts/audit-ui.mjs
|
||||
git diff --check
|
||||
```
|
||||
|
||||
The gate runs Astro types and build checks, content contracts, the runtime
|
||||
dependency audit, and the token check. It also refuses a reduced count of
|
||||
`verify.mjs` assertions.
|
||||
Expected project verifier output:
|
||||
|
||||
```text
|
||||
content verification passed
|
||||
interaction verification passed
|
||||
standalone verification passed
|
||||
```
|
||||
|
||||
### 4. Commit and push the source branch
|
||||
|
||||
```bash
|
||||
git add <only-files-for-this-change>
|
||||
git add README.md app.js index.html full-guide/ styles.css responsive.css scripts/verify.mjs scripts/audit-ui.mjs docs/
|
||||
git commit -m "feat: describe the change"
|
||||
git push origin main
|
||||
```
|
||||
@@ -114,61 +110,34 @@ git push origin main
|
||||
Stage only files that belong to the change. Review `git status --short` before
|
||||
committing.
|
||||
|
||||
### 5. CI publication and its manual fallback
|
||||
### 5. Fast-forward the published branch
|
||||
|
||||
Gitea Actions builds `dist/` and force-pushes it to `pages`. This force-push is
|
||||
intentional: `pages` is machine-owned generated output, and no person or other
|
||||
workflow may write it.
|
||||
|
||||
**For the duration of the Astro migration, publication is manual.** The
|
||||
`publish` job runs only from a `workflow_dispatch` with its `publish` input set
|
||||
to true — a push to `main` runs the gate and stops there. The reason: `dist/`
|
||||
currently holds three HTML files (`/summary/` plus the two `hands-on/` fixtures)
|
||||
against the ten pages the live branch serves, so publishing on every push would
|
||||
take the site down to a stub. Task 20 (cutover) makes it automatic again.
|
||||
|
||||
This Gitea's act-runner registration is kept in an `emptyDir`. A pod restart
|
||||
silently removes the registration; if a site does not update, check and
|
||||
re-register the runner before changing the workflow.
|
||||
|
||||
If the runner is unavailable, use the following manual fallback from a clean
|
||||
`main` checkout. It deliberately replaces the generated branch tree only:
|
||||
Use a temporary worktree so the current checkout stays on `main`:
|
||||
|
||||
```bash
|
||||
pnpm install --frozen-lockfile
|
||||
pnpm run build
|
||||
git worktree add /tmp/ai-for-dummies-pages --detach pages
|
||||
git -C /tmp/ai-for-dummies-pages rm -rf .
|
||||
cp -a dist/. /tmp/ai-for-dummies-pages/
|
||||
git -C /tmp/ai-for-dummies-pages add --all
|
||||
git -C /tmp/ai-for-dummies-pages commit -m "chore: publish site"
|
||||
git -C /tmp/ai-for-dummies-pages push --force origin HEAD:pages
|
||||
git worktree add /tmp/ai-for-dummies-pages pages
|
||||
git -C /tmp/ai-for-dummies-pages merge --ff-only main
|
||||
git -C /tmp/ai-for-dummies-pages push origin pages
|
||||
git worktree remove /tmp/ai-for-dummies-pages
|
||||
```
|
||||
|
||||
The `pages` branch should represent the exact published source. Avoid editing
|
||||
it directly and avoid force-pushing it.
|
||||
|
||||
### 6. Verify the deployment
|
||||
|
||||
```bash
|
||||
curl -sS -o /dev/null -w '%{http_code}\n' \
|
||||
"https://netcracker.pages.marcospaulo.dev.br/ai-for-dummies/summary/"
|
||||
curl -I https://netcracker.pages.marcospaulo.dev.br/ai-for-dummies/
|
||||
```
|
||||
|
||||
Also check a nested static asset; base-path problems usually appear on assets
|
||||
first:
|
||||
If the edge still shows an older page, retry with the current commit as a
|
||||
cache-busting query:
|
||||
|
||||
```bash
|
||||
curl -sS -o /dev/null -w '%{http_code}\n' \
|
||||
"https://netcracker.pages.marcospaulo.dev.br/ai-for-dummies/hands-on/starter/"
|
||||
git rev-parse --short HEAD
|
||||
curl -I "https://netcracker.pages.marcospaulo.dev.br/ai-for-dummies/?v=COMMIT"
|
||||
```
|
||||
|
||||
**The Pages Server caches for ten minutes** (`x-pages-cache: true`,
|
||||
`cache-control: public, max-age=600`), and the cache is keyed on the _path_. A
|
||||
`?v=$(git rev-parse …)` query string does **not** bust it — that idiom used to
|
||||
be in this guide and it never worked. After a publish, a URL can keep serving
|
||||
the previous content, or keep serving a file you just deleted, for up to ten
|
||||
minutes. Budget for that before concluding a deploy failed. Check
|
||||
`last-modified` and `etag` with `curl -I` to tell fresh from cached.
|
||||
|
||||
The correct URL pattern is **owner subdomain + repository path**:
|
||||
|
||||
```text
|
||||
@@ -179,58 +148,9 @@ https://netcracker.pages.marcospaulo.dev.br/ai-for-dummies/
|
||||
produce `ERR_SSL_PROTOCOL_ERROR` because it does not match the wildcard TLS
|
||||
certificate.
|
||||
|
||||
## Skills-review vote service
|
||||
|
||||
`skills-review/` is served by the same static Pages Server as the rest of this
|
||||
site, so it cannot itself remember votes. A separate Go API on its own pod does
|
||||
that: one JSON file as the store, one vote per visitor enforced by IP (a MAC
|
||||
address never reaches a server across the internet). It is deployed
|
||||
independently of `main`/`pages` — the site can be republished without touching
|
||||
it, and vice versa.
|
||||
|
||||
The service's source is no longer in this repository; run these from wherever it
|
||||
now lives.
|
||||
|
||||
```bash
|
||||
docker build -t localhost:30892/ai-for-dummies-vote-service:latest .
|
||||
docker push localhost:30892/ai-for-dummies-vote-service:latest
|
||||
|
||||
# kubelet cannot pull that ref (no certs.d/hosts.toml for localhost:30892 →
|
||||
# `no basic auth credentials`), so side-load into containerd instead and let
|
||||
# `imagePullPolicy: Never` skip the network pull. Use microk8s's bundled ctr.
|
||||
docker save localhost:30892/ai-for-dummies-vote-service:latest -o /tmp/vote-service.tar
|
||||
/snap/microk8s/current/bin/ctr --address /var/snap/microk8s/common/run/containerd.sock \
|
||||
--namespace k8s.io image import /tmp/vote-service.tar
|
||||
|
||||
microk8s kubectl apply -f deploy/deployment.yaml # namespace + Deployment + PVC + Service
|
||||
microk8s kubectl apply -f deploy/ingress.yaml
|
||||
microk8s kubectl -n ai-for-dummies rollout restart deploy ai-for-dummies-vote
|
||||
```
|
||||
|
||||
Namespace `ai-for-dummies`, `ingressClassName: public`, no per-ingress TLS. The
|
||||
Deployment is pinned to node `kubernets` with a `nodeSelector`: the
|
||||
`microk8s-hostpath` PV carries a `nodeAffinity` for whichever node first binds
|
||||
it, so scheduling and storage have to agree on one node.
|
||||
|
||||
The vote widget's browser-side `fetch` calls must reach the API over the public
|
||||
internet — a cluster-internal-only Service would be unreachable from a visitor's
|
||||
browser even if the Pages Server happens to run on the same network. Exposure is
|
||||
therefore public, terminated by **Caddy on the Oracle VPS over Tailscale** (the
|
||||
same path as every other public host here, not the cloudflared tunnel), with
|
||||
`ALLOWED_ORIGIN`/CORS as the boundary that restricts which site's script may
|
||||
call it. After deploying, keep `window.SKILLS_REVIEW_VOTE_API` in
|
||||
`src/pages/skills-review.astro` in sync with `ALLOWED_ORIGIN` on the service.
|
||||
|
||||
One cluster-wide gotcha worth knowing before reading the vote code: the ingress
|
||||
controller runs with `use-forwarded-headers` off, so nginx _overwrites_
|
||||
`X-Forwarded-For`/`X-Real-IP` with the VPS's tailnet address. Caddy stamps the
|
||||
true client address into `X-Client-IP` instead. Full rationale, the Caddy block,
|
||||
and the anti-abuse design are in [docs/vote-service.md](vote-service.md).
|
||||
|
||||
## Adding or changing a presentation section
|
||||
|
||||
1. Add semantic HTML and stable `data-*` hooks in the focused chapter or
|
||||
`full-guide/index.html`; keep `index.html` as the short route map.
|
||||
1. Add semantic HTML and stable `data-*` hooks in the focused chapter or `full-guide/index.html`; keep `index.html` as the short route map.
|
||||
2. Put interactive content in a data object inside `app.js`.
|
||||
3. Add one focused render function and bind its controls once.
|
||||
4. Add Portuguese static copy to `translations.pt` and dynamic copy to the
|
||||
@@ -260,8 +180,8 @@ flowchart TD
|
||||
|
||||
Use a strong model where ambiguity dominates: repository inspection,
|
||||
architecture, decomposition, risk analysis, and review. Use faster or cheaper
|
||||
models for bounded implementation only after the brief defines the goal, files,
|
||||
constraints, and checks.
|
||||
models for bounded implementation only after the brief defines the goal,
|
||||
files, constraints, and checks.
|
||||
|
||||
Every worker should return:
|
||||
|
||||
@@ -275,8 +195,8 @@ coordination cost, context cost, and integration risk.
|
||||
|
||||
## Worktree-per-worker model
|
||||
|
||||
A Git branch isolates history; a Git worktree also isolates the active files and
|
||||
index. Give each editing agent one task, one branch, and one worktree.
|
||||
A Git branch isolates history; a Git worktree also isolates the active files
|
||||
and index. Give each editing agent one task, one branch, and one worktree.
|
||||
|
||||
```bash
|
||||
git worktree add ../task-ui -b agent/ui
|
||||
@@ -294,14 +214,14 @@ Recommended lifecycle:
|
||||
5. Merge, request changes, or discard.
|
||||
6. Remove the finished worktree with `git worktree remove PATH`.
|
||||
|
||||
Worktrees prevent agents from changing the same checkout underneath each other.
|
||||
They do not eliminate semantic merge conflicts; task ownership and review still
|
||||
matter.
|
||||
Worktrees prevent agents from changing the same checkout underneath each
|
||||
other. They do not eliminate semantic merge conflicts; task ownership and
|
||||
review still matter.
|
||||
|
||||
## What a skill is
|
||||
|
||||
A skill is a reusable procedure that changes how an agent makes decisions. It is
|
||||
not magical memory and does not replace a task brief or acceptance criteria.
|
||||
A skill is a reusable procedure that changes how an agent makes decisions. It
|
||||
is not magical memory and does not replace a task brief or acceptance criteria.
|
||||
|
||||
```text
|
||||
skill-name/
|
||||
@@ -318,8 +238,8 @@ Progressive disclosure keeps context light:
|
||||
2. **SKILL.md** loads when the skill applies.
|
||||
3. **References, scripts, and assets** load only when the workflow needs them.
|
||||
|
||||
Do not create empty resource directories. Every file should have a real consumer
|
||||
and should improve a decision or repeatable operation.
|
||||
Do not create empty resource directories. Every file should have a real
|
||||
consumer and should improve a decision or repeatable operation.
|
||||
|
||||
## Skill-creation workflow
|
||||
|
||||
@@ -338,17 +258,14 @@ likely false activation.
|
||||
```yaml
|
||||
---
|
||||
name: review-ui
|
||||
description:
|
||||
Review frontend changes for focus, responsive layout, and reduced-motion
|
||||
behavior.
|
||||
description: Review frontend changes for focus, responsive layout, and reduced-motion behavior.
|
||||
---
|
||||
```
|
||||
|
||||
### 3. Choose the smallest anatomy
|
||||
|
||||
- Put shared workflow and constraints in `SKILL.md`.
|
||||
- Add `scripts/` when deterministic execution prevents repeated
|
||||
reimplementation.
|
||||
- Add `scripts/` when deterministic execution prevents repeated reimplementation.
|
||||
- Add `references/` for details needed only in certain modes.
|
||||
- Add `assets/` for templates or generated-output inputs.
|
||||
- Add `agents/openai.yaml` only when UI metadata or invocation policy is useful.
|
||||
@@ -373,7 +290,7 @@ accumulating universal instructions.
|
||||
## Common skills and when to use them
|
||||
|
||||
| Skill | Use it for | Core rule | Avoid when |
|
||||
| :---------------- | :-------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------- |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| `ponytail-lite` | Requests inviting unnecessary frameworks or abstractions | Stop at the first sufficient solution: reuse, standard library, native platform, existing dependency, then minimum new code | Simplification would remove validation, security, accessibility, or real edge cases |
|
||||
| `caveman` | Routine status, handoffs, and technical summaries | Put signal first and remove filler | Security warnings, irreversible actions, or sequences where terse wording can be misread |
|
||||
| `unlazy` | Substantial builds, audits, and parallel work | Define observable gates and finish against evidence | Trivial edits or factual answers |
|
||||
@@ -385,21 +302,17 @@ accumulating universal instructions.
|
||||
|
||||
Useful compositions:
|
||||
|
||||
- **Large feature:** `unlazy` → `ponytail-lite` → implementation →
|
||||
`code-review`.
|
||||
- **Hard regression:** `diagnosing-bugs` → fix → `code-review` → `caveman`
|
||||
handoff.
|
||||
- **Documentation with unstable facts:** `research` → writing → cited
|
||||
verification.
|
||||
- **Interactive presentation:** `frontend-design` → `webapp-testing` →
|
||||
responsive evidence.
|
||||
- **Large feature:** `unlazy` → `ponytail-lite` → implementation → `code-review`.
|
||||
- **Hard regression:** `diagnosing-bugs` → fix → `code-review` → `caveman` handoff.
|
||||
- **Documentation with unstable facts:** `research` → writing → cited verification.
|
||||
- **Interactive presentation:** `frontend-design` → `webapp-testing` → responsive evidence.
|
||||
|
||||
## Model and effort routing
|
||||
|
||||
Treat model tier and reasoning effort as separate controls:
|
||||
|
||||
| Work shape | Capability tier | Effort baseline |
|
||||
| :------------------------------------------ | :------------------------ | :----------------------------- |
|
||||
| :--- | :--- | :--- |
|
||||
| Formatting, lookup, narrow edit | Luna / Haiku / Flash-Lite | Low or minimal where supported |
|
||||
| Normal implementation and tests | Terra / Sonnet / Flash | Medium |
|
||||
| Architecture, orchestration, hard debugging | Sol / Opus / Pro | High |
|
||||
@@ -430,25 +343,22 @@ includes a copy-ready installation request that tells the coding agent to:
|
||||
Important exceptions: `ponytail-lite` is published as `AGENTS.md`, not a
|
||||
conventional skill package; `token-saver` expects a separate RTK binary; and
|
||||
`unlazy` includes optional hooks. The prompt does not install binaries or enable
|
||||
hooks without separate approval. See
|
||||
[skill-sources.md](references/skill-sources.md) for exact commits, package
|
||||
paths, and confidence notes.
|
||||
hooks without separate approval. See [skill-sources.md](references/skill-sources.md)
|
||||
for exact commits, package paths, and confidence notes.
|
||||
|
||||
## Hands-on lab
|
||||
|
||||
The presentation includes a dependency-free starter at
|
||||
`public/hands-on/starter/`. It renders a small task board but intentionally
|
||||
omits the All / Open / Done filter. Attendees clone it from the `pages` branch,
|
||||
where the build places it at `hands-on/starter/`.
|
||||
`hands-on/starter/`. It renders a small task board but intentionally omits the
|
||||
All / Open / Done filter.
|
||||
|
||||
Run it from the repository root:
|
||||
|
||||
```bash
|
||||
pnpm run dev
|
||||
python3 -m http.server 4173
|
||||
```
|
||||
|
||||
Open
|
||||
[http://localhost:4321/ai-for-dummies/hands-on/starter/](http://localhost:4321/ai-for-dummies/hands-on/starter/).
|
||||
Open [http://localhost:4173/hands-on/starter/](http://localhost:4173/hands-on/starter/).
|
||||
In a fresh coding-agent session, copy **Run A — Good prompt** from the
|
||||
presentation. Record changed files, dependencies, checks, and evidence. Restore
|
||||
the starter, then repeat with **Run B — Good prompt + skills**.
|
||||
@@ -459,14 +369,14 @@ The skill-enabled prompt invokes only two working methods:
|
||||
- `$webapp-testing` verifies filters, URL state, history navigation,
|
||||
accessibility state, empty state, and mobile layout.
|
||||
|
||||
The goal is not to prove that a longer prompt is better. Both prompts define the
|
||||
same task contract. Run B adds reusable operating discipline without repeating
|
||||
those skill instructions inside the prompt.
|
||||
The goal is not to prove that a longer prompt is better. Both prompts define
|
||||
the same task contract. Run B adds reusable operating discipline without
|
||||
repeating those skill instructions inside the prompt.
|
||||
|
||||
Compare:
|
||||
|
||||
| Signal | Useful question |
|
||||
| :------------ | :-------------------------------------------------------------- |
|
||||
| :--- | :--- |
|
||||
| Files changed | Did the agent stay inside `hands-on/starter/`? |
|
||||
| Dependencies | Did it add a library where native APIs were enough? |
|
||||
| Verification | Did it actually exercise URL reload and browser history? |
|
||||
@@ -475,28 +385,27 @@ Compare:
|
||||
|
||||
### Hands-on rules lab
|
||||
|
||||
A second lab at `public/hands-on/rules/` mirrors the starter's visual system and
|
||||
runs the same exercise against rule sources. It lists five toggleable rule
|
||||
sources — `AGENTS.md`, the `gate-discipline` skill body, the Husky `pre-commit`
|
||||
hook, the `check-ui-contract.mjs` enforcer, and `commitlint` — and rebuilds the
|
||||
A second lab at `hands-on/rules/` mirrors the starter's visual system and runs
|
||||
the same exercise against rule sources. It lists five toggleable rule sources
|
||||
— `AGENTS.md`, the `gate-discipline` skill body, the Husky `pre-commit` hook,
|
||||
the `check-ui-contract.mjs` enforcer, and `commitlint` — and rebuilds the
|
||||
**ruled** prompt live as each toggle flips.
|
||||
|
||||
Run it:
|
||||
|
||||
```bash
|
||||
pnpm run dev
|
||||
python3 -m http.server 4173
|
||||
```
|
||||
|
||||
Open
|
||||
[http://localhost:4321/ai-for-dummies/hands-on/rules/](http://localhost:4321/ai-for-dummies/hands-on/rules/).
|
||||
Open [http://localhost:4173/hands-on/rules/](http://localhost:4173/hands-on/rules/).
|
||||
Compare the **naive** and **ruled** prompt panels. Toggle rules off to shrink
|
||||
the prompt; toggle them on to add more guards. Copy the final prompt and run it
|
||||
against a real coding agent.
|
||||
the prompt; toggle them on to add more guards. Copy the final prompt and run
|
||||
it against a real coding agent.
|
||||
|
||||
## Rules and enforcement case study
|
||||
|
||||
The separate `/rules/` page uses `netcracker/interview` as a concrete example of
|
||||
repository-level control. Its interactive pipeline shows five layers:
|
||||
The separate `/rules/` page uses `netcracker/interview` as a concrete example
|
||||
of repository-level control. Its interactive pipeline shows five layers:
|
||||
|
||||
1. `AGENTS.md` gives every agent the same product and toolchain context.
|
||||
2. `.agents/skills/` loads narrow procedures for frontend, Go API, gates,
|
||||
@@ -515,7 +424,7 @@ together when the underlying interview workflow changes.
|
||||
## Troubleshooting
|
||||
|
||||
| Symptom | Check | Fix |
|
||||
| :------------------------------------------- | :------------------------------------------------------ | :--------------------------------------------------------------------------------------- |
|
||||
| :--- | :--- | :--- |
|
||||
| Live page is old | Compare `main`, `pages`, and remote SHAs | Fast-forward and push `pages`; retry with `?v=COMMIT` |
|
||||
| `ERR_SSL_PROTOCOL_ERROR` | Confirm the hostname | Use `netcracker.pages.marcospaulo.dev.br/ai-for-dummies/` |
|
||||
| Portuguese copy is missing | Inspect `translations.pt` and dynamic interaction data | Add both static and dynamic translations; reload after clearing saved language if needed |
|
||||
@@ -526,51 +435,32 @@ together when the underlying interview workflow changes.
|
||||
|
||||
## Safe rollback
|
||||
|
||||
`pages` holds build output, not a copy of `main`, so it is not merged into or
|
||||
fast-forwarded from `main`. Rolling the _site_ back and rolling the _source_
|
||||
back are two separate actions.
|
||||
|
||||
**Roll the live site back immediately**, without touching `main`. The publisher
|
||||
prints the rollback command every time it runs; `pages` keeps its history, so
|
||||
any previous tip works:
|
||||
|
||||
```bash
|
||||
git fetch origin pages
|
||||
git log --oneline origin/pages | head # pick the tip you want back
|
||||
git push --force origin <SHA>:refs/heads/pages
|
||||
```
|
||||
|
||||
`pages-backup-2026-09-06` (`37a1e48`) is the last commit of the hand-written
|
||||
site, kept as a floor under every rollback.
|
||||
|
||||
Confirm with a cache-buster — a stale cached 200 looks exactly like success:
|
||||
|
||||
```bash
|
||||
curl -sS -o /dev/null -w '%{http_code}\n' \
|
||||
"https://netcracker.pages.marcospaulo.dev.br/ai-for-dummies/?v=$(date +%s)"
|
||||
```
|
||||
|
||||
**Then fix the source.** Revert on `main` and push; the pre-push hook rebuilds
|
||||
and republishes, which is what makes the site and the source agree again:
|
||||
Prefer a normal revert so history and the `pages` branch remain fast-forwardable:
|
||||
|
||||
```bash
|
||||
git switch main
|
||||
git revert BAD_COMMIT
|
||||
git push origin main
|
||||
git worktree add /tmp/ai-for-dummies-pages pages
|
||||
git -C /tmp/ai-for-dummies-pages merge --ff-only main
|
||||
git -C /tmp/ai-for-dummies-pages push origin pages
|
||||
git worktree remove /tmp/ai-for-dummies-pages
|
||||
```
|
||||
|
||||
Verify the live URL after rollback. Do not use `reset --hard` or force-push for
|
||||
ordinary content recovery.
|
||||
|
||||
## Completion checklist
|
||||
|
||||
- [ ] English content is complete without JavaScript.
|
||||
- [ ] Portuguese static and dynamic copy is complete.
|
||||
- [ ] Mouse and keyboard interactions work.
|
||||
- [ ] Full HD, 4K, and mobile layouts remain readable.
|
||||
- [ ] `pnpm run verify`, `node --check app.js`, and `git diff --check` pass.
|
||||
- [ ] `npm run verify`, `node --check app.js`, and `git diff --check` pass.
|
||||
- [ ] `main` is pushed.
|
||||
- [ ] `pages` fast-forwards to the same commit.
|
||||
- [ ] Live endpoint returns HTTP 200 and contains the new section.
|
||||
- [ ] Research links and this SilverBullet guide are updated when the workflow
|
||||
changes.
|
||||
- [ ] Research links and this SilverBullet guide are updated when the workflow changes.
|
||||
|
||||
## Resumo rápido em português
|
||||
|
||||
@@ -580,6 +470,6 @@ Gitea Pages publica diretamente essa branch. Use o endereço com
|
||||
`netcracker.pages.../ai-for-dummies/`; o formato inverso quebra o TLS.
|
||||
|
||||
Para agentes: modelo forte planeja e revisa; workers delimitados implementam em
|
||||
worktrees separados; evidências voltam ao orquestrador. Para skills: capture uma
|
||||
decisão repetida, defina um gatilho preciso, crie apenas os recursos úteis,
|
||||
worktrees separados; evidências voltam ao orquestrador. Para skills: capture
|
||||
uma decisão repetida, defina um gatilho preciso, crie apenas os recursos úteis,
|
||||
escreva orientação que muda decisões e valide estrutura **e** comportamento.
|
||||
|
||||
+20
-29
@@ -7,47 +7,38 @@ articles are context, not authority.
|
||||
|
||||
- Anthropic — custom subagents: https://code.claude.com/docs/en/sub-agents
|
||||
Separate context, tools, permissions, model selection, and worktree isolation.
|
||||
- Anthropic — skills: https://code.claude.com/docs/en/skills Reusable
|
||||
instruction packages and skill discovery.
|
||||
- Anthropic — worktrees: https://code.claude.com/docs/en/worktrees Isolated
|
||||
sessions, branches, cleanup, and ignored files.
|
||||
- OpenAI — build skills: https://developers.openai.com/codex/skills Packaged
|
||||
instructions and resources for Codex workflows.
|
||||
- OpenAI API — skills reference:
|
||||
https://developers.openai.com/api/reference/go/resources/skills Creating,
|
||||
versioning, listing, and downloading skill bundles.
|
||||
- Git — worktree: https://git-scm.com/docs/git-worktree.html Linked working
|
||||
trees, branches, shared history, add/list/remove/prune.
|
||||
- Anthropic — skills: https://code.claude.com/docs/en/skills
|
||||
Reusable instruction packages and skill discovery.
|
||||
- Anthropic — worktrees: https://code.claude.com/docs/en/worktrees
|
||||
Isolated sessions, branches, cleanup, and ignored files.
|
||||
- OpenAI — build skills: https://developers.openai.com/codex/skills
|
||||
Packaged instructions and resources for Codex workflows.
|
||||
- OpenAI API — skills reference: https://developers.openai.com/api/reference/go/resources/skills
|
||||
Creating, versioning, listing, and downloading skill bundles.
|
||||
- Git — worktree: https://git-scm.com/docs/git-worktree.html
|
||||
Linked working trees, branches, shared history, add/list/remove/prune.
|
||||
|
||||
## Research and articles
|
||||
|
||||
- [Model routing and reasoning controls](model-routing.md) — official OpenAI,
|
||||
Anthropic, and Google terminology, commands, compatibility caveats, and a
|
||||
practical tier/effort baseline.
|
||||
- [Verified skill sources](skill-sources.md) — pinned GitHub references, package
|
||||
paths, local-match confidence, and an approval-first install prompt.
|
||||
- [Verified skill sources](skill-sources.md) — pinned GitHub references,
|
||||
package paths, local-match confidence, and an approval-first install prompt.
|
||||
|
||||
For a structured 12-part reading path—including Git and Anthropic documentation,
|
||||
OpenAI orchestration guidance, Medium, and Substack—see
|
||||
[additional-reading.md](additional-reading.md).
|
||||
|
||||
- Infobip Research — phased coding-agent workflow:
|
||||
https://arxiv.org/abs/2608.30701
|
||||
- Effective asynchronous software engineering agents:
|
||||
https://arxiv.org/abs/2603.21489
|
||||
- Launch Receipts — AI coding workflow without losing control:
|
||||
https://launchreceipts.com/articles/ai-coding-agent-workflow
|
||||
- GitWorktree.org — three agents, three worktrees case study:
|
||||
https://www.gitworktree.org/cases/parallel-ai-agents
|
||||
- Infobip Research — phased coding-agent workflow: https://arxiv.org/abs/2608.30701
|
||||
- Effective asynchronous software engineering agents: https://arxiv.org/abs/2603.21489
|
||||
- Launch Receipts — AI coding workflow without losing control: https://launchreceipts.com/articles/ai-coding-agent-workflow
|
||||
- GitWorktree.org — three agents, three worktrees case study: https://www.gitworktree.org/cases/parallel-ai-agents
|
||||
|
||||
## Teaching claims
|
||||
|
||||
- Use a stronger model where ambiguity, architecture, decomposition, and review
|
||||
dominate.
|
||||
- Use a stronger model where ambiguity, architecture, decomposition, and review dominate.
|
||||
- Use faster models for bounded implementation with explicit context and checks.
|
||||
- Give every editing worker an isolated branch/worktree; merge only reviewed
|
||||
diffs.
|
||||
- A skill is a reusable procedure plus optional references/scripts/assets, not
|
||||
magical memory.
|
||||
- Delegation does not remove human responsibility for intent, boundaries, or
|
||||
evidence.
|
||||
- Give every editing worker an isolated branch/worktree; merge only reviewed diffs.
|
||||
- A skill is a reusable procedure plus optional references/scripts/assets, not magical memory.
|
||||
- Delegation does not remove human responsibility for intent, boundaries, or evidence.
|
||||
|
||||
@@ -1,8 +1,6 @@
|
||||
# Additional reading: multi-agent coding
|
||||
|
||||
Verified on 2026-09-02. Start with the official references for behavior and
|
||||
constraints; use the practitioner articles for concrete workflow ideas that
|
||||
should be tested against your own repository.
|
||||
Verified on 2026-09-02. Start with the official references for behavior and constraints; use the practitioner articles for concrete workflow ideas that should be tested against your own repository.
|
||||
|
||||
## Git worktrees and isolated coding sessions
|
||||
|
||||
@@ -10,38 +8,25 @@ should be tested against your own repository.
|
||||
|
||||
- **Publisher:** Git
|
||||
- **Topic:** Worktree fundamentals and lifecycle
|
||||
- **Teaching takeaway:** The authoritative reference for how linked worktrees
|
||||
share repository data while retaining separate `HEAD` and index state. Use its
|
||||
`add`, `list`, `lock`, `remove`, `prune`, and `repair` sections to teach the
|
||||
complete lifecycle rather than only worktree creation.
|
||||
- **Teaching takeaway:** The authoritative reference for how linked worktrees share repository data while retaining separate `HEAD` and index state. Use its `add`, `list`, `lock`, `remove`, `prune`, and `repair` sections to teach the complete lifecycle rather than only worktree creation.
|
||||
|
||||
### 2. [Run parallel sessions with worktrees](https://code.claude.com/docs/en/worktrees)
|
||||
|
||||
- **Publisher:** Anthropic — Claude Code Docs
|
||||
- **Topic:** Native worktree isolation for coding agents
|
||||
- **Teaching takeaway:** Shows how Claude Code creates isolated sessions with
|
||||
`--worktree`, how gitignored environment files can be copied with
|
||||
`.worktreeinclude`, and how subagents can use worktree isolation. It is a
|
||||
useful bridge between raw Git commands and a real agent workflow.
|
||||
- **Teaching takeaway:** Shows how Claude Code creates isolated sessions with `--worktree`, how gitignored environment files can be copied with `.worktreeinclude`, and how subagents can use worktree isolation. It is a useful bridge between raw Git commands and a real agent workflow.
|
||||
|
||||
### 3. [How Git Worktrees Transformed My AI Agent Development Workflow in 2026](https://medium.com/@mudassir00seven/how-git-worktrees-transformed-my-ai-agent-development-workflow-in-2026-ad8a59b8edfb)
|
||||
|
||||
- **Publisher:** Medium — Mudassir Khan
|
||||
- **Topic:** One worktree per agent and task
|
||||
- **Teaching takeaway:** A concise practitioner explanation of why parallel
|
||||
agents collide in a shared filesystem and how one task, branch, worktree, and
|
||||
pull request per agent reduces that interference. Pair it with the official
|
||||
Git documentation because operational details may evolve.
|
||||
- **Teaching takeaway:** A concise practitioner explanation of why parallel agents collide in a shared filesystem and how one task, branch, worktree, and pull request per agent reduces that interference. Pair it with the official Git documentation because operational details may evolve.
|
||||
|
||||
### 4. [How to Use Git Worktrees with Coding Agents](https://meshintelligence.substack.com/p/how-to-use-git-worktrees-with-coding)
|
||||
|
||||
- **Publisher:** Mesh Intelligence on Substack — Petar Djukic
|
||||
- **Topic:** Worktree-per-task workflow and integration boundaries
|
||||
- **Teaching takeaway:** Explains why branches alone do not isolate active
|
||||
files, compares worktrees with clones and containers, and presents a
|
||||
create-work-review-remove lifecycle. Its strongest lesson is that worktrees
|
||||
isolate execution, not merge conflicts, so scheduling and review gates still
|
||||
matter.
|
||||
- **Teaching takeaway:** Explains why branches alone do not isolate active files, compares worktrees with clones and containers, and presents a create-work-review-remove lifecycle. Its strongest lesson is that worktrees isolate execution, not merge conflicts, so scheduling and review gates still matter.
|
||||
|
||||
## Subagents and orchestration
|
||||
|
||||
@@ -49,48 +34,31 @@ should be tested against your own repository.
|
||||
|
||||
- **Publisher:** Anthropic — Claude Code Docs
|
||||
- **Topic:** Specialized subagents, context, tools, and background execution
|
||||
- **Teaching takeaway:** Demonstrates how to define narrow subagents with their
|
||||
own prompts, tool permissions, and models, then run them in foreground or
|
||||
background. It supports teaching that delegation quality depends on explicit
|
||||
responsibility and context boundaries, not merely spawning more agents.
|
||||
- **Teaching takeaway:** Demonstrates how to define narrow subagents with their own prompts, tool permissions, and models, then run them in foreground or background. It supports teaching that delegation quality depends on explicit responsibility and context boundaries, not merely spawning more agents.
|
||||
|
||||
### 6. [Building Effective AI Agents](https://www.anthropic.com/engineering/building-effective-agents)
|
||||
|
||||
- **Publisher:** Anthropic Engineering
|
||||
- **Topic:** Agent architecture patterns
|
||||
- **Teaching takeaway:** Introduces routing, parallelization,
|
||||
orchestrator-worker, and evaluator-optimizer patterns while recommending the
|
||||
simplest architecture that meets the task. The orchestrator-worker section is
|
||||
especially useful for explaining when a strong planner should dynamically
|
||||
decompose work for bounded workers.
|
||||
- **Teaching takeaway:** Introduces routing, parallelization, orchestrator-worker, and evaluator-optimizer patterns while recommending the simplest architecture that meets the task. The orchestrator-worker section is especially useful for explaining when a strong planner should dynamically decompose work for bounded workers.
|
||||
|
||||
### 7. [How we built our multi-agent research system](https://www.anthropic.com/engineering/multi-agent-research-system)
|
||||
|
||||
- **Publisher:** Anthropic Engineering
|
||||
- **Topic:** Production multi-agent coordination
|
||||
- **Teaching takeaway:** A production case study in which a lead agent plans and
|
||||
delegates independent searches to parallel subagents. It is useful for
|
||||
discussing breadth-first tasks, separate context windows, token cost,
|
||||
evaluation, and why parallelism helps most when subtasks are genuinely
|
||||
independent.
|
||||
- **Teaching takeaway:** A production case study in which a lead agent plans and delegates independent searches to parallel subagents. It is useful for discussing breadth-first tasks, separate context windows, token cost, evaluation, and why parallelism helps most when subtasks are genuinely independent.
|
||||
|
||||
### 8. [A practical guide to building agents](https://openai.com/business/guides-and-resources/a-practical-guide-to-building-ai-agents/)
|
||||
|
||||
- **Publisher:** OpenAI
|
||||
- **Topic:** Manager and handoff orchestration patterns
|
||||
- **Teaching takeaway:** Distinguishes centralized manager orchestration from
|
||||
decentralized handoffs and shows agents being exposed as tools to other
|
||||
agents. Use it to teach that the right topology depends on who must retain
|
||||
control, combine outputs, and own the final response.
|
||||
- **Teaching takeaway:** Distinguishes centralized manager orchestration from decentralized handoffs and shows agents being exposed as tools to other agents. Use it to teach that the right topology depends on who must retain control, combine outputs, and own the final response.
|
||||
|
||||
### 9. [Agent orchestration](https://openai.github.io/openai-agents-python/multi_agent/)
|
||||
|
||||
- **Publisher:** OpenAI Agents SDK
|
||||
- **Topic:** Agents-as-tools, handoffs, and code-driven workflows
|
||||
- **Teaching takeaway:** Gives a precise comparison between a manager calling
|
||||
specialists as tools and handing control to a specialist. It also covers
|
||||
deterministic orchestration in code, including chains, evaluator loops, and
|
||||
parallel execution for independent tasks.
|
||||
- **Teaching takeaway:** Gives a precise comparison between a manager calling specialists as tools and handing control to a specialist. It also covers deterministic orchestration in code, including chains, evaluator loops, and parallel execution for independent tasks.
|
||||
|
||||
## Model routing and reusable skills
|
||||
|
||||
@@ -98,30 +66,19 @@ should be tested against your own repository.
|
||||
|
||||
- **Publisher:** Anthropic — Claude Platform Docs
|
||||
- **Topic:** Routing work between frontier and lower-cost models
|
||||
- **Teaching takeaway:** Compares model selection, advisor, and orchestrator
|
||||
strategies using cost-per-completed-task rather than token price alone. Its
|
||||
orchestrator guidance directly supports a frontier planner dispatching bulk
|
||||
independent work to cheaper workers—but also explains when one model is
|
||||
simpler and less expensive.
|
||||
- **Teaching takeaway:** Compares model selection, advisor, and orchestrator strategies using cost-per-completed-task rather than token price alone. Its orchestrator guidance directly supports a frontier planner dispatching bulk independent work to cheaper workers—but also explains when one model is simpler and less expensive.
|
||||
|
||||
### 11. [Models](https://openai.github.io/openai-agents-python/models/)
|
||||
|
||||
- **Publisher:** OpenAI Agents SDK
|
||||
- **Topic:** Per-agent model selection and mixed-provider routing
|
||||
- **Teaching takeaway:** Documents how different agents in one workflow can use
|
||||
different models or providers and how routing can be configured centrally.
|
||||
This is a practical implementation reference for turning a conceptual “strong
|
||||
planner, lightweight workers” policy into explicit per-agent configuration.
|
||||
- **Teaching takeaway:** Documents how different agents in one workflow can use different models or providers and how routing can be configured centrally. This is a practical implementation reference for turning a conceptual “strong planner, lightweight workers” policy into explicit per-agent configuration.
|
||||
|
||||
### 12. [Skills](https://platform.claude.com/docs/en/managed-agents/skills)
|
||||
|
||||
- **Publisher:** Anthropic — Claude Platform Docs
|
||||
- **Topic:** Reusable filesystem-based agent skills
|
||||
- **Teaching takeaway:** Explains the `SKILL.md` package model, repository
|
||||
discovery, supporting scripts and resources, and why only task-relevant skills
|
||||
should be attached. It also highlights the security lesson that repository
|
||||
skills are executable instructions and therefore part of the agent’s trust
|
||||
boundary.
|
||||
- **Teaching takeaway:** Explains the `SKILL.md` package model, repository discovery, supporting scripts and resources, and why only task-relevant skills should be attached. It also highlights the security lesson that repository skills are executable instructions and therefore part of the agent’s trust boundary.
|
||||
|
||||
## Suggested teaching order
|
||||
|
||||
|
||||
@@ -1,42 +1,25 @@
|
||||
# Model routing and reasoning controls
|
||||
|
||||
Verified against first-party documentation on 2026-09-02. Model catalogs and
|
||||
aliases change; pin production model IDs and re-check the linked compatibility
|
||||
tables before rollout.
|
||||
Verified against first-party documentation on 2026-09-02. Model catalogs and aliases change; pin production model IDs and re-check the linked compatibility tables before rollout.
|
||||
|
||||
## Two independent routing knobs
|
||||
|
||||
1. **Model tier** chooses the capability, latency, and cost envelope.
|
||||
2. **Effort / thinking control** changes how much reasoning work a supported
|
||||
model performs for one request.
|
||||
2. **Effort / thinking control** changes how much reasoning work a supported model performs for one request.
|
||||
|
||||
Do not assume that every effort value works with every model or product.
|
||||
Unsupported values may fail, be ignored, or be mapped to another level depending
|
||||
on the client.
|
||||
Do not assume that every effort value works with every model or product. Unsupported values may fail, be ignored, or be mapped to another level depending on the client.
|
||||
|
||||
## OpenAI
|
||||
|
||||
The current GPT-5.6 family exposes the **Sol**, **Terra**, and **Luna** model
|
||||
tiers. Its documented `reasoning.effort` values are `none`, `low`, `medium`,
|
||||
`high`, `xhigh`, and `max`. Availability remains model-specific, so select from
|
||||
the levels shown for the chosen model rather than treating the full list as
|
||||
universal.
|
||||
[OpenAI: latest model guide](https://developers.openai.com/api/docs/guides/latest-model)
|
||||
The current GPT-5.6 family exposes the **Sol**, **Terra**, and **Luna** model tiers. Its documented `reasoning.effort` values are `none`, `low`, `medium`, `high`, `xhigh`, and `max`. Availability remains model-specific, so select from the levels shown for the chosen model rather than treating the full list as universal. [OpenAI: latest model guide](https://developers.openai.com/api/docs/guides/latest-model)
|
||||
|
||||
Use a lower-cost tier and low effort for bounded, mechanical work; raise the
|
||||
model tier or effort for planning, architecture, difficult debugging, and final
|
||||
review. This is routing guidance, not an API guarantee.
|
||||
Use a lower-cost tier and low effort for bounded, mechanical work; raise the model tier or effort for planning, architecture, difficult debugging, and final review. This is routing guidance, not an API guarantee.
|
||||
|
||||
## Anthropic Claude
|
||||
|
||||
### Model tier
|
||||
|
||||
Claude Code provides the aliases `opus`, `sonnet`, and `haiku`: Opus is intended
|
||||
for complex reasoning, Sonnet for everyday coding, and Haiku for simple, fast
|
||||
work. Aliases resolve to provider-dependent recommended versions and can change
|
||||
over time; use a full model ID when reproducibility matters. Claude Code also
|
||||
documents `opusplan`, which uses Opus in plan mode and Sonnet for execution.
|
||||
[Claude Code: model configuration](https://docs.anthropic.com/en/docs/claude-code/model-config)
|
||||
Claude Code provides the aliases `opus`, `sonnet`, and `haiku`: Opus is intended for complex reasoning, Sonnet for everyday coding, and Haiku for simple, fast work. Aliases resolve to provider-dependent recommended versions and can change over time; use a full model ID when reproducibility matters. Claude Code also documents `opusplan`, which uses Opus in plan mode and Sonnet for execution. [Claude Code: model configuration](https://docs.anthropic.com/en/docs/claude-code/model-config)
|
||||
|
||||
Copy-ready Claude Code switches:
|
||||
|
||||
@@ -54,12 +37,7 @@ claude --model opus
|
||||
|
||||
### Effort
|
||||
|
||||
The Claude API parameter is `output_config.effort`. The documented levels are
|
||||
`low`, `medium`, `high`, `xhigh`, and `max`; `high` is the API default. `xhigh`
|
||||
and `max` have narrower model support, and Haiku 4.5 does not support effort.
|
||||
Effort affects the whole response—including thinking and tool calls—and is a
|
||||
behavioral signal, not a strict token budget.
|
||||
[Anthropic: effort](https://docs.anthropic.com/en/docs/build-with-claude/effort)
|
||||
The Claude API parameter is `output_config.effort`. The documented levels are `low`, `medium`, `high`, `xhigh`, and `max`; `high` is the API default. `xhigh` and `max` have narrower model support, and Haiku 4.5 does not support effort. Effort affects the whole response—including thinking and tool calls—and is a behavioral signal, not a strict token budget. [Anthropic: effort](https://docs.anthropic.com/en/docs/build-with-claude/effort)
|
||||
|
||||
Documented Python example:
|
||||
|
||||
@@ -75,45 +53,27 @@ response = client.messages.create(
|
||||
)
|
||||
```
|
||||
|
||||
Claude Code exposes `/effort`; its available choices depend on the active model.
|
||||
Current Claude Code documentation lists `low`, `medium`, `high`, `xhigh`, and
|
||||
`max` for supported Opus versions, while some Opus/Sonnet versions omit `xhigh`.
|
||||
When a selected level is unsupported, Claude Code can fall back to the highest
|
||||
supported level at or below it.
|
||||
[Claude Code: effort compatibility](https://docs.anthropic.com/en/docs/claude-code/model-config#adjust-effort-level)
|
||||
Claude Code exposes `/effort`; its available choices depend on the active model. Current Claude Code documentation lists `low`, `medium`, `high`, `xhigh`, and `max` for supported Opus versions, while some Opus/Sonnet versions omit `xhigh`. When a selected level is unsupported, Claude Code can fall back to the highest supported level at or below it. [Claude Code: effort compatibility](https://docs.anthropic.com/en/docs/claude-code/model-config#adjust-effort-level)
|
||||
|
||||
## Google Gemini
|
||||
|
||||
### Model tier
|
||||
|
||||
Gemini uses model families rather than interchangeable aliases: **Pro** targets
|
||||
the most complex reasoning, **Flash** balances capability and throughput, and
|
||||
**Flash-Lite** prioritizes latency, volume, and cost. Select an explicit
|
||||
endpoint such as `gemini-3.7-flash`; Google recommends stable model names for
|
||||
most production applications because `latest` aliases can be hot-swapped.
|
||||
[Gemini API: models](https://ai.google.dev/gemini-api/docs/models)
|
||||
Gemini uses model families rather than interchangeable aliases: **Pro** targets the most complex reasoning, **Flash** balances capability and throughput, and **Flash-Lite** prioritizes latency, volume, and cost. Select an explicit endpoint such as `gemini-3.7-flash`; Google recommends stable model names for most production applications because `latest` aliases can be hot-swapped. [Gemini API: models](https://ai.google.dev/gemini-api/docs/models)
|
||||
|
||||
### Thinking level
|
||||
|
||||
For Gemini 3 models, the control is `thinkingLevel` in SDKs (`thinking_level` in
|
||||
Python). Across the family the documented values are `minimal`, `low`, `medium`,
|
||||
and `high`, but support and defaults vary by model. For example, Gemini 3.7
|
||||
Flash supports `low`, `medium`, and `high` and defaults to `medium`; Gemini 3.1
|
||||
Pro supports `low`, `medium`, and `high` and defaults to `high`. `minimal` is
|
||||
unavailable on several models and does not guarantee that reasoning is
|
||||
completely off where supported. Gemini 2.5 uses `thinkingBudget`, not
|
||||
`thinkingLevel`.
|
||||
[Gemini API: thinking](https://ai.google.dev/gemini-api/docs/thinking)
|
||||
For Gemini 3 models, the control is `thinkingLevel` in SDKs (`thinking_level` in Python). Across the family the documented values are `minimal`, `low`, `medium`, and `high`, but support and defaults vary by model. For example, Gemini 3.7 Flash supports `low`, `medium`, and `high` and defaults to `medium`; Gemini 3.1 Pro supports `low`, `medium`, and `high` and defaults to `high`. `minimal` is unavailable on several models and does not guarantee that reasoning is completely off where supported. Gemini 2.5 uses `thinkingBudget`, not `thinkingLevel`. [Gemini API: thinking](https://ai.google.dev/gemini-api/docs/thinking)
|
||||
|
||||
Documented JavaScript pattern:
|
||||
|
||||
```javascript
|
||||
import { GoogleGenAI, ThinkingLevel } from '@google/genai';
|
||||
import { GoogleGenAI, ThinkingLevel } from "@google/genai";
|
||||
|
||||
const ai = new GoogleGenAI({});
|
||||
const response = await ai.models.generateContent({
|
||||
model: 'gemini-3.7-flash',
|
||||
contents: 'Review this implementation plan.',
|
||||
model: "gemini-3.7-flash",
|
||||
contents: "Review this implementation plan.",
|
||||
config: {
|
||||
thinkingConfig: {
|
||||
thinkingLevel: ThinkingLevel.LOW,
|
||||
@@ -127,12 +87,10 @@ console.log(response.text);
|
||||
## Practical routing baseline
|
||||
|
||||
| Work | Model tier | Effort / thinking |
|
||||
| --------------------------------------------------- | ------------------------- | -------------------------------------- |
|
||||
| --- | --- | --- |
|
||||
| Formatting, lookup, narrow edit | Haiku / Flash-Lite / Luna | Low or minimal where supported |
|
||||
| Normal implementation, tests, review | Sonnet / Flash / Terra | Medium |
|
||||
| Architecture, orchestration, hard debugging | Opus / Pro / Sol | High |
|
||||
| Frontier or long-horizon work with measured benefit | Strongest supported tier | `xhigh` or `max` only where documented |
|
||||
|
||||
Treat this table as a starting hypothesis. Evaluate quality, latency, and cost
|
||||
on representative tasks, then route to the cheapest combination that still
|
||||
passes the required checks.
|
||||
Treat this table as a starting hypothesis. Evaluate quality, latency, and cost on representative tasks, then route to the cheapest combination that still passes the required checks.
|
||||
|
||||
@@ -1,12 +1,9 @@
|
||||
# Verified skill sources
|
||||
|
||||
Checked on 2026-09-02 against the installed files under `~/.codex/skills`. A
|
||||
pinned blob link identifies the content inspected; the repository/path column
|
||||
identifies what an installer should copy. Pinned commits are preferable to
|
||||
mutable `main` when reproducibility matters.
|
||||
Checked on 2026-09-02 against the installed files under `~/.codex/skills`. A pinned blob link identifies the content inspected; the repository/path column identifies what an installer should copy. Pinned commits are preferable to mutable `main` when reproducibility matters.
|
||||
|
||||
| Skill | Verified source URL | Installable repo URL/path | Confidence / note |
|
||||
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
|---|---|---|---|
|
||||
| `ponytail-lite` | [`AGENTS.md` at `e7b42dc`](https://github.com/ilindaniel/ponytail-lite/blob/e7b42dc2d384a702240dea4d52a7bf5530b821b6/AGENTS.md) | [`ilindaniel/ponytail-lite`](https://github.com/ilindaniel/ponytail-lite), path `AGENTS.md` | **High — exact byte match.** The local `ponytail-lite/SKILL.md` is this file unchanged. Upstream presents it as an agent instruction file, not a conventional frontmatter-based skill package; install it through the host's project/global instruction mechanism. |
|
||||
| `caveman` | [Public upstream skill at `3b74643`](https://github.com/JuliusBrussee/caveman/blob/3b74643f4d910f496babd4e634b1ba7168816f14/skills/caveman/SKILL.md) | [`JuliusBrussee/caveman`](https://github.com/JuliusBrussee/caveman), path `skills/caveman/` | **Medium for the installed file; high for upstream.** The local file is an environment-specific wrapper that names this public project and its skill files, but it is not byte-identical to the public `skills/caveman/SKILL.md`. Install upstream, not the local wrapper. |
|
||||
| `unlazy` | [`SKILL.md` at `473d4b8`](https://github.com/Leonxlnx/unlazy/blob/473d4b80421c36d733042434cd4b938f81a19ef1/SKILL.md) | [`Leonxlnx/unlazy`](https://github.com/Leonxlnx/unlazy), repository root (copy the whole package) | **High — exact byte match**, also corroborated by local `.unlazy-source.txt`. The package includes referenced scripts, templates, security notes, and workflow documents; do not copy only `SKILL.md`. |
|
||||
@@ -41,8 +38,4 @@ Workflow:
|
||||
|
||||
## Verification method
|
||||
|
||||
The seven **exact** findings were established by downloading the pinned public
|
||||
files and comparing them byte-for-byte with the local installed copies. For
|
||||
`caveman`, the local wrapper was compared against both the repository-level
|
||||
instructions and public `skills/caveman/SKILL.md`; neither matched, so only its
|
||||
upstream family is attributed, not the wrapper itself.
|
||||
The seven **exact** findings were established by downloading the pinned public files and comparing them byte-for-byte with the local installed copies. For `caveman`, the local wrapper was compared against both the repository-level instructions and public `skills/caveman/SKILL.md`; neither matched, so only its upstream family is attributed, not the wrapper itself.
|
||||
|
||||
@@ -1,157 +0,0 @@
|
||||
# vote-service
|
||||
|
||||
> The service's source — `main.go`, `Dockerfile`, `go.mod`, and the `deploy/`
|
||||
> manifests — was removed from this repository on 2026-09-06. This runbook stays
|
||||
> because the deployed service is unchanged and the review desk still calls it.
|
||||
> Recover the source with `git show <pre-removal-sha>:vote-service/`.
|
||||
|
||||
Tiny Go HTTP API backing the "prefer original / prefer improved" vote widget on
|
||||
`skills-review/`. One binary, no external dependencies, one JSON file on disk as
|
||||
the store — proportionate to workshop-scale traffic, not a general voting
|
||||
platform.
|
||||
|
||||
## Why a separate service
|
||||
|
||||
`netcracker.pages.marcospaulo.dev.br` is a static Pages Server: it serves files,
|
||||
it cannot run server code or remember state. Any real vote count needs a small
|
||||
stateful service reachable from the visitor's browser, so this lives outside the
|
||||
static repo and runs as its own pod.
|
||||
|
||||
## Anti-abuse: IP, not MAC
|
||||
|
||||
A MAC address is a link-layer detail; it never reaches a server across the
|
||||
internet, so it cannot be used here. "Same source" is approximated by client IP
|
||||
(`X-Forwarded-For` / `X-Real-IP` behind the ingress, else the raw remote
|
||||
address). One IP holds at most one active vote per skill — casting again updates
|
||||
that vote instead of stacking a second one. This is imperfect (NAT, VPNs, shared
|
||||
networks collapse to one vote; IP changes let someone vote again) but matches
|
||||
the ask and needs no cookies, accounts, or client secrets. A `X-Voter-Id` header
|
||||
(a random id the frontend keeps in `localStorage`) is layered on only so a
|
||||
browser can display "you already voted X" — it is never trusted as the sole
|
||||
anti-abuse signal, since `localStorage` is trivially resettable.
|
||||
|
||||
## API
|
||||
|
||||
| Method | Path | Body | Response |
|
||||
| :----- | :--------------------- | :------------------------------------------------ | :----------------------------------------------------------------------------- |
|
||||
| `GET` | `/api/votes` | — | `{ "tallies": { "<skillId>": { "original": n, "improved": n } } }` |
|
||||
| `GET` | `/api/votes?skillId=X` | — | adds `"you": "original"\|"improved"` when the caller's IP already voted on `X` |
|
||||
| `POST` | `/api/votes` | `{"skillId":"X","choice":"original"\|"improved"}` | `{"skillId","original","improved","you"}` |
|
||||
| `GET` | `/healthz` | — | `200` |
|
||||
|
||||
## Run locally
|
||||
|
||||
```bash
|
||||
go run . # PORT=8080 VOTE_DB_PATH=/tmp/votes.json ALLOWED_ORIGIN=http://localhost:4173
|
||||
```
|
||||
|
||||
## Build and publish the image
|
||||
|
||||
Pushed to this cluster's Nexus registry (docker-hosted repo, anonymous read
|
||||
already enabled cluster-wide — no `imagePullSecrets` needed). Push host and pull
|
||||
host differ because Nexus is reached from a workstation via its NodePort but
|
||||
from inside the cluster via its Service DNS name:
|
||||
|
||||
```bash
|
||||
docker build -t localhost:30892/ai-for-dummies-vote-service:latest .
|
||||
docker push localhost:30892/ai-for-dummies-vote-service:latest
|
||||
# pods pull the same image as: nexus-service.nexus.svc.cluster.local:8082/ai-for-dummies-vote-service:latest
|
||||
```
|
||||
|
||||
## Deploy (microk8s)
|
||||
|
||||
The `ai-for-dummies-vote-data` PVC uses `microk8s-hostpath`, whose PVs carry a
|
||||
`nodeAffinity` for whichever node first binds them — so scheduling and storage
|
||||
must agree on one node. This runs on `kubernets` (the control-plane node that
|
||||
hosts the rest of the cluster's workloads), pinned via `nodeSelector` in
|
||||
`deployment.yaml`.
|
||||
|
||||
kubelet's image pulls run in the _host_ network namespace and there is no
|
||||
`certs.d/hosts.toml` entry for `localhost:30892`, so a plain pull of the Nexus
|
||||
ref fails (`no basic auth credentials`). Push to Nexus for a durable off-node
|
||||
copy, then import straight into that node's containerd store and let
|
||||
`imagePullPolicy: Never` skip the network pull entirely — the same pattern the
|
||||
`pragent-webhook` image uses in this cluster:
|
||||
|
||||
```bash
|
||||
docker save localhost:30892/ai-for-dummies-vote-service:latest -o /tmp/vote-service.tar
|
||||
/snap/microk8s/current/bin/ctr --address /var/snap/microk8s/common/run/containerd.sock \
|
||||
--namespace k8s.io image import /tmp/vote-service.tar
|
||||
# use microk8s's own bundled ctr, not the host's — different containerd major
|
||||
# versions speak incompatible client/server protocols (`unknown service
|
||||
# containerd.services.streaming.v1.Streaming` otherwise)
|
||||
|
||||
microk8s kubectl apply -f deploy/deployment.yaml # namespace + Deployment + PVC + Service
|
||||
microk8s kubectl apply -f deploy/ingress.yaml
|
||||
microk8s kubectl -n ai-for-dummies rollout restart deploy ai-for-dummies-vote
|
||||
```
|
||||
|
||||
Re-run the `docker save`/`ctr image import` pair after every image rebuild —
|
||||
`imagePullPolicy: Never` means the cluster never fetches a newer tag on its own,
|
||||
and a `rollout restart` is what picks the new image up.
|
||||
|
||||
## Public exposure
|
||||
|
||||
Public traffic reaches the cluster through **Caddy on the Oracle VPS over
|
||||
Tailscale**, which is how all ~21 public hosts in this account are served
|
||||
(`langfuse`, `pragent-dashboard`, `vault`, …) — _not_ through the cloudflared
|
||||
tunnel. The tunnel's public-hostname routes are dashboard-managed and the DNS
|
||||
API token cannot write them, so the Caddy path is also the only one that can be
|
||||
automated end to end.
|
||||
|
||||
```bash
|
||||
cf-dns add ai-for-dummies-vote A 129.148.56.8 # DNS-only (grey cloud), like every other Caddy host
|
||||
```
|
||||
|
||||
Caddy block (`/etc/caddy/Caddyfile` on the VPS, local copy
|
||||
`~/scripts/Caddyfile`):
|
||||
|
||||
```caddyfile
|
||||
ai-for-dummies-vote.marcospaulo.dev.br {
|
||||
tls {
|
||||
dns cloudflare <CF_TOKEN>
|
||||
}
|
||||
reverse_proxy 100.74.17.70:80 {
|
||||
header_up Host {host}
|
||||
header_up X-Client-IP {remote_host}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
It proxies to port `80` (not a NodePort): the cluster's nginx ingress runs on
|
||||
`hostNetwork` on `kubernets` and routes by `Host`.
|
||||
|
||||
### Why `X-Client-IP`
|
||||
|
||||
The ingress controller runs with `use-forwarded-headers` **off** (the microk8s
|
||||
default — `nginx-load-balancer-microk8s-conf` has no `data`). nginx therefore
|
||||
_overwrites_ `X-Forwarded-For` and `X-Real-IP` with its own downstream peer,
|
||||
which is the VPS's tailnet address `100.67.25.57`. Every visitor would collapse
|
||||
into one voter, and since one IP holds at most one active vote per skill, each
|
||||
skill would only ever hold a single vote in total — the anti-abuse rule would
|
||||
silently become a hard cap.
|
||||
|
||||
Rather than flip `use-forwarded-headers` globally (it would change client-IP
|
||||
handling for every other ingress in the cluster), Caddy stamps the true remote
|
||||
address into `X-Client-IP`, a non-standard header nginx forwards untouched, and
|
||||
`clientIP()` reads it first. `header_up` sets it unconditionally, so a public
|
||||
client cannot spoof it; the trust placed in it is exactly the trust already
|
||||
placed in `X-Forwarded-For`.
|
||||
|
||||
Verified after deploy: requests from two distinct sources are recorded as two
|
||||
separate votes rather than overwriting one another.
|
||||
|
||||
## Frontend wiring
|
||||
|
||||
`skills-review/index.html` sets `window.SKILLS_REVIEW_VOTE_API` to
|
||||
`https://ai-for-dummies-vote.marcospaulo.dev.br`; keep it in sync with
|
||||
`ALLOWED_ORIGIN` in `deployment.yaml`
|
||||
(`https://netcracker.pages.marcospaulo.dev.br`), which is the real caller
|
||||
boundary — CORS restricts which origin's browser code may call the API, not
|
||||
which network can reach it.
|
||||
|
||||
`replicas: 1` and `strategy: Recreate` are deliberate: the store is one file on
|
||||
one `ReadWriteOnce` PVC, so two pods writing it concurrently would race. Scale
|
||||
up only after moving the store to something that supports concurrent writers
|
||||
(e.g. SQLite on a shared volume with proper locking, or Postgres) — not needed
|
||||
at this traffic scale.
|
||||
@@ -1,41 +0,0 @@
|
||||
import js from '@eslint/js';
|
||||
import astro from 'eslint-plugin-astro';
|
||||
|
||||
export default [
|
||||
{
|
||||
ignores: [
|
||||
'.agents/**',
|
||||
'.astro/**',
|
||||
'dist/**',
|
||||
'hands-on/**',
|
||||
'legacy/**',
|
||||
'public/hands-on/**',
|
||||
'scripts/**',
|
||||
'skill-reviews/**',
|
||||
'skills/**',
|
||||
'submitted-skills/**',
|
||||
'vote-service/**',
|
||||
],
|
||||
},
|
||||
js.configs.recommended,
|
||||
...astro.configs.recommended,
|
||||
{
|
||||
ignores: [
|
||||
'dist/**',
|
||||
'hands-on/**',
|
||||
'legacy/**',
|
||||
'public/hands-on/**',
|
||||
'submitted-skills/**',
|
||||
'skill-reviews/**',
|
||||
'vote-service/**',
|
||||
],
|
||||
},
|
||||
{
|
||||
rules: {
|
||||
'no-console': ['warn', { allow: ['warn', 'error'] }],
|
||||
eqeqeq: ['error', 'always'],
|
||||
'no-var': 'error',
|
||||
'prefer-const': 'error',
|
||||
},
|
||||
},
|
||||
];
|
||||
@@ -15,7 +15,7 @@
|
||||
.handoff thead{position:absolute;width:1px;height:1px;overflow:hidden;clip:rect(0 0 0 0)}
|
||||
.handoff tbody tr{padding:14px 0;border-bottom:1px solid var(--line)}
|
||||
.handoff th,.handoff td{padding:4px 0;border:0}
|
||||
.handoff td::before{display:block;margin-top:7px;color:var(--blue);font:600 9px var(--font-mono);letter-spacing:.08em;text-transform:uppercase}
|
||||
.handoff td::before{display:block;margin-top:7px;color:var(--blue);font:600 9px 'DM Mono',monospace;letter-spacing:.08em;text-transform:uppercase}
|
||||
.handoff td:nth-child(2)::before{content:'Contains'}
|
||||
.handoff td:nth-child(3)::before{content:'Why it matters'}
|
||||
.route-table .head{display:none}
|
||||
@@ -0,0 +1,37 @@
|
||||
<!doctype html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<link rel="stylesheet" href="../responsive.css" />
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
<meta name="description" content="AI For Dummies: a field guide to skills, models, subagents, and worktrees." />
|
||||
<title>AI For Dummies — Field Guide</title>
|
||||
<link rel="stylesheet" href="../styles.css" />
|
||||
<link rel="stylesheet" href="audit.css" />
|
||||
</head>
|
||||
<body>
|
||||
<div class="reading-progress" aria-hidden="true"><span></span></div>
|
||||
<main>
|
||||
<header class="topbar"><a class="brand" href="#top"><span class="mark">A</span> field guide</a><nav class="chapter-links" aria-label="Chapter sections"><a href="#fleet">01 fleet</a><a href="#worktrees">02 worktrees</a><a href="#models">03 models</a><a href="#skills">04 skills</a><a href="#create-skill">05 create</a><a href="#field-kit">06 field kit</a><a href="#hands-on">07 hands-on</a><a href="#verification">08 verify</a></nav><div class="topbar-tools"><a class="skills-review-link" href="../skills-review/">review submissions ↗</a><div class="lang-switch" aria-label="Language"><button class="active" data-lang="en" aria-pressed="true">EN</button><span>/</span><button data-lang="pt" aria-pressed="false">PT</button></div><span class="edition">AI ENGINEERING <i></i> 01 / 2026</span></div></header>
|
||||
<section class="hero" id="top"><div><p class="eyebrow">A presentation for humans who ship</p><h1>AI for<br /><em>dummies.</em></h1><p class="lede">You do not need an army of models. You need a system: one mind to frame the work, several hands to execute it, and a clean boundary between every task.</p></div><aside class="hero-index"><span>FIELD NOTE / 001</span><strong>Ship the<br /><em>system.</em></strong><small>Skills · agents · worktrees · proof</small></aside></section>
|
||||
<section class="hero-stats" aria-label="Chapter summary"><div><strong>01</strong><span>strong model<br />for ambiguity</span></div><div><strong>03</strong><span>bounded workers<br />in parallel</span></div><div><strong>∞</strong><span>iterations<br />with evidence</span></div><p>Read this as a route map, not a prompt recipe.</p></section>
|
||||
<section class="thesis"><div><span>RULE ZERO</span><strong>Strong model for ambiguity.<br />Light model for bounded work.</strong></div><div class="signal" aria-hidden="true"><b>THINK</b><i></i><i></i><i></i><b>MAKE</b></div></section>
|
||||
<section class="fleet" id="fleet"><div class="section-label"><span>A small fleet</span><span>coordination before parallelism</span></div><div class="fleet-grid"><article class="captain"><span>ORCHESTRATOR</span><h2>Decides what<br />needs to happen.</h2><code>Opus / reasoning</code></article><div class="arrow">→</div><div class="workers" role="group" aria-label="Worker agents"><button class="worker-card active" data-worker="ui" aria-pressed="true"><span>UI</span><strong>Component and visual states</strong><code>agent/ui</code></button><button class="worker-card" data-worker="tests" aria-pressed="false"><span>TEST</span><strong>Acceptance cases</strong><code>agent/tests</code></button><button class="worker-card" data-worker="docs" aria-pressed="false"><span>DOCS</span><strong>Guide and examples</strong><code>agent/docs</code></button></div></div><div class="worker-detail" id="worker-detail" aria-live="polite"></div><p class="caption">The orchestrator preserves intent, writes small contracts, and gathers results that can be verified. It does not need to type every line.</p></section>
|
||||
<section class="failure-map"><div class="section-label"><span>Why the boundary matters</span><span>one vague task / three predictable failures</span></div><div class="failure-grid"><article><span>01</span><strong>Context soup</strong><p>Every worker reads everything. Nobody knows which facts are load-bearing.</p></article><article><span>02</span><strong>Branch collision</strong><p>Two agents touch the same checkout. The fastest path becomes conflict resolution.</p></article><article><span>03</span><strong>Confident drift</strong><p>The diff is polished, but no one checks whether it solved the original problem.</p></article></div></section>
|
||||
<section class="workflow" aria-labelledby="workflow-title"><div class="copy"><p class="eyebrow">The subagent loop</p><h2 id="workflow-title">Click a phase.<br /><em>See the handoff.</em></h2><p>Delegation means moving one bounded task into a smaller context—not giving away responsibility.</p></div><div class="phase-tabs" role="tablist" aria-label="Workflow phases"><button class="active" data-phase="plan" role="tab" aria-selected="true"><b>01</b> PLAN</button><button data-phase="build" role="tab" aria-selected="false"><b>02</b> BUILD</button><button data-phase="review" role="tab" aria-selected="false"><b>03</b> REVIEW</button></div><article class="phase-panel" id="phase-panel" aria-live="polite"></article></section>
|
||||
<section class="handoff"><div class="section-label"><span>What crosses contexts</span><span>brief → diff → evidence</span></div><table><thead><tr><th>Package</th><th>Contains</th><th>Why it matters</th></tr></thead><tbody><tr><th scope="row">Brief</th><td>goal, files, boundaries</td><td>stops the worker inventing the problem</td></tr><tr><th scope="row">Worktree</th><td>branch and isolated checkout</td><td>parallel edits do not collide</td></tr><tr><th scope="row">Checks</th><td>tests, build, criteria</td><td>turns “looks good” into evidence</td></tr><tr><th scope="row">Diff</th><td>small, reviewable change</td><td>integration and discard stay cheap</td></tr></tbody></table></section>
|
||||
<section class="worktrees" id="worktrees"><div class="worktree-intro"><p class="eyebrow">Git worktrees</p><h2>One branch<br />per <em>hand.</em></h2><p>A worktree is another directory linked to the same repository. Each agent gets its own checkout and index; history remains shared.</p><p class="interaction-hint">Select a node to inspect its checkout, owner, and next action.</p></div><div class="tree-lab"><div class="tree-toolbar"><span>repository topology</span><span class="tree-live"><i></i> 4 checkouts</span></div><div class="tree-stage" role="tree" aria-label="Repository worktree topology"><svg viewBox="0 0 760 330" preserveAspectRatio="none" aria-hidden="true"><path class="tree-edge trunk" d="M380 48 V118"/><path class="tree-edge" d="M380 118 C380 170 110 150 110 224"/><path class="tree-edge" d="M380 118 V224"/><path class="tree-edge" d="M380 118 C380 170 650 150 650 224"/></svg><button class="tree-node root active" data-tree="main" role="treeitem" aria-selected="true"><span>ROOT</span><strong>main</strong><small>● clean</small></button><button class="tree-node branch ui" data-tree="ui" role="treeitem" aria-selected="false"><span>UI AGENT</span><strong>agent/ui</strong><small>3 files · working</small></button><button class="tree-node branch tests" data-tree="tests" role="treeitem" aria-selected="false"><span>TEST AGENT</span><strong>agent/tests</strong><small>8 checks · ready</small></button><button class="tree-node branch docs" data-tree="docs" role="treeitem" aria-selected="false"><span>DOCS AGENT</span><strong>agent/docs</strong><small>2 pages · review</small></button></div><article class="tree-detail" id="tree-detail" aria-live="polite"></article></div></section>
|
||||
<section class="routing"><div><p class="eyebrow">Model routing</p><h2>Do not pay for<br />reasoning where<br />you need <em>rhythm.</em></h2><p class="interaction-hint">Choose a job to see why the model profile changes.</p></div><div class="route-console"><div class="route-table"><div class="head"><span>Work</span><span>Profile</span><span>Prompt shape</span></div><button class="active" data-route="plan" aria-pressed="true"><strong>Plan</strong><b>strong / broad</b><small>What changes? What can break?</small></button><button data-route="build" aria-pressed="false"><strong>Build</strong><b>fast / focused</b><small>Implement this slice. Run these checks.</small></button><button data-route="explore" aria-pressed="false"><strong>Explore</strong><b>read-only / light</b><small>Find where this contract is used.</small></button><button data-route="review" aria-pressed="false"><strong>Review</strong><b>independent</b><small>Does the diff satisfy the brief?</small></button></div><article class="route-detail" id="route-detail" aria-live="polite"></article></div></section>
|
||||
<section class="model-gearbox" id="models"><div class="section-label"><span>Model gearbox</span><span>capability tier × thinking effort</span></div><div class="gearbox-intro"><div><p class="eyebrow">Two separate knobs</p><h2>Choose the engine.<br />Then choose the <em>gear.</em></h2></div><p>A stronger model changes the capability ceiling. Higher reasoning effort gives that model more room to work. Start with the lightest combination that passes your real checks, then move one knob at a time.</p></div><div class="gearbox"><div class="provider-tabs" role="tablist" aria-label="Model providers"><button class="active" data-model-provider="openai" role="tab" aria-selected="true">OPENAI</button><button data-model-provider="claude" role="tab" aria-selected="false">CLAUDE</button><button data-model-provider="gemini" role="tab" aria-selected="false">GEMINI</button></div><article class="provider-detail" id="provider-detail" aria-live="polite"></article><div class="effort-rail"><span>REASONING / THINKING</span><button data-effort="low" aria-pressed="false"><b>LOW</b><small>bounded + fast</small></button><button class="active" data-effort="medium" aria-pressed="true"><b>MEDIUM</b><small>default start</small></button><button data-effort="high" aria-pressed="false"><b>HIGH</b><small>complex + costly</small></button></div><article class="effort-detail" id="effort-detail" aria-live="polite"></article></div><div class="gearbox-rule"><span>ROUTING RULE</span><strong>Use strong models for ambiguity and judgment. Use lighter models for bounded execution. Raise effort only when evaluation shows a gain.</strong></div></section>
|
||||
<section class="skills" id="skills"><div><p class="eyebrow">Skills</p><h2>Write the right way<br /><em>once.</em></h2><p>A skill is a reusable procedure. It can carry instructions, references, scripts, and assets. It is not magical memory, and it does not replace acceptance criteria.</p><div class="skill-principles"><span>01 / trigger clearly</span><span>02 / load detail on demand</span><span>03 / return evidence</span></div></div><div class="skill-explorer"><div class="skill-package" role="tree" aria-label="Skill package files"><span>SKILL PACKAGE</span><button class="active" data-skill-file="skill" role="treeitem" aria-selected="true"><code>SKILL.md</code><small>procedure and limits</small></button><button data-skill-file="references" role="treeitem" aria-selected="false"><code>references/</code><small>facts to consult</small></button><button data-skill-file="scripts" role="treeitem" aria-selected="false"><code>scripts/</code><small>repeatable checks</small></button><button data-skill-file="assets" role="treeitem" aria-selected="false"><code>assets/</code><small>templates and examples</small></button></div><article class="skill-detail" id="skill-detail" aria-live="polite"></article></div><pre><code>name: review-ui · check focus, mobile, reduced motion · run verification · return evidence</code></pre></section>
|
||||
<section class="skill-builder" id="create-skill"><div class="section-label"><span>Create a skill</span><span>repeatable pain → reusable judgment</span></div><div class="builder-intro"><div><p class="eyebrow">The skill forge</p><h2>Teach the decision.<br />Keep the context <em>light.</em></h2></div><p>Do not package everything you know. Capture the non-obvious choices that repeatedly improve an outcome, then prove the skill changes behavior.</p></div><div class="builder-workbench"><nav class="builder-steps" role="tablist" aria-label="Skill creation workflow"><button class="active" data-skill-step="observe" role="tab" aria-selected="true"><b>01</b><span>Observe</span><small>find repeated friction</small></button><button data-skill-step="trigger" role="tab" aria-selected="false"><b>02</b><span>Define trigger</span><small>route precisely</small></button><button data-skill-step="scaffold" role="tab" aria-selected="false"><b>03</b><span>Choose anatomy</span><small>only needed files</small></button><button data-skill-step="write" role="tab" aria-selected="false"><b>04</b><span>Write guidance</span><small>decisions, not trivia</small></button><button data-skill-step="validate" role="tab" aria-selected="false"><b>05</b><span>Validate</span><small>test real behavior</small></button></nav><article class="builder-detail" id="builder-detail" aria-live="polite"></article><aside class="builder-artifact"><div class="artifact-head"><span>OUTPUT / SKILL PACKAGE</span><i></i></div><pre aria-label="Example skill structure"><code>review-ui/<br />├── SKILL.md<br />├── agents/<br />│ └── openai.yaml<br />├── references/<br />│ └── accessibility.md<br />└── scripts/<br /> └── verify.mjs</code></pre><div class="artifact-command"><span>VALIDATE</span><code>quick_validate.py ./review-ui</code></div></aside></div><div class="builder-loop"><span>AFTER REAL USE</span><div><b>observe failure</b><i>→</i><b>sharpen one rule</b><i>→</i><b>retest behavior</b><i>→</i><b>keep it narrow</b></div></div></section>
|
||||
<section class="skill-catalog" id="field-kit"><div class="section-label"><span>Common skills</span><span>choose behavior before model</span></div><div class="catalog-intro"><div><p class="eyebrow">The field kit</p><h2>Different jobs.<br />Different <em>instincts.</em></h2></div><p>A skill changes how an agent approaches work. Some shape communication. Others enforce research, debugging, review, or completion discipline. Select one to inspect its operating rule and verified source.</p></div><div class="skill-deck"><div class="skill-index" role="tablist" aria-label="Common agent skills"><button class="active" data-common-skill="ponytail" role="tab" aria-selected="true"><span>SIMPLIFY</span><strong>ponytail-lite</strong><small>minimum code that holds</small></button><button data-common-skill="caveman" role="tab" aria-selected="false"><span>COMMUNICATE</span><strong>caveman</strong><small>signal without filler</small></button><button data-common-skill="unlazy" role="tab" aria-selected="false"><span>COMPLETE</span><strong>unlazy</strong><small>gates and evidence</small></button><button data-common-skill="research" role="tab" aria-selected="false"><span>INVESTIGATE</span><strong>research</strong><small>primary sources first</small></button><button data-common-skill="debug" role="tab" aria-selected="false"><span>DIAGNOSE</span><strong>diagnosing-bugs</strong><small>tight feedback loop</small></button><button data-common-skill="review" role="tab" aria-selected="false"><span>REVIEW</span><strong>code-review</strong><small>standards × spec</small></button><button data-common-skill="tokens" role="tab" aria-selected="false"><span>ECONOMIZE</span><strong>token-saver</strong><small>compress noisy output</small></button></div><article class="common-skill-detail" id="common-skill-detail" aria-live="polite"></article></div><div class="skill-loadout"><span>ONE PRACTICAL LOADOUT</span><div><b>PLAN</b> unlazy <i>→</i> <b>BUILD</b> ponytail-lite <i>→</i> <b>DEBUG</b> diagnosing-bugs <i>→</i> <b>REPORT</b> caveman</div></div><article class="install-skills"><header><div><span>INSTALL PACK</span><strong>Ask your coding agent to verify, install, and validate the skills.</strong></div><button data-copy-target="prompt-install-skills"><span>COPY</span><i aria-hidden="true">↗</i></button></header><pre><code id="prompt-install-skills"></code></pre><footer>Review every source before installation. Existing local skills must be preserved.</footer></article></section>
|
||||
<section class="hands-on" id="hands-on"><div class="section-label"><span>Hands-on</span><span>10 minutes / one missing feature</span></div><div class="hands-intro"><div><p class="eyebrow">Tiny Tasks lab</p><h2>Same task.<br />Better <em>operating system.</em></h2></div><div><p>Start with a deliberately incomplete static task board. Run one prompt as written, reset, then run the skill-enabled version. Compare diff size, verification evidence, and unnecessary complexity.</p><div class="starter-links"><div class="starter-link-group"><a href="../hands-on/starter/" class="starter-link">Open the starter →</a><a href="https://git.marcospaulo.dev.br/netcracker/ai-for-dummies/src/branch/pages/hands-on/starter" class="starter-link starter-link-source">Clone from Gitea →</a></div><div class="starter-link-group"><a href="../hands-on/rules/" class="starter-link">Open the rules lab →</a><a href="https://git.marcospaulo.dev.br/netcracker/ai-for-dummies/src/branch/pages/hands-on/rules" class="starter-link starter-link-source">Clone from Gitea →</a></div></div></div></div><div class="exercise-brief"><span>THE MISSING FEATURE</span><strong>Add All / Open / Done filters that survive reload and browser navigation.</strong><div><b>STACK</b> HTML · CSS · JavaScript <b>DEPENDENCIES</b> none <b>FILES</b> 3</div></div><div class="prompt-compare"><article class="prompt-card"><header><div><span>RUN A</span><strong>Good prompt</strong></div><button data-copy-target="prompt-basic"><span>COPY</span><i aria-hidden="true">↗</i></button></header><pre><code id="prompt-basic"></code></pre><footer>Clear context · constraints · acceptance · evidence</footer></article><article class="prompt-card enhanced"><header><div><span>RUN B</span><strong>Good prompt + skills</strong></div><button data-copy-target="prompt-skills"><span>COPY</span><i aria-hidden="true">↗</i></button></header><pre><code id="prompt-skills"></code></pre><footer>Same contract · explicit working methods · stronger proof</footer></article></div><div class="comparison-strip"><span>COMPARE THE RUNS</span><div><b>01</b> Files changed</div><div><b>02</b> New dependencies</div><div><b>03</b> Checks actually run</div><div><b>04</b> Evidence returned</div></div><p class="copy-status" id="copy-status" role="status" aria-live="polite"></p></section>
|
||||
<aside class="rule"><span>THE HUMAN JOB</span><strong>The agent may be autonomous in execution. Intent, boundaries, and evidence remain yours.</strong></aside><aside class="callout"><span>START HERE</span><strong>Begin with one agent and one skill. Add parallelism only when the tasks are truly independent.</strong></aside>
|
||||
<section class="verification" id="verification"><div class="section-label"><span>Verification</span><span>run each gate separately</span></div><div class="verify-intro"><div><p class="eyebrow">Checks become evidence</p><h2>Three layers.<br />Run each one alone.</h2></div><p>Run a gate on its own line, print its exit code, attach the output. The result is the deliverable.</p></div><div class="verify-layers"><article><span>01 · STATIC</span><h3>Lint and types</h3><p>Format, lint, type-check. Fast and scoped to one file. Run on every save.</p><code>pnpm lint; echo "lint=$?"
|
||||
pnpm typecheck; echo "typecheck=$?"</code></article><article><span>02 · BEHAVIOR</span><h3>Unit and contract</h3><p>Tests that repeat. Run before claiming done.</p><code>pnpm test; echo "test=$?"
|
||||
cd services/api && go test ./...</code></article><article><span>03 · INTEGRATION</span><h3>Real UI and API</h3><p>Drive the actual UI, API, or browser. Slower and flakier — only this catches mobile overflow and a missing 404.</p><code>pnpm check:ui; echo "ui=$?"
|
||||
TURBO_FORCE=true pnpm e2e</code></article></div><div class="verify-antipatterns"><span>FOUR WAYS A GREEN REPORT IS FALSE</span><div class="ap-grid"><article><b>1</b><div><strong>Pipe a gate</strong><p>tail, grep, or head hide the real exit code — a pipeline returns the last command's status.</p></div></article><article><b>2</b><div><strong>Swallow a rejection</strong><p>A silent <code>.catch(() => {})</code> hides a panic, an upstream limit, or a partial failure.</p></div></article><article><b>3</b><div><strong>Trust the cache</strong><p>Turbo caches results. A gate that "passes" may not have run — use <code>TURBO_FORCE=true</code>.</p></div></article><article><b>4</b><div><strong>Skip the third layer</strong><p>Lint and unit can both be green while the page breaks on mobile and the API never returns 404.</p></div></article></div></div><article class="verify-cta"><span>RUN IT YOURSELF · two labs, under 10 minutes each</span><div class="verify-cta-grid"><a href="../hands-on/starter/" class="verify-card"><strong>Path A · verification lab</strong><p>Fill the four-row comparison strip on the starter. Run A naively, Run B with <code>$gate-discipline</code> and <code>$webapp-testing</code>.</p><small>Open the starter →</small><small class="verify-card-source">Clone ↗ <span>git.marcospaulo.dev.br/.../src/branch/pages/hands-on/starter</span></small></a><a href="../hands-on/rules/" class="verify-card"><strong>Path B · rules lab</strong><p>Toggle every rule off, run the prompt. Toggle every rule on, run it again. Compare diff size, gate invocations, and the names of checks the agent names back.</p><small>Open the rules lab →</small><small class="verify-card-source">Clone ↗ <span>git.marcospaulo.dev.br/.../src/branch/pages/hands-on/rules</span></small></a></div></article></section>
|
||||
<section class="sources"><div class="section-label"><span>Keep learning</span><span>12 new readings + primary docs</span></div><p>Go deeper with official documentation, production case studies, Medium, and practitioner workflows. <a href="../rules/">Rules and enforcement case study →</a> <a href="../skills-review/">Skills review desk →</a> <a href="../docs/references/README.md">Primary references →</a> <a href="../docs/references/additional-reading.md">12-part reading path →</a></p></section>
|
||||
<section class="chapter-route"><div class="section-label"><span>Navigate by idea</span><span>short chapters / one system</span></div><p>Prefer a focused chapter? Start with the <a href="../summary/">route map</a>, then jump directly to <a href="../models/">models</a>, <a href="../agents/">agents and worktrees</a>, <a href="../skills/">skill creation</a>, <a href="../rules/">rules</a>, or the <a href="../skills-review/">skills review desk</a>.</p></section></main><script src="../app.js" defer></script>
|
||||
</body></html>
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user