@the-bearded-bear/claude-craft 3.0.3-next.d0d2746 → 3.1.0-next.a356bbd

package/Dev/i18n/pt/Common/agents/ralph-conductor.md

@@ -0,0 +1,146 @@
+---
+name: ralph-conductor
+description: Orquestra sessoes de loop continuo Ralph Wiggum com validacao DoD
+---
+
+# Agente Ralph Conductor
+
+Voce e um agente especializado para orquestrar sessoes de loop continuo Ralph Wiggum. Seu papel e guiar tarefas atraves da execucao iterativa do Claude ate que os criterios de Definition of Done (DoD) sejam atendidos.
+
+## Responsabilidades Principais
+
+### 1. Gerenciamento de Sessao
+- Inicializar sessoes Ralph com configuracao apropriada
+- Acompanhar progresso de iteracoes e metricas
+- Gerenciar estado de sessao e recuperacao
+
+### 2. Validacao Definition of Done
+- Avaliar criterios DoD em cada iteracao
+- Fornecer feedback sobre criterios aprovados/reprovados
+- Sugerir acoes corretivas quando criterios falham
+
+### 3. Monitoramento do Disjuntor
+- Monitorar condicoes de estagnacao (sem progresso)
+- Detectar loops de erro e falhas repetidas
+- Recomendar parar quando apropriado
+
+### 4. Avaliacao de Progresso
+- Avaliar se progresso significativo esta sendo feito
+- Identificar quando tarefas estao bloqueadas
+- Sugerir abordagens alternativas quando necessario
+
+## Modo de Trabalho
+
+Ao orquestrar uma sessao Ralph:
+
+1. **Avaliacao Inicial**
+   - Entender requisitos da tarefa
+   - Identificar criterios de sucesso
+   - Configurar checklist DoD apropriada
+
+2. **Guia de Iteracao**
+   - Fornecer prompts claros e acionaveis
+   - Focar em um objetivo por vez
+   - Construir incrementalmente sobre progresso anterior
+
+3. **Portoes de Qualidade**
+   - Verificar que testes passam antes de continuar
+   - Checar metricas de qualidade de codigo
+   - Validar atualizacoes de documentacao
+
+4. **Sinais de Conclusao**
+   - Indicar claramente quando DoD e atingido
+   - Usar marcador de conclusao: `<promise>COMPLETE</promise>`
+   - Resumir o que foi realizado
+
+## Tipos de Validadores DoD
+
+| Tipo | Quando Usar |
+|------|-------------|
+| `command` | Executar testes, linting, build |
+| `output_contains` | Verificar marcadores de conclusao |
+| `file_changed` | Verificar atualizacoes de documentacao |
+| `hook` | Integrar com portoes de qualidade existentes |
+| `human` | Decisoes criticas que requerem aprovacao |
+
+## Boas Praticas
+
+### Decomposicao de Tarefas
+Decompor tarefas complexas em passos menores e verificaveis:
+1. Escrever teste que falha primeiro (VERMELHO)
+2. Implementar codigo minimo para passar (VERDE)
+3. Refatorar mantendo testes verdes (REFATORAR)
+4. Atualizar documentacao
+5. Sinalizar conclusao
+
+### Indicadores de Progresso
+Incluir marcadores de progresso claros na saida:
+- `[PROGRESSO]` - Fazendo progresso
+- `[BLOQUEADO]` - Obstaculo encontrado
+- `[TESTING]` - Executando verificacao
+- `[COMPLETO]` - Tarefa finalizada
+
+### Tratamento de Erros
+Ao encontrar erros:
+1. Descrever o erro claramente
+2. Analisar causa raiz
+3. Propor solucao
+4. Implementar correcao
+5. Verificar resolucao
+
+## Exemplo de Fluxo de Sessao
+
+```
+Sessao: ralph-1704067200-a1b2
+Tarefa: Implementar autenticacao de usuario
+
+Iteracao 1:
+[PROGRESSO] Analisando estrutura de codigo existente
+- Entidade User encontrada
+- Servico de autenticacao precisa ser criado
+- Diretorio de testes pronto
+
+Iteracao 2:
+[TESTING] Escrevendo testes de autenticacao
+- Criado AuthServiceTest.php
+- 3 casos de teste: login, logout, validateToken
+- Testes atualmente FALHANDO (esperado)
+
+Iteracao 3:
+[PROGRESSO] Implementando AuthService
+- Criado AuthService.php
+- Implementada geracao de token JWT
+- Testes agora PASSANDO
+
+Iteracao 4:
+[PROGRESSO] Atualizando documentacao
+- Secao de autenticacao adicionada ao README
+- Endpoints de API documentados
+
+<promise>COMPLETE</promise>
+
+Resumo:
+- AuthService criado com suporte JWT
+- 3 testes passando
+- Documentacao atualizada
+```
+
+## Pontos de Integracao
+
+- Funciona com comando `/common:ralph-run`
+- Integra com hooks existentes (quality-gate.sh)
+- Compativel com workflow `/project:sprint-dev`
+- Usa principios do `@tdd-coach`
+
+## Quando Parar
+
+Sinalizar conclusao e parar iteracoes quando:
+1. Todos os criterios DoD obrigatorios passam
+2. Objetivos da tarefa completamente atingidos
+3. Testes verificam funcionalidade
+4. Documentacao atualizada
+
+NAO continuar se:
+- Limites do disjuntor atingidos
+- Falhas repetidas indicam problema fundamental
+- Intervencao humana necessaria

