agent-devkit 0.0.1 → 0.0.3

package/README.md

@@ -1,12 +1,182 @@
-# Agent DevKit npm package
+# Agent DevKit
 
-Install the Agent DevKit CLI from npm:
+Agent DevKit is a CLI runtime for specialist AI agents, capabilities,
+provider-aware automations and local host adapters for Codex and Claude.
+
+The npm package installs the canonical command:
+
+```bash
+agent
+```
+
+## Install
 
 ```bash
 npm install -g agent-devkit
+```
+
+Validate the installation:
+
+```bash
 agent --version
+agent -v
 agent doctor
 ```
 
-The npm package installs the canonical `agent` command. The runtime remains
-provider-aware and stores credentials only by reference.
+Expected version for this release:
+
+```text
+agent 0.0.3
+```
+
+## Quick Start
+
+List available agents and capabilities:
+
+```bash
+agent agents list
+agent capabilities list
+agent providers list
+agent llm list
+agent commands list
+```
+
+Install project-local host artifacts for Codex, Claude Code and Claude
+Desktop/Claude.ai:
+
+```bash
+cd /path/to/your/project
+agent install project --target . --host all
+agent doctor --project .
+```
+
+Run a natural-language task:
+
+```bash
+agent "analise o problema relatado no card 9900"
+```
+
+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.
+
+## Configure LLM Backends
+
+Agent DevKit stores references to credentials, not secret values. API keys stay
+in environment variables.
+
+OpenAI:
+
+```bash
+export OPENAI_API_KEY="..."
+agent llm configure openai --api-key-env OPENAI_API_KEY --model gpt-5 --set-default
+agent llm doctor
+```
+
+Anthropic:
+
+```bash
+export ANTHROPIC_API_KEY="..."
+agent llm configure anthropic --api-key-env ANTHROPIC_API_KEY --model claude-sonnet-4-5 --set-default
+```
+
+OpenRouter:
+
+```bash
+export OPENROUTER_API_KEY="..."
+agent llm configure openrouter --api-key-env OPENROUTER_API_KEY --model openai/gpt-5 --set-default
+```
+
+Local or host-authenticated backends:
+
+```bash
+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
+```
+
+## Configure Providers
+
+Configure only the provider you need for a task. Missing optional providers are
+reported as partial diagnostics and do not break local discovery.
+
+Azure DevOps:
+
+```bash
+export AZURE_DEVOPS_ORG="your-org"
+export AZURE_DEVOPS_PAT="..."
+agent provider configure azure-devops --env AZURE_DEVOPS_ORG --env AZURE_DEVOPS_PAT
+agent provider doctor azure-devops
+```
+
+AWS:
+
+```bash
+export AWS_PROFILE="default"
+export AWS_REGION="us-east-1"
+agent provider configure aws --env AWS_PROFILE --env AWS_REGION
+agent provider doctor aws
+```
+
+TOPdesk:
+
+```bash
+export TOPDESK_BASE_URL="https://your-instance.topdesk.net"
+export TOPDESK_USERNAME="user"
+export TOPDESK_APP_PASSWORD="..."
+agent provider configure topdesk --env TOPDESK_BASE_URL --env TOPDESK_USERNAME --env TOPDESK_APP_PASSWORD
+agent provider doctor topdesk
+```
+
+You can also inspect a credentials file without printing secret values:
+
+```bash
+agent credential resolve topdesk --env-file ./topdesk.env
+```
+
+## Deterministic Capability Runs
+
+Use `agent run` when you want direct execution without natural-language routing:
+
+```bash
+agent run azure-devops-orchestrator read-card --project "Project" --id 9900 --include-comments
+agent run aws-cloudwatch-log-analyzer search-log-events --help
+```
+
+Inspect a capability contract before running it:
+
+```bash
+agent inspect azure-devops-orchestrator read-card
+```
+
+## Memory
+
+Agent DevKit can keep local usage memory for routines and source preferences:
+
+```bash
+agent memory show
+agent memory reset --all
+```
+
+## Host Installation
+
+Install only one host adapter when needed:
+
+```bash
+agent install project --target . --host codex
+agent install project --target . --host claude-code
+agent install project --target . --host claude-desktop
+agent install global --host all
+```
+
+Preview writes without touching the filesystem:
+
+```bash
+agent install project --target . --host all --dry-run --json
+```
+
+## Links
+
+- GitHub: https://github.com/jhenriquedev/agent-devkit
+- npm: https://www.npmjs.com/package/agent-devkit
+- License: MIT

