Skip to content

PRD.md

Latest commit

 

History

History
522 lines (422 loc) · 15 KB

PRD.md

File metadata and controls

522 lines (422 loc) · 15 KB

LoopForge - Product Requirements Document

Uma CLI em Go para autonomous coding loops, inspirada no Ralph mas melhor arquitetada.

Visão Geral

LoopForge é uma ferramenta que orquestra agentes de código (Claude Code, Codex, OpenCode, etc.) em loops iterativos baseados em arquivos. Cada iteração trabalha em uma story por vez, commita o progresso, e mantém estado persistente para aprendizado contínuo.

Filosofia Core:

  • Arquivos e git são memória, não o contexto do modelo
  • Uma story por iteração (contexto limpo)
  • Commits granulares (rollback fácil)
  • Guardrails persistentes (aprendizado acumulativo)

Problemas que Resolve

  1. Context Pollution - Conversas longas poluem o contexto do LLM
  2. Falta de Estrutura - Prompts grandes sem organização
  3. Commits Gigantes - Difícil fazer rollback
  4. Perda de Aprendizado - Erros não informam futuras iterações
  5. Falta de Validação - UI não é testada automaticamente

Usuários Alvo

  • Desenvolvedores usando agentes de código (Claude Code, Codex, etc.)
  • Times que querem automação de desenvolvimento
  • Projetos que precisam de auditoria (commits granulares)

Requisitos Funcionais

RF01 - Geração de PRD

Comando: loopforge prd

O sistema deve gerar um PRD estruturado em JSON a partir de uma descrição:

loopforge prd "Sistema de autenticação com OAuth2"
loopforge prd --file requirements.txt
loopforge prd --interactive  # modo pergunta-resposta

PRD JSON Schema:

{
  "version": 1,
  "project": "string",
  "overview": "string",
  "goals": ["string"],
  "nonGoals": ["string"],
  "stack": {
    "language": "string",
    "framework": "string",
    "database": "string"
  },
  "qualityGates": ["string"],
  "stories": [
    {
      "id": "US-001",
      "title": "string",
      "status": "open|in_progress|done|blocked",
      "dependsOn": ["US-000"],
      "description": "string",
      "acceptanceCriteria": ["string"],
      "estimatedMinutes": 30,
      "startedAt": "ISO8601",
      "completedAt": "ISO8601"
    }
  ]
}

Funcionalidades:

  • Modo interativo com perguntas clarificadoras
  • Modo não-interativo com prompt direto
  • Leitura de arquivo de requisitos
  • Validação de schema JSON
  • Auto-numeração de stories (US-001, US-002, ...)
  • Detecção automática de dependências entre stories

RF02 - Loop de Execução

Comando: loopforge build [iterations]

loopforge build           # executa até completar (max 25)
loopforge build 5         # executa 5 iterações
loopforge build --dry-run # simula sem executar agente
loopforge build --no-commit # não commita mudanças

Fluxo por Iteração:

  1. Selecionar próxima story open (respeitando dependências)
  2. Marcar como in_progress
  3. Renderizar prompt com contexto
  4. Executar agente
  5. Detectar sinal de conclusão
  6. Se completo: marcar done, commitar
  7. Se falhou: resetar para open, logar erro
  8. Atualizar progress.md
  9. Repetir

Funcionalidades:

  • Seleção inteligente de stories (dependências, prioridade)
  • Lock otimista para execução concorrente
  • Timeout configurável por story
  • Retry automático com backoff
  • Detecção de stories "stale" (in_progress por muito tempo)
  • Interrupção limpa (SIGINT/SIGTERM)

RF03 - Gerenciamento de Agentes

Comando: loopforge agent

loopforge agent list              # lista agentes disponíveis
loopforge agent set claude        # define agente padrão
loopforge agent test              # testa conexão com agente

Agentes Suportados:

  • Claude Code (claude)
  • OpenAI Codex (codex)
  • OpenCode (opencode)
  • Factory Droid (droid)
  • Custom (configurável)

Configuração:

# .loopforge/config.yaml
agent:
  name: claude
  command: "claude -p --dangerously-skip-permissions"
  inputMode: file  # stdin | file | arg
  completionSignal: "<promise>COMPLETE</promise>"
  timeout: 30m

RF04 - Sistema de State

Diretório: .loopforge/

.loopforge/
├── config.yaml        # Configuração
├── progress.md        # Log de progresso
├── guardrails.md      # Signs/lições aprendidas
├── errors.log         # Falhas para análise
├── activity.log       # Timeline de eventos
├── context.log        # Tracking de contexto
└── runs/
    ├── run-20260123-143022-001.log
    └── run-20260123-143022-001.meta.json

Funcionalidades:

  • Inicialização automática
  • Migração de versões de config
  • Backup antes de operações destrutivas
  • Cleanup de runs antigos

RF05 - Sistema de Guardrails

Comando: loopforge guardrail

