forjajs 1.1.4 → 1.1.5
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 +31 -0
- package/README.md +40 -35
- package/docs/capacidades-externas.md +44 -28
- package/package.json +4 -1
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,37 @@ Histórico consolidado das mudanças estruturais do framework. Para decisões ar
|
|
|
4
4
|
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
+
## [1.1.5] — 2026-07-14 — O comando é forja
|
|
8
|
+
|
|
9
|
+
A documentação pública ainda falava a língua interna do repo: `npm run x -- args` onde o usuário
|
|
10
|
+
do pacote tem `forja x args`. Esta versão alinha o que o README promete com o que o binário faz.
|
|
11
|
+
|
|
12
|
+
### Corrigido
|
|
13
|
+
|
|
14
|
+
- **README inteiro migrado para `forja` como forma canônica** — os scripts npm continuam
|
|
15
|
+
existindo como aliases do repo clonado, mas deixam de ser a vitrine.
|
|
16
|
+
- **Exemplos do "60 segundos" estavam quebrados**: `forja gsd:handoff -- plan …` passa o `--`
|
|
17
|
+
cru para o script (o core não filtra separador) e o comando falha. O `--` só era necessário
|
|
18
|
+
na forma `npm run`; removido dos exemplos diretos.
|
|
19
|
+
- **Comando errado na lista de essenciais**: validar projeto do workspace é
|
|
20
|
+
`workspace:project:check <nome>`, não `project:check <nome>` (que é o standards check do framework).
|
|
21
|
+
- **Links mortos**: `projects/ai-engineering-from-scratch-main/` não existe no repo;
|
|
22
|
+
`docs/capacidades-externas.md` agora aponta para as fontes upstream (ADR-0016) e a
|
|
23
|
+
reinstalação segue a prescrição do `tools:doctor` (`npm i -g @codegraph/cli`) em vez do
|
|
24
|
+
symlink manual antigo.
|
|
25
|
+
- **`package-lock.json` preso em 1.1.3** desde o bump da 1.1.4; sincronizado.
|
|
26
|
+
|
|
27
|
+
### Adicionado
|
|
28
|
+
|
|
29
|
+
- Seção "Comandos essenciais" do README ampliada com o que já existia no registry mas não
|
|
30
|
+
aparecia: `gsd:plan`/`gsd:check`, `code:check`/`code:impact`, `memory:compress`,
|
|
31
|
+
`tools:doctor`, `release:check --publish`.
|
|
32
|
+
- `allowScripts` no `package.json`: instalações com política allow-scripts ativa deixam de
|
|
33
|
+
bloquear silenciosamente o prebuild do `better-sqlite3` — exatamente o modo de falha que
|
|
34
|
+
matava a memória (ADR-0023).
|
|
35
|
+
|
|
36
|
+
---
|
|
37
|
+
|
|
7
38
|
## [1.1.4] — 2026-07-14 — Os gates
|
|
8
39
|
|
|
9
40
|
Duas fronteiras do framework funcionavam por disciplina, e a disciplina falhou nas duas. Esta versão
|
package/README.md
CHANGED
|
@@ -51,15 +51,15 @@ principal força de trabalho — e precisa da disciplina de um time grande sem t
|
|
|
51
51
|
$ forja spec:new pagamentos-pix
|
|
52
52
|
✓ Spec criada: specs/pagamentos-pix/spec.md # nada vira código sem isso
|
|
53
53
|
|
|
54
|
-
$ forja gsd:handoff
|
|
54
|
+
$ forja gsd:handoff plan pagamentos-pix
|
|
55
55
|
Handoff registrado: product → sdd-architect # 7 campos, auditável (ADR-0005)
|
|
56
56
|
|
|
57
|
-
$ forja code:impact
|
|
57
|
+
$ forja code:impact processPayment
|
|
58
58
|
Mapa de impacto: processPayment (profundidade 2) # blast radius ANTES de editar
|
|
59
59
|
--- Chamadores diretos ---
|
|
60
60
|
BillingController.charge · RetryWorker.run
|
|
61
61
|
|
|
62
|
-
$ forja gsd:check
|
|
62
|
+
$ forja gsd:check pagamentos-pix
|
|
63
63
|
OK GSD runbook OK Spec directory
|
|
64
64
|
OK SDD spec check OK Codegraph
|
|
65
65
|
Resultado: gates básicos prontos. # governança executável, não checklist
|
|
@@ -90,31 +90,30 @@ E cada comando acima ficou gravado em `.context/forja-runs.jsonl` — quando a g
|
|
|
90
90
|
# Instalar (o pacote é forjajs; o comando é forja)
|
|
91
91
|
npm install -g forjajs
|
|
92
92
|
forja # help agrupado por domínio
|
|
93
|
-
```
|
|
94
|
-
|
|
95
|
-
Ou clonando o repo:
|
|
96
93
|
|
|
97
|
-
```bash
|
|
98
94
|
# Preparar o workspace de produção (canto fixo dos projetos)
|
|
99
|
-
|
|
95
|
+
forja workspace:init
|
|
100
96
|
|
|
101
97
|
# Criar um projeto novo (gera em ~/forja-workspace/projects/<nome>)
|
|
102
|
-
|
|
98
|
+
forja project:new meu-projeto --ai claude,copilot
|
|
103
99
|
|
|
104
100
|
# Entrar no ciclo SDD/GSD da primeira feature
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
101
|
+
forja spec:new minha-feature
|
|
102
|
+
forja spec:plan minha-feature
|
|
103
|
+
forja spec:tasks minha-feature
|
|
104
|
+
forja spec:check minha-feature
|
|
109
105
|
```
|
|
110
106
|
|
|
107
|
+
> Clonou o repo em vez de instalar? Os mesmos comandos rodam como
|
|
108
|
+
> `node bin/forja.mjs <comando>` — os scripts npm são apenas aliases finos do core.
|
|
109
|
+
|
|
111
110
|
Passo a passo de **criar vs atualizar** projeto: [`docs/processo-projeto.md`](docs/processo-projeto.md).
|
|
112
111
|
|
|
113
112
|
## Como funciona — o processo
|
|
114
113
|
|
|
115
114
|
```
|
|
116
115
|
💡 Demanda
|
|
117
|
-
├─ projeto NÃO existe ─►
|
|
116
|
+
├─ projeto NÃO existe ─► project:new + boilerplate + harness (desenha o time)
|
|
118
117
|
└─ projeto JÁ existe ──► overlay --only-memory + codegraph init (entende o código)
|
|
119
118
|
│
|
|
120
119
|
▼
|
|
@@ -137,9 +136,9 @@ Mapa completo do ciclo: [`docs/fluxo.md`](docs/fluxo.md).
|
|
|
137
136
|
|
|
138
137
|
| Capacidade | Papel | Como usar |
|
|
139
138
|
|---|---|---|
|
|
140
|
-
| **codegraph** | análise de código (MCP local) | `
|
|
139
|
+
| **codegraph** | análise de código (MCP local) | `forja code:index` · `codegraph explore "<área>"` · ferramentas MCP `codegraph_explore`/`codegraph_node` |
|
|
141
140
|
| **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) | `
|
|
141
|
+
| **ai-engineering** | base de conhecimento (referência) | ver [`docs/capacidades-externas.md`](docs/capacidades-externas.md) |
|
|
143
142
|
|
|
144
143
|
Detalhes e reinstalação: [`docs/capacidades-externas.md`](docs/capacidades-externas.md) · [ADR-0016](memory/90-decisions/0016-integracao-capacidades-externas.md).
|
|
145
144
|
|
|
@@ -148,43 +147,49 @@ Detalhes e reinstalação: [`docs/capacidades-externas.md`](docs/capacidades-ext
|
|
|
148
147
|
Todos os comandos de processo passam por um único ponto de entrada (ADR-0020):
|
|
149
148
|
|
|
150
149
|
```bash
|
|
151
|
-
|
|
152
|
-
|
|
150
|
+
forja # help agrupado por domínio
|
|
151
|
+
forja <comando> [args] # no repo clonado: node bin/forja.mjs <comando>
|
|
153
152
|
```
|
|
154
153
|
|
|
155
154
|
O core aplica **gates** antes de executar (ex.: comandos de produto falham cedo sem
|
|
156
155
|
workspace) e grava **auditoria** de cada execução (comando, args, exit code, duração)
|
|
157
156
|
em `<workspace>/.context/forja-runs.jsonl` — a trilha que a governança usa no review.
|
|
158
|
-
Os scripts npm
|
|
157
|
+
Os scripts npm do repo são aliases finos que roteiam pelo core.
|
|
159
158
|
|
|
160
159
|
## Comandos essenciais
|
|
161
160
|
|
|
162
161
|
```bash
|
|
163
162
|
# Workspace & projetos
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
163
|
+
forja workspace:init # cria ~/forja-workspace
|
|
164
|
+
forja project:new <nome> --ai claude,copilot # cria projeto no workspace
|
|
165
|
+
forja project:list # lista projetos do workspace
|
|
166
|
+
forja workspace:project:check <nome> # valida padrões num projeto do workspace
|
|
168
167
|
|
|
169
168
|
# Pipeline SDD
|
|
170
|
-
|
|
169
|
+
forja spec:new <slug> # também: spec:plan · spec:tasks · spec:check
|
|
171
170
|
|
|
172
171
|
# Sprint & handoffs (GSD)
|
|
173
|
-
|
|
174
|
-
|
|
172
|
+
forja sprint:start # também: sprint:status · sprint:complete
|
|
173
|
+
forja gsd:plan <slug> # runbook GSD em .context/
|
|
174
|
+
forja gsd:handoff <intent> <slug> # handoff entre papéis (ADR-0005)
|
|
175
|
+
forja gsd:check <slug> # gates básicos do runbook
|
|
175
176
|
|
|
176
177
|
# Análise de código (codegraph)
|
|
177
|
-
|
|
178
|
-
|
|
178
|
+
forja code:check # índice confiável (worktree + freshness)
|
|
179
|
+
forja code:impact <símbolo> # chamadores + blast radius antes de editar
|
|
180
|
+
forja code:query "<termo>" # também: code:index · code:sync · code:status
|
|
179
181
|
|
|
180
182
|
# Memória & contexto (workspace)
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
183
|
+
forja sync:universal # reindexa SQLite FTS5 do workspace
|
|
184
|
+
forja query:universal "<query>" # busca FTS5
|
|
185
|
+
forja context:smart # smart-context (3 modos, ADR-0003)
|
|
186
|
+
forja memory:compress # arquiva runs antigos + VACUUM
|
|
187
|
+
|
|
188
|
+
# Qualidade & release
|
|
189
|
+
forja project:check # standards do framework (pre-commit)
|
|
190
|
+
forja tools:doctor # raio-x do núcleo; exit 1 se quebrou
|
|
191
|
+
forja release:check --publish # gate do tarball antes de publicar
|
|
192
|
+
forja project:dashboard # relatório estático de status
|
|
188
193
|
```
|
|
189
194
|
|
|
190
195
|
## Separação framework × workspace
|
|
@@ -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.5",
|
|
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",
|
|
@@ -104,5 +104,8 @@
|
|
|
104
104
|
"license": "MIT",
|
|
105
105
|
"dependencies": {
|
|
106
106
|
"better-sqlite3": "^12.11.1"
|
|
107
|
+
},
|
|
108
|
+
"allowScripts": {
|
|
109
|
+
"better-sqlite3@12.11.1": true
|
|
107
110
|
}
|
|
108
111
|
}
|