agent-devkit 0.0.2 → 0.0.4

package/README.md

@@ -19,13 +19,14 @@ Validate the installation:
 
 ```bash
 agent --version
+agent -v
 agent doctor
 ```
 
 Expected version for this release:
 
 ```text
-agent 0.0.2
+agent 0.0.4
 ```
 
 ## Quick Start
@@ -59,6 +60,168 @@ Natural-language mode requires an LLM backend. Deterministic commands such as
 `agent agents list`, `agent capabilities list`, `agent doctor`, `agent provider`
 and `agent run` do not require an LLM.
 
+## Complete Configuration Tutorial
+
+There are three practical ways to use agents from the CLI:
+
+1. Use an official authenticated host CLI, such as Codex CLI or Claude Code.
+2. Use API keys for OpenAI, Anthropic or OpenRouter.
+3. Use a local OpenAI-compatible backend, such as Ollama.
+
+Agent DevKit does not log in directly to ChatGPT web, Claude.ai or Claude
+Desktop. To reuse a user subscription/login, it delegates to the official host
+CLI already installed and authenticated on your machine. For CI, automation or
+non-interactive servers, prefer API-key backends.
+
+### Option A: GPT through Codex CLI
+
+Install the official Codex CLI:
+
+```bash
+curl -fsSL https://chatgpt.com/codex/install.sh | sh
+```
+
+Run Codex once and complete the browser login with your ChatGPT account or API
+key:
+
+```bash
+codex
+```
+
+Verify that the binary is available:
+
+```bash
+codex --version
+```
+
+Configure Agent DevKit to use Codex CLI as the default LLM backend:
+
+```bash
+agent llm configure codex-cli --set-default
+agent llm doctor codex-cli
+```
+
+Run a prompt:
+
+```bash
+agent "analyze this repository and identify stabilization risks"
+```
+
+### Option B: Claude through Claude Code
+
+Install the official Claude Code CLI:
+
+```bash
+curl -fsSL https://claude.ai/install.sh | bash
+```
+
+Run Claude Code once and complete the browser login:
+
+```bash
+claude
+```
+
+Verify that the binary is available:
+
+```bash
+claude --version
+```
+
+Configure Agent DevKit to use Claude Code as the default LLM backend:
+
+```bash
+agent llm configure claude-code --set-default
+agent llm doctor claude-code
+```
+
+Run a prompt:
+
+```bash
+agent "plan the investigation for this production incident"
+```
+
+To switch Claude accounts later, open `claude` and use `/login` inside the
+interactive session.
+
+### Option C: OpenAI API key
+
+Agent DevKit stores credential references, not secret values. Keep the API key
+in your shell environment:
+
+```bash
+export OPENAI_API_KEY="..."
+agent llm configure openai --api-key-env OPENAI_API_KEY --model gpt-5 --set-default
+agent llm doctor openai
+```
+
+### Option D: Anthropic API key
+
+```bash
+export ANTHROPIC_API_KEY="..."
+agent llm configure anthropic --api-key-env ANTHROPIC_API_KEY --model claude-sonnet-4-5 --set-default
+agent llm doctor anthropic
+```
+
+### Option E: OpenRouter API key
+
+```bash
+export OPENROUTER_API_KEY="..."
+agent llm configure openrouter --api-key-env OPENROUTER_API_KEY --model openai/gpt-5 --set-default
+agent llm doctor openrouter
+```
+
+### Option F: Ollama local backend
+
+```bash
+ollama serve
+ollama pull qwen2.5-coder
+agent llm configure ollama --base-url http://localhost:11434/v1 --model qwen2.5-coder --set-default
+agent llm doctor ollama
+```
+
+### Switch or override the backend
+
+```bash
+agent llm list
+agent llm set-default codex-cli
+agent llm set-default claude-code
+agent llm set-default openai
+agent llm doctor
+```
+
+Use one backend for a single run:
+
+```bash
+agent --llm claude-code "analyze this incident"
+agent --llm openai "create a regression test plan"
+```
+
+## Use Agents From The CLI
+
+Agent DevKit has two execution modes:
+
+- `agent "<prompt>"`: natural-language routing; requires an LLM backend.
+- `agent run <agent> <capability>`: deterministic execution; does not require
+  an LLM backend.
+
+Natural-language example:
+
+```bash
+agent "analise o problema relatado no card 9900"
+```
+
+Deterministic example:
+
+```bash
+agent run azure-devops-orchestrator read-card --project "Project" --id 9900 --include-comments
+```
+
+Inspect a capability contract before running it:
+
+```bash
+agent inspect azure-devops-orchestrator read-card
+```
+
 ## Configure LLM Backends
 
 Agent DevKit stores references to credentials, not secret values. API keys stay
