agent-engineering-skills 1.0.0

package/AGENTS.md

@@ -0,0 +1,249 @@
+# AGENTS.md — Regras globais do agente
+
+> **Don't just review the code. Attack the assumptions behind the system.**
+
+Este arquivo define as regras globais que todo agente que opera sobre este repositório
+deve seguir. As skills em `skills/` ensinam **como pensar**; as referências em `references/`
+ensinam **onde olhar**; este arquivo define o **comportamento base** que governa ambos.
+
+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**.
+
+---
+
+## 1. Regras de investigação
+
+Antes de concluir qualquer coisa, o agente deve:
+
+* **Investigar antes de concluir.** Nunca reportar um bug a partir de uma hipótese
+  não verificada. Toda conclusão precisa de evidência.
+* **Pensar em invariantes.** Para cada componente, identificar o que **deve** ser
+  sempre verdade. Um invariant violado é quase sempre um bug real.
+* **Considerar estados.** Toda operação ocorre sobre um estado. Perguntar: qual o
+  estado antes? qual o estado depois? quais estados são possíveis? quais são
+  impossíveis? quais são não-desejados mas alcançáveis?
+* **Testar repetição.** O que acontece se a mesma operação for executada N vezes?
+  (Recompensa duplicada? contador inflado? recurso criado várias vezes?)
+* **Testar reversão.** O que acontece se a operação for desfeita e refeita?
+  (Farming infinito? estado inconsistente? perda de dados?)
+* **Testar concorrência.** O que acontece se dois requests modificam o mesmo estado
+  simultaneamente? (Race condition? double-spend? estado corrompido?)
+* **Não confiar no frontend.** O frontend é uma sugestão, não uma fonte de verdade.
+  Validação de cliente pode ser ignorada. Campos como `userId`, `role`, `price`, `XP`
+  nunca devem ser confiados sem validação no servidor.
+* **Verificar APIs diretamente.** Tratar a API como diretamente acessível, ignorando
+  a UI. O usuário malicioso não usa o frontend; ele chama os endpoints.
+* **Pesquisar referências quando necessário.** Para tarefas não triviais, perguntar
+  "alguém já resolveu esse problema?" e consultar `references/` antes de reinventar.
+  Ver `references/` e o `research-router`.
+* **Distinguir inspiração de evidência.** Referências externas são inspiração
+  (princípios, padrões, trade-offs), não especificação. Extrair ideias, nunca copiar
+  cegamente código, layout, branding ou componentes proprietários.
+* **Minimizar falsos positivos.** Antes de reportar um comportamento estranho como
+  bug, confirmar que ele é realmente um defeito e não um comportamento aceitável ou
+  intencional. Consultar a seção "False Positives" da skill usada.
+* **Reportar evidências.** Todo finding deve ser classificado por nível de confiança
+  (ver abaixo) e incluir reprodução, causa raiz e impacto.
+
+---
+
+## 2. Classificação de evidência
+
+Todo finding deve ser classificado em um destes quatro níveis. Nunca transformar uma
+hipótese em bug confirmado.
+
+```text
+CONFIRMED         — reproduzido com evidência direta (logs, teste, reprodução passo a passo)
+HIGH CONFIDENCE   — forte indício técnico, mas sem reprodução completa
+POSSIBLE          — plausível, exige mais investigação para confirmar ou descartar
+SPECULATIVE       — hipótese sem evidência direta; reportar apenas como risco, não como bug
+```
+
+Regra prática: se você não consegue reproduzir, no máximo é `HIGH CONFIDENCE`.
+Se você não consegue apontar o mecanismo exato, no máximo é `POSSIBLE`.
+Se é "acho que pode acontecer", é `SPECULATIVE` — e findings `SPECULATIVE` não devem
+bloquear implementação, apenas ser listados como riscos a verificar.
+
+---
+
+## 3. Pesquisar antes de reinventar
+
+Para tarefas não triviais, o agente deve seguir o fluxo:
+
+```text
+UNDERSTAND  →  CLASSIFY  →  RESEARCH  →  COMPARE  →  DECIDE  →  IMPLEMENT
+```
+
+Não:
+
+```text
+UNDERSTAND  →  IMPLEMENT
+```
+
+Mas **pesquisa deve ser proporcional à complexidade**.
+
+* Um botão simples não precisa de pesquisa.
+* Uma arquitetura nova provavelmente precisa.
+* Um padrão de concorrência em pagamentos certamente precisa.
+
+Quando apropriado, pesquisar nesta ordem:
+
+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.
+
+A ordem reflete confiabilidade: o que já existe no projeto e a documentação oficial
+vêm antes de inspiração externa.
+
+---
+
+## 4. Workflow completo de auditoria
+
+Para uma auditoria (não apenas uma implementação), o fluxo é:
+
+```text
+┌──────────────────────┐
+│       REQUEST        │
+└──────────┬───────────┘
+           ↓
+┌──────────────────────┐
+│     UNDERSTAND       │
+└──────────┬───────────┘
+           ↓
+┌──────────────────────┐
+│    CLASSIFY TASK     │
+└──────────┬───────────┘
+           ↓
+┌──────────────────────┐
+│     SKILL ROUTER     │
+└──────────┬───────────┘
+           ↓
+┌──────────────────────┐
+│   RESEARCH ROUTER    │
+└──────────┬───────────┘
+           ↓
+┌──────────────────────┐
+│      RESEARCH        │
+└──────────┬───────────┘
+           ↓
+┌──────────────────────┐
+│       ANALYZE        │
+└──────────┬───────────┘
+           ↓
+┌──────────────────────┐
+│       IMPLEMENT      │
+└──────────┬───────────┘
+           ↓
+┌──────────────────────┐
+│   ADVERSARIAL TEST   │
+└──────────┬───────────┘
+           ↓
+┌──────────────────────┐
+│       VERIFY         │
+└──────────┬───────────┘
+           ↓
+┌──────────────────────┐
+│       REPORT         │
+└──────────────────────┘
+```
+
+* **SKILL ROUTER** (`skills/meta/skill-router/`) — analisa a tarefa e seleciona
+  quais skills ativar. Nem toda tarefa precisa de todas as skills.
+* **RESEARCH ROUTER** (`skills/meta/research-router/`) — decide **onde** pesquisar
+  com base no tipo de problema.
+* **ADVERSARIAL TEST** — testa a implementação como um usuário adversarial
+  (repeat, reverse, replay, concurrent). Ver `adversarial-review`.
+
+---
+
+## 5. Síntese de pesquisa
+
+O agente **nunca** deve retornar apenas uma lista de links. Toda pesquisa deve
+ser sintetizada no formato:
+
+```markdown
+## Research
+
+### Reference
+[Name]
+
+### Relevant Pattern
+O que foi encontrado.
+
+### Why It Matters
+Por que este padrão é útil.
+
+### Adaptation
+Como ele poderia se aplicar ao projeto atual.
+
+### Trade-offs
+Que problemas ele introduz.
+
+### Recommendation
+O que deve de fato ser adotado.
+```
+
+---
+
+## 6. Evitar overengineering
+
+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.
+
+Princípio:
+
+> **Research proportional to uncertainty and impact.**
+
+Quanto maior:
+
+```text
+uncertainty  +  impact  +  irreversibility
+```
+
+maior deve ser o nível de pesquisa. Uma mudança trivial e reversível não justifica
+uma auditoria completa; uma mudança em fluxo de pagamento, irreversível e de alto
+impacto, justifica o workflow completo.
+
+---
+
+## 7. Composição entre skills
+
+Skills devem trabalhar em conjunto. O `skill-router` define a composição, mas a
+regra geral é: uma tarefa raramente ativa uma skill isolada.
+
+Exemplos:
+
+* `payment` → `business-logic-audit`, `idempotency-audit`, `race-condition-hunter`,
+  `data-integrity-audit`, `error-flow-audit`, `authorization-audit`.
+* `social reactions` → `gamification-audit`, `business-logic-audit`,
+  `idempotency-audit`, `race-condition-hunter`, `api-abuse-audit`.
+
+Ao combinar skills, **deduplicar findings**: quando duas skills apontam o mesmo
+defeito, consolidar em um único finding com a análise combinada.
+
+---
+
+## 8. Referências rápidas
+
+| Precisa de… | Onde |
+|---|---|
+| Formato de uma skill | `docs/skill-authoring.md` |
+| Formato de uma referência | `docs/reference-authoring.md` |
+| Filosofia e princípios | `docs/philosophy.md` |
+| Integração do agente (workflows) | `docs/agent-integration.md` |
+| Catálogo de referências | `references/*.yaml` |
+| Template de relatório de auditoria | `templates/audit-report.md` |
+| Template de bug report | `templates/bug-report.md` |
+| Validação (lint de skills/refs) | `scripts/validate.py` |

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 1arley-agent-skills contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,113 @@
+# Agent Engineering Skills
+
+> **Don't just review the code. Attack the assumptions behind the system.**
+
+Um repositório de skills modulares que ensinam agentes de IA a **entender → pesquisar
+→ questionar → testar → verificar → implementar → revisar**.
+
+O objetivo 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**.
+
+---
+
+## O que isto é
+
+Três camadas, separadas de propósito:
+
+```text
+skills/        →  como pensar   (modelo mental, perguntas, padrões de ataque, evidência)
+knowledge/     →  o que considerar
+references/    →  onde pesquisar (catálogo centralizado de fontes externas)
+```
+
+As skills ensinam raciocínio. As referências ensinam onde olhar. Nenhuma skill depende
+de conhecimento implícito que não esteja documentado ou disponível através das
+referências.
+
+## Estrutura
+
+```text
+├── AGENTS.md              # regras globais do agente
+├── plan.md                # especificação completa (fases, formato, definição de pronto)
+├── LICENSE                # MIT
+│
+├── skills/
+│   ├── audit/             # auditoria de sistemas e descoberta de bugs
+│   ├── security/          # autorização, abuso de API, confiança de input
+│   ├── reliability/       # race conditions, idempotência, integridade de dados
+│   ├── product/           # regras de negócio e gamificação
+│   ├── frontend/          # UX, visual, interação, animação, acessibilidade
+│   ├── research/          # descoberta de referências e implementações
+│   └── meta/              # routers que despacham para skills e fontes
+│
+├── references/            # catálogo YAML de fontes externas
+├── knowledge/             # material "o que considerar"
+├── templates/             # templates de relatório (audit, bug, design, research)
+├── examples/              # exemplos concretos de auditorias
+├── docs/                  # filosofia, authoring, integração
+└── scripts/               # validação (lint de skills e referências)
+```
+
+Cada skill é `skills/<categoria>/<nome>/SKILL.md` com frontmatter YAML e nove seções
+fixas. Ver `docs/skill-authoring.md`.
+
+## Skills (primeira versão — 24)
+
+| Categoria | Skills |
+|---|---|
+| **Core audit** | `adversarial-review`, `user-flow-audit`, `business-logic-audit`, `edge-case-hunter`, `state-consistency-audit`, `error-flow-audit` |
+| **Security** | `authorization-audit`, `api-abuse-audit`, `input-trust-audit` |
+| **Reliability** | `race-condition-hunter`, `idempotency-audit`, `data-integrity-audit` |
+| **Product** | `gamification-audit` |
+| **Frontend** | `ux-review`, `visual-quality-review`, `interaction-design`, `animation-review`, `accessibility-review` |
+| **Research** | `reference-research`, `github-reference-research`, `market-research`, `implementation-research` |
+| **Meta** | `skill-router`, `research-router` |
+
+A prioridade é **qualidade, composição e capacidade de raciocínio — não quantidade**.
+
+## Como usar
+
+1. Leia `AGENTS.md` para as regras globais.
+2. Para uma tarefa, comece pelo `skills/meta/skill-router/` — ele seleciona quais
+   skills ativar com base no tipo de tarefa.
+3. Para pesquisa, use `skills/meta/research-router/` — ele aponta quais fontes em
+   `references/` consultar.
+4. Ao reportar findings, siga `templates/audit-report.md` e classifique cada um por
+   nível de evidência (`CONFIRMED` / `HIGH CONFIDENCE` / `POSSIBLE` / `SPECULATIVE`).
+
+## Workflow completo
+
+```text
+REQUEST → UNDERSTAND → CLASSIFY → SKILL ROUTER → RESEARCH ROUTER →
+RESEARCH → ANALYZE → IMPLEMENT → ADVERSARIAL TEST → VERIFY → REPORT
+```
+
+Pesquisa é proporcional à complexidade: um botão simples não precisa de pesquisa;
+uma arquitetura nova provavelmente precisa; concorrência em pagamentos certamente.
+
+## Status
+
+**Primeira versão completa.** 24 skills implementadas, 6 catálogos de referências,
+4 templates de relatório, 4 exemplos concretos, 2 meta routers, validador.
+
+```bash
+python3 scripts/validate.py
+```
+
+Verifica que toda `skills/**/SKILL.md` tem o frontmatter e as nove seções exigidas,
+que toda `references/*.yaml` segue o schema de catálogo, e que as referências do
+`skill-router` são consistentes. Ver `docs/skill-authoring.md` e
+`docs/reference-authoring.md`.
+
+## Documentação
+
+* `docs/philosophy.md` — princípios e filosofia central.
+* `docs/skill-authoring.md` — como escrever uma skill (formato `SKILL.md`).
+* `docs/reference-authoring.md` — como adicionar referências (schema YAML).
+* `docs/agent-integration.md` — como o agente integra skills, routers e workflows.
+* `plan.md` — especificação completa e Definition of Done.
+
+## Licença
+
+MIT — ver `LICENSE`.

