Skip to content
Skills Library
Programming · Automation

autopilot-implement

/autopilot-implement

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.

Licence
Apache-2.0
Last repository change
27.10.2026

Assessment and security

86/ 100Class: good
Format20 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content26 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
2
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

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.

Triggers from the description

implement planexecute planautopilot
Original author 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.

How it works

  1. Working set (v5.32.0)
  2. Checkpoint System
  3. Uso
  4. Paso 0.0 — Política de Autopilot v5.29.0
  5. Paso 0: Cargar y Validar Plan
  6. Paso 1: Crear Rama de Feature
  7. Paso 2: Orquestacion por Sub-Agentes (Aislamiento Estricto)
  8. Paso 3: Generar Diseños en Stitch (si faltan)
  9. Paso 3.5: Generar Imagenes con MCP (si hay VEG activo)
  10. Paso 4: Design-to-Code (si hay disenos)
Original SKILL.md headings · 2,451 lines, 13,806 words
SKILL.md preview
---
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:
  ```bash
  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.

**Decisiones aplazadas (US-99 · UC-9902).** Con `autopilot.queue_enabled` y un `defaultOption` en el contexto, una
decisión que se preguntaría vuelve como `queue` (nunca las inviolables ni las que fijó la persona con
`always_ask_overrides`). Entonces, sin parar:

1. Aplica `defaultOption` y sigue.
2. Anótala en el proyecto con `enqueue_decision_tool` (devuelve el id `dq-…`).
3. Publícala en el board con `publish_decision(decision_key, question, options=[{id, label}, …], default_option,
   uc_id, decision_id=<el dq-… del paso 2>)`: pregunta corta, de 2 a 6 opciones y sin credenciales. Así la ve la
   persona en el panel y en el teléfono.
4. Si al arrancar la siguiente sesión aparece en «Decisiones resueltas fuera de esta sesión», aplica la opción elegida
   en lugar de la de por defecto y muévela a resueltas en la cola local con `resolve_queue_entry`.

`list_pending_decisions` lista las que siguen esperando; `resolve_decision` la resuelve desde una sesión si la persona
contesta en el chat.

| 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.
- Escribir código en main lo bloquea el hook `spec-guard.mjs` y los commits en main, `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?
├── EP-NN → Modo épica (US-78): encadenar las UC pendientes de la épica, en el orden de sus historias
├── 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.1a-bis Si es EP-NN (épica, D20 · US-78)

1. `get_epic(board_id, epic_id)` → nombre, objetivo, historias y avance. Si responde
   `EPIC_NOT_FOUND`, para y dilo.
2. `find_next_uc(board_id, epic=epic_id)` (añade `satellite=<clave>` si trabajas desde un
   satélite) → la UC pendiente de la épica en el orden de sus historias; una historia que ya
   tiene trabajo en curso va primero.
3. Para esa UC sigue el flujo normal (0.1a con `UC-XXX`: plan de su US, `start_uc`, fases,
   PR, merge secuencial).
4. Tras cada UC (Paso 8.5.5) vuelve a `find_next_uc(board_id, epic=epic_id)`. Cuando devuelve
   `None`, **la épica no tiene más UC pendientes: para** y resume con `get_epic` (estado y
   avance). No saltes a UC de otras épicas.

En un satélite, `find_next_uc(board_id, satellite="<clave>")` sustituye a construir
`uc_scope` a mano.

### 0.1b Si es plan local:

```bash
# 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

```bash
# 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:

```bash
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:

```json
// .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).

```python
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

```bash
# 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.
```

```bash
# 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:**
```bash
# 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

```bash
# 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

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

### 3.2 Detectar configuracion Stitch

Igual que `/plan` 6.0: `stitch.projectId` en `.claude/settings.local.json` (o en el global) y,
antes de la primera tool `stitch_*` de la sesión, `stitch_set_api_key` con la clave de esos mismos
settings. Si no hay proyecto, `/plan` 6.0a (Stitch Config Gate): preguntar, nunca inventarlo.

### 3.3 Generar pantallas faltantes (misma cadena que `/plan`, US-91 · UC-9103)

Las pantallas que faltan se generan **con la cadena del Paso 6 de `/plan`**, no llamando a Stitch
directamente. Esa cadena valida el prompt, lleva el DESIGN.md del proyecto como contexto y marca el
resultado como candidato (D18). Para cada pantalla del plan que no tenga HTML:

1. **Brief y dirección.** Si faltan `doc/design/{feature}/{pantalla}.brief.md` o `.direction.md`,
   ejecutar antes `/design-review brief` y `direction`: sin brief no hay diseño.
2. **Prompt** como en `/plan` 6.2 (siempre Light Mode, sin valores de diseño inventados), con el
   bloque «Visual Direction» de la dirección y, si hay VEG activo, sus directivas (abajo).
3. **Validar** con `validate_stitch_prompt` (`/plan` 6.3.1; con MCP remoto,
   `design_md_content=<doc/design/DESIGN.md>`) y actuar según su resultado: `normalized_prompt` con
   avisos, `split_prompts` si hay que dividir.
4. **Generar** con `stitch_generate_screen_v2` (`/plan` 6.3.2), una pantalla a la vez. El pipeline
   ya reintenta (`edit_baseline → variants_refine → regenerate`): no se reintenta a mano.
