sddx-workflow 0.6.0 → 0.7.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/README.md +58 -40
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,8 +1,12 @@
|
|
|
1
1
|
# sddx-workflow
|
|
2
2
|
|
|
3
|
+
[](https://www.npmjs.com/package/sddx-workflow)
|
|
4
|
+
[](https://nodejs.org)
|
|
5
|
+
[](LICENSE)
|
|
6
|
+
|
|
3
7
|
Spec-Driven Development CLI for AI-assisted projects. Installs a structured workflow system that guides AI agents (Claude, Cursor, Copilot) through planning, execution, and review — without letting them run loose.
|
|
4
8
|
|
|
5
|
-
Works with any project: Next.js, Python, React, Django, Go, Rails
|
|
9
|
+
Works with any project: Next.js, Python, React, Django, Go, Rails.
|
|
6
10
|
|
|
7
11
|
```bash
|
|
8
12
|
npx sddx-workflow init
|
|
@@ -10,91 +14,97 @@ npx sddx-workflow init
|
|
|
10
14
|
|
|
11
15
|
---
|
|
12
16
|
|
|
13
|
-
##
|
|
17
|
+
## Why this exists
|
|
14
18
|
|
|
15
19
|
AI agents tend to implement without validating assumptions, refactor more than asked, and don't have a mental model of when to stop and ask for approval. This system enforces explicit ceremony levels and stop points.
|
|
16
20
|
|
|
17
21
|
---
|
|
18
22
|
|
|
19
|
-
##
|
|
23
|
+
## Quick start
|
|
20
24
|
|
|
21
25
|
```bash
|
|
22
|
-
# Initialize in
|
|
26
|
+
# 1. Initialize the workflow in your project
|
|
23
27
|
npx sddx-workflow init
|
|
24
28
|
|
|
25
|
-
#
|
|
26
|
-
|
|
29
|
+
# 2. Populate project context (run with your AI agent)
|
|
30
|
+
/bootstrap
|
|
31
|
+
|
|
32
|
+
# 3. Build a feature
|
|
33
|
+
/spec-new # scaffold a spec folder
|
|
34
|
+
/spec-plan # generate a technical plan — stops for your approval
|
|
35
|
+
/spec-tasks # execute one atomic task at a time
|
|
36
|
+
/finish # stage files + generate a conventional commit
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
---
|
|
40
|
+
|
|
41
|
+
## CLI reference
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
npx sddx-workflow init # Initialize in current project
|
|
45
|
+
npx sddx-workflow init --force # Overwrite existing files
|
|
27
46
|
|
|
28
|
-
# Add a domain file
|
|
29
|
-
npx sddx-workflow add domain auth
|
|
47
|
+
npx sddx-workflow add domain auth # Add a domain file
|
|
30
48
|
npx sddx-workflow add domain payments
|
|
31
49
|
npx sddx-workflow add domain storage
|
|
32
50
|
npx sddx-workflow add domain email
|
|
51
|
+
|
|
52
|
+
npx sddx-workflow status # Show current workflow state
|
|
53
|
+
npx sddx-workflow update # Update workflow templates
|
|
33
54
|
```
|
|
34
55
|
|
|
35
|
-
Files are **copied locally** — your project owns them. No runtime dependency. Edit
|
|
56
|
+
Files are **copied locally** — your project owns them. No runtime dependency. Edit freely.
|
|
36
57
|
|
|
37
58
|
---
|
|
38
59
|
|
|
39
|
-
##
|
|
60
|
+
## Generated structure
|
|
40
61
|
|
|
41
62
|
```
|
|
42
63
|
.sdd/
|
|
43
64
|
workflow.md # Commands, ceremony levels, stop points
|
|
44
|
-
project-overview.md # What this app is
|
|
45
|
-
conventions.md # Stack and patterns
|
|
65
|
+
project-overview.md # What this app is — populated by /bootstrap
|
|
66
|
+
conventions.md # Stack and patterns — populated by /bootstrap
|
|
46
67
|
domains/ # Domain-specific rules (auth, payments, etc.)
|
|
47
68
|
specs/
|
|
48
69
|
_template/
|
|
49
70
|
1-requirements.md # Problem, goals, acceptance criteria (BDD)
|
|
50
71
|
2-plan.md # Technical plan — requires approval before coding
|
|
51
72
|
3-tasks.md # Atomic task checklist with TDD gate
|
|
52
|
-
CLAUDE.md #
|
|
73
|
+
CLAUDE.md # Agent entry point — points to .sdd/
|
|
53
74
|
```
|
|
54
75
|
|
|
55
76
|
---
|
|
56
77
|
|
|
57
|
-
##
|
|
58
|
-
|
|
59
|
-
Run `/bootstrap` with your AI agent to populate the project context:
|
|
60
|
-
|
|
61
|
-
- **New project** — the agent interviews you with 6 targeted questions (problem, stack, non-goals, architecture decisions, domains, definition of done) and writes `.sdd/project-overview.md` and `.sdd/conventions.md`
|
|
62
|
-
- **Existing project** — run `/bootstrap --scan` and the agent reads your codebase first, infers what it can, then asks only about what the code can't answer
|
|
63
|
-
|
|
64
|
-
The agent presents a full draft for your approval before writing anything.
|
|
65
|
-
|
|
66
|
-
---
|
|
67
|
-
|
|
68
|
-
## Workflow commands
|
|
78
|
+
## Agent commands
|
|
69
79
|
|
|
70
80
|
| Command | Purpose |
|
|
71
81
|
|---|---|
|
|
72
|
-
| `/bootstrap` | Populate project context
|
|
82
|
+
| `/bootstrap` | Populate project context via interview or codebase scan |
|
|
73
83
|
| `/ask` | Research and exploration — no code changes |
|
|
74
|
-
| `/assume` | Surface all assumptions before acting
|
|
84
|
+
| `/assume` | Surface all assumptions before acting |
|
|
75
85
|
| `/bugfix` | Reproduce → diagnose → fix → validate |
|
|
76
|
-
| `/refactor` | Restructure without behavior change
|
|
86
|
+
| `/refactor` | Restructure without behavior change (green baseline required) |
|
|
77
87
|
| `/spec-new` | Scaffold a spec folder for a feature |
|
|
78
88
|
| `/spec-plan` | Generate technical plan — **stops for approval before any code** |
|
|
79
89
|
| `/spec-tasks` | Execute plan one atomic task at a time, TDD-first |
|
|
80
|
-
| `/review` | Final audit — verifies goals,
|
|
81
|
-
| `/finish` | Stage files
|
|
90
|
+
| `/review` | Final audit — verifies goals, no scope creep |
|
|
91
|
+
| `/finish` | Stage files + generate conventional commit message |
|
|
82
92
|
|
|
83
93
|
### Ceremony levels
|
|
84
94
|
|
|
85
|
-
| Change | Flow |
|
|
95
|
+
| Change type | Flow |
|
|
86
96
|
|---|---|
|
|
87
97
|
| Typo / comment | Direct |
|
|
88
98
|
| Bug | `/bugfix` → `/finish` |
|
|
89
99
|
| Refactor | `/refactor` → `/finish` |
|
|
90
100
|
| Feature | `/spec-new` → `/spec-plan` → `/spec-tasks` → `/review` → `/finish` |
|
|
91
|
-
| Architecture | `/spec-new` → `/spec-plan` (mandatory
|
|
101
|
+
| Architecture | `/spec-new` → `/spec-plan` (mandatory review) → `/spec-tasks` → `/review` → `/finish` |
|
|
92
102
|
|
|
93
103
|
---
|
|
94
104
|
|
|
95
105
|
## Execution principles
|
|
96
106
|
|
|
97
|
-
|
|
107
|
+
Enforced by every command:
|
|
98
108
|
|
|
99
109
|
1. **Surface assumptions** — list them before acting, not mid-execution
|
|
100
110
|
2. **Minimum code** — only what was asked; no "while I'm here" changes
|
|
@@ -105,17 +115,27 @@ Built into the workflow — every command enforces these:
|
|
|
105
115
|
|
|
106
116
|
## Spec structure
|
|
107
117
|
|
|
108
|
-
Each feature
|
|
118
|
+
Each feature lives in `specs/<name>/` with three files:
|
|
109
119
|
|
|
110
120
|
**`1-requirements.md`** — Problem, measurable goals (G1, G2…), BDD acceptance criteria, constraints, open questions (blocking vs. non-blocking).
|
|
111
121
|
|
|
112
|
-
**`2-plan.md`** — Goals coverage, assumptions
|
|
122
|
+
**`2-plan.md`** — Goals coverage, assumptions confirmed via `/assume`, approach + tradeoffs, components affected, abort criteria. Requires explicit approval before execution starts.
|
|
113
123
|
|
|
114
|
-
**`3-tasks.md`** — One task at a time. Each
|
|
124
|
+
**`3-tasks.md`** — One task at a time. Each has: test to write first (red → green), files to change, goal ID, and acceptance scenario. Completed specs move to `specs/_done/`.
|
|
115
125
|
|
|
116
126
|
---
|
|
117
127
|
|
|
118
|
-
##
|
|
128
|
+
## Development
|
|
129
|
+
|
|
130
|
+
```bash
|
|
131
|
+
git clone https://github.com/MarcosCamara01/sddx-workflow.git
|
|
132
|
+
cd sddx-workflow
|
|
133
|
+
npm install
|
|
134
|
+
npm run dev # watch mode
|
|
135
|
+
npm run build # production build
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
### Publishing
|
|
119
139
|
|
|
120
140
|
```bash
|
|
121
141
|
npm version patch # bug fix: 0.1.0 → 0.1.1
|
|
@@ -123,9 +143,7 @@ npm version minor # new feature: 0.1.0 → 0.2.0
|
|
|
123
143
|
npm publish
|
|
124
144
|
```
|
|
125
145
|
|
|
126
|
-
Users running `npx sddx-workflow init` always get the latest version
|
|
127
|
-
|
|
128
|
-
Since files are copied to your project, existing `.sdd/` files are never overwritten on update — use `--force` to explicitly replace them.
|
|
146
|
+
Users running `npx sddx-workflow init` always get the latest version. Existing `.sdd/` files are never overwritten on update — use `--force` to explicitly replace them.
|
|
129
147
|
|
|
130
148
|
---
|
|
131
149
|
|