agent-devkit 0.1.6 → 0.3.0

package/runtime/tooling/toolchain.yaml

@@ -0,0 +1,92 @@
+version: 1
+tools:
+  claude-code:
+    label: Claude Code CLI
+    command: claude
+    required: false
+    install:
+      darwin: npm install -g @anthropic-ai/claude-code
+      linux: npm install -g @anthropic-ai/claude-code
+      windows: npm install -g @anthropic-ai/claude-code
+    notes: Uses official Claude Code authentication.
+  codex-cli:
+    label: Codex CLI
+    command: codex
+    required: false
+    install:
+      darwin: npm install -g @openai/codex
+      linux: npm install -g @openai/codex
+      windows: npm install -g @openai/codex
+    notes: Uses official Codex CLI authentication.
+  gh-cli:
+    label: GitHub CLI
+    command: gh
+    required: false
+    install:
+      darwin: brew install gh
+      linux: See https://github.com/cli/cli/blob/trunk/docs/install_linux.md
+      windows: winget install --id GitHub.cli
+    notes: Required for GitHub PR reviewer workflows.
+  playwright:
+    label: Playwright
+    command: playwright
+    required: false
+    install:
+      darwin: python3 -m pip install playwright && python3 -m playwright install chromium
+      linux: python3 -m pip install playwright && python3 -m playwright install chromium
+      windows: python -m pip install playwright && python -m playwright install chromium
+    notes: Optional; used by Playwright automation builder for real browser checks.
+  aws-cli:
+    label: AWS CLI
+    command: aws
+    required: false
+    install:
+      darwin: brew install awscli
+      linux: See https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html
+      windows: winget install --id Amazon.AWSCLI
+    notes: Required for AWS agents using real AWS accounts.
+  figma-mcp:
+    label: Figma MCP
+    command: figma
+    required: false
+    install:
+      darwin: Configure the official Figma MCP integration in your host app.
+      linux: Configure the official Figma MCP integration in your host app.
+      windows: Configure the official Figma MCP integration in your host app.
+    notes: Optional; usually installed through Codex/Claude host integrations.
+  ollama:
+    label: Ollama
+    command: ollama
+    required: false
+    install:
+      darwin: brew install ollama
+      linux: curl -fsSL https://ollama.com/install.sh | sh
+      windows: winget install Ollama.Ollama
+    notes: Local LLM runtime used for operational subagent work.
+  node:
+    label: Node.js
+    command: node
+    required: true
+    install:
+      darwin: brew install node
+      linux: Use your distro package manager or https://nodejs.org/
+      windows: winget install OpenJS.NodeJS.LTS
+    notes: Required by several artifact builders and host CLIs.
+  python:
+    label: Python
+    command: python3
+    required: true
+    install:
+      darwin: brew install python
+      linux: Use your distro package manager.
+      windows: winget install Python.Python.3.12
+    notes: Required by the Agent DevKit CLI runtime.
+  git:
+    label: Git
+    command: git
+    required: true
+    install:
+      darwin: xcode-select --install
+      linux: Use your distro package manager.
+      windows: winget install Git.Git
+    notes: Required for repository-aware workflows.

package/runtime/vendor/skills/napkin/napkin.md

@@ -7,11 +7,21 @@
 - Each item includes date + "Do instead".
 
 ## Execution & Validation (Highest Priority)
-1. **[2026-06-20] Validate agent capabilities through `agent`**
+1. **[2026-06-29] Nao paralelizar build e verify do pacote npm**
+   Do instead: rode `npm run package:build && npm run package:verify` sequencialmente; o build remove/recria `tooling/agent-devkit/runtime` e quebra verifies simultaneos.
+2. **[2026-06-29] QA destrutivo de instalacao roda em Docker**
+   Do instead: use `npm run docker:qa` para instalar tarball em container limpo, validar fluxos CLI criticos, desinstalar e remover `.agent-devkit` sem tocar no host.
+3. **[2026-06-29] Docker sem espaco causa falsos erros de apt/GPG**
+   Do instead: se `npm run docker:qa` falhar com assinatura invalida no `apt`, verificar `docker system df` e liberar artefatos regeneraveis antes de diagnosticar o CLI.
+4. **[2026-06-29] Release gate completo precisa de timeout folgado**
+   Do instead: manter timeout do `scripts/release-gate.py` acima da duracao real da suite completa; a suite isolada ja passa de 300s e o gate adiciona overhead.
+5. **[2026-06-29] Isolar home do Agent DevKit em testes**
+   Do instead: use `AGENT_DEVKIT_HOME=$(mktemp -d)` ou `AI_DEVKIT_CONFIG_HOME=$(mktemp -d)`; `AI_DEVKIT_HOME` nao e lido pelo runtime e pode gravar em `~/.agent-devkit`.
+6. **[2026-06-20] Validate agent capabilities through `agent`**
    Do instead: when testing a capability, execute it through `agent run <agent> <capability>` before using lower-level integration CLIs.
