From 054393f7af612a66c8f47a61b4be9a5973f1f034 Mon Sep 17 00:00:00 2001 From: Marcos Paulo Date: Sat, 5 Sep 2026 22:30:50 +0000 Subject: [PATCH] feat(15d): complete localization of full-guide page to PT --- .agents/agents/motion-designer.md | 5 +- .agents/agents/reviewer.md | 8 +- .agents/context/architecture.md | 39 +- .agents/rules/accessibility.md | 3 +- .agents/rules/animation.md | 12 +- .agents/rules/astro.md | 25 +- .agents/rules/code-style.md | 6 +- .agents/rules/componentization.md | 3 +- .agents/rules/content-i18n.md | 4 +- .agents/scripts/snapshot-route.mjs | 8 +- .agents/skills/content-migration/SKILL.md | 9 +- .agents/skills/motion/SKILL.md | 29 +- .agents/skills/verify-contract/SKILL.md | 23 +- .agents/templates/components/grid-group.astro | 6 +- .agents/templates/components/island.astro | 55 ++- .../templates/components/static-block.astro | 8 +- .agents/templates/config/.stylelintrc.json | 6 +- .agents/templates/config/eslint.config.js | 10 +- .agents/templates/config/gitea-ci.yaml | 2 +- .agents/templates/pages/chapter.astro | 31 +- .agents/templates/pages/interactive.astro | 17 +- GATES.md | 46 +- agents/index.html | 89 +++- docs/references/README.md | 49 ++- docs/references/additional-reading.md | 69 ++- docs/references/model-routing.md | 82 +++- docs/references/skill-sources.md | 31 +- index.html | 100 +++-- models/index.html | 88 +++- plans/astro-refactor/task-05-content-guide.md | 19 +- .../astro-refactor/task-06-content-review.md | 14 +- plans/astro-refactor/task-17-hands-on.md | 6 +- scripts/verify.mjs | 394 ++++++++++++++++-- src/components/blocks/RouteTable.astro | 56 ++- src/components/blocks/SkillPackage.astro | 18 +- src/components/blocks/WorktreeMap.astro | 35 +- src/pages/full-guide.astro | 171 ++++++-- summary/index.html | 71 +++- 38 files changed, 1322 insertions(+), 325 deletions(-) diff --git a/.agents/agents/motion-designer.md b/.agents/agents/motion-designer.md index 14a13ee..d9dfc16 100644 --- a/.agents/agents/motion-designer.md +++ b/.agents/agents/motion-designer.md @@ -1,6 +1,9 @@ --- 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. +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 --- diff --git a/.agents/agents/reviewer.md b/.agents/agents/reviewer.md index 268b1c6..ffc448b 100644 --- a/.agents/agents/reviewer.md +++ b/.agents/agents/reviewer.md @@ -1,6 +1,9 @@ --- 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. +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 --- @@ -8,7 +11,8 @@ 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. +**Read**: the task file, then every rule in `.agents/rules/` relevant to the +diff. ## Order of checks — highest-value first diff --git a/.agents/context/architecture.md b/.agents/context/architecture.md index 1220b53..33b0252 100644 --- a/.agents/context/architecture.md +++ b/.agents/context/architecture.md @@ -4,18 +4,18 @@ Ten hand-written HTML pages, each linking its own CSS and one ES module: -| Route | Page | Script | Stylesheets | -| --- | --- | --- | --- | -| `/` | `index.html` | — | `chapters.css`, `landing.css` | -| `/full-guide/` | `full-guide/index.html` | `app.js` (50 KB) | `styles.css`, `responsive.css`, `audit.css` | -| `/summary/` | `summary/index.html` | — | `chapters.css` | -| `/models/` | `models/index.html` | — | `chapters.css` | -| `/agents/` | `agents/index.html` | — | `chapters.css` | -| `/skills/` | `skills/index.html` | `skills/app.js` | `skills/styles.css` | -| `/rules/` | `rules/index.html` | `rules/app.js` | `rules/styles.css` | -| `/skills-review/` | `skills-review/index.html` | `skills-review/app.js` | `skills-review/styles.css`, `change-lens.css` | -| `/hands-on/starter/` | lab fixture | own | own | -| `/hands-on/rules/` | lab fixture | own | own | +| Route | Page | Script | Stylesheets | +| -------------------- | -------------------------- | ---------------------- | --------------------------------------------- | +| `/` | `index.html` | — | `chapters.css`, `landing.css` | +| `/full-guide/` | `full-guide/index.html` | `app.js` (50 KB) | `styles.css`, `responsive.css`, `audit.css` | +| `/summary/` | `summary/index.html` | — | `chapters.css` | +| `/models/` | `models/index.html` | — | `chapters.css` | +| `/agents/` | `agents/index.html` | — | `chapters.css` | +| `/skills/` | `skills/index.html` | `skills/app.js` | `skills/styles.css` | +| `/rules/` | `rules/index.html` | `rules/app.js` | `rules/styles.css` | +| `/skills-review/` | `skills-review/index.html` | `skills-review/app.js` | `skills-review/styles.css`, `change-lens.css` | +| `/hands-on/starter/` | lab fixture | own | own | +| `/hands-on/rules/` | lab fixture | own | own | Weight is concentrated: `app.js` 50 KB, `responsive.css` 30 KB, `skills-review/catalog.js` 27 KB, `skills-review/submitted-catalog.js` 18 KB. @@ -35,7 +35,8 @@ Weight is concentrated: `app.js` 50 KB, `responsive.css` 30 KB, `wins[]`, `improve[]`, `extras`, `improved` (full markdown). 24 entries across `catalog.js` + `submitted-catalog.js`. This is already a content collection in all but name. -- **`skills-review/files.js` / `submitted-files.js`** — generated file manifests. +- **`skills-review/files.js` / `submitted-files.js`** — generated file + manifests. - **`vote.js`** — the vote widget island; talks to `vote-service/`. ## Target (Astro) @@ -53,12 +54,12 @@ public/ ### Non-negotiables for the target -- **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 today. - They must still ship none. Islands are opt-in, per component, and justified. +- **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 today. They + must still ship none. Islands are opt-in, per component, and justified. - **`hands-on/` stays vanilla.** It goes in `public/` untouched. It is a lab fixture, not a component. - **No external runtime requests.** `audit-ui.mjs` enforces this and it is part diff --git a/.agents/rules/accessibility.md b/.agents/rules/accessibility.md index beaf75f..69a6a95 100644 --- a/.agents/rules/accessibility.md +++ b/.agents/rules/accessibility.md @@ -49,4 +49,5 @@ likely to fail; verify before shipping. ## Bilingual content `` must change with the language toggle, not just the text. Screen -readers pick pronunciation from it. This already works today — do not regress it. +readers pick pronunciation from it. This already works today — do not regress +it. diff --git a/.agents/rules/animation.md b/.agents/rules/animation.md index 6ecdffc..7d5415c 100644 --- a/.agents/rules/animation.md +++ b/.agents/rules/animation.md @@ -20,12 +20,16 @@ Several current stylesheets already honour it. Every new animation must: ```css @media (prefers-reduced-motion: reduce) { - * { animation-duration: .01ms !important; animation-iteration-count: 1 !important; - transition-duration: .01ms !important; scroll-behavior: auto !important; } + * { + 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 +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`. @@ -35,7 +39,7 @@ Emulate `prefers-reduced-motion`. 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. + 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. diff --git a/.agents/rules/astro.md b/.agents/rules/astro.md index 5bad9b5..2a49055 100644 --- a/.agents/rules/astro.md +++ b/.agents/rules/astro.md @@ -15,12 +15,12 @@ this site's ten pages ship no JS today and must continue to. 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 `vote-service/` | `client:visible` | -| Language toggle | swaps EN/PT across the page | `client:idle` | +| 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 `vote-service/` | `client:visible` | +| Language toggle | swaps EN/PT across the page | `client:idle` | ## Structure @@ -31,8 +31,11 @@ Only these need interactivity. Anything else claiming island status is wrong: // 3. destructure Astro.props // 4. derived values — no side effects, no fetch in components --- + - + ``` - Typed props always: `interface Props { … }`, then `const { … } = Astro.props`. @@ -60,13 +63,13 @@ almost one-to-one — do that rather than importing a 27 KB JS file. 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. +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 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. diff --git a/.agents/rules/code-style.md b/.agents/rules/code-style.md index 7d93492..2a79483 100644 --- a/.agents/rules/code-style.md +++ b/.agents/rules/code-style.md @@ -3,7 +3,7 @@ ## 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 +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 @@ -44,5 +44,5 @@ overrides, and the temptation during migration will be to port it wholesale ## Commits -Present tense, lowercase, `type: subject`, matching the existing log -(`feat:`, `fix:`, `docs:`). The body explains why, and states what you did not do. +Present tense, lowercase, `type: subject`, matching the existing log (`feat:`, +`fix:`, `docs:`). The body explains why, and states what you did not do. diff --git a/.agents/rules/componentization.md b/.agents/rules/componentization.md index 4adb3fc..3f9a154 100644 --- a/.agents/rules/componentization.md +++ b/.agents/rules/componentization.md @@ -3,7 +3,8 @@ ## 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"). +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. diff --git a/.agents/rules/content-i18n.md b/.agents/rules/content-i18n.md index 0e9c724..a9af322 100644 --- a/.agents/rules/content-i18n.md +++ b/.agents/rules/content-i18n.md @@ -55,5 +55,5 @@ 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. +committed. Keep that generator working, or replace it and update every reference +to it. diff --git a/.agents/scripts/snapshot-route.mjs b/.agents/scripts/snapshot-route.mjs index 5ff5a5f..8a1ffb7 100755 --- a/.agents/scripts/snapshot-route.mjs +++ b/.agents/scripts/snapshot-route.mjs @@ -27,8 +27,12 @@ const text = html .replace(//gi, '') .replace(//g, '') .replace(/<[^>]+>/g, '\n') - .replace(/&/g, '&').replace(/</g, '<').replace(/>/g, '>') - .replace(/"/g, '"').replace(/�?39;/g, "'").replace(/ /g, ' ') + .replace(/&/g, '&') + .replace(/</g, '<') + .replace(/>/g, '>') + .replace(/"/g, '"') + .replace(/�?39;/g, "'") + .replace(/ /g, ' ') .split('\n') .map((line) => line.trim()) .filter(Boolean) diff --git a/.agents/skills/content-migration/SKILL.md b/.agents/skills/content-migration/SKILL.md index c9b27a8..c3bb25d 100644 --- a/.agents/skills/content-migration/SKILL.md +++ b/.agents/skills/content-migration/SKILL.md @@ -1,6 +1,9 @@ --- 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. +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 @@ -9,8 +12,8 @@ description: Move bilingual copy out of app.js and catalog.js into typed Astro c - `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`, +- `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 diff --git a/.agents/skills/motion/SKILL.md b/.agents/skills/motion/SKILL.md index 8f4f380..93fe7b5 100644 --- a/.agents/skills/motion/SKILL.md +++ b/.agents/skills/motion/SKILL.md @@ -1,6 +1,9 @@ --- 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. +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 @@ -22,10 +25,14 @@ If there is no answer, ship it static. That is a legitimate, common outcome. ```css .panel { - transition: opacity 180ms cubic-bezier(.2,0,0,1), - transform 180ms cubic-bezier(.2,0,0,1); + 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); } -.panel[data-state='entering'] { opacity: 0; transform: translateY(6px); } ``` - **`transform` and `opacity` only.** Animating `width`/`height`/`top`/`left` @@ -39,14 +46,18 @@ If there is no answer, ship it static. That is a legitimate, common outcome. ```css @media (prefers-reduced-motion: reduce) { - * { animation-duration: .01ms !important; animation-iteration-count: 1 !important; - transition-duration: .01ms !important; scroll-behavior: auto !important; } + * { + 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. +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 diff --git a/.agents/skills/verify-contract/SKILL.md b/.agents/skills/verify-contract/SKILL.md index 656d912..6fbc9f5 100644 --- a/.agents/skills/verify-contract/SKILL.md +++ b/.agents/skills/verify-contract/SKILL.md @@ -1,6 +1,9 @@ --- 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. +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 @@ -29,13 +32,13 @@ 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 | +| 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. +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. @@ -54,9 +57,9 @@ Commit the snapshots. They are the migration's regression net. ## Extend audit-ui.mjs -It rejects external ` diff --git a/.agents/templates/components/static-block.astro b/.agents/templates/components/static-block.astro index c5845da..31f4dd8 100644 --- a/.agents/templates/components/static-block.astro +++ b/.agents/templates/components/static-block.astro @@ -40,7 +40,7 @@ const { eyebrow, title, body, href } = Astro.props; .eyebrow { color: var(--accent); font: var(--font-eyebrow); - letter-spacing: .1em; + letter-spacing: 0.1em; text-transform: uppercase; } @@ -48,7 +48,7 @@ const { eyebrow, title, body, href } = Astro.props; margin: 0; font-size: var(--step-5); line-height: 1.05; - letter-spacing: -.06em; /* tight display tracking is a signature of this design */ + letter-spacing: -0.06em; /* tight display tracking is a signature of this design */ } p { @@ -69,6 +69,8 @@ const { eyebrow, title, body, href } = Astro.props; } @media (max-width: 800px) { - .block { padding: 18px; } + .block { + padding: 18px; + } } diff --git a/.agents/templates/config/.stylelintrc.json b/.agents/templates/config/.stylelintrc.json index e48c43d..f0aabce 100644 --- a/.agents/templates/config/.stylelintrc.json +++ b/.agents/templates/config/.stylelintrc.json @@ -1,10 +1,6 @@ { "extends": ["stylelint-config-standard"], - "ignoreFiles": [ - "dist/**", - "public/hands-on/**", - "submitted-skills/**" - ], + "ignoreFiles": ["dist/**", "public/hands-on/**", "submitted-skills/**"], "rules": { "custom-property-pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*$", "declaration-property-value-disallowed-list": { diff --git a/.agents/templates/config/eslint.config.js b/.agents/templates/config/eslint.config.js index 3b3240b..ade73d6 100644 --- a/.agents/templates/config/eslint.config.js +++ b/.agents/templates/config/eslint.config.js @@ -8,11 +8,11 @@ export default [ { 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 + '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 ], }, { diff --git a/.agents/templates/config/gitea-ci.yaml b/.agents/templates/config/gitea-ci.yaml index c3c1952..214a63f 100644 --- a/.agents/templates/config/gitea-ci.yaml +++ b/.agents/templates/config/gitea-ci.yaml @@ -15,7 +15,7 @@ jobs: steps: - uses: actions/checkout@v4 with: - fetch-depth: 0 # gate.sh compares assertion counts against origin/main + fetch-depth: 0 # gate.sh compares assertion counts against origin/main - uses: actions/setup-node@v4 with: diff --git a/.agents/templates/pages/chapter.astro b/.agents/templates/pages/chapter.astro index 8decd0d..fddfdb2 100644 --- a/.agents/templates/pages/chapter.astro +++ b/.agents/templates/pages/chapter.astro @@ -28,25 +28,30 @@ const lang = 'en'; // TODO: wire to the language toggle decision (task 03) - {chapter.data.sections.map((section) => ( - - ))} + { + chapter.data.sections.map((section) => ( + + )) + } diff --git a/.agents/templates/pages/interactive.astro b/.agents/templates/pages/interactive.astro index 31ad48b..40c99d5 100644 --- a/.agents/templates/pages/interactive.astro +++ b/.agents/templates/pages/interactive.astro @@ -39,7 +39,18 @@ const items = entries.map((entry) => ({ diff --git a/GATES.md b/GATES.md index 7b2521e..0487e81 100644 --- a/GATES.md +++ b/GATES.md @@ -1,23 +1,37 @@ # Gates: review desk privacy and improved-draft audit -OWNS: 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 -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. diff --git a/agents/index.html b/agents/index.html index ce8da42..3b781e1 100644 --- a/agents/index.html +++ b/agents/index.html @@ -1 +1,88 @@ -AI For Dummies — Agents and trees
← ROUTE MAP02 / AGENTS & TREESfield 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
BriefGoal, owned files, dependencies, non-goals, acceptance.
02
IsolationOne branch and worktree per independent change.
03
EvidenceCommands, result, changed files, screenshots, gaps.
+ + + + + + AI For Dummies — Agents and trees + + + +
+
+ ← ROUTE MAP02 / AGENTS & TREESfield 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 +
+ BriefGoal, owned files, dependencies, non-goals, acceptance. +
+
+
+ 02 +
+ IsolationOne branch and worktree per independent change. +
+
+
+ 03 +
+ EvidenceCommands, result, changed files, screenshots, gaps. +
+
+
+
+ +
+ + diff --git a/docs/references/README.md b/docs/references/README.md index 776007d..c1d5a76 100644 --- a/docs/references/README.md +++ b/docs/references/README.md @@ -7,38 +7,47 @@ 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. diff --git a/docs/references/additional-reading.md b/docs/references/additional-reading.md index 1baaba1..07d91c1 100644 --- a/docs/references/additional-reading.md +++ b/docs/references/additional-reading.md @@ -1,6 +1,8 @@ # 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 @@ -8,25 +10,38 @@ Verified on 2026-09-02. Start with the official references for behavior and cons - **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 @@ -34,31 +49,48 @@ Verified on 2026-09-02. Start with the official references for behavior and cons - **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 @@ -66,19 +98,30 @@ Verified on 2026-09-02. Start with the official references for behavior and cons - **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 diff --git a/docs/references/model-routing.md b/docs/references/model-routing.md index eb4be8a..52a1316 100644 --- a/docs/references/model-routing.md +++ b/docs/references/model-routing.md @@ -1,25 +1,42 @@ # 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: @@ -37,7 +54,12 @@ 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: @@ -53,27 +75,45 @@ 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, @@ -86,11 +126,13 @@ 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 | +| 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. diff --git a/docs/references/skill-sources.md b/docs/references/skill-sources.md index 2a41265..0b01aed 100644 --- a/docs/references/skill-sources.md +++ b/docs/references/skill-sources.md @@ -1,17 +1,20 @@ # 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`. | -| `research` | [`SKILL.md` at `6654f6b`](https://github.com/mattpocock/skills/blob/6654f6b60cd9d5be8b54c6fafe44346dabeb3b76/skills/engineering/research/SKILL.md) | [`mattpocock/skills`](https://github.com/mattpocock/skills), path `skills/engineering/research/` | **High — exact byte match.** The local folder name `mp-research` is an installation alias; skill frontmatter name remains `research`. | -| `diagnosing-bugs` | [`SKILL.md` at `6654f6b`](https://github.com/mattpocock/skills/blob/6654f6b60cd9d5be8b54c6fafe44346dabeb3b76/skills/engineering/diagnosing-bugs/SKILL.md) | [`mattpocock/skills`](https://github.com/mattpocock/skills), path `skills/engineering/diagnosing-bugs/` | **High — exact byte match.** The local folder is aliased as `mp-diagnosing-bugs`. | -| `code-review` | [`SKILL.md` at `6654f6b`](https://github.com/mattpocock/skills/blob/6654f6b60cd9d5be8b54c6fafe44346dabeb3b76/skills/engineering/code-review/SKILL.md) | [`mattpocock/skills`](https://github.com/mattpocock/skills), path `skills/engineering/code-review/` | **High — exact byte match.** The local folder is aliased as `mp-code-review`. Copy the directory so any future supporting files remain available. | -| `token-saver` | [`SKILL.md` at `8f21188`](https://github.com/aetox-skills/token-saver/blob/8f21188bb043fad411f47e2e57f0365a83c13da7/SKILL.md) | [`aetox-skills/token-saver`](https://github.com/aetox-skills/token-saver), repository root | **High — exact byte match.** The skill expects the separate [`rtk-ai/rtk`](https://github.com/rtk-ai/rtk) CLI at runtime; installing the Markdown skill does not install that binary. | -| `webapp-testing` | [`SKILL.md` at `5304866`](https://github.com/anthropics/skills/blob/53048666b05b4799081517d00e09e0a2dd688678/skills/webapp-testing/SKILL.md) | [`anthropics/skills`](https://github.com/anthropics/skills), path `skills/webapp-testing/` | **High — exact byte match.** Copy the full directory because the skill calls `scripts/with_server.py` and carries its own license file. | +| 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`. | +| `research` | [`SKILL.md` at `6654f6b`](https://github.com/mattpocock/skills/blob/6654f6b60cd9d5be8b54c6fafe44346dabeb3b76/skills/engineering/research/SKILL.md) | [`mattpocock/skills`](https://github.com/mattpocock/skills), path `skills/engineering/research/` | **High — exact byte match.** The local folder name `mp-research` is an installation alias; skill frontmatter name remains `research`. | +| `diagnosing-bugs` | [`SKILL.md` at `6654f6b`](https://github.com/mattpocock/skills/blob/6654f6b60cd9d5be8b54c6fafe44346dabeb3b76/skills/engineering/diagnosing-bugs/SKILL.md) | [`mattpocock/skills`](https://github.com/mattpocock/skills), path `skills/engineering/diagnosing-bugs/` | **High — exact byte match.** The local folder is aliased as `mp-diagnosing-bugs`. | +| `code-review` | [`SKILL.md` at `6654f6b`](https://github.com/mattpocock/skills/blob/6654f6b60cd9d5be8b54c6fafe44346dabeb3b76/skills/engineering/code-review/SKILL.md) | [`mattpocock/skills`](https://github.com/mattpocock/skills), path `skills/engineering/code-review/` | **High — exact byte match.** The local folder is aliased as `mp-code-review`. Copy the directory so any future supporting files remain available. | +| `token-saver` | [`SKILL.md` at `8f21188`](https://github.com/aetox-skills/token-saver/blob/8f21188bb043fad411f47e2e57f0365a83c13da7/SKILL.md) | [`aetox-skills/token-saver`](https://github.com/aetox-skills/token-saver), repository root | **High — exact byte match.** The skill expects the separate [`rtk-ai/rtk`](https://github.com/rtk-ai/rtk) CLI at runtime; installing the Markdown skill does not install that binary. | +| `webapp-testing` | [`SKILL.md` at `5304866`](https://github.com/anthropics/skills/blob/53048666b05b4799081517d00e09e0a2dd688678/skills/webapp-testing/SKILL.md) | [`anthropics/skills`](https://github.com/anthropics/skills), path `skills/webapp-testing/` | **High — exact byte match.** Copy the full directory because the skill calls `scripts/with_server.py` and carries its own license file. | ## Safe copy-paste prompt @@ -38,4 +41,8 @@ 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. diff --git a/index.html b/index.html index 42934ea..ff0cf1f 100644 --- a/index.html +++ b/index.html @@ -1,27 +1,79 @@ - - - - - AI For Dummies — Start here - - - - -
-
AI FOR DUMMIES00 / START HEREreview 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 →
-
- - - - -
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 THREADFrame 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.
-
- + + + + + AI For Dummies — Start here + + + + +
+
+ AI FOR DUMMIES00 / START HEREreview 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 → +
+ +
+ 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 THREADFrame 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. +
+
+ diff --git a/models/index.html b/models/index.html index e6ba8fc..d92d41c 100644 --- a/models/index.html +++ b/models/index.html @@ -1 +1,87 @@ -AI For Dummies — Models
← ROUTE MAP01 / MODELSfield 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 RULEstrong 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
PlanStrong model: scope, risks, acceptance, and worktree split.
02
BuildFocused worker: smallest context and lightest model that can pass.
03
ReviewIndependent pass when missed issues cost more than the call.
+ + + + + + AI For Dummies — Models + + + +
+
+ ← ROUTE MAP01 / MODELSfield 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 RULEstrong 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 +
+ PlanStrong model: scope, risks, acceptance, and worktree split. +
+
+
+ 02 +
+ BuildFocused worker: smallest context and lightest model that can pass. +
+
+
+ 03 +
+ ReviewIndependent pass when missed issues cost more than the call. +
+
+
+
+ +
+ + diff --git a/plans/astro-refactor/task-05-content-guide.md b/plans/astro-refactor/task-05-content-guide.md index 00c35dc..188b2b8 100644 --- a/plans/astro-refactor/task-05-content-guide.md +++ b/plans/astro-refactor/task-05-content-guide.md @@ -1,12 +1,13 @@ # Task 05 — Guide content out of app.js -**Agent**: `content-i18n-migrator` · **Model**: MiniMax-M3 -**Depends on**: 04 · **Parallel with**: 06 · **Blocks**: 15 -**Worktree**: `.agents/scripts/worktree.sh start 05 content-guide` +**Agent**: `content-i18n-migrator` · **Model**: MiniMax-M3 **Depends on**: 04 · +**Parallel with**: 06 · **Blocks**: 15 **Worktree**: +`.agents/scripts/worktree.sh start 05 content-guide` ## Goal -Every `{ en, pt }` string in `app.js` lives in `src/content/guide/`, byte-identical. +Every `{ en, pt }` string in `app.js` lives in `src/content/guide/`, +byte-identical. ## Scope @@ -15,13 +16,13 @@ removes it once the page consumes the collection. ## Steps -1. `node .agents/scripts/extract-strings.mjs app.js > /tmp/before.json` - (~50 pairs across `phases`, `handsOnPrompts`, `modelGuide`, `skillSources`, +1. `node .agents/scripts/extract-strings.mjs app.js > /tmp/before.json` (~50 + pairs across `phases`, `handsOnPrompts`, `modelGuide`, `skillSources`, `skillInstallPrompts`). 2. Move them into the collection. **Copy mechanically — never retype.** These - are hand-written translations with deliberate tone (`'Transforme ambiguidade - em trabalho'`); retyping introduces drift nobody catches until a Portuguese - speaker reads it. + are hand-written translations with deliberate tone + (`'Transforme ambiguidade em trabalho'`); retyping introduces drift nobody + catches until a Portuguese speaker reads it. 3. `node .agents/scripts/extract-strings.mjs src/content/guide/ > /tmp/after.json` 4. `diff /tmp/before.json /tmp/after.json` → **must be empty**. diff --git a/plans/astro-refactor/task-06-content-review.md b/plans/astro-refactor/task-06-content-review.md index a9796fe..98eee28 100644 --- a/plans/astro-refactor/task-06-content-review.md +++ b/plans/astro-refactor/task-06-content-review.md @@ -1,8 +1,8 @@ # Task 06 — Review-desk content out of catalog.js -**Agent**: `content-i18n-migrator` · **Model**: MiniMax-M3 -**Depends on**: 04 · **Parallel with**: 05 · **Blocks**: 16 -**Worktree**: `.agents/scripts/worktree.sh start 06 content-review` +**Agent**: `content-i18n-migrator` · **Model**: MiniMax-M3 **Depends on**: 04 · +**Parallel with**: 05 · **Blocks**: 16 **Worktree**: +`.agents/scripts/worktree.sh start 06 content-review` ## Goal @@ -32,12 +32,14 @@ real `.md` files. node scripts/build-skill-review.mjs && git diff --exit-code skill-reviews/ ``` 2. **The diff view needs raw source.** The review desk compares original and - improved as *text*. If `improved` only exists as rendered HTML, the change + improved as _text_. If `improved` only exists as rendered HTML, the change lens breaks. Keep the raw string reachable. ## Done when -- [ ] 24 entries in the collection; `verify.mjs`'s `id:'` count assertion still passes +- [ ] 24 entries in the collection; `verify.mjs`'s `id:'` count assertion still + passes - [ ] `git diff --exit-code skill-reviews/` clean after regenerating - [ ] `astro check` passes -- [ ] Every reference to the generator still accurate (`package.json`, `README.md`, `docs/operations-guide.md`, the review desk footer) +- [ ] Every reference to the generator still accurate (`package.json`, + `README.md`, `docs/operations-guide.md`, the review desk footer) diff --git a/plans/astro-refactor/task-17-hands-on.md b/plans/astro-refactor/task-17-hands-on.md index ffd1e70..15469ee 100644 --- a/plans/astro-refactor/task-17-hands-on.md +++ b/plans/astro-refactor/task-17-hands-on.md @@ -1,8 +1,8 @@ # Task 17 — hands-on passthrough -**Agent**: `astro-architect` · **Model**: MiniMax-M3 -**Depends on**: 01 · **Parallel with**: 12, 13, 14 -**Worktree**: `.agents/scripts/worktree.sh start 17 hands-on` +**Agent**: `astro-architect` · **Model**: MiniMax-M3 **Depends on**: 01 · +**Parallel with**: 12, 13, 14 **Worktree**: +`.agents/scripts/worktree.sh start 17 hands-on` ## Goal diff --git a/scripts/verify.mjs b/scripts/verify.mjs index 84d9165..faee2ae 100644 --- a/scripts/verify.mjs +++ b/scripts/verify.mjs @@ -24,68 +24,374 @@ const skillsHtml = read('skills/index.html'); const reviewCatalog = read('skills-review/catalog.js'); const reviewVoteJs = read('skills-review/vote.js'); const voteService = read('vote-service/main.go'); -for (const url of ['https://code.claude.com/docs/en/sub-agents','https://code.claude.com/docs/en/skills','https://code.claude.com/docs/en/worktrees','https://git-scm.com/docs/git-worktree.html','https://developers.openai.com/codex/skills']) if (!refs.includes(url)) throw new Error(`missing reference ${url}`); +for (const url of [ + 'https://code.claude.com/docs/en/sub-agents', + 'https://code.claude.com/docs/en/skills', + 'https://code.claude.com/docs/en/worktrees', + 'https://git-scm.com/docs/git-worktree.html', + 'https://developers.openai.com/codex/skills', +]) + if (!refs.includes(url)) throw new Error(`missing reference ${url}`); console.log('content verification passed'); -for (const token of ['data-phase="plan"','data-phase="build"','data-phase="review"','data-tree="main"','data-tree="ui"','data-worker="ui"','data-route="plan"','data-model-provider="openai"','data-model-provider="claude"','data-model-provider="gemini"','data-effort="low"','data-effort="medium"','data-effort="high"','data-skill-file="skill"','data-skill-step="observe"','data-skill-step="validate"','data-common-skill="ponytail"','data-common-skill="caveman"','data-common-skill="unlazy"','id="hands-on"','data-copy-target="prompt-install-skills"','data-copy-target="prompt-basic"','data-copy-target="prompt-skills"','hands-on/starter/','additional-reading.md','role="tablist"',']+(src|href)="https?:[^"]+"/i)) throw new Error('external runtime dependency found'); +if (html.match(/<(script|link)[^>]+(src|href)="https?:[^"]+"/i)) + throw new Error('external runtime dependency found'); console.log('standalone verification passed'); -for (const token of ['id="pipeline"','id="skills"','id="examples"','data-stage="context"','data-stage="cli"','data-stage="commit"','data-stage="review"','gate-discipline','parallel-agents','repo-db','tech-debt','skill-writer','scripts/check-ui-contract.mjs','.husky/pre-commit','.pr-review.json','.agents/skills','netcracker/interview']) if (!rulesHtml.includes(token)) throw new Error(`missing rules content ${token}`); +for (const token of [ + 'id="pipeline"', + 'id="skills"', + 'id="examples"', + 'data-stage="context"', + 'data-stage="cli"', + 'data-stage="commit"', + 'data-stage="review"', + 'gate-discipline', + 'parallel-agents', + 'repo-db', + 'tech-debt', + 'skill-writer', + 'scripts/check-ui-contract.mjs', + '.husky/pre-commit', + '.pr-review.json', + '.agents/skills', + 'netcracker/interview', +]) + if (!rulesHtml.includes(token)) throw new Error(`missing rules content ${token}`); console.log('rules content verification passed'); -for (const token of ['const languageCopy','const stages','const skills','const prompts','renderStage','renderSkill','renderLanguage','copyPrompt','addEventListener']) if (!rulesJs.includes(token)) throw new Error(`missing rules interaction ${token}`); -for (const token of ['data-lang="en"','data-lang="pt"','data-copy-prompt','aria-live="polite"','role="tablist"']) if (!rulesHtml.includes(token)) throw new Error(`missing rules control ${token}`); +for (const token of [ + 'const languageCopy', + 'const stages', + 'const skills', + 'const prompts', + 'renderStage', + 'renderSkill', + 'renderLanguage', + 'copyPrompt', + 'addEventListener', +]) + if (!rulesJs.includes(token)) throw new Error(`missing rules interaction ${token}`); +for (const token of [ + 'data-lang="en"', + 'data-lang="pt"', + 'data-copy-prompt', + 'aria-live="polite"', + 'role="tablist"', +]) + if (!rulesHtml.includes(token)) throw new Error(`missing rules control ${token}`); console.log('rules interaction verification passed'); -if (!html.includes('href="../rules/"')) throw new Error('main presentation does not link to rules page'); -if (!html.includes('href="../skills-review/"')) throw new Error('main presentation does not link to skills review page'); -for (const token of ['../summary/','../models/','../agents/','../skills/','chapter-route']) if (!html.includes(token)) throw new Error(`main presentation missing chapter route ${token}`); -if (rulesHtml.includes('script src="http') || rulesHtml.includes('rel="stylesheet" href="http')) throw new Error('rules page has an external runtime dependency'); -for (const token of ['@media(min-width:2200px)','@media(max-width:900px)','@media(max-width:600px)','prefers-reduced-motion']) if (!rulesCss.includes(token)) throw new Error(`missing rules responsive contract ${token}`); +if (!html.includes('href="../rules/"')) + throw new Error('main presentation does not link to rules page'); +if (!html.includes('href="../skills-review/"')) + throw new Error('main presentation does not link to skills review page'); +for (const token of ['../summary/', '../models/', '../agents/', '../skills/', 'chapter-route']) + if (!html.includes(token)) throw new Error(`main presentation missing chapter route ${token}`); +if (rulesHtml.includes('script src="http') || rulesHtml.includes('rel="stylesheet" href="http')) + throw new Error('rules page has an external runtime dependency'); +for (const token of [ + '@media(min-width:2200px)', + '@media(max-width:900px)', + '@media(max-width:600px)', + 'prefers-reduced-motion', +]) + if (!rulesCss.includes(token)) throw new Error(`missing rules responsive contract ${token}`); console.log('rules standalone verification passed'); -for (const token of ['id="catalog"','id="skill-filter"','id="skill-list"','id="detail"','Preview Markdown','styles.css?v=20260904-vote-widget','change-lens.css?v=20260904-vote-widget','app.js?v=20260904-vote-widget','?author=Name&skill=skill-id&view=improved','SKILLS_REVIEW_VOTE_API']) if (!reviewHtml.includes(token)) throw new Error(`missing review page content ${token}`); -for (const token of ["from './catalog.js'", "from './files.js'",'function renderList','function renderDetail','selectSkill','packageSummary','markdownHeadings','markdownToc','document.addEventListener(\'keydown\'','loadSelectedFile','schedulePackageSearch','fetchSource','packageSearchText','diffMarkup','diffRows','data-diff','searchParams.set(\'compare\'','markdownMarkup','data-render','preview-markdown','Preview Markdown','View source','FILE PREVIEW','searchParams.set(\'render\'','AUTHOR ·','SKILL ·','function selectFromUrl','function syncUrl','URLSearchParams','navigator.clipboard','document.execCommand','download','data-file','searchParams.set(\'file\'']) if (!reviewJs.includes(token)) throw new Error(`missing review interaction ${token}`); -for (const token of ['ndo-repro','gfiber-logging','confluence-page','diagram-plantuml','page-reviewer','unslop','spanish-naturalizer','draft-mr','semantic-diff-review','reference.md','files =']) if (!`${reviewFiles}\n${read('skills-review/submitted-files.js')}`.includes(token)) throw new Error(`missing review file manifest ${token}`); -if ((reviewCatalog.match(/id:'/g) || []).length + (read('skills-review/submitted-catalog.js').match(/id:'/g) || []).length !== 24) throw new Error('review catalog does not cover all submissions'); -if (!reviewCatalog.includes('hardcoded password') || !reviewCatalog.includes('safety-redacted') || !reviewJs.includes('[REDACTED]') || !reviewJs.includes('[REDACTED LOCAL USER]') || !reviewJs.includes('[REDACTED USER]')) throw new Error('review catalog does not record secret safety handling'); +for (const token of [ + 'id="catalog"', + 'id="skill-filter"', + 'id="skill-list"', + 'id="detail"', + 'Preview Markdown', + 'styles.css?v=20260904-vote-widget', + 'change-lens.css?v=20260904-vote-widget', + 'app.js?v=20260904-vote-widget', + '?author=Name&skill=skill-id&view=improved', + 'SKILLS_REVIEW_VOTE_API', +]) + if (!reviewHtml.includes(token)) throw new Error(`missing review page content ${token}`); +for (const token of [ + "from './catalog.js'", + "from './files.js'", + 'function renderList', + 'function renderDetail', + 'selectSkill', + 'packageSummary', + 'markdownHeadings', + 'markdownToc', + "document.addEventListener('keydown'", + 'loadSelectedFile', + 'schedulePackageSearch', + 'fetchSource', + 'packageSearchText', + 'diffMarkup', + 'diffRows', + 'data-diff', + "searchParams.set('compare'", + 'markdownMarkup', + 'data-render', + 'preview-markdown', + 'Preview Markdown', + 'View source', + 'FILE PREVIEW', + "searchParams.set('render'", + 'AUTHOR ·', + 'SKILL ·', + 'function selectFromUrl', + 'function syncUrl', + 'URLSearchParams', + 'navigator.clipboard', + 'document.execCommand', + 'download', + 'data-file', + "searchParams.set('file'", +]) + if (!reviewJs.includes(token)) throw new Error(`missing review interaction ${token}`); +for (const token of [ + 'ndo-repro', + 'gfiber-logging', + 'confluence-page', + 'diagram-plantuml', + 'page-reviewer', + 'unslop', + 'spanish-naturalizer', + 'draft-mr', + 'semantic-diff-review', + 'reference.md', + 'files =', +]) + if (!`${reviewFiles}\n${read('skills-review/submitted-files.js')}`.includes(token)) + throw new Error(`missing review file manifest ${token}`); +if ( + (reviewCatalog.match(/id:'/g) || []).length + + (read('skills-review/submitted-catalog.js').match(/id:'/g) || []).length !== + 24 +) + throw new Error('review catalog does not cover all submissions'); +if ( + !reviewCatalog.includes('hardcoded password') || + !reviewCatalog.includes('safety-redacted') || + !reviewJs.includes('[REDACTED]') || + !reviewJs.includes('[REDACTED LOCAL USER]') || + !reviewJs.includes('[REDACTED USER]') +) + throw new Error('review catalog does not record secret safety handling'); console.log('skills review verification passed'); -for (const page of [summaryHtml, modelsHtml, agentsHtml, skillsHtml]) if (!page.includes('../chapters.css') || !page.includes('ROUTE MAP')) throw new Error('chapter page missing shared navigation'); -for (const token of ['--ink','@media(max-width:800px)','@media(max-width:520px)']) if (!chaptersCss.includes(token)) throw new Error(`missing chapter responsive contract ${token}`); +for (const page of [summaryHtml, modelsHtml, agentsHtml, skillsHtml]) + if (!page.includes('../chapters.css') || !page.includes('ROUTE MAP')) + throw new Error('chapter page missing shared navigation'); +for (const token of ['--ink', '@media(max-width:800px)', '@media(max-width:520px)']) + if (!chaptersCss.includes(token)) throw new Error(`missing chapter responsive contract ${token}`); console.log('chapter route verification passed'); -for (const token of ['The short route','full-guide/','models/','agents/','skills/','rules/','hands-on/starter/','skills-review/']) if (!landingHtml.includes(token)) throw new Error(`landing page missing ${token}`); -if (landingHtml.includes('app.js')) throw new Error('landing page should remain a fast, static route map'); +for (const token of [ + 'The short route', + 'full-guide/', + 'models/', + 'agents/', + 'skills/', + 'rules/', + 'hands-on/starter/', + 'skills-review/', +]) + if (!landingHtml.includes(token)) throw new Error(`landing page missing ${token}`); +if (landingHtml.includes('app.js')) + throw new Error('landing page should remain a fast, static route map'); console.log('landing route verification passed'); -for (const token of ['data-package-file="skill"','data-package-file="references"','data-package-file="scripts"','data-package-file="assets"','id="package-preview"','script src="app.js"']) if (!skillsHtml.includes(token)) throw new Error(`skills anatomy missing ${token}`); +for (const token of [ + 'data-package-file="skill"', + 'data-package-file="references"', + 'data-package-file="scripts"', + 'data-package-file="assets"', + 'id="package-preview"', + 'script src="app.js"', +]) + if (!skillsHtml.includes(token)) throw new Error(`skills anatomy missing ${token}`); const skillsApp = read('skills/app.js'); const skillsCss = read('skills/styles.css'); -for (const token of ['const packageFiles','function renderPackage','addEventListener','renderPackage(\'skill\')']) if (!skillsApp.includes(token)) throw new Error(`skills anatomy interaction missing ${token}`); -for (const token of ['grid-template-columns:minmax(190px','overflow-wrap:anywhere','@media(max-width:800px)','prefers-reduced-motion']) if (!skillsCss.includes(token)) throw new Error(`skills anatomy responsive contract missing ${token}`); +for (const token of [ + 'const packageFiles', + 'function renderPackage', + 'addEventListener', + "renderPackage('skill')", +]) + if (!skillsApp.includes(token)) throw new Error(`skills anatomy interaction missing ${token}`); +for (const token of [ + 'grid-template-columns:minmax(190px', + 'overflow-wrap:anywhere', + '@media(max-width:800px)', + 'prefers-reduced-motion', +]) + if (!skillsCss.includes(token)) + throw new Error(`skills anatomy responsive contract missing ${token}`); console.log('skills anatomy verification passed'); console.log('presentation verification passed'); -const legacyName = String.fromCharCode(80,101,100,114,111,32,65,114,97,110,104,97); +const legacyName = String.fromCharCode(80, 101, 100, 114, 111, 32, 65, 114, 97, 110, 104, 97); const legacyHandle = legacyName.toLowerCase().replace(' ', '.'); -for (const path of ['submitted-skills/Anonymous Operational Submission/skills/ndo-repro/SKILL.md','submitted-skills/Anonymous Operational Submission/skills/ndo-repro/envs.tsv','submitted-skills/Anonymous Operational Submission/skills/ndo-repro/lib/env.sh','submitted-skills/Anonymous Operational Submission/skills/ndo-repro/ndo-api.sh','submitted-skills/Anonymous Operational Submission/skills/ndo-repro/ndo-ship.sh','submitted-skills/Anonymous Operational Submission/skills/ndo-repro/reference/bom-Dockerfile_local.example','submitted-skills/Anonymous Operational Submission/skills/ndo-repro/reference/dockerfile-local.md','skill-reviews/improved/ndo-repro/SKILL.md']) { +for (const path of [ + 'submitted-skills/Anonymous Operational Submission/skills/ndo-repro/SKILL.md', + 'submitted-skills/Anonymous Operational Submission/skills/ndo-repro/envs.tsv', + 'submitted-skills/Anonymous Operational Submission/skills/ndo-repro/lib/env.sh', + 'submitted-skills/Anonymous Operational Submission/skills/ndo-repro/ndo-api.sh', + 'submitted-skills/Anonymous Operational Submission/skills/ndo-repro/ndo-ship.sh', + 'submitted-skills/Anonymous Operational Submission/skills/ndo-repro/reference/bom-Dockerfile_local.example', + 'submitted-skills/Anonymous Operational Submission/skills/ndo-repro/reference/dockerfile-local.md', + 'skill-reviews/improved/ndo-repro/SKILL.md', +]) { const source = read(path); - if (new RegExp(`${legacyName}|${legacyHandle}|https?:\\/\\/|git\\.netcracker\\.com|artifactorycn|managed\\.netcracker\\.cloud`, 'i').test(source)) throw new Error(`operational submission privacy leak in ${path}`); + if ( + new RegExp( + `${legacyName}|${legacyHandle}|https?:\\/\\/|git\\.netcracker\\.com|artifactorycn|managed\\.netcracker\\.cloud`, + 'i', + ).test(source) + ) + throw new Error(`operational submission privacy leak in ${path}`); } -for (const source of [reviewCatalog, reviewFiles, reviewJs]) if (source.includes(legacyName) || source.includes(legacyName.replace(' ', '%20'))) throw new Error('operational submission identity remains in review desk source'); -if (!reviewFiles.includes('Anonymous%20Operational%20Submission') || !reviewJs.includes("entry.id === 'ndo-repro'")) throw new Error('operational submission redaction contract missing'); +for (const source of [reviewCatalog, reviewFiles, reviewJs]) + if (source.includes(legacyName) || source.includes(legacyName.replace(' ', '%20'))) + throw new Error('operational submission identity remains in review desk source'); +if ( + !reviewFiles.includes('Anonymous%20Operational%20Submission') || + !reviewJs.includes("entry.id === 'ndo-repro'") +) + throw new Error('operational submission redaction contract missing'); console.log('review privacy verification passed'); -for (const token of ['currentContent','unchangedDraft','state.preview = button.dataset.preview','state.file = available.find','loadSelectedFile']) if (!reviewJs.includes(token)) throw new Error(`review file-mode contract missing ${token}`); -if (reviewJs.includes("state.preview = 'original'; syncUrl(); renderDetail(); loadSelectedFile();")) throw new Error('file selection still resets improved mode'); +for (const token of [ + 'currentContent', + 'unchangedDraft', + 'state.preview = button.dataset.preview', + 'state.file = available.find', + 'loadSelectedFile', +]) + if (!reviewJs.includes(token)) throw new Error(`review file-mode contract missing ${token}`); +if (reviewJs.includes("state.preview = 'original'; syncUrl(); renderDetail(); loadSelectedFile();")) + throw new Error('file selection still resets improved mode'); console.log('review file-mode verification passed'); -for (const token of ['const changeRows','function lensMarkup','data-lens','CHANGE LENS','What changed — and why.']) if (!reviewJs.includes(token)) throw new Error(`review change-lens contract missing ${token}`); -for (const token of ['.change-lens','.change-rows','.skill-diff','.diff-lines','@media(max-width:620px)','prefers-reduced-motion']) if (!reviewLensCss.includes(token)) throw new Error(`review change-lens CSS missing ${token}`); +for (const token of [ + 'const changeRows', + 'function lensMarkup', + 'data-lens', + 'CHANGE LENS', + 'What changed — and why.', +]) + if (!reviewJs.includes(token)) throw new Error(`review change-lens contract missing ${token}`); +for (const token of [ + '.change-lens', + '.change-rows', + '.skill-diff', + '.diff-lines', + '@media(max-width:620px)', + 'prefers-reduced-motion', +]) + if (!reviewLensCss.includes(token)) throw new Error(`review change-lens CSS missing ${token}`); console.log('review change-lens verification passed'); -for (const token of ['.markdown-preview','max-height:540px','.markdown-table-wrap','.markdown-frontmatter','.markdown-toc','.preview-title','.preview-markdown','grid-template-columns:minmax(0,1fr)','height:120px','-webkit-line-clamp:2']) if (!read('skills-review/styles.css').includes(token)) throw new Error(`review markdown preview contract missing ${token}`); +for (const token of [ + '.markdown-preview', + 'max-height:540px', + '.markdown-table-wrap', + '.markdown-frontmatter', + '.markdown-toc', + '.preview-title', + '.preview-markdown', + 'grid-template-columns:minmax(0,1fr)', + 'height:120px', + '-webkit-line-clamp:2', +]) + if (!read('skills-review/styles.css').includes(token)) + throw new Error(`review markdown preview contract missing ${token}`); console.log('review markdown preview verification passed'); -for (const token of ["from './vote.js'","renderVoteWidget($('#vote-widget'"]) if (!reviewJs.includes(token)) throw new Error(`review vote widget wiring missing ${token}`); -for (const token of ['id="vote-widget"','function renderVoteWidget','X-Voter-Id','/api/votes','Voting is offline']) if (!reviewVoteJs.includes(token) && !reviewJs.includes(token)) throw new Error(`review vote widget contract missing ${token}`); -for (const token of ['.vote-widget','.vote-buttons','[aria-pressed="true"]']) if (!read('skills-review/styles.css').includes(token)) throw new Error(`review vote widget CSS missing ${token}`); -if (!voteService.includes('X-Forwarded-For') || !voteService.includes('one active vote per skill') && !voteService.includes('at most one active vote')) throw new Error('vote-service missing IP-based one-vote-per-source contract'); +for (const token of ["from './vote.js'", "renderVoteWidget($('#vote-widget'"]) + if (!reviewJs.includes(token)) throw new Error(`review vote widget wiring missing ${token}`); +for (const token of [ + 'id="vote-widget"', + 'function renderVoteWidget', + 'X-Voter-Id', + '/api/votes', + 'Voting is offline', +]) + if (!reviewVoteJs.includes(token) && !reviewJs.includes(token)) + throw new Error(`review vote widget contract missing ${token}`); +for (const token of ['.vote-widget', '.vote-buttons', '[aria-pressed="true"]']) + if (!read('skills-review/styles.css').includes(token)) + throw new Error(`review vote widget CSS missing ${token}`); +if ( + !voteService.includes('X-Forwarded-For') || + (!voteService.includes('one active vote per skill') && + !voteService.includes('at most one active vote')) +) + throw new Error('vote-service missing IP-based one-vote-per-source contract'); console.log('review vote widget verification passed'); diff --git a/src/components/blocks/RouteTable.astro b/src/components/blocks/RouteTable.astro index 6c9d244..958b165 100644 --- a/src/components/blocks/RouteTable.astro +++ b/src/components/blocks/RouteTable.astro @@ -21,16 +21,64 @@ interface Route { interface Props { routes: Route[]; initial?: string; + headWork?: string | Localized; + headProfile?: string | Localized; + headPromptShape?: string | Localized; } -const { routes, initial = routes[0]?.id ?? 'plan' } = Astro.props; +const { + routes, + initial = routes[0]?.id ?? 'plan', + headWork = 'Work', + headProfile = 'Profile', + headPromptShape = 'Prompt shape', +} = Astro.props; ---
- Work - Profile - Prompt shape + + { + typeof headWork === 'string' ? ( + headWork + ) : ( + <> + {headWork.en} + + + ) + } + + + { + typeof headProfile === 'string' ? ( + headProfile + ) : ( + <> + {headProfile.en} + + + ) + } + + + { + typeof headPromptShape === 'string' ? ( + headPromptShape + ) : ( + <> + {headPromptShape.en} + + + ) + } +
{ routes.map((route) => ( diff --git a/src/components/blocks/SkillPackage.astro b/src/components/blocks/SkillPackage.astro index 6557391..8ae3314 100644 --- a/src/components/blocks/SkillPackage.astro +++ b/src/components/blocks/SkillPackage.astro @@ -20,13 +20,27 @@ interface PackageFile { interface Props { files: PackageFile[]; initial?: string; + packageLabel?: string | Localized; } -const { files, initial = files[0]?.id ?? 'skill' } = Astro.props; +const { files, initial = files[0]?.id ?? 'skill', packageLabel = 'SKILL PACKAGE' } = Astro.props; ---
- SKILL PACKAGE + + { + typeof packageLabel === 'string' ? ( + packageLabel + ) : ( + <> + {packageLabel.en} + + + ) + } + { files.map((file) => ( + + { + typeof rootLabel === 'string' ? ( + rootLabel + ) : ( + <> + {rootLabel.en} + + + ) + } + + main + + { + typeof rootSmall === 'string' ? ( + rootSmall + ) : ( + <> + {rootSmall.en} + + + ) + } + + { branches.map((branch) => (
03bounded workers
in paralleliterations
with evidence + >

Read this as a route map, not a prompt recipe.{workers.ui.en[2]}

- The orchestrator preserves intent, writes small contracts, and gathers results that can be - verified. It does not need to type every line. + The orchestrator preserves intent, writes small contracts, and gathers results that can + be verified. It does not need to type every line.

@@ -403,15 +411,21 @@ const base = import.meta.env.BASE_URL;

The subagent loop + hidden>O ciclo de subagentes

Click a phase.
See the handoff.

- Delegation means moving one bounded task into a smaller context—not giving away - responsibility. + Delegation means moving one bounded task into a smaller context—not giving away + responsibility.

Git worktrees + hidden>Git worktrees

One branch
per hand. + hidden>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. + A worktree is another directory linked to the same repository. Each agent gets its own + checkout and index; history remains shared.

Select a node to inspect its checkout, owner, and next action. 4 checkouts -

+
{labels.owner.en}{trees.main.owner.en}
CHECKOUT{trees.main.path}

{trees.main.note.en}

{trees.main.command} @@ -539,7 +560,8 @@ const base = import.meta.env.BASE_URL;

Model routing + hidden>Roteamento de modelos

Do not pay for
reasoning where
you need rhythm.

Choose a job to see why the model profile changes. + >Escolha um trabalho para entender por que o perfil do modelo muda.

Two separate knobs + hidden>Dois controles separados

Choose the engine.
Then choose the gear. + >Escolha o motor.
Depois escolha a marcha.

@@ -625,7 +653,8 @@ const base = import.meta.env.BASE_URL; > + checks e mova um controle por vez.

@@ -703,11 +732,13 @@ const base = import.meta.env.BASE_URL;

Skills + >Skills

Write the right way
once. + hidden>Escreva do jeito certo
uma vez.

A skill is a reusable procedure. It can carry instructions, references, scripts, and @@ -717,9 +748,23 @@ const base = import.meta.env.BASE_URL; >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 + 02 / load detail on demand + 03 / return evidence +
+
+

+ The field kit +

+

+ Different jobs.
Different instincts. +

+
+

+ 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. +

{ @@ -802,9 +874,19 @@ const base = import.meta.env.BASE_URL; aria-selected={skill.id === 'ponytail'} > <> - {skill.kind.en} + + {skill.kind.en} + + {skill.title} - {skill.use.en} + + {skill.use.en} + + )) @@ -830,6 +912,23 @@ const base = import.meta.env.BASE_URL; rel="noopener">{labels.commonSkill.source.en}

+
+ ONE PRACTICAL LOADOUT +
+ PLAN unlazy → + BUILD ponytail-lite → + DEBUG diagnosing-bugs → + REPORT caveman +
+
@@ -898,6 +997,21 @@ const base = import.meta.env.BASE_URL; > +
Verificationrun each gate separately @@ -935,13 +1049,14 @@ const base = import.meta.env.BASE_URL; >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 → diff --git a/summary/index.html b/summary/index.html index ed706a8..25fb6b0 100644 --- a/summary/index.html +++ b/summary/index.html @@ -1 +1,70 @@ -AI For Dummies — Route map
← AI FOR DUMMIES00 / ROUTE MAPreview 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.

05

Practice

Compare prompts and skill-enabled runs.

Open lab →
06

Review desk

Browse original files and improved drafts.

Open desk →
Each chapter stands alone; the order follows a real task becoming a reliable change.
+ + + + + + AI For Dummies — Route map + + + +
+
+ ← AI FOR DUMMIES00 / ROUTE MAPreview 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 → +
+ + +
+ 05 +

Practice

+

Compare prompts and skill-enabled runs.

+ Open lab → +
+
+ 06 +

Review desk

+

Browse original files and improved drafts.

+ Open desk → +
+
+ + +
+ +