# Feature: Flexible Builder — modo ad-hoc paralelo al Foreman

**Slug:** `feature-flexible-builder`
**Status:** Draft (v1 — archivada)
**Plan ID:** `[PENDIENTE DE ASIGNACIÓN]`
**Created:** 2026-06-19
**Archived:** 2026-06-19 (spec v2 reemplaza este documento)

---

## 1. Resumen ejecutivo

Agregar un nuevo **primary agent `builder`** al ecosistema ndomo, paralelo al `foreman`, que implementa código sin la rigidez del orquestador. El user alterna manualmente entre foreman (planificación multi-step) y builder (implementación directa, TDD, commits). Builder usa `plan_db` **solo si la tarea es multi-archivo o necesita tracking**; si es trivial, ejecuta y reporta sin tocar la DB. El patrón replica exactamente el modo ad-hoc del proyecto referencia `nicosup98/ndomo` (opencode-core-slim), donde `default_agent: build` + `builder` primary + `qagent` ad-hoc conviven sin que el user deba pasar por un orquestador para trabajo simple.

---

## 2. Contexto y motivación

### 2.1 Estado actual: rigidez del foreman

El `foreman` (`agents/foreman.md`) es un orquestador primario con un flujo de 10 pasos obligatorios:

| # | Paso | ¿Salteable? |
|---|------|------------|
| 1 | Aclaración | No |
| 2 | Memory Search | No |
| 3 | Routing | No |
| 4 | Plan Atómico | No |
| 5 | Brief de Delegación | No |
| 6 | Trivium en Vivo | Parcial (≤5 líneas) |
| 7 | Reconciliación | No |
| 8 | Validación | No |
| 9 | Reporte Final | No |

**Evidencia:** `agents/foreman.md:162-200` define los 10 pasos secuenciales sin excepción.

### 2.2 Grietas específicas identificadas

| Grieta | Ubicación | Impacto |
|--------|-----------|---------|
| Trivium solo self-edit ≤5 líneas, 1 archivo, 0 nuevos exports | `agents/foreman.md:29-34` | El foreman no puede corregir ni un typo sin delegar → sobrecarga de `task` para cambios triviales |
| No hay modo ad-hoc; toda tarea requiere `plan_create` + `task_create_batch` | `agents/foreman.md:238` ("Antes de despachar subagentes, crear plan + tasks en DB") | tareas de 1 archivo requieren ciclo completo de plan_db |
| `session_start` colisiona con `ctx.sessionID` | `docs/bugs/plan-create-orphan-fk.md:60-70` | `plan_approve` / `plan_update_status` fallan en planes creados sin `session_start` explícito |
| `task_update_status` trunca `result`/`error` a 16KB | `src/db/tasks.ts:109-121` | Outputs grandes se pierden sin advertencia |
| Foreman monopoliza el rol de "único primary"; los 14 smiths son `subagent` con `task: deny` | `agents/foreman.md:28` y `agents/*.md` (`mode: subagent`) | El user no puede delegar directamente a un smith sin pasar por el foreman. El trivium es el único escape. |
| Routing estático en scheduler | `src/orchestrator/scheduler.ts:41-47` stack de 5 lenguajes | No hay detección dinámica de stack; el foreman debe adivinar o preguntar |
| `opencode.json` ausente en el repo | `glob("*opencode.json*")` → 0 resultados | Config global no versionada; no se puede definir `default_agent` ni modelos por proyecto |

---

## 3. Análisis comparativo con nicosup98/ndomo

### 3.1 Tabla side-by-side

| Aspecto | ndomo-v2 actual (foreman rígido) | nicosup98/ndomo (opencode-core-slim) |
|---------|----------------------------------|--------------------------------------|
| Default agent | foreman (primary, orquestador) | `build` (built-in, no overridden) |
| Modo trivial | Trivium ≤5 líneas, plan_db obligatorio | `build` single-turn, 0 coordination |
| Modo plan formal | foreman → `plan_create` → `task` → smiths | architect → `plan_db.add` → user switch → builder/scout/qagent |
| Modo ad-hoc | No existe | qagent "audit ad-hoc" deriva scope del query |
| Coordinación entre primaries | `task` desde foreman | `plan_db` async + user switch en TUI |
| Skill loading | Hardcodeado en cada smith | Dinámico: researcher detecta stack, carga max 5 |
| Audit trail | Solo `created_at`/`updated_at` | `original_plan_data` NUNCA se sobrescribe |
| Plan↔file association | No existe | `plan_files` join table |
| Tono global | Caveman en foreman + algunos smiths | Caveman en TODOS los 6 agents |
| `plan_delete` safety | No existe | Rechaza si `status='pending'` |
| Plan ≤5 steps | No hay regla | Regla en architect.md + `parent_id` para sub-plans |

**Evidencia del reporte:** `/tmp/opencode/ndomo-report.md:419-427` (tres modos de trabajo), `433-445` (tabla comparativa), `453-514` (puntos portables).

