Hornero

Construí tu software como el hornero su nido — spec por spec. (Build your software like the hornero builds its nest — spec by spec.)

End-to-end SDD platform — desde la spec ambigua del cliente hasta el bug en producción.

🇪🇸 Getting started · 📚 Comparativa · 🎯 Cursor o Claude Code · 💰 Pricing · 📜 Constitution

🇬🇧 Getting started (EN) · Comparison (EN) · Cursor vs Claude Code (EN)

¿Qué es Hornero?

Una plataforma SDD (Spec-Driven Development) end-to-end que cubre el ciclo de vida completo de un proyecto de software: refinement → analysis → design → estimation → planning → implementation → QA → bugs → cambios → feedback. Multi-IDE (Claude Code y Cursor), bilingüe (Spanish + English), con audit trail GitHub-native, governance compliance-ready.

El nombre. El hornero (Furnarius rufus) es el ave nacional de Argentina, conocida por construir nidos de barro estructurados, durables y meticulosamente planificados. Mismo enfoque, distinto medio: specs que compounden, código que llega a producción.

Para quién: agencias y ISVs LATAM mid-size que entregan software a clientes externos con governance + traceability. Tech Leads de equipos de 5-50 devs que necesitan leverage operacional — más proyectos en paralelo sin contratar más gente, sin sacrificar calidad.

Por qué Hornero y no otras herramientas: la cobertura horizontal end-to-end es el moat. IDE assistants cubren implementación, no-code cubre prototipos, autonomous agents pierden gobernanza. Hornero cubre todas las fases con checkpoints humanos en cada transición. Detalle: comparativa.

Highlights

| | | |--|--| | 90+ agentes especializados (refinement, analysis, design, implementation, QA, migration, post-prod) | 35 slash commands invocables (/refinar, /analizar-spec, /implementar, /qa, /bug, /cambio, /feedback...) | | Multi-IDE Cursor + Claude Code via adapter — sin forquear el framework (P10) | Spec viva con 3-way merge para changes concurrentes | | Brownfield Tier 1 — 5 stacks (GeneXus, Java Spring, Django, Rails, .NET Core) | Web dashboard local Astro + React, read-only, 0 telemetría | | EARS notation + validator de antipatterns | Personas opt-in — /as-architect, /as-pm, /as-qa | | Commercial proposal generator — Statement of Work auto-emitido | Multi-modelo Anthropic — Opus/Sonnet/Haiku per-agent (~30-40% menos costo) | | Hooks event-driven (Claude Code) — auto-regen, auto-validate | CI/CD GitHub Actions — cursor-adapter validate + cli-smoke + rag-engine tests | | Context Engine local (RAG, opt-in) — LanceDB + Ollama, hybrid search BM25 + vector, ~-72% tokens/proyecto | Métricas + cache + reranker opcionales — telemetría NDJSON, LRU 256, cross-encoder MS MARCO |

Quick install

Recomendado — vía npm (sin clonar repo):

# Instalar global desde GitHub (release v2.0.1)
npm install -g github:Accionpoint-SA/pipelines#v2.0.1

# Inicializar tu proyecto desde un sample (spec + config pre-completados)
sdlc init ~/proyectos/mi-proyecto --template greenfield-saas
cd ~/proyectos/mi-proyecto
git init && git add . && git commit -m "init: hornero scaffold"

# O ver samples disponibles:
sdlc init --list-templates

Eso es todo. sdlc queda disponible global, los archivos del framework viven en ~/.npm/... (no contaminan tu workspace).

Opcional — Context Engine local (RAG): activar con --with-rag durante el init. Instala Ollama si falta, hace pull del modelo de embeddings (~280 MB), instala las Python deps mínimas y verifica.

⚠️ El RAG todavía NO está en v2.0.1. Vive en la branch primate/rag-v1 (Sprints 1-5 cerrados, 354 tests passing). Para usarlo, instalar desde la branch hasta que cortemos v2.1.0:

# Desde la branch (estable de Sprint 5, sujeto a cambios menores):
npm install -g github:Accionpoint-SA/pipelines#primate/rag-v1

# Después:
sdlc init ~/proyectos/mi-proyecto --template greenfield-saas --with-rag --yes

Cuando se cierre el merge a main y el tag v2.1.0 (próximo release), bastará con #v2.1.0.

El RAG reduce ~-72% los tokens consumidos por los agentes en proyectos típicos via queries dirigidas en lugar de Read entero de specs/código. Off por default; --yes auto-confirma los prompts (recomendado para CI). Setup manual y comandos comunes: .claude/skills/rag-engine/README.md.

Pre-requisitos: Node.js ≥ 20 y Python 3.9+. Bash + GNU coreutils. Linux / macOS / WSL. Windows nativo no soportado.

Cuando publiquemos a npm registry (M3 offline pendiente): npm install -g @hornero/cli.

Alternativa — clone directo (para contribuir al framework):

git clone https://github.com/Accionpoint-SA/pipelines hornero-upstream
cd hornero-upstream
export PATH="$(pwd)/bin:$PATH"
sdlc init ~/proyectos/mi-proyecto --template greenfield-saas \
  --link-upstream https://github.com/Accionpoint-SA/pipelines

Después: editar .claude/agents/shared/pipeline-config.md (configuración del proyecto), agregar la spec en sdlc/input/functional-spec.md, y abrir el repo en Claude Code o Cursor → /refinar o /analizar-spec. Detalle paso a paso: getting-started.

Tiers (resumen)

| Tier | Precio | Qué incluye | Buyer ideal | |------|--------|-------------|-------------| | Free | $0 | Refinement + Analysis + Design + Estimation + Planning + Constitution + Multi-IDE + Web dashboard + Personas opt-in | Dev individual, contributor OSS, evaluación | | Pro | $49/seat/mo | + Implementation + QA + Bug/CR/Feedback + Brownfield Tier 1 (4 stacks) + Living spec auto-sync + Commercial proposal + Multi-modelo Anthropic + Hooks | Agencia/ISV mid-size 5-50 devs | | Enterprise | desde $999/mo (10 seats) | + GeneXus migration + Brownfield Tier 2 + SAML/SSO + Audit logs + Dedicated support | Mid-size con legacy LATAM/España |

Detalle: pricing.md. Split físico OSS/Pro/Enterprise: sdlc/roadmap/oss-manifest.yaml.

Status del producto (a 2026-05-05)

• ✅ Producto comercial MVP listo — 36 sprints completos del SDD positioning roadmap.
• ✅ Greenfield + brownfield (5 stacks Tier 1) operativos end-to-end.
• ✅ Multi-IDE (Cursor + Claude Code) con adapter automático.
• ✅ OSS-core split formalizado, bundle reproducible.
• ✅ Naming + brand voice — Hornero (M3 resuelto 2026-05-05). Repo GitHub: rename pendiente como tarea offline.
• ✅ i18n English first-class — docs/en/ con 4 docs públicas traducidas + flag OUTPUT_LANG en pipeline-config.md (M4 resuelto 2026-05-05).
• ✅ 3 sample templates — greenfield-saas, greenfield-api, brownfield-gx-mini operativos via sdlc init --template <name>.
• ✅ Context Engine local (RAG) — Sprints 1-5 completos: indexer + MCP server (8 tools), 19 agentes integrados (greenfield + brownfield + post-impl), métricas + LRU cache + reranker opt-in, CI gate. Activación: sdlc init --with-rag.

Roadmap completo: sdlc/roadmap/STATE.md.

Contribuir

Bienvenidas contribuciones a OSS-core (MIT). Issues + PRs en este repo. Detalle: CONTRIBUTING.md. Code of Conduct: CODE_OF_CONDUCT.md. Reportar vulnerabilidades: SECURITY.md.

Changelog

Historial de releases versionado en CHANGELOG.md. Versión actual: v2.0.1 (2026-05-05) — Hornero (patch sobre v2.0.0 con install via npm funcional).

Esta página es el manual técnico del framework — exhaustivo, secciones 1-11 abajo. Para el pitch público de cara al cliente, ver docs/.

Índice

