merge: task 03-verification-net

.agents/scripts/visual-regression.mjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+// Keep vanilla screenshots before a page changes; compare them against the
+// migrated preview when a visual diff needs investigation.
+
+import { mkdirSync } from 'node:fs';
+
+const routes = [
+  '/',
+  '/full-guide/',
+  '/summary/',
+  '/models/',
+  '/agents/',
+  '/skills/',
+  '/rules/',
+  '/skills-review/',
+  '/hands-on/starter/',
+  '/hands-on/rules/',
+];
+const widths = [560, 800, 1100, 1600];
+const hasReducedMotion = process.argv.includes('--reduced-motion');
+const base = process.env.VISUAL_BASE_URL ?? 'http://localhost:4173';
+const output =
+  process.env.VISUAL_OUTPUT_DIR ??
+  `.agents/snapshots/${hasReducedMotion ? 'before-reduced-motion' : 'before'}`;
+
+mkdirSync(output, { recursive: true });
+
+let chromium;
+try {
+  ({ chromium } = await import('playwright'));
+} catch {
+  throw new Error(
+    'visual regression requires Playwright; install its project dependency and run npx playwright install chromium',
+  );
+}
+
+const browser = await chromium.launch({
+  headless: true,
+  ...(process.env.VISUAL_BROWSER_PATH ? { executablePath: process.env.VISUAL_BROWSER_PATH } : {}),
+});
+try {
+  for (const route of routes) {
+    for (const width of widths) {
+      const page = await browser.newPage({ viewport: { width, height: 900 } });
+      if (hasReducedMotion) await page.emulateMedia({ reducedMotion: 'reduce' });
+      // The legacy site intentionally calls optional services that may be down;
+      // visual capture is about the rendered page, not their network lifetime.
+      await page.goto(new URL(route, base).toString(), { waitUntil: 'domcontentloaded' });
+      const name = route.replace(/^\/+|\/+$/g, '').replaceAll('/', '_') || 'index';
+      await page.screenshot({ path: `${output}/${name}-${width}.png`, fullPage: true });
+      await page.close();
+    }
+  }
+} finally {
+  await browser.close();
+}
+
+console.log(`captured ${routes.length * widths.length} screenshots in ${output}`);

.agents/snapshots/agents.txt

@@ -0,0 +1,40 @@
+AI For Dummies — Agents and trees
+← ROUTE MAP
+02 / AGENTS & TREES
+field guide ↗
+Subagent workflow
+One branch
+per
+hand.
+Agents work when roles, files, and evidence are bounded. A worktree gives each worker its own checkout while the orchestrator protects intent.
+The tree
+Split at
+the
+seam.
+MAIN / ORCHESTRATOR
+├── agent/ui → components + visual states · ├── agent/tests → acceptance + regressions · └── agent/docs → guide + examples · merge after each leaf returns a diff and evidence
+FRAME
+Orchestrator
+Owns scope, task graph, boundaries, and integration.
+HAND OFF
+Worker
+Owns one coherent slice and one worktree.
+PROVE
+Verifier
+Re-runs gates and reports remaining gaps.
+Handoff
+Context that
+can
+travel.
+01
+Brief
+Goal, owned files, dependencies, non-goals, acceptance.
+02
+Isolation
+One branch and worktree per independent change.
+03
+Evidence
+Commands, result, changed files, screenshots, gaps.
+Previous: models →
+Rules case study →
+Try the rules lab →

.agents/snapshots/full-guide.txt

