forjajs 1.1.4 → 1.1.6

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.
package/CHANGELOG.md CHANGED
@@ -4,6 +4,50 @@ Histórico consolidado das mudanças estruturais do framework. Para decisões ar
4
4
 
5
5
  ---
6
6
 
7
+ ## [1.1.6] — 2026-07-14 — README em inglês
8
+
9
+ A vitrine do pacote passa a ter versão em inglês, para alcançar quem chega pelo npm.
10
+
11
+ ### Adicionado
12
+ - `README.en.md` — adaptação fiel do README em português, no estilo canônico `forja <comando>`.
13
+ Seletor de idioma no topo dos dois arquivos. Incluído no `files[]` do pacote.
14
+
15
+ ### Nota
16
+ - A **documentação** (`docs/`) permanece em pt-BR — é parte da identidade do projeto. Só a capa
17
+ ganhou inglês. O README inglês foi verificado contra o registry: zero comandos inexistentes,
18
+ zero links quebrados.
19
+
20
+ ## [1.1.5] — 2026-07-14 — O comando é forja
21
+
22
+ A documentação pública ainda falava a língua interna do repo: `npm run x -- args` onde o usuário
23
+ do pacote tem `forja x args`. Esta versão alinha o que o README promete com o que o binário faz.
24
+
25
+ ### Corrigido
26
+
27
+ - **README inteiro migrado para `forja` como forma canônica** — os scripts npm continuam
28
+ existindo como aliases do repo clonado, mas deixam de ser a vitrine.
29
+ - **Exemplos do "60 segundos" estavam quebrados**: `forja gsd:handoff -- plan …` passa o `--`
30
+ cru para o script (o core não filtra separador) e o comando falha. O `--` só era necessário
31
+ na forma `npm run`; removido dos exemplos diretos.
32
+ - **Comando errado na lista de essenciais**: validar projeto do workspace é
33
+ `workspace:project:check <nome>`, não `project:check <nome>` (que é o standards check do framework).
34
+ - **Links mortos**: `projects/ai-engineering-from-scratch-main/` não existe no repo;
35
+ `docs/capacidades-externas.md` agora aponta para as fontes upstream (ADR-0016) e a
36
+ reinstalação segue a prescrição do `tools:doctor` (`npm i -g @codegraph/cli`) em vez do
37
+ symlink manual antigo.
38
+ - **`package-lock.json` preso em 1.1.3** desde o bump da 1.1.4; sincronizado.
39
+
40
+ ### Adicionado
41
+
42
+ - Seção "Comandos essenciais" do README ampliada com o que já existia no registry mas não
43
+ aparecia: `gsd:plan`/`gsd:check`, `code:check`/`code:impact`, `memory:compress`,
44
+ `tools:doctor`, `release:check --publish`.
45
+ - `allowScripts` no `package.json`: instalações com política allow-scripts ativa deixam de
46
+ bloquear silenciosamente o prebuild do `better-sqlite3` — exatamente o modo de falha que
47
+ matava a memória (ADR-0023).
48
+
49
+ ---
50
+
7
51
  ## [1.1.4] — 2026-07-14 — Os gates
8
52
 
9
53
  Duas fronteiras do framework funcionavam por disciplina, e a disciplina falhou nas duas. Esta versão
