Flujo: Documentacion Automatizada¶

Pipeline de documentacion continua que se integra en el ciclo de vida del proyecto como paso post-ejecucion de cada plugin del ecosistema. En lugar de tratar la documentacion como una tarea separada al final del proyecto, doc-gen genera y mantiene docs de forma incremental: cada vez que un plugin completa su trabajo, doc-gen captura el estado actual del codigo, las decisiones tomadas y los artefactos producidos. El resultado es documentacion que siempre refleja la realidad del proyecto, no una foto estatica que se desactualiza al siguiente commit.

Resumen¶

doc-gen opera con 5 skills especializados que cubren el ciclo completo: doc-proyecto genera la documentacion inicial de un proyecto (estructura, arquitectura, stack, convenciones), doc-modulo documenta un modulo o componente individual despues de implementarlo, doc-sync detecta docs desactualizados comparando timestamps de codigo vs docs, doc-changelog genera changelogs a partir del historial de commits y milestones, y doc-auditar produce un reporte de gaps identificando que partes del proyecto carecen de documentacion o la tienen desactualizada. No se ejecuta aislado: se conecta con cada plugin del ecosistema como paso natural posterior a la ejecucion, asegurando que la documentacion crece al mismo ritmo que el codigo.

Cuando documentar¶

La siguiente tabla mapea cada momento del proyecto al skill de doc-gen correspondiente. La columna "Plugin que se uso" indica que plugin acaba de completar su trabajo, disparando la necesidad de documentar.

Momento del proyecto	Plugin que se uso	Skill de doc-gen	Que genera
Proyecto nuevo (despues de SDD-Wizards PRD)	`sdd-wizards`	`/doc-gen:doc-proyecto`	Docs completas iniciales: estructura del proyecto, stack, convenciones, glosario base, arbol de navegacion
Onboarding legacy (despues de SDD-Legacy)	`sdd-legacy`	`/doc-gen:doc-proyecto`	Docs del baseline: arquitectura actual, inventario de features, mapa de deuda tecnica, reglas de negocio extraidas
Ingenieria inversa (despues de RE-Wizard)	`re-wizard`	`/doc-gen:doc-proyecto`	Docs del target: arquitectura objetivo, modulos identificados, decisiones de diseno del sistema original
Feature implementada (despues de ATL archive)	`atl-inteliside`	`/doc-gen:doc-modulo {path}`	Doc del modulo: API, contratos, dependencias, decisiones tecnicas, tests asociados
Design system listo (despues de UX-Studio)	`ux-studio`	`/doc-gen:doc-modulo {path}`	Doc del design system: tokens, componentes, motion specs, responsive breakpoints, guia de uso
Workflow creado (despues de N8N-Studio)	`n8n-studio`	`/doc-gen:doc-modulo {path}`	Doc de automatizacion: trigger, nodos, flujo de datos, manejo de errores, dependencias externas
Plugin/skill creado (despues de CC-Toolkit)	`cc-toolkit`	`/doc-gen:doc-modulo {path}`	Doc del componente: proposito, frontmatter, tools permitidas, ejemplos de invocacion
Pipeline de ventas (despues de Sales-Engine)	`sales-engine`	`/doc-gen:doc-modulo {path}`	Doc de materiales: catalogo de assets, templates, flujos de demos, metricas de conversion
Verificacion periodica	—	`/doc-gen:doc-sync`	Detecta y regenera docs desactualizados comparando timestamps de codigo vs documentacion existente
Antes de release	—	`/doc-gen:doc-changelog`	Changelog actualizado con features, fixes, breaking changes agrupados por version y milestone
Auditoria de calidad	—	`/doc-gen:doc-auditar`	Reporte de gaps: modulos sin docs, docs obsoletos, secciones faltantes, score de cobertura

