Skip to content
Skills Library
Programming · Planning

implementation-plan

/implementation-plan

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.

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

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.

Triggers from the description

plan featurecreate plantechnical plananalyze for implementation
Original author 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.

How it works

  1. Uso
  2. Paso 0.0 — Leer documentos canónicos (v5.29.0 + v6.0.1 content-passing)
  3. Paso 0: Detectar Origen y Extraer Requisitos
  4. Paso 1: Explorar Proyecto
  5. Paso 2: Análisis de Componentes UI (OBLIGATORIO)
  6. Paso 2.5b: Visual Experience Generation (VEG)
  7. Paso 3: Detectar Agentes/Skills Disponibles
  8. Paso 4: Generar Plan de Implementación
  9. Paso 5: Guardar Plan
  10. Paso 5.5: Stitch Autopilot — Pre-check (v5.31.0+)
Original SKILL.md headings · 1,274 lines, 7,072 words
SKILL.md preview
---
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
```bash
# 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

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

### 2.5 Generar tabla de componentes

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

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

### Regla de redaccion cara-al-cliente (US-33 / UC-3302) — OBLIGATORIA

> Aplica a **todo AC que este skill derive o reescriba**, no solo a los del
> `/prd`. Un AC generado aquí acaba en el mismo board y en la misma pantalla
> delante del cliente.

La regla completa, con los ejemplos reales antes → despues, vive en
`.claude/skills/prd/SKILL.md` → «Regla de redaccion cara-al-cliente». No se
duplica aquí para que no puedan divergir. Resumen operativo:

| No | En su lugar |
|----|-------------|
| Credenciales (usuario, contrasena, api key, secret, token con valor) | Nombrar el mecanismo, no el secreto |
| **Rutas de fichero internas** (`web/src/lib/x.ts`, `server/y.py`) | Nombrar el **comportamiento observable**, no su ubicacion |
| Lenguaje despectivo o jerga interna («roto», «chapuza», «hardcoded») | Terminos neutros y verificables |

**Un AC generado por este skill que cite una ruta de fichero es un fallo de la
UC**, no un detalle de estilo. Es la trampa mas facil de pisar desde `/plan`,
porque el plan tecnico SI habla de ficheros: el plan puede nombrarlos, el AC no.

Distinguir las dos cosas:

- **Plan** → «Fase 2: modificar `server/tools/_mutation_helpers.py`». Correcto,
  el plan es interno.
- **AC** → «El gate deja de marcar como no verificables los criterios escritos
  en indicativo». Correcto, describe el comportamiento observable.
- **AC** → ❌ «`validate_ac_text` deja de anadir `not_testable`». Cita la
  implementacion: si manana la funcion cambia de nombre, el AC miente.

Antes de cerrar el plan, pasar `validate_ac_quality` y revisar **las dos
listas** que devuelve: `failed` (calidad, bloquea) y `warnings` (exposicion,
solo avisa).

### Template de Plan

```markdown
# 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]

## Fuente de diseño

> Obligatoria si el plan tiene pantallas o UI. Se completa con lo que devuelve
> `generate_design_md_tool` en el Paso 5.5.1.

- **Fuente de producción**: los tokens del sistema `[ruta de design-system.tokens.json]`
  ([nombre], versión [N]). Colores, tipografía, radios y estados salen solo de ahí (y del
  registro de componentes del sistema, si el proyecto lo tiene).
- **Diseños de Stitch / Claude Design de este plan**: son **candidatos**. Sirven para decidir
  disposición, jerarquía y flujo; nunca son fuente de producción y el código no copia sus valores.
- **Lienzo de Claude Design** (si se usó, Paso 6.0b): [dirección del lienzo]. Una fila por pantalla:

  | Pantalla | Artboard 1440 | Artboard 390 | Brief |
  |---|---|---|---|
  | [pantalla] | `[artboard].dc.html` | `[pantalla]-390.dc.html` | `doc/design/[feature]/[pantalla].brief.md` |

  Las pantallas aprobadas llegan al proyecto con `/design-review import`.
