RW-UC Framework

Ralph Wiggum - Use Case to Command

Framework para automatização de desenvolvimento de software usando a Metodologia Ralph Wiggum.

Visão Geral

O RW-UC Framework transforma histórias de usuário e requisitos em planos de execução determinísticos que podem ser executados automaticamente por um agente de IA (como Claude Code).

$3

- Decomposição Inteligente: Quebra features complexas em tasks atômicas executáveis
- Critérios Objetivos: Garante que cada task tenha critérios de sucesso verificáveis
- Execução Determinística: Loop de execução com detecção de COMPLETE e stall
- Persistência de Estado: Permite pausar e retomar pipelines
- Git Integrado: Commits automáticos após cada task
- CLI Completo: Interface de linha de comando intuitiva
- Suporte a Épicos: Extrai user stories de documentos de épico e gera planos automaticamente
- MCP Server: Integração nativa com Claude Code via Model Context Protocol

Instalação

$3

``bash


Instalação global (CLI disponível em qualquer lugar)

npm install -g rw-uc
rw-uc --help

Ou localmente em um projeto

npm install rw-uc
npx rw-uc --help
`

$3

`bash
npm install -g github:josmar-oliveira/rwuc
`

$3

`bash
git clone https://github.com/josmar-oliveira/rwuc.git
cd rwuc
npm install
npm link
`

Início Rápido

O framework aceita entradas em diversos formatos: desde texto livre (user stories) até JSON estruturado.

$3

A forma mais simples de usar o framework é com texto livre:

`bash


Via linha de comando

rw-uc generate --text "Como admin, quero cadastrar produtos para que clientes possam comprar"

Ou via arquivo de texto

echo "Criar sistema CRUD de produtos com validação de preço" > story.txt
rw-uc generate --input story.txt
`

O framework analisa automaticamente o texto e:
- Detecta o tipo de ação (CRUD, refactor, fix, etc.)
- Identifica a entidade principal (Produto, Usuário, etc.)
- Infere o contexto tecnológico do projeto atual
- Gera critérios de sucesso apropriados

$3

Para mais controle, use Markdown:

`markdown


Sistema de Autenticação

Objetivo

Implementar login com JWT.

Critérios de Aceitação

- Usuários podem se registrar com email e senha
- Login retorna token JWT válido
- Rotas protegidas validam token

Restrições

- Não usar cookies para tokens
`

`bash
rw-uc generate --input feature.md
`

$3

Para controle total sobre todos os parâmetros:

`json
{
"featureId": "feat-user-crud",
"featureName": "CRUD de Usuários",
"source": { "type": "raw" },
"description": {
"original": "Criar sistema CRUD completo para gerenciamento de usuários"
},
"techContext": {
"language": "TypeScript",
"framework": "Node.js",
"testFramework": "vitest"
},
"scope": { "layer": "backend" },
"successCriteria": [
{
"id": "crit-1",
"description": "API endpoints funcionam corretamente",
"verification": {
"type": "command",
"command": "npm test",
"expectedExitCode": 0
},
"required": true
}
]
}
`

$3

O framework pode processar documentos de épico completos e extrair automaticamente as user stories:

`bash


Listar stories do épico

rw-uc epic list docs/epics/EPIC-ADM-01.md

Gerar planos para todas as stories

rw-uc generate --epic docs/epics/EPIC-ADM-01.md --output plans/

Gerar plano para uma story específica

rw-uc generate --epic docs/epics/EPIC-ADM-01.md --story CAD-01

Gerar plano consolidado (todas as stories em um único plano)

rw-uc generate --epic docs/epics/EPIC-ADM-01.md --consolidate
`

O formato esperado do documento de épico:

`markdown


EPIC-XXX-01: Título do Épico

> Prioridade: P0
> Status: Draft

2. User Stories

$3

Como usuário
Quero realizar uma ação
Para obter um benefício

Critérios de Aceite:
- [ ] Critério 1
- [ ] Critério 2

Endpoints:
- GET /api/resource
- POST /api/resource
`

$3

`bash
rw-uc validate feature.json # ou .md, .txt, .yaml
`

$3

`bash
rw-uc generate --input feature.json --output plan.yaml


ou


rw-uc generate --text "Criar CRUD de produtos" --output plan.yaml
`

$3

O RW-UC gera planos de execução que podem ser executados de diferentes formas:

#### Opção 1: Comandos CLI (Recomendado)

Use os comandos CLI para executar tasks com Claude Code:

`bash


1. Gerar o plano

rw-uc generate --text "Criar CRUD de produtos" --output plan.yaml

2. Extrair o prompt de uma task específica (índice 0, 1, 2...)

rw-uc-task plan.yaml 0

