Ralph TUI - Criar Beads (beads-rust)
Converte PRDs em beads (épica + tarefas filhas) para execução autônoma com ralph-tui usando beads-rust (CLI br).
Nota: Este skill usa o comando
brdo beads-rust. Se você tiver o beads original (bd) instalado, use o skillralph-tui-create-beads.
O Trabalho
Pegue um PRD (arquivo markdown ou texto) e crie beads usando comandos br:
- Extraia os Portões de Qualidade da seção "Portões de Qualidade" do PRD
- Crie um bead épico para a funcionalidade
- Crie beads filhos para cada história de usuário (com os portões de qualidade anexados)
- Configure dependências entre os beads (esquema → backend → UI)
- Saída pronta para
ralph-tui run --tracker beads-rust
Passo 1: Extrair Portões de Qualidade
Procure pela seção "Portões de Qualidade" no PRD:
## Portões de Qualidade
Estes comandos devem passar para toda história de usuário:
- `pnpm typecheck` - Verificação de tipos
- `pnpm lint` - Linting
Para histórias de UI, inclua também:
- Verifique no navegador usando o skill dev-browser
Extraia:
- Portões universais: Comandos que se aplicam a TODAS as histórias (ex.:
pnpm typecheck) - Portões de UI: Comandos que se aplicam apenas a histórias de UI (ex.: verificação no navegador)
Se não existir seção de Portões de Qualidade: Pergunte ao usuário quais comandos devem passar, ou use um padrão sensato como npm run typecheck.
Formato de Saída
Os beads usam o comando br create com sintaxe HEREDOC para lidar com segurança com caracteres especiais:
# Criar épica (link de volta para o PRD fonte)
br create --type=epic \
--title="[Nome da Funcionalidade]" \
--description="$(cat <<'EOF'
[Descrição da funcionalidade do PRD]
EOF
)" \
--external-ref="prd:./tasks/feature-name-prd.md"
# Criar bead filho (com portões de qualidade nos critérios de aceitação)
br create \
--parent=EPIC_ID \
--title="[Título da História]" \
--description="$(cat <<'EOF'
[Descrição da história com critérios de aceitação INCLUINDO portões de qualidade]
EOF
)" \
--priority=[1-4]
CRÍTICO: Sempre use
<<'EOF'(com aspas simples) para o delimitador HEREDOC. Isso evita a interpretação pelo shell de acentos graves,$variáveise()nas descrições.
Tamanho da História: A Regra #1
Cada história deve ser completável em UMA iteração do ralph-tui (~uma janela de contexto do agente).
O ralph-tui cria uma nova instância de agente por iteração, sem memória do trabalho anterior. Se uma história for muito grande, o agente fica sem contexto antes de terminar.
Histórias de tamanho adequado:
- Adicionar uma coluna no banco de dados + migração
- Adicionar um componente de UI a uma página existente
- Atualizar uma server action com nova lógica
- Adicionar um dropdown de filtro a uma lista
Muito grande (divida estas):
- "Construir o dashboard inteiro" → Dividir em: esquema, consultas, componentes de UI, filtros
- "Adicionar autenticação" → Dividir em: esquema, middleware, UI de login, gerenciamento de sessão
- "Refatorar a API" → Dividir em uma história por endpoint ou padrão
Regra prática: Se você não consegue descrever a mudança em 2-3 frases, é grande demais.
Ordem das Histórias: Dependências Primeiro
As histórias executam na ordem das dependências. Histórias anteriores não devem depender de histórias posteriores.
Ordem correta:
- Mudanças de esquema/banco de dados (migrações)
- Server actions / lógica de backend
- Componentes de UI que usam o backend
- Views de dashboard/resumo que agregam dados
Ordem errada:
- ❌ Componente de UI (depende de esquema que ainda não existe)
- ❌ Mudança de esquema
Dependências com br dep add
Use o comando br dep add para especificar quais beads devem ser concluídos primeiro:
# Crie os beads primeiro
br create --parent=epic-123 --title="US-001: Adicionar esquema" ...
br create --parent=epic-123 --title="US-002: Criar API" ...
br create --parent=epic-123 --title="US-003: Construir UI" ...
# Em seguida, adicione dependências (issue depende-do 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
Sintaxe: br dep add <issue> <depende-de> — o issue depende de (é bloqueado por) depende-de.
O ralph-tui irá:
- Mostrar beads bloqueados como "bloqueados" até que as dependências sejam concluídas
- Nunca selecionar um bead para execução enquanto suas dependências estiverem abertas
- Incluir contexto de dependência no prompt ao trabalhar em um bead
Ordem correta de dependências:
- Mudanças de esquema/banco de dados (sem dependências)
- Lógica de backend (depende do esquema)
- Componentes de UI (dependem do backend)
- Integração/polimento (depende da UI)
Critérios de Aceitação: Portões de Qualidade + Específicos da História
A descrição de cada bead deve incluir critérios de aceitação com:
- Critérios específicos da história do PRD (o que esta história realiza)
- Portões de qualidade da seção de Portões de Qualidade do PRD (anexados ao final)
Bons critérios (verificáveis):
- "Adicionar coluna
investorTypeà tabela investor com padrão 'cold'" - "O dropdown de filtro tem opções: Todos, Frio, Amigo"
- "Clicar no alternador mostra diálogo de confirmação"
Maus critérios (vagos):
- ❌ "Funciona corretamente"
- ❌ "O usuário pode fazer X facilmente"
- ❌ "Boa UX"
- ❌ "Lida com casos de borda"
Regras de Conversão
- Extraia os Portões de Qualidade do PRD primeiro
- Cada história de usuário → um bead
- Primeira história: Sem dependências (cria a fundação)
- Histórias subsequentes: Dependem das predecessoras (UI depende do backend, etc.)
- Prioridade: Baseada na ordem de dependência, depois na ordem do documento (0=crítico, 2=médio, 4=backlog)
- Todas as histórias:
status: "open" - Critérios de aceitação: Critérios da história + portões de qualidade anexados
- Histórias de UI: Anexar também portões específicos de UI (verificação no navegador)
Dividindo PRDs Grandes
Se um PRD tiver funcionalidades grandes, divida-as:
Original:
"Adicionar trilha de divulgação para amigos com diferentes mensagens"
Dividido em:
- US-001: Adicionar campo investorType ao banco de dados
- US-002: Adicionar alternador de tipo à UI da lista de investidores
- US-003: Criar lógica de progressão de fase específica para amigos
- US-004: Criar modelos de mensagem para amigos
- US-005: Integrar geração de tarefas para amigos
- US-006: Adicionar filtro por tipo
- US-007: Atualizar formulário de novo investidor
- US-008: Atualizar contagens do dashboard
Cada uma é uma mudança focada que pode ser completada e verificada independentemente.
Exemplo
PRD de entrada:
# PRD: Divulgação para Amigos
Adicionar capacidade de marcar investidores como "amigos" para divulgação calorosa.
## Portões de Qualidade
Estes comandos devem passar para toda história de usuário:
- `pnpm typecheck` - Verificação de tipos
- `pnpm lint` - Linting
Para histórias de UI, inclua também:
- Verifique no navegador usando o skill dev-browser
## Histórias de Usuário
### US-001: Adicionar campo investorType à tabela investor
**Descrição:** Como desenvolvedor, preciso categorizar investidores como 'frio' ou 'amigo'.
**Critérios de Aceitação:**
- [ ] Adicionar coluna investorType: 'cold' | 'friend' (padrão 'cold')
- [ ] Gerar e executar migração com sucesso
### US-002: Adicionar alternador de tipo às linhas da lista de investidores
**Descrição:** Como Ryan, quero alternar o tipo do investidor diretamente da lista.
**Critérios de Aceitação:**
- [ ] Cada linha tem alternador Frio | Amigo
- [ ] Alternar mostra diálogo de confirmação
- [ ] Ao confirmar: atualiza tipo no banco de dados
### US-003: Filtrar investidores por tipo
**Descrição:** Como Ryan, quero filtrar a lista para ver apenas amigos ou frios.
**Critérios de Aceitação:**
- [ ] Dropdown de filtro: Todos | Frio | Amigo
- [ ] Filtro persiste nos parâmetros de URL
Beads de saída:
# Criar épica (link de volta para o PRD fonte)
br create --type=epic \
--title="Trilha de Divulgação para Amigos" \
--description="$(cat <<'EOF'
Divulgação calorosa para feedback de deck
EOF
)" \
--external-ref="prd:./tasks/friends-outreach-prd.md"
# US-001: Sem deps (primeiro - cria esquema)
br create --parent=ralph-tui-abc \
--title="US-001: Adicionar campo investorType à tabela investor" \
--description="$(cat <<'EOF'
Como desenvolvedor, preciso categorizar investidores como 'frio' ou 'amigo'.
## Critérios de Aceitação
- [ ] Adicionar coluna investorType: 'cold' | 'friend' (padrão 'cold')
- [ ] Gerar e executar migração com sucesso
- [ ] pnpm typecheck passa
- [ ] pnpm lint passa
EOF
)" \
--priority=1
# US-002: História de UI (também recebe verificação no navegador)
br create --parent=ralph-tui-abc \
--title="US-002: Adicionar alternador de tipo às linhas da lista de investidores" \
--description="$(cat <<'EOF'
Como Ryan, quero alternar o tipo do investidor diretamente da lista.
## Critérios de Aceitação
- [ ] Cada linha tem alternador Frio | Amigo
- [ ] Alternar mostra diálogo de confirmação
- [ ] Ao confirmar: atualiza tipo no banco de dados
- [ ] pnpm typecheck passa
- [ ] pnpm lint passa
- [ ] Verifique no navegador usando o skill dev-browser
EOF
)" \
--priority=2
# Adicionar dependência: US-002 depende de US-001
br dep add ralph-tui-002 ralph-tui-001
# US-003: História de UI
br create --parent=ralph-tui-abc \
--title="US-003: Filtrar investidores por tipo" \
--description="$(cat <<'EOF'
Como Ryan, quero filtrar a lista para ver apenas amigos ou frios.
## Critérios de Aceitação
- [ ] Dropdown de filtro: Todos | Frio | Amigo
- [ ] Filtro persiste nos parâmetros de URL
- [ ] pnpm typecheck passa
- [ ] pnpm lint passa
- [ ] Verifique no navegador usando o skill dev-browser
EOF
)" \
--priority=3
# Adicionar dependência: US-003 depende de US-002
br dep add ralph-tui-003 ralph-tui-002
Sincronizando Mudanças
Após criar beads, sincronize para exportar para JSONL (para rastreamento git):
br sync --flush-only
Isso exporta o banco de dados SQLite para .beads/issues.jsonl para controle de versão.
Localização da Saída
Os beads são armazenados no diretório: .beads/ (banco de dados SQLite + exportação JSONL)
Após a criação, execute o ralph-tui:
# Trabalhar em uma épica específica
ralph-tui run --tracker beads-rust --epic ralph-tui-abc
# Ou deixe ele escolher a melhor tarefa automaticamente
ralph-tui run --tracker beads-rust
O ralph-tui irá:
- Trabalhar nos beads dentro da épica especificada (ou selecionar a melhor tarefa disponível)
- Fechar cada bead quando completo
- Fechar a épica quando todos os filhos estiverem prontos
- Gerar
<promise>COMPLETE</promise>quando a épica estiver concluída
Lista de Verificação Antes de Criar Beads
- Extraídos os Portões de Qualidade do PRD (ou perguntado ao usuário se ausentes)
- Cada história é completável em uma iteração (pequena o suficiente)
- Histórias ordenadas por dependência (esquema → backend → UI)
- Portões de qualidade anexados aos critérios de aceitação de cada bead
- Histórias de UI têm verificação no navegador (se especificado nos Portões de Qualidade)
- Critérios de aceitação são verificáveis (não vagos)
- Nenhuma história depende de uma história posterior (apenas de anteriores)
- Dependências adicionadas com
br dep addapós criar os beads - Executado
br sync --flush-onlypara exportar para rastreamento git
Diferenças do beads (versão Go)
| Comando | beads (bd) | beads-rust (br) |
|---|---|---|
| Criar | bd create | br create |
| Dependências | bd dep add | br dep add |
| Sincronizar | bd sync | br sync --flush-only |
| Fechar | bd close | br close |
| Armazenamento | .beads/beads.jsonl | .beads/*.db + exportação JSONL |