Habilidad Plan-Doc-Do-Follow
Plan → Doc → Do → Follow
Coincidir intención → primera ruta gana → leer routes/a-b.md (ruta a/b) → seguirla → aplicar Invariantes Globales + Modelo de Estado. Cargar solo la ruta necesaria, sus plantillas, sus subagentes — nunca todo
Rutas
Planificación
| Intención | Ruta | Parámetros |
|---|---|---|
| Extraer épicas de la visión del producto | plan/proj | |
| Validar épicas con interesados | plan/proj-review | |
| Crear PRD de épica y seguimiento | plan/epic | E{n} |
| Validar especificación o arquitectura de épica | plan/epic-review | E{n} {prd|arch} |
| Diseñar arquitectura de épica | plan/epic-arch | E{n} |
| Crear PRD de funcionalidad | plan/feat | E{n} F{n} |
| Validar especificación o arquitectura de funcionalidad | plan/feat-review | E{n} F{n} {prd|arch} |
| Arquitectura de funcionalidad (solo excepción) | plan/feat-arch | E{n} F{n} |
| Dividir funcionalidad en tareas | plan/tasks | E{n} F{n} |
| Cambio de alcance — añadir/actualizar funcionalidad o épica, incluso implementada | plan/change | descripción |
| Migrar documentos de proyecto v2 a v3 (de una sola vez) | plan/migrate |
Ejecución
| Intención | Ruta | Parámetros |
|---|---|---|
| Configurar herramientas de ahorro de tokens (LSP, filtros, economía, agentes nativos) | do/init | |
| Ejecutar una tarea | do/task | E{n} F{n} T{n} |
| Ejecutar todas las tareas de una funcionalidad, verificar en línea | do/all-tasks | E{n} F{n} |
| Verificar trabajo completado (ruta tarea por tarea) | do/verify | E{n} F{n} |
| Recalcular y reparar todos los estados | do/sync-status | |
| Memorizar buenas prácticas | do/memorize |
Invariantes Globales (todas las rutas)
- Verificación del espíritu: alinear con
docs/product.md; Espíritu del Producto (al inicio dedocs/project-status.md) palabra por palabra en cada ruta de planificación + resumen para revisor - Voluntad del usuario:
docs/decisions.mdvinculante; desviación = preguntar, nunca aplicar en silencio - Negocio primero: revisión de especificación antes de la siguiente fase
- Verificación de arquitectura: alinear con
docs/global_architecture.md+docs/technical-stack.md - Un hecho, un archivo: estado/hecho tiene un archivo propietario (Modelo de Estado); otros enlazan, nunca copian
- Lenguaje según audiencia: humano/negocio = oraciones completas, sin abreviaturas sin explicación; orientado al agente = estilo Documento (conciso tipo cavernícola)
- Sin andamios vacíos: eliminar secciones de plantilla no utilizadas; nunca "N/A" o marcadores de posición
- Sin suposiciones: ambigüedad bloqueante → preguntar primero; etiquetar bloqueante / importante / menor
- Trazabilidad: cada documento referencia al padre; historias ↔ requisitos ↔ tareas ↔ pruebas enlazados
- Documentos globales vivos:
docs/data-model.md,docs/ui-map.md,docs/decisions.mdactualizados en el mismo cambio que los afecta — nunca "después" - Niveles de modelo:
plan/*+ revisores = modelo fuerte; cada tarea deplan/tasksejecutable por modelo más débil sin abrir PRD - Sincronización de Estado: cada ruta que cambia estado termina con el procedimiento de Sincronización de Estado
- Formato de traspaso: resumen breve · progreso actual · siguiente comando exacto · preguntas abiertas
- Subagentes con alcance definido: solo las entradas que enumeran sus definiciones
- Mentalidad por ruta: adoptar la línea de Mentalidad de la ruta
- Debate interno: los intercambios de críticos nunca aparecen en documentos/traspasos — el humano ve el resultado final + qué validar
- Economía en todas partes: Economía de Trabajo en cada ruta y subagente
Modelo de Estado
⚪ TODO · 🟡 SPEC especificado · 🟣 PLAN tareas generadas · 🔵 DEV en desarrollo · 🟢 DONE completado y verificado
Propiedad — única fuente de verdad
| Hecho | Archivo propietario (ÚNICO lugar donde se escribe) |
|---|---|
| Estado de tarea | feat-tasks.md — Tabla Resumen de Tareas |
| Estado y progreso de funcionalidad | epic-status.md — Tabla de Funcionalidades |
| Estado y progreso de épica | docs/project-status.md — Tabla Hoja de Ruta de Épicas |
| Progreso del proyecto | docs/project-status.md — Sección de Progreso |
No existe feat-status.md. Secciones por tarea: sin línea de estado. Mermaid = decorativo, regenerado a partir de tablas propietarias, nunca fuente de verdad
Reglas de derivación
- Funcionalidad: sin
feat-prd.md→ ⚪ · PRD existe → 🟡 ·feat-tasks.mdexiste, ninguna tarea más allá de TODO → 🟣 · cualquier tarea DEV/DONE → 🔵 · 🟢 solo a través de compuertas de verificación (do/verify, o fase final dedo/all-tasks). Tareas añadidas a funcionalidad 🟢 → revertir a 🔵 - Épica: sin
epic-prd.md→ ⚪ · PRD existe → 🟡 · todas las funcionalidades ≥ 🟣 → 🟣 · cualquier funcionalidad 🔵/🟢 (no todas 🟢) → 🔵 · todas 🟢 → 🟢 - Proyecto: misma agregación sobre épicas
- Progreso: tareas hechas / tareas totales (0 si ninguna), sumado a nivel de épica y proyecto
Procedimiento de Sincronización de Estado
Al final de cualquier ruta que cambie estado (independiente: do/sync-status, todas las épicas):
- Leer Tablas Resumen de Tareas de la(s) funcionalidad(es) afectada(s)
- Recalcular cada estado + progreso de funcionalidad; actualizar fila en
epic-status.md - Recalcular cada épica afectada; actualizar su fila, sección de Progreso, gráfico circular en
docs/project-status.md. Sincronización de Estado nunca escribe registro de cambios — solo eventos nombrados por la regla estricta de registro de cambios (estilo Documento), escritos por la ruta que produjo el hito - Informar desviación (almacenado ≠ derivado) en el traspaso
Determinista e idempotente
Subagentes
Definiciones en subagents/ — un archivo por agente (formato: subagents/README.md). Invocar: leer archivo → ensamblar entradas exactamente listadas (los revisores siempre reciben Espíritu del Producto) → generar con el cuerpo del archivo como mensaje de sistema
Perfil de economía
Leer Economía de subagente: de la sección Herramientas del archivo de instrucciones del repositorio (do/init lo escribe). Si falta → equilibrado
| Perfil | Comportamiento |
|---|---|
estricto | Primero en línea forzado · scout casi siempre en línea · límites de pregunta/herramienta/devolución aplicados · críticos aún se generan |
equilibrado | Primero en línea como se describe abajo · límites aplicados · advertencia suave si >5 preguntas de scout |
calidad | Puerta de costo solo como advertencia · los límices aún se aplican al uso de herramientas scout y tamaño de devolución |
Antes de cualquier generación (primero en línea)
Ejecutar en orden — primera coincidencia gana → no generar:
- Hechos ya en contexto principal → trabajar en línea
- Respondible por el principal en ≤5 llamadas a Grep/Glob/Read (o LSP) → en línea (usar lista de verificación scout-lite en
subagents/repo-scout.md) - El resumen se acercaría al tamaño de la respuesta esperada → en línea
- Hallazgos probablemente cosméticos / lista de verificación mecánica en superficie pequeña → en línea (igual que la puerta de costo actual)
- Sino generar
repo-scout extra (bajo estricto / equilibrado): generar solo si ≥3 preguntas falsables y la búsqueda abarca ≥2 áreas que el principal no ha abierto, o el contexto principal ya está grande y el aislamiento claramente más barato. Sino scout-lite en línea
Al generar:
- Inyección de herramientas: el resumen incluye un bloque de Herramientas de una línea del archivo de instrucciones del repo (prefijo de filtro CLI, preferencia LSP, perfil de economía) — el subagente debe obedecerlo
- Resumen preciso: preguntas/verificaciones exactas · estándares sobre los que se construye · fuera de alcance · para scout, rutas/globs iniciales cuando el área se conoce · ≤5 preguntas por ola de scout (
equilibrado/estricto; dividir o el resto en línea) - Anteponer la barrera: antes del borrador, leer las preguntas de Revisión del crítico; redactar para pasar a la primera
- Límite de carga de devolución: scout ≤15 líneas · críticos ≤25 líneas · el principal solo conserva los hechos necesarios — nunca pegar volcados de scout en documentos
Hallazgos del crítico: aplicar si cambian comportamiento, contrato o decisión humana; descartar lo fútil/cosmético en silencio. Decisión de criterio rechazada → pregunta de decisión para el humano. Convergencia: una ejecución por documento; como máximo una re-ejecución después de retrabajo sustancial de hallazgos bloqueantes, limitada a ellos — la re-ejecución solo acepta bloqueantes; nunca tercera ejecución. Nunca informar el intercambio (Invariante 16)
| Subagente | Tipo | Llamado por | Cuándo |
|---|---|---|---|
repo-scout | investigación | plan/epic-arch, plan/feat, plan/feat-arch, plan/change | el plan debe basarse en código existente |
prd-critic | revisor | plan/epic, plan/feat | siempre |
arch-critic | revisor | plan/epic-arch, plan/feat-arch | siempre |
perf-critic-backend / -frontend | revisor | rutas de arquitectura, compuertas de verificación | solo cuando se activan los criterios (al inicio de sus archivos) |
task-checker | revisor | plan/tasks | después de auto-revisión; máximo dos ejecuciones |
feature-coder | ejecutor | do/all-tasks | uno por tarea paralelizable por ola |
ui-consistency-reviewer | revisor | compuertas de verificación | funcionalidades de UI, superficie no trivial |
doc-coherence-reviewer | revisor | compuertas de verificación · plan/change · plan/migrate | finalización de épica · después de cambio · después de migración |
Las compuertas de verificación (+ sus subagentes) se ejecutan en do/verify o en línea como fase final de do/all-tasks
UX de revisión humana
Conclusiones, no proceso. Verificaciones mecánicas auto-verificadas → una línea de resumen. "Decisiones que requieren su validación": ≤10 declaraciones en lenguaje sencillo + preguntas abiertas etiquetadas como bloqueantes/importantes/menores. Decisiones validadas → docs/decisions.md. Respuestas de interesados textuales — nunca parafrasear, nunca volver a preguntar (si ambiguo, preguntar solo aclaración)
Economía de Trabajo (Invariante 17)
Economía de entrada
- Preferir navegación LSP/semántica sobre lecturas de archivos completos; rangos de línea acotados
- Preferir Grep/Glob/LSP sobre Shell para búsqueda de código — Shell solo cuando sea necesario
- Salida larga de CLI (pruebas, compilaciones, git, gestores de paquetes) a través del filtro declarado en el repositorio (ej.
rtk,snip) —do/initlo configura; si se usa Shell sin hook activo, prefijar manualmente - Nunca releer lo que ya está en contexto; nunca cargar documento "por seguridad"
- Obedecer perfil de economía + primero en línea antes de generar (Subagentes)
Estilo de salida (principal y subagentes)
- Conciso tipo cavernícola (mismo nivel que documentos orientados al agente): sin preámbulo, sin repetir la solicitud, sin resumen final, sin relleno/ambigüedades
- Código, comandos, rutas, errores: byte exacto — nunca parafrasear
- Cambios de código como diferencias o ediciones dirigidas — nunca listados completos de archivos a menos que se solicite
- Respuestas de investigación ≤10 líneas a menos que se solicite profundidad; los retornos de subagentes obedecen el límite de carga de devolución
- Traspaso (Invariante 13) = solo bloque de cierre: ≤5 líneas
Implementación mínima (rutas do y feature-coder)
Entender completamente, detenerse en el primer escalón que se cumpla:
- No necesita existir → omitir (YAGNI)
- Ya en la base de código → reutilizar
- La biblioteca estándar lo hace → usarla
- Función nativa de la plataforma → usarla
- Dependencia instalada → usarla
- Una línea es suficiente → una línea
- Solo entonces escribir el mínimo que funcione
Nunca recortar: validación de límites de confianza, manejo de pérdida de datos, seguridad, accesibilidad
Estilo de documento
Dos audiencias — elegir según el propósito del archivo, no el estado de ánimo de la ruta
Humano / negocio (prosa completa) — PRDs (epic-prd.md, feat-prd.md), docs/product.md, Espíritu del Producto, cuerpos de revisión humana (secciones de decisión *-review.md), documentos centrados en el usuario (developer-setup, incorporación, READMEs humanos). Oraciones completas. Legible para interesados. Sin abreviaturas sin explicación
Orientado al agente (conciso tipo cavernícola) — guías de habilidad (SKILL.md, routes/, subagents/, comentarios de plantillas), feat-tasks.md, epic-arch.md / feat-arch.md, tablas/notas de estado, documentos técnicos vivos (data-model.md, ui-map.md, decisions.md), docs/patterns/*. Inspirado en caveman completo:
- Solo hechos y órdenes — omitir artículos/relleno/ambigüedades cuando el significado esté claro; fragmentos OK
- Sinónimos cortos; patrón
[cosa] [acción] [razón]·[siguiente paso] - Sin abreviaturas inventadas (
cfg/impl/fn); acrónimos técnicos conocidos OK (DB/API/HTTP) - Rutas, símbolos, código, comandos, cadenas de error: exactos
- Nunca omitir
no/nunca/ningún/solo/excepto - Sin punto final antes de salto de línea (puntos en medio de líneas con múltiples cláusulas se mantienen)
- Decisiones y hechos solo — nunca proceso ("el revisor sugirió…", "después de discusión…")
- Justificar solo cuando el agente futuro necesite el porqué (compensación, recorte de alcance): ≤2 líneas cortas
- Claridad automática: prosa más completa para advertencias de seguridad, pasos irreversibles o fragmentos que corren riesgo de malinterpretar orden/negación — luego reanudar conciso
Regla estricta de registro de cambios: una línea {fecha}: {hecho}, ≤25 palabras. Elegible solo — proyecto: épica completada, cambio de alcance mayor, migración; épica: funcionalidad verificada 🟢, cambio de alcance. Todo lo demás (tareas generadas, PRD redactado/aprobado, olas, sincronizaciones, correcciones de desviación) = sin entrada. Nunca: intercambios de críticos (Invariante 16), listas de tareas, resultados de compuertas, números de progreso, comandos Siguiente:. Entradas existentes detalladas = legado, nunca precedente — escribir solo línea elegible, o nada
Organización de Archivos
docs/
├── product.md (entrada: visión del producto)
├── global_architecture.md (entrada: visión general de arquitectura)
├── technical-stack.md (entrada: decisiones tecnológicas)
├── project-status.md (propietario: Espíritu del Producto, estados de épicas, progreso)
├── project-review.md
├── decisions.md (vivo: decisiones vinculantes del usuario, una línea cada una)
├── data-model.md (vivo: esquema global de datos, si lo hay)
├── ui-map.md (vivo: mapa de navegación global, si hay UI)
├── design-guidelines.md (vivo: convenciones de estilo de UI, si hay UI)
├── patterns/{patrón-name}.md (de do/memorize)
└── epics/e{n}-{nombre-épica}/ (slug ej. e2-orm-discovery)
├── epic-brief.md (plan/proj)
├── epic-prd.md (plan/epic)
├── epic-status.md (propietario: estados de funcionalidades)
├── epic-arch.md (plan/epic-arch)
├── epic-review.md (plan/epic-review)
└── f{n}-{nombre-funcionalidad}/ (hijo directo — sin nivel features/)
├── feat-prd.md (plan/feat; tiene Puntos de Entrada + Delta de Arquitectura)
├── feat-arch.md (plan/feat-arch — solo excepciones)
├── feat-tasks.md (propietario: estados de tareas)
└── feat-review.md (plan/feat-review)
Integración con plataformas
Convenciones del repositorio, precedencia: CLAUDE.md · AGENTS.md · .github/copilot-instructions.md · .cursor/rules/ · .github/instructions/. do/memorize escribe en el(los) archivo(s) realmente presentes
Plantillas
En templates/ — los nombres reflejan los archivos de salida