sdd-flow 2.0.0 → 2.1.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 +47 -33
- package/README.md +430 -113
- package/README.pt-BR.md +414 -100
- package/bin/cli.js +209 -175
- package/docs/architecture.md +98 -91
- package/docs/formats.md +221 -212
- package/docs/local-testing.pt-BR.md +200 -195
- package/docs/methodology.pt-BR.md +6 -0
- package/docs/migration.md +82 -75
- package/docs/releases.pt-BR.md +108 -186
- package/docs/spec-management.pt-BR.md +169 -0
- package/docs/usage.pt-BR.md +315 -305
- package/docs/validation.md +109 -95
- package/lib/adapters.js +1 -1
- package/lib/catalog.js +162 -0
- package/lib/check.js +25 -9
- package/lib/context.js +139 -117
- package/lib/handoff.js +1 -0
- package/lib/install.js +13 -7
- package/lib/io.js +119 -119
- package/lib/management.js +210 -0
- package/lib/markdown.js +71 -71
- package/lib/project.js +191 -200
- package/lib/verification.js +7 -4
- package/package.json +55 -55
- package/templates/agents/AGENTS.md +66 -54
- package/templates/agents/RULES.md +4 -1
- package/templates/agents/SETUP.md +2 -1
- package/templates/agents/config.yaml +13 -13
- package/templates/agents/prompts/intake.md +23 -23
- package/templates/agents/prompts/rpi-close.md +3 -0
- package/templates/agents/prompts/rpi-implement.md +5 -1
- package/templates/agents/prompts/rpi-plan.md +3 -0
package/CHANGELOG.md
CHANGED
|
@@ -1,33 +1,47 @@
|
|
|
1
|
-
# Changelog
|
|
2
|
-
|
|
3
|
-
## 2.
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
-
|
|
8
|
-
- Add
|
|
9
|
-
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
-
|
|
14
|
-
-
|
|
15
|
-
- Add
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
-
|
|
22
|
-
- Add
|
|
23
|
-
-
|
|
24
|
-
- Preserve
|
|
25
|
-
-
|
|
26
|
-
-
|
|
27
|
-
-
|
|
28
|
-
-
|
|
29
|
-
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 2.1.0 — 2026-11-21
|
|
4
|
+
|
|
5
|
+
- Decouple stable spec identity from directory names and visual numbering; preserve existing schema 2 IDs.
|
|
6
|
+
- Add previewable rename/archive/restore/remove operations, recoverable trash and explicit permanent discard.
|
|
7
|
+
- Retain compact observed closure summaries and resolve moved structured references without rewriting prior evidence.
|
|
8
|
+
- Add optional historical links, localized missing-prerequisite diagnostics and inventory reconciliation; keep required acceptance honest.
|
|
9
|
+
- List active specs by default with status --all for archive/trash/retained metadata; isolate malformed unrelated manifests.
|
|
10
|
+
|
|
11
|
+
## 2.0.1 — 2026-11-20
|
|
12
|
+
|
|
13
|
+
- Default new projects to step; follow explicit multi-task/all-task authorization as a bounded batch without resetting existing project preferences.
|
|
14
|
+
- Redesign README and update usage, migration, format and validation documentation accordingly.
|
|
15
|
+
- Add default engineering rules: KISS/Clean Code/YAGNI/DRY/SOLID guidance and no redundant comments or docblocks.
|
|
16
|
+
|
|
17
|
+
## 2.0.0 — 2026-11-20
|
|
18
|
+
|
|
19
|
+
Breaking: Node.js 22+, schema 2 artifacts, canonical YAML task state and version-bound scope/evidence.
|
|
20
|
+
|
|
21
|
+
- Replace fixed-line skill scanning with real YAML metadata and a discovery catalog.
|
|
22
|
+
- Add light/standard/rigorous modes and configurable step/batch autonomy.
|
|
23
|
+
- Add context, check, approve, evidence, verify, close, reopen, cancel, status, doctor and migration commands.
|
|
24
|
+
- Preserve existing entry-point content and customized files; add dry-run, ownership tracking and backups.
|
|
25
|
+
- Support manual/inspection evidence, partial verification and stale-input detection.
|
|
26
|
+
- Consolidate current knowledge before archival; reserve IDs beyond 999 and across archives.
|
|
27
|
+
- Install active Claude Code/OpenCode entry points and export versioned knowledge bundles.
|
|
28
|
+
- Retire distributed regex/TTY shell hooks; preserve old project settings for explicit migration review.
|
|
29
|
+
- Add automated regression tests, package checks and CI.
|
|
30
|
+
- Add body-free context inspection, section-scoped requirement sources and broad-request intake guidance.
|
|
31
|
+
- Preserve mandatory project policies, approved scope snapshots, revision impact and individual run receipts.
|
|
32
|
+
- Prepare manual OIDC npm publishing with next-first distribution, release identity checks and usage/release guides.
|
|
33
|
+
- Clarify the methodology's harness-independent scope and optional session boundaries, without adding an orchestrator.
|
|
34
|
+
- Carry a configurable project documentation language in context, preserve UTF-8/diacritics and seed Portuguese artifacts.
|
|
35
|
+
- Preserve completed setup on reinitialization with accurate maintenance guidance; add PowerShell testing/release instructions.
|
|
36
|
+
- Add required/advisory quality gates, opt-in external checks and project-owned quality policy.
|
|
37
|
+
- Record version-bound environment handoffs and safe user-test guides; allow implementation closure with explicit limitations.
|
|
38
|
+
- Preserve known observed failures, deferred verification tasks and later real verification without erasing history.
|
|
39
|
+
- Strengthen optional BDD/TDD guidance while keeping detailed quality procedures outside default implementation context.
|
|
40
|
+
- Make PRD/ADR/design inputs optional, strengthen existing-project baseline adoption and scoped consumer-regression analysis.
|
|
41
|
+
- Make the offline installed-package smoke test independent of warmed npm registry metadata caches.
|
|
42
|
+
- Restore opt-in legacy reference drafts with init --docs and add selected PRD, system design, design system, ADR and roadmap presets.
|
|
43
|
+
- Preserve existing reference files, preflight document collisions and distinguish proposed ADR templates from actual active decisions.
|
|
44
|
+
|
|
45
|
+
## 1.3.3
|
|
46
|
+
|
|
47
|
+
Previous public baseline, analyzed at commit d84c62d51d9c566b0f3e8a6279418220e0fc6e8f.
|
package/README.md
CHANGED
|
@@ -1,113 +1,430 @@
|
|
|
1
|
-
|
|
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
|
-
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
3
|
+
# sdd-flow
|
|
4
|
+
|
|
5
|
+
### A clear workflow for developing with AI.
|
|
6
|
+
|
|
7
|
+
Relevant context for the agent.<br>
|
|
8
|
+
Well-defined changes for you.<br>
|
|
9
|
+
A traceable history for the project.
|
|
10
|
+
|
|
11
|
+

