@nathanramorim/forge-sdd 1.6.0 → 1.6.1-beta.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/README.md +28 -193
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -3,226 +3,61 @@
|
|
|
3
3
|
[](https://www.npmjs.com/package/@nathanramorim/forge-sdd)
|
|
4
4
|
[](https://opensource.org/licenses/MIT)
|
|
5
5
|
|
|
6
|
-
> CLI open source que instala em qualquer projeto a **Metodologia Forge-SDD** v1.6.0 — 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.
|
|
6
|
+
> CLI open source que instala em qualquer projeto a **Metodologia Forge-SDD** v1.6.1-beta.0 — 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.
|
|
7
7
|
|
|
8
|
-
🚀 **Landing Page:** [forge-sdd.vercel.app](https://forge-sdd.vercel.app)
|
|
8
|
+
🚀 **Landing Page Oficial:** [forge-sdd.vercel.app](https://forge-sdd.vercel.app)
|
|
9
|
+
📖 **Wiki & Documentação Completa:** [Wiki do Forge-SDD](https://forge-sdd.vercel.app/wiki#introducao)
|
|
9
10
|
|
|
10
11
|
---
|
|
11
12
|
|
|
12
|
-
##
|
|
13
|
+
## ⚡ O que é o forge-sdd?
|
|
13
14
|
|
|
14
|
-
O **forge-sdd** nasceu para **mudar a dinâmica de desenvolvimento orientado a IA**.
|
|
15
|
+
O **forge-sdd** nasceu para **mudar a dinâmica de desenvolvimento orientado a IA**. Ele resolve o desafio de manter a consistência, qualidade e velocidade do desenvolvimento através de agentes de IA locais especializados (Orquestrador, Builder, Revisor, etc.) operando sob a metodologia SDD (Software Design Doc).
|
|
15
16
|
|
|
16
|
-
|
|
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.
|
|
17
|
+
Para conhecer todos os comandos disponíveis (`/status`, `/discovery`, `/nova-feature`, etc.), guias rápidos de início do zero e adoção em projetos existentes, acesse a nossa **[Landing Page Oficial](https://forge-sdd.vercel.app)** ou a **[Wiki do Projeto](https://forge-sdd.vercel.app/wiki#introducao)**.
|
|
24
18
|
|
|
25
19
|
---
|
|
26
20
|
|
|
27
|
-
## Instalação & Inicialização
|
|
21
|
+
## 💻 Instalação & Inicialização Rápida
|
|
28
22
|
|
|
29
|
-
|
|
23
|
+
Inicialize a estrutura em segundos. O instalador gerará as pastas de memória, especificações e configurações específicas para a sua IA preferida (Copilot, Gemini ou Claude):
|
|
30
24
|
|
|
31
25
|
```bash
|
|
32
|
-
# Inicialização interativa (
|
|
26
|
+
# Inicialização interativa (escolha os agentes no menu)
|
|
33
27
|
npx @nathanramorim/forge-sdd@latest init
|
|
34
28
|
|
|
35
|
-
# Inicialização
|
|
36
|
-
npx @nathanramorim/forge-sdd@latest init . --agent copilot,gemini
|
|
37
|
-
```
|
|
38
|
-
|
|
39
|
-
### Requisitos
|
|
40
|
-
|
|
41
|
-
- Node.js ≥ 18
|
|
42
|
-
- O binário Go é baixado automaticamente e cacheado em `~/.cache/forge-sdd/`.
|
|
43
|
-
|
|
44
|
-
---
|
|
45
|
-
|
|
46
|
-
## O que é gerado após o `init`
|
|
47
|
-
|
|
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
|
-
```
|
|
68
|
-
|
|
69
|
-
---
|
|
70
|
-
|
|
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
|
-
```
|
|
94
|
-
|
|
95
|
-
---
|
|
96
|
-
|
|
97
|
-
## 📖 Guia: Quando usar cada comando?
|
|
98
|
-
|
|
99
|
-
### `/discovery` — Explore antes de especificar
|
|
100
|
-
|
|
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".
|
|
102
|
-
|
|
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
|
|
106
|
-
```
|
|
107
|
-
|
|
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
|
-
|
|
29
|
+
# Inicialização rápida no diretório atual
|
|
30
|
+
npx @nathanramorim/forge-sdd@latest init . --agent copilot,gemini --name meu-projeto
|
|
115
31
|
```
|
|
116
|
-
Regra de ouro: a branch é criada ANTES do arquivo de spec
|
|
117
|
-
```
|
|
118
|
-
|
|
119
|
-
### `/split-features` — Quebre features grandes
|
|
120
|
-
|
|
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:
|
|
122
|
-
|
|
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.
|
|
136
|
-
|
|
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?
|
|
143
32
|
|
|
144
33
|
---
|
|
145
34
|
|
|
146
|
-
##
|
|
147
|
-
|
|
148
|
-
### 🆕 Projeto do Zero
|
|
149
|
-
|
|
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.
|
|
151
|
-
|
|
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
|
-
```
|
|
35
|
+
## 📢 Novidades da Versão (v1.6.1-beta.0)
|
|
159
36
|
|
|
160
|
-
|
|
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
|
|
37
|
+
A versão beta traz detecção inteligente de projetos existentes e upgrade aprimorado:
|
|
165
38
|
|
|
166
|
-
|
|
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
|
|
181
|
-
|
|
182
|
-
---
|
|
183
|
-
|
|
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 |
|
|
39
|
+
- **Fase 38 — Detecção Inteligente e Upgrade no CLI**: O CLI agora detecta automaticamente se o diretório já possui a metodologia estruturada e redireciona para a interface de upgrade.
|
|
40
|
+
- **Integração NPM Registry**: O CLI consulta dinamicamente as versões oficiais (`latest`) e de teste (`beta`) publicadas no NPM Registry para que o usuário escolha para qual deseja atualizar.
|
|
199
41
|
|
|
200
42
|
---
|
|
201
43
|
|
|
202
|
-
##
|
|
203
|
-
|
|
204
|
-
| Agente | Flag | Como acionar os comandos |
|
|
205
|
-
|--------|------|--------------------------|
|
|
206
|
-
| **GitHub Copilot** | `copilot` | Use `/` no chat do VS Code (ex: `/status`) |
|
|
207
|
-
| **Claude** | `claude` | Mencione o comando no chat (ex: `/revisar`) |
|
|
208
|
-
| **Gemini** | `gemini` | Peça pelo nome ("rodar o status") |
|
|
44
|
+
## 📢 Novidades da Versão Anterior (v1.6.0)
|
|
209
45
|
|
|
210
|
-
|
|
211
|
-
# Um agente
|
|
212
|
-
npx @nathanramorim/forge-sdd@latest init --yes --agent gemini --name meu-projeto
|
|
46
|
+
A versão estável v1.6.0 trouxe grandes evoluções de arquitetura e consistência no desenvolvimento:
|
|
213
47
|
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
48
|
+
- **Fase 36 — Documentação Estruturada**: Estruturação de diagramas conceituais Mermaid detalhados para visualização clara de fluxos e arquitetura.
|
|
49
|
+
- **Fase 35 — Remoção de Skill Incompleta**: Limpeza completa da funcionalidade de instalação de skill (`/install-skill`) em todos os prompts, agentes e documentação.
|
|
50
|
+
- **Fase 34 — Reestruturação de Prompts por Agente**: Migração dos prompts do Copilot e unificação dos prompts de sistema e habilidades customizadas específicas para Gemini, Claude e Copilot.
|
|
51
|
+
- **Fase 33 — Sincronização Automática da Wiki**: A documentação oficial (diretório docs/ e README) agora é enviada e atualizada automaticamente na wiki do repositório lp-forge-sdd a cada nova tag publicada.
|
|
52
|
+
- **Fase 32 — Geração de Release Notes**: Agora o agente documenta as entregas de cada feature de forma automática e em linguagem clara de produto ao encerrar as tarefas.
|
|
53
|
+
- **Fase 31 — Preservação de Domínio no Upgrade**: As atualizações do Forge-SDD ou do CLI protegem e preservam todas as suas especificações e arquivos de domínio do usuário.
|
|
54
|
+
- **Fase 30 — Correções de Fluxo de Branches**: Ajustado o fluxo de desenvolvimento automático do agente para garantir criação prévia de branches e integração robusta de PRs via `gh` CLI.
|
|
217
55
|
|
|
218
56
|
---
|
|
219
57
|
|
|
220
|
-
## Links
|
|
58
|
+
## Links Úteis
|
|
221
59
|
|
|
222
60
|
- [GitHub Repository](https://github.com/nathanramorim/forge-sdd)
|
|
223
|
-
- [
|
|
224
|
-
- [
|
|
225
|
-
|
|
226
|
-
## Licença
|
|
227
|
-
|
|
228
|
-
Distribuído sob a licença MIT. Veja [LICENSE](https://github.com/nathanramorim/forge-sdd/blob/main/LICENSE) para mais informações.
|
|
61
|
+
- [Landing Page](https://forge-sdd.vercel.app)
|
|
62
|
+
- [Metodologia SDD](https://github.com/nathanramorim/forge-sdd/blob/main/docs/metodologia-sdd.md)
|
|
63
|
+
- [Licença MIT](https://github.com/nathanramorim/forge-sdd/blob/main/LICENSE)
|
package/package.json
CHANGED