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 +44 -0
- package/README.en.md +287 -0
- package/README.md +48 -38
- package/docs/capacidades-externas.md +44 -28
- package/package.json +5 -1
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
|
|
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
|
|
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
|
|
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
|
-
|
|
97
|
+
forja workspace:init
|
|
100
98
|
|
|
101
99
|
# Criar um projeto novo (gera em ~/forja-workspace/projects/<nome>)
|
|
102
|
-
|
|
100
|
+
forja project:new meu-projeto --ai claude,copilot
|
|
103
101
|
|
|
104
102
|
# Entrar no ciclo SDD/GSD da primeira feature
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
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 ─►
|
|
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) | `
|
|
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) | `
|
|
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
|
-
|
|
152
|
-
|
|
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
|
|
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
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
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
|
-
|
|
171
|
+
forja spec:new <slug> # também: spec:plan · spec:tasks · spec:check
|
|
171
172
|
|
|
172
173
|
# Sprint & handoffs (GSD)
|
|
173
|
-
|
|
174
|
-
|
|
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
|
-
|
|
178
|
-
|
|
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
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
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
|
-
- [
|
|
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
|
|
265
|
+
## English
|
|
259
266
|
|
|
260
|
-
|
|
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
|
|
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
|
-
|
|
6
|
-
|
|
7
|
-
|
|
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`)
|
|
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
|
|
26
|
+
**CLI (via core `forja`):**
|
|
19
27
|
```bash
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
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/` (
|
|
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
|
|
33
|
-
|
|
34
|
-
|
|
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
|
-
`
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
67
|
-
|
|
68
|
-
|
|
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.
|
|
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
|
}
|