@@ -94,6 +257,13 @@ agent llm configure codex-cli --set-default
 agent llm configure claude-code --set-default
 ```
 
+Official references:
+
+- Codex CLI: https://developers.openai.com/codex/cli
+- Codex authentication: https://developers.openai.com/codex/auth
+- Claude Code quickstart: https://code.claude.com/docs/en/quickstart
+- Claude Code setup: https://code.claude.com/docs/en/setup
+
 ## Configure Providers
 
 Configure only the provider you need for a task. Missing optional providers are

package/package.json

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

package/runtime/README.md

@@ -23,6 +23,7 @@ Valide a instalacao:
 
 ```bash
 agent --version
+agent -v
 agent doctor
 ```
 
@@ -31,17 +32,19 @@ O pacote instala o comando canonico `agent`. O nome do pacote npm e
 
 ## Primeiro uso
 
-Comandos deterministicos nao precisam de LLM configurada:
+Comandos deterministicos nao precisam de LLM configurada. Use estes comandos
+para validar se o runtime esta saudavel e quais agentes existem:
 
 ```bash
 agent agents list
 agent capabilities list
 agent providers list
 agent llm list
+agent commands list
 agent doctor
 ```
 
-Instale os artefatos locais do Agent DevKit no projeto atual:
+Instale os artefatos locais do Agent DevKit no projeto em que voce trabalha:
 
 ```bash
 cd /caminho/do/projeto
@@ -49,48 +52,221 @@ agent install project --target . --host all
 agent doctor --project .
 ```
 
-Use prompts livres pelo proprio comando `agent`:
+Esse comando cria apenas arquivos de descoberta para hosts como Codex e Claude.
+Ele nao grava `.env`, nao solicita credenciais e nao persiste segredos.
+
+Depois de configurar uma LLM, voce pode usar prompt livre direto no comando
+canonico:
 
 ```bash
 agent "analise o problema relatado no card 9900"
 ```
 
 Esse modo usa backend LLM. Se nenhum backend estiver configurado, a CLI informa
-como configurar ou como executar uma capability deterministica com `agent run`.
+como configurar uma LLM ou como executar uma capability deterministica com
+`agent run`.
+
+## Tutorial completo de configuracao
+
+Existem tres formas principais de usar agentes pelo CLI:
+
+1. Usar uma CLI oficial ja autenticada, como Codex CLI ou Claude Code.
+2. Usar API key de OpenAI, Anthropic ou OpenRouter.
+3. Usar um modelo local compativel, como Ollama.
+
+O Agent DevKit nao faz login direto no ChatGPT web, Claude.ai ou Claude
+Desktop. Para reaproveitar assinatura/login de usuario, ele chama as CLIs
+oficiais instaladas na maquina. Para automacao, CI ou ambientes sem login
+interativo, prefira API key.
+
+### Opcao A: usar GPT pelo Codex CLI
+
+Instale o Codex CLI oficial:
+
+```bash
+curl -fsSL https://chatgpt.com/codex/install.sh | sh
+```
+
+Abra o Codex CLI e conclua o login com sua conta ChatGPT ou API key:
+
+```bash
+codex
+```
+
+Valide se o binario esta no `PATH`:
+
+```bash
+codex --version
+```
+
+Configure o Agent DevKit para usar o Codex CLI como backend padrao:
+
+```bash
+agent llm configure codex-cli --set-default
+agent llm doctor codex-cli
+```
+
+Execute um prompt livre:
+
+```bash
+agent "analise este repositorio e indique riscos de estabilizacao"
+```
+
+Quando este backend e usado, o Agent DevKit chama:
+
+```bash
+codex exec --skip-git-repo-check --ephemeral "<prompt>"
+```
+
+### Opcao B: usar Claude pelo Claude Code
+
+Instale o Claude Code oficial:
 
-## Configurar LLM
+```bash
+curl -fsSL https://claude.ai/install.sh | bash
+```
 
-O Agent DevKit nao grava chaves em claro. Ele salva referencias para variaveis
-de ambiente em `~/.ai-devkit/config.json`.
+Abra o Claude Code e conclua o login com sua conta Claude:
 
-OpenAI:
+```bash
+claude
+```
+
+Valide se o binario esta no `PATH`:
+
+```bash
+claude --version
+```
+
+Configure o Agent DevKit para usar Claude Code como backend padrao:
+
+```bash
+agent llm configure claude-code --set-default
+agent llm doctor claude-code
+```
+
+Execute um prompt livre:
+
+```bash
+agent "planeje a investigacao do incidente informado pelo suporte"
+```
+
+Quando este backend e usado, o Agent DevKit chama:
+
+```bash
+claude --print --permission-mode plan "<prompt>"
+```
+
+### Opcao C: usar OpenAI por API key
+
+Defina a chave no ambiente. O Agent DevKit salva apenas a referencia para a
+variavel, nao o valor da chave:
 
 ```bash
 export OPENAI_API_KEY="..."
 agent llm configure openai --api-key-env OPENAI_API_KEY --model gpt-5 --set-default