package/Dev/i18n/pt/Common/commands/ralph-run.md

@@ -0,0 +1,171 @@
+---
+description: Executar Claude em loop continuo ate completar tarefa (Ralph Wiggum)
+argument-hint: <descricao-tarefa> [--auto|--full]
+---
+
+# Ralph Run - Loop Continuo de Agente IA
+
+Executar Claude em loop continuo ate que a tarefa esteja completa ou os criterios de Definition of Done (DoD) sejam atendidos.
+
+## Argumentos
+
+**$ARGUMENTS**
+
+- `<descricao-tarefa>`: A tarefa para Claude completar
+- `--auto`: Deteccao automatica maxima, perguntas minimas
+- `--full`: Modo completo com todas as verificacoes DoD
+
+## Processo
+
+### 1. Inicializacao de Sessao
+
+1. **Verificar pre-requisitos**:
+   - Verificar se Claude esta disponivel
+   - Procurar configuracao `ralph.yml`
+   - Inicializar diretorio de sessao (`.ralph/`)
+
+2. **Carregar configuracao**:
+   - Ler `ralph.yml` ou `.claude/ralph.yml`
+   - Definir iteracoes max, timeouts, criterios DoD
+
+### 2. Loop Principal
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  LOOP RALPH                                                  │
+│                                                              │
+│  while (iteracoes < max && !DoD_aprovado) {                  │
+│      1. Verificar disjuntor                                  │
+│      2. Invocar Claude com prompt atual                      │
+│      3. Processar saida                                      │
+│      4. Validar Definition of Done                           │
+│      5. Criar checkpoint (commit git)                        │
+│      6. Se DoD nao atendido, usar resposta como prompt       │
+│  }                                                           │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 3. Validacao Definition of Done
+
+O sistema DoD valida conclusao atraves de multiplos criterios:
+
+| Validador | Descricao |
+|-----------|-----------|
+| `command` | Executar comando shell (tests, lint, build) |
+| `output_contains` | Verificar padrao na saida do Claude |
+| `file_changed` | Verificar se arquivos foram modificados |
+| `hook` | Executar hook Claude existente |
+| `human` | Validacao humana interativa |
+
+Exemplo DoD em `ralph.yml`:
+
+```yaml
+definition_of_done:
+  checklist:
+    - id: tests
+      name: "Todos os testes passam"
+      type: command
+      command: "docker compose exec app npm test"
+      required: true
+
+    - id: completion
+      name: "Claude sinaliza conclusao"
+      type: output_contains
+      pattern: "<promise>COMPLETE</promise>"
+      required: true
+```
+
+### 4. Disjuntor (Circuit Breaker)
+
+Mecanismo de seguranca para prevenir loops infinitos:
+
+| Gatilho | Limite | Acao |
+|---------|--------|------|
+| Sem alteracoes de arquivos | 3 iteracoes | Parar |
+| Erros repetidos | 5 iteracoes | Parar |
+| Declinio de saida | 70% | Parar |
+| Max iteracoes | 25 (padrao) | Parar |
+
+### 5. Checkpointing
+
+Checkpoints Git sao criados apos cada iteracao para:
+- **Recuperacao**: Restaurar estado anterior se necessario
+- **Historico**: Acompanhar progresso atraves das iteracoes
+- **Revisao**: Inspecionar o que mudou em cada passo
+
+## Saida
+
+```
+╔════════════════════════════════════════════════════════════╗
+║     🔁 Ralph Wiggum - Loop Continuo de Agente IA            ║
+╚════════════════════════════════════════════════════════════╝
+
+✓ Sessao criada: ralph-1704067200-a1b2
+
+ℹ Iniciando loop Ralph...
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Iteracao 1 de 25
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+ℹ Invocando Claude...
+ℹ Verificando criterios DoD...
+  ✓ [tests] Todos os testes passam - OK
+  ✓ [lint] Sem erros lint - OK
+  ✓ [completion] Claude sinaliza conclusao - OK
+
+  Todos os criterios obrigatorios aprovados!
+
+✓ DoD APROVADO
+
+╔════════════════════════════════════════════════════════════╗
+║     📊 Resumo da Sessao                                     ║
+╚════════════════════════════════════════════════════════════╝
+
+  ID da sessao:        ralph-1704067200-a1b2
+  Total de iteracoes:  3
+  Duracao:             45s
+  Status DoD:          APROVADO
+  Motivo de saida:     dod_complete
+```
+
+## Configuracao
+
+Criar `ralph.yml` na raiz do projeto:
+
+```yaml
+version: "1.0"
+
+session:
+  max_iterations: 25
+  timeout: 600000
+
+circuit_breaker:
+  enabled: true
+  no_file_changes_threshold: 3
+
+definition_of_done:
+  checklist:
+    - id: tests
+      type: command
+      command: "npm test"
+      required: true
+    - id: completion
+      type: output_contains
+      pattern: "<promise>COMPLETE</promise>"
+      required: true
+```
+
+## Boas Praticas
+
+1. **Descricao clara**: Fornecer tarefas especificas e acionaveis
+2. **Configurar DoD**: Definir criterios de conclusao em `ralph.yml`
+3. **Usar TDD**: Escrever testes primeiro, deixar Ralph implementar
+4. **Monitorar progresso**: Observar saidas de iteracao
+5. **Limites razoaveis**: Ajustar max_iterations conforme complexidade
+
+## Ver tambem
+
+- `@ralph-conductor` - Agente para orquestracao Ralph
+- `/common:fix-bug-tdd` - Correcao de bugs com TDD
+- `/project:sprint-dev` - Desenvolvimento de sprint com TDD

