@event4u/agent-config

Agent Config — toda afirmação verificada por máquina, incluindo as contagens nestes selos

_{Como estas contagens são feitas — um contador canônico, agent-config → update_counts --check, rederiva todos os seis a partir da árvore e falha no CI se houver desvio de um. Duas bases não são o que o diretório vinculado mostra, então são declaradas aqui em vez de deixadas para inferência: Commands 202 conta cada arquivo de comando recursivamente (o diretório vinculado contém 61 no seu nível superior), e Rules 121 conta as regras fonte enquanto a projeção vinculada contém 120 — uma regra está inativa e não é projetada. Personas 29 exclui o README do diretório. As contagens são de arquivos e diretórios: nenhuma delas mede qualidade, ativação ou adoção.}

Experimente em 30 segundos — coloque um único subagente somente-leitura em qualquer repositório e veja-o bloquear o "done": @production-validator check this branch is actually done. Sem assistente, sem dependência, nada mais instalado — a cunha de 30 segundos ↓ é todo o primeiro passo. Comece pela prova, não pelo catálogo: event4u-app.github.io/agent-config/proof/.

Toda afirmação pública neste README é verificada por máquina — verifique você mesmo. Em um mercado que vive de números de manchete sem comprovação, este vincula cada afirmação a evidências resolvíveis ou falha no próprio build.

Escolha sua experiência — desenvolvedor · fundador · conteúdo · agência · finanças · operações. Adicione pacotes. Obtenha um conjunto de comandos focado, não um despejo de 500 artefatos. Traga seu próprio provedor de IA.

Uma biblioteca profunda de skills, comandos e regras governadas — além de um roteador de capacidades que carrega a skill certa por intenção e orquestração multi-agente com revisão por consenso. Toda a camada é compilada em 20 agentes host — de 23 detectados, 3 sendo somente-exportação (Claude Code, Cursor, Augment, Cline, Windsurf, Copilot, Gemini CLI, Codex, Continue, Zed, JetBrains, Aider e mais). Processos residentes são permitidos apenas sob o contrato de supervisão que o ADR-249 estabelece — uma política que este repositório adotou em 2026-08-27, não uma descrição de nada em execução hoje. Seis caminhos de entrada moldados por papel ficam por cima, então qualquer host se torna um membro confiável da equipe — sem prendê-lo a um único modelo ou fornecedor.

Experimente em 30 segundos

Experimente uma coisa em 30 segundos — antes do pacote completo, adicione um único subagente autocontido e veja a disciplina no seu próprio repositório:

mkdir -p .claude/agents
curl -fsSL https://raw.githubusercontent.com/event4u-app/agent-config/main/docs/wedge/production-validator/production-validator.md \
  -o .claude/agents/production-validator.md
# then in Claude Code:  @production-validator check this branch is actually done

production-validator é somente-leitura e não instala mais nada — ele bloqueia o "done" caçando mocks/stubs no caminho de entrega e exigindo evidência de sistema real (o que ele faz). Gostou? O pacote completo instala com um comando — Quickstart ↓.

---

O que é diferente

Profundo e disciplinado, e honesto sobre o que deliberadamente não é:

• Profundidade que se roteia — um roteador de capacidades carrega a skill certa por intenção, não um despejo de contexto de 500 artefatos.
• Governança em todo host — regras compiladas no formato nativo de cada ferramenta no momento da projeção; hooks de runtime determinísticos adicionados em hosts com suporte a hooks. Essa governança agnóstica de host no espaço de configuração é o fosso (a vantagem da governança · aplicação por host).
• Desinstalação cirúrgica — remove apenas suas próprias chaves de uma configuração de host compartilhada (correspondidas por JSON-pointer + SHA-256), nunca as entradas de uma ferramenta vizinha.
• Instalação por pacote — grava apenas o pacote ativo, não um despejo de 500 artefatos.

O que deliberadamente não é — o núcleo é uma camada de governança com mecanismos embutidos opcionais e de adesão individual (inteligência de código, alcance controlado, a GUI de configuração, o laboratório de benchmark — ADR-124): nenhum daemon obrigatório ou sempre ativo, nenhum banco de dados de estado separado, nenhuma memória que se reescreve, nenhum pipeline de build automático. Mecanismos nunca são obrigatórios, nunca ativados por padrão sem ganho medido, e terminam com o comando que os invocou. O agente host executa o loop; toda mudança aprendida é revisada por humanos; a mesma camada permanece portátil entre ferramentas. Capacidade sem um processo para cuidar.

