implementation-plan

name	implementation-plan
description	Generate technical implementation plans with UI component analysis, agent mapping, and Stitch design generation. Use when the user says "plan feature", "create plan", "technical plan", "analyze for implementation", or references planning before coding. Reads PRDs from Plane/Trello.
context	direct

/plan (Global)

Genera un plan de implementacion detallado con analisis de componentes UI.

Uso

/plan [origen]

Origenes soportados:

• US-XX → User Story de Trello (spec-driven)
• board:BOARD_ID → Listar US de un board Trello para elegir
• MCPROFIT-42 → Work Item de Plane por identificador
• "descripcion de feature" → Texto directo
• feature:nombre → Analiza feature existente en el proyecto

---

Paso 0.0 — Leer documentos canónicos (v5.29.0 + v6.0.1 content-passing)

ANTES de cualquier otro paso:

1. Usa Read localmente sobre doc/app/app_prd.md y doc/app/app_spec.md (si existen).
2. Llama a la tool MCP con el contenido:

get_inheritable_values_tool(
  app_prd_content=<contenido o null>,
  app_spec_content=<contenido o null>,
)

Cambio v6.0.1: las tools del módulo app_docs ya no aceptan project_path. El cliente lee los archivos locales y pasa el contenido como string. Lo mismo aplica a read_app_docs_tool.

Devuelve un dict que indica qué decisiones de proyecto ya están definidas y son heredables, evitando repreguntar:

Flag	Si es True, NO preguntes
stack_known	Stack técnico para análisis de UI Components — usa stack_text
veg_mode_known	Modo VEG (Paso 2.5b) — heredado de app_spec.md sección 3
veg_archetype	Arquetipo VEG ya elegido a nivel de proyecto
backend_type	Backend tracking (freeform/trello/plane) — usa para decidir cómo guardar el plan
autopilot_level	Nivel de autopilot — afecta a qué confirmaciones del Paso 2.5b se auto-aceptan
image_budget_eur_per_feature	Presupuesto de imágenes — leído por el Paso 3.5.0 advertencia de costes

Regla de oro: si el valor del proyecto contradice algo que el usuario está pidiendo en esta feature, advierte explícitamente y pide confirmación antes de proceder. Si no hay contradicción, hereda silenciosamente.

Si read_app_docs_tool retorna has_app_spec=False, continúa en modo legacy (preguntar todo) y al final del Paso 0 sugiere:

⚠️  Sin doc/app/app_spec.md, /plan opera en modo legacy. Considera /app-init
   para evitar repreguntas en futuras features.

0.0.1 — Política de Autopilot aplicable a /plan

Antes de cada pregunta o gate de confirmación, llama a evaluateDecision(decision_key, context) desde .claude/hooks/lib/autopilot.mjs. Si retorna auto, aplica el default + log; si retorna ask, pregunta.

Pregunta del skill	decision_key	Default si auto
Modo VEG (Paso 2.5b.1)	veg_mode_selection	hereda de app_spec.md cuando veg_mode_known=true
VEG preview confirmation (Paso 2.5b.3)	veg_preview	equilibrado: auto si score≥0.8; agresivo: ≥0.7; otros tiers preguntan
Stitch config decision (Paso 4.6.6 si projectId falta)	stitch_config_decision	siempre ask (no se auto-confirma)
Stitch API key faltante	stitch_api_key_missing	siempre ask
Origen del plan ambigüo (Paso 0.1)	origin_detection	equilibrado+ con coincidencia única → auto
Aesthetic direction (heredable)	feature_aesthetic_direction	hereda de app_spec.md cuando hasAppSpec=true

Reglas inviolables:

• Si el VEG preview score < 0.7 nunca auto-confirmar.
• Generar diseños Stitch costosos no entra aquí: ese gate es la advertencia de costes (Paso 3.5.0) que es image_cost_under_budget / image_cost_over_budget (este último siempre ask).

Tras cada auto-decisión, mostrar:

ℹ️  modo VEG heredado de doc/app/app_spec.md: per_icp (autopilot: equilibrado)

---

Paso 0: Detectar Origen y Extraer Requisitos

Que recibi?
├── US-XX (ej: "US-01") → Obtener datos de Trello
├── board:BOARD_ID → Listar US del board, elegir una
├── PROYECTO-N (ej: "MCPROFIT-42") → Obtener PRD de Plane
├── Texto entre comillas → Tratar como mini-PRD
└── feature:nombre → Analizar codigo existente en lib/

Si es US-XX (Trello spec-driven):

1. Obtener board_id de .claude/settings.local.json → trello.boardId
2. Llamar get_us(board_id, us_id) via MCP dev-engine-trello
3. Llamar list_uc(board_id, us_id) para obtener todos los UCs hijos
4. Para cada UC: get_uc(board_id, uc_id) para detalle completo (ACs, pantallas, actor)
5. Buscar PRD adjunto: get_evidence(board_id, us_id, "us", "prd")
6. Si hay PRD adjunto → parsear secciones (Interacciones UI, NFRs, Riesgos)
7. Si no hay PRD → usar datos directos de Trello (nombre, descripcion, UCs, ACs)

