@nathanramorim/forge-sdd 1.5.2 → 1.5.4
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/README.md +184 -57
- package/bin/run.js +6 -6
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,102 +1,229 @@
|
|
|
1
1
|
# @nathanramorim/forge-sdd
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/@nathanramorim/forge-sdd)
|
|
4
|
+
[](https://opensource.org/licenses/MIT)
|
|
5
|
+
|
|
6
|
+
> CLI open source que instala em qualquer projeto a **Metodologia Forge-SDD** v1.5.2 — um framework de desenvolvimento guiado por IA que elimina a repetição de instruções, garante padrões arquiteturais e traz a expertise de um engenheiro sênior para o seu fluxo diário.
|
|
4
7
|
|
|
5
8
|
🚀 **Landing Page:** [forge-sdd.vercel.app](https://forge-sdd.vercel.app)
|
|
6
9
|
|
|
7
|
-
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
## Por que o forge-sdd? (Open Source)
|
|
13
|
+
|
|
14
|
+
O **forge-sdd** nasceu para **mudar a dinâmica de desenvolvimento orientado a IA**. Como um projeto **Open Source** (licenciado sob a licença MIT), ele resolve o desafio de manter a consistência e velocidade do desenvolvimento através de 4 pilares fundamentais:
|
|
15
|
+
|
|
16
|
+
| Pilar | O que resolve |
|
|
17
|
+
|-------|--------------|
|
|
18
|
+
| 🤖 **Controle de Fluxo com IA** | A IA atua de forma guiada e previsível (Orquestrador → Builder → Revisor) |
|
|
19
|
+
| 🧠 **Sem Repetição de Instruções** | As regras do projeto ficam em arquivos locais e a IA as lê a cada sessão |
|
|
20
|
+
| 🔄 **Padrões & Incrementalidade** | Cada evolução segue os padrões da sua arquitetura, de forma acumulativa |
|
|
21
|
+
| 🎓 **Expertise Sênior Embutida** | Discovery estruturado, specs claras e revisão automatizada de código |
|
|
22
|
+
|
|
23
|
+
O forge-sdd foi aberto para que a comunidade possa evoluir e adaptar o fluxo de scaffolding de SDDs para qualquer stack de desenvolvimento de forma livre.
|
|
24
|
+
|
|
25
|
+
---
|
|
26
|
+
|
|
27
|
+
## Instalação & Inicialização
|
|
28
|
+
|
|
29
|
+
Durante a inicialização, você deve definir para quais agentes de IA deseja gerar a estrutura do SDD (Copilot, Gemini ou Claude):
|
|
8
30
|
|
|
9
31
|
```bash
|
|
32
|
+
# Inicialização interativa (permite escolher os agentes no menu)
|
|
10
33
|
npx @nathanramorim/forge-sdd@latest init
|
|
34
|
+
|
|
35
|
+
# Inicialização direta no diretório atual especificando os agentes
|
|
36
|
+
npx @nathanramorim/forge-sdd@latest init . --agent copilot,gemini,claude --name meu-projeto
|
|
11
37
|
```
|
|
12
38
|
|
|
13
|
-
|
|
39
|
+
### Requisitos
|
|
40
|
+
|
|
41
|
+
- Node.js ≥ 18
|
|
42
|
+
- O binário Go é baixado automaticamente e cacheado em `~/.cache/forge-sdd/`.
|
|
14
43
|
|
|
15
44
|
---
|
|
16
45
|
|
|
17
|
-
##
|
|
46
|
+
## O que é gerado após o `init`
|
|
18
47
|
|
|
19
|
-
|
|
20
|
-
|
|
48
|
+
```
|
|
49
|
+
sdd/ → memória e especificação do projeto
|
|
50
|
+
memory/
|
|
51
|
+
progress.md → estado ativo (leia primeiro a cada sessão)
|
|
52
|
+
constitution.md → regras imutáveis do projeto
|
|
53
|
+
spec/
|
|
54
|
+
overview.md, stack.md, modules.md, flows.md, decisions.md
|
|
55
|
+
features/
|
|
56
|
+
feat-00-foundation.md → feature inicial
|
|
57
|
+
index.md → mapa de features
|
|
58
|
+
|
|
59
|
+
# Agente Selecionado (Ex: Gemini)
|
|
60
|
+
.gemini/
|
|
61
|
+
skills/*.chatmode.md → 6 papéis: Orquestrador, Builder, Revisor…
|
|
62
|
+
prompts/*.prompt.md → comandos: /status, /nova-feature…
|
|
63
|
+
GEMINI.md → Instruções de contexto para o Gemini
|
|
64
|
+
|
|
65
|
+
.vscode/
|
|
66
|
+
mcp.json → configuração dos MCPs (context7, git)
|
|
67
|
+
```
|
|
21
68
|
|
|
22
69
|
---
|
|
23
70
|
|
|
24
|
-
##
|
|
71
|
+
## 🗺️ Fluxo de Desenvolvimento
|
|
72
|
+
|
|
73
|
+
O Forge-SDD organiza o trabalho em ciclos curtos e incrementais. O diagrama abaixo mostra o fluxo completo:
|
|
74
|
+
|
|
75
|
+
```mermaid
|
|
76
|
+
flowchart TD
|
|
77
|
+
A([Inicio da Sessao]) --> B["/status<br/>Entende o estado atual"]
|
|
78
|
+
B --> C{"Existe feature<br/>em andamento?"}
|
|
79
|
+
C -- Sim --> D["/proxima-feature<br/>Retoma a feature"]
|
|
80
|
+
C -- Nao --> E{"Tenho uma<br/>ideia nova?"}
|
|
81
|
+
E -- Explorar --> F["/discovery<br/>Explora produto<br/>e engenharia"]
|
|
82
|
+
E -- Ja sei --> G["/nova-feature<br/>Especifica e<br/>cria a branch"]
|
|
83
|
+
F --> H{"Feature ficou<br/>muito grande?"}
|
|
84
|
+
G --> H
|
|
85
|
+
H -- mais de 7 tasks --> I["/split-features<br/>Quebra em<br/>feats independentes"]
|
|
86
|
+
H -- Nao --> D
|
|
87
|
+
I --> D
|
|
88
|
+
D --> J["Builder implementa"]
|
|
89
|
+
J --> K["/revisar<br/>Revisor valida<br/>criterio de conclusao"]
|
|
90
|
+
K -- Aprovado --> L["PR via gh cli<br/>Merge na main"]
|
|
91
|
+
K -- Reprovado --> J
|
|
92
|
+
L --> M([Proximo ciclo])
|
|
93
|
+
```
|
|
25
94
|
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
95
|
+
---
|
|
96
|
+
|
|
97
|
+
## 📖 Guia: Quando usar cada comando?
|
|
29
98
|
|
|
30
|
-
|
|
31
|
-
npx @nathanramorim/forge-sdd@latest init --yes --agent gemini
|
|
99
|
+
### `/discovery` — Explore antes de especificar
|
|
32
100
|
|
|
33
|
-
|
|
34
|
-
npx @nathanramorim/forge-sdd@latest init --yes --agent claude
|
|
101
|
+
Use quando você tem **uma ideia mas ainda não sabe exatamente o que construir**. O agente assume as personas de PM e Engenheiro Sênior e conduz uma sessão estruturada para definir o "o quê", o "para quem" e o "como".
|
|
35
102
|
|
|
36
|
-
|
|
37
|
-
|
|
103
|
+
```
|
|
104
|
+
Quando usar: Ideia vaga → /discovery → Features bem definidas
|
|
105
|
+
Quando NÃO usar: Se você já sabe exatamente o que fazer, vá direto para /nova-feature
|
|
38
106
|
```
|
|
39
107
|
|
|
40
|
-
|
|
108
|
+
### `/nova-feature` — Registre e inicie
|
|
109
|
+
|
|
110
|
+
Use quando você já sabe o que implementar. O agente:
|
|
111
|
+
1. Cria a branch `feat/<nome>` imediatamente
|
|
112
|
+
2. Cria o arquivo `sdd/features/feat-XX-<nome>.md` com objetivo, tasks e critério de conclusão
|
|
113
|
+
3. Atualiza o índice de features
|
|
114
|
+
|
|
115
|
+
```
|
|
116
|
+
Regra de ouro: a branch é criada ANTES do arquivo de spec
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
### `/split-features` — Quebre features grandes
|
|
41
120
|
|
|
42
|
-
|
|
121
|
+
Use quando uma feature ficou **grande demais** (mais de 7 tasks ou abrange mais de um domínio). O agente aplica os critérios de desacoplamento:
|
|
43
122
|
|
|
44
|
-
|
|
123
|
+
```mermaid
|
|
124
|
+
flowchart LR
|
|
125
|
+
A["feature-grande<br/>12 tasks, 3 dominios"] --> B{"Criterios<br/>de quebra"}
|
|
126
|
+
B --> C["Entrega valor<br/>independente"]
|
|
127
|
+
B --> D["Sem dependencia<br/>circular"]
|
|
128
|
+
B --> E["Respeita camadas<br/>infra → dominio → UI"]
|
|
129
|
+
B --> F["Criterio de conclusao<br/>proprio"]
|
|
130
|
+
C & D & E & F --> G["feat-XX-a<br/>feat-XX-b<br/>feat-XX-c"]
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
### `/proxima-feature` — Implemente
|
|
134
|
+
|
|
135
|
+
Use quando quer iniciar ou retomar a próxima feature do backlog. O Orquestrador lê o `progress.md`, identifica a feature `todo` mais prioritária, cria a branch e delega ao Builder.
|
|
45
136
|
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
-
|
|
50
|
-
-
|
|
137
|
+
### `/revisar` — Valide antes do merge
|
|
138
|
+
|
|
139
|
+
Sempre rode antes de criar o PR. O Revisor valida:
|
|
140
|
+
- ✅ O critério de conclusão definido na spec foi atingido?
|
|
141
|
+
- ✅ `go vet` / lint passou?
|
|
142
|
+
- ✅ Arquivos de memória (`progress.md`) estão atualizados?
|
|
51
143
|
|
|
52
144
|
---
|
|
53
145
|
|
|
54
|
-
## 🚀
|
|
146
|
+
## 🚀 Trilhas de Início Rápido
|
|
147
|
+
|
|
148
|
+
### 🆕 Projeto do Zero
|
|
55
149
|
|
|
56
|
-
|
|
57
|
-
1. `npx @nathanramorim/forge-sdd@latest init`
|
|
58
|
-
2. `/constitution` → Define arquitetura e regras base.
|
|
59
|
-
3. `/discovery "sua ideia"` → **Discovery de Produto:** Onde o agente define o "que" e o "para quem" será construído.
|
|
60
|
-
4. `/nova-feature` → Mapeia o roadmap de tarefas baseado no discovery.
|
|
61
|
-
5. `/proxima-feature` → Inicia a implementação.
|
|
150
|
+
Ao iniciar um projeto do zero, você pode escolher quais agentes deseja configurar (Copilot, Gemini ou Claude). Use a flag `--agent` no `init` para configurar múltiplos agentes simultaneamente.
|
|
62
151
|
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
152
|
+
```mermaid
|
|
153
|
+
flowchart LR
|
|
154
|
+
A["npx forge-sdd init"] --> B["/constitution<br/>Define arquitetura<br/>e regras base"]
|
|
155
|
+
B --> C["/discovery<br/>Explora a ideia"]
|
|
156
|
+
C --> D["/nova-feature<br/>Cria as features<br/>do roadmap"]
|
|
157
|
+
D --> E["/proxima-feature<br/>Inicia a implementacao"]
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
1. `npx @nathanramorim/forge-sdd@latest init` (especifique os agentes: `--agent copilot`, `--agent gemini` ou `--agent claude`)
|
|
161
|
+
2. `/constitution` → define arquitetura e regras base
|
|
162
|
+
3. `/discovery "sua ideia"` → explora produto e engenharia
|
|
163
|
+
4. `/nova-feature` → cria features do roadmap
|
|
164
|
+
5. `/proxima-feature` → inicia a implementação
|
|
165
|
+
|
|
166
|
+
### 🏗️ Projeto Existente (Adoção)
|
|
167
|
+
|
|
168
|
+
Para adotar a metodologia em um projeto existente sem alterar sua estrutura atual, inicialize diretamente no diretório corrente (`.`) e informe para quais agentes deseja gerar os arquivos:
|
|
169
|
+
|
|
170
|
+
```mermaid
|
|
171
|
+
flowchart LR
|
|
172
|
+
A["npx forge-sdd init . --yes"] --> B["/constitution<br/>Scan do codebase<br/>aprende as regras"]
|
|
173
|
+
B --> C["/status<br/>Sincroniza<br/>estado atual"]
|
|
174
|
+
C --> D["/nova-feature<br/>Mapeie a proxima<br/>evolucao"]
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
1. `npx @nathanramorim/forge-sdd@latest init . --yes` (especifique os agentes via flags, ex: `--agent copilot,gemini`)
|
|
178
|
+
2. `/constitution` → o agente escaneia seu codebase e aprende as regras do seu projeto
|
|
179
|
+
3. `/status` → sincroniza o estado atual do progresso
|
|
180
|
+
4. `/nova-feature` → mapeia a próxima evolução
|
|
68
181
|
|
|
69
182
|
---
|
|
70
183
|
|
|
71
|
-
##
|
|
184
|
+
## 🛠️ Referência de Comandos
|
|
185
|
+
|
|
186
|
+
| Comando | Quando usar | O que faz |
|
|
187
|
+
|---------|-------------|-----------|
|
|
188
|
+
| `/status` | Início de sessão | Lê `progress.md` e reporta fases e bloqueios |
|
|
189
|
+
| `/discovery <ideia>` | Ideia vaga | Sessão de discovery com personas PM + Engenheiro Sênior |
|
|
190
|
+
| `/nova-feature <desc>` | Ideia clara | Cria branch + spec + atualiza índice |
|
|
191
|
+
| `/split-features` | Feature grande (>7 tasks) | Quebra em sub-features desacopladas |
|
|
192
|
+
| `/proxima-feature` | Iniciar implementação | Retoma a próxima feature `todo` |
|
|
193
|
+
| `/revisar` | Antes do PR | Valida critério de conclusão e qualidade |
|
|
194
|
+
| `/constitution` | Início ou mudança arch. | Alinha `constitution.md` com o codebase real |
|
|
195
|
+
| `/c4-architecture` | Documentar arquitetura | Gera diagramas C4 em Mermaid |
|
|
196
|
+
| `/doctor` | Diagnóstico | Verifica integridade, MCPs e budgets |
|
|
197
|
+
| `/archive` | `progress.md` > 1 KB | Move histórico antigo para o log |
|
|
198
|
+
| `/upgrade-sdd` | Nova versão SDD | Migra a estrutura para a versão mais recente |
|
|
199
|
+
| `/install-skill` | Reutilizar skill | Importa skill de uma URL do GitHub |
|
|
72
200
|
|
|
73
|
-
|
|
201
|
+
---
|
|
74
202
|
|
|
75
|
-
|
|
203
|
+
## 🤖 Agentes Suportados
|
|
76
204
|
|
|
77
|
-
|
|
|
78
|
-
|
|
79
|
-
|
|
|
80
|
-
|
|
|
81
|
-
|
|
|
82
|
-
| `/revisar` | Revisor valida código e critério de conclusão. | Copilot, Claude, Gemini |
|
|
83
|
-
| `/doctor` | Check-up de integridade, MCPs e budgets. | Copilot, Claude, Gemini |
|
|
84
|
-
| `/archive` | Compacta `progress.md` movendo para o log. | Copilot, Claude, Gemini |
|
|
85
|
-
| `/upgrade-sdd` | Migra a estrutura para uma nova versão. | Copilot, Claude, Gemini |
|
|
86
|
-
| `/discovery` | Processo de Discovery (Produto + Engenharia Sênior). | Copilot, Claude, Gemini |
|
|
87
|
-
| `/c4-architecture` | Gera diagramas C4 Model em Mermaid. | Copilot, Claude, Gemini |
|
|
88
|
-
| `/split-features` | Quebra um plano de discovery em múltiplas features. | Copilot, Claude, Gemini |
|
|
89
|
-
| `/install-skill` | Instala uma skill via URL do GitHub/Raw. | Copilot, Claude, Gemini |
|
|
205
|
+
| Agente | Flag | Como acionar os comandos |
|
|
206
|
+
|--------|------|--------------------------|
|
|
207
|
+
| **GitHub Copilot** | `copilot` | Use `/` no chat do VS Code (ex: `/status`) |
|
|
208
|
+
| **Claude** | `claude` | Mencione o comando no chat (ex: `/revisar`) |
|
|
209
|
+
| **Gemini** | `gemini` | Peça pelo nome ("rodar o status") |
|
|
90
210
|
|
|
91
|
-
|
|
92
|
-
|
|
211
|
+
```bash
|
|
212
|
+
# Um agente
|
|
213
|
+
npx @nathanramorim/forge-sdd@latest init --yes --agent gemini --name meu-projeto
|
|
93
214
|
|
|
94
|
-
|
|
95
|
-
|
|
215
|
+
# Múltiplos agentes
|
|
216
|
+
npx @nathanramorim/forge-sdd@latest init --yes --agent copilot,claude,gemini --name meu-projeto
|
|
217
|
+
```
|
|
96
218
|
|
|
97
219
|
---
|
|
98
220
|
|
|
99
221
|
## Links
|
|
100
222
|
|
|
101
223
|
- [GitHub Repository](https://github.com/nathanramorim/forge-sdd)
|
|
102
|
-
- [Metodologia
|
|
224
|
+
- [Documentação da Metodologia](https://github.com/nathanramorim/forge-sdd#readme)
|
|
225
|
+
- [CONTRIBUTING.md](https://github.com/nathanramorim/forge-sdd/blob/main/CONTRIBUTING.md)
|
|
226
|
+
|
|
227
|
+
## Licença
|
|
228
|
+
|
|
229
|
+
Distribuído sob a licença MIT. Veja [LICENSE](https://github.com/nathanramorim/forge-sdd/blob/main/LICENSE) para mais informações.
|
package/bin/run.js
CHANGED
|
@@ -13,18 +13,18 @@ const zlib = require('zlib');
|
|
|
13
13
|
// ─── helpers ──────────────────────────────────────────────────────────────────
|
|
14
14
|
|
|
15
15
|
const VERSION = require('../package.json').version;
|
|
16
|
-
const BASE_URL = `https://github.com/nathanramorim/
|
|
16
|
+
const BASE_URL = `https://github.com/nathanramorim/forge-sdd/releases/download/v${VERSION}`;
|
|
17
17
|
|
|
18
18
|
function platformAsset() {
|
|
19
19
|
const plat = process.platform;
|
|
20
20
|
const arch = process.arch;
|
|
21
21
|
|
|
22
22
|
const map = {
|
|
23
|
-
'linux-x64': { file: `
|
|
24
|
-
'linux-arm64': { file: `
|
|
25
|
-
'darwin-x64': { file: `
|
|
26
|
-
'darwin-arm64': { file: `
|
|
27
|
-
'win32-x64': { file: `
|
|
23
|
+
'linux-x64': { file: `forge-sdd_linux_amd64.tar.gz`, ext: 'tar.gz' },
|
|
24
|
+
'linux-arm64': { file: `forge-sdd_linux_arm64.tar.gz`, ext: 'tar.gz' },
|
|
25
|
+
'darwin-x64': { file: `forge-sdd_darwin_amd64.tar.gz`, ext: 'tar.gz' },
|
|
26
|
+
'darwin-arm64': { file: `forge-sdd_darwin_arm64.tar.gz`, ext: 'tar.gz' },
|
|
27
|
+
'win32-x64': { file: `forge-sdd_windows_amd64.zip`, ext: 'zip' },
|
|
28
28
|
};
|
|
29
29
|
|
|
30
30
|
const key = `${plat}-${arch}`;
|
package/package.json
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@nathanramorim/forge-sdd",
|
|
3
|
-
"version": "1.5.
|
|
3
|
+
"version": "1.5.4",
|
|
4
4
|
"description": "CLI que scaffolda estruturas Forge-SDD em segundos",
|
|
5
|
-
"homepage": "https://github.com/nathanramorim/
|
|
5
|
+
"homepage": "https://github.com/nathanramorim/forge-sdd",
|
|
6
6
|
"repository": {
|
|
7
7
|
"type": "git",
|
|
8
8
|
"url": "https://github.com/nathanramorim/forge-sdd.git"
|