De onde isso vem (procedência honesta). As skills, regras e personas são destiladas de trabalho de produção real em codebases TypeScript e PHP. A mecânica de governança é agnóstica de stack, mas as heurísticas de domínio são mais ricas onde foram forjadas — trate a cobertura em outras stacks como promissora, não comprovada, e nos diga onde ela fica aquém.

Veja exatamente o que funciona em qual host ou pule para coisas que você pode fazer em um minuto.

Escolha seu perfil — seis caminhos de entrada

agent-config setup grava profile.id em .agent-settings.yml e envia você para a primeira tela desse perfil. Cada página de experiência traz o detalhe completo — para quem é, primeiros comandos e skills, pacotes e fluxos, e o que é deliberadamente não carregado.

Perfil	Público	Página de experiência
👩‍💻 developer	Engenheiro IC	página
✍️ content_creator	Escritores, ghostwriters, profissionais de marketing	página
🚀 founder	Fundador solo / em estágio inicial	página
🏛 agency	Agência de entrega multi-cliente	página
💼 finance	CFO / finanças fracionadas / FP&A	página
🛡 ops	RevOps, suporte, adjacente a SRE	página

Não sabe qual escolher? O assistente faz uma única pergunta de papel com 8 opções e mapeia para o perfil mais próximo. Fonte da verdade src/agent-src/profiles/ · schema docs/contracts/profile-system.md · além de software user-types/ (galabau · metalurgia · caminhão — veja Além de software).

Fluxos de trabalho, não comandos brutos

Você não memoriza comandos — você executa uma jornada de trabalho. Quatro fluxos cobrem a história do desenvolvedor de ponta a ponta:

Fluxo	Comece com	A jornada
🔍 Descoberta	/feature:plan · /research	explorar → planejar → estimar → refinar, antes de construir
🔨 Implementação	/work · /implement-ticket	planejar → implementar → verificar → commitar
🔎 Revisão	/review-changes · /judge	auto-revisão → julgar → corrigir qualidade → modelar ameaças
🚢 Entrega	/commit · /pr:create	commitar em partes → abrir PR → responder à revisão

Skills compostas e o caminho canônico por fluxo: docs/flows.md.

CHANGELOG · Upgrade para 14.x · Mudanças que quebram · Última versão · Discussões

