agent-devkit 0.1.5 → 0.2.0

package/README.md

@@ -26,7 +26,7 @@ agent doctor
 Expected version for this release:
 
 ```text
-agent 0.1.5
+agent 0.2.0
 ```
 
 ## Quick Start
@@ -41,6 +41,18 @@ agent llm list
 agent commands list
 ```
 
+Agent DevKit `v0.2.0` also includes deterministic runtime discovery and
+integration commands:
+
+```bash
+agent roadmap
+agent catalog search pr
+agent route explain "review the PRs waiting for me"
+agent eval run routing
+agent secrets doctor
+agent mcp tools
+```
+
 Install project-local host artifacts for Codex, Claude Code and Claude
 Desktop/Claude.ai:
 
@@ -259,7 +271,7 @@ agent "desative o azure devops por enquanto"
 agent "reative o ollama"
 ```
 
-Decisions are stored under `~/.ai-devkit/config/decisions.json`; secret values
+Decisions are stored under `~/.agent-devkit/config/decisions.json`; secret values
 are not stored there.
 
 ## Configure LLM Backends

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-devkit",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "description": "Agent DevKit CLI runtime for specialist AI agents, capabilities and provider-aware automations.",
   "type": "module",
   "license": "MIT",

package/runtime/README.md

@@ -44,6 +44,18 @@ agent commands list
 agent doctor
 ```
 
+Na `v0.2.0`, o runtime tambem expoe superficies deterministicas para
+descoberta, avaliacao e integracao por hosts:
+
+```bash
+agent roadmap
+agent catalog search pr
+agent route explain "revise as prs que recebi hoje"
+agent eval run routing
+agent secrets doctor
+agent mcp tools
+```
+
 Instale os artefatos locais do Agent DevKit no projeto em que voce trabalha:
 
 ```bash
@@ -255,7 +267,9 @@ Referencias oficiais:
 
 Existem dois modos de execucao:
 
-- `agent "<prompt>"`: entrada em linguagem natural; exige backend LLM.
+- `agent "<prompt>"`: entrada em linguagem natural; monta um plano multiagente,
+  usa capabilities deterministicas quando possivel e exige backend LLM apenas
+  quando nenhuma rota local atende a tarefa.
 - `agent run <agent> <capability>`: execucao deterministica; nao exige LLM.
 
 Exemplo em linguagem natural:
@@ -264,6 +278,24 @@ Exemplo em linguagem natural:
 agent "analise o problema relatado no card 9900"
 ```
 
+Em `--json`, prompts roteados retornam `execution_plan` com o coordenador
+`task-orchestrator`, tarefas especialistas, configuracoes pendentes,
+`review_task` e `orchestration_trace`. Se uma fonte ou provider faltar, o plano
+fica `needs-input` e inclui o `provider-configurator` com a proxima pergunta do
+wizard. Quando a fonte esta configurada e a capability e read-only, o runtime
+executa a task primaria pelo runner existente e revisa a conclusao pelo
+`review_gate`.
+
+Para tarefas operacionais como resumo, classificacao, extracao e normalizacao,
+o runtime pode delegar uma subtarefa limitada ao `local-llm-operator` usando
+Ollama. O resultado local aparece em `local_llm_execution` e e usado apenas como
+contexto de apoio pelo coordenador principal.
+
+Quando `review_gate.required = true`, o Agent DevKit exige uma segunda revisao
+concreta pelo `execution-reviewer`, preferindo `claude-code` ou `codex-cli`.
+Sem reviewer independente configurado, ou sem uma decisao explicita
+`REVIEW OK`, a execucao retorna `needs-review` em vez de concluir como `ok`.
+
 Exemplo deterministico:
 
 ```bash
