forjajs 4.1.2 → 5.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (180) hide show
  1. package/.claude/settings.json +2 -2
  2. package/.gemini-instructions.md +1 -1
  3. package/.github/copilot-instructions.md +1 -1
  4. package/.openai-instructions.md +1 -1
  5. package/CHANGELOG.md +139 -0
  6. package/DOC-MAP.md +2 -2
  7. package/README.md +62 -10
  8. package/README.pt-BR.md +46 -7
  9. package/boilerplates/01-api-rest/README.md +1 -1
  10. package/boilerplates/06-clean-arch/README.md +5 -3
  11. package/boilerplates/06-clean-arch/backend/.oxlintrc.json +10 -0
  12. package/boilerplates/06-clean-arch/backend/nest-cli.json +8 -0
  13. package/boilerplates/06-clean-arch/backend/package.json +22 -24
  14. package/boilerplates/06-clean-arch/backend/src/app.module.ts +4 -4
  15. package/boilerplates/06-clean-arch/backend/src/main.ts +2 -2
  16. package/boilerplates/06-clean-arch/backend/src/modules/orders/application/place-order.usecase.ts +4 -4
  17. package/boilerplates/06-clean-arch/backend/src/modules/orders/application/ship-order.usecase.ts +2 -2
  18. package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/order.entity.ts +3 -3
  19. package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/order.repository.ts +1 -1
  20. package/boilerplates/06-clean-arch/backend/src/modules/orders/infrastructure/typeorm-order.repository.ts +5 -5
  21. package/boilerplates/06-clean-arch/backend/src/modules/orders/orders.module.ts +6 -6
  22. package/boilerplates/06-clean-arch/backend/src/modules/orders/presentation/orders.controller.ts +3 -3
  23. package/boilerplates/06-clean-arch/backend/src/modules/products/products.controller.ts +1 -1
  24. package/boilerplates/06-clean-arch/backend/src/modules/products/products.module.ts +2 -2
  25. package/boilerplates/06-clean-arch/backend/test/orders/place-order.spec.ts +2 -2
  26. package/boilerplates/06-clean-arch/backend/tsconfig.build.json +15 -0
  27. package/boilerplates/06-clean-arch/backend/tsconfig.json +24 -10
  28. package/boilerplates/06-clean-arch/backend/vitest.config.ts +11 -0
  29. package/boilerplates/06-clean-arch/boilerplate.manifest.json +6 -5
  30. package/boilerplates/README.md +24 -44
  31. package/dist/apps/cli/src/index.js +6 -6
  32. package/dist/apps/dashboard/next.config.d.mts +5 -5
  33. package/dist/apps/server/src/app.module.js +1 -1
  34. package/dist/apps/server/src/forja-nest.module.js +1 -1
  35. package/dist/apps/server/src/index.js +1 -1
  36. package/dist/apps/server/src/main.js +20 -20
  37. package/dist/apps/worker/src/main.js +4 -4
  38. package/dist/bin/create-memory-nest-kit.js +5 -5
  39. package/dist/bin/forja.js +28 -14
  40. package/dist/bin/init-project.d.ts +4 -9
  41. package/dist/bin/init-project.js +126 -182
  42. package/dist/lib/audit.js +1 -1
  43. package/dist/lib/context-builder.d.ts +6 -1
  44. package/dist/lib/context-builder.js +21 -12
  45. package/dist/lib/core/architecture-gate.js +2 -4
  46. package/dist/lib/core/checks.d.ts +1 -1
  47. package/dist/lib/core/drift-gate.js +2 -4
  48. package/dist/lib/core/gates.js +5 -5
  49. package/dist/lib/core/health.d.ts +0 -1
  50. package/dist/lib/core/health.js +33 -7
  51. package/dist/lib/core/journey.d.ts +30 -0
  52. package/dist/lib/core/journey.js +142 -0
  53. package/dist/lib/core/model-pricing.js +3 -5
  54. package/dist/lib/core/project-smoke.d.ts +6 -2
  55. package/dist/lib/core/project-smoke.js +60 -61
  56. package/dist/lib/core/registry.d.ts +1 -12
  57. package/dist/lib/core/registry.js +42 -32
  58. package/dist/lib/core/release.d.ts +1 -1
  59. package/dist/lib/core/release.js +31 -3
  60. package/dist/lib/core/risk-collect.js +4 -4
  61. package/dist/lib/drift-sentinel.js +1 -1
  62. package/dist/lib/generators/memory-generator.d.ts +30 -30
  63. package/dist/lib/generators/memory-generator.js +19 -8
  64. package/dist/lib/generators/nest-generator.js +192 -275
  65. package/dist/lib/generators/readme-generator.js +1 -1
  66. package/dist/lib/governance-report.js +4 -4
  67. package/dist/lib/handoffs-index.d.ts +16 -2
  68. package/dist/lib/handoffs-index.js +32 -5
  69. package/dist/lib/llm/session.js +1 -1
  70. package/dist/lib/llm/validation.js +1 -1
  71. package/dist/lib/memory-audit.js +1 -1
  72. package/dist/lib/paths.d.ts +39 -0
  73. package/dist/lib/paths.js +73 -0
  74. package/dist/lib/project-upgrade.d.ts +0 -4
  75. package/dist/lib/project-upgrade.js +19 -1
  76. package/dist/lib/project-wiring.d.ts +54 -0
  77. package/dist/lib/project-wiring.js +391 -0
  78. package/dist/lib/status-model.js +18 -7
  79. package/dist/lib/templates.d.ts +24 -0
  80. package/dist/lib/templates.js +77 -0
  81. package/dist/lib/validators/structure-validator.js +0 -1
  82. package/dist/lib/workspace.d.ts +7 -0
  83. package/dist/lib/workspace.js +20 -2
  84. package/dist/packages/adapter-git/src/index.js +2 -2
  85. package/dist/packages/context/src/index.js +1 -1
  86. package/dist/packages/core/src/index.js +1 -1
  87. package/dist/packages/evals/src/index.js +1 -1
  88. package/dist/packages/events/src/index.js +1 -1
  89. package/dist/packages/graph/src/index.js +1 -1
  90. package/dist/packages/mcp/src/index.d.ts +1 -1
  91. package/dist/packages/observability/src/index.js +1 -1
  92. package/dist/packages/orchestration/src/index.js +1 -1
  93. package/dist/packages/planner/src/index.js +1 -1
  94. package/dist/packages/policy/src/index.js +1 -1
  95. package/dist/packages/runtime/src/index.js +1 -1
  96. package/dist/packages/sandbox/src/index.js +1 -1
  97. package/dist/packages/validator/src/index.js +1 -1
  98. package/dist/scripts/adr.js +4 -4
  99. package/dist/scripts/agent-harness.js +30 -23
  100. package/dist/scripts/agent-router.js +22 -5
  101. package/dist/scripts/agent.js +5 -5
  102. package/dist/scripts/architecture.js +6 -6
  103. package/dist/scripts/audit-query.js +1 -1
  104. package/dist/scripts/audit-sync.js +1 -1
  105. package/dist/scripts/build-smart-context.d.ts +19 -1
  106. package/dist/scripts/build-smart-context.js +84 -68
  107. package/dist/scripts/check-standards.js +8 -3
  108. package/dist/scripts/code-context.js +1 -1
  109. package/dist/scripts/compress-memory.js +3 -2
  110. package/dist/scripts/compress-project-memory.js +2 -2
  111. package/dist/scripts/context-ops.js +13 -5
  112. package/dist/scripts/cost-economy.js +4 -4
  113. package/dist/scripts/demo-autonomy.js +11 -11
  114. package/dist/scripts/demo-workspace.js +12 -4
  115. package/dist/scripts/dev.js +8 -7
  116. package/dist/scripts/drift-check.js +5 -5
  117. package/dist/scripts/engineer.js +11 -11
  118. package/dist/scripts/evidence.js +4 -4
  119. package/dist/scripts/extract-global-knowledge.js +6 -4
  120. package/dist/scripts/forja-setup.js +2 -1
  121. package/dist/scripts/forja-status.js +5 -4
  122. package/dist/scripts/gates.js +1 -1
  123. package/dist/scripts/generate-dashboard.js +6 -4
  124. package/dist/scripts/governance-dashboard.js +2 -2
  125. package/dist/scripts/hook-session-start.js +11 -10
  126. package/dist/scripts/hook-user-prompt.js +3 -2
  127. package/dist/scripts/incident.js +4 -4
  128. package/dist/scripts/llm-fit.js +11 -11
  129. package/dist/scripts/memory-audit.js +1 -1
  130. package/dist/scripts/memory-schema.js +3 -2
  131. package/dist/scripts/orchestrate.js +4 -5
  132. package/dist/scripts/project-smoke.js +13 -2
  133. package/dist/scripts/project-templates.d.ts +1 -0
  134. package/dist/scripts/project-templates.js +20 -0
  135. package/dist/scripts/project-upgrade.d.ts +13 -0
  136. package/dist/scripts/project-upgrade.js +110 -40
  137. package/dist/scripts/project-wire.d.ts +8 -0
  138. package/dist/scripts/project-wire.js +55 -0
  139. package/dist/scripts/provenance.js +3 -3
  140. package/dist/scripts/query-universal-memory.js +7 -4
  141. package/dist/scripts/release-check.js +1 -1
  142. package/dist/scripts/risk.js +4 -4
  143. package/dist/scripts/simulate.js +9 -9
  144. package/dist/scripts/spec-cli.d.ts +1 -0
  145. package/dist/scripts/spec-cli.js +25 -5
  146. package/dist/scripts/sprint-manager.js +4 -3
  147. package/dist/scripts/sync-universal-memory.js +22 -15
  148. package/dist/scripts/token-benchmark.js +4 -3
  149. package/dist/scripts/token-economy.js +4 -3
  150. package/dist/scripts/tools-doctor.d.ts +1 -1
  151. package/dist/scripts/tools-doctor.js +25 -3
  152. package/docs/GUIA-ONBOARDING-EXECUTIVO.md +1 -2
  153. package/docs/GUIA-ONBOARDING-OPERACIONAL-PAPEIS.md +5 -6
  154. package/docs/GUIA-ONBOARDING-PROJETO.md +7 -9
  155. package/docs/glossary.md +4 -4
  156. package/docs/init-project.md +88 -444
  157. package/docs/manual-operacional-cli-sdd-gsd.md +1 -1
  158. package/docs/modos-de-operacao.md +1 -1
  159. package/docs/processo-projeto.md +14 -11
  160. package/docs/produto/roteiro-demo.md +15 -18
  161. package/docs/publishing.md +5 -0
  162. package/docs/quick-reference.md +15 -23
  163. package/docs/structure.md +16 -30
  164. package/lib/core/model-pricing.json +19 -0
  165. package/memory/30-projects/README.md +1 -1
  166. package/memory/90-decisions/0022-congelar-dashboard-web.md +1 -1
  167. package/memory/90-decisions/0086-projeto-conectado-e-jornada-como-gate.md +95 -0
  168. package/memory/90-decisions/0087-remover-dashboard-legado.md +35 -0
  169. package/memory/90-decisions/0088-templates-validados.md +55 -0
  170. package/package.json +26 -26
  171. package/templates/project/AGENTS.md +75 -0
  172. package/templates/project/CLAUDE.md +9 -0
  173. package/templates/project/agents/context-engineer.md +15 -0
  174. package/templates/project/agents/governance.md +15 -0
  175. package/templates/project/agents/marketing.md +15 -0
  176. package/templates/project/agents/orchestrator.md +15 -0
  177. package/templates/project/agents/product.md +15 -0
  178. package/templates/project/agents/sdd-architect.md +15 -0
  179. package/dist/lib/multi-ai-instructions.d.ts +0 -28
  180. package/dist/lib/multi-ai-instructions.js +0 -83
