Skip to content
BranchesTags

Repository files navigation

Forge Agent

Forge Agent for Claude Code

Workflow de desenvolvimento autônomo — planejamento, execução, verificação e git
gerenciado por agentes especializados com memória emergente.

Baseado na metodologia GSD-2 (MIT) — reimplementado para o sistema nativo de agentes do Claude Code.

O que você ganha

  • Hierarquia Milestone → Slice → Task com contexto fresco por unidade
  • Agentes especializados por fase (Opus para pensar, Sonnet para executar)
  • Memória emergente — o sistema aprende padrões e gotchas do seu projeto
  • Git automático — branch por slice, squash merge, commits semânticos
  • Tudo em arquivos .md — recuperável após crash, auditável, versionável

Quick start

git clone https://github.com/<seu-usuario>/forge-agent
cd forge-agent
bash install.sh            # macOS/Linux
# .\install.ps1            # Windows
cd /seu/projeto
claude
/forge-init minha plataforma de e-commerce com Next.js
/forge-new-milestone autenticação de usuários com NextAuth
/forge

O /forge é o shell interativo principal — navega entre milestones, executa unidades e responde perguntas sem sair do REPL.

Verificar instalação: /forge-help

Arquitetura v1.0 — 3 comandos + skills

A partir da v1.0, o Forge Agent usa 3 comandos slash e skills para tudo o mais:

Tipo Exemplos Como invocar
Comando slash /forge, /forge-init, /forge-update Digitar / no Claude Code
Skill forge-auto, forge-status, forge-new-milestone... Via /forge REPL ou digitando o nome

Comandos slash

Comando O que faz
/forge Entry point principal — REPL interativo com menu: auto, task, new-milestone, status, help
/forge-init [descrição] Inicializa o projeto GSD — cria CLAUDE.md + .gsd/ + prefs
/forge-update [caminho] Atualiza Forge Agent (git pull + reinstala). Preserva preferências.

Skills de execução e planejamento

Skill O que faz
forge-auto Executa o milestone inteiro de forma autônoma até concluir
forge-next Executa exatamente uma unidade e para (step mode)
forge-task <descrição> Task autônoma sem milestone — brainstorm → discuss → plan → execute
forge-task <item-id> Consome um item do backlog (.gsd/items/, qualquer prefixo único) como task — descrição/proveniência no BRIEF, doing + promoted_to: T-…
forge-new-milestone <descrição> Cria milestone completo — brainstorm → scope → discuss → ROADMAP
forge-discuss <milestone|S##> Abre fase de discuss para milestone ou slice
forge-add-slice, forge-add-task Adiciona slice ou task a um milestone existente

Skills de visibilidade e manutenção

Skill O que faz
forge-status Dashboard de progresso — milestone, slices, próxima ação
forge-doctor [--fix] Diagnóstico do projeto — valida e corrige STATE, arquivos, prefs
forge-codebase [--fix] Qualidade do codebase — lint, nomenclatura, estrutura
forge-sweep [--apply] Limpa know-how (AUTO-MEMORY, DECISIONS, milestones, sessões) — dry-run por padrão
forge-explain <alvo> Explica qualquer artefato GSD sem modificar nada
forge-memories Gerencia memórias auto-aprendidas do projeto
forge-ask Modo conversa — discute ideias, captura decisões
forge-prefs Configuração de modelos por fase e git settings
forge-config, forge-mcps Status line, hooks e MCPs
forge-help Ajuda completa

Referência completa de preferências: cada um dos 94 knobs (40 seções) do catálogo de prefs — forge-agent-prefs.jsonc/.gsd/claude-agent-prefs.jsonc/.gsd/prefs.local.jsonc, todos JSONC com $schema: forge-prefs.schema.json — está documentado em shared/forge-prefs-reference.md (gerado a partir do schema, sem drift possível). Use forge-prefs para ver o estado resolvido ao vivo.

Skills de qualidade (invocadas automaticamente ou manualmente)

Skill O que faz
forge-brainstorm Explora alternativas e riscos antes de planejar
forge-scope-clarity Contrato de escopo com critérios testáveis
forge-risk-radar Análise de riscos por slice (auto-invocada em slices risk:high)
forge-security Checklist de segurança por task (auto-invocada por keywords)
forge-responsive Audit responsivo — Core Web Vitals, WCAG 2.2
forge-ui-review Review UI — acessibilidade, performance, React 19

Compatibilidade retroativa: IDs legados no formato M### (ex.: M006) e TASK-### continuam sendo lidos e resolvidos normalmente — --resume, /forge-explain e /forge-discuss aceitam ambos os formatos. Novos milestones e tasks soltas criados pelo forge geram IDs no formato timestamp M-<ts>-<slug> / T-<ts>-<slug> (ex.: M-20260522101500-pagamentos).

