Version: 1.0 · Fecha: 2026-04-20
Guía paso a paso para que un nuevo miembro del equipo (arquitecto, consultor, QA, DevOps) pueda instalar, configurar y operar el pipeline V1→V2 en su máquina en menos de 2 horas.
sudo apt update
sudo apt install -y \
git \
python3 python3-venv python3-pip \
poppler-utils \
imagemagick \
libpango-1.0-0 libpangoft2-1.0-0 \
libcairo2
Al menos uno de:
sudo apt install libreoffice-core --no-install-recommends.cd /media/catc/extra/Centrica # o tu ruta
git clone <url-del-repo-documentation> Documentation
cd Documentation
Verifica estructura:
ls
# Debes ver: wiki-arquitectura/ centrica/ .claude/ (y otros)
cd centrica/11_Backlog/03_Prompts/scripts
python3 -m venv .venv
.venv/bin/pip install --upgrade pip
.venv/bin/pip install python-docx pyyaml Pillow jinja2 weasyprint
Verifica:
.venv/bin/python3 -c "
import docx, yaml, PIL, jinja2, weasyprint
print('✓ python-docx:', docx.__version__)
print('✓ pyyaml:', yaml.__version__)
print('✓ Pillow:', PIL.__version__)
print('✓ jinja2:', jinja2.__version__)
print('✓ weasyprint:', weasyprint.__version__)
"
Salida esperada: 5 líneas con ✓.
chmod +x 01_extract_hu.sh 02_parse_hu.py 03_validate_v2.py 04_generate_docx.py 05_render_wireframe.py
ls -la
# Las 5 herramientas deben tener 'x' en sus permisos
Corre el pipeline sobre la HU-CON-012 (que ya fue procesada como piloto) para validar que todo funciona:
cd /media/catc/extra/Centrica/Documentation/centrica/11_Backlog/03_Prompts/scripts
./01_extract_hu.sh \
"/media/catc/extra/Centrica/HU/DESARROLLO NEBULA/SPRINT-02/HU-CON-012-V1 Causación de Cuentas – Modelo Privado (1).pdf" \
"/media/catc/extra/Centrica/HU/DESARROLLO NEBULA/SPRINT-02/ANEXOS/Anexo 1 HU-CON-012-V1 Flujo de Causación de Cuentas Modelo Privado-Diagrama de flujo.pdf" \
"/media/catc/extra/Centrica/HU/DESARROLLO NEBULA/SPRINT-02/ANEXOS/Anexo 2 CASOS DE PRUEBA - HU-CON-012 Causación de Cuentas – Modelo Privado.pdf" \
/tmp/smoke-test
Esperar ~30 seg. Verificar:
ls /tmp/smoke-test/02_fase_A_extraccion/
# hu-v1.txt, anexo1.txt, anexo2.txt, wireframes*/, sections.tsv, extraction.log
.venv/bin/python3 02_parse_hu.py /tmp/smoke-test/02_fase_A_extraccion \
--pdf-name "HU-CON-012-V1 Causación de Cuentas – Modelo Privado (1).pdf"
Salida esperada:
[OK] Generado: /tmp/smoke-test/02_fase_A_extraccion/extracted.yaml
Código HU: HU-CON-012
Reglas V1: 26
Criterios V1: 25
Mockups: 51
.venv/bin/python3 04_generate_docx.py \
/media/catc/extra/Centrica/Documentation/centrica/11_Backlog/04_Historias_Cliente/PILOTO_HU_CON_012/10_full_spec.yaml \
/tmp/smoke-test/02_fase_A_extraccion \
/tmp/smoke-test/HU-CON-012-SMOKE.docx
Espera ~15 seg (renderiza 10 wireframes). Verifica:
ls -la /tmp/smoke-test/HU-CON-012-SMOKE.docx
# Debe existir, > 500 KB
.venv/bin/python3 03_validate_v2.py \
/tmp/smoke-test/HU-CON-012-SMOKE.docx \
--v1-yaml /tmp/smoke-test/02_fase_A_extraccion/extracted.yaml \
--output /tmp/smoke-test/reporte.md
cat /tmp/smoke-test/reporte.md | head -20
Salida esperada: reporte con E1 pasando, E2 al 100%, E3 >= 85%, E4 >= 85%.
Abre /tmp/smoke-test/HU-CON-012-SMOKE.docx en WPS Office → Archivo → Exportar → PDF.
Verifica visualmente que:
Si todo lo anterior funcionó: instalación del pipeline está ✓.
Si la empresa ya compró Claude:
npm install -g @anthropic-ai/claude-code
claude --version
claude login
# Autentica con tu cuenta corporativa
cd /media/catc/extra/Centrica/Documentation
# El settings.template.json ya está en el repo
cp .claude/settings.template.json .claude/settings.json
ls .claude/agents/
# hu-extractor.md, wireframe-interpreter.md, mapping-analyst.md, docx-synthesizer.md, hu-validator.md
ls .claude/skills/
# reprocesar-hu, crear-hu-cero, validar-hu
claude
Dentro de Claude Code, probar:
/validar-hu /tmp/smoke-test/HU-CON-012-SMOKE.docx
Debe invocar el subagente hu-validator y retornar el reporte.
Ya puedes procesar una HU real. Dos caminos:
claude
/reprocesar-hu HU-CON-013
O manualmente si no tienes Claude Code:
cd /media/catc/extra/Centrica/Documentation/centrica/11_Backlog/03_Prompts/scripts
# 1. Fase A
./01_extract_hu.sh "<ruta-v1.pdf>" "<ruta-anexo.pdf>" "<ruta-casos.pdf>" ../../04_Historias_Cliente/HU-CON-013/fase_A
.venv/bin/python3 02_parse_hu.py ../../04_Historias_Cliente/HU-CON-013/fase_A --pdf-name "<v1-filename>"
# 2. Fase B — aplicar prompt Fase B en claude.ai por cada mockup
# 3. Fase C — aplicar prompt Fase C en claude.ai con extracted.yaml + catalog.yaml
# 4. Gate C4 — revisar y firmar mapping-approved.yaml
# 5. Fase D.1 — aplicar prompt Fase D en claude.ai con mapping-approved.yaml → hu_spec.yaml
# 6. Fase D.2:
.venv/bin/python3 04_generate_docx.py \
../../04_Historias_Cliente/HU-CON-013/hu_spec.yaml \
../../04_Historias_Cliente/HU-CON-013/fase_A \
../../04_Historias_Cliente/HU-CON-013/HU-CON-013-V2.docx
# 7. Fase E:
.venv/bin/python3 03_validate_v2.py \
../../04_Historias_Cliente/HU-CON-013/HU-CON-013-V2.docx \
--v1-yaml ../../04_Historias_Cliente/HU-CON-013/fase_A/extracted.yaml \
--output ../../04_Historias_Cliente/HU-CON-013/reporte_validacion.md
# 8. Export PDF en WPS
claude
/crear-hu-cero
Sigue las preguntas del skill.
O manualmente:
cp centrica/11_Backlog/02_Templates/TEMPLATE_HU_WIREFRAME_FIRST.yaml \
centrica/11_Backlog/04_Historias_Cliente/HU-CON-XXX/hu_spec.yaml
# Editar hu_spec.yaml en VS Code siguiendo [01_CONTEXTO_1_HU_DESDE_CERO](./01_CONTEXTO_1_HU_DESDE_CERO)
# Luego Fase D.2 + Fase E igual que arriba.
Antes de trabajar en HUs reales, lee:
Tiempo total de onboarding: ~2 horas.
Documentation/
├── wiki-arquitectura/
│ └── zona-interna/10-backlog/PROCESO_HU_NEBULA/ ← ESTA WIKI
│
├── .claude/ ← Config Claude Code
│ ├── settings.json
│ ├── settings.template.json
│ ├── agents/*.md ← 5 subagentes
│ └── skills/*/SKILL.md ← 3 skills
│
├── centrica/11_Backlog/
│ ├── 02_Templates/
│ │ ├── TEMPLATE_HU_WIREFRAME_FIRST.yaml ← usar para HU desde cero
│ │ └── TEMPLATE_HU_CONSULTORIA_V3.md
│ │
│ ├── 03_Prompts/
│ │ ├── PROMPT_PIPELINE_HU_V1_V2.md ← prompt maestro
│ │ ├── PROMPT_VALIDACION_HU.md ← gate E5
│ │ └── scripts/
│ │ ├── .venv/ ← virtualenv
│ │ ├── 01_extract_hu.sh
│ │ ├── 02_parse_hu.py
│ │ ├── 03_validate_v2.py
│ │ ├── 04_generate_docx.py
│ │ ├── 05_render_wireframe.py
│ │ ├── templates/*.html.j2 + nebula.css
│ │ └── icons/lucide_icons.py
│ │
│ └── 04_Historias_Cliente/
│ ├── PILOTO_HU_CON_012/ ← ejemplo de referencia
│ ├── HU-CON-013/ ← las siguientes que proceses
│ └── ...
│
└── _pipeline_runs/ ← logs de auditoría
├── HU-CON-012/
└── HU-CON-013/
/media/catc/extra/Centrica/Documentation.HU-CON-012 pasó (DOCX + PDF generados)._pipeline_runs/ para ver logs históricos.Documentation/ con etiqueta pipeline-v1-v2.| Problema | Solución |
|---|---|
weasyprint falla con "pango not found" |
sudo apt install libpango-1.0-0 libpangoft2-1.0-0 |
pdftoppm: command not found |
sudo apt install poppler-utils |
ImportError: docx en scripts |
Ejecutar con .venv/bin/python3, no con python3 del sistema |
| DOCX generado con tablas vacías | Revisar que hu_spec.yaml tenga los alcances bien estructurados |
| Wireframe se recorta mal | Ajustar umbral de crop en 05_render_wireframe.py función html_to_png |
| WPS tarda en abrir DOCX grande | Es esperado si tiene >10 wireframes embebidos (~20 seg) |
claude command not found |
npm install -g @anthropic-ai/claude-code |
| Version | Fecha | Autor | Descripcion |
|---|---|---|---|
| 1.0.0 | 2026-04-20 | Carlos Torres | Guia de replicacion inicial |