1. Para qué sirve
2. Arquitectura general
3. Cómo empezar un proyecto nuevo
4. Configuración del proyecto (pipeline-config.md)
5. Hornero — descripción completa
   • GX Migration
   • 0. Refinement
   • 1. Analysis
   • 2. Implementation
   • 3. QA
   • 4. Bug Reporter
   • 5. Change Request
   • 6. Feedback Loop
6. Slash commands y skills
7. Flujo completo de un proyecto
8. Estructura de carpetas del repo
9. Capacidades del pipeline
10. Before / After
11. Cómo contribuir mejoras al upstream

1. Para qué sirve

Este repo resuelve un problema concreto: usar agentes Claude de forma estructurada y trazable para construir software, desde que llega un documento de requisitos hasta que el sistema está en producción y recibiendo feedback.

Sin este framework, cada conversación con Claude es aislada. Con él, cada acción deja rastro: en archivos de output, en sdlc/status-board.md, en la BD del proyecto, y en GitHub PRs. El humano (Tech Lead) mantiene el control en los puntos de decisión críticos; el agente hace el trabajo pesado entre esos puntos.

Qué hace por vos:

• Analiza especificaciones funcionales y genera documentación técnica completa (arquitectura, modelo de datos, API, estimación, roadmap)
• Implementa sesión por sesión, con tests, commit y PR automáticos en GitHub
• Corre 8 capas de QA y genera fixes listos para merge
• Gestiona bugs, change requests y feedback de producción de forma trazable
• Mantiene CLAUDE.md actualizado como memoria compartida entre sesiones

2. Arquitectura general

[Sistema GeneXus Legacy]
      │
      ▼
┌─────────────────────────────────────────────────┐
│  PIPELINE GX — Migration (opcional)                     │
│  Reverse engineering: N XML exports de GeneXus →        │
│  functional-spec-enriched.md                            │
│  (el XML es fuente única — no requiere dump de BD)      │
└──────────────────────────────────────────────────┘
      │
      ▼
[Spec Funcional]
      │
      ▼
┌──────────────────────────────────────────────────┐
│  PIPELINE 0 — Refinement (opcional)                     │
│  Aclara ambigüedades antes de analizar                  │
└──────────────────────────────────────────────────┘
      │
      ▼
┌──────────────────────────────────────────────────┐
│  PIPELINE 1 — Analysis                                  │
│  Analyst-Specifier → System Designer + API Designer     │
│  (paralelo) → Estimator → Planner                       │
│  OUTPUT: sdlc/output/ con 7 artefactos de diseño             │
│  GATES: validate-artifacts.sh entre cada paso           │
└──────────────────────────────────────────────────┘
      │
      ▼
┌──────────────────────────────────────────────────┐
│  PIPELINE 2 — Implementation                            │
│  Orchestrator → Session Executor (batch de 2-4 sesiones)│
│  + Sprint Orchestrator (paralelo con worktrees)         │
│  + Auto-Reflect + State Tracking + Knowledge Capture    │
│  OUTPUT: código + tests + PRs en GitHub                 │
└──────────────────────────────────────────────────┘
      │
      ▼
┌──────────────────────────────────────────────────┐
│  PIPELINE 3 — QA                                        │
│  8 capas de detección → diagnóstico → fixes → PRs       │
└──────────────────────────────────────────────────┘
      │
      ▼ (producción / post-implementación)
┌──────────────┐  ┌──────────────────┐  ┌──────────────┐
│  Pipeline 4  │  │   Pipeline 5     │  │  Pipeline 6  │
│  Bug Reporter│  │  Change Request  │  │ Feedback Loop│
│  Bugs en     │  │  Cambios sobre   │  │  Feedback de │
│  cualquier   │  │  features ya     │  │  producción  │
│  etapa       │  │  implementadas   │  │  o sistema   │
└──────────────┘  └──────────────────┘  └──────────────┘

Los pipelines 4, 5 y 6 se pueden activar en cualquier momento y se comunican entre sí mediante el Delegation Protocol: cuando el feedback-loop detecta un bug, lo delega al bug-reporter; cuando un bug revela un cambio de diseño, se delega al change-request. Toda delegación pasa por confirmación del Tech Lead.

3. Cómo empezar un proyecto nuevo

Paso 1 — Clonar este repo (NO hacer fork de GitHub)

git clone https://github.com/tu-usuario/hornero mi-proyecto
cd mi-proyecto
git remote rename origin upstream

Paso 2 — Crear el repo del proyecto en GitHub y conectarlo

# Crear el repo en GitHub (vacío, sin README) y luego:
git remote add origin https://github.com/tu-usuario/mi-proyecto
git push -u origin main

A partir de acá, origin es tu proyecto y upstream es este framework. El proyecto queda desenganchado — puede ser privado, sin relación pública con el upstream.

Paso 3 — Completar .claude/agents/shared/pipeline-config.md

Este es el único archivo que necesitás tocar para que todos los pipelines funcionen con tu proyecto. Ver sección 4. Configuración del proyecto.

Paso 4 — Agregar la spec funcional

Copiar el documento de requisitos del proyecto a:

sdlc/input/functional-spec.md

Paso 5 — Arrancar

Si la spec tiene ambigüedades importantes → Pipeline 0: Refinement

Si la spec está clara → Pipeline 1: Analysis

4. Configuración del proyecto (pipeline-config.md)

Archivo: .claude/agents/shared/pipeline-config.md

Es el único punto de configuración específica del proyecto. Todos los agentes lo leen. Si está bien completado, los pipelines funcionan sin tocar ningún otro archivo.

Qué hay que completar

Repositorio GitHub — necesario para que los agentes creen branches y PRs:

GITHUB_OWNER="tu-usuario-o-org"
GITHUB_REPO="nombre-del-repo"
GITHUB_BASE_BRANCH="main"

Base de datos (para diagnóstico) — si el proyecto tiene BD con Docker:

DB_SERVICE="db"          # nombre del servicio en docker-compose.yml
DB_USER="app_user"
DB_NAME="app_db"

Módulos críticos — archivos cuyo impacto en producción es alto. Todo bug que los toque requiere confirmación explícita antes de proceder:

src/core/payments/processor.py
src/domain/pricing/calculator.py

Comandos de test — tres variantes que usan los agentes:

TEST_ALL="pytest tests/ -v"                    # suite completa
TEST_FILTERED="pytest tests/ -k '[keyword]'"   # archivo/módulo específico
TEST_REGRESSION="pytest tests/ -v --tb=short"  # post-merge

Parámetros configurables (si aplica) — para que el feedback-loop pueda proponer ajustes basados en evidencia.

Configuración de IA (si aplica) — rutas a prompts o configs de LLM si el proyecto los tiene.

CLAUDE.local.md — reglas específicas del entorno local

Qué problema resuelve

Claude Code carga CLAUDE.md al inicio de cada sesión como contexto permanente. Todo lo que está ahí, el agente lo "sabe" siempre. Pero hay reglas que dependen de la máquina, no del proyecto: qué MCPs tenés instalados, si usás git push directo o MCP GitHub, si tenés Docker o no. Estas reglas cambian entre máquinas, entre desarrolladores, y entre entornos (dev vs CI).

Si esas reglas van en CLAUDE.md (commiteado), cada desarrollador tiene que editarlo para su setup y después no puede pushear sin pisar las reglas de los demás. Si van en un archivo separado que no se commitea, cada uno tiene su versión local sin conflictos.

La solución es el split:

| Archivo | Se commitea | Contiene | Quién lo edita | |---------|-------------|----------|----------------| | CLAUDE.md | Sí | Descripción del framework, pipelines, convenciones, estructura — todo lo genérico | El framework (upstream) | | CLAUDE.local.md | No (gitignoreado) | MCPs disponibles, reglas de push/PR, tooling local — todo lo que depende del setup | Cada desarrollador en su máquina | | pipeline-config.md | Sí | Módulos críticos, comandos de test, repo GitHub — todo lo específico del proyecto | El Tech Lead al configurar el proyecto |

Cómo funciona la carga

CLAUDE.md incluye al final la directiva:

@CLAUDE.local.md

Claude Code interpreta @archivo como un include: al cargar CLAUDE.md, también carga el contenido de CLAUDE.local.md si existe. El efecto es que el agente ve un solo bloque de contexto que combina las reglas genéricas (committeadas) con las reglas locales (no committeadas), sin que ninguna de las dos necesite saber de la otra.

Si CLAUDE.local.md no existe (por ejemplo, en un CI o en un clon fresco), Claude Code simplemente ignora el include y funciona solo con CLAUDE.md. Nada se rompe — las reglas locales son opcionales.

Qué va en cada archivo

En CLAUDE.local.md (no committeado):

• Reglas de push y PR que dependen de los MCPs instalados (ej: "nunca git push directo, usar siempre mcp__github__push_files")
• Tabla de MCPs disponibles (github, playwright, etc.) con los tools exactos que el agente puede usar
• Cualquier restricción o capacidad que cambie entre máquinas (ej: "Docker no disponible en este entorno" o "usar puerto 3001 para el dev server")

NO va en CLAUDE.local.md:

• Descripción del framework, pipelines, convenciones de commits/branches → eso vive en CLAUDE.md
• Configuración del proyecto (módulos críticos, comandos de test, repo GitHub) → eso vive en pipeline-config.md

Ejemplo concreto

Un CLAUDE.local.md típico se ve así:

# CLAUDE.local.md — Configuración local del entorno

> Este archivo NO se commitea. Contiene reglas y herramientas
> específicas del setup local.

---

## Reglas de push y PR (MCP GitHub)

1. **Commit local siempre antes del push.** Flujo:
   `git add` → `git commit` → `mcp__github__create_branch`
   → `mcp__github__push_files` → `mcp__github__create_pull_request`
2. **Nunca `git push` directo** — usar siempre `mcp__github__push_files`
3. **Después del merge**, hacer `git pull origin main`

---

## MCPs disponibles

### Push y PR

| MCP | Tool | Uso |
|-----|------|-----|
| github | `mcp__github__create_branch` | Crear branch remota |
| github | `mcp__github__push_files` | Pushear archivos |
| github | `mcp__github__create_pull_request` | Abrir PR |

### Tests E2E

| MCP | Tool | Uso |
|-----|------|-----|
| playwright | `mcp__playwright__browser_navigate` | Tests E2E |
| playwright | `mcp__playwright__browser_take_screenshot` | Capturas |

Si un desarrollador no tiene Playwright instalado, simplemente omite esa sección de su CLAUDE.local.md y el agente no intentará usar esos tools. Si alguien trabaja en un entorno donde sí puede hacer git push directo (tiene SSH keys configuradas), puede reemplazar la regla "nunca git push directo" por "preferir git push via SSH".

Cómo crear el tuyo al configurar un proyecto

Al clonar el framework en un proyecto nuevo, creá tu CLAUDE.local.md en la raíz:

1. Verificá qué MCPs tenés disponibles en tu Claude Code (la lista aparece al correr /preflight)
2. Copiá la estructura del ejemplo de arriba
3. Ajustá las reglas de push/PR según tu setup
4. Agregá o quitá secciones de MCPs según lo que tengas instalado

El archivo ya está en .gitignore, así que no se commitea por accidente.

5. Hornero — descripción completa

Pipeline GX — GX Migration

Para qué sirve: Hacer reverse engineering de un sistema GeneXus legacy para generar una especificación funcional completa (functional-spec-enriched.md) que alimenta el resto de los pipelines. Toma como input cualquier cantidad de exports XML de Knowledge Bases GeneXus (1, 2 o N).

Cuándo usarlo: Cuando el proyecto es una migración de un sistema GeneXus existente y no se tiene documentación funcional.

Cuándo saltarlo: Si ya tenés una spec funcional escrita manualmente, ir directamente al Pipeline 0 o 1.

Cómo arrancarlo:

"ejecutar pipeline"

o con el slash command: /run-pipeline

Pre-requisito (una sola vez por proyecto):

pip install -r .claude/skills/gx-xml-parser/requirements.txt

Esto instala lxml>=4.9, usado por la CLI Python parse_gx_kb.py que Stage 1 invoca para parsear cada XML de manera determinista.

Cómo funciona:

El pipeline tiene 6 stages con gates de calidad entre cada uno. El orquestador coordina la ejecución y nunca avanza si un gate falla.

| Stage | Agente | Qué hace | Gate | |-------|--------|----------|------| | 1 | GX Inventory Analyzer | Auto-descubre los *.xml en sdlc/input/gx/, invoca la CLI Python por cada uno, produce JSONL (objetos, tablas, atributos, transactions), clasifica y construye grafo de dependencias | G1: CLI OK, parse errors < 5%, Transactions detectadas | | 2 | DB Legacy Modeler | Reconstruye el modelo físico de datos consumiendo los JSONL de todas las KBs (JOIN tables + attributes + transactions). Fuente única: el XML, no accede a DB viva | G2: ≥50 tablas, ≥80% con PK, columnas con tipo resuelto | | 3 | Functional Domain Reconstructor | Reconstruye entidades, procesos, reglas de negocio y módulos desde código GX | G3: ≥70% Transactions cubiertas, ≥60% Procedures clasificados | | 4 | Legacy Reconciler | Reconcilia modelo funcional (Stage 3) con modelo físico (Stage 2) | G4: ≥70% entidades mapeadas | | 5 | Ambiguity & Risk Refiner | Identifica zonas de incertidumbre, clasifica riesgos, genera preguntas críticas | G5: todas las ambigüedades registradas, risk matrix completa | | 6 | Functional Spec Consolidator | Integra todo en functional-spec-enriched.md | — |

Stage 2 depende de Stage 1 (consume los JSONL que Stage 1 produce). En GeneXus la BD se regenera desde el KB, por lo que el XML es la fuente única de verdad del modelo de datos — no se requiere dump de MSSQL ni drift check.

Archivos de entrada:

• sdlc/input/gx/*.xml — cualquier cantidad de exports de Knowledge Bases GeneXus. El kb_id de cada KB es el basename del archivo sin extensión (ej: web.xml → web, facturacion.xml → facturacion). Soporta formato Classic 2.x (GX 8.x/9.x) y Evolution 3+ auto-detectado.
• Override opcional en pipeline-config.md via variable GX_KBS=("<kb_id>:<path>" ...) si se quieren IDs lógicos distintos al filename.

Comportamiento por cantidad de XMLs:

• 0 → pipeline bloqueado
• 1 → procesa, skippea lógica cross-KB (sin detección de duplicados)
• N≥2 → procesa todos, detecta duplicados y divergencias entre KBs

Archivos de salida:

sdlc/output/
├── stage-01-gx/                    ← inventario GX y grafo de dependencias
├── stage-02-db/                    ← modelo físico anotado y relaciones implícitas
├── stage-03-domain/                ← entidades, procesos, reglas de negocio
├── stage-04-reconciliation/        ← mapeo entidad↔tabla, DAL spec
├── stage-05-refinement/            ← ambigüedades, riesgos, preguntas críticas
└── stage-06-spec/
    └── functional-spec-enriched.md ← entregable final → input para Pipeline 0/1

Slash commands disponibles:

| Command | Qué hace | |---------|----------| | /run-pipeline | Ejecutar pipeline completo, parcial (stage N) o desde un stage (from N) | | /check-gates | Verificar estado de los gates G1-G5 sin ejecutar agentes | | /query-spec | Consultar el spec consolidado por entidad, proceso, módulo o regla | | /resolve-ambiguity | Registrar la resolución de una ambigüedad (Q-NNN o AMB-NNN) |

CLI Python del parser (.claude/skills/gx-xml-parser/):

El parser es invocado automáticamente por Stage 1, pero puede ejecutarse manualmente para debugging:

python .claude/skills/gx-xml-parser/parse_gx_kb.py \
    --input sdlc/input/gx/web.xml --kb web \
    --output /tmp/out/ --strict

Exit codes: 0 OK / 1 error o validación estricta falló / 2 formato desconocido. Produce JSONL deterministas (objects.jsonl, tables.jsonl, attributes.jsonl, transactions.jsonl) + parse-report.md con métricas.

Después de este pipeline: El functional-spec-enriched.md se usa como input del Pipeline 0 (Refinement) o directamente del Pipeline 1 (Analysis).

Pipeline 0 — Refinement

Para qué sirve: Clarificar ambigüedades en la especificación funcional antes de analizarla. Evita que el pipeline de análisis genere artefactos basados en supuestos incorrectos.

Cuándo usarlo: Cuando la spec tiene reglas vagas ("según corresponda", "a definir"), flujos incompletos, integraciones sin protocolo definido, o actores con permisos ambiguos.

Cuándo saltarlo: Si la spec es clara y completa, ir directamente al Pipeline 1.

Cómo arrancarlo:

"refinar spec"

Cómo funciona:

El pipeline es iterativo por ciclos y usa un circuito cliente en 3 pasos (agente → /refinement-send → cliente → /refinement-receive → siguiente ciclo). Cada ciclo empieza con análisis de ambigüedades y termina con la spec enriquecida actualizada. Máximo 4 ciclos; después del 4° se fuerza el cierre documentando como riesgo las ambigüedades sin resolver.

Clasificación de ambigüedades (AMBs) por impacto:

| Prioridad | Criterio | Máx por ciclo | |-----------|----------|---------------| | 🔴 Crítica | Bloquea implementación; si se asume mal hay que reescribir código. Afecta modelo de datos, flujo principal, integración externa, o regla de dinero/compliance. | 5 | | 🟡 Importante | Afecta features del MVP pero tiene implementación default razonable. Riesgo: funcionalidad incorrecta, no reescritura total. | 8 | | 🟢 Deseable | Afecta features Should Have / Could Have. Puede implementarse con supuesto documentado. | 5 |

Circuito completo de un ciclo:

┌──────────────────────────────────────────────────────────────┐
│  1. "refinar spec" (ciclo 1) o "ciclo de refinamiento N"    │
│     → refinement-orchestrator                                │
│       • Fase A: análisis de ambigüedades                     │
│       • Fase B: genera preguntas priorizadas                 │
│       • (ciclos 2+) Fase C: incorpora respuestas del ciclo N-1│
│     → escribe sdlc/input/refinement/rounds/round-N-q.md           │
│     → pausa                                                   │
└────────────────────────────────┬──────────────────────────────┘
                              ↓
┌──────────────────────────────────────────────────────────────┐
│  2. /refinement-send                                          │
│     → toma round-N-q.md                                       │
│     → agrega encabezado de contexto para el cliente           │
│     → genera sdlc/input/refinement/send/preguntas-ciclo-N-fecha.md │
│     → informa al usuario qué archivo enviar                   │
└────────────────────────────────┬──────────────────────────────┘
                              ↓
              ░░░ Envío manual al cliente ░░░
                              ↓
              ░░░ Cliente responde y devuelve el archivo ░░░
                              ↓
              ░░░ Usuario lo coloca en sdlc/input/refinement/inbox/ ░░░
                              ↓
┌──────────────────────────────────────────────────────────────┐
│  3. /refinement-receive                                       │
│     → lee inbox/                                              │
│     → detecta el ciclo por nombre/contenido/dedección          │
│     → valida que haya respuestas (no solo placeholders)       │
│     → copia a sdlc/input/refinement/rounds/round-N-a.md            │
│     → mueve el original a inbox/processed/                    │
│     → informa cuántas preguntas tienen respuesta              │
└────────────────────────────────┬──────────────────────────────┘
                              ↓
              ░░░ Siguiente ciclo: "ciclo de refinamiento N+1" ░░░

Para cerrar el refinamiento:

"cerrar refinamiento"

(o automáticamente cuando no quedan AMBs 🔴 sin respuesta válida)

Genera sdlc/input/functional-spec-enriched.md (la spec final enriquecida) + REFINEMENT-COMPLETE.md con métricas. El Pipeline 1 usará automáticamente la spec enriquecida si existe.

Respuestas inválidas, vagas o ausentes:

• El orchestrator las documenta como AMB-PENDIENTE con supuesto default
• Se repreguntan en el ciclo siguiente si eran 🔴 críticas
• Nunca se inventan respuestas — la pausa humana es obligatoria

Archivos de entrada:

• sdlc/input/functional-spec.md o sdlc/input/functional-spec-enriched.md (requerido — este último si viene del pipeline GX)
• sdlc/input/refinement/analyst-input.md (opcional — contexto adicional del analista, leído en cada ciclo)
• sdlc/input/refinement/inbox/*.md (archivo respondido por el cliente, procesado por /refinement-receive)

Archivos de salida:

sdlc/input/
└── refinement/
    ├── rounds/
    │   ├── round-1-q.md                      ← preguntas del ciclo 1
    │   ├── round-1-a.md                      ← respuestas del cliente (copiadas por /refinement-receive)
    │   ├── round-2-q.md
    │   ├── round-2-a.md
    │   └── ...
    ├── send/
    │   └── preguntas-ciclo-N-YYYY-MM-DD.md   ← archivo listo para mandar al cliente
    ├── inbox/
    │   └── processed/                         ← archivos ya procesados (historial)
    ├── spec-enriched.md                       ← spec acumulativa con refinamientos marcados
    ├── refinement-log.md                      ← registro oficial de decisiones por ciclo
    └── REFINEMENT-COMPLETE.md                 ← reporte final (generado en el cierre)
sdlc/input/functional-spec-enriched.md              ← entregable final → Pipeline 1

Slash commands del pipeline de refinement:

| Command | Cuándo usarlo | |---------|---------------| | /refinement-send | Después de que el orchestrator generó las preguntas de un ciclo, para preparar el archivo que se le envía al cliente (con encabezado de contexto y sin modificar el original) | | /refinement-receive | Después de recibir el archivo respondido por el cliente y colocarlo en sdlc/input/refinement/inbox/. Detecta el ciclo automáticamente, valida respuestas y lo deja en rounds/round-N-a.md listo para el siguiente ciclo |

Pipeline 1 — Analysis

Para qué sirve: Transformar una especificación funcional en todos los artefactos técnicos necesarios para comenzar la implementación: análisis de dominio, user stories con criterios de aceptación, arquitectura, modelo de datos, diseño de API, estimación por sesiones y roadmap.

Cuándo usarlo: Una sola vez, al inicio del proyecto. Si el proyecto evoluciona significativamente, se puede re-ejecutar parcialmente.

Cómo arrancarlo:

"procesar spec funcional"

o alternativamente: "analizar el documento en sdlc/input/" / "ejecutar el pipeline completo"

Cómo funciona:

El orquestador coordina 6 pasos en secuencia, con verificación obligatoria de cada output antes de continuar:

| Paso | Agente | Output | |------|--------|--------| | 1 | Analyst-Specifier | sdlc/output/01-analysis.md + sdlc/output/02-specification.md — dominios, actores, casos de uso, reglas, user stories con criterios de aceptación | | 2 (paralelo) | System Designer | sdlc/output/03-design/architecture.md + sdlc/output/03-design/data-model.md — ADRs, stack, patrones, ER, tablas, índices | | 2 (paralelo) | API Designer | sdlc/output/03-design/api-design.md — endpoints, contratos, errores, flujos | | 3 | Estimator | sdlc/output/04-sessions.md + sdlc/output/04-estimation.md — sesiones agrupadas en batches, complejidad 1-8 | | — | Orquestador | Validación estructural con validate-artifacts.sh (bash, 0 tokens) entre cada paso | | 4 | Planner (haiku) | sdlc/output/05-planning.md — roadmap por batches, MVP, ciclos de review | | 5 | Orquestador (directo) | sdlc/output/SUMMARY.md — resumen ejecutivo con métricas y próximos pasos |

El Paso 2 es el único paralelo — los dos agentes de diseño trabajan simultáneamente.

Archivos de entrada:

• sdlc/input/functional-spec.md o sdlc/input/functional-spec-enriched.md (si se corrió Refinement)

Archivos de salida:

sdlc/output/
├── 01-analysis.md
├── 02-specification.md
├── 03-design/
│   ├── architecture.md
│   ├── data-model.md
│   └── api-design.md
├── 04-sessions.md
├── 04-estimation.md
├── 05-planning.md
└── SUMMARY.md

Después de este pipeline: Antes de arrancar la implementación, revisar sdlc/output/SUMMARY.md y sdlc/output/INTEGRITY-ISSUES.md (si existe). Si hay problemas de integridad → resolverlos antes de continuar.

Pipeline 2 — Implementation

Para qué sirve: Implementar el proyecto batch por batch. Cada batch agrupa 2-4 sesiones del mismo módulo y produce un único PR en GitHub. El orquestador determina automáticamente qué batch ejecutar respetando dependencias.

Cuándo usarlo: Después de completar el Pipeline 1 y revisar el SUMMARY.md.

Cómo arrancarlo (primera vez):

"implementar siguiente sesión"

o con el slash command: /next-session

El orquestador verifica que CLAUDE.md existe y está actualizado. Si es la primera sesión, lo genera desde los artefactos de diseño y pausa para confirmación. Después de confirmar:

"implementar siguiente sesión"

Cómo funciona:

Cada invocación ejecuta exactamente un batch (2-4 sesiones) y luego se detiene hasta que el Tech Lead mergea el PR y vuelve a invocar.

Flujo interno de cada batch:

1. Sincroniza PRs mergeados con GitHub (actualiza sdlc/status-board.md) + captura lessons de batches mergeados
2. Selecciona el próximo batch con dependencias completadas
3. Informa al Tech Lead (módulo, sesiones incluidas, complejidad acumulada)
4. Marca TODAS las sesiones del batch como 🔄 En curso
5. Delega al session-executor, que ejecuta cada sesión en orden:
   • Lee contexto 1× por batch (CLAUDE.md, design docs, lessons relevantes, assumptions activas)
   • Crea la branch batch/B-XX-modulo-kebab
   • Para cada sesión: implementa → tests unitarios → validación post-sesión
   • Test de regresión general al completar todas las sesiones
   • Auto-Reflect: 30+ checks en 6 categorías antes de commitear
   • Commit feat(B-XX): + push + PR via MCP GitHub
6. Reporta al Tech Lead con el PR (incluye reflect results y preguntas)

State tracking: Cada batch mantiene un archivo sdlc/state/B-XX-state.json persistente. Si el contexto se pierde por crash o timeout, el executor retoma desde el último paso completado.

Paralelismo con worktrees: Si hay batches independientes, el sprint-orchestrator puede crear worktrees aislados para ejecutar hasta 3 batches simultáneamente en terminales separadas de Claude Code.

Comandos disponibles:

| Comando | Qué hace | |---------|----------| | /next-session | Slash command equivalente a "implementar siguiente sesión" | | "estado de implementación" | Muestra resumen: completados, en review, pendientes, bloqueados | | "reintentar S-XXX" | Re-ejecuta un batch pausado | | "iterar S-XXX" | Pasa feedback del PR al executor para corregir | | "registrar PR B-XX #42" | Registra manualmente un PR | | "sprint batches" | Propone batches paralelos, crea worktrees | | "merge sprint" | Merge secuencial de batches completados | | "canary deploy" | Deploy canario con smoke tests (requiere config de deploy) | | "analizar codebase" | Auditoría de salud en 4 dimensiones |

Archivos de entrada:

• sdlc/output/04-sessions.md — plan de sesiones con batches
• sdlc/output/03-design/ — artefactos de diseño
• CLAUDE.md — contexto del proyecto
• sdlc/status-board.md — estado actual
• sdlc/knowledge/lessons/ — lecciones de batches previos

Archivos de salida:

• Código del proyecto en el repo
• CLAUDE.md actualizado
• sdlc/status-board.md actualizado
• sdlc/state/B-XX-state.json — state tracking por batch
• sdlc/knowledge/lessons/ — lecciones capturadas
• sdlc/knowledge/assumptions/ — supuestos documentados
• PRs en GitHub (batch/B-XX-*)

Después de cada PR: El Tech Lead revisa, aprueba y mergea. Luego invoca nuevamente "implementar siguiente sesión".

Pipeline 3 — QA

Para qué sirve: Detectar bugs en el sistema implementado mediante 8 capas de testing independientes, diagnosticar causas raíz, generar fixes y verificarlos post-merge.

Cuándo usarlo: Después de completar un bloque de sesiones de implementación, o antes de un release.

Cómo arrancarlo:

"iniciar QA"

o si ya tenés bugs identificados: "hay bugs para fixear: [descripción]" (salta directo a diagnóstico)

Las 8 capas de detección:

| Capa | Qué detecta | Requiere | |------|-------------|----------| | A.0 Smoke | Servicios caídos, BD sin conexión, app no responde | Docker | | A.1 Integridad de datos | FKs huérfanas, NULLs inválidos, seeders faltantes | Docker + BD | | A.2 Playwright | Bugs visuales, errores JS, UX roto | App corriendo | | A.3 Integración | Contratos API↔BD, servicio↔repositorio | Docker | | A.4 E2E | Flujos completos de usuario | Docker + App | | A.5 Unitarios | Regresiones, cobertura < 70% | — | | A.6 Contrato de API | Respuestas reales vs api-design.md | App corriendo | | A.7 Manual | Bugs reportados directamente por el Tech Lead | — |

Si una capa no puede correr (ej: Docker no disponible) → se documenta y se continúa con la siguiente.

Severidades:

| Nivel | Cuándo | |-------|--------| | 🔴 Crítico | Crash, 5xx, datos incorrectos, flujo principal roto | | 🟡 Medio | Feature incorrecta pero tiene workaround, validación faltante | | 🟢 Bajo | Visual, texto incorrecto, UX menor |

Flujo completo:

1. Fase A — Detección: corre las 8 capas y escribe qa-report.md
2. Fase B — Diagnóstico: para cada bug identifica causa raíz (nunca genera fix sin causa identificada)
3. Fase C — Generación de fixes: agrupa bugs por causa raíz, escribe qa-sessions.md, pausa y espera confirmación
4. Fase D — Ejecución: al recibir "ejecutar QA fixes", crea branches fix/FIX-XXX-*, implementa, testea y abre PRs
5. Fase E — Verificación: al recibir "verificar QA", re-corre solo las capas afectadas por los fixes mergeados

Otros comandos:

| Comando | Qué hace | |---------|----------| | "ejecutar QA fixes críticos" | Solo los fixes 🔴 | | "estado de QA" | Muestra resumen de qa-report.md | | "verificar QA" | Re-corre capas afectadas post-merge |

Archivos de salida:

• qa-report.md — log maestro con todos los bugs y su estado
• qa-sessions.md — fixes agrupados por causa raíz
• PRs en GitHub (fix/FIX-XXX-*)

Pipeline 4 — Bug Reporter

Para qué sirve: Recibir un bug de cualquier fuente (producción, testing, un usuario, el session-executor), diagnosticar la causa raíz, implementar el fix con test de regresión y abrir el PR. Funciona en cualquier etapa del proyecto, no solo post-QA.

Cuándo usarlo: Cuando se identifica un bug concreto con descripción clara. No requiere correr el pipeline de QA completo.

Cómo arrancarlo:

"reportar bug: [descripción del comportamiento incorrecto]"

Ejemplos:

"reportar bug: el endpoint /users devuelve 500 cuando el email tiene mayúsculas"
"encontré un bug en S-012: el cálculo de descuento ignora el código promocional"
"comportamiento inesperado: la sesión no expira después de 30 minutos de inactividad"
"regresión en checkout: el PR de S-018 rompió el flujo de pago con tarjeta"

Tipos de bug:

| Tipo | Descripción | Ejemplo | |------|-------------|---------| | 🔴 Regresión | Funcionaba y dejó de funcionar | PR de S-XXX rompió S-YYY | | 🟠 Contrato roto | Dos sesiones no encajan | Serializer devuelve id, frontend espera userId | | 🟡 Sin spec | Comportamiento no definido | ¿Qué pasa si el campo es vacío? | | 🟢 Bug funcional | Feature implementada incorrectamente | Cálculo usa fórmula errónea | | 🔵 Edge case | Caso no contemplado | Input de 0 no validado |

Flujo:

1. Fase A — Registra el bug en BD via API (ID auto-generado: BUG-001, BUG-002...) y lo clasifica
2. Fase B — Diagnostica la causa raíz (usa los mismos checklist que el QA Orchestrator)
   • Si el tipo es 🟡 Sin spec → pausa y pregunta al Tech Lead qué debería hacer
3. Fase C — Verifica si el fix toca módulos críticos (definidos en pipeline-config.md)
   • Si toca módulo crítico → pausa para confirmación explícita
   • Si no → implementa directo sin pausa
   • Crea branch fix/BUG-XXX-descripcion-kebab, implementa, agrega test de regresión, abre PR
4. Fase D — Verificación post-merge (activar con "verificar BUG-XXX")
   • Confirma que el PR está mergeado
   • Corre tests relevantes
   • Si detecta regresión → crea nuevo BUG automáticamente

Trazabilidad: Todo bug queda registrado en BD con causa raíz, archivos afectados, PR número y URL.

Pipeline 5 — Change Request

Para qué sirve: Gestionar cambios sobre features ya implementadas y funcionando correctamente. A diferencia del bug-reporter (que arregla algo roto), este pipeline cambia algo que funciona pero necesita comportarse diferente.

Cuándo usarlo: Cuando el Tech Lead quiere cambiar una regla de negocio, agregar un campo a una entidad existente, modificar el comportamiento de un endpoint, o refactorizar un módulo.

Cómo arrancarlo:

"quiero cambiar el comportamiento de [feature/endpoint/entidad]"
"necesito modificar [componente]"
"agregar campo [campo] a [entidad]"
"refactorizar [módulo] para [objetivo]"

Tipos de change request:

| Tipo | Impacto típico | |------|----------------| | 🔵 Lógica de negocio | Servicios + tests | | 🟣 Modelo de datos | Migración de BD + repositorio + serializer + tests | | 🟠 Contrato de API | Serializer + tests + todos los consumidores del endpoint | | ⚪ Refactor | Sin impacto externo, alto impacto interno |

Flujo (siempre hay pausa para confirmación):

1. Fase A — Registra el CR en BD (ID: CR-001, CR-002...) y lo clasifica
2. Fase B — Analiza el impacto: qué sesiones afecta, qué archivos cambian, si necesita migración de BD, qué contratos se rompen, cuántas sesiones de cambio requiere
3. Fase C — PAUSA OBLIGATORIA: presenta el análisis completo al Tech Lead y espera confirmación

   → "ejecutar CR-XXX" para proceder
   → "cancelar CR-XXX" para descartar
   → "modificar CR-XXX: [ajuste]" para ajustar el alcance

4. Fase D — Implementa las sesiones de cambio (branch change/CR-XXX-*), actualiza tests existentes, agrega tests nuevos, aplica migración si hay, abre PR
5. Fase E — Verificación post-merge (activar con "verificar CR-XXX")

Diferencia clave con Bug Reporter: El change request siempre pausa antes de ejecutar. El bug reporter solo pausa en casos específicos (sin spec o módulo crítico).

Pipeline 6 — Feedback Loop

Para qué sirve: Procesar feedback del usuario final o del sistema en producción y traducirlo en mejoras concretas y trazables. Es el mecanismo por el cual el sistema aprende de su propio comportamiento.

Cuándo usarlo: Cuando llega feedback de producción, cuando se observa comportamiento subóptimo del sistema, o cuando hay evidencia de que algún parámetro o configuración necesita ajustarse.

Cómo arrancarlo:

"feedback: [descripción de lo observado]"
"el sistema hace [X] pero debería hacer [Y]"
"quiero ajustar [parámetro] del sistema"
"nueva regla de negocio: [descripción]"

Tipos de feedback y qué hace con cada uno:

| Tipo | Cuándo | Qué hace | |------|--------|----------| | 🎯 Ajuste de parámetros | Un parámetro configurable tiene evidencia de que debería cambiar | Consulta métricas de efectividad, propone ajuste con evidencia, pausa para aprobación, aplica via PR | | 📝 Nueva regla de negocio | Se detecta en producción un comportamiento que debería aplicarse pero no está definido | Documenta la regla, genera CR y lo delega al Pipeline 5 | | 📖 Nueva user story | Feature nueva derivada de comportamiento observado | Redacta la US en formato Gherkin, presenta al Tech Lead, deriva al pipeline de análisis | | 🔧 Ajuste de configuración IA | Un prompt o config de IA no genera el comportamiento esperado | Propone modificación con evidencia, pausa para aprobación, versiona el cambio | | 🐛 Bug de lógica | El sistema hace algo incorrecto (no solo subóptimo) | Lo delega al Pipeline 4 (Bug Reporter) |

Todas las derivaciones pasan por el Tech Lead. El pipeline genera el trigger pre-armado y espera que el humano lo confirme:

→ "derivar FB-XXX a bug-reporter" para delegación automática
→ "reportar bug: [descripción] (origen: FB-XXX)" para invocación manual

Trazabilidad completa: Cada feedback tiene su ID (FB-001...), estado en BD, y si deriva a bug o CR, queda registrado el vínculo entre ambos.

6. Slash commands y skills

Slash commands

Los slash commands están en .claude/commands/ y se invocan con /nombre en la conversación. Ver /help o .claude/QUICK-REFERENCE.md para la guía completa con flujos de trabajo.

Análisis

| Command | Descripción | |---------|-------------| | /refinar | Inicia refinamiento iterativo de ambigüedades con el cliente | | /analizar-spec | Ejecuta el pipeline completo de análisis (7 artefactos) | | /validar [artefacto] | Valida artefactos del pipeline (all, analysis, specification, sessions, etc.) |

Implementación

| Command | Descripción | |---------|-------------| | /implementar | Selecciona el próximo batch, ejecuta todas sus sesiones, abre PR | | /estado | Muestra progreso de implementación sin ejecutar nada | | /iterar S-XXX | Pasa feedback del PR al executor para corregir | | /reintentar S-XXX | Re-ejecuta después de resolver un bloqueo manual | | /registrar-pr B-XX #N | Registra un PR abierto manualmente | | /next-session | Alias de /implementar (acepta status, retry S-XXX, S-XXX) |

Paralelismo

| Command | Descripción | |---------|-------------| | /sprint | Analiza dependencias, propone batches paralelos, crea worktrees | | /sprint-estado | Muestra progreso de todos los batches del sprint | | /sprint-merge | Mergea secuencialmente los batches completados | | /sprint-cancelar | Cancela sprint y elimina worktrees |

QA y seguridad

| Command | Descripción | |---------|-------------| | /qa | QA completo (8 capas). Acepta: fixes, fixes criticos, verificar, estado | | /security | Auditoría de seguridad (OWASP Top 10). Acepta: static, deps |

Deploy y auditoría

| Command | Descripción | |---------|-------------| | /deploy | Deploy canario a staging + smoke tests. Acepta: promover, rollback | | /auditar [módulo] | Auditoría de codebase en 4 dimensiones (quality, conventions, security, testing) |

Post-producción

| Command | Descripción | |---------|-------------| | /bug [descripción] | Diagnostica, fixea y abre PR | | /cambio [descripción] | Analiza impacto, pausa para confirmación, ejecuta cambio | | /feedback [descripción] | Clasifica feedback de producción y deriva |

Migración GX

| Command | Descripción | |---------|-------------| | /run-pipeline | Pipeline completo de migración GX (6 stages) | | /check-gates | Verifica estado de gates G1-G5 | | /query-spec | Consulta spec por entidad, proceso, módulo o regla | | /resolve-ambiguity | Registra resolución de ambigüedad |

Documentación de usuario

| Command | Descripción | |---------|-------------| | /manual | Regenerar manual de usuario completo. Acepta: [módulo] para regenerar sólo una sección; verificar para chequear cobertura |

Utilidades

| Command | Descripción | |---------|-------------| | /preflight | Valida entorno (MCP servers, git, estructura, inputs, pipeline state) | | /sync | Sincroniza pipeline desde el upstream | | /metricas | Reporte de tokens, costos y duración. Acepta: batch B-XX, presupuesto, exportar | | /help | Muestra Quick Reference Card completa |

Skills

Los skills están en .claude/skills/ y proveen conocimiento especializado que los agentes consumen automáticamente.

| Skill | Descripción | Usado por | |-------|-------------|-----------| | gx-xml-parser | CLI Python (parse_gx_kb.py) que parsea exports XML GeneXus (Classic 2.x y Evolution 3+) y produce JSONL deterministas. Contiene los adapters por formato, el schema de los JSONL y las heurísticas de disambiguation | A1 (GX Inventory Analyzer) | | gx-naming-conventions | Reglas de naming que GeneXus aplica al generar tablas/columnas desde Transactions y atributos, algoritmo de matching | A4 (Legacy Reconciler) | | pipeline-gate-validator | Criterios exactos y comandos de verificación para cada gate G1-G5 | Orquestador, /check-gates |

7. Flujo completo de un proyecto

DÍA 1 — Setup
  1. Clonar pipelines → crear repo del proyecto
  2. Completar pipeline-config.md
  3. Agregar functional-spec.md (o inputs GX si es migración)
  4. /preflight → verificar que todo está configurado

SI ES MIGRACIÓN GX — Reverse engineering
  Agregar uno o más XMLs en sdlc/input/gx/ (ej: web.xml, desktop.xml, mobile.xml)
  pip install -r .claude/skills/gx-xml-parser/requirements.txt    (una vez)
  /run-pipeline
  → Stage 1: CLI Python parsea cada XML → JSONL por KB
  → Stage 2: reconstruye modelo físico desde los JSONL (sin DB viva)
  → Stages 3-6: dominio, reconciliación, ambigüedades, spec consolidado
  → resolver ambigüedades con /resolve-ambiguity
  → verificar gates con /check-gates
  → output: functional-spec-enriched.md

DÍA 1/2 — Refinamiento (opcional)
  /refinar
  → completar respuestas en answers-round-1.md
  "ciclo de refinamiento 2"
  → ... (hasta cerrar ambigüedades críticas)
  "cerrar refinamiento"

DÍA 2 — Análisis
  /analizar-spec
  → esperar ~2 horas (gates automáticos con /validar entre cada paso)
  → revisar sdlc/output/SUMMARY.md

DÍA 3 en adelante — Implementación
  /implementar                → ejecuta batch B-XX, abre PR
  → revisar el PR en GitHub
  → mergear si está conforme
  /implementar                → siguiente batch
  → ... (repetir por cada batch)

  Si hay batches independientes:
  /sprint                     → propone paralelo, crea worktrees
  → abrir 2+ terminales de Claude Code, una por worktree
  /sprint-merge               → mergea al terminar

Cuando el bloque de batches está listo — QA
  /qa                         → 8 capas de detección
  → revisar qa-report.md
  /qa fixes                   → implementa fixes
  → mergear fixes
  /qa verificar               → re-corre tests post-merge

Deploy (requiere config)
  /deploy                     → staging + smoke tests
  /deploy promover            → a producción

POST-PRODUCCIÓN (en cualquier momento)
  Bug encontrado     → /bug [descripción]
  Cambio requerido   → /cambio [descripción]
  Feedback de uso    → /feedback [observación]
  Health check       → /auditar

8. Estructura de carpetas del repo

pipelines/
│
├── CLAUDE.md                    ← descripción del framework (este repo)
├── CLAUDE.local.md              ← reglas locales (MCPs, push/PR) — gitignoreado
├── README.md                    ← este archivo
│
├── .claude/                     ← agentes, commands y skills (NO modificar en proyectos fork)
│   ├── agents/
│   │   ├── analisis/
│   │   │   ├── orchestrator.md          ← Pipeline 1: punto de entrada
│   │   │   ├── analyst-specifier.md     ← fusión de analyst + specifier
│   │   │   ├── system-designer.md       ← fusión de architect + data-modeler
│   │   │   ├── api-designer.md
│   │   │   ├── estimator.md
│   │   │   ├── planner.md               ← modelo haiku (template filling)
│   │   │   └── templates/
│   │   ├── migration/
│   │   │   ├── orchestrator.md      ← Pipeline GX: punto de entrada
│   │   │   ├── gx-inventory-analyzer.md
│   │   │   ├── db-legacy-modeler.md
│   │   │   ├── functional-domain-reconstructor.md
│   │   │   ├── legacy-reconciler.md
│   │   │   ├── ambiguity-risk-refiner.md
│   │   │   └── functional-spec-consolidator.md
│   │   ├── refinement/
│   │   │   └── refinement-orchestrator.md  ← Pipeline 0: punto de entrada
│   │   ├── implementation/
│   │   │   ├── implementation-orchestrator.md  ← Pipeline 2: punto de entrada
│   │   │   ├── session-executor.md
│   │   │   ├── sprint-orchestrator.md          ← paralelismo con worktrees
│   │   │   ├── canary.md                       ← deploy canario + smoke tests
│   │   │   ├── claude-md-generator.md
│   │   │   ├── reflect.md                      ← auto-revisión pre-PR (30+ checks)
│   │   │   ├── validate-session.md             ← validación entre sesiones
│   │   │   └── templates/
│   │   ├── qa-orchestrating/
│   │   │   ├── SKILL.md             ← Pipeline 3: punto de entrada
│   │   │   ├── diagnosis.md
│   │   │   └── layers/              ← una capa por archivo
│   │   ├── bug-reporter/
│   │   │   ├── SKILL.md             ← Pipeline 4: punto de entrada
│   │   │   └── templates/
│   │   ├── change-request/
│   │   │   ├── SKILL.md             ← Pipeline 5: punto de entrada
│   │   │   └── templates/
│   │   ├── feedback-loop/
│   │   │   ├── SKILL.md             ← Pipeline 6: punto de entrada
│   │   │   └── templates/
│   │   └── shared/
│   │       ├── pipeline-config.md   ← ⚙️ ÚNICO ARCHIVO A COMPLETAR POR PROYECTO
│   │       ├── ETHOS.md             ← 5 principios inyectados en todos los agentes
│   │       ├── validate-artifacts.sh ← validación estructural bash (0 tokens)
│   │       ├── analyze.md           ← auditoría de codebase en 4 dimensiones
│   │       ├── delegation-protocol.md
│   │       ├── db-helpers.md
│   │       └── preflight-checker.md ← validador de entorno invocado por /preflight
│   ├── commands/
│   │   ├── run-pipeline.md          ← /run-pipeline
│   │   ├── check-gates.md           ← /check-gates
│   │   ├── query-spec.md            ← /query-spec
│   │   ├── resolve-ambiguity.md     ← /resolve-ambiguity
│   │   ├── next-session.md          ← /next-session
│   │   ├── preflight.md             ← /preflight
│   │   ├── refinement-send.md       ← /refinement-send
│   │   └── refinement-receive.md    ← /refinement-receive
│   └── skills/
│       ├── gx-xml-parser/
│       │   ├── SKILL.md             ← documentación de la CLI
│       │   ├── parse_gx_kb.py       ← CLI entry point
│       │   ├── requirements.txt     ← lxml>=4.9
│       │   └── parsers/
│       │       ├── schema.py        ← dataclasses (GXObject, GXTable, etc.)
│       │       ├── common.py        ← regex GX + extractores
│       │       ├── detect.py        ← detección auto de formato por <MajorVersion>
│       │       ├── classic_2x.py    ← adapter Classic 2.x (GX 8.x/9.x)
│       │       └── evolution_3.py   ← adapter Evolution 3+ con GUID_TYPE_MAP
│       ├── gx-naming-conventions/SKILL.md
│       └── pipeline-gate-validator/SKILL.md
│
└── sdlc/                        ← artefactos del pipeline (único directorio de trabajo)
    ├── input/                   ← entradas del proyecto
    │   ├── functional-spec.md   ← spec del proyecto (agregar manualmente)
    │   └── gx/                  ← cualquier cantidad de *.xml (si es migración GX)
    ├── output/                  ← artefactos generados por el pipeline (stages, design)
    ├── state/                   ← state files por batch (B-XX-state.json)
    │   └── archive/             ← state files de batches completados
    ├── status-board.md          ← tablero humano de sesiones
    ├── templates/               ← templates del pipeline (spec funcional, etc.)
    ├── knowledge/
    │   ├── lessons/             ← lecciones capturadas automáticamente
    │   └── assumptions/         ← supuestos documentados
    ├── metrics/                 ← log de costos y tokens
    ├── reports/                 ← reportes de auditoría y métricas
    └── context/
        └── smoke-tests.md       ← definición de smoke tests para canary

Otros archivos que genera el pipeline en el fork del proyecto:

qa-report.md                     ← generado por Pipeline 3 (raíz — temporal)
.worktrees/                      ← worktrees temporales de sprint (gitignoreado)

9. Capacidades del pipeline

ETHOS — Principios invariables

5 principios inyectados en todos los agentes via .claude/agents/shared/ETHOS.md:

1. Spec First, Code Second — Nunca implementar sin spec validada
2. Knowledge Compounds — Cada batch deja el proyecto más inteligente
3. Verify, Don't Trust — El output de un LLM es un borrador, no un entregable
4. Batch Efficiency — El contexto entre sesiones es el recurso más caro
5. Human at the Edges — El humano revisa batches, no sesiones

Batching

La unidad de trabajo es el batch (2-4 sesiones del mismo módulo), no la sesión individual. Cada batch produce un único PR y un único ciclo de review humano. Esto reduce PRs de ~62 a ~16 y elimina ~370K tokens de lecturas redundantes de contexto.

State Tracking

Cada batch mantiene un archivo sdlc/state/B-XX-state.json que trackea: paso actual, sesiones completadas, blockers, y resultados del reflect. Si el contexto se pierde por compactación, crash o timeout, el executor retoma desde el último paso completado.

Validation Gates

Capa determinista (bash, 0 tokens): validate-artifacts.sh valida estructura, conteos y campos obligatorios de los 7 artefactos del pipeline de análisis. Se ejecuta después de cada paso.

Capa evaluativa (LLM): validate-session.md verifica archivos, tests, imports, TODOs y consistencia entre cada sesión dentro de un batch.

Auto-Reflect

Antes de commitear, el executor ejecuta 30+ checks en 6 categorías (correctness, conventions, architecture, testing, completeness, shortcuts). Los hallazgos van al PR body y al state file. Critical/Major se fixean antes del commit; shortcuts se documentan.

Knowledge Persistence

Lessons (sdlc/knowledge/lessons/): capturadas automáticamente cuando un batch se mergea con feedback del Tech Lead. Consultadas antes de implementar cada batch para no repetir errores.

Assumptions (sdlc/knowledge/assumptions/): supuestos documentados con status (unvalidated/validated/invalidated) y plan de validación.

Paralelismo con Worktrees

El sprint-orchestrator analiza dependencias entre batches, propone hasta 3 batches independientes para ejecución paralela, crea worktrees aislados, y gestiona el merge secuencial. El Tech Lead lanza una sesión de Claude Code por worktree.

Canary Deploy

Deploy seguro: staging primero → smoke tests → promoción a producción con confirmación humana. Rollback automático ante fallo. Requiere configurar la sección "Deploy" de pipeline-config.md.

Codebase Audit

Auditoría en 4 dimensiones (code quality, conventions, security, testing) con scorecard A-F, issues priorizados y recomendaciones accionables. Se ejecuta bajo demanda con "analizar codebase".

10. Before / After

| Dimensión | Antes | Después | Mejora | |-----------|-------|---------|--------| | Agentes totales | 18 | 25 | +7 (sprint-orch, canary, analyze, reflect, validate, etc.) | | Modelo más caro | opus (6 agentes) | 0 opus | Eliminado | | Agentes en haiku | 0 | 3 (planner, claude-md-gen, preflight) | Reducción de costo | | Unidad de trabajo | Sesión individual | Batch (2-4 sesiones) | 1 PR por batch vs 1 PR por sesión | | Lecturas de contexto | 1 por sesión (~62) | 1 por batch (~16) | ~370K tokens menos | | State tracking | No | B-XX-state.json persistente | Resiliente a interrupciones | | Validación entre fases | Solo existencia de archivo | Bash (estructura) + LLM (calidad) | Detección temprana | | Auto-revisión pre-PR | No | 30+ checks, 6 categorías | Menos rework en code review | | Knowledge | CLAUDE.md manual | Lessons + Assumptions automáticos | Mejora acumulativa | | Paralelismo | Secuencial obligatorio | Worktrees (hasta 3 batches) | ~40% menos tiempo | | Deploy | Manual | Canary + smoke tests | Zero-downtime | | Auditoría de código | No | 4 dimensiones, scorecard A-F | Deuda técnica visible | | Principios compartidos | No | ETHOS.md en 18 agentes | Consistencia | | Comandos documentados | ~5 | 17+ | Quick Reference completa |

11. Cómo contribuir mejoras al upstream

Si mientras trabajás en un proyecto encontrás una mejora al framework (un paso que falta en un agente, una mejor forma de diagnosticar, un nuevo tipo de feedback), el flujo es:

Regla: Primero la mejora va al upstream (hornero), después se trae al proyecto.

# 1. Ir al repo del framework
cd ~/proyectos/hornero

# 2. Hacer el cambio en .claude/ o sdlc/templates/
# editar .claude/agents/[pipeline]/SKILL.md

# 3. Commitear y pushear al upstream
git add .claude/
git commit -m "feat: [descripción de la mejora genérica]"
git push origin main

# 4. Traer la mejora al proyecto
cd ~/proyectos/mi-proyecto
git fetch upstream
git merge upstream/main -- .claude/ sdlc/templates/
git push origin main

Por qué este orden: Si hacés el cambio directo en el proyecto, el merge futuro va a generar conflictos. Si lo hacés primero en el upstream, el git merge -- .claude/ nunca tiene conflictos porque .claude/ en el proyecto nunca fue modificado.

Qué va al upstream:

• Mejoras a la lógica de los agentes (.claude/agents/**)
• Nuevos commands (.claude/commands/**)
• Nuevos skills (.claude/skills/**)
• Nuevas capas de QA
• Nuevos tipos de bug, CR o feedback
• Mejoras al template de pipeline-config.md

Qué NUNCA va al upstream:

• .claude/agents/shared/pipeline-config.md completado con datos del proyecto
• CLAUDE.local.md (reglas específicas del entorno local, gitignoreado)
• sdlc/input/, sdlc/output/, sdlc/status-board.md
• El CLAUDE.md del proyecto (reemplaza al del framework)

Referencia rápida de comandos

Ver /help o .claude/QUICK-REFERENCE.md para la guía completa con flujos de trabajo.

| Pipeline | Slash command | Comandos adicionales | |----------|--------------|---------------------| | GX — Migration | /run-pipeline | /check-gates, /query-spec, /resolve-ambiguity | | 0 — Refinement | /refinar | "ciclo de refinamiento N", "cerrar refinamiento" | | 1 — Analysis | /analizar-spec | /validar (gates automáticos) | | 2 — Implementation | /implementar | /estado, /iterar, /reintentar, /registrar-pr | | 2 — Paralelismo | /sprint | /sprint-estado, /sprint-merge, /sprint-cancelar | | 2 — Deploy | /deploy | /deploy promover, /deploy rollback | | 2 — Audit | /auditar | /auditar [módulo], /auditar seguridad | | 3 — QA | /qa | /qa fixes, /qa verificar, /qa estado | | 4 — Bug Reporter | /bug [desc] | — | | 5 — Change Request | /cambio [desc] | — | | 6 — Feedback Loop | /feedback [desc] | — | | Utilidades | /preflight | /sync, /help |