| 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 elegirMCPROFIT-42 → Work Item de Plane por identificador"descripcion de feature" → Texto directofeature: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:
- Usa
Read localmente sobre doc/app/app_prd.md y doc/app/app_spec.md (si existen).
- 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):
- Obtener board_id de
.claude/settings.local.json → trello.boardId
- Llamar
get_us(board_id, us_id) via MCP dev-engine-trello
- Llamar
list_uc(board_id, us_id) para obtener todos los UCs hijos
- Para cada UC:
get_uc(board_id, uc_id) para detalle completo (ACs, pantallas, actor)
- Buscar PRD adjunto:
get_evidence(board_id, us_id, "us", "prd")
- Si hay PRD adjunto → parsear secciones (Interacciones UI, NFRs, Riesgos)
- 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):
- Usar
plane:retrieve_work_item_by_identifier con:
project_identifier: "MCPROFIT" (extraer del identificador)issue_identifier: 42 (numero extraido)
- Extraer descripcion del work item (contiene el PRD)
- Parsear secciones: User Stories, Use Cases, Interacciones UI, Criterios
Si es texto directo:
- Generar PRD minimo internamente:
- Inferir funcionalidades del texto
- Preguntar datos faltantes para seccion UI si es ambiguo
- Continuar con el flujo
Si es feature existente:
- Buscar en
lib/presentation/features/{nombre}/
- Analizar codigo para extraer: modelos, estados, widgets
- Identificar gaps o mejoras posibles
Paso 1: Explorar Proyecto
Detectar estructura
ls -la .claude/ 2>/dev/null
cat pubspec.yaml 2>/dev/null | grep -E "flutter:|dependencies:"
cat package.json 2>/dev/null | grep -E "react|next"
cat pyproject.toml 2>/dev/null | grep -E "fastapi|django"
ls .clasp.json appsscript.json 2>/dev/null
find lib -type d -name "widgets" 2>/dev/null
find src -type d -name "components" 2>/dev/null
find src -type d \( -name "html" -o -name "ui" \) 2>/dev/null
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
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:
-
Tomar el perfil del target/ICP como entrada
-
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)
-
Consultar tabla de arquetipos en doc/templates/veg-archetypes.md
-
Identificar el arquetipo base mas cercano por senales del target
-
Aplicar defaults del arquetipo
-
Si hay JTBD emocional: evaluar si contradice algun pilar y ajustar (max 2 cambios)
-
Si hay referentes visuales: cruzar con defaults y ajustar mood/type si difieren
-
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"
-
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:
- Aplicar los cambios indicados al VEG
- Mostrar preview actualizado
- Repetir hasta confirmacion
Si el usuario dice n:
- Descartar VEG generado
- Continuar con pipeline legacy (sin VEG)
- 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:
- Contexto del Design System (colores, tipografía, estilos del proyecto)
- Descripción funcional de la pantalla
- Componentes requeridos (del análisis UI del Paso 2)
- Estados (loaded, empty, loading, error)
- Layout (desktop-first o mobile-first)
- 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:
- Usar
mcp__stitch__get_screen para obtener el HTML completo
- Guardar en
doc/design/{feature}/{screen_name}.html
- 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):
- Adjuntar plan como PDF a la card US en Trello:
attach_evidence(board_id, us_id, "us", "plan", plan_markdown)
- Esto genera un PDF y lo sube como attachment a la card
Si origen es Plane (PROYECTO-N):
- Anadir link al plan generado en comentario
- 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
Referencia MCP
Trello (dev-engine-trello):
get_us(board_id, us_id) — Detalle completo de US con UCs hijosget_uc(board_id, uc_id) — Detalle completo de UC con ACslist_us(board_id) — Listar todas las US del boardlist_uc(board_id, us_id) — Listar UCs de una USget_evidence(board_id, target_id, target_type) — Obtener evidencia adjuntaattach_evidence(board_id, target_id, target_type, evidence_type, markdown) — Adjuntar PDF
Plane — Herramientas principales:
plane:list_projects - Listar proyectos del workspaceplane:retrieve_work_item_by_identifier - Obtener work item por identificador (ej: MCPROFIT-42)plane:retrieve_work_item - Obtener work item por UUIDplane:update_work_item - Actualizar work itemplane:create_work_item_comment - Añadir comentario a work itemplane: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