### 3.2 Por qué el patrón async + user switch es más liviano

En el modelo actual, el foreman:
1. Crea plan en DB (2 writes)
2. Crea tasks batch (N writes)
3. Llama `task` para cada smith (N LLM invocations)
4. Espera resultados (N context switches)
5. Reconoce resultados (N reads)

El modelo referencia:
1. architect escribe plan a SQLite (1 write)
2. User cambia agent en TUI (0 LLM tokens)
3. builder/scout/qagent lee plan y ejecuta (1 read + N writes)
4. User cambia de vuelta a architect si necesita replanificar

**Diferencia clave:** el modelo referencia gasta ~60% menos tokens en coordinación porque el "router" (architect) solo escribe a una DB persistente, no invoca LLMs secundarios. La coordinación entre primaries es **asíncrona vía SQLite**, no síncrona vía `task`.

---

## 4. Decisiones de diseño

### D1. Nuevo primary `builder` paralelo a `foreman` (Opción A del user)

**Decisión:** Crear `agents/builder.md` con `mode: primary`. El user alterna manualmente en TUI.

**Justificación:** Es el patrón probado del referencia (commit `167dc03`), donde `architect` NO usa `task` para invocar `builder`. Separar roles evita que el orquestador monopolice tokens y permite al user elegir el camino directo.

**Trade-offs:**
- (+) Zero cambios al foreman existente; conviven ambos primaries
- (+) El user retiene control del "threading" (no hay delegación automática)
- (-) El user debe saber cuándo usar builder vs foreman (curva de aprendizaje)
- (-) Dos primaries = dos configuraciones de modelo/temperatura

### D2. Builder carga skills de smiths según stack detectado

**Decisión:** Builder usa el mismo conjunto de skills que los smiths existentes, cargadas dinámicamente según stack detectado (max 5 skills por sesión).

**Justificación:** No duplicar skills. Reutilizar `vue-best-practices`, `golang-pro`, `rust-best-practices`, `typescript-expert`, etc., que ya existen.

**Trade-offs:**
- (+) Reutilización inmediata de 35+ skills existentes
- (+) Sin crear skills nuevas
- (-) Requiere lógica de detección de stack (a cargo del researcher subagent)

### D3. Audit trail inmutable con `original_plan_data`

**Decisión:** Agregar columna `original_plan_data TEXT` a `plans` y `plan_tasks`. En `plan_create` copiar `plan_data` → `original_plan_data`. NUNCA se sobrescribe.

**Justificación:** Permite responder "qué se planeó vs qué se hizo" sin re-parsear logs. Patrón probado del referencia (`/tmp/opencode/ndomo-report.md:465-467`).

**Trade-offs:**
- (+) Audit trail automático, zero esfuerzo del LLM
- (-) DB crece 2x por fila de plan (mitigación: archivar planes viejos)

### D4. Builder usa `plan_db` opcionalmente

**Decisión:** Builder NO crea `plan_create` para tareas triviales (1 archivo, ≤50 líneas de diff). Crea plan solo si multi-archivo o necesita tracking cross-session.

**Justificación:** Elimina el overhead del plan_db para el caso más común (fixes rápidos, single-file features). Es la misma lógica del referencia donde `build` (default) no toca `plan_db` y `builder` (primary) lo usa condicionalmente.

**Trade-offs:**
- (+) Tareas triviales se ejecutan en 1 turno, 0 writes a DB
- (-) Tareas sin plan_db no tienen trazabilidad (mitigación: builder reporta al user qué hizo vía salida directa)
- (-) Riesgo de que el user abuse builder para tareas grandes sin plan

---

## 5. Diseño del nuevo primary `builder`

### 5.1 Frontmatter YAML propuesto

```yaml
---
description: Implementador disciplinado / Fast Implementation Specialist (modo ad-hoc o planificado)
mode: primary
model: opencode-go/deepseek-v4-flash   # mismo modelo que smith genérico
temperature: 0.1
permission:
  edit: allow
  write: allow
  bash:
    "*": ask
    "git status*": allow
    "git log*": allow
    "git diff*": allow
    "git add *": allow
    "git commit*": allow
    "git checkout*": ask
    "git push*": ask
    "ls *": allow
    "cat *": allow
    "mkdir *": allow
    "mv *": allow
    "cp *": allow
    "bun *": allow
    "npm *": allow
    "rm *": ask
  webfetch: deny
  question: allow
  task:
    "scout": allow
    "scribe": allow
    "smith": allow
    "go-smith": allow
    "js-smith": allow
    "vue-smith": allow
    "python-smith": allow
    "rust-smith": allow
    "zig-smith": allow
  plan_db: allow      # opcional: tool plan_create/task_create_batch
---
```

**Diferencias clave con el foreman:**
- `mode: primary` (NO subagent)
- `task` permitido SOLO a subagents existentes (scout, scribe, smiths)
- `task` NO permitido a foreman, chronicler, inspector, painter, guild, sage (son primaries o roles no delegables)
- Permisos `edit: allow`, `bash: ask` (mismo que smiths, a diferencia del foreman que delega)
- `plan_db` tools disponibles pero no obligatorias

