forjajs 1.7.2 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (126) hide show
  1. package/CHANGELOG.md +49 -0
  2. package/README.md +223 -217
  3. package/README.pt-BR.md +323 -0
  4. package/dist/apps/dashboard/app/api/forja/[...path]/route.d.ts +10 -0
  5. package/dist/apps/dashboard/app/api/forja/[...path]/route.js +36 -0
  6. package/dist/apps/dashboard/app/api/forja/approval.d.ts +1 -0
  7. package/dist/apps/dashboard/app/api/forja/approval.js +8 -0
  8. package/dist/apps/dashboard/app/dashboard-client.d.ts +1 -0
  9. package/dist/apps/dashboard/app/dashboard-client.jsx +62 -0
  10. package/dist/apps/dashboard/app/layout.d.ts +9 -0
  11. package/dist/apps/dashboard/app/layout.jsx +7 -0
  12. package/dist/apps/dashboard/app/page.d.ts +1 -0
  13. package/dist/apps/dashboard/app/page.jsx +5 -0
  14. package/dist/apps/dashboard/app/providers.d.ts +4 -0
  15. package/dist/apps/dashboard/app/providers.jsx +7 -0
  16. package/dist/apps/dashboard/next.config.d.mts +6 -0
  17. package/dist/apps/dashboard/next.config.mjs +8 -0
  18. package/dist/apps/dashboard/src/index.d.ts +14 -0
  19. package/dist/apps/dashboard/src/index.js +16 -0
  20. package/dist/apps/server/src/app.module.d.ts +5 -0
  21. package/dist/apps/server/src/app.module.js +16 -0
  22. package/dist/apps/server/src/forja-nest.module.d.ts +59 -0
  23. package/dist/apps/server/src/forja-nest.module.js +316 -0
  24. package/dist/apps/server/src/index.d.ts +15 -0
  25. package/dist/apps/server/src/index.js +7 -0
  26. package/dist/apps/server/src/main.d.ts +12 -0
  27. package/dist/apps/server/src/main.js +105 -0
  28. package/dist/apps/worker/src/main.d.ts +12 -0
  29. package/dist/apps/worker/src/main.js +18 -0
  30. package/dist/lib/core/health.js +26 -4
  31. package/dist/packages/adapter-git/src/index.d.ts +27 -0
  32. package/dist/packages/adapter-git/src/index.js +53 -0
  33. package/dist/packages/adapter-nest/src/index.d.ts +71 -0
  34. package/dist/packages/adapter-nest/src/index.js +142 -0
  35. package/dist/packages/adapter-sqlite/src/index.d.ts +99 -0
  36. package/dist/packages/adapter-sqlite/src/index.js +108 -0
  37. package/dist/packages/context/src/index.d.ts +52 -0
  38. package/dist/packages/context/src/index.js +108 -0
  39. package/dist/packages/contracts/src/index.d.ts +368 -0
  40. package/dist/packages/contracts/src/index.js +27 -0
  41. package/dist/packages/core/src/index.d.ts +68 -0
  42. package/dist/packages/core/src/index.js +141 -0
  43. package/dist/packages/evals/src/index.d.ts +22 -0
  44. package/dist/packages/evals/src/index.js +65 -0
  45. package/dist/packages/events/src/index.d.ts +47 -0
  46. package/dist/packages/events/src/index.js +96 -0
  47. package/dist/packages/graph/src/index.d.ts +80 -0
  48. package/dist/packages/graph/src/index.js +163 -0
  49. package/dist/packages/mcp/src/index.d.ts +119 -0
  50. package/dist/packages/mcp/src/index.js +153 -0
  51. package/dist/packages/observability/src/index.d.ts +132 -0
  52. package/dist/packages/observability/src/index.js +86 -0
  53. package/dist/packages/orchestration/src/index.d.ts +122 -0
  54. package/dist/packages/orchestration/src/index.js +178 -0
  55. package/dist/packages/planner/src/index.d.ts +22 -0
  56. package/dist/packages/planner/src/index.js +70 -0
  57. package/dist/packages/plugin-sdk/src/index.d.ts +56 -0
  58. package/dist/packages/plugin-sdk/src/index.js +55 -0
  59. package/dist/packages/policy/src/index.d.ts +80 -0
  60. package/dist/packages/policy/src/index.js +136 -0
  61. package/dist/packages/runtime/src/index.d.ts +91 -0
  62. package/dist/packages/runtime/src/index.js +217 -0
  63. package/dist/packages/sandbox/src/index.d.ts +64 -0
  64. package/dist/packages/sandbox/src/index.js +108 -0
  65. package/dist/packages/scheduler/src/index.d.ts +56 -0
  66. package/dist/packages/scheduler/src/index.js +123 -0
  67. package/dist/packages/sdk/src/index.d.ts +122 -0
  68. package/dist/packages/sdk/src/index.js +40 -0
  69. package/dist/packages/validator/src/index.d.ts +36 -0
  70. package/dist/packages/validator/src/index.js +60 -0
  71. package/docs/architecture/FORJA-2.0-ARCHITECTURE.md +109 -0
  72. package/docs/architecture/FORJA-2.0-IMPACT-FOUNDATION.md +273 -0
  73. package/docs/security/FORJA-2.0-RELEASE-AUDIT-2026-08-01.md +95 -0
  74. package/docs/vision/FORJA-2.0-VISION.md +72 -0
  75. package/memory/50-orchestration/handoffs/2026-07-31_architect_foundation-contracts.md +15 -0
  76. package/memory/50-orchestration/handoffs/2026-07-31_backend-nest.md +22 -0
  77. package/memory/50-orchestration/handoffs/2026-07-31_context-engine.md +16 -0
  78. package/memory/50-orchestration/handoffs/2026-07-31_control-plane.md +28 -0
  79. package/memory/50-orchestration/handoffs/2026-07-31_core-capability-registry.md +15 -0
  80. package/memory/50-orchestration/handoffs/2026-07-31_evals-plugin-sdk.md +22 -0
  81. package/memory/50-orchestration/handoffs/2026-07-31_events-scheduler.md +16 -0
  82. package/memory/50-orchestration/handoffs/2026-07-31_graphloop.md +16 -0
  83. package/memory/50-orchestration/handoffs/2026-07-31_mcp.md +21 -0
  84. package/memory/50-orchestration/handoffs/2026-07-31_nest-bootstrap.md +28 -0
  85. package/memory/50-orchestration/handoffs/2026-07-31_next-dashboard.md +22 -0
  86. package/memory/50-orchestration/handoffs/2026-07-31_observability.md +27 -0
  87. package/memory/50-orchestration/handoffs/2026-07-31_orchestration.md +21 -0
  88. package/memory/50-orchestration/handoffs/2026-07-31_planner-validator.md +16 -0
  89. package/memory/50-orchestration/handoffs/2026-07-31_policy-engine.md +14 -0
  90. package/memory/50-orchestration/handoffs/2026-07-31_runtime-control-plane.md +23 -0
  91. package/memory/50-orchestration/handoffs/2026-07-31_runtime-controlado.md +15 -0
  92. package/memory/50-orchestration/handoffs/2026-07-31_sandbox.md +21 -0
  93. package/memory/50-orchestration/handoffs/2026-07-31_sdk.md +27 -0
  94. package/memory/50-orchestration/handoffs/2026-07-31_sqlite-adapter.md +21 -0
  95. package/memory/50-orchestration/handoffs/2026-07-31_worker-dashboard-boundary.md +23 -0
  96. package/memory/50-orchestration/handoffs/2026-08-01_approval-server-identity.md +23 -0
  97. package/memory/50-orchestration/handoffs/2026-08-01_dashboard-auth-query.md +24 -0
  98. package/memory/50-orchestration/handoffs/2026-08-01_graphloop-approvals.md +23 -0
  99. package/memory/90-decisions/0033-doctor-distingue-permissao-de-corrupcao.md +64 -0
  100. package/memory/90-decisions/0034-forja-2-core-e-contratos.md +29 -0
  101. package/memory/90-decisions/0035-forja-2-local-first-e-autonomia.md +23 -0
  102. package/memory/90-decisions/0036-forja-2-capability-registry.md +30 -0
  103. package/memory/90-decisions/0037-forja-2-policy-engine-obrigatorio.md +28 -0
  104. package/memory/90-decisions/0038-forja-2-runtime-controlado.md +28 -0
  105. package/memory/90-decisions/0039-forja-2-event-bus-scheduler-local-first.md +31 -0
  106. package/memory/90-decisions/0040-forja-2-context-engine-budget-cache.md +32 -0
  107. package/memory/90-decisions/0041-forja-2-graphloop-separado-codegraph.md +32 -0
  108. package/memory/90-decisions/0042-forja-2-planner-validator-independentes.md +29 -0
  109. package/memory/90-decisions/0043-forja-2-orchestration-entities.md +16 -0
  110. package/memory/90-decisions/0044-forja-2-sandbox-worktree.md +19 -0
  111. package/memory/90-decisions/0045-forja-2-sqlite-adapter.md +19 -0
  112. package/memory/90-decisions/0046-forja-2-mcp-adapter.md +18 -0
  113. package/memory/90-decisions/0047-forja-2-backend-nest-adapter.md +19 -0
  114. package/memory/90-decisions/0048-forja-2-sdk-transport.md +18 -0
  115. package/memory/90-decisions/0049-forja-2-observability-control-plane.md +18 -0
  116. package/memory/90-decisions/0050-forja-2-control-plane-application-ports.md +18 -0
  117. package/memory/90-decisions/0051-forja-2-runtime-control-plane-composition.md +18 -0
  118. package/memory/90-decisions/0052-forja-2-deterministic-evaluation.md +15 -0
  119. package/memory/90-decisions/0053-forja-2-plugin-sdk-permissionado.md +16 -0
  120. package/memory/90-decisions/0054-forja-2-worker-dashboard-boundary.md +15 -0
  121. package/memory/90-decisions/0055-forja-2-next-dashboard-distribution.md +16 -0
  122. package/memory/90-decisions/0056-forja-2-dashboard-proxy-auth-query.md +16 -0
  123. package/memory/90-decisions/0057-forja-2-graphloop-approvals-dashboard.md +15 -0
  124. package/memory/90-decisions/0058-forja-2-approval-server-identity.md +15 -0
  125. package/package.json +28 -3
  126. package/README.en.md +0 -329
