Formato Lean de Spec

El Lean Mode es la evolución del flujo de trabajo de Spec Driven Development en Planu. Reemplaza el antiguo formato de dos archivos (spec.md + technical.md separados) por un único documento unificado con frontmatter enriquecido. El resultado: menos sobrecarga de contexto, menos drift entre archivos y un encabezado legible por máquina sobre el que las herramientas de Planu pueden actuar de forma autónoma.

Qué es el Lean Mode

Antes del Lean Mode, cada spec requería dos archivos:

• spec.md — criterios de aceptación y enunciado del problema
• technical.md — detalle de implementación, tipos y listas de archivos

Mantener ambos sincronizados era propenso a errores. El Lean Mode los colapsa en un único spec.md con:

1. Un bloque de frontmatter YAML estructurado que contiene identidad, estado, orientación de modelo y restricciones de presupuesto
2. Una sección ## Technical al final del mismo archivo (ver spec.md Unificado)

Impacto en tokens. Las specs heredadas consumían ~50–100 K tokens de contexto por solicitud. Las specs lean se cargan en ~5 K tokens porque Planu lee solo el frontmatter para enrutar solicitudes y expande el cuerpo completo solo cuando es necesario.

Referencia de Frontmatter

Campo	Tipo	Requerido	Descripción
id	string	sí	Identificador único, formato SPEC-NNN
title	string	sí	Título legible por humanos (sentence case)
status	enum	sí	draft / review / approved / implementing / done / blocked
type	enum	sí	feature / fix / docs / refactor / chore
target	string	no	Capa principal — frontend, backend, infra, cross-module
scope	string	no	Radio de explosión — module, cross-module, system
difficulty	1–5	no	Puntuación de complejidad (1 trivial, 5 arquitectónico)
risk	enum	no	low / medium / high
model	enum	sí	Modelo recomendado — haiku / sonnet / opus
budget	number	sí	Presupuesto máximo de tokens para una ejecución de implementación
estimation.devHours	number	sí	Esfuerzo de desarrollo en horas
estimation.reviewHours	number	no	Esfuerzo de revisión en horas
estimation.totalCostUsd	number	sí	Costo USD estimado al precio del modelo indicado
tags	string[]	sí	Etiquetas de búsqueda (ej. [website, docs, vitepress])
branch	string	no	Nombre de la rama git — establecido automáticamente por create_spec
created	YYYY-MM-DD	sí	Fecha de creación de la spec
completedAt	YYYY-MM-DD	no	Fecha en que la spec alcanzó done — establecido por update_status

Ejemplo Anotado

---
id: SPEC-659              # Identificador único — nunca reutilizar
title: "Website — 5 new guide pages for Lean Mode features"
                          # Legible por humanos, sentence case, sin punto final
status: implementing      # Etapa actual del ciclo de vida — impulsa el autopilot
type: docs                # Uno de: feature / fix / docs / refactor / chore
target: frontend          # Capa más afectada por este trabajo
scope: cross-module       # Qué tan ampliamente se extiende el cambio
difficulty: 2             # Escala 1–5 (2 = moderado, principalmente contenido)
risk: low                 # Radio de explosión esperado
tags: [website, docs, lean-mode, guide, vitepress]
                          # Usados por la carga de herramientas por nivel
branch: docs/spec-659-website-5-new-guide-pages-for-lean-mode-features
created: 2026-04-24
model: sonnet             # Planu usa esto para recomendar qué modelo de Claude usar
budget: 2000              # Tokens máximos para una ejecución del agente de implementación
estimation:
  devHours: 6             # Esfuerzo humano (usado en reportes de velocidad)
  reviewHours: 1
  totalCostUsd: 8         # Precio de Sonnet × budget ÷ 1000
---

Por qué importan model y budget

Planu lee model y budget para validar de antemano que el plan de implementación cabe dentro del límite de tokens antes de lanzar sub-agentes. Configurarlos correctamente previene truncamientos a mitad de ejecución.

Ciclo de Vida del Estado

El campo status es el plano de control de las Transiciones de Estado Automáticas. Moverse entre estados activa cascadas de autopilot:

draft → review → approved → implementing → done

Cada transición se impulsa llamando a update_status. Ver Transiciones de Estado Automáticas para la tabla completa de cascadas.

---

Ver también

• spec.md Unificado (SPEC-630) — la sección ## Technical que vive dentro del mismo archivo
• Superficie MCP Enfocada — por qué Planu mantiene pequeña la lista pública de tools MCP
• Transiciones de Estado Automáticas — qué sucede cuando cambia el status