Levix-Digital/plan-memory

📐 Habilidad de Memoria de Planes de Proyecto (plan-memory)

Rutas: <skills_root> es la carpeta que contiene esta habilidad (el padre de la carpeta de este SKILL.md). Use la ruta absoluta real al ejecutar los comandos.

La habilidad plan-memory mantiene planes arquitectónicos, hojas de ruta estratégicas y planos de varios pasos 100% completos y sin comprimir de un proyecto, compartidos por todos los que trabajan en él.

• Fuente de verdad: un archivo Markdown por plan en el repositorio del proyecto, docs/plans/<plan_id>.md (frontmatter YAML + cuerpo del plan). Los planes se versionan, revisan y fusionan con el código. Cambie la carpeta con "plans_dir" en .dev-cycle.json del proyecto.
• Índice de búsqueda: un ChromaDB local en ~/.ai-code-agent-memory/plan-memory/db (anulable con PLAN_MEMORY_DB), colección plan_index. Es desechable: cada comando lo sincroniza desde los archivos (mediante SHA-256), y rebuild_index (motor) lo recrea.
• Proyecto: se resuelve desde el repositorio Git del directorio actual (o --dir): project_name en .dev-cycle.json, o si no, el nombre de la carpeta del repositorio, normalizado a kebab-case. --project lo anula.
• Niveles: el backlog (docs/BACKLOG.md) captura trabajo en segundos, sin descubrimiento, agrupado bajo épicas; la hoja de ruta (docs/ROADMAP.md) ordena los lanzamientos y asigna ítems a ellos; un plan se crea cuando el usuario promociona ítems del backlog y contiene el descubrimiento y la planificación (ver "Backlog" y "Hoja de ruta").
• Sobres de Spec Kit: cuando el proyecto usa Spec Kit, un plan de funcionalidad es un sobre (spec_dir) de una carpeta de Spec Kit (specs/NNN-slug/) que contiene el detalle; la búsqueda, detección de desviaciones y get_plan leen los artefactos de la carpeta junto con el plan (ver "Planes con Spec Kit").
• Principio rector: Cero Compresión / Cero Pérdida. Los planes se conservan en su totalidad (diagramas Mermaid, tablas, pasos, fórmulas, justificaciones) como conocimiento persistente para cada desarrollador y sesión.

---

🏛️ Formato del Archivo de Plan

---
plan_id: my_app_blueprint_v1_2_0_two_stage_search
project: my-app
title: Búsqueda en dos etapas con reordenamiento local
kind: feature              # feature (por defecto) | bug
version: v1.2.0
status: in_progress        # draft | planned | active | in_progress | completed | superseded
author: Jane Doe           # git user.name de quien lo creó
created_at: '2026-10-15T16:36:00'
updated_at: '2026-10-16T09:10:00'
session_id: 8abbc3bf-...   # conversación donde se concibió el plan (opcional)
tags: [search, reranker]
supersedes: my_app_blueprint_v1_1_0_search
superseded_by: null
parent_plan_id: null
backlog_items: [FEAT-004]  # ítems del backlog que entrega el plan (opcional)
spec_dir: specs/004-reranker  # carpeta de Spec Kit con el detalle del plan (opcional)
milestones:
- name: M1 Base de tiempo de ejecución
  done: true
  done_at: '2026-10-15'
  by: Jane Doe
- name: M2 Reordenador
  done: false
status_log:
- at: '2026-10-15T16:36:00'
  by: Jane Doe
  status: active
  note: Plan creado
---

# Título del plan

...cuerpo completo del plan en Markdown...

• Los scripts solo reescriben el frontmatter; el cuerpo se escribe una vez con save_plan (o se edita manualmente). Los cambios de hitos y estado producen diferencias pequeñas y legibles.
• El nombre del archivo es el ID del plan. Los campos de linaje (supersedes, superseded_by, parent_plan_id) referencian otros IDs de plan.
• Los scripts nunca hacen commit. El agente hace commit de los archivos de plan junto con el trabajo que describen (ver "Flujo de trabajo del equipo").

---

⚙️ Comandos