@@ -0,0 +1,15 @@
1
+ # ADR-0054 — Worker e dashboard como adaptadores do Control Plane
2
+
3
+ - **Status**: accepted
4
+ - **Data**: 2026-07-31
5
+ - **Contexto**: O processamento assíncrono e a interface operacional precisam consumir o núcleo sem duplicar suas regras.
6
+ - **Decisão**: `apps/worker` compõe Event Bus, Scheduler, Observability e Evaluation Engine. `apps/dashboard` expõe um view model de snapshot e ações delegadas ao `ControlPlanePort`; a futura casca Next/React consumirá esse view model por transporte remoto.
7
+ - **Regras**:
8
+ - worker não executa capabilities diretamente nem bypassa Policy;
9
+ - dashboard não autoriza, executa agente ou calcula GraphLoop;
10
+ - ações críticas são delegadas a portas do Control Plane;
11
+ - ausência de serviço é erro explícito;
12
+ - a camada atual permanece compilável offline sem instalar framework visual prematuramente.
13
+ - **Alternativas rejeitadas**: regra de negócio dentro de componentes React; worker com executor próprio; dashboard chamando SQLite diretamente.
14
+ - **Consequências**: A fronteira operacional pode ser testada sem navegador. Next/React, TanStack Query e SSE real serão ligados na etapa de distribuição visual, sem mudar o domínio.
15
+ - **Evidências**: `apps/worker/src/main.ts`, `apps/dashboard/src/index.ts`, `test/dashboard-worker.test.js`, `npm run types:check`, `npm run build`.
@@ -0,0 +1,16 @@
1
+ # ADR-0055 — Dashboard Next.js como adaptador de distribuição
2
+
3
+ - **Status**: accepted
4
+ - **Data**: 2026-07-31
5
+ - **Contexto**: O ForjaJS precisa de uma interface oficial operacional sem deslocar autorização, execução ou GraphLoop para o cliente.
6
+ - **Decisão**: `apps/dashboard` usa Next.js 15.5.9, React 19.2 e App Router. A página consulta métricas/observações por REST, reage a SSE e mantém ações críticas fora do cliente, delegadas ao Control Plane boundary.
7
+ - **Regras**:
8
+ - cliente não acessa SQLite nem conhece persistência;
9
+ - cliente não decide Policy nem executa capability;
10
+ - dados remotos são tratados como estado operacional, não como fonte de autorização;
11
+ - `outputFileTracingRoot` aponta para a raiz do monorepo;
12
+ - a versão do Next deve permanecer em linha corrigida de segurança.
13
+ - **Alternativas rejeitadas**: dashboard com regras próprias; polling como único canal; importação direta de adapters.
14
+ - **Consequências**: Existe uma distribuição visual compilável e offline quanto ao bundle. Autenticação real, TanStack Query, filtros avançados e GraphLoop visual continuam incrementos posteriores sobre o mesmo boundary.
15
+ - **Risco conhecido**: npm reportou vulnerabilidades altas transitivas no conjunto instalado; o release gate deve executar auditoria e não usar `audit fix --force` automaticamente.
16
+ - **Evidências**: `apps/dashboard/app/page.tsx`, `apps/dashboard/app/dashboard-client.tsx`, `apps/dashboard/next.config.mjs`, `npm run dashboard:build`.
@@ -0,0 +1,16 @@
1
+ # ADR-0056 — Proxy server-side, autenticação local e cache remoto do dashboard
2
+
3
+ - **Status**: accepted
4
+ - **Data**: 2026-08-01
5
+ - **Contexto**: O dashboard precisava consumir o backend local sem expor segredo no bundle, duplicar autorização ou refazer consultas a cada renderização.
6
+ - **Decisão**: `apps/dashboard` usa Route Handler server-side com allowlist de recursos, encaminha `FORJA_AUTH_TOKEN` somente ao backend e usa TanStack Query no cliente para cache/invalidação. SSE invalida a query; não transporta credenciais.
7
+ - **Regras**:
8
+ - somente métricas, observações, eventos e transições de execução são encaminhados;
9
+ - rotas fora da allowlist retornam 403;
10
+ - token nunca usa prefixo `NEXT_PUBLIC_`;
11
+ - backend valida Bearer com comparação de tamanho e `timingSafeEqual`;
12
+ - cliente não decide Policy e não acessa SQLite;
13
+ - pausa/cancelamento continuam comandos do Control Plane.
14
+ - **Alternativas rejeitadas**: token público no bundle; proxy genérico para qualquer URL; autorização no React; polling sem invalidação por evento.
15
+ - **Consequências**: Desenvolvimento local continua simples com `FORJA_API_URL` e `FORJA_AUTH_TOKEN`; autenticação sem token permanece compatibilidade de ambiente local, e implantação deve definir o token.
16
+ - **Evidências**: `apps/dashboard/app/api/forja/[...path]/route.ts`, `apps/dashboard/app/providers.tsx`, `apps/dashboard/app/dashboard-client.tsx`, `packages/adapter-nest/src/index.ts`, `apps/server/src/main.ts`, 265 testes.
@@ -0,0 +1,15 @@
1
+ # ADR-0057 — GraphLoop e approvals no dashboard por portas do Control Plane
2
+
3
+ - **Status**: accepted
4
+ - **Data**: 2026-08-01
5
+ - **Contexto**: A interface precisava tornar relações e aprovações operacionais sem reproduzir algoritmos do domínio nem criar decisões no cliente.
6
+ - **Decisão**: O adapter Nest expõe consulta de nós, impacto e listagem de approvals; o dashboard renderiza nós/status e impacto sob demanda, além de listar decisões pendentes/finais. GraphLoop continua no pacote de domínio e Policy continua no backend.
7
+ - **Regras**:
8
+ - toda relação exibida vem da API e preserva status/evidência do GraphLoop;
9
+ - impacto exige um ID de origem explícito;
10
+ - approvals são somente leitura nesta fatia; decisão deve usar identidade/aprovador configurado;
11
+ - nenhuma heurística de grafo é executada no React;
12
+ - endpoints entram na allowlist do proxy, nunca em proxy genérico.
13
+ - **Alternativas rejeitadas**: importar GraphLoop para o browser; renderizar arestas inventadas; aprovar sem identidade explícita; consultar SQLite no dashboard.
14
+ - **Consequências**: A UI já permite inspeção operacional básica offline/remota. Visualização espacial avançada, evidências detalhadas e fluxo de aprovação autenticado continuam etapas posteriores.
15
+ - **Evidências**: `packages/adapter-nest/src/index.ts`, `packages/policy/src/index.ts`, `apps/dashboard/app/dashboard-client.tsx`, `apps/dashboard/app/api/forja/[...path]/route.ts`, 265 testes.
@@ -0,0 +1,15 @@
1
+ # ADR-0058 — Decisão de approval com identidade server-side
2
+
3
+ - **Status**: accepted
4
+ - **Data**: 2026-08-01
5
+ - **Contexto**: O dashboard precisava responder approvals sem permitir que o cliente escolhesse ou falsificasse o aprovador.
6
+ - **Decisão**: O cliente envia somente `approved` ou `rejected`. O Route Handler valida o valor, exige `FORJA_APPROVER_ID`, injeta o aprovador e timestamp, e encaminha a decisão ao Control Plane usando o token server-side.
7
+ - **Regras**:
8
+ - ausência de `FORJA_APPROVER_ID` retorna configuração indisponível;
9
+ - qualquer decisão fora do enum é rejeitada;
10
+ - o valor de `approverId` vindo do cliente é ignorado;
11
+ - Policy/ApprovalLedger continuam responsáveis por validade, expiração e idempotência semântica;
12
+ - a UI não exibe nem recebe segredo de autenticação.
13
+ - **Alternativas rejeitadas**: aceitar aprovador no body do browser; usar identidade fixa inventada; aprovar automaticamente quando não houver configuração.
14
+ - **Consequências**: O dashboard operacional exige configuração explícita do ambiente para decidir approvals. Listagem continua possível sem identidade de decisão.
15
+ - **Evidências**: `apps/dashboard/app/api/forja/approval.ts`, `apps/dashboard/app/api/forja/[...path]/route.ts`, `apps/dashboard/app/dashboard-client.tsx`, `test/dashboard-approval.test.js`, 267 testes.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "forjajs",
3
- "version": "1.7.2",
3
+ "version": "2.0.0",
4
4
  "description": "Forja — framework CLI-first de orquestração multiagente, memória hierárquica e geração de projetos com IA",
