oficina-opencode 0.0.0-stage → 2.0.1

package/examples/opencode.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "experimental": {
+    "subagent_depth": 3
+  },
+  "plugin": ["oficina-opencode"]
+}

package/package.json

@@ -1,6 +1,83 @@
 {
   "name": "oficina-opencode",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2.0.1",
+  "description": "Oficina de Agents — malla de coordinadores + peer mesh para OpenCode. Orquestación durable de subagentes con bus de mensajes en disco, roster de roles, leases, gates de calidad y escalamiento por invariantes.",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./cli": {
+      "types": "./dist/cli.d.ts",
+      "import": "./dist/cli.js"
+    }
+  },
+  "bin": {
+    "oficina": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "agents",
+    "commands",
+    "docs",
+    "examples",
+    "DESIGN.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "opencode-agent",
+    "agents",
+    "orchestration",
+    "multi-agent",
+    "agent-mesh",
+    "peer-to-peer",
+    "durable-execution",
+    "workflow",
+    "state-machine",
+    "cli",
+    "ai"
+  ],
+  "author": "Marcos <casselsmarcos1@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SOCRAMbt/AI-OFFICE.git"
+  },
+  "homepage": "https://github.com/SOCRAMbt/AI-OFFICE#readme",
+  "bugs": {
+    "url": "https://github.com/SOCRAMbt/AI-OFFICE/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsc -p tsconfig.build.json --watch",
+    "typecheck": "tsc --noEmit",
+    "pretest": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "coverage": "npm run build && vitest run --coverage",
+    "prepublishOnly": "npm run typecheck && npm run test && npm run build"
+  },
+  "dependencies": {
+    "@opencode-ai/plugin": "^1.15.11",
+    "zod": "4.1.8"
+  },
+  "devDependencies": {
+    "@types/node": "^24.12.2",
+    "typescript": "^5.8.2",
+    "vitest": "^3.2.4",
+    "@vitest/coverage-v8": "^3.2.4"
+  }
+}

package/skills/oficina/README.md

