¿Qué hace plan-it?
Toma una demanda difusa → entrega un paquete construible. Este es el director
de planificación: la mitad frontal disciplinada del ciclo de vida que termina exactamente donde
comienza /build-it. Realiza descubrimiento (investigar la verdad sobre el terreno), especificación
(redactar los documentos de diseño) y división ágil (PRDs, épicas, pruebas, el contrato
compartido) — y luego transfiere.
/plan-it ─────────────► docs/ + delivery/ ─────────────► /build-it
(descubrimiento → especificación → plan) (el paquete construible) (lo construye)
Utilizable directamente por un humano, y por cualquier agente conductor orquestador que reciba una nueva demanda y deba convertirla en un paquete de entrega antes de despachar trabajadores.
Las cinco reglas no negociables (aplícalas — no solo las sugieras)
Estas son las reglas estructurales extraídas de cada ejecución exitosa. Si violas una, la construcción aguas abajo se desvía o falla silenciosamente.
-
Congela un CONTRATO compartido antes de cualquier planificación paralela. El CONTRATO es la ley: entidades canónicas, esquema, API/interfaz, enumeraciones, mapa de repos/ramas y la definición de "entregado". Los equipos escriben para él; cualquier descubrimiento transversal se pliega de vuelta en él como una enmienda fechada (v1.0 → v1.1 …). Sin contrato congelado → sin equipos paralelos.
-
Agrupa cada decisión exclusivamente humana en UNA compuerta. No decidas de antemano nada irreversible (topología del repo, alojamiento, nombre del producto, modo arquitectónico, construir-vs-comprar). Preséntalos juntos, cada uno con una recomendación adjunta, y deja que el humano responda numerados. Esta compuerta es donde el humano inyecta visión, no solo elige opciones — deja espacio para que añadan un concepto que no propusiste. Bloquea cada respuesta con propietario + fecha.
-
Verifica la salida de cada agente en disco — "inactivo ≠ entregado". Un equipo que pasa a inactividad NO significa que haya escrito archivos. Después de cualquier expansión, verifica que las rutas reales existan y no estén vacías antes de continuar. Si un equipo retuvo su salida como mensaje, indícale que
Escribaen la ruta absoluta exacta. Nunca confíes en un "listo". -
Contrasta el plan contra el SISTEMA EN VIVO, no contra el repo — antes de congelar. Para cualquier plan que toque un sistema en ejecución, el repo es una hipótesis; la realidad desplegada es la verdad, y divergen. Antes de congelar el CONTRATO, verifica contra el sistema real y escribe las observaciones (no suposiciones derivadas del repo). Probado en batalla: en un programa, CADA corrección a medio camino se remontaba a una suposición inferida del repo que la realidad contradecía — identificadores canónicos incorrectos (los manifiestos habían divergido del catálogo desplegado), un valor de configuración que existía-pero-apuntaba-a-un-host-muerto, componentes "por construir" que ya estaban desplegados y una credencial encontrada que era la incorrecta. Consulta la compuerta de anclaje en vivo de la Fase 3 para las comprobaciones concretas.
-
Ejecuta la máquina, no la prosa. El flujo de control del pipeline vive en
machine.json(el diagrama de estados explícito), no en este documento — esta prosa explica la máquina. Al invocar, lee o inicializa.plan-it/state.json(en el proyecto de destino) y reanuda desde sustate; escríbelo en cada transición. En cada transición vigilada, ejecuta el subcomando asignado al guardián (node scripts/gate-check.mjs <check> …) y nunca avances ante una salida distinta de cero — corrige, vuelve a ejecutar, luego transiciona. Si Node no está disponible, realiza las mismas comprobaciones manualmente y regístralas en el archivo de estado (degrade, nunca rompas). Protocolo completo:references/machine.md.
El núcleo determinista (v2) — por qué una máquina
El flujo de control escrito como prosa ("haz el paso 1, nunca te saltes la compuerta") es lo que la literatura sobre determinismo llama flujo de control en prosa: depende de la disciplina del modelo en un contexto largo y propenso a resumir, y a veces el modelo no lo sigue. v2 lo invierte a la altitud correcta — no determinismo en los bordes, determinismo en el núcleo:
machine.json— diagrama de estados del pipeline compatible con XState v5: 15 estados, las tres compuertas humanas (meta.gate+meta.human), transiciones vigiladas, y un bucle automáticoAMENDMENTenparallelPlanning. Pégalo en stately.ai/viz para verlo..plan-it/state.json— la ejecución persistida: estado actual, aprobaciones de compuerta (propietario + fecha), versión del contrato, registro de artefactos verificados, historial. Esto es lo que hace que una ejecución sobreviva a un bloqueo o a una sesión nueva.scripts/gate-check.mjs— los guardianes como códigos de salida:verify(Regla 3, inactivo ≠ entregado),freeze(Regla 1, sin contrato → sin equipos),handoff(la parte mecanizable de los playbooks §F),state(Regla 2, compuertas registradas),adversary(Regla 6 / D4 — profundidad del modo de fallo: una máquina modelada debe cubrir-o- eximir las cinco clases de cascada; N/A para flujos de trabajo lineales). Las transicionesLINT_CLEANyADVERSARY_CLEAN(verify → adversaryGate → handoff) dependen de las dos últimas.
Las fases difusas — descubrimiento, síntesis, redacción de especificaciones, juicio — permanecen
como LLM-en-el-nodo (etiquetadas llmAtTheNode en la máquina). No las formalices;
el modelado no es ceremonia solo cuando reemplaza confusión. Detalles, esquema del archivo de estado,
y el protocolo de reanudación: references/machine.md.
Imposición estricta (v2.1, instalación de plugins solo en Claude Code): un enganche
PreToolUse (scripts/hooks/planit-guard.mjs) deniega llamadas Write/Edit en entregables de PRD/épica
mientras la ejecución del contrato no esté congelada — la Regla 1 deja de ser una instrucción y se convierte
en algo que el arnés rechaza. Falla-abierto: nunca toca trabajo que no sea de plan-it. Las instalaciones
solo de skill dependen en cambio de la disciplina de la Regla 5.
El Contrato de Prueba — el diferenciador de calidad (hazlo no negociable)
Lo que más eleva la calidad del código entregado: cada PRD/épica termina generando su propio
contrato de prueba — hasta ~20 casos de uso/escenarios concretos que estresan la implementación —
y la función NO está "terminada" hasta que el 100% de ellos pase.
El agente de construcción no puede simplemente entregar la función; debe satisfacer el contrato,
y /iterate hasta que esté en verde.
Esta es una disciplina con nombre y probada: Specification by Example (Gojko Adzic) + ATDD/BDD para código (los ejemplos concretos se convierten en pruebas de aceptación ejecutables y en documentación viva), y Desarrollo Impulsado por Evaluación para skills/funciones LLM (registra dorados con salidas esperadas, itera hasta que pasen). Redactar los casos en el momento de la planificación es el punto clave — se convierten en un contrato vinculante, no una ocurrencia tardía.
Reglas del Contrato de Prueba:
- Redactado en el momento de la planificación — el ÚLTIMO paso de escribir cada épica/PRD es su contrato de prueba. Las salidas esperadas se registran ahora ("diseñado primero; salidas esperadas registradas"), no se descubren durante la construcción.
- Hasta ~20 casos de alta calidad por función — suficientes para estresar el comportamiento real + bordes; no miles de casos superficiales (calidad > cantidad — auto-masivo = "chapuza", según la literatura de evaluación). Extrae casos de modos de fallo reales/probables. Regla de conteo por forma: los programas grandes de Forma-1 con múltiples equipos tienen un mínimo de ≥10 casos por épica (cada épica es una función grande); las formas pequeñas (único skill/función, S/M) redactan ~20 casos en total en todo el paquete (un puñado por épica). Nunca ambos a la vez — elige por forma para que un revisor no marque un paquete pequeño correcto como insuficientemente probado.
- Vinculante — DoD = 100% del contrato pasa; hasta entonces,
/iterate. No hay envío parcial; no hay VERIFICADO-en-un-mock (un caso[REAL]cuyo destino es inalcanzable → IMPLEMENTADO-NO-VERIFICADO, nunca un falso verde). - Elige los tipos de prueba por implementación (uno o más de unitaria / e2e / casos de uso / estrés):
| Implementación | Tipos de prueba | Cómo |
|---|---|---|
| CRUD / API REST | casos de uso (feliz+borde) + e2e | ejecuta cada escenario vía API y vía UI con Chrome CDP (chrome-cdp-control); prueba unitaria de la lógica |
| Skill / prompt / función LLM | casos de uso con salida esperada | ejecútalo, compara real vs esperada — coincidencia exacta para salidas cerradas, rúbrica / LLM-como-juez para abiertas (make-eval, promptfoo, DeepEval G-Eval) |
| Agente / con estado / multi-paso | escenarios de estrés + casos de uso | seis ejes: asíncrono, expansión, escalamiento, compuerta humana, recursión, guarda de ciclo (Configuración/Esperado/Pasa) |
| Lógica pura / librería | unitaria + basada en propiedades | casos enumerados + invariantes |
| Pipeline de datos / migración | valor-dorado + e2e | valores esperados calculados a mano; idempotencia/reversión |
| Cualquier cosa con superficie de carga/abuso | estrés / adversarial | concurrencia, tasa, entrada malformada, equipo rojo |
- Ruta de ejecución:
/full-qaejecuta el contrato,/iteratelo repite hasta el 100%,chrome-cdp-controlmaneja escenarios de UI. El contrato es el puente de plan-it → build-it: la Definición de Terminado de/build-it= este contrato.
Gramáticas y el formato del encabezado del contrato: references/formats.md (el bloque del Contrato de Prueba
- §4–5).
Postura de autonomía (guiada con ráfagas autónomas)
Ejecuta la investigación y redacción de forma autónoma con alto esfuerzo, pero detente en tres compuertas:
| Compuerta | Cuándo | Qué preguntas |
|---|---|---|
| G1 — Alcance | después de la ingesta (Fase 2) | confirma el dimensionamiento (función vs programa) + la DoD numerada antes de invertir esfuerzo |
| G2 — Decisiones | después de redactar las especificaciones (Fase 7) | las decisiones agrupadas "solo tú puedes tomar", cada una con una recomendación |
| G3 — Entrega | antes de la división ágil (Fase 8) | "las especificaciones parecen alineadas — ¿procedo a PRDs/épicas?" |
Todo lo que hay entre las compuertas funciona sin supervisión. Recomienda /effort xhigh al principio
(no puedes configurarlo tú mismo — dile al usuario que ejecute /effort xhigh si no lo ha hecho).
Fase 0 — Ingesta
Máquina primero (Regla 5): si .plan-it/state.json existe en el proyecto de destino,
ejecuta node scripts/gate-check.mjs state .plan-it/state.json y reanuda desde el
estado impreso — no reinicies fases ya presentes en history. Si no existe,
creálo ahora en estado intake (esquema en references/machine.md) y mantenlo actualizado
en cada transición durante el resto de la ejecución.
Acepta la demanda en la forma que llegue: un volcado de cerebro, una transcripción pegada,
una lista de deseos, o una frase corta. Espera referencias, no contenido —
nombres de sesión (/read-chat "<nombre>"), rutas de repo, carpetas de documentación. Tu trabajo es ir a
buscar la verdad sobre el terreno, no que te la entreguen.
Captura de antemano:
- La visión en bruto en las propias palabras del usuario (la citarás de vuelta en
02 §1). - Referencias a sesiones / repos / documentos anteriores para investigar.
- Caso de uso (detección automática — esto impulsa la forma del paquete en la Compuerta G1):
- nueva aplicación única, campo verde · función en un repositorio grande existente · programa multisistema desde cero · plataforma multiaplicación (muchas PRDs) · refactorización / migración / deuda · pico de investigación (sin construcción aún) · automatización PM/tablero · documento/auditar un sistema ya construido.
- Método de investigación: por defecto, equipos Claude paralelos en xhigh.
Si la demanda es genuinamente un párrafo difuso sin referencias y un repositorio existente, está bien — el anclaje previo (Fase 3) encontrará los objetivos.
Fase 1 — Bloqueo de DoD
Reestructura la prosa difusa en una Definición de Terminado numerada e individualmente verificable
- una lista corta de suposiciones declaradas. Este es tu contrato con el usuario para el trabajo de planificación en sí mismo. Ejemplo de forma:
DoD para esta ejecución de planificación:
1. Documento de hallazgos de verdad sobre el terreno (cada afirmación → ruta:línea o tabla)
2. Documento de visión + arquitectura que resuelve cada hallazgo/contradicción
3. Contrato de datos/interfaz
4. … (tamaño automático — ver Fase 2)
N. Transferencia: contrato congelado, PRDs+épicas con ≥10 pruebas cada una, prompt de inicio
Suposiciones: <lista>
Fase 2 — Gobernador de alcance y forma ⏸ COMPUERTA G1
Elige tamaño (cuánto) y forma (qué forma) antes de invertir esfuerzo. Confirma ambos con el usuario.
Tamaño escala el recuento de artefactos:
| Señal | Tamaño |
|---|---|
| Función única, 1 subsistema | S |
| Multifunción / nuevo subsistema, 1–2 repos | M |
| Programa desde cero / muchos subsistemas | L |
Forma se elige por caso de uso (definiciones completas + la tabla caso-de-uso→forma en
references/templates.md PARTE D):
- Multidoc +
delivery/(línea base) — programa desde cero, equipos paralelos. - PRD de archivo único como todo — aplicación única campo verde; CONTRATO en línea como reglas G.
- Investigación → arquitectura bloqueada → PRDs maestro+fase — función en un repositorio grande existente.
implementation/<name>/con PRD-NN numerado — plataforma multiaplicación, muchas PRDs.- Catálogo de trabajo de refactorización/deuda — campo marrón in situ. (+modos de pico de investigación, tablero ejecutable y documentación inversa — ver PARTE D.)
Mismas fases independientemente — solo cambian el recuento de artefactos y la forma. No le des a una
función una organización de 4 equipos; no le des a una refactorización de campo marrón un documento de visión de campo verde.
Presenta el tamaño + forma elegidos + la DoD numerada y obtén un sí antes de continuar.
Al recibir el sí, registra G1 = {approved, owner, date} más el tamaño/forma elegidos en
.plan-it/state.json — la transición G1_APPROVED está vigilada por gateRecorded.
Fase 3 — Anclaje previo
Antes de cualquier expansión, localiza los objetivos exactos para que los agentes reciban rutas precisas, no instrucciones vagas:
- Resuelve sesiones de referencia con un skill de lectura de sesiones (
/read-chato similar) si hay uno instalado; de lo contrario, solicita la transcripción o el resumen relevante. ls/greplos repos nombrados; encuentra lasdocs/, archivos de esquema, puntos de entrada.- Lee la caché caliente/índice del wiki si el repo está conectado a vault (según su
CLAUDE.md).
Salida: una lista de {subsistema → rutas exactas para leer} que siembra los equipos de investigación.
Compuerta de anclaje en vivo (regla 4) — cuando el plan toca un sistema EN EJECUCIÓN
El repo te dice lo que debería ser verdad; el sistema en vivo te dice lo que es. Haz esto antes de la congelación de la Fase 8, y escribe los hallazgos en el CONTRATO como hechos observados:
- Accesibilidad de configuración, no presencia. Para cada palanca de entorno/config de la que depende el plan (URLs base, hosts de API, indicadores de funcionalidad), golpéala — no solo confirmes que está configurada. Un valor puede estar configurado para un host muerto y pasar una comprobación de "existe" mientras rompe silenciosamente producción.
- Registro en vivo / identificadores canónicos. Duplica.
...
[truncado para traducción]