autopilot-implement

name	autopilot-implement
description	Autonomous implementation from a plan file. Creates feature branch, implements all phases, generates Stitch designs if needed, converts designs to code, runs QA validation, and creates GitHub PR. Use when the user says "implement plan", "execute plan", "autopilot", or references implementing a previously created plan.
disable-model-invocation	true

Working set (v5.32.0)

/implement mantiene 4 archivos en .quality/evidence/{feature}/:

Archivo	Vida	Quien escribe	Quien lee
pipeline_state.json	Toda la run	Orquestador (Paso 0.4a + tras cada fase)	pipeline-phase-guard.mjs
execution_context.json	Toda la run (immutable)	Orquestador (Paso 0.4b)	Cada Task delegado, hooks
phase_outputs.jsonl	Append-only durante la run	Cada Task al cierre	Spec-Code Sync (Paso 5.1.1b, 8.5.1a)
checkpoint.json	Toda la run, sobrescrito	Orquestador post-fase	Resume al iniciar nueva sesion

Y .quality/active_agent.json en raiz del proyecto, transient (escrito antes de cada Task(AG-XX), borrado tras retorno) — leido por file-ownership-guard.mjs para validar Write/Edit.

Telemetria adicional:

• .quality/task_isolation.json — counters (tasks_run_total, tasks_failed_budget, tasks_failed_ownership). Bumped por los hooks y por el bloque post-Task del Paso 5.0. Telemetria local.

Checkpoint System

Before starting, check for existing checkpoint:

• Read .quality/evidence/${feature}/checkpoint.json if exists
• If checkpoint found AND branch exists:
  • Report: "Found checkpoint at Phase {N}. Resume or restart?"
  • If resume: git checkout the branch, skip to Phase N+1
• After each successful phase, save checkpoint:

  mkdir -p .quality/evidence/${feature}
  echo '{"phase": N, "phase_name": "...", "branch": "...", "timestamp": "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'", "status": "complete"}' > .quality/evidence/${feature}/checkpoint.json
  

• On error: save checkpoint with status "failed" and phase details

/implement (Global)

Autopilot de implementacion: lee un plan, crea rama, ejecuta todas las fases, genera diseños si aplica, valida con QA, commitea y crea PR.

Uso

/implement [plan]

Origenes soportados:

• US-XX → User Story de Trello (ejecuta todos los UCs en secuencia)
• UC-XXX → Use Case individual de Trello
• nombre_del_plan → Busca doc/plans/{nombre}_plan.md
• doc/plans/mi_plan.md → Path directo al archivo del plan
• Sin argumento → Lista planes disponibles en doc/plans/ y pregunta cual ejecutar

---

Paso 0.0 — Política de Autopilot v5.29.0

ANTES de cualquier otro paso, llama a la tool MCP get_inheritable_values_tool(project_path=".") para conocer el autopilot_level del proyecto y los valores heredables desde app_*.md.

Antes de cada gate o pregunta, llama a evaluateDecision(decision_key, context) desde .claude/hooks/lib/autopilot.mjs. Si retorna auto, aplica el default + log; si ask, pregunta como en v5.28; si block, bloquea con el mensaje del helper.

Pregunta / gate	decision_key	Default si auto
Origen ambigüo (Paso 0.1, sin argumento)	origin_detection	equilibrado+: usar match único
Uncommitted changes warning (Paso 0.2)	uncommitted_changes_warning	siempre ask
Stitch design por pantalla (Paso 3)	stitch_design_per_screen	conservador+: auto si HTML existe
Image cost ≤ presupuesto (Paso 3.5.0)	image_cost_under_budget	equilibrado+: auto cuando coste ≤ budget de app_spec.md sección 5
Image cost > presupuesto (Paso 3.5.0)	image_cost_over_budget	siempre ask (inviolable)
Stitch API key faltante	stitch_api_key_missing	siempre ask
Push directo a main	branch_to_main_push	siempre block (inviolable)
Acciones destructivas (reset, force-push)	destructive_action	siempre ask (inviolable, además bloqueado por no-bypass-guard)

Reglas inviolables:

• Image cost > presupuesto nunca auto-confirma. Para subir el límite, edita app_spec.md sección 5 → autopilot.
• Push a main siempre bloqueado por hook branch-guard.mjs y commit-spec-guard.mjs. /implement no debe intentar bypassearlo.
• Acceptance Validator (AG-09b) verdict ACCEPTED no se auto-confirma — eso es validación de calidad y vive aparte del autopilot.

Tras cada auto-decisión visible al usuario:

ℹ️  Diseños Stitch existentes auto-confirmados (autopilot: equilibrado, decision_key: stitch_design_per_screen)

---

Paso 0: Cargar y Validar Plan

0.1 Localizar el plan