@@ -1,457 +1,101 @@
1
- # 🚀 Init Project - Guia de Uso
1
+ # Criar um projeto — `forja project:new`
2
2
 
3
- Comando universal para iniciar novo projeto com agentes orquestrados e configuração automática de IAs.
4
-
5
- > **Atenção**: projetos de produto vivem no **workspace Forja** (`~/forja-workspace` por padrão), fora do repo do framework. Veja ADR-0019.
6
-
7
- ---
8
-
9
- ## Quick Start (2 minutos)
3
+ Cria um projeto no workspace Forja (`~/forja-workspace/projects/<nome>`) já conectado à IA que você
4
+ usa. O gerador é `bin/init-project.ts`; a conexão vem de `lib/project-wiring.ts` (ADR-0086).
10
5
 
11
6
  ```bash
12
- # 1. Ir para repo root do framework Forja
13
- cd /home/apk/Documentos/GitHub/Projetos/2-Projeto-Agents/projects/forja
14
-
15
- # 2. Inicializar o workspace (canto fixo dos projetos)
16
- npm run workspace:init
17
-
18
- # 3. Criar novo projeto (setup automático completo)
19
- npm run project:new meu-projeto
20
-
21
- # 4. Entrar no projeto
7
+ forja workspace:init # uma vez por máquina
8
+ forja project:new meu-projeto --ai claude,codex
22
9
  cd ~/forja-workspace/projects/meu-projeto
23
-
24
- # 5. Ver estrutura
25
- ls -la
26
- tree memory/ | head -30
27
-
28
- # 6. Carregar instruções para sua IA favorita
29
- cat .ia-instructions/copilot.md
30
- cat .ia-instructions/claude.md
31
- cat .ia-instructions/gemini.md
32
- ```
33
-
34
- **Resultado**: Projeto totalmente setup com:
35
- - ✅ Estrutura de memória hierárquica
36
- - ✅ Backend NestJS pronto
37
- - ✅ Instruções para 3 IAs (Copilot, Claude, Gemini)
38
- - ✅ SQLite inicializado
39
- - ✅ Context pack construído
40
- - ✅ Git configurado
41
-
42
- ---
43
-
44
- ## Sintaxe Completa
45
-
46
- ```bash
47
- # Via harness (recomendado — resolve workspace automaticamente)
48
- npm run project:new <project-name> [opções]
49
-
50
- # Via binário direto (ainda válido, mas sempre cria no workspace)
51
- node bin/init-project.js <project-name> [opções]
52
- ```
53
-
54
- ### Opções
55
-
56
- | Flag | Padrão | O quê |
57
- |------|--------|-------|
58
- | `--ai <list>` | copilot,claude,gemini,codex | IAs para configurar (comma-separated) |
59
- | `--skip-backend` | false | Pula geração do backend NestJS |
60
- | `--skip-db` | false | Pula inicialização do SQLite |
61
- | `--skip-git` | false | Pula inicialização do Git |
62
- | `--skip-design` | false | Pula cópia da biblioteca design-md |
63
- | `--interactive` | false | Modo interativo (perguntas) |
64
- | `--verbose` | false | Output detalhado |
65
-
66
- ### Workspace
67
-
68
- O caminho do workspace é resolvido por prioridade:
69
-
70
- 1. Variável de ambiente `FORJA_WORKSPACE`
71
- 2. Campo `workspaceRoot` em `~/.forjarc.json`
72
- 3. Padrão: `~/forja-workspace`
73
-
74
- ---
75
-
76
- ## Exemplos de Uso
77
-
78
- ### 1. Setup Completo (Recomendado)
79
- ```bash
80
- npm run project:new meu-projeto
81
- ```
82
- Resultado:
83
- - Projeto em `~/forja-workspace/projects/meu-projeto/`
84
- - Estrutura memória + backend NestJS
85
- - IAs: Copilot, Claude, Gemini, Codex
86
- - Git inicializado
87
- - DB setup
88
-
89
- ### 2. Só com Copilot e Claude
90
- ```bash
91
- npm run project:new meu-projeto -- --ai copilot,claude
92
- ```
93
- Resultado:
94
- - Instruções apenas para Copilot e Claude
95
- - Resto completo
96
-
97
- ### 3. Só Memória (Sem Backend)
98
- ```bash
99
- npm run project:new meu-projeto -- --skip-backend
100
- ```
101
- Resultado:
102
- - Estrutura memória + agentes + skills
103
- - SEM backend NestJS
104
- - SEM npm install
105
- - Útil para projetos frontend-only
106
-
107
- ### 4. Backend sem DB
108
- ```bash
109
- npm run project:new meu-projeto -- --skip-db
110
- ```
111
- Resultado:
112
- - Projeto completo
113
- - SQLite NÃO inicializado
114
- - Útil se quer setupar BD depois
115
-
116
- ### 5. Setup Verbose (Debug)
117
- ```bash
118
- npm run project:new meu-projeto -- --verbose
119
- ```
120
- Resultado:
121
- - Mostra todos os comandos executados
122
- - Útil para troubleshooting
123
-
124
- ### 6. Modo Interativo (Perguntas)
125
- ```bash
126
- npm run project:new -- --interactive
127
- ```
128
- Resultado:
129
- - Pergunta nome do projeto
130
- - Pergunta quais IAs configurar
131
- - Pergunta se quer backend
132
- - Etc
133
-
134
- ---
135
-
136
- ## O que o Comando Faz (Step-by-Step)
137
-
138
- ### 1️⃣ Git Init
139
- - Cria `.git` se não existir
140
- - Cria `.gitignore` básico
141
-
142
- ### 2️⃣ Generate Structure
143
- - Roda `bin/create-memory-nest-kit.js`
144
- - Cria `memory/`, `agents/`, `skills/`, `prompts/`
145
- - Cria `backend/` (se não --skip-backend)
146
- - Cria scripts úteis
147
-
148
- ### 3️⃣ Copy Instructions
149
- - Copia `.github/copilot-instructions.md`
150
- - Copia `CLAUDE.md`
151
- - Copia `.gemini-instructions.md`
152
- - Coloca em `.ia-instructions/README.md`
153
-
154
- ### 4️⃣ Install Backend
155
- - Roda `npm install` no backend
156
- - Instala: NestJS, Jest, Prettier, ESLint, etc
157
- - Toma alguns minutos na primeira vez
158
-
159
- ### 5️⃣ Init Memory DB
160
- - Roda `npm run memory:db:init`
161
- - Cria `.memory/sqlite/context.db`
162
- - Setup schema SQLite
163
-
164
- ### 6️⃣ Build Context Pack
165
- - Roda `node scripts/build-context-pack.mjs`
166
- - Cria `.context/context-pack.md`
167
- - Resumo compacto para IA ler
168
-
169
- ### 7️⃣ Show Next Steps
170
- - Exibe checklist de próximos passos
171
- - Mostra comandos importantes
172
-
173
- ---
174
-
175
- ## Estrutura Criada
176
-
177
- Após `npm run project:new meu-projeto`, o projeto é criado em `~/forja-workspace/projects/meu-projeto/`:
178
-
179
- ```
180
- ~/forja-workspace/projects/meu-projeto/
181
- ├─ .git/ # Git repository
182
- ├─ .gitignore
183
- ├─ .ia-instructions/ # Instruções por IA
184
- │ ├─ README.md
185
- │ ├─ copilot.md
186
- │ ├─ claude.md
187
- │ └─ gemini.md
188
- ├─ .context/
189
- │ └─ context-pack.md # Resumo compacto
190
- ├─ .memory/
191
- │ └─ sqlite/
192
- │ └─ context.db # SQLite DB
193
- ├─ memory/ # Estrutura hierárquica
194
- │ ├─ 00-global/
195
- │ ├─ 10-product/
196
- │ ├─ 20-architecture/
197
- │ ├─ 30-domains/
198
- │ ├─ 40-delivery/
199
- │ ├─ 50-orchestration/
200
- │ ├─ 60-runs/
201
- │ ├─ 70-summaries/
202
- │ ├─ 80-data/
203
- │ └─ 90-decisions/
204
- ├─ agents/ # Especificação de agentes
205
- │ ├─ orchestrator.md
206
- │ ├─ backend-nest.md
207
- │ ├─ frontend.md
208
- │ ├─ dba.md
209
- │ ├─ security.md
210
- │ ├─ reviewer.md
211
- │ └─ README.md
212
- ├─ skills/ # Skills operacionais
213
- │ ├─ triage-task/
214
- │ ├─ context-compaction/
215
- │ ├─ handoff/
216
- │ └─ nest-api/
217
- ├─ prompts/ # Templates de prompts
218
- │ ├─ project-prompt-base.md
219
- │ ├─ multi-agent-orchestrator.md
220
- │ └─ worker-task-template.md
221
- ├─ scripts/
222
- │ ├─ build-context-pack.mjs # Compactar contexto
223
- │ └─ append-handoff.mjs # Criar handoff
224
- ├─ docs/ # Documentação adicional
225
- ├─ backend/ # NestJS (se não --skip-backend)
226
- │ ├─ src/
227
- │ ├─ test/
228
- │ ├─ scripts/
229
- │ │ ├─ memory-db-init.mjs
230
- │ │ ├─ memory-db-sync.mjs
231
- │ │ ├─ memory-db-query.mjs
232
- │ │ └─ memory-db-schema.sql
233
- │ ├─ package.json
234
- │ ├─ tsconfig.json
235
- │ └─ nest-cli.json
236
- ├─ README.md
237
- └─ AGENTS.md
238
- ```
239
-
240
- ---
241
-
242
- ## Workflow Após Init
243
-
244
- ### Copilot / Claude / Gemini Setup
245
-
246
- ```bash
247
- # 1. Ver instruções
248
- cat ~/forja-workspace/projects/meu-projeto/.ia-instructions/copilot.md
249
-
250
- # 2. Copiar para IA assistant
251
- # - Abra seu editor com Copilot/Claude
252
- # - New chat
253
- # - Paste conteúdo do arquivo
254
- # - Pronto! IA entende seu projeto
255
-
256
- # 3. Pedir para IA:
257
- # "Implemente endpoint GET /users/:id com validação de UUID"
258
- # "Crie teste para criar novo usuário"
259
- # etc
260
- ```
261
-
262
- ### Desenvolvimento Local
263
-
264
- ```bash
265
- cd ~/forja-workspace/projects/meu-projeto
266
-
267
- # Ver estrutura de memória
268
- tree memory/ -L 2
269
-
270
- # Carregar contexto para IA
271
- cat .context/context-pack.md | head -100
272
-
273
- # Iniciar backend em dev
274
- cd backend && npm run start:dev
275
-
276
- # Rodar testes
277
- cd backend && npm test
278
-
279
- # Sincronizar BD (após mudanças grandes)
280
- cd backend && npm run memory:db:sync
281
-
282
- # Consultar contexto
283
- cd backend && npm run memory:db:query -- "search" "auth" 10
284
- ```
285
-
286
- ### Registrar Handoff (Quando Passar para Outro Agente)
10
+ forja project:wire --check # tudo conectado?
11
+ forja status # memória indexada, specs, handoffs
12
+ ```
13
+
14
+ ## Opções
15
+
16
+ | Opção | Padrão | Efeito |
17
+ |---|---|---|
18
+ | `--ai <lista>` | `copilot,claude,gemini,codex` | IAs a conectar |
19
+ | `--template <nome>` | — | Parte de um template validado (`forja project:templates`) |
20
+ | `--skip-backend` | — | Não gera nem instala o backend NestJS |
21
+ | `--skip-db` | — | Não indexa a memória do projeto |
22
+ | `--skip-git` | — | Não roda `git init` |
23
+ | `--skip-design` | — | Não copia a biblioteca `design-md/` |
24
+ | `--verbose` | — | Saída detalhada (ex.: erros do `npm install`) |
25
+
26
+ O workspace é resolvido por: `FORJA_WORKSPACE` → `workspaceRoot` em `~/.forjarc.json` →
27
+ `~/forja-workspace`.
28
+
29
+ ## O que acontece, em ordem
30
+
31
+ 1. **git init** e `.gitignore` inicial.
32
+ 2. **Memória e agentes** (`create-memory-nest-kit`): `memory/` hierárquica (00-global a
33
+ 90-decisions), `agents/`, `prompts/`, `skills/`, `specs/` e o backend NestJS (exceto com
34
+ `--skip-backend`). O backend segue o `nest new` do NestJS 12: ESM, Vitest, oxlint; a página
35
+ `/api/ops` mostra specs, handoffs e a memória indexada do projeto.
36
+ - Com `--template`, o backend e a memória específica vêm do boilerplate (ADR-0088).
37
+ 3. **design-md/**: biblioteca de referências de design.
38
+ 4. **Conexão com a IA**:
39
+ - `AGENTS.md` com o bloco do Forja (lido por Codex, Copilot agent e Gemini).
40
+ - `CLAUDE.md` e `GEMINI.md` importando o `AGENTS.md`; `.github/copilot-instructions.md`.
41
+ - `.claude/settings.json`: hooks `forja hook:session-start` (briefing da sessão) e
42
+ `forja hook:user-prompt` (anexa a spec citada), mais a permissão `Bash(forja *)`.
43
+ - `.claude/agents/`: orchestrator, product, sdd-architect, context-engineer, governance, marketing.
44
+ - `.mcp.json`: servidor `forja mcp:start` (e `codegraph`, se instalado); o mesmo servidor em
45
+ `.codex/config.toml` (Codex), `.gemini/settings.json` (Gemini) e `.vscode/mcp.json` (Copilot).
46
+ - `.forja/models.json`: cadeia de fallback entre IAs.
47
+ - `memory/sqlite/` e `.context/` no `.gitignore`.
48
+ 5. **npm install** do backend.
49
+ 6. **Indexação da memória** (`forja sync:universal` no projeto).
50
+ 7. **Context pack** em `.context/context-pack.md`.
51
+ 8. **Ficha** do projeto em `<workspace>/memory/30-projects/<nome>.md`.
52
+
53
+ No fim aparece um resumo. Falha essencial (ex.: a conexão não verificou) faz o comando sair com
54
+ **exit 1** e listar cada pendência. Falha recuperável (ex.: `npm install` sem rede) aparece como
55
+ pendência, com o comando para refazer.
56
+
57
+ ## O que a IA encontra ao abrir o projeto
58
+
59
+ - **Claude Code**: lê o `CLAUDE.md` → `AGENTS.md`; o hook de sessão injeta specs ativas, handoffs
60
+ do projeto e a saúde do núcleo; ao citar uma spec no prompt, o hook anexa spec, plan e tasks.
61
+ - **Codex / Copilot / Gemini**: leem o `AGENTS.md` (o Gemini via `GEMINI.md`, o Copilot via
62
+ `.github/copilot-instructions.md`).
63
+ - **Qualquer IA com MCP**: as capacidades do Forja como ferramentas (`forja mcp:start`).
64
+
65
+ Hooks e MCP chamam o binário `forja`. Instale-o globalmente (`npm i -g forjajs`). Sem ele, a sessão
66
+ abre normalmente e o `project:wire --check` avisa.
67
+
68
+ ## Seu conteúdo é preservado
69
+
70
+ Em `AGENTS.md`, `CLAUDE.md`, `GEMINI.md` e no arquivo do Copilot, o Forja só reescreve o trecho entre
71
+ `<!-- forja:begin -->` e `<!-- forja:end -->`. Um sub-agent em `.claude/agents/` que você editar e do
72
+ qual remover a marca `<!-- forja:managed -->` não é mais tocado. Hooks e servidores MCP seus em
73
+ `.claude/settings.json`/`.mcp.json` são mantidos; o Forja só acrescenta os dele.
74
+
75
+ ## Projeto existente ou gerado antes da v5
287
76
 
288
77
  ```bash
