specstocode 0.5.0 → 0.5.1

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.
Files changed (2) hide show
  1. package/README.md +75 -131
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,218 +1,162 @@
1
- # ProductBuilders CLI
1
+ # specstocode
2
2
 
3
- Plan, validate, and build products — from your terminal. Turn a problem into a structured product blueprint with AI-powered story mapping.
3
+ Write structured specs, map your user stories, and let your AI coding agent do the rest.
4
4
 
5
- ```
6
- ██████╗ ██████╗
7
- ██╔══██╗██╔══██╗ ProductBuilders
8
- ██████╔╝██████╔╝ Stop building for nobody.
9
- ██╔═══╝ ██╔══██╗
10
- ██║ ██████╔╝
11
- ╚═╝ ╚═════╝
5
+ ## Install
6
+
7
+ ```bash
8
+ npm install -g specstocode
12
9
  ```
13
10
 
14
- ## Install
11
+ Or use without installing:
15
12
 
16
13
  ```bash
17
- npm install -g productbuilders
14
+ npx specstocode init
18
15
  ```
19
16
 
20
- ## Getting Started
17
+ ## How it works
21
18
 
22
- ### 1. Log in
19
+ 1. **Plan on the web** — create a project on [specstocode.com](https://specstocode.com), map your user stories, and write Gherkin specs for each one
20
+ 2. **Connect your codebase** — run `specstocode init` in your project directory
21
+ 3. **Build with AI** — your AI coding agent reads `SPECSTOCODE.md` for full product context: stories, acceptance criteria, decisions, and notes
23
22
 
24
- ```bash
25
- productbuilders login
23
+ ```
24
+ specstocode.com Your project
25
+ ┌─────────────────┐ ┌─────────────────┐
26
+ │ Story map UI │◄── sync API ─────►│ CLI / MCP │
27
+ │ Specs editor │ │ SPECSTOCODE.md │
28
+ │ (plan here) │ GET /context │ (build here) │
29
+ │ │──────────────────►│ │
30
+ │ Stories │ PATCH /stories │ Claude Code │
31
+ │ Acceptance │◄──────────────────│ Cursor / etc │
32
+ │ criteria │ │ │
33
+ └─────────────────┘ └─────────────────┘
26
34
  ```
27
35
 