|
|
12
|
+

|
|
13
|
+

|
|
14
|
+
|
|
15
|
+
[Português brasileiro](README.pt-BR.md) · [Get started](#get-started-in-3-steps) · [Workflow](#how-it-works) · [Context](#how-context-stays-focused) · [Documentation](#documentation)
|
|
16
|
+
|
|
17
|
+
</div>
|
|
18
|
+
|
|
19
|
+
---
|
|
20
|
+
|
|
21
|
+
**sdd-flow organizes AI-assisted development into cohesive changes that you can understand, implement and verify.**
|
|
22
|
+
|
|
23
|
+
Describe what you need. The agent consults relevant sources, prepares a spec, implements the authorized scope and records the results. Project knowledge and progress remain in the repository for the next session.
|
|
24
|
+
|
|
25
|
+
| Organization | Context | Traceability |
|
|
26
|
+
|---|---|---|
|
|
27
|
+
| One spec per cohesive change | Sources selected for the phase and task | Connected requirements, tasks, decisions and verification |
|
|
28
|
+
|
|
29
|
+
**Your daily focus stays on the spec.** The agent and CLI maintain supporting records. Configuration, skills and general documents are consulted when relevant.
|
|
30
|
+
|
|
31
|
+
## How it works
|
|
32
|
+
|
|
33
|
+
```mermaid
|
|
34
|
+
flowchart TD
|
|
35
|
+
A["Describe the change"] --> B["Agent researches and plans"]
|
|
36
|
+
B --> C["Review the scope"]
|
|
37
|
+
C --> D["Agent implements and verifies"]
|
|
38
|
+
D --> E{"Result"}
|
|
39
|
+
E -->|"Needs adjustment"| D
|
|
40
|
+
E -->|"Ready to close"| F["Consolidate and record the outcome"]
|
|
41
|
+
D -. "Requirement changed" .-> B
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
**Research → plan → implement → validate → close.** These are responsibilities, not mandatory separate conversations.
|
|
45
|
+
|
|
46
|
+
- **Before:** clarify the goal, define acceptance and consider affected consumers.
|
|
47
|
+
- **During:** execute cohesive tasks and check regressions.
|
|
48
|
+
- **After:** record observations and consolidate current knowledge.
|
|
49
|
+
|
|
50
|
+
Use the method for **new projects** or **existing applications**, with any application stack. Node.js 22+ is required for the CLI.
|
|
51
|
+
|
|
52
|
+
## Get started in 3 steps
|
|
53
|
+
|
|
54
|
+
> **This README describes 2.1.** Flexible spec management is new in this release. Confirm your CLI with `sdd --version`.
|
|
55
|
+
|
|
56
|
+
### 1. Install the CLI
|
|
57
|
+
|
|
58
|
+
With Node.js 22+:
|
|
59
|
+
|
|
60
|
+
```sh
|
|
61
|
+
npm install -g sdd-flow
|
|
62
|
+
sdd --version
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
<details>
|
|
66
|
+
<summary>Other options: run without installing, or from source</summary>
|
|
67
|
+
|
|
68
|
+
Run without a global install:
|
|
69
|
+
|
|
70
|
+
```sh
|
|
71
|
+
npx sdd-flow@latest --help
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
From the **sdd-flow source checkout** (for contributors):
|
|
75
|
+
|
|
76
|
+
```sh
|
|
77
|
+
npm ci
|
|
78
|
+
npm link
|
|
79
|
+
sdd --version
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
Installing the package provides the CLI. Project files are installed by running `sdd init` inside each application.
|
|
83
|
+
|
|
84
|
+
</details>
|
|
85
|
+
|
|
86
|
+
### 2. Initialize your project
|
|
87
|
+
|
|
88
|
+
```sh
|
|
89
|
+
cd /path/to/your-project
|
|
90
|
+
sdd init
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
Optional native entry points:
|
|
94
|
+
|
|
95
|
+
```sh
|
|
96
|
+
sdd harness claude-code
|
|
97
|
+
# Alternative: sdd harness opencode
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
For other environments, direct the agent to the project's `AGENTS.md`. The core uses files and commands; a native adapter is optional.
|
|
101
|
+
|
|
102
|
+
### 3. Keep using short prompts
|
|
103
|
+
|
|
104
|
+
For initial setup:
|
|
105
|
+
|
|
106
|
+
```text
|
|
107
|
+
Read and follow agents/SETUP.md to configure the workflow.
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
Then describe the change and select the phase:
|
|
111
|
+
|
|
112
|
+
| Phase | Prompt |
|
|
113
|
+
|---|---|
|
|
114
|
+
| Research | Read and follow agents/prompts/rpi-research.md. |
|
|
115
|
+
| Plan | Read and follow agents/prompts/rpi-plan.md. |
|
|
116
|
+
| Implement | Read and follow agents/prompts/rpi-implement.md. |
|
|
117
|
+
| Validate | Read and follow agents/prompts/rpi-validate.md. |
|
|
118
|
+
| Close | Read and follow agents/prompts/rpi-close.md. |
|
|
119
|
+
|
|
120
|
+
The procedures contain the workflow instructions. You do not need to repeat them in chat.
|
|
121
|
+
The request and active spec must be identifiable. If several changes exist or a new session lacks context,
|
|
122
|
+
provide the spec ID or let the agent clarify which one to use.
|
|
123
|
+
|
|
124
|
+
Setup is initial adoption, not a repeated step for every spec. Once complete, `SETUP.md` may be removed.
|
|
125
|
+
Project language and conventions belong in configuration and policies.
|
|
126
|
+
|
|
127
|
+
**Follow the spec, tasks and verification outcome.** The agent uses the CLI and maintains supporting records.
|
|
128
|
+
Phases may run in the same conversation.
|
|
129
|
+
|
|
130
|
+
For an existing application, setup records an observed baseline without refactoring the application
|
|
131
|
+
or inventing historical specs.
|
|
132
|
+
|
|
133
|
+
## What is added to your repository
|
|
134
|
+
|
|
135
|
+
| Files | Purpose |
|
|
136
|
+
|---|---|
|
|
137
|
+
| `AGENTS.md` and `QUICKSTART.md` | Entry point and getting started |
|
|
138
|
+
| `agents/PROJECT.md` | Short application map and source references |
|
|
139
|
+
| `agents/POLICIES.md` and `agents/QUALITY.md` | Project constraints and quality criteria |
|
|
140
|
+
| `agents/config.yaml` | Language, autonomy, rigor and actual check commands |
|
|
141
|
+
| `agents/RULES.md`, `agents/AGENTS.md` and `agents/prompts/` | Method and phase procedures |
|
|
142
|
+
| `agents/specs/` | Active changes |
|
|
143
|
+
| `agents/current/` and active decisions | Current knowledge |
|
|
144
|
+
| `agents/archive/` | Closed changes |
|
|
145
|
+
| `agents/skills/` | Reusable project procedures |
|
|
146
|
+
|
|
147
|
+
Installation includes templates and maintenance metadata. **It does not generate features or fictional specs.**
|
|
148
|
+
|
|
149
|
+
Each change uses only the applicable artifacts:
|
|
150
|
+
|
|
151
|
+
| Artifact | Role |
|
|
152
|
+
|---|---|
|
|
153
|
+
| `change.yaml` | Identity, references, dependencies and lifecycle |
|
|
154
|
+
| `SPEC.md` | Requirements and acceptance |
|
|
155
|
+
| `TASK.md` | Plan and canonical task state, when applicable |
|
|
156
|
+
| `RESEARCH.md` | Research when useful or required by the mode |
|
|
157
|
+
| Evidence and run records | What was checked, for which inputs, with which result |
|
|
158
|
+
|
|
159
|
+
The agent maintains these as work progresses. Research, evidence and history are not all created by `sdd new`.
|
|
160
|
+
|
|
161
|
+
## How context stays focused
|
|
162
|
+
|
|
163
|
+
**The repository stores knowledge. The agent receives a relevant selection for the current task.**
|
|
164
|
+
|
|
165
|
+
```mermaid
|
|
166
|
+
flowchart TD
|
|
167
|
+
A["Active spec and task"] --> D["Select context"]
|
|
168
|
+
B["Contracts, decisions and skills"] --> D
|
|
169
|
+
C["Relevant docs/ references"] --> D
|
|
170
|
+
D --> E{"Within budget?"}
|
|
171
|
+
E -->|"Yes"| F["Provide context to the agent"]
|
|
172
|
+
E -->|"No"| G["Review sources, sections and scope"]
|
|
173
|
+
G --> D
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
- A short entry point maps the project.
|
|
177
|
+
- Phase and task guide selection.
|
|
178
|
+
- Skills are discovered by name and description; selected bodies are loaded.
|
|
179
|
+
- Large references can be selected by heading.
|
|
180
|
+
- Full historical logs are not loaded automatically.
|
|
181
|
+
- `TASK.md` holds task state; `STATE.md` is an optional short resumption note.
|
|
182
|
+
|
|
183
|
+
```sh
|
|
184
|
+
sdd context 001-my-change --phase implement --task T01 --inspect
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
Inspection reports sizes without emitting document bodies. The default budget is **48,000 UTF-8 bytes**,
|
|
188
|
+
configurable. It is not a token count or the complete chat context window.
|
|
189
|
+
|
|
190
|
+
Generating an oversized packet reports the problem **without silently truncating content**.
|
|
191
|
+
The agent can select sections, review references or split independent deliverables.
|
|
192
|
+
|
|
193
|
+
Selection depends on maintained references. The CLI cannot infer every semantic dependency or control chat history.
|
|
194
|
+
|
|
195
|
+
## Keep references organized in docs/
|
|
196
|
+
|
|
197
|
+
PRDs, business rules, system design, ADRs, design systems, contracts and external materials can stay
|
|
198
|
+
in `docs/`, with or without subdirectories.
|
|
199
|
+
|
|
200
|
+
**Centralize sources; select what to read.** The agent consults relevant documents and preserves their origin.
|
|
201
|
+
|
|
202
|
+
Example in `change.yaml`:
|
|
203
|
+
|
|
204
|
+
```yaml
|
|
205
|
+
sources:
|
|
206
|
+
- path: docs/product/prd.md
|
|
207
|
+
section: Data export
|
|
208
|
+
context:
|
|
209
|
+
- path: docs/design/design-system.md
|
|
210
|
+
section: States and interactions
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
There is no mandatory document bundle. A clear description can be enough to start.
|
|
214
|
+
|
|
215
|
+
Optional reference drafts:
|
|
216
|
+
|
|
217
|
+
```sh
|
|
218
|
+
sdd docs --types prd,sd,ds,adr,roadmap --dry-run
|
|
219
|
+
sdd docs --types prd,sd,ds,adr,roadmap
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
Existing files are preserved. New files are drafts for review.
|
|
223
|
+
See [setup and reference documents (Português)](docs/setup-documents.pt-BR.md).
|
|
224
|
+
|
|
225
|
+
## Organize specs without restarting work
|
|
226
|
+
|
|
227
|
+
Folder names and visual numbers can change while the manifest ID stays stable.
|
|
228
|
+
Archive unfinished specs, restore them or remove obsolete content. Removal is recoverable by default;
|
|
229
|
+
permanent deletion is explicit.
|
|
230
|
+
|
|
231
|
+
Missing historical references warn. Unknown prerequisites need local review, without restarting
|
|
232
|
+
the consumer or inventing completion.
|
|
233
|
+
|
|
234
|
+
<details>
|
|
235
|
+
<summary>Rename, archive, restore and discard</summary>
|
|
236
|
+
|
|
237
|
+
```sh
|
|
238
|
+
sdd rename 015-export --name export-reports --number 3 --by "Reviewer" --reason "Organize" --dry-run
|
|
239
|
+
sdd archive 015-export --by "Reviewer" --reason "Remove from active work"
|
|
240
|
+
sdd restore 015-export --by "Reviewer" --reason "Resume"
|
|
241
|
+
sdd remove 015-export --by "Reviewer" --reason "Obsolete" --dry-run
|
|
242
|
+
sdd reconcile --dry-run
|
|
243
|
+
sdd status --all
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
Use actual IDs and review previews. Rename preserves ID 015-export even with folder 003-export-reports.
|
|
247
|
+
Reconcile updates observed inventory only; it does not rewrite requirements or manufacture evidence.
|
|
248
|
+
Current contracts remain available independently of historical spec folders.
|
|
249
|
+
See [spec management (Português)](docs/spec-management.pt-BR.md) for application, permanent discard and recovery.
|
|
250
|
+
|
|
251
|
+
</details>
|
|
252
|
+
|
|
253
|
+
## Choose proportional rigor
|
|
254
|
+
|
|
255
|
+
| Mode | Typical use |
|
|
256
|
+
|---|---|
|
|
257
|
+
| `light` | Small change; tasks and research may be omitted |
|
|
258
|
+
| `standard` | Bounded feature with verifiable tasks |
|
|
259
|
+
| `rigorous` | Sensitive or uncertain work with research and explicit approval |
|
|
260
|
+
|
|
261
|
+
New installations default to **step**: implement and verify one task, then stop for review.
|
|
262
|
+
Authorize named tasks or all tasks to continue as a bounded batch without repeated confirmations.
|
|
263
|
+
Plan approval alone does not override step. **Batch** can also be the project's standing preference;
|
|
264
|
+
updates preserve an existing choice. Each task is still checked and dependencies respected.
|
|
265
|
+
|
|
266
|
+
## Verify honestly, including unavailable environments
|
|
267
|
+
|
|
268
|
+
The CLI runs configured checks and records commands, results and inputs.
|
|
269
|
+
Approval binds to scope; verification binds to the inputs examined.
|
|
270
|
+
|
|
271
|
+
| Result | Meaning |
|
|
272
|
+
|---|---|
|
|
273
|
+
| `passed` | Full verification passed for current inputs |
|
|
274
|
+
| `limited` | Implementation complete with explicit external limitations and pending verification |
|
|
275
|
+
| `partial` | Conditions for final closure are not yet met |
|
|
276
|
+
| `failed` | Required failure observed or inputs changed during execution |
|
|
277
|
+
|
|
278
|
+
**Unavailable staging or production access need not block completed implementation.**
|
|
279
|
+
A reviewed handoff records limitations and can generate safe steps in `USER_TESTS.md`.
|
|
280
|
+
|
|
281
|
+
`limited` does not claim external tests passed or authorize deployment.
|
|
282
|
+
Omitting evidence cannot erase a known failure for the same inputs.
|
|
283
|
+
|
|
284
|
+
Required failures block passing verification; advisory issues remain warnings.
|
|
285
|
+
Use TDD, BDD examples and metrics as appropriate, without a mandatory tool or universal percentage.
|
|
286
|
+
|
|
287
|
+
See [quality gates and missing environments (Português)](docs/quality-gates.pt-BR.md).
|
|
288
|
+
|
|
289
|
+
## Portability and scope
|
|
290
|
+
|
|
291
|
+
| sdd-flow organizes | The harness provides |
|
|
292
|
+
|---|---|
|
|
293
|
+
| Method, specs, context and traceability | Models, tools and permissions |
|
|
294
|
+
| Sources and evidence | MCPs and service access |
|
|
295
|
+
| Knowledge entry points and exports | Compaction and optional delegation |
|
|
296
|
+
|
|
297
|
+
Use one conversation, separate sessions or native delegation. **No built-in orchestrator or multiagent requirement.**
|
|
298
|
+
|
|
299
|
+
Claude Code and OpenCode adapters provide commands and a workflow skill.
|
|
300
|
+
Exports prepare knowledge for distribution; they do not publish to marketplaces.
|
|
301
|
+
See [adapters and distribution](docs/distribution.md).
|
|
302
|
+
|
|
303
|
+
## For AI agents
|
|
304
|
+
|
|
305
|
+
1. Start with `AGENTS.md` and the project map.
|
|
306
|
+
2. Follow `SETUP.md` for initial adoption, then the current phase procedure.
|
|
307
|
+
3. Consult relevant sources instead of bulk-loading `docs/`.
|
|
308
|
+
4. Preserve IDs, current rules, observed architecture and existing work.
|
|
309
|
+
5. Review consumers and regressions before changing shared behavior.
|
|
310
|
+
6. Record actual authorization, observations and limitations.
|
|
311
|
+
7. Maintain canonical state and consolidate current knowledge before closure.
|
|
312
|
+
|
|
313
|
+
Metadata uses YAML rather than fixed line excerpts. Source documents are project data;
|
|
314
|
+
they do not replace user authorization.
|
|
315
|
+
|
|
316
|
+
<details>
|
|
317
|
+
<summary>Essential change commands</summary>
|
|
318
|
+
|
|
319
|
+
Use the actual ID and complete the plan between commands:
|
|
320
|
+
|
|
321
|
+
```sh
|
|
322
|
+
sdd new my-change --mode standard
|
|
323
|
+
sdd context 001-my-change --phase plan
|
|
324
|
+
# Define requirements, acceptance, tasks and references.
|
|
325
|
+
sdd check 001-my-change
|
|
326
|
+
|
|
327
|
+
# Record only authorization actually given:
|
|
328
|
+
sdd approve 001-my-change --by "Reviewer"
|
|
329
|
+
|
|
330
|
+
sdd context 001-my-change --phase implement --task T01
|
|
331
|
+
# Implement, check and update tasks.
|
|
332
|
+
# Consolidate current contracts before final verification.
|
|
333
|
+
sdd verify 001-my-change
|
|
334
|
+
sdd close 001-my-change --by "Reviewer" --archive
|
|
335
|
+
```
|
|
336
|
+
|
|
337
|
+
Closure requires consolidation of selected capabilities, or `--note` explaining why no lasting update is needed.
|
|
338
|
+
Manual evidence and external limitations use the corresponding verification arguments.
|
|
339
|
+
|
|
340
|
+
`sdd check` validates structure. `sdd verify` executes configured checks.
|
|
341
|
+
|
|
342
|
+
</details>
|
|
343
|
+
|
|
344
|
+
## Reinstall or upgrade without starting over
|
|
345
|
+
|
|
346
|
+
The 2.x installer distinguishes project-owned files from managed workflow files.
|
|
347
|
+
|
|
348
|
+
| Situation | Expected behavior |
|
|
349
|
+
|---|---|
|
|
350
|
+
| Repeat `init` on the same version | Preserve configuration and work; missing files may be restored |
|
|
351
|
+
| Customized core files | Report conflicts rather than silently overwrite |
|
|
352
|
+
| Install a newer CLI | Existing application files are not updated automatically |
|
|
353
|
+
| Run `update` with recognized, conflict-free core files | Refresh managed files and preserve project-owned files |
|
|
354
|
+
| Adopt from 1.x | Review core/artifact migration; old evidence does not become fresh approval |
|
|
355
|
+
|
|
356
|
+
Existing `PROJECT.md`, `POLICIES.md`, `QUALITY.md`, `config.yaml` and `DECISIONS.md` are preserved.
|
|
357
|
+
The installer does not delete project specs, custom skills, `docs/` sources or history.
|
|
358
|
+
Normal maintenance does not recreate a completed, removed setup guide.
|
|
359
|
+
|
|
360
|
+
Preserve your current work in a commit or backup. Install the desired CLI version from npm
|
|
361
|
+
(or from the source checkout when testing). Inside the application:
|
|
362
|
+
|
|
363
|
+
```sh
|
|
364
|
+
sdd --version
|
|
365
|
+
sdd update --dry-run
|
|
366
|
+
# Review the plan and resolve conflicts before applying.
|
|
367
|
+
sdd update
|
|
368
|
+
sdd doctor
|
|
369
|
+
```
|
|
370
|
+
|
|
371
|
+
Refresh native entry points with `sdd harness claude-code` or `sdd harness opencode` when used.
|
|
372
|
+
Native settings are not overwritten; old permissions/hooks require their own review.
|
|
373
|
+
|
|
374
|
+
<details>
|
|
375
|
+
<summary>Migrating from 1.x or handling a conflict</summary>
|
|
376
|
+
|
|
377
|
+
The updater recognizes unchanged templates from the original 1.3.3 baseline.
|
|
378
|
+
Customized versions, including third-party adaptations, may need manual review.
|
|
379
|
+
|
|
380
|
+
For a legacy spec that you will resume or normalize:
|
|
381
|
+
|
|
382
|
+
```sh
|
|
383
|
+
sdd migrate 001-my-change --dry-run
|
|
384
|
+
sdd migrate 001-my-change
|
|
385
|
+
```
|
|
386
|
+
|
|
387
|
+
Use the real ID. Migration preserves old bodies and creates structures for review.
|
|
388
|
+
Review requirements, acceptance, tasks and references before normalization.
|
|
389
|
+
You do not need to convert all closed historical work just to adopt the flow for new changes.
|
|
390
|
+
|
|
391
|
+
Customized core files cause a conflict before planned core writes are applied.
|
|
392
|
+
Move project-specific rules into policies, contracts or skills before deciding to replace core files.
|
|
393
|
+
`--replace-managed` is explicit and should follow review; replaced content is backed up.
|
|
394
|
+
|
|
395
|
+
These protections describe the 2.x installer. Do not use a 1.x installer to downgrade
|
|
396
|
+
or assume automatic compatibility with future versions.
|
|
397
|
+
Read the [migration guide](docs/migration.md).
|
|
398
|
+
|
|
399
|
+
</details>
|
|
400
|
+
|
|
401
|
+
## Documentation
|
|
402
|
+
|
|
403
|
+
| Goal | Guide |
|
|
404
|
+
|---|---|
|
|
405
|
+
| Use the workflow end to end | [Usage (Português)](docs/usage.pt-BR.md) |
|
|
406
|
+
| Understand setup and documents | [Setup (Português)](docs/setup-documents.pt-BR.md) |
|
|
407
|
+
| Understand the method and changes | [Methodology (Português)](docs/methodology.pt-BR.md) |
|
|
408
|
+
| Configure quality and external tests | [Quality gates (Português)](docs/quality-gates.pt-BR.md) |
|
|
409
|
+
| Understand artifact formats | [Formats and examples](docs/formats.md) |
|
|
410
|
+
| Test locally | [Local testing (Português)](docs/local-testing.pt-BR.md) |
|
|
411
|
+
| Upgrade legacy projects | [Migration](docs/migration.md) |
|
|
412
|
+
| Prepare plugins and skills | [Distribution](docs/distribution.md) |
|
|
413
|
+
| Review observed validation and limits | [Implementation validation](docs/validation.md) |
|
|
414
|
+
| Publish a version | [GitHub and npm (Português)](docs/releases.pt-BR.md) |
|
|
415
|
+
| Contribute | [Contributing](CONTRIBUTING.md) · [Changelog](CHANGELOG.md) |
|
|
416
|
+
|
|
417
|
+
## Important limits
|
|
418
|
+
|
|
419
|
+
The CLI validates declared relationships and records runs. Passing tests do not prove semantic coverage.
|
|
420
|
+
Approval is a recorded assertion, not identity authentication.
|
|
421
|
+
|
|
422
|
+
Configured commands run with current account permissions; the CLI is not a sandbox.
|
|
423
|
+
Review settings, use native harness controls and choose safe environments.
|
|
424
|
+
|
|
425
|
+
Context selection avoids unnecessary reading; no universal cost or generated-code improvement is claimed.
|
|
426
|
+
Interactive adapter compatibility must be checked against the actual tool versions in use.
|
|
427
|
+
|
|
428
|
+
## License
|
|
429
|
+
|
|
430
|
+
[MIT](LICENSE).
|