SeemSeam/plan-tree

Árbol de Planificación (Plan Tree)

Utiliza esta habilidad como la autoridad del flujo de trabajo de planificación para la dirección duradera del proyecto, la preparación para la ejecución, el estado del progreso y los árboles de planificación en Markdown. Preserva la intención del usuario, el estilo del documento existente, la línea de razonamiento y la evidencia de plan a implementación a través de sesiones y agentes.

Modo de Operación Requerido

Para cada tarea de árbol de planificación, determina el modo de trabajo antes de editar o implementar.

• Si el modo no está claro, por defecto usa clarify o ready-check, no execute-ready.
• Cuando el estado del árbol de planificación existente esté disponible, inspecciona el punto de entrada relevante y el estado del plan actual antes de cambiar de dirección.
• Antes de que una solución sea lo suficientemente madura para implementar, permanece en modo de planificación y aclaración. Expande la intención del usuario en objetivos, no objetivos, restricciones, opciones, compensaciones, riesgos, dependencias, criterios de aceptación, ruta de verificación y notas de implementación o reversión.
• No comiences la implementación formal en la superficie principal del proyecto mientras persista una ambigüedad central sobre el alcance, el enfoque, las superficies afectadas, el comportamiento esperado, los criterios de aceptación, la ruta de verificación o los riesgos.
• Se permite un prototipo o ejemplo pequeño y aislado solo cuando valida una dirección y permanece claramente separado de la ruta de producción.
• Un plan está listo para implementación solo cuando la ejecución no debería depender de "resolverlo mientras se codifica" para decisiones centrales.
• Después de que la implementación se haya realizado, actualiza el estado del árbol de planificación, la evidencia implementada, las decisiones, las preguntas abiertas y las notas de traspaso para que los proyectos de implementación vuelvan a un estado de planificación duradero.

Modos de Trabajo

Elige un modo principal al comienzo de una tarea, luego transiciona solo cuando el estado cambie.

• clarify: la intención, el alcance, las restricciones, los criterios de éxito o las compensaciones no están claros. Discute, haz preguntas enfocadas cuando sea necesario y registra los resultados duraderos de la aclaración en los archivos del árbol de planificación cuando sea útil. No edites los archivos de implementación del proyecto principal.
• shape-plan: la dirección es mayormente conocida pero necesita un mapa de solución concreto. Crea o actualiza elementos de la hoja de ruta, temas, suposiciones, decisiones, riesgos, criterios de aceptación y preguntas abiertas.
• ready-check: el usuario quiere implementar o proceder, pero la preparación es incierta. Evalúa si el alcance, el enfoque, las superficies afectadas, los criterios de aceptación, la verificación y los riesgos son lo suficientemente explícitos. Si no, regresa a clarify o shape-plan.
• resume: continúa desde trabajo anterior. Lee el punto de entrada raíz, la línea base relevante, el README del plan objetivo, el estado de implementación, la hoja de ruta y solo los archivos vinculados activos. Resume la fase actual, el TODO activo, los bloqueadores, el próximo objetivo y la última verificación antes de editar.
• execute-ready: el plan está suficientemente listo para implementar. Modifica los archivos del proyecto solo dentro del alcance acordado, luego actualiza el estado del árbol de planificación y la evidencia.
• status-update: actualiza el estado de la hoja de ruta, el estado de implementación, Último Implementado, Próximo Objetivo, bloqueadores, traspaso o registro del plan después del trabajo o la revisión.
• archive: mueve detalles obsoletos, instantáneas de estado antiguas, evidencia aceptada o material de solo referencia fuera de los archivos activos mientras se preservan los enlaces de recuperación.
• normalize: reorganiza un árbol de planificación existente o archivos fuente de roles mixtos de gran tamaño en unidades de recuperación más pequeñas. Primero crea o actualiza indexes/migration-map.md o el índice útil más cercano, luego clasifica el material fuente por rol de recuperación, crea cápsulas cortas y fragmentos de detalle de tareas de lectura, mueve la verificación aceptada a evidence/ y mueve el estado antiguo o la narrativa de razonamiento a history/ sin eliminar el material fuente a menos que se apruebe explícitamente.
• audit o migrate: inspecciona consistencia, recuperación, desviación, raíces heredadas o mapeo de migración. Por defecto, solo lectura a menos que el usuario solicite reparar, normalizar o migrar.

