forjajs 4.1.2 → 5.0.0
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/.claude/settings.json +2 -2
- package/.gemini-instructions.md +1 -1
- package/.github/copilot-instructions.md +1 -1
- package/.openai-instructions.md +1 -1
- package/CHANGELOG.md +109 -0
- package/DOC-MAP.md +2 -2
- package/README.md +62 -10
- package/README.pt-BR.md +46 -7
- package/boilerplates/01-api-rest/README.md +1 -1
- package/boilerplates/06-clean-arch/README.md +5 -3
- package/boilerplates/06-clean-arch/backend/.oxlintrc.json +10 -0
- package/boilerplates/06-clean-arch/backend/nest-cli.json +8 -0
- package/boilerplates/06-clean-arch/backend/package.json +22 -24
- package/boilerplates/06-clean-arch/backend/src/app.module.ts +4 -4
- package/boilerplates/06-clean-arch/backend/src/main.ts +2 -2
- package/boilerplates/06-clean-arch/backend/src/modules/orders/application/place-order.usecase.ts +4 -4
- package/boilerplates/06-clean-arch/backend/src/modules/orders/application/ship-order.usecase.ts +2 -2
- package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/order.entity.ts +3 -3
- package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/order.repository.ts +1 -1
- package/boilerplates/06-clean-arch/backend/src/modules/orders/infrastructure/typeorm-order.repository.ts +5 -5
- package/boilerplates/06-clean-arch/backend/src/modules/orders/orders.module.ts +6 -6
- package/boilerplates/06-clean-arch/backend/src/modules/orders/presentation/orders.controller.ts +3 -3
- package/boilerplates/06-clean-arch/backend/src/modules/products/products.controller.ts +1 -1
- package/boilerplates/06-clean-arch/backend/src/modules/products/products.module.ts +2 -2
- package/boilerplates/06-clean-arch/backend/test/orders/place-order.spec.ts +2 -2
- package/boilerplates/06-clean-arch/backend/tsconfig.build.json +15 -0
- package/boilerplates/06-clean-arch/backend/tsconfig.json +24 -10
- package/boilerplates/06-clean-arch/backend/vitest.config.ts +11 -0
- package/boilerplates/06-clean-arch/boilerplate.manifest.json +6 -5
- package/boilerplates/README.md +24 -44
- package/dist/apps/cli/src/index.js +6 -6
- package/dist/apps/dashboard/next.config.d.mts +5 -5
- package/dist/apps/server/src/app.module.js +1 -1
- package/dist/apps/server/src/forja-nest.module.js +1 -1
- package/dist/apps/server/src/index.js +1 -1
- package/dist/apps/server/src/main.js +20 -20
- package/dist/apps/worker/src/main.js +4 -4
- package/dist/bin/create-memory-nest-kit.js +5 -5
- package/dist/bin/forja.js +28 -14
- package/dist/bin/init-project.d.ts +4 -9
- package/dist/bin/init-project.js +126 -182
- package/dist/lib/audit.js +1 -1
- package/dist/lib/context-builder.d.ts +6 -1
- package/dist/lib/context-builder.js +21 -12
- package/dist/lib/core/architecture-gate.js +2 -4
- package/dist/lib/core/checks.d.ts +1 -1
- package/dist/lib/core/drift-gate.js +2 -4
- package/dist/lib/core/gates.js +5 -5
- package/dist/lib/core/health.d.ts +0 -1
- package/dist/lib/core/health.js +33 -7
- package/dist/lib/core/journey.d.ts +30 -0
- package/dist/lib/core/journey.js +142 -0
- package/dist/lib/core/model-pricing.js +3 -5
- package/dist/lib/core/project-smoke.d.ts +6 -2
- package/dist/lib/core/project-smoke.js +60 -61
- package/dist/lib/core/registry.d.ts +1 -12
- package/dist/lib/core/registry.js +42 -32
- package/dist/lib/core/release.d.ts +1 -1
- package/dist/lib/core/release.js +31 -3
- package/dist/lib/core/risk-collect.js +4 -4
- package/dist/lib/drift-sentinel.js +1 -1
- package/dist/lib/generators/memory-generator.d.ts +30 -30
- package/dist/lib/generators/memory-generator.js +19 -8
- package/dist/lib/generators/nest-generator.js +192 -275
- package/dist/lib/generators/readme-generator.js +1 -1
- package/dist/lib/governance-report.js +4 -4
- package/dist/lib/handoffs-index.d.ts +16 -2
- package/dist/lib/handoffs-index.js +32 -5
- package/dist/lib/llm/session.js +1 -1
- package/dist/lib/llm/validation.js +1 -1
- package/dist/lib/memory-audit.js +1 -1
- package/dist/lib/paths.d.ts +39 -0
- package/dist/lib/paths.js +73 -0
- package/dist/lib/project-wiring.d.ts +54 -0
- package/dist/lib/project-wiring.js +391 -0
- package/dist/lib/status-model.js +18 -7
- package/dist/lib/templates.d.ts +24 -0
- package/dist/lib/templates.js +77 -0
- package/dist/lib/validators/structure-validator.js +0 -1
- package/dist/lib/workspace.d.ts +7 -0
- package/dist/lib/workspace.js +20 -2
- package/dist/packages/adapter-git/src/index.js +2 -2
- package/dist/packages/context/src/index.js +1 -1
- package/dist/packages/core/src/index.js +1 -1
- package/dist/packages/evals/src/index.js +1 -1
- package/dist/packages/events/src/index.js +1 -1
- package/dist/packages/graph/src/index.js +1 -1
- package/dist/packages/mcp/src/index.d.ts +1 -1
- package/dist/packages/observability/src/index.js +1 -1
- package/dist/packages/orchestration/src/index.js +1 -1
- package/dist/packages/planner/src/index.js +1 -1
- package/dist/packages/policy/src/index.js +1 -1
- package/dist/packages/runtime/src/index.js +1 -1
- package/dist/packages/sandbox/src/index.js +1 -1
- package/dist/packages/validator/src/index.js +1 -1
- package/dist/scripts/adr.js +4 -4
- package/dist/scripts/agent-harness.js +30 -23
- package/dist/scripts/agent-router.js +22 -5
- package/dist/scripts/agent.js +5 -5
- package/dist/scripts/architecture.js +6 -6
- package/dist/scripts/audit-query.js +1 -1
- package/dist/scripts/audit-sync.js +1 -1
- package/dist/scripts/build-smart-context.d.ts +19 -1
- package/dist/scripts/build-smart-context.js +84 -68
- package/dist/scripts/check-standards.js +8 -3
- package/dist/scripts/code-context.js +1 -1
- package/dist/scripts/compress-memory.js +3 -2
- package/dist/scripts/compress-project-memory.js +2 -2
- package/dist/scripts/context-ops.js +13 -5
- package/dist/scripts/cost-economy.js +4 -4
- package/dist/scripts/demo-autonomy.js +11 -11
- package/dist/scripts/demo-workspace.js +12 -4
- package/dist/scripts/dev.js +8 -7
- package/dist/scripts/drift-check.js +5 -5
- package/dist/scripts/engineer.js +11 -11
- package/dist/scripts/evidence.js +4 -4
- package/dist/scripts/extract-global-knowledge.js +6 -4
- package/dist/scripts/forja-setup.js +2 -1
- package/dist/scripts/forja-status.js +5 -4
- package/dist/scripts/gates.js +1 -1
- package/dist/scripts/generate-dashboard.js +6 -4
- package/dist/scripts/governance-dashboard.js +2 -2
- package/dist/scripts/hook-session-start.js +11 -10
- package/dist/scripts/hook-user-prompt.js +3 -2
- package/dist/scripts/incident.js +4 -4
- package/dist/scripts/llm-fit.js +11 -11
- package/dist/scripts/memory-audit.js +1 -1
- package/dist/scripts/memory-schema.js +3 -2
- package/dist/scripts/orchestrate.js +4 -5
- package/dist/scripts/project-smoke.js +13 -2
- package/dist/scripts/project-templates.d.ts +1 -0
- package/dist/scripts/project-templates.js +20 -0
- package/dist/scripts/project-upgrade.d.ts +13 -0
- package/dist/scripts/project-upgrade.js +107 -40
- package/dist/scripts/project-wire.d.ts +8 -0
- package/dist/scripts/project-wire.js +55 -0
- package/dist/scripts/provenance.js +3 -3
- package/dist/scripts/query-universal-memory.js +7 -4
- package/dist/scripts/release-check.js +1 -1
- package/dist/scripts/risk.js +4 -4
- package/dist/scripts/simulate.js +9 -9
- package/dist/scripts/spec-cli.d.ts +1 -0
- package/dist/scripts/spec-cli.js +25 -5
- package/dist/scripts/sprint-manager.js +4 -3
- package/dist/scripts/sync-universal-memory.js +22 -15
- package/dist/scripts/token-benchmark.js +4 -3
- package/dist/scripts/token-economy.js +4 -3
- package/dist/scripts/tools-doctor.d.ts +1 -1
- package/dist/scripts/tools-doctor.js +25 -3
- package/docs/GUIA-ONBOARDING-EXECUTIVO.md +1 -2
- package/docs/GUIA-ONBOARDING-OPERACIONAL-PAPEIS.md +5 -6
- package/docs/GUIA-ONBOARDING-PROJETO.md +7 -9
- package/docs/glossary.md +4 -4
- package/docs/init-project.md +88 -444
- package/docs/manual-operacional-cli-sdd-gsd.md +1 -1
- package/docs/modos-de-operacao.md +1 -1
- package/docs/processo-projeto.md +14 -11
- package/docs/produto/roteiro-demo.md +15 -18
- package/docs/publishing.md +5 -0
- package/docs/quick-reference.md +15 -23
- package/docs/structure.md +16 -30
- package/lib/core/model-pricing.json +19 -0
- package/memory/30-projects/README.md +1 -1
- package/memory/90-decisions/0022-congelar-dashboard-web.md +1 -1
- package/memory/90-decisions/0086-projeto-conectado-e-jornada-como-gate.md +95 -0
- package/memory/90-decisions/0087-remover-dashboard-legado.md +35 -0
- package/memory/90-decisions/0088-templates-validados.md +55 -0
- package/package.json +25 -25
- package/templates/project/AGENTS.md +75 -0
- package/templates/project/CLAUDE.md +9 -0
- package/templates/project/agents/context-engineer.md +15 -0
- package/templates/project/agents/governance.md +15 -0
- package/templates/project/agents/marketing.md +15 -0
- package/templates/project/agents/orchestrator.md +15 -0
- package/templates/project/agents/product.md +15 -0
- package/templates/project/agents/sdd-architect.md +15 -0
- package/dist/lib/multi-ai-instructions.d.ts +0 -28
- package/dist/lib/multi-ai-instructions.js +0 -83
package/docs/init-project.md
CHANGED
|
@@ -1,457 +1,101 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Criar um projeto — `forja project:new`
|
|
2
2
|
|
|
3
|
-
|
|
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
|
-
#
|
|
13
|
-
|
|
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
|
-
#
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
-
|
|
36
|
-
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
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
|
-
#
|
|
292
|
-
|
|
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; só traz backend se o projeto já tem um)
|
|
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
|
-
|
|
449
|
-
|
|
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
|
-
|
|
455
|
-
|
|
456
|
-
|
|
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/
|
|
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
|
|
32
|
+
`workspace:project:check` e `demo:workspace`.
|
|
33
33
|
|
|
34
34
|
```bash
|
|
35
35
|
forja workspace:init
|
package/docs/processo-projeto.md
CHANGED
|
@@ -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/>
|
|
20
|
+
Q -- "Não" --> A1["A1· Gerar scaffold<br/>forja project:new <nome> -- --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·
|
|
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
|
|
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
|
|
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.
|
|
65
|
-
→ design-lib →
|
|
66
|
-
|
|
67
|
-
|
|
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.
|
|
95
|
-
# (
|
|
96
|
-
|
|
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
|