Que recibi?
├── US-XX → Modo Trello: ejecutar bloque de UCs de la US
├── UC-XXX → Modo Trello: ejecutar un UC individual
├── nombre_del_plan → Buscar doc/plans/{nombre}_plan.md
├── path directo → Leer directamente
└── sin argumento → Listar doc/plans/*.md y preguntar

0.1a Si es US-XX o UC-XXX (Trello spec-driven):

1. Obtener board_id (buscar en orden de prioridad):
   • .claude/project-config.json → trello.boardId (PREFERIDO — Claude Code rechaza campos custom en settings.local.json)
   • .claude/settings.local.json → trello.boardId (fallback legacy)
   • Si no existe en ninguno → ERROR: "Configura trello.boardId en .claude/project-config.json"
2. Si US-XX:
   • Llamar get_us(board_id, us_id) → datos de la US
   • Llamar list_uc(board_id, us_id) → listar UCs hijos
   • Llamar find_next_uc(board_id) → determinar primer UC a ejecutar
   • Buscar plan adjunto: get_evidence(board_id, us_id, "us", "plan")
   • Si hay plan en doc/plans/ → cargar plan local
   • Si no hay plan → ERROR: "Ejecuta /plan US-XX primero"
3. Si UC-XXX:
   • Llamar get_uc(board_id, uc_id) → datos completos del UC
   • Derivar us_id del UC → buscar plan de la US padre
4. Parsear plan y filtrar solo las fases relevantes para el UC actual
5. Llamar start_uc(board_id, uc_id) → mover a In Progress + timestamp

Flujo de ejecucion por US (bloque de UCs):

US-XX recibida
  ├── Cargar plan de la US
  ├── find_next_uc → UC-001 (Backlog)
  │   ├── start_uc(UC-001) → In Progress
  │   ├── Implementar (Pasos 1-7.7)
  │   ├── move_uc(UC-001, "review") → Review (humano aprueba Done)
  │   ├── Merge secuencial (Paso 8.5)
  │   └── Pull main
  ├── find_next_uc → UC-002 (Backlog)
  │   ├── start_uc(UC-002) → In Progress
  │   ├── ... (mismo ciclo)
  │   └── Pull main
  └── No mas UCs en Backlog → Finalizar

0.1b Si es plan local:

# Listar planes disponibles
ls doc/plans/*_plan.md 2>/dev/null

Si no hay planes → Informar: "No hay planes en doc/plans/. Ejecuta /plan primero."

0.2 Parsear el plan

Leer el archivo del plan completo y extraer:

Campo	Donde encontrarlo	Obligatorio
Titulo	# Plan: [titulo] (primera linea H1)	Si
Resumen	Seccion ## Resumen	Si
Fases	Secciones ### Fase N:	Si
Componentes UI	Seccion ## Analisis UI o ## Componentes UI	No
Widgets a crear	Subseccion ### Widgets a Crear	No
Archivos a crear/modificar	Seccion ## Archivos a Crear/Modificar	No
Agentes involucrados	Referencias a AG-XX en las fases	No
Comandos finales	Seccion ## Comandos Finales	No
Diseños Stitch	Referencias a doc/design/ o pantallas Stitch	No
VEGs	doc/veg/{feature}/*.md — artefactos Visual Experience Generation	No
Modo VEG	Seccion "Visual Experience Generation" del plan	No
Trello US/UC	Origen US-XX o UC-XXX + board_id	No

0.3 Detectar si requiere diseño y VEG

Regla de decision:

¿El plan tiene diseños Stitch?
├── SI: Referencia a doc/design/{feature}/*.html
│   ├── ¿Existen los HTML? → Ir a Paso 4 (design-to-code)
│   └── ¿No existen? → Generar con Stitch (Paso 3)
├── SI: Seccion "Diseños Stitch" con pantallas listadas
│   └── Mismo flujo: verificar existencia → generar si faltan
└── NO: No hay referencias a diseño
    └── Saltar directamente a Paso 5 (implementacion)

¿El plan tiene seccion "Visual Experience Generation"?
├── SI: Cargar VEGs de doc/veg/{feature}/*.md
│   ├── Leer modo VEG (1/2/3) y archivos generados
│   ├── Activar pasos VEG: enriquecer Stitch (3), generar imagenes (3.5), inyectar motion (4)
│   └── Preparar resumen VEG compacto (~400 tokens) para sub-agentes
└── NO: Pipeline legacy (sin cambios)

0.4 Detectar stack tecnologico

# Detectar stack del proyecto actual
cat pubspec.yaml 2>/dev/null | grep -E "flutter:|dependencies:"  # Flutter
cat package.json 2>/dev/null | grep -E "react|next"              # React/Node
cat pyproject.toml 2>/dev/null | grep -E "fastapi|django"        # Python
ls .clasp.json appsscript.json 2>/dev/null                       # Google Apps Script

0.4a Inicializar Pipeline State (v5.19.0)

Despues de detectar el stack y parsear el plan, inicializar pipeline_state.json para que pipeline-phase-guard.mjs pueda validar el orden de fases:

mkdir -p .quality/evidence/${feature}

Determinar qué fases aplican al proyecto:

has_db = plan incluye fase DB/Infra (AG-03)
has_ui = plan incluye fase Diseño/Design-to-code (AG-02/AG-06)

# Pre-marcar fases no aplicables como completadas
completed_phases = []
if NOT has_db:  completed_phases.append("db_infra")
if NOT has_ui:  completed_phases.append("stitch_designs", "design_to_code")

Escribir el estado inicial:

// .quality/evidence/${feature}/pipeline_state.json
{
  "feature": "${feature}",
  "has_ui": true|false,
  "has_db": true|false,
  "completed_phases": ["...fases no aplicables pre-marcadas..."],
  "current_phase": "init",
  "last_updated": "ISO8601"
}

IMPORTANTE: Este archivo es OBLIGATORIO. Sin el, pipeline-phase-guard.mjs permite todo (modo permisivo). Con el, enforce mecánico del orden de fases.

0.4b Inicializar Execution Context (v5.32.0)

Inmediatamente despues de pipeline_state, escribir tambien el execution_context.json que cada Task delegado leera para conocer branch / feature / stack sin que el orquestador los repita verbatim en cada prompt (causa raiz de la exhaustion de contexto en UCs grandes — ver doc/plans/v5.32.0_implement_task_isolation_plan.md).

from server.implement_context import write_execution_context, compute_plan_hash

write_execution_context(
    feature_slug=feature,
    branch=branch,                     # se conocera en Paso 1; aqui pasar valor
                                       # tentativo y refrescar tras crear la rama
                                       # con update_last_updated()
    stack=stack,                       # detectado en Paso 0.x
    project_name=project_name,
    project_root_absolute=str(Path.cwd()),
    engine_version="5.32.0",
    uc_id=uc_id,
    us_id=us_id,
    backend_type=backend_type,         # freeform | trello | plane
    board_id=board_id,
    plan_path=str(plan_path),
    plan_hash=compute_plan_hash(plan_path),
    autopilot_level=autopilot_level,   # equilibrado | conservador | ...
)

Esto crea .quality/evidence/{feature}/execution_context.json con escritura atomica e idempotente (no churnea el archivo si el contenido no cambia).

Contrato de uso: a partir de aqui, cualquier Task delegado por /implement debe arrancar leyendo este archivo en lugar de recibir branch/feature/stack en el prompt. Ver Paso 5.X.0 para el bloque reusable de invocacion.

0.4c Pre-flight Autonomy Triage (US-06 — BLOQUEANTE)

Por que aqui: este paso corre antes de start_uc y de crear la rama (Paso 1). El autopilot rara vez falla al ejecutar; falla cuando adivina una decision que era del usuario (un contrato de API, un naming, un trade-off) y arrastra el error por toda la cadena rama->fases->QA->PR. El gate resuelve esas decisiones con el usuario por adelantado, cuando corregir cuesta ~50 tokens en vez de un PR entero.

1. Analizar el plan con la tool MCP (content-passing: leer el plan local con Read y pasar su contenido):

   analyze_preflight_decisions(
     plan_content="<contenido de doc/plans/{feature}_plan.md>",
     autopilot_level="<specbox.autopilot.level de settings.local.json>"
   )
   

   Devuelve {decisions[], verdict, user_dependent, user_dependent_decisions[], ...}.

2. Actuar segun el verdict:

   verdict	Accion
   no_user_decisions	Continuar directo a 0.5 / start_uc / rama sin interrumpir. El gate no molesta cuando todo es autonomo o no hay decisiones (AC-08).
   needs_user_input	BLOQUEAR la creacion de rama. Presentar al usuario la lista de user_dependent_decisions (cada una con su description y, si la hay, su reason) y pedirle que las resuelva TODAS antes de continuar (AC-06).

3. Mostrar lo autonomo como informativo (no pedir accion): las decisiones clasificadas autonomous se listan con su reason (de la politica) para que el usuario vea que se resolvio solo y por que — transparencia (JE-F.1).

4. No re-preguntar: las decisiones resueltas aqui NO se vuelven a preguntar durante las fases (AC-07). El registro queda en .quality/autopilot_decisions.jsonl (kind=preflight) via la capa de log de la tool, auditable despues (UC-604).

5. Inviolables: las decisiones destructivas / push-a-main / coste-sobre-budget siempre caen en user_dependent aunque el nivel sea agresivo — el gate nunca las auto-confirma (AC-05). "Mas autonomia" jamas significa "menos seguridad".

Degradacion: si la tool no esta disponible (engine viejo), el gate se omite y /implement se comporta como antes — backwards-compatible.

0.5 Validacion pre-vuelo (HARD BLOCKS)

Antes de ejecutar, verificar:

• El plan tiene al menos una fase con tareas
• El stack del proyecto es detectable
• No hay cambios sin commitear (git status --porcelain)
• La rama main/master esta actualizada

# Verificar working tree limpio
git status --porcelain

# Verificar rama actual
git branch --show-current

# Actualizar main
git fetch origin

Si hay cambios sin commitear → Advertir al usuario y preguntar si continuar (puede perder contexto).

Si no esta en main → Advertir y preguntar si crear la rama desde la rama actual o desde main.

0.5b Guardia anti-implementacion-en-main (BLOQUEANTE)

REGLA INNEGOCIABLE: Nunca se puede implementar directamente en main/master.

Esta validacion se ejecuta ANTES del Paso 1 y se RE-VERIFICA antes de cada Paso 5 (implementacion de fases).

current_branch = git branch --show-current

¿current_branch es main o master?
├── SI (estamos en Paso 0): OK — el Paso 1 creara la rama feature/
├── SI (estamos en Paso 5+): ❌ ERROR FATAL
│   → "BLOQUEADO: Se esta intentando implementar directamente en main.
│      Esto viola el protocolo de ramas del engine.
│      El Paso 1 debio crear una rama feature/ antes de llegar aqui.
│      ACCION: Parar inmediatamente. NO escribir codigo en main."
│   → PARAR el pipeline. No continuar bajo ninguna circunstancia.
└── NO: OK — continuar normalmente

Por que este bloqueo es necesario:

• Sin rama feature/, no hay PR posible
• Sin PR, no hay acceptance evidence ni review
• Sin review, el merge secuencial no puede funcionar
• Implementar en main directamente rompe TODO el pipeline de calidad

0.5c.vs Visual Identity Gate (si UC tiene pantallas) (BLOQUEANTE)

REGLA: No se puede implementar UI sin identidad visual configurada. Este gate impide generar diseños genéricos que no representan la marca del producto. Se ejecuta ANTES del Design Gate (0.5d) porque sin brand kit los diseños carecen de sentido.

¿El UC/plan tiene pantallas listadas?
├── No tiene pantallas → SKIP (gate no aplica, UC sin UI)
└── Tiene pantallas → Verificar identidad visual:
    │
    ¿Existe doc/brand/brand_kit/SKILL.md?
    ├── SI → OK — brand kit configurado, continuar
    └── NO → Verificar mas:
        │
        ¿Existe stitch.designSystemAssetId en .claude/settings.local.json?
        ├── SI → OK — Design System configurado (brand kit parcial aceptable)
        └── NO → Verificar si el proyecto usa Stitch:
            │
            ¿Existe stitch.projectId en .claude/settings.local.json
             O existen doc/design/**/*.html?
            ├── NO → SKIP (proyecto no usa Stitch, gate no aplica)
            └── SI → ❌ BLOCKED
                "❌ BLOCKED: Visual identity not configured.
                 This project uses Stitch but has no brand kit or Design System.
                 Without visual identity, designs are generic and inconsistent.

                 Run /visual-setup first to configure:
                 - Brand Kit (colors, typography, CSS tokens)
                 - Design System in Stitch (applied automatically to every screen)
                 - VEG base (visual directives for sub-agents)
                 - Prompt template (reusable structure for Stitch generation)

                 /visual-setup takes ~5 minutes and only needs to run once per project."
                → PARAR. No continuar bajo ninguna circunstancia.

# Verificacion rapida
ls doc/brand/brand_kit/SKILL.md 2>/dev/null
cat .claude/settings.local.json 2>/dev/null | grep -c "designSystemAssetId"

Por que este bloqueo es necesario:

• Sin brand kit, Stitch genera con paleta y tipografia por defecto
• Los diseños resultantes no representan la marca del producto
• design-to-code hereda el estilo generico, creando deuda visual
• Cada pantalla generada sin brand kit es una pantalla que hay que rehacer
• /visual-setup solo se ejecuta UNA VEZ por proyecto (~5 min) y resuelve el problema permanentemente

0.5d Stitch Design Gate (si UC tiene pantallas) (BLOQUEANTE)

REGLA: No se puede generar codigo de presentacion sin diseños Stitch previos. Este gate impide que el agente en modo autopilot salte el paso de diseño.