Todos los scripts están en <skills_root>/plan-memory/ y aceptan --dir <directorio del proyecto> (por defecto: directorio actual) y --project <nombre>.

1. Guardar / Actualizar un Plan con Linaje (save_plan)

Escribe docs/plans/<plan_id>.md con el plan completo, sin cortes ni resúmenes. Guardar un ID existente actualiza título, cuerpo y campos, manteniendo autor, fecha de creación y progreso de hitos. --supersedes marca el plan anterior como superseded. save_plan se ejecuta en el motor nativo. En shells sh (Linux, macOS, Git Bash):

"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory save_plan \
  --title "Hoja de ruta integrada: Python -> Rust, Model Router y Model Kit" \
  --file "ruta/al/plan.md" \
  --version "v1.2.0" \
  --tags "roadmap,rust_refactor,model_router" \
  --milestones "Prioridad 1,Prioridad 2,Hito 3" \
  --status "active" \
  --session-id "<session_id>" \
  --supersedes "<id_del_plan_anterior>"

En PowerShell, ejecute & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory save_plan [argumentos] en su lugar. Opciones: --id (por defecto: slug <proyecto>_<título>), --parent-id, --content en lugar de --file, --kind feature|bug, --backlog-items "BUG-001,FEAT-002" (enlaza los ítems, que pasan a planned), --spec-dir specs/NNN-slug (el plan es el sobre de esa carpeta de Spec Kit).

2. Seguimiento de Hitos y Progreso (check_milestone)

check_milestone se ejecuta en el motor nativo. En shells sh (Linux, macOS, Git Bash):

# Progreso y lista de verificación del último plan activo (o --id <plan_id>):
"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory check_milestone --list

# Marcar un hito como completado (registra fecha y autor):
"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory check_milestone --milestone "Prioridad 1" --notes "Completado vía PR #319"

# Revertir un hito a pendiente:
"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory check_milestone --milestone "Prioridad 1" --uncheck

En PowerShell, ejecute & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory check_milestone [argumentos] en su lugar. El primer hito completado mueve un plan active a in_progress; el último lo mueve a completed.

3. Detector de Desviaciones Arquitectónicas (detect_drift)

Compara cualquier propuesta de implementación, problema o nuevo prompt contra el plan activo: similitud semántica, cobertura y orden de hitos, y las reglas anti-patrón del propio proyecto. detect_drift se ejecuta en el motor nativo. En shells sh (Linux, macOS, Git Bash):

"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory detect_drift --proposal "Prioridad 1: construir el orquestador nativo ReAct en Rust, reemplazando el Python LangGraph"
"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory detect_drift --file "ruta/a/la/propuesta.md" --strict   # código de salida != 0 en conflicto

En PowerShell, ejecute & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory detect_drift [argumentos] en su lugar.

Las reglas anti-patrón viven en la clave drift_rules del archivo .dev-cycle.json del proyecto (buscado desde --dir hacia arriba). Sin reglas, solo se verifican la similitud y los hitos.

"drift_rules": [
  { "tech": "langchain", "conflict_msg": "El plan base elimina LangChain." },
  {
    "tech": "base de datos paralela",
    "negative_markers": ["fuente única", "settings.db"],
    "proposal_allow": [],
    "conflict_msg": "La propuesta insinúa una base de datos paralela, violando la fuente única de verdad."
  }
]

Una regla genera un conflicto cuando un plan vigente (active / in_progress) menciona tech junto con un marcador de rechazo, y la propuesta menciona tech sin una frase permitida.

• negative_markers (opcional): palabras que marcan el rechazo. Por defecto: remove, replace, without, forbidden, ... más sus equivalentes en portugués, mantenidos mientras los planes existentes no estén traducidos.
• proposal_allow (opcional): frases que hacen aceptable una mención. Por defecto: without <tech>, remove <tech>, replace <tech>, ... más sus equivalentes en portugués.

4. Listar Planes (list_plans)

list_plans se ejecuta en el motor nativo. En shells sh (Linux, macOS, Git Bash):

"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory list_plans [--status active] [--kind bug]

En PowerShell, ejecute & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory list_plans [argumentos] en su lugar.

5. Leer un Plan Completo (get_plan)