package/README.en.md ADDED
@@ -0,0 +1,287 @@
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
+ - **Project generation** — `project:new` scaffolds a full project in the workspace (memory, agents,
92
+ multi-AI instructions, a NestJS backend as the default boilerplate) and registers the project
93
+ record automatically.
94
+ - **Release gates** — `tools:doctor` fails when the core is broken (native ABI, memory, runtime
95
+ deps); `release:check` proves a clean install works before `npm publish` (ADR-0023, ADR-0024).
96
+ - **3 integrated capabilities** (ADR-0016): **codegraph** (code analysis via MCP), **harness**
97
+ (agent-team design), **ai-engineering** (knowledge base).
98
+
99
+ ## ⚡ Quick start
100
+
101
+ ```bash
102
+ # Install (the package is forjajs; the command is forja)
103
+ npm install -g forjajs
104
+ forja # help grouped by domain
105
+
106
+ # Prepare the production workspace (the fixed home for your projects)
107
+ forja workspace:init
108
+
109
+ # Create a new project (generated in ~/forja-workspace/projects/<name>)
110
+ forja project:new my-project --ai claude,copilot
111
+
112
+ # Enter the SDD/GSD cycle for the first feature
113
+ forja spec:new my-feature
114
+ forja spec:plan my-feature
115
+ forja spec:tasks my-feature
116
+ forja spec:check my-feature
117
+ ```
118
+
119
+ > Cloned the repo instead of installing? The same commands run as
120
+ > `node bin/forja.mjs <command>` — the npm scripts are just thin aliases of the core.
121
+
122
+ Step by step on **create vs update** a project: [`docs/processo-projeto.md`](docs/processo-projeto.md).
123
+
124
+ ## How it works — the process
125
+
126
+ ```
127
+ 💡 Demand
128
+ ├─ project does NOT exist ─► project:new + boilerplate + harness (designs the team)
129
+ └─ project DOES exist ─────► overlay --only-memory + codegraph init (understands the code)
130
+ │
131
+ ▼
132
+ CLI-first CYCLE (docs/fluxo.md):
133
+ 1·Understand → 2·Specify → 3·Architect → 4·Decompose → 5·Implement → 6·Govern → ✅
134
+ ```
135
+
136
+ | Step | Role | Capability |
137
+ |------|------|------------|
138
+ | 1 Understand | context-engineer | codegraph · ai-engineering |
139
+ | 2 Specify | product | — |
140
+ | 3 Architect | sdd-architect | harness · ADR |
141
+ | 4 Decompose | sdd-architect | — |
142
+ | 5 Implement | orchestrator + worker | codegraph (MCP) |
143
+ | 6 Govern | governance | codegraph (`affected`) |
144
+
145
+ Full cycle map: [`docs/fluxo.md`](docs/fluxo.md).
146
+
147
+ ## The 3 integrated capabilities
148
+
149
+ | Capability | Role | How to use |
150
+ |---|---|---|
151
+ | **codegraph** | code analysis (local MCP) | `forja code:index` · `codegraph explore "<area>"` · MCP tools `codegraph_explore`/`codegraph_node` |
152
+ | **harness** | agent-team design (plugin) | in a Claude Code session: _"build a harness for this project"_ → generates `.claude/agents` + `.claude/skills` |
153
+ | **ai-engineering** | knowledge base (reference) | see [`docs/capacidades-externas.md`](docs/capacidades-externas.md) |
154
+
155
+ Details and reinstall: [`docs/capacidades-externas.md`](docs/capacidades-externas.md) · [ADR-0016](memory/90-decisions/0016-integracao-capacidades-externas.md).
156
+
157
+ ## The `forja` core
158
+
159
+ Every process command goes through a single entry point (ADR-0020):
160
+
161
+ ```bash
162
+ forja # help grouped by domain
163
+ forja <command> [args] # in a cloned repo: node bin/forja.mjs <command>
164
+ ```
165
+
166
+ The core applies **gates** before running (e.g. product commands fail fast without a workspace) and
167
+ records an **audit** of each run (command, args, exit code, duration) in
168
+ `<workspace>/.context/forja-runs.jsonl` — the trail governance uses at review. The repo's npm
169
+ scripts are thin aliases that route through the core.
170
+
171
+ ## Essential commands
172
+
173
+ ```bash
174
+ # Workspace & projects
175
+ forja workspace:init # create ~/forja-workspace
176
+ forja project:new <name> --ai claude,copilot # create a project in the workspace
177
+ forja project:list # list workspace projects
178
+ forja workspace:project:check <name> # validate standards in a workspace project
179
+
180
+ # SDD pipeline
181
+ forja spec:new <slug> # also: spec:plan · spec:tasks · spec:check
182
+
183
+ # Sprint & handoffs (GSD)
184
+ forja sprint:start # also: sprint:status · sprint:complete
185
+ forja gsd:plan <slug> # GSD runbook in .context/
186
+ forja gsd:handoff <intent> <slug> # role-to-role handoff (ADR-0005)
187
+ forja gsd:check <slug> # baseline runbook gates
188
+
189
+ # Code analysis (codegraph)
190
+ forja code:check # trustworthy index (worktree + freshness)
191
+ forja code:impact <symbol> # callers + blast radius before you edit
192
+ forja code:query "<term>" # also: code:index · code:sync · code:status
193
+
194
+ # Memory & context (workspace)
195
+ forja sync:universal # reindex the workspace SQLite FTS5
196
+ forja query:universal "<query>" # FTS5 search
197
+ forja context:smart # smart-context (3 modes, ADR-0003)
198
+ forja memory:compress # archive old runs + VACUUM
199
+
200
+ # Quality & release
201
+ forja project:check # framework standards (pre-commit)
202
+ forja tools:doctor # core X-ray; exit 1 if broken
203
+ forja release:check --publish # tarball gate before publishing
204
+ forja project:dashboard # static status report
205
+ ```
206
+
207
+ ## Framework vs workspace separation
208
+
209
+ Forja is split in two:
210
+
211
+ 1. **Framework** (this repository): the engine, conventions, scripts, and the framework's own memory.
212
+ 2. **Workspace** (`~/forja-workspace` by default): the "fixed home" where product projects, their
213
+ universal memory, and product specs live.
214
+
215
+ The workspace path is resolved by priority:
216
+
217
+ 1. `FORJA_WORKSPACE` environment variable
218
+ 2. `workspaceRoot` field in `~/.forjarc.json`
219
+ 3. Default: `~/forja-workspace`
220
+
221
+ See ADR-0019 for the architectural decision.
222
+
223
+ ## Repository structure (framework)
224
+
225
+ ```
226
+ bin/ CLIs (init-project, create-memory-nest-kit)
227
+ lib/ Reusable modules (workspace, generators, validators, context-builder)
228
+ scripts/ Automation (sprint-manager, agent-router, sync-universal-memory, …)
229
+ specs/ The framework's own SDD pipeline (spec → plan → tasks)
230
+ boilerplates/ Stack templates (api-rest, saas, ecommerce, microservices, monorepo)
231
+ memory/ Framework memory (00-global … 90-decisions/ADRs)
232
+ docs/ Documentation by persona and by topic (see DOC-MAP.md)
233
+ prompts/ Portable prompts for the 6 roles
234
+ .claude/ Claude Code sub-agents and settings
235
+ projects/ LEGACY — do not use; projects live in the external workspace
236
+ ```
237
+
238
+ ## Workspace structure
239
+
240
+ ```
241
+ ~/forja-workspace/
242
+ projects/ # generated products
243
+ memory/
244
+ sqlite/universal.db # SQLite FTS5 for the products
245
+ 30-projects/ # project records
246
+ specs/ # product specs
247
+ .context/ # product GSD runbooks
248
+ README.md
249
+ ```
250
+
251
+ ## Documentation
252
+
253
+ The docs are written in **Brazilian Portuguese** — that's part of the project's identity. The CLI
254
+ output, code, and ADRs are readable regardless of language.
255
+
256
+ - [`DOC-MAP.md`](DOC-MAP.md) — map by role and by topic (start here)
257
+ - [`docs/processo-projeto.md`](docs/processo-projeto.md) — create vs update a project
258
+ - [`docs/fluxo.md`](docs/fluxo.md) — the CLI-first cycle map
259
+ - [`AGENTS.md`](AGENTS.md) — the 6 roles and the topology
260
+ - [`memory/90-decisions/`](memory/90-decisions/) — ADRs with rationale
261
+ - [`CHANGELOG.md`](CHANGELOG.md) — history
262
+
263
+ ## Conventions
264
+
265
+ - **CLI-first** — sprints, SDD, GSD, handoffs, and governance by command; the UI is never a gate.
266
+ - **ADRs** — every structural decision becomes `memory/90-decisions/NNNN-title.md`.
267
+ - **Handoffs** — 7 required fields (ADR-0005), stored in SQLite (ADR-0008).
268
+ - **pt-BR** — communication and documentation in Portuguese.
269
+
270
+ ## Roadmap
271
+
272
+ - [ ] **Core phase 2** — the `forja` CLI embedded in generated projects (today they inherit the
273
+ harness + instructions)
274
+ - [ ] **Audit in SQLite** — promote `forja-runs.jsonl` to a queryable FTS5 table
275
+ - [ ] **Boilerplates beyond NestJS** — the process is stack-agnostic; the templates will follow
276
+ - [x] **English README** — you're reading it
277
+
278
+ Suggestions? Open an issue — a non-trivial feature here starts from a spec, yours included.
279
+
280
+ ---
281
+
282
+ <p align="center">
283
+ <strong>Did Forja help you tame your agents?</strong><br>
284
+ A ⭐ is what carries the project to more devs still paying the amnesiac-AI tax.
285
+ </p>
286
+
287
+ <p align="center"><sub>Forja (npm: <code>forjajs</code>) · MIT License · <a href="CONTRIBUTING.md">Contributing</a></sub></p>
package/README.md CHANGED
@@ -16,6 +16,8 @@
16
16
  <img src="https://img.shields.io/badge/PRs-welcome-8957e5?style=flat-square" alt="PRs welcome">
