Lego Plan

¿Qué hace Lego Plan?

Convierte un cambio definido en un DAG por capas desde primitivas simples hasta una funcionalidad funcional. Solo planifica. Luego se detiene.

El grafo es una pirámide: bloques independientes en la base, bloques compuestos arriba, un solo nodo final. Un controlador posterior puede ejecutar nodos de la misma capa en paralelo, cambiar el status y redibujar este grafo. Esta habilidad no despacha subagentes. No carga otras habilidades.

Cuándo usarla

Cargar cuando la tarea es convertir un cambio definido en un mapa de implementación que el controlador pueda seguir.

• Necesidad: ya se ha elegido qué construir. Si ya hay una lista de archivos a tocar o una selección de rutas en esta conversación, úsala. Si no, trabaja desde la intención definida y el código. No inventes un segundo mapa del sistema.
• Omitir: errores tipográficos, comentarios, formato, documentación sin código.
• Si la intención aún está abierta: detente. Pregunta hasta que el cambio esté definido. No apiles bloques para una funcionalidad no elegida.

Un nodo sigue siendo un DAG. Emite el contrato completo.

Reglas estrictas

1. Solo planifica. No escribas código de producción. No escribas pruebas. Nombra la comprobación en done when. No la implementes aquí.
2. Detente después de emitir. Muestra el DAG en el chat y el archivo de tablero. No despaches. No cargues la siguiente habilidad.
3. Sin ciclos. Si un bloque depende de un bloque posterior, la división está mal. Divide de nuevo.
4. No esperes aprobación. Muestra el DAG y detente. El usuario interrumpe si está mal.
5. No abras el archivo de tablero para el usuario. No escribas un plan en docs/.

Granularidad de nodo

Nodo del grafo (unidad paralela): una primitiva independiente que un subagente puede asumir sin esperar a otro nodo en progreso.

Ejemplos: escribe fetchOrder, escribe OrderCard, conecta fetchOrder en el cargador.

Demasiado grande: implementa auth. Divídelo. Demasiado pequeño: renombra una variable. Fúndelo en el nodo que lo necesita.

Partes (dentro de un nodo): las funciones que deben implementarse juntas para que el nodo compile. Un subagente hace las partes en orden. No dividas las partes en nodos separados.

Ejemplo de nodo fetch-order:

• files: src/fetchOrder.ts, src/fetchOrder.test.ts
• parts: tipo Order, luego fetchOrder, luego escribe o extiende src/fetchOrder.test.ts
• esas partes no son nodos separados del grafo

Forma del grafo

• Capa 0: nodos con depends on: none. El controlador puede ejecutarlos todos en paralelo.
• Capa N: nodos cuyas dependencias están todas en capas anteriores.
• Última capa: un nodo (o un conjunto cohesionado) que significa que la funcionalidad funciona de extremo a extremo.
• Dos nodos que no dependen entre sí deben compartir una capa (o estar en capas que no se esperan mutuamente).
• depends on lista ids de nodo, nunca nombres de archivo.

Mismo archivo: si dos nodos crean o editan la misma ruta, no deben compartir capa. Fúndelos o añade una arista depends on para que uno espere. No dividas un archivo solo para ejecutarlo en paralelo. Dos nodos que solo leen una ruta pueden compartir capa. files lista solo rutas de creación o edición. La regla del mismo archivo incluye archivos de prueba.

Campos del nodo

Cada nodo tiene los siete:

1. id: en kebab-case, único en este plan, estable (un controlador posterior marca este id como completado).
2. name: nombre corto en inglés.
3. depends on: otros ids o none.
4. files: creación o edición (rutas). Incluye la ruta de prueba de done when.
5. parts: lista ordenada. La última parte es escribir o extender esa prueba. Si done when es una comprobación manual y no hay archivo de prueba, la última parte es esa comprobación y files no tiene ruta de prueba.
6. done when: un archivo de prueba o comando que el controlador pueda ejecutar antes de iniciar las dependencias.
7. status: esta habilidad siempre escribe pending. Un controlador posterior puede establecer in-progress o done. Esta habilidad nunca escribe esos dos.

No pongas el código fuente completo en el plan.

Tablero vivo

Ruta: <repo>/.agent/scratch/lego-plan.json

