sdd-flow 1.0.0 → 1.2.5

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/README.md CHANGED
@@ -19,32 +19,43 @@ npm install -g sdd-flow
19
19
  ## Usage
20
20
 
21
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
22
+ sdd init # Installs the workflow into the current project
23
+ sdd new <name> # Creates a spec folder with auto-numbering
24
+ sdd harness # Installs, switches, or removes the agent harness
25
+ sdd update # Updates prompts and rules, preserves project data
25
26
  sdd --version
26
27
  ```
27
28
 
28
- > Alias disponível: use `sdd` ou `sdd-cli` — ambos funcionam.
29
+ > Alias available: use `sdd` or `sdd-cli` — both work.
29
30
 
30
- ### New or existing project
31
+ ---
31
32
 
32
- ```bash
33
- cd my-project
34
- sdd init
33
+ ## After `init`
34
+
35
+ Open a new session with your agent and instruct:
36
+
37
+ ```
38
+ "Read and follow agents/SETUP.md"
35
39
  ```
36
40
 
37
- Installs the `agents/` folder with all workflow files. Optionally installs safety hooks and slash commands for your agent (Claude Code or OpenCode).
41
+ - **New project:** describe the project or provide a PRD — the agent generates PROJECT.md and skills
42
+ - **Existing project:** the agent scans the codebase automatically
43
+
44
+ Review the generated files and delete `agents/SETUP.md`.
45
+
46
+ ---
38
47
 
39
- ### Add or switch harness after init
48
+ ## Add or switch harness after init
40
49
 
41
50
  ```bash
42
51
  sdd harness
43
52
  ```
44
53
 
45
- Installs, replaces, or removes the harness and slash commands at any time — no need to reinstall the package.
54
+ Installs, replaces, or removes the harness and slash commands at any time.
55
+
56
+ ---
46
57
 
47
- ### Update workflow (preserves your project data)
58
+ ## Update workflow (preserves your project data)
48
59
 
49
60
  ```bash
50
61
  sdd update
@@ -54,15 +65,6 @@ Updates `AGENTS.md`, `RULES.md`, `QUICKSTART.md`, and all prompts. Your `PROJECT
54
65
 
55
66
  ---
56
67
 
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
68
  ## The RPI Cycle
67
69
 
68
70
  Each feature goes through four isolated phases, each in its own agent session:
package/bin/cli.js CHANGED
@@ -134,8 +134,9 @@ async function init() {
134
134
  log(bold('Próximos passos:'));
135
135
  log(` ${c.cyan}1.${c.reset} Abra uma sessão do seu agente no projeto`);
136
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`);
137
+ log(` ${dim('→ Projeto novo: descreva o projeto ou forneça o PRD')}`);
138
+ log(` ${dim('→ Projeto existente: o agente escaneia o código automaticamente')}`);
139
+ log(` ${c.cyan}3.${c.reset} Revise os arquivos gerados e delete agents/SETUP.md`);
139
140
  log();
140
141
 
141
142
  if (harnessInstalled) {
@@ -267,18 +268,80 @@ async function update() {
267
268
  log();
268
269
  }
269
270
 
271
+ function nextSpecNumber(specsDir) {
272
+ if (!fs.existsSync(specsDir)) return '001';
273
+ const entries = fs.readdirSync(specsDir, { withFileTypes: true })
274
+ .filter(e => e.isDirectory())
275
+ .map(e => parseInt(e.name.slice(0, 3), 10))
276
+ .filter(n => !isNaN(n));
277
+ const max = entries.length ? Math.max(...entries) : 0;
278
+ return String(max + 1).padStart(3, '0');
279
+ }
280
+
281
+ function newSpec(rawName) {
282
+ log();
283
+ log(bold('sdd new'));
284
+ log();
285
+
286
+ const agentsDir = path.join(CWD, 'agents');
287
+ if (!fs.existsSync(agentsDir)) {
288
+ error('Pasta agents/ não encontrada. Rode ' + bold('sdd init') + ' primeiro.');
289
+ log();
290
+ process.exit(1);
291
+ }
292
+
293
+ if (!rawName) {
294
+ error('Informe o nome da feature: ' + bold('sdd new <nome-da-feature>'));
295
+ log(' Exemplo: ' + dim('sdd new user-authentication'));
296
+ log();
297
+ process.exit(1);
298
+ }
299
+
300
+ const name = rawName.toLowerCase().trim().replace(/\s+/g, '-').replace(/[^a-z0-9-]/g, '');
301
+ if (!name) {
302
+ error('Nome inválido. Use apenas letras, números e hífens.');
303
+ log();
304
+ process.exit(1);
305
+ }
306
+
307
+ const specsDir = path.join(agentsDir, 'specs');
308
+ const num = nextSpecNumber(specsDir);
309
+ const slug = num + '-' + name;
310
+ const specDir = path.join(specsDir, slug);
311
+
312
+ if (fs.existsSync(specDir)) {
313
+ error('Spec já existe: agents/specs/' + slug + '/');
314
+ log();
315
+ process.exit(1);
316
+ }
317
+
318
+ fs.mkdirSync(specDir, { recursive: true });
319
+ fs.writeFileSync(
320
+ path.join(specDir, 'DECISIONS.md'),
321
+ '# DECISIONS — ' + name + '\n\n(decisões arquiteturais registradas durante o ciclo)\n'
322
+ );
323
+
324
+ ok('Spec criada: agents/specs/' + slug + '/');
325
+ log();
326
+ log(bold('Próximo passo — inicie a fase de Research:'));
327
+ log(' ' + c.cyan + '/sdd-research' + c.reset + ' ' + slug);
328
+ log(' ' + dim('"Leia e siga agents/prompts/rpi-research.md. Spec: ' + slug + '"'));
329
+ log();
330
+ }
331
+
270
332
  function help() {
271
333
  log();
272
334
  log(bold('sdd-cli') + dim(' — Spec Driven Development workflow'));
273
335
  log();
274
336
  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`);
