Orchestrator
Owns scope, task graph, boundaries, and integration.
diff --git a/GATES.md b/GATES.md index e05c9c1..188edd1 100644 --- a/GATES.md +++ b/GATES.md @@ -1,27 +1,23 @@ -# Gates: Rules and enforcement case study +# Gates: responsive chapter audit and summary landing -OWNS: rules/**, index.html, README.md, docs/operations-guide.md, scripts/verify.mjs +OWNS: index.html, full-guide/**, chapters.css, skills/index.html, skills/app.js, scripts/verify.mjs, scripts/audit-ui.mjs -Scope: Add a concise bilingual page that explains how `netcracker/interview` -combines agent context, reusable skills, CLI checks, Husky hooks, and PR review. +Scope: Make the route map the default entry point, repair the skills package anatomy layout, add purposeful interactions, and verify the guide across responsive, desktop, and accessibility-critical viewports. -- [ ] G1: separate rules page presents repository-grounded summary and examples +- [x] G1: root entry directs readers to the summary while the full guide remains available at a stable route CHECK: node scripts/verify.mjs - EXPECT: rules content verification passed - EVIDENCE: pending + EXPECT: landing route verification passed + EVIDENCE: `node scripts/verify.mjs` on 2026-09-04 emitted `landing route verification passed`. -- [ ] G2: pipeline, skill examples, language switch, and copy controls work +- [x] G2: the skill package anatomy renders as a readable tree with one node per line and selectable file previews CHECK: node scripts/verify.mjs - EXPECT: rules interaction verification passed - EVIDENCE: pending + EXPECT: skills anatomy verification passed + EVIDENCE: `node scripts/verify.mjs` on 2026-09-04 emitted `skills anatomy verification passed`; Playwright selected all four package files. -- [ ] G3: page is dependency-free and linked from the main presentation +- [x] G3: public pages reflow without horizontal overflow and retain usable navigation at compact through 4K viewports + EVIDENCE: Playwright audit on 2026-09-04: 10 public routes × 320, 390, 1280, 1920, and 3840px; no horizontal overflow, HTTP failures, page errors, or failed skills-package selections. + +- [x] G4: repository verification covers the landing route, skills anatomy, and interaction contracts CHECK: node scripts/verify.mjs - EXPECT: rules standalone verification passed - EVIDENCE: pending - -- [ ] G4: mobile, Full HD, and 4K browser checks pass without overflow or errors - EVIDENCE: pending - -- [ ] G5: main and pages point to one commit and the live rules endpoint serves it - EVIDENCE: pending + EXPECT: presentation verification passed + EVIDENCE: `node scripts/verify.mjs` and `node scripts/audit-ui.mjs` passed on 2026-09-04. diff --git a/README.md b/README.md index 97a00a5..e601ba1 100644 --- a/README.md +++ b/README.md @@ -32,16 +32,16 @@ npm run verify ## Project structure -- `index.html` — presentation content and semantic structure -- `styles.css` — editorial visual system and responsive layout -- `app.js` — bilingual workflow, repository-tree, routing, and skill interactions +- `index.html` — default route map and focused chapter navigation +- `full-guide/` — the complete bilingual presentation, with responsive audit overrides +- `styles.css` / `app.js` — editorial visual system and bilingual field-guide interactions - `responsive.css` — interactive diagrams and Full HD-to-4K adaptations - `docs/references/` — bundled research sources and notes - `docs/operations-guide.md` — canonical SilverBullet operations and skills guide - `hands-on/starter/` — dependency-free Tiny Tasks exercise - `hands-on/rules/` — dependency-free Guardrails lab; toggles rule sources into the prompt - `rules/` — bilingual case study of skills, CLI ratchets, Husky, and PR review -- `skills/` — reusable design and rules-case-study skills extracted from this implementation +- `skills/` — reusable design and rules-case-study skills, plus an interactive package anatomy explorer - `GATES.md` — acceptance ledger for the project ## Publishing diff --git a/agents/index.html b/agents/index.html index ee4d1f3..ce8da42 100644 --- a/agents/index.html +++ b/agents/index.html @@ -1 +1 @@ -
Subagent workflow
Agents work when roles, files, and evidence are bounded. A worktree gives each worker its own checkout while the orchestrator protects intent.
The tree
├── agent/ui → components + visual states · ├── agent/tests → acceptance + regressions · └── agent/docs → guide + examples · merge after each leaf returns a diff and evidenceOwns scope, task graph, boundaries, and integration.
Owns one coherent slice and one worktree.
Re-runs gates and reports remaining gaps.
Handoff
Subagent workflow
Agents work when roles, files, and evidence are bounded. A worktree gives each worker its own checkout while the orchestrator protects intent.
The tree
├── agent/ui → components + visual states · ├── agent/tests → acceptance + regressions · └── agent/docs → guide + examples · merge after each leaf returns a diff and evidenceOwns scope, task graph, boundaries, and integration.
Owns one coherent slice and one worktree.
Re-runs gates and reports remaining gaps.
Handoff
A presentation for humans who ship
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.
Read this as a route map, not a prompt recipe.
Opus / reasoningThe orchestrator preserves intent, writes small contracts, and gathers results that can be verified. It does not need to type every line.
Every worker reads everything. Nobody knows which facts are load-bearing.
Two agents touch the same checkout. The fastest path becomes conflict resolution.
The diff is polished, but no one checks whether it solved the original problem.
The subagent loop
Delegation means moving one bounded task into a smaller context—not giving away responsibility.
| 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
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.
Model routing
Choose a job to see why the model profile changes.
Two separate knobs
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.
Skills
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.
name: review-ui · check focus, mobile, reduced motion · run verification · return evidenceThe skill forge
Do not package everything you know. Capture the non-obvious choices that repeatedly improve an outcome, then prove the skill changes behavior.
The field kit
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.
Tiny Tasks lab
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.
Checks become evidence
Run a gate on its own line, print its exit code, attach the output. The result is the deliverable.
Format, lint, type-check. Fast and scoped to one file. Run on every save.
pnpm lint; echo "lint=$?"
+pnpm typecheck; echo "typecheck=$?"Tests that repeat. Run before claiming done.
pnpm test; echo "test=$?"
+cd services/api && go test ./...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 e2etail, grep, or head hide the real exit code — a pipeline returns the last command's status.
A silent .catch(() => {}) hides a panic, an upstream limit, or a partial failure.
Turbo caches results. A gate that "passes" may not have run — use TURBO_FORCE=true.
Lint and unit can both be green while the page breaks on mobile and the API never returns 404.
Fill the four-row comparison strip on the starter. Run A naively, Run B with $gate-discipline and $webapp-testing.
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/rulesGo 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 →
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.
A presentation for humans who ship
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.
Read this as a route map, not a prompt recipe.
Opus / reasoningThe orchestrator preserves intent, writes small contracts, and gathers results that can be verified. It does not need to type every line.
Every worker reads everything. Nobody knows which facts are load-bearing.
Two agents touch the same checkout. The fastest path becomes conflict resolution.
The diff is polished, but no one checks whether it solved the original problem.
The subagent loop
Delegation means moving one bounded task into a smaller context—not giving away responsibility.
| 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
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.
Model routing
Choose a job to see why the model profile changes.
Two separate knobs
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.
Skills
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.
name: review-ui · check focus, mobile, reduced motion · run verification · return evidenceThe skill forge
Do not package everything you know. Capture the non-obvious choices that repeatedly improve an outcome, then prove the skill changes behavior.
The field kit
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.
Tiny Tasks lab
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.
Checks become evidence
Run a gate on its own line, print its exit code, attach the output. The result is the deliverable.
Format, lint, type-check. Fast and scoped to one file. Run on every save.
pnpm lint; echo "lint=$?"
-pnpm typecheck; echo "typecheck=$?"Tests that repeat. Run before claiming done.
pnpm test; echo "test=$?"
-cd services/api && go test ./...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 e2etail, grep, or head hide the real exit code — a pipeline returns the last command's status.
A silent .catch(() => {}) hides a panic, an upstream limit, or a partial failure.
Turbo caches results. A gate that "passes" may not have run — use TURBO_FORCE=true.
Lint and unit can both be green while the page breaks on mobile and the API never returns 404.
Fill the four-row comparison strip on the starter. Run A naively, Run B with $gate-discipline and $webapp-testing.
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/rulesGo 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 →
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.
The short route
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 →Capability and effort are separate knobs.
Open chapter →Bound roles, handoffs, and worktrees.
Open chapter →Capture repeatable decisions in small packages.
Open chapter →Connect guidance to enforcement.
Open chapter →Compare a strong prompt with skill-enabled work.
Open lab →Browse original packages, references, scripts, and improvements.
Open desk →