-agent llm doctor
+agent llm doctor openai
+```
+
+Uso:
+
+```bash
+agent "gere um plano de rollback para esta mudanca"
 ```
 
-Anthropic:
+### Opcao D: usar Anthropic por API key
 
 ```bash
 export ANTHROPIC_API_KEY="..."
 agent llm configure anthropic --api-key-env ANTHROPIC_API_KEY --model claude-sonnet-4-5 --set-default
+agent llm doctor anthropic
 ```
 
-OpenRouter:
+Uso:
+
+```bash
+agent "revise este plano tecnico e aponte lacunas"
+```
+
+### Opcao E: usar OpenRouter por API key
 
 ```bash
 export OPENROUTER_API_KEY="..."
 agent llm configure openrouter --api-key-env OPENROUTER_API_KEY --model openai/gpt-5 --set-default
+agent llm doctor openrouter
 ```
 
-LLMs locais ou CLIs autenticadas:
+Uso:
 
 ```bash
+agent "roteie este pedido para o agente especialista adequado"
+```
+
+### Opcao F: usar Ollama local
+
+Inicie o Ollama localmente e configure um endpoint compativel com OpenAI:
+
+```bash
+ollama serve
+ollama pull qwen2.5-coder
 agent llm configure ollama --base-url http://localhost:11434/v1 --model qwen2.5-coder --set-default
-agent llm configure codex-cli --set-default
-agent llm configure claude-code --set-default
+agent llm doctor ollama
+```
+
+Uso:
+
+```bash
+agent "explique quais capabilities podem ajudar nesta demanda"
+```
+
+### Alternar backend padrao
+
+```bash
+agent llm list
+agent llm set-default codex-cli
+agent llm set-default claude-code
+agent llm set-default openai
+agent llm doctor
+```
+
+Tambem e possivel escolher um backend apenas para uma execucao:
+
+```bash
+agent --llm claude-code "analise este incidente"
+agent --llm openai "crie um plano de testes"
+```
+
+Referencias oficiais:
+
+- Codex CLI: https://developers.openai.com/codex/cli
+- Codex authentication: https://developers.openai.com/codex/auth
+- Claude Code quickstart: https://code.claude.com/docs/en/quickstart
+- Claude Code setup: https://code.claude.com/docs/en/setup
+
+## Usar agentes por CLI
+
+Existem dois modos de execucao:
+
+- `agent "<prompt>"`: entrada em linguagem natural; exige backend LLM.
+- `agent run <agent> <capability>`: execucao deterministica; nao exige LLM.
+
+Exemplo em linguagem natural:
+
+```bash
+agent "analise o problema relatado no card 9900"
+```
+
+Exemplo deterministico:
+
+```bash
+agent run azure-devops-orchestrator read-card --project "Projeto" --id 9900 --include-comments
+```
+
+Antes de executar uma capability, voce pode inspecionar contrato, entradas e
+saidas:
+
+```bash
+agent inspect azure-devops-orchestrator read-card
 ```
 
 ## Configurar providers

package/runtime/agent

@@ -13,7 +13,7 @@ def normalize_args(argv: list[str]) -> list[str]:
         return ["agent"]
     commands = set(DETERMINISTIC_COMMANDS) | set(LLM_COMMANDS)
     first = argv[0]
-    if first in {"--help", "-h", "--version"}:
+    if first in {"--help", "-h", "--version", "-v"}:
         return argv
     if first == "--json":
         if len(argv) == 1:

package/runtime/cli/README.md

@@ -174,6 +174,67 @@ instalada aparecem no bloco de diagnostico e podem ser resolvidos sob demanda.
 
 ## Backends LLM
 
+O modo `agent "<prompt>"` exige um backend LLM. O Agent DevKit suporta tres
+familias de backend:
+
+- CLIs oficiais autenticadas fora do Agent DevKit (`codex-cli` e
+  `claude-code`).
+- APIs configuradas por referencia a variavel de ambiente (`openai`,
+  `anthropic` e `openrouter`).
+- Endpoint local compativel com OpenAI (`ollama`).
+
+O Agent DevKit nao faz login direto no ChatGPT web, Claude.ai ou Claude
+Desktop. Para usar login/assinatura de usuario, autentique primeiro a CLI
+oficial e depois configure o Agent DevKit para chama-la.
+
+### Codex CLI
+
+Instale o Codex CLI oficial:
+
+```bash
+curl -fsSL https://chatgpt.com/codex/install.sh | sh
+```
+
+Execute `codex` uma vez e conclua o login:
+
+```bash
+codex
+codex --version
+agent llm configure codex-cli --set-default
+agent llm doctor codex-cli
+```
+
+Quando este backend e usado, o runtime chama:
+
+```bash
+codex exec --skip-git-repo-check --ephemeral "<prompt>"
+```
+
+### Claude Code
+
+Instale o Claude Code oficial:
+
+```bash
+curl -fsSL https://claude.ai/install.sh | bash
+```
+
+Execute `claude` uma vez e conclua o login:
+
+```bash
+claude
+claude --version
+agent llm configure claude-code --set-default
+agent llm doctor claude-code
+```
+
+Quando este backend e usado, o runtime chama:
+
+```bash
+claude --print --permission-mode plan "<prompt>"
+```
+
+### APIs por chave
+
 O Agent DevKit nao grava chaves em claro. Backends de API sao configurados por
 referencia a variaveis de ambiente:
 
@@ -183,6 +244,31 @@ agent llm configure openai --api-key-env OPENAI_API_KEY --model gpt-5 --set-defa
 agent llm doctor openai
 ```
 
