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/bin/cli.js
CHANGED
|
@@ -1,175 +1,209 @@
|
|
|
1
|
-
#!/usr/bin/env node
|
|
2
|
-
'use strict';
|
|
3
|
-
|
|
4
|
-
const fs = require('node:fs');
|
|
5
|
-
const { parseArgs } = require('node:util');
|
|
6
|
-
const io = require('../lib/io');
|
|
7
|
-
const project = require('../lib/project');
|
|
8
|
-
const validation = require('../lib/check');
|
|
9
|
-
const lifecycle = require('../lib/verification');
|
|
10
|
-
const installation = require('../lib/install');
|
|
11
|
-
const adapters = require('../lib/adapters');
|
|
12
|
-
|
|
13
|
-
const HELP = [
|
|
14
|
-
'sdd-flow ' + installation.VERSION + ' — portable, evidence-based spec-driven development',
|
|
15
|
-
'',
|
|
16
|
-
'sdd init [--mode light|standard|rigorous] [--harness claude-code|opencode] [--docs]',
|
|
17
|
-
'sdd docs [--types prd,roadmap,sd,ds,adr] [--dry-run]',
|
|
18
|
-
'sdd new <name> [--mode light|standard|rigorous]',
|
|
19
|
-
'sdd context <spec> [--phase implement] [--task T01] [--inspect] [--max-bytes N] [--json]',
|
|
20
|
-
'sdd skills list | show <name>',
|
|
21
|
-
'sdd check <spec> [--phase plan|implement|validate|close] [--final] [--json]',
|
|
22
|
-
'sdd approve <spec> --by <name>',
|
|
23
|
-
'sdd revise <spec> --by <name> --reason <reason> [--dry-run]',
|
|
24
|
-
'sdd evidence <spec> [--out path.json]',
|
|
25
|
-
'sdd handoff <spec>',
|
|
26
|
-
'sdd verify <spec> [--scope full|partial] [--evidence path.json] [--handoff path.json] [--run-external]',
|
|
27
|
-
'sdd close <spec> --by <name> [--note reason] [--archive]',
|
|
28
|
-
'sdd reopen <spec> --by <name> --reason <reason>',
|
|
29
|
-
'sdd cancel <spec> --by <name> --reason <reason>',
|
|
30
|
-
'sdd
|
|
31
|
-
'sdd
|
|
32
|
-
'sdd
|
|
33
|
-
'sdd
|
|
34
|
-
'sdd
|
|
35
|
-
'sdd
|
|
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
|
-
if (values.
|
|
89
|
-
|
|
90
|
-
result
|
|
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
|
-
case '
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
spec.change.
|
|
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
|
-
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
'use strict';
|
|
3
|
+
|
|
4
|
+
const fs = require('node:fs');
|
|
5
|
+
const { parseArgs } = require('node:util');
|
|
6
|
+
const io = require('../lib/io');
|
|
7
|
+
const project = require('../lib/project');
|
|
8
|
+
const validation = require('../lib/check');
|
|
9
|
+
const lifecycle = require('../lib/verification');
|
|
10
|
+
const installation = require('../lib/install');
|
|
11
|
+
const adapters = require('../lib/adapters');
|
|
12
|
+
|
|
13
|
+
const HELP = [
|
|
14
|
+
'sdd-flow ' + installation.VERSION + ' — portable, evidence-based spec-driven development',
|
|
15
|
+
'',
|
|
16
|
+
'sdd init [--mode light|standard|rigorous] [--harness claude-code|opencode] [--docs]',
|
|
17
|
+
'sdd docs [--types prd,roadmap,sd,ds,adr] [--dry-run]',
|
|
18
|
+
'sdd new <name> [--mode light|standard|rigorous]',
|
|
19
|
+
'sdd context <spec> [--phase implement] [--task T01] [--inspect] [--max-bytes N] [--json]',
|
|
20
|
+
'sdd skills list | show <name>',
|
|
21
|
+
'sdd check <spec> [--phase plan|implement|validate|close] [--final] [--json]',
|
|
22
|
+
'sdd approve <spec> --by <name>',
|
|
23
|
+
'sdd revise <spec> --by <name> --reason <reason> [--dry-run]',
|
|
24
|
+
'sdd evidence <spec> [--out path.json]',
|
|
25
|
+
'sdd handoff <spec>',
|
|
26
|
+
'sdd verify <spec> [--scope full|partial] [--evidence path.json] [--handoff path.json] [--run-external]',
|
|
27
|
+
'sdd close <spec> --by <name> [--note reason] [--archive]',
|
|
28
|
+
'sdd reopen <spec> --by <name> --reason <reason>',
|
|
29
|
+
'sdd cancel <spec> --by <name> --reason <reason>',
|
|
30
|
+
'sdd rename <spec> [--name folder-name] [--number N] --by <name> --reason <reason> [--dry-run]',
|
|
31
|
+
'sdd archive <spec> --by <name> --reason <reason> [--dry-run]',
|
|
32
|
+
'sdd restore <spec> [--name folder-name] --by <name> --reason <reason> [--dry-run]',
|
|
33
|
+
'sdd remove <spec> --by <name> --reason <reason> [--permanent] [--dry-run]',
|
|
34
|
+
'sdd reconcile [--dry-run]',
|
|
35
|
+
'sdd status [<spec>] [--all] [--json]',
|
|
36
|
+
'sdd doctor [--json]',
|
|
37
|
+
'sdd update [--dry-run] [--replace-managed]',
|
|
38
|
+
'sdd migrate <spec> [--dry-run]',
|
|
39
|
+
'sdd harness <claude-code|opencode> [--remove] [--dry-run]',
|
|
40
|
+
'sdd export <claude-code|opencode|agent-skills> --out <new-directory>',
|
|
41
|
+
'',
|
|
42
|
+
'All commands accept --json. Paths are relative to the project root.',
|
|
43
|
+
'Verification commands run with your account permissions. Use isolated test environments.',
|
|
44
|
+
'Approval records user authorization; it does not grant tool permissions.',
|
|
45
|
+
].join('\n');
|
|
46
|
+
|
|
47
|
+
const OPTIONS = {
|
|
48
|
+
json: { type: 'boolean' }, help: { type: 'boolean', short: 'h' }, version: { type: 'boolean', short: 'v' },
|
|
49
|
+
mode: { type: 'string' }, harness: { type: 'string' }, phase: { type: 'string' }, task: { type: 'string' },
|
|
50
|
+
'max-bytes': { type: 'string' }, final: { type: 'boolean' }, by: { type: 'string' },
|
|
51
|
+
out: { type: 'string' }, scope: { type: 'string' }, evidence: { type: 'string' },
|
|
52
|
+
note: { type: 'string' }, archive: { type: 'boolean' }, reason: { type: 'string' },
|
|
53
|
+
'dry-run': { type: 'boolean' }, 'replace-managed': { type: 'boolean' }, remove: { type: 'boolean' },
|
|
54
|
+
inspect: { type: 'boolean' },
|
|
55
|
+
handoff: { type: 'string' }, 'run-external': { type: 'boolean' },
|
|
56
|
+
docs: { type: 'boolean' }, types: { type: 'string' },
|
|
57
|
+
name: { type: 'string' }, number: { type: 'string' }, permanent: { type: 'boolean' }, all: { type: 'boolean' },
|
|
58
|
+
};
|
|
59
|
+
const ALLOWED = {
|
|
60
|
+
init: ['mode', 'harness', 'docs'], docs: ['types', 'dry-run'], new: ['mode'], context: ['phase', 'task', 'max-bytes', 'inspect'],
|
|
61
|
+
skills: [], check: ['phase', 'final'], approve: ['by'], evidence: ['out'], handoff: [], verify: ['scope', 'evidence', 'handoff', 'run-external'],
|
|
62
|
+
close: ['by', 'note', 'archive'], reopen: ['by', 'reason'], cancel: ['by', 'reason'],
|
|
63
|
+
status: ['all'], doctor: [], update: ['dry-run', 'replace-managed'], migrate: ['dry-run'],
|
|
64
|
+
harness: ['remove', 'dry-run'], export: ['out'],
|
|
65
|
+
revise: ['by', 'reason', 'dry-run'],
|
|
66
|
+
rename: ['name', 'number', 'by', 'reason', 'dry-run'],
|
|
67
|
+
archive: ['by', 'reason', 'dry-run'], restore: ['by', 'reason', 'name', 'dry-run'],
|
|
68
|
+
remove: ['by', 'reason', 'permanent', 'dry-run'], reconcile: ['dry-run'],
|
|
69
|
+
};
|
|
70
|
+
|
|
71
|
+
async function main(argv = process.argv.slice(2), root = process.cwd()) {
|
|
72
|
+
const { values, positionals } = parseArgs({ args: argv, options: OPTIONS, allowPositionals: true, strict: true });
|
|
73
|
+
if (values.version) { console.log(installation.VERSION); return 0; }
|
|
74
|
+
const [command = 'help', first, second] = positionals;
|
|
75
|
+
if (values.help || command === 'help') { console.log(HELP); return 0; }
|
|
76
|
+
if (!ALLOWED[command]) throw new Error('Unknown command: ' + command + '\nRun sdd help');
|
|
77
|
+
for (const key of Object.keys(values)) {
|
|
78
|
+
if (key !== 'json' && !ALLOWED[command].includes(key)) throw new Error('--' + key + ' is not supported by ' + command);
|
|
79
|
+
}
|
|
80
|
+
const maximum = command === 'skills' ? 3 : ['init', 'doctor', 'update', 'docs', 'reconcile'].includes(command) ? 1 : 2;
|
|
81
|
+
if (positionals.length > maximum) throw new Error('Unexpected positional arguments');
|
|
82
|
+
const mutating = new Set(['init', 'docs', 'new', 'approve', 'revise', 'evidence', 'handoff', 'verify', 'close', 'reopen', 'cancel', 'update', 'migrate', 'harness', 'export', 'rename', 'archive', 'restore', 'remove', 'reconcile']);
|
|
83
|
+
async function action() {
|
|
84
|
+
switch (command) {
|
|
85
|
+
case 'init': {
|
|
86
|
+
if (values.mode && !project.MODES.includes(values.mode)) throw new Error('Mode must be light, standard or rigorous');
|
|
87
|
+
if (values.harness && !adapters.NAMES.includes(values.harness)) throw new Error('Unsupported adapter');
|
|
88
|
+
if (values.docs) require('../lib/documents').scaffold(root, { dryRun: true });
|
|
89
|
+
const existed = io.exists(root, 'agents/config.yaml');
|
|
90
|
+
const result = installation.install(root);
|
|
91
|
+
if (values.mode && !existed) {
|
|
92
|
+
const YAML = require('yaml');
|
|
93
|
+
const cfg = project.config(root);
|
|
94
|
+
cfg.mode = values.mode;
|
|
95
|
+
io.write(root, 'agents/config.yaml', YAML.stringify(cfg));
|
|
96
|
+
}
|
|
97
|
+
if (values.harness) result.adapter = adapters.harness(root, values.harness);
|
|
98
|
+
if (values.docs) result.documents = require('../lib/documents').scaffold(root);
|
|
99
|
+
result.next = existed
|
|
100
|
+
? 'Existing project configuration was preserved. Run sdd doctor and review any reported maintenance needs; no new setup is required.'
|
|
101
|
+
: 'Complete agents/PROJECT.md, documentation language and checks in agents/config.yaml using agents/SETUP.md; then run sdd doctor.';
|
|
102
|
+
return result;
|
|
103
|
+
}
|
|
104
|
+
case 'docs': return require('../lib/documents').scaffold(root, { types: values.types, dryRun: values['dry-run'] });
|
|
105
|
+
case 'new': return project.createSpec(root, first, values.mode);
|
|
106
|
+
case 'context': return require('../lib/context').context(root, first, { phase: values.phase, task: values.task, maxBytes: values['max-bytes'] ? Number(values['max-bytes']) : undefined, inspect: values.inspect });
|
|
107
|
+
case 'skills': {
|
|
108
|
+
const catalog = project.skills(root);
|
|
109
|
+
if (first === 'list') return catalog;
|
|
110
|
+
if (first === 'show' && second) {
|
|
111
|
+
const found = catalog.find(item => item.name === second);
|
|
112
|
+
if (!found) throw new Error('Unknown skill: ' + second);
|
|
113
|
+
return { ...found, content: io.read(root, found.path) };
|
|
114
|
+
}
|
|
115
|
+
throw new Error('Use sdd skills list or sdd skills show <name>');
|
|
116
|
+
}
|
|
117
|
+
case 'check': {
|
|
118
|
+
const result = validation.check(root, first, { phase: values.phase, final: values.final });
|
|
119
|
+
return { valid: result.valid, errors: result.errors, warnings: result.warnings };
|
|
120
|
+
}
|
|
121
|
+
case 'approve': return validation.approve(root, first, values.by);
|
|
122
|
+
case 'revise': return require('../lib/revisions').revise(root, first, { by: values.by, reason: values.reason, dryRun: values['dry-run'] });
|
|
123
|
+
case 'evidence': return lifecycle.evidenceTemplate(root, first, values.out);
|
|
124
|
+
case 'handoff': return require('../lib/handoff').template(root, first);
|
|
125
|
+
case 'verify': return lifecycle.verify(root, first, { scope: values.scope, evidence: values.evidence, handoff: values.handoff, runExternal: values['run-external'] });
|
|
126
|
+
case 'close': return lifecycle.close(root, first, { by: values.by, note: values.note, archive: values.archive });
|
|
127
|
+
case 'rename':
|
|
128
|
+
case 'archive':
|
|
129
|
+
case 'restore':
|
|
130
|
+
case 'remove': return require('../lib/management').manage(root, command, first, {
|
|
131
|
+
name: values.name, number: values.number, by: values.by, reason: values.reason,
|
|
132
|
+
permanent: values.permanent, dryRun: values['dry-run'],
|
|
133
|
+
});
|
|
134
|
+
case 'reconcile': return require('../lib/management').reconcile(root, { dryRun: values['dry-run'] });
|
|
135
|
+
case 'reopen':
|
|
136
|
+
case 'cancel': {
|
|
137
|
+
if (!values.by?.trim() || !values.reason?.trim()) throw new Error('Provide --by and --reason');
|
|
138
|
+
const spec = project.loadSpec(root, first);
|
|
139
|
+
if (spec.legacy) throw new Error('Migrate the spec before changing its lifecycle');
|
|
140
|
+
if (command === 'reopen') {
|
|
141
|
+
if (!['closed', 'cancelled'].includes(spec.change.status)) throw new Error('Only closed/cancelled changes can be reopened');
|
|
142
|
+
const target = 'agents/specs/' + require('node:path').posix.basename(spec.relative);
|
|
143
|
+
if (spec.relative !== target) {
|
|
144
|
+
if (io.exists(root, target)) throw new Error('Active spec destination exists');
|
|
145
|
+
fs.renameSync(io.resolve(root, spec.relative), io.resolve(root, target));
|
|
146
|
+
spec.relative = target;
|
|
147
|
+
}
|
|
148
|
+
const receipt = spec.relative + '/verification.json';
|
|
149
|
+
if (io.exists(root, receipt)) {
|
|
150
|
+
fs.mkdirSync(io.resolve(root, spec.relative + '/runs'), { recursive: true });
|
|
151
|
+
fs.renameSync(io.resolve(root, receipt), io.resolve(root, spec.relative + '/runs/reopened-' + Date.now() + '.json'));
|
|
152
|
+
}
|
|
153
|
+
spec.change.status = 'implementing';
|
|
154
|
+
spec.change.reopened = { by: values.by, reason: values.reason, at: new Date().toISOString() };
|
|
155
|
+
} else {
|
|
156
|
+
if (spec.change.status === 'closed') throw new Error('Reopen a closed change before cancelling it');
|
|
157
|
+
spec.change.status = 'cancelled';
|
|
158
|
+
spec.change.cancellation = { by: values.by, reason: values.reason, at: new Date().toISOString() };
|
|
159
|
+
}
|
|
160
|
+
require('../lib/history').record(root, spec, command, { by: values.by, reason: values.reason, status: spec.change.status });
|
|
161
|
+
project.writeChange(root, spec);
|
|
162
|
+
return { id: spec.id, status: spec.change.status };
|
|
163
|
+
}
|
|
164
|
+
case 'status': {
|
|
165
|
+
const options = { includeTrash: values.all || Boolean(first) };
|
|
166
|
+
const records = require('../lib/catalog').registry(root).records;
|
|
167
|
+
if (first && records[first] && (!records[first].path || !io.exists(root, records[first].path))) {
|
|
168
|
+
const existing = project.specDirectories(root).some(spec => spec.id === first);
|
|
169
|
+
if (!existing) return [{ id: first, ...records[first], retained: true, historical_only: true }];
|
|
170
|
+
}
|
|
171
|
+
const items = first ? [project.locate(root, first, options)] : project.specDirectories(root, options).filter(item => values.all || item.location === 'active');
|
|
172
|
+
const result = items.map(item => {
|
|
173
|
+
try {
|
|
174
|
+
const spec = project.loadSpec(root, item.id, options);
|
|
175
|
+
return { id: spec.id, name: item.name, location: item.location, path: spec.relative, status: spec.legacy ? 'legacy' : spec.change.status,
|
|
176
|
+
approval: spec.legacy ? 'legacy' : project.approvalValid(root, spec) ? 'current' : 'missing-or-stale',
|
|
177
|
+
closure: spec.change?.closure || null };
|
|
178
|
+
} catch (error) {
|
|
179
|
+
return { id: item.id, name: item.name, path: item.relative, status: 'invalid', error: error.message };
|
|
180
|
+
}
|
|
181
|
+
});
|
|
182
|
+
if (!first && values.all) for (const [id, record] of Object.entries(records)) {
|
|
183
|
+
if (!result.some(item => item.id === id)) result.push({ id, ...record, retained: true, historical_only: true });
|
|
184
|
+
}
|
|
185
|
+
return result;
|
|
186
|
+
}
|
|
187
|
+
case 'doctor': return installation.doctor(root);
|
|
188
|
+
case 'update': return installation.install(root, { update: true, dryRun: values['dry-run'], replaceManaged: values['replace-managed'] });
|
|
189
|
+
case 'migrate': return installation.migrate(root, first, { dryRun: values['dry-run'] });
|
|
190
|
+
case 'harness': return adapters.harness(root, first, { remove: values.remove, dryRun: values['dry-run'] });
|
|
191
|
+
case 'export': return adapters.exportBundle(root, first, values.out);
|
|
192
|
+
}
|
|
193
|
+
}
|
|
194
|
+
const result = await (mutating.has(command) && !values['dry-run'] ? io.locked(root, action) : action());
|
|
195
|
+
if (!values.json && typeof result.content === 'string') console.log(result.content);
|
|
196
|
+
else console.log(JSON.stringify(result, null, 2));
|
|
197
|
+
if (result.valid === false || result.verdict === 'failed' || result.conflicts?.length) return 1;
|
|
198
|
+
if (result.verdict === 'partial') return 2;
|
|
199
|
+
return 0;
|
|
200
|
+
}
|
|
201
|
+
|
|
202
|
+
if (require.main === module) {
|
|
203
|
+
main().then(code => { process.exitCode = code; }).catch(error => {
|
|
204
|
+
if (process.argv.includes('--json')) console.log(JSON.stringify({ error: error.message, ...(error.code && { code: error.code }), ...(error.diagnostics && { diagnostics: error.diagnostics }) }));
|
|
205
|
+
else console.error('SDD: ' + error.message);
|
|
206
|
+
process.exitCode = 1;
|
|
207
|
+
});
|
|
208
|
+
}
|
|
209
|
+
module.exports = { main, HELP };
|