forjajs 1.1.5 → 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,19 @@ 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
+
7
20
  ## [1.1.5] — 2026-07-14 — O comando é forja
8
21
 
9
22
  A documentação pública ainda falava a língua interna do repo: `npm run x -- args` onde o usuário
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
@@ -256,13 +258,16 @@ projects/ LEGADO — não usar; projetos vivem no workspace externo
256
258
  - [ ] **Core fase 2** — CLI `forja` embutida nos projetos gerados (hoje herdam harness + instruções)
257
259
  - [ ] **Auditoria no SQLite** — promover `forja-runs.jsonl` a tabela consultável via FTS5
258
260
  - [ ] **Boilerplates além de NestJS** — o processo é agnóstico de stack; os templates vão atrás
259
- - [ ] **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)
260
262
 
261
263
  Sugestões? Abra uma issue — feature não-trivial aqui começa por spec, inclusive as suas.
262
264
 
263
- ## English summary
265
+ ## English
264
266
 
265
- **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.
266
271
 
267
272
  ---
268
273
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "forjajs",
3
- "version": "1.1.5",
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",