Delfosti Docs Pipeline

Herramienta que automatiza la generación de changelog y documentación técnica en cada git commit, usando Claude AI como motor de análisis.

Funciona en cualquier proyecto y stack (Node.js, .NET, PHP, Flutter, Python, etc.) porque se apoya en hooks de Git, no en herramientas específicas del lenguaje.

Se puede instalar de dos formas independientes: como extensión de VS Code / Cursor / Antigravity, o como CLI desde la terminal (Neovim, cualquier otro editor, o sin IDE).

Qué hace

En cada git commit, el pipeline ejecuta 3 fases en secuencia:

| Fase | Qué genera | Dónde guarda | |------|-----------|--------------| | 1 · Bitácora | Documento Markdown con análisis técnico del commit (archivos, impacto, riesgos, pruebas sugeridas) | docs/changelog/YYYY-MM-DD_HHmm_<branch>_<sha>.md | | 2 · Living Docs | Actualiza o crea documentación Obsidian de los módulos afectados | docs/02-Arquitectura/, docs/03-Implementación/ | | 3 · CHANGELOG.md | Actualiza el CHANGELOG.md ejecutivo en formato Keep a Changelog | CHANGELOG.md (raíz del proyecto) |

Cada fase hace un auto-commit con el contenido generado. Si alguna fase falla, el flujo continúa normalmente sin bloquear al desarrollador.

Requisitos previos

| Requisito | Versión mínima | Cómo instalar | |-----------|---------------|---------------| | Node.js | 18+ | nodejs.org | | Git | 2.x | git-scm.com | | Claude Code CLI | última | npm install -g @anthropic-ai/claude-code | | VS Code / Cursor / Antigravity | VS Code 1.85+ | Solo si usas la vía extensión | | MCP codebase-memory-mcp | — | Opcional, solo para docs-pipeline mcp (ver más abajo) |

Proyectos sin Node.js (.NET, PHP, Flutter, etc.): Node.js solo se necesita para ejecutar los scripts del pipeline. No afecta las dependencias ni el build de tu proyecto. Instálalo como herramienta de desarrollo.

Instalación

Hay dos vías independientes. Elige la que corresponde a tu entorno:

Vía A — Extensión (VS Code, Cursor, Antigravity)

Genera el .vsix y luego instálalo en tu IDE:

# 1. Compilar y empaquetar
cd delfosti-docs-pipeline
npm install
npm run package          # genera delfosti-docs-pipeline-1.0.18.vsix

# 2. Instalar según tu IDE
code --install-extension delfosti-docs-pipeline-1.0.18.vsix        # VS Code
cursor --install-extension delfosti-docs-pipeline-1.0.18.vsix      # Cursor
antigravity --install-extension delfosti-docs-pipeline-1.0.18.vsix # Antigravity

O desde el IDE: Ctrl+Shift+P → Extensions: Install from VSIX... → seleccionar el .vsix.

Una vez instalada la extensión, activa el pipeline en tu proyecto:

Ctrl+Shift+P → "Docs Pipeline: Instalar Hook"

Vía B — CLI desde terminal (Neovim, cualquier editor, sin IDE)

El paquete está publicado en npm. Se puede instalar de forma global (una vez por máquina) o local (por proyecto).

Importante: instalar el paquete no activa el pipeline. Es necesario ejecutar docs-pipeline install (o npx docs-pipeline install) en cada proyecto donde se quiera activar.

Instalación global (recomendado)

El comando queda disponible en el PATH y funciona en cualquier proyecto sin prefijos.

# Una sola vez por máquina
npm install -g delfosti-docs-pipeline

# En cada proyecto donde se quiera activar el pipeline
cd /ruta/a/mi-proyecto
docs-pipeline install

Instalación local por proyecto

Útil si el equipo quiere fijar la versión del CLI en el package.json del proyecto.

# En la raíz del proyecto
npm install delfosti-docs-pipeline

# Instalar el hook con npx
npx docs-pipeline install

No requiere VS Code ni ningún IDE. Funciona desde cualquier terminal.

Comandos del CLI

docs-pipeline install                    # Instala el hook en el proyecto actual
docs-pipeline uninstall                  # Elimina el hook
docs-pipeline update                     # Actualiza scripts a la versión actual
docs-pipeline status                     # Muestra estado del hook y ruta de Node
docs-pipeline run                        # Ejecuta el pipeline sobre el último commit
docs-pipeline run --range HEAD~3..HEAD   # Ejecuta sobre un rango específico
docs-pipeline run --only changelog       # Solo Fase 1 (bitácora)
docs-pipeline run --only docs            # Solo Fase 2 (Obsidian docs)
docs-pipeline run --only summary         # Solo Fase 3 (CHANGELOG.md)
docs-pipeline docs                       # Genera la documentación técnica completa (Obsidian) del proyecto actual
docs-pipeline mcp                        # Genera solo la documentación estructural vía MCP codebase-memory-mcp
docs-pipeline version                    # Muestra la versión instalada del CLI
docs-pipeline help                       # Muestra la ayuda