Fragment store + projection

Forge Agent stores .gsd/ knowledge (ledger, decisions, auto-memory) as per-unit fragments instead of mutable monolith files — one small file per milestone, session, or task.

Three stores live under .gsd/:

Store Path Contents
Ledger .gsd/ledger/<id>.md Compact record of each completed milestone
Decisions .gsd/decisions/<id>.md Architecture decisions scoped to a unit
Memory .gsd/memory/<id>.md Auto-learned patterns from completed work

The familiar monolith files (LEDGER.md, DECISIONS.md, AUTO-MEMORY.md) are projection cache — rebuilt on-read by scripts/forge-projection.js and excluded from version control (.gitignore/svn:ignore). This makes the stores conflict-free by construction: each fragment has exactly one owner (one unit of work, one developer, one branch).

Migration from the pre-M001 monolith layout runs automatically during /forge-update and keeps a .bak copy of every monolith until you verify the projection matches.

For full details — layout, fragment schema, projection engine, migration, and doctor checks — see docs/fragment-store.md.

Documentação

Doc Conteúdo
Arquitetura Fluxo de execução, agentes, modelos, memória emergente
Comandos Referência completa de todos os comandos
Skills Skills incluídas, como instalar e contribuir
Configuração Preferências, status line, arquivos do projeto

Nota — review.engine: workflow e approval prompt: quando review.engine: workflow está configurado, cada debate de review usa a tool Workflow do Claude Code (requer ≥ v2.1.154). Em permissions.defaultMode padrão, cada invocação Workflow pede aprovação do operador — o que pausa o forge-auto silenciosamente. Para uso autônomo, configure permissions.defaultMode: bypassPermissions (usuários com a statusline ativa já têm — ativado pelo merge-settings.js). Se a tool Workflow não estiver disponível ou a invocação falhar, o gate faz fallback automático para engine: agents com um warning e regista o evento review-engine-fallback — nunca bloqueia.

Pré-requisito — review.challenger: codex: o challenger Codex requer o Codex CLI (codex) instalado e autenticado, por um destes dois caminhos:

  • Login por assinatura ChatGPT (recomendado): codex login — abre um fluxo de browser, credencial gerenciada pelo próprio CLI.
  • OPENAI_API_KEY no ambiente: exporte a variável de uma fonte segura (.env gitignored ou secret manager) — nunca hardcoded em prefs commitáveis (.gsd/claude-agent-prefs.jsonc é versionado; uma chave ali seria vazamento).

O forge não instala nem autentica tooling de terceiros — apenas invoca o codex já configurado pelo usuário via scripts/forge-xllm.js, que nunca recebe a credencial por argumento (a auth é gerenciada inteiramente pelo próprio CLI). Sem codex disponível, o gate faz fallback automático para forge-reviewer (Claude) com o evento review-challenger-fallback — nunca bloqueia. Implicação de privacidade: com challenger: codex, o diff do slice sai da máquina local para a API da OpenAI.

Pré-requisito — review.challenger: gemini: o challenger Gemini requer o Antigravity CLI (agy) instalado e autenticado, por um destes dois caminhos:

  • Login no Antigravity (recomendado): faça login uma vez (IDE ou CLI) — em headless o agy usa a auth silenciosa por keyring, com refresh automático de token.
  • GEMINI_API_KEY (ou ANTIGRAVITY_API_KEY) no ambiente: exporte de uma fonte segura (.env gitignored ou secret manager) — nunca hardcoded em prefs commitáveis.

O modelo é opcional: challenger_model aceita um label do agy models (pode conter espaços — use aspas: "Gemini 3.1 Pro (High)"); unset usa o default do CLI. O adapter invoca agy --print com --sandbox (restrições de terminal) e o mesmo contrato do codex: sem agy disponível (binário, auth, quota, rede, stdout vazio), fallback automático para forge-reviewer (Claude) com o evento review-challenger-fallback (gemini-exit-nonzero) — nunca bloqueia. Implicação de privacidade: com challenger: gemini, o diff do slice sai da máquina local para a API do Google.

Multi-LLM fase 2 — workers GPT via sidecar

Além do challenger de review Codex (acima), o forge permite rotear as próprias fases de trabalho — execute-task e plan-slice — para GPT via o mesmo sidecar codex exec, através das prefs workers.execute-task: codex / workers.plan-slice: codex (ver forge-agent-prefs.jsonc § Workers Settings). O default continua claude — é opt-in, não uma migração de engine.

