sdd-flow 1.3.1 → 1.3.3
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
|
@@ -1,85 +1,168 @@
|
|
|
1
|
-
# sdd-flow
|
|
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
|
-
sdd
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
1
|
+
# sdd-flow
|
|
2
|
+
|
|
3
|
+
> A spec-driven workflow for AI-assisted development — installed in seconds, works with any agent.
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
npm install -g sdd-flow
|
|
7
|
+
sdd init
|
|
8
|
+
```
|
|
9
|
+
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
## Why sdd-flow exists
|
|
13
|
+
|
|
14
|
+
AI agents drift. A session that starts well ends with the agent ignoring the spec, inventing APIs, and refactoring things you didn't ask it to touch. The usual fix — better prompts, more context — doesn't scale.
|
|
15
|
+
|
|
16
|
+
**sdd-flow takes a different approach: phase isolation.**
|
|
17
|
+
|
|
18
|
+
Every feature goes through four phases. Each phase runs in its own agent session and receives only the artifact from the previous phase — not the full conversation history. Context stays lean. The agent reads the spec fresh every session and can't drift from what it hasn't accumulated.
|
|
19
|
+
|
|
20
|
+
This is a workflow for developers who want to stay in control of what gets built and why.
|
|
21
|
+
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
## The RPIV Cycle
|
|
25
|
+
|
|
26
|
+
```
|
|
27
|
+
Requirements
|
|
28
|
+
│
|
|
29
|
+
▼
|
|
30
|
+
┌────────────┐ new session ┌────────────┐ new session ┌─────────────┐ new session ┌────────────┐
|
|
31
|
+
│ RESEARCH │ ────────────▶ │ PLAN │ ────────────▶ │ IMPLEMENT │ ────────────▶ │ VALIDATE │
|
|
32
|
+
│ │ │ │ │ │ │ │
|
|
33
|
+
│ RESEARCH │ │ SPEC.md │ │ Code │ │ Verified │
|
|
34
|
+
│ .md │ │ TASK.md │ │ TASK.md ✓ │ │ PROGRESS │
|
|
35
|
+
│ │ │ TEST.md │ │ (one task, │ │ .md │
|
|
36
|
+
│ │ │ PROGRESS │ │ then stop) │ │ │
|
|
37
|
+
└────────────┘ └────────────┘ └─────────────┘ └────────────┘
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
Each arrow is a phase boundary. The agent starts fresh. Only the artifact passes through.
|
|
41
|
+
|
|
42
|
+
| Phase | Input | Output |
|
|
43
|
+
|-------|-------|--------|
|
|
44
|
+
| 🔍 **Research** | Your requirements | `RESEARCH.md` |
|
|
45
|
+
| 📐 **Plan** | `RESEARCH.md` | `SPEC.md` + `TASK.md` + `TEST.md` |
|
|
46
|
+
| 🔨 **Implement** | `SPEC.md` + `TASK.md` | Code + updated `TASK.md` |
|
|
47
|
+
| ✅ **Validate** | `TEST.md` + codebase | `VALIDATION.md` |
|
|
48
|
+
|
|
49
|
+
> The agent stops after each task in the Implement phase and waits for your review. One task, one diff, one decision at a time.
|
|
50
|
+
|
|
51
|
+
---
|
|
52
|
+
|
|
53
|
+
## Quick Start
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
# Install
|
|
57
|
+
npm install -g sdd-flow
|
|
58
|
+
|
|
59
|
+
# Set up in your project
|
|
60
|
+
cd your-project
|
|
61
|
+
sdd init
|
|
62
|
+
|
|
63
|
+
# Create your first feature spec
|
|
64
|
+
sdd new user-auth # creates agents/specs/001-user-auth/
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
Open a new agent session and say:
|
|
68
|
+
|
|
69
|
+
```
|
|
70
|
+
Read and follow agents/SETUP.md
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
The agent scans your project (or reads your PRD) and generates `PROJECT.md`, `DECISIONS.md`, and a `skills/` directory tailored to your stack. Review the files, then delete `agents/SETUP.md`. You're ready.
|
|
74
|
+
|
|
75
|
+
---
|
|
76
|
+
|
|
77
|
+
## Running a Feature
|
|
78
|
+
|
|
79
|
+
### Without harness — any editor
|
|
80
|
+
|
|
81
|
+
```
|
|
82
|
+
# Session 1 — Research
|
|
83
|
+
"Read and follow agents/prompts/rpi-research.md"
|
|
84
|
+
|
|
85
|
+
# Session 2 — Plan
|
|
86
|
+
"Read and follow agents/prompts/rpi-plan.md. Spec at agents/specs/001-user-auth/"
|
|
87
|
+
|
|
88
|
+
# Session 3 — Implement
|
|
89
|
+
"Read and follow agents/prompts/rpi-implement.md. Spec at agents/specs/001-user-auth/"
|
|
90
|
+
|
|
91
|
+
# Session 4 — Validate
|
|
92
|
+
"Read and follow agents/prompts/rpi-validate.md. Spec at agents/specs/001-user-auth/"
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
### With harness — Claude Code / OpenCode
|
|
96
|
+
|
|
97
|
+
```bash
|
|
98
|
+
sdd harness # installs slash commands
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
```
|
|
102
|
+
/sdd-research 001-user-auth
|
|
103
|
+
/sdd-plan 001-user-auth
|
|
104
|
+
/sdd-implement 001-user-auth
|
|
105
|
+
/sdd-validate 001-user-auth
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
---
|
|
109
|
+
|
|
110
|
+
## Commands
|
|
111
|
+
|
|
112
|
+
```bash
|
|
113
|
+
sdd init # install the workflow into the current project
|
|
114
|
+
sdd new <name> # create a numbered spec folder (001-, 002-, ...)
|
|
115
|
+
sdd harness # install, switch, or remove slash commands
|
|
116
|
+
sdd update # update prompts and rules — never touches your specs or decisions
|
|
117
|
+
sdd --version
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
---
|
|
121
|
+
|
|
122
|
+
## What gets installed
|
|
123
|
+
|
|
124
|
+
```
|
|
125
|
+
agents/
|
|
126
|
+
├── AGENTS.md ← agent role and SDD rules (read every session)
|
|
127
|
+
├── RULES.md ← behavioral constraints (no rogue git, no scope creep)
|
|
128
|
+
├── PROJECT.md ← your stack and conventions (auto-generated on setup)
|
|
129
|
+
├── DECISIONS.md ← append-only architectural decisions log
|
|
130
|
+
├── SETUP.md ← first-run only (delete after setup)
|
|
131
|
+
├── prompts/ ← one file per phase + utility prompts
|
|
132
|
+
├── skills/ ← capability files auto-generated for your stack
|
|
133
|
+
└── specs/
|
|
134
|
+
└── 001-user-auth/
|
|
135
|
+
├── RESEARCH.md
|
|
136
|
+
├── SPEC.md
|
|
137
|
+
├── TASK.md
|
|
138
|
+
├── PROGRESS.md
|
|
139
|
+
└── TEST.md
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
> `sdd update` only touches `AGENTS.md`, `RULES.md`, and `prompts/`.
|
|
143
|
+
> Your specs, decisions, and skills are never modified.
|
|
144
|
+
|
|
145
|
+
---
|
|
146
|
+
|
|
147
|
+
## Works with any stack
|
|
148
|
+
|
|
149
|
+
sdd-flow operates at the spec level, not the code level. JavaScript, TypeScript, Python, Java, Go, PHP — the agent adapts to your stack during setup. No framework assumptions, no extra API keys, no additional costs beyond what you already use.
|
|
150
|
+
|
|
151
|
+
---
|
|
152
|
+
|
|
153
|
+
## Compatible editors
|
|
154
|
+
|
|
155
|
+
Claude Code · OpenCode · Cursor · Windsurf · Codex CLI · any IDE with filesystem access
|
|
156
|
+
|
|
157
|
+
---
|
|
158
|
+
|
|
159
|
+
## Workflow template
|
|
160
|
+
|
|
161
|
+
The prompts and rules installed by `sdd-flow` are maintained at:
|
|
162
|
+
[github.com/moisesuailab/spec-driven-workflow](https://github.com/moisesuailab/spec-driven-workflow)
|
|
163
|
+
|
|
164
|
+
---
|
|
165
|
+
|
|
166
|
+
## License
|
|
167
|
+
|
|
168
|
+
MIT
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "sdd-flow",
|
|
3
|
-
"version": "1.3.
|
|
4
|
-
"description": "Spec Driven Development workflow for AI-assisted development (SDD +
|
|
3
|
+
"version": "1.3.3",
|
|
4
|
+
"description": "Spec Driven Development workflow for AI-assisted development (SDD + RPIV)",
|
|
5
5
|
"bin": {
|
|
6
6
|
"sdd-cli": "bin/cli.js",
|
|
7
7
|
"sdd": "bin/cli.js"
|
|
@@ -16,7 +16,7 @@
|
|
|
16
16
|
"keywords": [
|
|
17
17
|
"sdd",
|
|
18
18
|
"spec-driven-development",
|
|
19
|
-
"
|
|
19
|
+
"rpiv",
|
|
20
20
|
"ai-workflow",
|
|
21
21
|
"claude-code",
|
|
22
22
|
"opencode",
|
package/templates/AGENTS.md
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# Agent Instructions
|
|
2
2
|
|
|
3
|
-
This project uses **Spec Driven Development (SDD)** with the **Research → Plan → Implement (
|
|
4
|
-
methodology. Every feature goes through
|
|
3
|
+
This project uses **Spec Driven Development (SDD)** with the **Research → Plan → Implement → Validate (RPIV)**
|
|
4
|
+
methodology. Every feature goes through four isolated phases, each in its own agent session.
|
|
5
5
|
|
|
6
6
|
---
|
|
7
7
|
|
|
@@ -35,12 +35,13 @@ When a spec folder is provided, read `SPEC.md` and `TASK.md` before implementing
|
|
|
35
35
|
|
|
36
36
|
---
|
|
37
37
|
|
|
38
|
-
##
|
|
38
|
+
## RPIV prompts
|
|
39
39
|
|
|
40
40
|
Full prompts for each phase are in `agents/prompts/`. Use them by reading the relevant file:
|
|
41
41
|
- Phase 1 — Research: `agents/prompts/rpi-research.md`
|
|
42
42
|
- Phase 2 — Plan: `agents/prompts/rpi-plan.md`
|
|
43
43
|
- Phase 3 — Implement: `agents/prompts/rpi-implement.md`
|
|
44
|
+
- Phase 4 — Validate: `agents/prompts/rpi-validate.md`
|
|
44
45
|
|
|
45
46
|
---
|
|
46
47
|
|
|
@@ -114,3 +114,19 @@ Every generated code must follow:
|
|
|
114
114
|
If a requirement has multiple valid interpretations, list them explicitly
|
|
115
115
|
before choosing one. Never pick silently. If the ambiguity blocks progress,
|
|
116
116
|
stop and ask before generating any code.
|
|
117
|
+
|
|
118
|
+
---
|
|
119
|
+
|
|
120
|
+
### R15 — New work during Implement: add task or new spec?
|
|
121
|
+
|
|
122
|
+
When unexpected work emerges during the Implement phase, apply this decision table:
|
|
123
|
+
|
|
124
|
+
| Condition | Action |
|
|
125
|
+
|---|---|
|
|
126
|
+
| Modifies files already in this spec's scope | Add task to current `TASK.md` |
|
|
127
|
+
| Small gap or planning oversight | Add task to current `TASK.md` |
|
|
128
|
+
| New module, entity, or feature goal not in `SPEC.md` | Create new spec |
|
|
129
|
+
| Explicitly listed in `SPEC.md` "Out of scope" section | Create new spec |
|
|
130
|
+
| Crosses a domain boundary | Create new spec |
|
|
131
|
+
|
|
132
|
+
**Never decide silently.** Always stop, describe the emerging work, apply the table, state the chosen action with justification, and wait for developer confirmation before proceeding.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Agents Template — Setup Guide
|
|
2
2
|
|
|
3
|
-
This template implements the **SDD (Spec Driven Development)** workflow using the **
|
|
3
|
+
This template implements the **SDD (Spec Driven Development)** workflow using the **RPIV (Research → Plan → Implement → Validate)** methodology. It is LLM-agnostic and stack-agnostic.
|
|
4
4
|
|
|
5
5
|
> After completing setup, delete this file from the project.
|
|
6
6
|
|
|
@@ -192,7 +192,7 @@ chmod +x agents/harness/claude-code/.hooks/*.sh
|
|
|
192
192
|
|
|
193
193
|
### Step 5 — Validate Before First Spec
|
|
194
194
|
|
|
195
|
-
Before starting the first
|
|
195
|
+
Before starting the first RPIV cycle, confirm:
|
|
196
196
|
|
|
197
197
|
- [ ] Root `AGENTS.md` is present and unmodified
|
|
198
198
|
- [ ] `agents/PROJECT.md` has no `[FILL: ...]` placeholders remaining
|
|
@@ -209,7 +209,7 @@ When setup is complete:
|
|
|
209
209
|
|
|
210
210
|
1. Create the folder: `agents/specs/001-feature-name/`
|
|
211
211
|
2. Run the Research phase using `agents/prompts/rpi-research.md`
|
|
212
|
-
3. Follow the
|
|
212
|
+
3. Follow the RPIV cycle through to validation
|
|
213
213
|
|
|
214
214
|
---
|
|
215
215
|
|
|
@@ -33,10 +33,32 @@ You will implement **one single task** from an already planned feature.
|
|
|
33
33
|
- Mark `[x]` on the task in TASK.md
|
|
34
34
|
- Update PROGRESS.md with what was done and any observations
|
|
35
35
|
- Record relevant architectural decisions in DECISIONS.md
|
|
36
|
+
- **Check TEST.md for impact** — if any test case covers behavior changed by this task:
|
|
37
|
+
- Update the affected test case(s) in TEST.md if the expected behavior changed
|
|
38
|
+
- Record in PROGRESS.md which test cases were affected and why
|
|
39
|
+
- If VALIDATION.md exists and covers those cases, mark the affected rows as `⚠️ Needs re-validation`
|
|
36
40
|
5. **Stop and wait for confirmation** before moving to the next task
|
|
37
41
|
|
|
38
42
|
---
|
|
39
43
|
|
|
44
|
+
## Emerging scope
|
|
45
|
+
|
|
46
|
+
If unexpected work is discovered during implementation, apply **R15** before continuing:
|
|
47
|
+
|
|
48
|
+
1. Describe the emerging work in one sentence
|
|
49
|
+
2. Apply the decision table:
|
|
50
|
+
- Modifies files already in this spec's scope → add task to current `TASK.md`
|
|
51
|
+
- Small gap or planning oversight → add task to current `TASK.md`
|
|
52
|
+
- New module, entity, or feature goal not in `SPEC.md` → new spec
|
|
53
|
+
- Explicitly in `SPEC.md` "Out of scope" → new spec
|
|
54
|
+
- Crosses a domain boundary → new spec
|
|
55
|
+
3. State the chosen action with justification
|
|
56
|
+
4. **Stop and wait for developer confirmation** before proceeding
|
|
57
|
+
|
|
58
|
+
Never decide silently. Never create a new spec or add a task without surfacing the decision first.
|
|
59
|
+
|
|
60
|
+
---
|
|
61
|
+
|
|
40
62
|
## Constraints
|
|
41
63
|
|
|
42
64
|
- Do not anticipate future tasks
|
|
@@ -13,7 +13,7 @@ You will validate the implementation of a completed feature against its spec and
|
|
|
13
13
|
- `agents/PROJECT.md`
|
|
14
14
|
- `agents/RULES.md`
|
|
15
15
|
- `agents/specs/NNN-name/SPEC.md`
|
|
16
|
-
- `agents/specs/NNN-name/TASK.md` —
|
|
16
|
+
- `agents/specs/NNN-name/TASK.md` — identify which tasks are complete `[x]` and which are pending `[ ]`
|
|
17
17
|
- `agents/specs/NNN-name/TEST.md`
|
|
18
18
|
- `agents/specs/NNN-name/PROGRESS.md`
|
|
19
19
|
- The code files produced during Implement (listed in PROGRESS.md History)
|
|
@@ -25,9 +25,13 @@ You will validate the implementation of a completed feature against its spec and
|
|
|
25
25
|
|
|
26
26
|
## Validation procedure
|
|
27
27
|
|
|
28
|
-
### Step 1 —
|
|
29
|
-
|
|
30
|
-
|
|
28
|
+
### Step 1 — Determine validation scope
|
|
29
|
+
Validation may be requested at any time — it does not require all tasks to be complete.
|
|
30
|
+
|
|
31
|
+
- If all tasks are `[x]`: full validation — cover every task and every test case in TEST.md
|
|
32
|
+
- If some tasks are still `[ ]`: partial validation — scope to completed tasks only; explicitly list which tasks and test cases are **out of scope** in VALIDATION.md
|
|
33
|
+
|
|
34
|
+
Never block validation because tasks are pending. Report the scope clearly instead.
|
|
31
35
|
|
|
32
36
|
### Step 2 — Verify task-level conditions
|
|
33
37
|
For each task in `TASK.md`, read its `verify:` condition and check whether
|
|
@@ -49,6 +53,9 @@ Write `agents/specs/NNN-name/VALIDATION.md` with the structure below.
|
|
|
49
53
|
|
|
50
54
|
## Status: [✅ Approved | ⚠️ Partial | ❌ Failed]
|
|
51
55
|
|
|
56
|
+
## Scope
|
|
57
|
+
[Full — all tasks complete] or [Partial — tasks T01..TNN validated; TXX..TYY pending implementation]
|
|
58
|
+
|
|
52
59
|
---
|
|
53
60
|
|
|
54
61
|
## Task Verification
|