@jmanuelcorral/openteam 0.1.0 → 0.1.2

package/README.md

@@ -1,315 +1,358 @@
-# openteam
-
-**openteam — plugin de opencode con routing coste-consciente local-first, fallback FRONTIER cheapest-capable y orquestación multiagente tipo Squad.**
-
-## Tabla de contenidos
-
-- [Qué es y por qué existe](#qué-es-y-por-qué-existe)
-- [Características](#características)
-- [Requisitos](#requisitos)
-- [Instalación](#instalación)
-- [Configuración](#configuración)
-- [Uso](#uso)
-- [Ejemplos en Windows](#ejemplos-en-windows)
-- [Privacidad](#privacidad)
-- [Calidad](#calidad)
-- [Compatibilidad](#compatibilidad)
-- [Roadmap](#roadmap)
-- [Licencia](#licencia)
-
-## Qué es y por qué existe
-
-openteam añade a opencode una capa de routing y orquestación para ahorrar tokens y coste frontier sin perder calidad ni privacidad. La estrategia por defecto es **local-first**: tareas triviales, resúmenes, documentación sencilla y diffs pequeños intentan usar runtimes locales; tareas de arquitectura, seguridad, refactors multiarchivo, tool calling crítico o debugging ambiguo escalan a **FRONTIER cheapest-capable**.
-
-El router mantiene una garantía de privacidad: con `privacyMode: "forceLocalOnSensitive"`, una tarea marcada como `privacySensitive` no escala a frontier.
-
-## Características
-
-- Routing por turno desde el hook `chat.message`, mutando `output.message.model` antes de que opencode persista el mensaje.
-- Registro de runtimes locales OpenAI-compatible: Ollama, LM Studio y Foundry Local.
-- Clasificador local JSON con fallback heurístico determinista.
-- Perfiles de capacidad desde Models.dev, con cache y fallback curado cuando el catálogo no está disponible.
-- Selección frontier **cheapest-capable** por coste blended `0.75 * inputUSD + 0.25 * outputUSD`.
-- Presupuestos por sesión, mes y tokens frontier por sesión.
-- Telemetría `CostRecord` JSONL hash-only: guarda `promptHash`, métricas de coste y decisión, nunca prompts crudos.
-- Orquestación Squad con `runRoleTask` / `runRoleTasks`, subsesiones SDK y modelo explícito en `client.session.prompt({ body: { model } })`.
-- Refresh de disponibilidad local al arrancar y en eventos `session.created` / `session.idle`.
-
-## Requisitos
-
-- opencode compatible con `@opencode-ai/plugin` `1.17.13`.
-- Bun `>=1.3` para desarrollo y tests.
-- Runtimes locales opcionales:
-  - Ollama en `http://localhost:11434/v1`.
-  - LM Studio en `http://localhost:1234/v1`.
-  - Foundry Local con puerto dinámico descubierto por CLI en Windows.
-
-## Instalación
-
-### Opción A: paquete npm
-
-El paquete se publica como `@jmanuelcorral/openteam`. opencode instala los plugins declarados en el array `plugin` de `opencode.json`; basta con referenciar el nombre del paquete:
-
-```jsonc
-{
-  "$schema": "https://opencode.ai/config.json",
-  "model": "anthropic/claude-sonnet-4-5",
-  "small_model": "ollama/qwen3:8b",
-  "plugin": [
-    [
-      "@jmanuelcorral/openteam",
-      {
-        "baseline": {
-          "mode": "auto",
-          "pinnedModel": null,
-          "hardDefault": {
-            "providerID": "anthropic",
-            "modelID": "claude-sonnet-4-5"
-          }
-        },
-        "router": {
-          "mode": "balanced",
-          "localDefault": {
-            "providerID": "ollama",
-            "modelID": "qwen3:8b"
-          },
-          "trivialPromptMaxChars": 280,
-          "frontierPromptMinChars": 2000
-        },
-        "local": {
-          "runtimes": [
-            {
-              "id": "ollama",
-              "enabled": true,
-              "baseURL": "http://localhost:11434/v1",
-              "defaultModel": {
-                "providerID": "ollama",
-                "modelID": "qwen3:8b"
-              }
-            },
-            {
-              "id": "lmstudio",
-              "enabled": true,
-              "baseURL": "http://localhost:1234/v1",
-              "defaultModel": {
-                "providerID": "lmstudio",
-                "modelID": "qwen2.5-coder-local"
-              }
-            }
-          ]
-        },
-        "budgets": {
-          "sessionUSD": 2,
-          "monthlyUSD": 30,
-          "frontierTokensPerSession": 250000,
-          "hardStopOnBudgetExhaustion": false
-        },
-        "privacyMode": "forceLocalOnSensitive",
-        "telemetry": {
-          "enabled": true,
-          "path": ".opencode/openteam-telemetry.jsonl"
-        }
-      }
-    ]
-  ],
-  "provider": {
-    "ollama": {
-      "npm": "@ai-sdk/openai-compatible",
-      "name": "Ollama (local)",
-      "options": {
-        "baseURL": "http://localhost:11434/v1",
-        "apiKey": "ollama",
-        "chunkTimeout": 60000
-      },
-      "models": {
-        "qwen3:8b": {
-          "name": "Qwen3 8B (Ollama)",
-          "tool_call": true,
-          "limit": { "context": 32768, "output": 8192 }
-        }
-      }
-    },
-    "lmstudio": {
-      "npm": "@ai-sdk/openai-compatible",
-      "name": "LM Studio (local)",
-      "options": {
-        "baseURL": "http://localhost:1234/v1",
-        "apiKey": "lm-studio"
-      },
-      "models": {
-        "qwen2.5-coder-local": {
-          "name": "Qwen2.5 Coder Local",
-          "tool_call": true,
-          "limit": { "context": 32768, "output": 8192 }
-        }
-      }
-    }
-  }
-}
-```
-
-### Opción B: ruta de desarrollo
-
-Durante desarrollo puedes cargar un plugin local desde `.opencode/plugins/openteam.ts`:
-
-```jsonc
-{
-  "$schema": "https://opencode.ai/config.json",
-  "plugin": [
-    [
-      "./.opencode/plugins/openteam.ts",
-      {
-        "router": {
-          "mode": "balanced",
-          "localDefault": {
-            "providerID": "ollama",
-            "modelID": "qwen3:8b"
-          }
-        },
-        "telemetry": {
-          "path": ".opencode/openteam-telemetry.jsonl"
-        }
-      }
-    ]
-  ]
-}
-```
-
-## Configuración
-
-La configuración runtime canónica vive en `.opencode/openteam.json`; este repositorio incluye `.opencode/openteam.example.json` como ejemplo completo. La forma validada por Zod es la de `src/config/schema.ts`. `telemetry` es una opción del plugin leída por `src/index.ts`, no parte del objeto `OpenTeamConfig` persistido.
-
-| Key | Tipo | Default | Descripción |
-| --- | --- | --- | --- |
-| `baseline.mode` | `"auto" \| "pinned"` | `"auto"` | En `auto`, usa perfiles frontier cheapest-capable cuando se pasan al router; en `pinned`, usa `baseline.pinnedModel` si existe. |
-| `baseline.pinnedModel` | `ModelRef \| null` | `null` | Modelo frontier fijado explícitamente. `ModelRef` usa `{ "providerID": string, "modelID": string }`. |
-| `baseline.hardDefault` | `ModelRef` | `{ "providerID": "anthropic", "modelID": "claude-sonnet-4-5" }` | Fallback frontier si no hay perfiles cheapest-capable o pin válido. |
-| `router.mode` | `"economy" \| "balanced" \| "quality"` | `"balanced"` | Modo de routing validado y reservado para política. |
-| `router.localDefault` | `ModelRef` | `{ "providerID": "ollama", "modelID": "qwen3:8b" }` | Modelo local principal. |
-| `router.trivialPromptMaxChars` | `number` entero positivo | `280` | Prompts sin código hasta este tamaño prefieren local. |
-| `router.frontierPromptMinChars` | `number` entero positivo | `2000` | Prompts desde este tamaño se tratan como candidatos a frontier si no aplican guards. |
-| `local.runtimes` | `LocalRuntime[]` | Ollama enabled en `http://localhost:11434/v1` con `qwen3:8b` | Lista mínima de un runtime local. |
-| `local.runtimes[].id` | `"ollama" \| "lmstudio" \| "foundry-local"` | requerido | Runtime local. |
-| `local.runtimes[].enabled` | `boolean` | `true` | Habilita o deshabilita ese runtime. |
-| `local.runtimes[].baseURL` | URL opcional | según runtime/config | Endpoint OpenAI-compatible `/v1`; Foundry Local puede omitirlo si usa discovery. |
-| `local.runtimes[].discovery` | `"cli" \| "sdk" \| "manual"` opcional | sin default por item | Discovery de Foundry Local; el registry usa CLI si está configurado y no es `manual`. |
-| `local.runtimes[].defaultModel` | `ModelRef` | requerido | Modelo por defecto de ese runtime. |
-| `budgets.sessionUSD` | `number` positivo opcional | sin límite | Presupuesto frontier por sesión. |
-| `budgets.monthlyUSD` | `number` positivo opcional | sin límite | Presupuesto frontier mensual. |
-| `budgets.frontierTokensPerSession` | `number` entero positivo opcional | sin límite | Límite de tokens frontier por sesión. |
-| `budgets.hardStopOnBudgetExhaustion` | `boolean` | `false` | Si es `true`, agotar presupuesto devuelve `blockFrontier`; si es `false`, fuerza local. |
-| `privacyMode` | `"forceLocalOnSensitive" \| "consentBeforeFrontier" \| "off"` | `"forceLocalOnSensitive"` | Política de privacidad para tareas sensibles. |
-| `telemetry.enabled` | `boolean` plugin option | `true` | Activa/desactiva escritura JSONL. |
-| `telemetry.path` | `string` plugin option | `.opencode/openteam-telemetry.jsonl` | Ruta del log `CostRecord` JSONL. |
-
-## Uso
-
-En cada turno, openteam deriva señales del prompt (`promptChars`, `hasCode`, `privacySensitive`, `requiresTools` y override de modelo si existe), ejecuta `chooseModel` y asigna `output.message.model`.
-
-La orquestación Squad usa roles estáticos y subsesiones opencode:
-
-| Rol | Agent opencode | Tier base | Política |
-| --- | --- | --- | --- |
-| `rusty` | `architect` | `hard` | Arquitectura y decisiones de alto riesgo; frontier auto. |
-| `livingston` | `integration` | `moderate` | Integración TS/opencode; tool calling por defecto. |
-| `yen` | `local-runtime` | `moderate` | Runtimes locales; local-first con fallback frontier. |
-| `basher` | `routing-cost` | `moderate` | Router, coste y presupuesto; local-first. |
-| `scribe` | `scribe` | `trivial` | Documentación y resúmenes; local-first. |
-| `linus` | `tester` | `simple` | Tests y contratos; local-first con tools. |
-
-`runRoleTask` ejecuta una subsesión; `runRoleTasks` ejecuta varias con `batchID`. Los roles con `destructive` o `multiFileEdit` elevan el tier antes de elegir modelo.
-
-Para ver ahorro y decisiones, revisa el JSONL de telemetría. Campos clave: `promptHash`, `promptChars`, `tier`, `routeKind`, `selected`, `rationale`, `estimatedCostUSD`, `baselineCostUSD`, `estimatedSavingsUSD`, `budgetAction`, `tokensIn` y `tokensOut`.
-
-## Ejemplos en Windows
-
-### Ollama
-
-```powershell
-ollama serve
-ollama pull qwen3:8b
-Invoke-RestMethod -Uri "http://localhost:11434/v1/models" -Method Get
-```
-
-### LM Studio
-
-1. Abre LM Studio.
-2. Carga un modelo compatible.
-3. Activa el servidor local OpenAI-compatible en el puerto `1234`.
-
-```powershell
-Invoke-RestMethod -Uri "http://localhost:1234/v1/models" -Method Get
-```
-
-### Foundry Local
-
-```powershell
-foundry service status
-```
-
-openteam extrae el puerto de la salida del CLI y normaliza el endpoint a `http://localhost:<PORT>/v1`.
-
-### Telemetría
-
-```powershell
-$telemetryPath = "C:\gitrepos\openteam\.opencode\openteam-telemetry.jsonl"
-Get-Content -Path $telemetryPath -Tail 5
-```
-
-### Verificación local
-
-```powershell
-Set-Location -Path "C:\gitrepos\openteam"
-bun test
-bun run typecheck
-bun run lint
-bun run format:check
-# Cuando el empaquetado de Fase 4 exponga el script:
-bun run build
-```
-
-## Privacidad
-
-Con `privacyMode: "forceLocalOnSensitive"`, si `TaskSignals.privacySensitive` es `true`, `chooseModel` usa local y no permite fallback frontier. Si no hay local utilizable, la decisión conserva la ruta local y registra la razón en `rationale`.
-
-La telemetría usa `hashPrompt`, actualmente `fnv1a32:<hash>`, y no serializa el prompt completo.
-
-## Calidad
-
-Gates no negociables:
-
-- `bun test`
-- Coverage global: líneas `>= 85%`, branches `>= 80%`.
-- Coverage de `src/router/**`: `100%` lines, branches, statements y functions.
-- `bun run typecheck`
-- `biome check .` o `bun run lint` + `bun run format:check`
-- Test de determinismo del router.
-- Tests de contrato si cambian hooks opencode, agents, comandos, providers o SDK.
-
-Estado actual de Fases 0-3: **202 tests verdes**.
-
-## Compatibilidad
-
-Consulta [docs/compatibility.md](docs/compatibility.md). Resumen verificado el `2026-07-06`:
-
-| Superficie | Versión / contrato |
-| --- | --- |
-| openteam | `0.1.0` para Fase 4 npm + docs |
-| `@opencode-ai/plugin` | `1.17.13` |
-| `@opencode-ai/sdk` | `1.17.13` |
-| Hook de routing | `chat.message`; no `chat.params` para cambiar modelo |
-| Subsesiones | `client.session.create` + `client.session.prompt({ body: { model } })` |
-
-## Roadmap
-
-| Fase | Estado | Entregables |
-| --- | --- | --- |
-| 0. Scaffold/PoC | Hecha | TS/Bun, plugin mínimo, hook `chat.message`. |
-| 1. Local registry + router heurístico | Hecha | Ollama/LM Studio/Foundry, probes y `chooseModel` determinista. |
-| 2. Clasificador + perfiles + presupuesto + telemetría | Hecha | Clasificador local, `ModelCapabilityProfile`, budgets y `CostRecord`. |
-| 3. Orquestación multiagente | Hecha | Coordinator, roles, child sessions y permisos. |
-| 4. Empaquetado npm + docs | En curso | Package exportable, README, ejemplos Windows y matriz de compatibilidad. |
-
-## Licencia
-
-MIT. Consulta [LICENSE](LICENSE).
+# openteam
+
+**openteam — plugin de opencode con routing coste-consciente local-first, fallback FRONTIER cheapest-capable y orquestación multiagente tipo Squad.**
+
+## Tabla de contenidos
+
+- [Qué es y por qué existe](#qué-es-y-por-qué-existe)
+- [Características](#características)
+- [Requisitos](#requisitos)
+- [Instalación](#instalación)
+- [Configuración](#configuración)
+- [Uso](#uso)
+- [Ejemplos en Windows](#ejemplos-en-windows)
+- [Privacidad](#privacidad)
+- [Calidad](#calidad)
+- [Compatibilidad](#compatibilidad)
+- [Roadmap](#roadmap)
+- [Licencia](#licencia)
+
+## Qué es y por qué existe
+
+openteam añade a opencode una capa de routing y orquestación para ahorrar tokens y coste frontier sin perder calidad ni privacidad. La estrategia por defecto es **local-first**: tareas triviales, resúmenes, documentación sencilla y diffs pequeños intentan usar runtimes locales; tareas de arquitectura, seguridad, refactors multiarchivo, tool calling crítico o debugging ambiguo escalan a **FRONTIER cheapest-capable**.
+
+El router mantiene una garantía de privacidad: con `privacyMode: "forceLocalOnSensitive"`, una tarea marcada como `privacySensitive` no escala a frontier.
+
+## Características
+
+- Routing por turno desde el hook `chat.message`, mutando `output.message.model` antes de que opencode persista el mensaje.
+- Registro de runtimes locales OpenAI-compatible: Ollama, LM Studio y Foundry Local.
+- Clasificador local JSON con fallback heurístico determinista.
+- Perfiles de capacidad desde Models.dev, con cache y fallback curado cuando el catálogo no está disponible.
+- Selección frontier **cheapest-capable** por coste blended `0.75 * inputUSD + 0.25 * outputUSD`.
+- Presupuestos por sesión, mes y tokens frontier por sesión.
+- Telemetría `CostRecord` JSONL hash-only: guarda `promptHash`, métricas de coste y decisión, nunca prompts crudos.
+- Orquestación Squad con `runRoleTask` / `runRoleTasks`, subsesiones SDK y modelo explícito en `client.session.prompt({ body: { model } })`.
+- Refresh de disponibilidad local al arrancar y en eventos `session.created` / `session.idle`.
+
+## Requisitos
+
+- opencode compatible con `@opencode-ai/plugin` `1.17.13`.
+- Bun `>=1.3` para desarrollo y tests.
+- Runtimes locales opcionales:
+  - Ollama en `http://localhost:11434/v1`.
+  - LM Studio en `http://localhost:1234/v1`.
+  - Foundry Local con puerto dinámico descubierto por CLI en Windows.
+
+## Instalación
+
+### Opción A: paquete npm
+
+El paquete se publica como `@jmanuelcorral/openteam`. opencode instala los plugins declarados en el array `plugin` de `opencode.json`; basta con referenciar el nombre del paquete:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "model": "anthropic/claude-sonnet-4-5",
+  "small_model": "ollama/qwen3:8b",
+  "plugin": [
+    [
+      "@jmanuelcorral/openteam",
+      {
+        "baseline": {
+          "mode": "auto",
+          "pinnedModel": null,
+          "hardDefault": {
+            "providerID": "anthropic",
+            "modelID": "claude-sonnet-4-5"
+          }
+        },
+        "router": {
+          "mode": "balanced",
+          "localDefault": {
+            "providerID": "ollama",
+            "modelID": "qwen3:8b"
+          },
+          "trivialPromptMaxChars": 280,
+          "frontierPromptMinChars": 2000
+        },
+        "local": {
+          "runtimes": [
+            {
+              "id": "ollama",
+              "enabled": true,
+              "baseURL": "http://localhost:11434/v1",
+              "defaultModel": {
+                "providerID": "ollama",
+                "modelID": "qwen3:8b"
+              }
+            },
+            {
+              "id": "lmstudio",
+              "enabled": true,
+              "baseURL": "http://localhost:1234/v1",
+              "defaultModel": {
+                "providerID": "lmstudio",
+                "modelID": "qwen2.5-coder-local"
+              }
+            }
+          ]
+        },
+        "budgets": {
+          "sessionUSD": 2,
+          "monthlyUSD": 30,
+          "frontierTokensPerSession": 250000,
+          "hardStopOnBudgetExhaustion": false
+        },
+        "privacyMode": "forceLocalOnSensitive",
+        "telemetry": {
+          "enabled": true,
+          "path": ".opencode/openteam-telemetry.jsonl"
+        }
+      }
+    ]
+  ],
+  "provider": {
+    "ollama": {
+      "npm": "@ai-sdk/openai-compatible",
+      "name": "Ollama (local)",
+      "options": {
+        "baseURL": "http://localhost:11434/v1",
+        "apiKey": "ollama",
+        "chunkTimeout": 60000
+      },
+      "models": {
+        "qwen3:8b": {
+          "name": "Qwen3 8B (Ollama)",
+          "tool_call": true,
+          "limit": { "context": 32768, "output": 8192 }
+        }
+      }
+    },
+    "lmstudio": {
+      "npm": "@ai-sdk/openai-compatible",
+      "name": "LM Studio (local)",
+      "options": {
+        "baseURL": "http://localhost:1234/v1",
+        "apiKey": "lm-studio"
+      },
+      "models": {
+        "qwen2.5-coder-local": {
+          "name": "Qwen2.5 Coder Local",
+          "tool_call": true,
+          "limit": { "context": 32768, "output": 8192 }
+        }
+      }
+    }
+  }
+}
+```
+
+### Opción B: ruta de desarrollo
+
+Durante desarrollo puedes cargar un plugin local desde `.opencode/plugins/openteam.ts`:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    [
+      "./.opencode/plugins/openteam.ts",
+      {
+        "router": {
+          "mode": "balanced",
+          "localDefault": {
+            "providerID": "ollama",
+            "modelID": "qwen3:8b"
+          }
+        },
+        "telemetry": {
+          "path": ".opencode/openteam-telemetry.jsonl"
+        }
+      }
+    ]
+  ]
+}
+```
+
+## Configuración
+
+La configuración runtime canónica vive en `.opencode/openteam.json`; este repositorio incluye `.opencode/openteam.example.json` como ejemplo completo. La forma validada por Zod es la de `src/config/schema.ts`. `telemetry` es una opción del plugin leída por `src/index.ts`, no parte del objeto `OpenTeamConfig` persistido.
+
+| Key | Tipo | Default | Descripción |
+| --- | --- | --- | --- |
+| `baseline.mode` | `"auto" \| "pinned"` | `"auto"` | En `auto`, usa perfiles frontier cheapest-capable cuando se pasan al router; en `pinned`, usa `baseline.pinnedModel` si existe. |
+| `baseline.pinnedModel` | `ModelRef \| null` | `null` | Modelo frontier fijado explícitamente. `ModelRef` usa `{ "providerID": string, "modelID": string }`. |
+| `baseline.hardDefault` | `ModelRef` | `{ "providerID": "anthropic", "modelID": "claude-sonnet-4-5" }` | Fallback frontier si no hay perfiles cheapest-capable o pin válido. |
+| `router.mode` | `"economy" \| "balanced" \| "quality"` | `"balanced"` | Modo de routing validado y reservado para política. |
+| `router.localDefault` | `ModelRef` | `{ "providerID": "ollama", "modelID": "qwen3:8b" }` | Modelo local principal. |
+| `router.trivialPromptMaxChars` | `number` entero positivo | `280` | Prompts sin código hasta este tamaño prefieren local. |
+| `router.frontierPromptMinChars` | `number` entero positivo | `2000` | Prompts desde este tamaño se tratan como candidatos a frontier si no aplican guards. |
+| `local.runtimes` | `LocalRuntime[]` | Ollama enabled en `http://localhost:11434/v1` con `qwen3:8b` | Lista mínima de un runtime local. |
+| `local.runtimes[].id` | `"ollama" \| "lmstudio" \| "foundry-local"` | requerido | Runtime local. |
+| `local.runtimes[].enabled` | `boolean` | `true` | Habilita o deshabilita ese runtime. |
+| `local.runtimes[].baseURL` | URL opcional | según runtime/config | Endpoint OpenAI-compatible `/v1`; Foundry Local puede omitirlo si usa discovery. |
+| `local.runtimes[].discovery` | `"cli" \| "sdk" \| "manual"` opcional | sin default por item | Discovery de Foundry Local; el registry usa CLI si está configurado y no es `manual`. |
+| `local.runtimes[].defaultModel` | `ModelRef` | requerido | Modelo por defecto de ese runtime. |
+| `budgets.sessionUSD` | `number` positivo opcional | sin límite | Presupuesto frontier por sesión. |
+| `budgets.monthlyUSD` | `number` positivo opcional | sin límite | Presupuesto frontier mensual. |
+| `budgets.frontierTokensPerSession` | `number` entero positivo opcional | sin límite | Límite de tokens frontier por sesión. |
+| `budgets.hardStopOnBudgetExhaustion` | `boolean` | `false` | Si es `true`, agotar presupuesto devuelve `blockFrontier`; si es `false`, fuerza local. |
+| `privacyMode` | `"forceLocalOnSensitive" \| "consentBeforeFrontier" \| "off"` | `"forceLocalOnSensitive"` | Política de privacidad para tareas sensibles. |
+| `telemetry.enabled` | `boolean` plugin option | `true` | Activa/desactiva escritura JSONL. |
+| `telemetry.path` | `string` plugin option | `.opencode/openteam-telemetry.jsonl` | Ruta del log `CostRecord` JSONL. |
+
+## Uso
+
+En cada turno, openteam deriva señales del prompt (`promptChars`, `hasCode`, `privacySensitive`, `requiresTools` y override de modelo si existe), ejecuta `chooseModel` y asigna `output.message.model`.
+
+La orquestación Squad usa roles estáticos y subsesiones opencode:
+
+| Rol | Agent opencode | Tier base | Política |
+| --- | --- | --- | --- |
+| `rusty` | `architect` | `hard` | Arquitectura y decisiones de alto riesgo; frontier auto. |
+| `livingston` | `integration` | `moderate` | Integración TS/opencode; tool calling por defecto. |
+| `yen` | `local-runtime` | `moderate` | Runtimes locales; local-first con fallback frontier. |
+| `basher` | `routing-cost` | `moderate` | Router, coste y presupuesto; local-first. |
+| `scribe` | `scribe` | `trivial` | Documentación y resúmenes; local-first. |
+| `linus` | `tester` | `simple` | Tests y contratos; local-first con tools. |
+
+`runRoleTask` ejecuta una subsesión; `runRoleTasks` ejecuta varias con `batchID`. Los roles con `destructive` o `multiFileEdit` elevan el tier antes de elegir modelo.
+
+Para ver ahorro y decisiones, revisa el JSONL de telemetría. Campos clave: `promptHash`, `promptChars`, `tier`, `routeKind`, `selected`, `rationale`, `estimatedCostUSD`, `baselineCostUSD`, `estimatedSavingsUSD`, `budgetAction`, `tokensIn` y `tokensOut`.
+
+## Comandos runtime
+
+openteam expone comandos para inspeccionar y cambiar el routing sin editar JSON a mano. Hay tres superficies equivalentes:
+
+### 1. Tool en la conversación
+
+El plugin registra la herramienta `openteam`. Pídele al agente que la use, o instala el comando `/openteam` (ver más abajo). Acciones:
+
+- `show` — muestra el baseline efectivo.
+- `set` (con `model` en formato `provider/model`) — fija el baseline (modo `pinned`).
+- `auto` — vuelve a cheapest-capable (modo `auto`).
+- `doctor` — diagnóstico de runtimes locales, privacidad y telemetría.
+- `report` — resumen de coste y ahorro desde la telemetría.
+
+Los cambios de `set`/`auto` se persisten en `.opencode/openteam.json` y aplican en el siguiente arranque del plugin.
+
+### 2. Slash command `/openteam`
+
+Copia [`.opencode/command/openteam.md`](.opencode/command/openteam.md) a tu proyecto (o a `~/.config/opencode/command/`). Después:
+
+```text
+/openteam baseline show
+/openteam baseline set anthropic/claude-sonnet-4-5
+/openteam baseline auto
+/openteam doctor
+/openteam report
+```
+
+### 3. CLI (`bin`)
+
+El paquete expone el binario `openteam`. Con instalación global:
+
+```powershell
+npm i -g @jmanuelcorral/openteam
+openteam baseline show
+openteam baseline set openai/gpt-5-mini
+openteam doctor --config .opencode/openteam.json
+openteam report --telemetry .opencode/openteam-telemetry.jsonl
+```
+
+Flags: `--config <path>` y `--telemetry <path>` sobrescriben las rutas por defecto.
+
+## Ejemplos en Windows
+
+### Ollama
+
+```powershell
+ollama serve
+ollama pull qwen3:8b
+Invoke-RestMethod -Uri "http://localhost:11434/v1/models" -Method Get
+```
+
+### LM Studio
+
+1. Abre LM Studio.
+2. Carga un modelo compatible.
+3. Activa el servidor local OpenAI-compatible en el puerto `1234`.
+
+```powershell
+Invoke-RestMethod -Uri "http://localhost:1234/v1/models" -Method Get
+```
+
+### Foundry Local
+
+```powershell
+foundry service status
+```
+
+openteam extrae el puerto de la salida del CLI y normaliza el endpoint a `http://localhost:<PORT>/v1`.
+
+### Telemetría
+
+```powershell
+$telemetryPath = "C:\gitrepos\openteam\.opencode\openteam-telemetry.jsonl"
+Get-Content -Path $telemetryPath -Tail 5
+```
+
+### Verificación local
+
+```powershell
+Set-Location -Path "C:\gitrepos\openteam"
+bun test
+bun run typecheck
+bun run lint
+bun run format:check
+# Cuando el empaquetado de Fase 4 exponga el script:
+bun run build
+```
+
+## Privacidad
+
+Con `privacyMode: "forceLocalOnSensitive"`, si `TaskSignals.privacySensitive` es `true`, `chooseModel` usa local y no permite fallback frontier. Si no hay local utilizable, la decisión conserva la ruta local y registra la razón en `rationale`.
+
+La telemetría usa `hashPrompt`, actualmente `fnv1a32:<hash>`, y no serializa el prompt completo.
+
+## Calidad
+
+Gates no negociables:
+
+- `bun test`
+- Coverage global: líneas `>= 85%`, branches `>= 80%`.
+- Coverage de `src/router/**`: `100%` lines, branches, statements y functions.
+- `bun run typecheck`
+- `biome check .` o `bun run lint` + `bun run format:check`
+- Test de determinismo del router.
+- Tests de contrato si cambian hooks opencode, agents, comandos, providers o SDK.
+
+Estado actual de Fases 0-3: **202 tests verdes**.
+
+## Compatibilidad
+
+Consulta [docs/compatibility.md](docs/compatibility.md). Resumen verificado el `2026-07-06`:
+
+| Superficie | Versión / contrato |
+| --- | --- |
+| openteam | `0.1.0` para Fase 4 npm + docs |
+| `@opencode-ai/plugin` | `1.17.13` |
+| `@opencode-ai/sdk` | `1.17.13` |
+| Hook de routing | `chat.message`; no `chat.params` para cambiar modelo |
+| Subsesiones | `client.session.create` + `client.session.prompt({ body: { model } })` |
+
+## Roadmap
+
+| Fase | Estado | Entregables |
+| --- | --- | --- |
+| 0. Scaffold/PoC | Hecha | TS/Bun, plugin mínimo, hook `chat.message`. |
+| 1. Local registry + router heurístico | Hecha | Ollama/LM Studio/Foundry, probes y `chooseModel` determinista. |
+| 2. Clasificador + perfiles + presupuesto + telemetría | Hecha | Clasificador local, `ModelCapabilityProfile`, budgets y `CostRecord`. |
+| 3. Orquestación multiagente | Hecha | Coordinator, roles, child sessions y permisos. |
+| 4. Empaquetado npm + docs | Hecha | Package exportable, README, ejemplos Windows y matriz de compatibilidad. |
+| 5. Comandos runtime | Hecha | `baseline show/set/auto`, `doctor` y `report` vía tool, `/openteam` y CLI `bin`. |
+
+## Licencia
+
+MIT. Consulta [LICENSE](LICENSE).