5. **Guardar** con `stitch_fetch_screen_code` en `doc/design/{feature}/{screen_name}.html`, con el
   `html_banner` de la respuesta como **primera línea** (`/plan` 6.4): el fichero es un candidato
   para decidir disposición y flujo, nunca fuente de producción.
6. **Revisar el candidato** con la crítica de candidatos de `/plan` (6.4b): revisor aislado, una
   sola edición y se queda la mejor versión. En autopilot avisa y sigue.
7. **Registrar** el prompt en `doc/design/{feature}/{feature}_stitch_prompts.md` (`/plan` 6.5).

**Prohibido aquí:** `mcp__stitch__generate_screen_from_text` y `mcp__stitch__get_screen`
directos. Se saltan la validación del prompt, el DESIGN.md y la marca de candidato.

**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 una pantalla sale con `outcome: "failed"`, registrar sus `attempts[]` y continuar con las
  demas; con `ok_degraded`, avisar de que salio en Flash

---

## 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`:

```markdown
# 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 candidatos de Stitch o Claude Design a codigo del stack del proyecto.
>
> **Fuente de valores (D18):** del HTML candidato se toman disposicion, jerarquia, componentes y
> flujo. **Ningun valor visual se copia del HTML.** Colores, tipografia, espaciado, radios y
> sombras salen de los tokens del sistema (`design-system.tokens.json`) cuando existen y, si no,
> del theme del proyecto y de `doc/design/DESIGN.md`. Un valor del HTML que no este en el sistema
> se sustituye por el token mas cercano y se anota en el resumen de la fase.
>
> **Pantallas de un lienzo de Claude Design (US-92 · UC-9202):**
> - La entrada es la vista congelada `doc/design/{feature}/{artboard}.html`, que deja
>   `/design-review import`. La fuente `canvas/{artboard}.dc.html` solo se lee para entender
>   estados e interaccion.
> - El codigo no lleva nada del motor del lienzo (`support.js`, `<x-dc>`, `DCLogic`, `<sc-for>`,
>   `<sc-if>`, `<dc-import>`, `<x-import>`, `/_blob/`). La puerta de diseño bloquea la pagina que
>   lo lleve.
> - Si falta la vista congelada, se importa antes.

### 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

```bash
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 el HTML candidato y extraer: layout, jerarquia, componentes y estados. Colores,
   espaciado y tipografia **no** se extraen: se usan los del sistema (tokens → `AppColors`,
   `AppSpacing`, `TextTheme`)
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 el HTML candidato y extraer: estructura JSX, jerarquia y componentes. Las clases de
   color, fuente, espaciado o radio del candidato (hex, valores arbitrarios de Tailwind) se
   sustituyen por las utilidades o variables de los tokens del sistema
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:

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

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

```python
# 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).

> La verificación de cada pantalla (capturas, reglas, revisor aislado y una ronda de corrección)
> se hace en el **Paso 6.5**, cuando la pantalla ya está integrada y se puede servir.

### 4.4 Commit parcial de diseños

```bash
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:
```bash
.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)`:

```python
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:

```python
# 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:

```bash
# 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:

```json
{
  "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:

```javascript
// 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:

```python
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
```bash
# 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
```bash
# Despues de cambios
npx eslint . --fix && npx tsc --noEmit
```

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

#### Google Apps Script
```bash
# Despues de cambios
npm run lint && npm run build
```

### 5.3 Commits parciales por fase

Cada fase completada genera un commit:

```bash
# 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`:

[…] pełny plik w paczce .zip
Files in this package (2)
  • SKILL.md 96 KB
  • file-ownership.md 1 KB

Versions

The database has no other skills named autopilot-implement.

Database snapshot: 13.11.2026 · package version e202dd53c16d (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100dev-autopilot
    Full autonomous execution from idea to working code. Use when user says "autopilot", "autonomous", "build me", "create me", "make me", "full auto" — orchestrates spec → plan → code → QA → validation across the engineering layer agents.
  • 84execute-plan
    Execute implementation plans step-by-step. Use when user says "execute the plan", "implement the plan we created", "start building based on the plan", "go ahead and implement it", "proceed with the implementation", "execute as a stack", "create a PR stack while implementing",…
  • 100autopilot-plan
    Turn a large change into an autopilot plan (SPEC.md + tasks.json) that the `autopilot` orchestrator runs unattended across many Claude Code sessions, each with its own model and effort. Use when the user runs /autopilot-plan or asks to plan work for an overnight or unattended run.
  • 100autopilot-github-execution
    Use when implementing a GitHub issue or other GitHub change request, when the user says autopilot or ready for PR, or when an issue is unclear, contradictory, or missing acceptance criteria. Also use when tempted to guess the requirement, skip review, ask the user to approve a…
  • 86build-feature
    Stage 3b (Build) - implement an approved plan.md on a feature branch in the app (the app in `<app.dir>/`, database in `<app.migrationsDir>`), commit, push and open a GitHub PR. Use only after plan.md is approved, or when the user says "build it", "implement the plan", or…
  • 100stitch-to-react
    Converts Google Stitch exports into React components with design DNA integration. Use when user references design-intent/google-stitch exports, mentions "convert Stitch output", "Stitch to React", or processes Stitch code directories containing HTML + PNG pairs.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.