337
+ log(` sdd-cli ${c.cyan}init${c.reset} Instala o workflow no projeto atual`);
338
+ log(` sdd-cli ${c.cyan}new <nome>${c.reset} Cria pasta da spec com numeração automática`);
339
+ log(` sdd-cli ${c.cyan}harness${c.reset} Instala, troca ou remove o harness do agente`);
340
+ log(` sdd-cli ${c.cyan}update${c.reset} Atualiza prompts e regras, preserva dados do projeto`);
341
+ log(` sdd-cli ${c.cyan}help${c.reset} Exibe esta mensagem`);
342
+ log(` sdd-cli ${c.cyan}--version${c.reset} Exibe a versão instalada`);
280
343
  log();
281
- log(dim(' Alias: sdd init / sdd harness / sdd update / sdd help / sdd --version'));
344
+ log(dim(' Alias: sdd init / sdd new / sdd harness / sdd update / sdd help / sdd --version'));
282
345
  log();
283
346
  log(dim(' Documentação: https://github.com/moisesuailab/spec-driven-workflow'));
284
347
  log();
@@ -290,6 +353,9 @@ switch (cmd) {
290
353
  case 'init':
291
354
  init().catch(e => { error(e.message); process.exit(1); });
292
355
  break;
356
+ case 'new':
357
+ newSpec(process.argv[3]);
358
+ break;
293
359
  case 'harness':
294
360
  harness().catch(e => { error(e.message); process.exit(1); });
295
361
  break;
package/package.json CHANGED
@@ -1,32 +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
- }
1
+ {
2
+ "name": "sdd-flow",
3
+ "version": "1.2.5",
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/sdd-flow.git"
31
+ }
32
+ }
@@ -1,50 +1,70 @@
1
- # SDD Workflow — Quick Start
1
+ # SDD Workflow - Quick Start
2
2
 
3
- ## Ciclo
3
+ ## Cycle
4
4
 
5
- Cada feature passa por 4 fases em sessões isoladas:
5
+ Each feature goes through 4 phases in isolated sessions:
6
6
 
7
7
  ```
8
8
  RESEARCH → PLAN → IMPLEMENT → VALIDATE
9
9
  ```
10
10
 
11
- ## Iniciando uma feature
11
+ ## Initial setup
12
12
 
13
- ### Com slash commands
13
+ After running `sdd init`, open your agent in the project and instruct:
14
14
 
15
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
16
+ "Read and follow agents/SETUP.md"
20
17
  ```
21
18
 
22
- ### Sem slash commands
19
+ - **New project:** describe the project or provide the PRD — the agent generates PROJECT.md and the skills
20
+ - **Existing project:** the agent scans the code automatically
23
21
 
24
- Instrua seu agente em cada sessão:
22
+ Review the generated files and delete `agents/SETUP.md`.
25
23
 
24
+ ## Starting a feature
25
+
26
+ ### With slash commands
27
+
28
+ ```
29
+ /sdd-research 001-feature-name → produces RESEARCH.md
30
+ /sdd-plan 001-feature-name → produces SPEC.md + TASK.md + TEST.md
31
+ /sdd-implement 001-feature-name → implements one task at a time
32
+ /sdd-validate 001-feature-name → produces VALIDATION.md
33
+ ```
34
+
35
+ ### Without slash commands
36
+
37
+ Instruct your agent in each session:
38
+
39
+ ```
40
+ "Read and follow agents/prompts/rpi-research.md. Spec: 001-feature-name"
41
+ "Read and follow agents/prompts/rpi-plan.md. Spec: 001-feature-name"
42
+ "Read and follow agents/prompts/rpi-implement.md. Spec: 001-feature-name"
43
+ "Read and follow agents/prompts/rpi-validate.md. Spec: 001-feature-name"
26
44
  ```
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"
45
+
46
+ ## Creating a new spec
47
+
48
+ ```bash
49
+ sdd new feature-name
50
+ # ✔ Spec created: agents/specs/001-feature-name/
31
51
  ```
32
52
 
33
- ## Estrutura da spec após o ciclo completo
53
+ ## Spec structure after the full cycle
34
54
 
35
55
  ```
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
56
+ agents/specs/001-feature-name/
57
+ RESEARCH.md ← phase 1
58
+ SPEC.md ← phase 2
59
+ TASK.md ← phase 2
60
+ TEST.md ← phase 2
61
+ PROGRESS.md ← updated in phase 3
62
+ DECISIONS.md ← architectural decisions
63
+ VALIDATION.md ← phase 4
44
64
  ```
45
65
 
46
- ## Referências
66
+ ## References
47
67
 
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
68
+ - Process rules → `agents/RULES.md`
69
+ - Full workflow definition → `agents/AGENTS.md`
70
+ - Documentation → https://github.com/moisesuailab/sdd-flow
@@ -1,92 +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)
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)