-2. **[2026-06-21] Excel artifact-tool Node scripts may keep handles alive**
+7. **[2026-06-21] Excel artifact-tool Node scripts may keep handles alive**
    Do instead: guard `run_node_script()` calls with timeouts and make successful JS runners call `process.exit(0)` after awaited saves.
-3. **[2026-06-21] `unittest discover` does not find repo tests**
+8. **[2026-06-21] `unittest discover` does not find repo tests**
    Do instead: run `python3 -m unittest $(rg --files -g 'test*.py' -g '!vendor/**')` for the project suite.
 
 ## Shell & Command Reliability
@@ -25,23 +35,33 @@
    Do instead: intercept `--source` only for capabilities that explicitly support Agent DevKit source registry injection; otherwise leave it for the runner domain contract.
 
 ## Domain Behavior Guardrails
-1. **[2026-06-28] Agentes devem ser agnosticos de cliente/projeto**
+1. **[2026-06-28] `write_policy` usa vocabulário canônico**
+   Do instead: usar apenas `read_only`, `dry_run`, `output_only`, `local_write`, `local_config_write`, `confirm`, `blocked_by_default` ou `delegated`; aliases antigos devem ser aceitos só em runtime e rejeitados como warning pelo validator.
+2. **[2026-06-28] Exemplos de roteamento nao sao evidencia por alias**
+   Do instead: ao usar `routing.examples`, comparar tokens reais ou frase exata; anchors/intents carregam aliases, exemplos nao devem promover matches genericos como apenas "analise".
+3. **[2026-06-28] Agentes devem ser agnosticos de cliente/projeto**
    Do instead: mover nomes de produto, cliente, URLs, paths locais, regras de elegibilidade e campos XML especificos para provider/config/env antes de versionar o agente.
-2. **[2026-06-28] Sessao ativa nao deve vazar contexto entre projetos**
+4. **[2026-06-28] Sessao ativa nao deve vazar contexto entre projetos**
    Do instead: ao persistir contexto de conversa, reutilizar automaticamente apenas sessoes do mesmo projeto; para outro projeto, criar nova sessao ou exigir retomada explicita.
-3. **[2026-06-28] Roteamento de PR deve usar tokens reais**
+5. **[2026-06-28] Roteamento de PR deve usar tokens reais**
    Do instead: detectar `pr`, `prs` ou `pull request` como tokens/expressao, nao substring ampla que captura palavras como `problema`.
-4. **[2026-06-28] Tasks com escrita externa devem bloquear por padrao**
+6. **[2026-06-28] Tasks com escrita externa devem bloquear por padrao**
    Do instead: permitir `dry-run`, mas bloquear execucao real quando `action.external_writes=true` sem permissao explicita de escrita externa.
-5. **[2026-06-20] Azure card descriptions may include sensitive production log data**
+7. **[2026-06-20] Azure card descriptions may include sensitive production log data**
    Do instead: retrieve the complete card for validation, but summarize PII-heavy log payloads in user-facing responses unless raw content is explicitly required.
-6. **[2026-06-21] N1 restrictive-base uses a scoped SQL Server override**
+8. **[2026-06-21] N1 restrictive-base uses a scoped SQL Server override**
    Do instead: when the N1 agent checks the restrictive base, prefer `DB_RESTRICTIVE_CONN_STRING` only in the subprocess environment for `sqlserver-data-analyzer`, without changing the global SQL Server analyzer default.
 
 ## User Directives
-1. **[2026-06-22] Implement agentic specs individually**
+1. **[2026-06-28] Rodar testes focados durante patches**
+   Do instead: para melhorias intermediarias, executar apenas testes necessarios para validar o patch e no maximo `scripts/release-gate.py --quick`; reservar suite completa e gate completo apenas para fechamento de fase/versao.
+2. **[2026-06-29] Manter `.agent-devkit` como home local**
+   Do instead: persistir instalacao, memoria local, configs e artefatos locais em `.agent-devkit` quando o runtime ja usar esse caminho; nao migrar para `.ai-devkit`.
+3. **[2026-06-29] Comando canonico permanece `agent`**
+   Do instead: manter `agent` como comando default e validar que renomeacao/persona altera o nome publico do agente, nao o executavel canonico.
+4. **[2026-06-22] Implement agentic specs individually**
    Do instead: process one `docs/agentic/*_plan.md` spec at a time with agent-specific analysis, tests, implementation, and review; do not use broad multi-agent waves or mechanical generation.
-2. **[2026-06-22] Use Agent DevKit agents for work**
+5. **[2026-06-22] Use Agent DevKit agents for work**
    Do instead: route every current and future activity through the relevant Agent DevKit agent/capability before doing direct ad-hoc work.