3. Executar todas as tasks automaticamente com Claude Code

rw-uc-run plan.yaml

4. Extrair todos os prompts para um arquivo

rw-uc-prompts plan.yaml > prompts.txt
`

#### Comandos de Execução Disponíveis

| Comando | Descrição |
|---------|-----------|
| rw-uc-run | Executa todas as tasks do plano com Claude Code |
| rw-uc-task | Extrai o prompt de uma task específica |
| rw-uc-prompts | Extrai todos os prompts do plano |

Requisitos:
- Node.js 18+
- Claude Code CLI (npm install -g @anthropic-ai/claude-code)

#### Opção 2: Execução Manual

Para executar manualmente, copie o prompt da task e cole no Claude Code:

`bash


Ver prompt da primeira task

rw-uc-task plan.yaml 0

Cole o prompt no Claude Code e execute

Quando a task completar, o Claude responde com: COMPLETE

`

#### Opção 3: Comando Execute (Mock)

O comando execute atualmente usa um backend de demonstração:

`bash
rw-uc execute --plan plan.yaml
`

> Nota: Este comando usa um backend mock. Para execução real, use rw-uc-run.

#### Estrutura do Prompt de Task

Cada task no plano contém um prompt completo com:
- Objetivo da task
- Contexto técnico (linguagem, framework)
- Instruções específicas
- Critérios de sucesso verificáveis
- Comportamento esperado ao completar (COMPLETE)

`yaml


Exemplo de task no plano

tasks:
- id: crud-bancos-01
name: Criar entidade Bancos
prompt: |
Você está rodando dentro da Metodologia Ralph Wiggum.

## Objetivo
Criar entidade Bancos

## Critérios de Sucesso
- npm run build executa sem erros
- Arquivo src/entities/Bancos.ts existe

## Ao Concluir
Responda com: COMPLETE
`

Comandos CLI

$3

Gera um plano de execução a partir de uma feature ou user story.

`bash
rw-uc generate --input [options]


ou


rw-uc generate --text "" [options]
`

Opções:
- -i, --input - Arquivo de entrada (JSON/YAML/Markdown/TXT)
- -t, --text - User story ou descrição em texto livre
- -e, --epic - Documento de épico (.md)
- -s, --story - ID da story específica (requer --epic)
- -c, --consolidate - Gerar plano único consolidado (com --epic)
- -l, --layer - Camada de código (ver tabela abaixo)
- -o, --output - Arquivo de saída (default: plan.yaml)

Camadas de Código (--layer):

| Layer | Descrição | Exemplo de Artefatos |
|-------|-----------|----------------------|
| backend | API e lógica de negócio | Controllers, Services, Repositories, Entities |
| frontend | Interface do usuário | Components, Pages, Hooks, Stores |
| fullstack | Backend + Frontend | Todos os artefatos acima |
| database | Estrutura de dados | Migrations, Seeds, Schemas |
| infrastructure | DevOps e deploy | Dockerfiles, CI/CD, Terraform |
- --dry-run - Apenas validar, não gerar arquivo
- --max-iterations - Iterações máximas por task
- --verbose - Output detalhado

Exemplos:
`bash


Texto livre inline

rw-uc generate --text "Criar CRUD de produtos" --output plan.yaml

Arquivo texto simples

rw-uc generate --input user-story.txt

Markdown estruturado

rw-uc generate --input feature.md

JSON completo (controle total)

rw-uc generate --input feature.json

Documento de épico (gera múltiplos planos)

rw-uc generate --epic EPIC-01.md --output plans/

Story específica de um épico

rw-uc generate --epic EPIC-01.md --story CAD-01 --output plan.yaml

Gerar para fullstack (backend + frontend)

rw-uc generate --epic EPIC-01.md --layer fullstack --output plans/

Gerar apenas frontend

rw-uc generate --text "Criar tela de cadastro de produtos" --layer frontend
`

$3

Executa um plano de execução (atualmente em modo demonstração).

`bash
rw-uc execute --plan [options]
`

Opções:
- -p, --plan - Arquivo do plano (default: plan.yaml)
- -t, --task - Executar apenas uma task específica
- --interactive - Modo interativo (aprovar cada task)
- --resume - Retomar pipeline pausado
- --dry-run - Simular execução

> Nota: O comando execute usa um backend mock por padrão. Para execução real, use o Ralph Loop (veja seção "Executar o pipeline" acima).

$3

Exibe o status do pipeline atual.

`bash
rw-uc status [options]
`

Opções:
- -t, --task - Status de uma task específica
- --json - Output em formato JSON
- --watch - Monitorar em tempo real

$3

Valida um arquivo de entrada ou plano.

`bash
rw-uc validate [options]
`

Opções:
- --verbose - Output detalhado

$3

Comandos para trabalhar com documentos de épico.

#### rw-uc epic list

Lista as user stories de um documento de épico.

`bash
rw-uc epic list
`

Exemplo de saída:
`
EPIC-ADM-01: Autenticação e Autorização
Priority: P0 | Status: Draft | Sprints: 2