- **DESIGN.md**: generado desde los tokens (`values_outside_system` vacío); no se edita a mano.
- *Si el proyecto no tiene tokens del sistema*: [mensaje del aviso `SYSTEM_TOKENS_MISSING`, con
  su enlace a la guía]. Mientras tanto la fuente es el Brand Kit / DESIGN.md, y los diseños
  siguen siendo candidatos.

---

## 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 Generar DESIGN.md desde el sistema (US-49 · UC-4901)

DESIGN.md (formato oficial Google: github.com/google-labs-code/design.md) es lo
que Stitch recibe como sistema en cada generación. Si el proyecto tiene **tokens
del sistema** (`design-system.tokens.json`), el DESIGN.md sale solo de ellos; el
Brand Kit y el arquetipo no se leen. Se regenera en cada `/plan` con pantallas
(es idempotente) y siempre en modo contenido: el MCP es remoto y no ve el disco
del proyecto.

1. Buscar los tokens del sistema: el primer `design-system.tokens.json` en
   `doc/design/`, `src/styles/tokens/`, `apps/web/src/styles/tokens/`,
   `web/src/styles/tokens/`, `packages/tokens/dist/` o la raíz del repo.
2. Leer también, si existen: el brand kit (`doc/brand/brand_kit/SKILL.md`, el que escribe
   `/visual-setup`, o `doc/brand/brand_kit.md` en proyectos antiguos), el VEG activo y
   `doc/app/app_prd.md` / `doc/app/app_spec.md`.
3. Llamar (pasar solo los contenidos que existan):

```
generate_design_md_tool(
  project="{project_slug}",
  system_tokens_content=<design-system.tokens.json>,
  system_tokens_path="<ruta relativa del fichero>",
  brand_kit_content=<brand kit>,
  veg_content=<VEG activo>,
  app_prd_content=<app_prd.md>,
  app_spec_content=<app_spec.md>
)
```

4. Escribir `design_md_content` en `suggested_relpath` (`doc/design/DESIGN.md`).
5. Según la respuesta:

```
├── system_tokens.found == true
│     └── values_outside_system tiene que venir vacío. Si no, PARAR y mostrar
│         la lista: el DESIGN.md contiene valores que no son del sistema.
│         Mostrar también `warnings` (p. ej. una fuente que Stitch no ofrece).
├── notice.code == "SYSTEM_TOKENS_MISSING"
│     └── Mostrar notice.message al usuario (incluye el enlace a la guía) y seguir:
│         la fuente es el Brand Kit o el arquetipo. Si tampoco hay Brand Kit,
│         avisar del riesgo de deriva y preguntar si continuar; abortar el
│         Paso 6 si no.
└── code == "SYSTEM_TOKENS_INVALID"
      └── PARAR: los tokens existen pero están rotos. Mostrar el mensaje (dice
          qué falta). No generar desde el Brand Kit.
```

6. Completar la sección «Fuente de diseño» del plan guardado con `system_tokens`
   (ruta, nombre y versión) o con el aviso.

### 5.5.2 Dar el sistema a Stitch

Si hay `stitch.projectId`, Stitch recibe el DESIGN.md recién generado. Con el
contrato `native_v2` (el de siempre desde v6.4.0):

```
stitch_upload_design_md(project, stitch_project_id, design_md_content)
  → screen_instance {id, sourceScreen}
stitch_create_design_system_from_design_md(project, stitch_project_id,
  screen_instance_id=id, source_screen=sourceScreen, device_type)
```

Si el proyecto Stitch ya tenía un Design System (`stitch_list_design_systems`),
actualizarlo en lugar de crear otro: `stitch_update_design_system(...,
theme=material3.theme)` con el `material3` de la respuesta del 5.5.1.

Con el Design System aplicado, `stitch_generate_screen_v2` quita del prompt los
colores, fuentes y radios: los pone Stitch desde el sistema. Con el contrato
legado `inline_prefix_v1`, pasar `design_md_content` en cada
`stitch_generate_screen_v2`.