289
78
  cd meu-projeto
290
-
291
- # Criar handoff estruturado
292
- node scripts/append-handoff.mjs orchestrator backend-nest "Implementar módulo de autenticação com JWT"
293
-
294
- # Resultado: novo arquivo em memory/50-orchestration/handoffs/
295
- ```
296
-
297
- ### Atualizar Documentação
298
-
299
- ```bash
300
- # Após mudanças importantes
301
- vim memory/20-architecture/backend.md
302
- vim memory/30-domains/auth/rules.md
303
-
304
- # Sincronizar DB
305
- cd backend && npm run memory:db:sync
306
- ```
307
-
308
- ---
309
-
310
- ## Troubleshooting
311
-
312
- ### "Node not found"
313
- ```bash
314
- # Instalar Node.js >= 18
315
- curl -fsSL https://fnm.io/install | bash
316
- fnm install 18
317
- fnm use 18
318
- node --version
319
- ```
320
-
321
- ### "npm install falha"
322
- ```bash
323
- # Limpar cache
324
- npm cache clean --force
325
-
326
- # Atualizar npm
327
- npm install -g npm@latest
328
-
329
- # Tentar novamente
330
- node bin/init-project.js meu-projeto --verbose
331
- ```
332
-
333
- ### "Git conflicts"
334
- ```bash
335
- # Se projeto já existe com Git
336
- node bin/init-project.js meu-projeto --force --skip-git
337
- ```
338
-
339
- ### "BD não inicializa"
340
- ```bash
341
- # Manual
342
- cd meu-projeto/backend
343
- npm run memory:db:init
344
- npm run memory:db:sync
345
- ```
346
-
347
- ### "Backend não compila"
348
- ```bash
349
- # Debug detalhado
350
- cd meu-projeto/backend
351
- npm run build -- --verbose
352
- npm run lint
353
- npm test
354
- ```
355
-
356
- ---
357
-
358
- ## Integração com CI/CD
359
-
360
- ### GitHub Actions
361
-
362
- ```yaml
363
- # .github/workflows/init-new-project.yml
364
- name: Create New Project
365
- on:
366
- workflow_dispatch:
367
- inputs:
368
- project_name:
369
- description: "Nome do projeto"
370
- required: true
371
-
372
- jobs:
373
- init:
374
- runs-on: ubuntu-latest
375
- steps:
376
- - uses: actions/checkout@v3
377
- - uses: actions/setup-node@v3
378
- with:
379
- node-version: "18"
380
-
381
- - name: Init project
382
- run: |
383
- node bin/init-project.js ${{ github.event.inputs.project_name }} \
384
- --ai copilot,claude,gemini
385
-
386
- - name: Commit and push
387
- run: |
388
- git config user.email "bot@example.com"
389
- git config user.name "Bot"
390
- git add .
391
- git commit -m "feat: init project ${{ github.event.inputs.project_name }}"
392
- git push
393
- ```
394
-
395
- ---
396
-
397
- ## Próximas Features Planejadas
398
-
399
- - [ ] --ai-config: arquivo YAML com config por IA
400
- - [ ] --template: escolher template (web, api, fullstack)
401
- - [ ] --preset: preset de IAs (solo, team, enterprise)
402
- - [ ] --github-org: criar repo automático
403
- - [ ] --docker: Dockerfile pronto
404
- - [ ] --k8s: deployment manifests
405
-
406
- ---
407
-
408
- ## Sumário de Comandos Frequentes
409
-
410
- ```bash
411
- # Inicializar workspace (uma vez)
412
- npm run workspace:init
413
-
414
- # Criar novo projeto (tudo automático)
415
- npm run project:new meu-projeto
416
-
417
- # Variantes
418
- npm run project:new meu-projeto -- --skip-backend
419
- npm run project:new meu-projeto -- --ai claude,copilot
420
- npm run project:new meu-projeto -- --verbose
421
-
422
- # Dentro do projeto
423
- cd ~/forja-workspace/projects/meu-projeto
424
-
425
- # Ver instruções para IA
426
- cat .ia-instructions/copilot.md
427
-
428
- # Ver contexto resumido
429
- cat .context/context-pack.md | head -50
430
-
431
- # Rodar backend
432
- cd backend && npm run start:dev
433
-
434
- # Sincronizar memória
435
- cd backend && npm run memory:db:sync
436
-
437
- # Criar handoff
438
- node scripts/append-handoff.mjs orchestrator backend-nest "tarefa"
439
-
440
- # Query contexto
441
- cd backend && npm run memory:db:query -- "search" "auth" 10
79
+ forja project:upgrade # dry-run: peças de scaffold novas + conexão a refazer
80
+ forja project:upgrade --apply # aplica (aditivo; nunca toca backend/, frontend/, apps/ nem src/)
81
+ forja project:wire --check
442
82
  ```
443
83
 
444
- ---
445
-
446
- ## Help Rápido
84
+ Para o workspace inteiro: `forja project:upgrade --all` (relatório por projeto) e depois
85
+ `--all --apply`.
447
86
 
448
- ```bash
449
- node bin/init-project.js --help
450
- ```
87
+ Num repositório que nunca foi Forja, comece por `forja project:wire --ai claude,codex` e depois rode
88
+ o `project:upgrade --apply`.
451
89
 
452
- ---
90
+ ## Problemas comuns
453
91
 
454
- **Criado**: 2026-04-21
455
- **Status**: 🟢 Pronto para Uso
456
- **Próximo**: Implementar em `bin/init-project.js` (já feito!)
92
+ | Sintoma | Causa | Correção |
93
+ |---|---|---|
94
+ | `Workspace não encontrado` | workspace não criado | `forja workspace:init` (ou `forja setup`) |
95
+ | `Projeto ja existe no workspace` | nome em uso | escolha outro nome ou use `project:upgrade` dentro dele |
96
+ | `npm install do backend falhou` | sem rede/registry | `cd backend && npm install` depois |
97
+ | Briefing não aparece no Claude Code | `forja` fora do PATH | `npm i -g forjajs`; confira com `forja project:wire --check` |
98
+ | `project:wire --check` com FAIL | arquivo de conexão ausente/alterado | `forja project:wire` |
457
99
 
100
+ Veja também: [`processo-projeto.md`](processo-projeto.md) (criar × atualizar) e a
101
+ [ADR-0086](../memory/90-decisions/0086-projeto-conectado-e-jornada-como-gate.md).
@@ -51,7 +51,7 @@ memory/50-orchestration/ Protocolos de orquestracao
51
51
  memory/90-decisions/ ADRs e decisoes estruturais
52
52
  scripts/ Harness CLI, sprint, specs, checks
53
53
  .context/ Runbooks GSD e context packs
54
- dashboard/ Web opcional/legada
54
+ apps/dashboard/ Dashboard web opcional (npm run dashboard:api + dashboard:dev)
55
55
  ```