package/Tools/Ralph/README.md

@@ -0,0 +1,303 @@
+# Ralph Wiggum - Continuous AI Agent Loop
+
+Ralph Wiggum is a methodology and tool for running Claude in a continuous loop until a task is complete. It provides structured completion detection through Definition of Done (DoD) validation, safety mechanisms via circuit breakers, and progress tracking through git checkpoints.
+
+## Overview
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  RALPH LOOP                                                  │
+│                                                              │
+│  while (iterations < max && !complete) {                     │
+│      response = claude("--continue", session_id, prompt)     │
+│      complete = checkDoD(response)                           │
+│      if (circuitBreaker.triggered()) break                   │
+│      createCheckpoint(iteration)                             │
+│      prompt = response  // feedback loop                     │
+│  }                                                           │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Quick Start
+
+### Via CLI
+
+```bash
+# Basic usage
+npx @the-bearded-bear/claude-craft ralph "Implement user authentication"
+
+# With configuration
+npx @the-bearded-bear/claude-craft ralph --config=ralph.yml "Fix the login bug"
+
+# Resume session
+npx @the-bearded-bear/claude-craft ralph --continue=ralph-1704067200-a1b2
+```
+
+### Via Command in Claude Code
+
+```bash
+/common:ralph-run "Implement user authentication"
+```
+
+### Direct Script
+
+```bash
+./Tools/Ralph/ralph.sh "Implement user authentication"
+./Tools/Ralph/ralph.sh --lang=fr --verbose "Corriger le bug de connexion"
+```
+
+## Configuration
+
+Create `ralph.yml` in your project root or `.claude/ralph.yml`:
+
+```yaml
+version: "1.0"
+
+session:
+  max_iterations: 25
+  timeout: 600000  # 10 minutes per iteration
+  delay_between_iterations: 1000
+
+circuit_breaker:
+  enabled: true
+  no_file_changes_threshold: 3
+  repeated_error_threshold: 5
+  output_decline_threshold: 70
+
+checkpointing:
+  enabled: true
+  async: true
+  branch_prefix: "ralph/"
+
+definition_of_done:
+  checklist:
+    - id: tests
+      name: "All tests pass"
+      type: command
+      command: "docker compose exec app npm test"
+      required: true
+
+    - id: lint
+      name: "No lint errors"
+      type: command
+      command: "docker compose exec app npm run lint"
+      required: true
+
+    - id: completion
+      name: "Claude signals completion"
+      type: output_contains
+      pattern: "<promise>COMPLETE</promise>"
+      required: true
+```
+
+## Definition of Done (DoD)
+
+The key improvement over simple completion markers. DoD validates task completion through multiple criteria:
+
+### Validator Types
+
+| Type | Description | Example |
+|------|-------------|---------|
+| `command` | Run shell command, check exit code | `npm test` |
+| `output_contains` | Check Claude output for pattern | `<promise>COMPLETE</promise>` |
+| `file_changed` | Check if files matching pattern changed | `*.md` |
+| `hook` | Run existing Claude hook script | `quality-gate.sh` |
+| `human` | Prompt user for confirmation | Interactive gate |
+
+### Example Checklist
+
+```yaml
+definition_of_done:
+  checklist:
+    # Automated tests
+    - id: tests
+      name: "All tests pass"
+      type: command
+      command: "docker compose exec app npm test"
+      required: true
+
+    # Code quality
+    - id: lint
+      name: "No lint errors"
+      type: command
+      command: "docker compose exec app npm run lint"
+      required: true
+
+    # Completion signal
+    - id: completion
+      name: "Claude signals completion"
+      type: output_contains
+      pattern: "<promise>COMPLETE</promise>"
+      required: true
+
+    # Integration with existing hooks
+    - id: quality_gate
+      name: "Quality gate passes"
+      type: hook
+      script: ".claude/hooks/quality-gate.sh"
+      required: true
+
+    # Documentation (optional)
+    - id: docs
+      name: "Documentation updated"
+      type: file_changed
+      pattern: "*.md"
+      required: false
+
+    # Human approval (optional)
+    - id: review
+      name: "Manual review approved"
+      type: human
+      prompt: "Does the implementation look correct? (y/n):"
+      required: false
+```
+
+## Circuit Breaker
+
+Safety mechanism to prevent infinite loops:
+
+| Trigger | Default Threshold | Description |
+|---------|-------------------|-------------|
+| No file changes | 3 iterations | Stops if no files modified |
+| Repeated errors | 5 iterations | Stops on error loops |
+| Output decline | 70% | Stops if output shrinks significantly |
+| Max iterations | 25 | Hard limit |
+
+## Git Checkpointing
+
+Automatic git commits after each iteration:
+
+- **Recovery**: Restore to previous state if needed
+- **History**: Track progress through iterations
+- **Review**: Inspect what changed at each step
+
+Configuration:
+
+```yaml
+checkpointing:
+  enabled: true
+  async: true  # Non-blocking
+  branch_prefix: "ralph/"
+  commit_message_template: "checkpoint: Ralph iteration {iteration}"
+```
+
+## File Structure
+
+```
+Tools/Ralph/
+├── ralph.sh                    # Main entry point
+├── lib/
+│   ├── session.sh              # Session management
+│   ├── loop.sh                 # Core iteration loop
+│   ├── dod-validator.sh        # DoD validation
+│   ├── circuit-breaker.sh      # Safety mechanism
+│   └── checkpoint.sh           # Git checkpointing
+├── templates/
+│   └── ralph.yml.template      # Default configuration
+└── README.md                   # This file
+
+Tools/i18n/ralph/
+├── en.sh                       # English messages
+├── fr.sh                       # French messages
+├── es.sh                       # Spanish messages
+├── de.sh                       # German messages
+└── pt.sh                       # Portuguese messages
+```
+
+## CLI Options
+
+```
+ralph.sh [options] <prompt>
+
+Options:
+  --config=<file>       Path to ralph.yml configuration
+  --continue=<id>       Resume existing session
+  --max-iterations=<n>  Maximum iterations (default: 25)
+  --timeout=<ms>        Timeout per iteration (default: 600000)
+  --verbose             Enable verbose output
+  --dry-run             Show what would be done without executing
+  --lang=<code>         Language (en, fr, es, de, pt)
+  --help                Show help message
+```
+
+## Integration
+
+### With Existing Hooks
+
+Ralph can leverage existing Claude hooks:
+
+```yaml
+definition_of_done:
+  checklist:
+    - id: quality_gate
+      type: hook
+      script: ".claude/hooks/quality-gate.sh"
+      required: true
+```
+
+### With Sprint Development
+
+```bash
+# In sprint workflow
+/project:sprint-dev 1
+# Ralph handles each task until DoD passes
+```
+
+### With TDD Coach
+
+Ralph follows TDD principles:
+1. Write failing test (RED)
+2. Implement minimum code to pass (GREEN)
+3. Refactor while keeping tests green (REFACTOR)
+
+## Session Files
+
+Ralph creates a `.ralph/` directory in your project:
+
+```
+.ralph/
+├── sessions/
+│   └── ralph-1704067200-a1b2/
+│       ├── state.json          # Session state
+│       ├── metrics.json        # Iteration metrics
+│       ├── session.log         # Execution log
+│       └── last_output.txt     # Last Claude response
+```
+
+## Best Practices
+
+1. **Clear task description**: Provide specific, actionable tasks
+2. **Configure DoD**: Define completion criteria in `ralph.yml`
+3. **Use TDD**: Write tests first, let Ralph implement
+4. **Monitor progress**: Watch iteration output for issues
+5. **Set reasonable limits**: Adjust max_iterations for task complexity
+6. **Use Docker**: Run commands in Docker for consistency
+
+## Troubleshooting
+
+### Ralph stops immediately
+- Check if prompt is provided
+- Verify `ralph.yml` is valid YAML
+
+### Circuit breaker triggers too early
+- Increase thresholds in configuration
+- Check if task is making actual progress
+
+### DoD never passes
+- Verify commands work manually
+- Check required vs optional criteria
+- Ensure completion marker is output by Claude
+
+## Related
+
+- `/common:ralph-run` - Command to start Ralph from Claude Code
+- `@ralph-conductor` - Agent for Ralph orchestration
+- `/common:fix-bug-tdd` - TDD-based bug fixing
+- `/project:sprint-dev` - Sprint development with TDD
+
+## Credits
+
+Inspired by:
+- [anthropics/claude-code/plugins/ralph-wiggum](https://github.com/anthropics/claude-code)
+- [frankbria/ralph-claude-code](https://github.com/frankbria/ralph-claude-code)
+- [mikeyobrien/ralph-orchestrator](https://github.com/mikeyobrien/ralph-orchestrator)