agent-devkit 0.1.6 → 0.3.0

package/runtime/agent

@@ -12,12 +12,15 @@ 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"}
+RENAME_FLAGS = {"--rename"}
+AGENTIC_PROMPT_COMMANDS = {"plan", "execute", "orchestrate"}
 
 
 def normalize_args(argv: list[str]) -> list[str]:
     if not argv:
-        return ["agent"]
+        return ["onboard"]
     commands = set(DETERMINISTIC_COMMANDS) | set(LLM_COMMANDS)
     leading: list[str] = []
     remaining = list(argv)
@@ -25,22 +28,50 @@ def normalize_args(argv: list[str]) -> list[str]:
         leading.append(remaining.pop(0))
     if leading:
         if not remaining:
-            return [*leading, "agent"]
+            return [*leading, "onboard"]
         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 RENAME_FLAGS:
+            return [*leading, "personality", "edit", *remaining]
+        if remaining[0] in AGENTIC_PROMPT_COMMANDS:
+            prompt_flags, prompt_args = split_global_prompt_flags(remaining[1:])
+            return [*leading, remaining[0], *prompt_flags, *prompt_args]
         if remaining[0] in commands:
             return [*leading, *remaining]
-        return [*leading, "agent", *remaining]
+        prompt_flags, prompt_args = split_global_prompt_flags(remaining)
+        return [*leading, *prompt_flags, "agent", *prompt_args]
     first = remaining[0]
     if first in {"--help", "-h", "--version", "-v"}:
         return remaining
     if first in SESSION_SHORTCUTS:
         return remaining
+    if first in EXPLAIN_FLAGS:
+        return ["route", "explain", *remaining[1:]]
+    if first in RENAME_FLAGS:
+        return ["personality", "edit", *remaining]
     if first in AGENT_PROMPT_FLAGS:
-        return ["agent", *remaining]
+        prompt_flags, prompt_args = split_global_prompt_flags(remaining)
+        return [*prompt_flags, "agent", *prompt_args]
+    if first in AGENTIC_PROMPT_COMMANDS:
+        prompt_flags, prompt_args = split_global_prompt_flags(remaining[1:])
+        return [first, *prompt_flags, *prompt_args]
     if first in commands:
         return remaining
-    return ["agent", *remaining]
+    prompt_flags, prompt_args = split_global_prompt_flags(remaining)
+    return [*prompt_flags, "agent", *prompt_args]
+
+
+def split_global_prompt_flags(argv: list[str]) -> tuple[list[str], list[str]]:
+    leading: list[str] = []
+    remaining: list[str] = []
+    for item in argv:
+        if item in GLOBAL_PROMPT_FLAGS:
+            leading.append(item)
+        else:
+            remaining.append(item)
+    return leading, remaining
 
 
 if __name__ == "__main__":

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,12 @@ 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.
+- `contribution-reviewer`: agente runtime para validar extensoes locais,
+  revisar riscos de contribuicao upstream e planejar PRs em modo report-only.
 - `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.
@@ -62,10 +85,24 @@ agents/<agent-id>/
 - `github-pr-reviewer`: especialista em Pull Requests GitHub, revisao
   report-only, permissao explicita para comentarios/aprovacoes e automacoes
   locais conservadoras.
+- `knowledge-infra-builder`: especialista em criar e diagnosticar a
+  infraestrutura file-first da knowledge base compartilhada.
+- `knowledge-author`: especialista em criar snapshots de conhecimento
+  reutilizavel, sanitizado e revisavel.
 - `knowledge-generator`: especialista em gerar knowledge versionavel a partir de
   fontes locais e documentacoes.
+- `knowledge-reviewer`: especialista em revisar snapshots, bloqueando segredo,
+  PII indevida, duplicidade e prompt injection.
+- `knowledge-curator`: especialista em curadoria continua, deduplicacao,
+  arquivamento e reindexacao derivada da knowledge base.
+- `knowledge-owner`: autoridade de publicacao controlada da knowledge base
+  principal apos revisao.
 - `local-llm-operator`: agente runtime para diagnosticar, selecionar e delegar
   tarefas operacionais a LLMs locais como Ollama.
+- `local-memory-manager`: agente runtime para inspecionar e curar memoria local,
+  preferencias, sessoes e identidade sem expor segredos.
+- `memory-sync-manager`: especialista em planejar backup, restore e
+  sincronizacao seletiva da memoria local e personalidade.
 - `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
@@ -74,12 +111,19 @@ 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.
+- `shared-memory-curator`: agente runtime para criar memorias compartilhadas,
+  revisar contribuicoes externas e publicar apenas conteudo aprovado pelo dono.
 - `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

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.