Ralph TUI - Criar Beads
Converte PRDs em beads (épico + tarefas filhas) para execução autônoma com ralph-tui.
Nota: Esta skill acompanha o plugin de rastreador de Beads do ralph-tui. Plugins de rastreador futuros (Linear, GitHub Issues, etc.) incluirão suas próprias skills de criação de tarefas.
O Trabalho
Pegue um PRD (arquivo markdown ou texto) e crie beads em .beads/beads.jsonl:
- Extrair Portões de Qualidade da seção "Portões de Qualidade" do PRD
- Criar um bead de épico para a funcionalidade
- Criar beads filhas para cada história de usuário (com portões de qualidade anexados)
- Configurar dependências entre os beads (esquema → backend → UI)
- Saída pronta para
ralph-tui run --tracker beads
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 cada história de usuário:
- `pnpm typecheck` - Verificação de tipos
- `pnpm lint` - Verificação de linting
Para histórias de UI, inclua também:
- Verificar no navegador usando a 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 houver 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 bd create com sintaxe HEREDOC para lidar com caracteres especiais com segurança:
# Criar épico (link de volta ao PRD fonte)
bd create --type=epic \
--title="[Nome da Funcionalidade]" \
--description="$(cat <<'EOF'
[Descrição da funcionalidade do PRD]
EOF
)" \
--external-ref="prd:./tasks/nome-da-funcionalidade-prd.md"
# Criar bead filho (com portões de qualidade nos critérios de aceitação)
bd 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]
IMPORTANTE: Sempre use
<<'EOF'(com aspas simples) para o delimitador HEREDOC. Isso evita a interpretação de acentos graves,$variáveise()pelo shell nas descrições.
Tamanho da História: A Regra #1
Cada história deve ser concluível em UMA iteração do ralph-tui (~um contexto de janela do agente).
O ralph-tui inicia uma nova instância do 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 ao banco + migração
- Adicionar um componente de UI em 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" → Divida em: esquema, consultas, componentes de UI, filtros
- "Adicionar autenticação" → Divida em: esquema, middleware, UI de login, gerenciamento de sessão
- "Refatorar a API" → Divida 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, é muito grande.
Ordem das Histórias: Dependências Primeiro
As histórias executam na ordem de dependência. Histórias anteriores não devem depender de posteriores.
Ordem correta:
- Alterações de esquema/banco (migrações)
- Server actions / lógica de backend
- Componentes de UI que usam o backend
- Visualizações de dashboard/resumo que agregam dados
Ordem errada:
- ❌ Componente de UI (depende de esquema que ainda não existe)
- ❌ Alteração de esquema
Dependências com bd dep add
Use o comando bd dep add para especificar quais beads devem ser concluídos primeiro:
# Crie os beads primeiro
bd create --parent=epico-123 --title="US-001: Adicionar esquema" ...
bd create --parent=epico-123 --title="US-002: Criar API" ...
bd create --parent=epico-123 --title="US-003: Construir UI" ...
# Depois adicione as dependências (issue depende-de bloqueador)
bd dep add ralph-tui-002 ralph-tui-001 # US-002 depende de US-001
bd dep add ralph-tui-003 ralph-tui-002 # US-003 depende de US-002
Sintaxe: bd dep add <issue> <depende-de> — a issue depende de (é bloqueada 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 da dependência no prompt ao trabalhar em um bead
Ordem correta de dependência:
- Alterações de esquema/banco (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 Portões de Qualidade do PRD (anexados ao final)
Bons critérios (verificáveis):
- "Adicionar coluna
investorTypeà tabela investor com padrão 'cold'" - "Dropdown de filtro tem opções: All, Cold, Friend"
- "Clicar no toggle mostra diálogo de confirmação"
Maus critérios (vagos):
- ❌ "Funciona corretamente"
- ❌ "O usuário pode fazer X facilmente"
- ❌ "Boa UX"
- ❌ "Trata casos de borda"
Regras de Conversão
- Extrair Portões de Qualidade do PRD primeiro
- Cada história de usuário → um bead
- Primeira história: Sem dependências (cria a base)
- Histórias subsequentes: Dependem de suas antecessoras (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 rastreamento de outreach para amigos com mensagens diferentes"
Dividido em:
- US-001: Adicionar campo investorType ao banco
- US-002: Adicionar alternância de tipo à lista de investidores UI
- US-003: Criar lógica de progressão de fase específica para amigos
- US-004: Criar templates de mensagem para amigos
- US-005: Configurar 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 concluída e verificada independentemente.
Exemplo
PRD de entrada:
# PRD: Outreach para Amigos
Adicionar capacidade de marcar investidores como "amigos" para outreach caloroso.
## Portões de Qualidade
Estes comandos devem passar para cada história de usuário:
- `pnpm typecheck` - Verificação de tipos
- `pnpm lint` - Verificação de linting
Para histórias de UI, inclua também:
- Verificar no navegador usando a skill dev-browser
## Histórias de Usuário
### US-001: Adicionar campo investorType à tabela investor
**Descrição:** Como desenvolvedor, preciso categorizar investidores como 'cold' ou 'friend'.
**Critérios de Aceitação:**
- [ ] Adicionar coluna investorType: 'cold' | 'friend' (padrão 'cold')
- [ ] Gerar e executar migração com sucesso
### US-002: Adicionar alternância 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 alternância Cold | Friend
- [ ] Alternar mostra diálogo de confirmação
- [ ] Ao confirmar: atualiza tipo no banco
### US-003: Filtrar investidores por tipo
**Descrição:** Como Ryan, quero filtrar a lista para ver apenas amigos ou cold.
**Critérios de Aceitação:**
- [ ] Dropdown de filtro: All | Cold | Friend
- [ ] Filtro persiste nos parâmetros da URL
Beads de saída:
# Criar épico (link de volta ao PRD fonte)
bd create --type=epic \
--title="Funcionalidade de Outreach para Amigos" \
--description="$(cat <<'EOF'
Outreach caloroso para feedback de deck
EOF
)" \
--external-ref="prd:./tasks/friends-outreach-prd.md"
# US-001: Sem dependências (primeiro - cria esquema)
bd create --parent=ralph-tui-abc \
--title="US-001: Adicionar campo investorType à tabela investor" \
--description="$(cat <<'EOF'
Como desenvolvedor, preciso categorizar investidores como 'cold' ou 'friend'.
## 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)
bd create --parent=ralph-tui-abc \
--title="US-002: Adicionar alternância 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 alternância Cold | Friend
- [ ] Alternar mostra diálogo de confirmação
- [ ] Ao confirmar: atualiza tipo no banco
- [ ] pnpm typecheck passa
- [ ] pnpm lint passa
- [ ] Verificar no navegador usando a skill dev-browser
EOF
)" \
--priority=2
# Adicionar dependência: US-002 depende de US-001
bd dep add ralph-tui-002 ralph-tui-001
# US-003: História de UI
bd 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 cold.
## Critérios de Aceitação
- [ ] Dropdown de filtro: All | Cold | Friend
- [ ] Filtro persiste nos parâmetros da URL
- [ ] pnpm typecheck passa
- [ ] pnpm lint passa
- [ ] Verificar no navegador usando a skill dev-browser
EOF
)" \
--priority=3
# Adicionar dependência: US-003 depende de US-002
bd dep add ralph-tui-003 ralph-tui-002
Local de Saída
Os beads são escritos em: .beads/beads.jsonl
Após a criação, execute o ralph-tui:
# Trabalhar em um épico específico
ralph-tui run --tracker beads --epic ralph-tui-abc
# Ou deixar que ele selecione a melhor tarefa automaticamente
ralph-tui run --tracker beads
O ralph-tui irá:
- Trabalhar nos beads dentro do épico especificado (ou selecionar a melhor tarefa disponível)
- Fechar cada bead quando concluído
- Fechar o épico quando todos os filhos estiverem prontos
- Gerar
<promise>COMPLETE</promise>quando o épico for concluído
Lista de Verificação Antes de Criar Beads
- Portões de Qualidade extraídos do PRD (ou perguntado ao usuário se ausentes)
- Cada história é concluí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 especificada 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
bd dep addapós criar beads