Las acciones documentales como idea, promote, question y decision ocurren dentro de estos modos:

• idea: agrega un pensamiento de bajo compromiso a ideas/inbox.md o al equivalente local.
• promote: mueve una idea a un elemento de la hoja de ruta, tema, pregunta abierta o decisión, y enlaza la idea original.
• question: agrega, acota o resuelve una pregunta no resuelta.
• decision: crea o actualiza un registro de decisión estable.

Flujo de Trabajo Central

Para cada tarea de árbol de planificación:

1. Selecciona el modo de trabajo y la superficie de escritura permitida: ninguna, solo árbol de planificación, prototipo aislado, o archivos del proyecto más actualización del árbol de planificación.
2. Identifica la raíz del árbol de planificación, la raíz del plan objetivo y la intención del usuario.
3. Lee el índice raíz más solo los archivos relevantes de hoja de ruta, estado, tema, decisión, pregunta, idea, historial o línea base.
4. Preserva los puntos de entrada existentes, las raíces registradas, los nombres de carpeta, el estilo del documento y el orden de autoridad a menos que la tarea sea reorganizarlos explícitamente.
5. Mantén los archivos activos de hoja de ruta, traspaso y cápsula de tema pequeños; mueve detalles, evidencia e historial fuera del estado activo.
6. Actualiza índices, encabezados de recuperación y enlaces al agregar, mover, promover, archivar o dividir archivos duraderos.
7. Ejecuta verificaciones finales antes de responder.
8. Informa los archivos modificados, las preguntas no resueltas, el modo activo y la próxima acción de mantenimiento útil cuando sea relevante.

Sistema de Archivos Predeterminado

Usa docs/plantree/ como el sistema de archivos predeterminado entre proyectos para el material administrado por el árbol de planificación. Es la raíz del sistema y el registro del árbol de planificación, no una raíz de plan único; el nombre evita colisiones con carpetas plans/ nativas del proveedor o del framework.

Forma predeterminada:

• docs/plantree/README.md: registro, orden de autoridad, enlace a la línea base, tabla de planes activos y cómo leer el árbol.
• docs/plantree/baseline/: contexto de todo el proyecto, como mapa de módulos, flujos de ejecución, límites de estado/almacenamiento, puertas de prueba/lanzamiento y puntos críticos de riesgo.
• docs/plantree/plans/<NNN>-<nombre-del-plan>/: raíces de plan específicas con orden numérico estable, hoja de ruta/estado, temas, decisiones, preguntas abiertas, evidencia, índices e historial opcional cuando el proyecto no tiene una convención de nomenclatura establecida.
• docs/plantree/ideas/inbox.md: bandeja de entrada de ideas de bajo compromiso.

Orden de descubrimiento:

1. Utiliza una ruta de usuario explícita cuando se proporcione.
2. Si no, usa docs/plantree/ cuando exista docs/plantree/README.md.
3. Si no, preserva otro árbol claramente activo y establecido para la tarea actual; evalúa la migración solo cuando el usuario solicite adoptarlo, normalizarlo o migrarlo.
4. Si no, inicializa docs/plantree/ antes de crear o actualizar un plan.

Los nuevos planes específicos por defecto van a docs/plantree/plans/<NNN>-<nombre-del-plan>/ cuando no exista una convención local, deben registrarse en docs/plantree/README.md y deben enlazar a los archivos de línea base relevantes en lugar de copiar el contexto global. Preserva árboles establecidos sin numerar o con organización diferente a menos que el usuario apruebe explícitamente la migración.

Primer Uso

Cuando se invoca una tarea de árbol de planificación en un proyecto sin docs/plantree/, crea una raíz mínima a menos que el usuario solicite explícitamente no crear archivos.

Inicialización:

• Raíz: docs/plantree/README.md
• Línea base: baseline/README.md, module-map.md, runtime-flows.md, storage-and-state.md, test-and-release-gates.md, risk-hotspots.md
• Contenedores: plans/, ideas/inbox.md

