Workflow AI-first

Este es el pipeline completo de desarrollo con AI Framework: de idea a código en producción en 5 fases, cada una con skills dedicados y quality gates automáticos.

Antes de empezar: lee Inicio rápido para instalar el framework.

El Pipeline

💡 1. IDEA — brainstorming → plan mode

Convierte ideas vagas en diseños completos. Claude activa brainstorming automáticamente: pregunta una cosa a la vez, propone 2-3 enfoques con trade-offs, y cristaliza diseño + escenarios en plan file nativo. Ver detalle →

📋 2. PLAN — ralph-orchestrator · discovery → planning → tasks

Entry point único para desarrollo autónomo. Ralph ejecuta 8 pasos (0-7): elige modo (Interactive/Autonomous), discovery, planning, genera .code-task.md files, configura gates, y presenta plan completo en plan mode para tu aprobación antes de ejecutar. Ver detalle →

⚙️ 3. IMPLEMENT — SCENARIO → SATISFY → REFACTOR

La metodología central. Cada feature se define primero como escenario observable, se implementa hasta que el behavior converge (satisfaction, no boolean), y se refactoriza preservando behavior. Ver detalle →

🔍 4. QUALITY — 6 agents automáticos + verification gate

Seis agentes se activan solos según contexto: code-reviewer, security-reviewer, edge-case-detector, code-simplifier, performance-engineer, systematic-debugger. Verification gate de 6 pasos antes de declarar cualquier tarea completa. Ver detalle →

🚀 5. DELIVER — commit → pull-request → branch-cleanup

Commits semánticos con agrupación automática por tipo de archivo. Pull request con quality gate integrado (code review + security review en paralelo). Post-merge cleanup automático. Ver detalle →

Cada fase tiene un skill dedicado. Claude los activa automáticamente o puedes invocarlos tú.

Fase 1: Idea

Convierte ideas vagas en diseños completos mediante diálogo.

"Necesito sistema de notificaciones push"

Claude activa brainstorming automáticamente:

Examina el proyecto, pregunta una cosa a la vez
Propone 2-3 enfoques con trade-offs
Diseña en secciones de 200-300 palabras, valida cada una
Cristaliza diseño + escenarios en plan file nativo (plan mode)

Después de aprobar el plan

Según el tamaño de la tarea, continúa con:

Tarea pequeña → Implementa directamente (ver Patrones por tamaño)
Tarea mediana/grande → ralph-orchestrator para planificación + ejecución autónoma

Fase 2: Plan

Ralph Orchestrator recomendado

Entry point único para desarrollo autónomo. Una invocación orquesta todo el pipeline.

"Implementa el sistema de notificaciones del design doc"

Ralph ejecuta 8 pasos (0-7) en secuencia:

Paso	Qué hace	Output
0	Elige modo: Interactive o Autonomous	—
1	Valida prerrequisitos	—
2	Discovery (nuevo) o Reverse (existente)	`discovery.md`
3	Planning — diseño detallado	`detailed-design.md`
4	Task generation — todas las tareas upfront	`.code-task.md` files
5	Genera `AGENTS.md` para workers	`AGENTS.md`
6	Configura ejecución (quality gates)	`.ralph/config.sh`
7	Plan mode + aprobación + ejecución autónoma	Agent Teams

Aprobación obligatoria (Paso 7)

Ralph nunca ejecuta código sin tu aprobación. Antes de lanzar Agent Teams, presenta un plan completo en plan mode con resumen de planificación, estrategia de ejecución y configuración. Nada se ejecuta sin tu OK.

¿Qué son los modos?

Interactive — Ralph pregunta y espera confirmación en cada decisión. Para cuando quieres control granular.

Autonomous — Ralph toma decisiones solo, documenta assumptions y continúa sin bloquear. Para desarrollo overnight/AFK.

En ambos modos, la aprobación en plan mode (paso 7) es obligatoria.