5
5
  "type": "module",
6
6
  "main": "index.js",
@@ -25,7 +25,8 @@
25
25
  ".github/copilot-instructions.md",
26
26
  ".memoryrc.json",
27
27
  "AGENTS.md",
28
- "README.en.md",
28
+ "README.md",
29
+ "README.pt-BR.md",
29
30
  "DOC-MAP.md",
30
31
  "CHANGELOG.md",
31
32
  "CONTRIBUTING.md",
@@ -83,6 +84,9 @@
83
84
  "code:impact": "node bin/forja.ts code:impact",
84
85
  "tools:doctor": "node bin/forja.ts tools:doctor",
85
86
  "release:check": "node bin/forja.ts release:check",
87
+ "dashboard:dev": "npm --prefix apps/dashboard run dev",
88
+ "dashboard:build": "npm --prefix apps/dashboard run build",
89
+ "dashboard:start": "npm --prefix apps/dashboard run start",
86
90
  "build": "tsc -p tsconfig.build.json",
87
91
  "types:check": "tsc --noEmit",
88
92
  "test": "node --test test/*.test.js"
@@ -104,13 +108,34 @@
104
108
  "author": "Allan Pablo",
105
109
  "license": "MIT",
106
110
  "dependencies": {
107
- "better-sqlite3": "^12.11.1"
111
+ "@nestjs/common": "^11.1.28",
112
+ "@nestjs/core": "^11.1.28",
113
+ "@nestjs/platform-express": "^11.1.28",
114
+ "@nestjs/swagger": "^11.4.5",
115
+ "@tanstack/react-query": "^5.90.5",
116
+ "better-sqlite3": "^12.11.1",
117
+ "next": "^16.2.12",
118
+ "react": "^19.2.0",
119
+ "react-dom": "^19.2.0",
120
+ "reflect-metadata": "^0.2.2",
121
+ "rxjs": "^7.8.2",
122
+ "swagger-ui-express": "^5.0.1"
108
123
  },