17
17
  </p>
18
18
 
19
+ <p align="center"><sub>🌐 <a href="README.en.md">English</a> · <strong>Português</strong></sub></p>
20
+
19
21
  ---
20
22
 
21
23
  ## Por que a Forja existe
@@ -51,15 +53,15 @@ principal força de trabalho — e precisa da disciplina de um time grande sem t
51
53
  $ forja spec:new pagamentos-pix
52
54
  ✓ Spec criada: specs/pagamentos-pix/spec.md # nada vira código sem isso
53
55
 
54
- $ forja gsd:handoff -- plan pagamentos-pix
56
+ $ forja gsd:handoff plan pagamentos-pix
55
57
  Handoff registrado: product → sdd-architect # 7 campos, auditável (ADR-0005)
56
58
 
57
- $ forja code:impact -- processPayment
59
+ $ forja code:impact processPayment
58
60
  Mapa de impacto: processPayment (profundidade 2) # blast radius ANTES de editar
59
61
  --- Chamadores diretos ---
60
62
  BillingController.charge · RetryWorker.run
61
63
 
62
- $ forja gsd:check -- pagamentos-pix
64
+ $ forja gsd:check pagamentos-pix
63
65
  OK GSD runbook OK Spec directory
64
66
  OK SDD spec check OK Codegraph