Datos disponibles desde Trello:

• US: nombre, descripcion, horas, pantallas, estado
• UCs: nombre, actor, horas, pantallas, ACs con estado
• Evidencia: PDFs adjuntos (PRD, plans anteriores)

Si es identificador de Plane (PROYECTO-N):

1. Usar plane:retrieve_work_item_by_identifier con:
   • project_identifier: "MCPROFIT" (extraer del identificador)
   • issue_identifier: 42 (numero extraido)
2. Extraer descripcion del work item (contiene el PRD)
3. Parsear secciones: User Stories, Use Cases, Interacciones UI, Criterios

Si es texto directo:

1. Generar PRD minimo internamente:
   • Inferir funcionalidades del texto
   • Preguntar datos faltantes para seccion UI si es ambiguo
2. Continuar con el flujo

Si es feature existente:

1. Buscar en lib/presentation/features/{nombre}/
2. Analizar codigo para extraer: modelos, estados, widgets
3. Identificar gaps o mejoras posibles

---

Paso 1: Explorar Proyecto

Detectar estructura

# Buscar configuración Claude
ls -la .claude/ 2>/dev/null

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

# Encontrar biblioteca de widgets/componentes
find lib -type d -name "widgets" 2>/dev/null                      # Flutter
find src -type d -name "components" 2>/dev/null                   # React
find src -type d \( -name "html" -o -name "ui" \) 2>/dev/null    # Apps Script

Mapeo de estructura detectada

Detectado	Acción
.claude/orchestrator.md	Usar agentes del proyecto
.claude/agents/	Mapear tareas a agentes específicos
lib/core/widgets/	Usar como biblioteca de componentes (Flutter)
lib/presentation/shared/widgets/	Alternativa de biblioteca (Flutter)
src/components/	Biblioteca de componentes (React)
.clasp.json + src/html/	Proyecto Apps Script con clasp
Ninguna biblioteca	Proponer crear según stack detectado

---

Paso 2: Análisis de Componentes UI (OBLIGATORIO)

Esta fase se ejecuta SIEMPRE, independiente del origen

2.1 Leer skill de decisiones UI

Consultar: .claude/skills/adapt-ui/SKILL.md (seccion de criterios UI)
Si no existe: Usar criterios embebidos (ver Anexo A)

2.2 Extraer requisitos UI del PRD

Del PRD (o texto), identificar:

Categoría	Qué buscar	Archivo de referencia
Navegación	Secciones, tabs, flujos	navigation.md
Visualización	Listas, tablas, cards, volúmenes	data-display.md
Selección	Filtros, opciones, dropdowns	selection.md
Entrada	Formularios, campos, validación	data-entry.md
Feedback	Confirmaciones, errores, loading	feedback.md
Acciones	Botones, FAB, swipe actions	actions.md

2.3 Aplicar árboles de decisión

Para cada requisito funcional:

Requisito: "Mostrar lista de propiedades con acciones"
    ↓
Volumen: 20-100 items
Acciones por item: ver, editar, eliminar
Visual importante: Sí (thumbnail)
    ↓
Decisión: Cards con actions (no lista simple)
    ↓
Widget: PropertyCard

2.4 Buscar en biblioteca existente

# Buscar widgets existentes
find lib/core/widgets lib/presentation/shared/widgets -name "*.dart" 2>/dev/null

2.5 Generar tabla de componentes

## Componentes UI Requeridos

| Requisito | Componente | Existe | Ubicación | Acción |
|-----------|------------|--------|-----------|--------|
| Lista de propiedades | PropertyCard | ✅ | core/widgets/cards/ | Reutilizar |
| Filtro por tipo | FilterDropdown | ❌ | - | CREAR |
| Confirmación eliminar | ConfirmDialog | ✅ | core/widgets/feedback/ | Reutilizar |
| Empty state | EmptyStateView | ❌ | - | CREAR |

### Widgets a Crear

1. **FilterDropdown** (`lib/core/widgets/inputs/filter_dropdown.dart`)
   - Props: options, selected, onChanged
   - Criterio: 5-7 opciones, selección única, uso frecuente

2. **EmptyStateView** (`lib/core/widgets/feedback/empty_state_view.dart`)
   - Props: icon, title, subtitle, action
   - Criterio: Estado inicial, guiar al usuario

---

Paso 2.5b: Visual Experience Generation (VEG)

Este paso genera artefactos VEG que condicionan los diseños Stitch y el design-to-code. Se ejecuta SOLO si el PRD tiene seccion "Audiencia" con al menos 1 target. Si no hay targets → saltar a Paso 3 (pipeline legacy, backward compatible).

2.5b.1 Determinar modo VEG

Leer la seccion "Audiencia" del PRD y decidir:

Hay ICPs con JTBD definidos para landings?
├── SI → Modo 3: VEG por ICP + JTBD
│   └── Generar 1 VEG por ICP
├── NO → Hay multiples targets con expectativas visuales distintas?
│   ├── SI → Modo 2: VEG por Perfil
│   │   └── Generar 1 VEG por target
│   └── NO → Hay al menos 1 target definido?
│       ├── SI → Modo 1: VEG Uniforme
│       │   └── Generar 1 VEG unico
│       └── NO → Sin VEG (pipeline legacy)

2.5b.2 Generar VEG(s)

Para cada VEG a generar:

1. Tomar el perfil del target/ICP como entrada

2. Cruzar con:

   • Tipo de producto (SaaS, e-commerce, app interna, landing...)
   • Stack del proyecto (Flutter = flutter_animate, React = motion)
   • Branding del proyecto (si existe en settings o design system)
   • Plataforma (mobile-first vs desktop-first)

3. Consultar tabla de arquetipos en doc/templates/veg-archetypes.md

4. Identificar el arquetipo base mas cercano por senales del target

5. Aplicar defaults del arquetipo

6. Si hay JTBD emocional: evaluar si contradice algun pilar y ajustar (max 2 cambios)

7. Si hay referentes visuales: cruzar con defaults y ajustar mood/type si difieren

8. Generar prompts de imagen contextualizados:

   • Combinar: mood del pilar 1 + tipo de imagen + contexto del producto + JTBD
   • Ejemplo: Target "CTO enterprise" + producto "analytics SaaS" + JTBD emocional "sentirse en control" → Hero prompt: "Professional executive reviewing holographic data dashboard, blue ambient lighting, modern office, photorealistic, cinematic composition, sense of control and clarity"

9. Guardar en doc/veg/{feature}/veg-{slug}.md usando template de doc/templates/veg-template.md

2.5b.3 Preview y confirmacion del VEG

OBLIGATORIO: Presentar al usuario un resumen del VEG derivado antes de continuar.

📋 VEG Preview — {feature}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Modo: {1-Uniforme / 2-Por Perfil / 3-Por ICP}
Target: {nombre del target/ICP}
Arquetipo base: {Corporate / Startup / Creative / Consumer / Gen-Z / Gobierno}

Pilar 1 — Imagenes:
  Tipo: {photography / illustration_flat / illustration_3d / mixed}
  Mood: {professional / energy / premium / confidence / playful / calm}
  Paleta: {cool / vibrant / muted / warm / neutral}

Pilar 2 — Motion:
  Nivel: {subtle / moderate / expressive}
  Page enter: {animation} {duration}ms
  Loading: {style}

Pilar 3 — Diseno:
  Densidad: {compact / balanced / spacious}
  Whitespace: {tight / moderate / generous}
  Jerarquia: {card-based / full-bleed / editorial / dashboard}
  CTA: {subtle / medium / high}

⚠️ Costes de imagenes (Paso 3.5 de /implement):
  Las imagenes se generan via MCP de pago. Coste estimado:
  {N} imagenes × $0.02-0.19 = ${min}-${max} (segun provider)
  Puedes elegir "skip" en /implement para solo documentar prompts.

¿El VEG derivado es correcto? (s/n/ajustar)
  s = continuar con este VEG
  n = descartar VEG, usar pipeline legacy
  ajustar = indicar que cambiar (ej: "cambiar motion a subtle", "usar photography en vez de illustration")

Si el usuario dice ajustar:

1. Aplicar los cambios indicados al VEG
2. Mostrar preview actualizado
3. Repetir hasta confirmacion

Si el usuario dice n:

1. Descartar VEG generado
2. Continuar con pipeline legacy (sin VEG)
3. No generar archivos en doc/veg/

2.5b.4 Incluir VEG en el output del plan

Anadir seccion al plan generado:

## Visual Experience Generation

**Modo**: {1-Uniforme / 2-Por Perfil / 3-Por ICP}
**Justificacion**: {por que este modo}

### VEGs Generados

| Target/ICP | Archivo | Modo |
|------------|---------|------|
| {nombre} | doc/veg/{feature}/veg-{slug}.md | {modo} |

### VEG Activo para Stitch
{Indicar cual VEG se usara para la generacion Stitch.
En Modo 1: el unico. En Modo 2/3: el del target principal o todos si se generan variantes.}

### Resumen VEG Compacto (para sub-agentes)

> Este bloque (~400 tokens) se inyecta en el contexto de AG-02 y AG-06.

{Pegar el bloque "Resumen para inyeccion" del VEG activo}

---

Paso 3: Detectar Agentes/Skills Disponibles

Si existe .claude/orchestrator.md:

Leer y mapear agentes:

Agente	Tareas que puede ejecutar
AG-01 Feature Generator	Estructura, modelos, BLoC, routes
AG-02 UI/Design	Widgets, estilos, layouts
AG-03 Supabase	DB, queries, RLS
AG-04 QA	Tests, validación
AG-05 n8n	Workflows, automatizaciones
AG-07 Apps Script	Scripts GAS, clasp, triggers, Web Apps

Si NO existe orquestador:

Generar plan sin referencias a agentes (tareas genéricas)

---

Paso 4: Generar Plan de Implementación

Template de Plan

# Plan: [Título del PRD]

> Generado: [fecha]
> Origen: [US-XX (Trello) / MCPROFIT-N (Plane) / texto / feature]
> Estado: Pendiente

---

## Resumen

[1-2 oraciones del objetivo]

## Análisis UI (Fase 0)

### Componentes Requeridos

| Requisito | Componente | Estado | Acción |
|-----------|------------|--------|--------|
| [req] | [widget] | ✅/❌ | Reutilizar/CREAR |

### Widgets a Crear

[Lista con specs básicas]

---

## Fases de Implementación

### Fase 1: Preparación [AG-03 si existe]

- [ ] Verificar/crear tablas en DB
- [ ] Configurar índices y RLS
- [ ] Tiempo estimado: X min

### Fase 2: Componentes UI [AG-02 si existe]

- [ ] Crear widgets faltantes en `lib/core/widgets/`
- [ ] [Lista de widgets a crear]
- [ ] Tiempo estimado: X min

### Fase 3: Feature Structure [AG-01 si existe]

- [ ] Modelo con Freezed
- [ ] Repository contract + impl
- [ ] BLoC + Events + States
- [ ] Page + Layouts responsivos
- [ ] Routes con GoRouteData
- [ ] Tiempo estimado: X min

### Fase 4: Integración

- [ ] Registrar en DI
- [ ] Añadir rutas
- [ ] build_runner
- [ ] dart fix --apply
- [ ] Tiempo estimado: X min

### Fase 5: QA [AG-04 si existe]

- [ ] Tests unitarios BLoC
- [ ] Tests de repository
- [ ] Widget tests
- [ ] Coverage 85%+
- [ ] Tiempo estimado: X min

---

## Comandos Finales