Mantén el contenido de inicialización liviano y basado en evidencia. Si no se ha inspeccionado suficiente código, escribe Desconocido / necesita inventario en lugar de inventar datos del proyecto. Para proyectos antiguos o desconocidos, construye o actualiza la línea base antes de crear un plan detallado.

Modelo de Plan

Utiliza estos roles al crear o mantener una raíz de plan, adaptando los nombres a la convención local:

• README.md: alcance, autoridad, mapa de archivos, ruta de lectura y registro activo cuando es la raíz del árbol de planificación. Para tablas de Plan activas, prefiere ID | Plan | Módulos Afectados | Estado | Fase Actual | Último Implementado | Próximo Objetivo cuando se usan IDs livianos.
• roadmap.md: estado duradero agrupado como Hecho, En Progreso, Siguiente y Diferido a menos que el árbol ya use otro modelo.
• implementation-status.md: traspaso operativo corto solo para planes En Progreso. Los planes en planificación o diferidos generalmente no necesitan este archivo.
• open-questions.md: solo preguntas no resueltas.
• topics/: contexto duradero, mapas de solución, opciones, restricciones, criterios de aceptación, notas de implementación, planes de higiene del repositorio y análisis de riesgos. Mantén los archivos de tema de nivel superior como cápsulas cortas; divide temas grandes en carpetas de tema con fragmentos de detalle.
• decisions/: decisiones estables, indexadas cuando el conjunto crece.
• evidence/: registros de verificación actuales o aceptados, resultados de revisión, notas de artefactos e índices de evidencia cuando estos deben recuperarse independientemente del historial.
• history/: registros de puntos de control aceptados, revisiones antiguas, instantáneas retiradas, notas de fuente de solo archivo y detalles obsoletos.
• indexes/: mapas de recuperación opcionales, como mapas de fase, mapas de tema, mapas de autoridad, mapas de migración y mapas de evidencia cuando los índices locales resuelven un problema de navegación.
• ideas/: grupo de ideas opcional de bajo compromiso cuando las ideas a nivel de raíz no son lo suficientemente específicas.

Lee references/maintenance-patterns.md al crear plantillas, manejar árboles grandes, mantener archivos de decisión/estado/traspaso/historial/índice, agregar planes de higiene del repositorio o necesitar la lista de verificación de verificación final detallada.

IDs Livianos y Clasificación de Módulos

Cuando un proyecto no tiene una convención de nomenclatura de Plan establecida, usa IDs livianos para mejorar el escaneo del sistema de archivos y las referencias duraderas sin crear una base de datos de tareas:

• Asigna IDs de Plan a nivel de proyecto como P001, P002, etc. Mapa P001 a una raíz plana como docs/plantree/plans/001-authentication/.
• Usa números decimales de tres dígitos de ancho fijo. Asigna el número de Plan máximo retenido más uno; nunca reutilices un ID, cierres huecos renumerando, ni codifiques prioridad, estado, módulo, propietario, trabajador, fase o fecha.
• Mantén el slug semántico estable y en minúsculas con guiones. Un título o módulo afectado puede cambiar sin cambiar el ID del Plan o el directorio.
• Mientras el registro de Planes sea pequeño, mantén la identidad y el registro del ciclo de vida en docs/plantree/README.md. Divídelo en un índice solo cuando eso mejore la recuperación; no mantengas un libro de contabilidad de asignación paralelo por defecto.
• Los IDs de tareas de la hoja de ruta, como T001, son opcionales y locales al Plan. Úsalos solo cuando las referencias estables entre archivos ayuden. Cuando estén presentes, roadmap.md es la única autoridad activa para la identidad, el estado y el orden de la tarea; no crees un registro de tareas separado ni una carpeta de tareas por defecto.
• Los nombres de archivos de decisión pueden conservar la convención 001-<decision>.md. Las preguntas abiertas pueden usar Q001 cuando las referencias duraderas ayuden. Las ideas permanecen sin numerar hasta que se promocionan.
• Trata los módulos de código o producto como metadatos del Plan, como Módulos Afectados, utilizando claves estables definidas en baseline/module-map.md. Mantén las raíces del Plan planas por defecto; agrega índices de módulos o directorios de módulos físicos solo después de una necesidad de navegación demostrada y una decisión registrada.
• Aplica consistencia de cambio simultáneo: actualiza el archivo autoritativo y cualquier resumen de punto de entrada requerido en un solo cambio de mantenimiento, luego verifica IDs, rutas, claves de módulo, unicidad de la hoja de ruta, afirmaciones de estado y enlaces relativos antes de finalizar.
• Prefiere la detección de desviación de solo lectura sobre la reparación automática. No agregues observadores, renumeración automática, bloqueos de asignación o diarios de recuperación hasta que las fallas de coordinación observadas justifiquen su costo.