@@ -0,0 +1,375 @@
+AI For Dummies — Field Guide
+A
+field guide
+01 fleet
+02 worktrees
+03 models
+04 skills
+05 create
+06 field kit
+07 hands-on
+08 verify
+review submissions ↗
+EN
+/
+PT
+AI ENGINEERING
+01 / 2026
+A presentation for humans who ship
+AI for
+dummies.
+You do not need an army of models. You need a system: one mind to frame the work, several hands to execute it, and a clean boundary between every task.
+FIELD NOTE / 001
+Ship the
+system.
+Skills · agents · worktrees · proof
+01
+strong model
+for ambiguity
+03
+bounded workers
+in parallel
+∞
+iterations
+with evidence
+Read this as a route map, not a prompt recipe.
+RULE ZERO
+Strong model for ambiguity.
+Light model for bounded work.
+THINK
+MAKE
+A small fleet
+coordination before parallelism
+ORCHESTRATOR
+Decides what
+needs to happen.
+Opus / reasoning
+→
+UI
+Component and visual states
+agent/ui
+TEST
+Acceptance cases
+agent/tests
+DOCS
+Guide and examples
+agent/docs
+The orchestrator preserves intent, writes small contracts, and gathers results that can be verified. It does not need to type every line.
+Why the boundary matters
+one vague task / three predictable failures
+01
+Context soup
+Every worker reads everything. Nobody knows which facts are load-bearing.
+02
+Branch collision
+Two agents touch the same checkout. The fastest path becomes conflict resolution.
+03
+Confident drift
+The diff is polished, but no one checks whether it solved the original problem.
+The subagent loop
+Click a phase.
+See the handoff.
+Delegation means moving one bounded task into a smaller context—not giving away responsibility.
+01
+PLAN
+02
+BUILD
+03
+REVIEW
+What crosses contexts
+brief → diff → evidence
+Package
+Contains
+Why it matters
+Brief
+goal, files, boundaries
+stops the worker inventing the problem
+Worktree
+branch and isolated checkout
+parallel edits do not collide
+Checks
+tests, build, criteria
+turns “looks good” into evidence
+Diff
+small, reviewable change
+integration and discard stay cheap
+Git worktrees
+One branch
+per
+hand.
+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.
+repository topology
+4 checkouts
+ROOT
+main
+● clean
+UI AGENT
+agent/ui
+3 files · working
+TEST AGENT
+agent/tests
+8 checks · ready
+DOCS AGENT
+agent/docs
+2 pages · review
+Model routing
+Do not pay for
+reasoning where
+you need
+rhythm.
+Choose a job to see why the model profile changes.
+Work
+Profile
+Prompt shape
+Plan
+strong / broad
+What changes? What can break?
+Build
+fast / focused
+Implement this slice. Run these checks.
+Explore
+read-only / light
+Find where this contract is used.
+Review
+independent
+Does the diff satisfy the brief?
+Model gearbox
+capability tier × thinking effort
+Two separate knobs
+Choose the engine.
+Then choose the
+gear.
+A stronger model changes the capability ceiling. Higher reasoning effort gives that model more room to work. Start with the lightest combination that passes your real checks, then move one knob at a time.
+OPENAI
+CLAUDE
+GEMINI
+REASONING / THINKING
+LOW
+bounded + fast
+MEDIUM
+default start
+HIGH
+complex + costly
+ROUTING RULE
+Use strong models for ambiguity and judgment. Use lighter models for bounded execution. Raise effort only when evaluation shows a gain.
+Skills
+Write the right way
+once.
+A skill is a reusable procedure. It can carry instructions, references, scripts, and assets. It is not magical memory, and it does not replace acceptance criteria.
+01 / trigger clearly
+02 / load detail on demand
+03 / return evidence
+SKILL PACKAGE
+SKILL.md
+procedure and limits
+references/
+facts to consult
+scripts/
+repeatable checks
+assets/
+templates and examples
+name: review-ui · check focus, mobile, reduced motion · run verification · return evidence
+Create a skill
+repeatable pain → reusable judgment
+The skill forge
+Teach the decision.
+Keep the context
+light.
+Do not package everything you know. Capture the non-obvious choices that repeatedly improve an outcome, then prove the skill changes behavior.
+01
+Observe
+find repeated friction
+02
+Define trigger
+route precisely
+03
+Choose anatomy
+only needed files
+04
+Write guidance
+decisions, not trivia
+05
+Validate
+test real behavior
+OUTPUT / SKILL PACKAGE
+review-ui/
+├── SKILL.md
+├── agents/
+│   └── openai.yaml
+├── references/
+│   └── accessibility.md
+└── scripts/
+└── verify.mjs
+VALIDATE
+quick_validate.py ./review-ui
+AFTER REAL USE
+observe failure
+→
+sharpen one rule
+→
+retest behavior
+→
+keep it narrow
+Common skills
+choose behavior before model
+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.
+SIMPLIFY
+ponytail-lite
+minimum code that holds
+COMMUNICATE
+caveman
+signal without filler
+COMPLETE
+unlazy
+gates and evidence
+INVESTIGATE
+research
+primary sources first
+DIAGNOSE
+diagnosing-bugs
+tight feedback loop
+REVIEW
+code-review
+standards × spec
+ECONOMIZE
+token-saver
+compress noisy output
+ONE PRACTICAL LOADOUT
+PLAN
+unlazy
+→
+BUILD
+ponytail-lite
+→
+DEBUG
+diagnosing-bugs
+→
+REPORT
+caveman
+INSTALL PACK
+Ask your coding agent to verify, install, and validate the skills.
+COPY
+↗
+Review every source before installation. Existing local skills must be preserved.
+Hands-on
+10 minutes / one missing feature
+Tiny Tasks lab
+Same task.
+Better
+operating system.
+Start with a deliberately incomplete static task board. Run one prompt as written, reset, then run the skill-enabled version. Compare diff size, verification evidence, and unnecessary complexity.
+Open the starter →
+Clone from Gitea →
+Open the rules lab →
+Clone from Gitea →
+THE MISSING FEATURE
+Add All / Open / Done filters that survive reload and browser navigation.
+STACK
+HTML · CSS · JavaScript
+DEPENDENCIES
+none
+FILES
+3
+RUN A
+Good prompt
+COPY
+↗
+Clear context · constraints · acceptance · evidence
+RUN B
+Good prompt + skills
+COPY
+↗
+Same contract · explicit working methods · stronger proof
+COMPARE THE RUNS
+01
+Files changed
+02
+New dependencies
+03
+Checks actually run
+04
+Evidence returned
+THE HUMAN JOB
+The agent may be autonomous in execution. Intent, boundaries, and evidence remain yours.
+START HERE
+Begin with one agent and one skill. Add parallelism only when the tasks are truly independent.
+Verification
+run each gate separately
+Checks become evidence
+Three layers.
+Run each one alone.
+Run a gate on its own line, print its exit code, attach the output. The result is the deliverable.
+01 · STATIC
+Lint and types
+Format, lint, type-check. Fast and scoped to one file. Run on every save.
+pnpm lint; echo "lint=$?"
+pnpm typecheck; echo "typecheck=$?"
+02 · BEHAVIOR
+Unit and contract
+Tests that repeat. Run before claiming done.
+pnpm test; echo "test=$?"
+cd services/api && go test ./...
+03 · INTEGRATION
+Real UI and API
+Drive the actual UI, API, or browser. Slower and flakier — only this catches mobile overflow and a missing 404.
+pnpm check:ui; echo "ui=$?"
+TURBO_FORCE=true pnpm e2e
+FOUR WAYS A GREEN REPORT IS FALSE
+1
+Pipe a gate
+tail, grep, or head hide the real exit code — a pipeline returns the last command's status.
+2
+Swallow a rejection
+A silent
+.catch(() => {})
+hides a panic, an upstream limit, or a partial failure.
+3
+Trust the cache
+Turbo caches results. A gate that "passes" may not have run — use
+TURBO_FORCE=true
+.
+4
+Skip the third layer
+Lint and unit can both be green while the page breaks on mobile and the API never returns 404.
+RUN IT YOURSELF · two labs, under 10 minutes each
+Path A · verification lab
+Fill the four-row comparison strip on the starter. Run A naively, Run B with
+$gate-discipline
+and
+$webapp-testing
+.
+Open the starter →
+Clone ↗
+git.marcospaulo.dev.br/.../src/branch/pages/hands-on/starter
+Path B · rules lab
+Toggle every rule off, run the prompt. Toggle every rule on, run it again. Compare diff size, gate invocations, and the names of checks the agent names back.
+Open the rules lab →
+Clone ↗
+git.marcospaulo.dev.br/.../src/branch/pages/hands-on/rules
+Keep learning
+12 new readings + primary docs
+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 →
+Navigate by idea
+short chapters / one system
+Prefer a focused chapter? Start with the
+route map
+, then jump directly to
+models
+,
+agents and worktrees
+,
+skill creation
+,
+rules
+, or the
+skills review desk
+.