56
56
 
57
57
  Arquivos que voce vai abrir com frequencia:
@@ -29,7 +29,7 @@ Use `FORJA_MODE=embedded` para forçar esse comportamento em um diretório sem `
29
29
 
30
30
  O studio administra vários projetos num workspace externo. Os comandos de catálogo entram nesse modo
31
31
  automaticamente: `workspace:init`, `project:new`, `project:list`, `project:upgrade`,
32
- `workspace:project:check`, `init:project` e `demo:workspace`.
32
+ `workspace:project:check` e `demo:workspace`.
33
33
 
34
34
  ```bash
35
35
  forja workspace:init
@@ -17,14 +17,14 @@ flowchart TD
17
17
  D(["💡 Demanda"]) --> Q{"Projeto já<br/>existe?"}
18
18
 
19
19
  %% ── Ramo A: NOVO ──
20
- Q -- "Não" --> A1["A1· Gerar scaffold<br/>npm run init:project &lt;nome&gt; --ai claude,copilot"]
20
+ Q -- "Não" --> A1["A1· Gerar scaffold<br/>forja project:new &lt;nome&gt; -- --ai claude,copilot"]
21
21
  A1 --> A2["A2· Escolher boilerplate<br/>api-rest · saas · ecommerce · microservices · monorepo"]