package/package.json

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

package/runtime/README.md

@@ -11,6 +11,138 @@ Nome publico do projeto no GitHub: `agent-devkit`. Nome do produto:
 > versionados e prontos para uso, com baixo consumo de contexto, decisoes mais
 > consistentes e artefatos padronizados.
 
+## Instalacao rapida
+
+Instale o CLI publicado no npm:
+
+```bash
+npm install -g agent-devkit
+```
+
+Valide a instalacao:
+
+```bash
+agent --version
+agent -v
+agent doctor
+```
+
+O pacote instala o comando canonico `agent`. O nome do pacote npm e
+`agent-devkit`.
+
+## Primeiro uso
+
+Comandos deterministicos nao precisam de LLM configurada:
+
+```bash
+agent agents list
+agent capabilities list
+agent providers list
+agent llm list
+agent doctor
+```
+
+Instale os artefatos locais do Agent DevKit no projeto atual:
+
+```bash
+cd /caminho/do/projeto
+agent install project --target . --host all
+agent doctor --project .
+```
+
+Use prompts livres pelo proprio comando `agent`:
+
+```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`.
+
+## Configurar LLM
+
+O Agent DevKit nao grava chaves em claro. Ele salva referencias para variaveis
+de ambiente em `~/.ai-devkit/config.json`.
+
+OpenAI:
+
+```bash
+export OPENAI_API_KEY="..."
+agent llm configure openai --api-key-env OPENAI_API_KEY --model gpt-5 --set-default
+agent llm doctor
+```
+
+Anthropic:
+
+```bash
+export ANTHROPIC_API_KEY="..."
+agent llm configure anthropic --api-key-env ANTHROPIC_API_KEY --model claude-sonnet-4-5 --set-default
+```
+
+OpenRouter:
+
+```bash
+export OPENROUTER_API_KEY="..."
+agent llm configure openrouter --api-key-env OPENROUTER_API_KEY --model openai/gpt-5 --set-default
+```
+
+LLMs locais ou CLIs autenticadas:
+
+```bash
+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
+```
+
+## Configurar providers
+
+Providers tambem sao configurados por referencia. Configure apenas o que for
+necessario para a tarefa; o agente pode seguir com fallback quando um provider
+opcional nao estiver disponivel.
+
+Azure DevOps:
+
+```bash
+export AZURE_DEVOPS_ORG="sua-org"
+export AZURE_DEVOPS_PAT="..."
+agent provider configure azure-devops --env AZURE_DEVOPS_ORG --env AZURE_DEVOPS_PAT
+agent provider doctor azure-devops
+```
+
+AWS:
+
+```bash
+export AWS_PROFILE="default"
+export AWS_REGION="us-east-1"
+agent provider configure aws --env AWS_PROFILE --env AWS_REGION
+agent provider doctor aws
+```
+
+TOPdesk:
+
+```bash
+export TOPDESK_BASE_URL="https://sua-instancia.topdesk.net"
+export TOPDESK_USERNAME="usuario"
+export TOPDESK_APP_PASSWORD="..."
+agent provider configure topdesk --env TOPDESK_BASE_URL --env TOPDESK_USERNAME --env TOPDESK_APP_PASSWORD
+agent provider doctor topdesk
+```
+
+Exemplo de uso deterministico com uma capability:
+
+```bash
+agent run azure-devops-orchestrator read-card --project "Projeto" --id 9900 --include-comments
+```
+
+Comandos uteis:
+
+```bash
+agent commands list
+agent inspect azure-devops-orchestrator read-card
+agent memory show
+agent memory reset --all
+```
+
 ## O que e
 
 O Agent DevKit e um repositorio agent-native. Seu produto principal nao e uma pasta

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/aikit/__init__.py

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

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.1",
+  "version": "0.0.3",
   "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.1",
+  "version": "0.0.3",
   "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.1
+npm run release:verify -- v0.0.3
 ```
 
 ## 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.1");
+    throw new Error("Usage: npm run release:verify -- v0.0.3");
   }
 
   const version = normalizeVersion(rawVersion);