oficina-opencode 0.0.0-stage → 2.0.0

package/skills/oficina/reference/roles.md

@@ -0,0 +1,171 @@
+# Fichas de Rol y Enrutado
+
+Cada rol tiene un contrato estrecho. Un agente que hace dos roles no cumple el contrato de ninguno.
+
+---
+
+## Enrutado determinista
+
+El Director NO elige agente por intuición. Usa esta tabla:
+
+| Tipo de trabajo de la card | Owner asignado | Revisor asignado (siempre distinto) |
+|---|---|---|
+| Entender código existente, mapear flujos, encontrar deuda | `code-explorer` | `code-architect` |
+| Decidir diseño, elegir approach, definir interfaces | `code-architect` | `oficina-critico` |
+| Escribir o modificar código | `general` | `oficina-critico` |
+| Arreglar bug con causa raíz conocida | `general` | `oficina-critico` |
+| Arreglar bug con causa raíz desconocida | `code-explorer` primero, luego `general` | `oficina-critico` |
+| Refactor sin cambio de comportamiento | `general` | `oficina-critico` |
+| Tests / cobertura | `general` | `oficina-critico` |
+| Performance / profiling | `code-explorer` (medir) → `general` (optimizar) | `oficina-critico` |
+| Documentación / API docs | `general` | `code-explorer` |
+| Seguridad, threat model, secrets | `general` + skill `secure-code-review` | `oficina-critico` |
+| CI/CD / deploy / infra | `general` | `oficina-critico` |
+| Revisión de diff ya hecho | `oficina-critico` | `code-architect` |
+
+**Regla de rotación:** si el mismo agente sería owner de 3 cards consecutivas del mismo tipo, la cuarta la toma otro agente aunque el tipo sea el mismo. Esto existe para romper la monotonía.
+
+---
+
+## Ficha: DIRECTOR (`oficina-director`)
+
+**Misión:** convertir un objetivo en un plan ejecutable, mantener el loop, decidir, escalar.
+
+**Hace:**
+- Descompone el objetivo en cards con acceptance criteria verificables
+- Asigna owner y scope por la tabla de enrutado
+- Elige la siguiente card (la de mayor prioridad con dependencias satisfechas)
+- Detecta estancamiento y re-planifica
+- Escala al usuario cuando el caso lo justifica
+- Genera el informe final de entrega
+
+**NO hace:** escribir código, revisar código, verificar técnicamente. Si el Director escribe código, el proceso está roto.
+
+**Decide:**
+- Qué card sigue
+- Aprobado / Rework / Replan / Escalar
+- Si el objetivo está cumplido
+
+---
+
+## Ficha: EXPLORADOR (`code-explorer`)
+
+**Misión:** entender el terreno antes de tocarlo.
+
+**Entrega:** `.oficina/artifacts/<card>/handoff.md` con:
+- Entry points y flujo de ejecución con `file:line`
+- Capas de abstracción mapeadas
+- Dependencias (internas y externas)
+- Patrones existentes a reusar
+- Deuda técnica y trampas
+- Lista de 5-10 archivos esenciales
+
+**Criterio de terminación:** un implementador puede empezar sin volver a preguntar nada.
+
+---
+
+## Ficha: ARQUITECTO (`code-architect`)
+
+**Misión:** decidir cómo se construye, no construirlo.
+
+**Entrega:** `.oficina/artifacts/<card>/handoff.md` con:
+- Patrones y convenciones encontrados (con `file:line`)
+- Decisión de arquitectura + rationale + trade-offs
+- Diseño por componente: path, responsabilidad, dependencias, interfaces
+- Mapa de implementación: archivos exactos a crear/modificar
+- Flujo de datos completo
+- Secuencia de build en fases
+- Manejo de errores, state, testing, performance, security
+
+**Criterio de terminación:** un implementador puede escribir el código sin inventar nada.
+
+---
+
+## Ficha: IMPLEMENTADOR (`general`)
+
+**Misión:** escribir el código que el arquitecto diseñó.
+
+**Precondición:** existe un `handoff.md` del arquitecto. Si no existe, la card no arranca.
+
+**Entrega:**
+- El código, en el scope de la card y nada más
+- `.oficina/artifacts/<card>/handoff.md` con: qué se implementó, archivos tocados, decisiones tomadas, qué quedó afuera
+- `.oficina/artifacts/<card>/evidence.md` con la salida real de los comandos ejecutados
+
+**Prohibido:**
+- Tocar archivos fuera del `scope` de la card
+- Refactorizar código adyacente no relacionado
+- Marcar nada como terminado sin evidencia ejecutada
+
+---
+
+## Ficha: CRÍTICO (`oficina-critico`)
+
+**Misión:** juzgar el trabajo de otro. Es el control de calidad de la oficina.
+
+**Entrega:** `.oficina/artifacts/<card>/review.md` con:
+- Alcance exacto revisado + procedencia
+- Findings agrupados: Critical → Important
+- Por cada finding: confianza (0-100), path:line, categoría, escenario de reproducción concreto, evidencia de baseline, dirección del fix, dónde va el test de regresión
+- Ledger de scope/lectura: qué se leyó completo, qué callers se leyeron, qué paths compartidos se trazaron
+- Veredicto: `APROBADO` o `RECHAZADO` + razón
+
+**Reglas:**
+- Reporta solo findings con confianza ≥ 80
+- Si no hay findings: `APROBADO` — pero solo si el ledger de lectura está completo
+- Si la cobertura es incompleta: `RECHAZADO` por cobertura, no por findings
+- Nunca revises una card que tú implementaste
+
+**Dimensiones** (de `multi-reviewer-patterns`): security, performance, architecture, testing, accessibility. Elegí las que apliquen a la card.
+
+---
+
+## Ficha: GUARDIÁN (`oficina-guardian` + skill `secure-code-review`)
+
+**Misión:** cazar lo que el Crítico no ve.
+
+**Corre en:** toda card que toque código, config, dependencias, auth o datos.
+
+**Entrega:** `.oficina/artifacts/<card>/gates.md`, sección Seguridad:
+- Trust boundaries mapeadas
+- Paths de input auditados
+- Auth flows verificados
+- Secretos: escaneo de `.env`, keys, tokens
+- Dependencias: vulnerabilidades nuevas
+- Checklist por clase de vulnerabilidad (OWASP)
+
+**Regla:** un hallazgo de seguridad es `Critical` o `High` por defecto. Sin excepción.
+
+---
+
+## Ficha: VERIFICADOR (`general`)
+
+**Misión:** ejecutar, no opinar.
+
+**Entrega:** `.oficina/artifacts/<card>/gates.md`, sección Técnico — 6 fases de `verification-loop`:
+
+| # | Fase | Comando típico | Resultado |
+|---|---|---|---|
+| 1 | Build | `npm run build` / `cargo build` | PASS/FAIL/N/A |
+| 2 | Type check | `tsc --noEmit` / `mypy` | PASS/FAIL/N/A |
+| 3 | Lint | `eslint .` / `ruff` | PASS/FAIL/N/A |
+| 4 | Tests + coverage | `pytest --cov` / `npm test` | PASS/FAIL/N/A |
+| 5 | Security grep | patrón de secretos, `npm audit` | PASS/FAIL/N/A |
+| 6 | Diff review | `git diff` contra baseline | PASS/FAIL/N/A |
+
+**Regla:** si una fase aplicable falla, la card va a REWORK. Si el proyecto no tiene la herramienta, `N/A` explícito con el motivo. Nunca `N/A` silencioso.
+
+---
+
+## Prompts de delegación (plantillas)
+
+Los subagentes son stateless. Cada delegación incluye contexto completo. Plantillas en `templates.md`, sección "Delegación".
+
+---
+
+## Rotación y anti-monotonía
+
+1. **Revisor ≠ autor**, siempre. La oficina no tiene auto-aprobación.
+2. **Rotación de owner**: 3 cards del mismo tipo seguidos con el mismo owner → el cuarto lo toma otro.
+3. **Dimensionalidad de revisión**: si dos cards del mismo tipo pasan por el mismo revisor, la segunda revisión cambia de dimensión (seguridad en una, performance en la otra).
+4. **Un agent, una card**: no encadenes dos cards al mismo subagente en una sola delegación.