docs-pipeline docs

Genera desde cero la documentación técnica del proyecto donde se ejecuta el comando (no depende del hook ni de un diff de git). Muestra el banner, un spinner mientras Claude analiza el proyecto, y al finalizar el tiempo total de generación.

Crea la carpeta docs/ en la raíz del proyecto actual con la siguiente estructura Obsidian:

docs/
├── .obsidian/              # Configuración de Obsidian
├── 00-indice/              # Índice de contenido
├── 01-especificaciones/    # Requisitos funcionales y no funcionales
├── 02-arquitectura/        # Base de datos, decisiones, diagramas, stack tecnológico
├── 03-implementacion/      # Backend, DevOps, referencias de API
├── 04-testing/             # Guía de tests unitarios y estrategia de test
├── 05-seguridad/           # OWASP Top 10
├── 06-aprendizajes/        # Deuda técnica
└── 07-configuracion/       # Variables de entorno

Puede ejecutarse tantas veces como se quiera: las carpetas y la configuración de Obsidian se preservan si ya existen, y cada sección se regenera con el estado actual del proyecto.

docs-pipeline mcp

Genera documentación técnica basada en el grafo de código real del proyecto, usando el servidor MCP codebase-memory-mcp como fuente de verdad estructural — a diferencia de docs-pipeline docs, que infiere a partir del árbol de archivos y el README, este comando indexa el código (funciones, clases, rutas, llamadas, dependencias) y solo documenta lo que efectivamente existe en el grafo.

Requiere tener el servidor codebase-memory-mcp instalado y conectado (claude mcp list). Si no está disponible, el comando lo indica y no hace nada — no rompe el resto del pipeline.

Genera, dentro de la misma carpeta docs/ (creando .obsidian/ si todavía no existe):

docs/
├── Architecture.md                 # Stack, entry points, hotspots, boundaries, clusters reales
├── Modules/<slug>.md                # Un archivo por módulo arquitectónico real (clusters detectados en el grafo)
├── Functions/<slug>.md              # Un archivo por función/clase/interfaz documentada (snippet real + llamadores/llamados)
├── Routes/<slug>.md                 # Solo si el proyecto tiene rutas HTTP indexadas
├── ADRs/<Sección>.md                # Solo si ya existe un ADR registrado en el MCP — nunca se inventa
├── Diagrams/call-graph-overview.md  # Diagrama Mermaid de dependencias reales entre módulos
├── TechDebt/                        # dead-code, duplicated-code, high-coupling, untested-functions, hotspots
└── Security/                        # owasp-summary + un archivo por categoría OWASP Top 10 aplicable

Algunas notas importantes:

• Los hallazgos de Security/ son candidatos estructurales para revisión humana, nunca vulnerabilidades confirmadas — el MCP no es un scanner SAST. Las categorías A04, A06 y A08 quedan explícitamente fuera de alcance (requieren revisión de diseño y SCA dedicado, ej. npm audit).
• Es idempotente: al volver a correrlo, las notas de símbolos que ya no existen en el grafo (renombrados o eliminados) se borran automáticamente.
• Tarda considerablemente más que docs-pipeline docs (puede ser 15-30 minutos incluso en proyectos chicos) porque cada archivo/categoría se genera con su propia llamada a Claude para maximizar confiabilidad, en vez de pedir todo en un solo turno.

Comandos de la extensión (VS Code / Cursor / Antigravity)

| Comando | Descripción | |---------|------------| | Docs Pipeline: Instalar Hook | Instala el hook en el proyecto actual | | Docs Pipeline: Desinstalar Hook | Elimina el hook del proyecto actual | | Docs Pipeline: Actualizar Hook | Regenera el hook con la versión más reciente | | Docs Pipeline: Ver Estado | Muestra si el hook está instalado y actualizado | | Docs Pipeline: Generar Documentación | Genera la documentación técnica completa (Obsidian) del proyecto actual en una terminal integrada — no requiere el hook instalado | | Docs Pipeline: MCP | Genera solo la documentación estructural vía MCP codebase-memory-mcp (Architecture, Modules, Functions, Routes, ADRs, Diagrams, TechDebt, Security) en una terminal integrada — requiere el servidor MCP conectado | | Docs Pipeline: Ver Versión | Muestra la versión instalada de la extensión |

La barra de estado muestra ✓ Docs cuando el hook está instalado o ○ Docs si no lo está.