Estos valores predeterminados son progresivos. Preserva la convención local de ID, problema, ticket o carpeta de un árbol maduro en lugar de superponer un espacio de nombres en competencia.

Estado Dinámico y Evidencia

• Solo los planes En Progreso necesitan implementation-status.md; los planes En Planificación deben expresar la preparación en roadmap.md, temas, preguntas abiertas o decisiones.
• Mantén implementation-status.md operativo y corto. Prefiere menos de 100 líneas; si crece, archiva o indexa los detalles antiguos.
• Mantén TODO Activo en un máximo de cinco elementos actuales. Más elementos generalmente significa que el trabajo necesita una fase de hoja de ruta, tema o división.
• Cuando se usen IDs de tareas de la hoja de ruta, reutiliza esos IDs en TODO Activo en lugar de reafirmar la identidad de la tarea en un segundo registro.
• Incluye Fase Actual, Próximo Objetivo, Último Implementado, TODO Activo, Bloqueado Por y Último Verificado concretos o notas de traspaso cuando sea aplicable.
• Último Implementado debe apuntar a un commit, artefacto, resultado de prueba, punto de control aceptado u otra evidencia con una fecha cuando esté disponible.
• Usa evidence/README.md, indexes/evidence-map.md o el equivalente local para evidencia a nivel de fase/paquete/puerta. Usa history/evidence-index.md solo para archivos de evidencia obsoleta. No registres cada pequeño paso allí.
• Los archivos activos de hoja de ruta/estado deben enlazar a evidencia antigua, no absorber registros repetidos, salida de automatización antigua, detalles de trabajos de revisión o narrativas históricas.

Modelo de Recuperación

El árbol de planificación es un sistema de unidades de recuperación, no un lugar para hacer crecer grandes documentos generales. Cada archivo duradero debe tener un rol principal:

• Punto de entrada o índice: enrutamiento, orden de autoridad, rutas de lectura y resúmenes de una línea.
• Estado actual: hoja de ruta activa, fase actual, bloqueadores, próximo objetivo y traspaso.
• Cápsula de tema: un resumen breve de un dominio, característica, conjunto de restricciones o flujo de trabajo con enlaces a fragmentos de detalle.
• Fragmento de detalle: contratos, alternativas, casos extremos, notas de implementación, implementación, operaciones, preparación o detalles de higiene del repositorio para una tarea de lectura.
• Decisión: una elección estable con contexto y consecuencias.
• Evidencia: registros de verificación, resultados de revisión, enlaces a artefactos, resúmenes de prueba aceptados o índices de evidencia.
• Historial/archivo: estado obsoleto, registros de ejecución antiguos, material fuente migrado y detalles retirados.

No permitas que un archivo lleve resumen, estado activo, decisiones, razonamiento extenso, registros, evidencia e historial al mismo tiempo. Si una actualización hiciera que un archivo cruzara su límite de rol, crea o actualiza primero una unidad de recuperación vinculada, luego deja solo el resumen conciso y los enlaces en el archivo activo.

Usa estos recuentos de líneas como desencadenantes de división, no como pruebas de corrección estrictas:

• README raíz, README del plan, hoja de ruta y estado de implementación: manten cerca de 150 líneas o menos.
• Cápsula de tema: manten cerca de 250 líneas o menos.
• Fragmento de detalle ordinario: divide o indexa alrededor de 400 líneas.
• Archivos de historial o evidencia: indexa o divide alrededor de 500 líneas.