@@ -0,0 +1,120 @@
+# 🏢 OFICINA — Oficina de Agents
+
+Un objetivo entra por la puerta. La oficina lo ejecuta, se auto-verifica, y entrega evidencia.
+
+## Qué es
+
+Un sistema de orquestación de agentes **nativo de OpenCode**. Combina:
+
+- **agency-agents** → los especialistas (`code-explorer`, `code-architect`) y el patrón de subagentes
+- **AgentTeams** → la disciplina de coordinación: cards con owner, scope, acceptance, gate, Kanban, merge gates
+- **Skills nuevas** → `multi-reviewer-patterns` (dimensiones + dedup + severidad), `verification-loop` (6 fases), `deep-agents-orchestration` (subagentes stateless), `secure-code-review` (trust boundaries)
+
+## El problema que resuelve
+
+| Falla común | Mecanismo de OFICINA |
+|---|---|
+| Tenés que dar todas las instrucciones | El **Director** descompone solo |
+| El agent "no cumple" | Cada card tiene **acceptance criteria** + **gate ejecutable** |
+| Los subagentes se desaprovechan | Tabla de **enrutado determinista** rol→agente |
+| Hay que repetir el contexto | **Ledger de contexto** en disco (`.oficina/context.md`) |
+| No se coordinan entre sí | **Handoff por artefactos** — el disco es el bus de mensajes |
+| Son monotonos | **Revisor distinto del autor** + rotación de owner y de dimensión |
+| Nadie los orquesta | El **Director** corre el loop, detecta estancamiento, escala |
+
+## Uso
+
+```bash
+# Desde la raíz de tu proyecto
+/oficina Agregar autenticación JWT con refresh tokens
+```
+
+El comando carga la skill `oficina` y arranca el ciclo. No pide permiso: informa y sigue.
+
+### Comandos de control (durante la corrida)
+
+| Quiero | Digo |
+|---|---|
+| Ver el estado | `/oficina status` |
+| Cambiar de rumbo | `/oficina cambiar a <nuevo objetivo>` |
+| Pausar | `/oficina pausar` |
+| Detener | `/oficina stop` |
+
+## Los 7 roles
+
+| Rol | Agente | Puede aprobar? |
+|---|---|---|
+| Director | `oficina-director` | No revisa técnico |
+| Explorador | `code-explorer` | No |
+| Arquitecto | `code-architect` | No |
+| Implementador | `general` | No |
+| **Crítico** | `oficina-critico` | Sí (revisión de card) |
+| **Guardián** | `oficina-guardian` | Sí (gate seguridad) |
+| **Verificador** | `oficina-verificador` | Sí (gate técnico) |
+
+**Nadie se auto-aprueba.** El Crítico de una card es siempre distinto de su owner.
+
+## El ciclo
+
+```
+OBJETIVO → PLAN (Director)
+              ↓
+         STANDUP (elegir card)
+              ↓
+         TRABAJO (owner → handoff.md + evidence.md)
+              ↓
+         AUTO-REVIEW (oficina-critico → review.md)
+              ↓
+         GATES (oficina-verificador + oficina-guardian → gates.md)
+              ↓
+     ┌────────┴────────┐
+   DONE            REWORK → REPLAN → ESCALADA
+```
+
+## Garantías
+
+1. **Ninguna card DONE sin `gates.md` en PASS** (técnico Y seguridad).
+2. **Ningún trabajo se auto-aprueba.**
+3. **Nada se pierde**: 35+ artefactos por corrida, todo en `.oficina/`.
+4. **La oficina se audita a sí misma**: el Verificador marca en el diff review cualquier archivo tocado fuera de scope.
+5. **Escala con opciones**, nunca con monólogo. 3 rechazos de la misma card = escalación.
+
+## Estructura de una 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
+└── artifacts/
+    └── T-00/
+        ├── 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
+        └── delegation.md # prompt de delegación (para relanzar)
+```
+
+## Requisitos
+
+- OpenCode con `experimental.subagent_depth: 3` (ya configurado en `~/.config/opencode/opencode.json`) — sin esto los subagentes no pueden delegar.
+- Correr `/oficina` **desde la raíz del proyecto**.
+
+## Costos
+
+Presupuesto por corrida: **20 cards, 40 invocaciones de subagente**. Una corrida típica de un bug acotado consume 5 cards / 22 agentes. Si se agota, la oficina entrega informe parcial honesto y pregunta.
+
+## Archivos
+
+| Ruta | Qué es |
+|---|---|
+| `~/.config/opencode/skills/oficina/SKILL.md` | La skill (protocolo) |
+| `~/.config/opencode/skills/oficina/reference/roles.md` | Fichas de rol + tabla de enrutado |
+| `~/.config/opencode/skills/oficina/reference/protocol.md` | Handoff, gates, escalamiento, checkpoints |
+| `~/.config/opencode/skills/oficina/reference/templates.md` | Templates + prompts de delegación |
+| `~/.config/opencode/agents/oficina-director.md` | El Director |
+| `~/.config/opencode/agents/oficina-critico.md` | El Crítico |
+| `~/.config/opencode/agents/oficina-guardian.md` | El Guardián (gate seguridad) |
+| `~/.config/opencode/agents/oficina-verificador.md` | El Verificador (gate técnico) |
+| `~/.config/opencode/commands/oficina.md` | El comando `/oficina` |

package/skills/oficina/SKILL.md

@@ -0,0 +1,251 @@
+---
+name: oficina
+description: Oficina de Agents que trabaja un objetivo de principio a fin sin instrucciones repetidas. Con el plugin instalado, la oficina es una máquina de estados con hooks de enforcement: el Director descompone, delega a especialistas con ficha normalizada, coordina por un bus de mensajes en disco, permite pedir ayuda y delegar entre pares, y un hook de auto-continuación sigue trabajando cuando el modelo dice "terminé". Sin el plugin, el mismo protocolo funciona con el flujo de artefactos en markdown. Úsala cuando el usuario da un objetivo, feature, bug o refactor y quiere que un equipo de agentes lo ejecute completo, se auto-verifique y entregue evidencia, en vez de que el assistant lo haga todo lineal.
+---
+
+# OFICINA — Oficina de Agents
+
+Un objetivo entra por la puerta. La oficina lo ejecuta, se auto-verifica, y entrega evidencia.
+
+## Dos motores, un solo protocolo
+
+| | **Con plugin** (motor duro) | **Sin plugin** (fallback) |
+|---|---|---|
+| Estado | Máquina de estados en TypeScript | `state.json` markdown + JSON |
+| Gates | Comandos reales, exit codes interpretados por código | El modelo corre los comandos y pega la salida |
+| Enforcement | Guard de scope: no se puede editar fuera del scope | Disciplina del prompt |
+| Loop | Hook `session.idle` → la oficina sigue sola | El modelo decide si sigue |
+| Invariantes | `assertInvariants` en código | Regla dura en el prompt |
+| Comunicación | Bus de mensajes con TTL/ack/idempotencia | Artefactos en disco, unidireccional |
+
+**Preferí el plugin.** Si las tools `oficina_*` están disponibles, usá el motor duro: los invariantes dejan de ser sugerencias.
+
+El protocolo de este documento sirve para los dos. Las secciones marcadas **[plugin]** solo aplican con el plugin instalado.
+
+---
+
+## Por qué existe
+
+| Falla | Cómo la resuelve OFICINA |
+|---|---|
+| El usuario tiene que dar todas las instrucciones | El **Comandante** descompone solo. El usuario da un objetivo y basta. |
+| El agent "no cumple" lo que dice | Cada card tiene **acceptance criteria** explícitos y un **gate** que se ejecuta, no se opina. |
+| Los subagentes se desaprovechan | Tabla de **enrutado determinista** + resolución desde el catálogo real de agency-agents. |
+| Hay que repetir el contexto | **Ledger de contexto** en disco (`.oficina/context.md`) + handoff por artefactos. |
+| Los agents no se coordinan ni se ayudan | **Bus de mensajes**: pueden pedir ayuda, delegar y contestar. |
+| Son monotonos | **Revisor distinto del autor** + rotación de owner y de dimensión. |
+| Nadie los orquesta | **3 coordinadores** con dominios particionados y arbitraje explícito. |
+| La IA dice "terminé" sin terminar | **[plugin]** Hook de auto-continuación: el estado decide, no la confianza. |
+
+---
+
+## Las 4 capas
+
+```
+CAPA 3 — COORDINACIÓN    Comandante · Arquitecto · Integrador
+CAPA 2 — BUS             bus/<canal>/<seq>-<msgid>.json · inbox/ · leases/
+CAPA 1 — ESPECIALISTAS   fichas normalizadas (agency-agents o factory)
+CAPA 0 — ROSTER/FICHAS   resolución de roles + matching de capabilities
+```
+
+Detalle completo en `reference/mesh.md`.
+
+---
+
+## Los 3 coordinadores
+
+Un solo coordinador es cuello de botella y punto único de falla. Tres, con dominios particionados:
+
+| | 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 |
+| **NO hace** | 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.
+
+**Al usuario solo se escala** si el coordinador no puede decidir (criterio de producto), si el conflicto cruza dominios sin resolución, o si se agotó el presupuesto.
+
+---
+
+## El ciclo de la oficina
+
+```
+OBJETIVO
+   |
+   v
+ +---------------------------+
+ | 1. PLAN (Comandante)     |  Descompone -> cards con owner, acceptance, gate, scope
+ +---------------------------+
+   |
+   v
+ +---------------------------+
+ | 2. STANDUP               |  Elige la card mas prioritaria con deps satisfechas
+ +---------------------------+
+   |
+   v
+ +---------------------------+
+ | 3. TRABAJO (Owner)       |  Ejecuta + escribe handoff.md + evidence.md
+ +---------------------------+
+   |
+   v
+ +---------------------------+
+ | 4. AUTO-REVIEW           |  Critico != owner. APROBADO o RECHAZADO con razon
+ +---------------------------+
+   | RECHAZADO ----------------+
+   | APROBADO                 |
+   v                           |
+ +---------------------------+ |
+ | 5. GATES                 | |
+ |  Verificador (tecnico)   | |
+ |  Guardian (seguridad)     | |
+ +---------------------------+ |
+   |                           |
+   | FALLA ---------------------+
+   | PASA
+   v
+ +-----------+         +---------------+
+ | 6. DONE   |         | 7. REWORK     |
+ +-----------+         |  1er: reintenta|
+                       |  2do: replan  |
+                       |  3ro: ESCALA  |
+                       +---------------+
+```
+
+**[plugin]** Con el plugin, el paso 3 es un `oficina_assign` y el paso 5 un `oficina_gate` que corre los comandos de verdad.
+
+Cada 3 cards completadas → **checkpoint** al usuario. Al final → **informe de entrega**.
+
+---
+
+## Los roles
+
+| Rol | Agente | Puede aprobar? |
+|---|---|---|
+| Comandante | `oficina-commander` | No revisa técnico |
+| Arquitecto | `oficina-architect` | No revisa técnico |
+| Integrador | `oficina-integrator` | No revisa técnico |
+| Explorador | `code-explorer` | No |
+| Arquitecto (rol) | `code-architect` | No |
+| Implementador | `general` | No |
+| **Crítico** | `oficina-critico` | Sí (revisión de card) |
+| **Guardián** | `oficina-guardian` | Sí (gate seguridad) |
+| **Verificador** | `oficina-verificador` | Sí (gate técnico) |
+
+**Regla dura:** el que implementa nunca revisa su propio trabajo.
+
+---
+
+## Resolver roles: catálogo → factory → panel
+
+**[plugin]** `oficina_brief` muestra el panel sin desplegar; `oficina_ficha` además despliega el agente con su briefing.
+
+**1. Catálogo primero.** El repo de agency-agents tiene **306 agentes en 25 divisiones**. La especialidad real de cada uno está en el **cuerpo** (Core Mission, Technical Deliverables, Advanced Capabilities), no en el `description`. El matcher pondera el nombre del rol (40%), la misión literal (35%) y la misión conceptual (20%).
+
+**2. Factory si la cobertura es < 60%.** El rol fabricado emite la **misma estructura de 10 secciones** que el catálogo, con las capabilities, el scope, el objetivo de la corrida y los modos de fallo del rol. Un rol fabricado con contexto es usable; uno genérico no.
+
+**3. Panel, no un solo agente.** Un objetivo casi nunca es de un solo dominio. El panel devuelve:
+
+- **primario** — el mejor match. Se lleva la card.
+- **complementos** — los que cubren lo que el primario NO cubre. Son sus pares en el bus.
+- **sin cubrir** — lo que nadie cubre. Señal de que la card debería partirse en dos.
+
+**Nunca fuerces un mal match.** Si nadie cubre una capacidad, se fabrica el rol o se pide ayuda. Un rol medio-tono en el equipo arruina más de lo que aporta.
+
+**Sin plugin**: la tabla de `reference/roles.md`.
+
+---
+
+## El briefing: qué recibe cada agente
+
+**[plugin]** Todo agente desplegado recibe un briefing de **10 secciones en orden fijo** —de lo más estable a lo más cambiante— y **4 artefactos** en `.oficina/fichas/<agentId>/`:
+
+| Artefacto | Contenido |
+|---|---|
+| `ficha.md` | Quién sos: rol, especialidad, origen, vibe |
+| `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: dónde, formato, TTLs, cómo acusar recibo |
+
+**El agente no arranca sin `misiones.md`. Nunca.**
+
+**Mínimo**: las 10 secciones son requeridas. Si alguna queda vacía, el briefing se marca `INCOMPLETO` y el agente no se despliega. Un briefing a medio llenar produce un agente a medio informado, que es peor que no tener agente.
+
+La sección *"lo que ya sabés"* se alimenta del **ledger** (`.oficina/context.md`): decisiones, restricciones, piezas construidas y trampas. Es lo que evita repetir lo ya decidido.
+
+Detalle completo en `reference/mesh.md`.
+
+---
+
+## Pedir ayuda y delegar
+
+**[plugin]** `oficina_bus` con `action: "help"`.
+
+El que recibe **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.
+
+**[plugin]** Delegar un rol nuevo: `oficina_spawn`. El Integrador aprueba o rechaza. Nunca clones agentes por tu cuenta.
+
+**Sin plugin**: `reference/protocol.md`.
+
+---
+
+## El pool idle
+
+Cuando un agente termina su objetivo, entra al pool y puede ayudar de tres modos:
+
+1. Atender un `HELP_REQUEST` dirigido
+2. Atender un broadcast (`to: ["*"]`) — el primero que acepta toma el lease
+3. **Claim proactivo** — si hay cards sin owner y tu capability matchea, la reclamás
+
+El modo 3 es lo que convierte la oficina de "N tareas en paralelo" a "N agentes que se acomodan solos según la carga".
+
+---
+
+## Reglas de ejecución
+
+1. **Nunca marques DONE sin los gates en verde.** Una card sin `gates.md` en PASS no está DONE, está mintiendo.
+2. **Nunca revises tu propio trabajo.**
+3. **Un subagente, una card, un artefacto.** Los subagentes son stateless: la delegación lleva todo el contexto.
+4. **Los artefactos son la memoria.** Si no está en `.oficina/`, no existe.
+5. **Escalá cuando el caso lo pida**, no antes. 3 rechazos de la misma card = escalación con opciones concretas.
+6. **Presupuesto**: 20 cards, 40 invocaciones, 20 spawns por corrida. Si se agota, informe parcial honesto y preguntá.
+
+---
+
+## Umbral de calidad
+
+De `verification-loop`: build → type check → lint → tests → security grep → diff review.
+
+Si el proyecto no tiene tooling para alguna fase, se marca `N/A` explícito — nunca se saltea en silencio.
+
+**[plugin]** El escaneo de secretos corre en código y **redacta** el valor: un log de gate que imprime la credencial completa la acaba de filtrar.
+
+---
+
+## Cuándo NO usar OFICINA
+
+- Tarea de una sola acción.
+- El usuario pidió explícitamente hacerlo vos directo.
+- Exploración sin objetivo claro — primero brainstorming, después OFICINA.
+
+En esos casos, hacelo vos. OFICINA es para trabajo multi-paso con objetivo verificable.
+
+---
+
+## Referencias
+
+- `reference/mesh.md` — bus, fichas, roster, leases, spawn policy, idle pool (v2)
+- `reference/roles.md` — fichas de rol, criterios de enrutado, rotación
+- `reference/protocol.md` — handoff, gates, escalamiento, checkpoints, reintentos
+- `reference/templates.md` — templates de board, state.json, handoff, review, gates, informe