EdwardAstill/agentfiles

Missão (para agentes)

Este repositório é um harness de agente orientado a crescimento. Cada tarefa é uma oportunidade para melhorar o próprio sistema — mas adicione algo apenas se servir absolutamente a um propósito e for o melhor caminho para atingi-lo. Inchaço é uma falha de primeira ordem: wrappers sobre comandos existentes, documentações que repetem outras documentações, CLIs com apenas um chamador razoável. Antes de adicionar algo novo, pergunte: essa capacidade já existe? Um simples rg / cat / touch é suficiente? Se sim, não adicione.

Quando descobrir algo que vale a pena lembrar, anexe com af note ou crie um arquivo diretamente em research/lessons/. As skills de pesquisa existem para que o sistema possa aprender sozinho — use-as antes de recorrer a suposições.

Antes de planejar mudanças arquiteturais, consulte o conhecimento do agente

research/knowledge/ é a memória de longo prazo do projeto — a saída destilada de tudo em research/ (artigos, projetos, documentação, lições). Antes de propor mudanças no harness, orquestração ou sistema de skills, verifique o que já foi pesquisado:

af ak list                           # índice das páginas de research/knowledge/
af ak show <slug>                    # ler uma página
af ak grep "<pattern>"               # busca em texto completo dentro de knowledge/
rg "<pattern>" research/             # busca em toda a árvore de pesquisa (entradas brutas também)
af archetype match "<user intent>"   # esta tarefa corresponde a um formato conhecido?

Se uma página de conhecimento já cobrir o assunto, construa sobre ela em vez de redescobrir. Se uma lição contradizer o que você está prestes a fazer, pare e reconcilie.

Ciclo semanal de melhoria

A maquinaria de auto-melhoria só se acumula se alguém a executar. Agende af log review + af skill-usage summary semanalmente (cron ou lembrete de calendário) e aja com base na saída:

# ~/.config/systemd/user/... ou crontab -e
0 9 * * 0  /home/you/.local/bin/af log review >> ~/.claude/logs/reviews/$(date +\%F).md

Após a revisão, examine:

• ~/.claude/logs/observations.md — anomalias e lições esboçadas por af log review. Promova qualquer padrão recorrente para uma edição de skill ou uma página de conhecimento (veja a regra de promoção em research/knowledge/README.md).
• af skill-usage summary — a lista "nunca carregado" informa o que é peso morto no catálogo; "principais cadeias de despacho" sugere candidatos a fios de gatilho.

Se duas semanas consecutivas não produzirem nada que valha a pena ser posto em prática, isso ainda é sinal — registre a "revisão sem ação" em research/lessons/ para evitar superajuste do ritual.

---

agentfiles — Orientação para Claude Code

Este repositório é a fonte da verdade para uma suíte pessoal de skills do Claude Code. As skills são vinculadas simbolicamente (symlinks) para ~/.claude/skills/ (nível de usuário) ou .claude/skills/ (nível de projeto) via af install.

Comandos de Barra (Slash Commands)

Skills usam a forma /nome-da-skill (ex.: /git-expert, /brainstorming). Essas são a sobreposição manual — use-as quando você souber exatamente o que quer. Caso contrário, o executor cuida do roteamento automaticamente.

Para uso diário você não precisa digitá-las — using-agentfiles é acionado no início da sessão e o sistema roteia através do executor automaticamente.

Qual Skill Quando

Situação	Skill
Nova tarefa (padrão)	executor
Nova funcionalidade / componente / design	brainstorming primeiro, depois executor
Bug ou comportamento inesperado	systematic-debugging
Base de código desconhecida	codebase-explainer
Plano de implementação a executar	writing-plans → subagent-driven-development
Trabalho em Python / TypeScript / Rust / Typst	python-expert / typescript-expert / rust-expert / typst-expert
Design ou revisão de API	api-architect
Schema de banco de dados / migrações / consultas	database-expert
Auditoria de segurança	security-review
Problemas de performance	performance-profiling
Reestruturação em larga escala	refactoring-patterns
Docker / K8s / Terraform	infrastructure-expert
Atualizações de dependências / varredura de CVEs	dependency-management
Logging / tracing / métricas	observability
Acessibilidade web	accessibility
Operações Git / worktrees	git-expert / git-worktree-workflow
PRs, issues e Actions do GitHub	github-expert / github-actions-expert
"Como uso X?" — consulta de API	docs-agent
"Devo usar X?" — trade-offs	research-agent
Responder perguntas a partir de material de referência	test-taker
Escrever anotações ou lições interativas	readrun
Trabalho paralelo com múltiplos agentes	manager
Criar ou editar uma skill	writing-skills

Fatos Chave

