sdd-flow 1.3.2 → 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.
- package/CHANGELOG.md +33 -0
- package/CONTRIBUTING.md +25 -0
- package/LICENSE +21 -21
- package/README.md +113 -168
- package/README.pt-BR.md +100 -0
- package/bin/cli.js +162 -424
- package/docs/architecture.md +91 -0
- package/docs/distribution.md +64 -0
- package/docs/formats.md +212 -0
- package/docs/local-testing.pt-BR.md +195 -0
- package/docs/methodology.pt-BR.md +133 -0
- package/docs/migration.md +75 -0
- package/docs/quality-gates.pt-BR.md +160 -0
- package/docs/quality.md +56 -0
- package/docs/releases.pt-BR.md +186 -0
- package/docs/setup-documents.pt-BR.md +120 -0
- package/docs/usage.pt-BR.md +305 -0
- package/docs/validation.md +95 -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 -49
- package/templates/QUICKSTART.md +16 -70
- package/templates/agents/AGENTS.md +54 -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 +22 -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 +31 -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/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.
|
package/CONTRIBUTING.md
ADDED
|
@@ -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
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
##
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
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.
|
package/README.pt-BR.md
ADDED
|
@@ -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.
|