get_plan se ejecuta en el motor nativo. En shells sh (Linux, macOS, Git Bash):

"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory get_plan --id "<plan_id>"
"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory get_plan                  # último plan activo

En PowerShell, ejecute & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory get_plan [argumentos] en su lugar.

6. Búsqueda Semántica (search_plans)

search_plans se ejecuta en el motor nativo. En shells sh (Linux, macOS, Git Bash):

"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory search_plans --query "cómo implementar el model router en el chat" [--limit 5] [--all-projects]

En PowerShell, ejecute & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory search_plans [argumentos] en su lugar.

7. Actualizar Estado del Ciclo de Vida (update_plan_status)

Establece el estado del plan, lo registra en el registro de estado y actualiza los ítems del backlog vinculados. update_plan_status se ejecuta en el motor nativo. En shells sh (Linux, macOS, Git Bash):

"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory update_plan_status --id "<plan_id>" --status "completed" --notes "Prioridad 1 y 2 entregadas."

En PowerShell, ejecute & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory update_plan_status [argumentos] en su lugar.

8. Exportar (export_plan)

Copia un plan a otro lugar, como JSON o Markdown con o sin frontmatter. export_plan se ejecuta en el motor nativo. En shells sh (Linux, macOS, Git Bash):

"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory export_plan --id "<plan_id>" --format json --output-dir "out/"

En PowerShell, ejecute & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory export_plan [argumentos] en su lugar.

9. Reconstruir el Índice (rebuild_index)

rebuild_index se ejecuta en el motor nativo. En shells sh (Linux, macOS, Git Bash):

"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory rebuild_index [--project <nombre>] [--dir <ruta>]

En PowerShell, ejecute & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory rebuild_index [argumentos] en su lugar.

---

📥 Backlog (backlog)

El primer nivel de planificación: un archivo Markdown (backlog.file en .dev-cycle.json, por defecto docs/BACKLOG.md), creado por el primer add desde templates/BACKLOG_TEMPLATE.md.

## Bugs | Funcionalidades | Mejoras | Ajustes | Épicas | Cerrados

### BUG-001: El preajuste frontier selecciona un id de modelo obsoleto
- **Severidad**: alta              # bugs: crítica | alta | media | baja
- **Estado**: abierto                # abierto | planificado | en_progreso (hecho | descartado | duplicado | reemplazado bajo Cerrados)
- **Encontrado**: 2026-10-16, v0.45.0, PR #333
- **Plan**: -                         # id del plan una vez promocionado
- **Descripción**: `/preset frontier` establece `claude-3-7-sonnet`, que el proveedor puede rechazar.

