Auxiliares
Agentes auxiliares persistentes para pesquisa, auditoria, qualidade e orquestração, com contratos de frontmatter e protocolos de isolamento de implantação.
Os auxiliares persistentes ficam como arquivos planos no diretório canônico de
auxiliares, com o sufixo <name>.md. O caminho canônico é:
src/apothem/agents/Cada auxiliar é um papel específico, como pesquisa, auditoria, qualidade, refatoração ou criação de esqueletos, com suas próprias restrições de ferramentas e seu próprio prompt de sistema.
A tabela e a lista de caminhos abaixo mostram quatro dos auxiliares. O inventário gerado no final desta página lista todas as definições de auxiliares.
| Auxiliar | Arquivo | Padrão | Política de modelo |
|---|---|---|---|
| Codebase Explorer | veja o caminho do manifesto abaixo | Pesquisa | selecionado pelo host |
| Convention Auditor | veja o caminho do manifesto abaixo | Auditoria | selecionado pelo host |
| Quality Gate | veja o caminho do manifesto abaixo | Qualidade | selecionado pelo host |
| Memory Auditor | veja o caminho do manifesto abaixo | Auditoria | selecionado pelo host |
Caminhos canônicos dos manifestos:
src/apothem/agents/codebase-explorer.md
src/apothem/agents/convention-auditor.md
src/apothem/agents/quality-gate.md
src/apothem/agents/memory-auditor.mdContrato de frontmatter
---
name: <agent name>
version: <semver>
updated: <YYYY-MM-DD>
description: <one-line role>
tools: <comma-separated tool list>
disallowedTools: <comma-separated deny list>
maxTurns: <integer>
---tools é opcional. Um auxiliar que o omite herda todas as ferramentas que a sessão tem,
incluindo as ferramentas MCP conectadas, e disallowedTools carrega o seu limite. Todos os
catorze auxiliares entregues listam tools.
Servidores MCP conectados
Um auxiliar que lista tools só pode chamar o que lista. O Claude Code admite uma
ferramenta MCP nessa lista somente quando a entrada nomeia o servidor, como em
mcp__<server>__*; um mcp__* isolado é documentado como entrada de disallowedTools
e em nenhum outro lugar. Os nomes de servidores pertencem à pessoa que os conecta, então um
auxiliar entregue não pode nomeá-los.
citation-auditor e research-scout consultam fontes acadêmicas. Cada um é entregue com
tools: Read, Glob, Grep, WebSearch, WebFetch e nega as ferramentas que gravam
arquivos, executam comandos, iniciam outros auxiliares ou publicam: Write, Edit,
MultiEdit, NotebookEdit, Bash, PowerShell, Monitor, Agent,
Artifact e as ferramentas de lista de tarefas. Sem nenhuma configuração no perfil, nenhum dos dois alcança uma
ferramenta MCP, e ambos consultam fontes por meio de busca na web e obtenção de páginas da web.
Para dar a um deles um índice acadêmico conectado, nomeie o servidor na
chave agent_mcp_servers do perfil, que mapeia um nome de agente para nomes de servidores. A
instalação pelo motor do Claude Code (apothem install) então acrescenta uma
entrada mcp__<server>__* por servidor nomeado à linha tools desse agente e
não altera nenhum outro agente. A instalação do Gemini CLI faz o mesmo com uma
entrada mcp_<server>_* por servidor na lista de permissões tools do agente, para um nome de
servidor composto de letras, dígitos e -. Em ambos, um servidor que o próprio
disallowedTools do agente nomeia continua negado. A entrada admite todas as ferramentas desse servidor, incluindo
as que gravam, então nomeie somente um servidor em que você confia para consultas: as
instruções dos auxiliares os limitam a chamadas de busca, consulta, leitura, verificação e resolução, mas
o harness impõe apenas os nomes que a linha tools lista. Um nome para um agente
que não existe, ou que não tem uma linha tools explícita, é relatado e
ignorado.
Harnesses que não sejam o Claude Code e o Gemini CLI ignoram a chave. A árvore do plugin do Claude Code é montada sem
um perfil e mantém a lista simples, então um usuário do plugin define um agente de nível de usuário
em ~/.claude/agents/ em vez disso. A sintaxe do perfil, as regras de nomes de servidores e
essa solução alternativa estão em
Dar a um auxiliar acesso a servidores MCP.
Conversão por harness
Um auxiliar cuja concessão tools, depois de aplicado disallowedTools, não
inclui nenhuma ferramenta de edição de arquivos (Write, Edit, MultiEdit ou
NotebookEdit) é somente leitura. Um auxiliar
sem concessão tools é somente leitura quando disallowedTools nega pelo menos
Write e Edit. Cada harness que converte auxiliares aplica
esse limite nativamente, o declara nas instruções do auxiliar ou remove o rótulo de somente leitura:
| Harness | Limite de ferramentas | Limite de turnos | Modelo e esforço |
|---|---|---|---|
| Claude Code | tools / disallowedTools conforme escritos, mais as entradas mcp__<server>__* que a chave agent_mcp_servers do perfil acrescenta a uma linha tools listada; sem tools, todas as ferramentas são herdadas, incluindo as MCP | maxTurns | herdado (não definido) |
| Codex | nenhum emitido; as instruções do auxiliar o declaram, e o sandbox da sessão pai governa as gravações | não disponível | herdado (não definido) |
| Gemini CLI | lista de permissões tools com nomes de ferramentas do Gemini, mais as entradas mcp_<server>_* que a chave agent_mcp_servers do perfil acrescenta a uma lista explícita listada; sem tools, a lista de permissões que as negações implicam mais mcp_* | max_turns | herdado (não definido) |
| Qwen Code | tools / disallowedTools com nomes de ferramentas do Qwen; sem tools, nenhuma lista é emitida, de modo que as ferramentas MCP são herdadas e as negações se aplicam | não mapeado | model: inherit |
| OpenCode | permission (allow / deny por ferramenta); as ferramentas MCP não são restringidas | não mapeado | herdado (não definido) |
| Antigravity | nenhum emitido; a descrição remove "somente leitura" | não disponível | herdado (não definido) |
| CodeBuddy | tools / disallowedTools como strings separadas por vírgulas, limitadas aos nomes de ferramentas que o CodeBuddy documenta; nenhuma entrada MCP | maxTurns | herdado (não definido) |
| Trae | tools / disallowedTools como strings separadas por vírgulas, limitadas aos nomes de ferramentas que o Trae documenta; nenhuma entrada MCP | não disponível | herdado (não definido) |
| GitHub Copilot | lista de permissões tools de aliases do Copilot (read, search, edit, execute, web, agent, todo) com as negações incorporadas, porque o Copilot não tem chave de negação; um alias que abrange uma ferramenta negada fica de fora; nenhuma entrada MCP | não disponível | herdado (não definido) |
| Cursor | nenhuma lista de ferramentas (o Cursor não tem uma); readonly: true para os cinco auxiliares somente leitura sem Bash, e os demais auxiliares somente leitura removem o rótulo "somente leitura" | não disponível | herdado (não definido) |
| Kimi Code | tools / disallowedTools como listas de nomes de ferramentas do Kimi Code (WebFetch vira FetchURL, TodoWrite vira TodoList; nomes para os quais o Kimi Code não tem ferramenta ficam de fora); nenhuma entrada MCP | não disponível | herdado (não definido) |
| Kiro | lista de permissões tools de categorias de ferramentas do Kiro (read, write, shell, web, subagent) com as negações incorporadas, porque a lista é a única restrição gravada; uma categoria que abrange uma ferramenta negada fica de fora; nenhuma entrada MCP | não disponível | herdado (não definido) |
| Windsurf | lista de permissões allowed-tools de nomes de ferramentas do Devin (read, edit, grep, glob, exec, write) com as negações incorporadas, porque o Devin não tem chave de negação; os três auxiliares que precisam de ferramentas web não são instalados; nenhuma entrada MCP | não disponível | modelo de subagente padrão do Devin (não definido) |
Hermes e Open-Claw recebem os arquivos de auxiliares como material de suporte, não como auxiliares nativos.
Orquestração
A implantação de auxiliares, o protocolo de disparo em paralelo, a aplicação do contrato de retorno e a disciplina de isolamento ficam na regra de orquestração. A árvore de despacho por trabalhador fica na regra de padrões de orquestração, §Decision Tree. Caminhos canônicos:
src/apothem/rules/agent-orchestration.md
src/apothem/rules/agent-orchestration-patterns.mdInventário de agentes gerado
| Name | Description | Source |
|---|---|---|
README | Persistent agent definitions — the reusable sub-agent specifications the harness materializes whenever the orchestrator deploys a research, audit, or quality team. Each agent is a | src/apothem/agents/README.md |
citation-auditor | Read-only citation audit — checks that each reference in a bibliography or cited passage exists, matches its record, and that the opened source states what the text attributes to it. Use when a draft cites sources: 'check my references', 'are these DOIs real', 'does this paper say what I cite it for'. Finding new sources routes to research-scout; a free-standing claim routes to fact-checker. | src/apothem/agents/citation-auditor.md |
codebase-explorer | Read-only codebase exploration — exhaustively find every instance of a pattern, trace call/import dependencies, discover host conventions, map architecture and layering. Use when the query is 'where is X used', 'find all callers of Y', 'what convention does this repo follow for Z', 'map the module structure', or 'trace what depends on this file' — never for edits or design, and never for review verdicts (architecture-review, code-audit). Works through Grep / Glob / Read plus read-only Bash and returns evidence-cited findings (path + line + snippet) exhaustive within the declared scope; reports gaps rather than guessing. | src/apothem/agents/codebase-explorer.md |
convention-auditor | Read-only conventions auditor: verify naming (kebab-case files, snake_case Python, frontmatter keys), cross-reference resolution (dead rule/skill/agent paths, broken anchors, half-edge bindings), formatting standards (SPDX header presence, frontmatter contract), and ecosystem coherence (orphan artifacts, sibling-convention drift, registry gaps). Dispatch when a change touches multiple rules/skills/agents/commands and you need a binary PASS/FINDING verdict per instance with file+line+expected+actual evidence — e.g. 'audit naming across the harness adapters', 'check every new rule resolves its Bindings cross-refs', 'verify the skills cohort matches the kebab-case + SKILL.md convention'. Read-only: never fixes, never runs shell. A whole-tree sweep, or any fix, is the ecosystem-audit skill. Conventions are owned upstream and verified against, never re-derived; every finding cites severity + evidence. | src/apothem/agents/convention-auditor.md |
dependency-auditor | Read-only dependency-tree risk audit — flags unpinned, stale, duplicate, and known-vulnerable dependencies with manifest/lockfile evidence. Dispatch within a dependency audit, before a release cut, or after adding a dependency; one named CVE or advisory routes to the vuln-triage skill, and a signing or provenance review to the supply-chain-audit command. Detects the ecosystem via host-discovery: npm (package.json + package-lock/yarn/pnpm), pip (pyproject/requirements + lock), cargo (Cargo.toml + Cargo.lock), go (go.mod + go.sum). Runs npm audit / pip-audit / cargo audit / govulncheck and returns a risk-ranked table (known-vulnerable → unpinned → duplicate → stale) with per-row evidence; never widens a pin or escalates a scope — gaps surface as inquiry. | src/apothem/agents/dependency-auditor.md |
design-critic | Read-only UI critique. Use for a design review, a usability or accessibility check, or 'what is wrong with this screen' before a UI ships. A WCAG sweep across a whole web surface routes to the a11y-audit command; a CLI or install-flow review to ux-review. Reviews code, screenshots, or a running page and returns fixes ranked by user impact, from a scored heuristic review and separately measured evidence. Opens with a degraded notice when measurement tooling is missing; never guesses a measurement. | src/apothem/agents/design-critic.md |
fact-checker | Read-only adversarial claim verification — decompose input into atomic claims, seek ≥2 independent sources, attempt refutation, assign cited verdicts (supported / refuted / unverifiable) with quoted evidence and confidence. Use when a claim needs proof before it ships: a benchmark or statistic in docs/copy, a 'X is faster/safer than Y' assertion, a citation that names an RFC or spec, a release note, or any factual claim a reviewer would challenge. Routes external claims through WebSearch / WebFetch and repository claims through Read / Glob / Grep; defaults to refuted-or-unverifiable when evidence is insufficient, never a charitable supported. | src/apothem/agents/fact-checker.md |
mcp-builder | Scaffold a Model Context Protocol (MCP) server skeleton from a tool/resource contract — contract-first, well-typed tools, minimal surface. Use when: 'build an MCP server for <API>', 'scaffold MCP tools from this spec', 'wire FastMCP/TypeScript-SDK tool definitions', 'add a tool that exposes <resource> over MCP'. Detection: tool names + argument shapes + return types + resource URIs are stated or derivable. Selects the SDK via host-discovery (FastMCP for Python, the TypeScript SDK for Node), emits one typed tool definition per contract entry plus a list-tools smoke test, and scaffolds nothing speculative. Not for: tuning, securing, or load-testing an existing server (those surface as adjacent gaps). | src/apothem/agents/mcp-builder.md |
memory-auditor | Read-only memory-file auditor: cross-reference every claim in the harness memory tier (MEMORY.md index + topic files under <harness-root>/projects/{hash}/memory/ and <harness-root>/memory/) against actual filesystem state — file/line/rule counts (glob and count), referenced paths (do they exist?), rule scope labels (match pathFilter frontmatter?), dates (against frontmatter updated: or mtime, never the system clock), and cross-reference matrices. Dispatch when MEMORY.md or a topic file may have drifted from reality and you need a per-claim PASS/FAIL verdict with contradicting evidence — e.g. 'audit MEMORY.md after the rules cohort was renamed', 'verify the memory index counts match the current ecosystem', 'check the debugging topic file for stale references to deleted artifacts'. Existence + name match only; never re-audit an artifact's internal correctness (convention-auditor's scope). Read-only: never writes, never fixes. | src/apothem/agents/memory-auditor.md |
prompt-evaluator | Read-only rubric scoring of a prompt's output set — score each output against each named criterion (PASS/FAIL with cited evidence), aggregate per-criterion pass-rate, flag regressions against a baseline, and name recurring failure modes. Use when prompt or model outputs need a reproducible verdict before they ship: comparing a reprompted variant against the prior version, gating a system-prompt change, judging an LLM-as-judge eval set, scoring few-shot outputs against acceptance criteria, or proving a quality claim a reviewer would challenge. Scores outputs that already exist: building the dataset, scorer or runner routes to the eval-harness skill, and a full campaign to the eval command. Requires an explicit rubric — an absent or underspecified rubric blocks scoring and routes as inquiry; never invents a criterion or threshold, never scores charitably. | src/apothem/agents/prompt-evaluator.md |
quality-gate | Read-only quality-gate runner — discovers the host's lint / type-check / test / security / build commands, runs them in the correct order (build → type-check → tests+lint+security in parallel), and returns a per-gate PASS/FAIL verdict with file+line+error evidence. Reports, never fixes. Dispatch as a Quality team before a release cut, after a multi-file change, or to confirm a fix is green — e.g. 'run the full quality matrix and tell me what fails', 'gate this branch before I push', 'is the test suite green and the types clean?'. Runs the whole matrix; tests alone route to test-runner. Detects tooling via host-discovery (ruff/eslint/markdownlint, mypy/tsc/pyright, pytest/jest/cargo test/go test, bandit/npm audit/gitleaks); never assumes a stack. | src/apothem/agents/quality-gate.md |
refactor-surgeon | Scoped, behavior-preserving refactor of a named target — extract the behavioral contract, re-derive clean-room (never edit in place), name the one deficiency removed, verify regression via the host's own tests. Dispatch as a delegated team member on a single named target with a clear refactor intent; a user-driven interactive extraction is the refactor-extract skill — e.g. 'consolidate the duplicated validation in the CLI's install module', 'untangle the nested conditionals in the config renderer without changing output', 'rename the god-object methods in the adapter class to reveal intent'. Touches only the named target; adjacent gaps surface as findings, never as edits. Behavior, contracts, and side effects are identical before and after; a behavior change is a defect. | src/apothem/agents/refactor-surgeon.md |
research-scout | Read-only source discovery and ranking — decompose a research question into facets, fan out parallel web queries, rank candidates by authority, recency, and relevance, and return a deduplicated ranked source list. Use when a question needs sources before it can be answered: 'find the authoritative spec/RFC for X', 'what are the primary sources on Y', 'gather current references for a docs/copy claim', 'survey the landscape before a deep dive'. Fans external facets through any scholarly index server the operator has granted it, WebSearch, and WebFetch, and any in-repo corpus through Read / Glob / Grep. Also looks up papers and preprints by DOI, arXiv id, or topic ('find the paper behind this DOI'), and scouts existing open-source projects before anything new is built ('is there already a library for this', 'adopt or fork'). Discovery and ranking only — never fabricates a URL, never synthesizes; a written cited report routes to the multi-source-research skill, claim verification to fact-checker, and combining given documents to source-synthesis. | src/apothem/agents/research-scout.md |
security-scanner | Read-only secret, SAST-pattern, and config-risk sweep — a coarse first-pass that surfaces candidates fast and routes deep scanning to the host's CI scanners. Dispatch inside a security audit, after touching auth/crypto/IO surfaces, or when a secret may have been committed; a full repository security audit routes to the security-audit command. Greps for credential literals (key/token/password/private-key/certificate, committed .env values), injection surfaces (shell=True on untrusted input, string-formatted SQL, command interpolation), unsafe-eval (eval/exec/Invoke-Expression), unsafe deserialization (pickle.loads, yaml.load without SafeLoader), and config risk (over-broad CI permissions:, unpinned Actions uses:, network egress). Routes known-vulnerable dependencies to the dependency-auditor agent, CVE/advisory triage to the vuln-triage skill, and leaked-credential rotation to the secret-rotation skill. | src/apothem/agents/security-scanner.md |
test-runner | Read-only test-suite runner — discovers the host's test command, runs it, and triages every failure by root cause with test+file+line+assertion evidence. Reports, never fixes. Dispatch as a Research/Quality team member after a code change, before a release cut, or to confirm a fix is green — e.g. 'run the tests and tell me what's failing and why', 'is the suite green on this branch?', 'triage the failures in the auth module'. Tests only: lint, type and security gates route to quality-gate. Detects the runner via host-discovery (pytest/jest/cargo test/go test/Makefile target from the manifest + CI config); never assumes pytest. | src/apothem/agents/test-runner.md |
Comandos
Definições de comandos de barra que implementam o pipeline da suíte de planejamento, além de auditorias de código, arquitetura, segurança, dependências e revisão de documentação.
Hooks
Manipuladores de eventos de ferramentas que disparam em SessionStart, PreToolUse, PostToolUse e Stop, carregando contextos de mensagem que impõem o isolamento do git e a disciplina de planos, com um contrato de tempo de execução testado e estado por usuário.