sdd-flow 1.3.3 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (70) hide show
  1. package/CHANGELOG.md +33 -0
  2. package/CONTRIBUTING.md +25 -0
  3. package/LICENSE +21 -21
  4. package/README.md +113 -168
  5. package/README.pt-BR.md +100 -0
  6. package/bin/cli.js +162 -424
  7. package/docs/architecture.md +91 -0
  8. package/docs/distribution.md +64 -0
  9. package/docs/formats.md +212 -0
  10. package/docs/local-testing.pt-BR.md +195 -0
  11. package/docs/methodology.pt-BR.md +133 -0
  12. package/docs/migration.md +75 -0
  13. package/docs/quality-gates.pt-BR.md +160 -0
  14. package/docs/quality.md +56 -0
  15. package/docs/releases.pt-BR.md +186 -0
  16. package/docs/setup-documents.pt-BR.md +120 -0
  17. package/docs/usage.pt-BR.md +305 -0
  18. package/docs/validation.md +95 -0
  19. package/lib/adapters.js +115 -0
  20. package/lib/check.js +221 -0
  21. package/lib/context.js +117 -0
  22. package/lib/documents.js +71 -0
  23. package/lib/handoff.js +81 -0
  24. package/lib/history.js +16 -0
  25. package/lib/install.js +181 -0
  26. package/lib/io.js +119 -0
  27. package/lib/legacy-hashes.json +31 -0
  28. package/lib/markdown.js +71 -0
  29. package/lib/project.js +200 -0
  30. package/lib/quality.js +24 -0
  31. package/lib/revisions.js +79 -0
  32. package/lib/verification.js +267 -0
  33. package/package.json +55 -32
  34. package/templates/AGENTS.md +12 -50
  35. package/templates/QUICKSTART.md +16 -70
  36. package/templates/agents/AGENTS.md +54 -92
  37. package/templates/agents/DECISIONS.md +5 -21
  38. package/templates/agents/POLICIES.md +14 -0
  39. package/templates/agents/PROJECT.md +35 -145
  40. package/templates/agents/QUALITY.md +19 -0
  41. package/templates/agents/RULES.md +22 -132
  42. package/templates/agents/SETUP.md +38 -224
  43. package/templates/agents/config.yaml +13 -0
  44. package/templates/agents/current/_template.md +19 -0
  45. package/templates/agents/decisions/_template.md +22 -0
  46. package/templates/agents/prompts/conventional-commit.md +11 -51
  47. package/templates/agents/prompts/intake.md +23 -0
  48. package/templates/agents/prompts/pr-template.md +12 -21
  49. package/templates/agents/prompts/quality.md +57 -0
  50. package/templates/agents/prompts/rpi-close.md +23 -0
  51. package/templates/agents/prompts/rpi-implement.md +31 -68
  52. package/templates/agents/prompts/rpi-plan.md +87 -117
  53. package/templates/agents/prompts/rpi-research.md +21 -67
  54. package/templates/agents/prompts/rpi-validate.md +40 -103
  55. package/templates/agents/prompts/skill-call.md +11 -29
  56. package/templates/agents/prompts/task-create.md +13 -42
  57. package/templates/agents/skills/_template/SKILL.md +11 -37
  58. package/templates/agents/harness/claude-code/.hooks/guard-delete.sh +0 -22
  59. package/templates/agents/harness/claude-code/.hooks/guard-deps.sh +0 -25
  60. package/templates/agents/harness/claude-code/.hooks/guard-git.sh +0 -24
  61. package/templates/agents/harness/claude-code/commands/sdd-implement.md +0 -3
  62. package/templates/agents/harness/claude-code/commands/sdd-plan.md +0 -3
  63. package/templates/agents/harness/claude-code/commands/sdd-research.md +0 -3
  64. package/templates/agents/harness/claude-code/commands/sdd-validate.md +0 -3
  65. package/templates/agents/harness/claude-code/settings.json +0 -34
  66. package/templates/agents/harness/opencode/commands/sdd-implement.md +0 -3
  67. package/templates/agents/harness/opencode/commands/sdd-plan.md +0 -3
  68. package/templates/agents/harness/opencode/commands/sdd-research.md +0 -3
  69. package/templates/agents/harness/opencode/commands/sdd-validate.md +0 -3
  70. package/templates/agents/harness/opencode/opencode.json +0 -18