Stories (5):
# ID Title Criteria Endpoints
--- ----------- ------------------------------- --------- ---------
1 AUTH-01 Login de Usuários 6 3
2 AUTH-02 Registro de Usuários 5 2
...
`

#### rw-uc epic validate

Valida a estrutura de um documento de épico.

`bash
rw-uc epic validate [--strict]
`

Opções:
- --strict - Validação rigorosa (verifica endpoints, schemas, etc.)

#### rw-uc epic status

Mostra o progresso de implementação baseado nos checkboxes do épico.

`bash
rw-uc epic status
`

Exemplo de saída:
`
EPIC-ADM-01: Autenticação
Progress: 12/30 criteria completed (40%)

Stories:
AUTH-01 Login ████████░░ 6/8 (75%)
AUTH-02 Registro ██████░░░░ 4/6 (67%)
AUTH-03 Recuperar Senha ░░░░░░░░░░ 0/5 (0%)
`

$3

Inicia o servidor MCP (Model Context Protocol) para integração nativa com Claude Code.

`bash
rw-uc mcp [options]
`

Opções:
- --transport - Tipo de transporte: stdio (default) ou sse
- -p, --port - Porta para SSE (quando transport=sse)
- --verbose - Log detalhado

$3

Configura automaticamente o MCP e subagent rwuc no Claude Code.

`bash
rw-uc setup [options]
`

Opções:
- -g, --global - Usar configuração global (~/.claude.json) para MCP
- -f, --force - Sobrescrever configuração existente
- --mcp-only - Instalar apenas o MCP (sem subagent)
- --agent-only - Instalar apenas o subagent (sem MCP)
- --verbose - Output detalhado

Exemplo:
`bash


Instalar e configurar tudo (MCP + subagent)

npm install -g rw-uc
rw-uc setup --global

Instalar apenas o subagent no projeto atual

rw-uc setup --agent-only

Reiniciar Claude Code para carregar as configurações

`

O comando setup instala:
1. MCP rwuc em ~/.claude.json (com --global) - ferramentas MCP
2. Subagent rwuc em .claude/agents/rwuc.md - agente especializado

Integração com Claude Code (MCP)

O RW-UC Framework oferece integração nativa com Claude Code através do Model Context Protocol (MCP).

$3

Opção 1: Automática (Recomendado)

`bash
rw-uc setup --global
`

Opção 2: Manual

Adicione ao seu arquivo de configuração do Claude Code (~/.claude.json ou .claude/settings.json):

`json
{
"mcpServers": {
"rwuc": {
"command": "rw-uc",
"args": ["mcp"]
}
}
}
`

Após configurar, reinicie o Claude Code para carregar o MCP.

$3

O MCP server expõe 20 tools para Claude Code:

| Tool | Descrição |
|------|-----------|
| normalize_input | Normaliza texto (user story, feature) |
| normalize_file | Normaliza arquivo (JSON/YAML/MD/TXT) |
| generate_plan | Gera plano de execução |
| generate_plan_from_text | Gera plano a partir de texto |
| validate_plan | Valida estrutura do plano |
| validate_input | Valida input normalizado |
| save_plan | Salva plano em arquivo |
| load_plan | Carrega plano de arquivo |
| get_pipeline_status | Status atual do pipeline |
| get_pipeline_progress | Progresso de execução |
| list_completed_tasks | Tasks completadas |
| list_pending_tasks | Tasks pendentes |
| analyze_feature | Analisa feature |
| detect_tech_stack | Detecta stack do projeto |
| decompose_feature | Decompõe em tasks |
| check_eligibility | Verifica elegibilidade |
| git_status | Status do repositório |
| git_diff | Diff de alterações |
| git_log | Histórico de commits |

$3

| URI | Descrição |
|-----|-----------|
| rwuc://plans/active | Plano ativo atual |
| rwuc://plans/list | Lista de planos disponíveis |
| rwuc://state/current | Estado atual do pipeline |
| rwuc://state/progress | Progresso resumido |
| rwuc://templates/list | Templates disponíveis |
| rwuc://config/current | Configuração atual |

$3

Após configurar, você pode usar comandos naturais no Claude Code:

`
> Use rwuc para gerar um plano a partir desta feature: "Adicionar autenticação JWT"

> Qual o status atual do pipeline?

