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
|
@@ -0,0 +1,139 @@
|
|
|
1
|
+
# Metodologia e limites do sdd-flow
|
|
2
|
+
|
|
3
|
+
O objetivo do sdd-flow é organizar desenvolvimento assistido por IA, entregar contexto pertinente
|
|
4
|
+
e manter acompanhamento e rastreabilidade, independentemente da tecnologia da aplicação.
|
|
5
|
+
O CLI operacionaliza partes objetivas do método; o harness fornece ferramentas e execução.
|
|
6
|
+
Não é objetivo criar um orquestrador, um cliente MCP ou uma plataforma de agentes.
|
|
7
|
+
|
|
8
|
+
## O que continua essencial
|
|
9
|
+
|
|
10
|
+
1. Compreender o problema e investigar incertezas relevantes.
|
|
11
|
+
2. Definir escopo observável, requisitos e aceitação.
|
|
12
|
+
3. Planejar e executar resultados coesos, preservando o trabalho existente.
|
|
13
|
+
4. Verificar o comportamento e registrar o que foi realmente observado.
|
|
14
|
+
5. Consolidar conhecimento vigente e preservar o histórico da mudança.
|
|
15
|
+
|
|
16
|
+
Research, Plan, Implement, Validate e Close são responsabilidades lógicas. A pesquisa pode ser breve
|
|
17
|
+
quando já existe informação suficiente; rigorous exige um registro explícito. Verificações parciais
|
|
18
|
+
podem ocorrer durante a implementação. O encerramento depende de evidência final atual e consolidação.
|
|
19
|
+
Fases não obrigam abrir novas conversas. Uma sessão, subagentes nativos ou uma sessão nova são opções
|
|
20
|
+
do ambiente. Depois de compactação ou transferência, recupere o estado pelos arquivos canônicos.
|
|
21
|
+
|
|
22
|
+
Instalações novas usam step: uma tarefa por vez, seguida de revisão. A autorização do usuário para
|
|
23
|
+
várias tarefas específicas ou todas as tarefas permite continuar nesse lote sem confirmações repetidas
|
|
24
|
+
nem alteração obrigatória da configuração. Aprovação do plano, por si só, não muda a autonomia.
|
|
25
|
+
Batch pode ser a preferência permanente; atualizações preservam a escolha de projetos existentes.
|
|
26
|
+
Cada tarefa continua sendo verificada e as dependências respeitadas, inclusive durante um lote.
|
|
27
|
+
|
|
28
|
+
Evidência de execução local e validação externa são distintas. Falta de ambiente não precisa bloquear
|
|
29
|
+
uma implementação concluída: um handoff atual registra o que ficou pendente e como testar com segurança.
|
|
30
|
+
O encerramento limited nunca representa teste externo aprovado; falhas observadas continuam registradas.
|
|
31
|
+
Veja quality-gates.pt-BR.md para a política required/advisory, exemplos BDD e procedimento TDD.
|
|
32
|
+
|
|
33
|
+
## Comparação com as versões analisadas
|
|
34
|
+
|
|
35
|
+
Base original: sdd-flow 1.3.3, commit d84c62d51d9c566b0f3e8a6279418220e0fc6e8f.
|
|
36
|
+
O anexo do colaborador foi analisado como conjunto de arquivos; não continha histórico Git que
|
|
37
|
+
permitisse demonstrar ancestralidade. A comparação se refere aos materiais examinados em 20/11/2026.
|
|
38
|
+
|
|
39
|
+
| Aspecto | Original 1.3.3 | Ajuste do colaborador | Atual 2.x |
|
|
40
|
+
|---|---|---|---|
|
|
41
|
+
| Método | RPIV e tarefas muito fragmentadas | Mais controles sobre o mesmo método | Método preservado, modos light/standard/rigorous, execução step/batch e consolidação |
|
|
42
|
+
| Contexto | Leitura global e histórico acumulado | Acrescentou conteúdo obrigatório e repetição | Seleção por tarefa/fase e fontes explícitas; histórico fora da leitura padrão |
|
|
43
|
+
| Tarefas | Estado repetido em TASK/PROGRESS | Conservou a necessidade de sincronização | TASK canônico; STATE curto e opcional |
|
|
44
|
+
| Rastreabilidade | Predominantemente orientações em Markdown | IDs e covers mais explícitos | IDs e relações validados, registros por execução e histórico de revisões |
|
|
45
|
+
| Skills | Extração por trechos fixos | Front matter com instruções de geração/leitura divergentes | Parser YAML, catálogo curto e corpo por pertinência |
|
|
46
|
+
| Aprovação | Orientação no processo | Aprovação de seis arquivos sem vincular todas ao conteúdo | Aprovação do escopo normativo com digest e snapshots |
|
|
47
|
+
| Mudança de regra | Procedimento manual de revisão do plano | Invalidação incompleta de alguns registros | Revisão, reabertura de trabalho afetado e rejeição de evidência obsoleta |
|
|
48
|
+
| Validação parcial | Permitida | Bloqueada com tarefas pendentes | Permitida, sem representar encerramento final |
|
|
49
|
+
| Teste manual | Previsto em instruções | Sem caminho claro até conclusão aprovada | Evidência manual real pode passar; falta de ambiente pode ser registrada como limited |
|
|
50
|
+
| Qualidade | Princípios no prompt | Atenção adicional às assertions e achados | Checks required/advisory, evidências, regressões, TDD/BDD e handoff seguro |
|
|
51
|
+
| Git | Proibição geral de writes | Não houve mecanismo novo de integração demonstrado no anexo | Autorização real e permissões nativas, sem bloqueio geral do método |
|
|
52
|
+
| Documentos | Opção fixa de PRD, roadmap e architecture | Sem evolução do instalador demonstrada no anexo | Mesma opção restaurada e presets adicionais SD/DS/ADR, preservando fontes existentes |
|
|
53
|
+
| Instalação | Cópia de templates com opção de sobrescrever | Sem instalador alternativo demonstrado no anexo | Preservação, conflitos, prévia, backups e migração conservadora |
|
|
54
|
+
|
|
55
|
+
O ganho demonstrável é estrutural e funcional: menos estados redundantes, seleção de contexto e
|
|
56
|
+
condições verificáveis. Isso não prova menor custo de tokens, melhor código ou superioridade sobre
|
|
57
|
+
todo framework. Tais afirmações exigem avaliações repetidas com tarefas, modelos e condições comparáveis.
|
|
58
|
+
|
|
59
|
+
O colaborador melhorou o desenho de rastreabilidade; esta evolução incorpora esses acertos e corrige
|
|
60
|
+
as inconsistências encontradas nos materiais. Não foram comparadas implementações reais produzidas
|
|
61
|
+
pelos três workflows, portanto superioridade de custo ou de qualidade do código gerado não está demonstrada.
|
|
62
|
+
|
|
63
|
+
O núcleo ficou mais verificável, mas também exige aprender formatos e comandos novos e usar Node 22+.
|
|
64
|
+
A seleção de contexto depende de referências bem mantidas; o CLI não infere automaticamente todos os
|
|
65
|
+
efeitos de uma mudança. A verificação é conservadora: alterações nos inputs podem exigir nova execução.
|
|
66
|
+
Identidade do revisor, semântica dos testes e segurança do ambiente não são atestadas pelo CLI.
|
|
67
|
+
Há hotspots de complexidade no próprio código, registrados em validation.md; os testes não eliminam
|
|
68
|
+
a necessidade de manutenção e avaliação prática nos harnesses.
|
|
69
|
+
|
|
70
|
+
## Como o fluxo funciona na prática
|
|
71
|
+
|
|
72
|
+
1. Instale a base e faça o setup guiado pelo agente, usando fontes e fatos disponíveis.
|
|
73
|
+
2. Crie uma mudança com objetivo delimitado; pesquise somente as incertezas relevantes.
|
|
74
|
+
3. Defina requisitos, exemplos de aceitação, tarefas e impacto nos consumidores.
|
|
75
|
+
4. Registre a autorização real e implemente dentro desse escopo, consultando contexto pertinente.
|
|
76
|
+
5. Execute checks disponíveis, revise assertions/regressões e registre limitações quando faltar ambiente.
|
|
77
|
+
6. Consolide o conhecimento vigente e encerre como verificado ou implementado com limitações explícitas.
|
|
78
|
+
|
|
79
|
+
Instalação não cria entendimento de produto sozinha. Veja setup-documents.pt-BR.md para perguntas,
|
|
80
|
+
PRD, ADR, system design, design system e modelos opcionais. O método não exige uma tríade fixa de documentos.
|
|
81
|
+
|
|
82
|
+
## O que permanece rastreável
|
|
83
|
+
|
|
84
|
+
| Pergunta | Registro |
|
|
85
|
+
|---|---|
|
|
86
|
+
| O que foi solicitado e qual aceitação deve ser atendida? | change.yaml e SPEC.md |
|
|
87
|
+
| Como será feito e em que estado está? | TASK.md |
|
|
88
|
+
| Qual escopo foi autorizado, quando e por quem? | approval e history/approval-*.json |
|
|
89
|
+
| O que mudou no plano aprovado e por quê? | history/revision-*.json |
|
|
90
|
+
| Quais comandos rodaram e que resultado produziram? | runs/ID/receipt.json e logs |
|
|
91
|
+
| Que observação manual foi realizada? | Evidência com cenário, executor, instante e fingerprint |
|
|
92
|
+
| Qual resultado pode ser usado agora? | verification.json, válido somente para os inputs atuais |
|
|
93
|
+
| Como o sistema funciona após a entrega? | current/ e decisões ativas |
|
|
94
|
+
| Como chegamos até aqui? | Histórico da mudança, arquivo e Git |
|
|
95
|
+
|
|
96
|
+
O framework rastreia artefatos, estados, decisões e execuções registradas. Não captura cada pensamento
|
|
97
|
+
do modelo nem todas as chamadas do harness. Sessões, traces e auditoria externa podem complementar
|
|
98
|
+
os registros. Aprovações são declarações registradas, não autenticação de identidade.
|
|
99
|
+
|
|
100
|
+
## Portabilidade
|
|
101
|
+
|
|
102
|
+
O núcleo funciona com arquivos e comandos. Adaptadores fornecem pontos de entrada, preservando
|
|
103
|
+
configurações existentes. Permissões, MCP, modelos, compactação e delegação pertencem ao harness.
|
|
104
|
+
Essas capacidades não alteram as condições de aceitação e de encerramento.
|
|
105
|
+
|
|
106
|
+
Ferramentas externas podem fornecer evidência; registre origem e instante quando relevantes.
|
|
107
|
+
O fingerprint local não atesta por conta própria um sistema remoto.
|
|
108
|
+
Não é necessário A2A ou multiagentes para seguir esta metodologia.
|
|
109
|
+
|
|
110
|
+
## Idioma e escrita
|
|
111
|
+
|
|
112
|
+
As instruções distribuídas do método permanecem em inglês como fonte comum.
|
|
113
|
+
O idioma dos documentos do aplicativo é configurável, independentemente do idioma desses templates.
|
|
114
|
+
|
|
115
|
+
~~~yaml
|
|
116
|
+
documentation:
|
|
117
|
+
language: pt-BR
|
|
118
|
+
~~~
|
|
119
|
+
|
|
120
|
+
Use português correto e UTF-8 nos artefatos narrativos: requisitos, aceitação, tarefas, pesquisa,
|
|
121
|
+
contratos, decisões e observações. Preserve termos originais quando a tradução prejudicar o significado.
|
|
122
|
+
Chaves técnicas, IDs, paths e APIs permanecem estáveis; a chave description pode ter valor em português.
|
|
123
|
+
Slugs podem ser ASCII sem eliminar acentos do título ou do conteúdo.
|
|
124
|
+
|
|
125
|
+
auto é o padrão genérico: o agente segue o idioma do usuário até o setup registrar a escolha da equipe.
|
|
126
|
+
Configurações antigas sem documentation continuam válidas. O CLI valida a tag e a inclui no contexto;
|
|
127
|
+
isso orienta o agente, não certifica linguisticamente cada frase.
|
|
128
|
+
Novas specs/tarefas têm textos iniciais em português quando a configuração usa pt ou pt-BR.
|
|
129
|
+
Outros idiomas podem ser usados pelo agente; os textos iniciais do CLI usam inglês como fallback.
|
|
130
|
+
Diagnósticos, chaves de máquina e relatórios determinísticos do CLI ainda podem permanecer em inglês;
|
|
131
|
+
esta versão não é uma localização completa da interface do CLI.
|
|
132
|
+
|
|
133
|
+
Não foi medido ganho de qualidade/custo por escrever as instruções em inglês. Não elimine
|
|
134
|
+
acentos como técnica de otimização. A clareza para autores e revisores de negócio é o critério principal.
|
|
135
|
+
Não traduza o histórico encerrado apenas para uniformizar aparência. A tradução de um contrato ativo
|
|
136
|
+
aprovado altera seu conteúdo e exige revisão; preserve o registro anterior.
|
|
137
|
+
|
|
138
|
+
Use local-testing.pt-BR.md para testar o CLI e executar cenários com um agente real.
|
|
139
|
+
Um pacote menor que omite uma regra é uma regressão, não uma otimização.
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
# Migrating from 1.x
|
|
2
|
+
|
|
3
|
+
2.x changes the artifact format and requires Node.js 22+. Work in a versioned branch and review the diff.
|
|
4
|
+
|
|
5
|
+
## Preview and install the new core
|
|
6
|
+
|
|
7
|
+
~~~sh
|
|
8
|
+
sdd update --dry-run
|
|
9
|
+
sdd update
|
|
10
|
+
~~~
|
|
11
|
+
|
|
12
|
+
The updater recognizes unchanged templates from the 1.3.3 baseline.
|
|
13
|
+
It preserves project-owned PROJECT.md, POLICIES.md, config.yaml and the historical DECISIONS.md.
|
|
14
|
+
The root entry point is a managed block; existing custom content outside that block is preserved.
|
|
15
|
+
Custom or unowned core files produce a conflict and no planned template writes are applied.
|
|
16
|
+
Review them before using sdd update --replace-managed. Replaced contents are backed up under agents/.sdd/backups/.
|
|
17
|
+
|
|
18
|
+
Do not use replacement as an automatic resolution for project-specific requirements.
|
|
19
|
+
Move durable rules to the project map, current contracts or ADRs, then review the new core.
|
|
20
|
+
|
|
21
|
+
## Migrate each legacy change
|
|
22
|
+
|
|
23
|
+
~~~sh
|
|
24
|
+
sdd migrate 001-feature --dry-run
|
|
25
|
+
sdd migrate 001-feature
|
|
26
|
+
~~~
|
|
27
|
+
|
|
28
|
+
Migration adds change.yaml and preserves the original Markdown bodies.
|
|
29
|
+
It extracts recognizable task IDs/statuses without inventing requirement links or verify evidence.
|
|
30
|
+
Original files are backed up. The new scope remains draft and unapproved.
|
|
31
|
+
Legacy context remains readable before migration with an explicit warning.
|
|
32
|
+
|
|
33
|
+
Review SPEC.md requirements/acceptance and TASK.md covers/verify/dependencies.
|
|
34
|
+
Consolidate current behavior from the old specs into current capability documents.
|
|
35
|
+
Remove legacy: true only after normalization. Resolve sdd check findings and record actual authorization.
|
|
36
|
+
Old PROGRESS.md, TEST.md, decisions and validation reports remain historical; v2 does not treat them
|
|
37
|
+
as canonical state or current execution evidence.
|
|
38
|
+
|
|
39
|
+
## Adapters and old settings
|
|
40
|
+
|
|
41
|
+
~~~sh
|
|
42
|
+
sdd harness claude-code
|
|
43
|
+
sdd harness opencode
|
|
44
|
+
~~~
|
|
45
|
+
|
|
46
|
+
2.x installs native commands and a workflow skill, plus a managed CLAUDE.md entry for compatible clients.
|
|
47
|
+
No permission settings are changed. Existing 1.x active hooks/settings are not silently deleted.
|
|
48
|
+
Review old .claude/settings.json, opencode.json(c) and agents/harness references manually.
|
|
49
|
+
Remove obsolete blocks only after confirming which parts belong to the old workflow.
|
|
50
|
+
|
|
51
|
+
Existing adapter files with local/unowned edits are preserved and reported.
|
|
52
|
+
Removal deletes only files whose current content matches the recorded ownership hash.
|
|
53
|
+
Update installed wrappers by rerunning the corresponding harness command after a core upgrade.
|
|
54
|
+
|
|
55
|
+
## Backups and recovery
|
|
56
|
+
|
|
57
|
+
Backups retain project-relative names under the reported backup directory.
|
|
58
|
+
Compare and restore only the desired files. The CLI never runs Git reset or rewrites repository history.
|
|
59
|
+
Do not delete the registry when archiving changes; it reserves IDs even if directories later move.
|
|
60
|
+
If a crashed process leaves agents/.sdd/lock, confirm no SDD mutation is active before removing it.
|
|
61
|
+
|
|
62
|
+
## Behavioral changes
|
|
63
|
+
|
|
64
|
+
- New projects default to step; explicit user authorization for several/all tasks permits a bounded batch.
|
|
65
|
+
- Existing configured autonomy is preserved. Update does not reset a project's batch preference to step.
|
|
66
|
+
- Research is optional except in rigorous mode.
|
|
67
|
+
- Task state lives in YAML metadata, with no duplicate PROGRESS table.
|
|
68
|
+
- Approval applies to scope, not to six independently mutable files.
|
|
69
|
+
- Mandatory project constraints live in POLICIES.md; skills carry conditional procedures.
|
|
70
|
+
- Approved-scope snapshots, revisions and each run receipt remain available outside default context.
|
|
71
|
+
- Tests may be automated, manual or inspection-based.
|
|
72
|
+
- Partial verification is supported and cannot close a change.
|
|
73
|
+
- Closing requires fresh full evidence and explicit consolidation.
|
|
74
|
+
- Full limited verification may close implementation with a current environment handoff, retaining pending tests explicitly.
|
|
75
|
+
- Existing checks remain required/local. Classify external checks deliberately; they no longer run without --run-external.
|
|
76
|
+
- QUALITY.md is project-owned. New quality policy fields can invalidate old active approvals; review/reapprove their actual scope.
|
|
@@ -0,0 +1,160 @@
|
|
|
1
|
+
# Qualidade e validação sem acesso ao ambiente real
|
|
2
|
+
|
|
3
|
+
O objetivo é concluir trabalho útil com evidência honesta. Falta de produção ou homologação não exige
|
|
4
|
+
inventar um teste, arriscar dados reais ou manter uma implementação pronta bloqueada indefinidamente.
|
|
5
|
+
Falha observada, implementação incompleta e ausência de ambiente são situações diferentes.
|
|
6
|
+
|
|
7
|
+
## Política pequena por projeto
|
|
8
|
+
|
|
9
|
+
~~~yaml
|
|
10
|
+
quality:
|
|
11
|
+
tdd: preferred
|
|
12
|
+
checks:
|
|
13
|
+
- name: unit
|
|
14
|
+
command: npm test
|
|
15
|
+
timeout_ms: 60000
|
|
16
|
+
- name: complexity
|
|
17
|
+
command: npm run analyze:complexity
|
|
18
|
+
timeout_ms: 60000
|
|
19
|
+
level: advisory
|
|
20
|
+
- name: integration
|
|
21
|
+
command: npm run test:integration
|
|
22
|
+
timeout_ms: 60000
|
|
23
|
+
environment: external
|
|
24
|
+
~~~
|
|
25
|
+
|
|
26
|
+
Exemplo para um projeto com esses scripts reais; não os copie sem configurar as ferramentas.
|
|
27
|
+
Os padrões são level: required e environment: local. optional/preferred/required em quality.tdd
|
|
28
|
+
orientam o procedimento do agente; o CLI não certifica que ele realmente seguiu TDD.
|
|
29
|
+
|
|
30
|
+
- Required: falha observada impede declarar o gate aprovado.
|
|
31
|
+
- Advisory: resultado aparece no relatório, sem bloquear a aceitação funcional.
|
|
32
|
+
- External: o comando não roda por padrão; depende de ambiente/autorização disponíveis.
|
|
33
|
+
- --run-external permite solicitar execução externa, mas não concede autorização nem prova segurança.
|
|
34
|
+
|
|
35
|
+
Aceitação automatizada deve referenciar checks required. Um indicador advisory não comprova
|
|
36
|
+
o comportamento obrigatório. Limiar de complexidade, cobertura, dependências e carga pertence à
|
|
37
|
+
configuração da ferramenta usada. Não há percentual universal imposto pelo sdd-flow.
|
|
38
|
+
Não reclassifique uma falha de código como falta de acesso apenas para encerrar a mudança.
|
|
39
|
+
|
|
40
|
+
QUALITY.md registra critérios do projeto e links; é carregado em plan/validate/close.
|
|
41
|
+
POLICIES.md continua sendo a fonte de obrigações essenciais. O roteiro detalhado em
|
|
42
|
+
agents/prompts/quality.md é consultado quando necessário, sem entrar em toda tarefa.
|
|
43
|
+
Não é preciso instalar Sonar, Cucumber, uma plataforma de observabilidade ou um orquestrador.
|
|
44
|
+
|
|
45
|
+
## BDD e TDD sem duplicação de documentos
|
|
46
|
+
|
|
47
|
+
Registre exemplos concretos em acceptance.description da SPEC: estado inicial, ação e resultado.
|
|
48
|
+
Inclua fronteiras, rejeições e falhas pertinentes ao comportamento. Gherkin/Cucumber são opcionais.
|
|
49
|
+
|
|
50
|
+
Para mudanças de comportamento testáveis, prefira ciclos pequenos: teste falhando pelo motivo esperado,
|
|
51
|
+
implementação suficiente e refatoração. Para bugs, reproduza com regressão quando possível.
|
|
52
|
+
Guarde referências dos resultados RED/GREEN em task.evidence e logs, sem um diário sempre carregado.
|
|
53
|
+
sdd verify --scope partial pode registrar essas execuções, mas uma falha RED nunca é aprovação final.
|
|
54
|
+
Um comando verde não demonstra sozinho a qualidade das assertions, a cobertura semântica ou TDD.
|
|
55
|
+
|
|
56
|
+
## Quando o teste só pode ser feito pelo usuário
|
|
57
|
+
|
|
58
|
+
Classifique a dependência real. Para aceitação manual/inspeção:
|
|
59
|
+
|
|
60
|
+
~~~yaml
|
|
61
|
+
- id: AC02
|
|
62
|
+
covers: [REQ01]
|
|
63
|
+
description: No ambiente autorizado, um usuário sem permissão não consegue alterar o registro.
|
|
64
|
+
method: manual
|
|
65
|
+
environment: external
|
|
66
|
+
~~~
|
|
67
|
+
|
|
68
|
+
Para automação externa, marque o check com environment: external.
|
|
69
|
+
Execute os checks locais disponíveis. Não tente operar produção só para satisfazer a spec.
|
|
70
|
+
|
|
71
|
+
~~~sh
|
|
72
|
+
sdd handoff 001-minha-mudanca
|
|
73
|
+
~~~
|
|
74
|
+
|
|
75
|
+
O comando retorna um caminho novo HANDOFF-<id>.json dentro da spec. O agente preenche o documento.
|
|
76
|
+
Preserve schema_version, id e input_digest gerados; cada limitação tem alvo e responsável claros.
|
|
77
|
+
Exemplo de um item quando ainda não existe ambiente seguro:
|
|
78
|
+
|
|
79
|
+
~~~json
|
|
80
|
+
{
|
|
81
|
+
"kind": "criterion",
|
|
82
|
+
"id": "AC02",
|
|
83
|
+
"result": "deferred",
|
|
84
|
+
"reason": "O agente e o desenvolvedor não têm acesso a um ambiente adequado.",
|
|
85
|
+
"owner": "Responsável pelo projeto",
|
|
86
|
+
"environment": "unavailable",
|
|
87
|
+
"prerequisites": [],
|
|
88
|
+
"steps": [],
|
|
89
|
+
"expected": "A operação é negada e nenhum dado é alterado.",
|
|
90
|
+
"safety": "Não executar escritas, exclusões ou mudanças de permissão em produção como teste.",
|
|
91
|
+
"resume_when": "Existir uma cópia isolada com dados fictícios e acesso autorizado."
|
|
92
|
+
}
|
|
93
|
+
~~~
|
|
94
|
+
|
|
95
|
+
Quando houver teste seguro, use isolated, non-production ou production-read-only e forneça passos
|
|
96
|
+
curtos, pré-requisitos e resultado observável. Exemplo para uma cópia isolada:
|
|
97
|
+
|
|
98
|
+
1. Abra a versão indicada com os dados fictícios informados.
|
|
99
|
+
2. Entre com o perfil de teste sem a permissão necessária.
|
|
100
|
+
3. Tente a ação apenas nessa cópia isolada.
|
|
101
|
+
4. Confira a mensagem de recusa e que o registro fictício permaneceu igual.
|
|
102
|
+
5. Informe versão, ambiente, resultado observado e evidência sem expor credenciais/dados pessoais.
|
|
103
|
+
|
|
104
|
+
production-read-only só cabe quando a ação realmente não provoca efeitos; o nome do campo não
|
|
105
|
+
comprova isso. Não sugira testes de carga, envio de mensagens, exclusões, alterações de permissões ou
|
|
106
|
+
movimentação de dados reais em produção. Quando não houver um teste seguro, steps pode ficar vazio
|
|
107
|
+
em unavailable: registre a condição futura e siga com a implementação disponível.
|
|
108
|
+
|
|
109
|
+
O usuário não precisa preencher metadados técnicos para fazer o teste. O agente prepara USER_TESTS.md;
|
|
110
|
+
o usuário segue apenas o que é possível e seguro e relata o observado. O agente registra depois
|
|
111
|
+
executor, instante, versão e resultado reais, sem declarar que ele próprio executou o teste.
|
|
112
|
+
|
|
113
|
+
## Verificar e encerrar com limitações
|
|
114
|
+
|
|
115
|
+
~~~sh
|
|
116
|
+
sdd verify 001-minha-mudanca --handoff agents/specs/001-minha-mudanca/HANDOFF-ID.json
|
|
117
|
+
sdd close 001-minha-mudanca --by "Responsável" --note "Implementação revista; validação externa pendente" --archive
|
|
118
|
+
~~~
|
|
119
|
+
|
|
120
|
+
Use o caminho realmente retornado. A verificação gera USER_TESTS.md a partir do handoff validado
|
|
121
|
+
e registra os hashes do JSON e do roteiro. Não há execução automática desses passos.
|
|
122
|
+
Cada execução preserva seu roteiro em runs/ID/USER_TESTS.md; USER_TESTS.md é a cópia da versão mais recente.
|
|
123
|
+
|
|
124
|
+
| Resultado | Significado | Encerramento da implementação |
|
|
125
|
+
|---|---|---|
|
|
126
|
+
| passed | Aceitação e checks obrigatórios verificados para os inputs atuais | Permitido |
|
|
127
|
+
| limited | Trabalho concluído com limitações externas explícitas e handoff atual | Permitido, como implemented_with_limitations |
|
|
128
|
+
| partial | Verificação parcial ou itens ainda sem evidência/handoff suficiente | Continuar implementação/registro; não declarar encerramento final |
|
|
129
|
+
| failed | Falha obrigatória observada ou inputs alterados durante a execução | Corrigir/reavaliar e verificar novamente |
|
|
130
|
+
|
|
131
|
+
Com limited, acceptance_verified é false; os itens continuam deferred/not_applicable.
|
|
132
|
+
closure.validation, pending_verification e histórico preservam essas condições após arquivamento.
|
|
133
|
+
Antes de fechar, o estado da mudança é implemented, distinto de verified.
|
|
134
|
+
Consolide o comportamento implementado identificando o que ainda não foi observado no ambiente externo.
|
|
135
|
+
Concluir implementação não comprova funcionamento em produção e não autoriza deploy.
|
|
136
|
+
|
|
137
|
+
Se existe uma tarefa específica de teste externo, use kind: verification, status: deferred e
|
|
138
|
+
deferral: {by: Responsável, reason: Motivo}, cobrindo os IDs externos de aceitação.
|
|
139
|
+
Tarefas de implementação não podem ser adiadas dessa forma. Dependências realmente necessárias
|
|
140
|
+
continuam sendo respeitadas. Se a tarefa externa for executada, atualize seu estado para done antes
|
|
141
|
+
de gerar a evidência final dos inputs atuais.
|
|
142
|
+
|
|
143
|
+
Um caso externo not_applicable precisa de justificativa; não cancela silenciosamente um requisito.
|
|
144
|
+
Para remover comportamento do escopo, revise o contrato e a autorização normalmente.
|
|
145
|
+
Os checks advisory não executados ou falhos aparecem em warnings.
|
|
146
|
+
|
|
147
|
+
## Continuidade, segurança e rastreabilidade
|
|
148
|
+
|
|
149
|
+
- Um handoff só vale para seus inputs; mudança em código/plano exige revisar as limitações.
|
|
150
|
+
- Uma falha observada nos mesmos inputs não desaparece ao omitir evidência ou pular a execução externa.
|
|
151
|
+
- Guia/JSON alterado depois da verificação exige uma nova verificação antes de fechar.
|
|
152
|
+
- Todos os comandos continuam sujeitos às permissões reais. O CLI não é um sandbox.
|
|
153
|
+
- sdd status mostra o resultado do encerramento e as verificações pendentes.
|
|
154
|
+
- Uma dependência encerrada com limitações permite progresso, mas gera aviso para análise do trabalho seguinte.
|
|
155
|
+
- Reabra com motivo quando o ambiente estiver disponível, registre resultados reais e verifique novamente.
|
|
156
|
+
- O histórico do encerramento anterior, com suas limitações, permanece preservado.
|
|
157
|
+
|
|
158
|
+
CLI: 0 significa operação concluída, inclusive limited; 1 indica falha e 2 verificação partial.
|
|
159
|
+
Uma automação que exige validação integral deve avaliar verdict/acceptance_verified, não só o código 0.
|
|
160
|
+
Não transforme esse requisito de uma publicação específica em bloqueio universal do desenvolvimento.
|
package/docs/quality.md
ADDED
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
# Quality and evaluation
|
|
2
|
+
|
|
3
|
+
## Automated checks
|
|
4
|
+
|
|
5
|
+
~~~sh
|
|
6
|
+
npm ci
|
|
7
|
+
npm test
|
|
8
|
+
npm run check
|
|
9
|
+
npm run test:coverage
|
|
10
|
+
npm pack --dry-run
|
|
11
|
+
~~~
|
|
12
|
+
|
|
13
|
+
Tests exercise real temporary projects and child processes:
|
|
14
|
+
installation/preservation/conflicts, YAML parsing, references and cycles, context budgets,
|
|
15
|
+
approval freshness, automated and manual verification, cancellation, archival/reopen,
|
|
16
|
+
timeouts, path restrictions, adapters, conservative migration and npm package installation.
|
|
17
|
+
|
|
18
|
+
Structural checks verify shipped metadata and exports. Test coverage helps find unexercised paths;
|
|
19
|
+
it is not a quality score or proof of semantic correctness.
|
|
20
|
+
|
|
21
|
+
CI is configured to run supported Node.js versions on Linux and Windows.
|
|
22
|
+
The package has one maintained runtime dependency, yaml, locked for reproducible contributor installation.
|
|
23
|
+
Review dependency updates and run package smoke tests before release.
|
|
24
|
+
|
|
25
|
+
## Forward evaluation
|
|
26
|
+
|
|
27
|
+
Use the same project baseline for:
|
|
28
|
+
1. A small reversible automated fix.
|
|
29
|
+
2. A capability with manual verification.
|
|
30
|
+
3. A partially implemented approved requirement that changes.
|
|
31
|
+
4. A fresh-session resume using only the context packet.
|
|
32
|
+
5. A change touching an integration whose current contract must remain valid.
|
|
33
|
+
|
|
34
|
+
Measure omitted constraints, time to resume, relevant/irrelevant documents loaded,
|
|
35
|
+
human interventions, rework and defects found. Repeat cases to account for model variation.
|
|
36
|
+
Do not grade the workflow only by how little Markdown it generates.
|
|
37
|
+
|
|
38
|
+
## Release checklist
|
|
39
|
+
|
|
40
|
+
- Run the suite, package checks and installed-tarball smoke test.
|
|
41
|
+
- Review the diff, migration instructions, scope/evidence semantics and security limitations.
|
|
42
|
+
- Exercise native adapters interactively when available; otherwise record the unverified compatibility without claiming it passed.
|
|
43
|
+
- Record any unverified platform behavior.
|
|
44
|
+
- Publish npm/marketplace artifacts only through an explicitly authorized release action.
|
|
45
|
+
|
|
46
|
+
No comparison in this project claims parity with every other workflow.
|
|
47
|
+
Quality claims should identify tested scenarios and remaining limits.
|
|
48
|
+
|
|
49
|
+
## Project quality and unavailable environments
|
|
50
|
+
|
|
51
|
+
Project-owned QUALITY.md selects meaningful criteria with links to analyzer configuration.
|
|
52
|
+
quality.tdd guides optional/preferred/required practice; acceptance descriptions carry concrete BDD examples.
|
|
53
|
+
Checks are required/local by default; advisory issues remain warnings and external commands require --run-external.
|
|
54
|
+
Full limited verification may close implementation with a current handoff and pending external verification.
|
|
55
|
+
It is not deployment approval or a claim that unavailable tests passed. Failed/partial/stale verification cannot close.
|
|
56
|
+
Detailed safe user-test instructions and examples: quality-gates.pt-BR.md.
|
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
# Publicação de uma nova versão
|
|
2
|
+
|
|
3
|
+
Guia do mantenedor para publicar o pacote npm `sdd-flow` a partir deste repositório.
|
|
4
|
+
Cada nome/versão publicado no npm é permanente: nunca reutilize um número, incremente-o.
|
|
5
|
+
Publicar no npm não atualiza o GitHub, e enviar ao GitHub não publica no npm.
|
|
6
|
+
|
|
7
|
+
## 1. Preparar
|
|
8
|
+
|
|
9
|
+
~~~sh
|
|
10
|
+
git switch main
|
|
11
|
+
git pull --ff-only
|
|
12
|
+
npm ci
|
|
13
|
+
npm test
|
|
14
|
+
npm run check
|
|
15
|
+
npm audit
|
|
16
|
+
~~~
|
|
17
|
+
|
|
18
|
+
1. Atualize `CHANGELOG.md` com a nova versão e a data.
|
|
19
|
+
2. Altere a versão sem criar tag: `npm version <major|minor|patch> --no-git-tag-version`
|
|
20
|
+
(atualiza `package.json` e `package-lock.json` juntos).
|
|
21
|
+
3. Faça o commit e envie para `main`. Não inclua credenciais, `node_modules` ou tarballs.
|
|
22
|
+
4. Aguarde o CI (Linux e Windows, Node 22 e 24) ficar verde.
|
|
23
|
+
|
|
24
|
+
Escolha da versão: correção ou ajuste de documentação/default dentro da mesma linha é patch;
|
|
25
|
+
funcionalidade compatível é minor; mudança incompatível de formato ou de runtime é major.
|
|
26
|
+
|
|
27
|
+
## 2. Publicar primeiro em `next`
|
|
28
|
+
|
|
29
|
+
`next` mantém `latest` na versão anterior, permitindo testar o pacote real do registro.
|
|
30
|
+
Escolha uma rota; não execute ambas para a mesma versão.
|
|
31
|
+
|
|
32
|
+
### Rota A — terminal autenticado
|
|
33
|
+
|
|
34
|
+
Requer acesso de mantenedor e Node.js 22+.
|
|
35
|
+
|
|
36
|
+
~~~sh
|
|
37
|
+
npm run release:check -- --version <versão> --tag next --check-registry
|
|
38
|
+
npm publish --dry-run --tag next
|
|
39
|
+
npm login
|
|
40
|
+
npm publish --tag next
|
|
41
|
+
~~~
|
|
42
|
+
|
|
43
|
+
- O hook `prepublishOnly` repete testes e checks.
|
|
44
|
+
- O npm pode abrir o navegador para confirmar passkey/2FA, ou pedir `--otp=<código>`.
|
|
45
|
+
Não compartilhe senha, OTP ou token em mensagens ou arquivos do projeto.
|
|
46
|
+
|
|
47
|
+
### Rota B — GitHub Actions com Trusted Publishing (OIDC)
|
|
48
|
+
|
|
49
|
+
Arquivo: `.github/workflows/publish.yml`. Acionamento manual, somente em `main` no repositório
|
|
50
|
+
`moisesuailab/sdd-flow`; depende de testes em Node 22/24 em Linux/Windows. O código vem do SHA do disparo,
|
|
51
|
+
a versão é conferida e o mesmo tarball passa por dry-run e publicação, com provenance. Não há token permanente.
|
|
52
|
+
|
|
53
|
+
Configure uma vez, nas definições do pacote no npm:
|
|
54
|
+
|
|
55
|
+
| Campo | Valor |
|
|
56
|
+
|---|---|
|
|
57
|
+
| Provedor | GitHub Actions |
|
|
58
|
+
| Organização/usuário | moisesuailab |
|
|
59
|
+
| Repositório | sdd-flow |
|
|
60
|
+
| Nome do workflow | publish.yml |
|
|
61
|
+
| Environment | npm |
|
|
62
|
+
|
|
63
|
+
E crie o environment `npm` no GitHub (com revisores obrigatórios, se quiser uma aprovação adicional).
|
|
64
|
+
Depois: Actions → “Publish npm package” → Run workflow em `main`, com `version` igual ao `package.json`
|
|
65
|
+
e `dist_tag` = `next`. Documentação atual: https://docs.npmjs.com/trusted-publishers/
|
|
66
|
+
|
|
67
|
+
## 3. Verificar
|
|
68
|
+
|
|
69
|
+
~~~sh
|
|
70
|
+
npm view sdd-flow dist-tags --json
|
|
71
|
+
npx sdd-flow@next --help
|
|
72
|
+
~~~
|
|
73
|
+
|
|
74
|
+
Em uma pasta vazia, execute `npx sdd-flow@next init` e `npx sdd-flow@next doctor`.
|
|
75
|
+
O `doctor` indica pendência até que `agents/PROJECT.md` seja preenchido; isso é esperado.
|
|
76
|
+
|
|
77
|
+
## 4. Tornar estável
|
|
78
|
+
|
|
79
|
+
Depois de revisar migração, evidências e limitações, um mantenedor autenticado promove a versão existente:
|
|
80
|
+
|
|
81
|
+
~~~sh
|
|
82
|
+
npm dist-tag add sdd-flow@<versão> latest
|
|
83
|
+
npm view sdd-flow dist-tags --json
|
|
84
|
+
~~~
|
|
85
|
+
|
|
86
|
+
Isso move a tag; não republica o número. Para voltar atrás, aponte `latest` para a versão anterior
|
|
87
|
+
(`npm dist-tag add sdd-flow@<anterior> latest`). A automação de publish não promove versões.
|
|
88
|
+
|
|
89
|
+
## 5. Registrar no GitHub
|
|
90
|
+
|
|
91
|
+
Crie a tag no **commit exato que foi publicado** (`npm view sdd-flow@<versão> gitHead`):
|
|
92
|
+
|
|
93
|
+
~~~sh
|
|
94
|
+
git tag -a v<versão> <gitHead> -m "sdd-flow <versão>"
|
|
95
|
+
git push origin v<versão>
|
|
96
|
+
~~~
|
|
97
|
+
|
|
98
|
+
Crie o GitHub Release a partir da tag, usando a seção da versão no `CHANGELOG.md`.
|
|
99
|
+
Marque como pré-lançamento enquanto a versão estiver só em `next`.
|
|
100
|
+
|
|
101
|
+
## Atualizar os projetos consumidores
|
|
102
|
+
|
|
103
|
+
Instale o CLI desejado e atualize os templates de cada projeto com `sdd update --dry-run`.
|
|
104
|
+
Atualizar a instalação global não modifica os arquivos já copiados nos aplicativos.
|
|
105
|
+
Leia `usage.pt-BR.md` e `migration.md` antes de migrar o formato 1.x.
|
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
# Perguntas do setup e documentos de referência
|
|
2
|
+
|
|
3
|
+
O setup configura o modo de trabalhar com IA. Os documentos do produto fornecem contexto e decisões.
|
|
4
|
+
sdd init instala arquivos; o agente interpreta objetivo, código e fontes ao seguir agents/SETUP.md.
|
|
5
|
+
O CLI não entrevista o usuário nem descobre automaticamente todas as regras de negócio.
|
|
6
|
+
|
|
7
|
+
## O que o agente precisa saber
|
|
8
|
+
|
|
9
|
+
Não há questionário obrigatório. Primeiro consulte as informações fornecidas e o próprio projeto.
|
|
10
|
+
Pergunte somente sobre lacunas materiais que alterem comportamento, escopo, arquitetura ou segurança.
|
|
11
|
+
|
|
12
|
+
| Informação | Projeto novo | Projeto existente |
|
|
13
|
+
|---|---|---|
|
|
14
|
+
| Propósito e público | Descrição do usuário ou material fornecido | README/PRD e aplicação; confirmar quando houver ambiguidade |
|
|
15
|
+
| Resultado pretendido | Primeira entrega ou objetivo conhecido; refinamento pode ocorrer por spec | Próxima mudança quando definida; não é necessário reconstruir todo o passado |
|
|
16
|
+
| Regras e restrições | Regras conhecidas, permissões e integrações relevantes | Código, contratos e fontes vigentes; separar intenção e comportamento observado |
|
|
17
|
+
| Tecnologia | Escolhas obrigatórias ou proposta justificada a revisar | Manifests, configuração, dependências e estrutura reais |
|
|
18
|
+
| Convenções e interface | Padrões fornecidos ou decisões ainda abertas | Componentes, tokens, design system e práticas existentes |
|
|
19
|
+
| Verificação | O que pode ser executado com segurança e o que depende de outro ambiente | Testes e resultados de baseline disponíveis, com limitações |
|
|
20
|
+
| Idioma e autonomia | Preferências conhecidas da equipe | Preservar configuração existente e perguntar apenas sobre conflitos |
|
|
21
|
+
|
|
22
|
+
Uma instalação pode ser feita antes dessas respostas. O agente pode registrar fatos e dúvidas
|
|
23
|
+
enquanto configura o projeto. Para implementar comportamento ainda ambíguo, precisa resolver a decisão
|
|
24
|
+
material; não precisa perguntar sobre fatos já claros no repositório nem preencher detalhes especulativos.
|
|
25
|
+
|
|
26
|
+
Em projeto existente, o setup preserva código e documentos e apresenta um resumo do entendimento.
|
|
27
|
+
Não autoriza refatorar, trocar arquitetura ou corrigir problemas históricos por conta própria.
|
|
28
|
+
Em projeto novo, uma descrição clara pode ser suficiente para começar; o PRD formal é opcional.
|
|
29
|
+
|
|
30
|
+
## PRD, SD, ADR e DS têm funções diferentes
|
|
31
|
+
|
|
32
|
+
| Documento | Pergunta principal | Conteúdo | Uso |
|
|
33
|
+
|---|---|---|---|
|
|
34
|
+
| PRD — Product Requirements Document | O que construir, para quem e com qual resultado? | Objetivos, escopo, regras, restrições e exemplos de aceitação | Direção do produto e fonte para mudanças |
|
|
35
|
+
| SD — System Design | Como a solução se organiza e se comunica? | Componentes, contratos, dados, integrações, segurança e operação | Mudanças arquiteturais ou entre componentes |
|
|
36
|
+
| ADR — Architecture Decision Record | Por que esta decisão foi tomada? | Contexto, alternativas/compromissos, escolha, consequências e estado | Um registro por decisão relevante |
|
|
37
|
+
| DS — Design System | Como a interface deve se apresentar e se comportar? | Tokens, componentes, estados, acessibilidade e responsividade | Trabalho de interface quando aplicável |
|
|
38
|
+
| Roadmap | Quais resultados vêm primeiro? | Prioridades, dependências e entregas esperadas | Priorização, sem duplicar estado das tarefas |
|
|
39
|
+
|
|
40
|
+
Um ADR não substitui um system design. O design system não precisa existir num serviço sem interface.
|
|
41
|
+
Arquivos de API, modelo de dados, segurança, operação e estratégia de testes também podem ser usados.
|
|
42
|
+
Esses nomes são convenções úteis, não uma lista fechada dos documentos aceitos pelo framework.
|
|
43
|
+
|
|
44
|
+
## Os três arquivos da versão antiga
|
|
45
|
+
|
|
46
|
+
Na 1.3.3, o instalador perguntava se deveria criar docs/.
|
|
47
|
+
Quando a pasta ainda não existia, criava prd.md, roadmap.md e architecture.md.
|
|
48
|
+
Não criava automaticamente uma tríade PRD/ADR/SD.
|
|
49
|
+
|
|
50
|
+
A interface 2.x oferece essa conveniência de maneira explícita e opcional:
|
|
51
|
+
|
|
52
|
+
~~~sh
|
|
53
|
+
sdd init --docs
|
|
54
|
+
~~~
|
|
55
|
+
|
|
56
|
+
Sem --docs, o setup não cria documentos de produto. Para escolher outros modelos depois:
|
|
57
|
+
|
|
58
|
+
~~~sh
|
|
59
|
+
sdd docs --types prd,sd,ds,adr,roadmap --dry-run
|
|
60
|
+
sdd docs --types prd,sd,ds,adr,roadmap
|
|
61
|
+
~~~
|
|
62
|
+
|
|
63
|
+
| Preset | Caminho |
|
|
64
|
+
|---|---|
|
|
65
|
+
| prd | docs/prd.md |
|
|
66
|
+
| roadmap | docs/roadmap.md |
|
|
67
|
+
| sd | docs/architecture.md |
|
|
68
|
+
| ds | docs/design-system.md |
|
|
69
|
+
| adr | docs/adr/README.md e docs/adr/_template.md |
|
|
70
|
+
|
|
71
|
+
O comando também cria docs/README.md quando ausente.
|
|
72
|
+
Sem --types, sdd docs usa os três presets originais: prd,roadmap,sd.
|
|
73
|
+
Pode selecionar apenas um, como sdd docs --types ds.
|
|
74
|
+
O dry-run não escreve arquivos. Documentos existentes são preservados, inclusive quando já contêm conteúdo personalizado.
|
|
75
|
+
Os arquivos são rascunhos para o agente/equipe revisar e preencher; não representam pesquisa ou decisões executadas.
|
|
76
|
+
O template ADR é proposed. Um registro real só deve ser selecionado como decisão active depois da escolha efetiva.
|
|
77
|
+
|
|
78
|
+
Use documentation.language: pt-BR em agents/config.yaml antes de gerar para receber os modelos em português.
|
|
79
|
+
auto usa os textos iniciais em inglês até o setup registrar a língua da equipe e preencher os documentos.
|
|
80
|
+
Chaves e estados técnicos permanecem estáveis; texto do projeto usa UTF-8 e acentos.
|
|
81
|
+
|
|
82
|
+
## Uma fonte por assunto
|
|
83
|
+
|
|
84
|
+
Preserve o local das fontes existentes. Se ADRs já ficam em agents/decisions/, não copie as mesmas
|
|
85
|
+
decisões para docs/adr/. Use um índice ou referência. Para decisões novas, escolha um local canônico.
|
|
86
|
+
Os presets não impedem outros caminhos; não existem nomes obrigatórios para documentos fornecidos pelo usuário.
|
|
87
|
+
|
|
88
|
+
Mapeie caminhos e responsabilidades em agents/PROJECT.md, sem copiar o conteúdo inteiro.
|
|
89
|
+
Regras essenciais do projeto pertencem a POLICIES.md; procedimentos reutilizáveis a skills;
|
|
90
|
+
conhecimento de comportamento vigente a current/. Esses papéis podem apontar para documentos já existentes.
|
|
91
|
+
|
|
92
|
+
Cada mudança seleciona somente as fontes necessárias. Exemplo:
|
|
93
|
+
|
|
94
|
+
~~~yaml
|
|
95
|
+
sources:
|
|
96
|
+
- path: docs/prd.md
|
|
97
|
+
section: Exportação de dados
|
|
98
|
+
context:
|
|
99
|
+
- path: docs/design-system.md
|
|
100
|
+
section: Estados e interações
|
|
101
|
+
decisions:
|
|
102
|
+
- docs/adr/0001-formato-exportacao.md
|
|
103
|
+
~~~
|
|
104
|
+
|
|
105
|
+
decisions exige os metadados de decisão do sdd-flow, incluindo kind: decision e status: active.
|
|
106
|
+
Um ADR antigo sem esses metadados pode ser consultado por context/sources sem conversão em massa.
|
|
107
|
+
Preserve sua origem e selecione sua pertinência; não invente uma aprovação ou razão histórica.
|
|
108
|
+
|
|
109
|
+
Para PDFs/imagens, use os leitores do harness. O CLI compõe texto Markdown/UTF-8, não interpreta
|
|
110
|
+
semanticamente um PDF ou um arquivo de design. Quando útil, mantenha um trecho revisado com proveniência
|
|
111
|
+
e o original preservado. Links externos podem ser consultados com as ferramentas disponíveis, sem exigir um harness específico.
|
|
112
|
+
|
|
113
|
+
## Documentação do framework e documentação da aplicação
|
|
114
|
+
|
|
115
|
+
A pasta docs/ do repositório sdd-flow explica como o framework funciona.
|
|
116
|
+
A pasta docs/ de uma aplicação consumidora contém referências daquele produto.
|
|
117
|
+
Instalar o workflow não copia todo o manual do framework para o contexto da aplicação.
|
|
118
|
+
|
|
119
|
+
A pasta não precisa ter todos os presets nem um número fixo de arquivos.
|
|
120
|
+
Gere o que for útil e mantenha referências curtas; não recrie o crescimento indiscriminado de documentos.
|