¿Qué hace Ralph TUI - Crear Beads (beads-rust)?
Convierte PRDs a beads (epic + tareas hijas) para ejecución autónoma con ralph-tui usando beads-rust (br CLI).
Nota: Este skill usa el comando
brde beads-rust. Si tienes instalado el beads original (bd), usa el skillralph-tui-create-beads.
El Trabajo
Tomar un PRD (archivo markdown o texto) y crear beads usando comandos br:
- Extraer Quality Gates de la sección "Quality Gates" del PRD
- Crear un bead epic para la funcionalidad
- Crear beads hijos para cada historia de usuario (con los quality gates añadidos)
- Establecer dependencias entre beads (esquema → backend → UI)
- Salida lista para
ralph-tui run --tracker beads-rust
Paso 1: Extraer Quality Gates
Buscar la sección "Quality Gates" en el PRD:
## Quality Gates
Estos comandos deben pasar para cada historia de usuario:
- `pnpm typecheck` - Verificación de tipos
- `pnpm lint` - Linting
Para historias de UI, incluir también:
- Verificar en navegador usando el skill dev-browser
Extraer:
- Gates universales: Comandos que aplican a TODAS las historias (ej.,
pnpm typecheck) - Gates de UI: Comandos que aplican solo a historias de UI (ej., verificación en navegador)
Si no existe sección de Quality Gates: Preguntar al usuario qué comandos deben pasar, o usar un valor predeterminado sensato como npm run typecheck.
Formato de Salida
Los beads usan el comando br create con sintaxis HEREDOC para manejar caracteres especiales de forma segura:
# Crear epic (enlace de vuelta al PRD fuente)
br create --type=epic \
--title="[Nombre de Funcionalidad]" \
--description="$(cat <<'EOF'
[Descripción de funcionalidad del PRD]
EOF
)" \
--external-ref="prd:./tasks/feature-name-prd.md"
# Crear bead hijo (con quality gates en criterios de aceptación)
br create \
--parent=EPIC_ID \
--title="[Título de Historia]" \
--description="$(cat <<'EOF'
[Descripción de historia con criterios de aceptación INCLUYENDO quality gates]
EOF
)" \
--priority=[1-4]
CRÍTICO: Usar siempre
<<'EOF'(con comillas simples) para el delimitador HEREDOC. Esto evita la interpretación por parte del shell de acentos graves,$variables, y()en las descripciones.
Tamaño de Historia: La Regla #1
Cada historia debe poder completarse en UNA iteración de ralph-tui (~una ventana de contexto de agente).
ralph-tui crea una instancia de agente nueva por iteración sin memoria del trabajo anterior. Si una historia es demasiado grande, el agente se queda sin contexto antes de terminarla.
Historias con tamaño correcto:
- Añadir una columna de base de datos + migración
- Añadir un componente UI a una página existente
- Actualizar una server action con nueva lógica
- Añadir un desplegable de filtro a una lista
Demasiado grandes (dividir estas):
- "Construir todo el dashboard" → Dividir en: esquema, consultas, componentes UI, filtros
- "Añadir autenticación" → Dividir en: esquema, middleware, UI de inicio de sesión, manejo de sesiones
- "Refactorizar la API" → Dividir en una historia por endpoint o patrón
Regla general: Si no puedes describir el cambio en 2-3 oraciones, es demasiado grande.
Orden de Historias: Dependencias Primero
Las historias se ejecutan en orden de dependencia. Las historias anteriores no deben depender de las posteriores.
Orden correcto:
- Cambios de esquema/base de datos (migraciones)
- Server actions / lógica backend
- Componentes UI que usan el backend
- Vistas de dashboard/resumen que agregan datos
Orden incorrecto:
- ❌ Componente UI (depende de un esquema que aún no existe)
- ❌ Cambio de esquema
Dependencias con br dep add
Usar el comando br dep add para especificar qué beads deben completarse primero:
# Crear los beads primero
br create --parent=epic-123 --title="US-001: Añadir esquema" ...
br create --parent=epic-123 --title="US-002: Crear API" ...
br create --parent=epic-123 --title="US-003: Construir UI" ...
# Luego añadir dependencias (issue depende-de blocker)
br dep add ralph-tui-002 ralph-tui-001 # US-002 depende de US-001
br dep add ralph-tui-003 ralph-tui-002 # US-003 depende de US-002
Sintaxis: br dep add <issue> <depende-de> — el issue depende de (está bloqueado por) depende-de.
ralph-tui:
- Mostrará los beads bloqueados como "bloqueados" hasta que las dependencias se completen
- Nunca seleccionará un bead para ejecución mientras sus dependencias estén abiertas
- Incluirá el contexto de dependencia en el prompt al trabajar en un bead
Orden correcto de dependencias:
- Cambios de esquema/base de datos (sin dependencias)
- Lógica backend (depende del esquema)
- Componentes UI (dependen del backend)
- Integración/pulido (depende de UI)
Criterios de Aceptación: Quality Gates + Específicos de Historia
La descripción de cada bead debe incluir criterios de aceptación con:
- Criterios específicos de la historia del PRD (lo que esta historia logra)
- Quality gates de la sección de Quality Gates del PRD (añadidos al final)
Criterios buenos (verificables):
- "Añadir columna
investorTypea la tabla investor con valor por defecto 'cold'" - "El desplegable de filtro tiene opciones: All, Cold, Friend"
- "Al hacer clic en el toggle se muestra un diálogo de confirmación"
Criterios malos (vagos):
- ❌ "Funciona correctamente"
- ❌ "El usuario puede hacer X fácilmente"
- ❌ "Buena experiencia de usuario"
- ❌ "Maneja casos límite"
Reglas de Conversión
- Extraer Quality Gates del PRD primero
- Cada historia de usuario → un bead
- Primera historia: Sin dependencias (crea la base)
- Historias siguientes: Dependen de sus predecesoras (UI depende de backend, etc.)
- Prioridad: Basada en orden de dependencia, luego orden del documento (0=crítica, 2=media, 4=backlog)
- Todas las historias:
status: "open" - Criterios de aceptación: Criterios de historia + quality gates añadidos
- Historias de UI: También añadir gates específicos de UI (verificación en navegador)
División de PRDs Grandes
Si un PRD tiene funcionalidades grandes, dividirlas:
Original:
"Añadir flujo de contactos amigos con diferentes mensajes"
Dividir en:
- US-001: Añadir campo investorType a la base de datos
- US-002: Añadir toggle de tipo a la lista de inversores en UI
- US-003: Crear lógica de progresión de fase específica para amigos
- US-004: Crear plantillas de mensajes para amigos
- US-005: Conectar generación de tareas para amigos
- US-006: Añadir filtro por tipo
- US-007: Actualizar formulario de nuevo inversor
- US-008: Actualizar contadores del dashboard
Cada una es un cambio enfocado que puede completarse y verificarse independientemente.
Ejemplo
PRD de entrada:
# PRD: Contactos Amigos
Añadir capacidad de marcar inversores como "amigos" para contacto cálido.
## Quality Gates
Estos comandos deben pasar para cada historia de usuario:
- `pnpm typecheck` - Verificación de tipos
- `pnpm lint` - Linting
Para historias de UI, incluir también:
- Verificar en navegador usando el skill dev-browser
## Historias de Usuario
### US-001: Añadir campo investorType a la tabla investor
**Descripción:** Como desarrollador, necesito categorizar inversores como 'cold' o 'friend'.
**Criterios de Aceptación:**
- [ ] Añadir columna investorType: 'cold' | 'friend' (valor por defecto 'cold')
- [ ] Generar y ejecutar migración exitosamente
### US-002: Añadir toggle de tipo a filas de lista de inversores
**Descripción:** Como Ryan, quiero cambiar el tipo de inversor directamente desde la lista.
**Criterios de Aceptación:**
- [ ] Cada fila tiene un toggle Cold | Friend
- [ ] Al cambiar muestra un diálogo de confirmación
- [ ] Al confirmar: actualiza el tipo en la base de datos
### US-003: Filtrar inversores por tipo
**Descripción:** Como Ryan, quiero filtrar la lista para ver solo amigos o cold.
**Criterios de Aceptación:**
- [ ] Desplegable de filtro: All | Cold | Friend
- [ ] El filtro persiste en parámetros de URL
Beads de salida:
# Crear epic (enlace de vuelta al PRD fuente)
br create --type=epic \
--title="Flujo de Contactos Amigos" \
--description="$(cat <<'EOF'
Contacto cálido para feedback de deck
EOF
)" \
--external-ref="prd:./tasks/friends-outreach-prd.md"
# US-001: Sin deps (primera - crea esquema)
br create --parent=ralph-tui-abc \
--title="US-001: Añadir campo investorType a la tabla investor" \
--description="$(cat <<'EOF'
Como desarrollador, necesito categorizar inversores como 'cold' o 'friend'.
## Criterios de Aceptación
- [ ] Añadir columna investorType: 'cold' | 'friend' (valor por defecto 'cold')
- [ ] Generar y ejecutar migración exitosamente
- [ ] pnpm typecheck pasa
- [ ] pnpm lint pasa
EOF
)" \
--priority=1
# US-002: Historia de UI (también recibe verificación en navegador)
br create --parent=ralph-tui-abc \
--title="US-002: Añadir toggle de tipo a filas de lista de inversores" \
--description="$(cat <<'EOF'
Como Ryan, quiero cambiar el tipo de inversor directamente desde la lista.
## Criterios de Aceptación
- [ ] Cada fila tiene un toggle Cold | Friend
- [ ] Al cambiar muestra un diálogo de confirmación
- [ ] Al confirmar: actualiza el tipo en la base de datos
- [ ] pnpm typecheck pasa
- [ ] pnpm lint pasa
- [ ] Verificar en navegador usando el skill dev-browser
EOF
)" \
--priority=2
# Añadir dependencia: US-002 depende de US-001
br dep add ralph-tui-002 ralph-tui-001
# US-003: Historia de UI
br create --parent=ralph-tui-abc \
--title="US-003: Filtrar inversores por tipo" \
--description="$(cat <<'EOF'
Como Ryan, quiero filtrar la lista para ver solo amigos o cold.
## Criterios de Aceptación
- [ ] Desplegable de filtro: All | Cold | Friend
- [ ] El filtro persiste en parámetros de URL
- [ ] pnpm typecheck pasa
- [ ] pnpm lint pasa
- [ ] Verificar en navegador usando el skill dev-browser
EOF
)" \
--priority=3
# Añadir dependencia: US-003 depende de US-002
br dep add ralph-tui-003 ralph-tui-002
Sincronizar Cambios
Después de crear beads, sincronizar para exportar a JSONL (para seguimiento con git):
br sync --flush-only
Esto exporta la base de datos SQLite a .beads/issues.jsonl para control de versiones.
Ubicación de Salida
Los beads se almacenan en: directorio .beads/ (BD SQLite + exportación JSONL)
Después de la creación, ejecutar ralph-tui:
# Trabajar en un epic específico
ralph-tui run --tracker beads-rust --epic ralph-tui-abc
# O dejar que seleccione automáticamente la mejor tarea
ralph-tui run --tracker beads-rust
ralph-tui:
- Trabajará en los beads dentro del epic especificado (o seleccionará la mejor tarea disponible)
- Cerrará cada bead cuando esté completo
- Cerrará el epic cuando todos los hijos estén hechos
- Mostrará
<promise>COMPLETE</promise>cuando el epic esté terminado
Lista de Verificación Antes de Crear Beads
- Quality Gates extraídos del PRD (o preguntados al usuario si faltan)
- Cada historia se puede completar en una iteración (suficientemente pequeña)
- Las historias están ordenadas por dependencia (esquema → backend → UI)
- Quality gates añadidos a los criterios de aceptación de cada bead
- Las historias de UI tienen verificación en navegador (si se especifica en Quality Gates)
- Los criterios de aceptación son verificables (no vagos)
- Ninguna historia depende de una historia posterior (solo de anteriores)
- Dependencias añadidas con
br dep adddespués de crear beads - Ejecutado
br sync --flush-onlypara exportar para seguimiento con git
Diferencias con beads (versión Go)
| Comando | beads (bd) | beads-rust (br) |
|---|---|---|
| Crear | bd create | br create |
| Dependencias | bd dep add | br dep add |
| Sincronizar | bd sync | br sync --flush-only |
| Cerrar | bd close | br close |
| Almacenamiento | .beads/beads.jsonl | .beads/*.db + exportación JSONL |