> Detecte a stack tecnológica deste projeto
`

$3

O framework também inclui um subagent especializado para Claude Code que automatiza o fluxo de geração de planos.

#### Configuração do Subagent

Adicione o arquivo .claude/agents/rwuc.md no seu projeto:

`yaml
---
name: rwuc
description: Agente especializado em gerar e gerenciar planos de execução RW-UC
tools: Read, Write, Bash, Glob, Grep, mcp__rwuc__*
model: sonnet
---
`

#### Capacidades do Subagent

| Capacidade | Ferramentas MCP |
|------------|-----------------|
| Geração de Planos | generate_plan_from_text, generate_plan, save_plan |
| Monitoramento | get_pipeline_status, get_pipeline_progress, list_*_tasks |
| Análise | analyze_feature, decompose_feature, check_eligibility |
| Arquivos | load_plan, save_plan, normalize_file |
| Git | git_status, git_diff, git_log |

#### Fluxo Automático

Quando você descreve uma feature, o subagent:

`
1. Detecta o tech stack do projeto
2. Gera o plano de execução
3. Valida a estrutura do plano
4. Salva em plan.yaml
5. Sugere o comando de execução
`

#### Exemplos de Interação

`
> Criar CRUD de produtos com nome, preço e categoria

🔍 Tech Stack: TypeScript, npm, Vitest
📋 Plano gerado: 5 tasks (heurística CRUD)
1. Criar entidade Produtos
2. Criar repositório Produtos
3. Criar service Produtos
4. Criar testes
5. Criar API REST

💾 Salvo em: plan.yaml
▶️ Execute: rw-uc-run plan.yaml
`

`
> Como está o pipeline?

📊 Pipeline: pipe-xxx-xxx
✅ Completadas: 3/5
⏳ Pendentes: 2
❌ Falhas: 0
`

Configuração

O framework pode ser configurado através de arquivos YAML:

- Global: ~/.rwuc/config.yaml
- Local: .rwuc/config.yaml (no diretório do projeto)

$3

`yaml
execution:
defaultMaxIterations: 30
globalTimeoutMinutes: 60
failFast: true

git:
autoCommit: true
commitPrefix: "ralph/"

logging:
level: info
enableFile: false

output:
colors: true
verbose: false
`

Estrutura do Plano de Execução

`yaml
pipelineId: pipe-xxx-xxx
featureId: feat-xxx
featureName: "Nome da Feature"
config:
defaultMaxIterations: 30
failFast: true
autoCommit: true
tasks:
- id: task-001
name: "Criar entidade"
order: 1
dependencies: []
maxIterations: 20
criteria:
- id: crit-1
description: "Build passa"
verification:
type: command
command: "npm run build"
expectedExitCode: 0
prompt: |
Você está rodando dentro da Metodologia Ralph Wiggum.
...
`

Tipos de Critérios

$3


`yaml
verification:
type: command
command: "npm test"
expectedExitCode: 0
`

$3

`yaml
verification:
type: file
path: "src/entity.ts"
shouldExist: true
`

$3

`yaml
verification:
type: content
path: "src/entity.ts"
pattern: "class Entity"
`

$3

`yaml
verification:
type: endpoint
url: "http://localhost:3000/api/users"
method: "GET"
expectedStatus: 200
`

Heurísticas de Decomposição

O framework usa heurísticas inteligentes para decompor features:

$3

Detecta padrões CRUD e gera tasks para:
- Entidade/Model
- Repository/DAO
- Service
- Controller/API
- Testes

$3

Detecta refatorações e gera tasks para:
- Testes de caracterização
- Extração de código
- Injeção de dependência
- Remoção de duplicação
- Limpeza

$3

Detecta migrações e gera tasks para:
- Adapter
- Nova implementação
- Testes paralelos
- Switch de implementação
- Remoção de código legado

API Programática

`typescript
import {
createInputNormalizer,
createPlan,
createExecutionController,
} from 'rw-uc';

// Normalizar input
const normalizer = createInputNormalizer();
const result = normalizer.normalizeFile('feature.json');

if (result.success) {
// Criar plano
const plan = createPlan(result.input);

// Executar
const controller = createExecutionController({
workingDirectory: process.cwd(),
backend: myBackend, // Implementação do ExecutionBackend
});

const pipelineResult = await controller.executePipeline(plan);
}
`

Requisitos

- Node.js 18+
- Git (para commits automáticos)

Desenvolvimento

`bash


Clonar repositório

git clone https://github.com/josmar-oliveira/rwuc.git
cd rwuc

Instalar dependências

npm install

Build

npm run build

Testes

npm test

Lint

npm run lint
``

Licença

MIT

Links

- Documentação Completa
- Arquitetura Epic Parser
- Roadmap