```bash
dart run build_runner build --delete-conflicting-outputs
dart fix --apply && dart analyze
flutter test --coverage

---

Alternativas y Tradeoffs

Decision	Opcion elegida	Alternativa descartada	Razon
[ej: State mgmt]	[BLoC]	[Riverpod]	[Consistencia con proyecto]
[ej: Navegacion]	[GoRouter]	[Auto Route]	[Ya integrado]

---

Archivos a Crear/Modificar

lib/
├── core/widgets/           # Nuevos widgets compartidos
│   └── [widgets nuevos]
├── data/
│   ├── models/[feature]_model.dart
│   └── repositories/[feature]_repository_impl.dart
├── domain/
│   └── repositories/[feature]_repository.dart
└── presentation/features/[feature]/
    ├── bloc/
    ├── page/
    ├── layouts/
    ├── widgets/
    └── routes/

---

Referencias

• PRD: [link al work item en Plane]
• UI Patterns: doc/ui-reference/UI_PATTERNS.md (si existe)
• Skill UI: .claude/skills/adapt-ui/

---

## Paso 5: Guardar Plan

1. Crear archivo: `doc/plans/[nombre]_plan.md`
2. Si no existe `doc/plans/`: crearlo
3. Confirmar al usuario

---

## Paso 5.5: Stitch Autopilot — Pre-check (v5.31.0+)

> Solo si el plan tiene pantallas (saltar Paso 6 si es feature backend-only).
> Este paso prepara el pipeline v2 (DESIGN.md canónico + cuota observada)
> para que la generación del Paso 6 sea fiable y trazable.

### 5.5.1 Verificar DESIGN.md canónico

DESIGN.md (formato oficial Google: github.com/google-labs-code/design.md)
es leído por Stitch como contexto persistente en cada generación, y es lo
que evita el drift visual entre pantallas. SpecBox lo materializa via
`/visual-setup` Paso 3.7.

¿Existe doc/design/DESIGN.md en el proyecto? ├── SI → Continuar a 5.5.2 └── NO → Tomar UNA de estas rutas: a) Si existe doc/brand/brand_kit.md (Brand Kit ya configurado): Llamar generate_design_md_tool( project="{project_slug}", project_root="{absolute_path}" ) Continuar a 5.5.2 b) Si NO existe brand_kit.md: AVISAR al usuario: "No hay DESIGN.md ni Brand Kit. Las pantallas saldrán con defaults del arquetipo VEG 'startup' y mayor riesgo de drift. Recomendado: corre /visual-setup primero. ¿Continuar igual?" Continuar a 5.5.2 si el usuario confirma; abortar Paso 6 si no.

### 5.5.2 Registrar DESIGN.md frente al proyecto Stitch

Si DESIGN.md existe Y hay `stitch.projectId` configurado:

upload_design_md_to_stitch( project="{project_slug}", stitch_project_id="{stitch.projectId}", project_root="{absolute_path}" )

Modo `inline-prefix` hoy (Stitch MCP no expone endpoint nativo de
attach todavía). Las tools v2 de generación leen este registro y
prepended el contenido de DESIGN.md a cada prompt automáticamente.

### 5.5.3 Pre-warning de cuota

Antes de entrar al loop de generación, consultar cuota Stitch
mensual (350 Standard + 200 Experimental, no upgradeable):

get_stitch_quota_status( project="{project_slug}", project_root="{absolute_path}", write_cache=true )

Tomar acción según el resultado:

| Estado | Acción |
|--------|--------|
| `experimental.percent < 80` | Continuar a Paso 6 sin avisar |
| `experimental.percent ≥ 80` y `< 100` | AVISAR al usuario: "Cuota PRO al X% — quedan N generaciones. ¿Continuar?" |
| `experimental.percent ≥ 100` | BLOQUEAR Paso 6: "Cuota PRO agotada hasta {reset_at}. Opciones: (a) activar `flash_safety_net` en settings.local.json para usar Flash como degradación; (b) esperar al reset; (c) generar pantallas manualmente." |

El cache `.quality/stitch_quota.json` que escribe esta tool lo puede leer
cualquier consumidor externo (specbox_cloud, scripts ad-hoc) para mostrar
el estado de cuota por proyecto.

---

## Paso 6: Generar Diseños en Google Stitch (OBLIGATORIO via MCP)

> Esta sección genera diseños HTML automáticamente usando el MCP de Stitch.
> **NO se copia/pega manualmente** — Claude ejecuta la generación directamente.
> **OBLIGATORIO**: Si el UC/plan tiene pantallas, los diseños DEBEN generarse aquí.
> /implement bloqueará la implementación si no existen diseños (Paso 0.5d).

### 6.0a Stitch Config Gate (OBLIGATORIO si hay pantallas)

¿El plan tiene pantallas/screens definidos? ├── NO → Saltar Paso 6 completamente (UC sin UI) └── SI → Verificar config Stitch: │ ¿Existe stitch.projectId en configuración? ├── SI → Continuar con 6.0 (detección normal) └── NO → PREGUNTAR al usuario (NUNCA saltar silenciosamente): "El plan requiere {N} pantallas pero no hay config Stitch. Opciones: a) Configurar Stitch ahora (necesito projectId) b) Marcar diseños como PENDING (bloquea /implement) c) Generar diseños manualmente en doc/design/{feature}/

     ¿Qué prefieres?"
    │
    ├── a) → Obtener projectId → Continuar con 6.0
    ├── b) → Registrar en plan: stitch_designs: PENDING
    │        Crear doc/design/{feature}/ vacío
    │        Continuar sin generar
    └── c) → Registrar en plan: stitch_designs: MANUAL
             Crear doc/design/{feature}/ vacío
             Continuar sin generar

### 6.0b Claude Design Gate (US-29 — si `veg.providers` incluye `claude_design`)

> Claude Design diseña con los componentes reales del design-system compilado.
> `decision_key`: `claude_design_config_check`. Respeta los prompts de permiso de
> DesignSync (`create_project`, `finalize_plan`, `write_files`) — **no** auto-aprobar.

¿veg.providers incluye "claude_design"? ├── NO → omitir 6.0b (seguir solo con Stitch según 6.0a) └── SI → Evaluar el gate de precondición por topología:

mcp__SpecBox-MCP__claude_design_status(project, project_root)
→ gate_ready, role, site, projectId, login_active

¿gate_ready == true (hay design-system compilado en el sitio resuelto)?
├── SI → Ejecutar/guiar el sync ANTES de construir pantallas:
│        mcp__SpecBox-MCP__claude_design_sync_design_system(
│          project, project_root, session_projects=<DesignSync.list_projects>)
│        - El agente corre DesignSync en orden list/read → finalize_plan →
│          write/delete (prompts de permiso respetados).
│        - Idempotente: si _ds_sync.json coincide, no re-sube (status="skip").
│        - Multi-cuenta: si el projectId lo creó otra cuenta pero la sesión
│          activa es writable, procede y avisa; el consumo va a la suscripción
│          del usuario logueado.
└── NO (not-ready: no hay design-system todavía) →
        Registrar en plan: claude_design_veg: PENDING (reason del gate)
        NO fallar — /plan continúa. Si Stitch también está activo, usarlo;
        si solo estaba claude_design, las pantallas quedan pending con motivo.

> **Caso "no design-system todavía → pending"**: el gate devuelve `ready=false` con un
> motivo legible (p. ej. "missing dist/"). El VEG de Claude Design se marca `pending` y
> el plan NO se interrumpe (JR-CD.3).

### 6.0 Detectar Proyecto Stitch

1. Buscar `stitch.projectId` en `.claude/settings.local.json` del proyecto
2. Si no existe, buscar en `~/.claude/settings.local.json` (global)
3. Si no se encuentra → preguntar al usuario o usar `mcp__stitch__list_projects`

**Configuración en settings:**
```json
{
  "stitch": {
    "projectId": "10448117637612065749",
    "deviceType": "DESKTOP",
    "modelId": "GEMINI_3_PRO"
  }
}

