sdd-flow 1.3.3 → 2.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.
- package/CHANGELOG.md +39 -0
- package/CONTRIBUTING.md +25 -0
- package/LICENSE +21 -21
- package/README.md +402 -168
- package/README.pt-BR.md +387 -0
- package/bin/cli.js +162 -424
- package/docs/architecture.md +91 -0
- package/docs/distribution.md +64 -0
- package/docs/formats.md +215 -0
- package/docs/local-testing.pt-BR.md +196 -0
- package/docs/methodology.pt-BR.md +139 -0
- package/docs/migration.md +76 -0
- package/docs/quality-gates.pt-BR.md +160 -0
- package/docs/quality.md +56 -0
- package/docs/releases.pt-BR.md +105 -0
- package/docs/setup-documents.pt-BR.md +120 -0
- package/docs/usage.pt-BR.md +310 -0
- package/docs/validation.md +101 -0
- package/lib/adapters.js +115 -0
- package/lib/check.js +221 -0
- package/lib/context.js +117 -0
- package/lib/documents.js +71 -0
- package/lib/handoff.js +81 -0
- package/lib/history.js +16 -0
- package/lib/install.js +181 -0
- package/lib/io.js +119 -0
- package/lib/legacy-hashes.json +31 -0
- package/lib/markdown.js +71 -0
- package/lib/project.js +200 -0
- package/lib/quality.js +24 -0
- package/lib/revisions.js +79 -0
- package/lib/verification.js +267 -0
- package/package.json +55 -32
- package/templates/AGENTS.md +12 -50
- package/templates/QUICKSTART.md +16 -70
- package/templates/agents/AGENTS.md +58 -92
- package/templates/agents/DECISIONS.md +5 -21
- package/templates/agents/POLICIES.md +14 -0
- package/templates/agents/PROJECT.md +35 -145
- package/templates/agents/QUALITY.md +19 -0
- package/templates/agents/RULES.md +24 -132
- package/templates/agents/SETUP.md +38 -224
- package/templates/agents/config.yaml +13 -0
- package/templates/agents/current/_template.md +19 -0
- package/templates/agents/decisions/_template.md +22 -0
- package/templates/agents/prompts/conventional-commit.md +11 -51
- package/templates/agents/prompts/intake.md +23 -0
- package/templates/agents/prompts/pr-template.md +12 -21
- package/templates/agents/prompts/quality.md +57 -0
- package/templates/agents/prompts/rpi-close.md +23 -0
- package/templates/agents/prompts/rpi-implement.md +35 -68
- package/templates/agents/prompts/rpi-plan.md +87 -117
- package/templates/agents/prompts/rpi-research.md +21 -67
- package/templates/agents/prompts/rpi-validate.md +40 -103
- package/templates/agents/prompts/skill-call.md +11 -29
- package/templates/agents/prompts/task-create.md +13 -42
- package/templates/agents/skills/_template/SKILL.md +11 -37
- package/templates/agents/harness/claude-code/.hooks/guard-delete.sh +0 -22
- package/templates/agents/harness/claude-code/.hooks/guard-deps.sh +0 -25
- package/templates/agents/harness/claude-code/.hooks/guard-git.sh +0 -24
- package/templates/agents/harness/claude-code/commands/sdd-implement.md +0 -3
- package/templates/agents/harness/claude-code/commands/sdd-plan.md +0 -3
- package/templates/agents/harness/claude-code/commands/sdd-research.md +0 -3
- package/templates/agents/harness/claude-code/commands/sdd-validate.md +0 -3
- package/templates/agents/harness/claude-code/settings.json +0 -34
- package/templates/agents/harness/opencode/commands/sdd-implement.md +0 -3
- package/templates/agents/harness/opencode/commands/sdd-plan.md +0 -3
- package/templates/agents/harness/opencode/commands/sdd-research.md +0 -3
- package/templates/agents/harness/opencode/commands/sdd-validate.md +0 -3
- package/templates/agents/harness/opencode/opencode.json +0 -18
package/README.pt-BR.md
ADDED
|
@@ -0,0 +1,387 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
3
|
+
# sdd-flow
|
|
4
|
+
|
|
5
|
+
### Um fluxo claro para desenvolver com IA.
|
|
6
|
+
|
|
7
|
+
Contexto relevante para o agente.<br>
|
|
8
|
+
Mudanças bem definidas para você.<br>
|
|
9
|
+
Histórico rastreável para o projeto.
|
|
10
|
+
|
|
11
|
+

