agent-devkit 0.1.6 → 0.2.0

package/README.md

@@ -26,7 +26,7 @@ agent doctor
 Expected version for this release:
 
 ```text
-agent 0.1.6
+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:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-devkit",
-  "version": "0.1.6",
+  "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
@@ -557,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
@@ -621,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.
@@ -645,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
@@ -667,6 +712,9 @@ e ignorado pelo Git. Para Azure DevOps, `AZURE_DEVOPS_ORG` e
   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.
@@ -676,6 +724,10 @@ 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/):

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,6 +67,10 @@ 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.
@@ -74,6 +95,11 @@ 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

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.

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

@@ -0,0 +1,28 @@
+id: agent-devkit-agent-builder.validate-agent-contract
+kind: capability
+name: Validate Agent Contract
+version: 0.1.0
+status: draft
+purpose: >
+  Validar a estrutura local de um agente interno do Agent DevKit gerado pelo
+  builder, conferindo manifests, docs, diretórios e decision rules.
+entrypoint:
+  runner: runner.py
+  workflow: workflow.md
+  prompt: ../../knowledge/system.md
+  output_template: ../../templates/validation-report-output.md
+inputs:
+  required:
+    - agent_id
+  optional: []
+outputs:
+  artifacts:
+    - validation-report.json
+write_policy: read_only
+routing:
+  anchors:
+    - validate-agent
+    - validar agente
+  intents:
+    - agent-devkit.agent-builder.validate
+  priority: 70

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

@@ -0,0 +1,6 @@
+# Decision Rules
+
+- Validacao e read-only.
+- Reportar erros sem corrigir arquivos.
+- Considerar ausente qualquer capability declarada sem diretorio correspondente.
+- Considerar invalido qualquer capability sem `decision-rules.md`.

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

@@ -0,0 +1,33 @@
+#!/usr/bin/env python3
+"""Runner for agent-devkit-agent-builder/validate-agent-contract."""
+
+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="Validate an internal Agent DevKit agent scaffold")
+    parser.add_argument("--agent-id", required=True)
+    args = parser.parse_args()
+
+    try:
+        result = AgentBuilderRepository().validate_agent_contract(agent_id=args.agent_id)
+    except AgentBuilderError as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 0 if result.get("valid") else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -0,0 +1,7 @@
+# Workflow
+
+1. Receber `agent_id`.
+2. Conferir estrutura obrigatoria do agente.
+3. Conferir capabilities declaradas e presentes em disco.
+4. Conferir `workflow.md`, `decision-rules.md` e `write_policy`.
+5. Retornar erros e warnings estruturados.