Merge branch 'refactor/task-05b-guide-interactive-data'

2026-09-05 19:25:50 +00:00
parent 4b758c765d 24d0af4840
commit 595006bcba
28 changed files with 507 additions and 0 deletions
@@ -0,0 +1,17 @@
+{
+  "id": "caveman",
+  "number": "02",
+  "kind": { "en": "COMMUNICATION STYLE", "pt": "ESTILO DE COMUNICAÇÃO" },
+  "title": "caveman",
+  "rule": { "en": "Signal first. Drop filler.", "pt": "Sinal primeiro. Corte o excesso." },
+  "use": {
+    "en": "Use for routine status, handoffs, and technical summaries where speed matters. Short fragments make actions and evidence easy to scan.",
+    "pt": "Use em status, handoffs e resumos técnicos rotineiros onde velocidade importa. Fragmentos curtos facilitam localizar ações e evidências."
+  },
+  "example": { "en": "Built. Tests pass. Published.", "pt": "Feito. Testes passaram. Publicado." },
+  "caution": {
+    "en": "Drop the style for security warnings, irreversible actions, and sequences where terse wording can be misread.",
+    "pt": "Abandone o estilo em alertas de segurança, ações irreversíveis e sequências onde concisão pode causar erro."
+  },
+  "source": "https://github.com/JuliusBrussee/caveman/blob/3b74643f4d910f496babd4e634b1ba7168816f14/skills/caveman/SKILL.md"
+}
@@ -0,0 +1,23 @@
+{
+  "id": "debug",
+  "number": "05",
+  "kind": { "en": "DIAGNOSTIC LOOP", "pt": "CICLO DE DIAGNÓSTICO" },
+  "title": "diagnosing-bugs",
+  "rule": {
+    "en": "No red-capable loop, no theory.",
+    "pt": "Sem ciclo capaz de falhar, sem teoria."
+  },
+  "use": {
+    "en": "Use for hard bugs, flakes, and regressions. First build a fast deterministic reproduction, then minimize, rank hypotheses, instrument, and fix the root cause.",
+    "pt": "Use para bugs difíceis, flakes e regressões. Primeiro crie reprodução rápida e determinística; depois minimize, ranqueie hipóteses, instrumente e corrija a causa raiz."
+  },
+  "example": {
+    "en": "One command reproduces the exact symptom before any fix.",
+    "pt": "Um comando reproduz o sintoma exato antes de qualquer correção."
+  },
+  "caution": {
+    "en": "Do not jump from error message straight to a patch.",
+    "pt": "Não pule da mensagem de erro direto para um patch."
+  },
+  "source": "https://github.com/mattpocock/skills/blob/6654f6b60cd9d5be8b54c6fafe44346dabeb3b76/skills/engineering/diagnosing-bugs/SKILL.md"
+}
@@ -0,0 +1,23 @@
+{
+  "id": "ponytail",
+  "number": "01",
+  "kind": { "en": "SIMPLIFICATION INSTINCT", "pt": "INSTINTO DE SIMPLIFICAÇÃO" },
+  "title": "ponytail-lite",
+  "rule": {
+    "en": "Stop at the first rung that holds.",
+    "pt": "Pare no primeiro degrau que sustenta."
+  },
+  "use": {
+    "en": "Use when a request invites frameworks, dependencies, abstractions, or speculative scaffolding. It checks reuse, standard library, and native platform features before adding code.",
+    "pt": "Use quando um pedido convida frameworks, dependências, abstrações ou scaffolding especulativo. Verifica reúso, biblioteca padrão e recursos nativos antes de adicionar código."
+  },
+  "example": {
+    "en": "Date picker? Start with &lt;input type=\"date\"&gt;.",
+    "pt": "Seletor de data? Comece com &lt;input type=\"date\"&gt;."
+  },
+  "caution": {
+    "en": "Never simplify away security, accessibility, validation, or real edge cases.",
+    "pt": "Nunca simplifique segurança, acessibilidade, validação ou casos extremos reais."
+  },
+  "source": "https://github.com/ilindaniel/ponytail-lite/blob/e7b42dc2d384a702240dea4d52a7bf5530b821b6/AGENTS.md"
+}
@@ -0,0 +1,20 @@
+{
+  "id": "research",
+  "number": "04",
+  "kind": { "en": "SOURCE DISCIPLINE", "pt": "DISCIPLINA DE FONTES" },
+  "title": "research",
+  "rule": { "en": "Trace claims to owners.", "pt": "Leve afirmações até suas fontes." },
+  "use": {
+    "en": "Use when APIs, standards, architecture facts, or current behavior must be verified. Capture findings in a cited note, prioritizing primary sources.",
+    "pt": "Use quando APIs, padrões, fatos de arquitetura ou comportamento atual precisam ser verificados. Registre achados citados, priorizando fontes primárias."
+  },
+  "example": {
+    "en": "Git behavior → git-scm.com docs, not a remembered blog summary.",
+    "pt": "Comportamento do Git → documentação git-scm.com, não memória de um blog."
+  },
+  "caution": {
+    "en": "Practitioner articles add context; they do not override official behavior.",
+    "pt": "Artigos de praticantes dão contexto; não substituem comportamento oficial."
+  },
+  "source": "https://github.com/mattpocock/skills/blob/6654f6b60cd9d5be8b54c6fafe44346dabeb3b76/skills/engineering/research/SKILL.md"
+}
@@ -0,0 +1,23 @@
+{
+  "id": "review",
+  "number": "06",
+  "kind": { "en": "INDEPENDENT REVIEW", "pt": "REVISÃO INDEPENDENTE" },
+  "title": "code-review",
+  "rule": {
+    "en": "Check standards and intent separately.",
+    "pt": "Verifique padrões e intenção separadamente."
+  },
+  "use": {
+    "en": "Use on a branch or PR. One axis checks repository standards; another checks whether the change actually satisfies its originating specification.",
+    "pt": "Use em branch ou PR. Um eixo verifica padrões do repositório; outro verifica se a mudança realmente satisfaz a especificação original."
+  },
+  "example": {
+    "en": "Clean code can still solve the wrong problem.",
+    "pt": "Código limpo ainda pode resolver o problema errado."
+  },
+  "caution": {
+    "en": "Pin the comparison point and source specification before reviewing.",
+    "pt": "Fixe o ponto de comparação e a especificação antes de revisar."
+  },
+  "source": "https://github.com/mattpocock/skills/blob/6654f6b60cd9d5be8b54c6fafe44346dabeb3b76/skills/engineering/code-review/SKILL.md"
+}
@@ -0,0 +1,23 @@
+{
+  "id": "tokens",
+  "number": "07",
+  "kind": { "en": "CONTEXT ECONOMY", "pt": "ECONOMIA DE CONTEXTO" },
+  "title": "token-saver",
+  "rule": {
+    "en": "Keep signal. Strip command noise.",
+    "pt": "Mantenha sinal. Corte ruído de comandos."
+  },
+  "use": {
+    "en": "Use around verbose tests, builds, Git output, and logs. Filtering preserves context for reasoning while retaining full failure output for recovery.",
+    "pt": "Use em testes, builds, saídas Git e logs verbosos. Filtragem preserva contexto para raciocínio e mantém falhas completas para recuperação."
+  },
+  "example": {
+    "en": "200 passing-test lines → one result; failures keep their trace.",
+    "pt": "200 linhas de testes passando → um resultado; falhas mantêm o trace."
+  },
+  "caution": {
+    "en": "Read raw output when exact wording or full diffs matter.",
+    "pt": "Leia saída bruta quando texto exato ou diffs completos importarem."
+  },
+  "source": "https://github.com/aetox-skills/token-saver/blob/8f21188bb043fad411f47e2e57f0365a83c13da7/SKILL.md"
+}
@@ -0,0 +1,23 @@
+{
+  "id": "unlazy",
+  "number": "03",
+  "kind": { "en": "COMPLETION DISCIPLINE", "pt": "DISCIPLINA DE CONCLUSÃO" },
+  "title": "unlazy",
+  "rule": {
+    "en": "Define observable gates. Finish against evidence.",
+    "pt": "Defina gates observáveis. Termine com evidências."
+  },
+  "use": {
+    "en": "Use for substantial autonomous builds, audits, and parallel work where quiet omissions are expensive. It turns “done” into runnable acceptance checks.",
+    "pt": "Use em builds autônomos grandes, auditorias e trabalho paralelo onde omissões custam caro. Transforma “pronto” em verificações executáveis."
+  },
+  "example": {
+    "en": "Gate: language toggle persists. Check: browser reload. Expect: pt-BR.",
+    "pt": "Gate: idioma persiste. Check: recarregar navegador. Esperado: pt-BR."
+  },
+  "caution": {
+    "en": "Too heavy for trivial edits or factual answers.",
+    "pt": "Pesado demais para edições triviais ou respostas factuais."
+  },
+  "source": "https://github.com/Leonxlnx/unlazy/blob/473d4b80421c36d733042434cd4b938f81a19ef1/SKILL.md"
+}
@@ -153,6 +153,103 @@ const chapters = defineCollection({
  }),
 });