65
67
  Resultado: gates básicos prontos. # governança executável, não checklist
@@ -90,31 +92,30 @@ E cada comando acima ficou gravado em `.context/forja-runs.jsonl` — quando a g
90
92
  # Instalar (o pacote é forjajs; o comando é forja)
91
93
  npm install -g forjajs
92
94
  forja # help agrupado por domínio
93
- ```
94
-
95
- Ou clonando o repo:
96
95
 
97
- ```bash
98
96
  # Preparar o workspace de produção (canto fixo dos projetos)
99
- npm run workspace:init
97
+ forja workspace:init
100
98
 
101
99
  # Criar um projeto novo (gera em ~/forja-workspace/projects/<nome>)
102
- npm run project:new meu-projeto -- --ai claude,copilot
100
+ forja project:new meu-projeto --ai claude,copilot
103
101
 
104
102
  # Entrar no ciclo SDD/GSD da primeira feature
105
- npm run spec:new -- minha-feature
106
- npm run spec:plan -- minha-feature
107
- npm run spec:tasks -- minha-feature
108
- npm run spec:check -- minha-feature
103
+ forja spec:new minha-feature
104
+ forja spec:plan minha-feature
105
+ forja spec:tasks minha-feature
106
+ forja spec:check minha-feature
109
107
  ```
110
108
 
109
+ > Clonou o repo em vez de instalar? Os mesmos comandos rodam como
110
+ > `node bin/forja.mjs <comando>` — os scripts npm são apenas aliases finos do core.
111
+
111
112
  Passo a passo de **criar vs atualizar** projeto: [`docs/processo-projeto.md`](docs/processo-projeto.md).
112
113
 
113
114
  ## Como funciona — o processo
114
115
 
115
116
  ```