28
- Opens your browser to authenticate with [ProductBuilders.pro](https://productbuilders.pro). You only need to do this once per machine.
36
+ ---
37
+
38
+ ## Getting Started
29
39
 
30
- ### 2. Start a new project
40
+ ### 1. Log in
31
41
 
32
42
  ```bash
33
- productbuilders start
43
+ specstocode login
34
44
  ```
35
45
 
36
- Interactive guided flow:
37
- 1. **Describe your problem** — what are you trying to solve?
38
- 2. **AI discovery questions** — sharpens your thinking with targeted questions
39
- 3. **Pitch synthesis** — generates a one-liner pitch and target user
40
- 4. **Name your product** — pick from AI-suggested names or type your own
41
- 5. **Validate** — publish to Explore to get feedback before building
42
- 6. **Scope** — generates a blueprint, story map, and optional HTML mockup
46
+ Opens your browser to authenticate. One-time per machine.
43
47
 
44
- ### 3. Connect to your codebase
48
+ ### 2. Connect your codebase
45
49
 
46
- After scoping, connect the story map to your project directory:
50
+ Run this inside your project directory after creating a project on [specstocode.com](https://specstocode.com):
47
51
 
48
52
  ```bash
49
- productbuilders init pb_sync_<your-token>
53
+ specstocode init
50
54
  ```
51
55
 
52
- Your project now has:
53
- - `PRODUCTBUILDERS.md` — product context (personas, stories, acceptance criteria)
54
- - `.productbuilders/config.json` — sync config (auto-gitignored)
56
+ This creates:
57
+ - `SPECSTOCODE.md` — product context file (stories, acceptance criteria, personas, decisions)
58
+ - `.specstocode/config.json` — sync config (auto-gitignored)
55
59
 
56
- ### 4. Configure your AI tool
60
+ ### 3. Set up your AI tool
57
61
 
58
62
  ```bash
59
- productbuilders setup
63
+ specstocode setup
60
64
  ```
61
65
 
62
- Sets up [Claude Code](https://claude.com/claude-code) and/or [Cursor](https://cursor.com) with:
63
- - `CLAUDE.md` / `.cursorrules` with product context
64
- - Slash commands for the development workflow (inside Claude Code, not the terminal)
66
+ Configures [Claude Code](https://claude.com/claude-code) or [Cursor](https://cursor.com) with:
67
+ - `CLAUDE.md` / `.cursorrules` pointing to your specs
65
68
  - `ARCHITECTURE.md` and `CONVENTIONS.md` scaffolding
66
69
 
67
- ### 5. Build
70
+ ### 4. Build
68
71
 
69
72
  ```bash
70
- productbuilders next # See what to build first
71
- productbuilders done <id> # Mark a story as complete
72
- productbuilders stories # List all stories
73
- productbuilders status # View progress dashboard
73
+ specstocode next # What to build next (highest priority story + acceptance criteria)
74
+ specstocode done <id> # Mark a story complete
75
+ specstocode stories # List all stories
76
+ specstocode status # Progress dashboard
74
77
  ```
75
78
 
76
79
  ---
77
80
 
78
81
  ## All Commands
79
82
 
80
- ### Project Creation
83
+ ### Setup
81
84
 
82
85
  | Command | Description |
83
86
  |---------|-------------|
84
- | `productbuilders login` | Authenticate (opens browser) |
85
- | `productbuilders logout` | Log out |
86
- | `productbuilders start` | New project — guided flow from problem to pitch |
87
- | `productbuilders scope [id]` | Scope a project — blueprint, story map, mockup |
88
- | `productbuilders setup` | Configure Claude Code / Cursor |
89
- | `productbuilders templates [name]` | Browse starter templates |
90
-
91
- ### Story Management
87
+ | `specstocode login` | Authenticate (opens browser) |
88
+ | `specstocode logout` | Log out |
89
+ | `specstocode init` | Connect project directory to a story map |
90
+ | `specstocode sync` | Refresh `SPECSTOCODE.md` with latest from the web |
91
+ | `specstocode setup` | Configure Claude Code / Cursor |
92
92
 
93
- | Command | Description |
94
- |---------|-------------|
95
- | `productbuilders init [token]` | Connect project to a story map |
96
- | `productbuilders sync` | Refresh PRODUCTBUILDERS.md |
97
- | `productbuilders status` | Progress dashboard |
98
- | `productbuilders stories [-f filter]` | List stories (filter: todo/done/keyword) |
99
- | `productbuilders next` | Next priority story with acceptance criteria |
100
- | `productbuilders done <id>` | Mark story as done (accepts ID prefix) |
101
- | `productbuilders add <title>` | Create a new story |
102
- | `productbuilders decide [title]` | Log an architectural decision |
103
- | `productbuilders note <id> [note]` | Add implementation notes |
104
-
105
- ### Analysis (coming soon)
93
+ ### Story management
106
94
 
107
95
  | Command | Description |
108
96
  |---------|-------------|
109
- | `productbuilders complexity [id]` | AI complexity scoring |
110
- | `productbuilders research [query]` | Research with project context |
111
- | `productbuilders import [file]` | Import PRD as stories |
97
+ | `specstocode status` | Progress dashboard |
98
+ | `specstocode stories [-f filter]` | List stories (filter: `todo` / `done` / keyword) |
99
+ | `specstocode next` | Next priority story with acceptance criteria |
100
+ | `specstocode done <id>` | Mark a story done (accepts ID prefix) |
101
+ | `specstocode add <title>` | Create a new story |
102
+ | `specstocode decide [title]` | Log an architectural decision |
103
+ | `specstocode note <id> [text]` | Add implementation notes to a story |
112
104
 
113
- ### Integration
105
+ ### MCP server
114
106
 
115
107
  | Command | Description |
116
108
  |---------|-------------|
117
- | `productbuilders mcp [--mode]` | Start MCP server (core/standard/all) |
109
+ | `specstocode mcp [--mode]` | Start MCP server (`core` / `standard` / `all`) |
118
110
 
119
111
  ---
120
112
 
121
113
  ## MCP Server
122
114
 
123
- Give Claude Code or Cursor native access to your story map.
115
+ Give Claude Code or Cursor native access to your story map and specs.
124
116
 
125
- ### Setup
117
+ Add to `~/.claude/settings.json` (Claude Code) or your Cursor MCP config:
126
118
 
127
119
  ```json
128
120
  {
129
121
  "mcpServers": {
130
- "productbuilders": {
122
+ "specstocode": {
131
123
  "command": "npx",
132
- "args": ["productbuilders", "mcp"],
124
+ "args": ["specstocode", "mcp"],
133
125
  "cwd": "/path/to/your/project"
134
126
  }
135
127
  }
136
128
  }
137
129
  ```
138
130
 
139
- Add to `~/.claude/settings.json` (Claude Code) or your Cursor MCP config.
140
-
141
- ### Tool Modes
131
+ ### Tool modes
142
132
 
143
133
  Control token usage with `--mode`:
144
134
 
145
135
  | Mode | Tools | Use case |
146
136
  |------|-------|----------|
147
- | `core` | 5 | Day-to-day dev (list, mark done, status, notes) |
148
- | `standard` | 8 | Active dev (+ create, context, decisions) |
149
- | `all` | 11 | Full power (+ complexity, research, import) |
137
+ | `core` | 5 | Day-to-day dev — list, mark done, status, notes |
138
+ | `standard` | 8 | Active dev — + create, context, decisions |
139
+ | `all` | 11 | Full access — + complexity, research, import |
150
140
 
151
- ### Available Tools
141
+ ### Available tools
152
142
 
153
143
  | Tool | Mode | Description |
154
144
  |------|------|-------------|
155
145
  | `list_stories` | core | List stories with optional filter |
156
- | `mark_done` | core | Mark a story as complete |
157
- | `mark_in_progress` | core | Mark a story as in progress |
146
+ | `mark_done` | core | Mark a story complete |
147
+ | `mark_in_progress` | core | Mark a story in progress |
158
148
  | `get_status` | core | Progress summary |
159
149
  | `add_note` | core | Add implementation notes |
160
150
  | `create_story` | standard | Create a new story |
161
- | `get_context` | standard | Fetch PRODUCTBUILDERS.md |
151
+ | `get_context` | standard | Fetch full product context |
162
152
  | `log_decision` | standard | Log an architectural decision |
163
153
  | `analyze_complexity` | all | AI complexity scoring |
164
154
  | `research` | all | AI research with project context |
165
- | `import_prd` | all | Parse PRD into stories |
166
-
167
- ---
168
-
169
- ## Templates
170
-
171
- Starter story maps for common product types:
172
-
173
- ```bash
174
- productbuilders templates # List all
175
- productbuilders templates saas # View details
176
- ```
177
-
178
- | Template | Description | Stories |
179
- |----------|-------------|---------|
180
- | `saas` | Multi-tenant SaaS with auth, billing, dashboards | 16 |
181
- | `marketplace` | Two-sided marketplace with payments | 13 |
182
- | `mobile-app` | Consumer app with feed, social, notifications | 12 |
183
- | `ai-tool` | AI-powered tool with streaming and billing | 12 |
184
-
185
- ---
186
-
187
- ## How It Works
188
-
189
- ```
190
- ProductBuilders.pro Your Project
191
- ┌──────────────────┐ ┌──────────────────┐
192
- │ │ │ │
193
- │ Story Map UI │◄── sync API ───►│ CLI / MCP │
194
- │ (plan here) │ │ (build here) │
195
- │ │ │ │
196
- │ ┌────────────┐ │ GET /context │ PRODUCTBUILDERS │
197
- │ │ Activities │ │ ───────────────► │ .md │
198
- │ │ Steps │ │ │ │
199
- │ │ Stories │ │ PATCH /stories │ Claude Code / │
200
- │ │ Personas │ │ ◄─────────────── │ Cursor / etc │
201
- │ └────────────┘ │ │ │
202
- └──────────────────┘ └──────────────────┘
203
- ```
204
-
205
- 1. **Start** — describe your problem, AI generates discovery questions and a pitch
206
- 2. **Validate** — publish to Explore, get feedback and intent signals
207
- 3. **Scope** — AI generates blueprint, story map, and mockup
208
- 4. **Connect** — `productbuilders init` links your codebase to the story map
209
- 5. **Build** — your AI tool reads PRODUCTBUILDERS.md for context
210
- 6. **Track** — mark stories done, log decisions, add notes — all flows back to the map
155
+ | `import_prd` | all | Parse a PRD into stories |
211
156
 
212
157
  ---
213
158
 
214
159
  ## Links
215
160
 
216
- - [ProductBuilders.pro](https://productbuilders.pro) — the web app
217
- - [Explore](https://productbuilders.pro/explore) — discover what others are building
218
- - [Community](https://productbuilders.pro/community) — connect with builders
161
+ - [specstocode.com](https://specstocode.com) — web app
162
+ - [npm](https://www.npmjs.com/package/specstocode) — this package
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "specstocode",
3
- "version": "0.5.0",
3
+ "version": "0.5.1",
4
4
  "description": "CLI for specstocode.com — connect your codebase to your product story map",
5
5
  "bin": {
6
6
  "specstocode": "bin/specstocode.js",