oficina-opencode 0.0.0-stage → 2.0.1

package/README.md

@@ -1,3 +1,671 @@
-# Temporary Holding Version
+<div align="center">
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# AI-OFFICE
+
+### Una oficina de agentes para OpenCode donde el trabajo no se detiene cuando el modelo dice «terminé».
+
+[![npm](https://img.shields.io/npm/v/oficina-opencode?label=npm&color=cb3837)](https://www.npmjs.com/package/oficina-opencode)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/SOCRAMbt/AI-OFFICE/tree/main/LICENSE)
+[![node](https://img.shields.io/badge/node-%3E%3D20-339933.svg)](https://nodejs.org)
+[![tests](https://img.shields.io/badge/tests-213%20passing-22a06b.svg)](https://github.com/SOCRAMbt/AI-OFFICE/tree/main/tests)
+[![coverage](https://img.shields.io/badge/coverage-87.3%25-7c3aed.svg)](https://vitest.dev)
+[![types](https://img.shields.io/badge/typescript-strict-3178c6.svg)](https://github.com/SOCRAMbt/AI-OFFICE/blob/main/tsconfig.json)
+
+**4 hooks · 13 tools · 7 agentes · 6 gates · 6 invariantes duros · 306 roles de catálogo**
+
+> **¿Preferís la versión en humano?** → [`docs/QUE-ES.md`](https://github.com/SOCRAMbt/AI-OFFICE/blob/main/docs/QUE-ES.md) — qué es, qué hace y por qué, sin jerga.
+> **¿Preferís el porqué técnico?** → [`docs/ARCHITECTURE.md`](https://github.com/SOCRAMbt/AI-OFFICE/blob/main/docs/ARCHITECTURE.md)
+
+[Documentación](#arquitectura) · [Instalación](#instalación) · [Uso](#uso) · [CLI](#cli-operación)
+
+</div>
+
+---
+
+## El problema
+
+Working con agents tiene cinco fallas concretas. No son falta de inteligencia: son falta de **estructura**.
+
+| Falla | Qué pasa en la práctica |
+|---|---|
+| **El modelo decide cuándo terminar** | Dice «listo, terminado» con la mitad del trabajo sin hacer, y la sesión para ahí. |
+| **El trabajo se hace lineal** | Todo en un solo contexto: un agente, una tarea, un hilo. Los subagentes existen pero se desaprovechan. |
+| **Nadie orquesta** | No hay un plan, no hay prioridad, no hay un dueño por tarea. |
+| **El contexto se pierde** | Hay que repetir lo que ya se dijo, lo ya se decidió y lo ya se encontró. |
+| **Los subagentes son islands** | No se piden ayuda, no se coordinan, no se benefician del trabajo del otro. |
+
+Una skill de markdown no arregla ninguna de las cinco. Un sistema con reglas escritas en código, no: porque **no dependen de que el modelo tenga ganas de seguirlas**.
+
+---
+
+## Qué es
+
+**AI-OFFICE** es un plugin de OpenCode que convierte la orquestación en **código ejecutable**, no en instrucciones.
+
+```
+Skill     →  "Hacé lo que corresponda"          →  depende de que el modelo quiera
+Plugin    →  máquina de estados + hooks         →  no depende de la buena voluntad
+```
+
+Cuatro piezas lo hacen posible:
+
+**1. Un hook que no deja que la sesión muera.** Cuando la sesión queda `idle` y quedan cards sin terminar, el motor manda un prompt sintético y la corrida sigue. El modelo **no puede declarar que terminó**: el estado lo dice.
+
+**2. Un guard que no deja editar fuera de scope.** `tool.execute.before` intercepta cada `edit`/`write` y lo rechaza si el archivo está fuera del scope de la card. "No toques eso" deja de ser una sugerencia.
+
+**3. Gates que se ejecutan, no se opinan.** Build, type check, lint, tests, escaneo de secretos y diff review. El motor corre los comandos, lee los exit codes y decide. La salida real queda pegada en el artefacto.
+
+**4. Invariantes que el código garantiza.** `gate_required_before_done` y `reviewer_neq_owner` no son recomendaciones: `assertInvariants` lanza y la transición no ocurre.
+
+Y una quinta, que es lo que hace confiable todo lo demás:
+
+**5. El roster se arma según el objetivo.** Los roles salen del catálogo real de agency-agents (**306 agentes, 25 divisiones**), matcheados contra lo que la card pide. Y cada agente recibe un **briefing** de 10 secciones con lo que sabe, lo que no, y qué tiene que entregar.
+
+---
+
+## Arquitectura
+
+Cuatro capas. De abajo hacia arriba.
+
+```
+┌──────────────────────────────────────────────────────────────────────┐
+│ CAPA 3 — COORDINACIÓN                                                │
+│  ┌──────────────┐  ┌──────────────┐  ┌───────────────────────────┐  │
+│  │ COMANDANTE   │  │ ARQUITECTO   │  │ INTEGRADOR                │  │
+│  │ scope        │  │ cross-cutting│  │ DAG · leases · gates      │  │
+│  │ objetivo     │  │ patrones     │  │ presupuesto · anti-deadlock│ │
+│  │ prioridad    │  │ contratos    │  │                            │  │
+│  └───────┬──────┘  └──────┬───────┘  └────────────┬──────────────┘  │
+│          │                │                       │                 │
+│  ════════╪════════════════╪═══════════════════════╪═════════════    │
+│          ▼                ▼                       ▼                 │
+│ CAPA 2 — BUS DE MENSAJES  (append-only sobre disco)                 │
+│  bus/<canal>/<seq>-<msgid>.json                                      │
+│  inbox/<agentId>/  ·  roster.json  ·  leases/<taskId>.json           │
+│  canales: coord-command │ coord-arch │ coord-flow │ peer            │
+│          │                                                              │
+│          ▼                                                              │
+│ CAPA 1 — ESPECIALISTAS  (ficha normalizada)                         │
+│  E1  E2  E3  E4  E5  E6  E7  E8  E9  E10                            │
+│  briefing: ficha.md · misiones.md · protocolo.md · bus.md            │
+│          │                                                              │
+│          ▼                                                              │
+│ CAPA 0 — ROSTER / FICHAS  (resolución de roles)                      │
+│  agency-agents/<division>/*.md  →  ficha  │  catálogo < 60% → factory│
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Capa 0 — De dónde sale la especialidad
+
+El repo de agency-agents tiene **306 agentes en 25 divisiones**, y cada uno trae un briefing de 10 secciones. La especialidad real **no está en el `description`** del frontmatter: está en el cuerpo.
+
+Un agente de statistics declara:
+- `description`: *"Expert in quantitative research methodology..."*
+- **Core Mission** → *Pressure-Test Quantitative Claims*, *Design Sound Studies*
+- **Technical Deliverables** → *Claim Interrogation Framework*, *Effect Size Report*
+- **Advanced Capabilities** → *Causal Inference*, *Experimental Design*
+
+La `description` dice de qué se ocupa. El cuerpo dice **en qué es exactamente bueno**. Un matcher que solo mira la `description` no puede distinguir a un metodólogo de un analista de datos — aunque uno de los dos sea exactamente lo que la card necesita.
+
+Por eso el parser extrae las secciones del cuerpo, y el score pondera cada señal por lo que aporta:
+
+| Señal | Peso | Por qué |
+|---|---|---|
+| **Identidad** (slug + nombre + `description` + `vibe`) | 35% | Las dos últimas son **líneas curadas** que dicen de qué se ocupa el agente. El cuerpo son 300 líneas donde cualquier palabra genérica aparece |
+| **Misión, overlap literal** | 28% | Lo que el agente dice que sabe hacer, con sus palabras |
+| **Misión, overlap conceptual** | 18% | Puentea sinónimos con una taxonomía de 26 dominios |
+| **División** | 10% | Una card de e2e testing va a la división `testing`, no a `engineering` |
+| **Cuerpo completo** | 5% | Ruido: "review" aparece en todos |
+
+**Sinónimos por capability**, no por concepto. La taxonomía agrupa; los sinónimos no. `"e2e"` es `"end-to-end"`, pero `"e2e"` **no** es `"playwright"`. Esa distinción separa a un especialista de un generalista que menciona la tool de pasada.
+
+**Lematización**: `"testing"` ~ `"test"`, `"validation"` ~ `"validate"`. El Commander pide capabilities en sus palabras y los agentes usan las suyas.
+
+**Focus de misión**: qué fracción de las misiones declaradas del agente tiene que ver con el objetivo. Un `Test Automation Engineer` tiene las 5 en el dominio → focus 1. Un PDF engine con *una* misión sobre "Playwright Browser Context Pools" y las otras 7 sobre PDF → focus 0.12. **Este es el discriminante real.**
+
+El score final combina: cobertura (35%) + recall (30%) + focus (25%) + F1 (10%).
+
+Resolución real contra el catálogo:
+
+| Objetivo | Primario | Cobertura |
+|---|---|---|
+| Pipeline de datos con ingesta y agregación | `engineering-data-engineer` | 76% |
+| Migración de Postgres con partitioning | `engineering-gaussdb-expert` | 60% |
+| Formulario de login en React con accesibilidad | `engineering-uswds-developer` | 56% |
+| CI/CD con Docker y Kubernetes | `engineering-devops-automator` | 53% |
+| Agente de GIS y cartografía | `gis-web-gis-developer` | 52% |
+| Tests e2e con Playwright | `testing-test-automation-engineer` | 47% |
+| Seguridad de un endpoint API | `testing-api-tester` | 42% |
+
+Reproducible: `npx tsx scripts/demo-roles.ts`
+
+### El panel: primario + complementos
+
+Un objetivo casi nunca es de un solo dominio. *"Formulario de login en React con validación y accesibilidad"* necesita un frontend (que no sabe de ARIA) **y** un especialista en accesibilidad (que no sabe de React).
+
+Si el sistema elige uno solo, deja huecos. Si elige varios sin criterio, duplica capacidad. El panel resuelve las dos cosas:
+
+```
+OBJETIVO: Implementar un formulario de login en React con validación y accesibilidad
+PIDE:     react, form, validation, accessibility, frontend
+
+  PRIMARIO    56%  engineering/engineering-uswds-developer
+              "USWDS Developer"
+              cubre:   react, css, form, accessibility
+
+  + COMPLEM. 39%  engineering/engineering-section-508-specialist
+              "Section 508 Accessibility Specialist"
+              aporta:  form, accessibility
+```
+
+El primario se lleva la card. Los complementos son los agentes que cubren **lo que el primario no cubre**, y son sus pares naturales en el bus. Y lo que nadie cubre **se reporta explícitamente**: es la señal de que la card debería partirse en dos.
+
+### La ficha: un solo schema
+
+Venga el rol de `agency-agents` o de la factory, se materializa en la **misma** ficha. Esa unificación es lo que permite que el bus, el matching de ayuda, la rotación y los coordinadores no necesiten saber el origen de nada.
+
+```yaml
+id: e-frontend
+role: frontend-developer
+source:
+  kind: agency-agents
+  division: engineering
+  path: engineering/frontend-developer.md
+  vibe: "Pixel obsessive, allergic to dead CSS."
+  missions: ["Create Modern Web Applications", "Optimize Performance and UX"]
+  deliverables: ["Component Library", "Design Token System"]
+  rules: ["Never ship a component without a test", "..."]
+capabilities: [react, component, ui, web, accessibility, performance, ...]
+scope:
+  mayTouch: ["src/components/**", "src/hooks/**"]
+  forbidden: ["src/server/**", "**/*.env*"]
+can_delegate: true
+delegate_budget: 2
+peers: [e-architect, e-qa, e-security]
+must_not:
+  - "no editar archivos fuera de may_touch"
+  - "no aprobar tu propio trabajo"
+on_finish: idle-join
+escalate_to: coordinator-flow
+```
+
+### La factory: el mismo briefing, sin catálogo
+
+Un rol fabricado tiene que ser **indistinguible en calidad** de uno del catálogo. Si el catálogo tiene agentes con briefing de 10 secciones, uno fabricado con un prompt de 5 líneas se nota: es monótono, no tiene criterio propio, y el resto de la malla lo trata como de segunda.
+
+Por eso la factory emite **exactamente la misma estructura**: Identity & Memory, Core Mission, Critical Rules, Technical Deliverables, Workflow Process, Communication Style, Learning & Memory, Success Metrics, Advanced Capabilities. El parser no distingue el origen.
+
+Y lo importante: el prompt fabricado **no es genérico**. Lleva las capabilities concretas, el scope, el objetivo de la corrida, los modos de fallo del rol y el contexto de la card.
+
+---
+
+## El equipo se arma
+
+El flujo completo es: **doy un objetivo → el jefe lo divide → crea los subagentes → arrancan a trabajar juntos**.
+
+`oficina_dispatch` es el momento en que eso pasa:
+
+1. **El Comandante descompone** el objetivo en cards (`oficina_plan`). Cada card dice qué se produce, cómo se sabe que está bien, y qué archivos puede tocar.
+2. **El dispatch resuelve los roles.** Para cada card busca en el catálogo de agency-agents el agente que mejor encaja, calcula el **panel** (primario + complementos), y si la cobertura queda baja **fabrica** el rol con la card como contexto.
+3. **Materializa los agentes** en `.opencode/agents/` del proyecto, cada uno con su briefing de 10 secciones y su prompt de especialidad. Quedan versionados con el repo: la próxima sesión ya están registrados.
+4. **Los arranca en paralelo** vía `session.prompt` con una parte `subtask` — la vía que OpenCode provee para crear subagentes reales.
+
+El resultado:
+
+```
+▸ formulario de login en React con validación y accesibilidad
+  → `oficina-engineering-uswds-developer`       card T-00
+  + `oficina-testing-api-tester`                  par libre   aporta: validation
+  → `oficina-engineering-section-508-specialist` card T-01
+  + `oficina-testing-accessibility-auditor`       par libre   aporta: aria
+  → `oficina-testing-test-automation-engineer`    card T-02
+```
+
+Los **pares libres** son los complementos: están en la mesa, pueden recibir un pedido de ayuda, y pueden reclamar una card que quedó sin dueño.
+
+---
+
+## La mesa
+
+Los subagentes son procesos aislados: no se ven, no saben quién más trabaja, no saben a quién preguntarle. La **mesa** es la vista compartida — vive en disco, así que todos la leen sin memoria compartida.
+
+`oficina_mesa` responde:
+
+- **Quién está trabajando en qué** — y qué archivos toca cada uno
+- **Quién está libre** y puede recibir un pedido de ayuda
+- **Qué cards no tienen owner** — reclamables proactivamente
+- **Qué ayuda sigue sin responder** y **qué preguntas están abiertas**
+
+Y cuando la sesión queda `idle`, el hook de auto-continuación inyecta esa foto en el prompt del agente que arranca. Sin esto, el peer mesh es un bus al que nadie mira.
+
+### El ciclo de un agente
+
+```
+DEPLOYED → WORKING → (terminó) → IDLE_AVAILABLE → (ayuda) → WORKING
+                            ↓                                        ↑
+                        BLOCKED ──→ IDLE_AVAILABLE ──────────────────┘
+```
+
+Cuando un agente termina, **ofrece ayuda** para lo que sigue. No queda esperando.
+
+### Hablar por el bus
+
+El que recibe un pedido de ayuda **hace su propio triage** — no acepta por cortesía:
+
+1. ¿Entiendo la tarea? → si no, `HELP_DECLINE` + explicar
+2. ¿Está en mi scope? → si no, `HELP_DECLINE` + sugerir a quién
+3. ¿Puedo hacerlo ya sin romper mi card? → si no, `HELP_DECLINE` + "cuando termine"
+4. ¿Tengo el contexto? → si no, `HELP_QUESTION` por el bus
+5. ¿Vale la pena? → si no, `HELP_DECLINE` + alternativa
+6. ¿Tengo presupuesto? → si no, `HELP_DECLINE` + "sin presupuesto"
+
+**Anti-deadlock**: máximo 2 saltos en una cadena de ayuda; después escala al Integrador.
+**Anti-monotonía**: si el par A↔B ya se ayudaron 2 veces, el tercer pedido va a un tercero.
+
+---
+
+## Capa 1 — El briefing: qué sabe cada agente antes de arrancar
+
+Un subagente arranca con el contexto vacío. Si el Commander le pasa un prompt suelta (*"implementá el login"*), el agente tiene que adivinar: qué sabe del proyecto, qué espera de él, qué puede tocar, a quién preguntarle si se traba, y qué tiene que entregar. Adivinar es la fuente de todo el trabajo que se repite y de los agentes que se salen del scope.
+
+El briefing es el contrato de información. Tiene **orden fijo** y **mínimo verificable**.
+
+### El orden
+
+La información llega de lo más estable a lo más cambiante. Un agente lee de arriba hacia abajo y siempre tiene lo que necesita para el paso siguiente.
+
+| # | Sección | Qué le dice |
+|---|---|---|
+| 1 | **Quién sos** | Rol, especialidad de origen, de dónde viene tu briefing, tu vibe |
+| 2 | **Tu misión** | La card exacta, los criterios de aceptación numerados, el control de calidad |
+| 3 | **Lo que ya sabés** | Decisiones tomadas, restricciones descubiertas, piezas construidas, trampas |
+| 4 | **Lo que NO sabés** | Los huecos explícitos y **a quién preguntarle** por cada uno |
+| 5 | **Tu territorio** | Qué podés tocar, qué no, y qué prohibiciones trae tu ficha |
+| 6 | **Cómo trabajás** | El ciclo, cuándo pedir ayuda, cuándo delegar, cuándo escalar |
+| 7 | **Tu canal** | Dónde dejás y encontrás mensajes, formato, TTLs, cómo acusar recibo |
+| 8 | **Qué se espera de vos** | Los entregables exactos: `handoff.md` y `evidence.md` |
+| 9 | **Lo que no podés hacer** | Las prohibiciones duras. Están en código, no en tu criterio |
+| 10 | **Cómo se mide que terminaste** | Las tres condiciones de terminado |
+
+### El mínimo
+
+Las diez secciones son **requeridas**. Si alguna queda vacía, el briefing se marca `INCOMPLETO` y **el agente no arranca**. Un briefing a medio llenar produce un agente a medio informado, que es peor que no tener agente.
+
+### Los cuatro artefactos
+
+El briefing se materializa en cuatro archivos en disco, porque un agente no "recuerda" un prompt largo: lo lee.
+
+```
+.oficina/fichas/<agentId>/
+├── ficha.md       ← Quién sos
+├── misiones.md    ← Tu misión · lo que ya sabés · lo que NO sabés
+├── protocolo.md   ← Cómo trabajás · tu territorio · qué se espera · límites · éxito
+├── bus.md         ← Tu canal
+└── briefing.md    ← el documento completo, para lectura humana
+```
+
+**El agente no arranca sin `misiones.md`. Nunca.**
+
+### El ledger: lo que ya sabés
+
+La sección 3 se alimenta del **contexto acumulado** de la corrida (`.oficina/context.md`), que registra decisiones, restricciones, piezas construidas y trampas. Es lo que evita que un agente repita lo que ya se decidió — y lo que convierte al bus en algo más que un tablón de avisos.
+
+---
+
+## Capa 2 — El bus
+
+Los subagentes de OpenCode son **procesos aislados sin memoria compartida**. No pueden hablarse de facto. La solución coherente es un bus append-only sobre disco.
+
+```json
+{
+  "id": "m-0042",
+  "seq": 42,
+  "from": "e-frontend",
+  "to": ["e-architect"],
+  "kind": "HELP_REQUEST",
+  "subject": "T-03",
+  "body": {
+    "need": "convertir este componente a streaming SSR",
+    "why_me": "tengo el contexto del componente pero no el del server"
+  },
+  "reply_to": null,
+  "in_reply_to": null,
+  "ttl_sec": 900,
+  "created_at": "2026-10-21T15:04:00Z",
+  "priority": "normal",
+  "idempotency_key": "help:T-03:e-frontend:a1b2c3",
+  "hops": 0
+}
+```
+
+| Garantía | Implementación | Por qué importa |
+|---|---|---|
+| **Append-only** | Los mensajes nunca se borran; `seq` es monótono por canal | El log es la auditoría |
+| **Escritura atómica** | `.tmp` + `rename` | Nunca hay un JSON partido en el read |
+| **Ack** | `inbox/<agentId>/<msgid>.ack` | El emisor sabe quién leyó |
+| **TTL** | Vencido = invisible para lectores nuevos, sigue en el log | Un pedido viejo no bloquea nada |
+| **Idempotency key** | Mismo key = mismo mensaje | Evita el storm de «¿me ayudás?» |
+| **Broadcast** | `to: ["*"]` al pool | El primero que acepta toma el lease |
+| **Anti-deadlock** | `hops` máximo 2 | Una cadena de ayuda no se enquista |
+
+### El que recibe hace su propio triage
+
+No acepta por cortesía. Seis preguntas, en orden:
+
+1. ¿Entiendo la tarea? → si no, `HELP_DECLINE` + explicar
+2. ¿Está en mi scope? → si no, `HELP_DECLINE` + sugerir a quién
+3. ¿Puedo hacerlo **ya** sin romper mi card? → si no, `HELP_DECLINE` + «cuando termine»
+4. ¿Tengo el contexto? → si no, `HELP_QUESTION` por el bus
+5. ¿Vale la pena? → si no, `HELP_DECLINE` + alternativa
+6. ¿Tengo presupuesto? → si no, `HELP_DECLINE` + «sin presupuesto»
+
+---
+
+## Los 4 hooks
+
+Acá es donde el protocolo deja de ser una intención.
+
+| Hook | Qué hace | Por qué importa |
+|---|---|---|
+| `event` → `session.idle` | Si queda trabajo, manda un prompt sintético y la corrida sigue | La oficina trabaja sola. El modelo no declara el fin: el estado. |
+| `tool.execute.before` | Bloquea escrituras fuera del scope de la card | «No toques eso» pasa de instrucción a restricción |
+| `experimental.chat.system.transform` | Inyecta el estado de la oficina en cada llamada | El agente no repregunta lo que ya sabe ni repite trabajo |
+| `experimental.session.compacting` | Reinyecta el estado **leído del disco** al compactar | Sin esto, la oficina se olvida a mitad de camino |
+
+El hook de auto-continuación tiene guardas duras: solo reanuda si queda trabajo real, tope de 25 auto-reanudaciones por sesión, cooldown de 1,5 s entre reanudaciones, y nunca reanuda una corrida `paused`, `blocked` o `delivered`.
+
+---
+
+## Los 6 gates
+
+De la skill `verification-loop`. Se ejecutan de verdad; el motor interpreta los exit codes.
+
+| # | Fase | Node | Python | Go | Rust |
+|---|---|---|---|---|---|
+| 1 | Build | `npm run build` | `python -m build` | `go build ./...` | `cargo build` |
+| 2 | Type check | `npm run typecheck` | `mypy` | `go vet ./...` | `cargo check` |
+| 3 | Lint | `npm run lint` | `ruff` | `golangci-lint` | `cargo clippy` |
+| 4 | Tests | `npm run test` | `pytest` | `go test` | `cargo test` |
+| 5 | Secretos | escaneo en código | ← | ← | ← |
+| 6 | Diff review | `git diff --stat` | ← | ← | ← |
+
+**Reglas de honestidad** — no negociables:
+
+- Nunca `PASS` en una fase que no se corrió → `NOT RUN` y eso hace fallar el gate
+- Nunca output inventado
+- `N/A` siempre con motivo explícito
+- Una fase aplicable en `FAIL` = gate `FAIL`. No se promedia
+- El escaneo de secretos corre **en TypeScript**, no shelling out a `grep` (que no existe en Windows), y **redacta** el valor: un log de gate que imprime la credencial completa la acaba de filtrar
+
+---
+
+## Invariantes duros
+
+Los implementa el código. Un prompt puede pedirle al modelo que sea cuidadoso; el motor no puede romperlos.
+
+| Invariante | Valor |
+|---|---|
+| `gate_required_before_done` | `true` — sin gates en `PASS` no hay `DONE` |
+| `reviewer_neq_owner` | `true` — no hay auto-aprobación |
+| `max_concurrent_agents` | 10 base · 14 hard cap |
+| `max_spawn_depth` | 2 niveles bajo el coordinador |
+| `max_spawns_total` | 20 por corrida |
+| `max_help_chain_hops` | 2 — anti-deadlock |
+| `max_messages_per_agent` | 150 — anti-spam |
+| `msg_ttl_sec` | 900 |
+| `lease_ttl_sec` | 1800 — con heartbeat; si el agente muere, expira |
+| `heartbeat_sec` | 60 |
+| `max_review_rejections` | 3 → escalación |
+| `max_cards` · `max_agent_calls` | 20 · 40 por corrida |
+
+---
+
+## Los 3 coordinadores
+
+Un solo coordinador es cuello de botella y punto único de falla.
+
+| | COMANDANTE | ARQUITECTO | INTEGRADOR |
+|---|---|---|---|
+| **Dominio** | Scope, objetivo, prioridades | Decisiones técnicas cross-cutting | DAG, leases, gates, calidad |
+| **Responde** | ¿esto está en el objetivo? | ¿qué patrón usamos? | ¿quién tiene T-07? ¿pasó el gate? |
+| **Detecta** | Scope creep, requisitos no cubiertos | Drift arquitectónico, decisiones inconsistentes | Deadlock, starvation, gates rojos, doble-claim |
+| **Nunca** | Diseñar ni revisar código | Escribir código | Escribir código |
+
+**Arbitraje**: scope → Comandante. Patrón/contrato → Arquitecto. Flujo/lease/gate → Integrador. Si cruza dos dominios, el Arquitecto decide lo técnico con visto bueno del Comandante; si el Integrador detecta deadlock, reparte y avisa.
+
+Las preguntas de un especialista al coordinador **van por el bus**, no interrumpen al humano. Al usuario solo llega lo que ningún coordinador puede resolver.
+
+---
+
+## Los 13 tools
+
+Trece, no treinta. Cada tool que se suma es ruido en el contexto de todos los agentes.
+
+| Tool | Qué hace |
+|---|---|
+| `oficina_plan` | Guarda el plan de cards. El modelo propone; el motor valida y rutea owner/reviewer |
+| `oficina_dispatch` | **Arma el equipo**: resuelve los roles, materializa los agentes con su briefing y los arranca en paralelo |
+| `oficina_mesa` | **La mesa**: quién trabaja en qué, quién está libre, qué ayuda espera respuesta, qué cards no tienen owner |
+| `oficina_board` | Estado: cards, owners, agentes libres, agentes sin heartbeat, presupuesto |
+| `oficina_assign` | Toma trabajo — la próxima card, o claim proactivo de una puntual |
+| `oficina_submit` | Entrega handoff + evidencia real → pasa a `REVIEW` |
+| `oficina_review` | Registra el veredicto. El motor **rechaza** que el owner se auto-revise |
+| `oficina_gate` | Corre los 6 gates. Exit codes reales, no opinión |
+| `oficina_bus` | Bus: `send` · `receive` · `ack` · `help` |
+| `oficina_spawn` | Pide desplegar un agente. El Integrador aprueba o rechaza |
+| `oficina_escalate` | Escala al usuario con 2-3 opciones concretas y recomendación |
+| `oficina_ficha` | Resuelve un rol a ficha y **despliega** el agente con su briefing |
+| `oficina_brief` | Muestra el briefing y el **panel de roles** sin desplegar: decisión del Comandante |
+
+---
+
+## Los 7 agentes
+
+| Agente | Rol | Aprueba? |
+|---|---|---|
+| `oficina-commander` | Scope, objetivo, prioridades | No revisa técnico |
+| `oficina-architect` | Decisiones técnicas cross-cutting | No revisa técnico |
+| `oficina-integrator` | DAG, leases, gates, presupuesto | No revisa técnico |
+| `oficina-critico` | Revisión con confianza calibrada (umbral 80) | Sí |
+| `oficina-guardian` | Secretos, inyecciones, deps, auth | Sí |
+| `oficina-verificador` | Ejecuta build/typecheck/lint/test | Sí |
+| `oficina-director` | Dirección de la oficina v1 (fallback) | No |
+
+---
+
+## Instalación
+
+### Desde npm
+
+```bash
+npm install -g oficina-opencode
+```
+
+### Local (desarrollo)
+
+```bash
+git clone https://github.com/SOCRAMbt/AI-OFFICE.git
+cd AI-OFFICE
+npm install
+npm run build
+
+cd ~/.config/opencode
+npm install file:/ruta/a/AI-OFFICE
+```
+
+Y el entry point en `~/.config/opencode/plugins/oficina.js`:
+
+```js
+export { OficinaPlugin, default } from "oficina-opencode"
+```
+
+### Configuración
+
+`~/.config/opencode/opencode.json`:
+
+```json
+{
+  "experimental": {
+    "subagent_depth": 3
+  }
+}
+```
+
+`subagent_depth: 3` es **obligatorio**: con el default (`1`) los subagentes no pueden delegar a otros subagentes, y la malla no arranca.
+
+### Los assets del protocolo
+
+```bash
+oficina install --target ~/.config/opencode
+```
+
+Instala la skill, los 7 agentes, el comando y el entry point del plugin.
+
+---
+
+## Uso
+
+Desde la raíz del proyecto:
+
+```text
+/oficina Agregar autenticación JWT con refresh rotation
+```
+
+El comando carga la skill `oficina`, el plugin registra las tools, y la corrida arranca sola.
+
+El ciclo:
+
+```
+OBJETIVO → PLAN (Comandante)
+              ↓
+         STANDUP — la card con deps satisfechas
+              ↓
+         TRABAJO (owner) → handoff.md + evidence.md
+              ↓
+         AUTO-REVIEW (oficina-critico, ≠ owner)
+              ↓
+         GATES (oficina-verificador + oficina-guardian)
+              ↓
+        ┌────────┴────────┐
+      DONE            REWORK → REPLAN → ESCALADA
+```
+
+---
+
+## CLI — operación
+
+```bash
+oficina init [objetivo]                    # Crea .oficina/ en el proyecto
+oficina status                             # Cards, agentes, presupuesto, escalaciones
+oficina board                              # Tablero Kanban
+oficina bus                                # Estadísticas del bus
+oficina audit T-03                         # Artefactos, gates y review de una card
+oficina verify                             # Corre los gates de las cards en review
+oficina install --target <dir>             # Instala skill, agentes y comando
+oficina catalog --agency-root <path>       # Lista el catálogo de roles disponible
+oficina reset --force                      # Abandona la corrida
+```
+
+---
+
+## Estructura de la corrida
+
+```
+<proyecto>/.oficina/
+├── board.md          # Kanban legible por humanos
+├── state.json        # estado legible por máquinas — retoma tras reinicio
+├── context.md        # ledger de conocimiento acumulado
+├── roster.json       # quién existe, qué puede, qué está haciendo
+├── config.json
+├── bus/
+│   ├── coord-command/0001-m-xxxxxxxx.json
+│   ├── coord-arch/
+│   ├── coord-flow/
+│   └── peer/
+├── inbox/<agentId>/  # acks
+├── leases/<taskId>.json
+├── fichas/<agentId>/ # los 4 artefactos del briefing + briefing.md
+└── artifacts/<cardId>/
+    ├── handoff.md    # qué hizo el owner
+    ├── evidence.md   # salida real de los comandos
+    ├── review.md     # veredicto del crítico
+    ├── gates.md      # PASS/FAIL técnico y seguridad
+    └── decision.md   # decisión del director
+```
+
+El formato de artefactos es compatible con OFICINA v1 (la skill). El plugin **migra el estado v1 automáticamente**: objetivo, cards y resultados se conservan.
+
+---
+
+## Código
+
+24 archivos TypeScript · 14 módulos en `core/` · 1 toolset · 4 hooks.
+
+```
+src/
+├── index.ts              # entry del plugin: tools + hooks
+├── cli.ts                # CLI de operación
+├── core/
+│   ├── types.ts          # el schema único del sistema
+│   ├── state.ts          # máquina de estados + invariantes + migración v1
+│   ├── bus.ts            # bus append-only con TTL/ack/idempotencia
+│   ├── roster.ts         # quién existe + pool idle
+│   ├── leases.ts         # leases con TTL y heartbeat
+│   ├── catalog.ts        # escaneo de agency-agents + matching + panel
+│   ├── factory.ts        # generación de roles con briefing de 10 secciones
+│   ├── briefing.ts       # el contrato de información del agente
+│   ├── router.ts         # enrutado + rotación anti-monotonía
+│   ├── gates.ts          # runner de los 6 gates + escaneo de secretos
+│   ├── retry.ts          # política de 3 golpes
+│   ├── office.ts         # la fachada que amarra todo
+│   ├── paths.ts          # resolución de project root
+│   ├── fsx.ts            # IO atómico
+│   └── log.ts            # logging estructurado
+├── tools/index.ts        # las 11 tools
+└── hooks/
+    ├── sessionIdle.ts    # auto-continuación
+    ├── scopeGuard.ts     # enforcement de scope
+    ├── systemTransform.ts
+    └── compacting.ts
+```
+
+### Dependencias
+
+Una sola, y es peer del host: `@opencode-ai/plugin`. Zod entra por `tool.schema` — la instancia del propio plugin — para que los tipos nunca divergan de la versión que el host está corriendo.
+
+---
+
+## Testing
+
+```bash
+npm test           # 213 tests, 14 archivos
+npm run coverage   # 90.2% stmts · 82.8% branches
+npm run typecheck  # tsc --noEmit, strict
+npm run build      # tsc → dist/
+```
+
+| Suite | Cubre |
+|---|---|
+| `bus.test.ts` | Append-only, ack, TTL, idempotencia, broadcast, prioridad, atomicidad |
+| `state.test.ts` | Transiciones, invariantes duros, selección de card, ciclo de corrida |
+| `gates.test.ts` | Detección de tooling, las 6 fases, N/A con motivo, consolidación, redacción |
+| `router.test.ts` | Enrutado, rotación, reviewer ≠ owner, política de 3 golpes, presupuesto |
+| `leases.test.ts` | Adquisición, heartbeat, expiración, double-claim, reasignación |
+| `catalog.test.ts` | Frontmatter, secciones, extracción, matching ponderado, panel, factory |
+| `catalogReal.test.ts` | El catálogo real de 306 agentes: estructuras, matching, división |
+| `briefing.test.ts` | Orden, mínimo, las 10 secciones, los 4 artefactos, INCOMPLETO |
+| `office.test.ts` | Ciclo completo end-to-end, invariantes, artefactos en disco |
+| `scopeGuard.test.ts` | Globs, extracción de path, enforcement de scope |
+| `plugin.test.ts` | El plugin contra un host mockeado: tools, hooks, auto-resume |
+| `migration.test.ts` | Migración v1 → v2 sin pérdida de datos |
+| `cli.test.ts` | init, status, board, install, audit, reset, idempotencia |
+
+---
+
+## Licencia
+
+MIT — ver [LICENSE](https://github.com/SOCRAMbt/AI-OFFICE/tree/main/LICENSE).
+
+El diseño se apoya en los patrones de `durable-execution` y `workflow-engine-design`: estado durable antes de los efectos, leases con TTL, transiciones nombradas explícitamente y at-least-once con reconciliación por idempotency key.