loopforge guardrail list          # lista guardrails ativos
loopforge guardrail add           # adiciona novo (interativo)
loopforge guardrail disable ID    # desabilita temporariamente
loopforge guardrail export        # exporta para compartilhar

Schema de Guardrail:

- id: GR-001
  name: "Read Before Writing"
  trigger: "Before modifying any file"
  instruction: "Read the file first to understand context"
  severity: warning  # info | warning | error
  addedAfter: "Iteration 3 - overwrote important code"
  enabled: true

Funcionalidades:

  • Guardrails built-in (core)
  • Guardrails customizados por projeto
  • Sugestão automática baseada em erros
  • Injeção no prompt do agente

RF06 - Templates de Prompt

Comando: loopforge template

loopforge template list           # lista templates
loopforge template show build     # mostra template
loopforge template edit build     # edita template
loopforge template reset          # restaura defaults

Templates Built-in:

  • build.md - Prompt principal de build
  • prd.md - Prompt para geração de PRD
  • review.md - Prompt para code review
  • refactor.md - Prompt para refatoração

Variáveis de Template:

  • {{.PRD}} - Caminho do PRD
  • {{.Story}} - Story atual (JSON)
  • {{.Guardrails}} - Conteúdo de guardrails.md
  • {{.Progress}} - Últimas N entradas de progress
  • {{.QualityGates}} - Quality gates do PRD
  • {{.RunID}} - ID único da execução
  • {{.Iteration}} - Número da iteração

RF07 - Quality Gates

Funcionalidades:

  • Execução de comandos de validação
  • Parsing de output (PASS/FAIL)
  • Blocking gates (impedem conclusão)
  • Warning gates (logam mas não bloqueiam)
  • Gates customizados por story
qualityGates:
  - name: tests
    command: "go test ./..."
    blocking: true
  - name: lint
    command: "golangci-lint run"
    blocking: false
  - name: build
    command: "go build ./..."
    blocking: true

RF08 - Integração com Browser (Opcional)

Comando: loopforge browser

loopforge browser start           # inicia servidor
loopforge browser stop            # para servidor
loopforge browser snapshot page   # captura ARIA snapshot
loopforge browser screenshot page # captura screenshot

Funcionalidades:

  • Servidor de automação Playwright-based
  • ARIA snapshots para descoberta de elementos
  • Screenshots para validação visual
  • Integração com stories de frontend

RF09 - Reporting

Comando: loopforge report

loopforge report                  # sumário do projeto
loopforge report --format json    # output JSON
loopforge report --html report.html  # gera HTML

Métricas:

  • Stories totais/completas/pendentes
  • Tempo médio por story
  • Taxa de sucesso por iteração
  • Erros mais comuns
  • Guardrails mais acionados

RF10 - Watch Mode

Comando: loopforge watch

loopforge watch                   # monitora PRD e executa quando muda
loopforge watch --auto-build      # auto-executa build em mudanças

Requisitos de Testes

RT01 - Testes Unitários

Cada pacote deve ter cobertura de testes unitários:

  • internal/prd/ - Parser e validação de PRD (100% coverage)
  • internal/core/ - Seleção de stories, template engine (90%+ coverage)
  • internal/config/ - Carregamento e validação de config (90%+ coverage)
  • internal/guardrail/ - CRUD de guardrails (90%+ coverage)

Convenções:

  • Arquivos de teste: *_test.go no mesmo pacote
  • Table-driven tests sempre que possível
  • Mocks para dependências externas (filesystem, agentes)

RT02 - Testes de Integração com Agentes

Interface abstrata Agent permite testar e adicionar novos agentes:

type Agent interface {
    Name() string
    IsAvailable() bool
    Run(ctx context.Context, prompt string) (AgentResult, error)
}

type AgentResult struct {
    Output       string
    ExitCode     int
    Completed    bool  // detectou sinal de conclusão
    Duration     time.Duration
}

Testes de integração:

  • tests/integration/agent_test.go - Testa interface com mock agent
  • tests/integration/claude_test.go - Testa Claude Code real (skip se não disponível)
  • tests/integration/e2e_test.go - Fluxo completo init→prd→build

Mock Agent para CI:

type MockAgent struct {
    Responses []string  // respostas pré-definidas
    Delay     time.Duration
}

RT03 - Coverage Mínimo

  • Unitários: 80% overall
  • Pacotes críticos (prd, core): 90%
  • CI falha se coverage cair

Requisitos Não-Funcionais

RNF01 - Performance

  • Startup em < 100ms
  • Overhead mínimo por iteração (< 1s)
  • Binário < 20MB

RNF02 - Portabilidade

  • Single binary (sem dependências runtime)
  • Cross-platform: Linux, macOS, Windows
  • ARM64 e AMD64

RNF03 - Usabilidade

  • Colorized output
  • Progress bars para operações longas
  • Mensagens de erro claras com sugestões
  • Autocompletion para shells (bash, zsh, fish)

