sdd-flow 1.3.0 → 1.3.2

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
- 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 # 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
26
- sdd --version
27
- ```
28
-
29
- > Alias available: use `sdd` or `sdd-cli` — both work.
30
-
31
- ---
32
-
33
- ## After `init`
34
-
35
- Open a new session with your agent and instruct:
36
-
37
- ```
38
- "Read and follow agents/SETUP.md"
39
- ```
40
-
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
- ---
47
-
48
- ## Add or switch harness after init
49
-
50
- ```bash
51
- sdd harness
52
- ```
53
-
54
- Installs, replaces, or removes the harness and slash commands at any time.
55
-
56
- ---
57
-
58
- ## Update workflow (preserves your project data)
59
-
60
- ```bash
61
- sdd update
62
- ```
63
-
64
- Updates `AGENTS.md`, `RULES.md`, `QUICKSTART.md`, and all prompts. Your `PROJECT.md`, `DECISIONS.md`, `skills/`, `specs/`, and `harness/` are never touched.
65
-
66
- ---
67
-
68
- ## The RPI Cycle
69
-
70
- Each feature goes through four isolated phases, each in its own agent session:
71
-
72
- | Phase | Slash command | Prompt file |
73
- |---|---|---|
74
- | Research | `/sdd-research 001-feature` | `agents/prompts/rpi-research.md` |
75
- | Plan | `/sdd-plan 001-feature` | `agents/prompts/rpi-plan.md` |
76
- | Implement | `/sdd-implement 001-feature` | `agents/prompts/rpi-implement.md` |
77
- | Validate | `/sdd-validate 001-feature` | `agents/prompts/rpi-validate.md` |
78
-
79
- > Slash commands require harness installation (`sdd harness`).
80
-
81
- ---
82
-
83
- ## Source
84
-
85
- [github.com/moisesuailab/spec-driven-workflow](https://github.com/moisesuailab/spec-driven-workflow)
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 | Verified `PROGRESS.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/bin/cli.js CHANGED
@@ -183,6 +183,7 @@ async function init() {
183
183
  if (!shouldVersion) {
184
184
  ok('Arquivos adicionados a .git/info/exclude');
185
185
  warn('Outros desenvolvedores no projeto não terão esses arquivos.');
186
+ info('Rode ' + bold('git status') + ' no terminal para atualizar a visualização do editor.');
186
187
  }
187
188
 
188
189
  log();
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "sdd-flow",
3
- "version": "1.3.0",
3
+ "version": "1.3.2",
4
4
  "description": "Spec Driven Development workflow for AI-assisted development (SDD + RPI)",
5
5
  "bin": {
6
6
  "sdd-cli": "bin/cli.js",
@@ -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.
@@ -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` — confirm all tasks are marked `[x]`
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 — Confirm implementation is complete
29
- Check that every task in `TASK.md` is marked `[x]`.
30
- If any `[ ]` remains, **stop and report** — do not proceed with validation.
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