|
|
12
|
+

|
|
13
|
+

|
|
14
|
+
|
|
15
|
+
[English](README.md) · [Começar](#comece-em-3-passos) · [Entender o fluxo](#como-funciona) · [Contexto](#como-o-contexto-permanece-enxuto) · [Documentação](#documentação)
|
|
16
|
+
|
|
17
|
+
</div>
|
|
18
|
+
|
|
19
|
+
---
|
|
20
|
+
|
|
21
|
+
**O sdd-flow organiza o desenvolvimento assistido por IA em mudanças pequenas o suficiente para entender, implementar e verificar.**
|
|
22
|
+
|
|
23
|
+
Você descreve o que precisa. O agente consulta as referências pertinentes, prepara uma spec, implementa o escopo autorizado e registra os resultados. O conhecimento e o andamento permanecem no repositório, disponíveis para a próxima sessão.
|
|
24
|
+
|
|
25
|
+
| Organização | Contexto | Rastreabilidade |
|
|
26
|
+
|---|---|---|
|
|
27
|
+
| Uma spec por mudança coesa | Fontes selecionadas por fase e tarefa | Requisitos, tarefas, decisões e verificações conectados |
|
|
28
|
+
|
|
29
|
+
**No dia a dia, seu foco continua na spec.** O agente e o CLI mantêm os registros de apoio. Configuração, skills e documentos gerais são consultados quando pertinentes.
|
|
30
|
+
|
|
31
|
+
## Como funciona
|
|
32
|
+
|
|
33
|
+
```mermaid
|
|
34
|
+
flowchart TD
|
|
35
|
+
A["Você descreve a mudança"] --> B["Agente pesquisa e planeja"]
|
|
36
|
+
B --> C["Você revisa o escopo"]
|
|
37
|
+
C --> D["Agente implementa e verifica"]
|
|
38
|
+
D --> E{"Resultado"}
|
|
39
|
+
E -->|"Precisa de ajuste"| D
|
|
40
|
+
E -->|"Pronto para encerrar"| F["Consolidar e registrar a entrega"]
|
|
41
|
+
D -. "Regra mudou" .-> B
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
**Pesquisar → planejar → implementar → validar → encerrar.** As etapas são responsabilidades do trabalho; podem acontecer na mesma conversa.
|
|
45
|
+
|
|
46
|
+
- **Antes:** esclarecer o objetivo, definir aceitação e considerar impactos.
|
|
47
|
+
- **Durante:** executar tarefas coesas e verificar regressões.
|
|
48
|
+
- **Depois:** registrar o que foi observado e atualizar o conhecimento vigente.
|
|
49
|
+
|
|
50
|
+
O framework serve tanto para **projetos novos** quanto para **aplicações em desenvolvimento**, com qualquer stack. Node.js 22+ é necessário para o CLI, não para a aplicação que você está construindo.
|
|
51
|
+
|
|
52
|
+
## Comece em 3 passos
|
|
53
|
+
|
|
54
|
+
> **Versão deste README: 2.x**, uma evolução com quebra de compatibilidade em relação à 1.x (veja a [migração](docs/migration.md)). Confira a versão com `sdd --version`.
|
|
55
|
+
|
|
56
|
+
### 1. Instale o CLI
|
|
57
|
+
|
|
58
|
+
Com Node.js 22+:
|
|
59
|
+
|
|
60
|
+
```sh
|
|
61
|
+
npm install -g sdd-flow
|
|
62
|
+
sdd --version
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
<details>
|
|
66
|
+
<summary>Outras opções: executar sem instalar ou pelo código-fonte</summary>
|
|
67
|
+
|
|
68
|
+
Executar sem instalação global:
|
|
69
|
+
|
|
70
|
+
```sh
|
|
71
|
+
npx sdd-flow@latest --help
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
Pelo código-fonte do **sdd-flow** (para quem contribui):
|
|
75
|
+
|
|
76
|
+
```sh
|
|
77
|
+
npm ci
|
|
78
|
+
npm link
|
|
79
|
+
sdd --version
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
Instalar o pacote disponibiliza o CLI. Os arquivos do método entram em cada aplicação ao executar `sdd init`.
|
|
83
|
+
|
|
84
|
+
</details>
|
|
85
|
+
|
|
86
|
+
### 2. Ative no seu projeto
|
|
87
|
+
|
|
88
|
+
```sh
|
|
89
|
+
cd /caminho/do/seu-projeto
|
|
90
|
+
sdd init
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
Usa Claude Code ou OpenCode? Você pode instalar seus pontos de entrada:
|
|
94
|
+
|
|
95
|
+
```sh
|
|
96
|
+
sdd harness claude-code
|
|
97
|
+
# Alternativa: sdd harness opencode
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
Em outros ambientes, indique ao agente o `AGENTS.md` do projeto. O núcleo usa arquivos e comandos, sem exigir um adaptador específico.
|
|
101
|
+
|
|
102
|
+
### 3. Use seus prompts habituais
|
|
103
|
+
|
|
104
|
+
Para configurar o projeto:
|
|
105
|
+
|
|
106
|
+
```text
|
|
107
|
+
Leia e siga as instruções do arquivo agents/SETUP.md para configurar o workflow.
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
Depois, apresente a demanda e indique a etapa. Prompts curtos continuam sendo suficientes:
|
|
111
|
+
|
|
112
|
+
| Etapa | Pedido ao agente |
|
|
113
|
+
|---|---|
|
|
114
|
+
| Pesquisa | Leia e siga as instruções do arquivo agents/prompts/rpi-research.md. |
|
|
115
|
+
| Planejamento | Leia e siga as instruções do arquivo agents/prompts/rpi-plan.md. |
|
|
116
|
+
| Implementação | Leia e siga as instruções do arquivo agents/prompts/rpi-implement.md. |
|
|
117
|
+
| Validação | Leia e siga as instruções do arquivo agents/prompts/rpi-validate.md. |
|
|
118
|
+
| Encerramento | Leia e siga as instruções do arquivo agents/prompts/rpi-close.md. |
|
|
119
|
+
|
|
120
|
+
Os procedimentos contêm as instruções do método; você não precisa repeti-las no chat.
|
|
121
|
+
A demanda e a spec precisam estar identificadas. Se houver várias mudanças ou uma sessão sem contexto,
|
|
122
|
+
informe o ID, como “Use a spec 001-exportar-dados”, ou deixe o agente esclarecer essa ambiguidade.
|
|
123
|
+
|
|
124
|
+
O setup é inicial. Depois de concluído, `SETUP.md` pode ser removido; não é necessário refazê-lo a cada spec.
|
|
125
|
+
Idioma e padrões particulares ficam na configuração e nas políticas do projeto.
|
|
126
|
+
|
|
127
|
+
**Seu foco continua na spec, nas tarefas e no resultado da validação.** O agente usa o CLI e mantém
|
|
128
|
+
os registros de apoio. Você pode acompanhar as etapas na mesma conversa.
|
|
129
|
+
|
|
130
|
+
Para uma aplicação existente, o setup registra uma baseline observada. Não refatora o projeto
|
|
131
|
+
nem inventa specs para o passado.
|
|
132
|
+
|
|
133
|
+
## O que entra no repositório
|
|
134
|
+
|
|
135
|
+
| Conjunto | Para que serve |
|
|
136
|
+
|---|---|
|
|
137
|
+
| `AGENTS.md` e `QUICKSTART.md` | Entrada e orientação inicial |
|
|
138
|
+
| `agents/PROJECT.md` | Mapa curto da aplicação e suas fontes |
|
|
139
|
+
| `agents/POLICIES.md` e `agents/QUALITY.md` | Particularidades e critérios do projeto |
|
|
140
|
+
| `agents/config.yaml` | Idioma, autonomia, rigor e comandos de verificação |
|
|
141
|
+
| `agents/RULES.md`, `agents/AGENTS.md` e `agents/prompts/` | Método e procedimentos |
|
|
142
|
+
| `agents/specs/` | Mudanças em andamento |
|
|
143
|
+
| `agents/current/` e decisões ativas | Conhecimento vigente |
|
|
144
|
+
| `agents/archive/` | Mudanças encerradas |
|
|
145
|
+
| `agents/skills/` | Procedimentos reutilizáveis do projeto |
|
|
146
|
+
|
|
147
|
+
A instalação também inclui modelos e controles de manutenção. **Não cria funcionalidades nem specs fictícias.** `SETUP.md` orienta a configuração e pode ser removido após concluí-la.
|
|
148
|
+
|
|
149
|
+
Cada spec reúne os artefatos necessários:
|
|
150
|
+
|
|
151
|
+
| Artefato | Papel |
|
|
152
|
+
|---|---|
|
|
153
|
+
| `change.yaml` | Identidade, referências, dependências e ciclo de vida |
|
|
154
|
+
| `SPEC.md` | Requisitos e aceitação |
|
|
155
|
+
| `TASK.md` | Plano e estado das tarefas, quando aplicável |
|
|
156
|
+
| `RESEARCH.md` | Pesquisa, quando necessária ou exigida pelo modo |
|
|
157
|
+
| Evidências e registros de execução | O que foi verificado, para qual versão e com qual resultado |
|
|
158
|
+
|
|
159
|
+
O agente mantém esses artefatos conforme o trabalho avança. Pesquisa, evidências e histórico não são todos gerados por `sdd new`.
|
|
160
|
+
|
|
161
|
+
## Como o contexto permanece enxuto
|
|
162
|
+
|
|
163
|
+
**O repositório guarda o conhecimento. O agente recebe uma seleção pertinente para o trabalho atual.**
|
|
164
|
+
|
|
165
|
+
```mermaid
|
|
166
|
+
flowchart TD
|
|
167
|
+
A["Spec e tarefa atual"] --> D["Selecionar contexto"]
|
|
168
|
+
B["Contratos, decisões e skills"] --> D
|
|
169
|
+
C["Referências pertinentes de docs/"] --> D
|
|
170
|
+
D --> E{"Cabe no orçamento?"}
|
|
171
|
+
E -->|"Sim"| F["Entregar pacote ao agente"]
|
|
172
|
+
E -->|"Não"| G["Revisar fontes, seções e escopo"]
|
|
173
|
+
G --> D
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
- O ponto de entrada é um mapa curto.
|
|
177
|
+
- A fase e a tarefa orientam a seleção.
|
|
178
|
+
- Skills são descobertas por nome e descrição; o corpo é carregado quando selecionado.
|
|
179
|
+
- Documentos extensos podem ser referenciados por seção.
|
|
180
|
+
- O histórico completo não entra automaticamente em cada sessão.
|
|
181
|
+
- `TASK.md` concentra o andamento; `STATE.md` é uma retomada curta e opcional.
|
|
182
|
+
|
|
183
|
+
```sh
|
|
184
|
+
sdd context 001-minha-mudanca --phase implement --task T01 --inspect
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
A inspeção mostra o tamanho e os documentos contribuintes, sem emitir seus corpos. O orçamento padrão é **48.000 bytes**, configurável; não é uma contagem de tokens nem o limite total da conversa.
|
|
188
|
+
|
|
189
|
+
Se o pacote ultrapassar o orçamento, a geração informa o problema **sem truncar conteúdo silenciosamente**. O agente pode selecionar seções, revisar referências ou separar entregas independentes.
|
|
190
|
+
|
|
191
|
+
A seleção depende de referências bem mantidas. O CLI não descobre sozinho todos os efeitos de uma mudança nem controla o histórico do chat.
|
|
192
|
+
|
|
193
|
+
## Use docs/ como seu acervo de referências
|
|
194
|
+
|
|
195
|
+
PRD, regras de negócio, System Design, ADRs, Design System, contratos e materiais externos podem continuar organizados em `docs/`, com ou sem subpastas.
|
|
196
|
+
|
|
197
|
+
**Centralize as fontes; selecione a leitura.** O agente consulta o índice e os documentos pertinentes, preservando a origem e identificando o que está vigente.
|
|
198
|
+
|
|
199
|
+
Exemplo de referência em `change.yaml`:
|
|
200
|
+
|
|
201
|
+
```yaml
|
|
202
|
+
sources:
|
|
203
|
+
- path: docs/produto/prd.md
|
|
204
|
+
section: Exportação de dados
|
|
205
|
+
context:
|
|
206
|
+
- path: docs/design/design-system.md
|
|
207
|
+
section: Estados e interações
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
Não há um conjunto obrigatório de documentos. Uma descrição clara pode bastar para iniciar um projeto.
|
|
211
|
+
|
|
212
|
+
Quer modelos opcionais?
|
|
213
|
+
|
|
214
|
+
```sh
|
|
215
|
+
sdd docs --types prd,sd,ds,adr,roadmap --dry-run
|
|
216
|
+
sdd docs --types prd,sd,ds,adr,roadmap
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
Arquivos existentes são preservados. Os novos são rascunhos para revisão. Consulte [setup e documentos](docs/setup-documents.pt-BR.md).
|
|
220
|
+
|
|
221
|
+
## Rigor proporcional à mudança
|
|
222
|
+
|
|
223
|
+
| Modo | Quando usar |
|
|
224
|
+
|---|---|
|
|
225
|
+
| `light` | Mudança pequena; tarefas e pesquisa podem ser dispensadas |
|
|
226
|
+
| `standard` | Funcionalidade delimitada, com tarefas verificáveis |
|
|
227
|
+
| `rigorous` | Mudança sensível ou com maior incerteza, com pesquisa e aprovação explícitas |
|
|
228
|
+
|
|
229
|
+
O padrão de instalações novas é **step**: implementar e verificar uma tarefa e parar para revisão.
|
|
230
|
+
Autorize tarefas específicas ou todas as tarefas para continuar em lote sem confirmações repetidas.
|
|
231
|
+
Aprovar o plano, por si só, não muda essa autonomia. **Batch** também pode ser a preferência permanente;
|
|
232
|
+
atualizações preservam a escolha existente. Cada tarefa continua sendo verificada, respeitando dependências.
|
|
233
|
+
|
|
234
|
+
## Verificação honesta, inclusive sem ambiente externo
|
|
235
|
+
|
|
236
|
+
O CLI executa checks configurados e registra comandos, resultados e inputs. Aprovações ficam vinculadas ao plano; verificações ficam vinculadas à versão examinada.
|
|
237
|
+
|
|
238
|
+
| Resultado | O que significa |
|
|
239
|
+
|---|---|
|
|
240
|
+
| `passed` | Verificação integral aprovada para os inputs atuais |
|
|
241
|
+
| `limited` | Implementação concluída com limitações externas e pendências explícitas |
|
|
242
|
+
| `partial` | Ainda não há condições para o encerramento final |
|
|
243
|
+
| `failed` | Há falha obrigatória observada ou alteração de inputs durante a execução |
|
|
244
|
+
|
|
245
|
+
**Falta de produção ou homologação não precisa bloquear uma implementação pronta.** Um handoff pode registrar o que falta e gerar um roteiro seguro em `USER_TESTS.md`.
|
|
246
|
+
|
|
247
|
+
`limited` não significa que o teste externo passou e não autoriza deploy. Uma falha conhecida não desaparece ao omitir sua evidência.
|
|
248
|
+
|
|
249
|
+
Checks obrigatórios bloqueiam em caso de falha; indicadores informativos aparecem como avisos. TDD, exemplos BDD e métricas podem ser adotados conforme o projeto, sem uma ferramenta ou percentual universal obrigatório.
|
|
250
|
+
|
|
251
|
+
Leia o [guia de qualidade e falta de ambiente](docs/quality-gates.pt-BR.md).
|
|
252
|
+
|
|
253
|
+
## Portabilidade e escopo
|
|
254
|
+
|
|
255
|
+
| O sdd-flow organiza | O harness fornece |
|
|
256
|
+
|---|---|
|
|
257
|
+
| Método, specs, contexto e rastreabilidade | Modelos, ferramentas e permissões |
|
|
258
|
+
| Referências e evidências | MCPs e acesso a serviços |
|
|
259
|
+
| Pontos de entrada e conhecimento exportável | Compactação e eventual delegação |
|
|
260
|
+
|
|
261
|
+
O método pode ser seguido em uma conversa, em sessões separadas ou com delegação nativa. **Não exige multiagentes nem cria um orquestrador próprio.**
|
|
262
|
+
|
|
263
|
+
Adaptadores para Claude Code e OpenCode fornecem comandos e uma skill do workflow. Exports preparam conhecimento para distribuição; não publicam em marketplaces. Veja [adaptadores e distribuição](docs/distribution.md).
|
|
264
|
+
|
|
265
|
+
## Para agentes de IA
|
|
266
|
+
|
|
267
|
+
1. Comece pelo `AGENTS.md` e pelo mapa do projeto.
|
|
268
|
+
2. Use `SETUP.md` na adoção inicial; depois siga o procedimento da fase.
|
|
269
|
+
3. Consulte as fontes pertinentes, sem carregar toda a pasta `docs/`.
|
|
270
|
+
4. Preserve IDs, regras vigentes, arquitetura observada e trabalho existente.
|
|
271
|
+
5. Considere consumidores e regressões antes de alterar comportamento compartilhado.
|
|
272
|
+
6. Registre autorização real, resultados observados e limitações.
|
|
273
|
+
7. Mantenha o estado canônico e consolide o conhecimento antes de encerrar.
|
|
274
|
+
|
|
275
|
+
Metadados estruturados usam YAML; não há dependência de números fixos de linha. Documentos de referência são dados do projeto e não substituem a autorização do usuário.
|
|
276
|
+
|
|
277
|
+
<details>
|
|
278
|
+
<summary>Comandos essenciais para uma mudança</summary>
|
|
279
|
+
|
|
280
|
+
Exemplo com ID ilustrativo; o agente precisa preencher o plano entre os comandos:
|
|
281
|
+
|
|
282
|
+
```sh
|
|
283
|
+
sdd new minha-mudanca --mode standard
|
|
284
|
+
sdd context 001-minha-mudanca --phase plan
|
|
285
|
+
# Definir requisitos, aceitação, tarefas e referências.
|
|
286
|
+
sdd check 001-minha-mudanca
|
|
287
|
+
|
|
288
|
+
# Registrar somente a autorização realmente concedida:
|
|
289
|
+
sdd approve 001-minha-mudanca --by "Responsável"
|
|
290
|
+
|
|
291
|
+
sdd context 001-minha-mudanca --phase implement --task T01
|
|
292
|
+
# Implementar, verificar e atualizar as tarefas.
|
|
293
|
+
# Consolidar os contratos vigentes antes da verificação final.
|
|
294
|
+
sdd verify 001-minha-mudanca
|
|
295
|
+
sdd close 001-minha-mudanca --by "Responsável" --archive
|
|
296
|
+
```
|
|
297
|
+
|
|
298
|
+
O fechamento exige consolidação das capacidades selecionadas ou `--note` explicando por que não há atualização duradoura. Evidências manuais e limitações externas usam os argumentos específicos de verificação.
|
|
299
|
+
|
|
300
|
+
`sdd check` valida estrutura; `sdd verify` executa os checks configurados. Não são a mesma operação.
|
|
301
|
+
|
|
302
|
+
</details>
|
|
303
|
+
|
|
304
|
+
## Reinstalar ou atualizar sem começar de novo
|
|
305
|
+
|
|
306
|
+
O instalador 2.x distingue arquivos do projeto e arquivos gerenciados do método.
|
|
307
|
+
|
|
308
|
+
| Situação | Comportamento esperado |
|
|
309
|
+
|---|---|
|
|
310
|
+
| `init` repetido na mesma versão | Preserva configuração e trabalho existentes; arquivos ausentes podem ser repostos |
|
|
311
|
+
| Núcleo personalizado | Informa conflito em vez de sobrescrever silenciosamente |
|
|
312
|
+
| Nova versão do CLI | Não atualiza automaticamente os arquivos já copiados na aplicação |
|
|
313
|
+
| `update` com núcleo reconhecido e sem conflito | Atualiza os arquivos gerenciados e preserva os arquivos do projeto |
|
|
314
|
+
| Projeto vindo da 1.x | Exige revisão do núcleo e dos formatos das specs; não converte evidência antiga em aprovação atual |
|
|
315
|
+
|
|
316
|
+
`PROJECT.md`, `POLICIES.md`, `QUALITY.md`, `config.yaml` e `DECISIONS.md` existentes são preservados.
|
|
317
|
+
Specs, skills próprias, documentos em `docs/` e histórico não são apagados pelo instalador.
|
|
318
|
+
Se o setup foi concluído e removido, a manutenção normal não o recria.
|
|
319
|
+
|
|
320
|
+
Antes de atualizar, preserve o estado atual em commit ou backup. Instale a versão desejada do CLI
|
|
321
|
+
— pelo npm ou, para testes, pelo código-fonte — e, dentro da aplicação, execute:
|
|
322
|
+
|
|
323
|
+
```sh
|
|
324
|
+
sdd --version
|
|
325
|
+
sdd update --dry-run
|
|
326
|
+
# Revise a prévia e resolva os conflitos antes de aplicar.
|
|
327
|
+
sdd update
|
|
328
|
+
sdd doctor
|
|
329
|
+
```
|
|
330
|
+
|
|
331
|
+
Se usa adaptador, atualize seus pontos de entrada com `sdd harness claude-code` ou `sdd harness opencode`.
|
|
332
|
+
Configurações nativas não são sobrescritas; permissões e hooks antigos exigem revisão própria.
|
|
333
|
+
|
|
334
|
+
<details>
|
|
335
|
+
<summary>Migrar da 1.x ou tratar um conflito</summary>
|
|
336
|
+
|
|
337
|
+
O updater reconhece os templates originais não modificados da base 1.3.3.
|
|
338
|
+
Versões personalizadas, inclusive adaptações de terceiros, podem exigir revisão manual.
|
|
339
|
+
|
|
340
|
+
Para uma spec antiga que será retomada ou normalizada:
|
|
341
|
+
|
|
342
|
+
```sh
|
|
343
|
+
sdd migrate 001-minha-mudanca --dry-run
|
|
344
|
+
sdd migrate 001-minha-mudanca
|
|
345
|
+
```
|
|
346
|
+
|
|
347
|
+
Use o ID real. A migração preserva os corpos antigos e cria estruturas para revisão.
|
|
348
|
+
Revise requisitos, aceitação, tarefas e referências antes de normalizar.
|
|
349
|
+
Não é necessário converter todo o histórico encerrado só para adotar o fluxo nas próximas mudanças.
|
|
350
|
+
|
|
351
|
+
Arquivos centrais personalizados geram conflito e interrompem a aplicação das mudanças planejadas do núcleo.
|
|
352
|
+
Transfira particularidades para políticas, contratos ou skills antes de decidir substituir o núcleo.
|
|
353
|
+
`--replace-managed` é uma opção explícita após revisão; conteúdos substituídos recebem backups.
|
|
354
|
+
|
|
355
|
+
Essa proteção descreve o instalador 2.x. Não use um instalador 1.x para fazer downgrade nem
|
|
356
|
+
presuma compatibilidade automática com versões futuras.
|
|
357
|
+
Veja o [guia de migração](docs/migration.md).
|
|
358
|
+
|
|
359
|
+
</details>
|
|
360
|
+
|
|
361
|
+
## Documentação
|
|
362
|
+
|
|
363
|
+
| Quero… | Consultar |
|
|
364
|
+
|---|---|
|
|
365
|
+
| Usar o fluxo do início ao fim | [Guia de uso](docs/usage.pt-BR.md) |
|
|
366
|
+
| Entender setup, perguntas e documentos | [Setup e referências](docs/setup-documents.pt-BR.md) |
|
|
367
|
+
| Conhecer o método e a evolução | [Metodologia](docs/methodology.pt-BR.md) |
|
|
368
|
+
| Configurar qualidade e testes externos | [Quality gates](docs/quality-gates.pt-BR.md) |
|
|
369
|
+
| Entender os formatos | [Formatos e exemplos](docs/formats.md) |
|
|
370
|
+
| Testar localmente | [Laboratórios de teste](docs/local-testing.pt-BR.md) |
|
|
371
|
+
| Atualizar projetos antigos | [Migração](docs/migration.md) |
|
|
372
|
+
| Preparar plugins e skills | [Distribuição](docs/distribution.md) |
|
|
373
|
+
| Revisar evidências e limites da entrega | [Validação registrada](docs/validation.md) |
|
|
374
|
+
| Publicar uma versão | [GitHub e npm](docs/releases.pt-BR.md) |
|
|
375
|
+
| Contribuir | [Contribuição](CONTRIBUTING.md) · [Changelog](CHANGELOG.md) |
|
|
376
|
+
|
|
377
|
+
## Limites importantes
|
|
378
|
+
|
|
379
|
+
O CLI valida relações declaradas e registra execuções. Uma suíte verde não prova que as assertions cobrem todo o negócio. Aprovações são declarações registradas, não autenticação de identidade.
|
|
380
|
+
|
|
381
|
+
Comandos usam as permissões da conta atual; o CLI não é sandbox. Revise configurações, use os controles nativos do harness e escolha ambientes seguros.
|
|
382
|
+
|
|
383
|
+
A seleção de contexto reduz leitura desnecessária; não garante menor custo ou melhor código em qualquer tarefa. A compatibilidade interativa dos adaptadores deve ser verificada nas versões de ferramentas utilizadas.
|
|
384
|
+
|
|
385
|
+
## Licença
|
|
386
|
+
|
|
387
|
+
[MIT](LICENSE).
|