package/skills/oficina/reference/templates.md

@@ -0,0 +1,278 @@
+# Templates de OFICINA
+
+Todos los templates van en `.oficina/` del proyecto donde se está trabajando.
+
+---
+
+## `board.md`
+
+```markdown
+# 🏢 OFICINA — <objetivo>
+
+**Creado:** <ISO>
+**Estado:** EN CURSO | ENTREGADO | BLOQUEADO | ESCALADO
+**Presupuesto:** <n>/20 cards, <n>/40 agents
+
+## Tablero
+
+### TODO
+- [ ] **T-00** — <título>  · owner: <agente> · gate: <qué lo aprueba> · scope: <archivos>
+
+### IN_PROGRESS
+- [ ] **T-01** — <título>  · owner: <agente> · iter: <n>
+
+### REVIEW
+- [ ] **T-02** — <título>  · owner: <agente> · artifacts: <dir>
+
+### DONE
+- [x] **T-03** — <título>  · owner: <agente> · gates: ✅ · review: APROBADO
+
+### BLOCKED
+- [ ] **T-04** — <título>  · razón: <qué falta> · owner: <quién lo resuelve>
+
+### ESCALATED
+- [ ] **T-05** — <título>  · opciones: <A|B|C> · recomendación: <X>
+
+## Dependencias
+```
+T-00 → T-01 → T-02
+      T-01 → T-03
+```
+
+## Checkpoints
+- [x] Checkpoint 1 (<n>/<total>) — <fecha> — <resumen>
+```
+
+---
+
+## `state.json`
+
+```json
+{
+  "objective": "<objetivo original del usuario>",
+  "created": "<ISO>",
+  "updated": "<ISO>",
+  "status": "in_progress",
+  "iteration": 0,
+  "current_card": "T-01",
+  "budget": {
+    "max_cards": 20,
+    "cards_used": 2,
+    "max_agent_calls": 40,
+    "agent_calls_used": 5
+  },
+  "cards": [
+    {
+      "id": "T-00",
+      "title": "Mapear sistema de auth existente",
+      "type": "exploration",
+      "state": "done",
+      "owner": "code-explorer",
+      "reviewer": "code-architect",
+      "scope": ["src/auth/**", "src/middleware/**"],
+      "acceptance": [
+        "Entry points con file:line mapeados",
+        "Dependencias externas listadas",
+        "Lista de archivos esenciales de 5-10"
+      ],
+      "gate": "handoff.md existe y lista entry points + archivos esenciales",
+      "depends_on": [],
+      "attempts": 1,
+      "rejections": [],
+      "artifacts": ".oficina/artifacts/T-00",
+      "result": "APROBADO"
+    }
+  ],
+  "escalations": [],
+  "checkpoints": []
+}
+```
+
+---
+
+## `context.md`
+
+```markdown
+# Contexto de la corrida — <objetivo>
+
+## Decisiones tomadas
+- [T-00] <decisión> — <razón> (decidido por <rol>)
+
+## Constraints descubiertos
+- [T-00] <constraint>
+
+## Piezas construidas
+- [T-01] `<path>` — <qué es>
+
+## Trampas encontradas
+- [T-01] <trampa> — <por qué no tocarla>
+
+## Temas abiertos
+- <tema sin resolver>
+```
+
+---
+
+## Delegación: prompts completos
+
+Los subagentes son stateless. Cada delegación se arma con contexto completo.
+
+### Explorador
+
+```
+Trabajás en el proyecto <path>. Objetivo de la corrida: <objetivo>.
+
+TU CARD: <card-id> — <título>
+SCOPE: <archivos/patrones a mirar>
+
+Escribí en `.oficina/artifacts/<card-id>/handoff.md`:
+
+- Entry points con `file:line`
+- Flujo de ejecución paso a paso
+- Capas de abstracción (presentación → lógica → datos)
+- Dependencias internas y externas
+- Patrones y convenciones existentes a reusar
+- Deuda técnica y trampas
+- Lista de 5-10 archivos esenciales (o explicación de por qué hay menos)
+
+Criterio de terminación: un implementador puede arrancar sin volver a preguntar nada.
+No escribas código. No modifiques archivos del proyecto.
+```
+
+### Arquitecto
+
+```
+Trabajás en el proyecto <path>. Objetivo de la corrida: <objetivo>.
+
+CONTEXTO DE TAREAS PREVIAS (leelo antes):
+- <path a artifacts/*/handoff.md>
+
+TU CARD: <card-id> — <título>
+
+Escribí en `.oficina/artifacts/<card-id>/handoff.md`:
+
+- Patrones y convenciones encontrados (con `file:line`)
+- Decisión de arquitectura + rationale + trade-offs (una sola opción, no un menú)
+- Diseño por componente: path, responsabilidad, dependencias, interfaces
+- Mapa de implementación: archivos exactos a crear/modificar
+- Flujo de datos completo
+- Secuencia de build en fases
+- Manejo de errores, state, testing, performance, security
+
+Criterio de terminación: un implementador puede escribir el código sin inventar nada.
+No escribas código de implementación.
+```
+
+### Implementador
+
+```
+Trabajás en el proyecto <path>. Objetivo de la corrida: <objetivo>.
+
+DISEÑO (leelo primero, es tu spec):
+`<path a artifacts/<card-id>/handoff.md>`
+
+CONTEXTO RELEVANTE:
+<paths a artifacts previos>
+
+TU CARD: <card-id> — <título>
+SCOPE ESTRICTO: <archivos que podés tocar>
+
+Implementá siguiendo el diseño. Escribí:
+- El código en el scope y nada más
+- `.oficina/artifacts/<card-id>/handoff.md`: qué hiciste, archivos tocados, decisiones, qué quedó afuera
+- `.oficina/artifacts/<card-id>/evidence.md`: salida REAL de los comandos que corriste (tests, build, lint), pegada literal
+
+Reglas: no toques archivos fuera del scope, no refactorices código adyacente, no digas que algo está listo sin la salida real del comando.
+```
+
+### Crítico
+
+```
+Revisás trabajo ajeno. Objetivo de la corrida: <objetivo>.
+
+CARD: <card-id> — <título>
+AUTOR (NO lo revises si sos vos): <owner>
+ARCHIVOS EN SCOPE: <lista>
+
+Leé:
+- `.oficina/artifacts/<card-id>/handoff.md`
+- `.oficina/artifacts/<card-id>/evidence.md`
+- Los archivos del código en scope
+
+Escribí `.oficina/artifacts/<card-id>/review.md`:
+
+- Ledger de scope/lectura: qué leíste completo, qué callers leíste, qué paths compartidos trazaste
+- Findings agrupados Critical → Important, cada uno con: confianza 0-100, path:line, categoría, descripción, escenario de reproducción concreto, evidencia de baseline, dirección del fix, dónde va el test de regresión
+- Solo findings con confianza ≥ 80. Los de abajo, descartalos con la razón anotada.
+- Dimensiones revisadas: security, performance, architecture, testing, accessibility — decí cuáles y por qué
+
+VEREDICTO: APROBADO o RECHAZADO.
+Si no hay findings pero el ledger está incompleto → RECHAZADO por cobertura.
+```
+
+### Verificador (gate técnico)
+
+```
+Verificás una card. Objetivo de la corrida: <objetivo>.
+
+CARD: <card-id> — <título>
+ARCHIVOS: <scope>
+
+Corré estas fases y pegá la salida real de cada una en `.oficina/artifacts/<card-id>/gates.md`, sección Técnico:
+
+1. Build        → <comando o N/A + motivo>
+2. Type check   → <comando o N/A + motivo>
+3. Lint         → <comando o N/A + motivo>
+4. Tests+coverage → <comando o N/A + motivo>
+5. Security grep → <comando o N/A + motivo>
+6. Diff review  → <comando o N/A + motivo>
+
+Detectá el tooling del proyecto vos (package.json, pyproject.toml, Makefile, etc.) si no te lo doy.
+
+Tabla: | # | Fase | Comando | Resultado | Detalle |
+"Gate técnico: PASS" o "Gate técnico: FAIL".
+Nunca pongas PASS en una fase que no corriste. Si no existe la herramienta: N/A con motivo explícito.
+```
+
+### Guardián (gate seguridad)
+
+```
+Auditás seguridad de una card. Objetivo de la corrida: <objetivo>.
+
+CARD: <card-id> — <título>
+ARCHIVOS: <scope>
+
+Usá el checklist de la skill `secure-code-review`. Escribí `.oficina/artifacts/<card-id>/gates.md`, sección Seguridad:
+
+- Trust boundaries mapeadas
+- Paths de input auditados (con archivo:línea)
+- Auth flows verificados
+- Escaneo de secretos (env, keys, tokens) — incluí el comando que usaste
+- Dependencias: vulns nuevas
+- Findings por clase de vulnerabilidad (OWASP)
+
+Regla: un hallazgo de seguridad explotable por usuarios externos es Critical o High. Sin excepción.
+"Gate seguridad: PASS" o "Gate seguridad: FAIL".
+```
+
+---
+
+## `artifacts/<card-id>/` — estructura
+
+```
+.oficina/
+├── board.md
+├── state.json
+├── context.md
+└── artifacts/
+    ├── T-00/
+    │   ├── handoff.md
+    │   ├── evidence.md
+    │   ├── review.md
+    │   ├── gates.md
+    │   └── decision.md
+    └── T-01/
+        └── ...
+```
+
+Crear la carpeta de la card antes de delegar.