claude-skills-fv: Instructions file for Codex

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

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

Atalhos por fase de desenvolvimento — use em vez de lembrar nomes de skills:

Command	O que faz
/spec	Especificar feature com critérios de aceitação
/plan	Classificar task e montar pipeline
/build	Implementar com stack do projeto
/test	Escrever e rodar testes
/review	Review final + security audit
/simplify	Simplificar e refatorar código
/ship	Release e deploy
/pipeline	Pipeline completo end-to-end
/best	Auditoria de boas práticas, clean code e DRY
/auto	Agente autônomo — executa task completa sem intervenção
/loop	Loop autônomo v2 — multi-agente (claude/codex), worktree paralelo, polishing pass (node scripts/auto-loop.mjs "task")
/worktree	Cria git worktree isolado, copia .env*, valida ambiente em background
/detective-spec	Engenharia reversa de specs em legado — extrai contratos sem tocar no código (skill 33)
/catalog-project	Sintetiza repo-audit + detective-spec + narrativa de produto (resumo/planos/FAQ) + histórico de sessões + dados operacionais (envs/endereços/métricas) em .project-memory/manifest.yaml versionado no repo consumidor — tudo sempre rastreável a evidência, alimenta o catálogo cross-repo project-brain
/grill-me	Interrogatório relentless de plano até convergência (uma pergunta + resposta sugerida por turno)
/to-prd	Converte conversa atual em PRD publicado no issue tracker (label needs-triage)
/to-issues	Quebra PRD em N issues independentes (vertical slices) e publica no tracker
/pipeline-discovery	Pipeline COMPLETO discovery: grill-me → to-prd → to-issues → loop+TDD → ship
/constitution	Bootstrap/update memory/constitution.md com princípios governantes (Code Quality, Testing, UX, Performance, Security)
/checklist	Checklist contextual por feature ("unit tests for English") — Completeness, Clarity, Consistency, Coverage, Edge Cases
/analyze	Cross-artifact consistency check (read-only) entre constituição → spec → plan → issues. CRITICAL bloqueia /build
/humanize	Remove os 29 padrões de AI-generated writing de qualquer prosa (docs, PRDs, copy, changelogs)
/consolidate-memory	Manutenção do vault de memória persistente — merge duplicatas, archive stale, prune índice. Workflow seguro com snapshot
/savings	(v2.4.0) Mostra o que o kit salvou na sessão/janela: tokens economizados, USD, riscos prevenidos, hot files, decisões do gate. Auditoria em policies/savings-metrics.md. Mini-resumo automático no Stop hook.
/drift-scan	(v2.5.0) Continuous drift detection contra todo o codebase: dead-code, large-files, stale-todos, dep-staleness, doc-code drift, test-coverage. Inspirado em Birgitta Böckeler — ver docs/inspiration/harness-engineering.md.
/context-budget	(v2.26.0) Audita peso de contexto carregado na sessão: skills/agents/MCP/rules/CLAUDE.md — tokens estimados por componente, headroom disponível, alertas de overflow. Distinto do /savings (que rastreia completions runtime).
/spec-kit	(v2.28.0) Pipeline SDD unificado: specify → plan → tasks → implement com checkpoints explícitos e Adversarial Verifier inline. Inspirado no GitHub Spec Kit (88k stars). --phase specify / --phase plan / --skip-checkpoints para CI.
/insights	(v2.28.0) Recomendações baseadas em uso real: lê JSONLs de telemetria dos hooks (gate decisions, investigate-first bloqueios, tool repetitions, conflict-resolutions) e recomenda o que calibrar. Similar ao /Insights nativo mas lê dados do kit.
/run-program	Executa pipeline declarativo YAML (programs/*.yml) com 7 step types (command/prompt/bash/gate/loop/parallel/conditional), context: fresh per step, provider/model routing, trigger_rule para parallel. 6 programs: pipeline-discovery, spec-driven-development, loop-polishing, detective-spec, adversarial-dev (GAN), comprehensive-review (5-agent parallel)
(auto)	Auto-orchestration (v1.8.0): hook intent-classifier sugere program adequado baseado em intent do prompt. Skill 39 (program-router) confirma. 4 níveis de autonomia em policies/auto-orchestration.md
/swarm	TOTAL AUTONOMY (v2.0.0): do prompt ao PR mergeable. Worktree isolado + Ralph loop (fresh context per story) + 4-agent parallel review + self-fix CRITICAL/HIGH + auto PR. Em modo Autonomous (Nível 3), o hook auto-roteia features pra /swarm. Inspirado em Ralph/fix-issue/comprehensive-review do archon.
(via /run-program)	refactor-safely (v2.1.0): pipeline com behavior preservation — baseline tests + analyze read-only + atomic plan + execute com type-check hooks + verify + PR. Use pra refactor de módulos grandes.
(doc)	docs/USE-CASES.md (v2.1.0): mapeia 17 cenários de dev no dia-a-dia → comando apropriado. Hook intent-classifier v2 roteia auto baseado nesses cenários.