+// Workers from `interactiveCopy.workers` in app.js: the three sub-agent
+// cards on /full-guide/. Each entry holds a 3-element array per locale
+// (`[label, detail, result]`), not a localized object — the renderer
+// unwraps it directly: `worker[language()][0..2]`.
+const workers = defineCollection({
+  type: 'data',
+  schema: z.object({
+    id: z.string(),
+    en: z.array(z.string()),
+    pt: z.array(z.string()),
+  }),
+});
+
+// Trees from `interactiveCopy.trees` in app.js: the four worktree nodes
+// (main / ui / tests / docs). `owner` and `note` are localized; `path`
+// and `command` are single shell strings (the git command shown to the
+// user). `status` is rendered by index.html, not the GuideSelector island,
+// but it ships in the data and the schema keeps it so nothing is dropped.
+const trees = defineCollection({
+  type: 'data',
+  schema: z.object({
+    id: z.string(),
+    status: z.string(),
+    owner: localized,
+    path: z.string(),
+    command: z.string(),
+    note: localized,
+  }),
+});
+
+// Routes from `interactiveCopy.routes` in app.js: plan / build / explore /
+// review. `score` is the numeric reasoning-load value (rendered into
+// `style="--score:N%"`), `label` and `why` are localized.
+const routes = defineCollection({
+  type: 'data',
+  schema: z.object({
+    id: z.string(),
+    score: z.number(),
+    label: localized,
+    why: localized,
+  }),
+});
+
+// Skill files from `interactiveCopy.skillFiles` in app.js: SKILL.md /
+// references/ / scripts/ / assets/. `icon` and `title` are unlocalized
+// labels; `en` and `pt` are separate top-level strings, not a localized
+// object — matching how `renderSkillFile` reads them.
+const skillFiles = defineCollection({
+  type: 'data',
+  schema: z.object({
+    id: z.string(),
+    icon: z.string(),
+    title: z.string(),
+    en: z.string(),
+    pt: z.string(),
+  }),
+});
+
+// Skill workflow from `interactiveCopy.skillWorkflow` in app.js: the five
+// steps of building a skill (observe / trigger / scaffold / write /
+// validate). `number` is unlocalized; `title` / `question` / `action` /
+// `output` / `proof` are all localized.
+const skillWorkflow = defineCollection({
+  type: 'data',
+  schema: z.object({
+    id: z.string(),
+    number: z.string(),
+    title: localized,
+    question: localized,
+    action: localized,
+    output: localized,
+    proof: localized,
+  }),
+});
+
+// Common skills from `interactiveCopy.commonSkills` in app.js: the seven
+// shared skill cards on /full-guide/. `number` and `title` are unlocalized;
+// `kind` / `rule` / `use` / `example` / `caution` are localized. `source`
+// is the GitHub URL — in app.js it is read from `skillSources[id]` at
+// render time; here it is embedded to match the GuideSelectorData
+// contract. If the URL changes, both this entry and the matching
+// `skillSources/<id>.json` must be updated.
+const commonSkills = defineCollection({
+  type: 'data',
+  schema: z.object({
+    id: z.string(),
+    number: z.string(),
+    kind: localized,
+    title: z.string(),
+    rule: localized,
+    use: localized,
+    example: localized,
+    caution: localized,
+    source: z.string().url(),
+  }),
+});
+
 // Review desk entries from skills-review/catalog.js +
 // skills-review/submitted-catalog.js: 24 in total. Each entry is a Markdown
 // file with frontmatter for the metadata and a body that holds the