---

## 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 Lienzo de Claude Design (US-92 · UC-9201 — si `veg.providers` incluye `claude_design`)

> Con Claude Design, cada feature tiene **un lienzo**: un Artifact del tipo **Design**, con dos
> artboards por pantalla (1440 y 390) y el sistema de diseño del proyecto instalado. El lienzo se
> hace con la herramienta `Artifact`, igual que `/design`. **No** se usa `DesignSync`: un proyecto de
> claude.ai/design no se puede instalar en un lienzo
> (`doc/research/claude-design-import/sistema-instalable.md`). Lo que se dibuja es un **candidato**
> (D18).

```
¿veg.providers incluye "claude_design"?
├── NO → omitir 6.0b (seguir con Stitch según 6.0a)
└── SI → 1. Precondiciones. Si falta una, se dice CUÁL y se sigue con Stitch (6.0a), sin fallar:
         - la herramienta Artifact en esta sesión
           → «Esta sesión no tiene la herramienta Artifact (Claude Code 2.1.265 o posterior)»
         - la plantilla Design: Artifact list con scope "types" incluye «Design»
           → «La plantilla Design no está disponible para esta cuenta»
         - sesión de claude.ai: la creación del lienzo (paso 3) falla por autorización
           → «No hay sesión de claude.ai en esta máquina: inicia sesión y vuelve a /plan»
         - el sistema del proyecto: veg.claude_design.designSystem (su dirección)
           → si falta y hay design-system.tokens.json: publicarlo ahora con /visual-setup 2.9.3
           → si no hay tokens: claude_design_veg: PENDING («sin tokens del sistema») y Stitch
         Registrar en el plan: claude_design_veg: PENDING (motivo) cuando no se use el lienzo.
```

2. **Brief y dirección de cada pantalla** (6.1): `/design-review brief` y `direction`. **Sin brief no
   hay artboard**: cada artboard parte de su brief (usuario, las tres preguntas y datos reales) y lo
   que falta va como `[DATO REAL: …]`.
3. **Un lienzo por feature.** Si `doc/design/{feature}/claude-design.json` ya tiene una dirección, se
   usa ese lienzo: se revisa, nunca se crea otro. Si no, una llamada a `Artifact` con el `type_url` del
   tipo Design (de `list` con `scope: "types"`), `title` = la feature y `auto_open:
   "after_first_write"`, sin ficheros. La respuesta trae la dirección y la guía del tipo: síguela para
   los ficheros.
4. **Esqueleto** en una carpeta del scratchpad:

   ```bash
   node .claude/skills/design-review/scripts/canvas.mjs scaffold --feature {feature} --title "{feature}" \
     --url <lienzo> --screens <pantallas.json> --root <scratch>/lienzo \
     --ds-url <veg.claude_design.designSystem> --ds-namespace <Ns> --ds-version <versión> \
     --ds-files tokens.json,tokens.css,components/bundle.css[,components/bundle.js]
   ```

   - `<pantallas.json>`: `[{"slug", "titulo", "ucs": [...], "brief": "doc/design/{feature}/{pantalla}.brief.md"}]`,
     una entrada por pantalla de las UC.
   - El namespace y los ficheros salen de «Consuming this system» del README del sistema; la versión,
     de `Artifact list` con `scope: "files"`.

   El script escribe `project/canvas.json`:
   - dos artboards por pantalla, a 1440 y 390 (el de escritorio de la primera es `Main.dc.html`);
   - un título por fila y una nota con las tres preguntas del brief;
   - el registro del sistema.

   Devuelve la `cabecera` de cada artboard y las `copias_del_sistema`, y apunta en
   `doc/design/{feature}/claude-design.json` qué pantalla y qué UC son de cada artboard.