-3. **[2026-06-20] Keep generated docs out of final project versioning**
+6. **[2026-06-20] Keep generated docs out of final project versioning**
    Do instead: treat `docs/` as local development/generated artifact space and keep it ignored.

package/runtime/workflows/azure-card-analysis/README.md

@@ -0,0 +1,3 @@
+# Azure Card Analysis
+
+Fluxo manual para analisar cards Azure DevOps sem escrita externa por padrao.

package/runtime/workflows/azure-card-analysis/workflow.yaml

@@ -0,0 +1,30 @@
+id: azure-card-analysis
+title: Azure card analysis
+description: Analyze an Azure DevOps card and prepare an operational response plan.
+schedule:
+  type: manual
+providers:
+  - azure-devops
+permissions:
+  mode: report-only
+write_policy: local_config_write
+task:
+  title: Azure card analysis
+  prompt: Analise o card do Azure DevOps informado e prepare um plano de acao.
+  action:
+    type: prompt
+    prompt: Analise o card do Azure DevOps informado e prepare um plano de acao.
+    external_writes: false
+  permissions:
+    mode: report-only
+  notifications:
+    - type: desktop
+      events:
+        - task.completed
+        - task.blocked
+outputs:
+  - card-analysis
+risks:
+  - Requires Azure DevOps source configuration before reading real cards.
+examples:
+  - analise o card 7914 do projeto sustentacao no azure

package/runtime/workflows/daily-pr-review/README.md

@@ -0,0 +1,3 @@
+# Daily PR Review
+
+Instala uma task local para revisar PRs pendentes em modo report-only.

package/runtime/workflows/daily-pr-review/workflow.yaml

@@ -0,0 +1,31 @@
+id: daily-pr-review
+title: Daily PR review
+description: Create a local scheduled prompt to review pending pull requests.
+schedule:
+  type: cron
+  cron: "0 9 * * 1-5"
+providers:
+  - github
+permissions:
+  mode: report-only
+write_policy: local_config_write
+task:
+  title: Daily PR review
+  prompt: Revise as PRs que aguardam minha revisao hoje.
+  action:
+    type: prompt
+    prompt: Revise as PRs que aguardam minha revisao hoje.
+    external_writes: false
+  permissions:
+    mode: report-only
+  notifications:
+    - type: desktop
+      events:
+        - task.completed
+        - task.blocked
+outputs:
+  - pr-review-summary
+risks:
+  - Requires GitHub source/authentication for real PR data.
+examples:
+  - revise as prs que recebi hoje

package/runtime/workflows/incident-analysis/README.md

@@ -0,0 +1,3 @@
+# Incident Analysis
+
+Fluxo manual para planejar analise de incidente com fontes configuradas.

package/runtime/workflows/incident-analysis/workflow.yaml

@@ -0,0 +1,33 @@
+id: incident-analysis
+title: Incident analysis
+description: Plan an incident analysis using available cards, logs and source context.
+schedule:
+  type: manual
+providers:
+  - azure-devops
+  - github
+  - elasticsearch
+  - aws
+permissions:
+  mode: report-only
+write_policy: local_config_write
+task:
+  title: Incident analysis
+  prompt: Analise o incidente informado usando fontes configuradas e gere um resumo com evidencias.
+  action:
+    type: prompt
+    prompt: Analise o incidente informado usando fontes configuradas e gere um resumo com evidencias.
+    external_writes: false
+  permissions:
+    mode: report-only
+  notifications:
+    - type: desktop
+      events:
+        - task.completed
+        - task.blocked
+outputs:
+  - incident-report
+risks:
+  - External logs and tickets may contain sensitive data and must be summarized.
+examples:
+  - analise esse incidente

package/runtime/workflows/release-prep/README.md

@@ -0,0 +1,3 @@
+# Release Prep
+
+Fluxo manual para preparar checklist de release, testes e verificacao de pacote.

package/runtime/workflows/release-prep/workflow.yaml

@@ -0,0 +1,30 @@
+id: release-prep
+title: Release prep
+description: Prepare a release checklist, focused tests and package verification.
+schedule:
+  type: manual
+providers:
+  - github
+permissions:
+  mode: report-only
+write_policy: local_config_write
+task:
+  title: Release prep
+  prompt: Prepare o corte de versao com checklist, testes focados e verificacao de pacote.
+  action:
+    type: prompt
+    prompt: Prepare o corte de versao com checklist, testes focados e verificacao de pacote.
+    external_writes: false
+  permissions:
+    mode: report-only
+  notifications:
+    - type: desktop
+      events:
+        - task.completed
+        - task.blocked
+outputs:
+  - release-checklist
+risks:
+  - Publishing, tagging and pushing still require explicit confirmation.
+examples:
+  - prepare o corte da proxima versao