116
117
  💡 Demanda
117
- ├─ projeto NÃO existe ─► init:project + boilerplate + harness (desenha o time)
118
+ ├─ projeto NÃO existe ─► project:new + boilerplate + harness (desenha o time)
118
119
  └─ projeto JÁ existe ──► overlay --only-memory + codegraph init (entende o código)
119
120
  │
120
121
  ▼
@@ -137,9 +138,9 @@ Mapa completo do ciclo: [`docs/fluxo.md`](docs/fluxo.md).
137
138
 
138
139
  | Capacidade | Papel | Como usar |
139
140
  |---|---|---|
140
- | **codegraph** | análise de código (MCP local) | `npm run code:index` · `codegraph explore "<área>"` · ferramentas MCP `codegraph_explore`/`codegraph_node` |
141
+ | **codegraph** | análise de código (MCP local) | `forja code:index` · `codegraph explore "<área>"` · ferramentas MCP `codegraph_explore`/`codegraph_node` |
141
142
  | **harness** | desenho de times de agentes (plugin) | na sessão Claude Code: _"build a harness for this project"_ → gera `.claude/agents` + `.claude/skills` |
142
- | **ai-engineering** | base de conhecimento (referência) | `projects/ai-engineering-from-scratch-main/` (ROADMAP, phases, glossary) |
143
+ | **ai-engineering** | base de conhecimento (referência) | ver [`docs/capacidades-externas.md`](docs/capacidades-externas.md) |
143
144
 
144
145
  Detalhes e reinstalação: [`docs/capacidades-externas.md`](docs/capacidades-externas.md) · [ADR-0016](memory/90-decisions/0016-integracao-capacidades-externas.md).
145
146
 