5. **Artboards**, según la guía del tipo:
   - La primera llamada lleva `canvas.json`, `Main.dc.html` y las `copias_del_sistema`, entradas
     `{artifact, path}` que copia el servidor. Después, un artboard por llamada.
   - Cada artboard abre con la `cabecera`. Pinta con `var(--token)` y las clases de los estilos de
     texto del sistema, **sin declarar variables**.
   - Si el sistema publica componentes (`window.<Ns>`), monta los reales con
     `<x-import component-from-global-scope="<Ns>.<Comp>">`; nunca imitaciones.
   - El artboard de 390 puede montar la página fluida de 1440 con `<dc-import>`: es la misma pantalla
     a otro ancho, no una copia.
6. **Anotar en el plan** («Fuente de diseño»): la dirección del lienzo y, por pantalla, sus dos
   artboards.
7. **Crítica**: 6.4b, sobre la copia congelada del lienzo.

### 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`
4. Antes de la primera tool `mcp__SpecBox-MCP__stitch_*` de la sesión, llamar a
   `mcp__SpecBox-MCP__stitch_set_api_key(project, api_key)` con `stitch.apiKey` de esos
   mismos settings (o preguntar la clave). El servidor la guarda solo en la sesión y no la
   recupera de disco (UC-8601): sin ella responde «not configured … in this session».

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

### 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")
- **Brief y dirección (US-90)**: `doc/design/{feature}/{pantalla}.brief.md` y
  `{pantalla}.direction.md`, escritos por `/design-review brief <pantalla>` y
  `/design-review direction <pantalla>`. **Sin brief no se construye el prompt**: si falta,
  ejecutar esos dos subcomandos antes de 6.2.
- **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.

**El prompt sale del brief y de la dirección (US-90):**
- La descripción funcional, los datos reales y los estados salen del brief.
- El bloque «Visual Direction» de la dirección va **antes** del prompt (formato en
  `.claude/skills/design-review/reference/direction.md`). En la prueba UC-9001, ese bloque subió el
  candidato de Stitch de 5,5 a 12 sobre 40.
- Con un Design System aplicado en Stitch, el bloque no lleva colores, fuentes ni radios.

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:**

> **El prompt no inventa valores de diseño.** Con Design System aplicado (5.5.2),
> no se escriben colores, fuentes ni radios: los pone Stitch desde el sistema.
> Sin él, se copian del DESIGN.md generado en 5.5.1; nunca se escriben de memoria.

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

Design System:
- Theme: Light Mode
- Use the project's design system applied in this Stitch project
  (sin Design System aplicado: colores, fuente, radio y sombra copiados del DESIGN.md)

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
- Use the project's design system applied in this Stitch project

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}"
)
# MCP remoto (UC-8604): en lugar de project_root, design_md_content=<doc/design/DESIGN.md>
```

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_8_FLASH por defecto (calidad-first)
  baseline_screen_id=null,                 // null en primera generación; ver 6.3.3
  max_total_attempts=3
)
```

La respuesta trae `design_role: "candidate"`, `design_role_note` y `html_banner`:
la pantalla es un **candidato** para decidir disposición y flujo, nunca fuente de
producción. Decirlo así al presentarla al usuario.

**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, **junto al veredicto de la crítica
  de 6.4b** (total, veredicto y defectos principales).
- Esperar confirmación antes de la siguiente pantalla. En autopilot, el veredicto no detiene el
  plan (ver 6.4b).

### 6.4 Obtener y guardar HTML

Para cada pantalla generada:

1. Obtener el HTML completo con `stitch_fetch_screen_code(project, stitch_project_id, screen_id)`:
   el HTML viene en `result.html` (el engine lo baja de `htmlCode.downloadUrl` de
   `get_screen`; la captura, con `stitch_fetch_screen_image`, en `result.image_base64`)
2. Guardar en `doc/design/{feature}/{screen_name}.html` con el `html_banner` de la
   respuesta como **primera línea**: el fichero queda marcado como diseño candidato
   (`specbox:design-role=candidate`) y nadie lo toma por fuente de producción
3. Crear carpeta `doc/design/{feature}/` si no existe