SOP Pipeline manual

Si prefieres control paso a paso en lugar de Ralph, puedes invocar cada skill del pipeline individualmente:

1. Discovery2. Planning3. Tasks4. Implement

bash

"Explora constraints y riesgos del sistema de notificaciones"
# → sop-discovery → discovery.md

bash

"Diseña la solución basándote en el discovery"
# → sop-planning → detailed-design.md + plan.md

bash

"Genera las tareas del plan"
# → sop-task-generator → .code-task.md files

bash

"Implementa la primera tarea"
# → sop-code-assist → código + tests + commit

¿Cuándo usar pipeline manual vs Ralph?

Ralph — Features completas, desarrollo overnight, cuando quieres que el framework maneje todo.

Pipeline manual — Cuando quieres iterar en una fase específica (ej: refinar el planning sin regenerar discovery), o para tareas donde solo necesitas una parte del pipeline.

Fase 3: Implement

Scenario-Driven Development metodología central

Todo código se escribe para satisfacer escenarios, nunca al revés.

Ley de hierro

NO se escribe código de producción sin un escenario definido primero. Los escenarios definen el comportamiento esperado; el código existe para satisfacerlos.

El ciclo:

1. SCENARIO — Definir qué debe pasar (user story con valores concretos)

gherkin

Dado un usuario con plan "free"
Cuando intenta enviar más de 10 notificaciones/día
Entonces recibe error "Límite diario alcanzado" y el contador no incrementa // [!code highlight]

2. SATISFY — Escribir código hasta que el escenario converge

// ❌ Esto NO es convergencia
test('should limit notifications', () => { expect(true).toBe(true) }) 

// ✅ Esto SÍ es convergencia
// Ejecuté sendNotification() 11 veces → observé "Límite diario alcanzado"
// y counter.value === 10 (no incrementó)

Ejecutar → observar output → ajustar → repetir
"Converge" = el behavior observable satisface al usuario, no solo "pasa un test"

3. REFACTOR — Simplificar sin romper behavior

// Antes
if (count >= limit) {                     
  if (plan === 'free') {                  
    throw new Error('Límite alcanzado')   
  }                                       
}                                         

// Después
const planLimits = { free: 10, pro: 100 } 
if (count >= planLimits[plan]) {          
  throw new LimitExceededError(plan)      
}

Validar ANTES y DESPUÉS de cada cambio
Un cambio pequeño a la vez
Si algo rompe → undo inmediatamente

Enforcement automático invisible

Múltiples hooks operan en background durante toda implementación — no requieren configuración ni invocación manual:

Hook	Trigger	Qué hace
`sdd-test-guard`	PreToolUse (Edit\|Write)	Si los tests están fallando Y un edit reduce assertions o debilita precisión (assertEqual→assertTrue, try/catch) → deniega el edit. Previene reward hacking.
`sdd-auto-test`	PostToolUse (Edit\|Write\|Skill)	Después de cada edit, lanza tests en background con trailing-edge coalescing (1 runner máximo por proyecto). Timeouts adaptativos basados en duración histórica.
`constraint-reinforcement`	UserPromptSubmit	Inyecta ~55 tokens de constraints en recency zone de cada prompt — contrarresta dilución de atención en conversaciones largas.
`task-completed`	TaskCompleted	Coverage enforcement: detecta archivos sin tests. Skill enforcement: valida que SOP skills fueron invocados. Baseline comparison: distingue fallos preexistentes de regresiones.

sdd-test-guard implementa la ley de hierro: "Not M/M → fix code, never weaken scenarios." Su matriz de decisión:

Tests	Edit	Resultado
Passing + cualquier cambio	→ ALLOW	Refactoring legítimo
Failing + assertions ≥	→ ALLOW	Fix o test nuevo
Failing + assertions <	→ DENY	Reward hacking detectado
Failing + precision downgrade	→ DENY	Weakening semántico detectado
Sin estado + cualquier cambio	→ ALLOW	Sin datos = sin bloqueo