¿El UC/plan tiene pantallas listadas?
  pantallas = extraer campo "screens" o "pantallas" del UC/plan
  ├── pantallas vacías o no definidas → SKIP (gate no aplica, UC sin UI)
  └── pantallas definidas → Verificar diseños:
      │
      Para cada pantalla listada:
        ¿Existe doc/design/{feature}/*.html con HTML correspondiente?
        ├── SI → OK
        └── NO → Acumular en lista missing_designs[]
      │
      ¿missing_designs está vacío?
      ├── SI → OK — todos los diseños existen, continuar
      └── NO → Verificar campo stitch_designs del plan:
          │
          ¿stitch_designs == "PENDING"?
          ├── SI → ❌ BLOCKED
          │   "❌ BLOCKED: Stitch designs pending for UC-XXX.
          │    The plan has stitch_designs: PENDING — designs were not generated.
          │    Run /plan first to generate Stitch designs, or create them manually
          │    in doc/design/{feature}/ before running /implement."
          │   → PARAR. No continuar bajo ninguna circunstancia.
          └── NO (campo no existe o no es PENDING) → ❌ BLOCKED
              "❌ BLOCKED: No Stitch designs found for UC-XXX.
               Missing designs for screens: {missing_designs[]}
               Expected location: doc/design/{feature}/
               Run /plan first or generate designs manually."
              → PARAR. No continuar bajo ninguna circunstancia.

Verificacion concreta:

# Contar HTMLs de diseño existentes para el feature
ls doc/design/${feature}/*.html 2>/dev/null | wc -l

# Si es 0 y el UC tiene pantallas → BLOCKED

Por que este bloqueo es necesario:

• Sin diseños previos, el design-to-code genera UI sin referencia visual
• El agente en autopilot inventa layouts que no fueron aprobados por el usuario
• Se pierde la trazabilidad diseño → codigo que AG-08 verifica
• El resultado es UI generica en lugar de UI intencional derivada de VEG/Stitch

0.5d.1 Retrofit: Enforcement progresivo para proyectos legacy

Para proyectos con codigo UI pre-v4.2.0, el Design Gate aplica enforcement progresivo basado en el nivel de compliance del proyecto.

¿Existe baseline de design compliance?
  .quality/scripts/design-baseline.sh . → leer enforcementLevel
  │
  ├── L0 (compliance < 30%): Proyecto legacy, mucho codigo sin Stitch
  │   → Paso 0.5d se comporta como WARNING, no BLOCK
  │   → Mensaje: "⚠️ Design compliance L0: {rate}%. UC-XXX no tiene diseños.
  │     Recomendacion: ejecutar /plan para generar diseños antes de implementar.
  │     Este proyecto esta en modo retrofit — el gate no bloquea aun."
  │   → Continuar implementacion (el codigo se genera sin diseño)
  │   → AG-08 Check 6 reporta como INFO, no CRITICAL
  │   → /check-designs muestra deuda de diseño acumulada
  │
  ├── L1 (compliance 30-79%): Proyecto en transicion
  │   → Paso 0.5d BLOQUEA solo si el plan es nuevo (post-v4.2.0)
  │   → Planes legacy (sin campo stitch_designs) → WARNING + continuar
  │   → Planes nuevos (con campo stitch_designs) → BLOCK si PENDING/missing
  │   → AG-08 Check 6: CRITICAL solo en archivos nuevos del diff
  │   → Archivos existentes modificados: WARNING (no CRITICAL)
  │   → complianceRate solo puede subir (ratchet)
  │
  └── L2 (compliance >= 80%): Proyecto alineado
      → Paso 0.5d BLOQUEA siempre (comportamiento estandar)
      → AG-08 Check 6: CRITICAL en todo archivo de presentation/pages/
      → Sin excepciones — el proyecto ya esta alineado

Como migrar de L0 a L2 progresivamente:

1. Fase 1 (L0 → L1): Ejecutar /check-designs para ver deuda. Al implementar features nuevas, usar /plan con Stitch. Cada feature alineada sube el rate. Al alcanzar 30% → upgrade automatico a L1.

2. Fase 2 (L1 → L2): Aprovechar cada modificacion de features existentes para generar diseños Stitch retroactivos. Usar /plan feature:nombre_existente para generar diseños de features legacy que se estan tocando. Al alcanzar 80% → L2.

3. Fase 3 (L2 estable): Todo nuevo codigo pasa por Stitch. La deuda legacy restante se resuelve en sprints dedicados o cuando se toca el codigo.

0.5c Validacion de Trello state (si spec-driven) (BLOQUEANTE)

Solo aplica si el origen es US-XX o UC-XXX (Trello spec-driven).

¿Se llamo start_uc(board_id, uc_id) en Paso 0.1a?
├── SI: Verificar con get_uc(board_id, uc_id) que status == "in_progress"
│   ├── Confirmado: OK — continuar
│   └── No confirmado: ⚠️ WARNING — start_uc pudo haber fallado silenciosamente
│       → Reintentar start_uc una vez
│       → Si falla de nuevo: continuar con WARNING en el log
└── NO (start_uc no fue llamado): ❌ ERROR FATAL
    → "BLOQUEADO: No se llamo start_uc antes de implementar.
       El estado del UC en Trello no refleja que esta en progreso.
       Esto causara inconsistencia en el board."
    → Llamar start_uc ahora como recovery
    → Si falla: PARAR y notificar al usuario

---

Paso 1: Crear Rama de Feature

1.1 Derivar nombre de rama

Del titulo del plan, generar nombre de rama:

Plan: "Gestion de Propiedades"  → feature/gestion-de-propiedades
Plan: "Auth con Google OAuth"   → feature/auth-con-google-oauth
Plan: "Refactor DataSources"    → feature/refactor-datasources

Reglas de naming:

• Prefijo: feature/ (siempre)
• Titulo en kebab-case (minusculas, guiones)
• Sin caracteres especiales ni acentos
• Max 50 caracteres despues del prefijo

1.2 Crear y cambiar a la rama

# Crear rama desde main (o rama base)
git checkout -b feature/{nombre-del-plan} main

# Verificar
git branch --show-current

Si la rama ya existe → Preguntar al usuario: ¿Continuar en la rama existente o crear nueva con sufijo?

---

Paso 2: Orquestacion por Sub-Agentes (Aislamiento Estricto)

REGLA: El orquestador NUNCA implementa codigo. Solo planifica, delega y consolida. Ver rules/GLOBAL_RULES.md seccion "Aislamiento Estricto del Orquestador".

2.1 Mapeo de fases a sub-agentes

Cada fase del plan se ejecuta en un sub-agente (Task) con contexto limpio e independiente.

Fase del plan	Sub-agente	Contexto que recibe
Preparacion DB	AG-03 DB Specialist	Schema del plan + patrones infra/{db}/
Diseño UI	AG-06 Design Specialist	Pantallas del plan + config Stitch
Design-to-code	AG-02 UI/UX Designer	HTMLs generados + patrones del stack
Feature Structure	AG-01 Feature Generator	Seccion de la fase + arquitectura del stack
Apps Script	AG-07 Apps Script	Seccion de la fase + patrones GAS
n8n / Workflows	AG-05 n8n Specialist	Seccion de la fase + patrones n8n
QA / Tests	AG-04 QA Validation	Archivos creados en fases previas (paths)
Quality Audit	AG-08 Quality Auditor	Evidence + baseline
Acceptance Tests	AG-09a Acceptance Tester	PRD con AC-XX + codigo implementado
Acceptance Gate	AG-09b Acceptance Validator	Evidence de AG-09a + audit de AG-08

2.2 Orden de ejecucion (secuencial)

Orquestador: Parsea plan → Extrae fases → Persiste plan en Engram
  |
  ├─ Task(AG-03): DB/Infra → reporte → mem_save → checkpoint
  ├─ Task(AG-06): Diseño Stitch (si aplica) → reporte → checkpoint
  ├─ Task(AG-02): Design-to-code (si aplica) → reporte → checkpoint
  ├─ Task(AG-01): Feature → reporte → mem_save → checkpoint
  ├─ Task(AG-07): Apps Script (si aplica) → reporte → checkpoint
  ├─ Task(AG-05): n8n (si aplica) → reporte → checkpoint
  ├─ Task(Orq.): Integracion (DI, routing) → commit
  ├─ Task(AG-04): QA → reporte → checkpoint
  ├─ Task(AG-08): Quality Audit → veredicto GO/NO-GO
  ├─ Task(AG-09a): Acceptance Tests → evidencia
  ├─ Task(AG-09b): Acceptance Gate → veredicto ACCEPTED/REJECTED
  |
  └─ Orquestador: Consolida → Push → PR → mem_session_summary

2.3 Protocolo de delegacion por fase

Para cada fase, el orquestador ejecuta:

1. PREPARAR contexto (max ~20,000 tokens — v5.24.0 expandido para Opus 4.7):
   - Extraer SOLO la seccion de la fase del plan
   - Cargar overview de arquitectura del stack (~500 words max)
   - Listar archivos que la fase va a modificar (paths, no contenido)
   - Incluir checkpoint de la fase anterior

2. LANZAR sub-agente (Task tool):
   - Contexto limpio e independiente
   - Acceso completo a Read/Write/Edit/Bash
   - Ejecuta lint, build, tests dentro de su contexto

3. RECIBIR reporte estructurado:
   - files_created, files_modified, lint_result, phase_status, errors

4. CONSOLIDAR:
   - mem_save con tags "phase,{N},{feature}"
   - checkpoint.json
   - Si failed → Self-Healing
   - Si complete → commit + siguiente fase
   - DESCARTAR contexto del sub-agente excepto resumen

---

Paso 3: Generar Diseños en Stitch (si faltan)

Solo ejecutar si el plan referencia diseños que NO existen aun.

3.1 Verificar HTMLs existentes

# Buscar HTMLs de diseño referenciados en el plan
ls doc/design/{feature}/*.html 2>/dev/null

3.2 Detectar configuracion Stitch

1. Buscar stitch.projectId en .claude/settings.local.json
2. Si no existe, buscar en ~/.claude/settings.local.json
3. Si no se encuentra → Preguntar al usuario o usar mcp__stitch__list_projects

3.3 Generar pantallas faltantes

Para cada pantalla referenciada en el plan que no tenga HTML:

1. Construir prompt siguiendo la plantilla del engine (ver design/stitch/prompt-template.md)
2. SIEMPRE Light Mode en los prompts
3. Ejecutar generacion:

mcp__stitch__generate_screen_from_text(
  projectId: "[stitch.projectId]",
  prompt: "[prompt construido]",
  deviceType: "[stitch.deviceType]",
  modelId: "[stitch.modelId]"
)

4. Obtener HTML con mcp__stitch__get_screen
5. Guardar en doc/design/{feature}/{screen_name}.html
6. Registrar prompts en doc/design/{feature}/{feature}_stitch_prompts.md

Si hay VEG activo: Enriquecer cada prompt Stitch con las directivas del Pilar 3 (Diseno):

Visual Direction (from VEG - {target_name}):
- Density: {density}, Whitespace: {whitespace}
- Visual hierarchy: {style}, CTA prominence: {prominence}
- Typography: headings {weight}, body {spacing}, hero {scale}
- Section separation: {separation_style}
- Mood: {mood} — this should FEEL {JTBD emocional}
- Data presentation: {data_style}

Image Placeholders (generate with placeholder boxes):
- Hero: [{type}] {description from VEG Pilar 1}
- (mark each with [IMAGE: {id}] for later replacement)

Reglas:

• Una pantalla a la vez (la API tarda minutos)
• NO preguntar entre pantallas (modo autopilot) — generar todas las que falten
• Si falla una pantalla, registrar el error y continuar con las demas
• Reintentar una vez si hay timeout

---

Paso 3.5: Generar Imagenes con MCP (si hay VEG activo)

Prerequisito: VEG activo con prompts de imagen definidos (Pilar 1). Si el MCP de imagenes no esta configurado → registrar prompts pendientes y continuar.

3.5.0 Advertencia de costes

OBLIGATORIO: Antes de generar imagenes, informar al usuario:

📷 VEG Image Generation — {N} imagenes
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Provider configurado: {primary} ({fallback} como fallback)

Coste estimado:
  • Canva (Pro/Premium): €0 adicional (incluido en suscripcion)
  • Freepik (Mystic): Segun plan contratado
  • OpenAI GPT-Image-1: ~$0.02-0.19/imagen → total ~${min}-${max}
  • Gemini Imagen 4: ~$0.02-0.06/imagen → total ~${min}-${max}

¿Continuar con la generacion de imagenes? (s/n/skip)
  s = generar imagenes con MCP
  n = cancelar VEG imagenes completamente
  skip = documentar prompts para generacion manual posterior

Si el provider es canva y el usuario tiene suscripcion activa, el coste es €0 — mencionar explicitamente. Si el usuario elige skip o n → saltar a Paso 3.5.4 (registrar prompts pendientes).

3.5.1 Verificar MCP de imagenes (Health Check)

No basta con leer la config — hay que probar que el MCP responde.

1. Leer veg.image_provider de .claude/settings.local.json
2. Determinar el provider a usar:
   • Si primary: "canva" → intentar Canva MCP
   • Si primary: "freepik" → intentar Freepik MCP
   • Si primary: "lansespirit" → intentar lansespirit MCP
3. Health check obligatorio — intentar una operacion trivial:
   • Canva: llamar mcp__canva__search-designs con query trivial (ej: "test")
   • Freepik: llamar mcp__freepik__check_status o mcp__freepik__search_resources con query trivial
   • lansespirit: llamar mcp__image-gen__generate_image con un prompt de test minimo
   • Si la llamada retorna "tool not found" o error de conexion → MCP no instalado
4. Decision:

   Health check OK?
   ├── SI → Continuar con generacion
   ├── NO (tool not found) → MCP no instalado
   │   ├── Informar: "El MCP '{provider}' no esta configurado en este entorno.
   │   │   Para configurarlo, anadir a .vscode/mcp.json o .claude/settings.json:"
   │   │   {mostrar bloque JSON de configuracion del provider}
   │   │
   │   │   Canva: Solo necesita suscripcion Pro/Premium. Auth via OAuth (browser popup).
   │   │   Freepik: Necesita FREEPIK_API_KEY con plan activo.
   │   │   lansespirit: Necesita OPENAI_API_KEY y/o GOOGLE_API_KEY con billing activo.
   │   └── Saltar a Paso 3.5.4 (registrar prompts pendientes)
   ├── NO (auth error / 401 / 403) → Sesion expirada o suscripcion inactiva
   │   ├── Canva: "La sesion OAuth de Canva expiro. Reconectar en el navegador."
   │   ├── Otros: "Verificar que la API key es valida y tiene creditos."
   │   └── Saltar a Paso 3.5.4
   └── NO (timeout / 500) → intentar fallback
       ├── Si hay fallback configurado → repetir health check con fallback
       └── Si no hay fallback → Paso 3.5.4
   

3.5.2 Generar imagenes

El flujo depende del provider configurado.

Si provider = "canva" (RECOMENDADO — €0 con suscripcion)

Para cada [IMAGE: {id}] identificado en los disenos Stitch:

1. Leer el prompt base del VEG para ese tipo de seccion (hero, features, etc.)
2. Contextualizar con el contenido especifico de la pantalla
3. Construir prompt para Canva generate-design:

   Create a {width}x{height} design: {prompt del VEG}.
   Style: {mood from Pilar 1}. Palette: {palette}. Type: {photography/illustration}.
   This is a standalone visual asset, not a presentation.
   

4. Llamar mcp__canva__generate-design con el prompt
5. Llamar mcp__canva__export-design para exportar como PNG
6. Guardar en: doc/veg/{feature}/assets/{image_id}.png
7. Registrar en: doc/veg/{feature}/image_prompts.md

Dimensiones por tipo de asset:

Tipo	Dimensiones	Uso
Hero	1920x1080	Banner principal, above the fold
Feature illustration	800x800	Secciones de features
Background	1920x1080	Fondos de seccion
Icon/badge	512x512	Iconos decorativos
Social proof	1200x630	Testimonios, logos

Si provider = "freepik"

Para cada [IMAGE: {id}]:

1. Si stockSearchFirst = true: buscar en stock con search_resources
   • Si hay match profesional → download_resource → usar
   • Si no → generar con generate_image (Mystic AI)
2. Guardar y registrar igual que arriba

Si provider = "lansespirit" (fallback de pago)

Para cada [IMAGE: {id}]:

1. Generar con generate_image (OpenAI GPT-Image-1 o Gemini Imagen 4)
   • Imagenes con texto legible → preferir OpenAI
   • Fotorrealismo puro → preferir Gemini Imagen 4 (mas barato)
2. Guardar y registrar igual que arriba

3.5.3 Reglas

• Maximo de imagenes por pantalla: veg.image_provider.maxImagesPerScreen (default 5)
• Prioridad: hero > feature illustrations > social proof > backgrounds > decorativas
• Si el MCP falla mid-generation: registrar prompt + continuar (imagen pendiente)
• Retry: 1 intento. Si falla 2 veces → skip con log
• Budget de contexto: Los prompts de imagen NO se incluyen en el contexto de los sub-agentes. Solo el orquestador ejecuta este paso.
• Canva genera diseños con layers — el export como PNG aplana automaticamente. El resultado es una imagen usable directamente.

3.5.4 Registrar imagenes pendientes (fallback manual)

Si el MCP no estaba disponible, fallo, o el usuario eligio skip:

1. Crear doc/veg/{feature}/PENDING_IMAGES.md:

# Imagenes Pendientes — {feature}

> Generadas por VEG pero no producidas por MCP.
> Usar estos prompts para generar manualmente en Canva, Midjourney, DALL-E, Freepik, etc.

| ID | Tipo | Prompt | Aspect Ratio | Prioridad |
|----|------|--------|-------------|-----------|
| hero | photography | "{prompt completo}" | 16:9 | Alta |
| feature-1 | illustration | "{prompt completo}" | 1:1 | Media |

## Como completar

1. Generar cada imagen con el provider de tu preferencia
2. Guardar en `doc/veg/{feature}/assets/{id}.{ext}`
3. Ejecutar `/implement` de nuevo — detectara las imagenes y las integrara (Paso 6.1b)

## Coste estimado si se usa API

| Provider | Coste/imagen | Total ({N} imagenes) |
|----------|-------------|---------------------|
| Canva (Pro/Premium) | €0 | €0 |
| Freepik Mystic | Segun plan | Segun plan |
| OpenAI GPT-Image-1 | $0.02-0.19 | ${min}-${max} |
| Gemini Imagen 4 | $0.02-0.06 | ${min}-${max} |

2. Mantener placeholders [IMAGE: {id}] en los diseños — el Paso 6.1b los reemplazara cuando las imagenes existan.
3. Log en consola: ⚠️ {N} imagenes pendientes. Ver doc/veg/{feature}/PENDING_IMAGES.md
4. NUEVO: Activar flag de calidad visual degradada:

   veg_images_pending = true
   

   Este flag tiene consecuencias en pasos posteriores:
   • Paso 7.6 (AG-08 Quality Audit): Si veg_images_pending == true:
     • AG-08 verdict = CONDITIONAL GO como maximo (nunca GO pleno)
     • Razon: "VEG Pilar 1 no completado — {N} imagenes usan placeholders CSS"
     • AG-08 DEBE listar las imagenes pendientes en su report
   • Paso 8 (PR body): Anadir banner visible:

     > ⚠️ **VEG Pilar 1 incompleto**: Este PR usa {N} imagenes placeholder.
     > Las imagenes profesionales deben generarse antes del deploy a produccion.
     > Ver `doc/veg/{feature}/PENDING_IMAGES.md` para prompts listos.
     

   • Paso 8.5 (Auto-merge): Auto-merge BLOQUEADO si veg_images_pending == true
     • Razon: "No se puede auto-merge con imagenes placeholder — calidad visual degradada"
     • El usuario puede aprobar manualmente si acepta el estado visual actual

3.5.5 Prohibicion de placeholders CSS como sustituto de imagenes VEG

REGLA: Cuando el VEG especifica imagenes (Pilar 1), los sub-agentes NO pueden sustituirlas por gradientes CSS, iconos SVG inline, o iniciales de texto como "solucion". Estas tecnicas son aceptables SOLO si el VEG no existe o no especifica imagenes.

¿El proyecto tiene VEG con Pilar 1 (Imagenes)?
├── SI: Las secciones que requieren imagenes DEBEN usar:
│   ├── Imagenes reales de doc/veg/{feature}/assets/ (si existen)
│   ├── Placeholders <img> con src apuntando a PENDING_IMAGES paths (si no existen)
│   └── NUNCA: gradientes CSS, divs con colores, iconos como sustituto de fotos
└── NO: Libre de usar cualquier tecnica visual

---

Paso 4: Design-to-Code (si hay disenos)

Convertir los HTML de Stitch a codigo del stack del proyecto.

4.0 Instalar dependencias VEG Motion (si hay VEG activo)

OBLIGATORIO antes de escribir codigo con animaciones. Verificar e instalar:

¿El VEG tiene motion habilitado (motion_level != none)?
├── SI → Verificar e instalar dependencias:
│   ├── Flutter:
│   │   ├── Leer pubspec.yaml → ¿tiene flutter_animate?
│   │   ├── NO → ejecutar: flutter pub add flutter_animate
│   │   └── SI → verificar version compatible (^4.5.2)
│   ├── React:
│   │   ├── Leer package.json → ¿tiene motion?
│   │   ├── NO → ejecutar: npm install motion
│   │   └── SI → verificar version compatible (^12.35.0)
│   └── Python / Apps Script → N/A (sin motion library)
└── NO → Saltar (no hay animaciones que implementar)

Si la instalacion falla → WARNING, continuar design-to-code SIN animaciones. Registrar en log: ⚠️ No se pudo instalar {package}. Design-to-code sin VEG Motion.

4.1 Listar HTMLs disponibles

ls doc/design/{feature}/*.html

4.2 Conversion por stack

Si hay VEG activo, incluir el Motion Catalog (Pilar 2) en el contexto del sub-agente AG-02:

VEG Motion Catalog:
  page_enter: {animation} {duration}ms {easing}
  scroll_reveal: {animation} stagger {delay}ms
  hover_buttons: {animation} {duration}ms
  loading: {style}
  transitions_pages: {type} {duration}ms
  feedback_success: {animation}
  feedback_error: {animation}
  motion_level: {subtle / moderate / expressive}

Motion level rules:
  - subtle: ONLY page_enter + loading. Skip scroll, hover, feedback.
  - moderate: All except feedback animations.
  - expressive: Full catalog.

Para cada HTML de diseno:

Flutter

1. Leer HTML y extraer: layout, componentes, colores, espaciado, tipografia
2. Crear widgets en la estructura del feature:
   • lib/presentation/features/{feature}/widgets/ para widgets especificos
   • lib/core/widgets/ para widgets reutilizables (si se identifican)
3. Respetar:
   • AppColors y AppSpacing (nunca hardcodear)
   • Responsividad: mobile/tablet/desktop layouts
   • Clases separadas (NUNCA metodos _buildX())
4. Si hay VEG Motion: Aplicar animaciones usando flutter_animate:
   • Importar package:flutter_animate/flutter_animate.dart
   • Usar .animate() chainable para cada tipo de animacion del catalogo
   • Loading states: usar el estilo VEG (skeleton = shimmer + Container, shimmer = .shimmer())
   • NO anadir animaciones que no esten en el catalogo VEG
   • Mobile hover enforcement: Si el proyecto es mobile-first o el VEG target es mobile:
     • NO usar MouseRegion para hover effects
     • Reemplazar hover → GestureDetector con onTapDown/onTapUp para feedback tactil
     • Si se necesita hover en desktop: usar LayoutBuilder para detectar plataforma

React

1. Leer HTML y extraer: estructura JSX, clases CSS, componentes
2. Crear componentes en:
   • src/components/features/{feature}/ para componentes especificos
   • src/components/ui/ para primitivos reutilizables
3. Respetar:
   • Server Components por defecto, 'use client' solo si necesita interactividad
   • Tailwind CSS para estilos
   • TypeScript obligatorio
4. Si hay VEG Motion: Aplicar animaciones usando motion (ex Framer Motion):
   • Importar { motion, AnimatePresence } de "motion/react"
   • Definir variants como constantes reutilizables
   • whileInView para scroll_reveal, whileHover para hover effects
   • AnimatePresence para page transitions y exit animations
   • NO anadir animaciones que no esten en el catalogo VEG
   • Mobile hover enforcement: Si el proyecto es mobile-first o el VEG target es mobile:
     • Reemplazar whileHover → whileTap en todos los componentes interactivos
     • Si se necesita hover en desktop: usar media query @media (hover: hover) para aplicar condicionalmente
     • NUNCA dejar whileHover sin alternativa whileTap en un proyecto responsive

Google Apps Script

1. Leer HTML y extraer: estructura, estilos, interacciones
2. Crear templates en:
   • src/html/ o html/ para templates HtmlService
3. Respetar:
   • google.script.run para comunicacion con backend
   • CSS inline o <style> en el template
   • <?!= include('css') ?> para estilos compartidos

Python (FastAPI)

1. Si hay frontend (Jinja2/NiceGUI):
   • Convertir HTML a templates Jinja2 o componentes NiceGUI
2. Si es API-only: saltar design-to-code

4.3 Traceability comment (OBLIGATORIO)

Cada archivo de pagina/pantalla generado por design-to-code DEBE incluir un comentario de trazabilidad en las primeras lineas:

// Generated from: doc/design/{feature}/{screen}.html

// Generated from: doc/design/{feature}/{screen}.html

# Generated from: doc/design/{feature}/{screen}.html

Regla: Si el archivo no tiene este comentario, AG-08 lo reportara como violacion de trazabilidad en el Check 6 (Design Traceability).

4.4 Commit parcial de diseños

git add doc/design/{feature}/
git commit -m "design: add Stitch designs for {feature}"

---

Execution Strategy: Task Isolation with Context Budget

CRITICAL: Each phase MUST be executed in an isolated Task to prevent context saturation.

Context Budget per Phase

Each spawned Task has a context budget. The main agent MUST control what goes into each task.

Concepto	Budget máximo	Notas
Phase description	~1,500 tokens	Del plan, sección completa de la fase (v5.24.0: ampliado para incluir edge cases)
Architecture rules	~4,500 tokens	Overview del stack + patrones relevantes para la fase
Relevant source files	~11,000 tokens	Archivos que la fase modifica + dependencias cercanas (v5.24.0: permite contexto más rico)
Stack patterns	~2,500 tokens	Patterns relevantes (ej: BLoC + repository + testing si es state mgmt)
Checkpoint state	~500 tokens	JSON del checkpoint anterior + resumen de fases completadas
Total per task	~20,000 tokens	~2% de ventana de Opus 4.7 (1M context) — v5.24.0: expandido de ~8,700

Context Loading Rules

INCLUIR en el Task:

• Descripción de la fase (copiada literalmente del plan)
• File ownership del agente asignado a esta fase
• Archivos existentes que la fase va a MODIFICAR (contenido actual)
• Reglas de arquitectura del stack detectado (solo el overview, no todos los docs)
• Checkpoint de la fase anterior (si existe)

EXCLUIR del Task (nunca cargar):

• Código de fases anteriores ya completadas
• Archivos que la fase no va a tocar
• Logs, evidence, baselines, healing history
• Otros planes, PRDs, o documentación no relacionada
• Código generado (.g.dart, .freezed.dart, node_modules, build/)
• README, CHANGELOG, o documentación del engine

EXCLUIR de la respuesta del Task (poda de retorno):

• Contenido completo de archivos creados (solo devolver paths)
• Stack traces completos (solo primeras 10 líneas si hay error)
• Output completo de lint (solo resumen: N errors, N warnings)

Phase Task Template

Para cada fase, el main agent spawnea un Task con exactamente este formato:

Execute Phase {N}: {phase_name}

CONTEXT:
- Plan: {paste ONLY the phase section, not the full plan}
- Stack: {stack_name}
- Architecture: {paste overview paragraph, max 500 words}
- Files to modify: {list paths}
- Ownership: Only modify files in {ownership_paths}

RULES:
- Run lint after implementation: {stack_lint_command}
- Save checkpoint: node .claude/hooks/implement-checkpoint.mjs {feature} {N} {phase_name}
- If lint fails, apply self-healing (Level 1 first, then Level 2)

RETURN FORMAT:
- files_created: [list of paths]
- files_modified: [list of paths]
- lint_result: pass|fail (N errors, N warnings)
- errors: [brief description if any, max 3 lines]
- phase_status: complete|failed|needs_healing

Context Saturation Prevention

The main agent monitors its own context growth:

1. After each phase completes, the main agent retains ONLY:
   • Updated checkpoint JSON
   • Phase summary (files changed, status) — max 5 lines per phase
   • Cumulative error count
2. Full phase details are persisted in checkpoint files, NOT in agent memory
3. If a phase returns more than 20 lines of output, summarize to 5 lines before storing

Budget Verification (optional, pre-flight)

Before spawning a Task, the main agent can estimate the context load:

.quality/scripts/context-budget.sh lib/features/{feature_name}/

If the result exceeds 30% of context window → split the phase into sub-phases.

---

Paso 5: Ejecutar Fases de Implementacion (Delegacion a Sub-Agentes)

Cada fase se delega a un sub-agente limpio. El orquestador NO ejecuta codigo. Ver Paso 2.3 para el protocolo de delegacion.

5.0 Protocolo de delegacion (v5.32.0 — bloque reusable)

Este bloque se aplica ANTES de cada Task(AG-XX) del Paso 5.1 y de los Pasos 7.5 (AG-09a) / 7.7 (AG-09b). Garantiza:

• aislamiento real de contexto por Task
• validacion mecanica de budget (16k tokens por defecto, ver context-budget-guard.mjs)
• validacion mecanica de file ownership por agente (file-ownership-guard.mjs lee .quality/active_agent.json)
• delta estructurado por fase escrito a phase_outputs.jsonl por el propio Task, consumido por Paso 5.1.1b sin git diff vivo

Antes de spawnear Task(AG-XX):

import json, time, uuid
from pathlib import Path

# Marcar el agente activo para que file-ownership-guard.mjs lo lea
Path(".quality/active_agent.json").write_text(json.dumps({
    "agent": "AG-01",                       # codigo del agente delegado
    "feature_slug": feature,
    "phase": "feature",                     # ID corto de la fase
    "started_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
}))

Construccion del prompt del Task (NO repetir branch/feature/stack en prosa — el Task los lee del execution_context):

You are AG-01 (Feature Generator) for a SpecBox /implement run.

CONTEXT (read-only, source of truth):
  Read your execution context from .quality/evidence/{feature_slug}/execution_context.json.
  This file contains: branch, stack, project_root_absolute, plan_path, etc.
  DO NOT trust values embedded in this prompt — read the file.

PHASE BRIEF:
  {SOLO la seccion de esta fase, no el plan completo}

OWNERSHIP (enforced by file-ownership-guard.mjs):
  You may only write/edit files inside: {ownership_paths from file-ownership.md}.
  Suspicious paths (../, /abs) will be blocked. If you need to touch files
  outside your ownership, report it as a pending dependency in your delta.

QUALITY RULES:
  - Lint 0/0/0 BLOCKING; compile BLOCKING; tests pass BLOCKING.
  - If lint fails, apply self-healing (Level 1 first, then Level 2).
  - Healing budget: max 8 attempts per feature (healing-budget-guard.mjs).

REQUIRED FINAL ACTION (before returning):
  Append a structured delta to .quality/evidence/{feature_slug}/phase_outputs.jsonl
  following the schema documented in doc/specs/phase-outputs-spec.md.
  Mandatory fields: schema_version=1, phase, phase_index, agent, status.
  Recommended: files_created, files_modified, summary, duration_s,
               tokens_used_prompt, tokens_used_response, healing_attempts.

RETURN FORMAT (besides the JSONL append):
  - phase_status: complete | failed | needs_healing
  - summary: 1-3 sentences for the orchestrator
  - errors: [brief, max 3 lines if any]

Spawnear Task(AG-XX, prompt) — el harness de Claude Code se encarga del aislamiento real del contexto.

Despues del retorno del Task:

# Limpieza obligatoria del marcador de agente activo
try:
    Path(".quality/active_agent.json").unlink()
except FileNotFoundError:
    pass

# Bumpear el contador de telemetria local
# context-budget-guard.mjs ya bumpeo tasks_run_total al spawnearlo;
# aqui actualizamos last_feature_slug.
isolation_cache = Path(".quality/task_isolation.json")
data = json.loads(isolation_cache.read_text()) if isolation_cache.exists() else {}
data["enabled"] = True
data["last_feature_slug"] = feature
data["last_event_at"] = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
isolation_cache.parent.mkdir(parents=True, exist_ok=True)
isolation_cache.write_text(json.dumps(data, indent=2))

Si el Task falla / crashea: el try/finally debe garantizar siempre la limpieza de active_agent.json. El siguiente Task encontrara el archivo borrado y operara con guard en modo no-op (no asume agente activo).

5.1 Para cada fase del plan

El orquestador lanza un Task por fase con el Phase Task Template:

Execute Phase {N}: {phase_name}

CONTEXT:
- Plan: {SOLO la seccion de esta fase, no el plan completo}
- Stack: {stack_name}
- Architecture: {overview del stack, max 500 words}
- Files to modify: {list paths}
- Ownership: Only modify files in {ownership_paths}
- Previous checkpoint: {checkpoint JSON de fase N-1}

RULES:
- Run lint after implementation: {stack_lint_command}
- Quality gate: lint 0/0/0 (BLOQUEANTE), compile (BLOQUEANTE), tests pass (BLOQUEANTE)
- Save checkpoint: node .claude/hooks/implement-checkpoint.mjs {feature} {N} {phase_name}
- If lint fails, apply self-healing (Level 1 first, then Level 2)

RETURN FORMAT (OBLIGATORIO):
- files_created: [list of paths]
- files_modified: [list of paths]
- lint_result: pass|fail (N errors, N warnings)
- gate_result: {lint, compile, tests} each pass|fail
- errors: [brief description if any, max 3 lines]
- phase_status: complete|failed|needs_healing

5.1.1 Post-Task (orquestador)

¿phase_status?
├── complete → Commit parcial + mem_save resumen + siguiente fase
├── needs_healing → Lanzar nuevo Task de healing (ver Self-Healing Protocol)
└── failed → Guardar checkpoint failed + escalar a humano

5.1.1a Pipeline State Update (Post-Phase) — v5.19.0 Mechanical Enforcement

Despues de guardar el checkpoint, SIEMPRE actualizar pipeline_state.json para que pipeline-phase-guard.mjs pueda validar la secuencia de fases mecanicamente:

# Leer estado actual o crear nuevo
PIPELINE_STATE=".quality/evidence/${feature}/pipeline_state.json"
mkdir -p ".quality/evidence/${feature}"

El orquestador mantiene y actualiza este archivo despues de CADA fase completada:

{
  "feature": "${feature}",
  "has_ui": true,
  "has_db": true,
  "completed_phases": ["db_infra", "stitch_designs", "design_to_code", "feature_code"],
  "current_phase": "integration",
  "last_updated": "2026-04-05T18:00:00Z"
}

Mapeo de fases del plan a IDs de pipeline_state:

Fase del plan	ID en completed_phases	Condicion
DB/Infra (AG-03)	db_infra	Solo si el plan tiene fase DB
Stitch Designs (AG-06)	stitch_designs	Solo si proyecto tiene UI
Design-to-Code (AG-02)	design_to_code	Solo si proyecto tiene UI
Feature Code (AG-01)	feature_code	Siempre
Apps Script (AG-07)	appscript	Solo si aplica
n8n (AG-05)	n8n	Solo si aplica
Integration/DI	integration	Siempre (si hay fase)
QA/Tests (AG-04)	tests	Siempre

IMPORTANTE: Si una fase no aplica al proyecto (ej: no hay DB), marcarla como completada al inicio para que el guard no bloquee las fases dependientes:

// Ejemplo: proyecto sin DB ni UI
{
  "completed_phases": ["db_infra", "stitch_designs", "design_to_code"],
  "has_ui": false,
  "has_db": false
}

Esto permite que pipeline-phase-guard.mjs valide el orden sin falsos positivos.

5.1.1b Implementation Delta (Post-Phase) — v5.0 Spec-Code Sync (v5.32.0 update)

v5.32.0: la fuente de verdad para los deltas paso de "lo que el orquestador observa via git diff" a phase_outputs.jsonl. El propio Task escribe su delta al final de su corrida (Paso 5.0 lo exige), asi que aqui solo agregamos. Esto sobrevive a Tasks aislados que escriben en otra sesion.

Despues de guardar el checkpoint, agregar el delta block:

from server.implement_context import aggregate_for_spec_sync

# Lee phase_outputs.jsonl y devuelve el SpecSyncAggregate
agg = aggregate_for_spec_sync(feature)

# agg.overall_status ∈ {ok, partial, error, empty}
# agg.delta_count                              — files tocados (sum across phases)
# agg.files_created / files_modified / files_deleted   — listas dedupeadas
# agg.phases                                   — uno por fase, en orden de ejecucion
# agg.total_duration_s, agg.total_healing_attempts

Reglas de uso:

• Si agg.overall_status == "error" → linea: "Fase {phase} fallida — pendiente de resolucion"
• Si agg.total_healing_attempts > 0 → linea adicional con count y nivel maximo
• Si todo conforme al plan → linea: "Sin deltas — implementacion conforme al plan"

El orquestador YA NO mantiene implementation_deltas: list[str] en memoria. Cualquier consulta posterior (Paso 7.7a, Paso 8.5.1a) re-llama a aggregate_for_spec_sync(feature) — la fuente esta en disco.

IMPORTANTE: Este paso es informativo (nunca bloquea). Si phase_outputs.jsonl no existe (Task legacy que no lo escribio), aggregate_for_spec_sync retorna overall_status="empty" y el orquestador continua con la observacion via git diff como fallback (compat con flujo pre-v5.32).

5.2 Reglas por stack durante implementacion

Flutter

# Despues de cada modificacion .dart
dart fix --apply && dart analyze

# Despues de build_runner (Freezed, etc.)
dart run build_runner build --delete-conflicting-outputs && dart fix --apply

React

# Despues de cambios
npx eslint . --fix && npx tsc --noEmit

Python

# Despues de cambios
ruff check . --fix && ruff format . && mypy .

Google Apps Script

# Despues de cambios
npm run lint && npm run build

5.3 Commits parciales por fase

Cada fase completada genera un commit:

# Formato: tipo(scope): descripcion
git add [archivos-de-la-fase]
git commit -m "feat({feature}): {descripcion de la fase}"

Tipos de commit:

• feat: Nueva funcionalidad
• fix: Correccion
• refactor: Reestructuracion
• chore: Configuracion, dependencias
• test: Tests
• design: Diseños UI

---

Paso 6: Integracion

Tareas transversales post-implementacion.

6.1 Registrar en DI / Routing / Config

Segun el stack:

Stack	Accion
Flutter	Registrar en GetIt/Injectable, anadir GoRoutes
React	Actualizar App Router, registrar stores
Python	Registrar routers en main.py, actualizar DI
Apps Script	Exportar funciones en index.ts, actualizar appsscript.json scopes

6.1b Registrar assets VEG (si hay imagenes generadas)

Si el Paso 3.5 genero imagenes en doc/veg/{feature}/assets/:

Stack	Accion
Flutter	Copiar a assets/images/veg/ + registrar en pubspec.yaml assets
React	Copiar a public/images/veg/ o src/assets/veg/ + importar en componentes
Python	Copiar a static/images/veg/ (si tiene frontend)
Apps Script	Subir a Google Drive o embeber como base64 en HTML

Referenciar las imagenes en los widgets/componentes generados en Paso 4, reemplazando los placeholders [IMAGE: {id}] con las rutas reales.

6.2 Build final

# Flutter
dart run build_runner build --delete-conflicting-outputs
dart fix --apply && dart analyze

# React
npm run build

# Python
ruff check . --fix && mypy .

# Apps Script
npm run build

6.3 Commit de integracion

git add .
git commit -m "chore({feature}): integration and wiring"

---

Paso 7: QA y Validacion

7.1 Ejecutar tests

# Flutter
flutter test --coverage
lcov -l coverage/lcov.info | tail -1  # Verificar >= 85%

# React
npx jest --coverage --passWithNoTests

# Python
pytest --cov --cov-report=term-missing

# Apps Script
npm run test

7.2 Verificar coverage minimo

Cobertura minima: 85%

Si la cobertura es menor:

1. Identificar archivos sin cobertura
2. Generar tests adicionales
3. Re-ejecutar hasta alcanzar 85%

7.3 Lint final

# Flutter
dart analyze

# React
npx eslint . && npx tsc --noEmit

# Python
ruff check . && mypy .

# Apps Script
npm run lint

7.4 Commit de tests

git add .
git commit -m "test({feature}): add tests with 85%+ coverage"

---

Paso 7.5: Acceptance Tests con Gherkin BDD (AG-09a)

Generar y ejecutar tests BDD en formato Gherkin que validen acceptance criteria del PRD. PRD es OBLIGATORIO. Sin PRD no hay AC-XX → no hay acceptance tests → pipeline PARA.

7.5.1 Localizar PRD

¿Cómo encontrar el PRD?
├── Spec-Driven (Trello/Plane/FreeForm)
│   └── get_evidence(board_id, us_id, "us", "prd") → extraer PRD adjunto
├── Existe doc/prd/{feature}.md o doc/prd/PRD_{feature}.md
│   └── Leer directamente
├── Existe en attachment de la US card/item
│   └── Descargar y leer
└── No se encuentra PRD en NINGUNA ubicacion
    └── ERROR FATAL: "No PRD found. Cannot validate acceptance criteria."
    └── PARAR PIPELINE — no continuar sin PRD
    └── Reportar al usuario: "PRD requerido. Ejecutar /prd primero."

Extraer sección "Criterios de Aceptación > Funcionales":

• Extraer cada AC-XX con su descripción
• Ignorar sección "Técnicos"
• Si no hay criterios AC-XX en el PRD → ERROR FATAL, PARAR pipeline

7.5.2 Generar archivos .feature

Delegar a AG-09a (ver agents/acceptance-tester.md).

Generar un archivo .feature por cada UC del plan actual, con un Escenario por cada AC-XX:

# language: es
@US-XX @UC-XXX
Característica: {Título del UC-XXX}

  @AC-01
  Escenario: {Descripción del AC-01}
    Dado ...
    Cuando ...
    Entonces ...

  @AC-02
  Escenario: {Descripción del AC-02}
    Dado ...
    Cuando ...
    Entonces ...

Reglas:

• Tags obligatorios: @US-XX, @UC-XXX, @AC-XX en cada escenario
• Idioma obligatorio: # language: es
• Un .feature por UC, un Escenario por AC-XX

Ubicación por stack:

Stack	Directorio
Flutter	test/acceptance/features/
React	tests/acceptance/features/
Python	tests/acceptance/features/
GAS	tests/acceptance/features/

7.5.3 Generar step definitions

Generar step definitions usando el framework BDD nativo del stack:

Flutter (Playwright E2E contra CanvasKit web build):

• Step file: e2e/acceptance/steps/UC-XXX_steps.ts
• Framework: playwright-bdd + @playwright/test
• Reutilizar e2e/acceptance/steps/common_steps.ts si existe
• Screenshot: via evidenceStep() en cada paso (PASS y FAIL)
• Traces: retain-on-failure
• Reporter: html + json (OBLIGATORIO ambos)
• Pre-requisito: flutter build web --web-renderer canvaskit --release
• Selectores: getByRole() semánticos (CanvasKit no genera DOM)

React (Playwright E2E real):

• Step file: tests/acceptance/steps/UC-XXX_steps.ts
• Framework: playwright-bdd + @playwright/test
• Reutilizar tests/acceptance/steps/common_steps.ts si existe
• Screenshot: via evidenceStep() en cada paso (PASS y FAIL)
• Traces: retain-on-failure
• Reporter: html + json (OBLIGATORIO ambos)

Python (pytest-bdd):

• Step file: tests/acceptance/steps/UC_XXX_steps.py
• Framework: pytest-bdd
• Reutilizar tests/acceptance/steps/common_steps.py si existe
• Evidence: request/response log por escenario

GAS (jest-cucumber):

• Step file: tests/acceptance/steps/UC-XXX_steps.ts
• Framework: jest-cucumber
• Reutilizar tests/acceptance/steps/common_steps.ts si existe

7.5.4 Instalar dependencias BDD (si no están)

Verificar que las dependencias BDD están instaladas. Si no, instalarlas:

# Flutter
flutter pub add --dev bdd_widget_test

# React
npm install -D playwright-bdd

# Python
pip install pytest-bdd

# GAS
npm install -D jest-cucumber

7.5.5 Ejecutar tests

# Flutter
flutter test test/acceptance/ --reporter json > reports/cucumber-report.json

# React
npx bddgen && npx playwright test tests/acceptance/ --reporter=json

# Python
pytest tests/acceptance/ --cucumberjson=reports/cucumber-report.json

# GAS
npx jest tests/acceptance/ --json --outputFile=reports/cucumber-report.json

7.5.6 Recopilar evidencia

Guardar en .quality/evidence/{feature}/acceptance/:

• Screenshots automáticos en cada Escenario (AC-01.png, AC-02.png...)
• JSON report en formato Cucumber estándar (cucumber-report.json)
• Traces (solo Playwright)

7.5.7 Generar HTML Evidence Report (Flutter y React OBLIGATORIO)

Para Flutter y React, generar informe HTML self-contained con screenshots base64. El humano abre este archivo en su browser para validar calidad visual del E2E.

1. Leer results.json de .quality/evidence/{feature}/acceptance/
2. Para cada AC-XX con screenshot → leer PNG, convertir a base64
3. Generar HTML usando el template definido en agents/acceptance-tester.md seccion 8
4. Guardar en .quality/evidence/{feature}/acceptance/e2e-evidence-report.html

El informe DEBE incluir:

• Pass rate (%) con color verde/amarillo/rojo
• Card por cada AC-XX con: status badge, screenshot embebido, steps, duration
• Error details con stack trace para los FAIL
• Resumen de viewports testeados

7.5.8 Generar PDF de evidencia

Generar PDF con estructura:

• Titulo: Acceptance Tests — {feature} / UC-XXX
• Resumen: Total escenarios, pasados, fallidos, pass rate
• Tabla AC: AC-XX | Descripcion | Resultado (PASS/FAIL)
• Detalle por escenario: Steps ejecutados, screenshot path, logs
• Footer: Timestamp, branch, commit SHA

Guardar en .quality/evidence/{feature}/acceptance/acceptance-report.pdf

7.5.9 Adjuntar evidencia (si spec-driven)

Si el flujo es spec-driven (tiene board_id y UC card):

attach_evidence(board_id, uc_card_id, "uc", "acceptance", pdf_path)

Agregar comentario estructurado en la card del UC:

Acceptance Tests — UC-XXX
{N} passed / {M} failed | Pass rate: XX%
Evidencia adjunta: acceptance-report.pdf
HTML report: .quality/evidence/{feature}/acceptance/e2e-evidence-report.html

7.5.10 Commit

git add test/acceptance/ tests/acceptance/ e2e/acceptance/ .quality/evidence/{feature}/acceptance/
git commit -m "test(acceptance): E2E acceptance tests + evidence report for UC-XXX"

NOTA: Si los acceptance tests fallan, NO bloquear aqui. Reportar fallos y dejar que AG-09b decida el veredicto en Paso 7.7.

---

Paso 7.6: Quality Audit (AG-08)

Ejecutar AG-08 Quality Auditor para verificar calidad de código. Ver agents/quality-auditor.md para checks completos.

Ejecutar audit completo:

1. Test Quality Audit (tests reales, no triviales)
2. Coverage Legitimacy Audit (sin exclusiones tramposas)
3. Architecture Compliance Audit (capas respetadas)
4. Convention Compliance Audit (patrones del stack)
5. Dead Code Detection (no aumentó)

Generar .quality/evidence/{feature}/audit.json y .quality/evidence/{feature}/report.md.

Emitir veredicto: GO / CONDITIONAL GO / NO-GO

Si NO-GO → Aplicar self-healing (ver Self-Healing Protocol) y re-auditar. Máximo 2 intentos.

---

Paso 7.7: Acceptance Gate (AG-09b)

Validación independiente de que la feature cumple los acceptance criteria. PRD es obligatorio (Paso 7.5 ya lo verifico). Si llegamos aqui, el PRD existe.

7.7.1 Ejecutar AG-09b Acceptance Validator

Delegar a AG-09b (ver agents/acceptance-validator.md). El validador recibe:

• PRD con AC-XX (misma fuente que 7.5.1)
• git diff main..HEAD (código implementado)
• Resultados de tests unitarios (AG-04, Paso 7)
• Resultados de acceptance tests (AG-09a, Paso 7.5)
• Screenshots/evidencia generada
• audit.json de AG-08 (Paso 7.6)

7.7.2 Evaluar veredicto

ACCEPTED    → Continuar a Paso 8 (crear PR)
CONDITIONAL → Healing (ver 7.7.3), luego re-validar
REJECTED    → Healing (ver 7.7.3), luego re-validar

7.7.3 Healing de Acceptance

Si CONDITIONAL o REJECTED:

1. Leer acceptance-report.json → identificar criterios FAIL
2. Para cada criterio FAIL:
   • Falta código → implementar lo faltante
   • Falta test → AG-09a regenera solo los fallidos
   • Test falla → corregir implementación o test
3. Re-ejecutar acceptance tests (solo los fallidos)
4. Re-ejecutar validaciones: lint + compile + AG-09b
5. Máximo 2 intentos de healing de acceptance
6. Si tras 2 intentos sigue REJECTED → reportar al humano con acceptance-report.md

7.7.4 Registrar healing

node .claude/hooks/implement-healing.mjs {feature} acceptance {level} "{action}" "{result}"

7.7a Implementation Status — modo freeform (v5.0 Spec-Code Sync)

Si el pipeline NO es spec-driven (no hay board_id ni Trello/Plane configurado):

1. Verificar que implementation_deltas[] tiene al menos 1 entrada
2. Derivar uc_id del nombre del plan (e.g. uc_001_plan.md → UC-001) o usar "FREEFORM"
3. Obtener branch name actual: git rev-parse --abbrev-ref HEAD
4. Buscar PRD en doc/prds/ usando find_prd_path(project_path, feature=feature_name)
5. Si PRD encontrado: ejecutar append_implementation_status(prd_path, uc_id, branch, implementation_deltas)
6. Commit del PRD actualizado:

   git add doc/prds/{prd_file}
   git commit -m "docs({feature}): add Implementation Status for {uc_id}"
   

7. Si no se encuentra PRD → WARNING en output, no bloquear

IMPORTANTE: En modo spec-driven, este paso se ejecuta en 8.5.3a en su lugar.

---

Paso 8: Crear Pull Request

8.1 Push de la rama

git push -u origin feature/{nombre-del-plan}

8.2 Generar resumen de PR

Analizar todos los commits de la rama para generar el body:

# Ver commits de la rama
git log main..HEAD --oneline

# Ver archivos cambiados
git diff main..HEAD --stat

8.3 Crear PR

gh pr create \
  --title "[Feature] {Titulo del plan}" \
  --body "$(cat <<'EOF'
## Summary

{Resumen del plan en 2-3 bullet points}

## Changes

{Lista de cambios principales agrupados por fase}

## Stitch Designs

{Si aplica: lista de pantallas generadas con links a HTMLs}

## Acceptance Evidence

{Generar tabla desde acceptance-report.json de AG-09b. Si no hay PRD/AC-XX, omitir sección.}

| Criterio | Status | Evidencia |
|----------|--------|-----------|
| AC-01: {descripción} | ✅ PASS | [screenshot](evidence/AC-01.png) |
| AC-02: {descripción} | ✅ PASS | [screenshot](evidence/AC-02.png) |
| AC-XX: {descripción} | ⚠️ CONDITIONAL | [trace](evidence/AC-XX_trace.zip) |

**AG-09 Verdict**: {ACCEPTED / CONDITIONAL / REJECTED}
**AG-08 Verdict**: {GO / CONDITIONAL GO / NO-GO}

## Test Plan

- [ ] Tests unitarios pasan con 85%+ coverage
- [ ] Lint sin errores
- [ ] Build exitoso
- [ ] Acceptance tests pasan
- [ ] {Criterios adicionales del plan}

## Developer Feedback

{Si existe .quality/evidence/${feature}/feedback-summary.json con open > 0:}

| ID | Severity | AC-XX | Status | GitHub |
|----|----------|-------|--------|--------|
{Fila por cada FB-NNN open}

{Si no hay feedback o todos resueltos: "No developer feedback reported."}

## Plan Reference

`{path al plan}`

---
🤖 Implementado con [SpecBox Engine](https://github.com/jesusperezdeveloper/specbox-engine) `/implement`
EOF
)"

8.4 Vincular con work item (si aplica)

Si el plan referencia un work item de Plane/Trello:

• Anadir link a la PR en un comentario del work item
• Actualizar estado a "En Pruebas"

---

Paso 8.5: Merge Secuencial (Post-PR)

Si estamos en modo autopilot (ejecutando múltiples cards en secuencia), merge antes de iniciar la siguiente card. Esto evita conflictos entre PRs.

8.5.0 Validacion pre-merge (BLOQUEANTES)

Estas validaciones se ejecutan ANTES de verificar condiciones de auto-merge. Son HARD BLOCKS — si fallan, el merge NO puede proceder bajo ninguna circunstancia.

VALIDACION 1: ¿Estamos en una rama feature/?
  branch = git branch --show-current
  ¿branch empieza con "feature/"?
  ├── SI: OK
  └── NO: ❌ ERROR FATAL
      → "BLOQUEADO: No se puede hacer merge desde '{branch}'.
         El protocolo requiere una rama feature/ con PR asociada.
         Algo salto el Paso 1 (Crear Rama de Feature)."
      → PARAR INMEDIATAMENTE.

VALIDACION 2: ¿Existe PR abierta para esta rama?
  gh pr view --json state,url 2>/dev/null
  ¿Existe PR con state == "OPEN"?
  ├── SI: OK — guardar URL para referencia
  └── NO: ❌ ERROR FATAL
      → "BLOQUEADO: No hay PR abierta para la rama actual.
         El Paso 8 debio crear una PR antes de llegar aqui.
         Sin PR no hay acceptance evidence ni review."
      → PARAR. Ofrecer ejecutar Paso 8 como recovery.

VALIDACION 3 (solo Trello spec-driven): ¿El UC esta en estado correcto?
  uc_data = get_uc(board_id, uc_id)
  ¿uc_data.status == "in_progress"?
  ├── SI: OK — el UC fue iniciado correctamente con start_uc
  └── NO: ⚠️ WARNING
      → "El UC {uc_id} esta en estado '{uc_data.status}' en lugar de 'in_progress'.
         Esto indica que start_uc no fue llamado o fallo."
      → Intentar start_uc como recovery
      → Continuar con WARNING en el log

VALIDACION 4: ¿El flag veg_images_pending esta activo?
  ¿veg_images_pending == true?
  ├── SI: Auto-merge BLOQUEADO
  │   → "⚠️ Auto-merge bloqueado: VEG Pilar 1 incompleto ({N} imagenes placeholder).
  │      Opciones:
  │      a) Generar imagenes con /implement --images-only
  │      b) Aprobar merge manualmente aceptando calidad visual degradada
  │      c) Crear PENDING_IMAGES.md y resolver post-merge"
  │   → Esperar decision del usuario
  └── NO: OK

8.5.1 Verificar condiciones de auto-merge

Auto-merge SOLO si se cumplen TODAS estas condiciones:

• AG-08 verdict = GO o CONDITIONAL GO
• AG-09b verdict = ACCEPTED (no INVALIDATED)
• Todos los acceptance tests pasan
• El usuario ha confirmado modo autopilot
• No hay feedback abierto con severity critical o major (verificar feedback-summary.json)
• No hay VEG images pendientes (veg_images_pending == false) — NUEVO v4.0.1

8.5.1a Verificar feedback abierto

Si existe .quality/evidence/${feature}/feedback-summary.json:

• Leer campo blocking
• Si blocking == true → merge bloqueado por feedback

¿Todas las condiciones se cumplen?
├── SÍ → Paso 8.5.2 (auto-merge)
└── NO → Pausar, notificar al usuario, esperar aprobación manual
         → Si el bloqueo es por feedback:
           "⚠️ Merge bloqueado: {N} feedback tickets abiertos ({blocking_ids})"
           "Resolver con /feedback resolve FB-NNN o aprobar manualmente"
         → Si el bloqueo es por AG-09b INVALIDATED:
           "⚠️ AG-09b verdict fue INVALIDATED por feedback {FB-NNN}."
           "Re-ejecutar /implement para re-validar o resolver feedback primero."
         → Cuando el usuario apruebe: continuar con 8.5.2

8.5.1a Escribir Implementation Status en PRD (v5.0 Spec-Code Sync — v5.32.0 update)

Antes del merge, escribir el Implementation Status en el PRD:

1. Localizar PRD del feature/US actual:
   • Si spec-driven: buscar en doc/prds/ por us_id o feature name
   • Si freeform: ya se hizo en Paso 7.7a (saltar este paso)
2. (v5.32.0) Construir el aggregate desde phase_outputs.jsonl en lugar de acumulado del orquestador:

   from server.implement_context import aggregate_for_spec_sync
   agg = aggregate_for_spec_sync(feature)
   # agg.phases es la lista que antes llamabamos implementation_deltas
   

3. Compilar el aggregate en seccion Markdown con compile_uc_status(uc_id, branch, agg.phases) (la firma de compile_uc_status acepta tanto la lista vieja de strings como la lista nueva de dicts; mantiene compat con flujos pre-v5.32).
4. Append al PRD con append_implementation_status(prd_path, uc_id, branch, agg.phases)
5. Commit del PRD actualizado:

   git add doc/prds/{prd_file}
   git commit -m "docs({feature}): add Implementation Status for {uc_id}"
   git push origin {branch}
   

6. Si no se encuentra PRD → WARNING, no bloquear el merge.
7. Si agg.overall_status == "empty" → WARNING (probable Task legacy que no escribio phase_outputs.jsonl); fallback al flujo pre-v5.32 con git diff.

Tambien disponible como MCP tool: write_implementation_status(project_path, uc_id, branch, phase_deltas) Consulta posterior: get_implementation_status(project_path, item_id) — devuelve JSON con deltas y overall_status

8.5.2 Merge

gh pr merge --squash --delete-branch

8.5.3 Actualizar main

git checkout main
git pull origin main

8.5.4 Actualizar work item

Todos los backends (Trello/Plane/FreeForm):

1. Llamar move_uc(board_id, uc_id, "review") — mueve UC a Review (NO a Done)
2. Adjuntar evidencia: attach_evidence(board_id, uc_id, "uc", "acceptance", evidence_md)
3. Reportar acceptance tests: mark_ac_batch(board_id, uc_id, results)

IMPORTANTE: El agente NUNCA mueve a Done. Solo a Review. El humano revisa la PR, ejecuta flujos manuales, verifica E2E, y SOLO ENTONCES mueve a Done (manualmente o via complete_uc). Si todos los UCs de la US estan en Review/Done, la US se queda en su estado actual — el humano decide cuando mover la US a Done.

8.5.5 Siguiente UC/card

Si origen es Trello (US-XX mode):

→ Llamar find_next_uc(board_id) para obtener siguiente UC en Backlog
→ Si hay UC disponible:
  → start_uc(board_id, uc_id) — mueve a In Progress
  → Volver a Paso 0.1a con el nuevo UC
  → El nuevo feature branch parte del main actualizado (post-merge)
  → CERO conflictos garantizados
→ Si no hay mas UCs en Backlog:
  → Verificar si todos los UCs de la US estan en Review o Done
  → NO mover US a Done — el humano decide tras revisar todas las PRs
  → Finalizar pipeline con resumen global

Si origen es plan local:

→ Volver a Paso 0 con la siguiente card
→ El nuevo feature branch parte del main actualizado (post-merge)
→ CERO conflictos garantizados

Si no hay mas cards → finalizar pipeline con resumen global.

---

Output Final

## ✅ Implementacion Completada

**Plan**: `{path al plan}`
**Rama**: `feature/{nombre}`
**PR**: {url de la PR}

### Resumen de ejecucion:

| Fase | Estado | Commits |
|------|--------|---------|
| Diseño Stitch | ✅/⏭️ Saltado | {N} |
| Design-to-code | ✅/⏭️ Saltado | {N} |
| {Fase 1 del plan} | ✅ | {N} |
| {Fase 2 del plan} | ✅ | {N} |
| Integracion | ✅ | {N} |
| QA | ✅ | {N} |

### Metricas:

- **Archivos creados**: {N}
- **Archivos modificados**: {N}
- **Tests**: {N} pasando
- **Coverage**: {X}%
- **Commits**: {N} totales
- **Diseños Stitch**: {N} pantallas (si aplica)

### PR lista para review:
{url de la PR}

---

Self-Healing Protocol

Cuando una fase falla, el sistema intenta auto-recuperarse antes de pedir intervención humana.

Nivel 1: Auto-Fix (automático, sin preguntar)

Para errores de lint/format:

1. Ejecutar auto-fix del stack:
   • Flutter: dart fix --apply && dart format .
   • React: npx eslint --fix . && npx prettier --write .
   • Python: ruff check --fix . && ruff format .
   • GAS: npx eslint --fix .
2. Re-ejecutar validación
3. Si pasa → continuar. Si falla → escalar a Nivel 2

Nivel 2: Diagnóstico + Fix (automático, 1 intento)

Para errores de compilación o imports:

1. Leer el error completo (primeras 50 líneas)
2. Identificar la causa raíz:
   • Import faltante → añadir import
   • Tipo incorrecto → corregir tipo
   • Archivo referenciado no existe → crear stub o corregir path
   • Dependencia faltante → añadir a pubspec/package.json/requirements
3. Aplicar fix
4. Re-ejecutar validación
5. Si pasa → continuar. Si falla → escalar a Nivel 3

Nivel 3: Rollback parcial (automático, último recurso)

Si el error persiste tras Nivel 2:

1. Guardar checkpoint con status "failed" y error details
2. git stash los cambios de la fase actual
3. Registrar en .quality/evidence/${feature}/healing.jsonl:

   {"phase": N, "error": "...", "level": 3, "action": "rollback", "timestamp": "..."}
   

4. Intentar la fase una vez más desde cero (fresh attempt)
5. Si falla de nuevo → escalar a Nivel 4

Nivel 4: Intervención humana (reportar y pausar)

Si nada funciona:

1. Guardar checkpoint con status "needs_human" y full error context
2. Generar .quality/evidence/${feature}/error_report.md con:
   • Fase que falló y número de intentos
   • Error completo
   • Fixes intentados
   • Archivos modificados en la fase
   • Sugerencia de resolución
3. Reportar al usuario: "Phase {N} failed after 2 attempts. See error report at .quality/evidence/{feature}/error_report.md"
4. Preguntar: "¿Quieres que intente un approach diferente, o prefieres intervenir manualmente?"

Retry Budget

• Máximo 2 intentos completos por fase (original + 1 retry)
• Máximo 3 auto-fixes de lint por fase
• Si 2 fases consecutivas fallan → detener pipeline y generar report completo
• Total de auto-heals por implementación: máximo 8

Logging

TODOS los intentos de self-healing se registran en .quality/evidence/${feature}/healing.jsonl:

{"phase": 1, "error": "dart analyze: 3 errors", "level": 1, "action": "dart fix --apply", "result": "resolved", "timestamp": "..."}
{"phase": 3, "error": "build failed: missing import", "level": 2, "action": "added import to user_bloc.dart", "result": "resolved", "timestamp": "..."}

Error en generacion Stitch

1. Registrar el error
2. Reintentar UNA vez
3. Si falla de nuevo:
   - Continuar con las demas pantallas
   - Reportar pantallas fallidas al final
   - La implementacion continua sin esos diseños

Tests no alcanzan 85% coverage

1. Identificar archivos sin coverage
2. Generar tests adicionales (hasta 3 intentos)
3. Si no se alcanza:
   - Reportar coverage actual
   - Listar archivos que necesitan tests
   - Crear la PR de todas formas con nota sobre coverage

Conflictos de merge

1. NO resolver automaticamente
2. Reportar los archivos en conflicto
3. Pedir al usuario que resuelva
4. Continuar despues de la resolucion

---

Checklist de Calidad

• Plan leido y parseado correctamente
• Rama creada desde main
• Stack detectado
• Stitch Design Gate pasado (Paso 0.5d — si UC tiene pantallas)
• VEGs cargados del plan (si aplica)
• Disenos Stitch generados con directivas VEG (si aplica)
• Usuario informado de costes antes de generar (Paso 3.5.0 — €0 con Canva)
• MCP health check ejecutado antes de generar imagenes (Paso 3.5.1)
• Imagenes generadas con MCP o PENDING_IMAGES.md creado (Paso 3.5.4)
• Motion dependencies instaladas antes de design-to-code (Paso 4.0)
• Design-to-code ejecutado con Motion Catalog (si VEG activo)
• Mobile hover→tap enforcement aplicado (si proyecto responsive/mobile)
• Assets VEG registrados en el proyecto (Paso 6.1b, si aplica)
• Todas las fases del plan implementadas
• Commits parciales por fase
• Integracion completada (DI, routing, config)
• Build sin errores
• Tests con 85%+ coverage
• Lint sin errores
• PRD con acceptance criteria (AC-XX) localizado
• Acceptance tests generados (1 por criterio funcional)
• Evidencia visual capturada (screenshots/traces)
• AG-08 veredicto GO o CONDITIONAL GO
• AG-09 veredicto ACCEPTED
• PR creada con sección Acceptance Evidence
• Work item actualizado (si aplica)
• Self-healing log limpio (0 level 3+ events)
• Healing budget no excedido (≤8 auto-heals total)

---