Los diseños de Claude Design llegan con `/design-review import <feature> <artboard…>` (US-92 ·
UC-9202). Por cada artboard aprobado deja:
- su fuente (`canvas/<artboard>.dc.html`);
- su **vista congelada** (`<artboard>.html`), que es HTML sin el motor del lienzo, con el banner de
  candidato y su origen (lienzo, versión y artboard) en la primera línea;
- la vista del lienzo (`canvas.html`);
- el manifiesto (`claude-design.json`).

Si el lienzo no cambió, no escribe nada. Detalle en `.claude/skills/design-review/reference/canvas.md`.

### 6.4b Criticar el candidato antes de darlo por bueno (US-90 · UC-9004)

> **Por qué.** En la prueba UC-9001, los candidatos de Stitch sacaron 5,5 y 12 sobre 40: solo
> escritorio, datos del brief alterados y tells. La verificación con un revisor aislado fue la capa
> que más subió las pantallas (+5,75/40). Un candidato no se guarda sin pasar por aquí.
>
> **Alcance.** Toda pantalla de Stitch y todo artboard de un lienzo de Claude Design (US-92 · UC-9201).
> El lienzo no se abre ni se captura: se critica la **copia congelada**. `/design-review import`
> (UC-9202), con `--out <scratch>/critica`, todos los artboards de la feature y `--states` con los
> estados del brief (vacío, carga, error…), la deja sin motor. A esa copia se le pasa `verify` (1440 y
> 390) y el revisor aislado, que recibe también las vistas de cada estado. La «edición» de Needs changes es
> una revisión de ese artboard en el lienzo, siguiendo la guía del tipo. Después se vuelve a importar y
> a revisar. Si la edición puntúa menos, se vuelve a publicar la fuente anterior.
> **Rúbrica:** `.claude/skills/design-review/reference/rubric.md`.

1. **Captura.** `stitch_fetch_screen_image(project, stitch_project_id, screen_id)` y guardar
   `result.image_base64` en `doc/design/{feature}/{screen_name}.png`. Si el proyecto tiene Playwright,
   capturar además el HTML de 6.4 al ancho del dispositivo del candidato (1440 px en DESKTOP, 390 px en
   MOBILE) y medir `scrollWidth` («Mediciones antes de opinar» en la rúbrica).
2. **Revisor aislado.** Lanzar un subagente (herramienta Agent, `general-purpose`) que **no** reciba el
   prompt de Stitch ni el razonamiento de este plan. Encargo:

   ```
   Eres el revisor de diseño de un proceso de verificación. Revisas un candidato que ha hecho otra
   herramienta; no ves cómo se hizo. Lee ÚNICAMENTE:
   - el brief: doc/design/{feature}/{screen_name}.brief.md
   - la rúbrica: .claude/skills/design-review/reference/rubric.md (y defaults.md, que enlaza)
   - el candidato: doc/design/{feature}/{screen_name}.html y su captura {screen_name}.png
   - las mediciones, si las hay
   Puntúa los 8 criterios (0-5) y da total sobre 40 y veredicto (Block, Needs changes o Approve).
   El responsive se juzga al ancho del dispositivo del candidato (DESKTOP: 1440 px); que un
   candidato DESKTOP no se adapte a 390 px se anota, no se suspende.
   Lista hasta 8 defectos por severidad, cada uno con dónde, qué está mal y qué hacer, aplicables en
   una sola ronda. Marca como defecto cualquier dato que no salga del brief.
   Escribe el resultado en el formato de la rúbrica y no modifiques nada.
   ```
3. **Veredicto.**
   - **Approve:** seguir.
   - **Needs changes:** **una sola** edición. Llamar a `stitch_edit_screen(project,
     stitch_project_id, screen_id, prompt=<los defectos concretos, uno por línea>)`. El prompt de
     edición no pide datos que el brief no da: lo que falte se pide como marcador visible. Después,
     traer el HTML y la captura de la versión editada y pasarla por un revisor aislado nuevo con el
     mismo encargo. **Se conserva la versión con mejor total**, que queda en `{screen_name}.html`; la
     otra, con su `screen_id`, se anota en la revisión.
   - **Block:** no se edita a ciegas. En modo interactivo, se propone al usuario regenerar con el
     prompt corregido. En autopilot, se avisa y se anota (paso 6).
