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).

Principais Características

• 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

Via npm (Recomendado)

# 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

Via Git

npm install -g github:josmar-oliveira/rwuc

Para desenvolvimento

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.

Opção 1: Texto Livre (User Story)

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

# 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

Opção 2: Markdown Estruturado

Para mais controle, use 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

rw-uc generate --input feature.md

Opção 3: JSON Estruturado (Controle Total)

Para controle total sobre todos os parâmetros:

{
  "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
    }
  ]
}

Opção 4: Documento de Épico

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

# 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:

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

> **Prioridade:** P0
> **Status:** Draft

## 2. User Stories

### 2.1 STORY-01: Título da Story

**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`

Validar a entrada

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

Gerar plano de execução

rw-uc generate --input feature.json --output plan.yaml
# ou
rw-uc generate --text "Criar CRUD de produtos" --output plan.yaml

Executar o pipeline

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:

# 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 <plan> | Executa todas as tasks do plano com Claude Code | | rw-uc-task <plan> <index> | Extrai o prompt de uma task específica | | rw-uc-prompts <plan> | 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:

# 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: <promise>COMPLETE</promise>

Opção 3: Comando Execute (Mock)

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

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 (<promise>COMPLETE</promise>)

# 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: <promise>COMPLETE</promise>

Comandos CLI

rw-uc generate

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

rw-uc generate --input <file> [options]
# ou
rw-uc generate --text "<user story>" [options]

Opções:

• -i, --input <file> - Arquivo de entrada (JSON/YAML/Markdown/TXT)
• -t, --text <story> - User story ou descrição em texto livre
• -e, --epic <file> - Documento de épico (.md)
• -s, --story <id> - ID da story específica (requer --epic)
• -c, --consolidate - Gerar plano único consolidado (com --epic)
• -l, --layer <layer> - Camada de código (ver tabela abaixo)
• -o, --output <file> - 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 <n> - Iterações máximas por task
• --verbose - Output detalhado

Exemplos:

# 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

rw-uc execute

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

rw-uc execute --plan <file> [options]

Opções:

• -p, --plan <file> - Arquivo do plano (default: plan.yaml)
• -t, --task <id> - 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).

rw-uc status

Exibe o status do pipeline atual.

rw-uc status [options]

Opções:

• -t, --task <id> - Status de uma task específica
• --json - Output em formato JSON
• --watch - Monitorar em tempo real

rw-uc validate

Valida um arquivo de entrada ou plano.

rw-uc validate <file> [options]

Opções:

• --verbose - Output detalhado

rw-uc epic

Comandos para trabalhar com documentos de épico.

rw-uc epic list

Lista as user stories de um documento de épico.

rw-uc epic list <epic-file>

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.

rw-uc epic validate <epic-file> [--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.

rw-uc epic status <epic-file>

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%)

rw-uc mcp

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

rw-uc mcp [options]

Opções:

• --transport <type> - Tipo de transporte: stdio (default) ou sse
• -p, --port <number> - Porta para SSE (quando transport=sse)
• --verbose - Log detalhado

rw-uc setup

Configura automaticamente o MCP e subagent rwuc no Claude Code.

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:

# 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).

Configuração

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

rw-uc setup --global

Opção 2: Manual

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

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

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

Tools Disponíveis

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 |

Resources Disponíveis

| 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 |

Exemplo de Uso

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

Subagent RWUC

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:

---
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)

Exemplo de Configuração

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

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

Command

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

File

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

Content

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

Endpoint

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:

CRUD

Detecta padrões CRUD e gera tasks para:

• Entidade/Model
• Repository/DAO
• Service
• Controller/API
• Testes

Refactor

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

Migration

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

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

# 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