### 5.2 Prompt completo sugerido (esqueleto con TODOs)

```markdown
# Rol: Builder (Implementador Disciplinado)

Eres un **primary agent** paralelo al foreman. Tu misión es implementar código
directamente — bugs fixes, features pequeñas, refactors acotados — sin pasar por
el ciclo de planificación del orquestador. **Eres la opción "rápida"** para cuando
la tarea no amerita un plan completo.

## Tono

- Caveman nivel `full` SIEMPRE. Cero saludos, cero justificaciones, viñetas densas.
- [TODO: cargar skill `caveman` al inicio]

## Modo de trabajo (3 estados)

### Estado 1: Trivial (sin plan_db)
**Cuándo:** 1 archivo, ≤50 líneas de diff, sin dependencias externas.
**Flujo:**
1. Lee archivo objetivo
2. Implementa cambio
3. Corre `bun run typecheck` / tests / lint del scope
4. Commit atómico (conventional commits, ≤72 chars)
5. Reporta al user: archivo, línea, cambio, verificación.
**NO crea plan_create. NO toca task_db.**

### Estado 2: Ad-hoc multi-archivo (con plan_db opcional)
**Cuándo:** 2-5 archivos, cambios que cruzan stacks, o necesita tracking.
**Flujo:**
1. Si no hay plan previo: `plan_create` con slug, overview, approach breve.
2. `task_create_batch` con steps numerados.
3. Para cada step: `task_update_status("running")` → implementar → `task_update_status("done")`.
4. Al final: `plan_update_status("completed")`.
**Obligatorio si la tarea toca más de 1 stack o requiere session tracking.**

### Estado 3: Plan formal (lee plan_db existente)
**Cuándo:** El foreman ya creó un plan y tasks; builder es invocado para implementar.
**Flujo:**
1. `plan_get({id})` o `task_next_for_agent({agent: "builder"})` para encontrar tarea.
2. Leer plan_data y entender el contexto.
3. Implementar TDD: test first → code → refactor.
4. `task_update_status("done")` con reporte.
5. Si todas las tasks hechas: `plan_update_status("completed")`.

### Regla de selección de estado
```
¿Tarea bien definida, 1 archivo, <50 líneas?
  → Estado 1: trivial (no plan_db)
¿Tarea multi-archivo o cross-stack?
  → Estado 2: ad-hoc con plan_db
¿Hay plan/task existente asignado a "builder"?
  → Estado 3: plan formal
¿Tarea >5 archivos o requiere diseño de arquitectura?
  → [FUERA DE MI DOMINIO] → cambiar a foreman
