ndomo 0.1.0

package/docs/features/feature-flexible-builder-v2.md

@@ -0,0 +1,882 @@
+# Feature: Primary Craftsman — refactor arquitectónico (v2)
+
+**Slug:** `feature-flexible-builder`
+**Status:** Draft (spec v2)
+**Plan ID:** `be21c801-b770-4d82-979a-2bb5186928f1`
+**Plan slug:** `flexible-builder-v2`
+**Created:** 2026-06-19
+**Supersedes:** `docs/features/feature-flexible-builder-v1.md`
+
+---
+
+## 1. Resumen ejecutivo
+
+Refactor arquitectónico mayor del ecosistema ndomo. Dos cambios estructurales que transforman el modelo de orquestación:
+
+1. **Foreman simplificado a 4 pasos** (Aclaración → Exploración → Plan atómico → Persistir): se eliminan 6 pasos del flujo original de 10 (Brief de Delegación, Trivium en Vivo, Reconciliación, Validación, Reporte Final). Foreman pasa de orquestador ejecutor a **planner puro**: planifica y persiste en DB; la ejecución la toma otro agente.
+
+2. **Nuevo primary `craftsman`** (antes `builder` en v1): agente implementador disciplinado con threshold estricto 2/5/1. Ataca bugs, features pequeñas y refactors acotados sin pasar por el ciclo de planificación del foreman. Opera con 4 estados de complejidad progresiva.
+
+El user alterna manualmente entre foreman (planificación formal) y craftsman (ejecución directa) mediante el TUI. No hay dispatch automático ni enrutamiento foreman→craftsman — la separación es manual por diseño.
+
+**Decisión clave del grill:** El nombre final es `craftsman` (no `builder`). El threshold es **2/5/1** (no 1/2-5/3 como en v1). El prompt del craftsman incluye 4 estados (no 3). Foreman baja a 4 pasos puramente planificadores.
+
+---
+
+## 2. Contexto y motivación
+
+### 2.1 Problemas del foreman original (10 pasos)
+
+El `foreman` (`agents/foreman.md`) operaba con un flujo de 10 pasos obligatorios que mezclaba planificación con ejecución:
+
+| # | Paso | Problema |
+|---|------|----------|
+| 1 | Aclaración | OK — necesario |
+| 2 | Memory Search | OK — necesario |
+| 3 | Routing | OK — necesario |
+| 4 | Plan Atómico | OK — necesario |
+| 5 | Brief de Delegación | Inflado: el prompt del subagente ya contiene el objetivo |
+| 6 | Trivium en Vivo | Contradictorio: foreman no debe implementar |
+| 7 | Reconciliación | Innecesario si craftsman ejecuta completo |
+| 8 | Validación | Craftsman corre sus propios tests |
+| 9 | Reporte Final | Craftsman reporta en su output |
+
+**Evidencia:** `agents/foreman.md:162-200` — secuencia de 10 pasos que el foreman debía seguir en cada request.
+
+### 2.2 Grietas específicas identificadas
+
+| Grieta | Ubicación en v1 | Impacto |
+|--------|-----------------|---------|
+| Trivium ≤5 líneas, 1 archivo, 0 nuevos exports | `agents/foreman.md:29-34` | Foreman no puede corregir ni un typo sin delegar |
+| No hay modo ad-hoc; toda tarea requiere `plan_create` + `task_create_batch` | `agents/foreman.md:238` | 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 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 rol de "único primary" | `agents/foreman.md:28` y `agents/*.md` (`mode: subagent`) | User no puede delegar directamente a un smith |
+| Routing estático en scheduler | `src/orchestrator/scheduler.ts:41-47` | No hay detección dinámica de stack |
+| `opencode.json` ausente en el repo | `glob("*opencode.json*")` → 0 resultados | Config global no versionada |
+| Sin asociación plan↔archivos | `src/db/schema.ts` | No hay trazabilidad de qué archivos toca cada plan |
+| Sin `original_plan_data` | `src/db/schema.ts` | No hay audit trail de "qué se planeó vs qué se hizo" |
+| Sin `plan_delete` | `src/plugin.ts` | No hay forma segura de eliminar planes huérfanos |
+
+### 2.3 Diferencias clave entre v1 y v2
+
+| Aspecto | v1 (`builder`) | v2 (`craftsman`) |
+|---------|----------------|-------------------|
+| Nombre | `builder` | `craftsman` (confirmado en grill) |
+| Estados | 3 (trivial, ad-hoc, formal) | 4 (con threshold 2/5/1) |
+| Threshold archivos | 1 / 2-5 / >5 | ≤2 Estado 1, 3-5 Estado 2, >5 Estado 4 |
+| Foreman | Sin cambios (10 pasos) | Simplificado a 4 pasos (planner puro) |
+| Cross-session close | `created_by` básico | `executed_by_agent` + `executed_by_session` + `created_by_agent` |
+| Migraciones DB | v6 + v7 | v6 (original_plan_data) + v7 (plan_files) + v8 (agent/session audit) |
+| Painter routing | Foreman | Solo craftsman |
+| Caveman | 14 agents target | Mismos 14 + snippet estándar |
+| `plan_delete` | Fase 3 | Fase 1 (priorizada) |
+| Plan ≤5 steps | Soft warning | Soft warning + log |
+
+---
+
+## 3. Análisis comparativo con nicosup98/ndomo
+
+### 3.1 Arquitectura referencia: architect + builder + qagent
+
+El proyecto referencia `nicosup98/ndomo` (opencode-core-slim) define tres modos de trabajo:
+
+| Modo | Agente | Cuándo |
+|------|--------|--------|
+| Plan formal | `architect` (primary) | Tarea multi-archivo, necesita diseño |
+| Ejecución directa | `builder` (primary) | Tarea bien definida, 1-5 archivos |
+| Ad-hoc audit | `qagent` (ad-hoc tool) | Scope se deriva del query |
+
+**Patrón clave:** `architect` NO usa `task` para invocar `builder`. Ambos son primaries que se comunican vía `plan_db` asíncrona. El user cambia de agente manualmente en el TUI.
+
+### 3.2 Tabla comparativa ndomo-v1 vs nicosup98/ndomo vs ndomo-v2
+
+| Aspecto | ndomo-v1 (foreman 10 pasos) | nicosup98/ndomo | ndomo-v2 (craftsman + foreman 4 pasos) |
+|---------|-----------------------------|-----------------|----------------------------------------|
+| Default agent | foreman (primary) | `build` (built-in) | foreman (primary planner) |
+| Implementador | foreman delega a smiths | builder/scout/qagent | **craftsman** (primary implementer) |
+| Modo trivial | Trivium ≤5 líneas + plan_db | `build` single-turn | Craftsman Estado 1 (sin plan_db) |
+| Modo plan formal | foreman → 10 pasos → smiths | architect → plan_db → builder | Foreman 4 pasos → plan_db → craftsman |
+| Coordinación | `task` síncrono | `plan_db` async + TUI switch | `plan_db` async + TUI switch |
+| Audit trail | Solo `created_at`/`updated_at` | `original_plan_data` | `original_plan_data` + agent/session FK |
+| Plan↔file | No existe | `plan_files` | `plan_files` |
+| Tono global | Caveman parcial (foreman + algunos) | Caveman en TODOS | Caveman en TODOS los 14 + craftsman |
+| `plan_delete` | No existe | Rechaza si `status='pending'` | Safety 3-capas |
+| Plan ≤5 steps | No hay regla | Regla en architect.md | Soft warning en task_create_batch |
+
+### 3.3 Por qué el patrón async + user switch gana
+
+Modelo v1 (foreman 10 pasos):
+1. Foreman crea plan en DB (2 writes)
+2. Foreman crea tasks batch (N writes)
+3. Foreman llama `task` para cada smith (N LLM invocations)
+4. Foreman espera resultados (N context switches)
+5. Foreman reconcilia resultados (N reads)
+
+Modelo v2 (foreman 4 pasos + craftsman):
+1. Foreman crea plan en DB (1-2 writes) — solo si >5 archivos o diseño arquitectura
+2. User cambia a craftsman en TUI (0 LLM tokens)
+3. Craftsman lee plan y ejecuta (1 read + N writes)
+4. Craftsman cierra plan con `plan_update_status("completed")`
+
+**Diferencia clave:** El modelo v2 gasta ~60% menos tokens en coordinación porque el "router" (foreman) solo escribe a DB, no invoca LLMs secundarios. Craftsman opera autónomamente.
+
+---
+
+## 4. Decisiones de diseño
+
+### D1. Nombre `craftsman` (no `builder`)
+
+**Decisión:** El primary implementador se llama `craftsman`, no `builder` como en v1.
+
+**Justificación:** Decisión del grill. `craftsman` evoca artesanía disciplinada (implementación precisa, threshold estricto, 4 estados). `builder` quedó descartado por ambigüedad con "builder pattern" y por la connotación genérica en el referencia.
+
+**Archivo:** `agents/craftsman.md`
+
+### D2. Threshold estricto 2/5/1
+
+**Decisión:** El craftsman opera con threshold numérico estricto:
+
+| Estado | Archivos | Comportamiento |
+|--------|----------|----------------|
+| Estado 1 | ≤2 archivos | Implementación directa, sin plan_db |
+| Estado 2 | 3-5 archivos | Implementación con plan_db (crea plan y tasks) |
+| Estado 3 | — | Lee plan existente del foreman y ejecuta |
+| Estado 4 | >5 archivos | **Rechaza** — "fuera de mi dominio" → cambiar a foreman |
+
+**Diferencia con v1:** v1 proponía 1/2-5 con threshold 1 archivo para Estado 1. v2 sube a ≤2 archivos para Estado 1, reflejando que fixes de 2 archivos son comunes y no requieren plan_db.
+
+**Enforcement:** Solo por prompt (no hay validación en código). Craftsman es un primary agent; su prompt es la única barrera.
+
+### D3. Routing interno: `task.files` extensión + `metadata.stack`
+
+**Decisión:** El craftsman decide a qué sub-smith delegar basándose en (1) extensión de archivo en `task.files`, (2) `task.metadata.stack` si existe, (3) LLM fallback.
+
+| Extensión | Sub-smith |
+|-----------|-----------|
+| `.go` | `go-smith` |
+| `.vue`, `.svelte` | `vue-smith` |
+| `.ts`, `.tsx`, `.js`, `.jsx` | `js-smith` |
+| `.py` | `python-smith` |
+| `.rs` | `rust-smith` |
+| `.zig` | `zig-smith` |
+| Sin match | `smith` (genérico) |
+
+**Archivo:** `agents/craftsman.md` — tabla de routing interno.
+
+### D4. Painter solo disponible vía craftsman
+
+**Decisión:** `painter` (UI/UX designer) solo es invocable desde craftsman, no desde foreman.
+
+**Justificación:** Foreman es planner puro (4 pasos). Si hay componente UI, craftsman decide: painter si `stack === "vue"` y `type === "design"`, o vue-smith si es implementación lógica.
+
+**Diferencia con v1:** v1 no especificaba painter routing — quedaba como responsabilidad del foreman.
+
+### D5. Cross-session close con audit trail completo
+
+**Decisión:** Tres nuevos campos en tabla `plans`:
+
+| Campo | Tipo | Descripción |
+|-------|------|-------------|
+| `created_by_agent` | TEXT | Agente que creó el plan (`foreman` o `craftsman`) |
+| `executed_by_agent` | TEXT | Agente que ejecutó (`craftsman`, `go-smith`, etc.) |
+| `executed_by_session` | TEXT FK → sessions.id | Sesión en que se ejecutó |
+
+**Justificación:** Permite trazabilidad cross-session: "qué agente creó este plan, qué agente lo ejecutó, en qué sesión". Especialmente útil cuando foreman planifica y craftsman ejecuta en sesiones separadas.
+
+**Comportamiento:**
+- `plan_create` setea `created_by_agent` desde `ctx.agent`
+- `task_update_status` / `plan_update_status` setea `executed_by_agent` y `executed_by_session` al primer `running`
+- Write-once: no se sobrescriben si ya están seteados
+
+### D6. `plan_delete` en Phase 1 (priorizada)
+
+**Decisión:** `plan_delete` tool se implementa en Phase 1 (no Phase 3 como en v1).
+
+**Safety checks:**
+1. Rechaza si `confirm !== true`
+2. Rechaza si `plan.status === 'pending'`
+3. Rechaza si hay tasks `pending` o `running`
+4. CASCADE: borra plan_tasks, plan_tags, plan_files, sessions ON DELETE SET NULL
+
+### D7. Plan ≤5 steps: soft warning (no bloqueo)
+
+**Decisión:** `task_create_batch` emite `console.warn` si `tasks.length > 5`. No bloquea. La regla se documenta en el prompt del foreman.
+
+**Justificación:** Bloquear sería contraproducente — el usuario podría tener razón. El warning es suficiente para que el foreman reevalúe.
+
+### D8. Caveman global snippet estándar
+
+**Decisión:** Insertar snippet exacto al inicio del prompt de 14 agents (después del frontmatter, antes del primer heading):
+
+```
+Tono: caveman por default, nivel full. Activa siempre.
+Excepción: prosa normal para advertencias de seguridad,
+acciones irreversibles o ambigüedad multi-paso.
+```
+
+**Agentes:** chronicler, go-smith, guild, inspector, js-smith, painter, python-smith, rust-smith, sage, scout, scribe, smith, vue-smith, zig-smith.
+
+**NO tocar:** `agents/craftsman.md` (ya incluye caveman en su prompt), `agents/foreman.md` (ya tiene caveman).
+
+---
+
+## 5. Diseño del craftsman
+
+### 5.1 Frontmatter YAML
+
+```yaml
+---
+description: Implementador Artesano / Disciplined Craftsman (modo ad-hoc o planificado)
+mode: primary
+model: opencode-go/deepseek-v4-flash
+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
+    "painter": allow
+  plan_db: allow
+---
+```
+
+**Diferencias con el foreman:**
+- `mode: primary` (NO subagent)
+- `task` permitido solo a subagents implementadores + painter
+- `task` NO permitido a foreman, guild, sage (son planners/advisors)
+- `task` permitido a chronicler (post-implementation docs) e inspector (review gate) — decisión confirmada en user dialog v2
+- Permisos `edit: allow`, `bash: ask` (craftsman implementa; foreman solo planifica)
+- `plan_db` tools disponibles pero condicionales (Estado 1 no las usa)
+
+### 5.2 Prompt con 4 estados
+
+```
+# Rol: Craftsman (Implementador Artesano)
+
+Eres un **primary agent** diseñado para implementar código con precisión
+artesanal. Atacas bugs, features pequeñas y refactors acotados. Operas en
+4 estados según el alcance del trabajo. Cuando el alcance excede tu umbral,
+escalas al foreman.
+
+## Tono
+Caveman nivel full SIEMPRE. Cero saludos, cero justificaciones.
+
+## Threshold estricto 2/5/1
+
+### Estado 1: Trivial (≤2 archivos, sin plan_db)
+**Cuándo:** ≤2 archivos, cambios acotados (≤50 líneas diff), sin dependencias externas.
+**Flujo:**
+1. Lee archivos objetivo
+2. Implementa cambios
+3. Corre validación (typecheck / tests / lint)
+4. Commit opcional (preguntar al user)
+5. Reporta directo: archivos, líneas, verificación
+**NO crea plan_create. NO toca plan_db.**
+
+### Estado 2: Multi-archivo acotado (3-5 archivos, con plan_db)
+**Cuándo:** 3-5 archivos, cambios que cruzan stacks, o necesita tracking cross-session.
+**Flujo:**
+1. `plan_create` con slug, overview, approach (1 línea cada uno)
+2. `task_create_batch` con steps (máximo 5)
+3. Para cada step: `task_update_status("running")` → implementar → `task_update_status("done")`
+4. Al final: `plan_update_status("completed")`
+**Obligatorio si toca más de 1 stack o requiere trazabilidad.**
+
+### Estado 3: Plan formal (lee plan_db existente)
+**Cuándo:** El foreman ya creó un plan con tasks asignadas a craftsman.
+**Flujo:**
+1. `plan_get({id})` o `task_next_for_agent({agent: "craftsman"})`
+2. Lee plan_data completo: overview, approach, contexto
+3. Implementa TDD: test → code → refactor
+4. `task_update_status("done")` con reporte
+5. Si todas las tasks hechas: `plan_update_status("completed")`
+
+### Estado 4: FUERA DE MI DOMINIO (>5 archivos)
+**Cuándo:** La tarea involucra >5 archivos o requiere diseño de arquitectura.
+**Acción:**
+→ Reportar: `[FUERA DE MI DOMINIO]` + cuantos archivos/por qué
+→ Sugerir cambiar a `foreman` en TUI
+→ NO implementar parcialmente
+
+### Regla de selección
+```
+¿Archivos ≤ 2 y sin dependencias externas?
+  → Estado 1: trivial (0 writes a DB)
+¿Archivos 3-5 o necesita tracking?
+  → Estado 2: plan_db propio
+¿Plan existente con tasks para craftsman?
+  → Estado 3: ejecutar plan formal
+¿Archivos > 5 o requiere diseño?
+  → Estado 4: fuera de dominio → foreman
+```
+
+## Routing interno (delegación a sub-smiths)
+Cuando necesites implementación especializada, usa:
+
+| Extensión archivo | Sub-smith |
+|---|---|
+| `.go` | `go-smith` |
+| `.vue` / `.svelte` | `vue-smith` |
+| `.ts` / `.tsx` / `.js` / `.jsx` | `js-smith` |
+| `.py` | `python-smith` |
+| `.rs` | `rust-smith` |
+| `.zig` | `zig-smith` |
+| UI/design + `type=design` | `painter` |
+| Sin match | `smith` (genérico) |
+
+Si `task.metadata.stack` existe, úsalo como override explícito.
+Si no hay match y no hay stack, usa `smith`.
+
+## Cross-session close
+- `executed_by_agent`: siempre `craftsman`
+- `executed_by_session`: siempre `current_session_id` (ctx.sessionID)
+- `created_by_agent`: setear en `plan_create` si creaste el plan
+
+## TDD workflow
+1. Test first (si existen tests en el proyecto)
+2. Code mínimo para pasar
+3. Refactor
+4. Verificar con suite del scope
+5. Commit atómico
+
+## Lo que NO puedes hacer
+- ❌ Invocar foreman, guild, sage vía task
+- ⚠️ Invocar chronicler solo post-implementación; inspector solo como review gate (no chaining entre ambos)
+- ❌ Editar prompts de otros agents
+- ❌ Editar tools MCP
+- ❌ Usar `plan_approve`
+- ❌ Modificar archivos sin leerlos primero
+
+## Output format
+```
+cambios:
+  - archivo:linea — desc — verified: OK
+tests:
+  - typecheck: passed
+  - test suite: N/N passed
+plan:
+  - id: (si se creó/usó)
+  - estado: completed | ad-hoc (no plan_db)
+```
+
+## Caveman skill
+Activa siempre. Excepción: prosa normal para advertencias de
+seguridad, acciones irreversibles o ambigüedad multi-paso.
+```
+
+---
+
+## 6. Foreman nuevo flow: 4 pasos (planner puro)
+
+### 6.1 Comparativa 10 pasos → 4 pasos
+
+| v1 (10 pasos) | v2 (4 pasos) | Diferencia |
+|---------------|--------------|------------|
+| 1. Aclaración | **1. Aclaración** | Se conserva |
+| 2. Memory Search | **2. Exploración** | Se fusiona: memory + scout/scribe/sage/guild |
+| 3. Routing | — | Routing implícito en la exploración |
+| 4. Plan Atómico | **3. Plan Atómico** | Se conserva, más liviano |
+| 5. Brief de Delegación | — | Eliminado: craftsman lee plan_db directamente |
+| 6. Trivium en Vivo | — | Eliminado: craftsman implementa |
+| 7. Reconciliación | — | Eliminado: craftsman ejecuta todo |
+| 8. Validación | — | Eliminado: craftsman corre tests |
+| 9. Reporte Final | — | Eliminado: craftsman reporta |
+| — | **4. Persistir** | Nuevo: plan_create + write plan_db |
+
+### 6.2 Flujo detallado
+
+#### Paso 1: Aclaración
+- Identificar intención en 1-2 frases
+- Si ambigüedad: `question` al usuario
+- Si la tarea es ≤5 archivos y bien definida → sugerir `craftsman`
+- Si >5 archivos o requiere diseño → continuar con planificación
+
+#### Paso 2: Exploración
+- `memory({mode:"search", scope:"project"})` — decisiones pasadas
+- Delegar a subagentes según necesidad:
+  - `scout` — mapear repo, encontrar archivos, detectar stack
+  - `scribe` — investigar APIs, versiones, docs externas
+  - `sage` — evaluar trade-offs arquitectónicos
+  - `guild` — solo si usuario pide debate explícito
+- NO delegar a smiths, painter, chronicler, inspector
+
+#### Paso 3: Plan Atómico
+- Desglosar en ≤5 steps top-level
+- Cada step: `(Acción) → archivos esperados → dependencias`
+- Estimar complejidad (1-5) y riesgo (low/medium/high)
+
+#### Paso 4: Persistir
+- `plan_create` con slug, overview, approach
+- `task_create_batch` con steps (máximo 5, warning si >5)
+- NO crear `session_start` (lo hace craftsman al ejecutar)
+- NO ejecutar tasks — craftsman las toma via `task_next_for_agent`
+
+### 6.3 Routing table del foreman (v2)
+
+| Petición | Delegar a |
+|----------|-----------|
+| Explorar código / mapear repo | `scout` |
+| Investigar APIs / docs / versiones | `scribe` |
+| Arquitectura / trade-offs / debugging difícil | `sage` |
+| Debate multi-perspectiva | `guild` (solo manual) |
+
+NOTA: foreman solo planifica. Ejecución es craftsman. NO delegar a smiths, painter, chronicler, inspector.
+
+### 6.4 Output del foreman (v2)
+
+```
+**Objetivo:** [1 línea]
+**Exploración:** [scout/scribe/sage findings]
+**Plan:**
+  1. [acción] → archivos: [paths] → complejidad: N
+  2. [acción] → archivos: [paths] → complejidad: N
+**Persistido:** plan_id=[uuid] slug=[slug]
+**Siguiente:** cambiar a craftsman en TUI → task_next_for_agent
+```
+
+### 6.5 Plan Approve (legacy)
+
+`plan_approve` es un tool MCP registrado en `src/plugin.ts:621-632` que marca un plan como `approved` seteando `approved_at`.
+
+**Estado:** **LEGACY** — El flujo v2 de foreman (4 pasos, sección 6.2) **NO usa `plan_approve`**. En v2, el foreman pasa directo de `plan_create` (status `draft`) a `task_create_batch`. El status `approved` queda implícito al dispatchar tasks via `task_create_batch`.
+
+**Por qué existe aún:** Compatibilidad con código externo y workflows manuales que requieren gating explícito antes de ejecutar. Se mantiene como tool MCP para uso legacy/humano.
+
+**Cuándo invocarlo manualmente:** Si un usuario externo o script quiere un gating explícito "aprobar antes de ejecutar", puede llamar `plan_approve` entre `plan_create` y `task_create_batch`. En el flujo v2 normal esto es innecesario.
+
+**Diferencia con v2 flow:**
+
+| Aspecto | v2 flow (foreman 4 pasos) | Legacy (con `plan_approve`) |
+|---------|---------------------------|-----------------------------|
+| Flujo | `plan_create` → `task_create_batch` | `plan_create` → `plan_approve` → `task_create_batch` |
+| Status intermedio | `draft` → directo a tasks | `draft` → `approved` → tasks |
+| Gating | Ninguno (dispatch inmediato) | Explícito (aprobación manual) |
+| Uso en v2 | Siempre | Nunca (solo externo/manual) |
+
+**Archivo:** `src/plugin.ts:621-632`
+
+---
+
+## 7. Cambios al sistema
+
+### 7.1 Migración v6: `original_plan_data`
+
+| Campo | Tabla | Tipo | Comportamiento |
+|-------|-------|------|----------------|
+| `original_plan_data` | `plans` | `TEXT` | En `plan_create`: copiar snapshot de args como JSON |
+| `original_plan_data` | `plan_tasks` | `TEXT` | En `task_create_batch`: copiar `{description, files, dependencies}` como JSON |
+
+**Reglas:**
+- `plan_create` setea `original_plan_data` al serializar los args de entrada
+- `plan_approve` NO toca `original_plan_data`
+- `plan_update_status` NO toca `original_plan_data`
+- `archivePlan` lo incluye en markdown pero NO lo modifica
+- `task_create_batch` setea `original_plan_data` por task
+
+**Archivos afectados:**
+- `src/db/schema.ts` — agregar columna vía `addColumnIfMissing` en migrations.ts (patrón v5)
+- `src/db/types.ts` — agregar `originalPlanData: string | null` a Plan y PlanTask, PlanRow, TaskRow
+- `src/db/plan-create.ts` — serializar `PlanCreateArgs` como `original_plan_data`
+- `src/db/tasks.ts` — serializar cada task input como `original_plan_data`; warning si `tasks.length > 5`
+- `src/db/plan-archive.ts` — leer y exportar `original_plan_data` en markdown archive
+- `src/db/plans.ts` — `createPlan` acepta `originalPlanData`; `updatePlanStatus` / `approvePlan` NO lo sobrescriben
+
+### 7.2 Migración v7: `plan_files`
+
+```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,
+  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 con role `'input'`
+- `task_create_batch` acepta `files: string[]` por task → inserta con role `'modified'`
+- `plan_get` retorna `files[]` via 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` — SCHEMA_V7_SQL con CREATE TABLE
+- `src/db/types.ts` — extender Plan/PlanTask con `files` array
+- `src/db/plan-create.ts` — `files?: string[]` en args, insertar en plan_files
+- `src/db/tasks.ts` — insertar en plan_files si `files` no vacío
+- `src/db/plans.ts` — `getPlan` JOIN con plan_files
+- `src/db/plan-archive.ts` — incluir files en markdown
+
+### 7.3 Migración v8: `created_by_agent` + `executed_by_agent` + `executed_by_session`
+
+```sql
+ALTER TABLE plans ADD COLUMN created_by_agent TEXT;
+ALTER TABLE plans ADD COLUMN executed_by_agent TEXT;
+ALTER TABLE plans ADD COLUMN executed_by_session TEXT REFERENCES sessions(id) ON DELETE SET NULL;
+```
+
+**Comportamiento:**
+- `plan_create`: setea `created_by_agent = ctx.agent` (write-once)
+- `task_update_status("running")` o `plan_update_status("executing")`: setea `executed_by_agent` y `executed_by_session` si es el primer running
+- `plan_approve` / `plan_update_status("completed")`: NO tocan estos campos
+- `getPlan`: retorna los campos en el objeto Plan
+
+**Archivos afectados:**
+- `src/db/schema.ts` — `addColumnIfMissing` en migrations.ts
+- `src/db/types.ts` — agregar `createdByAgent`, `executedByAgent`, `executedBySession` a Plan y PlanRow
+- `src/db/plan-create.ts` — pasar `ctx.agent` como `createdByAgent`
+- `src/db/plans.ts` — en `updatePlanStatus`, setear `executed_by_agent`/`executed_by_session` al pasar a `executing`; en `createPlan`, setear `created_by_agent`
+- `src/db/plan-archive.ts` — incluir en markdown archive
+
+### 7.4 `plan_delete` safety
+
+**Tool:** Nuevo en `src/plugin.ts`
+
+**Función:** `deletePlan(db, id, confirm)` en `src/db/plans.ts`
+
+**Validaciones:**
+1. `typeof confirm !== 'boolean' || confirm !== true` → error `"ndomo: plan_delete requires confirm: true"`
+2. `plan.status === 'draft'` → error `"ndomo: cannot delete a draft plan — use abandonPlan or approve first"`
+3. Existen tasks con `status IN ('pending', 'running')` → error `"ndomo: plan has active tasks — resolve them first"`
+
+**Si pasa:** `DELETE FROM plans WHERE id = ?` (CASCADE: plan_tasks, plan_tags, plan_files; sessions → SET NULL)
+
+### 7.5 Plan ≤5 steps soft warning
+
+En `src/db/tasks.ts`, función `createTasksBatch`:
+
+```typescript
+if (tasks.length > 5) {
+  console.warn(`[ndomo] plan ${planId} has ${tasks.length} tasks (>5): consider splitting`);
+}
+```
+
+No bloquea. Warning visible en logs de OpenCode.
+
+### 7.6 Caveman global en 14 agents
+
+Insertar snippet estándar después del frontmatter YAML, antes del primer heading:
+
+```
+Tono: caveman por default, nivel full. Activa siempre.
+Excepción: prosa normal para advertencias de seguridad,
+acciones irreversibles o ambigüedad multi-paso.
+```
+
+**Archivos:** `agents/chronicler.md`, `agents/go-smith.md`, `agents/guild.md`, `agents/inspector.md`, `agents/js-smith.md`, `agents/painter.md`, `agents/python-smith.md`, `agents/rust-smith.md`, `agents/sage.md`, `agents/scout.md`, `agents/scribe.md`, `agents/smith.md`, `agents/vue-smith.md`, `agents/zig-smith.md`.
+
+---
+
+## 8. Acceptance criteria
+
+### 8.1 Craftsman existe y es primary
+- [ ] `agents/craftsman.md` existe con `mode: primary`, frontmatter completo
+- [ ] Prompt cubre 4 estados con threshold 2/5/1
+- [ ] User puede cambiar a craftsman en TUI
+
+### 8.2 Threshold 2/5/1 funcional
+- [ ] Estado 1: tarea ≤2 archivos → implementa sin plan_db
+- [ ] Estado 2: tarea 3-5 archivos → crea plan_db + tasks
+- [ ] Estado 3: plan existente → ejecuta tasks asignadas
+- [ ] Estado 4: tarea >5 archivos → reporta fuera de dominio
+
+### 8.3 Routing interno del craftsman
+- [ ] Delegación por extensión: .go → go-smith, .vue → vue-smith, etc.
+- [ ] `metadata.stack` override funciona
+- [ ] LLM fallback a `smith` genérico
+
+### 8.4 Painter solo vía craftsman
+- [ ] Foreman NO lista painter en su routing
+- [ ] Craftsman puede delegar a painter si `stack === "vue"` y `type === "design"`
+- [ ] Craftsman usa vue-smith para UI no-design
+
+### 8.5 Cross-session close
+- [ ] `plan_create` setea `created_by_agent` (write-once)
+- [ ] Primer `task_update_status("running")` setea `executed_by_agent` + `executed_by_session`
+- [ ] Campos no se sobrescriben en updates posteriores
+
+### 8.6 Migraciones DB
+- [ ] v6: `original_plan_data` write-once en plans y plan_tasks
+- [ ] v7: `plan_files` insert + query + CASCADE
+- [ ] v8: `created_by_agent`, `executed_by_agent`, `executed_by_session` en plans
+- [ ] Migraciones aplican limpias a DB existente
+
+### 8.7 `plan_delete` safety
+- [ ] Rechaza sin `confirm: true`
+- [ ] Rechaza si `status='draft'`
+- [ ] Rechaza si hay tasks pending/running
+- [ ] CASCADE ejecuta correctamente
+
+### 8.8 Plan ≤5 steps
+- [ ] `agents/foreman.md` contiene regla de ≤5 steps
+- [ ] `task_create_batch` emite console.warn si >5 tasks
+
+### 8.9 Caveman global
+- [ ] 14 agents tienen snippet caveman estándar
+- [ ] Craftsman tiene caveman en prompt
+- [ ] Foreman ya tenía caveman (no duplicar)
+
+### 8.10 Tests y verificación
+- [ ] `plan_delete` tests (3 sub-casos)
+- [ ] `original_plan_data` write-once test
+- [ ] `plan_files` insert + query + CASCADE test
+- [ ] Audit trail write-once test (v8)
+- [ ] `bun run typecheck` pasa sin errores
+- [ ] `bun test` pasa (suite completa)
+
+### 8.11 Docs
+- [ ] `docs/agents.md` tiene sección craftsman (rol, cuándo usar, threshold 2/5/1)
+- [ ] `docs/workflows.md` árbol de decisión actualizado
+
+---
+
+## 9. Plan de implementación (5 fases)
+
+### Fase 0: Spec v2 + backup v1 (chronicler, ~30min)
+
+**Qué:**
+1. Backup `docs/features/feature-flexible-builder.md` → `-v1.md`
+2. Reescribir spec v2 con arquitectura craftsman + foreman 4 pasos + threshold 2/5/1
+
+**Archivos:**
+- `docs/features/feature-flexible-builder.md` (rewrite)
+- `docs/features/feature-flexible-builder-v1.md` (backup)
+
+### Fase 1: Migraciones DB + tests (js-smith, ~2h)
+
+**Qué:**
+1. v6: `original_plan_data` en plans + plan_tasks
+2. v7: `plan_files` join table
+3. v8: `created_by_agent` + `executed_by_agent` + `executed_by_session`
+4. `deletePlan` en `src/db/plans.ts` con safety checks
+5. Tests: `plans.test.ts` (delete), `plan-files.test.ts`, `migrations-v8.test.ts`
+
+**Archivos:** Ver sección 7.1, 7.2, 7.3, 7.4
+
+### Fase 2: `agents/craftsman.md` (chronicler, ~1h)
+
+**Qué:**
+1. Crear `agents/craftsman.md` con frontmatter + prompt 4 estados + routing + cross-session close
+
+**Archivos:**
+- `agents/craftsman.md` (nuevo)
+
+**Dependencia:** Phase 1 (para referencias DB en el prompt)
+
+### Fase 3: Foreman rewrite + caveman global (smith/chronicler, ~1.5h)
+
+**Qué:**
+1. Rewrite `agents/foreman.md` a 4 pasos: Aclaración→Exploración→Plan Atómico→Persistir
+2. Agregar caveman a 14 agents (diff mecánico)
+3. Registrar `plan_delete` en `src/plugin.ts`
+4. Soft warning ≤5 tasks en `src/db/tasks.ts`
+
+**Archivos:**
+- `agents/foreman.md` (rewrite)
+- `agents/*.md` (14 archivos, +caveman)
+- `src/plugin.ts` (+plan_delete tool)
+- `src/db/tasks.ts` (+warning)
+
+**Dependencia:** Phase 2 (foreman routing ya no incluye smiths)
+
+### Fase 4: Docs + smoke tests (chronicler, ~1h)
+
+**Qué:**
+1. Actualizar `docs/agents.md` con craftsman
+2. Actualizar `docs/workflows.md` con árbol de decisión
+3. Smoke tests checklist (no automatizados):
+   - Foreman flow 4 pasos: plan_create + task_create_batch
+   - Craftsman Estado 1: ≤2 archivos, sin plan_db
+   - Craftsman Estado 4: >5 archivos → rechazo
+4. `bun run typecheck` y `bun test` verdes
+
+**Archivos:**
+- `docs/agents.md` (nueva sección craftsman)
+- `docs/workflows.md` (árbol actualizado)
+
+**Dependencia:** Phase 2 + Phase 3
+
+---
+
+## 10. Riesgos y trade-offs
+
+### R1. Abuso del craftsman para tareas grandes
+
+**Riesgo:** Craftsman tiene `edit: allow` + `task: allow`. El user podría usarlo para features >5 archivos, saltándose el foreman.
+
+**Mitigación (2 capas):**
+1. **Prompt:** Estado 4 rechaza explícitamente >5 archivos
+2. **Modelo:** craftsman usa temperatura 0.1, menos propenso a auto-expandir scope
+
+**Severidad:** baja (el sistema es una herramienta, no un guardián).
+
+### R2. Separación manual foreman→craftsman confusa
+
+**Riesgo:** El user no sabe cuándo usar foreman vs craftsman, resultando en planes mal diseñados o implementaciones sin plan.
+
+**Mitigación:**
+1. Foreman en el Paso 1 (Aclaración) sugiere craftsman si la tarea es ≤5 archivos
+2. Craftsman en Estado 4 sugiere foreman si >5 archivos
+3. `docs/workflows.md` documenta árbol de decisión
+
+**Severidad:** media (curva de aprendizaje inicial).
+
+### R3. Crecimiento de DB con `original_plan_data`
+
+**Riesgo:** Duplica `plan_data` (2x por fila). En proyectos grandes, puede sumar MB.
+
+**Mitigación:**
+1. Auto-archive a markdown cuando el plan se completa
+2. Archivar setea `archived_at`, limpiando de DB activa
+
+**Severidad:** baja (SQLite, 1000 planes ≈ 2-5MB extra).
+
+### R4. Write-once no enforced en DB
+
+**Riesgo:** Los campos `created_by_agent`, `executed_by_agent`, `executed_by_session` y `original_plan_data` son write-once por convención, no por constraint DB.
+
+**Mitigación:**
+1. El código en `planCreateExecutor`, `createPlan`, `updatePlanStatus` verifica antes de setear
+2. Tests unitarios validan write-once behavior
+
+**Severidad:** baja (si se sobrescribe, es bug en el código, no en la DB).
+
+### R5. Caveman en 14 agents = 14 lugares de mantenimiento
+
+**Riesgo:** El snippet caveman puede volverse inconsistente si se edita en un agent y no en los otros.
+
+**Mitigación:**
+1. Snippet exacto documentado en spec (sección 7.6)
+2. Si cambia, buscar/replace en 14 archivos
+
+**Severidad:** baja (diff mecánico).
+
+### R6. Foreman sin acceso a smiths — posible fricción
+
+**Riesgo:** Si el user pide al foreman "implementa X en Go" y el foreman no puede delegar a go-smith directamente, el user debe cambiar manualmente a craftsman.
+
+**Mitigación:**
+1. Foreman en Paso 1 sugiere craftsman temprano
+2. Foreman puede planificar y craftsman ejecuta — el user cambia una vez
+
+**Severidad:** media-baja (un switch manual adicional vs delegación automática).
+
+---
+
+## 11. Referencias cruzadas
+
+### 11.1 Archivos clave
+
+| Archivo | Líneas relevantes | Notas |
+|---------|-------------------|-------|
+| `agents/foreman.md` | 1-21 (frontmatter), 162-200 (10 pasos v1) | Se reescribe a 4 pasos en Phase 3 |
+| `agents/craftsman.md` | (nuevo) | Creado en Phase 2 |
+| `src/db/schema.ts` | 8-497 (v1-v5), MIGRATIONS array 465-497 | Se agregan v6/v7/v8 |
+| `src/db/types.ts` | 41-64 (Plan), 66-91 (PlanTask), 119-166 (Rows) | Se extienden con nuevos campos |
+| `src/db/plans.ts` | createPlan, updatePlanStatus, approvePlan | Puntos de inserción original_plan_data + v8 |
+| `src/db/tasks.ts` | 13-80 (createTasksBatch), 109-121 (truncation) | original_plan_data + warning ≤5 |
+| `src/db/plan-create.ts` | 15-30 (PlanCreateArgs), 32-62 (planCreateExecutor) | ensureSession ya existe |
+| `src/db/plan-archive.ts` | serializePlanToMarkdown, archivePlan | Incluir nuevos campos |
+| `src/db/migrations.ts` | addColumnIfMissing, runMigrations | Patrón para v6/v7/v8 |
+| `src/plugin.ts` | 352-822 (tools) | Nuevo tool plan_delete + adjust plan_create |
+| `src/db/plans.ts` | (nueva función) | deletePlan con safety checks |
+| `docs/bugs/plan-create-orphan-fk.md` | 60-70, 88-103 | Bug conocido, no resuelto |
+
+### 11.2 Specs relacionados
+
+| Recurso | Relación |
+|---------|----------|
+| `docs/features/feature-flexible-builder-v1.md` | Spec original v1 (archivada). Define `builder` con 3 estados. Reemplazada por v2. |
+| `agents/foreman.md` | Prompt actual del foreman (10 pasos). Se reescribe en Phase 3. |
+| `docs/agents.md` | Se actualiza en Phase 4 con craftsman. |
+| `docs/workflows.md` | Se actualiza en Phase 4 con árbol de decisión. |
+| `src/db/schema.ts` | Schema DB actual (v1-v5). Migraciones v6+v7+v8 en spec. |
+
+### 11.3 Árbol de decisión actualizado
+
+```
+User envía prompt
+  │
+  ├─ ¿Tarea ≤2 archivos, ≤50 líneas, bien definida?
+  │   → `craftsman` en TUI → Estado 1 (trivial, sin plan_db)
+  │
+  ├─ ¿Tarea 3-5 archivos, multi-stack, necesita tracking?
+  │   → `craftsman` en TUI → Estado 2 (ad-hoc con plan_db)
+  │
+  ├─ ¿Tarea >5 archivos, diseño de arquitectura, o ambigua?
+  │   → `foreman` en TUI → 4 pasos: Aclaración → Exploración → Plan → Persistir
+  │   → Luego `craftsman` en TUI → Estado 3 (lee plan formal)
+  │
+  ├─ ¿Auditoría de PR existente o tarea read-only?
+  │   → `craftsman` o `scout` según necesite escribir
+  │
+  └─ ¿Exploración read-only?
+      → `scout` en TUI
+```
+
+---
+
+## Apéndice A: Decisiones del grill
+
+| Decisión | Opción elegida | Alternativas descartadas |
+|----------|---------------|--------------------------|
+| Nombre del primary | `craftsman` | `builder` (v1), `implementer`, `artisan` |
+| Threshold | 2/5/1 (≤2 Estado 1, 3-5 Estado 2, >5 Estado 4) | 1/2-5 (v1), 1/3-5/6+ |
+| Estados del craftsman | 4 (trivial / multi-archivo / plan formal / fuera dominio) | 3 (v1) |
+| Foreman pasos | 4 (Aclaración / Exploración / Plan / Persistir) | 10 (v1), 6, 3 |
+| Painter routing | Solo craftsman | Foreman + craftsman |
+| Cross-session close | `created_by_agent` + `executed_by_agent` + `executed_by_session` | Solo `created_by` |
+| `plan_delete` fase | Phase 1 (priorizada) | Phase 3 (v1) |
+| Plan ≤5 steps | Soft warning (no bloqueo) | Bloqueo estricto |
+| Caveman snippet | Estándar en 14 agents | Caveman solo en prompt |
+
+---
+
+## Apéndice B: Relación con bugs existentes
+
+### Bug `ctx.sessionID` (`docs/bugs/plan-create-orphan-fk.md`)
+
+No se resuelve en este spec. Craftsman usa `plan_create` + `plan_update_status("completed")`:
+- `planCreateExecutor` ya tiene `ensureSession` automático (`src/db/plan-create.ts:39-41`)
+- `planUpdateStatus` solo chequea FK para status `executing`/`approved` (`src/db/plans.ts:122`)
+- Craftsman no usa `plan_approve`
+
+**Impacto:** El bug no afecta al flujo craftsman.
+
+### Truncation 16KB (`src/db/tasks.ts:109-121`)
+
+No se resuelve en este spec. Craftsman genera resultados pequeños (formato caveman). Si un sub-smith produce output grande, el truncation aplica igual que hoy.
+
+---
+
+*Fin del feature spec v2 — ~600 líneas*