@@ -148,43 +149,49 @@ Detalhes e reinstalação: [`docs/capacidades-externas.md`](docs/capacidades-ext
148
149
  Todos os comandos de processo passam por um único ponto de entrada (ADR-0020):
149
150
 
150
151
  ```bash
151
- node bin/forja.mjs # help agrupado por domínio
152
- node bin/forja.mjs <comando> # ou, com o pacote linkado: forja <comando>
152
+ forja # help agrupado por domínio
153
+ forja <comando> [args] # no repo clonado: node bin/forja.mjs <comando>
153
154
  ```
154
155
 
155
156
  O core aplica **gates** antes de executar (ex.: comandos de produto falham cedo sem
156
157
  workspace) e grava **auditoria** de cada execução (comando, args, exit code, duração)
157
158
  em `<workspace>/.context/forja-runs.jsonl` — a trilha que a governança usa no review.
158
- Os scripts npm abaixo são aliases finos que roteiam pelo core.
159
+ Os scripts npm do repo são aliases finos que roteiam pelo core.
159
160
 
160
161
  ## Comandos essenciais
161
162
 
162
163
  ```bash
163
164
  # Workspace & projetos
164
- npm run workspace:init # cria ~/forja-workspace
165
- npm run project:new <nome> -- --ai claude,copilot # cria projeto no workspace
166
- npm run project:list # lista projetos do workspace
167
- npm run project:check <nome> # valida padrões no projeto
165
+ forja workspace:init # cria ~/forja-workspace
166
+ forja project:new <nome> --ai claude,copilot # cria projeto no workspace
167
+ forja project:list # lista projetos do workspace
168
+ forja workspace:project:check <nome> # valida padrões num projeto do workspace
168
169
 
169
170
  # Pipeline SDD
170
- npm run spec:new|plan|tasks|check -- <slug>
171
+ forja spec:new <slug> # também: spec:plan · spec:tasks · spec:check
171
172
 
172
173
  # Sprint & handoffs (GSD)
173
- npm run sprint:start | sprint:status | sprint:complete
174
- npm run gsd:handoff -- <intent> <slug> # handoff entre papéis (ADR-0005)
174
+ forja sprint:start # também: sprint:status · sprint:complete
175
+ forja gsd:plan <slug> # runbook GSD em .context/
176
+ forja gsd:handoff <intent> <slug> # handoff entre papéis (ADR-0005)
177
+ forja gsd:check <slug> # gates básicos do runbook
175
178
 
176
179
  # Análise de código (codegraph)
177
- npm run code:index | code:sync | code:status
178
- npm run code:query "<termo>"
180
+ forja code:check # índice confiável (worktree + freshness)
181
+ forja code:impact <símbolo> # chamadores + blast radius antes de editar
182
+ forja code:query "<termo>" # também: code:index · code:sync · code:status
179
183
 
180
184
  # Memória & contexto (workspace)
181
- npm run sync:universal # reindexa SQLite FTS5 do workspace
182
- npm run query:universal "<query>"
183
- npm run context:smart # smart-context
184
-
185
- # Qualidade & visão
186
- npm run project:check # standards do framework
187
- npm run project:dashboard # relatório estático de status
185
+ forja sync:universal # reindexa SQLite FTS5 do workspace
186
+ forja query:universal "<query>" # busca FTS5
187
+ forja context:smart # smart-context (3 modos, ADR-0003)
188
+ forja memory:compress # arquiva runs antigos + VACUUM
189
+
190
+ # Qualidade & release
191
+ forja project:check # standards do framework (pre-commit)
192
+ forja tools:doctor # raio-x do núcleo; exit 1 se quebrou
193
+ forja release:check --publish # gate do tarball antes de publicar
194
+ forja project:dashboard # relatório estático de status
188
195
  ```
189
196
 
190
197
  ## Separação framework × workspace
@@ -251,13 +258,16 @@ projects/ LEGADO — não usar; projetos vivem no workspace externo
251
258
  - [ ] **Core fase 2** — CLI `forja` embutida nos projetos gerados (hoje herdam harness + instruções)
252
259
  - [ ] **Auditoria no SQLite** — promover `forja-runs.jsonl` a tabela consultável via FTS5
253
260
  - [ ] **Boilerplates além de NestJS** — o processo é agnóstico de stack; os templates vão atrás
254
- - [ ] **Docs em inglês** — pt-BR continua sendo a língua do projeto
261
+ - [x] **README em inglês** — [`README.en.md`](README.en.md) (a documentação continua em pt-BR)
255
262
 
256
263
  Sugestões? Abra uma issue — feature não-trivial aqui começa por spec, inclusive as suas.
257
264
 
258
- ## English summary
265
+ ## English
259
266
 
260
- **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. It orchestrates 6 agent roles through a Spec-Driven + GSD pipeline, keeps hierarchical memory indexed in SQLite FTS5, routes every command through a single audited core CLI (`forja`), and works with Claude, Copilot, Gemini and Codex by design. Documentation is in Brazilian Portuguese — that's part of the project's identity; the CLI and the code are readable regardless.
267
+ Full English version: **[README.en.md](README.en.md)**. In short — **Forja** turns coding AI into an
268
+ engineering team with process and memory: every project starts from a spec, every structural
269
+ decision becomes an ADR, and nothing is lost between sessions. Documentation is in Brazilian
270
+ Portuguese — that's part of the project's identity; the CLI and the code are readable regardless.
261
271
 
262
272
  ---
263
273
 
@@ -1,38 +1,47 @@
1
1
  # Capacidades externas integradas
2
2
 
3
- Três produtos open-source foram alocados ao `2-projeto-agents` como capacidades de
3
+ Três produtos open-source foram integrados ao framework como capacidades de
4
4
  primeira classe (ver [ADR-0016](../memory/90-decisions/0016-integracao-capacidades-externas.md)).
5
- Antigamente viviam em `projects/`; agora estão no workspace Forja
6
- (`~/forja-workspace`, configurável — ver [ADR-0019](../memory/90-decisions/0019-workspace-separado.md)).
7
- Aqui ficam só a fiação e o modo de uso.
5
+ Os produtos em si **não são versionados neste repo** — são instalados por máquina.
6
+ O que o repo versiona é a **fiação**: `.mcp.json` (servidor MCP do codegraph),
7
+ os comandos `code:*` no registry do core e este guia. O estado da instalação na
8
+ sua máquina é reportado por `forja tools:doctor`.
9
+
10
+ | Capacidade | Eixo | Fonte |
11
+ |---|---|---|
12
+ | **codegraph** | análise de código (MCP + CLI) | [colbymchenry/codegraph](https://github.com/colbymchenry/codegraph) |
13
+ | **harness** | desenho de times de agentes (plugin Claude Code) | [revfactory/harness](https://github.com/revfactory/harness) |
14
+ | **ai-engineering-from-scratch** | base de conhecimento (referência) | [rohitg00/ai-engineering-from-scratch](https://github.com/rohitg00/ai-engineering-from-scratch) |
8
15
 
9
16
  ## 1. codegraph — análise de código (MCP)
10
17
 
11
18
  Grafo de código semântico, 100% local. Registrado como **servidor MCP** no repo
12
- (`.mcp.json`) e disponível no PATH (`~/.local/bin/codegraph`).
19
+ (`.mcp.json`, comando `codegraph serve --mcp`) — quem clona o repo herda o registro;
20
+ basta ter o binário `codegraph` no PATH.
13
21
 
14
22
  **Ferramentas MCP** (aparecem automaticamente em sessões Claude Code neste repo):
15
23
  - `codegraph_explore` — símbolos relevantes + call paths de uma área, num disparo só.
16
24
  - `codegraph_node` — fonte de um símbolo + trilha de callers/callees, ou leitura de arquivo.
17
25
 
18
- **CLI / npm scripts:**
26
+ **CLI (via core `forja`):**
19
27
  ```bash
20
- npm run code:index # codegraph init — constrói o índice inicial (respeita .gitignore)
21
- npm run code:sync # sincroniza mudanças desde o último índice
22
- npm run code:status # status e estatísticas do índice
23
- npm run code:query "<termo>" # busca símbolos
24
- codegraph explore "<query>" # exploração ad-hoc
25
- codegraph callers <símbolo> # quem chama um símbolo
28
+ forja code:index # codegraph init — constrói o índice inicial (respeita .gitignore)
29
+ forja code:sync # sincroniza mudanças desde o último índice
30
+ forja code:status # status e estatísticas do índice
31
+ forja code:query "<termo>" # busca símbolos
32
+ forja code:check # gate: índice confiável (worktree + freshness, ADR-0017)
33
+ forja code:impact <símbolo> # chamadores + blast radius antes de editar
34
+ codegraph explore "<query>" # exploração ad-hoc direto no binário
35
+ codegraph callers <símbolo> # quem chama um símbolo
26
36
  ```
27
37
 
28
- O índice fica em `.codegraph/` (já coberto por `.gitignore` do projeto, se necessário).
38
+ O índice fica em `.codegraph/` (coberto pelo `.gitignore` do projeto).
29
39
 
30
40
  ## 2. harness — orquestração de times de agentes (plugin)
31
41
 
32
- Plugin do Claude Code (`harness@harness-marketplace`, instalado e habilitado) que
33
- transforma uma descrição de domínio em um time de agentes + skills, a partir de 6
34
- padrões: Pipeline, Fan-out/Fan-in, Expert Pool, Producer-Reviewer, Supervisor,
35
- Hierarchical Delegation.
42
+ Plugin do Claude Code (`harness@harness-marketplace`) que transforma uma descrição
43
+ de domínio em um time de agentes + skills, a partir de 6 padrões: Pipeline,
44
+ Fan-out/Fan-in, Expert Pool, Producer-Reviewer, Supervisor, Hierarchical Delegation.
36
45
 
37
46
  **Uso:** numa sessão Claude Code, peça _"build a harness for this project"_ (ou
38
47
  _"configure um harness para X"_) e ele gera `.claude/agents/` e `.claude/skills/`
@@ -46,25 +55,32 @@ claude plugin update harness@harness-marketplace
46
55
  ```
47
56
 
48
57
  Complementa o sistema de orquestração nativo do framework (AGENTS.md, handoffs,
49
- `scripts/agent-router.mjs`): harness ajuda a *desenhar* novos times; o framework
50
- *opera* os handoffs.
58
+ `forja gsd:handoff` / `forja agent:route`): harness ajuda a *desenhar* novos times;
59
+ o framework *opera* os handoffs.
51
60
 
52
61
  ## 3. ai-engineering-from-scratch — base de conhecimento (referência)
53
62
 
54
63
  Currículo de AI engineering: 503 lições, 20 fases, 4 linguagens (Python, TypeScript,
55
64
  Rust, Julia). Material de referência para fundamentar decisões técnicas de IA do
56
- framework. Não há instalação — consultar diretamente:
65
+ framework. Não há instalação nem fiação — consultar direto no repositório upstream:
66
+
67
+ - [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) — índice das 20 fases.
68
+ - `phases/` — lições por fase.
69
+ - `glossary/` — glossário.
57
70
 
58
- - `projects/ai-engineering-from-scratch-main/ROADMAP.md` — índice das 20 fases.
59
- - `projects/ai-engineering-from-scratch-main/phases/` — lições por fase.
60
- - `projects/ai-engineering-from-scratch-main/glossary/` — glossário.
71
+ ## Instalação / reinstalação
61
72
 
62
- ## Reinstalação
73
+ O `forja tools:doctor` diz o que falta e como instalar. Para as capacidades deste guia:
63
74
 
64
- Se `projects/` for limpo, recriar a fiação:
65
75
  ```bash
66
- ln -sf "$PWD/projects/codegraph-linux-x64/bin/codegraph" ~/.local/bin/codegraph
67
- claude mcp add codegraph --scope project -- codegraph serve --mcp
68
- claude plugin marketplace add "$PWD/projects/harness-main"
76
+ # codegraph — binário no PATH (o .mcp.json versionado faz o resto)
77
+ npm i -g @codegraph/cli
78
+
79
+ # harness — clonar o repo e registrar como marketplace local
80
+ git clone https://github.com/revfactory/harness ~/tools/harness
81
+ claude plugin marketplace add ~/tools/harness
69
82
  claude plugin install harness@harness-marketplace
70
83
  ```
84
+
85
+ Depois, confira com `forja tools:doctor` (codegraph) e `claude plugin list` (harness).
86
+ Ferramentas ausentes apenas desativam seus gates — o fluxo nunca trava por elas.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "forjajs",
3
- "version": "1.1.4",
3
+ "version": "1.1.6",
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",
@@ -27,6 +27,7 @@
27
27
  ".github/copilot-instructions.md",
28
28
  ".memoryrc.json",
29
29
  "AGENTS.md",
30
+ "README.en.md",
30
31
  "DOC-MAP.md",
31
32
  "CHANGELOG.md",
32
33
  "CONTRIBUTING.md",
@@ -104,5 +105,8 @@
104
105
  "license": "MIT",
105
106
  "dependencies": {
106
107
  "better-sqlite3": "^12.11.1"
108
+ },
109
+ "allowScripts": {
110
+ "better-sqlite3@12.11.1": true
107
111
  }
108
112
  }