AGENTS.md

Objetivo

Este repositorio define um kit de skills e governanca para agentes de coding em Claude, OpenCode e superficies compativeis.

Uso em Repos Consumidores

• em repos de aplicacao, o modo recomendado e manter AGENTS.md na raiz e instalar o kit dentro de .bot/
• usar templates/AGENTS-root.md como base para o AGENTS.md do repo consumidor
• se o repo consumidor nao tiver auditoria valida, iniciar por Repo Auditor

Ordem de Leitura

1. GLOBAL.md
2. policies/
3. docs/WIKI.md — visao panoramica de todo o kit (todas as skills, subagents, commands, policies)
4. README.md
5. skills/*/SKILL.md — skill especifica conforme task
6. docs/skill-guides/ somente quando a tarefa exigir exemplos extensos

Defaults Operacionais

• responder curto por padrao
• agir primeiro quando houver default seguro
• nao repetir contexto desnecessario
• usar tools com minimo privilegio
• pedir aprovacao para acoes destrutivas ou externas de alto risco
• registrar handoff curto e objetivo

Memoria do Kit (vale para qualquer agente, com ou sem hooks)

Os hooks do kit so rodam onde estao registrados (Claude Code pelo plugin; Codex por .codex/hooks.json). Agente sem hook — Grok Build (que ignora hooks do Claude por padrao), Cursor, Gemini CLI, OpenCode — le este arquivo e deve fazer a mao o que o hook faz:

• antes de repetir uma abordagem, procure em .bot/learned-skills/*.md pelo campo triggers que casa com a tarefa; leia o state
• state: rejected = ja tentado e descartado; o campo reason diz por que. Nao repita sem fato novo que invalide o motivo. superseded aponta o sucessor em superseded_by; stale e hipotese
• files: + commit: dizem de que arquivos a nota depende: se mudaram desde o commit (git diff <commit>..HEAD -- <arquivo>), revalide antes de aplicar
• apos uma compactacao, trate qualquer resumo recebido como pista, nao como fato: reconfira o estado do git e rode de novo a verificacao que ele cita
• com o servidor ai-memory ligado por MCP, node scripts/learned-skills-to-ai-memory.mjs --apply publica as learned-skills nele, e entao memory_query as encontra em qualquer agente. Nunca grave valor de chave/token em nota Detalhe: policies/learned-skills.md, policies/compaction-recovery.md, policies/memory-write-rules.md.

Guardas sob demanda (/careful, /freeze) em qualquer agente

Sem slash commands (Codex, Grok Build, Cursor...), ligue pelo shell: node scripts/session-guard-cli.mjs careful on|off e freeze <pasta>|off (status mostra). Onde o hook esta registrado (Claude, Codex pelo .codex/hooks.json, Grok com install-memory-hooks.mjs --runtime grok --guards --apply) o bloqueio e mecanico. Sem hook, a regra vale por convencao: com freeze ativo, nao edite fora da pasta; com careful ativo, nao rode rm -rf, git push --force, git reset --hard, deploy nem SQL destrutivo sem confirmacao explicita da pessoa. Estado em .auto/session-guards.json (do projeto, expira em 8 h).

Mudancas no Repositorio

• prefira mudancas pequenas e revisaveis
• preserve a hierarquia global do kit
• nao reintroduza acoplamento a vendor ou comando especifico sem necessidade
• mova exemplos longos para docs/skill-guides/ quando uma skill comecar a inflar

Validacao Minima

• siga policies/evals.md para mudancas de skills, prompts e tools
• siga policies/tool-safety.md para MCP, rede, escrita e acoes externas

Slash Commands

Use atalhos por fase quando couber: /spec → /plan → /build → /test → /review → /ship; /pipeline reúne o fluxo completo. /context-budget mede contexto, /savings mede economia runtime. Para os demais atalhos, carregue docs/skill-guides/skill-discovery.md ou o comando específico em commands/ somente quando necessário. Não carregue o catálogo inteiro em cada sessão.

Modos de execução autônomos

• /auto — prompt-based, executa no contexto atual da conversa
• /loop — process-based (auto-loop v2), roda o agente como subprocess com:
  • multi-agente via --agent claude|codex
  • worktree integrado via --worktree (paralelo via --parallel N, até 8)
  • polishing pass configurável via --polish none|light|standard|full
  • exit codes determinísticos para uso em CI (ver .claude/commands/loop.md)

Image Generation (v2.16.0 — regra canônica do kit)

Quando o agente precisar gerar ou adaptar imagem (hero, ícone, ilustração, OG card, mascote, favicon):

1. Despachar skill 17 (17-image-generator) — nunca chamar API FAL.AI direto, nunca instalar SDK extra.
2. Skill 17 aplica regra default automaticamente:
   • text-to-image (sem referenceImages) → grok-imagine ($0.020/img)
   • edit/refine (com referenceImages) → gemini-25-flash ($0.039/img)
   • Override (--model gemini-3-pro etc.) só com justificativa documentada
3. Execução: node scripts/generate-image.mjs --prompt "..." [--ref ./img.jpg] --out path (zero-dep, lê models/image-models.json).
4. /swarm invoca automaticamente em Phase 2.5 quando PRD/stories mencionam landing/sistema/UI novo.
5. Fonte única de models: models/image-models.json — atualizar lá quando preços mudarem, propaga pra skill + template stack-default.

Detalhes em skills/17-image-generator/SKILL.md → Regra Default.

Template stack-default (v2.15.x)

Pra projeto novo (greenfield), em vez de scaffoldar do zero (Write × 130):

cp -r templates/stack-default/ ../meu-projeto/
cd ../meu-projeto/ && cp .env.example .env && make dev

Stack já decidida (não reabrir): Docker Compose + Postgres 16 + Redis 7 + MinIO + Traefik + Next.js 15 + Better Auth + Drizzle + OpenRouter (LLM) + FAL.AI (image). Decisões em templates/stack-default/README-stack.md.

Artefatos Principais

• GLOBAL.md = regras universais
• policies/ = regras compartilhadas (inclui context-engineering.md para hierarquia de contexto e rules-system.md para os rules path-scoped)
• rules/ = padrões de codificação path-scoped (common/ sempre aplica; <linguagem>/ anexa via paths: glob). Copiados para .claude/rules/dev-team-kit/ no install. Ver policies/rules-system.md.
• templates/ = formatos curtos padronizados
• skills/ = especialidades
• personas/ = personas estruturadas para review (code-reviewer, security-auditor, test-engineer)
• docs/repo-audit/ = auditoria reutilizavel do repositorio
• docs/skill-guides/ = anexos sob demanda (inclui skill-discovery.md e context-engineering.md)
• evals/ = casos de avaliacao do sistema
• docs/setup-bot-folder.md = modo recomendado de instalacao em .bot/
• patterns/ai-integration/ = padroes reutilizaveis para integrar IA em apps
• .claude/commands/ = slash commands por fase de desenvolvimento
• .claude/agents/ = subagents despachaveis via Task tool

Ferramentas de mídia e conduta dos subagentes (qualquer agente)

As skills 84 (vídeo com IA), 85 (ilustração) e 86 (filme em código) trazem ferramentas em Node puro (Node 20+), sem depender de slash command nem de hook: funcionam igual em Claude Code, Codex, Grok Build, Cursor, Gemini CLI, OpenCode e outros, em Windows, macOS e Linux. Em repo consumidor, prefixe os caminhos com .bot/.

node skills/86-code-motion-film/scripts/doctor.mjs --install    # verifica e instala ffmpeg, Playwright e Chromium (winget/choco, brew ou apt) e prova com um render
node skills/86-code-motion-film/scripts/check-film.mjs film/index.html   # o filme é função pura do tempo? (fonte limpa, mesmo quadro em qualquer ordem, loop fechado)
node skills/86-code-motion-film/scripts/beats.mjs analyze trilha.mp3     # andamento, compasso 1, drops; `cut` corta compassos inteiros
node skills/84-ai-video-direction/scripts/briefing-qa.mjs briefing.json  # reprova número, preço ou depoimento sem fonte no briefing de vídeo
node scripts/svg-icon-lint.mjs <pasta-ou-arquivo.svg>                    # linter de ícones e ilustrações (skill 85)

• As ações que variam por agente (planejar, perguntar, olhar uma imagem, delegar, rodar em segundo plano, enviar arquivo) estão numa tabela em skills/86-code-motion-film/references/AGENTES.md. Onde o seu agente não tem uma delas, o fluxo diz o que fazer no lugar; nunca finja que viu uma imagem que não abriu.
• Subagentes sem despacho (agentes que não têm Agent/Task): os arquivos de agents/*.md servem como prompt de papel. Leia o arquivo inteiro, inclusive o bloco "Conduta" no fim (investigar antes de afirmar, declarar o que não foi verificado, escopo é o pedido; os que escrevem também confirmam antes de ação destrutiva e nunca enfraquecem teste). A fonte desse bloco é policies/subagent-conduct.md; node scripts/sync-agent-conduct.mjs confere que nenhum agente divergiu.
• Texto de terceiros (galerias de prompts, por exemplo) fica fora do repositório: a biblioteca local de prompt-motion.mjs vive em ~/.dev-team-kit/prompt-motion/.

Subagents Despacháveis (agents/) vs Skills (skills/NN-*/)

⚠ REGRA CRÍTICA — ler antes de despachar qualquer trabalho paralelo.

O kit tem dois universos que compartilham o prefixo dev-team-kit-fv::

Os 16 papéis de agents/ são os subagents do kit em hosts que os registram; nomes expostos variam conforme o host. Confirme o catálogo real antes de invocar.

Detalhes completos: policies/skills-vs-agents.md. Hook fail-fast: hooks/scripts/agent-dispatch-validator.mjs.

Despacho sob demanda

Os nomes e papéis ficam em agents/*.md e policies/skills-vs-agents.md; consulte o papel antes de despachar. Use a ferramenta disponível no host, apenas com autorização aplicável, e forneça contexto autocontido. Onde não houver despacho, leia o papel como instrução local.

Nunca passe uma skill como tipo de subagent. A identificação pelo prefixo numérico é específica do caminho do kit e não substitui o catálogo de ferramentas do host. Ver docs/skill-guides/agent-compatibility.md.