菜单
Autonomous implementation from a plan file. Creates feature branch, implements all phases, generates Stitch designs if needed, converts designs to code, runs QA validation, and creates GitHub PR. Use when the user says "implement plan", "execute plan", "autopilot", or references implementing a previously created plan.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | autopilot-implement |
| description | Autonomous implementation from a plan file. Creates feature branch, implements all phases, generates Stitch designs if needed, converts designs to code, runs QA validation, and creates GitHub PR. Use when the user says "implement plan", "execute plan", "autopilot", or references implementing a previously created plan. |
| disable-model-invocation | true |
/implement mantiene 4 archivos en .quality/evidence/{feature}/:
| Archivo | Vida | Quien escribe | Quien lee |
|---|---|---|---|
pipeline_state.json | Toda la run | Orquestador (Paso 0.4a + tras cada fase) | pipeline-phase-guard.mjs |
execution_context.json | Toda la run (immutable) | Orquestador (Paso 0.4b) | Cada Task delegado, hooks |
phase_outputs.jsonl | Append-only durante la run | Cada Task al cierre | Spec-Code Sync (Paso 5.1.1b, 8.5.1a) |
checkpoint.json | Toda la run, sobrescrito | Orquestador post-fase | Resume al iniciar nueva sesion |
Y .quality/active_agent.json en raiz del proyecto, transient (escrito
antes de cada Task(AG-XX), borrado tras retorno) — leido por
file-ownership-guard.mjs para validar Write/Edit.
Telemetria adicional:
.quality/task_isolation.json — counters (tasks_run_total,
tasks_failed_budget, tasks_failed_ownership). Bumped por los hooks
y por el bloque post-Task del Paso 5.0. Telemetria local.Before starting, check for existing checkpoint:
mkdir -p .quality/evidence/${feature}
echo '{"phase": N, "phase_name": "...", "branch": "...", "timestamp": "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'", "status": "complete"}' > .quality/evidence/${feature}/checkpoint.json
Autopilot de implementacion: lee un plan, crea rama, ejecuta todas las fases, genera diseños si aplica, valida con QA, commitea y crea PR.
/implement [plan]
Origenes soportados:
US-XX → User Story de Trello (ejecuta todos los UCs en secuencia)UC-XXX → Use Case individual de Trellonombre_del_plan → Busca doc/plans/{nombre}_plan.mddoc/plans/mi_plan.md → Path directo al archivo del plandoc/plans/ y pregunta cual ejecutarANTES de cualquier otro paso, llama a la tool MCP get_inheritable_values_tool(project_path=".") para conocer el autopilot_level del proyecto y los valores heredables desde app_*.md.
Antes de cada gate o pregunta, llama a evaluateDecision(decision_key, context) desde .claude/hooks/lib/autopilot.mjs. Si retorna auto, aplica el default + log; si ask, pregunta como en v5.28; si block, bloquea con el mensaje del helper.
| Pregunta / gate | decision_key | Default si auto |
|---|---|---|
| Origen ambigüo (Paso 0.1, sin argumento) | origin_detection | equilibrado+: usar match único |
| Uncommitted changes warning (Paso 0.2) | uncommitted_changes_warning | siempre ask |
| Stitch design por pantalla (Paso 3) | stitch_design_per_screen | conservador+: auto si HTML existe |
| Image cost ≤ presupuesto (Paso 3.5.0) | image_cost_under_budget | equilibrado+: auto cuando coste ≤ budget de app_spec.md sección 5 |
| Image cost > presupuesto (Paso 3.5.0) | image_cost_over_budget | siempre ask (inviolable) |
| Stitch API key faltante | stitch_api_key_missing | siempre ask |
| Push directo a main | branch_to_main_push | siempre block (inviolable) |
| Acciones destructivas (reset, force-push) | destructive_action | siempre ask (inviolable, además bloqueado por no-bypass-guard) |
Reglas inviolables:
app_spec.md sección 5 → autopilot.branch-guard.mjs y commit-spec-guard.mjs. /implement no debe intentar bypassearlo.Tras cada auto-decisión visible al usuario:
ℹ️ Diseños Stitch existentes auto-confirmados (autopilot: equilibrado, decision_key: stitch_design_per_screen)
Que recibi?
├── US-XX → Modo Trello: ejecutar bloque de UCs de la US
├── UC-XXX → Modo Trello: ejecutar un UC individual
├── nombre_del_plan → Buscar doc/plans/{nombre}_plan.md
├── path directo → Leer directamente
└── sin argumento → Listar doc/plans/*.md y preguntar
.claude/project-config.json → trello.boardId (PREFERIDO — Claude Code rechaza campos custom en settings.local.json).claude/settings.local.json → trello.boardId (fallback legacy)get_us(board_id, us_id) → datos de la USlist_uc(board_id, us_id) → listar UCs hijosfind_next_uc(board_id) → determinar primer UC a ejecutarget_evidence(board_id, us_id, "us", "plan")doc/plans/ → cargar plan localget_uc(board_id, uc_id) → datos completos del UCstart_uc(board_id, uc_id) → mover a In Progress + timestampFlujo de ejecucion por US (bloque de UCs):
US-XX recibida
├── Cargar plan de la US
├── find_next_uc → UC-001 (Backlog)
│ ├── start_uc(UC-001) → In Progress
│ ├── Implementar (Pasos 1-7.7)
│ ├── move_uc(UC-001, "review") → Review (humano aprueba Done)
│ ├── Merge secuencial (Paso 8.5)
│ └── Pull main
├── find_next_uc → UC-002 (Backlog)
│ ├── start_uc(UC-002) → In Progress
│ ├── ... (mismo ciclo)
│ └── Pull main
└── No mas UCs en Backlog → Finalizar
# Listar planes disponibles
ls doc/plans/*_plan.md 2>/dev/null
Si no hay planes → Informar: "No hay planes en doc/plans/. Ejecuta /plan primero."
Leer el archivo del plan completo y extraer:
| Campo | Donde encontrarlo | Obligatorio |
|---|---|---|
| Titulo | # Plan: [titulo] (primera linea H1) | Si |
| Resumen | Seccion ## Resumen | Si |
| Fases | Secciones ### Fase N: | Si |
| Componentes UI | Seccion ## Analisis UI o ## Componentes UI | No |
| Widgets a crear | Subseccion ### Widgets a Crear | No |
| Archivos a crear/modificar | Seccion ## Archivos a Crear/Modificar | No |
| Agentes involucrados | Referencias a AG-XX en las fases | No |
| Comandos finales | Seccion ## Comandos Finales | No |
| Diseños Stitch | Referencias a doc/design/ o pantallas Stitch | No |
| VEGs | doc/veg/{feature}/*.md — artefactos Visual Experience Generation | No |
| Modo VEG | Seccion "Visual Experience Generation" del plan | No |
| Trello US/UC | Origen US-XX o UC-XXX + board_id | No |
Regla de decision:
¿El plan tiene diseños Stitch?
├── SI: Referencia a doc/design/{feature}/*.html
│ ├── ¿Existen los HTML? → Ir a Paso 4 (design-to-code)
│ └── ¿No existen? → Generar con Stitch (Paso 3)
├── SI: Seccion "Diseños Stitch" con pantallas listadas
│ └── Mismo flujo: verificar existencia → generar si faltan
└── NO: No hay referencias a diseño
└── Saltar directamente a Paso 5 (implementacion)
¿El plan tiene seccion "Visual Experience Generation"?
├── SI: Cargar VEGs de doc/veg/{feature}/*.md
│ ├── Leer modo VEG (1/2/3) y archivos generados
│ ├── Activar pasos VEG: enriquecer Stitch (3), generar imagenes (3.5), inyectar motion (4)
│ └── Preparar resumen VEG compacto (~400 tokens) para sub-agentes
└── NO: Pipeline legacy (sin cambios)
# Detectar stack del proyecto actual
cat pubspec.yaml 2>/dev/null | grep -E "flutter:|dependencies:" # Flutter
cat package.json 2>/dev/null | grep -E "react|next" # React/Node
cat pyproject.toml 2>/dev/null | grep -E "fastapi|django" # Python
ls .clasp.json appsscript.json 2>/dev/null # Google Apps Script
Despues de detectar el stack y parsear el plan, inicializar pipeline_state.json
para que pipeline-phase-guard.mjs pueda validar el orden de fases:
mkdir -p .quality/evidence/${feature}
Determinar qué fases aplican al proyecto:
has_db = plan incluye fase DB/Infra (AG-03)
has_ui = plan incluye fase Diseño/Design-to-code (AG-02/AG-06)
# Pre-marcar fases no aplicables como completadas
completed_phases = []
if NOT has_db: completed_phases.append("db_infra")
if NOT has_ui: completed_phases.append("stitch_designs", "design_to_code")
Escribir el estado inicial:
// .quality/evidence/${feature}/pipeline_state.json
{
"feature": "${feature}",
"has_ui": true|false,
"has_db": true|false,
"completed_phases": ["...fases no aplicables pre-marcadas..."],
"current_phase": "init",
"last_updated": "ISO8601"
}
IMPORTANTE: Este archivo es OBLIGATORIO. Sin el, pipeline-phase-guard.mjs permite todo
(modo permisivo). Con el, enforce mecánico del orden de fases.
Inmediatamente despues de pipeline_state, escribir tambien el execution_context.json
que cada Task delegado leera para conocer branch / feature / stack sin que el
orquestador los repita verbatim en cada prompt (causa raiz de la exhaustion de
contexto en UCs grandes — ver doc/plans/v5.32.0_implement_task_isolation_plan.md).
from server.implement_context import write_execution_context, compute_plan_hash
write_execution_context(
feature_slug=feature,
branch=branch, # se conocera en Paso 1; aqui pasar valor
# tentativo y refrescar tras crear la rama
# con update_last_updated()
stack=stack, # detectado en Paso 0.x
project_name=project_name,
project_root_absolute=str(Path.cwd()),
engine_version="5.32.0",
uc_id=uc_id,
us_id=us_id,
backend_type=backend_type, # freeform | trello | plane
board_id=board_id,
plan_path=str(plan_path),
plan_hash=compute_plan_hash(plan_path),
autopilot_level=autopilot_level, # equilibrado | conservador | ...
)
Esto crea .quality/evidence/{feature}/execution_context.json con escritura
atomica e idempotente (no churnea el archivo si el contenido no cambia).
Contrato de uso: a partir de aqui, cualquier Task delegado por /implement debe arrancar leyendo este archivo en lugar de recibir branch/feature/stack en el prompt. Ver Paso 5.X.0 para el bloque reusable de invocacion.
Por que aqui: este paso corre antes de
start_ucy de crear la rama (Paso 1). El autopilot rara vez falla al ejecutar; falla cuando adivina una decision que era del usuario (un contrato de API, un naming, un trade-off) y arrastra el error por toda la cadena rama->fases->QA->PR. El gate resuelve esas decisiones con el usuario por adelantado, cuando corregir cuesta ~50 tokens en vez de un PR entero.
Analizar el plan con la tool MCP (content-passing: leer el plan local con
Read y pasar su contenido):
analyze_preflight_decisions(
plan_content="<contenido de doc/plans/{feature}_plan.md>",
autopilot_level="<specbox.autopilot.level de settings.local.json>"
)
Devuelve {decisions[], verdict, user_dependent, user_dependent_decisions[], ...}.
Actuar segun el verdict:
verdict | Accion |
|---|---|
no_user_decisions | Continuar directo a 0.5 / start_uc / rama sin interrumpir. El gate no molesta cuando todo es autonomo o no hay decisiones (AC-08). |
needs_user_input | BLOQUEAR la creacion de rama. Presentar al usuario la lista de user_dependent_decisions (cada una con su description y, si la hay, su reason) y pedirle que las resuelva TODAS antes de continuar (AC-06). |
Mostrar lo autonomo como informativo (no pedir accion): las decisiones
clasificadas autonomous se listan con su reason (de la politica) para que
el usuario vea que se resolvio solo y por que — transparencia (JE-F.1).
No re-preguntar: las decisiones resueltas aqui NO se vuelven a preguntar
durante las fases (AC-07). El registro queda en
.quality/autopilot_decisions.jsonl (kind=preflight) via la capa de log de
la tool, auditable despues (UC-604).
Inviolables: las decisiones destructivas / push-a-main / coste-sobre-budget
siempre caen en user_dependent aunque el nivel sea agresivo — el gate nunca
las auto-confirma (AC-05). "Mas autonomia" jamas significa "menos seguridad".
Degradacion: si la tool no esta disponible (engine viejo), el gate se omite y
/implementse comporta como antes — backwards-compatible.
Antes de ejecutar, verificar:
git status --porcelain)# Verificar working tree limpio
git status --porcelain
# Verificar rama actual
git branch --show-current
# Actualizar main
git fetch origin
Si hay cambios sin commitear → Advertir al usuario y preguntar si continuar (puede perder contexto).
Si no esta en main → Advertir y preguntar si crear la rama desde la rama actual o desde main.
REGLA INNEGOCIABLE: Nunca se puede implementar directamente en main/master.
Esta validacion se ejecuta ANTES del Paso 1 y se RE-VERIFICA antes de cada Paso 5 (implementacion de fases).
current_branch = git branch --show-current
¿current_branch es main o master?
├── SI (estamos en Paso 0): OK — el Paso 1 creara la rama feature/
├── SI (estamos en Paso 5+): ❌ ERROR FATAL
│ → "BLOQUEADO: Se esta intentando implementar directamente en main.
│ Esto viola el protocolo de ramas del engine.
│ El Paso 1 debio crear una rama feature/ antes de llegar aqui.
│ ACCION: Parar inmediatamente. NO escribir codigo en main."
│ → PARAR el pipeline. No continuar bajo ninguna circunstancia.
└── NO: OK — continuar normalmente
Por que este bloqueo es necesario:
REGLA: No se puede implementar UI sin identidad visual configurada. Este gate impide generar diseños genéricos que no representan la marca del producto. Se ejecuta ANTES del Design Gate (0.5d) porque sin brand kit los diseños carecen de sentido.
¿El UC/plan tiene pantallas listadas?
├── No tiene pantallas → SKIP (gate no aplica, UC sin UI)
└── Tiene pantallas → Verificar identidad visual:
│
¿Existe doc/brand/brand_kit/SKILL.md?
├── SI → OK — brand kit configurado, continuar
└── NO → Verificar mas:
│
¿Existe stitch.designSystemAssetId en .claude/settings.local.json?
├── SI → OK — Design System configurado (brand kit parcial aceptable)
└── NO → Verificar si el proyecto usa Stitch:
│
¿Existe stitch.projectId en .claude/settings.local.json
O existen doc/design/**/*.html?
├── NO → SKIP (proyecto no usa Stitch, gate no aplica)
└── SI → ❌ BLOCKED
"❌ BLOCKED: Visual identity not configured.
This project uses Stitch but has no brand kit or Design System.
Without visual identity, designs are generic and inconsistent.
Run /visual-setup first to configure:
- Brand Kit (colors, typography, CSS tokens)
- Design System in Stitch (applied automatically to every screen)
- VEG base (visual directives for sub-agents)
- Prompt template (reusable structure for Stitch generation)
/visual-setup takes ~5 minutes and only needs to run once per project."
→ PARAR. No continuar bajo ninguna circunstancia.
# Verificacion rapida
ls doc/brand/brand_kit/SKILL.md 2>/dev/null
cat .claude/settings.local.json 2>/dev/null | grep -c "designSystemAssetId"
Por que este bloqueo es necesario:
/visual-setup solo se ejecuta UNA VEZ por proyecto (~5 min) y resuelve el problema permanentementeREGLA: No se puede generar codigo de presentacion sin diseños Stitch previos. Este gate impide que el agente en modo autopilot salte el paso de diseño.
¿El UC/plan tiene pantallas listadas?
pantallas = extraer campo "screens" o "pantallas" del UC/plan
├── pantallas vacías o no definidas → SKIP (gate no aplica, UC sin UI)
└── pantallas definidas → Verificar diseños:
│
Para cada pantalla listada:
¿Existe doc/design/{feature}/*.html con HTML correspondiente?
├── SI → OK
└── NO → Acumular en lista missing_designs[]
│
¿missing_designs está vacío?
├── SI → OK — todos los diseños existen, continuar
└── NO → Verificar campo stitch_designs del plan:
│
¿stitch_designs == "PENDING"?
├── SI → ❌ BLOCKED
│ "❌ BLOCKED: Stitch designs pending for UC-XXX.
│ The plan has stitch_designs: PENDING — designs were not generated.
│ Run /plan first to generate Stitch designs, or create them manually
│ in doc/design/{feature}/ before running /implement."
│ → PARAR. No continuar bajo ninguna circunstancia.
└── NO (campo no existe o no es PENDING) → ❌ BLOCKED
"❌ BLOCKED: No Stitch designs found for UC-XXX.
Missing designs for screens: {missing_designs[]}
Expected location: doc/design/{feature}/
Run /plan first or generate designs manually."
→ PARAR. No continuar bajo ninguna circunstancia.
Verificacion concreta:
# Contar HTMLs de diseño existentes para el feature
ls doc/design/${feature}/*.html 2>/dev/null | wc -l
# Si es 0 y el UC tiene pantallas → BLOCKED
Por que este bloqueo es necesario:
Para proyectos con codigo UI pre-v4.2.0, el Design Gate aplica enforcement progresivo basado en el nivel de compliance del proyecto.
¿Existe baseline de design compliance?
.quality/scripts/design-baseline.sh . → leer enforcementLevel
│
├── L0 (compliance < 30%): Proyecto legacy, mucho codigo sin Stitch
│ → Paso 0.5d se comporta como WARNING, no BLOCK
│ → Mensaje: "⚠️ Design compliance L0: {rate}%. UC-XXX no tiene diseños.
│ Recomendacion: ejecutar /plan para generar diseños antes de implementar.
│ Este proyecto esta en modo retrofit — el gate no bloquea aun."
│ → Continuar implementacion (el codigo se genera sin diseño)
│ → AG-08 Check 6 reporta como INFO, no CRITICAL
│ → /check-designs muestra deuda de diseño acumulada
│
├── L1 (compliance 30-79%): Proyecto en transicion
│ → Paso 0.5d BLOQUEA solo si el plan es nuevo (post-v4.2.0)
│ → Planes legacy (sin campo stitch_designs) → WARNING + continuar
│ → Planes nuevos (con campo stitch_designs) → BLOCK si PENDING/missing
│ → AG-08 Check 6: CRITICAL solo en archivos nuevos del diff
│ → Archivos existentes modificados: WARNING (no CRITICAL)
│ → complianceRate solo puede subir (ratchet)
│
└── L2 (compliance >= 80%): Proyecto alineado
→ Paso 0.5d BLOQUEA siempre (comportamiento estandar)
→ AG-08 Check 6: CRITICAL en todo archivo de presentation/pages/
→ Sin excepciones — el proyecto ya esta alineado
Como migrar de L0 a L2 progresivamente:
Fase 1 (L0 → L1): Ejecutar /check-designs para ver deuda. Al implementar
features nuevas, usar /plan con Stitch. Cada feature alineada sube el rate.
Al alcanzar 30% → upgrade automatico a L1.
Fase 2 (L1 → L2): Aprovechar cada modificacion de features existentes para
generar diseños Stitch retroactivos. Usar /plan feature:nombre_existente para
generar diseños de features legacy que se estan tocando. Al alcanzar 80% → L2.
Fase 3 (L2 estable): Todo nuevo codigo pasa por Stitch. La deuda legacy restante se resuelve en sprints dedicados o cuando se toca el codigo.
Solo aplica si el origen es US-XX o UC-XXX (Trello spec-driven).
¿Se llamo start_uc(board_id, uc_id) en Paso 0.1a?
├── SI: Verificar con get_uc(board_id, uc_id) que status == "in_progress"
│ ├── Confirmado: OK — continuar
│ └── No confirmado: ⚠️ WARNING — start_uc pudo haber fallado silenciosamente
│ → Reintentar start_uc una vez
│ → Si falla de nuevo: continuar con WARNING en el log
└── NO (start_uc no fue llamado): ❌ ERROR FATAL
→ "BLOQUEADO: No se llamo start_uc antes de implementar.
El estado del UC en Trello no refleja que esta en progreso.
Esto causara inconsistencia en el board."
→ Llamar start_uc ahora como recovery
→ Si falla: PARAR y notificar al usuario
Del titulo del plan, generar nombre de rama:
Plan: "Gestion de Propiedades" → feature/gestion-de-propiedades
Plan: "Auth con Google OAuth" → feature/auth-con-google-oauth
Plan: "Refactor DataSources" → feature/refactor-datasources
Reglas de naming:
feature/ (siempre)# Crear rama desde main (o rama base)
git checkout -b feature/{nombre-del-plan} main
# Verificar
git branch --show-current
Si la rama ya existe → Preguntar al usuario: ¿Continuar en la rama existente o crear nueva con sufijo?
REGLA: El orquestador NUNCA implementa codigo. Solo planifica, delega y consolida. Ver
rules/GLOBAL_RULES.mdseccion "Aislamiento Estricto del Orquestador".
Cada fase del plan se ejecuta en un sub-agente (Task) con contexto limpio e independiente.
| Fase del plan | Sub-agente | Contexto que recibe |
|---|---|---|
| Preparacion DB | AG-03 DB Specialist | Schema del plan + patrones infra/{db}/ |
| Diseño UI | AG-06 Design Specialist | Pantallas del plan + config Stitch |
| Design-to-code | AG-02 UI/UX Designer | HTMLs generados + patrones del stack |
| Feature Structure | AG-01 Feature Generator | Seccion de la fase + arquitectura del stack |
| Apps Script | AG-07 Apps Script | Seccion de la fase + patrones GAS |
| n8n / Workflows | AG-05 n8n Specialist | Seccion de la fase + patrones n8n |
| QA / Tests | AG-04 QA Validation | Archivos creados en fases previas (paths) |
| Quality Audit | AG-08 Quality Auditor | Evidence + baseline |
| Acceptance Tests | AG-09a Acceptance Tester | PRD con AC-XX + codigo implementado |
| Acceptance Gate | AG-09b Acceptance Validator | Evidence de AG-09a + audit de AG-08 |
Orquestador: Parsea plan → Extrae fases → Persiste plan en Engram
|
├─ Task(AG-03): DB/Infra → reporte → mem_save → checkpoint
├─ Task(AG-06): Diseño Stitch (si aplica) → reporte → checkpoint
├─ Task(AG-02): Design-to-code (si aplica) → reporte → checkpoint
├─ Task(AG-01): Feature → reporte → mem_save → checkpoint
├─ Task(AG-07): Apps Script (si aplica) → reporte → checkpoint
├─ Task(AG-05): n8n (si aplica) → reporte → checkpoint
├─ Task(Orq.): Integracion (DI, routing) → commit
├─ Task(AG-04): QA → reporte → checkpoint
├─ Task(AG-08): Quality Audit → veredicto GO/NO-GO
├─ Task(AG-09a): Acceptance Tests → evidencia
├─ Task(AG-09b): Acceptance Gate → veredicto ACCEPTED/REJECTED
|
└─ Orquestador: Consolida → Push → PR → mem_session_summary
Para cada fase, el orquestador ejecuta:
1. PREPARAR contexto (max ~20,000 tokens — v5.24.0 expandido para Opus 4.7):
- Extraer SOLO la seccion de la fase del plan
- Cargar overview de arquitectura del stack (~500 words max)
- Listar archivos que la fase va a modificar (paths, no contenido)
- Incluir checkpoint de la fase anterior
2. LANZAR sub-agente (Task tool):
- Contexto limpio e independiente
- Acceso completo a Read/Write/Edit/Bash
- Ejecuta lint, build, tests dentro de su contexto
3. RECIBIR reporte estructurado:
- files_created, files_modified, lint_result, phase_status, errors
4. CONSOLIDAR:
- mem_save con tags "phase,{N},{feature}"
- checkpoint.json
- Si failed → Self-Healing
- Si complete → commit + siguiente fase
- DESCARTAR contexto del sub-agente excepto resumen
Solo ejecutar si el plan referencia diseños que NO existen aun.
# Buscar HTMLs de diseño referenciados en el plan
ls doc/design/{feature}/*.html 2>/dev/null
stitch.projectId en .claude/settings.local.json~/.claude/settings.local.jsonmcp__stitch__list_projectsPara cada pantalla referenciada en el plan que no tenga HTML:
design/stitch/prompt-template.md)mcp__stitch__generate_screen_from_text(
projectId: "[stitch.projectId]",
prompt: "[prompt construido]",
deviceType: "[stitch.deviceType]",
modelId: "[stitch.modelId]"
)
mcp__stitch__get_screendoc/design/{feature}/{screen_name}.htmldoc/design/{feature}/{feature}_stitch_prompts.mdSi hay VEG activo: Enriquecer cada prompt Stitch con las directivas del Pilar 3 (Diseno):
Visual Direction (from VEG - {target_name}):
- Density: {density}, Whitespace: {whitespace}
- Visual hierarchy: {style}, CTA prominence: {prominence}
- Typography: headings {weight}, body {spacing}, hero {scale}
- Section separation: {separation_style}
- Mood: {mood} — this should FEEL {JTBD emocional}
- Data presentation: {data_style}
Image Placeholders (generate with placeholder boxes):
- Hero: [{type}] {description from VEG Pilar 1}
- (mark each with [IMAGE: {id}] for later replacement)
Reglas:
Prerequisito: VEG activo con prompts de imagen definidos (Pilar 1). Si el MCP de imagenes no esta configurado → registrar prompts pendientes y continuar.
OBLIGATORIO: Antes de generar imagenes, informar al usuario:
📷 VEG Image Generation — {N} imagenes
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Provider configurado: {primary} ({fallback} como fallback)
Coste estimado:
• Canva (Pro/Premium): €0 adicional (incluido en suscripcion)
• Freepik (Mystic): Segun plan contratado
• OpenAI GPT-Image-1: ~$0.02-0.19/imagen → total ~${min}-${max}
• Gemini Imagen 4: ~$0.02-0.06/imagen → total ~${min}-${max}
¿Continuar con la generacion de imagenes? (s/n/skip)
s = generar imagenes con MCP
n = cancelar VEG imagenes completamente
skip = documentar prompts para generacion manual posterior
Si el provider es canva y el usuario tiene suscripcion activa, el coste es €0 — mencionar explicitamente.
Si el usuario elige skip o n → saltar a Paso 3.5.4 (registrar prompts pendientes).
No basta con leer la config — hay que probar que el MCP responde.
veg.image_provider de .claude/settings.local.jsonprimary: "canva" → intentar Canva MCPprimary: "freepik" → intentar Freepik MCPprimary: "lansespirit" → intentar lansespirit MCPmcp__canva__search-designs con query trivial (ej: "test")mcp__freepik__check_status o mcp__freepik__search_resources con query trivialmcp__image-gen__generate_image con un prompt de test minimoHealth check OK?
├── SI → Continuar con generacion
├── NO (tool not found) → MCP no instalado
│ ├── Informar: "El MCP '{provider}' no esta configurado en este entorno.
│ │ Para configurarlo, anadir a .vscode/mcp.json o .claude/settings.json:"
│ │ {mostrar bloque JSON de configuracion del provider}
│ │
│ │ Canva: Solo necesita suscripcion Pro/Premium. Auth via OAuth (browser popup).
│ │ Freepik: Necesita FREEPIK_API_KEY con plan activo.
│ │ lansespirit: Necesita OPENAI_API_KEY y/o GOOGLE_API_KEY con billing activo.
│ └── Saltar a Paso 3.5.4 (registrar prompts pendientes)
├── NO (auth error / 401 / 403) → Sesion expirada o suscripcion inactiva
│ ├── Canva: "La sesion OAuth de Canva expiro. Reconectar en el navegador."
│ ├── Otros: "Verificar que la API key es valida y tiene creditos."
│ └── Saltar a Paso 3.5.4
└── NO (timeout / 500) → intentar fallback
├── Si hay fallback configurado → repetir health check con fallback
└── Si no hay fallback → Paso 3.5.4
El flujo depende del provider configurado.
Para cada [IMAGE: {id}] identificado en los disenos Stitch:
generate-design:
Create a {width}x{height} design: {prompt del VEG}.
Style: {mood from Pilar 1}. Palette: {palette}. Type: {photography/illustration}.
This is a standalone visual asset, not a presentation.
mcp__canva__generate-design con el promptmcp__canva__export-design para exportar como PNGdoc/veg/{feature}/assets/{image_id}.pngdoc/veg/{feature}/image_prompts.mdDimensiones por tipo de asset:
| Tipo | Dimensiones | Uso |
|---|---|---|
| Hero | 1920x1080 | Banner principal, above the fold |
| Feature illustration | 800x800 | Secciones de features |
| Background | 1920x1080 | Fondos de seccion |
| Icon/badge | 512x512 | Iconos decorativos |
| Social proof | 1200x630 | Testimonios, logos |
Para cada [IMAGE: {id}]:
search_resources
download_resource → usargenerate_image (Mystic AI)Para cada [IMAGE: {id}]:
generate_image (OpenAI GPT-Image-1 o Gemini Imagen 4)
veg.image_provider.maxImagesPerScreen (default 5)Si el MCP no estaba disponible, fallo, o el usuario eligio skip:
doc/veg/{feature}/PENDING_IMAGES.md:# Imagenes Pendientes — {feature}
> Generadas por VEG pero no producidas por MCP.
> Usar estos prompts para generar manualmente en Canva, Midjourney, DALL-E, Freepik, etc.
| ID | Tipo | Prompt | Aspect Ratio | Prioridad |
|----|------|--------|-------------|-----------|
| hero | photography | "{prompt completo}" | 16:9 | Alta |
| feature-1 | illustration | "{prompt completo}" | 1:1 | Media |
## Como completar
1. Generar cada imagen con el provider de tu preferencia
2. Guardar en `doc/veg/{feature}/assets/{id}.{ext}`
3. Ejecutar `/implement` de nuevo — detectara las imagenes y las integrara (Paso 6.1b)
## Coste estimado si se usa API
| Provider | Coste/imagen | Total ({N} imagenes) |
|----------|-------------|---------------------|
| Canva (Pro/Premium) | €0 | €0 |
| Freepik Mystic | Segun plan | Segun plan |
| OpenAI GPT-Image-1 | $0.02-0.19 | ${min}-${max} |
| Gemini Imagen 4 | $0.02-0.06 | ${min}-${max} |
[IMAGE: {id}] en los diseños — el Paso 6.1b los reemplazara cuando las imagenes existan.⚠️ {N} imagenes pendientes. Ver doc/veg/{feature}/PENDING_IMAGES.mdveg_images_pending = true
veg_images_pending == true:
> ⚠️ **VEG Pilar 1 incompleto**: Este PR usa {N} imagenes placeholder.
> Las imagenes profesionales deben generarse antes del deploy a produccion.
> Ver `doc/veg/{feature}/PENDING_IMAGES.md` para prompts listos.
veg_images_pending == true
REGLA: Cuando el VEG especifica imagenes (Pilar 1), los sub-agentes NO pueden sustituirlas por gradientes CSS, iconos SVG inline, o iniciales de texto como "solucion". Estas tecnicas son aceptables SOLO si el VEG no existe o no especifica imagenes.
¿El proyecto tiene VEG con Pilar 1 (Imagenes)?
├── SI: Las secciones que requieren imagenes DEBEN usar:
│ ├── Imagenes reales de doc/veg/{feature}/assets/ (si existen)
│ ├── Placeholders <img> con src apuntando a PENDING_IMAGES paths (si no existen)
│ └── NUNCA: gradientes CSS, divs con colores, iconos como sustituto de fotos
└── NO: Libre de usar cualquier tecnica visual
Convertir los HTML de Stitch a codigo del stack del proyecto.
OBLIGATORIO antes de escribir codigo con animaciones. Verificar e instalar:
¿El VEG tiene motion habilitado (motion_level != none)?
├── SI → Verificar e instalar dependencias:
│ ├── Flutter:
│ │ ├── Leer pubspec.yaml → ¿tiene flutter_animate?
│ │ ├── NO → ejecutar: flutter pub add flutter_animate
│ │ └── SI → verificar version compatible (^4.5.2)
│ ├── React:
│ │ ├── Leer package.json → ¿tiene motion?
│ │ ├── NO → ejecutar: npm install motion
│ │ └── SI → verificar version compatible (^12.35.0)
│ └── Python / Apps Script → N/A (sin motion library)
└── NO → Saltar (no hay animaciones que implementar)
Si la instalacion falla → WARNING, continuar design-to-code SIN animaciones.
Registrar en log: ⚠️ No se pudo instalar {package}. Design-to-code sin VEG Motion.
ls doc/design/{feature}/*.html
Si hay VEG activo, incluir el Motion Catalog (Pilar 2) en el contexto del sub-agente AG-02:
VEG Motion Catalog:
page_enter: {animation} {duration}ms {easing}
scroll_reveal: {animation} stagger {delay}ms
hover_buttons: {animation} {duration}ms
loading: {style}
transitions_pages: {type} {duration}ms
feedback_success: {animation}
feedback_error: {animation}
motion_level: {subtle / moderate / expressive}
Motion level rules:
- subtle: ONLY page_enter + loading. Skip scroll, hover, feedback.
- moderate: All except feedback animations.
- expressive: Full catalog.
Para cada HTML de diseno:
lib/presentation/features/{feature}/widgets/ para widgets especificoslib/core/widgets/ para widgets reutilizables (si se identifican)AppColors y AppSpacing (nunca hardcodear)_buildX())flutter_animate:
package:flutter_animate/flutter_animate.dart.animate() chainable para cada tipo de animacion del catalogo.shimmer())src/components/features/{feature}/ para componentes especificossrc/components/ui/ para primitivos reutilizables'use client' solo si necesita interactividadmotion (ex Framer Motion):
{ motion, AnimatePresence } de "motion/react"whileInView para scroll_reveal, whileHover para hover effectsAnimatePresence para page transitions y exit animationswhileHover → whileTap en todos los componentes interactivos@media (hover: hover) para aplicar condicionalmentewhileHover sin alternativa whileTap en un proyecto responsivesrc/html/ o html/ para templates HtmlServicegoogle.script.run para comunicacion con backend<style> en el template<?!= include('css') ?> para estilos compartidosCada archivo de pagina/pantalla generado por design-to-code DEBE incluir un comentario de trazabilidad en las primeras lineas:
// Generated from: doc/design/{feature}/{screen}.html
// Generated from: doc/design/{feature}/{screen}.html
# Generated from: doc/design/{feature}/{screen}.html
Regla: Si el archivo no tiene este comentario, AG-08 lo reportara como violacion de trazabilidad en el Check 6 (Design Traceability).
git add doc/design/{feature}/
git commit -m "design: add Stitch designs for {feature}"
CRITICAL: Each phase MUST be executed in an isolated Task to prevent context saturation.
Each spawned Task has a context budget. The main agent MUST control what goes into each task.
| Concepto | Budget máximo | Notas |
|---|---|---|
| Phase description | ~1,500 tokens | Del plan, sección completa de la fase (v5.24.0: ampliado para incluir edge cases) |
| Architecture rules | ~4,500 tokens | Overview del stack + patrones relevantes para la fase |
| Relevant source files | ~11,000 tokens | Archivos que la fase modifica + dependencias cercanas (v5.24.0: permite contexto más rico) |
| Stack patterns | ~2,500 tokens | Patterns relevantes (ej: BLoC + repository + testing si es state mgmt) |
| Checkpoint state | ~500 tokens | JSON del checkpoint anterior + resumen de fases completadas |
| Total per task | ~20,000 tokens | ~2% de ventana de Opus 4.7 (1M context) — v5.24.0: expandido de ~8,700 |
INCLUIR en el Task:
EXCLUIR del Task (nunca cargar):
EXCLUIR de la respuesta del Task (poda de retorno):
Para cada fase, el main agent spawnea un Task con exactamente este formato:
Execute Phase {N}: {phase_name}
CONTEXT:
- Plan: {paste ONLY the phase section, not the full plan}
- Stack: {stack_name}
- Architecture: {paste overview paragraph, max 500 words}
- Files to modify: {list paths}
- Ownership: Only modify files in {ownership_paths}
RULES:
- Run lint after implementation: {stack_lint_command}
- Save checkpoint: node .claude/hooks/implement-checkpoint.mjs {feature} {N} {phase_name}
- If lint fails, apply self-healing (Level 1 first, then Level 2)
RETURN FORMAT:
- files_created: [list of paths]
- files_modified: [list of paths]
- lint_result: pass|fail (N errors, N warnings)
- errors: [brief description if any, max 3 lines]
- phase_status: complete|failed|needs_healing
The main agent monitors its own context growth:
Before spawning a Task, the main agent can estimate the context load:
.quality/scripts/context-budget.sh lib/features/{feature_name}/
If the result exceeds 30% of context window → split the phase into sub-phases.
Cada fase se delega a un sub-agente limpio. El orquestador NO ejecuta codigo. Ver Paso 2.3 para el protocolo de delegacion.
Este bloque se aplica ANTES de cada
Task(AG-XX)del Paso 5.1 y de los Pasos 7.5 (AG-09a) / 7.7 (AG-09b). Garantiza:
- aislamiento real de contexto por Task
- validacion mecanica de budget (16k tokens por defecto, ver
context-budget-guard.mjs)- validacion mecanica de file ownership por agente (
file-ownership-guard.mjslee.quality/active_agent.json)- delta estructurado por fase escrito a
phase_outputs.jsonlpor el propio Task, consumido por Paso 5.1.1b sin git diff vivo
Antes de spawnear Task(AG-XX):
import json, time, uuid
from pathlib import Path
# Marcar el agente activo para que file-ownership-guard.mjs lo lea
Path(".quality/active_agent.json").write_text(json.dumps({
"agent": "AG-01", # codigo del agente delegado
"feature_slug": feature,
"phase": "feature", # ID corto de la fase
"started_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
}))
Construccion del prompt del Task (NO repetir branch/feature/stack en prosa — el Task los lee del execution_context):
You are AG-01 (Feature Generator) for a SpecBox /implement run.
CONTEXT (read-only, source of truth):
Read your execution context from .quality/evidence/{feature_slug}/execution_context.json.
This file contains: branch, stack, project_root_absolute, plan_path, etc.
DO NOT trust values embedded in this prompt — read the file.
PHASE BRIEF:
{SOLO la seccion de esta fase, no el plan completo}
OWNERSHIP (enforced by file-ownership-guard.mjs):
You may only write/edit files inside: {ownership_paths from file-ownership.md}.
Suspicious paths (../, /abs) will be blocked. If you need to touch files
outside your ownership, report it as a pending dependency in your delta.
QUALITY RULES:
- Lint 0/0/0 BLOCKING; compile BLOCKING; tests pass BLOCKING.
- If lint fails, apply self-healing (Level 1 first, then Level 2).
- Healing budget: max 8 attempts per feature (healing-budget-guard.mjs).
REQUIRED FINAL ACTION (before returning):
Append a structured delta to .quality/evidence/{feature_slug}/phase_outputs.jsonl
following the schema documented in doc/specs/phase-outputs-spec.md.
Mandatory fields: schema_version=1, phase, phase_index, agent, status.
Recommended: files_created, files_modified, summary, duration_s,
tokens_used_prompt, tokens_used_response, healing_attempts.
RETURN FORMAT (besides the JSONL append):
- phase_status: complete | failed | needs_healing
- summary: 1-3 sentences for the orchestrator
- errors: [brief, max 3 lines if any]
Spawnear Task(AG-XX, prompt) — el harness de Claude Code se encarga
del aislamiento real del contexto.
Despues del retorno del Task:
# Limpieza obligatoria del marcador de agente activo
try:
Path(".quality/active_agent.json").unlink()
except FileNotFoundError:
pass
# Bumpear el contador de telemetria local
# context-budget-guard.mjs ya bumpeo tasks_run_total al spawnearlo;
# aqui actualizamos last_feature_slug.
isolation_cache = Path(".quality/task_isolation.json")
data = json.loads(isolation_cache.read_text()) if isolation_cache.exists() else {}
data["enabled"] = True
data["last_feature_slug"] = feature
data["last_event_at"] = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
isolation_cache.parent.mkdir(parents=True, exist_ok=True)
isolation_cache.write_text(json.dumps(data, indent=2))
Si el Task falla / crashea: el try/finally debe garantizar siempre la
limpieza de active_agent.json. El siguiente Task encontrara el archivo
borrado y operara con guard en modo no-op (no asume agente activo).
El orquestador lanza un Task por fase con el Phase Task Template:
Execute Phase {N}: {phase_name}
CONTEXT:
- Plan: {SOLO la seccion de esta fase, no el plan completo}
- Stack: {stack_name}
- Architecture: {overview del stack, max 500 words}
- Files to modify: {list paths}
- Ownership: Only modify files in {ownership_paths}
- Previous checkpoint: {checkpoint JSON de fase N-1}
RULES:
- Run lint after implementation: {stack_lint_command}
- Quality gate: lint 0/0/0 (BLOQUEANTE), compile (BLOQUEANTE), tests pass (BLOQUEANTE)
- Save checkpoint: node .claude/hooks/implement-checkpoint.mjs {feature} {N} {phase_name}
- If lint fails, apply self-healing (Level 1 first, then Level 2)
RETURN FORMAT (OBLIGATORIO):
- files_created: [list of paths]
- files_modified: [list of paths]
- lint_result: pass|fail (N errors, N warnings)
- gate_result: {lint, compile, tests} each pass|fail
- errors: [brief description if any, max 3 lines]
- phase_status: complete|failed|needs_healing
¿phase_status?
├── complete → Commit parcial + mem_save resumen + siguiente fase
├── needs_healing → Lanzar nuevo Task de healing (ver Self-Healing Protocol)
└── failed → Guardar checkpoint failed + escalar a humano
Despues de guardar el checkpoint, SIEMPRE actualizar pipeline_state.json para que
pipeline-phase-guard.mjs pueda validar la secuencia de fases mecanicamente:
# Leer estado actual o crear nuevo
PIPELINE_STATE=".quality/evidence/${feature}/pipeline_state.json"
mkdir -p ".quality/evidence/${feature}"
El orquestador mantiene y actualiza este archivo despues de CADA fase completada:
{
"feature": "${feature}",
"has_ui": true,
"has_db": true,
"completed_phases": ["db_infra", "stitch_designs", "design_to_code", "feature_code"],
"current_phase": "integration",
"last_updated": "2026-04-05T18:00:00Z"
}
Mapeo de fases del plan a IDs de pipeline_state:
| Fase del plan | ID en completed_phases | Condicion |
|---|---|---|
| DB/Infra (AG-03) | db_infra | Solo si el plan tiene fase DB |
| Stitch Designs (AG-06) | stitch_designs | Solo si proyecto tiene UI |
| Design-to-Code (AG-02) | design_to_code | Solo si proyecto tiene UI |
| Feature Code (AG-01) | feature_code | Siempre |
| Apps Script (AG-07) | appscript | Solo si aplica |
| n8n (AG-05) | n8n | Solo si aplica |
| Integration/DI | integration | Siempre (si hay fase) |
| QA/Tests (AG-04) | tests | Siempre |
IMPORTANTE: Si una fase no aplica al proyecto (ej: no hay DB), marcarla como completada al inicio para que el guard no bloquee las fases dependientes:
// Ejemplo: proyecto sin DB ni UI
{
"completed_phases": ["db_infra", "stitch_designs", "design_to_code"],
"has_ui": false,
"has_db": false
}
Esto permite que pipeline-phase-guard.mjs valide el orden sin falsos positivos.
v5.32.0: la fuente de verdad para los deltas paso de "lo que el orquestador observa via git diff" a
phase_outputs.jsonl. El propio Task escribe su delta al final de su corrida (Paso 5.0 lo exige), asi que aqui solo agregamos. Esto sobrevive a Tasks aislados que escriben en otra sesion.
Despues de guardar el checkpoint, agregar el delta block:
from server.implement_context import aggregate_for_spec_sync
# Lee phase_outputs.jsonl y devuelve el SpecSyncAggregate
agg = aggregate_for_spec_sync(feature)
# agg.overall_status ∈ {ok, partial, error, empty}
# agg.delta_count — files tocados (sum across phases)
# agg.files_created / files_modified / files_deleted — listas dedupeadas
# agg.phases — uno por fase, en orden de ejecucion
# agg.total_duration_s, agg.total_healing_attempts
Reglas de uso:
agg.overall_status == "error" → linea: "Fase {phase} fallida — pendiente de resolucion"agg.total_healing_attempts > 0 → linea adicional con count y nivel maximoEl orquestador YA NO mantiene implementation_deltas: list[str] en memoria.
Cualquier consulta posterior (Paso 7.7a, Paso 8.5.1a) re-llama a
aggregate_for_spec_sync(feature) — la fuente esta en disco.
IMPORTANTE: Este paso es informativo (nunca bloquea). Si phase_outputs.jsonl
no existe (Task legacy que no lo escribio), aggregate_for_spec_sync retorna
overall_status="empty" y el orquestador continua con la observacion via
git diff como fallback (compat con flujo pre-v5.32).
# Despues de cada modificacion .dart
dart fix --apply && dart analyze
# Despues de build_runner (Freezed, etc.)
dart run build_runner build --delete-conflicting-outputs && dart fix --apply
# Despues de cambios
npx eslint . --fix && npx tsc --noEmit
# Despues de cambios
ruff check . --fix && ruff format . && mypy .
# Despues de cambios
npm run lint && npm run build
Cada fase completada genera un commit:
# Formato: tipo(scope): descripcion
git add [archivos-de-la-fase]
git commit -m "feat({feature}): {descripcion de la fase}"
Tipos de commit:
feat: Nueva funcionalidadfix: Correccionrefactor: Reestructuracionchore: Configuracion, dependenciastest: Testsdesign: Diseños UITareas transversales post-implementacion.
Segun el stack:
| Stack | Accion |
|---|---|
| Flutter | Registrar en GetIt/Injectable, anadir GoRoutes |
| React | Actualizar App Router, registrar stores |
| Python | Registrar routers en main.py, actualizar DI |
| Apps Script | Exportar funciones en index.ts, actualizar appsscript.json scopes |
Si el Paso 3.5 genero imagenes en doc/veg/{feature}/assets/:
| Stack | Accion |
|---|---|
| Flutter | Copiar a assets/images/veg/ + registrar en pubspec.yaml assets |
| React | Copiar a public/images/veg/ o src/assets/veg/ + importar en componentes |
| Python | Copiar a static/images/veg/ (si tiene frontend) |
| Apps Script | Subir a Google Drive o embeber como base64 en HTML |
Referenciar las imagenes en los widgets/componentes generados en Paso 4, reemplazando los placeholders [IMAGE: {id}] con las rutas reales.
# Flutter
dart run build_runner build --delete-conflicting-outputs
dart fix --apply && dart analyze
# React
npm run build
# Python
ruff check . --fix && mypy .
# Apps Script
npm run build
git add .
git commit -m "chore({feature}): integration and wiring"
# Flutter
flutter test --coverage
lcov -l coverage/lcov.info | tail -1 # Verificar >= 85%
# React
npx jest --coverage --passWithNoTests
# Python
pytest --cov --cov-report=term-missing
# Apps Script
npm run test
Cobertura minima: 85%
Si la cobertura es menor:
# Flutter
dart analyze
# React
npx eslint . && npx tsc --noEmit
# Python
ruff check . && mypy .
# Apps Script
npm run lint
git add .
git commit -m "test({feature}): add tests with 85%+ coverage"
Generar y ejecutar tests BDD en formato Gherkin que validen acceptance criteria del PRD. PRD es OBLIGATORIO. Sin PRD no hay AC-XX → no hay acceptance tests → pipeline PARA.
¿Cómo encontrar el PRD?
├── Spec-Driven (Trello/Plane/FreeForm)
│ └── get_evidence(board_id, us_id, "us", "prd") → extraer PRD adjunto
├── Existe doc/prd/{feature}.md o doc/prd/PRD_{feature}.md
│ └── Leer directamente
├── Existe en attachment de la US card/item
│ └── Descargar y leer
└── No se encuentra PRD en NINGUNA ubicacion
└── ERROR FATAL: "No PRD found. Cannot validate acceptance criteria."
└── PARAR PIPELINE — no continuar sin PRD
└── Reportar al usuario: "PRD requerido. Ejecutar /prd primero."
Extraer sección "Criterios de Aceptación > Funcionales":
Delegar a AG-09a (ver agents/acceptance-tester.md).
Generar un archivo .feature por cada UC del plan actual, con un Escenario por cada AC-XX:
# language: es
@US-XX @UC-XXX
Característica: {Título del UC-XXX}
@AC-01
Escenario: {Descripción del AC-01}
Dado ...
Cuando ...
Entonces ...
@AC-02
Escenario: {Descripción del AC-02}
Dado ...
Cuando ...
Entonces ...
Reglas:
@US-XX, @UC-XXX, @AC-XX en cada escenario# language: es.feature por UC, un Escenario por AC-XXUbicación por stack:
| Stack | Directorio |
|---|---|
| Flutter | test/acceptance/features/ |
| React | tests/acceptance/features/ |
| Python | tests/acceptance/features/ |
| GAS | tests/acceptance/features/ |
Generar step definitions usando el framework BDD nativo del stack:
Flutter (Playwright E2E contra CanvasKit web build):
e2e/acceptance/steps/UC-XXX_steps.tsplaywright-bdd + @playwright/teste2e/acceptance/steps/common_steps.ts si existeevidenceStep() en cada paso (PASS y FAIL)retain-on-failurehtml + json (OBLIGATORIO ambos)flutter build web --web-renderer canvaskit --releasegetByRole() semánticos (CanvasKit no genera DOM)React (Playwright E2E real):
tests/acceptance/steps/UC-XXX_steps.tsplaywright-bdd + @playwright/testtests/acceptance/steps/common_steps.ts si existeevidenceStep() en cada paso (PASS y FAIL)retain-on-failurehtml + json (OBLIGATORIO ambos)Python (pytest-bdd):
tests/acceptance/steps/UC_XXX_steps.pypytest-bddtests/acceptance/steps/common_steps.py si existeGAS (jest-cucumber):
tests/acceptance/steps/UC-XXX_steps.tsjest-cucumbertests/acceptance/steps/common_steps.ts si existeVerificar que las dependencias BDD están instaladas. Si no, instalarlas:
# Flutter
flutter pub add --dev bdd_widget_test
# React
npm install -D playwright-bdd
# Python
pip install pytest-bdd
# GAS
npm install -D jest-cucumber
# Flutter
flutter test test/acceptance/ --reporter json > reports/cucumber-report.json
# React
npx bddgen && npx playwright test tests/acceptance/ --reporter=json
# Python
pytest tests/acceptance/ --cucumberjson=reports/cucumber-report.json
# GAS
npx jest tests/acceptance/ --json --outputFile=reports/cucumber-report.json
Guardar en .quality/evidence/{feature}/acceptance/:
cucumber-report.json)Para Flutter y React, generar informe HTML self-contained con screenshots base64. El humano abre este archivo en su browser para validar calidad visual del E2E.
results.json de .quality/evidence/{feature}/acceptance/agents/acceptance-tester.md seccion 8.quality/evidence/{feature}/acceptance/e2e-evidence-report.htmlEl informe DEBE incluir:
Generar PDF con estructura:
Guardar en .quality/evidence/{feature}/acceptance/acceptance-report.pdf
Si el flujo es spec-driven (tiene board_id y UC card):
attach_evidence(board_id, uc_card_id, "uc", "acceptance", pdf_path)
Agregar comentario estructurado en la card del UC:
Acceptance Tests — UC-XXX
{N} passed / {M} failed | Pass rate: XX%
Evidencia adjunta: acceptance-report.pdf
HTML report: .quality/evidence/{feature}/acceptance/e2e-evidence-report.html
git add test/acceptance/ tests/acceptance/ e2e/acceptance/ .quality/evidence/{feature}/acceptance/
git commit -m "test(acceptance): E2E acceptance tests + evidence report for UC-XXX"
NOTA: Si los acceptance tests fallan, NO bloquear aqui. Reportar fallos y dejar que AG-09b decida el veredicto en Paso 7.7.
Ejecutar AG-08 Quality Auditor para verificar calidad de código. Ver
agents/quality-auditor.mdpara checks completos.
Ejecutar audit completo:
Generar .quality/evidence/{feature}/audit.json y .quality/evidence/{feature}/report.md.
Emitir veredicto: GO / CONDITIONAL GO / NO-GO
Si NO-GO → Aplicar self-healing (ver Self-Healing Protocol) y re-auditar. Máximo 2 intentos.
Validación independiente de que la feature cumple los acceptance criteria. PRD es obligatorio (Paso 7.5 ya lo verifico). Si llegamos aqui, el PRD existe.
Delegar a AG-09b (ver agents/acceptance-validator.md). El validador recibe:
git diff main..HEAD (código implementado)ACCEPTED → Continuar a Paso 8 (crear PR)
CONDITIONAL → Healing (ver 7.7.3), luego re-validar
REJECTED → Healing (ver 7.7.3), luego re-validar
Si CONDITIONAL o REJECTED:
acceptance-report.json → identificar criterios FAILacceptance-report.mdnode .claude/hooks/implement-healing.mjs {feature} acceptance {level} "{action}" "{result}"
Si el pipeline NO es spec-driven (no hay board_id ni Trello/Plane configurado):
implementation_deltas[] tiene al menos 1 entradauc_id del nombre del plan (e.g. uc_001_plan.md → UC-001) o usar "FREEFORM"git rev-parse --abbrev-ref HEADdoc/prds/ usando find_prd_path(project_path, feature=feature_name)append_implementation_status(prd_path, uc_id, branch, implementation_deltas)git add doc/prds/{prd_file}
git commit -m "docs({feature}): add Implementation Status for {uc_id}"
IMPORTANTE: En modo spec-driven, este paso se ejecuta en 8.5.3a en su lugar.
git push -u origin feature/{nombre-del-plan}
Analizar todos los commits de la rama para generar el body:
# Ver commits de la rama
git log main..HEAD --oneline
# Ver archivos cambiados
git diff main..HEAD --stat
gh pr create \
--title "[Feature] {Titulo del plan}" \
--body "$(cat <<'EOF'
## Summary
{Resumen del plan en 2-3 bullet points}
## Changes
{Lista de cambios principales agrupados por fase}
## Stitch Designs
{Si aplica: lista de pantallas generadas con links a HTMLs}
## Acceptance Evidence
{Generar tabla desde acceptance-report.json de AG-09b. Si no hay PRD/AC-XX, omitir sección.}
| Criterio | Status | Evidencia |
|----------|--------|-----------|
| AC-01: {descripción} | ✅ PASS | [screenshot](evidence/AC-01.png) |
| AC-02: {descripción} | ✅ PASS | [screenshot](evidence/AC-02.png) |
| AC-XX: {descripción} | ⚠️ CONDITIONAL | [trace](evidence/AC-XX_trace.zip) |
**AG-09 Verdict**: {ACCEPTED / CONDITIONAL / REJECTED}
**AG-08 Verdict**: {GO / CONDITIONAL GO / NO-GO}
## Test Plan
- [ ] Tests unitarios pasan con 85%+ coverage
- [ ] Lint sin errores
- [ ] Build exitoso
- [ ] Acceptance tests pasan
- [ ] {Criterios adicionales del plan}
## Developer Feedback
{Si existe .quality/evidence/${feature}/feedback-summary.json con open > 0:}
| ID | Severity | AC-XX | Status | GitHub |
|----|----------|-------|--------|--------|
{Fila por cada FB-NNN open}
{Si no hay feedback o todos resueltos: "No developer feedback reported."}
## Plan Reference
`{path al plan}`
---
🤖 Implementado con [SpecBox Engine](https://github.com/jesusperezdeveloper/specbox-engine) `/implement`
EOF
)"
Si el plan referencia un work item de Plane/Trello:
Si estamos en modo autopilot (ejecutando múltiples cards en secuencia), merge antes de iniciar la siguiente card. Esto evita conflictos entre PRs.
Estas validaciones se ejecutan ANTES de verificar condiciones de auto-merge. Son HARD BLOCKS — si fallan, el merge NO puede proceder bajo ninguna circunstancia.
VALIDACION 1: ¿Estamos en una rama feature/?
branch = git branch --show-current
¿branch empieza con "feature/"?
├── SI: OK
└── NO: ❌ ERROR FATAL
→ "BLOQUEADO: No se puede hacer merge desde '{branch}'.
El protocolo requiere una rama feature/ con PR asociada.
Algo salto el Paso 1 (Crear Rama de Feature)."
→ PARAR INMEDIATAMENTE.
VALIDACION 2: ¿Existe PR abierta para esta rama?
gh pr view --json state,url 2>/dev/null
¿Existe PR con state == "OPEN"?
├── SI: OK — guardar URL para referencia
└── NO: ❌ ERROR FATAL
→ "BLOQUEADO: No hay PR abierta para la rama actual.
El Paso 8 debio crear una PR antes de llegar aqui.
Sin PR no hay acceptance evidence ni review."
→ PARAR. Ofrecer ejecutar Paso 8 como recovery.
VALIDACION 3 (solo Trello spec-driven): ¿El UC esta en estado correcto?
uc_data = get_uc(board_id, uc_id)
¿uc_data.status == "in_progress"?
├── SI: OK — el UC fue iniciado correctamente con start_uc
└── NO: ⚠️ WARNING
→ "El UC {uc_id} esta en estado '{uc_data.status}' en lugar de 'in_progress'.
Esto indica que start_uc no fue llamado o fallo."
→ Intentar start_uc como recovery
→ Continuar con WARNING en el log
VALIDACION 4: ¿El flag veg_images_pending esta activo?
¿veg_images_pending == true?
├── SI: Auto-merge BLOQUEADO
│ → "⚠️ Auto-merge bloqueado: VEG Pilar 1 incompleto ({N} imagenes placeholder).
│ Opciones:
│ a) Generar imagenes con /implement --images-only
│ b) Aprobar merge manualmente aceptando calidad visual degradada
│ c) Crear PENDING_IMAGES.md y resolver post-merge"
│ → Esperar decision del usuario
└── NO: OK
Auto-merge SOLO si se cumplen TODAS estas condiciones:
veg_images_pending == false) — NUEVO v4.0.1Si existe .quality/evidence/${feature}/feedback-summary.json:
blockingblocking == true → merge bloqueado por feedback¿Todas las condiciones se cumplen?
├── SÍ → Paso 8.5.2 (auto-merge)
└── NO → Pausar, notificar al usuario, esperar aprobación manual
→ Si el bloqueo es por feedback:
"⚠️ Merge bloqueado: {N} feedback tickets abiertos ({blocking_ids})"
"Resolver con /feedback resolve FB-NNN o aprobar manualmente"
→ Si el bloqueo es por AG-09b INVALIDATED:
"⚠️ AG-09b verdict fue INVALIDATED por feedback {FB-NNN}."
"Re-ejecutar /implement para re-validar o resolver feedback primero."
→ Cuando el usuario apruebe: continuar con 8.5.2
Antes del merge, escribir el Implementation Status en el PRD:
doc/prds/ por us_id o feature namefrom server.implement_context import aggregate_for_spec_sync
agg = aggregate_for_spec_sync(feature)
# agg.phases es la lista que antes llamabamos implementation_deltas
compile_uc_status(uc_id, branch, agg.phases) (la firma de
compile_uc_status acepta tanto la lista vieja de strings como la
lista nueva de dicts; mantiene compat con flujos pre-v5.32).append_implementation_status(prd_path, uc_id, branch, agg.phases)git add doc/prds/{prd_file}
git commit -m "docs({feature}): add Implementation Status for {uc_id}"
git push origin {branch}
agg.overall_status == "empty" → WARNING (probable Task legacy que no
escribio phase_outputs.jsonl); fallback al flujo pre-v5.32 con git diff.Tambien disponible como MCP tool: write_implementation_status(project_path, uc_id, branch, phase_deltas)
Consulta posterior: get_implementation_status(project_path, item_id) — devuelve JSON con deltas y overall_status
gh pr merge --squash --delete-branch
git checkout main
git pull origin main
move_uc(board_id, uc_id, "review") — mueve UC a Review (NO a Done)attach_evidence(board_id, uc_id, "uc", "acceptance", evidence_md)mark_ac_batch(board_id, uc_id, results)IMPORTANTE: El agente NUNCA mueve a Done. Solo a Review. El humano revisa la PR, ejecuta flujos manuales, verifica E2E, y SOLO ENTONCES mueve a Done (manualmente o via complete_uc). Si todos los UCs de la US estan en Review/Done, la US se queda en su estado actual — el humano decide cuando mover la US a Done.
→ Llamar find_next_uc(board_id) para obtener siguiente UC en Backlog
→ Si hay UC disponible:
→ start_uc(board_id, uc_id) — mueve a In Progress
→ Volver a Paso 0.1a con el nuevo UC
→ El nuevo feature branch parte del main actualizado (post-merge)
→ CERO conflictos garantizados
→ Si no hay mas UCs en Backlog:
→ Verificar si todos los UCs de la US estan en Review o Done
→ NO mover US a Done — el humano decide tras revisar todas las PRs
→ Finalizar pipeline con resumen global
→ Volver a Paso 0 con la siguiente card
→ El nuevo feature branch parte del main actualizado (post-merge)
→ CERO conflictos garantizados
Si no hay mas cards → finalizar pipeline con resumen global.
## ✅ Implementacion Completada
**Plan**: `{path al plan}`
**Rama**: `feature/{nombre}`
**PR**: {url de la PR}
### Resumen de ejecucion:
| Fase | Estado | Commits |
|------|--------|---------|
| Diseño Stitch | ✅/⏭️ Saltado | {N} |
| Design-to-code | ✅/⏭️ Saltado | {N} |
| {Fase 1 del plan} | ✅ | {N} |
| {Fase 2 del plan} | ✅ | {N} |
| Integracion | ✅ | {N} |
| QA | ✅ | {N} |
### Metricas:
- **Archivos creados**: {N}
- **Archivos modificados**: {N}
- **Tests**: {N} pasando
- **Coverage**: {X}%
- **Commits**: {N} totales
- **Diseños Stitch**: {N} pantallas (si aplica)
### PR lista para review:
{url de la PR}
Cuando una fase falla, el sistema intenta auto-recuperarse antes de pedir intervención humana.
Para errores de lint/format:
dart fix --apply && dart format .npx eslint --fix . && npx prettier --write .ruff check --fix . && ruff format .npx eslint --fix .Para errores de compilación o imports:
Si el error persiste tras Nivel 2:
git stash los cambios de la fase actual.quality/evidence/${feature}/healing.jsonl:
{"phase": N, "error": "...", "level": 3, "action": "rollback", "timestamp": "..."}
Si nada funciona:
.quality/evidence/${feature}/error_report.md con:
TODOS los intentos de self-healing se registran en .quality/evidence/${feature}/healing.jsonl:
{"phase": 1, "error": "dart analyze: 3 errors", "level": 1, "action": "dart fix --apply", "result": "resolved", "timestamp": "..."}
{"phase": 3, "error": "build failed: missing import", "level": 2, "action": "added import to user_bloc.dart", "result": "resolved", "timestamp": "..."}
1. Registrar el error
2. Reintentar UNA vez
3. Si falla de nuevo:
- Continuar con las demas pantallas
- Reportar pantallas fallidas al final
- La implementacion continua sin esos diseños
1. Identificar archivos sin coverage
2. Generar tests adicionales (hasta 3 intentos)
3. Si no se alcanza:
- Reportar coverage actual
- Listar archivos que necesitan tests
- Crear la PR de todas formas con nota sobre coverage
1. NO resolver automaticamente
2. Reportar los archivos en conflicto
3. Pedir al usuario que resuelva
4. Continuar despues de la resolucion
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.
Configure complete visual identity for a project before development. Use when the user says "visual setup", "setup design", "configure brand", "design system", "visual identity", "brand kit", or wants to set up Stitch + VEG + brand tokens before running /plan.
Audits, cleans, and releases a new SpecBox Engine version. Checks for residual code, updates ENGINE_VERSION.yaml, CLAUDE.md, changelog, and pushes to remote. Use when the user says "release", "bump version", "new version", "cut release", "audit and release", "sube version", "prepara release".
Cambia el backend de tracking de un proyecto entre los 4 (FreeForm / Trello / Plane / Native) de forma guiada y sin pérdida de avance. Migra US/UC/AC/comments/ estado al destino, actualiza atómicamente los 3 lugares de verdad, y ofrece regenerar evidencias. Use when the user says "switch backend", "cambiar backend", "migrar de FreeForm a Trello/Plane/Native", "mover el tracking a", "change tracking backend".
ISO/IEC 25010 (SQuaRE) quality audit on-demand for onboarded projects. Use when the user says "audit project", "quality audit", "ISO 25010", "SQuaRE audit", "audita el proyecto", or wants a comprehensive quality report across 8 characteristics with PDF + JSON evidence.
Capture developer testing feedback as structured evidence and GitHub issues. Use when the user says "report feedback", "found a bug", "this doesn't work", "feedback on feature", "AC-XX is wrong", or reports an issue found during manual testing. Links feedback to acceptance criteria and blocks merge if unresolved.