Mecanicamente, scripts/forge-xllm.js --mode execute|plan invoca codex exec como sidecar, lê um plano (T##-PLAN.md) e retorna um result-file estruturado (status, summary, must_haves_status, files_changed, start_sha) — mesma interface de contrato que um worker Claude nativo devolveria. Isso significa que todos os gates de verificação Claude rodam intactos sobre código produzido por GPT: o schema must_haves continua enforcing, o goal-backward verifier continua auditando os artefatos declarados, o file-audit continua comparando o diff contra expected_output, e o review dialético continua rodando — com o challenger Claude revisando o código GPT. É a inversão simétrica do challenger Codex do M004 (lá, GPT revisa código Claude; aqui, Claude revisa código GPT).

Limitações

Três limitações são aceitas e documentadas explicitamente — não são bugs, são o contrato atual:

  1. Blast radius workspace-write: o sidecar de execução roda codex exec --sandbox workspace-write — um raio de ação mais amplo que o --sandbox read-only do challenger de review (M004). O invariante ".gsd/ intocado, nenhum git commit feito pelo sidecar" é contrato + detecção pós-hoc (o orquestrador confere o diff depois), não é sandbox-enforced pelo próprio codex. Na prática, isso significa que o raio de ação de um eventual prompt-injection no conteúdo processado é igual ao workspace inteiro, não limitado a leitura. Aceite essa superfície antes de ativar workers.execute-task: codex em repositórios sensíveis.
  2. Evidence sintetizado, não capturado ao vivo: para um worker Claude nativo, cada chamada Bash/Write/Edit grava uma linha no evidence log em tempo real (hook PostToolUse). Para o sidecar codex, o evidence é sintetizado pós-hoc a partir de git diff --name-status {START_SHA} ao final da execução (source: codex-sidecar) — é advisory, útil para auditoria, mas não tem a granularidade por-chamada do caminho nativo. Como o invariante no-commit mantém HEAD == {START_SHA}, esse git diff --name-status não inclui arquivos novos não-rastreados (untracked) — para tasks que criam arquivos, o evidence log fica quase vazio. A lista de arquivos autoritativa não é esse evidence: é o result JSON do sidecar (files_changed_declared, declarado pela task, mais files_changed, derivado de git status --porcelain, que captura untracked) — é essa fonte que o file-audit usa, não o --name-status. Blind spot residual aceito: arquivos gitignored criados pelo sidecar não aparecem nem no --name-status nem no git status --porcelain, e não são removidos pelo reset git clean -fd (sem -x) — fora do escopo de detecção atual.
  3. Sem retry do trabalho codex (fail-once): se o sidecar falhar por qualquer motivo (exit code ≠ 0, timeout, JSON de result-file inválido), o orquestrador reseta o repositório para START_SHA e faz um único fallback ao worker Claude equivalente — não há retry do trabalho GPT. Uma falha do sidecar custa, no máximo, uma tentativa perdida.

Multi-LLM fase 3 — pairing de review por autoria

A partir da M006, cada review dialético resolve seu challenger e advocate pela autoria do código, não por explícito. Via prefs review.challenger: auto e review.advocate: auto — que permanecem desativadas por padrão (claude / claude), decisão pós-dogfood:

  • challenger: auto → resolve para a família OPOSTA ao autor (Claude code → GPT challenger; GPT code → Claude challenger). Reduz viés de auto-preferência: um desafiante de fora encontra classes de bug que dois Claudes não acham.
  • advocate: auto → resolve para a MESMA família do autor (autor Claude → advocate Claude; autor GPT → advocate Claude, enquanto --mode defend não existe em fase 2). Mantém a defesa competente.

Autoria é derivada do campo engine dos dispatch events (.gsd/forge/events.jsonl), agregada por majority determinística — o orquestrador chama scripts/forge-review-pairing.js uma única vez por review antes da challenge. Degradações (autor sem evento de autoria, ou GPT sem --mode defend disponível) emitem review-pairing-fallback e retornam ao padrão Claude — nunca bloqueiam. Matriz canônica de resolver sem redefini-la: shared/forge-review.md § Step 0.

Ativar: edite forge-agent-prefs.jsonc (ou .gsd/prefs.local.jsonc), setando os campos abaixo dentro do bloco review:

{
  "review": {
    "challenger": "auto", // resolve de verdade na próxima review dialética
    "advocate": "auto"    // resolve junto
  }
}

Multi-LLM fase 4 — routing model-first por domínio

O forge permite rotear os workers — execute-task e plan-slice — por domínio de trabalho e fase, escolhendo inclusive cadeias cross-engine (misturar IDs Claude e GPT numa mesma célula). Diferente da fase 2 (workers:, que escolhe engine por unit_type), o routing é inteiramente opt-in — sem o bloco routing: definido nas prefs, o comportamento é 100% idêntico aos tiers legados (tier_models:/workers: decidem sozinhos). A cascata responde à última reescrita por domínio inteiro — nunca merge campo-a-campo, para evitar meia-domain de um arquivo + meia-domain de outro = misroute silencioso.

Mecanicamente, cada célula routing.<domínio>.<fase>.<tier> = [cadeia] contém uma lista ordenada de modelos (Claude e/ou GPT, cross-engine permitido), com um fallback: de categoria definindo um modelo Claude mapeado para casos de esgotamento. O resolvedor scripts/forge-routing.js usa precedência explícita (frontmatter > routing > tier_models legacy) e engine derivation por família (IDs claude-* → Agent(model), IDs gpt-* → sidecar forge-xllm.js). Cadeias com membros de família não-roteável (ex.: Gemini) skip o membro com phase-unsupported-family e continuam na próxima.

  • Fases roteáveis: apenas executor (execute-task) e planner (plan-slice). plan-milestone nunca é capturado por este eixo — permanece locked no tier max (Fable).
  • Nesting: routing.<domínio>.<fase>.<tier> = [id, ...] + routing.<domínio>.<fase>.fallback = <id>. <tier> é qualquer alias de tier (light, standard, heavy, max).
  • Domínios: chaves de domínio são abertas — default é recomendado (usado quando a task/slice não declara domain:); sem ele, unidades sem domain: correspondente caem direto no legado (tier_models), nunca erro. Qualquer outra chave (backend, frontend, ...) é definida pelo operador.
  • Precedência: frontmatter tier:/worker: na task (item 1, sempre ganha) > bloco routing: aqui (quando célula resolve) > comportamento legado tier_models:/workers: (quando não há routing: ou a célula não resolve).
  • Engine derivation: resolvida por modelFamily() (scripts/forge-model-alias.js) — aliases claude/fable/opus/sonnet/haiku → engine Agent (nativo em contexto); gpt/codex → engine codex (sidecar forge-xllm.js); família desconhecida (modelFamily() retorna null) → membro pulado com skipped-unknown-family; gemini (família conhecida, mas não roteável) → pulado com phase-unsupported-family.
  • Fallback de categoria: fallback: deve apontar para 1 modelo Claude mapeado. Um fallback: presente porém inválido (família não-Claude ou não mapeada) é substituído pelo fallback legado (tier_models:) e registrado como fallback-invalid-substituted no reason. Um fallback: ausente usa o fallback legado silenciosamente (sem reason — é o comportamento natural, não uma config inválida) — nunca aborta o dispatch.
  • Caveat gemini (phase-unsupported-family): um ID de família gemini numa cadeia é reconhecido mas não é roteável como executor/planner hoje — não há worker nativo Gemini. Um membro gemini é pulado silenciosamente e a resolução segue para o próximo membro.

Ativar:

Edite forge-agent-prefs.jsonc (ou .gsd/prefs.local.jsonc) e adicione/edite o bloco routing. Exemplo de célula cross-engine:

{
  "routing": {
    "default": {
      "executor": {
        "standard": ["claude-sonnet-5"],
        "heavy": ["claude-opus-5", "gpt-5"],   // cadeia cross-engine (claude -> gpt sidecar)
        "fallback": "claude-sonnet-5"          // categoria: 1 Claude mapeado
      }
    },
    "backend": {
      "executor": {
        "standard": ["gpt-5", "claude-sonnet-5"], // gpt primario, claude fallback
        "fallback": "claude-sonnet-5"
      }
    }
  }
}

Para inspecionar a resolução sem disparar dispatch real, use o CLI:

node scripts/forge-routing.js --unit-type execute-task --tier heavy \
  --domain backend --explain

A matriz canônica de resolver está em scripts/forge-routing.js (resolveRoute(opts)); precedência completa em shared/forge-dispatch.md.

Atualizar

cd forge-agent
git pull
bash install.sh --update

Preferências e arquivos de projeto nunca são sobrescritos.

Créditos

Reimplementação dos conceitos do GSD-2 (gsd-pi) para o sistema nativo de agentes do Claude Code. Hierarquia Milestone → Slice → Task, contexto fresco por unidade, memória emergente, workflow de fases e git branch-per-slice são designs originários do gsd-2.

Este repositório não distribui nem modifica código do gsd-2 — apenas reimplementa os conceitos usando arquivos .md.

Licença

MIT — veja LICENSE

About

forge agent with claude cli

Resources

Readme
License
Activity

Stars

0 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases

Packages

Contributors

Languages