6.1 Determinar pantallas a generar

Del análisis del PRD (Paso 2), identificar las pantallas únicas necesarias.

Regla de decisión:

Situación	¿Generar en Stitch?
Feature con pantallas nuevas	Si
Feature solo backend/lógica	No (saltar Paso 6)
Modificación menor de UI existente	No
Nuevo flujo o experiencia de usuario	Si

Para cada pantalla, definir:

• Nombre: Título descriptivo (ej: "Staff Management - Main View")
• Prompt: Descripción detallada para Stitch
• Device: DESKTOP o MOBILE (según proyecto)

6.2 Construir prompts por pantalla

⚠️ IMPORTANTE: SIEMPRE generar prompts en LIGHT MODE. NO usar dark mode.

Cada prompt DEBE incluir:

1. Contexto del Design System (colores, tipografía, estilos del proyecto)
2. Descripción funcional de la pantalla
3. Componentes requeridos (del análisis UI del Paso 2)
4. Estados (loaded, empty, loading, error)
5. Layout (desktop-first o mobile-first)
6. Iconos (Material Symbols)

Template de prompt por pantalla:

Design a [screen description] for [App Name].

Design System:
- Theme: Light Mode
- Background: #F5F5F5 (page), #FFFFFF (cards)
- Primary: [color primario del proyecto]
- Text: #1F2937 (primary), #6B7280 (secondary)
- Borders: #E5E7EB, radius 12px
- Font: [font del proyecto] / Inter / system-ui
- Shadows: subtle shadow-sm on cards

Screen: [Nombre de la pantalla]

[Descripcion detallada de que muestra la pantalla, que elementos tiene,
que acciones puede hacer el usuario, que datos se muestran]

Components:
- [Lista de componentes del analisis UI]

States to show:
- Loaded state with sample data
- Empty state with illustration + CTA
- [Loading state if complex]

Layout: Desktop (1280px wide)
Icons: Material Symbols

Si hay VEG activo (Paso 2.5b), ENRIQUECER el prompt con directivas visuales:

Design a [screen description] for [App Name].

Design System:
- Theme: Light Mode
- [colores, tipografia del proyecto]

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}] {brief description of what the image should convey}
- Section 2: [{type}] {description}
- (mark each with [IMAGE: {id}] for later replacement)

Screen: [Nombre de la pantalla]
[Descripcion funcional]

Components:
- [Lista de componentes]

States to show:
- Loaded state with sample data
- Empty state with illustration + CTA

Layout: Desktop (1280px wide)
Icons: Material Symbols

6.3 Ejecutar generación en Stitch (pipeline v2 — v5.31.0+)

Importante: a partir de v5.31.0 NO se usa mcp__stitch__generate_screen_from_text directamente. Las llamadas pasan por el pipeline v2 que añade prompt validation, fallback chain, telemetría granular, y propaga el DESIGN.md canónico como contexto persistente.

6.3.1 Validar prompt antes de generar

Para cada pantalla, validar el prompt construido en 6.2:

validate_stitch_prompt(
  project="{project_slug}",
  prompt="{prompt construido}",
  mode="warn",
  project_root="{absolute_path}"
)

Tomar acción según el resultado:

Resultado	Acción
valid=true, sin warnings	Continuar a 6.3.2 con el prompt original
valid=true, con warnings	Mostrar warnings al usuario; usar normalized_prompt (color-substitutions ya resueltas) y continuar
requires_split=true	Avisar: "El prompt mezcla layout + componentes. Voy a dividirlo en {N} llamadas: layout primero, componentes después." Iterar 6.3.2 una vez por cada split_prompts[i]
valid=false (modo strict)	Pedir al usuario revisar el prompt antes de seguir

6.3.2 Generar con fallback chain

stitch_generate_screen_v2(
  project="{project_slug}",
  stitch_project_id="{stitch.projectId}",
  prompt="{normalized_prompt o split_prompt[i]}",
  device_type="{stitch.deviceType}",       // DESKTOP por defecto
  model_id="{stitch.modelId}",             // GEMINI_3_PRO por defecto (calidad-first)
  baseline_screen_id=null,                 // null en primera generación; ver 6.3.3
  flash_safety_net=false,                  // opt-in en settings.local.json
  max_total_attempts=3
)

Reglas de ejecución:

• Generar UNA pantalla a la vez (la tool tarda minutos por pantalla en PRO).
• NO reintentar manualmente si falla: el pipeline v2 ya aplica edit_baseline → variants_refine → regenerate automáticamente. Si la respuesta es outcome: "failed", presentar el campo attempts[] al usuario y preguntar qué hacer (ajustar prompt, omitir pantalla, etc.).
• Si outcome: "ok_degraded" (Flash safety net), avisar al usuario: la pantalla salió en Flash y debería regenerarse manualmente con PRO cuando la cuota se reinicie. La respuesta incluye degraded_reason.
• Si output_components o sugerencias del result, presentarlas al usuario igual que antes.

6.3.3 Pasada incremental (cuando aplica)

Si una pantalla tiene una versión previa (ej. usuario quiere refinar), pasar el screen_id previo como baseline_screen_id para que el pipeline priorice edit_baseline sobre regenerar from scratch — preserva trabajo parcial y consume menos cuota.

6.3.4 Confirmación entre pantallas

• Presentar el resultado de la pantalla generada al usuario.
• Esperar confirmación antes de la siguiente pantalla.

6.4 Obtener y guardar HTML

Para cada pantalla generada:

1. Usar mcp__stitch__get_screen para obtener el HTML completo
2. Guardar en doc/design/{feature}/{screen_name}.html
3. Crear carpeta doc/design/{feature}/ si no existe

mcp__stitch__get_screen(
  name: "projects/[projectId]/screens/[screenId]"
)

6.5 Registrar prompts usados

Guardar los prompts en doc/design/{feature}/{feature}_stitch_prompts.md para trazabilidad:

# Stitch Prompts - {Feature Name}

> Generado automáticamente por /plan
> Proyecto Stitch: {projectId}
> Fecha: {fecha}

## Screen 1: {nombre}
**Screen ID**: {screenId}
**Prompt**:
{prompt usado}

## Screen 2: {nombre}
**Screen ID**: {screenId}
**Prompt**:
{prompt usado}

6.6 Preguntar si continuar con más pantallas

Después de cada pantalla generada, preguntar:

• "¿Quieres generar la siguiente pantalla: [nombre]?"
• "¿Quieres ajustar el prompt antes de generar?"
• "¿Saltamos el diseño y pasamos a implementación?"

6.7 Multi-pantalla con batching (cuando aplica — v5.31.0+)

Solo aplica si el plan tiene >5 pantallas relacionadas que comparten un mismo flujo o área funcional (ej. dashboard con varias vistas, marketplace con landing + listing + detalle + cart + checkout). Si las pantallas son independientes, mantén el flujo serial 6.3.

Stitch's build_site tiene un límite duro de ~5 pantallas conectadas por llamada. Para superar ese techo sin romper consistencia visual, usar:

stitch_build_site_batched_v2(
  project="{project_slug}",
  stitch_project_id="{stitch.projectId}",
  screens=[
    {"name": "landing", "prompt": "{prompt validado}", "route": "/", "order": 1, "group": "public"},
    {"name": "listing", "prompt": "{prompt validado}", "route": "/marketplace", "order": 2, "group": "public"},
    {"name": "detail",  "prompt": "{prompt validado}", "route": "/marketplace/:id", "order": 3, "group": "public"},
    {"name": "cart",    "prompt": "{prompt validado}", "route": "/cart", "order": 4, "group": "checkout"},
    {"name": "checkout","prompt": "{prompt validado}", "route": "/checkout", "order": 5, "group": "checkout"},
    {"name": "confirm", "prompt": "{prompt validado}", "route": "/confirm", "order": 6, "group": "checkout"},
    ...
  ],
  batch_size=4,
  apply_unified_theme_pass=true,
  unified_theme_prompt=null   // null usa el default referenciando DESIGN.md
)

Reglas:

• Validar cada prompt con validate_stitch_prompt antes de incluirlo en screens[] (mismo flujo que 6.3.1).
• Particionado automático prioriza group explícito → prefijo de route → chunks por order. Si quieres control fino, asigna group.
• apply_unified_theme_pass=true (default) ejecuta una pasada final de edit_screens por pantalla que homogeniza header/nav/footer/buttons contra DESIGN.md. Sin esta pasada, batches distintos pueden divergir.
• El response devuelve batches[] con duración y status por batch + unified_pass[] con el resultado de la pasada final + flags total_screens, total_batches, unified_pass_applied.
• Para descargar el HTML de cada pantalla generada por el batched build, seguir usando mcp__stitch__get_screen (Paso 6.4) screen-by-screen.

---

Paso 7: Actualizar Work Item y Adjuntar Evidencia

Si origen es Trello (US-XX):

1. Adjuntar plan como PDF a la card US en Trello:

   attach_evidence(board_id, us_id, "us", "plan", plan_markdown)
   

2. Esto genera un PDF y lo sube como attachment a la card

Si origen es Plane (PROYECTO-N):

1. Anadir link al plan generado en comentario
2. Cambiar estado a "To-Do" si estaba en "Backlog"

Usar plane:create_work_item_comment:

{
  "project_id": "[projectId]",
  "work_item_id": "[workItemId]",
  "comment_html": "Plan generado: `doc/plans/[nombre]_plan.md`"
}