@@ -189,5 +286,11 @@ export const collections = {
  handsOnPrompts,
  skillInstallPrompts,
  chapters,
+  workers,
+  trees,
+  routes,
+  skillFiles,
+  skillWorkflow,
+  commonSkills,
  reviews,
 };
@@ -0,0 +1,9 @@
+{
+  "id": "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."
+  }
+}
@@ -0,0 +1,9 @@
+{
+  "id": "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."
+  }
+}
@@ -0,0 +1,9 @@
+{
+  "id": "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."
+  }
+}
@@ -0,0 +1,9 @@
+{
+  "id": "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."
+  }
+}
@@ -0,0 +1,7 @@
+{
+  "id": "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."
+}
@@ -0,0 +1,7 @@
+{
+  "id": "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."
+}
@@ -0,0 +1,7 @@
+{
+  "id": "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."
+}
@@ -0,0 +1,7 @@
+{
+  "id": "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."
+}
@@ -0,0 +1,21 @@
+{
+  "id": "observe",
+  "number": "01",
+  "title": { "en": "Start from repeated friction", "pt": "Comece pelo atrito repetido" },
+  "question": {
+    "en": "Which non-obvious decision keeps being rediscovered?",
+    "pt": "Qual decisão não óbvia continua sendo redescoberta?"
+  },
+  "action": {
+    "en": "Collect two or three realistic requests. Separate durable judgment from one project’s temporary details.",
+    "pt": "Colete dois ou três pedidos realistas. Separe julgamento durável dos detalhes temporários de um projeto."
+  },
+  "output": {
+    "en": "A narrow capability and concrete examples.",
+    "pt": "Uma capacidade estreita e exemplos concretos."
+  },
+  "proof": {
+    "en": "Without the skill, agents repeatedly make the same avoidable mistake.",
+    "pt": "Sem a skill, agentes repetem o mesmo erro evitável."
+  }
+}
@@ -0,0 +1,21 @@
+{
+  "id": "scaffold",
+  "number": "03",
+  "title": { "en": "Choose only useful anatomy", "pt": "Escolha apenas a anatomia útil" },
+  "question": {
+    "en": "What must be instructions, executable, consulted, or copied?",
+    "pt": "O que deve ser instrução, executável, consultado ou copiado?"
+  },
+  "action": {
+    "en": "Keep shared guidance in SKILL.md. Add scripts for repeated deterministic work, references for conditional facts, and assets for generated output.",
+    "pt": "Mantenha orientação comum em SKILL.md. Adicione scripts para trabalho determinístico, referências para fatos condicionais e assets para saída."
+  },
+  "output": {
+    "en": "Smallest folder structure that supports the workflow.",
+    "pt": "A menor estrutura de pastas que sustenta o fluxo."
+  },
+  "proof": {
+    "en": "Every file has a real caller; no placeholder directories.",
+    "pt": "Cada arquivo tem um consumidor real; nenhuma pasta placeholder."
+  }
+}
@@ -0,0 +1,21 @@
+{
+  "id": "trigger",
+  "number": "02",
+  "title": { "en": "Make discovery precise", "pt": "Torne a descoberta precisa" },
+  "question": {
+    "en": "When should this load—and when should it stay out?",
+    "pt": "Quando isto deve carregar — e quando deve ficar de fora?"
+  },
+  "action": {
+    "en": "Choose a short action-oriented name. Write a discriminating description that names the task and meaningful boundary.",
+    "pt": "Escolha um nome curto orientado à ação. Escreva uma descrição discriminante que nomeie a tarefa e seu limite."
+  },
+  "output": {
+    "en": "YAML name + description in SKILL.md.",
+    "pt": "Nome + descrição YAML em SKILL.md."
+  },
+  "proof": {
+    "en": "Relevant prompts select it; nearby unrelated prompts do not.",
+    "pt": "Prompts relevantes selecionam; prompts próximos mas não relacionados, não."
+  }
+}
@@ -0,0 +1,21 @@
+{
+  "id": "validate",
+  "number": "05",
+  "title": { "en": "Test behavior, then sharpen", "pt": "Teste comportamento, depois refine" },
+  "question": {
+    "en": "Did the skill improve a realistic outcome?",
+    "pt": "A skill melhorou um resultado realista?"
+  },
+  "action": {
+    "en": "Run structural validation, execute every new script, and forward-test realistic requests. Fix observed failures with the narrowest rule.",
+    "pt": "Execute validação estrutural, rode cada script novo e teste pedidos realistas. Corrija falhas observadas com a regra mais estreita."
+  },
+  "output": {
+    "en": "Validated package plus evidence from real use.",
+    "pt": "Pacote validado mais evidência de uso real."
+  },
+  "proof": {
+    "en": "quick_validate passes and behavior improves without unrelated side effects.",
+    "pt": "quick_validate passa e o comportamento melhora sem efeitos colaterais."
+  }
+}
@@ -0,0 +1,21 @@
+{
+  "id": "write",
+  "number": "04",
+  "title": { "en": "Write what changes decisions", "pt": "Escreva o que muda decisões" },
+  "question": {
+    "en": "What would a capable agent still get wrong?",
+    "pt": "O que um agente capaz ainda erraria?"
+  },
+  "action": {
+    "en": "State outcome, non-obvious constraints, routing, and stopping conditions. Remove generic advice, duplicate facts, and speculative rules.",
+    "pt": "Declare resultado, restrições não óbvias, roteamento e condições de parada. Remova conselhos genéricos, fatos duplicados e regras especulativas."
+  },
+  "output": {
+    "en": "Lean SKILL.md with progressive links.",
+    "pt": "SKILL.md enxuto com links progressivos."
+  },
+  "proof": {
+    "en": "Another agent can act correctly without loading irrelevant detail.",
+    "pt": "Outro agente consegue agir corretamente sem carregar detalhes irrelevantes."
+  }
+}
@@ -0,0 +1,11 @@
+{
+  "id": "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."
+  }
+}
@@ -0,0 +1,11 @@
+{
+  "id": "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."
+  }
+}
@@ -0,0 +1,11 @@
+{
+  "id": "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."
+  }
+}
@@ -0,0 +1,11 @@
+{
+  "id": "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."
+  }
+}
@@ -0,0 +1,13 @@
+{
+  "id": "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"
+  ]
+}
@@ -0,0 +1,13 @@
+{
+  "id": "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"
+  ]
+}
@@ -0,0 +1,13 @@
+{
+  "id": "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"
+  ]
+}