_{Distribuição: npm install @event4u/agent-config. Versões principais seguem semver; cada uma traz uma entrada ### Breaking — todas as versões principais indexadas em BREAKING_CHANGES.md.}

---

Creative Pack — vídeo de IA cinematográfico. roteiro → imagem com personagem fixo → prompt de movimento+áudio → renderização do provedor → clipe costurado, com AIV_DRYRUN=true como padrão de segurança de custo. Uma capacidade de primeira classe dentro da experiência conteúdo / criador — não é mais o destaque do pacote. Veja /video:from-script.

Legal Pack — não é aconselhamento jurídico. O pacote jurídico UE/DE (revisão de contrato/NDA/DPA, triagem) é apenas um auxílio de pesquisa e redação — não fornece aconselhamento jurídico, não substitui um advogado qualificado e não deve ser usado como base para qualquer assunto concreto. Produz informações gerais e modelos gerais, nunca análise de caso individual. Leia LEGAL_NOTICE.md antes de usar.

Catálogo completo — toda skill, regra, comando, diretriz: docs/catalog.md. O destaque é a experiência (perfil + pacotes) e a profundidade por trás dela.

Use no seu projeto

Execute a partir de um repositório consumidor — inicialize via npx, o agente detecta sua stack e você entrega trabalho de ponta a ponta. Instalação nova? Comece pelo Quickstart. Já instalado? Ferramentas suportadas mostra as IAs conectadas; docs/featured-commands.md lista os fluxos de trabalho de ponta a ponta (/implement-ticket, /work, /commit, /pr:create). Tour mais profundo: demo de 2 minutos.

Escopo de instalação. Escolha um escopo por máquina — local ao projeto (padrão, recomendado para repositórios de aplicativos) ou global ao usuário (recomendado para repositórios de ferramentas / dotfiles). O instalador recusa um segundo escopo conflitante via pré-verificação scope_guard. Detalhes: docs/contracts/install-scopes.md. Limpeza quando necessário: bash src/scripts/cleanup_other_scope.sh --confirm.

Prove

Não aceite as afirmações por confiança — verifique-as. docs/proof.md é gerado a partir da fonte: uma tabela afirmação→evidência (toda afirmação pública vincula-se a um ponteiro resolvível ou o CI falha), benchmarks honestos de nulidade incluindo as execuções onde o pacote não mudou nada, e um bloco "verifique você mesmo" que você executa em um checkout novo. Ele falha no CI se desviar de suas fontes — reprodutibilidade é a prova. Leia em event4u-app.github.io/agent-config/proof/, com o quadro de comparação em docs/us-vs-the-category.md. Linha medida mais recente: em uma sessão pós-correção, a injeção de contexto consultivo reduziu violações de espelhamento de linguagem 555 → 19 enquanto os dois guardas bloqueadores foram 8 → 0 e 1 → 0 — consultivo reduzido massivamente, apenas bloqueio eliminado. Uma sessão e uma leitura post-hoc, então um registro anterior em vez de uma lei.

Mantém seu próprio catálogo de skills? O portão anti-reskin que bloqueia PRs de re-skin por localizar-e-substituir aqui também roda no seu — docs/anti-reskin-gate.md.

Disciplinado em auditoria por construção — toda consulta de memória, chave de decisão e preocupação de hook cai em agents/runtime/state/ para que você possa reproduzir. Princípios centrais nomeia os quatro invariantes.

Contribua

Trabalhando no próprio pacote? Desenvolvimento cobre o pipeline task ci, Requisitos a toolchain, Telemetria de mantenedor o loop de medição opt-in. A árvore fonte da verdade é src/ (src/skills, src/rules, src/agent-src/); nunca edite manualmente .augment/ ou dist/agent-src/.

Segurança. Política de divulgação: SECURITY.md. Modelo de ameaças: docs/threat-model.md.

---

Quickstart

Um comando. Orientado por detecção — suas ferramentas de IA instaladas são encontradas e pré-selecionadas. Nada é gravado até você clicar em Finish. Sem YAML manual.

Esses quatro são estruturais — propriedades do caminho de código, não da sua máquina. Quanto tempo leva não é: isso é dominado por latência de rede e registro. O CI mede o tempo de parede instalação → doctor em cada execução abrangente e publica com suas condições, como evidência em vez de promessa.

# 1. Install — on a terminal with a display, the browser wizard launches
#    automatically; the same TypeScript installer runs the real install behind it.
npx -y @event4u/agent-config init

# 2. Pick your profile + tools in the wizard, click Finish.
#    (Writes ~/.event4u/agent-config/, ~/.claude/, ~/.cursor/, …)

# 3. First real task — agent refines, plans, verifies.
/work "your first real task"

Headless / CI: init pula a GUI em CI, em um ambiente sem TTY, em um host headless ou com qualquer flag de modo CLI, e executa o instalador não interativo. A GUI e a CLI compartilham um único instalador (src/scripts/install.ts), portanto ambos produzem resultados idênticos. Flags, o conjunto completo de opt-out e --dry-run: docs/wizard.md · gui-wizard § Quando a GUI é pulada.

Escolher IAs específicas: --tools=claude-code,cursor,augment,… (qualquer subconjunto). --gui força o seletor vinculado a loopback e protegido por CSRF a passar pelas verificações de TTY e headless; ele não substitui CI, AGENT_CONFIG_NO_UI ou uma flag de modo CLI, e combiná-lo com uma dessas opções encerra com código de saída diferente de zero, em vez de executar silenciosamente a instalação via CLI.

Verificar cobertura de hooks: npx @event4u/agent-config hooks:status (--strict para CI, --format json para ferramentas).

Escopo (v2.5+): init grava apenas global — ~/.event4u/agent-config/, ~/.claude/, ~/.cursor/, …. A árvore do projeto recebe apenas agents/overrides/. --project é exclusivo do mantenedor, protegido por AGENT_CONFIG_DEV_MODE=1 (ADR-020, modo dev).

Migrando da v1.x? npx @event4u/agent-config migrate — docs/migration/v1-to-v2.md.

---

O que agent-config é — e o que não é

Uma camada de conteúdo — skills, regras, comandos, diretrizes, personas — distribuída via npm e projetada no formato de configuração nativo de cada ferramenta de IA suportada. Ela segue o padrão aberto Agent Skills.

Não é um runtime de agente. O loop do agente, o dispatcher de LLM e a orquestração de ferramentas permanecem com a ferramenta host (Claude Code, Augment, Cursor, Cline, Windsurf, Gemini CLI, Copilot). Pense nisso como um playbook e guia de estilo para essas ferramentas — não um substituto.

No escopo	Fora do escopo
Skills, regras, comandos, diretrizes, personas	Loop do agente / dispatcher de LLM
Projeção multi-ferramenta + pipeline de condensação	Motor de execução dentro do pacote
Auxiliares de memória (memory-add, memory-promote)	Painel de observabilidade entre ferramentas
Linters, CI, validação de frontmatter contra JSON-Schema (contrato)	GUI de runtime / painel web
Orquestração de skills via citações + auxiliares determinísticos	Resolvedor automático opinativo de skills (ranqueamento por ML / relevância que decide por você)
Filtragem no momento da projeção, orientada pelo usuário, por perfil + pacotes (ADR-040)	Um resolvedor / daemon de runtime (troca no meio da sessão — condicional, pós-6.0.0)

O que seu agente é solicitado a fazer

Comportamento padrão	Com agent-config
Adivinhar e editar às cegas	Analisar o código antes de alterá-lo
Desviar das convenções do projeto	Seguir convenções de stack detectadas
Pular ou inventar testes	Escrever testes no framework do projeto
Mensagens de commit genéricas	Conventional Commits com escopo + links de ticket
Pular verificações de qualidade	Executar o pipeline de qualidade do projeto e corrigir erros relatados
Abrir PRs sem contexto	Descrições estruturadas de PR a partir de Jira / Linear / GitHub
Alegar "concluído" sem prova	Verificar com execução real antes de alegar conclusão

---

Demonstração de 2 minutos — /implement-ticket

O comando principal. Conduz um ticket de ponta a ponta por um fluxo linear fixo — e bloqueia em ambiguidade em vez de adivinhar.

/implement-ticket PROJ-123

O agente executa esta sequência:

refine → memory → analyze → plan → implement → test → verify → report

• Refina o ticket se os critérios de aceite forem vagos.
• Consulta a memória para decisões passadas, invariantes, incidentes.
• Planeja a mudança; você confirma antes que qualquer arquivo seja tocado.
• Implementa sob minimal-safe-diff + scope-control — sem edições por impulso.
• Testa (direcionado primeiro, suíte completa em caso de sucesso).
• Revisa o diff por meio de quatro juízes (bugs, segurança, testes, qualidade de código).
• Relata mudanças, veredictos, acompanhamentos — e então para. /commit e /pr:create são sugestões, nunca executadas automaticamente.

Qualquer ambiguidade interrompe o fluxo com opções numeradas — nunca uma suposição silenciosa. A persona vem de .agent-settings.yml (roles.active_role): senior-engineer (padrão), qa ou advisory (somente plano).

→ Referência de comandos · Contrato de fluxo

Irmão — /work (prompt de forma livre)

Mesmo motor, sem necessidade de ticket:

/work add a CSV export endpoint to the audit-log controller

A primeira passagem pontua o prompt em cinco dimensões e roteia com base na faixa:

Faixa	Pontuação	Ação
alta	≥ 0.8	Prosseguir silenciosamente — AC + suposições no relatório
média	0.5–0.79	Interrompe com relatório de suposições; confirme ou edite
baixa	< 0.5	Interrompe com uma pergunta de esclarecimento sobre a dimensão mais fraca

Após o portão de faixa, o fluxo é idêntico ao /implement-ticket. Meta de forma livre → /work; payload de ticket → /implement-ticket.

→ Referência de comandos · skill refine-prompt

Após a execução: agent-config explain last reconstrói o rastreamento (rota · memória · conselho · interrupções · provedor) — somente leitura, com PII removida, offline. Docs

Trilha de UI de produto

Trabalho com formato de UI é roteado para um de três conjuntos de diretrizes — ui (auditoria completa→design→aplicar→revisar→polir→relatar), ui-trivial (≤ 1 arquivo, ≤ 5 linhas: aplicar→testar→relatar), mixed (backend + UI: contrato→ui→integrar). A auditoria de UI existente é um portão rígido (ui-audit-gate); o polimento tem um teto de 2 rodadas com precedência de a11y. Detecção de stack → blade-livewire-flux / react-shadcn / vue / plain.

→ Modelo mental (1 página) · Contrato de fluxo

---

Personalizar

Perfis — quanta governança é carregada

O piso de segurança (padrões não destrutivos · perguntar antes de adivinhar · espelhar o idioma do usuário) está incluído em todos os perfis. O que muda é quanto treinamento extra é incorporado.

Perfil	O que você obtém	Quando escolher
minimal	Apenas o piso de segurança inegociável. Mais barato, mais rápido.	Perguntas rápidas · scripts descartáveis · CI · orçamentos de token apertados
balanced (padrão)	Piso de segurança + treinamento diário (padrões sensatos, lembretes de revisão, armadilhas comuns).	Trabalho do dia a dia
full	Tudo, incluindo regras de cauda longa que normalmente apenas mantenedores precisam.	Trabalhando no agent-config em si · auditorias · demonstrações de máxima fidelidade

Nos bastidores: somente kernel · kernel + camada 1 · kernel + camada 1 + camada 2. Detalhes: rule-router · kernel-membership · Configurar →.

Estabilidade: STABILITY.md para a matriz completa. Work Engine (/work + /implement-ticket): beta. Runtime Dispatcher: estável. Tool Adapters: experimental (perfil full apenas).

.agent-user.md e Ghostwriter — primitivas de voz

Primitiva	Voz	Divulgação
personas/*.md	Lente de revisão (crítica interna)	n/a
.agent-user.md (raiz do projeto, gitignored)	A voz do próprio mantenedor — /post-as:me	Nenhuma (você é o autor)
agents/reference/ghostwriter/<slug>.md (gitignored)	Figura pública documentada — /post-as:ghostwriter	Rodapé obrigatório, não removível

Crie o arquivo de usuário interativamente: /agents user init (schema). Cluster Ghostwriter: /ghostwriter:fetch <url-or-name> executa um portão de atestação; indivíduos privados rejeitados; conteúdo pago / vazado / DM banido no nível do schema.

MCP auto-hospedado no Cloudflare — zero instalação local

Skills, comandos, regras e diretrizes podem ser servidos como um endpoint MCP a partir do seu próprio Cloudflare Worker, acessível via HTTP por qualquer cliente MCP. Dois modos de autenticação: public (padrão) e bearer-auth (opt-in do operador, segredo MCP-Token do Wrangler).

task mcp:cloud:login         # one-time, opens browser
task mcp:cloud:setup         # check → r2-create → r2-verify → whoami
task mcp:cloud:secret-put    # opt in to bearer-auth (recommended for private deploys)

→ Passo a passo do operador: mcp-cloud-setup · Configuração por cliente: mcp-client-config · Endpoints: mcp-cloud-endpoints.

Escopo — Lite, não Full. O Worker serve governança somente leitura (skills · comandos · regras · diretrizes · contextos) como prompts e recursos MCP, além de pequenas ferramentas somente leitura (memory_lookup, chat_history_read, list_*). Ele não executa os scripts locais do repositório (linters, auditorias, task ci, hooks do work-engine) — esses exigem instalação local conforme o Quickstart.

O servidor local stdio integrado está listado no Glama MCP Registry — ele requer um checkout local, não uma instalação turnkey (ADR-067).

Postura de implantação

Forma	Status	Caminho
Workspace de usuário único	✅ hoje	npx @event4u/agent-config init — máquina única, usuário único; sem sincronização remota
Pequena equipe (3–10 pessoas)	✅ hoje	Repo Git agents/overrides/ compartilhado + NAS compartilhado para conhecimento — sem mudança de código, sem novo servidor. Receita: docs/deploy/small-team-recipe.md
Modo organização (SSO · política central · contexto de equipe · conectores internos)	⏸ não iniciado	Cada forma condicionada a um cliente recrutado + auditoria financiada + ADR do mantenedor. Racional da postura: docs/deploy/team-deployment-posture.md

Recursos do modo organização (SSO, política central, conectores OAuth, contexto de equipe) permanecem cancelados por design até que um cliente recrutado e uma auditoria de segurança financiada os elevem; a receita de pequena equipe é o caminho suportado enquanto isso. Cada um é uma linha de cancelamento estável em team-deployment-posture.

---

Expectativas do harness

Três classes de comportamento de instalação/runtime parecem bugs de pacote e são comportamento do harness host que o pacote não pode controlar: namespaces de plugins irmãos, ferramentas adiadas expostas via ToolSearch, e deriva de skills entre escopos. Diagnósticos e a resposta do pacote: docs/contracts/harness-expectations.md. Quando uma skill aparece duas vezes, comece com task probe:skills.

Ferramentas suportadas

Instaladas no projeto (npx)

Ferramenta	Regras	Skills	Comandos	Como funciona
Claude Code	✅	✅	✅	Lê .claude/
Cursor	✅	—	☑️	Lê .cursor/rules/ + comandos via AGENTS.md
Cline	✅	—	☑️	Lê .clinerules/ + comandos via AGENTS.md
Windsurf	✅	—	☑️	Lê .windsurfrules + comandos via AGENTS.md
Gemini CLI	✅	—	☑️	Lê GEMINI.md
GitHub Copilot	✅	—	☑️	Lê .github/copilot-instructions.md
Roo Code	✅	—	☑️	Auto-descobre .roo/rules/*.md + AGENTS.md
Codex CLI	✅	—	☑️	Auto-descobre AGENTS.md
Continue.dev	✅	—	☑️	Auto-descobre .continue/rules/*.md + AGENTS.md
Aider	📌	—	—	read: manual em .aider.conf.yml
Augment (VSCode/IntelliJ)	📌	—	—	Somente global; o projeto grava marcador
Claude Desktop	📌	—	—	Somente global

✅ nativo   ☑️ referência de texto (em AGENTS.md, não invocável como slash-command nativo)   📌 apenas marcador   — não disponível

Reprodutibilidade da equipe: cada ferramenta que você init é registrada em agents/installed-tools.lock (commitado, gerenciado por máquina). Novos membros da equipe executam npx @event4u/agent-config sync após o clone; o CI limita a deriva com agent-config validate. Schema: installed-tools-manifest.

Instaladas via plugin (opcional, global)

Ferramenta	Instalação
Augment CLI · Copilot CLI	Instalar → — regras + skills + comandos, atualizados via marketplace

Claude Code: o plugin do marketplace está obsoleto (modelo de superfície única). A projeção de arquivos via npx/npm agora carrega conteúdo e os hooks determinísticos (registrados em um bloco ~/.claude/settings.json gerenciado por agent-config global / upgrade), então o plugin apenas duplica listagens de skills/comandos enquanto seu snapshot de SHA do git apodrece silenciosamente. Instalações existentes: claude plugin uninstall agent-config@event4u-agent-config — agent-config doctor sinaliza a superfície duplicada. Mantenha a instalação global atualizada com agent-config upgrade (mais recente) ou agent-config refresh --global (reinstalação da mesma versão); agent-config doctor sinaliza um binário ausente do PATH ou uma ligação de hook quebrada. Consulte getting-started § Mantendo-se atualizado · Solução de problemas.

A superfície de comandos de relance

Comando	O que faz
agent-config init	Instalação única — abre o assistente no navegador (caminho recomendado ou passo a passo)
agent-config init --project	Inicializa um projeto: ponte mínima agents/ + bloco gerenciado .gitignore
agent-config config	Abre a GUI de configuração — hub global de configurações (níveis simples e avançado, busca, restaurar padrão)
agent-config config --project	Abre a superfície de configuração do projeto
agent-config setup	Reexecuta o assistente de integração guiado (pré-preenchido com seu estado atual)
agent-config upgrade	Atualiza a instalação global para a versão mais recente + sincroniza configurações de forma aditiva
agent-config doctor	Relatório somente leitura de saúde/deriva

Superfícies Cloud / Agentes hospedados

Para plataformas onde os scripts do pacote não podem ser executados, os artefatos são construídos para colar ou enviar:

• Linear AI (Codegen, Charlie, …) — dist/linear/{workspace,team,personal}.md
• Claude.ai Web Skills — dist/cloud/<skill>.zip

→ Instalar →

---

Funciona com agent-switch

agent-switch é o CLI companheiro para executar várias contas de agente em uma máquina: ele isola cada conta em seu próprio perfil (CLAUDE_CONFIG_DIR por perfil), então alternar contas nunca significa sair e entrar novamente. Os dois se compõem — agent-switch isola as contas, agent-config governa o que os agentes fazem dentro delas. Quando agent-config é executado sob um perfil agent-switch, ele informa isso no hub de configurações, avisa antes de gravações que iriam para uma árvore compartilhada (entre perfis), e aceita uma raiz de configuração fornecida pelo host para que suas próprias configurações permaneçam no escopo do perfil.

→ Como os dois se compõem →

---

Para quem é isto

Um núcleo de governança agnóstico de stack (orquestração · modos de função · clusters de comandos · portões de qualidade · disciplina de auditoria), além de conjuntos de habilidades específicos de stack:

Stack	Cobertura
Laravel · PHP moderno (mais profundo)	Pest · PHPStan · Rector · ECS · Eloquent · Livewire/Flux · Horizon · Pulse · Reverb · Pennant
Symfony	symfony-workflow (DI · Doctrine · Messenger · voters · Twig) + análise de projeto
Next.js App Router	nextjs-patterns (RSC · Server Actions · caching · route handlers) + UI react-shadcn
Zend / Laminas	análise de projeto + habilidades compartilhadas de PHP coder/quality
React · Node / Express	análise de projeto + UI react-shadcn
Vue · HTML simples	conjunto de diretivas de UI (vue / plain)
Entre stacks	design de API · testes · segurança · banco de dados · Docker · Git · CI · revisão · modelagem de ameaças · observabilidade

Além do software

O mesmo núcleo de orquestração impulsiona ofícios não relacionados a software via user-types/: galabau-field-crew · metalworking-shop · truck-driver. Contribua com o seu — scaffold de 5 minutos.

---

Governança de dados e segurança de domínio

Três regras de segurança de domínio (domain-safety-pii, domain-safety-disclaimer, domain-safety-retention) atuam como pisos de saída por domínio em ~12 áreas — redação de PII (suporte / finanças / recrutamento / marketing), avisos de aconselhamento (jurídico / financeiro / médico / consultoria), orientação de retenção (finanças / suporte), pisos operacionais (logging / exportação). Matriz completa de superfície → regra → piso: docs/safety.md. Contratos beta: memory-visibility-v1 · decision-trace-v1.

Proveniência de código e governança de licença

Cada diff é verificado contra uma política de licença derivada da licença detectada do próprio repositório alvo (ordenada por precedência; fontes discordam → escalar, nunca adivinhar) e um linter rigoroso sobre nosso registro de empréstimos (provenance/borrows.jsonl → docs/THIRD-PARTY-NOTICES.md) que reprova uma classe negada ou licença desconhecida, uma nota de transformação ausente, ou uma nota apenas renomeada — conectado a ci/ci-strict. license-compliance-audit executa uma varredura de similaridade sob demanda, invocada por um humano e nunca por um pipeline. Esta é uma disciplina de empréstimo governada por proveniência com trilha auditada — não um detector de cópia.

Escopo e limites

• A reprodução inconsciente de dados de treinamento não é detectável nesta camada. Nenhuma ferramenta aqui — ou em qualquer lugar — pode ver o que os dados de treinamento de um modelo continham; este sistema governa o que é conscientemente emprestado e registrado, nunca o que um modelo recorda silenciosamente.
• A detecção, onde existe, cobre uma base de conhecimento de OSS conhecido apenas — um subconjunto de todo o código que já existiu, nunca o corpus de treinamento de um modelo.
• Não existe portão de detecção voltado para CI. Um scanner determinístico (jscpd offline + SCANOSS online) foi construído e medido contra um corpus sintético congelado, mas não atingiu seus próprios limiares pré-registrados (medido: recall 12/16, falsos positivos 2/12, recall apenas renomeado SCANOSS 0/8) — veja docs/CLAIMS.md. Ele não é enviado em nenhuma forma no CI, nem mesmo consultivo — apenas como a habilidade sob demanda acima.
• A lavagem apenas por renomeação não é detectada por nada que enviamos ou avaliamos. A verificação de nota de transformação do registro rejeita uma nota apenas renomeada-redigida, mas não pode capturar uma cópia apenas renomeada não divulgada que nunca foi registrada.

Reduz e documenta risco — nunca o elimina.

Telemetria do mantenedor (opt-in, desativada por padrão)

Log de engajamento de artefatos apenas local. Defina telemetry.artifact_engagement.enabled: true em .agent-settings.yml. Registra quais habilidades / regras / comandos / diretrizes o agente consulta durante /implement-ticket / /work. JSONL sob a raiz do projeto, nada é enviado. Relatórios: npx @event4u/agent-config telemetry:report.

Sugestão de comando sensível ao contexto

Quando um prompt corresponde ao propósito de um comando ("setze ticket ABC-123 um" → /implement-ticket), o agente apresenta correspondências como opções numeradas — nada é executado automaticamente. Desativação por conversa: /command-suggestion-off. Configurações: commands.suggestion.{enabled,blocklist,confidence_floor} em .agent-settings.yml.

---

Princípios centrais

• Analise antes de implementar — sem adivinhação, sem edições cegas
• Verifique com execução real — sem "deveria funcionar"
• Desafie para melhorar — agentes são parceiros de pensamento, não máquinas de "sim"
• Rigoroso por design — qualidade sobre flexibilidade
• Runtime governado — processos residentes exigem supervisão, gravações com escopo e um controle de parada

---

Documentação

Documento	Conteúdo
Introdução	Primeira execução, experiência de 3 testes, perfis, próximos passos
Instalação	Todos os caminhos de instalação, Composer/npm, detalhes do orquestrador
Arquitetura	Camadas do sistema, pipeline de conteúdo, matriz de suporte de ferramentas
Personalização	Substituições, AGENTS.md, configurações do agente, perfis de custo
Qualidade e CI	Linting, pipeline de CI, sistema de condensação
Migração	Etapas de atualização por versão
Showcase	Mais exemplos e comportamento esperado

Navegue pelo conteúdo: todos os comandos · catálogo de habilidades · catálogo completo · llms.txt.

---

Solução de problemas

Primeiro passo para qualquer problema de instalação: agent-config doctor — ele sinaliza um binário ausente do PATH, deriva de versão binário↔plugin, órfãos obsoletos e problemas de manifesto, cada um com uma dica de correção de uma linha.

Para perguntas do tipo "por que a regra/hook X não disparou?": agent-config routing:doctor — um diagnóstico somente leitura e ao vivo que relata cada portão de início de sessão como ACTIVE/INACTIVE com a razão da própria preocupação (por exemplo, session-canary: ACTIVE for "Alex" vs INACTIVE — sem nome em nenhuma camada de configurações), a cadeia de preocupações da plataforma, registro de hook do host e frescor do router + projeção. Internals mais profundos de hook (postura fail-open/closed, último feedback do dispatcher por preocupação): agent-config hooks:doctor.

Sintomas de atualização e obsolescência — um comando ou habilidade ausente após uma atualização, habilidades aparecendo duas vezes, uma atualização interrompida, command not found, arquivos de projeto obsoletos: docs/troubleshooting.md § Atualização e obsolescência.

---

Desenvolvimento

Trabalhando no próprio pacote? Edite src/ (a fonte da verdade — src/skills, src/rules, src/agent-src/), regenere as árvores:

task sync             # regenerate dist/agent-src/ and .augment/
task generate-tools   # regenerate .claude/, .cursor/, .clinerules/, .windsurfrules
task ci               # full pipeline — green before PR
task test             # unit + integration tests
task dev:setup        # boot the onboarding wizard against the working tree

Invocando o CLI a partir de um checkout da fonte: ./agent-config <command> (o shim do mantenedor na raiz do repositório → scripts/agent-config → dist/cli/agent-config.js). npx @event4u/agent-config não resolve no repositório fonte sem um npm link prévio, pois não há symlink node_modules/.bin/agent-config — use ./agent-config em vez disso. Compile o binário TS com npm run build:cli se dist/cli/agent-config.js estiver ausente.

→ Estrutura completa do projeto e comandos: docs/development.md · CONTRIBUTING.md. Stack: TypeScript em todo lugar — CLI, UI e os scripts de build / lint. Payloads do registro MCP são renderizados sob dist/mcp/ (checklist de submissão).

---

Requisitos

• Node ≥ 20.11 — npx @event4u/agent-config init é o caminho de instalação canônico. Sem Python em nenhum lugar no caminho de instalação (o instalador Python se aposentou com a migração para TypeScript).
• Plataforma: macOS 12.3+, Linux, WSL2. Git Bash precisa do Developer Mode para symlinks. Contribuidores reconstruindo .augment/ também precisam de Task.

Windows

PowerShell / cmd nativo não é suportado para a instalação de arquivos — use WSL2 para a árvore instalada completa. A superfície nativa do Windows suportada é o servidor MCP stdio: aponte qualquer cliente MCP para

npx -y @event4u/agent-config mcp-server

e o conteúdo de governança (prompts, recursos, ferramentas) está disponível sem a instalação de arquivos. Portar o dispatcher bash para Windows nativo é limitado por demanda: um adotante Windows nomeado que não pode usar WSL2 ou o caminho MCP reabre isso (veja agents/roadmaps/ — road-to-credible-install Fase 3).

Financiamento

O pacote é gratuito, MIT, e permanece assim — sem nível pago, sem licenciamento duplo. Se ele economizar seu tempo e você quiser contribuir, o botão GitHub Sponsor no topo do repositório é todo o mecanismo. Se preferir não, use mesmo assim; nada aqui é condicionado a isso.

Licença

MIT.

mcp-name: io.github.event4u-app/agent-config