Thulr/agent-skill-kit

Agent DX

A experiência do desenvolvedor de uma superfície onde um agente de IA é o desenvolvedor — um SDK, ferramenta, saída estruturada, envelope de erro ou telemetria que um agente consome para construir ou agir através dela. A proveniência reside em skill.json; este arquivo é apenas para roteamento em tempo de execução.

Produz: um change-plan.md (DO), um audit-report.md mais um ledger de descobertas + estado do fluxo de trabalho quando rastreado (REVIEW), ou um design-doc.md / refactor-runbook.md / explanation.md (DESIGN).

Princípio central

Um agente consome a superfície sozinho, em velocidade de máquina, sem tooltips como suporte. Portanto, o padrão para qualquer SDK, ferramenta, erro ou span é se um consumidor estocástico consegue analisá-lo, recuperar-se dele e não ser prejudicado por ele: contratos tipados em vez de prosa; recuperação projetada, não esperada; a fronteira de confiança fechada por padrão. Ele fica acima do nível do cliente HTTP que dx-audit / dx-design possuem, nunca o substituindo.

Ativação

• Invocação simples ("use agent-dx", "revisar nossa superfície de ferramentas MCP", "iniciar"): carregar references/intent-router.csv, mostrar o menu de intenções, oferecer o modo. Aguardar. Nenhuma inspeção de arquivo, chamadas de rede ou gravações.
• Invocação concreta com intenção e superfície inferíveis: pular para o passo 3.
• Escopo ambíguo: fazer uma pergunta para desbloquear nomeando a intenção ou superfície candidata; não inspecionar sistemas privados primeiro.

Fluxo de trabalho

1. Escolher intenção. Carregar references/intent-router.csv; combinar com do, review ou design. Ambíguo → perguntar uma vez.
2. Escolher superfície. Carregar references/intents/<intent>.csv; combinar uma ou mais de sdk-design, tools-and-mcp, structured-output, errors-and-retry, sdk-telemetry — ou all para um fan-out de REVIEW. Ambíguo → perguntar uma vez com o menu.
3. Carregar contexto fundamentado. Carregar apenas o playbook da linha escolhida mais seus core_refs. Não carregar outros playbooks (a linha review/all não carrega nenhum — cada agente de superfície carrega o seu; ver passo 6).
4. Identificar a persona alvo a partir de references/core/personas.md.
5. Em seguida, calibrar para a escala do projeto (REVIEW / DESIGN) conforme references/calibration.md: abaixo de crítico, estreitar escopo, colapsar lacunas do mesmo mecanismo em uma descoberta sistêmica e dividir Agora vs Depois (à medida que cresce). O nível alimenta a emissão, nunca a severidade.
6. Despachar lentes em paralelo (REVIEW padrão quando permitido): uma superfície por agente para all; caso contrário, as três lentes abaixo. Fallback sequencial se não houver primitiva de delegação.
7. Aplicar o playbook. Usar as heurísticas marcadas para a intenção. Para REVIEW, pontuar cada superfície de 0 a 10 (references/core/score-rubric.md); sintetizar descobertas das lentes, preservando discordâncias como perguntas em aberto. Aplicar severidade e IDs estáveis AGENT-DX-<surface>-NNN (references/core/severity-rubric.md): AGENT-DX-SDK, AGENT-DX-TOOL, AGENT-DX-OUT, AGENT-DX-ERR, AGENT-DX-TEL.
8. Emitir. DO → templates/change-plan.md. REVIEW → templates/audit-report.md. DESIGN → templates/design-doc.md (forma), templates/refactor-runbook.md (sequenciar um endurecimento) ou templates/explanation.md (explicar um princípio).
9. Criar, retomar ou fechar estado de rastreamento (REVIEW). Para uma auditoria com 7+ descobertas, qualquer severidade 3–4, ou uma solicitação de salvar/rastrear/fechar, carregar references/trackable-findings.md. Se a solicitação nomear um ledger existente, estado do fluxo de trabalho, PR ou ID AGENT-DX-*, ler estado salvo primeiro; atualizar status somente após cada regra de verificação passar. Caso contrário, escrever o ledger em docs/audits/agent-dx-findings-ledger-<YYYY-MM-DD>-<scope-slug>.md e o estado do fluxo de trabalho em docs/audits/agent-dx-workflow-state-<YYYY-MM-DD>-<scope-slug>.json (recuar para audit-artifacts/agent-dx-... se docs/audits/ não for gravável). Reportar ambos os caminhos; manter roadmaps, issues e edições não relacionadas a rastreamento como opt-in.

Modos

Guided Draft (padrão), Autopilot, Grill Me — ver references/modes.md. Oferecer na invocação simples; padrão para Guided Draft em invocações concretas.

Requisitos de saída

Cada saída nomeia a intenção, superfície(s), persona, playbook(s) aplicados e fontes de fundamentação de skill.json; REVIEW adiciona severidade + verificação por descoberta e o nível do projeto. Nomear as garantias de consumibilidade por agente que você está DELIBERADAMENTE NÃO adicionando (YAGNI), não apenas as que você está adicionando.

Despacho de subagentes

Padrão para REVIEW quando a delegação é permitida; pular trabalho pequeno ou vinculado a segredos. Gerar três lentes em paralelo — contrato-e-esquema (esquemas tipados do código, envelope de erro estável, saída validada), recuperação-do-agente (parar+verificar, erros em formato de retry, retry semântico, loop limitado), confiança-e-isolamento (injeção de metadados de ferramenta, pontos de verificação de guardrail, barreiras de credenciais, redação de conteúdo) — conforme references/subagent-dispatch.md, depois sintetizar, ordenando por severidade.

Mapa de referência

• references/intent-router.csv + references/intents/<intent>.csv — as duas camadas de roteamento.
• references/playbooks/<surface>.md — sdk-design, tools-and-mcp, structured-output, errors-and-retry, sdk-telemetry.
• references/subagent-dispatch.md — prompts de três lentes e síntese.
• references/core/{severity-rubric,score-rubric,personas,glossary}.md — escalas, público, termos.
• references/{calibration,trackable-findings,modes}.md — compartilhados (symlinks).
• templates/*.md — change-plan, audit-report, design-doc, refactor-runbook, explanation, mais os artefatos de rastreamento compartilhados.
• evals/, skill.json — portões e proveniência.