package/CHANGELOG.md ADDED
@@ -0,0 +1,33 @@
1
+ # Changelog
2
+
3
+ ## 2.0.0 — 2026-11-20
4
+
5
+ Breaking: Node.js 22+, schema 2 artifacts, canonical YAML task state and version-bound scope/evidence.
6
+
7
+ - Replace fixed-line skill scanning with real YAML metadata and a discovery catalog.
8
+ - Add light/standard/rigorous modes and configurable step/batch autonomy.
9
+ - Add context, check, approve, evidence, verify, close, reopen, cancel, status, doctor and migration commands.
10
+ - Preserve existing entry-point content and customized files; add dry-run, ownership tracking and backups.
11
+ - Support manual/inspection evidence, partial verification and stale-input detection.
12
+ - Consolidate current knowledge before archival; reserve IDs beyond 999 and across archives.
13
+ - Install active Claude Code/OpenCode entry points and export versioned knowledge bundles.
14
+ - Retire distributed regex/TTY shell hooks; preserve old project settings for explicit migration review.
15
+ - Add automated regression tests, package checks and CI.
16
+ - Add body-free context inspection, section-scoped requirement sources and broad-request intake guidance.
17
+ - Preserve mandatory project policies, approved scope snapshots, revision impact and individual run receipts.
18
+ - Prepare manual OIDC npm publishing with next-first distribution, release identity checks and usage/release guides.
19
+ - Clarify the methodology's harness-independent scope and optional session boundaries, without adding an orchestrator.
20
+ - Carry a configurable project documentation language in context, preserve UTF-8/diacritics and seed Portuguese artifacts.
21
+ - Preserve completed setup on reinitialization with accurate maintenance guidance; add PowerShell testing/release instructions.
22
+ - Add required/advisory quality gates, opt-in external checks and project-owned quality policy.
23
+ - Record version-bound environment handoffs and safe user-test guides; allow implementation closure with explicit limitations.
24
+ - Preserve known observed failures, deferred verification tasks and later real verification without erasing history.
25
+ - Strengthen optional BDD/TDD guidance while keeping detailed quality procedures outside default implementation context.
26
+ - Make PRD/ADR/design inputs optional, strengthen existing-project baseline adoption and scoped consumer-regression analysis.
27
+ - Make the offline installed-package smoke test independent of warmed npm registry metadata caches.
28
+ - Restore opt-in legacy reference drafts with init --docs and add selected PRD, system design, design system, ADR and roadmap presets.
29
+ - Preserve existing reference files, preflight document collisions and distinguish proposed ADR templates from actual active decisions.
30
+
31
+ ## 1.3.3
32
+
33
+ Previous public baseline, analyzed at commit d84c62d51d9c566b0f3e8a6279418220e0fc6e8f.
@@ -0,0 +1,25 @@
1
+ # Contributing
2
+
3
+ ## Development
4
+
5
+ ~~~sh
6
+ git clone https://github.com/moisesuailab/sdd-flow.git
7
+ cd sdd-flow
8
+ npm ci
9
+ npm test
10
+ npm run check
11
+ ~~~
12
+
13
+ Use Node.js 22+. The CLI uses CommonJS and the maintained yaml parser.
14
+ Runtime modules live in lib/, the entry point in bin/, canonical knowledge in templates/agents/,
15
+ and behavior/integration tests in test/. This repository owns both the CLI and templates.
16
+
17
+ ## Changes
18
+
19
+ Describe the concrete problem and resulting behavior. Keep procedures concise and avoid
20
+ duplicating schema contracts across utility prompts. Add meaningful regression tests for
21
+ lifecycle, preservation, verification or compatibility changes.
22
+ Run the package smoke test and check that npm includes all runtime files.
23
+
24
+ Do not edit personal/global tool settings when testing adapters.
25
+ Use temporary projects. Do not publish npm or marketplace artifacts as part of tests.
package/LICENSE CHANGED
@@ -1,21 +1,21 @@
1
- MIT License
2
-
3
- Copyright (c) 2026 moisesuailab
4
-
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
11
-
12
- The above copyright notice and this permission notice shall be included in all
13
- copies or substantial portions of the Software.
14
-
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
- SOFTWARE.
1
+ MIT License
2
+
3
+ Copyright (c) 2026 moisesuailab
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,168 +1,113 @@
1
- # sdd-flow
2
-
3
- > A spec-driven workflow for AI-assisted development — installed in seconds, works with any agent.
4
-
5
- ```bash
6
- npm install -g sdd-flow
7
- sdd init
8
- ```
9
-
10
- ---
11
-
12
- ## Why sdd-flow exists
13
-
14
- AI agents drift. A session that starts well ends with the agent ignoring the spec, inventing APIs, and refactoring things you didn't ask it to touch. The usual fix — better prompts, more context — doesn't scale.
15
-
16
- **sdd-flow takes a different approach: phase isolation.**
17
-
18
- Every feature goes through four phases. Each phase runs in its own agent session and receives only the artifact from the previous phase — not the full conversation history. Context stays lean. The agent reads the spec fresh every session and can't drift from what it hasn't accumulated.
19
-
20
- This is a workflow for developers who want to stay in control of what gets built and why.
21
-
22
- ---
23
-
24
- ## The RPIV Cycle
25
-
26
- ```
27
- Requirements
28
- │
29
- ▼
30
- ┌────────────┐ new session ┌────────────┐ new session ┌─────────────┐ new session ┌────────────┐
31
- │ RESEARCH │ ────────────▶ │ PLAN │ ────────────▶ │ IMPLEMENT │ ────────────▶ │ VALIDATE │
32
- │ │ │ │ │ │ │ │
33
- │ RESEARCH │ │ SPEC.md │ │ Code │ │ Verified │
34
- │ .md │ │ TASK.md │ │ TASK.md ✓ │ │ PROGRESS │
35
- │ │ │ TEST.md │ │ (one task, │ │ .md │
36
- │ │ │ PROGRESS │ │ then stop) │ │ │
37
- └────────────┘ └────────────┘ └─────────────┘ └────────────┘
38
- ```
39
-
40
- Each arrow is a phase boundary. The agent starts fresh. Only the artifact passes through.
41
-
42
- | Phase | Input | Output |
43
- |-------|-------|--------|
44
- | 🔍 **Research** | Your requirements | `RESEARCH.md` |
45
- | 📐 **Plan** | `RESEARCH.md` | `SPEC.md` + `TASK.md` + `TEST.md` |
46
- | 🔨 **Implement** | `SPEC.md` + `TASK.md` | Code + updated `TASK.md` |
47
- | ✅ **Validate** | `TEST.md` + codebase | `VALIDATION.md` |
48
-
49
- > The agent stops after each task in the Implement phase and waits for your review. One task, one diff, one decision at a time.
50
-
51
- ---
52
-
53
- ## Quick Start
54
-
55
- ```bash
56
- # Install
57
- npm install -g sdd-flow
58
-
59
- # Set up in your project
60
- cd your-project
61
- sdd init
62
-
63
- # Create your first feature spec
64
- sdd new user-auth # creates agents/specs/001-user-auth/
65
- ```
66
-
67
- Open a new agent session and say:
68
-
69
- ```
70
- Read and follow agents/SETUP.md
71
- ```
72
-
73
- The agent scans your project (or reads your PRD) and generates `PROJECT.md`, `DECISIONS.md`, and a `skills/` directory tailored to your stack. Review the files, then delete `agents/SETUP.md`. You're ready.
74
-
75
- ---
76
-
77
- ## Running a Feature
78
-
79
- ### Without harness — any editor
80
-
81
- ```
82
- # Session 1 — Research
83
- "Read and follow agents/prompts/rpi-research.md"
84
-
85
- # Session 2 — Plan
86
- "Read and follow agents/prompts/rpi-plan.md. Spec at agents/specs/001-user-auth/"
87
-
88
- # Session 3 — Implement
89
- "Read and follow agents/prompts/rpi-implement.md. Spec at agents/specs/001-user-auth/"
90
-
91
- # Session 4 — Validate
92
- "Read and follow agents/prompts/rpi-validate.md. Spec at agents/specs/001-user-auth/"
93
- ```
94
-
95
- ### With harness — Claude Code / OpenCode
96
-
97
- ```bash
98
- sdd harness # installs slash commands
99
- ```
100
-
101
- ```
102
- /sdd-research 001-user-auth
103
- /sdd-plan 001-user-auth
104
- /sdd-implement 001-user-auth
105
- /sdd-validate 001-user-auth
106
- ```
107
-
108
- ---
109
-
110
- ## Commands
111
-
112
- ```bash
113
- sdd init # install the workflow into the current project
114
- sdd new <name> # create a numbered spec folder (001-, 002-, ...)
115
- sdd harness # install, switch, or remove slash commands
116
- sdd update # update prompts and rules — never touches your specs or decisions
117
- sdd --version
118
- ```
119
-
120
- ---
121
-
122
- ## What gets installed
123
-
124
- ```
125
- agents/
126
- ├── AGENTS.md ← agent role and SDD rules (read every session)
127
- ├── RULES.md ← behavioral constraints (no rogue git, no scope creep)
128
- ├── PROJECT.md ← your stack and conventions (auto-generated on setup)
129
- ├── DECISIONS.md ← append-only architectural decisions log
130
- ├── SETUP.md ← first-run only (delete after setup)
131
- ├── prompts/ ← one file per phase + utility prompts
132
- ├── skills/ ← capability files auto-generated for your stack
133
- └── specs/
134
- └── 001-user-auth/
135
- ├── RESEARCH.md
136
- ├── SPEC.md
137
- ├── TASK.md
138
- ├── PROGRESS.md
139
- └── TEST.md
140
- ```
141
-
142
- > `sdd update` only touches `AGENTS.md`, `RULES.md`, and `prompts/`.
143
- > Your specs, decisions, and skills are never modified.
144
-
145
- ---
146
-
147
- ## Works with any stack
148
-
149
- sdd-flow operates at the spec level, not the code level. JavaScript, TypeScript, Python, Java, Go, PHP — the agent adapts to your stack during setup. No framework assumptions, no extra API keys, no additional costs beyond what you already use.
150
-
151
- ---
152
-
153
- ## Compatible editors
154
-
155
- Claude Code · OpenCode · Cursor · Windsurf · Codex CLI · any IDE with filesystem access
156
-
157
- ---
158
-
159
- ## Workflow template
160
-
161
- The prompts and rules installed by `sdd-flow` are maintained at:
162
- [github.com/moisesuailab/spec-driven-workflow](https://github.com/moisesuailab/spec-driven-workflow)
163
-
164
- ---
165
-
166
- ## License
167
-
168
- MIT
1
+ # sdd-flow
2
+
3
+ A portable development methodology for AI-assisted software work. Organize intent, load relevant
4
+ task context and retain traceable execution. Harness orchestration is outside the core's scope.
5
+
6
+ This checkout targets **2.0.0**. It is a breaking evolution from 1.x; publishing this source is a separate release action.
7
+ Requires Node.js 22 or newer.
8
+
9
+ Portuguese guides: [methodology](docs/methodology.pt-BR.md), [local testing](docs/local-testing.pt-BR.md),
10
+ [usage](docs/usage.pt-BR.md) and [GitHub/npm release](docs/releases.pt-BR.md).
11
+
12
+ ## Try this checkout
13
+
14
+ ~~~sh
15
+ npm ci
16
+ npm link
17
+ cd /path/to/your-project
18
+ sdd init --harness claude-code
19
+ # Alternatively: sdd init --harness opencode
20
+ ~~~
21
+
22
+ Complete agents/SETUP.md and the short project map. Configure actual checks, then run sdd doctor.
23
+ For projects already using 1.x, read [migration](docs/migration.md) first.
24
+
25
+ ## A change from plan to evidence
26
+
27
+ ~~~sh
28
+ sdd new export-csv --mode standard
29
+ sdd context 001-export-csv --phase plan
30
+ # Author SPEC.md and TASK.md using the canonical formats.
31
+ sdd check 001-export-csv
32
+ # After the user authorizes this exact scope:
33
+ sdd approve 001-export-csv --by "Moisés"
34
+ sdd context 001-export-csv --phase implement --task T01
35
+ # Implement and verify the task, then set its canonical status to done.
36
+ sdd verify 001-export-csv --scope partial
37
+ # Consolidate lasting capability contracts before final verification.
38
+ sdd verify 001-export-csv
39
+ sdd close 001-export-csv --by "Moisés" --note "Local correction; no lasting contract changed" --archive
40
+ ~~~
41
+
42
+ The approval command records authorization; it does not prove who typed it or grant runtime permissions.
43
+ Agents must use actual authorization already given by the user and must not fabricate it.
44
+
45
+ ## What changes in 2.x
46
+
47
+ - **Short entry point:** a managed block preserves existing root instructions.
48
+ - **Structured metadata:** real YAML parsing, schema versions, stable IDs and explicit references.
49
+ - **Bounded context:** select the phase/task, current capabilities, active decisions and relevant skills.
50
+ Overflow fails with file sizes; documents are never silently truncated.
51
+ - **One task state:** TASK.md front matter is canonical. STATE.md is an optional short resumption note.
52
+ - **Adaptive rigor:** light, standard and rigorous modes; step or batch autonomy.
53
+ - **Executable checks:** approvals bind to scope; receipts bind to source files, selected contracts and configuration.
54
+ - **Manual evidence:** manual and inspection cases can pass when observed and recorded for current inputs.
55
+ - **Consolidation:** close only with current full verification and an explicit current-knowledge update or explanation.
56
+ - **Safe maintenance:** dry-run, ownership checks, backups, legacy preservation and active adapter entry points.
57
+ - **Portable distribution:** export Agent Skills bundles, a Claude Code plugin directory, or an OpenCode skill layout.
58
+
59
+ ## Commands
60
+
61
+ | Command | Purpose |
62
+ |---|---|
63
+ | init | Install missing project files and preserve project-owned configuration |
64
+ | docs --types prd,sd,ds,adr,roadmap | Create only selected missing reference drafts; --dry-run previews and existing documents are preserved |
65
+ | new NAME | Reserve an ID and create a change in the chosen mode |
66
+ | context ID | Compose the bounded packet; --inspect diagnoses size without emitting bodies; headings are selected in the manifest |
67
+ | skills list / show NAME | Discover metadata or read a selected body |
68
+ | check ID | Validate structure, references, task dependencies and phase gates |
69
+ | approve ID --by NAME | Record actual authorization for the current normative scope |
70
+ | revise ID --by NAME --reason TEXT | Preserve revision history, reopen impacted work and invalidate the prior scope approval |
71
+ | evidence ID | Create a template bound to current inputs for manual/inspection cases |
72
+ | handoff ID | Prepare version-bound external limitations and safe user verification instructions |
73
+ | verify ID | Run local checks; --handoff records limitations; --run-external opts into authorized external commands |
74
+ | close ID --by NAME | Require current full verification and consolidation; optionally --archive |
75
+ | reopen / cancel ID | Record explicit lifecycle decisions without deleting historical IDs |
76
+ | status / doctor | Inspect active/archive changes or diagnose project setup |
77
+ | update --dry-run | Preview installation changes; customized files are preserved unless explicitly replaced |
78
+ | migrate ID --dry-run | Preview conservative conversion of legacy artifacts |
79
+ | harness NAME | Install active native command/skill wrappers; --remove removes only unmodified owned files |
80
+ | export FORMAT --out DIR | Build a new directory for claude-code, opencode or agent-skills distribution |
81
+
82
+ All commands support --json. Exit codes: 0 completed (passed or limited), 1 invalid/failing, 2 partial verification.
83
+ Limited closes implementation with pending external verification; it never claims those tests passed or authorizes deployment.
84
+ Required checks block on failure; advisory checks remain visible warnings. QUALITY.md is loaded only for planning/review.
85
+ With --json, success and error objects use stdout; runtime/environment diagnostics remain on stderr.
86
+ CLI and documentation use English; project code, UI and conversation languages are configured by the project/user.
87
+
88
+ ## Documentation
89
+
90
+ - [Português](README.pt-BR.md)
91
+ - [Quality gates and missing environments (Português)](docs/quality-gates.pt-BR.md)
92
+ - [Usage scenarios and project-specific policies (Português)](docs/usage.pt-BR.md)
93
+ - [Updating the existing npm package (Português)](docs/releases.pt-BR.md)
94
+ - [Formats and a complete example](docs/formats.md)
95
+ - [Context and lifecycle design](docs/architecture.md)
96
+ - [Upgrading existing projects](docs/migration.md)
97
+ - [Adapters and distribution](docs/distribution.md)
98
+ - [Quality checks and evaluation](docs/quality.md)
99
+ - [Observed implementation validation](docs/validation.md)
100
+ - [Contributing](CONTRIBUTING.md)
101
+ - [Changelog](CHANGELOG.md)
102
+
103
+ ## Limits
104
+
105
+ The CLI validates declared relationships and records actual executions. It cannot prove that a passing test
106
+ semantically covers every requirement, authenticate an approval author, or sandbox a configured command.
107
+ Review assertions and use your tool's native permissions plus isolated test environments.
108
+ Source fingerprints use project files outside agents/ and dependency internals plus explicitly selected
109
+ workflow contracts. Configure verification.exclude for generated artifacts; exclusions affect evidence validity.
110
+
111
+ ## License
112
+
113
+ MIT. Workflow knowledge and runtime integrations are maintained together in this repository.
@@ -0,0 +1,100 @@
1
+ # sdd-flow
2
+
3
+ Framework de processo para desenvolvimento assistido por IA, com contexto selecionado por tarefa,
4
+ rastreabilidade e verificação vinculada à versão testada.
5
+
6
+ Este checkout prepara a versão 2.0.0. A publicação no npm é uma ação de release separada.
7
+ O foco é metodológico: organização, contexto pertinente e rastreabilidade, sem criar um orquestrador.
8
+ Requer Node.js 22 ou superior. Para testar este código:
9
+
10
+ ~~~sh
11
+ npm ci
12
+ npm link
13
+ cd /caminho/do/projeto
14
+ sdd init --harness claude-code
15
+ ~~~
16
+
17
+ Também há adaptador para OpenCode: sdd harness opencode.
18
+ Complete agents/SETUP.md, configure os comandos reais em agents/config.yaml e execute sdd doctor.
19
+
20
+ ## Princípios
21
+
22
+ - Mantenha o AGENTS.md curto, com navegação para os documentos relevantes.
23
+ - Separe conhecimento vigente, mudança ativa e histórico.
24
+ - Descubra skills por name e description; carregue seu corpo quando necessário.
25
+ - Use tarefas por resultado verificável, podendo alterar vários arquivos.
26
+ - Escolha modo light, standard ou rigorous e autonomia step ou batch.
27
+ - Mantenha o estado das tarefas apenas no front matter de TASK.md.
28
+ - Aprove o escopo autorizado, sem exigir aprovações de arquivos de progresso vazios.
29
+ - Verifique com comandos reais e evidência de execução. Testes manuais podem passar.
30
+ - Diferencie checks obrigatórios e informativos; registre limitações externas sem exigir testes arriscados em produção.
31
+ - Consolide contratos vigentes antes da verificação final e do arquivamento.
32
+
33
+ ## Fluxo
34
+
35
+ ~~~sh
36
+ sdd new minha-mudanca --mode standard
37
+ sdd context 001-minha-mudanca --phase plan
38
+ # Preencha SPEC.md e TASK.md nos formatos documentados.
39
+ sdd check 001-minha-mudanca
40
+ # Somente após autorização real do usuário para esse escopo:
41
+ sdd approve 001-minha-mudanca --by "Moisés"
42
+ sdd context 001-minha-mudanca --phase implement --task T01
43
+ # Implemente, verifique e atualize a tarefa.
44
+ sdd verify 001-minha-mudanca --scope partial
45
+ # Consolide os documentos vigentes e conclua as tarefas.
46
+ sdd verify 001-minha-mudanca
47
+ sdd close 001-minha-mudanca --by "Moisés" --note "Sem alteração de contrato duradouro" --archive
48
+ ~~~
49
+
50
+ Para verificação manual/inspeção, sdd evidence ID cria um registro para os inputs atuais.
51
+ Execute o cenário, preencha resultado, executor, data e observações e use
52
+ sdd verify ID --evidence agents/specs/ID/EVIDENCE.json.
53
+ Se código ou contrato mudar, a evidência anterior fica obsoleta.
54
+
55
+ Sem ambiente adequado, sdd handoff ID prepara um registro de limitações para preencher.
56
+ sdd verify ID --handoff CAMINHO gera USER_TESTS.md e pode resultar em limited.
57
+ Isso permite encerrar a implementação com pendências explícitas, sem declarar teste externo aprovado.
58
+ Leia o [guia de qualidade e falta de ambiente](docs/quality-gates.pt-BR.md) para TDD/BDD, gates e o roteiro seguro ao usuário.
59
+
60
+ ## Front matter e contexto
61
+
62
+ Front matter é metadado estruturado, interpretado por um parser YAML real.
63
+ Skills usam name e description do formato Agent Skills. Contratos do workflow usam schema_version,
64
+ tipo de artefato e seus campos específicos. README e textos apenas humanos não precisam de metadados.
65
+
66
+ O comando context seleciona as referências declaradas em change.yaml, a fase e a tarefa.
67
+ Também permite seções por título exato. Não há extração de um número fixo de linhas.
68
+ Se o limite em bytes for excedido, o comando apresenta o problema sem truncar instruções.
69
+ O limite mede bytes, não tokens, e pode ser configurado.
70
+
71
+ ## Distribuição e manutenção
72
+
73
+ ~~~sh
74
+ sdd update --dry-run
75
+ sdd harness claude-code
76
+ sdd harness opencode
77
+ sdd export claude-code --out packages/claude-code
78
+ sdd export opencode --out packages/opencode
79
+ ~~~
80
+
81
+ Os adaptadores instalam comandos e uma skill nos diretórios ativos das ferramentas.
82
+ Não alteram permissões nativas nem removem configurações antigas silenciosamente.
83
+ A exportação prepara diretórios versionáveis; não publica nem instala plugins.
84
+
85
+ Consulte os [formatos](docs/formats.md), a [migração](docs/migration.md),
86
+ a [distribuição](docs/distribution.md) e os [critérios de qualidade](docs/quality.md).
87
+ A CLI valida estrutura e executa checks; revisão semântica e permissões continuam necessárias.
88
+
89
+ O [guia de uso](docs/usage.pt-BR.md) explica adoção em projetos existentes, início do zero,
90
+ excesso de contexto, regras particulares, skills e mudanças de escopo.
91
+ O [guia de publicação](docs/releases.pt-BR.md) distingue PR, merge, publicação npm e atualização dos consumidores.
92
+
93
+ Consulte a [metodologia e comparação das versões](docs/methodology.pt-BR.md) e o
94
+ [roteiro de testes locais](docs/local-testing.pt-BR.md), com exemplos PowerShell.
95
+ Configure documentation.language: pt-BR em agents/config.yaml para documentos do projeto em português.
96
+ Preserve UTF-8 e acentuação; chaves técnicas e IDs não devem ser traduzidos.
97
+
98
+ O [guia de perguntas do setup e documentos](docs/setup-documents.pt-BR.md) distingue PRD, ADR, system design e design system.
99
+ sdd init --docs restaura a criação opcional de prd.md, roadmap.md e architecture.md.
100
+ Para selecionar referências, use sdd docs --types prd,sd,ds,adr,roadmap. Documentos existentes são preservados.