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/docs/formats.md
CHANGED
|
@@ -1,212 +1,221 @@
|
|
|
1
|
-
# Formats and worked example
|
|
2
|
-
|
|
3
|
-
## Metadata policy
|
|
4
|
-
|
|
5
|
-
Use YAML front matter for machine-consumed Markdown, and YAML for configuration/manifests.
|
|
6
|
-
Skills follow Agent Skills: name matches the directory, is lowercase kebab-case (1–64 characters),
|
|
7
|
-
and description explains the procedure and triggers (1–1024 characters).
|
|
8
|
-
Human-only README files do not need front matter.
|
|
9
|
-
General document metadata is an sdd-flow convention; clients do not automatically interpret arbitrary fields.
|
|
10
|
-
|
|
11
|
-
Optional config.yaml documentation.language is auto or a BCP 47 language tag such as pt-BR or en.
|
|
12
|
-
Existing configurations without this mapping use auto. It guides project-authored narrative; keys, IDs,
|
|
13
|
-
paths and original quotations remain stable. UTF-8 and normal spelling/diacritics are preserved.
|
|
14
|
-
Portuguese seed headings are generated for pt/pt-BR; other CLI seed headings use English as fallback.
|
|
15
|
-
See methodology.pt-BR.md for scope and localization limits.
|
|
16
|
-
|
|
17
|
-
The CLI parses YAML 1.2 with the yaml package. Duplicate keys, aliases, unsupported tags,
|
|
18
|
-
non-mapping roots and reserved prototype keys are rejected. Front matter must start at the file's
|
|
19
|
-
beginning (BOM/CRLF are accepted), close with a delimiter and stay under 64 KiB.
|
|
20
|
-
|
|
21
|
-
## Project configuration
|
|
22
|
-
|
|
23
|
-
Optional reference scaffolding: init --docs creates prd.md, roadmap.md and architecture.md.
|
|
24
|
-
docs --types prd,sd,ds,adr,roadmap selects presets; --dry-run is read-only and existing files are preserved.
|
|
25
|
-
ADR templates are proposed rather than actual active decisions. No fixed reference-document set is required.
|
|
26
|
-
|
|
27
|
-
~~~yaml
|
|
28
|
-
schema_version: 2
|
|
29
|
-
mode: standard
|
|
30
|
-
autonomy:
|
|
31
|
-
approval: required
|
|
32
|
-
context:
|
|
33
|
-
max_bytes: 48000
|
|
34
|
-
checks:
|
|
35
|
-
- name: unit
|
|
36
|
-
command: node --test
|
|
37
|
-
timeout_ms: 60000
|
|
38
|
-
verification:
|
|
39
|
-
exclude: [coverage, dist]
|
|
40
|
-
~~~
|
|
41
|
-
|
|
42
|
-
Check commands execute through the local shell using the current account.
|
|
43
|
-
Names are unique lowercase IDs. Timeouts are positive integers up to 3,600,000 ms.
|
|
44
|
-
Optional level is required (default) or advisory; environment is local (default) or external.
|
|
45
|
-
External commands are skipped unless --run-external is explicitly requested and authorized.
|
|
46
|
-
Optional quality.tdd is optional, preferred (default) or required; it guides the method rather than attesting test chronology.
|
|
47
|
-
QUALITY.md is project-owned, preserved by maintenance and read for planning/review.
|
|
48
|
-
Configure generated paths explicitly; do not exclude source or dependency manifests.
|
|
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
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
~~~
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
~~~
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
~~~
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
~~~
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
1
|
+
# Formats and worked example
|
|
2
|
+
|
|
3
|
+
## Metadata policy
|
|
4
|
+
|
|
5
|
+
Use YAML front matter for machine-consumed Markdown, and YAML for configuration/manifests.
|
|
6
|
+
Skills follow Agent Skills: name matches the directory, is lowercase kebab-case (1–64 characters),
|
|
7
|
+
and description explains the procedure and triggers (1–1024 characters).
|
|
8
|
+
Human-only README files do not need front matter.
|
|
9
|
+
General document metadata is an sdd-flow convention; clients do not automatically interpret arbitrary fields.
|
|
10
|
+
|
|
11
|
+
Optional config.yaml documentation.language is auto or a BCP 47 language tag such as pt-BR or en.
|
|
12
|
+
Existing configurations without this mapping use auto. It guides project-authored narrative; keys, IDs,
|
|
13
|
+
paths and original quotations remain stable. UTF-8 and normal spelling/diacritics are preserved.
|
|
14
|
+
Portuguese seed headings are generated for pt/pt-BR; other CLI seed headings use English as fallback.
|
|
15
|
+
See methodology.pt-BR.md for scope and localization limits.
|
|
16
|
+
|
|
17
|
+
The CLI parses YAML 1.2 with the yaml package. Duplicate keys, aliases, unsupported tags,
|
|
18
|
+
non-mapping roots and reserved prototype keys are rejected. Front matter must start at the file's
|
|
19
|
+
beginning (BOM/CRLF are accepted), close with a delimiter and stay under 64 KiB.
|
|
20
|
+
|
|
21
|
+
## Project configuration
|
|
22
|
+
|
|
23
|
+
Optional reference scaffolding: init --docs creates prd.md, roadmap.md and architecture.md.
|
|
24
|
+
docs --types prd,sd,ds,adr,roadmap selects presets; --dry-run is read-only and existing files are preserved.
|
|
25
|
+
ADR templates are proposed rather than actual active decisions. No fixed reference-document set is required.
|
|
26
|
+
|
|
27
|
+
~~~yaml
|
|
28
|
+
schema_version: 2
|
|
29
|
+
mode: standard
|
|
30
|
+
autonomy: step
|
|
31
|
+
approval: required
|
|
32
|
+
context:
|
|
33
|
+
max_bytes: 48000
|
|
34
|
+
checks:
|
|
35
|
+
- name: unit
|
|
36
|
+
command: node --test
|
|
37
|
+
timeout_ms: 60000
|
|
38
|
+
verification:
|
|
39
|
+
exclude: [coverage, dist]
|
|
40
|
+
~~~
|
|
41
|
+
|
|
42
|
+
Check commands execute through the local shell using the current account.
|
|
43
|
+
Names are unique lowercase IDs. Timeouts are positive integers up to 3,600,000 ms.
|
|
44
|
+
Optional level is required (default) or advisory; environment is local (default) or external.
|
|
45
|
+
External commands are skipped unless --run-external is explicitly requested and authorized.
|
|
46
|
+
Optional quality.tdd is optional, preferred (default) or required; it guides the method rather than attesting test chronology.
|
|
47
|
+
QUALITY.md is project-owned, preserved by maintenance and read for planning/review.
|
|
48
|
+
Configure generated paths explicitly; do not exclude source or dependency manifests.
|
|
49
|
+
New installations use step as the standing default. Explicit user authorization for named tasks or
|
|
50
|
+
all tasks permits a bounded batch without changing configuration; plan approval alone does not.
|
|
51
|
+
Existing configured autonomy is preserved on update. Task checks and dependencies still apply in batches.
|
|
52
|
+
A timeout kills the spawned process group on POSIX. On Windows the CLI invokes taskkill.exe
|
|
53
|
+
for its spawned process tree, with shell-process termination as fallback. Use a controlled environment
|
|
54
|
+
when stronger process isolation is required.
|
|
55
|
+
|
|
56
|
+
## Change manifest
|
|
57
|
+
|
|
58
|
+
Created by sdd new NAME:
|
|
59
|
+
|
|
60
|
+
~~~yaml
|
|
61
|
+
schema_version: 2
|
|
62
|
+
id: 001-addition
|
|
63
|
+
title: Addition
|
|
64
|
+
mode: standard
|
|
65
|
+
status: draft
|
|
66
|
+
capabilities: []
|
|
67
|
+
decisions: []
|
|
68
|
+
skills: []
|
|
69
|
+
depends_on: []
|
|
70
|
+
context:
|
|
71
|
+
- path: src/math.js
|
|
72
|
+
sources: []
|
|
73
|
+
approval: null
|
|
74
|
+
~~~
|
|
75
|
+
|
|
76
|
+
All paths are project-relative. Absolute paths, traversal and symbolic-link traversal are refused.
|
|
77
|
+
context also accepts {path: docs/domain.md, section: Exact heading}.
|
|
78
|
+
List relevant capabilities/decisions explicitly; they must have kind: capability/decision and status: active.
|
|
79
|
+
Dependencies reference full change IDs. Implementation/verification requires dependencies to be closed.
|
|
80
|
+
The manifest ID remains stable when the folder is renamed or renumbered; lookup accepts its current folder name too.
|
|
81
|
+
Optional related lists historical spec IDs without requiring their content or loading them into context.
|
|
82
|
+
Source/context objects may use historical: true for nonessential provenance; missing historical files warn.
|
|
83
|
+
Missing required sources still fail. Missing unfinished dependencies warn in plan and block execution until reviewed;
|
|
84
|
+
a retained recorded closure can satisfy a discarded historical dependency, with explicit warnings and fresh consumer checks.
|
|
85
|
+
Use management commands and reconcile; see spec-management.pt-BR.md for retention and recovery limits.
|
|
86
|
+
The approval command updates approval and ID history; do not fabricate those fields manually.
|
|
87
|
+
|
|
88
|
+
Lifecycle statuses: draft, implementing, implemented (limited verification), verified, closed, cancelled.
|
|
89
|
+
IDs remain reserved after archival through the durable project registry.
|
|
90
|
+
Store original requirement paths or {path: ..., section: Exact heading} references in sources. Research/plan context loads those sources/sections;
|
|
91
|
+
other phases may consult them on demand.
|
|
92
|
+
|
|
93
|
+
## Normative specification
|
|
94
|
+
|
|
95
|
+
~~~yaml
|
|
96
|
+
---
|
|
97
|
+
schema_version: 2
|
|
98
|
+
artifact: spec
|
|
99
|
+
id: 001-addition
|
|
100
|
+
requirements:
|
|
101
|
+
- id: REQ01
|
|
102
|
+
description: Add two finite numbers and reject nonnumeric values.
|
|
103
|
+
acceptance:
|
|
104
|
+
- id: AC01
|
|
105
|
+
covers: [REQ01]
|
|
106
|
+
description: Adding 2 and 3 yields 5; a string input raises TypeError.
|
|
107
|
+
method: automated
|
|
108
|
+
checks: [unit]
|
|
109
|
+
---
|
|
110
|
+
~~~
|
|
111
|
+
|
|
112
|
+
Use REQ, BR or EB for requirement IDs, AC or TC for acceptance IDs.
|
|
113
|
+
Every active requirement needs acceptance coverage. Methods: automated, manual or inspection.
|
|
114
|
+
Automated criteria reference configured check names. A single check can cover several criteria;
|
|
115
|
+
the reviewer must inspect whether assertions actually establish the declared behavior.
|
|
116
|
+
Keep details and rationale in the Markdown body; do not duplicate task execution status there.
|
|
117
|
+
|
|
118
|
+
## Canonical tasks
|
|
119
|
+
|
|
120
|
+
~~~yaml
|
|
121
|
+
---
|
|
122
|
+
schema_version: 2
|
|
123
|
+
artifact: tasks
|
|
124
|
+
id: 001-addition
|
|
125
|
+
tasks:
|
|
126
|
+
- id: T01
|
|
127
|
+
title: Implement addition and regression checks.
|
|
128
|
+
status: pending
|
|
129
|
+
covers: [REQ01, AC01]
|
|
130
|
+
depends_on: []
|
|
131
|
+
verify: The concrete success and rejection scenarios pass with the unit check.
|
|
132
|
+
---
|
|
133
|
+
~~~
|
|
134
|
+
|
|
135
|
+
Statuses: pending, in_progress, done, cancelled. Dependencies must be acyclic.
|
|
136
|
+
A started/done task requires completed dependencies. Task state changes do not invalidate scope approval;
|
|
137
|
+
changes to title, covers, depends_on, verify or normative body do.
|
|
138
|
+
Execution evidence may use the task evidence field without changing normative scope.
|
|
139
|
+
An external-only verification task may use kind: verification, status: deferred and deferral: {by: Name, reason: Explanation}.
|
|
140
|
+
It must cover external acceptance IDs, not replace unfinished implementation. Actual verification requires updating it to done.
|
|
141
|
+
Deferral execution metadata does not change the approved plan, but does bind the verification fingerprint.
|
|
142
|
+
Light changes may omit TASK.md. Standard/rigorous changes require at least one task.
|
|
143
|
+
|
|
144
|
+
To cancel an item, retain its ID and add status: cancelled and cancellation: {by: Name, reason: Explanation}.
|
|
145
|
+
Reassign or cancel dependent references consistently. No automatic code deletion is inferred.
|
|
146
|
+
IDs previously recorded by scope approval cannot disappear from a later revision.
|
|
147
|
+
|
|
148
|
+
## Manual and inspection evidence
|
|
149
|
+
|
|
150
|
+
For each manual/inspection criterion, generate a current template:
|
|
151
|
+
|
|
152
|
+
~~~sh
|
|
153
|
+
sdd evidence 001-addition
|
|
154
|
+
~~~
|
|
155
|
+
|
|
156
|
+
The template contains schema_version, change ID, input_digest and cases.
|
|
157
|
+
Execute the scenario before setting a case to passed/failed:
|
|
158
|
+
|
|
159
|
+
~~~json
|
|
160
|
+
{
|
|
161
|
+
"id": "AC02",
|
|
162
|
+
"result": "passed",
|
|
163
|
+
"by": "Moisés",
|
|
164
|
+
"at": "2026-11-20T16:00:00Z",
|
|
165
|
+
"notes": "Observed the expected result in the isolated test environment.",
|
|
166
|
+
"artifacts": []
|
|
167
|
+
}
|
|
168
|
+
~~~
|
|
169
|
+
|
|
170
|
+
Allowed results: passed, failed, not_run, blocked. Executed results require actor, timestamp and notes.
|
|
171
|
+
Artifacts are project-relative regular files and are hashed. Do not record secrets.
|
|
172
|
+
Evidence must match the current input digest. Finish source changes and task status updates before generating it.
|
|
173
|
+
Store evidence under the spec folder so filling it does not itself change the application source fingerprint.
|
|
174
|
+
If EVIDENCE.json already exists, the default command returns a new revision-specific filename and preserves
|
|
175
|
+
the previous observations. Use that returned path with --evidence. An explicit --out never overwrites a file.
|
|
176
|
+
|
|
177
|
+
~~~sh
|
|
178
|
+
sdd verify 001-addition --evidence agents/specs/001-addition/EVIDENCE.json
|
|
179
|
+
~~~
|
|
180
|
+
|
|
181
|
+
Full success can close a manually tested project. Partial runs never close changes.
|
|
182
|
+
Verification receipts record check-to-criterion mappings, output logs and known limitations.
|
|
183
|
+
|
|
184
|
+
## Current knowledge and decisions
|
|
185
|
+
|
|
186
|
+
~~~yaml
|
|
187
|
+
---
|
|
188
|
+
schema_version: 2
|
|
189
|
+
kind: capability
|
|
190
|
+
id: arithmetic
|
|
191
|
+
description: Arithmetic operations and input validation.
|
|
192
|
+
status: active
|
|
193
|
+
changes: [001-addition]
|
|
194
|
+
---
|
|
195
|
+
~~~
|
|
196
|
+
|
|
197
|
+
Maintain the current behavior and source links in the body. Add the change ID before final verification.
|
|
198
|
+
Decisions use kind: decision, status: active or superseded, and superseded_by when replaced.
|
|
199
|
+
Select the active ADR paths; do not load an entire global append-only decision log every session.
|
|
200
|
+
|
|
201
|
+
## Research
|
|
202
|
+
|
|
203
|
+
Rigorous mode requires RESEARCH.md with schema_version: 2, artifact: research and the matching id.
|
|
204
|
+
Document source evidence, decisions, risks and resolved questions in its body.
|
|
205
|
+
Research is optional for other modes. It does not replace the authoritative sources.
|
|
206
|
+
|
|
207
|
+
## Project policies, revision and history
|
|
208
|
+
|
|
209
|
+
POLICIES.md contains mandatory project-specific constraints and is preserved by updates.
|
|
210
|
+
Scope approval binds these policies, check commands and verification exclusions in addition to the plan.
|
|
211
|
+
It also binds QUALITY.md and quality settings. Advisory checks cannot be the evidence for required acceptance.
|
|
212
|
+
Context budgets are diagnostic settings and do not change scope approval by themselves.
|
|
213
|
+
|
|
214
|
+
Each approval retains a normative snapshot in history/approval-*.json. Editing a rule or policy
|
|
215
|
+
does not rewrite that prior snapshot. Use sdd revise ID --by NAME --reason TEXT --dry-run to inspect
|
|
216
|
+
affected task states, then record the revision and authorize the new scope.
|
|
217
|
+
Requirement/acceptance links determine local impact; policy, prose or reference changes may reopen all tasks.
|
|
218
|
+
Dependent tasks are reopened transitively. The agent must still review semantic impact and update tests.
|
|
219
|
+
|
|
220
|
+
Each verification run retains runs/RUN_ID/receipt.json alongside its logs; verification.json is the current view.
|
|
221
|
+
These historical records are not loaded automatically into context.
|