+Anthropic:
+
+```bash
+export ANTHROPIC_API_KEY="..."
+agent llm configure anthropic --api-key-env ANTHROPIC_API_KEY --model claude-sonnet-4-5 --set-default
+agent llm doctor anthropic
+```
+
+OpenRouter:
+
+```bash
+export OPENROUTER_API_KEY="..."
+agent llm configure openrouter --api-key-env OPENROUTER_API_KEY --model openai/gpt-5 --set-default
+agent llm doctor openrouter
+```
+
+### Ollama local
+
+```bash
+ollama serve
+ollama pull qwen2.5-coder
+agent llm configure ollama --base-url http://localhost:11434/v1 --model qwen2.5-coder --set-default
+agent llm doctor ollama
+```
+
 Backends suportados no MVP:
 
 - `openai`: API OpenAI ou endpoint OpenAI-compatible.
@@ -207,6 +293,13 @@ agent llm doctor
 agent llm doctor openai
 ```
 
+Tambem e possivel escolher um backend para uma unica execucao:
+
+```bash
+agent --llm claude-code "analise este incidente"
+agent --llm openai "crie um plano de testes"
+```
+
 A configuracao padrao fica em `~/.ai-devkit/config.json`. Para automacao e
 testes, use `AIKIT_CONFIG_HOME` ou `AI_DEVKIT_CONFIG_HOME` para apontar outro
 diretorio.

package/runtime/cli/aikit/__init__.py

@@ -1,3 +1,3 @@
 """Public CLI implementation for AI DevKit."""
 
-__version__ = "0.0.2"
+__version__ = "0.0.4"

package/runtime/cli/aikit/main.py

@@ -109,7 +109,7 @@ def build_parser(prog: str | None = None) -> argparse.ArgumentParser:
         description="AI DevKit CLI",
     )
     parser.add_argument("--json", action="store_true", help="print machine-readable JSON")
-    parser.add_argument("--version", action="store_true", help="print CLI version and exit")
+    parser.add_argument("-v", "--version", action="store_true", help="print CLI version and exit")
 
     subparsers = parser.add_subparsers(dest="command")
 

package/runtime/plugins/claude-code-ai-devkit/plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "claude-code-ai-devkit",
   "name": "AI DevKit",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "Thin Claude Code adapter for routing software support, infrastructure, data, and development tasks through the local AI DevKit runtime.",
   "runtime": {
     "command": "agent",

package/runtime/plugins/claude-skill-ai-devkit/plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "claude-skill-ai-devkit",
   "name": "AI DevKit Claude Skill",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "Skill bundle for Claude Desktop and Claude.ai to route support, infrastructure, data, documentation, and development work through AI DevKit practices.",
   "runtime": {
     "command": "agent",

package/runtime/scripts/README.md

@@ -34,7 +34,7 @@ python3 scripts/validate-repo.py --json
 python3 scripts/validate-repo.py --strict
 python3 scripts/mvp-readiness.py
 python3 scripts/mvp-readiness.py --json
-npm run release:verify -- v0.0.2
+npm run release:verify -- v0.0.4
 ```
 
 ## Regras

package/runtime/scripts/verify-release-alignment.mjs

@@ -63,7 +63,7 @@ function run(command, args, options = {}) {
 async function main() {
   const [rawVersion] = process.argv.slice(2);
   if (!rawVersion) {
-    throw new Error("Usage: npm run release:verify -- v0.0.2");
+    throw new Error("Usage: npm run release:verify -- v0.0.4");
   }
 
   const version = normalizeVersion(rawVersion);