From 273ea5e259bcd13c6609e482c7831d01c848417d Mon Sep 17 00:00:00 2001 From: Marcos Paulo Date: Wed, 2 Sep 2026 01:30:12 +0000 Subject: [PATCH] feat: add interactive agent workflow diagrams --- README.md | 6 +- app.js | 78 +++++++++++++++++++++++- docs/references/README.md | 4 ++ docs/references/additional-reading.md | 88 +++++++++++++++++++++++++++ index.html | 10 +-- responsive.css | 35 +++++++++++ scripts/verify.mjs | 7 ++- 7 files changed, 216 insertions(+), 12 deletions(-) create mode 100644 docs/references/additional-reading.md diff --git a/README.md b/README.md index f00b582..06e9df4 100644 --- a/README.md +++ b/README.md @@ -25,7 +25,8 @@ npm run verify - `index.html` — presentation content and semantic structure - `styles.css` — editorial visual system and responsive layout -- `app.js` — small workflow-phase interaction +- `app.js` — bilingual workflow, repository-tree, routing, and skill interactions +- `responsive.css` — interactive diagrams and Full HD-to-4K adaptations - `docs/references/` — bundled research sources and notes - `GATES.md` — acceptance ledger for the project @@ -44,4 +45,5 @@ Server and Actions deployment path. ## Research See [docs/references/README.md](docs/references/README.md) for official Claude, -Codex, and Git documentation plus agent-workflow research. +Codex, and Git documentation. The [additional reading path](docs/references/additional-reading.md) +bundles 12 verified articles and guides, including Medium and practitioner sources. diff --git a/app.js b/app.js index ef8e2fc..44f092f 100644 --- a/app.js +++ b/app.js @@ -4,16 +4,42 @@ const phases = { review: { model: { en: 'STRONG MODEL OR HUMAN', pt: 'MODELO FORTE OU HUMANO' }, title: { en: 'Reconnect result to intent', pt: 'Reconecte o resultado à intenção' }, copy: { en: 'Check the diff against the original brief, run the checks, then merge, request changes, or discard.', pt: 'Compare o diff com o brief original, execute as verificações e então faça merge, peça mudanças ou descarte.' }, code: { en: 'diff + checks → review → merge / iterate', pt: 'diff + verificações → revisar → merge / iterar' } } }; +const interactiveCopy = { + workers: { + ui: { en: ['Interface worker', 'Receives: component contract + visual states', 'Returns: focused diff + viewport evidence'], pt: ['Worker de interface', 'Recebe: contrato do componente + estados visuais', 'Devolve: diff focado + evidência dos viewports'] }, + tests: { en: ['Verification worker', 'Receives: acceptance criteria + changed surface', 'Returns: failing case, passing checks, risk notes'], pt: ['Worker de verificação', 'Recebe: critérios de aceitação + superfície alterada', 'Devolve: caso de falha, verificações passando e riscos'] }, + docs: { en: ['Documentation worker', 'Receives: reviewed behavior + audience', 'Returns: guide, examples, and migration notes'], pt: ['Worker de documentação', 'Recebe: comportamento revisado + público', 'Devolve: guia, exemplos e notas de migração'] } + }, + trees: { + main: { status: 'clean', owner: { en: 'Orchestrator', pt: 'Orquestrador' }, path: './project', command: 'git worktree list', note: { en: 'Shared history and integration point. Workers never edit here.', pt: 'Histórico compartilhado e ponto de integração. Workers nunca editam aqui.' } }, + ui: { status: 'working', owner: { en: 'UI worker', pt: 'Worker de UI' }, path: '../task-ui', command: 'git worktree add ../task-ui -b agent/ui', note: { en: 'Own checkout and index. Safe to change presentation files in parallel.', pt: 'Checkout e índice próprios. Seguro para alterar a apresentação em paralelo.' } }, + tests: { status: 'ready', owner: { en: 'Test worker', pt: 'Worker de testes' }, path: '../task-tests', command: 'git diff main...agent/tests', note: { en: 'Checks are green. Review the diff before merging into main.', pt: 'Verificações passaram. Revise o diff antes do merge em main.' } }, + docs: { status: 'review', owner: { en: 'Docs worker', pt: 'Worker de docs' }, path: '../task-docs', command: 'git merge --no-ff agent/docs', note: { en: 'Review requested. Merge, request changes, or discard without touching another checkout.', pt: 'Revisão solicitada. Faça merge, peça mudanças ou descarte sem tocar em outro checkout.' } } + }, + routes: { + plan: { score: 92, label: { en: 'High ambiguity', pt: 'Alta ambiguidade' }, why: { en: 'Architecture and decomposition have a wide error surface. Spend reasoning here.', pt: 'Arquitetura e decomposição têm grande superfície de erro. Invista raciocínio aqui.' } }, + build: { score: 38, label: { en: 'Bounded execution', pt: 'Execução delimitada' }, why: { en: 'The brief already removed ambiguity. Optimize for speed and tight feedback.', pt: 'O brief já removeu a ambiguidade. Otimize para velocidade e feedback curto.' } }, + explore: { score: 22, label: { en: 'Read-only discovery', pt: 'Descoberta somente leitura' }, why: { en: 'Search, map, and report. A lightweight model can return facts without editing.', pt: 'Busque, mapeie e reporte. Um modelo leve devolve fatos sem editar.' } }, + review: { score: 74, label: { en: 'Independent judgment', pt: 'Julgamento independente' }, why: { en: 'Reconnect the diff to intent with fresh context and adversarial attention.', pt: 'Reconecte o diff à intenção com contexto novo e atenção crítica.' } } + }, + skillFiles: { + skill: { icon: '◇', title: 'SKILL.md', en: 'Trigger, procedure, constraints, and the exact evidence the agent must return.', pt: 'Gatilho, procedimento, restrições e a evidência exata que o agente deve devolver.' }, + references: { icon: '≡', title: 'references/', en: 'Stable facts loaded only when the procedure needs them. Keep the main instruction lean.', pt: 'Fatos estáveis carregados apenas quando o procedimento precisa. Mantenha a instrução principal enxuta.' }, + scripts: { icon: '›_', title: 'scripts/', en: 'Deterministic checks and repeated operations. Prefer executable proof over prose.', pt: 'Verificações determinísticas e operações repetidas. Prefira prova executável a prosa.' }, + assets: { icon: '▧', title: 'assets/', en: 'Templates and examples the agent can copy without reinventing the expected shape.', pt: 'Templates e exemplos que o agente pode copiar sem reinventar o formato esperado.' } + } +}; + const translations = { pt: { '.chapter-links a:nth-child(1)': '01 frota', '.chapter-links a:nth-child(2)': '02 worktrees', '.chapter-links a:nth-child(3)': '03 skills', '.edition': 'ENGENHARIA DE IA 01 / 2026', '.hero .eyebrow': 'Uma apresentação para quem entrega software', '.lede': 'Você não precisa de um exército de modelos. Precisa de um sistema: uma mente para enquadrar o trabalho, várias mãos para executá-lo e uma fronteira clara entre cada tarefa.', '.hero-index span': 'NOTA DE CAMPO / 001', '.hero-index strong': 'Entregue o
sistema.', '.hero-index small': 'Skills · agentes · worktrees · evidências', '.hero-stats div:nth-child(1) span': 'modelo forte
para ambiguidade', '.hero-stats div:nth-child(2) span': 'workers delimitados
em paralelo', '.hero-stats div:nth-child(3) span': 'iterações
com evidências', '.hero-stats p': 'Leia isto como um mapa de rota, não como uma receita de prompt.', - '.thesis span': 'REGRA ZERO', '.thesis strong': 'Modelo forte para ambiguidade.
Modelo leve para trabalho delimitado.', '.fleet .section-label span:nth-child(1)': 'Uma pequena frota', '.fleet .section-label span:nth-child(2)': 'coordenação antes do paralelismo', '.captain span': 'ORQUESTRADOR', '.captain h2': 'Decide o que
precisa acontecer.', '.caption': 'O orquestrador preserva a intenção, escreve pequenos contratos e reúne resultados verificáveis. Ele não precisa digitar cada linha.', + '.thesis span': 'REGRA ZERO', '.thesis strong': 'Modelo forte para ambiguidade.
Modelo leve para trabalho delimitado.', '.fleet .section-label span:nth-child(1)': 'Uma pequena frota', '.fleet .section-label span:nth-child(2)': 'coordenação antes do paralelismo', '.captain span': 'ORQUESTRADOR', '.captain h2': 'Decide o que
precisa acontecer.', '.worker-card[data-worker="ui"] strong': 'Componentes e estados visuais', '.worker-card[data-worker="tests"] strong': 'Casos de aceitação', '.worker-card[data-worker="docs"] strong': 'Guia e exemplos', '.caption': 'O orquestrador preserva a intenção, escreve pequenos contratos e reúne resultados verificáveis. Ele não precisa digitar cada linha.', '.failure-map .section-label span:nth-child(1)': 'Por que a fronteira importa', '.failure-map .section-label span:nth-child(2)': 'uma tarefa vaga / três falhas previsíveis', '.failure-grid article:nth-child(1) strong': 'Sopa de contexto', '.failure-grid article:nth-child(1) p': 'Cada worker lê tudo. Ninguém sabe quais fatos são essenciais.', '.failure-grid article:nth-child(2) strong': 'Colisão de branches', '.failure-grid article:nth-child(2) p': 'Dois agentes usam o mesmo checkout. O caminho mais rápido vira resolução de conflitos.', '.failure-grid article:nth-child(3) strong': 'Desvio confiante', '.failure-grid article:nth-child(3) p': 'O diff parece ótimo, mas ninguém verifica se resolveu o problema original.', '.workflow .eyebrow': 'O ciclo de subagentes', '#workflow-title': 'Clique em uma fase.
Veja a passagem.', '.workflow .copy > p:last-child': 'Delegar é mover uma tarefa delimitada para um contexto menor — não abrir mão da responsabilidade.', '.handoff .section-label span:nth-child(1)': 'O que atravessa contextos', '.handoff .section-label span:nth-child(2)': 'brief → diff → evidência', '.handoff thead th:nth-child(1)': 'Pacote', '.handoff thead th:nth-child(2)': 'Contém', '.handoff thead th:nth-child(3)': 'Por que importa', - '.worktrees .eyebrow': 'Git worktrees', '.worktrees h2': 'Uma branch
por mão.', '.worktrees > div:first-child > p': 'Um worktree é outro diretório ligado ao mesmo repositório. Cada agente recebe seu próprio checkout e índice; o histórico continua compartilhado.', '.routing .eyebrow': 'Roteamento de modelos', '.routing h2': 'Não pague por
raciocínio onde precisa
de ritmo.', '.skills .eyebrow': 'Skills', '.skills h2': 'Escreva do jeito certo
uma vez.', '.skills > div:first-child > p': 'Uma skill é um procedimento reutilizável. Ela pode carregar instruções, referências, scripts e assets. Não é memória mágica e não substitui critérios de aceitação.', - '.skill-principles span:nth-child(1)': '01 / defina o gatilho', '.skill-principles span:nth-child(2)': '02 / carregue detalhes sob demanda', '.skill-principles span:nth-child(3)': '03 / devolva evidências', '.skill-package > span': 'PACOTE DE SKILL', '.rule span': 'O PAPEL HUMANO', '.rule strong': 'O agente pode ser autônomo na execução. Intenção, limites e evidências continuam sendo seus.', '.callout span': 'COMECE AQUI', '.callout strong': 'Comece com um agente e uma skill. Adicione paralelismo apenas quando as tarefas forem realmente independentes.', '.sources .section-label span:nth-child(1)': 'Continue aprendendo', '.sources .section-label span:nth-child(2)': 'fontes reunidas localmente', '.sources p': 'Baseado em pesquisas sobre Claude Code, Codex, Git e fluxos de agentes. Abrir o pacote de referências →' + '.worktrees .eyebrow': 'Git worktrees', '.worktrees h2': 'Uma branch
por mão.', '.worktree-intro > p:nth-of-type(2)': 'Um worktree é outro diretório ligado ao mesmo repositório. Cada agente recebe seu próprio checkout e índice; o histórico continua compartilhado.', '.worktree-intro .interaction-hint': 'Selecione um nó para inspecionar checkout, responsável e próxima ação.', '.tree-toolbar > span:first-child': 'topologia do repositório', '.tree-live': ' 4 checkouts', '.tree-node.root span': 'RAIZ', '.tree-node.ui span': 'AGENTE DE UI', '.tree-node.tests span': 'AGENTE DE TESTES', '.tree-node.docs span': 'AGENTE DE DOCS', '.tree-node.root small': '● limpo', '.tree-node.ui small': '3 arquivos · trabalhando', '.tree-node.tests small': '8 verificações · pronto', '.tree-node.docs small': '2 páginas · revisão', '.routing .eyebrow': 'Roteamento de modelos', '.routing h2': 'Não pague por
raciocínio onde precisa
de ritmo.', '.routing .interaction-hint': 'Escolha um trabalho para entender por que o perfil do modelo muda.', '.route-table .head span:nth-child(1)': 'Trabalho', '.route-table .head span:nth-child(2)': 'Perfil', '.route-table .head span:nth-child(3)': 'Formato do prompt', '.route-table [data-route="plan"] strong': 'Planejar', '.route-table [data-route="build"] strong': 'Construir', '.route-table [data-route="explore"] strong': 'Explorar', '.route-table [data-route="review"] strong': 'Revisar', '.skills .eyebrow': 'Skills', '.skills h2': 'Escreva do jeito certo
uma vez.', '.skills > div:first-child > p': 'Uma skill é um procedimento reutilizável. Ela pode carregar instruções, referências, scripts e assets. Não é memória mágica e não substitui critérios de aceitação.', + '.skill-principles span:nth-child(1)': '01 / defina o gatilho', '.skill-principles span:nth-child(2)': '02 / carregue detalhes sob demanda', '.skill-principles span:nth-child(3)': '03 / devolva evidências', '.skill-package > span': 'PACOTE DE SKILL', '.rule span': 'O PAPEL HUMANO', '.rule strong': 'O agente pode ser autônomo na execução. Intenção, limites e evidências continuam sendo seus.', '.callout span': 'COMECE AQUI', '.callout strong': 'Comece com um agente e uma skill. Adicione paralelismo apenas quando as tarefas forem realmente independentes.', '.sources .section-label span:nth-child(1)': 'Continue aprendendo', '.sources .section-label span:nth-child(2)': '12 novas leituras + documentação primária', '.sources p': 'Aprofunde com documentação oficial, casos de produção, Medium e fluxos de praticantes. Referências primárias → Trilha com 12 leituras →' } }; @@ -35,6 +61,47 @@ function render(id) { buttons.forEach((button) => { const active = button.dataset.phase === id; button.classList.toggle('active', active); button.setAttribute('aria-selected', String(active)); }); } +function selectButtons(selector, activeValue, key) { + document.querySelectorAll(selector).forEach((button) => { + const active = button.dataset[key] === activeValue; + button.classList.toggle('active', active); + button.setAttribute(button.hasAttribute('aria-selected') ? 'aria-selected' : 'aria-pressed', String(active)); + }); +} + +function renderWorker(id) { + const item = interactiveCopy.workers[id][currentLanguage]; + document.querySelector('#worker-detail').innerHTML = `${item[0]}${item[1]}${item[2]}`; + selectButtons('[data-worker]', id, 'worker'); +} + +function renderTree(id) { + const item = interactiveCopy.trees[id]; + const language = currentLanguage; + document.querySelector('#tree-detail').innerHTML = `
${language === 'pt' ? 'RESPONSÁVEL' : 'OWNER'}${item.owner[language]}
CHECKOUT${item.path}

