Ralph TUI - Criar Tarefas JSON
Converte PRDs para o formato prd.json para execução autônoma com ralph-tui.
Nota: Esta skill está incluída com o plugin de rastreador JSON do ralph-tui. Plugins de rastreador futuros (Linear, GitHub Issues, etc.) incluirão suas próprias skills de criação de tarefas.
⚠️ CRÍTICO: A saída DEVE ser um objeto JSON PLANO com "name" e "userStories" no nível RAÍZ. NÃO envolva o conteúdo em um objeto "prd" ou use um array "tasks". Veja a seção "Antipadrões de Esquema" abaixo.
A Tarefa
Pegue um PRD (arquivo markdown ou texto) e crie um arquivo prd.json:
- Extrair Gates de Qualidade da seção "Quality Gates" do PRD
- Analisar histórias de usuário do PRD
- Anexar gates de qualidade aos critérios de aceitação de cada história
- Configurar dependências entre histórias
- Saída pronta para
ralph-tui run --prd <caminho>
Passo 1: Extrair Gates de Qualidade
Procure pela seção "Quality Gates" no PRD:
## Quality Gates
Estes comandos devem passar para toda história de usuário:
- `pnpm typecheck` - Verificação de tipo
- `pnpm lint` - Linting
Para histórias de UI, inclua também:
- Verificar no navegador usando a skill dev-browser
Extraia:
- Gates universais: Comandos que se aplicam a TODAS as histórias (ex.:
pnpm typecheck) - Gates de UI: Comandos que se aplicam apenas a histórias de UI (ex.: verificação no navegador)
Se não houver seção de Quality Gates: Pergunte ao usuário quais comandos devem passar, ou use um padrão sensato como npm run typecheck.
Formato de Saída
O arquivo JSON DEVE ser um objeto PLANO no nível raiz:
{
"name": "[Nome do projeto do PRD ou diretório]",
"branchName": "ralph/[nome-da-funcionalidade-em-kebab-case]",
"description": "[Descrição da funcionalidade do PRD]",
"userStories": [
{
"id": "US-001",
"title": "[Título da história]",
"description": "Como um [usuário], quero [funcionalidade] para que [benefício]",
"acceptanceCriteria": [
"Critério 1 do PRD",
"Critério 2 do PRD",
"pnpm typecheck passa",
"pnpm lint passa"
],
"priority": 1,
"passes": false,
"notes": "",
"dependsOn": []
},
{
"id": "US-002",
"title": "[História de UI que depende de US-001]",
"description": "...",
"acceptanceCriteria": [
"...",
"pnpm typecheck passa",
"pnpm lint passa",
"Verificar no navegador usando a skill dev-browser"
],
"priority": 2,
"passes": false,
"notes": "",
"dependsOn": ["US-001"]
}
]
}
CRÍTICO: Antipadrões de Esquema (NÃO USE)
Os seguintes padrões são INVÁLIDOS e causarão erros de validação:
❌ ERRADO: Objeto wrapper
{
"prd": {
"name": "...",
"userStories": [...]
}
}
Isso envolve tudo em um objeto "prd". NÃO FAÇA ISSO. Os campos "name" e "userStories" devem estar no nível RAÍZ.
❌ ERRADO: Usar "tasks" em vez de "userStories"
{
"name": "...",
"tasks": [...]
}
O array é chamado de "userStories", não "tasks".
❌ ERRADO: Estruturas aninhadas complexas
{
"metadata": {...},
"overview": {...},
"migration_strategy": {
"phases": [...]
}
}
Mesmo que o PRD descreva fases/marcos/sprints, você DEVE achatá-los em um único array "userStories".
❌ ERRADO: Usar "status" em vez de "passes"
{
"userStories": [{
"id": "US-001",
"status": "open" // ERRADO!
}]
}
Use "passes": false para histórias incompletas, "passes": true para completas.
✅ CORRETO: Estrutura plana na raiz
{
"name": "Migração Kotlin para Android",
"branchName": "ralph/migracao-kotlin",
"userStories": [
{"id": "US-001", "title": "Criar interface Scraper", "passes": false, "dependsOn": []},
{"id": "US-002", "title": "Implementar WeebCentralScraper", "passes": false, "dependsOn": ["US-001"]}
]
}
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 gera 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 do tamanho certo:
- 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 grandes (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, é muito grande.
Dependências com dependsOn
Use o array dependsOn para especificar quais histórias devem ser concluídas primeiro:
{
"id": "US-002",
"title": "Criar endpoints da API",
"dependsOn": ["US-001"], // Não será selecionado até US-001 passar
...
}
O ralph-tui irá:
- Mostrar US-002 como "bloqueado" até US-001 ser concluída
- Nunca selecionar US-002 para execução enquanto US-001 estiver aberta
- Incluir "Pré-requisitos: US-001" no prompt ao trabalhar em US-002
Ordem de dependência correta:
- Mudanças no 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: Gates de Qualidade + Específicos da História
Os critérios de aceitação de cada história devem incluir:
- Critérios específicos da história do PRD (o que esta história realiza)
- Gates de qualidade da seção Quality Gates do PRD (anexados ao final)
Bons critérios (verificáveis):
- "Adicionar coluna
statusà tabela de tarefas com padrão 'open'" - "Dropdown de filtro tem opções: Todas, Abertas, Fechadas"
- "Clicar em excluir mostra diálogo de confirmação"
Maus critérios (vagos):
- ❌ "Funciona corretamente"
- ❌ "Usuário pode fazer X facilmente"
- ❌ "Boa UX"
- ❌ "Lida com casos de borda"
Regras de Conversão
- Extrair Gates de Qualidade do PRD primeiro
- Cada história de usuário → uma entrada JSON
- IDs: Sequenciais (US-001, US-002, etc.)
- Prioridade: Baseada na ordem de dependência (1 = maior)
- dependsOn: Array de IDs de história que esta história requer
- Todas as histórias:
passes: falseenotesvazios - branchName: Derivado do nome da funcionalidade, em kebab-case, prefixado com
ralph/ - Critérios de aceitação: Critérios da história + gates de qualidade anexados
- Histórias de UI: Anexar também gates específicos de UI (verificação no navegador)
Localização da Saída
Padrão: ./tasks/prd.json (junto com os arquivos markdown do PRD)
Isso mantém todos os arquivos relacionados ao PRD juntos no diretório tasks/.
Ou especifique um caminho diferente - o ralph-tui o usará com:
ralph-tui run --prd ./caminho/para/prd.json
Exemplo
PRD de Entrada:
# PRD: Sistema de Prioridade de Tarefas
Adicionar níveis de prioridade às tarefas.
## Quality Gates
Estes comandos devem passar para toda história de usuário:
- `pnpm typecheck` - Verificação de tipo
- `pnpm lint` - Linting
Para histórias de UI, inclua também:
- Verificar no navegador usando a skill dev-browser
## User Stories
### US-001: Adicionar campo de prioridade ao banco de dados
**Descrição:** Como desenvolvedor, preciso armazenar prioridade de tarefas.
**Critérios de Aceitação:**
- [ ] Adicionar coluna de prioridade: 1-4 (padrão 2)
- [ ] Migração executada com sucesso
### US-002: Exibir badge de prioridade nos cartões de tarefa
**Descrição:** Como usuário, quero ver a prioridade da tarefa rapidamente.
**Critérios de Aceitação:**
- [ ] Badge mostra P1/P2/P3/P4 com cores
- [ ] Badge visível sem passar o mouse
### US-003: Adicionar dropdown de filtro por prioridade
**Descrição:** Como usuário, quero filtrar tarefas por prioridade.
**Critérios de Aceitação:**
- [ ] Dropdown de filtro: Todas, P1, P2, P3, P4
- [ ] Filtro persiste na URL
prd.json de Saída:
{
"project": "my-app",
"branchName": "ralph/prioridade-tarefas",
"description": "Adicionar níveis de prioridade às tarefas",
"userStories": [
{
"id": "US-001",
"title": "Adicionar campo de prioridade ao banco de dados",
"description": "Como desenvolvedor, preciso armazenar prioridade de tarefas.",
"acceptanceCriteria": [
"Adicionar coluna de prioridade: 1-4 (padrão 2)",
"Migração executada com sucesso",
"pnpm typecheck passa",
"pnpm lint passa"
],
"priority": 1,
"passes": false,
"notes": "",
"dependsOn": []
},
{
"id": "US-002",
"title": "Exibir badge de prioridade nos cartões de tarefa",
"description": "Como usuário, quero ver a prioridade da tarefa rapidamente.",
"acceptanceCriteria": [
"Badge mostra P1/P2/P3/P4 com cores",
"Badge visível sem passar o mouse",
"pnpm typecheck passa",
"pnpm lint passa",
"Verificar no navegador usando a skill dev-browser"
],
"priority": 2,
"passes": false,
"notes": "",
"dependsOn": ["US-001"]
},
{
"id": "US-003",
"title": "Adicionar dropdown de filtro por prioridade",
"description": "Como usuário, quero filtrar tarefas por prioridade.",
"acceptanceCriteria": [
"Dropdown de filtro: Todas, P1, P2, P3, P4",
"Filtro persiste na URL",
"pnpm typecheck passa",
"pnpm lint passa",
"Verificar no navegador usando a skill dev-browser"
],
"priority": 3,
"passes": false,
"notes": "",
"dependsOn": ["US-002"]
}
]
}
Executando com ralph-tui
Após criar o prd.json:
ralph-tui run --prd ./tasks/prd.json
O ralph-tui irá:
- Carregar as histórias do prd.json
- Selecionar a história de maior prioridade com
passes: falsee sem dependências bloqueantes - Gerar um prompt com detalhes da história + critérios de aceitação
- Executar o agente para implementar a história
- Marcar
passes: trueao concluir - Repetir até que todas as histórias passem
Lista de Verificação Antes de Salvar
- Gates de Qualidade extraídos do PRD (ou perguntou ao usuário se estiverem faltando)
- Cada história completável em uma iteração
- Histórias ordenadas por dependência (esquema → backend → UI)
-
dependsOnconfigurado corretamente para cada história - Gates de qualidade anexados aos critérios de aceitação de cada história
- Histórias de UI têm verificação no navegador (se especificado nos Quality Gates)
- Critérios de aceitação são verificáveis (não vagos)
- Nenhuma dependência circular