agent-engineering-skills 1.0.0

package/docs/agent-integration.md

@@ -0,0 +1,200 @@
+# Agent Integration
+
+Como um agente de IA integra este repositório: a ordem de operação, a composição de
+skills, os workflows, e os anti-padrões. Este documento é a ponte entre as peças
+(`AGENTS.md`, `skills/`, `references/`, `templates/`) e a execução real.
+
+---
+
+## 1. Visão geral
+
+```text
+                    AGENT
+                      │
+                      ↓
+                SKILL ROUTER        ← skills/meta/skill-router/
+                      │
+          ┌───────────┼───────────┐
+          ↓           ↓           ↓
+       AUDIT       PRODUCT     FRONTEND      ← skills/audit, security, reliability,
+          │           │           │             product, frontend
+          └───────────┼───────────┘
+                      ↓
+               RESEARCH ROUTER     ← skills/meta/research-router/
+                      │
+        ┌─────────────┼─────────────┐
+        ↓             ↓             ↓
+      GitHub       Products      References    ← skills/research/* + references/*.yaml
+        │             │             │
+        └─────────────┼─────────────┘
+                      ↓
+                  SYNTHESIS         ← formato de síntese (AGENTS.md § 5)
+                      │
+                      ↓
+                 IMPLEMENT
+                      │
+                      ↓
+              ADVERSARIAL TEST      ← skills/audit/adversarial-review
+                      │
+                      ↓
+                   VERIFY
+                      │
+                      ↓
+                   REPORT           ← templates/*
+```
+
+O agente não "executa todas as skills". Ele **rota** — escolhe o subconjunto relevante
+pelo `skill-router`, pesquisa pelo `research-router`, implementa, ataca a própria
+implementação, verifica, e reporta.
+
+---
+
+## 2. Ordem de operação
+
+### 2.1 Workflow completo (auditoria / feature não-trivial)
+
+```text
+REQUEST → UNDERSTAND → CLASSIFY → SKILL ROUTER → RESEARCH ROUTER → RESEARCH →
+ANALYZE → IMPLEMENT → ADVERSARIAL TEST → VERIFY → REPORT
+```
+
+| Etapa | O que o agente faz | Onde |
+|---|---|---|
+| REQUEST | Recebe o pedido | — |
+| UNDERSTAND | Reformula o pedido: sistema, fluxo, mudança, risco | — |
+| CLASSIFY | Categoria dominante (audit/security/reliability/product/frontend/research) + sinais (valor transferível, estado compartilhado, permissões) | — |
+| SKILL ROUTER | Seleciona o conjunto ordenado de skills | `skills/meta/skill-router/` |
+| RESEARCH ROUTER | Decide onde pesquisar | `skills/meta/research-router/` + `references/` |
+| RESEARCH | Coleta + sintetiza (nunca só links) | skills de research + `AGENTS.md` § 5 |
+| ANALYZE | Aplica as skills selecionadas ao alvo | skills selecionadas |
+| IMPLEMENT | Faz a mudança (se aplicável) | — |
+| ADVERSARIAL TEST | Ataca a própria implementação | `adversarial-review` + skills relevantes |
+| VERIFY | Confirma evidência; sobe/desce confiança | escala de evidência `AGENTS.md` § 2 |
+| REPORT | Produz o relatório | `templates/audit-report.md` etc. |
+
+### 2.2 Pesquisa antes de implementar (regra §13)
+
+```text
+UNDERSTAND → CLASSIFY → RESEARCH → COMPARE → DECIDE → IMPLEMENT
+```
+
+Não:
+
+```text
+UNDERSTAND → IMPLEMENT
+```
+
+**Mas proporcional:** um botão simples não precisa de pesquisa; uma arquitetura nova
+provavelmente precisa; concorrência em pagamentos certamente. Critério:
+
+```text
+uncertainty + impact + irreversibility
+```
+
+quanto maior, maior o nível de pesquisa (`none` / `proportional` / `full`).
+
+---
+
+## 3. Como o agente escolhe skills
+
+1. Leia o frontmatter de cada skill candidata (`triggers`, `category`, `priority`).
+2. Cruze com a tabela de composição do `skill-router` (§14/§22).
+3. Ordena: hipóteses (adversarial-review) → confirmação (race, idempotência, etc.) →
+   domínio específico (frontend, product).
+4. **Justifique** a seleção e o que foi descartado (evita overengineering e mostra
+   cobertura).
+
+Exemplo (do `skill-router`):
+
+```text
+"Adicionar reações que dão XP"
+        ↓
+gamification-audit
+business-logic-audit
+idempotency-audit
+race-condition-hunter
+api-abuse-audit
+user-flow-audit
+```
+
+---
+
+## 4. Como o agente pesquisa
+
+1. Determine o tipo de problema (animation/ux/architecture/security/...).
+2. Consulte `references/*.yaml` do domínio (`use_when` × problema).
+3. Respeite `type` (methodology/heuristic/inspiration/implementation/discovery) e
+   `authority` (established > vendor > community > curated).
+4. Despache para a research skill correta.
+5. **Sintetize** — nunca retorne lista de links. Formato: Reference / Relevant
+   Pattern / Why It Matters / Adaptation / Trade-offs / Recommendation.
+6. **Não copie** — extraia princípios, adapte, avalie trade-offs (`AGENTS.md` § 1).
+
+---
+
+## 5. Como o agente reporta
+
+- **Auditoria completa** → `templates/audit-report.md` (findings com Severity,
+  Confidence, Reprodução, Causa raiz, etc. + dedup entre skills).
+- **Bug individual** → `templates/bug-report.md`.
+- **Frontend/design** → `templates/design-review.md` (dimensões + checklist WCAG).
+- **Pesquisa** → `templates/research-report.md` (síntese obrigatória + fontes +
+  autoridade + confiança).
+
+Todo finding carrega um nível de confiança:
+
+```text
+CONFIRMED         reproduzido com evidência direta
+HIGH CONFIDENCE   forte indício técnico, sem reprodução
+POSSIBLE          plausível, exige investigação
+SPECULATIVE       hipótese sem evidência → seção "riscos", não bugs
+```
+
+---
+
+## 6. Deduplicação entre skills
+
+Múltiplas skills podem apontar o mesmo defeito (ex: race → idempotency; authorization
+→ input-trust). Regras:
+
+1. **Consolidar** — um finding único com a análise combinada (ex: "raça + falta de
+   idempotência na criação de pedido").
+2. **Atribuir a skill mais específica** — a que explica a causa raiz (ex:
+   `race-condition-hunter` explica o *mecanismo*; `idempotency-audit` explica o *efeito*).
+3. **Não duplicar** — se duas skills apontam o mesmo, cite ambas na seção de
+   deduplicação do relatório.
+
+---
+
+## 7. Anti-padrões
+
+| Anti-padrão | Correto |
+|---|---|
+| Executar todas as skills sempre | Rotear pelo `skill-router`, proporcional ao risco |
+| Pesquisar tudo sempre | Research proporcional (uncertainty + impact + irreversibility) |
+| Relatórios gigantes | Concisos, priorizados, acionáveis |
+| Consultar referências irrelevantes | Cruzar `use_when` × problema |
+| Transformar qualquer coisa estranha em bug | Aplicar a seção "False Positives" de cada skill |
+| Tratar inspiração como evidência | Fontes `inspiration`/`curated` só calibram gosto |
+| Copiar código/layout de referências | Extrair princípios, adaptar |
+| Reportar SPECULATIVE como bug | Listar como risco a verificar |
+| Inventar skill inexistente | Verificar `skills/`; marcar gap |
+
+---
+
+## 8. Referência rápida
+
+| Precisa de… | Onde |
+|---|---|
+| Regras globais + escala de evidência | `AGENTS.md` |
+| Seleção de skills | `skills/meta/skill-router/` |
+| Seleção de fontes | `skills/meta/research-router/` + `references/` |
+| Como escrever uma skill | `docs/skill-authoring.md` |
+| Como adicionar referência | `docs/reference-authoring.md` |
+| Princípios do projeto | `docs/philosophy.md` |
+| Relatório de auditoria | `templates/audit-report.md` |
+| Bug report | `templates/bug-report.md` |
+| Design review | `templates/design-review.md` |
+| Research report | `templates/research-report.md` |
+| Exemplos reais | `examples/` |
+| Validação do repositório | `python3 scripts/validate.py` |

package/docs/philosophy.md

@@ -0,0 +1,131 @@
+# Philosophy
+
+> **Don't just review the code. Attack the assumptions behind the system.`
+
+A filosofia deste repositório é que uma skill não é uma lista de comandos. É uma
+**estrutura de raciocínio** que ensina o agente a descobrir problemas que ele não sabia
+que deveria procurar.
+
+---
+
+## 1. Skills ensinam como pensar
+
+Uma skill fornece:
+
+* **modelo mental** — a lente através da qual enxergar o sistema;
+* **perguntas** — o que questionar quando algo parece normal demais;
+* **heurísticas** — atalhos de decisão baseados em padrões conhecidos;
+* **padrões de ataque** — sequências concretas de operações que expõem defeitos;
+* **processo de investigação** — a ordem em que investigar;
+* **critérios de evidência** — o que conta como confirmação;
+* **critérios de falso positivo** — quando um comportamento estranho é aceitável;
+* **formato de saída** — como reportar de forma acionável.
+
+Nenhuma skill deve depender de conhecimento implícito que não esteja documentado ou
+disponível através das referências.
+
+## 2. Referências ensinam onde olhar
+
+Sites, projetos, produtos e documentações externas não ficam espalhados pelas skills.
+Elas vivem em um catálogo centralizado em `references/`, classificadas por classe de
+conhecimento e nível de autoridade.
+
+```text
+skills/        como pensar
+knowledge/     o que considerar
+references/    onde pesquisar
+```
+
+Isto mantém as skills focadas em raciocínio e evita que se tornem um dump de URLs.
+
+## 3. Pesquisar antes de reinventar
+
+Para tarefas não triviais, o agente pergunta:
+
+> "Alguém já resolveu esse problema?"
+
+E pesquisa, em ordem de confiabilidade:
+
+1. código existente no projeto;
+2. documentação oficial;
+3. GitHub;
+4. produtos reais;
+5. design systems;
+6. sites especializados;
+7. artigos técnicos;
+8. galerias de inspiração.
+
+## 4. Referências não são especificações
+
+O agente extrai princípios, padrões, decisões, trade-offs, soluções e problemas
+conhecidos. Não copia cegamente código, layout, branding, identidade visual, conteúdo
+ou componentes proprietários.
+
+Inspiração, não cópia.
+
+## 5. Evidência > especulação
+
+Todo finding é classificado em um destes níveis:
+
+```text
+CONFIRMED         — reproduzido com evidência direta
+HIGH CONFIDENCE   — forte indício técnico, sem reprodução completa
+POSSIBLE          — plausível, exige mais investigação
+SPECULATIVE       — hipótese sem evidência; risco a verificar, não bug
+```
+
+Nunca transformar uma hipótese em bug confirmado. Ver `AGENTS.md` § 2.
+
+## 6. Evitar overengineering
+
+```text
+uncertainty  +  impact  +  irreversibility
+```
+
+quanto maiores, maior o nível de pesquisa. Pesquisa é proporcional à complexidade —
+não é um ritual aplicado a tudo.
+
+O sistema deve evitar: pesquisar tudo sempre, executar todas as skills, produzir
+relatórios gigantes, consultar referências irrelevantes, transformar qualquer
+comportamento estranho em bug, adicionar dependências desnecessárias.
+
+## 7. Visão final
+
+```text
+                    AGENT
+                      │
+                      ↓
+                SKILL ROUTER
+                      │
+          ┌───────────┼───────────┐
+          ↓           ↓           ↓
+       AUDIT       PRODUCT     FRONTEND
+          │           │           │
+          └───────────┼───────────┘
+                      ↓
+               RESEARCH ROUTER
+                      │
+        ┌─────────────┼─────────────┐
+        ↓             ↓             ↓
+      GitHub       Products      References
+        │             │             │
+        └─────────────┼─────────────┘
+                      ↓
+                  SYNTHESIS
+                      │
+                      ↓
+                 IMPLEMENT
+                      │
+                      ↓
+              ADVERSARIAL TEST
+                      │
+                      ↓
+                   VERIFY
+                      │
+                      ↓
+                   REPORT
+```
+
+O objetivo final não é criar um agente que **sabe mais**.
+É criar um agente que **sabe como descobrir mais, onde procurar, quais perguntas fazer
+e como verificar se está certo**.

package/docs/reference-authoring.md

@@ -0,0 +1,117 @@
+# Reference Authoring
+
+Como adicionar fontes externas ao catálogo. As referências são centralizadas em
+`references/` — nunca embutidas em skills — para que o `research-router` possa
+despachar para elas e o `scripts/validate.py` possa validar o schema.
+
+## Por que centralizado
+
+Sites, projetos, produtos e documentações externas não ficam espalhados pelas skills.
+Isto evita:
+
+* URLs duplicadas e que apodrecem em múltiplas skills;
+* skills que viram um dump de links em vez de raciocínio;
+* inconsistência sobre quais fontes são confiáveis.
+
+```text
+skills/        como pensar
+references/    onde pesquisar
+```
+
+## Arquivos
+
+```text
+references/
+├── frontend.yaml
+├── ux.yaml
+├── engineering.yaml
+├── security.yaml
+├── product.yaml
+└── research.yaml
+```
+
+Cada arquivo é uma lista YAML de entradas. Um arquivo por domínio.
+
+## Schema de cada entrada
+
+```yaml
+- name: Example
+  url: https://example.com
+  type: methodology
+  category: ux
+  authority: established
+  use_when:
+    - reviewing usability
+    - designing flows
+  avoid_when:
+    - unrelated backend task
+  search_queries:
+    - "example usability heuristics"
+    - "example flow design patterns"
+```
+
+| Campo | Tipo | Valores |
+|---|---|---|
+| `name` | string | Nome reconhecível da fonte. |
+| `url` | string | URL canônica. |
+| `type` | enum | `methodology` \| `heuristic` \| `inspiration` \| `implementation` \| `discovery` |
+| `category` | string | Domínio — corresponde ao arquivo (`frontend`, `ux`, `engineering`, `security`, `product`, `research`). |
+| `authority` | enum | `established` \| `community` \| `vendor` \| `curated` (ver abaixo). |
+| `use_when` | list[string] | Situações em que a fonte é relevante. |
+| `avoid_when` | list[string] | Situações em que não é útil ou é misleading. |
+| `search_queries` | list[string] | Queries prontas para alimentar busca. |
+
+## Classes de conhecimento (`type`)
+
+Não tratar todas as fontes como iguais. O `type` diz **que tipo de coisa** a fonte
+oferece:
+
+| `type` | O que é | Exemplo |
+|---|---|---|
+| `methodology` | Um método ou framework estruturado | Laws of UX |
+| `heuristic` | Heurísticas e princípios aplicáveis | Impeccable |
+| `inspiration` | Inspiração visual, não prescritiva | Dribbble |
+| `implementation` | Código/padrões concretos de implementação | Animate UI |
+| `discovery` | Ferramenta de descoberta de mais fontes | LazyWeb, Shoogle |
+
+## Níveis de autoridade (`authority`)
+
+Nem toda fonte tem o mesmo peso. O `authority` diz **quanto confiar**:
+
+| `authority` | Significado |
+|---|---|
+| `established` | Autoridade reconhecida, padrão de fato, documentação oficial. Maior peso. |
+| `vendor` | Documentação de um vendor/framework específico. Confiável dentro do seu domínio. |
+| `community` | Sabedoria da comunidade, curadoria coletiva. Útil mas verificar. |
+| `curated` | Coleção curada (galerias, agregadores). Inspiração; não prescritivo. |
+
+Ao sintetizar pesquisa, fontes `established` e `vendor` pesam mais que `curated` e
+`inspiration`. Ver `AGENTS.md` § 5 (síntese) e § 1 (distinguir inspiração de evidência).
+
+## Regras
+
+1. **Uma fonte, uma entrada.** Não duplicar URLs entre arquivos. Se uma fonte serve a
+   múltiplos domínios, escolha o domínio primário e referencie-o do router.
+2. **`search_queries` sempre preenchido.** O `research-router` e as research skills
+   usam estas queries; entradas sem queries são inacionáveis.
+3. **`use_when`/`avoid_when` específicos.** "Quando útil" genérico não ajuda o router a
+   decidir entre fontes.
+4. **Inspiração ≠ evidência.** Fontes `type: inspiration` ou `authority: curated`
+   nunca justificam um finding técnico por si só.
+5. **URLs canônicas.** Use a URL raiz ou a página mais estável, não um deep link que
+   pode quebrar.
+
+## Validação
+
+```bash
+python3 scripts/validate.py
+```
+
+O validator verifica, para cada `references/*.yaml`:
+
+* YAML sintaticamente válido;
+* cada entrada tem todos os sete campos;
+* `type` e `authority` são enums válidos;
+* `category` corresponde ao arquivo em que está;
+* `url` é uma URL absoluta com esquema;
+* `use_when`, `avoid_when`, `search_queries` são listas não-vazias.

package/docs/skill-authoring.md

@@ -0,0 +1,126 @@
+# Skill Authoring
+
+Como escrever uma skill. Toda skill segue um formato padrão para que o `skill-router`
+possa despachar para ela, o `scripts/validate.py` possa verificá-la, e skills possam
+compor entre si sem ambiguidade.
+
+## Localização
+
+```text
+skills/<categoria>/<nome-da-skill>/SKILL.md
+```
+
+Categorias: `audit`, `security`, `reliability`, `product`, `frontend`, `research`,
+`meta`. O nome da skill é kebab-case e corresponde exatamente ao `name` no frontmatter.
+
+## Frontmatter
+
+YAML, entre `---`:
+
+```yaml
+---
+name: skill-name
+description: Short description
+category: audit
+triggers:
+  - trigger
+  - another trigger
+priority: high
+---
+```
+
+| Campo | Tipo | Descrição |
+|---|---|---|
+| `name` | string | kebab-case, igual ao nome do diretório. |
+| `description` | string | Descrição curta — usada para seleção. |
+| `category` | string | Uma das categorias acima. |
+| `triggers` | list[string] | Frases/tópicos que indicam quando a skill é relevante. O `skill-router` despacha com base nisto. |
+| `priority` | enum | `low` \| `medium` \| `high`. Indica quão central é a skill para a categoria. |
+
+## Corpo — nove seções fixas
+
+Ordem obrigatória. Nenhuma seção pode ser omitida (use "N/A" com justificativa se
+genuinamente não aplicável, mas prefira sempre preencher).
+
+```markdown
+# Skill Name
+
+## Objective
+O que esta skill ensina o agente a fazer. Uma frase.
+
+## When to Use
+Quando ativá-la. Condições, tipos de tarefa, sintomas. Corresponde aos `triggers`
+expandidos em prosa.
+
+## Mental Model
+A lente de raciocínio. Como enxergar o sistema através desta skill.
+
+## Investigation Procedure
+A ordem das investigações. Passo a passo, sequencial.
+
+## Questions to Ask
+Perguntas concretas a fazer sobre o sistema. Cada uma expõe uma classe de defeito.
+
+## Attack Patterns
+Sequências concretas de operações que expõem defeitos. Verbs like repeat, reverse,
+reorder, skip, replay, concurrent, manipulate.
+
+## Evidence Requirements
+O que conta como confirmação. Como reproduzir. Que nível de evidência é necessário
+para subir o finding de POSSIBLE para CONFIRMED. Referencie a escala em AGENTS.md § 2.
+
+## False Positives
+Quando o comportamento "estranho" detectado é na verdade aceitável ou intencional.
+O que NÃO reportar. Minimiza ruído.
+
+## Output Format
+Como reportar findings. Aponte para `templates/audit-report.md` e liste os campos
+obrigatórios. Toda skill de auditoria deve produzir findings no formato padronizado.
+```
+
+## Qualidade — seis perguntas
+
+Toda skill também deve responder (seção 21 do `plan.md`):
+
+| Pergunta | Onde vive no SKILL.md |
+|---|---|
+| **Necessidade** — qual problema ela resolve? | `Objective` |
+| **Escopo** — quando deve ser ativada? | `When to Use` + `triggers` |
+| **Heurísticas** — quais perguntas ela ensina? | `Questions to Ask` + `Mental Model` |
+| **Evidência** — como confirmar o finding? | `Evidence Requirements` |
+| **Falsos positivos** — quando o comportamento é aceitável? | `False Positives` |
+| **Composição** — quais skills trabalham junto? | `When to Use` (parágrafo final) ou seção dedicada |
+
+Se uma skill não consegue responder às seis, ela não está pronta.
+
+## Convenções de escrita
+
+* **Termos estruturais em inglês** — nomes de skills, cabeçalhos das nove seções,
+  campos de frontmatter, enums (CONFIRMED, etc.). Isto mantém compatibilidade com o
+  router e o validator.
+* **Prosa explicativa em português** — modelo mental, perguntas, procedimento. Isto
+  segue a convenção do `plan.md`.
+* **Diagrams em blocos de código `text`** — fluxos e pipelines ficam legíveis em
+  terminal e não dependem de renderização.
+* **Sem conhecimento implícito** — se a skill depende de um conceito, documente-o
+  ou aponte para `references/`.
+
+## Validação
+
+```bash
+python3 scripts/validate.py
+```
+
+O validator verifica:
+
+* frontmatter com os cinco campos (`name`, `description`, `category`, `triggers`,
+  `priority`);
+* `name` igual ao nome do diretório;
+* `category` válida;
+* `priority` em `low`/`medium`/`high`;
+* as nove seções presentes, em ordem, como headings `##`.
+
+## Exemplo
+
+Ver `skills/audit/adversarial-review/SKILL.md` para a skill de referência, e
+`examples/` para auditorias completas.