Las funcionalidades (FEAT-NNN), mejoras (IMP-NNN) y ajustes (ADJ-NNN) tienen Prioridad (alta, media, baja) en lugar de Severidad. Cualquier ítem que no sea una épica puede tener - **Épica**: EPIC-NNN. Las Épicas (EPIC-NNN, sección ## Épicas) agrupan los ítems del producto completo; tienen Prioridad, Estado (abierto hasta que se cierren), Encontrado y Descripción, sin Plan, y nunca se promocionan: sus ítems sí. validate advierte sobre una épica abierta cuyos ítems están todos cerrados. Los IDs nunca se reutilizan: los ítems cerrados permanecen bajo ## Cerrados con una nota - **Cerrado**: (fecha y pull request, motivo, duplicado de <ID>, o reemplazado por <ID>[, <ID>...]). Un ítem está reemplazado cuando es sustituido por otros ítems diferentes y mejor definidos (una idea dividida o reformulada después de su concepción); un duplicado es la misma solicitud capturada dos veces.

backlog se ejecuta en el motor nativo: "<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory backlog <comando> [argumentos] en shells sh (Linux, macOS, Git Bash). En PowerShell, ejecute & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory backlog [argumentos] en su lugar.

Tarea	Comando
Capturar	backlog add --type bug|feature|improvement|adjustment|epic --title "<t>" --description "<d>" [--severity S] [--priority P] [--epic EPIC-NNN] [--found-in "v1.2.0, PR #12"]
Capturar pruebas manuales fallidas	backlog add --from-failed --run vX.Y.Z-rc.N [--severity S]
Resumen (bugs antes del trabajo nuevo primero)	backlog summary [--json]
Listar, mostrar	backlog list [--type T] [--status S] [--epic EPIC-NNN] [--all] [--json], backlog show <ID>
Cambiar	backlog set <ID> [--title] [--description] [--severity] [--priority] [--status] [--plan] [--epic ID|-]
Promocionar a plan	backlog promote <ID> [<ID> ...] [--title T] [--id PLAN_ID] [--version V] o --into <PLAN_ID>
Cerrar	backlog close <ID> [--ref "PR #12"], drop <ID> --reason R, duplicate <ID> --of <ID>, supersede <ID> --by <ID>[,<ID>...], reopen <ID>
Validar	backlog validate

• Capturar no cuesta nada: sin descubrimiento, sin plan. El usuario lo hace con el comando /backlog; el agente lo hace para bugs que encuentra fuera del alcance actual.
• Promocionar crea un plan draft a partir de templates/BUG_PLAN_TEMPLATE.md (cada ítem es un bug: reproducción, evidencia y causa raíz, diseño de la corrección, prueba de regresión) o templates/FEATURE_PLAN_TEMPLATE.md, con los ítems copiados en su sección Ítems del backlog, y enlaza ambos sentidos. El descubrimiento se escribe en ese plan; se guarda de nuevo como active, con hitos, para su aprobación.
• Los ítems vinculados siguen a su plan: planned mientras el plan está en draft o activo, in_progress cuando está en progreso, cerrados como done cuando está completado (check_milestone y update_plan_status en el motor).
• El triaje es decisión del usuario: el agente nunca promociona, descarta ni re-prioriza por su cuenta.
• El script nunca hace commit y se niega a reescribir un archivo cuya estructura no puede leer, por lo que las ediciones manuales nunca se pierden.

---

🗺️ Hoja de Ruta (roadmap)

Los lanzamientos del producto en orden de entrega (roadmap.file en .dev-cycle.json, por defecto docs/ROADMAP.md), creados por el primer add desde templates/ROADMAP_TEMPLATE.md.

# Hoja de ruta de Mi Aplicación

## [v1.3.0] - Próximo lanzamiento
- **Estado**: planificado
- **Fecha de lanzamiento prevista**: 2026-11-01
- **Planos**: Nombre del plano 1, Nombre del plano 2
- **Épicas**: EPIC-001
- **Notas**: La integración de Rust debe completarse.

### FEAT-018: Autenticación biométrica

### BUG-007: Desbordamiento de búfer en el análisis de imágenes

### IMP-003: Reducir uso de memoria en la recomendación por lotes

Comandos

roadmap se ejecuta en el motor nativo: "<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory roadmap <comando> [argumentos] en shells sh (Linux, macOS, Git Bash). En PowerShell, ejecute & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory roadmap [argumentos] en su lugar.

Comando	Descripción
add --release "v1.3.0" --date 2026-11-01 --status planned --planos "<id1>,<id2>" --epics "EPIC-001" --notes "..."	Crear o actualizar un lanzamiento con sus planos y épicas
promote <ID1> <ID2> --release "v1.3.0"	Mover ítems del backlog a un lanzamiento
list [--release R] [--status S]	Listar lanzamientos (--json exportable)
set --release R --date D --status S --planos "id1,id2" --epics ... --notes ...	Actualizar lanzamiento (campos individuales con --planos "...")
release --version v1.3.0 --summary "..."	Anunciar lanzamiento: cambia estado a lanzado, coloca los planos e ítems como completados/cerrados, notifica la versión en la CI
validate	Verifica que los lanzamientos estén ordenados, los planos existan y los ítems no estén en dos sitios

roadmap obtiene planos, ítems del backlog y sus estados del motor y nunca edita el archivo excepto para los comandos add, set y release.

---

🧠 Planes con Spec Kit

Cuando un proyecto usa un directorio Spec Kit (specs/), un plan puede ser el sobre de una carpeta de Spec Kit (specs/NNN-slug/): el plan contiene el título, los hitos, las fechas y el linaje; la carpeta de Spec Kit contiene el detalle, los criterios de aceptación, las pruebas y la documentación de arquitectura.

• get_plan lee el plan base y concatena los artefactos relevantes de la carpeta de Spec Kit.
• search_plans indexa tanto el plan como los artefactos de la carpeta (Markdown, JSON, YAML, plantillas de código).
• detect_drift carga el plan y su carpeta de Spec Kit.

Al guardar un plan con --spec-dir specs/NNN-slug, el motor escribe el plan como sobre y completa el Spec Kit: README.md con el título y la descripción del plan, y una plantilla plan.md. El agente redacta el detalle en los archivos del Spec Kit.

---

🤝 Flujo de Trabajo del Equipo

1. Capturar: el equipo y los agentes añaden bugs, funcionalidades, mejoras y ajustes al backlog (segundos, sin descubrimiento).
2. Priorizar: el propietario del producto o el equipo prioriza y agrupa bajo épicas en el backlog.
3. Promocionar: el usuario promociona ítems a un plan (draft). Se escribe el descubrimiento: flujo, arquitectura, hitos, diseño. Se aprueba → active.
4. Implementar: los desarrolladores leen el plan, implementan, marcan hitos, detectan desviaciones, actualizan el estado. El agente refina el plan con el trabajo real.
5. Entregar: los planos guían los PRs. Los scripts nunca hacen commit. El agente incluye los archivos de plan en el commit que describe el trabajo. git commit -m "feat: búsqueda en dos etapas con reordenador" docs/plans/... specs/...
6. Cerrar: cuando se entrega todo, el usuario emite check_milestone --milestone "Último" (o update_plan_status --status completed). El motor cierra el plan y sus ítems del backlog. Si hay un lanzamiento, release lo anuncia.

---

🔧 Configuración

En .dev-cycle.json (buscado desde --dir hacia arriba)

{
  "project_name": "mi-aplicacion",
  "plans_dir": "docs/plans",
  "backlog": {
    "file": "docs/BACKLOG.md",
    "bug_template": "templates/BUG_PLAN_TEMPLATE.md",
    "feature_template": "templates/FEATURE_PLAN_TEMPLATE.md"
  },
  "roadmap": {
    "file": "docs/ROADMAP.md"
  },
  "drift_rules": [
    { "tech": "langchain", "conflict_msg": "El plan base elimina LangChain, pero la propuesta lo reintroduce." }
  ]
}

Variables de Entorno

Variable	Por defecto	Descripción
PLAN_MEMORY_DB	~/.ai-code-agent-memory/plan-memory/db	Ruta al directorio de la base de datos ChromaDB
DEVCYCLE_BIN	(automático)	Anula<skills_root>/dev-cycle-protocol/bin/dev-cycle

---

🧪 Ejemplos

# Guardar un plan de funcionalidad
"$HOME/.ai-code-agent/skills/plan-memory/save_plan" --title "Autenticación biométrica" --version "v1.3.0" --file "biometric-auth.md" --tags "auth,biometric,security" --kind feature --milestones "M1 Diseño,M2 Implementación,M3 Pruebas"

# Marcar hito completado
"$HOME/.ai-code-agent/skills/plan-memory/check_milestone" --milestone "M1 Diseño" --notes "Diseño revisado y aprobado."

# Detectar desviación
"$HOME/.ai-code-agent/skills/plan-memory/detect_drift" --proposal "Usar LangChain para la autenticación"

# Listar planes activos
"$HOME/.ai-code-agent/skills/plan-memory/list_plans" --status active --kind feature

# Añadir bug
"$HOME/.ai-code-agent/skills/plan-memory/backlog" add --type bug --title "Desbordamiento de búfer" --severity high --found-in "v1.0.0, PR #12"

# Promocionar ítems
"$HOME/.ai-code-agent/skills/plan-memory/backlog" promote BUG-007 FEAT-018 --title "Correcciones de seguridad v1.3.0" --version "v1.3.0"

# Exportar plan
"$HOME/.ai-code-agent/skills/plan-memory/export_plan" --id "mi-aplicacion_correcciones_seguridad_v1_3_0" --format json --output-dir "docs/reports/"