Mismo JSON que el bloque de código en el chat. Los agentes siguen este archivo. El producto visible para el usuario es la imagen del chat.

• Crea .agent/scratch/ si es necesario.
• Siempre sobrescribe. No preguntes, incluso si hay nodos existentes in-progress o done.
• Si el repositorio tiene git, asegúrate de que .gitignore contenga .agent/scratch/. Si .gitignore existe y falta la línea, agrégala. Si falta .gitignore, créalo con esa única línea.
• No abras el archivo. No lo vuelques como una segunda copia en el chat. El bloque JSON es la copia que ve el usuario.

Procedimientos

Procedimiento 1: Confirmar un cambio definido

1. Si el cambio está claro, continúa.
2. Si el usuario aún está eligiendo lo que quiere, detente. Pregunta. Regresa aquí cuando esté definido.

Procedimiento 2: Recopilar entradas ya en la sesión

1. Si esta conversación ya tiene una lista de archivos finales, partes o una selección de rutas, úsalos como conjunto inicial.
2. Si no, deriva los bloques de la intención definida y el código que debes leer para nombrar archivos. No recorras todo el repositorio.

Procedimiento 3: Dividir en nodos y partes

1. Enumera las primitivas candidatas (granularidad B).
2. Para cada primitiva, enumera las partes C que deben compilar juntas. Termina con escribir o extender la prueba (o la comprobación manual).
3. Dibuja depends on: un nodo depende de otro solo si llama o incrusta el resultado de ese nodo.
4. Asigna capas a partir de las dependencias. Los nodos independientes → misma capa.
5. Si dos nodos crean o editan la misma ruta y comparten capa, fúndelos o añade una arista. Luego reasigna capas.
6. Si aparece un ciclo, divide el nodo incorrecto y repite este procedimiento.

Procedimiento 4: Rellenar cada nodo

Rellena los siete campos. status es pending en cada nodo.

Procedimiento 5: Mostrar el DAG en el chat

Muestra, en este orden:

1. Capas: capa 0 hasta la última. Debajo de cada capa, los nodos de esa capa.
2. Nodos: los siete campos para cada id.
3. Mermaid: siempre. Un flowchart (o graph TD). Los ids de los nodos en el diagrama deben coincidir con los ids del plan. Sin classDef. Sin colores de estado. Cada nodo está pendiente.
4. Bloque JSON: un bloque json con el objeto del tablero vivo. Fuente de verdad para ids, dependencias, archivos, partes, doneWhen y status. Las capas se derivan de depends. No almacenes un campo layer.

Luego Procedimiento 6.

Forma Mermaid:

flowchart TD
  fetch-order[fetch-order]
  order-card[order-card]
  wire-loader[wire-loader]
  fetch-order --> wire-loader
  order-card --> wire-loader

Los nodos de la misma capa no tienen aristas entre sí.

Forma JSON:

{
  "version": 1,
  "nodes": [
    {
      "id": "fetch-order",
      "name": "fetch order",
      "depends": [],
      "files": ["src/fetchOrder.ts", "src/fetchOrder.test.ts"],
      "parts": ["Order type", "fetchOrder", "write or extend src/fetchOrder.test.ts"],
      "doneWhen": "pnpm test src/fetchOrder.test.ts",
      "status": "pending"
    }
  ]
}

depends es un array de ids. Vacío significa ninguno.

Procedimiento 6: Escribir el tablero vivo

1. Escribe el mismo JSON en .agent/scratch/lego-plan.json (sobrescribe).
2. Asegúrate de que .gitignore ignore .agent/scratch/ como en Tablero vivo.
3. No abras el archivo.

Procedimiento 7: Detenerse

Después del Procedimiento 6, detente. No escribas código. No despaches. No cargues otra habilidad.

Árbol de decisión

• Intención no definida → Procedimiento 1.
• Cambio definido, necesita mapa de implementación → Procedimiento 2 → 3 → 4 → 5 → 6 → 7.
• Un solo nodo → aún Procedimiento 2 → 7 (contrato completo).
• Error tipográfico / formato / solo documentación → esta habilidad no aplica.
• Ciclo en dependencias → Procedimiento 3 paso 6.
• Misma ruta en dos nodos de la misma capa → Procedimiento 3 paso 5.
• Nodo es