.agents/snapshots/hands-on/rules.txt

@@ -0,0 +1,14 @@
+Guardrails — Hands-on Rules
+HANDS-ON / RULES
+Guardrails
+Toggle rules. Same task, different coverage.
+Rule sources
+0 / 5 active
+Prompt diff
+EN
+PT
+NAIVE
+Plain prompt
+RULED
+With guardrails
+Copy ruled prompt

.agents/snapshots/hands-on/starter.txt

@@ -0,0 +1,5 @@
+Tiny Tasks — Hands-on Starter
+HANDS-ON / STARTER
+Tiny Tasks
+Three tasks. One missing filter.
+Today

.agents/snapshots/index.txt

@@ -0,0 +1,37 @@
+AI For Dummies — Start here
+AI FOR DUMMIES
+00 / START HERE
+review desk ↗
+The short route
+Ship the
+system.
+Start with the map. Then open the one chapter that matches the decision in front of you: model, agent, worktree, skill, rule, or proof.
+Take the full field guide
+→
+01
+Models
+Capability and effort are separate knobs.
+Open chapter →
+02
+Agents & trees
+Bound roles, handoffs, and worktrees.
+Open chapter →
+03
+Skills
+Capture repeatable decisions in small packages.
+Open chapter →
+04
+Rules
+Connect guidance to enforcement.
+Open chapter →
+05
+Hands-on
+Compare a strong prompt with skill-enabled work.
+Open lab →
+06
+Review desk
+Browse original packages, references, scripts, and improvements.
+Open desk →
+THE THREAD
+Frame uncertainty → isolate execution → preserve judgment → verify the change.
+The route map is now the default entry. The full guide remains available whenever you want the whole narrative.