package/bin/cli.js

@@ -0,0 +1,223 @@
+#!/usr/bin/env node
+/**
+ * agent-engineering-skills — CLI
+ *
+ * Usage:
+ *   npx agent-engineering-skills install [--target <dir>] [--link] [--force]
+ *   npx agent-engineering-skills validate
+ *   npx agent-engineering-skills --help
+ *
+ * `install` copies (or symlinks) the 24 skills into a Claude Code skills directory
+ * (default: ~/.claude/skills), adapting the frontmatter to Claude Code's native
+ * format (name + description) and making each skill user-invocable.
+ *
+ * Zero runtime dependencies — Node >= 18 only.
+ */
+
+import { execFileSync } from "node:child_process";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const require = createRequire(import.meta.url);
+const PKG = require("../package.json");
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(__dirname, "..");
+
+const SKILLS_GLOB = path.join(ROOT, "skills");
+const DEFAULT_TARGET = path.join(os.homedir(), ".claude", "skills");
+
+const HELP = `agent-engineering-skills v${PKG.version}
+
+Modular skills that teach AI agents to audit systems, find bugs, review
+UX/frontend, and research before reinventing.
+
+Usage:
+  agent-engineering-skills install [options]   Install the 24 skills into a
+                                               Claude Code skills directory
+  agent-engineering-skills validate            Run the repo validator
+  agent-engineering-skills --help              Show this help
+  agent-engineering-skills --version           Show version
+
+Options (install):
+  --target <dir>   Destination skills directory (default: ~/.claude/skills)
+  --link           Create symlinks instead of copying
+  --force          Overwrite existing skills with the same name
+`;
+
+function log(msg = "") {
+  process.stdout.write(msg + "\n");
+}
+
+function err(msg) {
+  process.stderr.write(msg + "\n");
+}
+
+/** List every <category>/<skill>/ directory under skills/. */
+function findSkillDirs() {
+  const dirs = [];
+  if (!fs.existsSync(SKILLS_GLOB)) return dirs;
+  for (const category of fs.readdirSync(SKILLS_GLOB)) {
+    const catPath = path.join(SKILLS_GLOB, category);
+    if (!fs.statSync(catPath).isDirectory()) continue;
+    for (const skill of fs.readdirSync(catPath)) {
+      const skillPath = path.join(catPath, skill);
+      if (!fs.statSync(skillPath).isDirectory()) continue;
+      if (!fs.existsSync(path.join(skillPath, "SKILL.md"))) continue;
+      dirs.push({ category, name: skill, src: skillPath });
+    }
+  }
+  return dirs.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * Rewrite a SKILL.md frontmatter into Claude Code's native shape:
+ *   - keep name + description (the fields the harness matches on)
+ *   - add user_invocable so the skill can be invoked via slash command
+ *   - drop plan.md-only fields (category/triggers/priority) that the harness
+ *     does not use; their routing duty lives in the skill-router instead
+ * Returns the rewritten file content (or original if unchanged).
+ */
+function adaptFrontmatter(original) {
+  const m = original.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!m) return original;
+  const fm = m[1];
+  const body = original.slice(m[0].length);
+
+  const get = (key) => {
+    const re = new RegExp(`^${key}:\\s*(.+)$`, "m");
+    const hit = fm.match(re);
+    return hit ? hit[1].trim().replace(/^['"]|['"]$/g, "") : null;
+  };
+
+  const name = get("name");
+  const description = get("description");
+  if (!name || !description) return original; // don't mangle malformed files
+
+  const adapted = `---\nname: ${name}\ndescription: ${description}\nuser_invocable: true\n---\n${body}`;
+  return adapted;
+}
+
+function copyDir(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const from = path.join(src, entry.name);
+    const to = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDir(from, to);
+    } else if (entry.isFile()) {
+      let content = fs.readFileSync(from, "utf8");
+      if (entry.name === "SKILL.md") {
+        content = adaptFrontmatter(content);
+      }
+      fs.writeFileSync(to, content);
+    }
+  }
+}
+
+function installSkill(skill, target, { link, force }) {
+  const dest = path.join(target, skill.name);
+  if (fs.existsSync(dest)) {
+    if (!force) {
+      return { name: skill.name, status: "skipped (exists — use --force)" };
+    }
+    fs.rmSync(dest, { recursive: true, force: true });
+  }
+  if (link) {
+    fs.symlinkSync(skill.src, dest, "dir");
+    return { name: skill.name, status: "linked" };
+  }
+  copyDir(skill.src, dest);
+  return { name: skill.name, status: "installed" };
+}
+
+function runInstall(target, { link, force }) {
+  const skills = findSkillDirs();
+  if (!skills.length) {
+    err(`No skills found under ${SKILLS_GLOB}`);
+    process.exitCode = 1;
+    return;
+  }
+  fs.mkdirSync(target, { recursive: true });
+  log(`agent-engineering-skills v${PKG.version} — installing ${skills.length} skills`);
+  log(`target: ${target}${link ? "  (symlink mode)" : ""}${force ? "  (force)" : ""}`);
+  log("");
+
+  const results = skills.map((s) => installSkill(s, target, { link, force }));
+  const counts = { installed: 0, linked: 0, skipped: 0 };
+  for (const r of results) {
+    if (r.status.startsWith("installed")) counts.installed++;
+    else if (r.status === "linked") counts.linked++;
+    else counts.skipped++;
+    log(`  ${r.status.startsWith("skipped") ? "•" : "✓"} ${r.name} — ${r.status}`);
+  }
+  log("");
+  log(
+    `Done: ${counts.installed} installed, ${counts.linked} linked, ` +
+      `${counts.skipped} skipped.`
+  );
+  log("");
+  log("Skills are now available in your Claude Code skills directory.");
+  log("Dispatch between them with skills/meta/skill-router (installed too).");
+  log("Next: run 'python3 scripts/validate.py' or 'npx agent-engineering-skills validate'.");
+}
+
+function runValidate() {
+  const script = path.join(ROOT, "scripts", "validate.py");
+  if (!fs.existsSync(script)) {
+    err(`Validator not found at ${script}`);
+    process.exitCode = 1;
+    return;
+  }
+  try {
+    execFileSync("python3", [script], { stdio: "inherit" });
+  } catch {
+    process.exitCode = 1;
+  }
+}
+
+function parseArgs(argv) {
+  const opts = { target: DEFAULT_TARGET, link: false, force: false, command: null };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--help" || a === "-h") {
+      log(HELP);
+      process.exit(0);
+    } else if (a === "--version" || a === "-v") {
+      log(PKG.version);
+      process.exit(0);
+    } else if (a === "--target") {
+      opts.target = path.resolve(argv[++i] || "");
+    } else if (a === "--link") {
+      opts.link = true;
+    } else if (a === "--force") {
+      opts.force = true;
+    } else if (a.startsWith("-")) {
+      err(`Unknown option: ${a}\n`);
+      log(HELP);
+      process.exitCode = 1;
+      return null;
+    } else if (!opts.command) {
+      opts.command = a;
+    }
+  }
+  return opts;
+}
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  if (!opts) return;
+  if (!opts.command || opts.command === "install") {
+    runInstall(opts.target, { link: opts.link, force: opts.force });
+  } else if (opts.command === "validate") {
+    runValidate();
+  } else {
+    err(`Unknown command: ${opts.command}\n`);
+    log(HELP);
+    process.exitCode = 1;
+  }
+}
+
+main();