Por que a Forja existe

Agentes de IA são amnésicos e indisciplinados: cada sessão recomeça do zero, decisões de arquitetura evaporam, o código diverge da intenção — e quem opera vários produtos ao mesmo tempo paga esse imposto multiplicado por N.

A Forja é o estúdio em volta da IA. Ela coordena 6 papéis de agentes num pipeline Spec-Driven (SDD) + Get-Stuff-Done (GSD), mantém uma memória hierárquica indexada em SQLite que sobrevive entre sessões, e amarra tudo num core CLI único com gates e trilha de auditoria (forja, ADR-0020). Multi-IA por design (Claude, Copilot, Gemini, Codex). A operação é inteiramente via CLI.

Para quem: o dev solo ou time pequeno que opera múltiplos produtos com IA como principal força de trabalho — e precisa da disciplina de um time grande sem ter esse time.

Os 3 pilares

| Pilar | O que entrega | Prova | |---|---|---| | Memória que sobrevive | contexto hierárquico, buscável, compartilhado entre sessões e IAs | SQLite FTS5, smart-context (ADR-0003) | | Processo que governa | nada vira código sem spec; nada estrutural sem ADR; comandos auditados | SDD+GSD, handoffs 7 campos (ADR-0005), core forja (ADR-0020) | | Fábrica, não projeto único | workspace multi-produto, times de agentes por projeto | ADR-0019, harness, codegraph (ADR-0017) |

Este repositório é o motor (framework) — não hospeda aplicações em produção. Os produtos do usuário vivem no workspace Forja (~/forja-workspace por padrão), fora deste repo. Veja ADR-0019 para a rationale.

60 segundos de Forja

$ forja spec:new pagamentos-pix
✓ Spec criada: specs/pagamentos-pix/spec.md          # nada vira código sem isso

$ forja gsd:handoff plan pagamentos-pix
Handoff registrado: product → sdd-architect          # 7 campos, auditável (ADR-0005)

$ forja code:impact processPayment
Mapa de impacto: processPayment (profundidade 2)     # blast radius ANTES de editar
--- Chamadores diretos ---
BillingController.charge · RetryWorker.run

$ forja gsd:check pagamentos-pix
OK   GSD runbook      OK   Spec directory
OK   SDD spec check   OK   Codegraph
Resultado: gates básicos prontos.                    # governança executável, não checklist

E cada comando acima ficou gravado em .context/forja-runs.jsonl — quando a governança pergunta "o processo foi seguido?", a resposta é um arquivo, não uma promessa.

Por que não só…?

| Alternativa | Onde ela para | O que a Forja acrescenta | |---|---|---| | Claude Code / Copilot puros | brilhantes na sessão, amnésicos entre sessões | memória FTS5 + processo + auditoria em volta da IA | | LangGraph / CrewAI | infraestrutura para construir agentes | a camada de cima: opera o time de agentes no dia a dia | | Templates & spec kits | param quando a spec está escrita | pipeline completo até a governança, com gates que executam |

Capacidades-chave

• Core CLI único — todo comando de processo passa por forja <comando>: registry declarativo, gates transversais (workspace) e auditoria append-only em .context/forja-runs.jsonl (ADR-0020).
• Orquestração multiagente — 6 papéis (orchestrator, context-engineer, sdd-architect, product, marketing, governance) com handoffs rastreados (7 campos, ADR-0005).
• Memória hierárquica — global → domínio → tarefa → resumo, com busca FTS5 e smart-context em 3 modos (ADR-0003).
• Pipeline SDD + GSD — spec → plan → tasks → check, decisões registradas como ADRs.
• Auto-verificação (invariantes que rodam) — o framework prova a si mesmo: uma família de gates guarda cada fronteira (núcleo, tarball, coerência de doc, topologia de agentes, projeto gerado), e check:all roda a bateria inteira num veredito só. A governança deixa de depender de disciplina — vira harness.
• Economia de token medida, não afirmada — a memória (context.md como mapa) economiza ~60% vs explorar no frio, e token:economy prova isso nos seus domínios. code:context entrega o mapa pronto; memory:audit garante que ele não mente sobre o código.
• Geração de projetos — project:new cria scaffold completo no workspace (memória, agentes, instruções multi-IA, backend NestJS como boilerplate padrão) e registra a ficha; project:upgrade traz peças novas para projetos já gerados sem tocar no código do usuário.
• 3 capacidades integradas (ADR-0016): codegraph (análise de código via MCP), harness (desenho de times de agentes), ai-engineering (base de conhecimento).
• Engineering Control Plane (v3.0, ADR-0078) — o Engineering Graph vira ADRs/SPECs em nós de primeira classe consultáveis; a Architecture Constitution checa o código real contra decisões já registradas; o Change Risk Engine pontua uma mudança 0-100 com fatores nomeados e evidenciados; forja simulate testa um ref num worktree isolado e nunca promove sozinho. Uma façade só, forja engineer "<objetivo>", compõe tudo isso — contexto, ADRs relevantes, checagem de arquitetura, risco, agentes recomendados, incidentes parecidos — antes de você começar. Todo score é informação pra um humano/regra de política consultar, nunca uma decisão autônoma por si só.