.agents/snapshots/models.txt

@@ -0,0 +1,37 @@
+AI For Dummies — Models
+← ROUTE MAP
+01 / MODELS
+field guide ↗
+Model routing
+Choose the
+engine.
+A model has a capability ceiling. Effort controls how much room it gets to reason. Route by uncertainty and verification cost.
+LOW
+Bounded rhythm
+Lookup, small edits, formatting, and transformations with clear checks.
+MEDIUM
+Default work
+Normal implementation where the contract is clear but context matters.
+HIGH
+Ambiguity
+Planning, architecture, security judgment, and hard failures.
+Two knobs
+Capability
+× effort
+ROUTING RULE
+strong model + high effort → frame ambiguity · light model + low effort → bounded execution · raise one knob at a time → compare evidence
+Sequence
+Spend judgment
+where it
+compounds.
+01
+Plan
+Strong model: scope, risks, acceptance, and worktree split.
+02
+Build
+Focused worker: smallest context and lightest model that can pass.
+03
+Review
+Independent pass when missed issues cost more than the call.
+Next: agents & trees →
+Rules case study →

.agents/snapshots/rules.txt

@@ -0,0 +1,118 @@
+Rules That Survive the Prompt — AI For Dummies
+A
+field guide
+Pipeline
+Skills
+Examples
+EN
+/
+PT
+A real repository case study
+Rules that
+survive the
+prompt.
+Prompts ask for behavior. Repositories preserve it. The interview project combines written context, reusable skills, executable checks, commit hooks, and independent review so the rule is still present when the conversation is gone.
+CASE / NETCRACKER
+interview
+8 skills · 3 agents · 4 enforcement layers
+THE SHORT VERSION
+A prompt is advice for one run. A repository rule is reusable context plus an executable boundary.
+Enforcement pipeline
+select a checkpoint
+From intent to evidence
+Five places
+a rule can
+hold.
+Not every rule belongs in a hook. Put guidance where an agent can discover it, deterministic policy in a command, cheap checks at commit time, and independent judgment at review.
+01
+CONTEXT
+AGENTS.md
+→
+02
+SKILLS
+.agents/skills
+→
+03
+CLI
+check:ui
+→
+04
+COMMIT
+Husky
+→
+05
+REVIEW
+pragent
+Project-local skills
+procedures born from repeated friction
+Small instruction packages
+Teach the trap.
+Name the
+trigger.
+These skills are not downloaded magic. They are repository-specific procedures under
+.agents/skills/
+, distilled from mistakes, commands, and architectural decisions that kept recurring.
+gate-discipline
+prove green is real
+parallel-agents
+worktree per task
+repo-db
+query before crawling
+tech-debt
+separate line of work
+skill-writer
+repeat twice, encode once
+frontend / go-api
+stack-specific traps
+Concrete examples
+open the source, then adapt
+CLI RATCHET
+Debt may go down.
+Never silently up.
+pnpm check:ui
+# raw buttons
+# swallowed catches
+# pages without h1
+# hardcoded colours
+Read the checker →
+HUSKY / PRE-COMMIT
+Fast checks before history.
+pnpm exec lint-staged
+node scripts/check-ui-contract.mjs
+Read the hook →
+COMMIT MESSAGE
+Intent has a grammar.
+pnpm exec commitlint --edit $1
+feat: add interview timer
+fix(api): scope session query
+Read commitlint config →
+INDEPENDENT REVIEW
+A second reader checks intent.
+.pr-review.json
+├── focus
+├── exclude_paths
+├── languages
+└── instructions
+Read review policy →
+COPY / ADAPT
+Ask your agent to map the enforcement stack.
+Use this in the interview repository or adapt the path names to another project.
+COPY PROMPT
+↗
+GO DEEPER
+Read the implementation, not just this summary.
+01
+Repository context
+AGENTS.md
+02
+Skill catalog
+.agents/skills/
+03
+Design skills
+skills/
+03
+Specialist agents
+.claude/agents/
+04
+Staged-file policy
+.lintstagedrc.cjs