${item.note[language]}

${item.command}`; + selectButtons('[data-tree]', id, 'tree'); +} + +function renderRoute(id) { + const item = interactiveCopy.routes[id]; + const language = currentLanguage; + document.querySelector('#route-detail').innerHTML = `
${language === 'pt' ? 'CARGA DE RACIOCÍNIO' : 'REASONING LOAD'} · ${item.score}${item.label[language]}

${item.why[language]}

`; + selectButtons('[data-route]', id, 'route'); +} + +function renderSkillFile(id) { + const item = interactiveCopy.skillFiles[id]; + document.querySelector('#skill-detail').innerHTML = `${item.icon}
${item.title}

${item[currentLanguage]}

${currentLanguage === 'pt' ? 'clique em outro arquivo para explorar' : 'select another file to explore'}
`; + selectButtons('[data-skill-file]', id, 'skillFile'); +} + +function renderInteractive() { + renderWorker(document.querySelector('[data-worker].active')?.dataset.worker || 'ui'); + renderTree(document.querySelector('[data-tree].active')?.dataset.tree || 'main'); + renderRoute(document.querySelector('[data-route].active')?.dataset.route || 'plan'); + renderSkillFile(document.querySelector('[data-skill-file].active')?.dataset.skillFile || 'skill'); +} + function applyLanguage(language) { currentLanguage = language === 'pt' ? 'pt' : 'en'; document.documentElement.lang = currentLanguage === 'pt' ? 'pt-BR' : 'en'; @@ -42,11 +109,16 @@ function applyLanguage(language) { else originals.forEach((values, selector) => document.querySelectorAll(selector).forEach((node, index) => { node.innerHTML = values[index]; })); document.querySelectorAll('[data-lang]').forEach((button) => { const active = button.dataset.lang === currentLanguage; button.classList.toggle('active', active); button.setAttribute('aria-pressed', String(active)); }); render(document.querySelector('[data-phase].active')?.dataset.phase || 'plan'); + renderInteractive(); try { localStorage.setItem('ai-for-dummies-language', currentLanguage); } catch (error) { /* previews may disable storage */ } } buttons.forEach((button) => button.addEventListener('click', () => render(button.dataset.phase))); document.querySelectorAll('[data-lang]').forEach((button) => button.addEventListener('click', () => applyLanguage(button.dataset.lang))); +document.querySelectorAll('[data-worker]').forEach((button) => button.addEventListener('click', () => renderWorker(button.dataset.worker))); +document.querySelectorAll('[data-tree]').forEach((button) => button.addEventListener('click', () => renderTree(button.dataset.tree))); +document.querySelectorAll('[data-route]').forEach((button) => button.addEventListener('click', () => renderRoute(button.dataset.route))); +document.querySelectorAll('[data-skill-file]').forEach((button) => button.addEventListener('click', () => renderSkillFile(button.dataset.skillFile))); window.addEventListener('scroll', () => { const height = document.documentElement.scrollHeight - window.innerHeight; document.querySelector('.reading-progress span').style.width = `${height > 0 ? (window.scrollY / height) * 100 : 0}%`; }, { passive: true }); let savedLanguage = 'en'; diff --git a/docs/references/README.md b/docs/references/README.md index 1678220..d5e0a2c 100644 --- a/docs/references/README.md +++ b/docs/references/README.md @@ -20,6 +20,10 @@ articles are context, not authority. ## Research and articles +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 diff --git a/docs/references/additional-reading.md b/docs/references/additional-reading.md new file mode 100644 index 0000000..1baaba1 --- /dev/null +++ b/docs/references/additional-reading.md @@ -0,0 +1,88 @@ +# 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. + +## Git worktrees and isolated coding sessions + +### 1. [Git — `git-worktree` Documentation](https://git-scm.com/docs/git-worktree.html) + +- **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. + +### 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. + +### 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. + +### 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. + +## Subagents and orchestration + +### 5. [Create custom subagents](https://code.claude.com/docs/en/sub-agents) + +- **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. + +### 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. + +### 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. + +### 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. + +### 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. + +## Model routing and reusable skills + +### 10. [Optimizing for cost and intelligence](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence) + +- **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. + +### 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. + +### 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. + +## Suggested teaching order + +1. Learn the Git primitive with resources 1–2. +2. Compare real worktree-per-agent practices with resources 3–4. +3. Design bounded workers and orchestration with resources 5–9. +4. Add deliberate model routing and reusable skills with resources 10–12. diff --git a/index.html b/index.html index d3b67ca..1f92de1 100644 --- a/index.html +++ b/index.html @@ -15,14 +15,14 @@

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.

01strong model
for ambiguity
03bounded workers
in parallel
∞iterations
with evidence

Read this as a route map, not a prompt recipe.

RULE ZEROStrong model for ambiguity.
Light model for bounded work.
-
A small fleetcoordination before parallelism
ORCHESTRATOR

Decides what
needs to happen.

Opus / reasoning
→
UIComponent and visual statesagent/ui
TESTAcceptance casesagent/tests
DOCSGuide and examplesagent/docs

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

+
A small fleetcoordination before parallelism
ORCHESTRATOR

Decides what
needs to happen.

Opus / reasoning
→

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 mattersone vague task / three predictable failures
01Context soup

Every worker reads everything. Nobody knows which facts are load-bearing.

02Branch collision

Two agents touch the same checkout. The fastest path becomes conflict resolution.

03Confident 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.

What crosses contextsbrief → diff → evidence
PackageContainsWhy it matters
Briefgoal, files, boundariesstops the worker inventing the problem
Worktreebranch and isolated checkoutparallel edits do not collide
Checkstests, build, criteriaturns “looks good” into evidence
Diffsmall, reviewable changeintegration 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.

git worktree add ../task-ui -b agent/ui · git worktree add ../task-tests -b agent/tests · git worktree list
REPOSITORYmainshared history
UIagent/uiisolated checkout
TESTagent/testsisolated checkout
DOCSagent/docsisolated checkout
-

Model routing

Do not pay for
reasoning where
you need rhythm.

WorkProfilePrompt shape
Planstrong / broadWhat changes? What can break?
Buildfast / focusedImplement this slice. Run these checks.
Exploreread-only / lightFind where this contract is used.
ReviewindependentDoes the diff satisfy the brief?
-

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 clearly02 / load detail on demand03 / return evidence
SKILL PACKAGE
SKILL.mdprocedure 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
+

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
+

Model routing

Do not pay for
reasoning where
you need rhythm.

Choose a job to see why the model profile changes.

WorkProfilePrompt shape
+

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 clearly02 / load detail on demand03 / return evidence
SKILL PACKAGE
name: review-ui · check focus, mobile, reduced motion · run verification · return evidence
-
Keep learningsources bundled locally

Based on Claude Code, Codex, Git, and agent-workflow research. Open the reference bundle →

+
Keep learning12 new readings + primary docs

Go deeper with official documentation, production case studies, Medium, and practitioner workflows. Primary references → 12-part reading path →

diff --git a/responsive.css b/responsive.css index 87fb7a9..e31dacd 100644 --- a/responsive.css +++ b/responsive.css @@ -5,3 +5,38 @@ .lang-switch button:focus-visible{outline:2px solid var(--accent);outline-offset:4px} @media(max-width:800px){.topbar-tools{margin-left:auto}} @media(max-width:600px){.topbar-tools .edition{display:none}} + +/* Interactive operations map */ +.interaction-hint{margin-top:24px!important;padding-left:18px;border-left:3px solid var(--gold);font:500 11px/1.6 'DM Mono',monospace!important;color:var(--muted)!important} +button{font-family:inherit} +.worker-card{display:grid;align-content:space-between;gap:20px;min-height:180px;padding:22px;border:0;color:var(--paper);background:var(--ink);text-align:left;cursor:pointer;transition:background .2s ease,transform .2s ease} +.worker-card span{color:#9eabb4;font:500 10px 'DM Mono',monospace;letter-spacing:.1em} +.worker-card strong{font-size:16px;line-height:1.2}.worker-card code{color:var(--gold);font:11px 'DM Mono',monospace} +.worker-card:hover,.worker-card.active{background:#244760}.worker-card.active{box-shadow:inset 0 -4px 0 var(--gold)}.worker-card:active{transform:translateY(2px)} +.worker-detail{display:grid;grid-template-columns:.55fr 1.1fr 1.2fr;gap:1px;margin-top:1px;background:var(--line)} +.worker-detail>*{margin:0;padding:16px 20px;background:#edf0f1}.worker-detail span,.worker-detail small{font:500 10px/1.5 'DM Mono',monospace;letter-spacing:.06em;text-transform:uppercase}.worker-detail span{color:var(--accent)}.worker-detail strong{font-size:13px}.worker-detail small{color:var(--muted);text-transform:none} + +.tree-lab{min-width:0;border:1px solid #41596b;background:#0b1b27;box-shadow:18px 18px 0 #081621} +.tree-toolbar{display:flex;justify-content:space-between;padding:14px 18px;border-bottom:1px solid #41596b;color:#9eabb4;font:500 9px 'DM Mono',monospace;letter-spacing:.1em;text-transform:uppercase} +.tree-live{display:flex;align-items:center;gap:8px}.tree-live i{display:block;width:7px;height:7px;border-radius:50%;background:#80c69a;box-shadow:0 0 0 4px #80c69a22} +.tree-stage{position:relative;height:330px;overflow:hidden;background-image:linear-gradient(#ffffff06 1px,transparent 1px),linear-gradient(90deg,#ffffff06 1px,transparent 1px);background-size:24px 24px} +.tree-stage svg{position:absolute;inset:0;width:100%;height:100%;overflow:visible}.tree-edge{fill:none;stroke:#527f9f;stroke-width:2;stroke-dasharray:5 5;vector-effect:non-scaling-stroke}.tree-edge.trunk{stroke:var(--gold);stroke-dasharray:none;stroke-width:3} +.tree-node{position:absolute;z-index:2;display:grid;gap:6px;width:164px;padding:13px 15px;border:1px solid #527085;color:var(--paper);background:#112a3b;text-align:left;cursor:pointer;transition:border-color .2s ease,background .2s ease,transform .2s ease,box-shadow .2s ease} +.tree-node span,.tree-node small{font:500 8px 'DM Mono',monospace;letter-spacing:.08em}.tree-node span{color:#8ca1af}.tree-node strong{font:600 12px 'DM Mono',monospace}.tree-node small{color:#a9b6be} +.tree-node.root{top:25px;left:50%;transform:translateX(-50%);border-color:var(--gold)}.tree-node.branch{top:220px}.tree-node.ui{left:3%}.tree-node.tests{left:50%;transform:translateX(-50%)}.tree-node.docs{right:3%} +.tree-node:hover,.tree-node.active{border-color:var(--gold);background:#1c425a;box-shadow:0 0 0 4px #efc76b18}.tree-node.root:hover,.tree-node.root.active{transform:translateX(-50%) translateY(-3px)}.tree-node.tests:hover,.tree-node.tests.active{transform:translateX(-50%) translateY(-3px)}.tree-node.ui:hover,.tree-node.ui.active,.tree-node.docs:hover,.tree-node.docs.active{transform:translateY(-3px)} +.tree-detail{display:grid;grid-template-columns:.7fr 1fr 1.6fr;gap:1px;border-top:1px solid #41596b;background:#41596b}.tree-detail>div,.tree-detail>p,.tree-detail>code{margin:0;padding:18px;background:#102536}.tree-detail div{display:grid;gap:8px}.tree-detail span{color:var(--accent);font:500 8px 'DM Mono',monospace;letter-spacing:.1em}.tree-detail strong{color:var(--paper);font:500 11px 'DM Mono',monospace}.tree-detail p{color:#aebbc3;font-size:11px;line-height:1.55}.tree-detail code{grid-column:1/-1;color:var(--gold);font:11px 'DM Mono',monospace} + +.route-console{display:grid;gap:14px}.route-table button{display:grid;grid-template-columns:.8fr .9fr 1.4fr;width:100%;padding:0;border:0;color:inherit;background:transparent;text-align:left;cursor:pointer}.route-table button>*{padding:15px;border-right:1px solid var(--line);border-bottom:1px solid var(--line)}.route-table button:hover,.route-table button.active{background:#e8ecee}.route-table button.active strong{box-shadow:inset 4px 0 0 var(--gold)} +.route-detail{display:grid;grid-template-columns:100px 1fr;gap:22px;align-items:center;padding:22px;color:var(--paper);background:var(--deep)}.route-meter{display:grid;align-items:end;width:76px;height:76px;padding:7px;border:1px solid #496274}.route-meter span{display:block;width:100%;height:var(--score);background:var(--gold);transition:height .35s ease}.route-detail>div:last-child{display:grid;gap:7px}.route-detail small{color:var(--gold);font:500 8px 'DM Mono',monospace;letter-spacing:.08em}.route-detail strong{font-size:17px}.route-detail p{margin:0;color:#b5c0c7;font-size:12px;line-height:1.5} + +.skill-explorer{display:grid;grid-template-columns:.9fr 1.1fr;min-height:290px;background:var(--blue)}.skill-package button{display:grid;grid-template-columns:1fr 1fr;gap:15px;padding:17px 20px;border:0;border-bottom:1px solid #ffffff40;color:var(--paper);background:transparent;text-align:left;cursor:pointer}.skill-package button:hover,.skill-package button.active{background:#315f80}.skill-package button.active{box-shadow:inset 4px 0 0 var(--gold)}.skill-package button code{font:12px 'DM Mono',monospace}.skill-package button small{opacity:.7} +.skill-detail{display:grid;grid-template-columns:auto 1fr;gap:18px;align-content:center;padding:28px;color:var(--paper);background:#244760}.skill-detail>span{color:var(--gold);font:42px Georgia,serif}.skill-detail>div{display:grid;gap:13px}.skill-detail strong{font:600 15px 'DM Mono',monospace}.skill-detail p{margin:0;color:#c4cdd3;font-size:12px;line-height:1.65}.skill-detail small{color:var(--gold);font:500 8px 'DM Mono',monospace;letter-spacing:.06em;text-transform:uppercase} + +.worker-card:focus-visible,.tree-node:focus-visible,.route-table button:focus-visible,.skill-package button:focus-visible{outline:3px solid var(--gold);outline-offset:-3px} +@media(min-width:1600px){.tree-stage{height:390px}.tree-stage svg{height:330px;top:30px}.tree-node.root{top:45px}.tree-node.branch{top:255px}.tree-node{width:190px;padding:17px}.tree-detail{grid-template-columns:.6fr .8fr 1.8fr}.worker-card{min-height:210px;padding:28px}} +@media(min-width:2200px){main{max-width:2880px;padding-inline:clamp(140px,7vw,280px)}.hero{max-width:1420px}.hero h1{font-size:clamp(150px,7vw,220px)}.tree-stage{height:460px}.tree-stage svg{height:380px;top:45px}.tree-node.root{top:65px}.tree-node.branch{top:305px}.tree-node{width:240px;padding:22px}.tree-node strong{font-size:15px}.tree-detail>*{font-size:14px!important}.fleet,.failure-map{margin-bottom:170px}.workflow,.routing,.skills{margin-bottom:180px}} +@media(max-width:1050px){.tree-node{width:145px}.tree-detail{grid-template-columns:1fr 1fr}.tree-detail p{grid-column:1/-1}.skill-explorer{grid-template-columns:1fr}} +@media(max-width:800px){.worker-detail{grid-template-columns:1fr}.worktrees{display:block}.worktree-intro{margin-bottom:40px}.tree-lab{box-shadow:9px 9px 0 #081621}.route-table button{min-width:620px}.skill-explorer{grid-template-columns:1fr 1fr}} +@media(max-width:600px){.tree-stage{height:auto;min-height:560px;padding:24px}.tree-stage svg{display:none}.tree-node,.tree-node.root,.tree-node.branch,.tree-node.ui,.tree-node.tests,.tree-node.docs{position:relative;top:auto;right:auto;left:auto;width:100%;margin:0 0 34px;transform:none}.tree-node:not(:last-child)::after{content:'↓';position:absolute;left:50%;bottom:-28px;color:var(--gold)}.tree-node:hover,.tree-node.active,.tree-node.root:hover,.tree-node.root.active,.tree-node.tests:hover,.tree-node.tests.active{transform:translateY(-2px)}.tree-detail{grid-template-columns:1fr}.tree-detail p,.tree-detail code{grid-column:auto}.skill-explorer{grid-template-columns:1fr}.route-detail{grid-template-columns:70px 1fr}.route-meter{width:56px;height:70px}} +@media(prefers-reduced-motion:reduce){.worker-card,.tree-node,.route-meter span{transition:none}.reading-progress span{transition:none}} diff --git a/scripts/verify.mjs b/scripts/verify.mjs index 0068b62..0f38492 100644 --- a/scripts/verify.mjs +++ b/scripts/verify.mjs @@ -3,10 +3,13 @@ const read = (path) => readFileSync(new URL(`../${path}`, import.meta.url), 'utf const html = read('index.html'); const js = read('app.js'); const refs = read('docs/references/README.md'); +const additional = read('docs/references/additional-reading.md'); 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"','docs/references/','role="tablist"','