agent-devkit 0.2.0 → 0.3.1

package/runtime/scripts/release-gate.py

@@ -6,6 +6,7 @@ from __future__ import annotations
 import argparse
 import json
 import os
+import shutil
 import subprocess
 import sys
 from pathlib import Path
@@ -22,6 +23,8 @@ CATALOG_SNAPSHOT = ROOT / "scripts" / "release-catalog-snapshot.json"
 CLAUDE_SKILL = ROOT / "plugins" / "claude-skill-ai-devkit" / "ai-devkit"
 CODEX_HOME = Path(os.environ.get("CODEX_HOME", Path.home() / ".codex"))
 SKILL_VALIDATOR = CODEX_HOME / "skills" / ".system" / "skill-creator" / "scripts" / "quick_validate.py"
+RELEASE_GATE_HOME = ROOT / "tmp" / "release-gate-home"
+COMMAND_TIMEOUT_SECONDS = 900
 
 
 def main() -> int:
@@ -39,18 +42,19 @@ def main() -> int:
 
 
 def run_gate(*, quick: bool = False) -> dict[str, Any]:
+    prepare_release_gate_home()
     checks = [
         check_command("agent version", [sys.executable, str(AGENT), "--version"], validate_agent_version),
         check_json("repo strict validation", [sys.executable, str(VALIDATE_REPO), "--strict", "--json"], validate_repo),
         catalog_snapshot_check(),
         check_json("mvp readiness", [sys.executable, str(MVP_READINESS), "--json"], validate_mvp_readiness),
-        check_json("v0.2.0 runtime evals", [sys.executable, str(AGENT), "eval", "run", "all", "--json"], validate_v020_evals),
+        check_json("v0.2.1 runtime evals", [sys.executable, str(AGENT), "eval", "run", "all", "--json"], validate_v021_evals),
         skill_validation_check(),
     ]
     if quick:
         checks.append(skipped_check("full unittest suite", "skipped by --quick"))
     else:
-        checks.append(check_command("full unittest suite", unittest_command(), validate_unittest))
+        checks.append(check_command("full unittest suite", unittest_command(), validate_unittest, use_release_home=False))
 
     errors = [check["message"] for check in checks if check["status"] == "failed"]
     return {
@@ -62,6 +66,11 @@ def run_gate(*, quick: bool = False) -> dict[str, Any]:
     }
 
 
+def prepare_release_gate_home() -> None:
+    shutil.rmtree(RELEASE_GATE_HOME, ignore_errors=True)
+    RELEASE_GATE_HOME.mkdir(parents=True, exist_ok=True)
+
+
 def skill_validation_check() -> dict[str, Any]:
     if not SKILL_VALIDATOR.exists():
         return skipped_check("claude skill validation", f"skill validator not found at {SKILL_VALIDATOR}")
@@ -97,8 +106,8 @@ def unittest_path_sort_key(path: Path) -> tuple[int, str]:
     return (0 if first == "tests" else 1, str(relative))
 
 
-def check_json(name: str, command: list[str], validator) -> dict[str, Any]:
-    result = run(command)
+def check_json(name: str, command: list[str], validator, *, use_release_home: bool = True) -> dict[str, Any]:
+    result = run(command, use_release_home=use_release_home)
     if result.returncode != 0:
         return failed_check(name, f"returncode {result.returncode}", result)
     try:
@@ -113,8 +122,8 @@ def check_json(name: str, command: list[str], validator) -> dict[str, Any]:
     return check
 
 
-def check_command(name: str, command: list[str], validator) -> dict[str, Any]:
-    result = run(command)
+def check_command(name: str, command: list[str], validator, *, use_release_home: bool = True) -> dict[str, Any]:
+    result = run(command, use_release_home=use_release_home)
     if result.returncode != 0:
         return failed_check(name, f"returncode {result.returncode}", result)
     message = validator(result)
@@ -123,18 +132,30 @@ def check_command(name: str, command: list[str], validator) -> dict[str, Any]:
     return ok_check(name, result)
 
 
-def run(command: list[str]) -> subprocess.CompletedProcess[str]:
+def run(command: list[str], *, use_release_home: bool = True) -> subprocess.CompletedProcess[str]:
+    env = command_env(use_release_home=use_release_home)
     return subprocess.run(
         command,
         cwd=ROOT,
         check=False,
+        env=env,
         text=True,
         stdout=subprocess.PIPE,
         stderr=subprocess.PIPE,
-        timeout=360,
+        timeout=COMMAND_TIMEOUT_SECONDS,
     )
 
 
+def command_env(*, use_release_home: bool) -> dict[str, str]:
+    env = os.environ.copy()
+    if use_release_home:
+        env["AGENT_DEVKIT_HOME"] = str(RELEASE_GATE_HOME)
+        return env
+    for name in ("AGENT_DEVKIT_HOME", "AI_DEVKIT_CONFIG_HOME", "AIKIT_CONFIG_HOME"):
+        env.pop(name, None)
+    return env
+
+
 def validate_agent_version(result: subprocess.CompletedProcess[str]) -> str | None:
     if not result.stdout.startswith("agent "):
         return "agent --version did not report the agent command"
@@ -260,14 +281,34 @@ def validate_mvp_readiness(payload: dict[str, Any]) -> str | None:
     return None
 
 
-def validate_v020_evals(payload: dict[str, Any]) -> str | None:
+def validate_v021_evals(payload: dict[str, Any]) -> str | None:
     if payload.get("kind") != "eval-run" or payload.get("suite") != "all":
-        return "v0.2.0 eval command returned an unexpected payload"
+        return "v0.2.1 eval command returned an unexpected payload"
     if payload.get("status") != "passed":
-        return "v0.2.0 runtime evals did not pass"
+        return "v0.2.1 runtime evals did not pass"
     checks = payload.get("checks") or []
-    if not isinstance(checks, list) or len(checks) < 5:
-        return "v0.2.0 runtime evals returned too few suites"
+    required = {
+        "routing",
+        "catalog",
+        "wizard",
+        "source_config",
+        "identity_enforcement",
+        "review_gate",
+        "model_router",
+        "agentic_plan",
+        "mcp",
+        "workflow_contract",
+        "extension_contract",
+        "contribution_contract",
+        "team_contract",
+        "knowledge_contract",
+        "secret_refs",
+        "prompt-injection",
+    }
+    suites = {item.get("suite") for item in checks if isinstance(item, dict)}
+    missing = sorted(required - suites)
+    if missing:
+        return f"v0.2.1 runtime evals missing suites: {', '.join(missing)}"
     return None
 
 

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
@@ -44,10 +54,14 @@
 
 ## User Directives
 1. **[2026-06-28] Rodar testes focados durante patches**
-   Do instead: para melhorias intermediarias, executar apenas testes necessarios para validar o patch; reservar suite completa para o fechamento do conjunto de melhorias.
-2. **[2026-06-22] Implement agentic specs individually**
+   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.
-3. **[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.
-4. **[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