.agents/snapshots/skills-review.txt

@@ -0,0 +1,50 @@
+Submitted Skills — Review Desk
+← field guide
+SUBMITTED SKILLS / REVIEW DESK
+submissions
+A friendly path from draft to dependable
+Every skill deserves
+a clear job.
+Read the original, understand what already works, and compare a safer, leaner draft. Nothing here overwrites a submission; revisions live in their own review output.
+01
+Discoverable
+A precise description tells an agent when to load the skill.
+02
+Useful in context
+Core workflow stays short; conditional detail loads only when needed.
+03
+Safe by design
+Commands, secrets, and shared systems have explicit boundaries.
+04
+Proven in use
+Real prompts and observable checks turn a draft into a reliable tool.
+How to use this desk
+Compare.
+Then choose.
+Select a submission, or open an author URL.
+Read the gentle review before judging the draft.
+Choose
+Preview Markdown
+in the file toolbar to render either version.
+Copy or download the version you want, then vote for the draft you would ship.
+The catalog
+Find a skill
+Why these reviews look this way
+The recommendations follow the open Agent Skills format: valid frontmatter for discovery, progressive disclosure for context economy, deterministic scripts for fragile repeated mechanics, and behavioral evaluation rather than a checklist of pretty headings.
+Format specification ↗
+Writing practices ↗
+Evaluation loop ↗
+Scripts guide ↗
+Share an author with
+?author=Name
+, or one review with
+?author=Name&skill=skill-id&view=improved
+. To add a submission later: drop a package under
+submitted-skills/
+, add a tailored entry in
+skills-review/catalog.js
+, then run
+node scripts/build-skill-review.mjs
+. Votes call a separate service — see
+vote-service/
+— one per visitor, tracked by network source.

.agents/snapshots/skills.txt

@@ -0,0 +1,45 @@
+AI For Dummies — Skills
+← ROUTE MAP
+03 / SKILLS
+review desk ↗
+Reusable judgment
+Teach the
+decision.
+A skill changes behavior. Keep the trigger precise, put the workflow in
+SKILL.md
+, and move conditional facts, scripts, and examples into focused files.
+Package anatomy
+One job.
+More than
+one
+file.
+Choose a file to see why it belongs in the package.
+REVIEW-UI / SKILL PACKAGE
+├── SKILL.md
+trigger + workflow
+├── references/
+conditional facts
+├── scripts/
+deterministic checks
+└── assets/
+templates + examples
+Create a skill
+Observe →
+trigger →
+validate
+01
+Observe friction
+Find a repeated decision or failure.
+02
+Define the trigger
+Say when it should load and when it should stay out.
+03
+Choose anatomy
+Use references for facts and scripts for deterministic mechanics.
+04
+Evaluate behavior
+Test realistic prompts, edge cases, safety, and evidence.
+Agents & trees →
+Rules case study →
+Review submitted skills →
+Full guide: skill forge →