22
22
  A2 --> A3["A3· (opcional) harness<br/>desenha o time de agentes do domínio"]
23
23
  A3 --> C0
24
24
 
25
25
  %% ── Ramo B: EXISTENTE ──
26
26
  Q -- "Sim" --> B0{"Já tem<br/>memory/?"}
27
- B0 -- "Não" --> B1["B1· Overlay de memória<br/>init:project detecta backend → --only-memory"]
27
+ B0 -- "Não" --> B1["B1· Conectar + memória<br/>project:wire + project:upgrade --apply"]
28
28
  B0 -- "Sim" --> B2["B2· Indexar código<br/>codegraph init (entender o que existe)"]
29
29
  B1 --> B2
30
30
  B2 --> C0
@@ -43,12 +43,12 @@ flowchart TD
43
43
  ```
44
44
  💡 Demanda
45
45
  │
46
- ├─ projeto NÃO existe ─► A1 init:project <nome> --ai …
46
+ ├─ projeto NÃO existe ─► A1 forja project:new <nome> -- --ai …
47
47
  │ A2 escolher boilerplate
48
48
  │ A3 (opc.) harness desenha o time ─┐
49
49
  │ │
50
50
  └─ projeto JÁ existe ──► tem memory/? │
51
- ├─ não ► B1 overlay --only-memory │
51
+ ├─ não ► B1 wire + upgrade │
52
52
  └─ sim ─┘ │
53
53
  B2 codegraph init ────────┤
54
54
  ▼
@@ -61,10 +61,11 @@ flowchart TD
61
61
 
62
62
  ## Ramo A — Criar projeto novo
63
63
 
64
- O gerador (`bin/init-project.js`) roda 8 passos: git-init → estrutura agentes+memória
65
- → design-lib → instruções multi-IA → install-backend → init memória SQLite →
66
- context-pack → next-steps. Cada projeto nasce com `memory/`, `.ia-instructions/`
67
- (claude/copilot/gemini/codex) e seu próprio banco de memória.
64
+ O gerador (`bin/init-project.ts`, via `forja project:new`) roda: git-init → estrutura
65
+ agentes+memória → design-lib → conexão com a IA (`AGENTS.md`/`CLAUDE.md`/`GEMINI.md`/Copilot,
66
+ hooks, sub-agents, MCP — ADR-0086) → install-backend → indexação da memória → context-pack →
67
+ resumo. Se algo essencial falhar, o comando sai com exit 1 e lista as pendências. Confira a
68
+ conexão a qualquer momento com `forja project:wire --check`.
68
69
 
69
70
  Projetos de produto vivem no **workspace Forja** (`~/forja-workspace/projects/<nome>`
70
71
  por padrão), fora do repo do framework. Veja ADR-0019.
@@ -91,9 +92,11 @@ npm run spec:new -- <slug>
91
92
  ## Ramo B — Atualizar projeto existente
92
93
 
93
94
  ```bash
94
- # B1. projeto sem memória ainda? sobrepõe só a camada de memória/agentes
95
- # (init:project detecta backend e aplica --only-memory automaticamente)
96
- npm run init:project <nome> # apontando para o projeto existente
95
+ # B1. dentro do repositório existente: liga a IA ao Forja e traz a camada de memória/agentes
96
+ # (aditivo: não instala backend e não sobrescreve arquivos do projeto)
97
+ forja project:wire --ai claude,codex
98
+ forja project:upgrade --apply
99
+ forja sync:universal
97
100
 
98
101
  # B2. indexar o código atual ANTES de mexer (entender sem ler arquivo a arquivo)
99
102
  codegraph init # ou: npm run code:index