sdd-auto-test cierra el loop de SDD: cada cambio al código fuente dispara tests automáticamente con coalescing (evita runners paralelos redundantes). Los resultados se reportan en el contexto del siguiente edit.

task-completed valida al completar tareas: que archivos source tengan tests correspondientes (coverage enforcement), que skills SOP fueron invocados antes de completar (skill enforcement), y que fallos nuevos no se confundan con preexistentes (baseline comparison).

Los hooks comparten estado via archivos temporales con session isolation para teammates paralelos y son invisibles en operación normal.

SDD vs TDD

	Scenario (SDD)	Test (TDD)
Vive	Spec externa al código	Código del codebase
Evalúa	"¿Satisface al usuario?"	"¿Pasa?" (boolean)
Vulnerable a	Nada (holdout externo)	Reward hacking
Escrito como	User story observable	Assertion técnica

SDD no reemplaza tests — los complementa. Los escenarios definen qué debe pasar; los tests verifican que siga pasando.

Fase 4: Quality

Seis agentes especializados se activan automáticamente según contexto. No necesitas invocarlos — Claude los delega cuando corresponde.

Agent	Qué revisa	Cuándo se activa
`code-reviewer`	SDD compliance, behavioral satisfaction, reward hacking	Después de implementar un step
`code-simplifier`	Complejidad, redundancia, nombres	Después de escribir código
`security-reviewer`	Injection, auth bypass, secrets	Antes de PR, cambios en auth/data
`edge-case-detector`	Boundary, concurrency, resource leaks	Código crítico (money, state)
`performance-engineer`	Queries, algorithmic complexity, I/O	Problemas de rendimiento
`systematic-debugger`	Root cause 4 fases	Bug o test failure

Ver descripción detallada de cada agente en Agentes.

Verification Gate obligatorio

Antes de declarar cualquier tarea completa, verification-before-completion ejecuta un gate de 6 pasos:

IDENTIFY — Listar cada claim que se está haciendo
RUN — Ejecutar la verificación ahora, no después
READ — Leer cada línea del output, completo
VERIFY — ¿El output coincide con el claim?
SATISFY — ¿Los escenarios convergen hacia satisfacción?
CLAIM — Afirmar con evidencia: npm test → 47/47 ✓

Sin evidencia no hay completion

"Debería funcionar"
"Ejecuté `npm test` y observé 47/47 passing"

Fase 5: Deliver

Commit

bash

/commit "feat: add push notification system"

Agrupa cambios automáticamente por tipo de archivo. Si modificaste código + config + docs, crea commits separados.

ConvencionalCorporativo

bash

/commit "feat(notifications): add daily limit"

bash

/commit "TRV-345 implementar límite diario"
# → feat|TRV-345|20260208|implementar límite diario

Pull Request

bash

/pull-request main

Quality gate integrado que ejecuta en paralelo:

Code review (lógica, arquitectura, bugs)
Security review (injection, secrets, XSS)
Observaciones (tests, API, breaking changes)

Tres opciones: Create PR · Auto fix · Cancel

Post-merge

bash

/branch-cleanup

Elimina feature branch local, sincroniza con remote.

Patrones por tamaño

Small ≤80 LOC — Directo

bash

# Describe y Claude implementa con SDD
"Agrega validación de email en el formulario de registro"

# Commit y PR
/commit "feat: add email validation"
/pull-request main

Sin pipeline. Claude aplica SDD automáticamente (define scenario → satisface → refactoriza).

Medium 80-250 LOC — Brainstorming + Plan Mode + SDD

bash

# 1. Explorar diseño
"Necesito rate limiting en la API"
# → brainstorming → plan mode → aprobación

# 2. Implementar con SDD
"Implementa el diseño"
# → SDD cycle por cada componente

# 3. Entregar
/commit "feat: add API rate limiting"
/pull-request main