⚡ Quick start

# Instalar (o pacote é forjajs; o comando é forja)
npm install -g forjajs
forja                    # help agrupado por domínio

# Preparar o workspace de produção (canto fixo dos projetos)
forja workspace:init

# Criar um projeto novo (gera em ~/forja-workspace/projects/<nome>)
forja project:new meu-projeto --ai claude,copilot

# Entrar no ciclo SDD/GSD da primeira feature
forja spec:new minha-feature
forja spec:plan minha-feature
forja spec:tasks minha-feature
forja spec:check minha-feature

Provar autonomia supervisionada localmente

A prova offline determinística usa uma fixture externa, Git worktree real, aprovação humana, npm test real, validação de diff, promoção, estado SQLite, evidências no GraphLoop e handoff compacto:

npm run demo:autonomy

O fluxo completo está documentado em docs/2x/SPRINT-12-REAL-AUTONOMY-PLAN.md.

Meça o baseline determinístico de contexto e a evidência de cache:

npm run benchmark:context

O sandbox também expõe rollback explícito e auditável após promoção. Os limites oficiais dos plugins @forja/plugin-github e @forja/plugin-docker estão disponíveis; handlers externos de rede ou Docker precisam ser injetados e permissionados pelo host.

Clonou o repo em vez de instalar? Os mesmos comandos rodam como node bin/forja.ts <comando> — os scripts npm são apenas aliases finos do core. A fonte é TypeScript e roda nativa: dev exige Node ≥ 22.6 (strip-types). O pacote publicado embarca dist/*.js e roda em Node ≥ 20 — o release-gate prova isso a cada release (SPEC-012).

Passo a passo de criar vs atualizar projeto: docs/processo-projeto.md.

Como funciona — o processo

💡 Demanda
   ├─ projeto NÃO existe ─► project:new + boilerplate + harness (desenha o time)
   └─ projeto JÁ existe ──► overlay --only-memory + codegraph init (entende o código)
                                              │
                                              ▼
   CICLO CLI-first (docs/fluxo.md):
   1·Entender → 2·Especificar → 3·Arquitetar → 4·Decompor → 5·Implementar → 6·Governar → ✅

| Etapa | Papel | Capacidade | |-------|-------|------------| | 1 Entender | context-engineer | codegraph · ai-engineering | | 2 Especificar | product | — | | 3 Arquitetar | sdd-architect | harness · ADR | | 4 Decompor | sdd-architect | — | | 5 Implementar | orchestrator + worker | codegraph (MCP) | | 6 Governar | governance | codegraph (affected) |

Mapa completo do ciclo: docs/fluxo.md.

As 3 capacidades integradas

| Capacidade | Papel | Como usar | |---|---|---| | codegraph | análise de código (MCP local) | forja code:index · codegraph explore "<área>" · ferramentas MCP codegraph_explore/codegraph_node | | harness | desenho de times de agentes (plugin) | na sessão Claude Code: "build a harness for this project" → gera .claude/agents + .claude/skills | | ai-engineering | base de conhecimento (referência) | ver docs/capacidades-externas.md |

Detalhes e reinstalação: docs/capacidades-externas.md · ADR-0016.

O core forja

Todos os comandos de processo passam por um único ponto de entrada (ADR-0020):

forja                              # help agrupado por domínio
forja <comando> [args]             # no repo clonado: node bin/forja.ts <comando>

O core aplica gates antes de executar (ex.: comandos de produto falham cedo sem workspace) e grava auditoria de cada execução (comando, args, exit code, duração) em <workspace>/.context/forja-runs.jsonl — a trilha que a governança usa no review. Os scripts npm do repo são aliases finos que roteiam pelo core.

Comandos essenciais

# Workspace & projetos
forja workspace:init                       # cria ~/forja-workspace
forja project:new <nome> --ai claude,copilot  # cria projeto no workspace
forja project:list                         # lista projetos do workspace
forja project:upgrade                      # traz peças novas de scaffold p/ um projeto (aditivo; --apply)
forja workspace:project:check <nome>       # valida padrões num projeto do workspace

# Pipeline SDD
forja spec:new <slug>                      # também: spec:plan · spec:tasks · spec:check

# Sprint & handoffs (GSD)
forja sprint:start                         # também: sprint:status · sprint:complete
forja gsd:plan <slug>                      # runbook GSD em .context/
forja gsd:handoff <intent> <slug>          # handoff entre papéis (ADR-0005)
forja gsd:check <slug>                     # gates básicos do runbook
forja orchestrate "<objetivo>" --slug <s>  # abre a corrida: a cadeia SDD/GSD como máquina de estados (SPEC-021)
forja orchestrate:status <slug>            # o estado da máquina: etapas, gates, vereditos
forja orchestrate:advance <slug>           # roda o gate da etapa; verde → próxima; vermelho → trava

# Análise de código (codegraph)
forja code:check                           # índice confiável (worktree + freshness)
forja code:impact <símbolo>                # chamadores + blast radius antes de editar
forja code:context <domínio>               # pacote de contexto mínimo (o mapa; --code p/ o código)
forja code:query "<termo>"                 # também: code:index · code:sync · code:status

# Memória & contexto (workspace)
forja sync:universal                       # reindexa SQLite FTS5 do workspace
forja query:universal "<query>"            # busca FTS5
forja context:smart                        # smart-context (3 modos, ADR-0003)
forja token:economy [--project <path>]     # economia de token; --project mede seus domínios reais (ADR-0009)
forja memory:compress                      # arquiva runs antigos + VACUUM
forja memory:extract                       # extrai conhecimento global da memória
forja memory:audit                         # coerência mapa↔código: mapa não mente + módulo sem mapa (SPEC-017)

# Qualidade & release
forja project:check                        # standards do framework (pre-commit)
forja tools:doctor                         # raio-x do núcleo; separa permissão/lock de corrupção; exit 1 se quebrou
forja release:check --publish              # gate do tarball antes de publicar
forja project:smoke                        # gate do projeto gerado; --full instala e builda o backend
forja check:all                            # a bateria inteira de gates, um veredito; --full inclui os caros (SPEC-020)
forja project:dashboard                    # relatório estático de status

# Governança & auditoria
forja audit:sync                           # projeta a trilha de auditoria numa tabela consultável
forja audit:query --failed                 # consulta: --failed, --cmd <x>, --since 7d
forja governance:dashboard                 # painel HTML estático (gates, SDD, auditoria) — sem servidor

Separação framework × workspace

O Forja é dividido em duas partes:

1. Framework (este repositório): motor, convenções, scripts e memória do próprio framework.
2. Workspace (~/forja-workspace por padrão): "canto fixo" onde vivem os projetos de produto, a memória universal deles e as specs de produto.

O caminho do workspace é resolvido por prioridade:

1. Variável de ambiente FORJA_WORKSPACE
2. Campo workspaceRoot em ~/.forjarc.json
3. Padrão: ~/forja-workspace

Veja ADR-0019 para a decisão arquitetural.

Estrutura do repositório (framework)

bin/          CLIs (forja — o core; init-project, create-memory-nest-kit)
lib/          Módulos reutilizáveis; lib/core/ é o motor de invariantes (registry, checks, health, release, doc-graph, gates)
scripts/      Automação (sprint-manager, agent-router, sync-universal-memory, …)
specs/        Pipeline SDD do próprio framework (spec → plan → tasks)
boilerplates/ Templates de stack (api-rest, saas, ecommerce, microservices, monorepo)
memory/       Memória do framework (00-global … 90-decisions/ADRs)
docs/         Documentação por persona e por tópico (ver DOC-MAP.md)
prompts/      Prompts portáteis dos 6 papéis
.claude/      Sub-agents e settings do Claude Code
projects/     LEGADO — não usar; projetos vivem no workspace externo

Estrutura do workspace

~/forja-workspace/
  projects/              # produtos gerados
  memory/
    sqlite/universal.db  # SQLite FTS5 dos produtos
    30-projects/         # fichas dos projetos
  specs/                 # specs de produto
  .context/              # runbooks GSD de produto
  README.md

Documentação

• DOC-MAP.md — mapa por papel e por tópico (comece aqui)
• docs/processo-projeto.md — criar vs atualizar projeto
• docs/fluxo.md — mapa do ciclo CLI-first
• AGENTS.md — os 6 papéis e a topologia
• memory/90-decisions/ — ADRs com rationale
• CHANGELOG.md — histórico

Convenções

• CLI-first — sprints, SDD, GSD, handoffs e governança por comando; o front nunca é gate.
• ADRs — toda decisão estrutural vira memory/90-decisions/NNNN-titulo.md.
• Handoffs — 7 campos obrigatórios (ADR-0005), gravados no SQLite (ADR-0008).
• Releases — toda versão nova reconcilia o README com o seu comportamento e abre a entrada do CHANGELOG.md por uma seção ### O que melhorou (diff em linguagem de produto vs. a versão anterior, reusada como nota de release no GitHub). Runbook: docs/publishing.md.
• pt-BR — comunicação e documentação em português.

Roadmap

O fio condutor: converter conhecimento que vive em convenção em invariante executável. Cada item abaixo ou fecha uma fronteira do framework por um gate, ou leva esse padrão para os projetos gerados.

Entregue (v3.0.0 — Engineering Control Plane, ADR-0078)

• [x] Engineering Graph — ADRs/SPECs como nós de primeira classe consultáveis (adr:list/show/impact/graph), extração determinística, sem LLM (SPEC-032).
• [x] Architecture Constitution — ## Constraints de ADR viram regras checadas contra o código real (architecture:compile/check/status/explain/approve), reaproveitando o ApprovalLedger, não um sistema de aprovação paralelo (SPEC-033).
• [x] Change Risk Engine — score 0-100 com 7 fatores nomeados e evidenciados (risk:assess/explain); o PolicyEngine pode opcionalmente consultá-lo (riskScoreRange), nunca um motor de decisão paralelo (SPEC-034).
• [x] Evidence Ledger + forja engineer — view agregada por run, e a façade que compõe contexto
  • ADRs relevantes + arquitetura + risco + agentes recomendados + incidentes parecidos + fluxo recomendado antes de você começar (SPEC-035, estendida em SPEC-042).
• [x] Agent Identity & Reputation, Smart Routing — registro persistente de agente com reputação derivada de comportamento real, nunca auto-declarada (agent:register/score/recommend, SPEC-036/037).
• [x] Predictive Change Simulation — forja simulate <ref> testa um ref num worktree git isolado; nunca promove sozinho (SPEC-038).
• [x] AI Code Provenance + Runtime Monitoring — forja blame/sbom (proveniência em granularidade de arquivo), agent:monitor (detecção de anomalia de comportamento contra a própria linha de base do agente) — os dois são informação pro PolicyEngine/um humano consultar, nunca automático (SPEC-039/040).
• [x] Learning Loop — incident:record/list/similar, sugestão por palavra-chave, nunca aplicação automática (SPEC-041).
• [x] Prontidão de Autonomous Maintenance — ADR-0079 documenta os guardrails que qualquer spec futura de manutenção autônoma real precisará respeitar; deliberadamente não habilitada ainda, por desenho explícito da própria visão.

Entregue (até v1.6.0)

• [x] Família de gates — cada fronteira do framework guarda por um invariante que roda: núcleo (tools:doctor, ADR-0023), tarball (release:check, ADR-0024), coerência de doc + ADRs + topologia de agentes (ADR-0025, SPEC-019), projeto gerado (project:smoke, ADR-0029). E check:all reúne a bateria num veredito (SPEC-020).
• [x] Migração TypeScript completa — fonte 100% .ts, publica dist/, noImplicitAny ON. Achou bugs latentes que nenhum teste pegava (SPEC-012).
• [x] Economia de memória como sistema — medida (token:economy prova ~60% vs frio), entregue (code:context), protegida (memory:audit, nas duas direções) e propagada: o projeto gerado herda o gate dos mapas (ADR-0030).
• [x] project:upgrade — atualizar um projeto já gerado sem perder código: aditivo, nunca sobrescreve (SPEC-018).
• [x] Clean Architecture calibrado — camadas onde se pagam, enxuto onde não; e a claim de token medida e corrigida — a economia é da memória, não das camadas (ADR-0027).
• [x] builds do backend gerado sob toolchain novo — o template alinhou o better-sqlite3 ao do framework (^12, com prebuilds); o check:all --full compila o backend gerado em Node 26.
• [x] release-auditor consome o gate — o agente executa e julga release:check --publish (ADR-0024), incluindo o consumer-spec-new; não reimplementa o procedimento.

Próximos passos (por dependência, não por desejo)

• [ ] Cross-project Intelligence (resto da Fase 6) — correlacionar incidentes entre múltiplos repositórios; exige uma fonte de dado que este workspace de um único repositório ainda não tem.
• [ ] Boilerplates além de NestJS — o processo é agnóstico de stack; os templates vão atrás.

Sugestões? Abra uma issue — feature não-trivial aqui começa por spec, inclusive as suas.

English

Full English version: README.md. In short — Forja turns coding AI into an engineering team with process and memory: every project starts from a spec, every structural decision becomes an ADR, and nothing is lost between sessions. Documentation is in Brazilian Portuguese — that's part of the project's identity; the CLI and the code are readable regardless.