Diagrama del flujo¶

                         ┌─────────────┐
                         │   doc-gen   │
                         │  (post-op)  │
                         └──────┬──────┘
                                │
            ┌───────────────────┼───────────────────┐
            │                   │                   │
     ┌──────▼──────┐    ┌──────▼──────┐    ┌──────▼──────┐
     │ doc-proyecto │    │ doc-modulo  │    │  doc-sync   │
     │ (inicial)   │    │ (incremental│    │ (periodico) │
     └──────┬──────┘    └──────┬──────┘    └──────┬──────┘
            │                   │                   │
    ┌───────┴───────┐   ┌──────┴──────────────┐    │
    │               │   │      │      │       │    │
┌───▼───┐ ┌────▼───┐ ┌─▼──┐┌──▼──┐┌──▼──┐┌──▼──┐ │
│SDD-Wiz│ │SDD-Leg│ │ATL ││ UX  ││ N8N ││ CC  │ │
│ards   │ │acy   │ │Inte││Stud ││Stud ││Tool │ │
│       │ │       │ │lisi││ io  ││ io  ││ kit │ │
└───────┘ └───────┘ │de  │└─────┘└─────┘└─────┘ │
  PRD       Base-   └────┘                       │
  nuevo     line     Feature   Design  Work-  Plugin
                     impl.    system  flow   skill
                                                 │
                         ┌───────────────────────┘
                         │
                  ┌──────▼──────┐    ┌─────────────┐
                  │doc-changelog│    │ doc-auditar  │
                  │ (release)   │    │ (calidad)    │
                  └─────────────┘    └─────────────┘

Flujo:
  Plugin completa trabajo → doc-gen documenta resultado
  Periodicamente        → doc-sync detecta desactualizaciones
  Antes de release      → doc-changelog genera version log
  Bajo demanda          → doc-auditar reporta gaps

Primer uso en un proyecto¶

Paso 1 — Instalar doc-gen¶

Cargar el plugin al iniciar la sesion de Claude Code:

claude --plugin-dir ./plugins/doc-gen

Para usarlo junto con el stack completo de desarrollo:

claude --plugin-dir ./plugins/sdd-wizards \
       --plugin-dir ./plugins/atl-inteliside \
       --plugin-dir ./plugins/doc-gen

Paso 2 — Generar docs iniciales¶

Ejecutar el skill de documentacion de proyecto completo:

/doc-gen:doc-proyecto

Esto analiza el codebase y genera la estructura de documentacion inicial: arbol de navegacion, docs de arquitectura, inventario de modulos, glosario base y convenciones detectadas. Si el proyecto ya tiene un PRD de SDD-Wizards o un baseline de SDD-Legacy, doc-gen los incorpora automaticamente como fuente primaria.

Paso 3 — Revisar y enriquecer¶

Los docs generados son un punto de partida. Revisar manualmente:

Decisiones de arquitectura: agregar contexto que solo el equipo conoce (tradeoffs, restricciones de negocio, razones historicas)
Glosario: validar terminos y agregar los especificos del dominio
Convenciones: confirmar que las detectadas son correctas y agregar las no inferibles del codigo

Paso 4 — Configurar en CLAUDE.md¶

Agregar la configuracion de doc-gen al CLAUDE.md del proyecto para que los skills conozcan las preferencias:

## Doc-Gen Config

- docs_root: `docs/`
- idioma: `es`
- formato: `markdown`
- auto_suggest: `true` (sugiere documentar despues de cambios significativos)
- changelog_style: `conventional` (agrupado por tipo: feat, fix, chore)

Paso 5 — Usar doc-modulo despues de cada cambio significativo¶

A partir de este punto, cada vez que un plugin complete su trabajo (ATL archive una feature, UX Studio entregue un design spec, N8N Studio cree un workflow), ejecutar:

/doc-gen:doc-modulo {path-al-modulo}

Esto genera o actualiza la documentacion del modulo especifico sin tocar el resto de los docs.

Mantenimiento continuo¶

doc-gen incluye un hook PostToolUse que monitorea la actividad de otros plugins. Cuando detecta que un plugin acaba de completar una operacion significativa (ATL cierra un milestone, UX Studio genera un Design Spec, N8N Studio despliega un workflow), sugiere automaticamente al usuario que ejecute el skill de doc-gen correspondiente.

Como funciona el hook:

El hook escucha eventos PostToolUse de herramientas asociadas a los plugins del ecosistema
Cuando detecta un patron de finalizacion (ej: ATL ejecuta sdd-archive, UX Studio escribe un Design Spec, N8N Studio hace deploy), genera un mensaje de sugerencia
El mensaje indica que skill ejecutar y con que argumentos: "El modulo src/features/auth/ fue modificado por ATL. Ejecuta /doc-gen:doc-modulo src/features/auth/ para actualizar su documentacion."
El usuario decide si ejecutar o no — el hook nunca ejecuta doc-gen automaticamente

Verificacion periodica con doc-sync:

Para proyectos activos con muchos cambios, ejecutar doc-sync semanalmente o antes de cada sprint review:

/doc-gen:doc-sync

Compara timestamps de archivos de codigo contra sus docs correspondientes, identifica modulos cuyo codigo cambio pero cuya documentacion no se actualizo, y regenera los docs afectados. Produce un resumen de que se actualizo y que requiere revision manual.

Antes de cada release con doc-changelog:

/doc-gen:doc-changelog

Recorre el historial de commits y milestones desde el ultimo release, genera un changelog agrupado por tipo (features, fixes, breaking changes) y lo formatea listo para incluir en el release.

Auditoria bajo demanda con doc-auditar:

/doc-gen:doc-auditar

Genera un reporte completo de salud de la documentacion: modulos sin documentar, docs obsoletos, secciones requeridas faltantes, y un score de cobertura global. Util antes de onboarding de nuevos miembros al equipo o entregas a cliente.