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

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

### Via Git

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

### Para desenvolvimento

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

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

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

### Opção 2: Markdown Estruturado

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

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

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
    }
  ]
}
```

### Opção 4: Documento de Épico

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

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

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

### Gerar plano de execução

```bash
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:

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

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

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

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

## Comandos CLI

### `rw-uc generate`

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

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

### `rw-uc execute`

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

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

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

### Configuração

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

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

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

### Exemplo de Configuração

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

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

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

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

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

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

```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](docs/0.%20Especificacao%20Completa%20-%20Framework%20RW-UC.md)
- [Arquitetura Epic Parser](docs/5.%20Arquitetura%20Epic%20Document%20Parser.md)
- [Roadmap](docs/4.%20Roadmap%20de%20Implementacao.md)