---

Output Final

## ✅ Plan Generado

**Archivo**: `doc/plans/[nombre]_plan.md`
**Origen**: [tipo de origen]

### Resumen:
- **Fases**: [N]
- **Componentes UI analizados**: [N]
- **Widgets a crear**: [N]
- **Agentes involucrados**: [lista o "N/A"]

### Componentes UI:
| Estado | Cantidad |
|--------|----------|
| ✅ Existentes | [N] |
| ❌ A crear | [N] |

### Visual Experience Generation:
| Campo | Valor |
|-------|-------|
| Modo VEG | {1-Uniforme / 2-Por Perfil / 3-Por ICP / Desactivado} |
| VEGs generados | {N} |
| Archivos | `doc/veg/[feature]/` |

### Disenos Stitch:

**stitch_designs**: {GENERATED / PENDING / MANUAL / N/A}

| Pantalla | Screen ID | Estado | VEG aplicado |
|----------|-----------|--------|--------------|
| [nombre] | [id] | Generado | {Si/No} |
| [nombre] | [id] | Generado | {Si/No} |

**HTMLs guardados en**: `doc/design/[feature]/`
**Prompts registrados en**: `doc/design/[feature]/[feature]_stitch_prompts.md`

> Si `stitch_designs: PENDING` — /implement bloqueará la implementación hasta que
> los diseños se generen manualmente o se re-ejecute /plan con config Stitch.

### Siguiente paso:
1. Revisar disenos HTML generados
2. Ejecutar `/implement` (verificará diseños en Paso 0.5d)

---

Anexo A: Criterios UI Embebidos

Si el skill ui-component-decisions no está disponible, usar estos criterios mínimos:

Visualización de Datos

Volumen < 5 → Cards inline
Volumen 5-20 → Lista/Cards con scroll
Volumen 20-100 → Lista virtualizada o paginada
Volumen 100+ → Búsqueda obligatoria + paginación

Selección

Opciones 2-3 → Radio buttons / Segmented control
Opciones 4-7 → Dropdown
Opciones 8+ → Autocomplete / Search
Múltiple selección → Chips / Checkboxes

Acciones

Acción principal → FAB o botón primario prominente
Acciones secundarias → IconButtons en AppBar
Acciones por item → Trailing icons o swipe actions
Acciones destructivas → Requieren confirmación

Feedback

Éxito/Info transitoria → SnackBar (auto-dismiss)
Error recuperable → SnackBar con action
Confirmación crítica → Dialog modal
Loading → Skeleton o CircularProgressIndicator
Empty state → Ilustración + CTA

---

Checklist de Calidad

• Origen identificado correctamente
• Fase 0 (UI) ejecutada
• Tabla de componentes generada
• Widgets faltantes identificados con specs
• Fases ordenadas lógicamente
• Agentes mapeados (si existen)
• Archivo guardado en doc/plans/
• VEG generado si PRD tiene seccion Audiencia (Paso 2.5b)
• VEG preview mostrado al usuario y confirmado (Paso 2.5b.3)
• Costes de imagenes advertidos al usuario en preview
• VEGs guardados en doc/veg/{feature}/ con los 3 pilares
• Resumen VEG compacto (<400 tokens) incluido en el plan
• Stitch config verificada (Paso 6.0a — si hay pantallas, NUNCA saltar silenciosamente)
• Campo stitch_designs incluido en el plan (GENERATED/PENDING/MANUAL/N/A)
• Pantallas Stitch generadas via MCP (si aplica UI)
• Prompts Stitch enriquecidos con VEG (si aplica)
• HTMLs guardados en doc/design/{feature}/
• Prompts de Stitch registrados para trazabilidad
• Seccion Alternativas/Tradeoffs incluida
• Plan adjuntado como evidencia a Trello (si spec-driven)

---

Referencia MCP

Trello (dev-engine-trello):

• get_us(board_id, us_id) — Detalle completo de US con UCs hijos
• get_uc(board_id, uc_id) — Detalle completo de UC con ACs
• list_us(board_id) — Listar todas las US del board
• list_uc(board_id, us_id) — Listar UCs de una US
• get_evidence(board_id, target_id, target_type) — Obtener evidencia adjunta
• attach_evidence(board_id, target_id, target_type, evidence_type, markdown) — Adjuntar PDF

Plane — Herramientas principales:

• plane:list_projects - Listar proyectos del workspace
• plane:retrieve_work_item_by_identifier - Obtener work item por identificador (ej: MCPROFIT-42)
• plane:retrieve_work_item - Obtener work item por UUID
• plane:update_work_item - Actualizar work item
• plane:create_work_item_comment - Añadir comentario a work item
• plane:list_states - Listar estados de un proyecto

Formato de identificador:

• MCPROFIT-42 → project_identifier: "MCPROFIT", issue_identifier: 42
• El número se extrae parseando el identificador