Large/XL >250 LOC — Ralph Orchestrator

bash

# 1. Brainstorming (si no hay plan aprobado)
"Necesito autenticación OAuth completa"
# → brainstorming → plan mode → aprobación

# 2. Ralph se encarga de todo
"Implementa con ralph-orchestrator"
# → discovery → planning → tasks → checkpoint
# → ejecución autónoma con commits incrementales

# 3. PR final
/pull-request main

¿Cuándo usar Ralph?

Features de más de 250 LOC
Desarrollo overnight o AFK
Cuando quieres fresh context en cada iteración (evita context rot)
Cuando el feature tiene múltiples componentes interdependientes

Hotfix urgente — Worktree aislado

bash

/worktree-create "hotfix-race-condition" main

# En la nueva ventana:
"Fix: race condition en checkout"
/commit "fix: race condition in checkout process"
/pull-request main

/worktree-cleanup hotfix-race-condition

Herramientas de soporte

Además del pipeline principal, el framework incluye herramientas para tareas específicas: /project-init para configurar reglas de proyecto, /deep-research para investigación multi-fuente, agent-browser para interacción web, /dogfood para QA exploratorio de apps web, y /worktree-create para trabajo paralelo.

Ver detalles completos en Skills.

Plugins complementarios

El framework se integra con plugins externos como Superpowers (skills para TDD, planificación estructurada, code review bidireccional, parallel agents) y Episodic Memory (búsqueda semántica de conversaciones pasadas).

Ver instalación y detalles en Integraciones.

Referencia rápida

Quiero...	Comando / Acción
Explorar una idea	`"Necesito X"` → brainstorming activa
Desarrollo autónomo	`"Implementa con ralph-orchestrator"`
Investigar sistema existente	`"Investiga el módulo de auth"` → sop-reverse
Debug metódico	`"Bug: el checkout falla"` → systematic-debugging
Commit	`/commit "tipo: descripción"`
Pull request	`/pull-request main`
Limpiar branch	`/branch-cleanup`
Worktree paralelo	`/worktree-create "nombre" base`
Inicializar proyecto	`/project-init`
Investigación profunda	`/deep-research "tema"`
Interacción web	`agent-browser open URL`
QA exploratorio	`"dogfood localhost:3000"` → reporte con repro evidence

Siguiente paso: Pro tips

Relacionados: Skills · Agents · Integrations · Quickstart

Última actualización

Fecha: 2026-03-11

Workflow AI-first ​

El Pipeline ​

Fase 1: Idea ​

Fase 2: Plan ​

Ralph Orchestrator recomendado ​

SOP Pipeline manual ​

Fase 3: Implement ​

Scenario-Driven Development metodología central ​

Enforcement automático invisible ​

Fase 4: Quality ​

Verification Gate obligatorio ​

Fase 5: Deliver ​

Commit ​

Pull Request ​

Post-merge ​

Patrones por tamaño ​

Small ≤80 LOC — Directo ​

Medium 80-250 LOC — Brainstorming + Plan Mode + SDD ​

Large/XL >250 LOC — Ralph Orchestrator ​

Hotfix urgente — Worktree aislado ​

Herramientas de soporte ​

Plugins complementarios ​

Referencia rápida ​

Workflow AI-first

El Pipeline

Fase 1: Idea

Fase 2: Plan

Ralph Orchestrator recomendado

SOP Pipeline manual

Fase 3: Implement

Scenario-Driven Development metodología central

Enforcement automático invisible

Fase 4: Quality

Verification Gate obligatorio

Fase 5: Deliver

Commit

Pull Request

Post-merge

Patrones por tamaño

Small ≤80 LOC — Directo

Medium 80-250 LOC — Brainstorming + Plan Mode + SDD

Large/XL >250 LOC — Ralph Orchestrator

Hotfix urgente — Worktree aislado

Herramientas de soporte

Plugins complementarios

Referencia rápida