RNF04 - Extensibilidade

  • Plugins para novos agentes
  • Hooks pre/post iteração
  • API programática (biblioteca Go)

RNF05 - Confiabilidade

  • Graceful shutdown
  • Lock files para operações concorrentes
  • Journaling para recovery

Arquitetura Proposta

cmd/
├── loopforge/
│   └── main.go           # Entry point
internal/
├── cli/
│   ├── root.go           # Cobra root command
│   ├── prd.go            # prd command
│   ├── build.go          # build command
│   ├── agent.go          # agent command
│   ├── guardrail.go      # guardrail command
│   └── ...
├── core/
│   ├── loop.go           # Main loop logic
│   ├── story.go          # Story selection/management
│   ├── state.go          # State management
│   └── template.go       # Template rendering
├── agent/
│   ├── interface.go      # Agent interface
│   ├── claude.go         # Claude implementation
│   ├── codex.go          # Codex implementation
│   └── custom.go         # Custom agent
├── prd/
│   ├── generator.go      # PRD generation
│   ├── parser.go         # PRD parsing
│   └── validator.go      # Schema validation
├── guardrail/
│   ├── manager.go        # Guardrail management
│   └── builtin.go        # Built-in guardrails
├── browser/
│   ├── server.go         # Browser automation server
│   └── snapshot.go       # ARIA snapshot
└── config/
    ├── config.go         # Configuration
    └── defaults.go       # Default values

Dependências:

  • cobra - CLI framework
  • viper - Configuration
  • go-git - Git operations
  • chromedp - Browser automation
  • zerolog - Logging
  • lipgloss - Terminal styling

Stories de Implementação

Fase 1: Core (MVP)

ID Título Dependências Estimativa
US-001 Scaffold projeto Go com estrutura de diretórios - 30min
US-002 CLI base com Cobra (root, version, help) US-001 30min
US-003 Sistema de configuração com Viper US-002 45min
US-004 Estrutura de state (.loopforge/) US-003 30min
US-005 Parser de PRD JSON US-004 45min
US-006 Seleção de stories (dependências, status) US-005 1h
US-007 Interface de agente + implementação Claude US-003 1h
US-008 Template engine para prompts US-004 45min
US-009 Loop principal de build US-006, US-007, US-008 2h
US-010 Comando build completo US-009 1h

Fase 2: PRD & Guardrails

ID Título Dependências Estimativa
US-011 Gerador de PRD interativo US-010 2h
US-012 Comando prd US-011 30min
US-013 Sistema de guardrails US-004 1h
US-014 Guardrails built-in US-013 45min
US-015 Comando guardrail US-013 30min

Fase 3: Agentes & Quality

ID Título Dependências Estimativa
US-016 Implementação Codex US-007 30min
US-017 Implementação OpenCode US-007 30min
US-018 Agente customizado US-007 45min
US-019 Comando agent US-016, US-017, US-018 30min
US-020 Quality gates execution US-010 1h
US-021 Progress tracking (progress.md) US-010 45min

Fase 4: Polish

ID Título Dependências Estimativa
US-022 Colorized output com lipgloss US-010 45min
US-023 Shell autocompletion US-002 30min
US-024 Comando report US-021 1h
US-025 Comando template US-008 30min
US-026 Watch mode US-010 1h
US-027 Testes de integração US-010 2h
US-028 Documentação README US-027 1h
US-029 GitHub Actions CI/CD US-028 1h
US-030 Release binários (goreleaser) US-029 45min

Fase 5: Browser (Opcional)

ID Título Dependências Estimativa
US-031 Browser server com chromedp US-010 2h
US-032 ARIA snapshot US-031 1h
US-033 Comando browser US-031, US-032 30min

Diferenças do Ralph Original

Aspecto Ralph LoopForge
Linguagem Shell/Node Go
Distribuição npm Single binary
Configuração .sh files YAML
Extensibilidade Shell scripts Go plugins
Agentes Hardcoded Pluggable
Error handling Basic Structured
Concorrência Não Lock-based
Watch mode Não Sim
Report Não Sim

Métricas de Sucesso

  1. Adoção: 100+ stars no GitHub em 3 meses
  2. Qualidade: 90%+ code coverage
  3. Performance: Startup < 100ms
  4. Compatibilidade: Funciona com os 4 agentes principais
  5. Documentação: README completo + examples

Timeline

  • Semana 1: Fase 1 (Core/MVP)
  • Semana 2: Fase 2 (PRD & Guardrails)
  • Semana 3: Fase 3 (Agentes & Quality)
  • Semana 4: Fase 4 (Polish) + Release

Riscos

Risco Probabilidade Impacto Mitigação
Agentes mudam API Média Alto Abstração via interface
chromedp instável Baixa Médio Browser opcional
Competição Média Baixo Foco em DX e Go ecosystem

PRD criado em 2026-01-23 Versão: 1.0