4. **Guardar la revisión junto al diseño**: `doc/design/{feature}/{screen_name}.review.md`, con:
   - las notas de los 8 criterios, el total y el veredicto;
   - los defectos;
   - si hubo edición, los totales antes y después y qué versión se conservó (con su `screen_id`).
5. **Anotar en el plan** de la feature la tabla «Revisión de candidatos»:

   | Pantalla | Screen ID conservado | Total | Veredicto | Edición (antes → después) |
   |---|---|---|---|---|

6. **Autopilot.** El veredicto **avisa y no detiene el plan** (modo `warn`): queda en la tabla del
   paso 5 y en el resumen final. Un «Block» se lista además en el resumen como pendiente de decisión
   del usuario.

### 6.5 Registrar prompts usados

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

```markdown
# 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.
- Cada pantalla del lote, una vez descargada, pasa por la crítica de 6.4b como cualquier otra
  (con su brief, su revisor aislado y una sola edición). El lote no se da por bueno en bloque.

---

## 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`:
```json
{
  "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]/` (todos **candidatos**: la fuente de
producción son los tokens del sistema; ver «Fuente de diseño» en el plan)
**Prompts registrados en**: `doc/design/[feature]/[feature]_stitch_prompts.md`

### Revisión de candidatos (6.4b):

| Pantalla | Total | Veredicto | Edición (antes → después) |
|----------|-------|-----------|---------------------------|
| [nombre] | [N]/40 | Approve / Needs changes / Block | [—, o 18 → 26] |

> Los «Block» quedan pendientes de tu decisión: regenerar con el prompt corregido o seguir.
> Revisiones completas en `doc/design/[feature]/[pantalla].review.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
Files in this package (2)
  • SKILL.md 50 KB
  • templates/.gitkeep 1 KB

Versions

RepositoryScoreLicence
This page · EmbedBuild/specbox-engine86Apache-2.0
langri-sha/skills100MIT
Mozurok/fhorja.dev100MIT
navapbc/digital-service-orchestra91Apache-2.0
hugrverk/riggverk90MIT
Gattic/GatPi-Harness90MIT
itsofficialadi/boundiff90MIT
nasac0x/code-orchestrator90MIT
Neeeophytee/finding-unknowns-skills90MIT

Database snapshot: 13.11.2026 · package version 3beccbd5338f (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

  • 86prd-generator
    Generate structured Product Requirements Documents from feature descriptions. Use when the user says "create PRD", "new feature", "write requirements", "define feature", or references creating specifications for implementation. Supports Trello (spec-driven) and Plane work item creation.
  • 100create-plan
    Create detailed implementation plans through interactive research and iteration. This skill should be used when creating new implementation plans, designing feature specifications, planning technical work, or when the user asks to plan an implementation. Triggers on requests…
  • 100trello-webhooks
    Receive and verify Trello webhooks. Use when setting up Trello webhook handlers, debugging x-trello-webhook signature verification, or handling board and card events like createCard, updateCard, commentCard, or addMemberToBoard.
  • 95technical-design
    Turn business requirements into a technical plan, data model, interface contracts, and deployment plan. Use to establish technical design before production development, or to design affected modules and interfaces in an existing system.
  • 95write-implementation-plan
    Use this skill when the user says 'plan before coding', 'write an implementation plan', 'implementation_plan.md', 'propose changes first', 'what files would you change', 'plan this feature', or when a coding task touches multiple files/modules and approval is expected before…
  • 100trello-cli
    Trello board, list and card management via CLI. Activate when user mentions "Trello" - examples: "Show my Trello tasks", "Add card to Trello", "Move on Trello", "Trello board", "List Trello", "Trello cards".

Feedback and reports

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