sdd-flow 1.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/LICENSE +21 -0
- package/README.md +83 -0
- package/bin/cli.js +315 -0
- package/package.json +32 -0
- package/templates/AGENTS.md +49 -0
- package/templates/QUICKSTART.md +50 -0
- package/templates/agents/AGENTS.md +92 -0
- package/templates/agents/DECISIONS.md +21 -0
- package/templates/agents/PROJECT.md +145 -0
- package/templates/agents/RULES.md +116 -0
- package/templates/agents/SETUP.md +224 -0
- package/templates/agents/harness/claude-code/.hooks/guard-delete.sh +22 -0
- package/templates/agents/harness/claude-code/.hooks/guard-deps.sh +25 -0
- package/templates/agents/harness/claude-code/.hooks/guard-git.sh +24 -0
- package/templates/agents/harness/claude-code/commands/sdd-implement.md +3 -0
- package/templates/agents/harness/claude-code/commands/sdd-plan.md +3 -0
- package/templates/agents/harness/claude-code/commands/sdd-research.md +3 -0
- package/templates/agents/harness/claude-code/commands/sdd-validate.md +3 -0
- package/templates/agents/harness/claude-code/settings.json +34 -0
- package/templates/agents/harness/opencode/commands/sdd-implement.md +3 -0
- package/templates/agents/harness/opencode/commands/sdd-plan.md +3 -0
- package/templates/agents/harness/opencode/commands/sdd-research.md +3 -0
- package/templates/agents/harness/opencode/commands/sdd-validate.md +3 -0
- package/templates/agents/harness/opencode/opencode.json +18 -0
- package/templates/agents/prompts/conventional-commit.md +51 -0
- package/templates/agents/prompts/pr-template.md +21 -0
- package/templates/agents/prompts/rpi-implement.md +46 -0
- package/templates/agents/prompts/rpi-plan.md +117 -0
- package/templates/agents/prompts/rpi-research.md +67 -0
- package/templates/agents/prompts/rpi-validate.md +96 -0
- package/templates/agents/prompts/skill-call.md +29 -0
- package/templates/agents/prompts/task-create.md +42 -0
- package/templates/agents/skills/_template/SKILL.md +37 -0
package/LICENSE
ADDED
|
@@ -0,0 +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.
|
package/README.md
ADDED
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
# sdd-flow
|
|
2
|
+
|
|
3
|
+
Spec Driven Development workflow for AI-assisted development.
|
|
4
|
+
|
|
5
|
+
Installs a structured **Research → Plan → Implement → Validate** cycle into any project, powered by markdown artifacts and isolated agent sessions.
|
|
6
|
+
|
|
7
|
+
Works with Claude Code, OpenCode, Cursor, Codex CLI, and any agentic IDE with filesystem access.
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
## Install
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
npm install -g sdd-flow
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
---
|
|
18
|
+
|
|
19
|
+
## Usage
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
sdd init # Instala o workflow no projeto atual
|
|
23
|
+
sdd harness # Instala, troca ou remove o harness do agente
|
|
24
|
+
sdd update # Atualiza prompts e regras, preserva dados do projeto
|
|
25
|
+
sdd --version
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
> Alias disponível: use `sdd` ou `sdd-cli` — ambos funcionam.
|
|
29
|
+
|
|
30
|
+
### New or existing project
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
cd my-project
|
|
34
|
+
sdd init
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
Installs the `agents/` folder with all workflow files. Optionally installs safety hooks and slash commands for your agent (Claude Code or OpenCode).
|
|
38
|
+
|
|
39
|
+
### Add or switch harness after init
|
|
40
|
+
|
|
41
|
+
```bash
|
|
42
|
+
sdd harness
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
Installs, replaces, or removes the harness and slash commands at any time — no need to reinstall the package.
|
|
46
|
+
|
|
47
|
+
### Update workflow (preserves your project data)
|
|
48
|
+
|
|
49
|
+
```bash
|
|
50
|
+
sdd update
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
Updates `AGENTS.md`, `RULES.md`, `QUICKSTART.md`, and all prompts. Your `PROJECT.md`, `DECISIONS.md`, `skills/`, `specs/`, and `harness/` are never touched.
|
|
54
|
+
|
|
55
|
+
---
|
|
56
|
+
|
|
57
|
+
## After `init`
|
|
58
|
+
|
|
59
|
+
1. Open a new session with your agent
|
|
60
|
+
2. Instruct: *"Read and follow `agents/SETUP.md`"*
|
|
61
|
+
3. Provide your PRD or describe the project
|
|
62
|
+
4. Review the generated files and delete `agents/SETUP.md`
|
|
63
|
+
|
|
64
|
+
---
|
|
65
|
+
|
|
66
|
+
## The RPI Cycle
|
|
67
|
+
|
|
68
|
+
Each feature goes through four isolated phases, each in its own agent session:
|
|
69
|
+
|
|
70
|
+
| Phase | Slash command | Prompt file |
|
|
71
|
+
|---|---|---|
|
|
72
|
+
| Research | `/sdd-research 001-feature` | `agents/prompts/rpi-research.md` |
|
|
73
|
+
| Plan | `/sdd-plan 001-feature` | `agents/prompts/rpi-plan.md` |
|
|
74
|
+
| Implement | `/sdd-implement 001-feature` | `agents/prompts/rpi-implement.md` |
|
|
75
|
+
| Validate | `/sdd-validate 001-feature` | `agents/prompts/rpi-validate.md` |
|
|
76
|
+
|
|
77
|
+
> Slash commands require harness installation (`sdd harness`).
|
|
78
|
+
|
|
79
|
+
---
|
|
80
|
+
|
|
81
|
+
## Source
|
|
82
|
+
|
|
83
|
+
[github.com/moisesuailab/spec-driven-workflow](https://github.com/moisesuailab/spec-driven-workflow)
|
package/bin/cli.js
ADDED
|
@@ -0,0 +1,315 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
|
|
3
|
+
'use strict';
|
|
4
|
+
|
|
5
|
+
const fs = require('fs');
|
|
6
|
+
const path = require('path');
|
|
7
|
+
const rl = require('readline');
|
|
8
|
+
|
|
9
|
+
const TEMPLATES = path.join(__dirname, '..', 'templates');
|
|
10
|
+
const CWD = process.cwd();
|
|
11
|
+
const VERSION = require('../package.json').version;
|
|
12
|
+
const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
|
|
13
|
+
|
|
14
|
+
const c = useColor
|
|
15
|
+
? { reset: '\x1b[0m', bold: '\x1b[1m', green: '\x1b[32m',
|
|
16
|
+
yellow: '\x1b[33m', cyan: '\x1b[36m', red: '\x1b[31m', dim: '\x1b[2m' }
|
|
17
|
+
: { reset: '', bold: '', green: '', yellow: '', cyan: '', red: '', dim: '' };
|
|
18
|
+
|
|
19
|
+
const log = (msg = '') => console.log(msg);
|
|
20
|
+
const ok = (msg) => console.log(`${c.green}✔${c.reset} ${msg}`);
|
|
21
|
+
const warn = (msg) => console.log(`${c.yellow}⚠${c.reset} ${msg}`);
|
|
22
|
+
const info = (msg) => console.log(`${c.cyan}ℹ${c.reset} ${msg}`);
|
|
23
|
+
const error = (msg) => console.log(`${c.red}✖${c.reset} ${msg}`);
|
|
24
|
+
const bold = (msg) => `${c.bold}${msg}${c.reset}`;
|
|
25
|
+
const dim = (msg) => `${c.dim}${msg}${c.reset}`;
|
|
26
|
+
|
|
27
|
+
function ask(prompt) {
|
|
28
|
+
const iface = rl.createInterface({ input: process.stdin, output: process.stdout });
|
|
29
|
+
return new Promise(resolve =>
|
|
30
|
+
iface.question(prompt, answer => { iface.close(); resolve(answer.trim()); })
|
|
31
|
+
);
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
function copy(src, dest) {
|
|
35
|
+
fs.mkdirSync(path.dirname(dest), { recursive: true });
|
|
36
|
+
fs.copyFileSync(src, dest);
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
function copyDir(src, dest, exclude = []) {
|
|
40
|
+
fs.mkdirSync(dest, { recursive: true });
|
|
41
|
+
for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
|
|
42
|
+
if (exclude.includes(entry.name)) continue;
|
|
43
|
+
const srcPath = path.join(src, entry.name);
|
|
44
|
+
const destPath = path.join(dest, entry.name);
|
|
45
|
+
entry.isDirectory() ? copyDir(srcPath, destPath) : copy(srcPath, destPath);
|
|
46
|
+
}
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
const HARNESS_CONFIG = {
|
|
50
|
+
'2': {
|
|
51
|
+
name: 'claude-code',
|
|
52
|
+
commandsDest: path.join(CWD, '.claude', 'commands'),
|
|
53
|
+
},
|
|
54
|
+
'3': {
|
|
55
|
+
name: 'opencode',
|
|
56
|
+
commandsDest: path.join(CWD, '.opencode', 'commands'),
|
|
57
|
+
},
|
|
58
|
+
};
|
|
59
|
+
|
|
60
|
+
function showSlashCommands() {
|
|
61
|
+
log(bold('Slash commands disponíveis:'));
|
|
62
|
+
log(` ${c.cyan}/sdd-research${c.reset} 001-nome-da-feature`);
|
|
63
|
+
log(` ${c.cyan}/sdd-plan${c.reset} 001-nome-da-feature`);
|
|
64
|
+
log(` ${c.cyan}/sdd-implement${c.reset} 001-nome-da-feature`);
|
|
65
|
+
log(` ${c.cyan}/sdd-validate${c.reset} 001-nome-da-feature`);
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
function removeSddCommands(commandsDest) {
|
|
69
|
+
if (!fs.existsSync(commandsDest)) return;
|
|
70
|
+
for (const f of fs.readdirSync(commandsDest)) {
|
|
71
|
+
if (f.startsWith('sdd-')) fs.rmSync(path.join(commandsDest, f));
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
async function init() {
|
|
76
|
+
log();
|
|
77
|
+
log(bold('sdd-cli') + dim(' — Spec Driven Development workflow'));
|
|
78
|
+
log();
|
|
79
|
+
|
|
80
|
+
const agentsDir = path.join(CWD, 'agents');
|
|
81
|
+
if (fs.existsSync(agentsDir)) {
|
|
82
|
+
warn('A pasta agents/ já existe neste projeto.');
|
|
83
|
+
const answer = await ask(' Deseja sobrescrever os arquivos do workflow? (s/N) ');
|
|
84
|
+
if (answer.toLowerCase() !== 's') {
|
|
85
|
+
info('Operação cancelada. Use ' + bold('sdd update') + ' para atualizar prompts e regras.');
|
|
86
|
+
log();
|
|
87
|
+
process.exit(0);
|
|
88
|
+
}
|
|
89
|
+
log();
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
copy(path.join(TEMPLATES, 'AGENTS.md'), path.join(CWD, 'AGENTS.md'));
|
|
93
|
+
ok('AGENTS.md criado na raiz do projeto');
|
|
94
|
+
|
|
95
|
+
copy(path.join(TEMPLATES, 'QUICKSTART.md'), path.join(CWD, 'QUICKSTART.md'));
|
|
96
|
+
ok('QUICKSTART.md criado na raiz do projeto');
|
|
97
|
+
|
|
98
|
+
copyDir(path.join(TEMPLATES, 'agents'), agentsDir, ['harness']);
|
|
99
|
+
ok('Workflow instalado em agents/');
|
|
100
|
+
|
|
101
|
+
log();
|
|
102
|
+
info('O harness instala hooks de segurança e slash commands ' + dim('(opcional)'));
|
|
103
|
+
log(' 1) Pular esta etapa');
|
|
104
|
+
log(' 2) Claude Code');
|
|
105
|
+
log(' 3) OpenCode');
|
|
106
|
+
const choice = await ask(' Escolha [1]: ');
|
|
107
|
+
|
|
108
|
+
const harnessCfg = HARNESS_CONFIG[choice];
|
|
109
|
+
let harnessInstalled = false;
|
|
110
|
+
|
|
111
|
+
if (harnessCfg) {
|
|
112
|
+
const { name, commandsDest } = harnessCfg;
|
|
113
|
+
const harnessSrc = path.join(TEMPLATES, 'agents', 'harness', name);
|
|
114
|
+
|
|
115
|
+
if (fs.existsSync(harnessSrc)) {
|
|
116
|
+
copyDir(harnessSrc, path.join(agentsDir, 'harness', name), ['commands']);
|
|
117
|
+
ok(`Harness instalado: ${name}`);
|
|
118
|
+
|
|
119
|
+
const cmdSrc = path.join(harnessSrc, 'commands');
|
|
120
|
+
if (fs.existsSync(cmdSrc)) {
|
|
121
|
+
copyDir(cmdSrc, commandsDest);
|
|
122
|
+
ok(`Slash commands instalados em ${path.relative(CWD, commandsDest)}/`);
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
harnessInstalled = true;
|
|
126
|
+
} else {
|
|
127
|
+
warn(`Harness "${name}" não encontrado. Use sdd harness para instalar depois.`);
|
|
128
|
+
}
|
|
129
|
+
} else {
|
|
130
|
+
info('Harness ignorado. Use ' + bold('sdd harness') + ' para instalar depois.');
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
log();
|
|
134
|
+
log(bold('Próximos passos:'));
|
|
135
|
+
log(` ${c.cyan}1.${c.reset} Abra uma sessão do seu agente no projeto`);
|
|
136
|
+
log(` ${c.cyan}2.${c.reset} Instrua: ${dim('"Leia e siga agents/SETUP.md"')}`);
|
|
137
|
+
log(` ${c.cyan}3.${c.reset} Forneça seu PRD ou descreva o projeto`);
|
|
138
|
+
log(` ${c.cyan}4.${c.reset} Revise os arquivos gerados e delete agents/SETUP.md`);
|
|
139
|
+
log();
|
|
140
|
+
|
|
141
|
+
if (harnessInstalled) {
|
|
142
|
+
showSlashCommands();
|
|
143
|
+
} else {
|
|
144
|
+
log(dim(' Sem slash commands — consulte QUICKSTART.md para instruções manuais.'));
|
|
145
|
+
log(dim(' Para instalar depois: sdd harness'));
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
log();
|
|
149
|
+
log(dim(' Documentação: https://github.com/moisesuailab/spec-driven-workflow'));
|
|
150
|
+
log();
|
|
151
|
+
}
|
|
152
|
+
|
|
153
|
+
async function harness() {
|
|
154
|
+
log();
|
|
155
|
+
log(bold('sdd harness'));
|
|
156
|
+
log();
|
|
157
|
+
|
|
158
|
+
const agentsDir = path.join(CWD, 'agents');
|
|
159
|
+
if (!fs.existsSync(agentsDir)) {
|
|
160
|
+
error('Pasta agents/ não encontrada. Rode ' + bold('sdd init') + ' primeiro.');
|
|
161
|
+
log();
|
|
162
|
+
process.exit(1);
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
info('O que deseja fazer?');
|
|
166
|
+
log(' 1) Remover harness atual');
|
|
167
|
+
log(' 2) Instalar / trocar para Claude Code');
|
|
168
|
+
log(' 3) Instalar / trocar para OpenCode');
|
|
169
|
+
const choice = await ask(' Escolha: ');
|
|
170
|
+
|
|
171
|
+
if (choice === '1') {
|
|
172
|
+
const harnessDir = path.join(agentsDir, 'harness');
|
|
173
|
+
if (fs.existsSync(harnessDir)) {
|
|
174
|
+
fs.rmSync(harnessDir, { recursive: true });
|
|
175
|
+
ok('Hooks removidos de agents/harness/');
|
|
176
|
+
}
|
|
177
|
+
for (const cfg of Object.values(HARNESS_CONFIG)) {
|
|
178
|
+
removeSddCommands(cfg.commandsDest);
|
|
179
|
+
if (fs.existsSync(cfg.commandsDest)) {
|
|
180
|
+
ok(`Slash commands removidos de ${path.relative(CWD, cfg.commandsDest)}/`);
|
|
181
|
+
}
|
|
182
|
+
}
|
|
183
|
+
log();
|
|
184
|
+
ok('Harness desinstalado.');
|
|
185
|
+
log();
|
|
186
|
+
return;
|
|
187
|
+
}
|
|
188
|
+
|
|
189
|
+
const harnessCfg = HARNESS_CONFIG[choice];
|
|
190
|
+
if (!harnessCfg) {
|
|
191
|
+
info('Operação cancelada.');
|
|
192
|
+
log();
|
|
193
|
+
process.exit(0);
|
|
194
|
+
}
|
|
195
|
+
|
|
196
|
+
const { name, commandsDest } = harnessCfg;
|
|
197
|
+
const harnessSrc = path.join(TEMPLATES, 'agents', 'harness', name);
|
|
198
|
+
|
|
199
|
+
if (!fs.existsSync(harnessSrc)) {
|
|
200
|
+
error(`Harness "${name}" não encontrado nos templates.`);
|
|
201
|
+
process.exit(1);
|
|
202
|
+
}
|
|
203
|
+
|
|
204
|
+
for (const cfg of Object.values(HARNESS_CONFIG)) {
|
|
205
|
+
removeSddCommands(cfg.commandsDest);
|
|
206
|
+
}
|
|
207
|
+
|
|
208
|
+
copyDir(harnessSrc, path.join(agentsDir, 'harness', name), ['commands']);
|
|
209
|
+
ok(`Harness instalado: ${name}`);
|
|
210
|
+
|
|
211
|
+
const cmdSrc = path.join(harnessSrc, 'commands');
|
|
212
|
+
if (fs.existsSync(cmdSrc)) {
|
|
213
|
+
copyDir(cmdSrc, commandsDest);
|
|
214
|
+
ok(`Slash commands instalados em ${path.relative(CWD, commandsDest)}/`);
|
|
215
|
+
}
|
|
216
|
+
|
|
217
|
+
log();
|
|
218
|
+
showSlashCommands();
|
|
219
|
+
log();
|
|
220
|
+
}
|
|
221
|
+
|
|
222
|
+
async function update() {
|
|
223
|
+
log();
|
|
224
|
+
log(bold('sdd update'));
|
|
225
|
+
log();
|
|
226
|
+
|
|
227
|
+
const agentsDir = path.join(CWD, 'agents');
|
|
228
|
+
if (!fs.existsSync(agentsDir)) {
|
|
229
|
+
error('Pasta agents/ não encontrada. Rode ' + bold('sdd init') + ' primeiro.');
|
|
230
|
+
log();
|
|
231
|
+
process.exit(1);
|
|
232
|
+
}
|
|
233
|
+
|
|
234
|
+
warn('Isso atualizará AGENTS.md, RULES.md, QUICKSTART.md e todos os prompts.');
|
|
235
|
+
const answer = await ask(' Deseja continuar? (s/N) ');
|
|
236
|
+
if (answer.toLowerCase() !== 's') {
|
|
237
|
+
info('Operação cancelada.');
|
|
238
|
+
log();
|
|
239
|
+
process.exit(0);
|
|
240
|
+
}
|
|
241
|
+
log();
|
|
242
|
+
|
|
243
|
+
const coreFiles = [
|
|
244
|
+
{ rel: ['AGENTS.md'], dest: path.join(CWD, 'AGENTS.md') },
|
|
245
|
+
{ rel: ['QUICKSTART.md'], dest: path.join(CWD, 'QUICKSTART.md') },
|
|
246
|
+
{ rel: ['agents', 'AGENTS.md'], dest: path.join(agentsDir, 'AGENTS.md') },
|
|
247
|
+
{ rel: ['agents', 'RULES.md'], dest: path.join(agentsDir, 'RULES.md') },
|
|
248
|
+
];
|
|
249
|
+
|
|
250
|
+
for (const { rel, dest } of coreFiles) {
|
|
251
|
+
copy(path.join(TEMPLATES, ...rel), dest);
|
|
252
|
+
ok(`Atualizado: ${rel.join('/')}`);
|
|
253
|
+
}
|
|
254
|
+
|
|
255
|
+
copyDir(
|
|
256
|
+
path.join(TEMPLATES, 'agents', 'prompts'),
|
|
257
|
+
path.join(agentsDir, 'prompts')
|
|
258
|
+
);
|
|
259
|
+
ok('Atualizado: agents/prompts/');
|
|
260
|
+
|
|
261
|
+
log();
|
|
262
|
+
info('Preservados (dados do projeto):');
|
|
263
|
+
['agents/PROJECT.md', 'agents/DECISIONS.md', 'agents/skills/', 'agents/specs/', 'agents/harness/']
|
|
264
|
+
.forEach(f => log(` ${dim(f)}`));
|
|
265
|
+
log();
|
|
266
|
+
ok('Workflow atualizado com sucesso.');
|
|
267
|
+
log();
|
|
268
|
+
}
|
|
269
|
+
|
|
270
|
+
function help() {
|
|
271
|
+
log();
|
|
272
|
+
log(bold('sdd-cli') + dim(' — Spec Driven Development workflow'));
|
|
273
|
+
log();
|
|
274
|
+
log('Uso:');
|
|
275
|
+
log(` sdd-cli ${c.cyan}init${c.reset} Instala o workflow no projeto atual`);
|
|
276
|
+
log(` sdd-cli ${c.cyan}harness${c.reset} Instala, troca ou remove o harness do agente`);
|
|
277
|
+
log(` sdd-cli ${c.cyan}update${c.reset} Atualiza prompts e regras, preserva dados do projeto`);
|
|
278
|
+
log(` sdd-cli ${c.cyan}help${c.reset} Exibe esta mensagem`);
|
|
279
|
+
log(` sdd-cli ${c.cyan}--version${c.reset} Exibe a versão instalada`);
|
|
280
|
+
log();
|
|
281
|
+
log(dim(' Alias: sdd init / sdd harness / sdd update / sdd help / sdd --version'));
|
|
282
|
+
log();
|
|
283
|
+
log(dim(' Documentação: https://github.com/moisesuailab/spec-driven-workflow'));
|
|
284
|
+
log();
|
|
285
|
+
}
|
|
286
|
+
|
|
287
|
+
const cmd = process.argv[2];
|
|
288
|
+
|
|
289
|
+
switch (cmd) {
|
|
290
|
+
case 'init':
|
|
291
|
+
init().catch(e => { error(e.message); process.exit(1); });
|
|
292
|
+
break;
|
|
293
|
+
case 'harness':
|
|
294
|
+
harness().catch(e => { error(e.message); process.exit(1); });
|
|
295
|
+
break;
|
|
296
|
+
case 'update':
|
|
297
|
+
update().catch(e => { error(e.message); process.exit(1); });
|
|
298
|
+
break;
|
|
299
|
+
case 'help':
|
|
300
|
+
case '--help':
|
|
301
|
+
case '-h':
|
|
302
|
+
help();
|
|
303
|
+
break;
|
|
304
|
+
case '--version':
|
|
305
|
+
case '-v':
|
|
306
|
+
log(VERSION);
|
|
307
|
+
break;
|
|
308
|
+
case undefined:
|
|
309
|
+
help();
|
|
310
|
+
break;
|
|
311
|
+
default:
|
|
312
|
+
error(`Comando desconhecido: "${cmd}"`);
|
|
313
|
+
help();
|
|
314
|
+
process.exit(1);
|
|
315
|
+
}
|
package/package.json
ADDED
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "sdd-flow",
|
|
3
|
+
"version": "1.0.0",
|
|
4
|
+
"description": "Spec Driven Development workflow for AI-assisted development (SDD + RPI)",
|
|
5
|
+
"bin": {
|
|
6
|
+
"sdd-cli": "./bin/cli.js",
|
|
7
|
+
"sdd": "./bin/cli.js"
|
|
8
|
+
},
|
|
9
|
+
"files": [
|
|
10
|
+
"bin/",
|
|
11
|
+
"templates/"
|
|
12
|
+
],
|
|
13
|
+
"engines": {
|
|
14
|
+
"node": ">=18"
|
|
15
|
+
},
|
|
16
|
+
"keywords": [
|
|
17
|
+
"sdd",
|
|
18
|
+
"spec-driven-development",
|
|
19
|
+
"rpi",
|
|
20
|
+
"ai-workflow",
|
|
21
|
+
"claude-code",
|
|
22
|
+
"opencode",
|
|
23
|
+
"agentic",
|
|
24
|
+
"workflow"
|
|
25
|
+
],
|
|
26
|
+
"author": "moisesuailab",
|
|
27
|
+
"license": "MIT",
|
|
28
|
+
"repository": {
|
|
29
|
+
"type": "git",
|
|
30
|
+
"url": "https://github.com/moisesuailab/spec-driven-workflow.git"
|
|
31
|
+
}
|
|
32
|
+
}
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
# Agent Instructions
|
|
2
|
+
|
|
3
|
+
This project uses **Spec Driven Development (SDD)** with the **Research → Plan → Implement (RPI)**
|
|
4
|
+
methodology. Every feature goes through three isolated phases, each in its own agent session.
|
|
5
|
+
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
## On session start — always read these files
|
|
9
|
+
|
|
10
|
+
| File | Purpose |
|
|
11
|
+
|---|---|
|
|
12
|
+
| `agents/AGENTS.md` | Role definition, SDD cycle, and session rules |
|
|
13
|
+
| `agents/PROJECT.md` | Stack, architecture, and project-specific rules |
|
|
14
|
+
| `agents/RULES.md` | Mandatory process rules (git, tasks, decisions) |
|
|
15
|
+
|
|
16
|
+
> **How to load:** Use your file reading tool to read each file above before taking any action.
|
|
17
|
+
> Do not proceed without reading them — they define the rules for this session.
|
|
18
|
+
|
|
19
|
+
---
|
|
20
|
+
|
|
21
|
+
## Skills — load on demand
|
|
22
|
+
|
|
23
|
+
Skills are in `agents/skills/<name>/SKILL.md`. Before implementing any task, scan the skills
|
|
24
|
+
directory and read the `## When to use this skill` section of each file. Load only the skills
|
|
25
|
+
relevant to the current task.
|
|
26
|
+
|
|
27
|
+
---
|
|
28
|
+
|
|
29
|
+
## Active spec
|
|
30
|
+
|
|
31
|
+
The active spec folder is `agents/specs/<NNN-feature-name>/`. It contains:
|
|
32
|
+
`RESEARCH.md`, `SPEC.md`, `TASK.md`, `PROGRESS.md`, `DECISIONS.md`, and `TEST.md`.
|
|
33
|
+
|
|
34
|
+
When a spec folder is provided, read `SPEC.md` and `TASK.md` before implementing.
|
|
35
|
+
|
|
36
|
+
---
|
|
37
|
+
|
|
38
|
+
## RPI prompts
|
|
39
|
+
|
|
40
|
+
Full prompts for each phase are in `agents/prompts/`. Use them by reading the relevant file:
|
|
41
|
+
- Phase 1 — Research: `agents/prompts/rpi-research.md`
|
|
42
|
+
- Phase 2 — Plan: `agents/prompts/rpi-plan.md`
|
|
43
|
+
- Phase 3 — Implement: `agents/prompts/rpi-implement.md`
|
|
44
|
+
|
|
45
|
+
---
|
|
46
|
+
|
|
47
|
+
## First-time setup
|
|
48
|
+
|
|
49
|
+
If `agents/PROJECT.md` does not exist yet, read `agents/SETUP.md` and follow its instructions.
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
# SDD Workflow — Quick Start
|
|
2
|
+
|
|
3
|
+
## Ciclo
|
|
4
|
+
|
|
5
|
+
Cada feature passa por 4 fases em sessões isoladas:
|
|
6
|
+
|
|
7
|
+
```
|
|
8
|
+
RESEARCH → PLAN → IMPLEMENT → VALIDATE
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## Iniciando uma feature
|
|
12
|
+
|
|
13
|
+
### Com slash commands
|
|
14
|
+
|
|
15
|
+
```
|
|
16
|
+
/sdd-research 001-nome-da-feature → produz RESEARCH.md
|
|
17
|
+
/sdd-plan 001-nome-da-feature → produz SPEC.md + TASK.md + TEST.md
|
|
18
|
+
/sdd-implement 001-nome-da-feature → implementa uma task por vez
|
|
19
|
+
/sdd-validate 001-nome-da-feature → produz VALIDATION.md
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
### Sem slash commands
|
|
23
|
+
|
|
24
|
+
Instrua seu agente em cada sessão:
|
|
25
|
+
|
|
26
|
+
```
|
|
27
|
+
"Leia e siga agents/prompts/rpi-research.md. Spec: 001-nome-da-feature"
|
|
28
|
+
"Leia e siga agents/prompts/rpi-plan.md. Spec: 001-nome-da-feature"
|
|
29
|
+
"Leia e siga agents/prompts/rpi-implement.md. Spec: 001-nome-da-feature"
|
|
30
|
+
"Leia e siga agents/prompts/rpi-validate.md. Spec: 001-nome-da-feature"
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
## Estrutura da spec após o ciclo completo
|
|
34
|
+
|
|
35
|
+
```
|
|
36
|
+
agents/specs/001-nome-da-feature/
|
|
37
|
+
RESEARCH.md ← fase 1
|
|
38
|
+
SPEC.md ← fase 2
|
|
39
|
+
TASK.md ← fase 2
|
|
40
|
+
TEST.md ← fase 2
|
|
41
|
+
PROGRESS.md ← atualizado na fase 3
|
|
42
|
+
DECISIONS.md ← decisões arquiteturais
|
|
43
|
+
VALIDATION.md ← fase 4
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
## Referências
|
|
47
|
+
|
|
48
|
+
- Regras do processo → `agents/RULES.md`
|
|
49
|
+
- Definição completa do workflow → `agents/AGENTS.md`
|
|
50
|
+
- Documentação → https://github.com/moisesuailab/spec-driven-workflow
|
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
# AGENTS.md
|
|
2
|
+
|
|
3
|
+
> This file is the full workflow definition. It is referenced by the root `AGENTS.md`.
|
|
4
|
+
> Do not modify the root file — extend rules here or in `RULES.md`.
|
|
5
|
+
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
## Agent Role
|
|
9
|
+
|
|
10
|
+
You are a senior developer working on this project. Your job is to execute tasks incrementally, in a controlled and traceable way, following the SDD cycle.
|
|
11
|
+
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
## Files to always read first
|
|
15
|
+
|
|
16
|
+
Before any action, read:
|
|
17
|
+
|
|
18
|
+
1. `agents/PROJECT.md` — stack, file structure, architecture patterns and stack rules
|
|
19
|
+
2. `agents/RULES.md` — mandatory process rules
|
|
20
|
+
3. `agents/DECISIONS.md` — architectural decisions already made
|
|
21
|
+
|
|
22
|
+
> Requirements (PRD or equivalent) are provided by the developer during the Research phase.
|
|
23
|
+
> From the Plan phase onward, `RESEARCH.md` replaces the PRD as the source of truth for that feature.
|
|
24
|
+
|
|
25
|
+
---
|
|
26
|
+
|
|
27
|
+
## SDD Cycle
|
|
28
|
+
|
|
29
|
+
Each phase runs in an **isolated session**. The artifact produced in each phase is the sole context for the next phase.
|
|
30
|
+
|
|
31
|
+
```
|
|
32
|
+
RESEARCH → PLAN → IMPLEMENT → VALIDATE
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
| Phase | Prompt | Reads | Produces |
|
|
36
|
+
|---|---|---|---|
|
|
37
|
+
| Research | `rpi-research.md` | `PROJECT.md` + `RULES.md` + requirements | `RESEARCH.md` |
|
|
38
|
+
| Plan | `rpi-plan.md` | `PROJECT.md` + `RULES.md` + `RESEARCH.md` | `SPEC.md` + `TASK.md` + `PROGRESS.md` + `TEST.md` |
|
|
39
|
+
| Implement | `rpi-implement.md` | `PROJECT.md` + `RULES.md` + `SPEC.md` + `TASK.md` + `PROGRESS.md` + relevant skill(s)¹ | code + updated `TASK.md` + updated `PROGRESS.md` |
|
|
40
|
+
| Validate | `rpi-validate.md` | `SPEC.md` + `TASK.md` + `TEST.md` + `PROGRESS.md` + produced code | `VALIDATION.md` |
|
|
41
|
+
|
|
42
|
+
> ¹ Run `grep -A 8 "## When to use" agents/skills/*/SKILL.md` to scan skill descriptions. Load the full `SKILL.md` only for skills relevant to the task.
|
|
43
|
+
|
|
44
|
+
---
|
|
45
|
+
|
|
46
|
+
## Spec Structure
|
|
47
|
+
|
|
48
|
+
```
|
|
49
|
+
agents/specs/NNN-feature-name/
|
|
50
|
+
RESEARCH.md — compressed understanding of the feature (produced in Research)
|
|
51
|
+
SPEC.md — functional requirements, business rules, UI section (produced in Plan)
|
|
52
|
+
TASK.md — task breakdown derived from the spec (produced in Plan)
|
|
53
|
+
PROGRESS.md — current execution state (produced in Plan, updated in Implement)
|
|
54
|
+
DECISIONS.md — feature-local decisions (updated as needed)
|
|
55
|
+
TEST.md — acceptance test cases in given/when/then format (produced in Plan)
|
|
56
|
+
VALIDATION.md — coverage matrix and approval status (produced in Validate)
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
---
|
|
60
|
+
|
|
61
|
+
## Before implementing a task
|
|
62
|
+
|
|
63
|
+
1. Read the feature's `SPEC.md`
|
|
64
|
+
2. Read `TASK.md` and identify the current task (first unchecked `[ ]`)
|
|
65
|
+
3. Read `PROGRESS.md` to understand the current state
|
|
66
|
+
4. Run `grep -A 8 "## When to use" agents/skills/*/SKILL.md` to read only the "When to use" section of each skill. Load the full `SKILL.md` only for skills relevant to this task.
|
|
67
|
+
5. If there is ambiguity, **ask before generating code**
|
|
68
|
+
|
|
69
|
+
---
|
|
70
|
+
|
|
71
|
+
## After implementing a task
|
|
72
|
+
|
|
73
|
+
1. Mark `[x]` on the task in `TASK.md`
|
|
74
|
+
2. Update `PROGRESS.md` with what was done and any observations
|
|
75
|
+
3. If an architectural decision was made, record it in `DECISIONS.md`
|
|
76
|
+
4. **Stop and wait for confirmation** before moving to the next task
|
|
77
|
+
|
|
78
|
+
---
|
|
79
|
+
|
|
80
|
+
## Behavioral rules
|
|
81
|
+
|
|
82
|
+
- Never implement more than one task at a time
|
|
83
|
+
- Never run git commands (commit, push, tag, branch)
|
|
84
|
+
- Never modify `agents/PROJECT.md` or `agents/RULES.md` without explicit request
|
|
85
|
+
- When in doubt about scope: ask, do not assume
|
|
86
|
+
- If a simpler approach exists than what is specified, mention it before implementing — never build in silence when a more direct solution is available
|
|
87
|
+
|
|
88
|
+
## Output Language
|
|
89
|
+
- Code and identifiers: English
|
|
90
|
+
- Agent explanations and responses: Portuguese (Brazil)
|
|
91
|
+
- Commit messages: English
|
|
92
|
+
- UI-facing strings (labels, messages, placeholders): Portuguese (Brazil)
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
# DECISIONS.md — Architectural Decisions Log
|
|
2
|
+
|
|
3
|
+
Append-only log of decisions with global impact on the project.
|
|
4
|
+
For decisions scoped to a single feature, use `agents/specs/NNN-*/DECISIONS.md`.
|
|
5
|
+
|
|
6
|
+
**Rule:** never delete or modify existing entries. Only append.
|
|
7
|
+
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## Format
|
|
11
|
+
|
|
12
|
+
```
|
|
13
|
+
### [YYYY-MM-DD] Decision title
|
|
14
|
+
**Context:** why this decision was needed
|
|
15
|
+
**Decision:** what was decided
|
|
16
|
+
**Consequences:** impacts and trade-offs
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
---
|
|
20
|
+
|
|
21
|
+
<!-- Record decisions below this line -->
|