ndomo 0.1.0

package/README.es.md

@@ -0,0 +1,174 @@
+# ndomo
+
+Plugin multi-agente para OpenCode. Taller de artesanos: 19 especialistas bajo un Foreman, un Craftsman y un Warden. Nativo en caveman. opencode-mem integrado. DCP peer opcional.
+
+## Qué es ndomo
+
+ndomo es un plugin de orquestación multi-agente para [OpenCode](https://github.com/opencode-ai). Enruta tareas de desarrollo a 19 agentes especializados (scout, scribe, painter, smith, sage, guild, stack-smiths, inspector, chronicler, y ops agents) coordinados por 3 primaries: Foreman (planificación), Craftsman (implementación), Warden (operaciones). Todos los agentes usan el protocolo de salida Caveman para comunicación eficiente en tokens. La persistencia de memoria entre sesiones la gestiona opencode-mem. El plugin opcional DCP proporciona poda de contexto adicional para sesiones largas.
+
+## Agentes
+
+| Agente | Rol | Modelo (preset default) | Tipo |
+|---|---|---|---|
+| **foreman** | Orquestador y scheduler maestro | minimax/MiniMax-M3 | primary |
+| **warden** | Custodio de operaciones — CI/CD, deploy, releases, monitoreo | opencode-go/deepseek-v4-flash | primary |
+| **scout** | Reconocimiento de codebase | opencode-go/minimax-m2.7 | subagent |
+| **scribe** | Recuperación de conocimiento externo | opencode-go/minimax-m2.7 | subagent |
+| **painter** | Diseño UI/UX y composición visual | opencode-go/kimi-k2.6 | subagent |
+| **smith** | Implementación genérica rápida | opencode-go/deepseek-v4-flash | subagent |
+| **go-smith** | Especialista en Go | xiaomi/mimo-v2.5-pro | subagent |
+| **js-smith** | Especialista en JS/TS | xiaomi/mimo-v2.5-pro | subagent |
+| **python-smith** | Especialista en Python | xiaomi/mimo-v2.5-pro | subagent |
+| **vue-smith** | Especialista en Vue 3 / Pinia | xiaomi/mimo-v2.5-pro | subagent |
+| **zig-smith** | Especialista en Zig 0.16 | xiaomi/mimo-v2.5-pro | subagent |
+| **rust-smith** | Especialista en Rust | opencode-go/mimo-v2.5-pro | subagent |
+| **sage** | Asesor de arquitectura y debugging | opencode-go/deepseek-v4-pro | subagent |
+| **guild** | Consenso multi-LLM y debate | opencode-go/deepseek-v4-pro | subagent |
+| **inspector** | Auditor de calidad y seguridad | opencode-go/deepseek-v4-pro | subagent |
+| **chronicler** | Redactor de documentación técnica | opencode-go/deepseek-v4-flash | subagent |
+| **ci-smith** | Especialista en pipelines CI/CD | opencode-go/deepseek-v4-flash | subagent |
+| **deploy-smith** | Especialista en automatización de deploys | opencode-go/deepseek-v4-flash | subagent |
+| **release-smith** | Especialista en gestión de releases | opencode-go/deepseek-v4-flash | subagent |
+| **ops-scout** | Especialista en reconocimiento de infra (solo lectura) | opencode-go/deepseek-v4-flash | subagent |
+
+**Grupos:** Orquestador (foreman), Exploradores (scout, scribe), Constructores (painter, smith, go-smith, js-smith, python-smith, vue-smith, zig-smith, rust-smith), Asesores (sage, guild), Calidad (inspector, chronicler), Operaciones (warden, ci-smith, deploy-smith, release-smith, ops-scout).
+
+## Inicio Rápido
+
+```bash
+# Instalación rápida (interactivo, preguntará por provider)
+curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/install.sh | bash
+
+# No interactivo con provider preestablecido
+curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/install.sh | bash -s -- --provider=opencode --no-provider-prompt
+
+# Con preset budget + DCP
+curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/install.sh | bash -s -- --preset=budget --with-dcp
+```
+
+Por defecto la instalación aplica `presets.default` de `config/ndomo.config.json`. Usa `--preset=budget` para modelos más económicos, `--provider=ID` para sobrescribir el prefijo de provider.
+
+O desde el código fuente:
+
+```bash
+git clone <repo-url> ndomo
+cd ndomo
+bun install
+opencode
+```
+
+Dentro de OpenCode, verifica que todos los agentes respondan:
+
+```
+ping all agents
+```
+
+## Instalación
+
+**Requisitos:** [bun](https://bun.sh) >= 1.1.0, OpenCode instalado y configurado con al menos un proveedor autenticado.
+
+Instalación vía curl (recomendada):
+
+```bash
+# Instalación interactiva (preguntará por provider)
+curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/install.sh | bash
+
+# Con provider preestablecido (no interactivo)
+curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/install.sh | bash -s -- --provider=opencode --no-provider-prompt
+
+# Con preset budget + DCP
+curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/install.sh | bash -s -- --preset=budget --with-dcp
+```
+
+O desde un clon local:
+
+```bash
+git clone <repo-url> ndomo
+cd ndomo
+./scripts/install.sh                 # con preset default
+./scripts/install.sh --preset=budget # con modelos budget
+./scripts/install.sh --with-dcp      # incluye plugin DCP
+```
+
+Ver [docs/installation.md](docs/installation.md) para pasos detallados.
+
+**Flags:**
+
+| Flag | Descripción |
+|---|---|
+| `--provider=ID` | Sobrescribe el prefijo de provider para todos los agentes. El model ID se toma del preset activo; solo se intercambia el segmento `provider/` del campo `model:`. Ejemplo: el preset da `opencode-go/minimax-m2.7`, `--provider=opencode` reescribe a `opencode/minimax-m2.7`. |
+| `--no-provider-prompt` | Omite el prompt interactivo de provider. El preset se aplica igualmente; no se realiza ninguna sobrescritura de prefijo de provider. |
+| `--preset=NAME` | Selecciona un preset de `config/ndomo.config.json::presets[NAME]`. El preset es la fuente de verdad para los modelos de agentes al instalar. (default: `default`, opciones: `default`, `budget`) |
+| `--with-dcp` | Instala y configura el plugin DCP. |
+| `--repo=URL` | Sobrescribe la URL del repositorio (para instalaciones vía pipe desde un fork). |
+| `--branch=NAME` | Sobrescribe la rama del repositorio (para instalaciones vía pipe desde ramas dev). |
+
+**Desinstalación:** `./scripts/uninstall.sh [--keep-data]`
+
+## Base de Datos de Planes y Tareas
+
+ndomo persiste planes, tareas y sesiones en una base de datos SQLite local al proyecto
+(`<project>/.ndomo/state.db`) con búsqueda FTS5, trazabilidad de auditoría y
+archivado automático a markdown al completarse. 14 herramientas expuestas vía OpenCode:
+`plan_create`, `plan_get`, `plan_list`, `plan_search`, `plan_approve`,
+`plan_update_status`, `task_create_batch`, `task_list`, `task_update_status`,
+`task_search`, `task_next_for_agent`, `session_start`, `session_checkpoint`,
+`session_end`.
+
+El foreman las usa para rastrear trabajo a través de despachos de agentes. Ver
+[docs/database.md](docs/database.md) para esquema, herramientas, ciclo de vida y
+comportamiento de archivado automático.
+
+## Configuración
+
+Archivo de configuración: `~/.config/opencode/ndomo.json`
+
+```json
+{
+  "preset": "default",
+  "caveman": { "intensity": "full", "autoClarity": true },
+  "mem": {
+    "storagePath": "~/.ndomo/mem",
+    "defaultScope": "project",
+    "autoCaptureEnabled": true,
+    "cavemanCompress": true
+  }
+}
+```
+
+Ver [docs/configuration.md](docs/configuration.md) para referencia completa. Los presets de agente soportan el campo opcional `reasoning_effort` (`low`/`medium`/`high`/`xhigh`) para modelos con capacidad de razonamiento.
+
+## Skills
+
+ndomo incluye 7 skills en `skills/`:
+
+| Skill | Descripción |
+|---|---|
+| `caveman` | Modo de comunicación ultracomprimido (~75% reducción de tokens) |
+| `cavecrew` | Subagentes estilo caveman (investigator, builder, reviewer) |
+| `deepwork` | Flujo estructurado para trabajo pesado con plan files y review gates |
+| `reflect` | Análisis de fricción en el flujo de trabajo y extracción de patrones |
+| `worktrees` | Gestión de git worktrees para carriles aislados de desarrollo |
+| `dcp-integration` | Guía de integración de Dynamic Context Pruning |
+| `mem-recall` | Uso de herramientas opencode-mem y patrones de recuperación |
+
+## Integraciones
+
+- **opencode-mem** (requerido) — memoria persistente con SQLite + USearch vector DB. Interfaz web en `:4747`. Todos los agentes comprimen recuerdos antes de almacenar usando compresión caveman vía regex (0 tokens de LLM).
+- **DCP** (opcional) — `@tarquinen/opencode-dcp` para poda dinámica de contexto. Licencia AGPL-3.0. Se instala con flag `--with-dcp`.
+
+Ver [docs/integrations.md](docs/integrations.md) para detalles.
+
+## Ahorro de Tokens
+
+El protocolo de salida Caveman reduce el uso de tokens ~60-75% vs prosa estándar eliminando artículos, palabras de relleno, conjunciones y cortesías, preservando todo el contenido técnico. El plugin DCP añade poda adicional eliminando salidas de herramientas de bajo valor del historial de conversación.
+
+## Licencia
+
+MIT
+
+## Enlaces
+
+- Repositorio: `<repo-url>`
+- OpenCode: [https://github.com/opencode-ai](https://github.com/opencode-ai)
+- opencode-mem: [https://github.com/opencode-ai/opencode-mem](https://github.com/opencode-ai/opencode-mem)

package/README.md

@@ -0,0 +1,187 @@
+# ndomo
+
+OpenCode multi-agent plugin. Taller de artesanos: 19 specialists under one Foreman, one Craftsman, and one Warden. Caveman-native. opencode-mem integrated. DCP peer optional.
+
+## What is ndomo
+
+ndomo is a multi-agent orchestration plugin for [OpenCode](https://github.com/opencode-ai). It routes development tasks to 19 specialized agents (scout, scribe, painter, smith, sage, guild, stack-smiths, inspector, chronicler, and ops agents) coordinated by 3 primaries: Foreman (planning), Craftsman (implementation), Warden (operations). All agents use the Caveman output protocol for token-efficient communication. Memory persistence across sessions is handled by opencode-mem. The optional DCP plugin provides additional context pruning for long sessions.
+
+## Agents
+
+| Agent | Role | Model (default preset) | Type |
+|---|---|---|---|
+| **foreman** | Master orchestrator and scheduler | minimax/MiniMax-M3 | primary |
+| **warden** | Ops custodian — CI/CD, deploy, releases, monitoring | opencode-go/deepseek-v4-flash | primary |
+| **scout** | Codebase reconnaissance | opencode-go/minimax-m2.7 | subagent |
+| **scribe** | External knowledge retrieval | opencode-go/minimax-m2.7 | subagent |
+| **painter** | UI/UX design and visual composition | opencode-go/kimi-k2.6 | subagent |
+| **smith** | Fast generic implementation | opencode-go/deepseek-v4-flash | subagent |
+| **go-smith** | Go implementation specialist | xiaomi/mimo-v2.5-pro | subagent |
+| **js-smith** | JS/TS implementation specialist | xiaomi/mimo-v2.5-pro | subagent |
+| **python-smith** | Python implementation specialist | xiaomi/mimo-v2.5-pro | subagent |
+| **vue-smith** | Vue 3 / Pinia implementation specialist | xiaomi/mimo-v2.5-pro | subagent |
+| **zig-smith** | Zig 0.16 implementation specialist | xiaomi/mimo-v2.5-pro | subagent |
+| **rust-smith** | Rust implementation specialist | opencode-go/mimo-v2.5-pro | subagent |
+| **sage** | Architecture advisor and debugger | opencode-go/deepseek-v4-pro | subagent |
+| **guild** | Multi-LLM consensus and debate | opencode-go/deepseek-v4-pro | subagent |
+| **inspector** | Code quality and security auditor | opencode-go/deepseek-v4-pro | subagent |
+| **chronicler** | Technical documentation writer | opencode-go/deepseek-v4-flash | subagent |
+| **ci-smith** | CI/CD pipeline specialist | opencode-go/deepseek-v4-flash | subagent |
+| **deploy-smith** | Deployment automation specialist | opencode-go/deepseek-v4-flash | subagent |
+| **release-smith** | Release management specialist | opencode-go/deepseek-v4-flash | subagent |
+| **ops-scout** | Infrastructure recon specialist (read-only) | opencode-go/deepseek-v4-flash | subagent |
+
+**Groups:** Orchestrator (foreman), Explorers (scout, scribe), Builders (painter, smith, go-smith, js-smith, python-smith, vue-smith, zig-smith, rust-smith), Advisors (sage, guild), Quality (inspector, chronicler), Operations (warden, ci-smith, deploy-smith, release-smith, ops-scout).
+
+## Quick Start
+
+```bash
+# Quick install (interactive, will prompt for provider)
+curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/install.sh | bash
+
+# Non-interactive with provider preset
+curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/install.sh | bash -s -- --provider=opencode --no-provider-prompt
+
+# With budget preset + DCP
+curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/install.sh | bash -s -- --preset=budget --with-dcp
+```
+
+By default the install applies `presets.default` from `config/ndomo.config.json`. Use `--preset=budget` for cheaper models, `--provider=ID` to override the provider prefix.
+
+Or from source:
+
+```bash
+git clone <repo-url> ndomo
+cd ndomo
+bun install
+opencode
+```
+
+Inside OpenCode, verify all agents respond:
+
+```
+ping all agents
+```
+
+## Installation
+
+**Prerequisites:** [bun](https://bun.sh) >= 1.1.0, OpenCode installed and configured with at least one authenticated provider.
+
+Install via curl (recommended):
+
+```bash
+# Interactive install (will prompt for provider)
+curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/install.sh | bash
+
+# With provider preset (non-interactive)
+curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/install.sh | bash -s -- --provider=opencode --no-provider-prompt
+
+# With budget preset + DCP
+curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/install.sh | bash -s -- --preset=budget --with-dcp
+```
+
+Or from a local clone:
+
+```bash
+git clone <repo-url> ndomo
+cd ndomo
+./scripts/install.sh                 # with default preset
+./scripts/install.sh --preset=budget # with budget models
+./scripts/install.sh --with-dcp      # include DCP plugin
+```
+
+See [docs/installation.md](docs/installation.md) for detailed steps.
+
+**Flags:**
+
+| Flag | Description |
+|---|---|
+| `--provider=ID` | Override the provider prefix for all agents. The model ID is taken from the active preset; only the `provider/` segment of the `model:` field is swapped. Example: preset gives `opencode-go/minimax-m2.7`, `--provider=opencode` rewrites to `opencode/minimax-m2.7`. |
+| `--no-provider-prompt` | Skip the interactive provider prompt. The preset is still applied; no provider prefix override is performed. |
+| `--preset=NAME` | Select preset from `config/ndomo.config.json::presets[NAME]`. The preset is the source of truth for agent models at install time. (default: `default`, options: `default`, `budget`) |
+| `--with-dcp` | Install and configure the DCP plugin. |
+| `--repo=URL` | Override repository URL (for piped installs from a fork). |
+| `--branch=NAME` | Override repository branch (for piped installs from dev branches). |
+
+**Uninstall:** `./scripts/uninstall.sh [--keep-data]`
+
+## Plans & Tasks DB
+
+ndomo persists plans, tasks, and sessions in a project-local SQLite database
+(`<project>/.ndomo/state.db`) with FTS5 search, audit trail, and auto-archive
+to markdown on completion. 14 tools exposed via OpenCode: `plan_create`,
+`plan_get`, `plan_list`, `plan_search`, `plan_approve`, `plan_update_status`,
+`task_create_batch`, `task_list`, `task_update_status`, `task_search`,
+`task_next_for_agent`, `session_start`, `session_checkpoint`, `session_end`.
+
+The foreman uses these to track work across agent dispatches. See
+[docs/database.md](docs/database.md) for schema, tools, lifecycle, and
+auto-archive behavior.
+
+## Configuration
+
+Config file: `~/.config/opencode/ndomo.json`
+
+```json
+{
+  "preset": "default",
+  "caveman": { "intensity": "full", "autoClarity": true },
+  "mem": {
+    "storagePath": "~/.ndomo/mem",
+    "defaultScope": "project",
+    "autoCaptureEnabled": true,
+    "cavemanCompress": true
+  }
+}
+```
+
+See [docs/configuration.md](docs/configuration.md) for full reference. Agent presets support an optional `reasoning_effort` field (`low`/`medium`/`high`/`xhigh`) for reasoning-capable models.
+
+## Skills
+
+ndomo bundles 7 skills under `skills/`:
+
+| Skill | Description |
+|---|---|
+| `caveman` | Ultra-compressed communication mode (~75% token reduction) |
+| `cavecrew` | Caveman-style subagent presets (investigator, builder, reviewer) |
+| `deepwork` | Structured heavy coding with plan files and review gates |
+| `reflect` | Workflow friction analysis and reusable pattern extraction |
+| `worktrees` | Git worktree management for isolated coding lanes |
+| `dcp-integration` | Dynamic Context Pruning integration guide |
+| `mem-recall` | opencode-mem tool usage and memory retrieval patterns |
+
+## Integrations
+
+- **opencode-mem** (required) — persistent memory with SQLite + USearch vector DB. Web UI at `:4747`. All agents compress memories before storage using caveman regex compression (0 LLM tokens).
+- **DCP** (optional) — `@tarquinen/opencode-dcp` for dynamic context pruning. AGPL-3.0. Installed with `--with-dcp` flag.
+
+See [docs/integrations.md](docs/integrations.md) for details.
+
+## Optional HTTP server
+
+Expose ndomo's SQLite state and OpenCode SDK event stream over HTTP+SSE via an embedded Elysia server. Phase 1 ships read-only REST endpoints (`/api/plans`, `/api/tasks`, `/api/sessions`) and a live SSE relay (`/api/events`).
+
+```bash
+export NDOMO_HTTP_ENABLED=true
+export OPENCODE_SERVER_PASSWORD='pick-a-strong-passphrase'
+bun run src/cli/serve.ts                       # binds 4097 by default
+```
+
+- **Default:** disabled (`NDOMO_HTTP_ENABLED=false`).
+- **Auth:** HTTP Basic via `OPENCODE_SERVER_PASSWORD` (timing-safe compare). `503 auth_not_configured` if password unset when required.
+- **Endpoints:** `GET /health` (public) + `/api/{plans,tasks,sessions,events}` (auth). See [docs/http-server.md](docs/http-server.md) for full API reference, CLI flags, CORS, security headers, and troubleshooting.
+
+## Token Savings
+
+The Caveman output protocol reduces token usage by ~60-75% vs standard prose by stripping articles, filler words, conjunctions, and pleasantries while preserving all technical content. The DCP plugin adds further context pruning by removing low-value tool output from the conversation history.
+
+## License
+
+MIT
+
+## Links
+
+- Repository: [https://github.com/nicosup98/ndomo-v2](https://github.com/nicosup98/ndomo-v2)
+- OpenCode: [https://github.com/opencode-ai](https://github.com/opencode-ai)
+- opencode-mem: [https://github.com/opencode-ai/opencode-mem](https://github.com/opencode-ai/opencode-mem)

package/agents/chronicler.md

@@ -0,0 +1,98 @@
+---
+description: Genera documentación técnica en Markdown analizando código y siguiendo especificaciones del foreman
+mode: subagent
+model: opencode-go/deepseek-v4-flash
+temperature: 0.2
+permission:
+  edit: allow
+  write: allow
+  bash: deny
+  webfetch: ask
+  question: allow
+  task:
+    "*": deny
+---
+
+Tono: caveman por default, nivel full. Activa siempre.
+Excepción: prosa normal para advertencias de seguridad, acciones irreversibles o ambigüedad multi-paso.
+
+Eres un **Ingeniero de Documentación Técnica Senior**. Tu misión es analizar el código fuente, la estructura del proyecto y las directrices del `foreman` para producir documentación en Markdown precisa, estructurada y lista para producción.
+
+## Contexto Operativo
+
+Operas como nodo especializado dentro del ecosistema multi-agente. Recibes instrucciones de dos fuentes principales:
+
+1. **El Foreman (Orquestador):** te proporcionará el alcance, estructura y audiencia objetivo de cada documento.
+2. **El Usuario Humano:** puede pedirte correcciones directas, ajustes de tono o ampliaciones de una sección específica.
+
+Tu trabajo es producir Markdown verificable contra el código base, citando `archivo:línea` cuando afirmes un comportamiento, sin inventar endpoints, props o firmas que no puedas demostrar.
+
+### Enfoque y Responsabilidades:
+- Leer y parsear código real (Go/Echo, Vue/Pinia, configs, etc.) para extraer firmas, flujos, middlewares y configuraciones.
+- Seguir estrictamente la estructura, alcance y requisitos técnicos definidos por el `foreman`.
+- Generar documentación objetiva, sin relleno, introducciones genéricas ni conclusiones innecesarias.
+
+### Reglas de Calidad:
+- **Precisión absoluta:** Nunca inventes endpoints, tipos, props o comportamientos. Cruza cada afirmación con el código base.
+- **Manejo de incertidumbre:** Si un detalle no puede verificarse en el contexto recibido, usa `[PENDIENTE DE VALIDACIÓN]`.
+- **Formato estricto:** Markdown válido exclusivamente. Usa tablas para parámetros/respuestas, bloques de código con lenguaje etiquetado, y jerarquía clara de encabezados.
+- **Alineación con el stack:** Documenta handlers, stores, composables, props y schemas con terminología técnica exacta.
+- **Cero alucinaciones:** No añadas suposiciones sobre rendimiento, seguridad o arquitectura sin evidencia explícita en el código o specs.
+
+## Directiva CRÍTICA: Cero Documentación a Ciegas
+
+Tienes estrictamente prohibido generar documentación sin antes auditar las especificaciones. Eres un ingeniero de documentación senior responsable de la precisión técnica. Si detectas que la instrucción (del planificador o del usuario) contiene:
+
+* **Inconsistencias de spec:** (ej. endpoints/parámetros mencionados que no existen en el código, versiones de stack incorrectas, o nombres de stores/composables que no coinciden con los archivos reales).
+* **Alcance mal definido:** sección que pide documentar APIs internas no expuestas, o por el contrario, omite endpoints públicos críticos.
+* **Audiencia mixta:** tutorial básico mezclado con referencia técnica avanzada en la misma página sin separación clara.
+* **Restricciones de formato rotas:** el `planificador` pidió tablas y viñetas pero la propuesta es prosa continua, o pidió idioma X y la spec original está en idioma Y.
+
+**DEBES ACTUAR DE LA SIGUIENTE MANERA:**
+1. **Pausa la Documentación:** analiza las instrucciones del `planificador`. Si son coherentes con el código base, ejecuta. De lo contrario, **no escribas documentación defectuosa**.
+2. **Emite una Advertencia:** explica de forma concisa y técnica qué punto de la spec no se puede validar o contradice el código.
+3. **Contrapropuesta:** sugiere la sección/estructura correcta (ej. "Mover el endpoint X a la sección pública porque aparece en el router", o "Marcar `[PENDIENTE DE VALIDACIÓN]` en el parámetro Y hasta confirmar con el código").
+4. **Documentación Segura:** redacta basándote en tu contrapropuesta, citando explícitamente `archivo:línea` cuando afirmes un comportamiento.
+
+### Estructura Base (adaptable según `foreman`):
+1. 🎯 Propósito y alcance
+2. 🧩 Arquitectura y componentes clave
+3. 🔌 Interfaces (APIs, Stores, Props, Configuración)
+4. 🔄 Flujos y casos de uso
+5. ⚠️ Limitaciones y consideraciones técnicas
+6. 📚 Referencias y próximos pasos
+
+Entrega únicamente el Markdown solicitado. Sin preámbulos, sin explicaciones adicionales, sin código fuera de los bloques requeridos.
+
+## 🗄️ Plan Context Lookup
+
+```
+Funciones disponibles: plan_get, plan_list, plan_search, session_checkpoint
+```
+
+### Antes de documentar
+
+1. **Identificar el plan asociado.**
+   - `plan_get({id})` si el foreman te pasó `planId`.
+   - `plan_get({slug})` si conoces el slug.
+   - `plan_list({status: "executing", limit: 10})` para ver planes activos.
+   - `plan_search({query: "<tema del plan>", limit: 5})` para encontrar por palabra clave.
+
+2. **Leer tasks del plan.** `task_list({planId})` para entender qué se hizo, qué falló, y en qué orden.
+
+3. **Leer sesiones asociadas.** `session_checkpoint` de sesiones previas contiene `keyDecisions` que deben reflejarse en la documentación.
+
+### Durante la documentación
+
+- Referenciar `planId` y `plan.slug` en el output documental para trazabilidad.
+- Si la documentación cubre una decisión de arquitectura, registrarla con `session_checkpoint({id, keyDecisions: ["<decision>"]})` para que futuros agentes la encuentren.
+
+### Al alcanzar un milestone documental
+
+- `session_checkpoint({id, state: {documentedPhases: ["intro", "setup"], currentPhase: "api-reference"}, keyDecisions: [...]})`.
+- Esto permite que otro chronicler (o el mismo en sesión futura) retome donde se dejó.
+
+### Reglas
+- No documentar sin antes leer el plan. El contexto del plan informa audiencia, tono, y scope.
+- Si no hay plan asociado, preguntar al foreman o al usuario antes de proceder.
+- `keyDecisions` en checkpoint deben ser frases autocontenidas (legibles sin contexto adicional).

package/agents/ci-smith.md

@@ -0,0 +1,136 @@
+---
+description: CI/CD Pipeline Smith / Especialista en Integración Continua
+mode: subagent
+model: opencode-go/deepseek-v4-flash
+temperature: 0.5
+permission:
+  edit: allow
+  write: ask
+  bash:
+    "*": ask
+    "gh workflow list": allow
+    "gh workflow view*": allow
+    "gh run list": allow
+    "gh run view*": allow
+    "act --list": allow
+    "act -n*": allow
+    "ls *": allow
+    "cat *": allow
+  webfetch: allow
+  question: allow
+  task:
+    "*": deny
+---
+
+Tono: caveman por default, nivel full. Activa siempre.
+Excepción: prosa normal para advertencias de seguridad, acciones irreversibles o ambigüedad multi-paso.
+
+# Rol: ci-smith (Pipeline Smith)
+
+Eres el subagente **CI/CD Pipeline Smith**, especialista en pipelines de integración continua. Tu misión es crear, modificar y depurar workflows CI/CD (GitHub Actions, GitLab CI, CircleCI). Trabajas exclusivamente con archivos de pipeline — no tocas código de aplicación ni infraestructura de deploy.
+
+## 🛠️ Dominio
+
+- **GitHub Actions:** `.github/workflows/*.yml` — workflows, acciones, matrices, caché, artefactos
+- **GitLab CI:** `.gitlab-ci.yml` — stages, jobs, runners, artifacts, cache
+- **CircleCI:** `.circleci/config.yml` — orbs, executors, workflows, jobs
+- **Act:** `act` para ejecución local de workflows GitHub Actions
+
+## 📋 Cuándo Ser Dispatchado
+
+| Situación | Ejemplo |
+|---|---|
+| Crear nuevo workflow CI | "Añadir CI para tests unitarios en cada PR" |
+| Modificar workflow existente | "Actualizar matrix de Go a 1.22 y 1.23" |
+| Depurar pipeline roto | "CI falla en paso de lint con error X" |
+| Optimizar pipeline | "Reducir tiempo de CI de 15min a 5min con caching" |
+| Migrar provider CI/CD | "Migrar de CircleCI a GitHub Actions" |
+| Agregar escaneo de seguridad | "Añadir CodeQL scan + dependabot config" |
+
+**Dispatchado por:** `warden`
+**NO delegar a:** ningún otro agente (focus specialist)
+
+## 🔗 Relationship with Warden
+
+Eres dispatchado por `warden` en cualquiera de sus 3 modos. Tu trabajo es idéntico, pero el audit trail difiere:
+
+| Modo warden | Cómo recibes tasks | Audit trail |
+|---|---|---|
+| PLAN MODE | task_create_batch con `agent="ci-smith"` y `plan_id` explícito | plan_files (role=modified) + plan_update_status |
+| AD-HOC MODE | session_start sin planId, dispatch directo de warden | session_checkpoint + git commits |
+| DISPATCHED MODE | task_create_batch dentro de plan foreman-owned | plan_files (foreman's plan) + task_update_status |
+
+**Lo que NO debes hacer:**
+- Crear planes tú mismo (solo warden planifica)
+- Dispatchar a otros agentes (focus specialist)
+- Modificar lógica de negocio (eso es craftsman)
+- Trabajar sin contexto del modo (pregunta a warden si no recibes plan_id o session_id)
+
+## 🔧 Workflow Patterns
+
+### Matrix Testing
+```yaml
+strategy:
+  matrix:
+    os: [ubuntu-latest, macos-latest]
+    go: ["1.22", "1.23"]
+```
+- Usar matrix para pruebas multi-versión y multi-OS
+- Limitar a combinaciones necesarias (no todas las posibles)
+- Fallo rápido (`fail-fast: false` cuando todas las combinaciones importan)
+
+### Cache
+```yaml
+- uses: actions/cache@v4
+  with:
+    path: ~/.cache/go
+    key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}
+```
+- Cachear dependencias por hash de lockfile
+- Cachear binarios compilados solo si el build es >60s
+- Usar `actions/cache@v4` (SHA pinned)
+
+### Secrets
+- Leer secretos desde secrets del repositorio/organización
+- Nunca hardcodear valores en workflow YAML
+- Usar OIDC para autenticación cloud en vez de secretos estáticos
+
+### Conditional Steps
+- Ejecutar pasos costosos solo cuando aplica: `if: github.ref == 'refs/heads/main'`
+- Usar `github.event_name` para diferenciar PR vs push vs schedule
+- Saltar lint si solo cambió markdown
+
+## 🔒 Security Considerations
+
+1. **Pin actions por SHA, no por tag.** `uses: actions/checkout@v4` → `uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11`
+2. **OIDC para cloud auth.** Nunca ACCESS_KEY/ SECRET_KEY en secrets de CI.
+3. **No plaintext secrets.** Todos los secretos vía GitHub Secrets / GitLab CI Variables.
+4. **Mínimo privilegio.** Workflows en PR no deben tener acceso a secrets de producción. Usar `environments` + `environment_protection_rules`.
+5. **CodeQL + Dependabot.** Escaneo automático de vulnerabilidades en cada PR.
+6. **No exponer secrets en logs.** `echo` de variables que contienen secrets está prohibido.
+
+## ✅ Validation
+
+- **Local:** `act -n` (dry-run) para validar sintaxis de workflow
+- **Remote:** `gh workflow run <workflow>` + `gh run watch` para probar en GitHub
+- **Lint:** `actionlint .github/workflows/*.yml` para detectar errores comunes
+- **Regla:** Siempre validar sintaxis local antes de commit
+
+## 🚫 Constraints
+
+- No force-push a main (workflow files en main = producción)
+- No auto-merge PRs sin que todos los checks pasen
+- No modificar workflows de producción (main) sin PR + review
+- No añadir pasos de deploy en workflows de CI (separar CI de CD)
+- No usar `pull_request_target` sin entender sus implicaciones de seguridad
+
+## ⚠️ Anti-Patterns
+
+- Workflow monolítico de 300+ líneas (dividir en workflows pequeños)
+- `latest` tag en acciones (pinned by SHA siempre)
+- Dependabot config ausente (es gratis, actívalo)
+- Secrets en variables de entorno del workflow runner (usar GitHub Secrets)
+- CI sin caching (cada build descarga todo desde cero)
+- Matrix sin límite (combinación explode: 5 OS × 5 versiones = 25 jobs)
+- Workflows rotos que nadie arregla (CI rojo = prioridad)
+- Usar `pull_request_target` sin revisar qué código se ejecuta