Guía por IDE

VS Code

code --install-extension delfosti-docs-pipeline-1.0.18.vsix
# Luego: Ctrl+Shift+P → "Docs Pipeline: Instalar Hook"

Cursor

cursor --install-extension delfosti-docs-pipeline-1.0.18.vsix
# Luego: Ctrl+Shift+P → "Docs Pipeline: Instalar Hook"

Antigravity

# Opción A — extensión
antigravity --install-extension delfosti-docs-pipeline-1.0.18.vsix
# Luego: Ctrl+Shift+P → "Docs Pipeline: Instalar Hook"

# Opción B — CLI desde terminal integrada (Ctrl+`)
docs-pipeline install

Neovim (y cualquier editor sin soporte .vsix)

# Desde :terminal en Neovim o terminal del sistema
docs-pipeline install
docs-pipeline status

Flujo de trabajo post-instalación

Una vez instalado el hook (por cualquier vía), el desarrollador no cambia nada en su rutina:

git add .
git commit -m "feat: nueva funcionalidad"
# ↑ el pipeline corre automáticamente en background

git push
# ↑ aquí aparece el log con la documentación generada

El hook vive en .git/hooks/post-commit y no le importa qué IDE hizo el commit — Neovim con fugitive, lazygit, VS Code Source Control, terminal, cualquiera.

Configuración

Settings de la extensión

Las opciones se configuran en Settings (Ctrl+,) → buscar "Docs Pipeline".

| Setting | Tipo | Default | Descripción | |---------|------|---------|-------------| | docsPipeline.changelogEnabled | boolean | true | Activa/desactiva Fase 1 (bitácora) | | docsPipeline.docsUpdateEnabled | boolean | true | Activa/desactiva Fase 2 (Obsidian docs) | | docsPipeline.summaryEnabled | boolean | true | Activa/desactiva Fase 3 (CHANGELOG.md) | | docsPipeline.claudeBin | string | "" | Ruta absoluta al binario claude (auto-detección si vacío) | | docsPipeline.nodeBin | string | "" | Ruta absoluta al binario node (auto-detección si vacío) |

Configuración por proyecto (.env.local)

Puedes sobreescribir la configuración en cada proyecto creando un archivo .env.local en la raíz:

CHANGELOG_ENABLED=true
DOCS_UPDATE_ENABLED=false    # deshabilitar Obsidian docs en este proyecto
SUMMARY_ENABLED=true
CLAUDE_BIN=/ruta/absoluta/al/claude
DOCS_DEBUG=true              # mostrar respuesta raw de Claude en Fase 2
SUMMARY_DEBUG=true           # mostrar respuesta raw de Claude en Fase 3

El .env.local tiene precedencia sobre los settings de la extensión.

Cómo funciona por dentro

git commit
  └── post-commit hook (.husky/post-commit o .git/hooks/post-commit)
        └── node <proyecto>/.docs-pipeline/scripts/generate-init.mjs <range> <ref>
              ├── [Fase 1] → claude --print (análisis del diff)
              │              → escribe docs/changelog/YYYY-MM-DD_...md
              │              → git commit --no-verify
              ├── [Fase 2] → claude --print (detección de módulos + docs existentes)
              │              → escribe/actualiza docs/...md
              │              → git commit --no-verify
              └── [Fase 3] → claude --print (resumen ejecutivo)
                             → actualiza CHANGELOG.md
                             → git commit --no-verify

Variable clave: el hook establece DOCS_PIPELINE_PROJECT_ROOT apuntando a la raíz del proyecto antes de invocar los scripts. Los scripts usan esta variable para saber dónde escribir los archivos generados.

Notas por stack

Node.js / NestJS

Funciona directamente. Si el proyecto tiene Husky, el pipeline se agrega a .husky/post-commit sin interferir con otras reglas (lint-staged, etc.).

.NET / C#

Node.js debe estar instalado como herramienta de desarrollo. Los scripts no analizan código .NET específicamente — Claude recibe el diff de Git y genera documentación basada en los cambios, independientemente del lenguaje.

PHP / Laravel

Igual que .NET. Si el proyecto usa herramientas con hooks existentes, el pipeline puede coexistir en el mismo archivo post-commit (se agrega como un bloque delimitado).

Flutter / Dart

Si el proyecto está en un mono-repo con pubspec.yaml, Node.js debe instalarse aparte. El pipeline detecta cambios en cualquier archivo del repo.

Python / Django / FastAPI

Sin consideraciones especiales. Funciona igual que en cualquier proyecto Git.

Actualizar

Vía extensión

1. Instalar el nuevo .vsix
2. La extensión detecta automáticamente que el hook usa scripts de una versión anterior y muestra una notificación
3. Hacer clic en "Actualizar ahora" o ejecutar Docs Pipeline: Actualizar Hook