```

## Skill loading dinámico (4 pasos)

1. [TODO: al recibir tarea que involucra código → delegar a `scout`
   con `task` para detectar stack]
   - Prompt fijo: "Analiza los archivos afectados y detecta el stack.
     Busca package.json → vue/react/etc, go.mod → Go, Cargo.toml → Rust,
     requirements.txt → Python, build.zig → Zig. Devuelve tabla de markers encontrados."
2. [TODO: recibir output estructurado — Stack / Markers / Skills recomendadas]
3. [TODO: cargar skills con tool `skill` — max 5 por sesión]
4. [TODO: reglas de borde — si toca auth/security → cargar `security-review`;
    si ya cargaste skills en turno anterior → NO recargar]

### Tabla marker→skill (del referencia, `/tmp/opencode/ndomo-report.md:337-344`)

| Marker | Stack | Skills |
|--------|-------|--------|
| `package.json` + `vue` en dependencies | Vue/Nuxt | `vue`, `vue-best-practices`, `pinia`, `vue-testing-best-practices`, `vite` |
| `package.json` + `react` | React/Next | `typescript-expert`, `modern-javascript-patterns` |
| `go.mod` + `go` en toolchain | Go | `golang-pro`, `golang-security`, `go-testing` |
| `Cargo.toml` | Rust | `rust-best-practices`, `rust-async-patterns`, `rust-testing` |
| `package.json` JS/TS genérico | JS/TS | `typescript-expert`, `modern-javascript-patterns`, `javascript-testing-patterns` |
| `requirements.txt` o `setup.py` | Python | [TODO: skill python específicas si existen] |
| `build.zig` | Zig | `zig-0.16` |
| Sin markers | generic | `caveman` + `ripgrep` solo |

## TDD workflow (obligatorio para código)

1. Test first: escribir test que falla cubriendo el cambio esperado
2. Code: implementar lo mínimo para pasar el test
3. Refactor: limpiar sin romper tests
4. Correr suite completa del scope
5. Commit atómico: `git add -A && git commit -m "tipo(scope): mensaje ≤72 chars"`

## Lo que NO puedes hacer

- ❌ Planificar tareas multi-step que involucren otros primaries (scout, painter, qagent)
- ❌ Invocar a `foreman` vía `task` — eso confunde roles
- ❌ Editar prompts de otros agents (`agents/*.md`)
- ❌ Editar tools MCP (`src/plugin.ts`, `src/db/*`)
- ❌ Crear planes con >5 steps top-level
- ❌ Usar `plan_approve` ni `plan_update_status` sin haber creado el plan
- ❌ Modificar archivos sin leerlos primero
- ✅ Sub-delegar a subagents existentes: `scout` (exploración), `smith`/`*-smith` (implementación especializada si cambia de stack)

## Output format

```
cambios:
  - path/file.ts:line — descripción — verified: OK

validación:
  - bun run typecheck — passed
  - bun test — 42/42 passed

plan:
  - plan_id: (si se creó)
  - tasks: 3 creadas, 3 completadas
  - estado: completed | ad-hoc (no plan_db)

notas:
  - [TODO: si algo queda pendiente]
```

## Reglas estrictas

1. Lee antes de editar. Siempre.
2. Verifica post-edit. Cada `edit` → `read` para confirmar.
3. Sin webfetch. Sin investigación externa.
4. Si la tarea excede tu scope → reporta `[FUERA DE MI DOMINIO]` + qué agente se necesita.
5. Caveman siempre. Salvo para advertencias de seguridad.
6. Commit atómico obligatorio después de cada tarea completada.
7. Si el proyecto no tiene tests → crear setup mínimo antes de implementar.
```

### 5.3 Skills loading: tabla marker → skill

Basado en el frontmatter de los smiths actuales, las skills existentes son:

| Agente existente | Skills cargadas en frontmatter/prompt |
|------------------|--------------------------------------|
| `smith` | `caveman`, `cavecrew` |
| `go-smith` | `golang-patterns`, `golang-testing`, `golang-security`, `api-security-best-practices` |
| `vue-smith` | `vue-best-practices`, `frontend-design` |
| `js-smith` | `modern-javascript-patterns`, `javascript-testing-patterns`, `api-security-best-practices` |
| `rust-smith` | [TODO: verificar — hereda de go-smith template] |
| `python-smith` | [TODO: verificar — hereda de go-smith template] |
| `zig-smith` | `zig-0.16` |
| `scout` | `caveman`, `ripgrep` |
| `inspector` | [TODO: verificar] |

**Evidencia en código:**
- `agents/smith.md:45-47` → `caveman`, `cavecrew`
- `agents/go-smith.md:48-52` → `golang-patterns`, `golang-testing`, `golang-security`, `api-security-best-practices`
- `agents/vue-smith.md:48-50` → `vue-best-practices`, `frontend-design`
- `agents/scout.md:44-46` → `caveman`, `ripgrep`

### 5.4 Integración con foreman

| Situación | Quién actúa | Por qué |
|-----------|-------------|---------|
| Bug fix de 1 archivo | Builder (ad-hoc) | Sin overhead de plan_db |
| Feature multi-archivo (3-5 files) | Builder (con plan_db) | Builder crea plan y tasks, ejecuta, completa |
| Feature >5 archivos / arquitectura | Foreman | Requiere diseño, routing a múltiples agents |
| Tarea cross-stack (Go + Vue) | Foreman | Foreman divide, delega a go-smith + vue-smith |
| El user no sabe qué necesita | Foreman | Foreman aclara antes de actuar |
| Auditoría de PR existente | Builder | No necesita plan; lee diff, reporta findings |
| Exploración de código | Scout (vía foreman o directo) | Builder no explora |

**Regla de convivencia:** builder y foreman comparten `plan_db`. Si builder crea un plan, foreman lo ve vía `plan_list`. Si foreman crea un plan con tareas para `builder`, builder las ve vía `task_next_for_agent`. No hay conflicto porque cada uno escribe/lee de la misma DB.

---

## 6. Cambios al sistema

### 6.1 Migración v6: `original_plan_data` en `plans` y `plan_tasks`

| Campo | Tabla | Tipo | Comportamiento |
|-------|-------|------|----------------|
| `original_plan_data` | `plans` | `TEXT` | En `plan_create`: copiar `plan_data` + `overview` + `approach` como JSON inmutable |
| `original_plan_data` | `plan_tasks` | `TEXT` | En `task_create_batch`: copiar `description` + `files` + `dependencies` como JSON inmutable |

**Reglas:**
- `plan_create` setea `original_plan_data` al mismo valor que `plan_data` en el INSERT
- `plan_approve` NO toca `original_plan_data`
- `plan_update_status` NO toca `original_plan_data`
- `archivePlan` lo lee y lo incluye en el markdown archive pero NO lo modifica
- `task_create_batch` setea `original_plan_data` al serializar `{description, files, dependencies}`

**Archivos afectados:**
- `src/db/schema.ts` — agregar columna vía `addColumnIfMissing` en migrations.ts (similar a v5 pattern)
- `src/db/types.ts` — agregar `originalPlanData: string | null` a Plan y PlanTask
- `src/db/plan-create.ts` — en `planCreateExecutor`, serializar args como `original_plan_data`
- `src/db/tasks.ts` — en `createTasksBatch`, serializar cada task input como `original_plan_data`
- `src/db/plan-archive.ts` — leer y exportar `original_plan_data` en el markdown archive
- `src/db/plans.ts` — en `createPlan`, pasar `original_plan_data`; en `updatePlanStatus` y `approvePlan`, verificar que NO se sobrescribe
- Nuevo: `src/db/plan-archive.test.ts` — test que verifica que `original_plan_data` es write-once

### 6.2 Migración v7: `plan_files` join table

```sql
CREATE TABLE IF NOT EXISTS plan_files (
  plan_id TEXT NOT NULL REFERENCES plans(id) ON DELETE CASCADE,
  file_path TEXT NOT NULL,
  role TEXT,                              -- 'input' | 'output' | 'modified'
  PRIMARY KEY (plan_id, file_path)
);
CREATE INDEX IF NOT EXISTS idx_plan_files_path ON plan_files(file_path);
```

**Comportamiento:**
- `plan_create` acepta `files: string[]` opcional → inserta en `plan_files` con role `'input'`
- `task_create_batch` acepta `files: string[]` por task → inserta en `plan_files` con role `'modified'`
- `plan_get` retorna `files[]` via subquery JOIN
- `plan_search` acepta `file_path` filter opcional
- `plan_delete` CASCADE borra `plan_files`
- `archivePlan` incluye files en el markdown archive

**Archivos afectados:**
- `src/db/schema.ts` — agregar SCHEMA_V7_SQL con CREATE TABLE
- `src/db/types.ts` — agregar `files: string[]` con role a Plan y PlanTask (ya existe `files` en PlanTask, extender Plan)
- `src/db/plan-create.ts` — agregar `files?: string[]` a `PlanCreateArgs`, insertar en plan_files
- `src/db/tasks.ts` — en `createTasksBatch`, si `files` no está vacío, insertar en plan_files
- `src/db/plans.ts` — en `getPlan`, hacer JOIN con plan_files para `files[]`
- `src/db/plan-archive.ts` — incluir files en el markdown

### 6.3 `plan_delete` safety

**Opción recomendada:** Nuevo tool `plan_delete` en `src/plugin.ts` + función en `src/db/plans.ts`.

**Comportamiento:**
- Recibe `{id: string, confirm: boolean}`
- Rechaza si `confirm !== true` con error `"ndomo: plan_delete requires confirm: true"`
- Rechaza si `plan.status === 'draft'` con error `"ndomo: cannot delete a draft plan — use abandonPlan or approve first"`
- Rechaza si `task.status === 'pending' | 'running'` con error `"ndomo: plan has active tasks — resolve them first"`
- Si pasa todas las validaciones: CASCADE delete (plan_tasks, plan_tags, plan_files, sessions con ON DELETE SET NULL)

**Archivos afectados:**
- `src/db/plans.ts` — nueva función `deletePlan(db, id)` con validaciones
- `src/db/plans.test.ts` — nuevo test: delete success, delete reject pending, delete reject without confirm
- `src/plugin.ts` — registrar tool `plan_delete`

### 6.4 Plan ≤5 steps top-level

**Dos capas de enforcement:**
1. **Prompt del foreman** (`agents/foreman.md`): agregar regla "Planifica en pasos atómicos. Máximo 5 steps top-level. Si necesitas más, usa `parent_id` para sub-planes o pregunta al usuario."
2. **Validación en `task_create_batch`** (`src/db/tasks.ts`): si `tasks.length > 5`, emitir warning al log (no bloquear, porque el usuario podría tener razón).

### 6.5 Caveman en TODOS los agents

Agregar `caveman` skill al frontmatter de los 14 subagents actuales:

```yaml
# Agregar a la sección de skills obligatorias de cada agent:
skills:
  - caveman
```

**Agentes afectados:** chronicler, go-smith, guild, inspector, js-smith, painter, python-smith, rust-smith, sage, scout, scribe, smith, vue-smith, zig-smith.

**Diff:** en cada `agents/*.md`, agregar 2-3 líneas al inicio del prompt: *"Tono: caveman por default, nivel `full`. Activa siempre."*

### 6.6 No cambios requeridos

| Componente | Estado | Razón |
|------------|--------|-------|
| `opencode.json` / `~/.config/opencode/opencode.json` | Sin cambios | Foreman sigue siendo `default_agent`. Builder se activa manualmente en TUI. |
| `agents/foreman.md` | Sin cambios estructurales | Foreman sigue operando igual. Solo recibirá la regla ≤5 steps y la nota de que builder existe. |
| `src/orchestrator/scheduler.ts` | Sin cambios | Builder no usa scheduler. Decide su ruta en el prompt. |
| `src/db/sessions.ts` | Sin cambios | Bug del `ctx.sessionID` queda como tech debt. |
| `docs/bugs/plan-create-orphan-fk.md` | Sin cambios | Bug documentado, no resuelto en este spec. |

---

## 7. Acceptance criteria

### 7.1 Builder existe y es primary

- [ ] `agents/builder.md` existe con frontmatter: `mode: primary`, `task: allow` solo a subagents, `plan_db: allow`
- [ ] `agents/builder.md` tiene prompt completo con 3 estados de trabajo (trivial, ad-hoc plan_db, formal plan_db)
- [ ] User puede cambiar a builder en TUI sin pasar por foreman

### 7.2 Stack detection + skill loading

- [ ] Builder puede delegar a `scout` via `task` para detección de stack
- [ ] Builder carga max 5 skills por sesión según stack detectado
- [ ] Tabla marker→skill existe en el prompt y cubre: Go, Vue, JS/TS, Rust, Python, Zig, generic

### 7.3 plan_db opcional

- [ ] Builder ejecuta tarea trivial (1 archivo, ≤50 líneas) sin crear `plan_create`
- [ ] Builder crea `plan_create` + `task_create_batch` para tarea multi-archivo
- [ ] Builder reporta resultado al user en formato caveman en ambos modos

### 7.4 Builder NO invoca primaries

- [ ] `task` a `foreman` produce error o es ignorado por builder
- [ ] `task` a `chronicler`/`inspector`/`painter`/`sage`/`guild` produce error (son primaries o roles específicos)
- [ ] `task` a `scout`, `scribe`, `smith`, `*-smith` funciona correctamente

### 7.5 Migraciones DB

- [ ] Migración v6 aplica limpio a DB existente con datos reales
- [ ] Migración v7 aplica limpio a DB existente con datos reales
- [ ] `original_plan_data` es write-once: `plan_create` lo setea, `plan_approve`/`plan_update_status` no lo tocan
- [ ] Test unitario verifica audit trail inmutable
- [ ] `plan_files` inserta correctamente en `plan_create` con `files[]`
- [ ] `plan_files` inserta correctamente en `task_create_batch`
- [ ] CASCADE delete funciona en `plan_delete`

### 7.6 plan_delete safety

- [ ] `plan_delete` rechaza sin `confirm: true`
- [ ] `plan_delete` rechaza si `status='draft'`
- [ ] `plan_delete` rechaza si hay tasks `pending`/`running`
- [ ] `plan_delete` ejecuta CASCADE si pasa validaciones

### 7.7 Plan ≤5 steps

- [ ] `agents/foreman.md` contiene regla de ≤5 steps top-level
- [ ] `task_create_batch` emite warning si >5 tasks (no bloquea)

### 7.8 Caveman global

- [ ] Los 14 subagents existentes tienen `caveman` en frontmatter o prompt
- [ ] `agents/builder.md` tiene caveman activo

### 7.9 Tests

- [ ] Test cubre flujo trivial de builder (no crea plan_db, reporta directo)
- [ ] Test cubre flujo multi-archivo de builder (crea plan_db, tasks, completa)
- [ ] Test cubre `plan_delete` safety (3 sub-casos)
- [ ] Test cubre `original_plan_data` write-once
- [ ] Test cubre `plan_files` insert + query + CASCADE

### 7.10 Docs

- [ ] `docs/agents.md` describe builder (rol, cuándo usar, diferencia con foreman)
- [ ] `docs/workflows.md` tiene árbol de decisión actualizado (ver sección 10.2 abajo)

---

## 8. Plan de implementación por fases

### Fase 1: Migraciones DB + tests (1-2h)

**Qué:**
1. Agregar `original_plan_data TEXT` a `plans` y `plan_tasks` (migration v6)
2. Crear `plan_files` join table (migration v7)
3. Implementar `deletePlan` en `src/db/plans.ts` con safety checks
4. Tests unitarios: `plan-archive.test.ts`, `plans.test.ts` (delete), `plan-create.test.ts` (audit trail)

**Archivos tocados:**
- `src/db/schema.ts` (SCHEMA_V6_SQL, SCHEMA_V7_SQL, MIGRATIONS array)
- `src/db/migrations.ts` (addColumnIfMissing para v6)
- `src/db/types.ts` (interfaces Plan, PlanTask)
- `src/db/plans.ts` (createPlan, getPlan, new deletePlan)
- `src/db/tasks.ts` (createTasksBatch)
- `src/db/plan-create.ts` (PlanCreateArgs, planCreateExecutor)
- `src/db/plan-archive.ts` (serializePlanToMarkdown)
- `src/db/plans.test.ts` (nuevos tests)
- `src/db/plan-create.test.ts` (nuevo test audit trail)

### Fase 2: agents/builder.md + skill loading (2-3h)

**Qué:**
1. Crear `agents/builder.md` con frontmatter y prompt completo (esqueleto de la sección 5.2)
2. Implementar lógica de stack detection delegando a `scout` (task prompt fijo)
3. Implementar skill loading dinámico con max 5
4. Probar manualmente: abrir builder en TUI, dar tarea trivial, verificar que no crea plan_db

**Archivos tocados:**
- `agents/builder.md` (nuevo)
- `agents/scout.md` (agregar instrucción de detección de stack si no existe — opcional, puede resolverse en el task prompt del builder)
- Ningún archivo de código nuevo (skill loading usa tool `skill` existente)

### Fase 3: Integración con foreman + caveman global (1-2h)

**Qué:**
1. Agregar regla ≤5 steps al foreman (prompt + warning en task_create_batch)
2. Agregar caveman a los 14 subagents (diff mecánico)
3. Registrar `plan_delete` como tool MCP en `src/plugin.ts`
4. Verificar que builder y foreman no colisionan en plan_db

**Archivos tocados:**
- `agents/foreman.md` (regla ≤5 steps, nota sobre builder)
- `agents/*.md` (14 archivos, agregar caveman)
- `src/plugin.ts` (registrar plan_delete)
- `src/db/tasks.ts` (warning si >5 tasks)

### Fase 4: Docs + smoke tests (1h)

**Qué:**
1. Actualizar `docs/agents.md` con builder
2. Actualizar `docs/workflows.md` con árbol de decisión actualizado
3. Smoke test end-to-end: cambiar a builder → tarea trivial → verificar output sin plan_db
4. Smoke test: builder → tarea multi-archivo → verificar plan creado

**Archivos tocados:**
- `docs/agents.md` (nueva sección builder)
- `docs/workflows.md` (nuevo diagrama de decisión)

---

## 9. Riesgos y trade-offs

### R1. Abuso del builder para tareas grandes

**Riesgo:** Builder tiene `edit: allow` + `task: allow`. El user podría usarlo para features complejas sin plan_db, saltándose el foreman incluso cuando debería planificar.

**Mitigación (3 capas):**
1. **Prompt:** Builder tiene regla explícita ">5 archivos → fuera de mi dominio"
2. **Modelo:** builder usa temperatura 0.1, más predecible, menos propenso a auto-expandir scope
3. **Documentación:** `docs/workflows.md` explica el árbol de decisión: foreman para >5 archivos o diseño de arquitectura

**Severidad:** baja (el user siempre puede abusar; el sistema es una herramienta, no un guardián).

### R2. Crecimiento de DB con `original_plan_data`

**Riesgo:** La columna duplica `plan_data` (2x tamaño por fila). En proyectos con cientos de planes, puede sumar MB.

**Mitigación:**
1. `original_plan_data` se archiva a markdown cuando el plan se completa (auto-archive)
2. Archivar borra el plan de la DB activa (archived_at set)
3. Si el tamaño es problema, agregar cleanup de plans archived >30 días

**Severidad:** baja-muy baja (DB SQLite, planes son texto, 1000 planes ≈ 2-5MB extra).

### R3. Caveman en 14 agents = 14 lugares donde mantener consistencia

**Riesgo:** El tono caveman se vuelve inconsistente entre agents si se editan individualmente.

**Mitigación:**
1. Documentar el snippet exacto en `skills/caveman/SKILL.md` y referenciarlo en cada agent
2. El snippet es: `"Tono: caveman por default, nivel {{level}}. Activa siempre. Excepción: prosa normal para advertencias de seguridad, acciones irreversibles o ambigüedad multi-paso."`
3. Si se cambia el formato, buscar/replace en 14 archivos

**Severidad:** baja (diff mecánico, 2 líneas por archivo).

### R4. Skill loading dinámico sin LLM en la detección

**Riesgo:** La detección de stack depende del researcher subagent (vía `task`), que podría alucinar markers o elegir skills incorrectas.

**Mitigación:**
1. El prompt de detección es fijo con tabla marker→skill (no generativa)
2. Researcher solo reporta lo que encuentra en archivos reales (glob/grep)
3. Builder carga skills secuencialmente y puede fallar graceful si la skill no existe

**Severidad:** media-baja (el researcher puede fallar, pero builder puede cargar skill genérica como fallback).

### R5. Bug `ctx.sessionID` no arreglado

**Riesgo:** Builder usa `plan_create` en modo ad-hoc. Si el bug del FK de session persiste, los planes que cree builder también quedarán huérfanos en `draft`.

**Mitigación:**
1. El fix automático de `ensureSession` en `planCreateExecutor` (`src/db/plan-create.ts:39-41`) ya existe y resuelve el caso de `plan_create`
2. Builder solo necesita `plan_create` + `plan_update_status("completed")` — no necesita `plan_approve`
3. Si builder usa `plan_update_status` directamente, pasa por el mismo `ensureSession` scoped en `updatePlanStatus` (solo para `executing`/`approved`)
4. Para `completed`/`failed`/`abandoned`, la validación FK está deshabilitada (ver `plans.ts:122`)

**Conclusión:** el bug actual no afecta al builder. Solo afecta si builder intentara `plan_approve`, que no está en su flujo.

---

## 10. Referencias cruzadas

### 10.1 Archivos clave

| Archivo | Líneas relevantes | Notas |
|---------|-------------------|-------|
| `agents/foreman.md` | 162-200 (10 pasos), 29-34 (trivium ≤5 líneas), 238 (plan_db obligatorio) | Fuente de la rigidez |
| `src/db/schema.ts` | 17-33 (plans table), 38-54 (plan_tasks), 60-73 (sessions), 466-497 (MIGRATIONS) | Schema actual para migrar |
| `src/db/plans.ts` | 14-41 (createPlan), 113-147 (updatePlanStatus), 158-185 (approvePlan) | Puntos de inserción original_plan_data |
| `src/db/tasks.ts` | 13-80 (createTasksBatch), 109-121 (truncation 16KB) | Puntos de inserción original_plan_data + warning ≤5 tasks |
| `src/db/plan-create.ts` | 15-24 (PlanCreateArgs), 32-62 (planCreateExecutor) | Ya tiene ensureSession (Fix #1) |
| `src/db/plan-archive.ts` | 43-121 (serializePlanToMarkdown), 169-257 (archivePlan) | Archivo a modificar para incluir original_plan_data |
| `src/db/migrations.ts` | 16-21 (addColumnIfMissing), 23-57 (runMigrations) | Patrón para migraciones v6/v7 |
| `src/db/types.ts` | 41-64 (Plan), 66-91 (PlanTask), 119-140 (PlanRow), 142-166 (TaskRow) | Tipos a extender |
| `src/orchestrator/scheduler.ts` | 65-186 (routeTask), 41-47 (STACK_AGENTS) | Routing estático; builder no lo usa |
| `docs/bugs/plan-create-orphan-fk.md` | 60-70 (ctx.sessionID collision), 88-103 (fix recommended) | Bug conocido, no arreglado en este spec |

### 10.2 Documentación del referencia

| Recurso | Contenido clave |
|---------|-----------------|
| `/tmp/opencode/ndomo-report.md` | Análisis completo del proyecto referencia (563 líneas) |
| Sección 3.2 (prompts) | Prompts de architect/builder/qagent/researcher/tester |
| Sección 4.1 (plan_db) | original_plan_data, plan_files, delete safety |
| Sección 7.1 (árbol de decisión) | Flujo user → build/architect/builder/qagent |
| Sección 7.2 (tres modos) | Single-turn, plan formal, ad-hoc |
| Sección 9 (puntos portables) | 16 ideas priorizadas, de las cuales se portan: 9.1, 9.2, 9.3, 9.4, 9.5, 9.6, 9.7, 9.14, 9.15 |
| `https://github.com/nicosup98/ndomo` | Repo referencia (opencode-core-slim bundle) |
| Commit `167dc03` | `refactor(architect): coordinate with primaries via plan_db, not via task` |
| Commit `9c1fb13` | `docs: clarify qagent ad-hoc audit flow + decouple from architect.md` |

### 10.3 Árbol de decisión actualizado (post-builder)

```
User envía prompt
  │
  ├─ ¿Tarea ≤1 archivo, ≤50 líneas, bien definida?
  │   → Cambiar a `builder` en TUI
  │   → Builder: Estado 1 (trivial, no plan_db)
  │   → Implementa, commits, reporta
  │
  ├─ ¿Tarea 2-5 archivos, multi-stack, necesita tracking?
  │   → Cambiar a `builder` en TUI
  │   → Builder: Estado 2 (ad-hoc con plan_db)
  │   → Crea plan, tasks, implementa, completa
  │
  ├─ ¿Tarea >5 archivos, diseño de arquitectura, o no sabe qué necesita?
  │   → Cambiar a `foreman` en TUI
  │   → Foreman: 10-step flow
  │   → Crea plan, tasks, delega a smiths
  │
  ├─ ¿Auditoría de PR existente sin plan previo?
  │   → Cambiar a `builder` en TUI (o futuro qagent)
  │   → Builder: Estado 1 (lee diff, reporta findings)
  │
  └─ ¿Tarea de exploración read-only?
      → Cambiar a `scout` en TUI (o delegar desde foreman)
```

---

## Apéndice: Relación con el bug existente

El bug documentado en `docs/bugs/plan-create-orphan-fk.md` sobre `ctx.sessionID` colisionando con `plan_approve`/`plan_update_status` **no se resuelve en este spec**. Razones:

1. Builder no usa `plan_approve` — solo usa `plan_create` + `plan_update_status("completed")`
2. `planUpdateStatus` ya tiene validación FK scoped: solo chequea `sessionId` para status `executing`/`approved` (`src/db/plans.ts:122`). Para `completed`/`failed`/`abandoned`, salta la validación.
3. `planCreateExecutor` ya tiene `ensureSession` automático (`src/db/plan-create.ts:39-41`), así que cualquier plan creado por builder tiene la sesión asegurada.

**Impacto:** El bug no afecta al builder en su flujo normal. Si en el futuro builder necesitara `plan_approve`, habría que aplicar el Fix (a) recomendado en el bug doc.

---

*Fin del feature spec v1 — 723 líneas*