• Skills residem em agentfiles/<categoria>/.../<nome-da-skill>/SKILL.md — quatro categorias: management/, planning/, coding/, research/
• Cada categoria tem um despachante em agentfiles/<categoria>/SKILL.md que roteia para a skill folha correta
• Execute af agents --tree para ver a hierarquia completa ativa
• Documentação regional em agentfiles/<categoria>/REGION.md — o manager as lê durante o planejamento
• Instalação: ./install.sh (inicialização), depois af install (instalação completa). Ou ./bootstrap.sh para máquinas novas.
• CLI: af <subcomando> — CLI Python em tools/python/src/af/, instalado via uv tool

Formato do Arquivo de Skill

---
name: nome-da-skill          # minúsculas, apenas hífens
description: >
  Use quando [condições de acionamento]. Mantenha abaixo de 1024 caracteres no total.
  Isto é o que o Claude lê para decidir se deve invocar a skill.
---

O campo description é a única coisa visível para outras skills sem invocar esta skill. Escreva-o de forma inequívoca sobre quando acioná-la.

Regra de Sincronização de REGION.md

Sempre que uma nova skill folha for adicionada ou removida, atualize o REGION.md da sua categoria.

Documentações regionais (agentfiles/<categoria>/REGION.md) são os catálogos de skills que o manager lê durante o planejamento. Cada entrada usa o formato de cabeçalho ### nome-da-skill. Se elas divergirem da realidade, o manager fará um planejamento incorreto.

Execute af check antes de commitar qualquer alteração em agentfiles/ para verificar se todas as skills folha têm entradas no REGION.md da sua categoria.

manifest.toml

Declara os requisitos de ferramenta por skill e quais entradas bin instalar. Atualize-o quando:

• Adicionar uma nova skill com requisitos de ferramenta
• Adicionar uma nova entrada bin
• Alterar os requisitos de ferramenta de uma skill

[skills.nome-da-skill]
tools = ["Bash", "Read"]   # nomes de ferramentas do Claude Code
mcp = ["context7"]         # nomes de servidores MCP (opcional)

Adicionando uma Nova Skill — Lista de Verificação

• Decida qual categoria: management/, planning/, coding/ ou research/
• Crie agentfiles/<categoria>/[sub-categoria/]<nome-da-skill>/SKILL.md com frontmatter válido
• Adicione a pasta scripts/ se a skill precisar de scripts auxiliares
• Adicione entrada em manifest.toml sob [skills.<nome-da-skill>]
• Adicione entrada no agentfiles/<categoria>/REGION.md sob ### nome-da-skill
• Execute af install (o symlink será detectado na próxima sessão)

Notas de Arquitetura

Orquestração de dois caminhos:

• executor — ponto de entrada padrão para cada nova tarefa. Orienta-se com af context/af status, toma a decisão de roteamento inline, então lida com a tarefa de ponta a ponta. Absorve skills especialistas inline via a ferramenta Skill. A verificação é OBRIGATÓRIA antes de relatar conclusão. Escalona para o manager com um bloco estruturado HANDOFF CONTEXT quando o trabalho paralelo é genuinamente necessário.
• manager — apenas para trabalho genuinamente multi-agente. Lê o contexto de handoff do executor, executa uma passagem de revisão de planejamento (design? estratégia de git? coordenação?), despacha agentes, depois revisa os resultados com replanejamento adaptativo se os agentes falharem. Consultores (design-advisor, git-advisor, coordination-advisor) são carregados inline apenas quando a decisão relevante não é óbvia.

Especialistas são bibliotecas de skills, não destinos de roteamento. Eles são carregados inline pelo executor com Skill("nome"). São despachados apenas como subagentes quando o manager precisa explicitamente de trabalho paralelo em domínio.

O git expert gera um bloco WORKTREE CONTEXT — outras skills devem procurar por isso quando precisarem saber onde fazer alterações.

Skills são independentes — cada skill funciona de forma autônoma. Os orquestradores adicionam coordenação sobre elas, não as substituem.

Instalação

Instalação em duas etapas:

1. Inicialização (./install.sh): instala a CLI af e a skill agentfiles-manager globalmente. Mínima — sem seleção de skills, sem ferramentas CLI.
2. Instalação completa (af install): instala todas as skills, hooks e ferramentas CLI. Suporta --global (padrão), --local, --skill, --category, --remove, --dry-run.

Dois modos:

• Modo A — tudo global: ./install.sh && af install instala todas as skills globalmente. Funciona em todos os projetos sem configuração por projeto.
• Modo B — apenas manager: ./install.sh instala apenas o manager. Então, em cada projeto, diga "configurar este projeto" e o agentfiles-manager seleciona e instala as skills relevantes localmente em .claude/skills/.

Usa symlinks, não cópias. Alterações nos arquivos de skill são refletidas imediatamente — sem necessidade de reinstalação.

O parser TOML do manifesto é um pipeline simples de awk/grep — mantenha o manifest.toml limpo e evite formatação incomum (comentários inline em linhas de valor, arrays multilinha, etc.).