Vía CLI

# Actualizar el CLI (global)
npm install -g delfosti-docs-pipeline@latest

# Actualizar los scripts en cada proyecto
cd /ruta/a/mi-proyecto
docs-pipeline update

# Actualizar el CLI (local por proyecto)
npm install delfosti-docs-pipeline@latest
npx docs-pipeline update

Desinstalar

Vía extensión

Ctrl+Shift+P → "Docs Pipeline: Desinstalar Hook"

Para desinstalar la extensión del IDE:

code --uninstall-extension maycolz-delfosti.delfosti-docs-pipeline        # VS Code
cursor --uninstall-extension maycolz-delfosti.delfosti-docs-pipeline      # Cursor
antigravity --uninstall-extension maycolz-delfosti.delfosti-docs-pipeline # Antigravity

Vía CLI

docs-pipeline uninstall

En ambos casos, si el hook tenía otras reglas (lint-staged, etc.), se conservan. Solo se elimina el bloque del pipeline.

Estructura del proyecto

delfosti-docs-pipeline/
├── bin/
│   ├── docs-pipeline.js    ← Entry point del CLI (registrado por npm en el PATH)
│   ├── docs-pipeline.mjs   ← Implementación del CLI (ES Module)
│   └── hook-manager.mjs    ← Lógica install/uninstall (port de hookInstaller.ts)
├── src/
│   ├── extension.ts        ← Punto de entrada de la extensión VS Code
│   ├── hookInstaller.ts    ← Lógica de instalación del hook (vía extensión)
│   ├── nodeResolver.ts     ← Detección del binario node en el sistema
│   └── statusBar.ts        ← Indicador en la barra de estado
├── scripts/                ← Pipeline (se copia al proyecto al instalar)
│   ├── generate-init.mjs                      ← Orquestador principal (hook)
│   ├── 00-generate-ascii-art-enterprise.mjs
│   ├── 01-generate-changelog-bitacora.mjs
│   ├── 02-generate-living-documentation.mjs
│   ├── 03-generate-changelog-summary.mjs
│   ├── generate-docs-init.mjs                 ← Orquestador de `docs-pipeline docs`
│   ├── 04-generate-full-documentation.mjs     ← Genera docs/00-indice … docs/07-configuracion
│   ├── generate-mcp-init.mjs                  ← Orquestador de `docs-pipeline mcp`
│   └── 05-generate-mcp-documentation.mjs      ← Genera Architecture/Modules/Functions/Routes/ADRs/Diagrams/TechDebt/Security vía MCP
├── out/                    ← TypeScript compilado (generado por npm run compile)
├── package.json
├── tsconfig.json
└── .vscodeignore

Al instalar el hook en un proyecto (por cualquier vía), los scripts se copian a:

<tu-proyecto>/
└── .docs-pipeline/
    └── scripts/        ← copia local de los scripts
        ├── generate-init.mjs
        ├── .version    ← versión que generó esta copia
        └── ...

Recomendado: añadir .docs-pipeline/ al .gitignore del proyecto.

Solución de problemas

El pipeline no corre al hacer commit

1. Verificar que el hook está instalado: docs-pipeline status o Docs Pipeline: Ver Estado
2. Revisar que Node.js está en PATH: node --version
3. Revisar que Claude Code está instalado: claude --version

Error "Cannot find module" al hacer commit

Ocurre cuando la versión del CLI o extensión fue actualizada pero los scripts locales del proyecto no. Solución:

docs-pipeline update
# o desde VS Code: Ctrl+Shift+P → "Docs Pipeline: Actualizar Hook"

"Node.js no encontrado" al instalar via extensión

Configura la ruta manualmente en Settings → docsPipeline.nodeBin:

• Windows: C:\Program Files\nodejs\node.exe
• macOS/Linux: /usr/local/bin/node o la salida de which node

El hook corre pero Claude no responde

Verifica que Claude Code tiene sesión activa:

claude --print "test"

Si devuelve error, ejecuta claude para autenticarte.

Conflicto con Husky

Si el proyecto usa Husky, el pipeline detecta .husky/ automáticamente y agrega su bloque al final del hook sin sobreescribir reglas existentes. El bloque está delimitado con marcadores y puede removerse limpiamente con docs-pipeline uninstall o Docs Pipeline: Desinstalar Hook.

Desarrollo y build

cd delfosti-docs-pipeline
npm install
npm run compile     # compilar TypeScript
npm run watch       # modo observación continua
npm run package     # empaquetar como .vsix
npm link            # instalar CLI localmente para pruebas

Licencia

MIT — Delfosti Engineering Team