@@ -329,8 +361,31 @@ agent --json "analise o card 7914 do projeto sustentacao no azure"
 agent --json run topdesk-orchestrator read-incident --number "I 2606 001"
 ```
 
+O retorno inclui `setup_wizard.wizard_id`. Continue o roteiro uma resposta por
+vez; ao concluir, o runtime cria a source reutilizavel e retoma o prompt
+original automaticamente:
+
+```bash
+agent wizard list
+agent wizard show wiz-20260628120000-abc12345
+agent wizard answer wiz-20260628120000-abc12345 sim
+agent wizard answer wiz-20260628120000-abc12345 "minha-org"
+agent wizard answer wiz-20260628120000-abc12345 AZURE_DEVOPS_PAT
+agent wizard cancel wiz-20260628120000-abc12345
+```
+
+Em terminal interativo, sem `--json`, o proprio `agent` conduz o roteiro
+pergunta por pergunta. Em automacoes, pipes e testes, use os subcomandos
+`agent wizard ...` para evitar bloqueio de terminal.
+
+Credenciais devem ser informadas por referencia, por exemplo o nome de uma
+variavel de ambiente ou o caminho de um arquivo local. O Agent DevKit nao grava
+o valor bruto do segredo no estado do wizard nem na configuracao da source.
+
 O usuario tambem pode controlar ferramentas, integracoes, skills e LLMs sem
-editar arquivos diretamente:
+editar arquivos diretamente. Os alvos sao resolvidos pelos catalogos locais:
+`tooling/toolchain.yaml`, `providers/*.yaml`, `vendor/skills/CATALOG.md` e
+backends LLM registrados.
 
 ```bash
 agent decisions list
@@ -347,13 +402,28 @@ As mesmas operacoes podem ser feitas por prompt:
 ```bash
 agent "mostre minhas decisoes"
 agent "desative o azure devops por enquanto"
+agent "desative topdesk"
+agent "habilite gh-cli"
+agent "desative a skill security-review"
+agent "desative openrouter"
 agent "reative o ollama"
+agent "liste llms"
+agent "esqueca minha decisao sobre anthropic"
 ```
 
+Se um nome existir em mais de uma categoria, o agente retorna `needs-input` com
+as opcoes encontradas em vez de escolher silenciosamente. Use a categoria no
+prompt para resolver, por exemplo `desative a integracao figma` ou `desative a
+ferramenta figma-mcp`.
+
 Se o usuario negar ou desativar uma ferramenta, a decisao fica persistida em
-`~/.ai-devkit/config/decisions.json` e o agente segue sem usar essa ferramenta
+`~/.agent-devkit/config/decisions.json` e o agente segue sem usar essa ferramenta
 nas proximas sessoes ate reativacao explicita.
 
+O home global canonico e `~/.agent-devkit`. Instancias antigas em `~/.ai-devkit`
+continuam funcionando como legado; use `agent config migrate-home --dry-run` e
+depois `agent config migrate-home` para migrar explicitamente.
+
 Comandos uteis:
 
 ```bash
@@ -499,7 +569,9 @@ python3 scripts/mvp-readiness.py --json
 dos agentes; apenas instalam skill/commands e delegam para o runtime `agent`.
 
 - `plugins/codex-ai-devkit`: plugin local para Codex App.
-- `plugins/claude-code-ai-devkit`: plugin local para Claude Code.
+- `plugins/claude-code-ai-devkit`: plugin local para Claude Code, incluindo
+  skill, comandos e subagentes opcionais para usar capabilities do Agent DevKit
+  em contextos isolados.
 - `plugins/claude-skill-ai-devkit`: skill para Claude Desktop/Claude.ai.
 
 Os nomes de pastas dos plugins ainda preservam `ai-devkit` por
@@ -522,7 +594,7 @@ solicita provider e nao persiste segredos. Use `--dry-run --json` para revisar
 os caminhos antes de escrever. O host `all` inclui Codex App, Claude Code e
 Claude Desktop/Claude.ai.
 
-Instalacoes globais gravam `~/.ai-devkit/runtime.lock`; instalacoes por projeto
+Instalacoes globais gravam `~/.agent-devkit/runtime.lock`; instalacoes por projeto
 gravam `.ai-devkit/ai-devkit.lock`. Use `agent doctor --project .` para
 verificar se o projeto esta fixado em runtime diferente do global.
 
@@ -542,7 +614,10 @@ Execucoes reais de capabilities com escrita exigem confirmacao dupla no runtime:
 `blocked_by_default` tambem exigem `--allow-dangerous`, alem das validacoes
 internas da capability.
 
-Saidas JSON de `agent run` usam contrato `ai-devkit.run/v1`, com `status`
+Saidas JSON de `agent "<prompt>"` usam o contrato de orquestracao
+`ai-devkit.agentic-plan/v1` dentro de `execution_plan`. Os estados principais
+sao `planned`, `needs-input`, `ok`, `partial` e `blocked`. Saidas JSON de
+`agent run` usam contrato `ai-devkit.run/v1`, com `status`
 parseavel (`ok`, `partial`, `blocked`, `failed`), `agent_id`, `capability_id`,
 `providers`, `fallback_applied`, `evidence`, `risks`, `next_steps` e
 `artifacts` sempre presentes.
@@ -560,6 +635,30 @@ e ignorado pelo Git. Para Azure DevOps, `AZURE_DEVOPS_ORG` e
 
 ## Agentes disponiveis
 
+- [`agent-devkit-agent-builder`](agents/agent-devkit-agent-builder/):
+  especialista interno para planejar, criar scaffold e validar novos agentes do
+  proprio Agent DevKit.
+- [`automation-architect`](agents/automation-architect/): especialista em
+  classificar pedidos de automacao, escolher tecnologia adequada, planejar a
+  solucao e delegar por contrato para builders especificos.
+- [`generic-agent-builder`](agents/generic-agent-builder/): especialista em
+  planejar, gerar e revisar agentes genericos portaveis para projetos e hosts
+  externos.
+- [`python-automation-builder`](agents/python-automation-builder/):
+  especialista em planejar, gerar, revisar e empacotar automacoes Python
+  seguras para tarefas repetitivas.
+- [`selenium-automation-builder`](agents/selenium-automation-builder/):
+  especialista em planejar, gerar e revisar automacoes Selenium/WebDriver quando
+  houver requisito tecnico para Selenium.
+- [`pyautogui-automation-builder`](agents/pyautogui-automation-builder/):
+  especialista em planejar, gerar e revisar automacoes desktop visuais com
+  PyAutoGUI como ultimo recurso.
+- [`playwright-automation-builder`](agents/playwright-automation-builder/):
+  especialista em planejar, gerar, revisar e executar checks controlados de
+  automacoes web modernas com Playwright.
+- [`aws-lambda-builder`](agents/aws-lambda-builder/): especialista em
+  planejar, gerar, revisar e empacotar projetos AWS Lambda locais sem executar
+  deploy real.
 - [`aws-architecture-analyst`](agents/aws-architecture-analyst/): especialista
   em analise arquitetural AWS read-only, inventario, dependencias, resiliencia,
   observabilidade, rede e blast radius.
@@ -584,6 +683,13 @@ e ignorado pelo Git. Para Azure DevOps, `AZURE_DEVOPS_ORG` e
 - [`database-change-operator`](agents/database-change-operator/):
   especialista em mudancas controladas em PostgreSQL, incluindo migrations,
   rollback, scripts de escrita, upserts e updates com dry-run por padrao.
+- [`docker-container-builder`](agents/docker-container-builder/): especialista
+  em planejar, gerar e revisar artefatos Docker locais, incluindo Dockerfile,
+  .dockerignore, docker-compose.yml, README.docker.md e planos de build sem
+  executar build, push ou deploy real.
+- [`execution-loop-builder`](agents/execution-loop-builder/): especialista em
+  planejar, gerar, revisar e registrar loops de execucao controlados com
+  budgets, criterios de parada, estado minimo e auditoria por iteracao.
 - [`drawio-diagram-builder`](agents/drawio-diagram-builder/): especialista em
   criar, revisar e refinar diagramas Draw.io editaveis a partir de briefings,
   documentos, pastas, cards Azure, especificacoes, inventarios tecnicos e
@@ -591,6 +697,8 @@ e ignorado pelo Git. Para Azure DevOps, `AZURE_DEVOPS_ORG` e
 - [`elasticsearch-log-analyzer`](agents/elasticsearch-log-analyzer/):
   especialista em Elasticsearch para descoberta de fontes, busca de eventos,
   rastreio de requests, padroes de erro e relatorios de logs.
+- [`execution-reviewer`](agents/execution-reviewer/): agente runtime de
+  revisao final, revisao de planos e revisao de resultados antes da conclusao.
 - [`excel-workbook-builder`](agents/excel-workbook-builder/): especialista em
   templates, preenchimento, conciliacao, revisao e exportacao de planilhas
   Excel.
@@ -602,6 +710,11 @@ e ignorado pelo Git. Para Azure DevOps, `AZURE_DEVOPS_ORG` e
   em modo report-only e criar automacoes locais conservadoras.
 - [`knowledge-generator`](agents/knowledge-generator/): especialista em gerar
   knowledge versionavel a partir de arquivos, pastas, projetos e documentacoes.
+- [`local-llm-operator`](agents/local-llm-operator/): agente runtime para
+  diagnosticar, selecionar e delegar tarefas operacionais a LLMs locais.
+- [`notification-operator`](agents/notification-operator/): agente runtime para
+  formatar, enviar e configurar notificacoes locais de tarefas com payload
+  canonico.
 - [`n1-support-agent`](agents/n1-support-agent/): especialista N1 para executar
   runbooks operacionais a partir de cards Azure DevOps, orquestrando Azure,
   SQL Server, logs e TOPdesk.
@@ -611,6 +724,12 @@ e ignorado pelo Git. Para Azure DevOps, `AZURE_DEVOPS_ORG` e
   especialista em PostgreSQL read-only para descoberta de databases, schemas,
   tabelas, relacionamentos, joins, queries assistidas, perfilamento, qualidade
   de dados e relatorios analiticos.
+- [`supabase-project-analyst`](agents/supabase-project-analyst/):
+  especialista em inspecao local e auditoria report-only de projetos Supabase,
+  cobrindo RLS, Auth, Storage, migrations, Edge Functions e planos de correcao
+  sem aplicar mudancas reais.
+- [`provider-configurator`](agents/provider-configurator/): agente runtime que
+  conduz wizard de providers, sources e referencias seguras de credenciais.
 - [`presentation-deck-builder`](agents/presentation-deck-builder/):
   especialista em templates versionados de PowerPoint, arquivos de entrada para
   preenchimento e geracao de decks a partir de conteudo estruturado.
@@ -626,6 +745,8 @@ e ignorado pelo Git. Para Azure DevOps, `AZURE_DEVOPS_ORG` e
   especialista em analise de requisitos, entrevistas, analise de projetos,
   documentacao funcional/tecnica, user stories, fluxos de jornada e
   rastreabilidade.
+- [`task-orchestrator`](agents/task-orchestrator/): agente runtime que planeja
+  prompts livres, seleciona especialistas, coordena execucao e aciona revisao.
 - [`technical-integration-analyst`](agents/technical-integration-analyst/):
   especialista em analise de documentacoes tecnicas de integracoes, com suporte
   a REST, SOAP, MCP, SFTP, SMTP e outros protocolos, gerando contratos, fluxos,

package/runtime/agent

@@ -12,6 +12,7 @@ from cli.aikit.main import DETERMINISTIC_COMMANDS, LLM_COMMANDS, main
 
 SESSION_SHORTCUTS = {"-s", "--sessions"}
 AGENT_PROMPT_FLAGS = {"--llm", "--no-llm-fallback", "--session", "--new-session"}
+EXPLAIN_FLAGS = {"--explain"}
 GLOBAL_PROMPT_FLAGS = {"--json", "--dry-run"}
 
 
@@ -28,6 +29,8 @@ def normalize_args(argv: list[str]) -> list[str]:
             return [*leading, "agent"]
         if remaining[0] in SESSION_SHORTCUTS:
             return [*leading, *remaining]
+        if remaining[0] in EXPLAIN_FLAGS:
+            return [*leading, "route", "explain", *remaining[1:]]
         if remaining[0] in commands:
             return [*leading, *remaining]
         return [*leading, "agent", *remaining]
@@ -36,6 +39,8 @@ def normalize_args(argv: list[str]) -> list[str]:
         return remaining
     if first in SESSION_SHORTCUTS:
         return remaining
+    if first in EXPLAIN_FLAGS:
+        return ["route", "explain", *remaining[1:]]
     if first in AGENT_PROMPT_FLAGS:
         return ["agent", *remaining]
     if first in commands:

package/runtime/agents/README.md

@@ -37,6 +37,23 @@ agents/<agent-id>/
 
 ## Agentes atuais
 
+- `agent-devkit-agent-builder`: especialista interno para planejar, criar
+  scaffold e validar novos agentes do proprio Agent DevKit.
+- `automation-architect`: especialista em classificar pedidos de automacao,
+  escolher tecnologia adequada e delegar por contrato para builders
+  especializados.
+- `generic-agent-builder`: especialista em planejar, gerar e revisar agentes
+  genericos portaveis para projetos e hosts externos.
+- `python-automation-builder`: especialista em planejar, gerar, revisar e
+  empacotar automacoes Python seguras para tarefas repetitivas.
+- `selenium-automation-builder`: especialista em planejar, gerar e revisar
+  automacoes Selenium/WebDriver quando houver requisito tecnico para Selenium.
+- `pyautogui-automation-builder`: especialista em planejar, gerar e revisar
+  automacoes desktop visuais com PyAutoGUI como ultimo recurso.
+- `playwright-automation-builder`: especialista em planejar, gerar, revisar e
+  executar checks controlados de automacoes web modernas com Playwright.
+- `aws-lambda-builder`: especialista em planejar, gerar, revisar e empacotar
+  projetos AWS Lambda locais sem executar deploy real.
 - `aws-architecture-analyst`: especialista em analise arquitetural AWS
   read-only.
 - `aws-cloudwatch-log-analyzer`: especialista em AWS CloudWatch Logs.
@@ -50,9 +67,15 @@ agents/<agent-id>/
 - `data-scientist-analyst`: especialista em analise de dados tabulares,
   profiling, conciliacao e relatorios tecnicos.
 - `database-change-operator`: especialista em mudancas controladas em Postgres.
+- `docker-container-builder`: especialista em planejar, gerar e revisar
+  artefatos Docker locais sem executar build, push ou deploy real.
+- `execution-loop-builder`: especialista em planejar, gerar, revisar e
+  registrar loops de execucao controlados com budgets e criterios de parada.
 - `drawio-diagram-builder`: especialista em diagramas Draw.io editaveis a
   partir de fontes reais, entrevista, geracao, revisao e refinamento.
 - `elasticsearch-log-analyzer`: especialista em logs no Elasticsearch.
+- `execution-reviewer`: agente runtime de revisao final, revisao de planos e
+  revisao de resultados de agentes especialistas.
 - `excel-workbook-builder`: especialista em templates, preenchimento,
   conciliacao, revisao e exportacao de planilhas Excel.
 - `figma-ui-ux-product-designer`: especialista UI/UX para criar, recriar,
@@ -62,6 +85,8 @@ agents/<agent-id>/
   locais conservadoras.
 - `knowledge-generator`: especialista em gerar knowledge versionavel a partir de
   fontes locais e documentacoes.
+- `local-llm-operator`: agente runtime para diagnosticar, selecionar e delegar
+  tarefas operacionais a LLMs locais como Ollama.
 - `n1-support-agent`: especialista N1 para runbooks operacionais a partir de
   cards Azure DevOps.
 - `n2-support-agent`: especialista N2 para investigacao de causa raiz e geracao
@@ -70,12 +95,21 @@ agents/<agent-id>/
   de apresentacoes PowerPoint.
 - `postgres-data-analyzer`: especialista em analise read-only forte de dados
   Postgres.
+- `supabase-project-analyst`: especialista em inspecao local e auditoria
+  report-only de projetos Supabase, RLS, Auth, Storage, migrations e planos de
+  correcao sem aplicar mudancas reais.
+- `notification-operator`: agente runtime para formatar, enviar e configurar
+  notificacoes locais de tarefas com payload canonico.
+- `provider-configurator`: agente runtime para conduzir wizard de configuracao
+  de providers, sources e referencias seguras de credenciais.
 - `sqlserver-data-analyzer`: especialista em analise read-only de dados SQL
   Server.
 - `sqlserver-change-operator`: especialista em mudancas controladas em SQL
   Server.
 - `software-specification-analyst`: especialista em analise de requisitos,
   entrevistas, analise de projetos e especificacoes completas de software.
+- `task-orchestrator`: agente runtime que planeja prompts livres, seleciona
+  especialistas, coordena execucao e aciona revisao.
 - `technical-integration-analyst`: especialista em documentacoes tecnicas de
   integracoes e artefatos de teste.
 - `topdesk-orchestrator`: especialista em TOPdesk para incidentes e triagem.

package/runtime/agents/agent-devkit-agent-builder/AGENTS.md

@@ -0,0 +1,24 @@
+# Agent DevKit Agent Builder
+
+Instrucoes locais para o agente `agent-devkit-agent-builder`.
+
+## Responsabilidade
+
+Este agente cria e valida novos agentes internos do proprio Agent DevKit em
+`agents/<agent-id>/`.
+
+## Guardrails
+
+- Nao criar arquivos fora de `agents/<agent-id>/`.
+- Nao sobrescrever agente existente sem permissao explicita.
+- Nao persistir segredos, URLs privadas ou contexto de cliente.
+- Nao criar provider ou dependencia externa nova.
+- Gerar sempre `write_policy`, `workflow.md` e `decision-rules.md`.
+- Usar dry-run como comportamento padrao para scaffold.
+
+## Fora De Escopo
+
+- Agentes genericos para outros projetos.
+- Marketplace de agentes.
+- Interface grafica.
+- Geracao baseada em LLM nesta primeira versao.

package/runtime/agents/agent-devkit-agent-builder/README.md

@@ -0,0 +1,37 @@
+# Agent DevKit Agent Builder
+
+Agente especialista interno para planejar, criar scaffold e validar novos
+agentes do Agent DevKit.
+
+## Capabilities
+
+- `plan-agent`: analisa uma spec estruturada e retorna o plano de agente sem
+  escrever arquivos.
+- `scaffold-agent`: gera o scaffold do agente em dry-run por padrao e escreve
+  arquivos somente com execucao confirmada.
+- `validate-agent-contract`: valida a estrutura de um agente gerado.
+
+## Exemplo
+
+```bash
+agent run agent-devkit-agent-builder plan-agent --spec docs/new-agent.yaml
+agent run agent-devkit-agent-builder scaffold-agent --spec docs/new-agent.yaml
+agent run agent-devkit-agent-builder scaffold-agent --spec docs/new-agent.yaml --execute --confirm-execute
+agent run agent-devkit-agent-builder validate-agent-contract --agent-id sample-agent
+```
+
+## Spec Minima
+
+```yaml
+agent_id: sample-agent
+name: Sample Agent
+purpose: >
+  Descrever o objetivo do agente.
+domain: dominio interno
+capabilities:
+  - id: do-thing
+    purpose: Executar uma tarefa controlada.
+    write_policy: read_only
+providers: []
+risk_profile: low
+```

package/runtime/agents/agent-devkit-agent-builder/agent.yaml

@@ -0,0 +1,46 @@
+id: agent-devkit-agent-builder
+kind: specialist-agent
+name: Agent DevKit Agent Builder
+version: 0.1.0
+status: draft
+owner: agent-devkit
+
+purpose: >
+  Planejar, criar scaffold e validar novos agentes internos do Agent DevKit,
+  seguindo contratos, guardrails, estrutura de ownership e gates do projeto.
+
+default_context:
+  - knowledge/system.md
+  - knowledge/context.md
+  - knowledge/policies.yaml
+
+env:
+  required: []
+  optional: []
+
+capabilities:
+  - plan-agent
+  - scaffold-agent
+  - validate-agent-contract
+
+agent_surface:
+  repositories:
+    - infra/integrations/agent-devkit/agent_builder_repository.py
+  policies:
+    - knowledge/policies.yaml
+
+write_policy:
+  planning: read_only
+  local_scaffold: confirm
+  validation: read_only
+  external_side_effects: blocked_by_default
+
+routing:
+  anchors:
+    - agent-devkit
+    - agent-builder
+    - scaffold
+    - agente
+  intents:
+    - agent-devkit.agent-builder
+  priority: 55

package/runtime/agents/agent-devkit-agent-builder/capabilities/plan-agent/capability.yaml

@@ -0,0 +1,29 @@
+id: agent-devkit-agent-builder.plan-agent
+kind: capability
+name: Plan Agent
+version: 0.1.0
+status: draft
+purpose: >
+  Ler uma spec estruturada de novo agente interno do Agent DevKit e retornar um
+  plano de arquivos, capabilities, policies e perguntas pendentes sem escrever
+  arquivos.
+entrypoint:
+  runner: runner.py
+  workflow: workflow.md
+  prompt: ../../knowledge/system.md
+  output_template: ../../templates/agent-plan-output.md
+inputs:
+  required:
+    - spec
+  optional: []
+outputs:
+  artifacts:
+    - agent-plan.json
+write_policy: read_only
+routing:
+  anchors:
+    - plan-agent
+    - criar agente
+  intents:
+    - agent-devkit.agent-builder.plan
+  priority: 70

package/runtime/agents/agent-devkit-agent-builder/capabilities/plan-agent/decision-rules.md

@@ -0,0 +1,7 @@
+# Decision Rules
+
+- Nunca escrever arquivos nesta capability.
+- Bloquear `agent_id` que nao seja kebab-case.
+- Bloquear tentativa de path traversal.
+- Exigir pelo menos uma capability.
+- Sinalizar perguntas pendentes em vez de inventar contrato ausente.

package/runtime/agents/agent-devkit-agent-builder/capabilities/plan-agent/runner.py

@@ -0,0 +1,33 @@
+#!/usr/bin/env python3
+"""Runner for agent-devkit-agent-builder/plan-agent."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import sys
+
+
+REPOSITORY_DIR = Path(__file__).resolve().parents[2] / "infra" / "integrations" / "agent-devkit"
+sys.path.insert(0, str(REPOSITORY_DIR))
+
+from agent_builder_repository import AgentBuilderRepository, AgentBuilderError  # noqa: E402
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Plan a new internal Agent DevKit agent")
+    parser.add_argument("--spec", required=True)
+    args = parser.parse_args()
+
+    try:
+        result = AgentBuilderRepository().plan_agent(spec_path=Path(args.spec))
+    except AgentBuilderError as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/runtime/agents/agent-devkit-agent-builder/capabilities/plan-agent/workflow.md

@@ -0,0 +1,8 @@
+# Workflow
+
+1. Ler a spec YAML ou JSON.
+2. Validar campos minimos.
+3. Normalizar IDs em kebab-case.
+4. Gerar lista de arquivos planejados.
+5. Retornar `needs-input` se a spec estiver incompleta.
+6. Nao escrever arquivos.

package/runtime/agents/agent-devkit-agent-builder/capabilities/scaffold-agent/capability.yaml

@@ -0,0 +1,31 @@
+id: agent-devkit-agent-builder.scaffold-agent
+kind: capability
+name: Scaffold Agent
+version: 0.1.0
+status: draft
+purpose: >
+  Criar scaffold local de um novo agente interno do Agent DevKit em dry-run por
+  padrao, escrevendo arquivos apenas quando a execucao for explicitamente
+  confirmada.
+entrypoint:
+  runner: runner.py
+  workflow: workflow.md
+  prompt: ../../knowledge/system.md
+  output_template: ../../templates/scaffold-plan-output.md
+inputs:
+  required:
+    - spec
+  optional:
+    - execute
+    - allow_overwrite
+outputs:
+  artifacts:
+    - scaffold-plan.json
+write_policy: confirm
+routing:
+  anchors:
+    - scaffold-agent
+    - gerar agente
+  intents:
+    - agent-devkit.agent-builder.scaffold
+  priority: 70

package/runtime/agents/agent-devkit-agent-builder/capabilities/scaffold-agent/decision-rules.md

@@ -0,0 +1,9 @@
+# Decision Rules
+
+- Dry-run e o comportamento padrao.
+- Escrita real exige `--execute` e confirmacao do runtime para `write_policy:
+  confirm`.
+- Nao escrever fora de `agents/<agent-id>/`.
+- Nao sobrescrever agente existente sem permissao explicita.
+- Nao criar providers, dependencias externas ou arquivos fora do contrato do
+  agente.

package/runtime/agents/agent-devkit-agent-builder/capabilities/scaffold-agent/runner.py

@@ -0,0 +1,39 @@
+#!/usr/bin/env python3
+"""Runner for agent-devkit-agent-builder/scaffold-agent."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import sys
+
+
+REPOSITORY_DIR = Path(__file__).resolve().parents[2] / "infra" / "integrations" / "agent-devkit"
+sys.path.insert(0, str(REPOSITORY_DIR))
+
+from agent_builder_repository import AgentBuilderRepository, AgentBuilderError  # noqa: E402
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Scaffold a new internal Agent DevKit agent")
+    parser.add_argument("--spec", required=True)
+    parser.add_argument("--execute", action="store_true")
+    parser.add_argument("--allow-overwrite", action="store_true")
+    args = parser.parse_args()
+
+    try:
+        result = AgentBuilderRepository().scaffold_agent(
+            spec_path=Path(args.spec),
+            execute=args.execute,
+            allow_overwrite=args.allow_overwrite,
+        )
+    except AgentBuilderError as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/runtime/agents/agent-devkit-agent-builder/capabilities/scaffold-agent/workflow.md

@@ -0,0 +1,8 @@
+# Workflow
+
+1. Ler a spec YAML ou JSON.
+2. Gerar plano de arquivos.
+3. Em dry-run, retornar os arquivos planejados sem escrever.
+4. Com `--execute`, escrever apenas dentro de `agents/<agent-id>/`.
+5. Bloquear overwrite sem `--allow-overwrite`.
+6. Retornar arquivos escritos e proximos passos de validacao.