109
124
  "allowScripts": {
110
125
  "better-sqlite3@12.11.1": true
111
126
  },
127
+ "overrides": {
128
+ "next": {
129
+ "postcss": "^8.5.25",
130
+ "sharp": "^0.35.3"
131
+ }
132
+ },
112
133
  "devDependencies": {
134
+ "@types/express": "^5.0.6",
113
135
  "@types/node": "^26.1.1",
136
+ "@types/react": "^19.2.2",
137
+ "@types/react-dom": "^19.2.2",
138
+ "tsx": "^4.23.1",
114
139
  "typescript": "^5.9.3"
115
140
  }
116
141
  }
package/README.en.md DELETED
@@ -1,329 +0,0 @@
1
- <h1 align="center">🔨 Forja</h1>
2
-
3
- <p align="center">
4
- <strong>Turn coding AI into an engineering team with process and memory:<br>every project starts from a spec, every decision becomes an ADR, and nothing is lost between sessions.</strong>
5
- </p>
6
-
7
- <p align="center">
8
- <a href="https://www.npmjs.com/package/forjajs"><img src="https://img.shields.io/npm/v/forjajs?style=flat-square&color=cb3837&logo=npm" alt="npm"></a>
9
- <img src="https://github.com/allanpablo/forja/actions/workflows/ci.yml/badge.svg" alt="CI">
10
- <img src="https://img.shields.io/badge/operation-CLI--first-3553ff?style=flat-square" alt="CLI-first">
11
- <img src="https://img.shields.io/badge/agents-6_roles-orange?style=flat-square" alt="6 agents">
12
- <img src="https://img.shields.io/badge/pipeline-SDD_+_GSD-teal?style=flat-square" alt="SDD+GSD">
13
- <img src="https://img.shields.io/badge/memory-SQLite_FTS5-green?style=flat-square" alt="Memory">
14
- <img src="https://img.shields.io/badge/node-%E2%89%A520-339933?style=flat-square&logo=node.js&logoColor=white" alt="Node >= 20">
15
- <img src="https://img.shields.io/badge/license-MIT-1a1a1a?style=flat-square" alt="MIT">
16
- <img src="https://img.shields.io/badge/PRs-welcome-8957e5?style=flat-square" alt="PRs welcome">
17
- </p>
18
-
19
- <p align="center"><sub>🌐 <strong>English</strong> · <a href="README.md">Português</a></sub></p>
20
-
21
- ---
22
-
23
- ## Why Forja exists
24
-
25
- Coding agents are **amnesiac and undisciplined**: every session starts from zero, architecture
26
- decisions evaporate, code drifts from intent — and if you run several products at once, you pay
27
- that tax multiplied by N.
28
-
29
- **Forja** is the studio around the AI. It coordinates **6 agent roles** through a
30
- **Spec-Driven (SDD)** + **Get-Stuff-Done (GSD)** pipeline, keeps a **hierarchical memory** indexed
31
- in SQLite that survives across sessions, and ties it all together behind **a single core CLI with
32
- gates and an audit trail** (`forja`, ADR-0020). Multi-AI by design (Claude, Copilot, Gemini,
33
- Codex). Everything is driven from the CLI.
34
-
35
- **Who it's for**: the solo dev or small team running multiple products with AI as the main
36
- workforce — and needing the discipline of a big team without having one.
37
-
38
- ## The 3 pillars
39
-
40
- | Pillar | What it delivers | Proof |
41
- |---|---|---|
42
- | **Memory that survives** | hierarchical, searchable context, shared across sessions and AIs | SQLite FTS5, smart-context (ADR-0003) |
43
- | **Process that governs** | nothing becomes code without a spec; nothing structural without an ADR; every command audited | SDD+GSD, 7-field handoffs (ADR-0005), `forja` core (ADR-0020) |
44
- | **A factory, not a single project** | multi-product workspace, per-project agent teams | ADR-0019, harness, codegraph (ADR-0017) |
45
-
46
- > This repository is the **engine (framework)** — it does not host production apps.
47
- > Your products live in the **Forja workspace** (`~/forja-workspace` by default), outside this repo.
48
- > See ADR-0019 for the rationale.
49
-
50
- ## Forja in 60 seconds
51
-
52
- ```console
53
- $ forja spec:new pix-payments
54
- ✓ Spec created: specs/pix-payments/spec.md # nothing becomes code without this
55
-
56
- $ forja gsd:handoff plan pix-payments
57
- Handoff recorded: product → sdd-architect # 7 fields, auditable (ADR-0005)
58
-
59
- $ forja code:impact processPayment
60
- Impact map: processPayment (depth 2) # blast radius BEFORE you edit
61
- --- Direct callers ---
62
- BillingController.charge · RetryWorker.run
63
-
64
- $ forja gsd:check pix-payments
65
- OK GSD runbook OK Spec directory
66
- OK SDD spec check OK Codegraph
67
- Result: baseline gates ready. # executable governance, not a checklist
68
- ```
69
-
70
- And each command above was recorded in `.context/forja-runs.jsonl` — when governance asks "was the
71
- process followed?", the answer is a file, not a promise.
72
-
73
- ## Why not just…?
74
-
75
- | Alternative | Where it stops | What Forja adds |
76
- |---|---|---|
77
- | **Plain Claude Code / Copilot** | brilliant in-session, amnesiac between sessions | FTS5 memory + process + audit around the AI |
78
- | **LangGraph / CrewAI** | infrastructure to *build* agents | the layer above: it *operates* the agent team day to day |
79
- | **Templates & spec kits** | stop once the spec is written | the full pipeline through governance, with gates that execute |
80
-
81
- ## Key capabilities
82
-
83
- - **Single core CLI** — every process command goes through `forja <command>`: a declarative
84
- registry, cross-cutting gates (workspace), and append-only audit in
85
- `.context/forja-runs.jsonl` (ADR-0020).
86
- - **Multi-agent orchestration** — 6 roles (orchestrator, context-engineer, sdd-architect, product,
87
- marketing, governance) with tracked handoffs (7 fields, ADR-0005).
88
- - **Hierarchical memory** — global → domain → task → summary, with FTS5 search and *smart-context*
89
- in 3 modes (ADR-0003).
90
- - **SDD + GSD pipeline** — `spec → plan → tasks → check`, decisions recorded as ADRs.
91
- - **Self-verification (invariants that run)** — the framework proves itself: a family of gates guards
92
- each frontier (core, tarball, doc coherence, agent topology, generated project), and `check:all`
93
- runs the whole battery into a single verdict. Governance stops depending on discipline — it becomes
94
- harness.
95
- - **Token economy measured, not asserted** — memory (the `context.md` as a map) saves ~60% vs
96
- exploring cold, and `token:economy` **proves** it across your domains. `code:context` delivers the
97
- map ready to paste; `memory:audit` guarantees it doesn't lie about the code.
98
- - **Project generation** — `project:new` scaffolds a full project (memory, agents, multi-AI
99
- instructions, a NestJS backend as the default boilerplate) and registers the record; `project:upgrade`
100
- brings new scaffold pieces to already-generated projects without touching the user's code.
101
- - **3 integrated capabilities** (ADR-0016): **codegraph** (code analysis via MCP), **harness**
102
- (agent-team design), **ai-engineering** (knowledge base).
103
-
104
- ## ⚡ Quick start
105
-
106
- ```bash
107
- # Install (the package is forjajs; the command is forja)
108
- npm install -g forjajs
109
- forja # help grouped by domain
110
-
111
- # Prepare the production workspace (the fixed home for your projects)
112
- forja workspace:init
113
-
114
- # Create a new project (generated in ~/forja-workspace/projects/<name>)
115
- forja project:new my-project --ai claude,copilot
116
-
117
- # Enter the SDD/GSD cycle for the first feature
118
- forja spec:new my-feature
119
- forja spec:plan my-feature
120
- forja spec:tasks my-feature
121
- forja spec:check my-feature
122
- ```
123
-
124
- > Cloned the repo instead of installing? The same commands run as
125
- > `node bin/forja.ts <command>` — the npm scripts are just thin aliases of the core.
126
- > The source is TypeScript and runs natively: **dev needs Node ≥ 22.6** (type stripping). The
127
- > *published* package ships `dist/*.js` and runs on **Node ≥ 20** — the `release-gate` proves it
128
- > every release (SPEC-012).
129
-
130
- Step by step on **create vs update** a project: [`docs/processo-projeto.md`](docs/processo-projeto.md).
131
-
132
- ## How it works — the process
133
-
134
- ```
135
- 💡 Demand
136
- ├─ project does NOT exist ─► project:new + boilerplate + harness (designs the team)
137
- └─ project DOES exist ─────► overlay --only-memory + codegraph init (understands the code)
138
- │
139
- ▼
140
- CLI-first CYCLE (docs/fluxo.md):
141
- 1·Understand → 2·Specify → 3·Architect → 4·Decompose → 5·Implement → 6·Govern → ✅
142
- ```
143
-
144
- | Step | Role | Capability |
145
- |------|------|------------|
146
- | 1 Understand | context-engineer | codegraph · ai-engineering |
147
- | 2 Specify | product | — |
148
- | 3 Architect | sdd-architect | harness · ADR |
149
- | 4 Decompose | sdd-architect | — |
150
- | 5 Implement | orchestrator + worker | codegraph (MCP) |
151
- | 6 Govern | governance | codegraph (`affected`) |
152
-
153
- Full cycle map: [`docs/fluxo.md`](docs/fluxo.md).
154
-
155
- ## The 3 integrated capabilities
156
-
157
- | Capability | Role | How to use |
158
- |---|---|---|
159
- | **codegraph** | code analysis (local MCP) | `forja code:index` · `codegraph explore "<area>"` · MCP tools `codegraph_explore`/`codegraph_node` |
160
- | **harness** | agent-team design (plugin) | in a Claude Code session: _"build a harness for this project"_ → generates `.claude/agents` + `.claude/skills` |
161
- | **ai-engineering** | knowledge base (reference) | see [`docs/capacidades-externas.md`](docs/capacidades-externas.md) |
162
-
163
- Details and reinstall: [`docs/capacidades-externas.md`](docs/capacidades-externas.md) · [ADR-0016](memory/90-decisions/0016-integracao-capacidades-externas.md).
164
-
165
- ## The `forja` core
166
-
167
- Every process command goes through a single entry point (ADR-0020):
168
-
169
- ```bash
170
- forja # help grouped by domain
171
- forja <command> [args] # in a cloned repo: node bin/forja.ts <command>
172
- ```
173
-
174
- The core applies **gates** before running (e.g. product commands fail fast without a workspace) and
175
- records an **audit** of each run (command, args, exit code, duration) in
176
- `<workspace>/.context/forja-runs.jsonl` — the trail governance uses at review. The repo's npm
177
- scripts are thin aliases that route through the core.
178
-
179
- ## Essential commands
180
-
181
- ```bash
182
- # Workspace & projects
183
- forja workspace:init # create ~/forja-workspace
184
- forja project:new <name> --ai claude,copilot # create a project in the workspace
185
- forja project:list # list workspace projects
186
- forja workspace:project:check <name> # validate standards in a workspace project
187
-
188
- # SDD pipeline
189
- forja spec:new <slug> # also: spec:plan · spec:tasks · spec:check
190
-
191
- # Sprint & handoffs (GSD)
192
- forja sprint:start # also: sprint:status · sprint:complete
193
- forja gsd:plan <slug> # GSD runbook in .context/
194
- forja gsd:handoff <intent> <slug> # role-to-role handoff (ADR-0005)
195
- forja gsd:check <slug> # baseline runbook gates
196
- forja orchestrate "<goal>" --slug <s> # open a run: the SDD/GSD chain as a gated state machine (SPEC-021)
197
- forja orchestrate:status <slug> # the machine state: stages, gates, verdicts
198
- forja orchestrate:advance <slug> # run the stage gate; green → next; red → blocked
199
-
200
- # Code analysis (codegraph)
201
- forja code:check # trustworthy index (worktree + freshness)
202
- forja code:impact <symbol> # callers + blast radius before you edit
203
- forja code:query "<term>" # also: code:index · code:sync · code:status
204
-
205
- # Memory & context (workspace)
206
- forja sync:universal # reindex the workspace SQLite FTS5
207
- forja query:universal "<query>" # FTS5 search
208
- forja context:smart # smart-context (3 modes, ADR-0003)
209
- forja memory:compress # archive old runs + VACUUM
210
- forja memory:extract # extract global knowledge from memory
211
-
212
- # Quality & release
213
- forja project:check # framework standards (pre-commit)
214
- forja tools:doctor # core X-ray; exit 1 if broken
215
- forja release:check --publish # tarball gate before publishing
216
- forja project:smoke # generated-project gate; --full installs and builds the backend
217
- forja project:dashboard # static status report
218
-
219
- # Governance & audit
220
- forja audit:sync # project the audit trail into a queryable table
221
- forja audit:query --failed # query: --failed, --cmd <x>, --since 7d
222
- forja governance:dashboard # static HTML panel (gates, SDD, audit) — no server
223
- ```
224
-
225
- ## Framework vs workspace separation
226
-
227
- Forja is split in two:
228
-
229
- 1. **Framework** (this repository): the engine, conventions, scripts, and the framework's own memory.
230
- 2. **Workspace** (`~/forja-workspace` by default): the "fixed home" where product projects, their
231
- universal memory, and product specs live.
232
-
233
- The workspace path is resolved by priority:
234
-
235
- 1. `FORJA_WORKSPACE` environment variable
236
- 2. `workspaceRoot` field in `~/.forjarc.json`
237
- 3. Default: `~/forja-workspace`
238
-
239
- See ADR-0019 for the architectural decision.
240
-
241
- ## Repository structure (framework)
242
-
243
- ```
244
- bin/ CLIs (forja — the core; init-project, create-memory-nest-kit)
245
- lib/ Reusable modules; lib/core/ is the invariant engine (registry, checks, health, release, doc-graph, gates)
246
- scripts/ Automation (sprint-manager, agent-router, sync-universal-memory, …)
247
- specs/ The framework's own SDD pipeline (spec → plan → tasks)
248
- boilerplates/ Stack templates (api-rest, saas, ecommerce, microservices, monorepo)
249
- memory/ Framework memory (00-global … 90-decisions/ADRs)
250
- docs/ Documentation by persona and by topic (see DOC-MAP.md)
251
- prompts/ Portable prompts for the 6 roles
252
- .claude/ Claude Code sub-agents and settings
253
- projects/ LEGACY — do not use; projects live in the external workspace
254
- ```
255
-
256
- ## Workspace structure
257
-
258
- ```
259
- ~/forja-workspace/
260
- projects/ # generated products
261
- memory/
262
- sqlite/universal.db # SQLite FTS5 for the products
263
- 30-projects/ # project records
264
- specs/ # product specs
265
- .context/ # product GSD runbooks
266
- README.md
267
- ```
268
-
269
- ## Documentation
270
-
271
- The docs are written in **Brazilian Portuguese** — that's part of the project's identity. The CLI
272
- output, code, and ADRs are readable regardless of language.
273
-
274
- - [`DOC-MAP.md`](DOC-MAP.md) — map by role and by topic (start here)
275
- - [`docs/processo-projeto.md`](docs/processo-projeto.md) — create vs update a project
276
- - [`docs/fluxo.md`](docs/fluxo.md) — the CLI-first cycle map
277
- - [`AGENTS.md`](AGENTS.md) — the 6 roles and the topology
278
- - [`memory/90-decisions/`](memory/90-decisions/) — ADRs with rationale
279
- - [`CHANGELOG.md`](CHANGELOG.md) — history
280
-
281
- ## Conventions
282
-
283
- - **CLI-first** — sprints, SDD, GSD, handoffs, and governance by command; the UI is never a gate.
284
- - **ADRs** — every structural decision becomes `memory/90-decisions/NNNN-title.md`.
285
- - **Handoffs** — 7 required fields (ADR-0005), stored in SQLite (ADR-0008).
286
- - **pt-BR** — communication and documentation in Portuguese.
287
-
288
- ## Roadmap
289
-
290
- The throughline: **turn knowledge that lives as convention into an executable invariant.** Each item
291
- below either closes a framework frontier with a gate, or carries that pattern into generated projects.
292
-
293
- **Shipped** (through v1.6.0)
294
-
295
- - [x] **Gate family** — every framework frontier is guarded by an invariant that runs: core
296
- (`tools:doctor`, ADR-0023), tarball (`release:check`, ADR-0024), doc + ADR + agent-topology
297
- coherence (ADR-0025, SPEC-019), generated project (`project:smoke`, ADR-0029). And `check:all`
298
- runs the whole battery into one verdict (SPEC-020).
299
- - [x] **TypeScript migration complete** — source 100% `.ts`, ships `dist/`, `noImplicitAny` ON. Found
300
- latent bugs no test caught (SPEC-012).
301
- - [x] **Memory economy as a system** — **measured** (`token:economy` proves ~60% vs cold),
302
- **delivered** (`code:context`), **protected** (`memory:audit`, both directions), and **propagated**:
303
- the generated project inherits the maps gate (ADR-0030).
304
- - [x] **`project:upgrade`** — update an already-generated project without losing code: additive, never
305
- overwrites (SPEC-018).
306
- - [x] **Calibrated Clean Architecture** — layers where they pay off, lean where they don't; and the
307
- token claim **measured and corrected** — the saving is memory's, not the layers' (ADR-0027).
308
-
309
- **Next** (by dependency, not by wish)
310
-
311
- - [x] **Generated backend `builds` under new toolchains** — the template now matches the
312
- framework's `better-sqlite3` (^12, with prebuilds); `check:all --full` compiles the generated
313
- backend on Node 26.
314
- - [x] **`release-auditor` consumes the gate** — the agent runs and judges `release:check --publish`
315
- (ADR-0024), including `consumer-spec-new`; it doesn't reimplement the procedure.
316
- - [ ] **Boilerplates beyond NestJS** — the process is stack-agnostic; the templates will follow.
317
- - [ ] **(vision) the orchestration engine** — the handoff chain that **runs**, not just is coherent
318
- (SPEC-019 left it as future). The namesake executing: a 2.0 candidate.
319
-
320
- Suggestions? Open an issue — a non-trivial feature here starts from a spec, yours included.
321
-
322
- ---
323
-
324
- <p align="center">
325
- <strong>Did Forja help you tame your agents?</strong><br>
326
- A ⭐ is what carries the project to more devs still paying the amnesiac-AI tax.
327
- </p>
328
-
329
- <p align="center"><sub>Forja (npm: <code>forjajs</code>) · MIT License · <a href="CONTRIBUTING.md">Contributing</a></sub></p>