specrails-core 3.3.1 → 3.4.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 +76 -48
- package/bin/doctor.sh +1 -1
- package/commands/doctor.md +1 -1
- package/commands/setup.md +70 -70
- package/docs/README.md +3 -2
- package/docs/agents.md +15 -15
- package/docs/changelog.md +20 -20
- package/docs/concepts.md +3 -3
- package/docs/customization.md +18 -5
- package/docs/deployment.md +20 -5
- package/docs/getting-started.md +16 -27
- package/docs/installation.md +81 -48
- package/docs/local-tickets.md +11 -12
- package/docs/migration-guide.md +9 -9
- package/docs/playbook-parallel-dev.md +8 -8
- package/docs/playbook-product-discovery.md +1 -1
- package/docs/plugin-architecture.md +137 -0
- package/docs/research/codex-compatibility-analysis.md +11 -11
- package/docs/research/mcp-feasibility-analysis.md +5 -5
- package/docs/testing/test-matrix-codex.md +1 -1
- package/docs/user-docs/cli-reference.md +57 -57
- package/docs/user-docs/codex-vs-claude-code.md +7 -7
- package/docs/user-docs/faq.md +32 -26
- package/docs/user-docs/getting-started-codex.md +7 -7
- package/docs/user-docs/installation.md +47 -38
- package/docs/user-docs/quick-start.md +20 -26
- package/docs/workflows.md +62 -62
- package/install.sh +3 -3
- package/package.json +1 -1
- package/templates/agents/sr-merge-resolver.md +1 -1
- package/templates/claude-md/CLAUDE-quickstart.md +2 -2
- package/templates/commands/{sr → specrails}/batch-implement.md +18 -18
- package/templates/commands/{sr → specrails}/implement.md +8 -8
- package/templates/commands/{sr → specrails}/memory-inspect.md +3 -3
- package/templates/commands/{sr → specrails}/merge-resolve.md +1 -1
- package/templates/commands/{sr → specrails}/opsx-diff.md +1 -1
- package/templates/commands/{sr → specrails}/product-backlog.md +7 -7
- package/templates/commands/{sr → specrails}/propose-spec.md +1 -1
- package/templates/commands/{sr → specrails}/refactor-recommender.md +1 -1
- package/templates/commands/{sr → specrails}/retry.md +13 -13
- package/templates/commands/{sr → specrails}/team-debug.md +5 -5
- package/templates/commands/{sr → specrails}/team-review.md +4 -4
- package/templates/commands/{sr → specrails}/telemetry.md +2 -2
- package/templates/commands/{sr → specrails}/update-product-driven-backlog.md +2 -2
- package/templates/commands/{sr → specrails}/vpc-drift.md +4 -4
- package/templates/commands/{sr → specrails}/why.md +5 -5
- package/templates/commands/test.md +2 -2
- package/templates/skills/sr-batch-implement/SKILL.md +18 -18
- package/templates/skills/sr-implement/SKILL.md +8 -8
- package/templates/skills/sr-product-backlog/SKILL.md +7 -7
- package/templates/skills/sr-refactor-recommender/SKILL.md +1 -1
- package/templates/skills/sr-update-backlog/SKILL.md +2 -2
- package/templates/skills/sr-why/SKILL.md +5 -5
- package/update.sh +2 -2
- /package/templates/commands/{sr → specrails}/compat-check.md +0 -0
- /package/templates/commands/{sr → specrails}/health-check.md +0 -0
|
@@ -45,7 +45,7 @@ npx specrails-core@latest init → install.sh (bash) → /setup (Claud
|
|
|
45
45
|
|
|
46
46
|
```
|
|
47
47
|
Claude Code
|
|
48
|
-
├── Commands (/
|
|
48
|
+
├── Commands (/specrails:implement, /specrails:product-backlog, ...)
|
|
49
49
|
├── Skills (/opsx:new, /opsx:apply, /opsx:ff, ...)
|
|
50
50
|
├── Agents (sr-architect, sr-developer, sr-reviewer, ...)
|
|
51
51
|
├── Rules (.claude/rules/ — layer-specific conventions)
|
|
@@ -146,7 +146,7 @@ The current architecture tightly couples specrails to Claude Code's command/skil
|
|
|
146
146
|
│ Specs, Personas, Memory, Config, Analysis │
|
|
147
147
|
├─────────────────────────────────────────────┤
|
|
148
148
|
│ Claude Code (Orchestration) │
|
|
149
|
-
│ /
|
|
149
|
+
│ /specrails:implement, /specrails:batch-implement, agents │
|
|
150
150
|
└─────────────────────────────────────────────┘
|
|
151
151
|
```
|
|
152
152
|
|
|
@@ -168,7 +168,7 @@ Skills and commands already provide strong Claude Code integration. MCP adds com
|
|
|
168
168
|
|
|
169
169
|
#### B. Orchestration Can't Move to MCP
|
|
170
170
|
|
|
171
|
-
The `/
|
|
171
|
+
The `/specrails:implement` pipeline requires Claude Code's Agent tool (subagent spawning, worktree isolation, background execution). MCP tools are request/response — they can't replicate multi-phase orchestration.
|
|
172
172
|
|
|
173
173
|
**Counter:** This is exactly why the recommendation is scoped. Orchestration stays in Claude Code; only knowledge access moves to MCP.
|
|
174
174
|
|
|
@@ -333,8 +333,8 @@ These capabilities require Claude Code's runtime and should NOT be exposed via M
|
|
|
333
333
|
|
|
334
334
|
| Capability | Reason |
|
|
335
335
|
|------------|--------|
|
|
336
|
-
| `/
|
|
337
|
-
| `/
|
|
336
|
+
| `/specrails:implement` pipeline | Requires Agent tool (subagent spawning) |
|
|
337
|
+
| `/specrails:batch-implement` | Requires git worktree isolation |
|
|
338
338
|
| Agent invocation (sr-*) | Requires Claude Code's Agent subagent system |
|
|
339
339
|
| OpenSpec artifact creation | Interactive, context-heavy (requires conversation) |
|
|
340
340
|
| `/setup` wizard | Multi-step interactive configuration |
|
|
@@ -36,7 +36,7 @@ Epic: [SPEA-505](/SPEA/issues/SPEA-505) — Codex Compatibility Approach B
|
|
|
36
36
|
|
|
37
37
|
| Feature | Claude Code | Codex |
|
|
38
38
|
|---------|:-:|:-:|
|
|
39
|
-
| Legacy slash commands `.claude/commands/
|
|
39
|
+
| Legacy slash commands `.claude/commands/specrails/` | ✅ | ❌ |
|
|
40
40
|
| SKILL.md format `.claude/skills/sr-*/` | ✅ | ✅ |
|
|
41
41
|
| `sr:implement` skill | ✅ | ✅ |
|
|
42
42
|
| `sr:product-backlog` skill | ✅ | ✅ |
|
|
@@ -21,15 +21,15 @@ codex # Codex
|
|
|
21
21
|
|
|
22
22
|
## Core workflow
|
|
23
23
|
|
|
24
|
-
### `/
|
|
24
|
+
### `/specrails:implement` ✅ Both
|
|
25
25
|
|
|
26
26
|
Implement a feature through the full agent pipeline: design → code → tests → docs → review → PR.
|
|
27
27
|
|
|
28
28
|
```
|
|
29
|
-
/
|
|
30
|
-
/
|
|
31
|
-
/
|
|
32
|
-
/
|
|
29
|
+
/specrails:implement #85
|
|
30
|
+
/specrails:implement #85, #71, #63
|
|
31
|
+
/specrails:implement "add a health check endpoint"
|
|
32
|
+
/specrails:implement UI, Analytics
|
|
33
33
|
```
|
|
34
34
|
|
|
35
35
|
**Flags:**
|
|
@@ -60,16 +60,16 @@ A single issue runs sequentially on the current branch. Multiple issues run in p
|
|
|
60
60
|
|
|
61
61
|
---
|
|
62
62
|
|
|
63
|
-
### `/
|
|
63
|
+
### `/specrails:telemetry` ✅ Both
|
|
64
64
|
|
|
65
65
|
Inspect per-agent execution metrics: token usage, estimated API cost, run count, average duration, and success/failure rate.
|
|
66
66
|
|
|
67
67
|
```
|
|
68
|
-
/
|
|
69
|
-
/
|
|
70
|
-
/
|
|
71
|
-
/
|
|
72
|
-
/
|
|
68
|
+
/specrails:telemetry
|
|
69
|
+
/specrails:telemetry --period today
|
|
70
|
+
/specrails:telemetry --agent sr-developer
|
|
71
|
+
/specrails:telemetry --format json
|
|
72
|
+
/specrails:telemetry --save
|
|
73
73
|
```
|
|
74
74
|
|
|
75
75
|
**Flags:**
|
|
@@ -83,14 +83,14 @@ Inspect per-agent execution metrics: token usage, estimated API cost, run count,
|
|
|
83
83
|
|
|
84
84
|
---
|
|
85
85
|
|
|
86
|
-
### `/
|
|
86
|
+
### `/specrails:merge-resolve` ✅ Both
|
|
87
87
|
|
|
88
88
|
Resolve git conflict markers using AI-powered context analysis.
|
|
89
89
|
|
|
90
90
|
```
|
|
91
|
-
/
|
|
92
|
-
/
|
|
93
|
-
/
|
|
91
|
+
/specrails:merge-resolve
|
|
92
|
+
/specrails:merge-resolve --files src/api/routes.ts
|
|
93
|
+
/specrails:merge-resolve --context openspec/changes/
|
|
94
94
|
```
|
|
95
95
|
|
|
96
96
|
**Flags:**
|
|
@@ -105,15 +105,15 @@ Reads OpenSpec context bundles from the features that produced each conflict, in
|
|
|
105
105
|
|
|
106
106
|
---
|
|
107
107
|
|
|
108
|
-
### `/
|
|
108
|
+
### `/specrails:retry` ✅ Both
|
|
109
109
|
|
|
110
|
-
Resume a failed `/
|
|
110
|
+
Resume a failed `/specrails:implement` run from the last successful phase.
|
|
111
111
|
|
|
112
112
|
```
|
|
113
|
-
/
|
|
114
|
-
/
|
|
115
|
-
/
|
|
116
|
-
/
|
|
113
|
+
/specrails:retry <feature-name>
|
|
114
|
+
/specrails:retry --list
|
|
115
|
+
/specrails:retry <feature-name> --from architect
|
|
116
|
+
/specrails:retry <feature-name> --dry-run
|
|
117
117
|
```
|
|
118
118
|
|
|
119
119
|
**Flags:**
|
|
@@ -130,15 +130,15 @@ Pipeline state is saved to `.claude/pipeline-state/<feature-name>.json` after ea
|
|
|
130
130
|
|
|
131
131
|
---
|
|
132
132
|
|
|
133
|
-
### `/
|
|
133
|
+
### `/specrails:batch-implement` ⚠️ Limited on Codex
|
|
134
134
|
|
|
135
135
|
Implement multiple independent features in parallel using git worktrees.
|
|
136
136
|
|
|
137
137
|
```
|
|
138
|
-
/
|
|
138
|
+
/specrails:batch-implement #85, #71, #63
|
|
139
139
|
```
|
|
140
140
|
|
|
141
|
-
Each feature gets its own worktree, its own agent pipeline, and its own PR. Use this instead of `/
|
|
141
|
+
Each feature gets its own worktree, its own agent pipeline, and its own PR. Use this instead of `/specrails:implement` with multiple issues when you want explicit control over parallel execution.
|
|
142
142
|
|
|
143
143
|
> **Codex note**: Worktree isolation is limited in Codex CLI beta. Prefer Codex Cloud for parallel batch work.
|
|
144
144
|
|
|
@@ -146,26 +146,26 @@ Each feature gets its own worktree, its own agent pipeline, and its own PR. Use
|
|
|
146
146
|
|
|
147
147
|
## Product and backlog
|
|
148
148
|
|
|
149
|
-
### `/
|
|
149
|
+
### `/specrails:product-backlog` ✅ Both
|
|
150
150
|
|
|
151
151
|
View your prioritized product backlog, ranked by VPC persona fit and estimated effort.
|
|
152
152
|
|
|
153
153
|
```
|
|
154
|
-
/
|
|
155
|
-
/
|
|
154
|
+
/specrails:product-backlog
|
|
155
|
+
/specrails:product-backlog UI, API
|
|
156
156
|
```
|
|
157
157
|
|
|
158
158
|
Reads GitHub Issues labeled `product-driven-backlog`. Produces a ranked table per area, top 3 recommendations, and a safe implementation order based on issue dependencies.
|
|
159
159
|
|
|
160
160
|
---
|
|
161
161
|
|
|
162
|
-
### `/
|
|
162
|
+
### `/specrails:update-product-driven-backlog` ✅ Both
|
|
163
163
|
|
|
164
164
|
Generate new feature ideas through product discovery and create GitHub Issues.
|
|
165
165
|
|
|
166
166
|
```
|
|
167
|
-
/
|
|
168
|
-
/
|
|
167
|
+
/specrails:update-product-driven-backlog
|
|
168
|
+
/specrails:update-product-driven-backlog UI, API
|
|
169
169
|
```
|
|
170
170
|
|
|
171
171
|
The Product Manager researches your competitive landscape, generates 2–4 feature ideas per area, and scores each against your user personas. Creates GitHub Issues with full VPC evaluation if write access is available.
|
|
@@ -174,73 +174,73 @@ The Product Manager researches your competitive landscape, generates 2–4 featu
|
|
|
174
174
|
|
|
175
175
|
## Analysis and inspection
|
|
176
176
|
|
|
177
|
-
### `/
|
|
177
|
+
### `/specrails:refactor-recommender` ✅ Both
|
|
178
178
|
|
|
179
179
|
Scan the codebase for refactoring opportunities, ranked by impact/effort ratio.
|
|
180
180
|
|
|
181
181
|
```
|
|
182
|
-
/
|
|
182
|
+
/specrails:refactor-recommender
|
|
183
183
|
```
|
|
184
184
|
|
|
185
185
|
Identifies duplicates, overly long functions, large files, dead code, outdated patterns, and complex logic. Optionally creates GitHub Issues for tracking.
|
|
186
186
|
|
|
187
187
|
---
|
|
188
188
|
|
|
189
|
-
### `/
|
|
189
|
+
### `/specrails:compat-check` ✅ Both
|
|
190
190
|
|
|
191
191
|
Analyze the backwards-compatibility impact of a proposed change.
|
|
192
192
|
|
|
193
193
|
```
|
|
194
|
-
/
|
|
195
|
-
/
|
|
194
|
+
/specrails:compat-check #85
|
|
195
|
+
/specrails:compat-check #85 --save
|
|
196
196
|
```
|
|
197
197
|
|
|
198
198
|
Detects removed endpoints, changed method signatures, changed response shapes, and behavioral changes. When breaking changes are found, generates a migration guide.
|
|
199
199
|
|
|
200
200
|
`--save` updates the stored API baseline so future checks compare against the new surface.
|
|
201
201
|
|
|
202
|
-
The Architect runs this automatically as part of every `/
|
|
202
|
+
The Architect runs this automatically as part of every `/specrails:implement` pipeline.
|
|
203
203
|
|
|
204
204
|
---
|
|
205
205
|
|
|
206
|
-
### `/
|
|
206
|
+
### `/specrails:why` ✅ Both
|
|
207
207
|
|
|
208
208
|
Search agent explanation records in plain language.
|
|
209
209
|
|
|
210
210
|
```
|
|
211
|
-
/
|
|
212
|
-
/
|
|
213
|
-
/
|
|
211
|
+
/specrails:why "why did we choose this database schema"
|
|
212
|
+
/specrails:why "explain the auth middleware design"
|
|
213
|
+
/specrails:why "why is pagination implemented this way"
|
|
214
214
|
```
|
|
215
215
|
|
|
216
|
-
Agents write decision rationale to `.claude/agent-memory/explanations/` as they work. `/
|
|
216
|
+
Agents write decision rationale to `.claude/agent-memory/explanations/` as they work. `/specrails:why` searches these records semantically. Useful for onboarding, code review, and revisiting past decisions.
|
|
217
217
|
|
|
218
218
|
---
|
|
219
219
|
|
|
220
|
-
### `/
|
|
220
|
+
### `/specrails:vpc-drift` ✅ Both
|
|
221
221
|
|
|
222
222
|
Detect when your VPC personas have drifted from what your product actually delivers.
|
|
223
223
|
|
|
224
224
|
```
|
|
225
|
-
/
|
|
226
|
-
/
|
|
227
|
-
/
|
|
228
|
-
/
|
|
225
|
+
/specrails:vpc-drift
|
|
226
|
+
/specrails:vpc-drift --persona "Alex,Sara"
|
|
227
|
+
/specrails:vpc-drift --verbose
|
|
228
|
+
/specrails:vpc-drift --format json
|
|
229
229
|
```
|
|
230
230
|
|
|
231
231
|
Compares persona Jobs/Pains/Gains against your backlog, implemented features, and agent memory. Produces a per-persona alignment score and recommendations for updating your VPC.
|
|
232
232
|
|
|
233
233
|
---
|
|
234
234
|
|
|
235
|
-
### `/
|
|
235
|
+
### `/specrails:memory-inspect` ✅ Both
|
|
236
236
|
|
|
237
237
|
Inspect and clean up agent memory directories.
|
|
238
238
|
|
|
239
239
|
```
|
|
240
|
-
/
|
|
241
|
-
/
|
|
242
|
-
/
|
|
243
|
-
/
|
|
240
|
+
/specrails:memory-inspect
|
|
241
|
+
/specrails:memory-inspect sr-developer
|
|
242
|
+
/specrails:memory-inspect --stale 14
|
|
243
|
+
/specrails:memory-inspect --prune
|
|
244
244
|
```
|
|
245
245
|
|
|
246
246
|
**Flags:**
|
|
@@ -254,12 +254,12 @@ Agent memory lives in `.claude/agent-memory/sr-*/` (Claude Code) or `.codex/agen
|
|
|
254
254
|
|
|
255
255
|
---
|
|
256
256
|
|
|
257
|
-
### `/
|
|
257
|
+
### `/specrails:propose-spec` ✅ Both
|
|
258
258
|
|
|
259
259
|
Explore a feature idea and produce a structured proposal ready for the OpenSpec pipeline.
|
|
260
260
|
|
|
261
261
|
```
|
|
262
|
-
/
|
|
262
|
+
/specrails:propose-spec "add rate limiting to the API"
|
|
263
263
|
```
|
|
264
264
|
|
|
265
265
|
Produces: problem statement, proposed solution, out-of-scope items, acceptance criteria, technical considerations, and a complexity estimate.
|
|
@@ -346,14 +346,14 @@ Open-ended thinking mode for brainstorming, investigating problems, or clarifyin
|
|
|
346
346
|
|
|
347
347
|
---
|
|
348
348
|
|
|
349
|
-
### `/
|
|
349
|
+
### `/specrails:opsx-diff` — Spec Change Diff
|
|
350
350
|
|
|
351
351
|
Visualize the before/after diff of an OpenSpec change.
|
|
352
352
|
|
|
353
353
|
```
|
|
354
|
-
/
|
|
355
|
-
/
|
|
356
|
-
/
|
|
354
|
+
/specrails:opsx-diff <change-name>
|
|
355
|
+
/specrails:opsx-diff my-feature --format json
|
|
356
|
+
/specrails:opsx-diff my-feature --summary-only
|
|
357
357
|
```
|
|
358
358
|
|
|
359
359
|
**Flags:**
|
|
@@ -12,7 +12,7 @@ SpecRails supports both **OpenAI Codex** and **Anthropic Claude Code** as AI age
|
|
|
12
12
|
| **CLI** | `claude` | `codex` |
|
|
13
13
|
| **Config directory** | `.claude/` | `.codex/` |
|
|
14
14
|
| **Agent instructions** | `CLAUDE.md` | `AGENTS.md` |
|
|
15
|
-
| **Skills (`/
|
|
15
|
+
| **Skills (`/specrails:*`, `/opsx:*`)** | ✅ Full support | ✅ Full support |
|
|
16
16
|
| **OpenSpec workflow** | ✅ Full support | ✅ Full support |
|
|
17
17
|
| **Parallel worktrees** | ✅ Native | ⚠️ Limited |
|
|
18
18
|
| **Agent definitions** | Markdown frontmatter | TOML |
|
|
@@ -27,10 +27,10 @@ SpecRails supports both **OpenAI Codex** and **Anthropic Claude Code** as AI age
|
|
|
27
27
|
|
|
28
28
|
### Skills
|
|
29
29
|
|
|
30
|
-
SpecRails Skills use `SKILL.md` format, which is shared between Codex and Claude Code. All `/
|
|
30
|
+
SpecRails Skills use `SKILL.md` format, which is shared between Codex and Claude Code. All `/specrails:*` and `/opsx:*` skills run identically on both platforms:
|
|
31
31
|
|
|
32
|
-
- `/
|
|
33
|
-
- `/
|
|
32
|
+
- `/specrails:implement` — full pipeline (design → code → review → PR)
|
|
33
|
+
- `/specrails:product-backlog` — VPC-ranked backlog view
|
|
34
34
|
- `/opsx:ff` — OpenSpec fast-forward
|
|
35
35
|
- All other workflow skills
|
|
36
36
|
|
|
@@ -52,7 +52,7 @@ Both platforms use file-based memory. Claude Code uses `.claude/agent-memory/`.
|
|
|
52
52
|
|
|
53
53
|
### Parallel execution and worktrees
|
|
54
54
|
|
|
55
|
-
`/
|
|
55
|
+
`/specrails:batch-implement` (multiple issues in parallel) uses git worktree isolation. On Claude Code this runs locally with full isolation. On Codex:
|
|
56
56
|
|
|
57
57
|
- **Codex CLI**: Parallel execution is supported but worktree isolation is limited in the current beta. Multiple issues may share a working directory.
|
|
58
58
|
- **Codex Cloud**: Native async parallelism — each task gets an isolated cloud environment. Well-suited for batch work.
|
|
@@ -83,10 +83,10 @@ Claude Code and Codex have different non-interactive modes:
|
|
|
83
83
|
|
|
84
84
|
```bash
|
|
85
85
|
# Claude Code
|
|
86
|
-
claude --print "run /
|
|
86
|
+
claude --print "run /specrails:implement #42"
|
|
87
87
|
|
|
88
88
|
# Codex
|
|
89
|
-
codex exec "run /
|
|
89
|
+
codex exec "run /specrails:implement #42"
|
|
90
90
|
```
|
|
91
91
|
|
|
92
92
|
Skills themselves are the same — only the CLI invocation differs.
|
package/docs/user-docs/faq.md
CHANGED
|
@@ -8,26 +8,26 @@ Yes. SpecRails runs on top of Claude Code, which requires an Anthropic account.
|
|
|
8
8
|
|
|
9
9
|
**What does the installer actually do to my project?**
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
The plugin method (`claude plugin install sr`) installs logic into Claude Code's plugin system — nothing is added to your project until you run `/specrails:setup`. The scaffold method (`npx specrails-core@latest init`) copies templates into `.claude/`. Neither method modifies your source code, creates commits, or pushes anything.
|
|
12
12
|
|
|
13
13
|
**Do I need Node.js if my project is not JavaScript?**
|
|
14
14
|
|
|
15
|
-
|
|
15
|
+
Not for the plugin method (`claude plugin install sr`). Node.js 18+ is only required for the scaffold method (`npx specrails-core@latest init`). Once installed, SpecRails works with any language or framework.
|
|
16
16
|
|
|
17
17
|
**Do I need GitHub Issues?**
|
|
18
18
|
|
|
19
|
-
No. SpecRails ships with a built-in local ticket system — no GitHub account required. Local tickets are the default. Commands like `/
|
|
19
|
+
No. SpecRails ships with a built-in local ticket system — no GitHub account required. Local tickets are the default. Commands like `/specrails:implement` accept ticket IDs or plain text:
|
|
20
20
|
|
|
21
21
|
```
|
|
22
|
-
/
|
|
23
|
-
/
|
|
22
|
+
/specrails:implement #1, #4
|
|
23
|
+
/specrails:implement "add rate limiting to the API"
|
|
24
24
|
```
|
|
25
25
|
|
|
26
|
-
You can switch to GitHub Issues or JIRA during `/setup` (Phase 3) if you prefer.
|
|
26
|
+
You can switch to GitHub Issues or JIRA during `/specrails:setup` (Phase 3) if you prefer.
|
|
27
27
|
|
|
28
|
-
**How long does /setup take?**
|
|
28
|
+
**How long does /specrails:setup take?**
|
|
29
29
|
|
|
30
|
-
The full wizard takes about 5 minutes — most of the time is Phase 2 (persona research via web search). For a faster start, use `/setup --lite`: three questions, under a minute, no web research.
|
|
30
|
+
The full wizard takes about 5 minutes — most of the time is Phase 2 (persona research via web search). For a faster start, use `/specrails:setup --lite`: three questions, under a minute, no web research.
|
|
31
31
|
|
|
32
32
|
---
|
|
33
33
|
|
|
@@ -35,28 +35,28 @@ The full wizard takes about 5 minutes — most of the time is Phase 2 (persona r
|
|
|
35
35
|
|
|
36
36
|
**Can I run SpecRails on an existing project with existing code?**
|
|
37
37
|
|
|
38
|
-
Yes, that's the intended use case. The `/setup` wizard analyzes your existing codebase — your tech stack, layers, CI commands, and conventions — and generates agents configured specifically for it.
|
|
38
|
+
Yes, that's the intended use case. The `/specrails:setup` wizard analyzes your existing codebase — your tech stack, layers, CI commands, and conventions — and generates agents configured specifically for it.
|
|
39
39
|
|
|
40
|
-
**Does /
|
|
40
|
+
**Does /specrails:implement always create a PR?**
|
|
41
41
|
|
|
42
42
|
By default, yes. If you want to preview the changes first without creating commits or a PR, use dry-run mode:
|
|
43
43
|
|
|
44
44
|
```
|
|
45
|
-
/
|
|
45
|
+
/specrails:implement --dry-run "add dark mode"
|
|
46
46
|
```
|
|
47
47
|
|
|
48
48
|
Then apply the cached result when you're ready:
|
|
49
49
|
|
|
50
50
|
```
|
|
51
|
-
/
|
|
51
|
+
/specrails:implement --apply dark-mode
|
|
52
52
|
```
|
|
53
53
|
|
|
54
54
|
**What happens if the pipeline fails mid-run?**
|
|
55
55
|
|
|
56
|
-
SpecRails saves pipeline state after each phase. If a run fails, use `/
|
|
56
|
+
SpecRails saves pipeline state after each phase. If a run fails, use `/specrails:retry` to resume from the last successful phase instead of starting over:
|
|
57
57
|
|
|
58
58
|
```
|
|
59
|
-
/
|
|
59
|
+
/specrails:retry dark-mode
|
|
60
60
|
```
|
|
61
61
|
|
|
62
62
|
**Can I implement multiple features at once?**
|
|
@@ -64,20 +64,20 @@ SpecRails saves pipeline state after each phase. If a run fails, use `/sr:retry`
|
|
|
64
64
|
Yes. Pass multiple issue numbers or descriptions:
|
|
65
65
|
|
|
66
66
|
```
|
|
67
|
-
/
|
|
67
|
+
/specrails:implement #42, #43, #44
|
|
68
68
|
```
|
|
69
69
|
|
|
70
70
|
Each feature gets an isolated git worktree. Pipelines run concurrently and the results are merged automatically at the end.
|
|
71
71
|
|
|
72
72
|
**Can I customize the agents?**
|
|
73
73
|
|
|
74
|
-
Yes.
|
|
74
|
+
Yes. With the plugin method, edit your project data files in `.specrails/` — personas, rules, config. With the scaffold method, agent files in `.claude/agents/` are also directly editable. Changes take effect on the next run.
|
|
75
75
|
|
|
76
|
-
For layer-specific coding conventions, edit `.claude/rules/*.md
|
|
76
|
+
For layer-specific coding conventions, edit `.specrails/rules/*.md` (plugin) or `.claude/rules/*.md` (scaffold).
|
|
77
77
|
|
|
78
78
|
**What is a VPC persona?**
|
|
79
79
|
|
|
80
|
-
VPC stands for Value Proposition Canvas. Personas are structured profiles of your target users with their Jobs (what they're trying to accomplish), Pains (what frustrates them), and Gains (what they want). The Product Manager and Architect use these to make better design decisions. They're generated during `/setup` and stored in `.claude/agents/personas
|
|
80
|
+
VPC stands for Value Proposition Canvas. Personas are structured profiles of your target users with their Jobs (what they're trying to accomplish), Pains (what frustrates them), and Gains (what they want). The Product Manager and Architect use these to make better design decisions. They're generated during `/specrails:setup` and stored in `.specrails/personas/` (plugin) or `.claude/agents/personas/` (scaffold).
|
|
81
81
|
|
|
82
82
|
---
|
|
83
83
|
|
|
@@ -85,11 +85,11 @@ VPC stands for Value Proposition Canvas. Personas are structured profiles of you
|
|
|
85
85
|
|
|
86
86
|
**Does SpecRails work with monorepos?**
|
|
87
87
|
|
|
88
|
-
Yes. During `/setup`, the architect detects your monorepo structure and generates separate layer configurations for each package or service.
|
|
88
|
+
Yes. During `/specrails:setup`, the architect detects your monorepo structure and generates separate layer configurations for each package or service.
|
|
89
89
|
|
|
90
90
|
**Which languages and frameworks are supported?**
|
|
91
91
|
|
|
92
|
-
SpecRails works with any stack. The agents are general-purpose and adapt based on what `/setup` detects in your codebase. It's been used with Node.js, Python, Go, Ruby, Rust, and mixed-stack projects.
|
|
92
|
+
SpecRails works with any stack. The agents are general-purpose and adapt based on what `/specrails:setup` detects in your codebase. It's been used with Node.js, Python, Go, Ruby, Rust, and mixed-stack projects.
|
|
93
93
|
|
|
94
94
|
**Does it work with private repositories?**
|
|
95
95
|
|
|
@@ -101,13 +101,19 @@ Yes, for code generation. For features that require GitHub integration (PR creat
|
|
|
101
101
|
|
|
102
102
|
**How do I update SpecRails?**
|
|
103
103
|
|
|
104
|
-
|
|
104
|
+
Plugin method:
|
|
105
|
+
|
|
106
|
+
```bash
|
|
107
|
+
claude plugin update sr
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
Scaffold method:
|
|
105
111
|
|
|
106
112
|
```bash
|
|
107
113
|
npx specrails-core@latest init --root-dir .
|
|
108
114
|
```
|
|
109
115
|
|
|
110
|
-
Then re-run `/setup` to regenerate
|
|
116
|
+
Then re-run `/specrails:setup` to regenerate project data with any new templates. See the [updating guide](../updating.md) for details.
|
|
111
117
|
|
|
112
118
|
**How do I know which version is installed?**
|
|
113
119
|
|
|
@@ -119,17 +125,17 @@ cat .specrails-version
|
|
|
119
125
|
|
|
120
126
|
## Troubleshooting
|
|
121
127
|
|
|
122
|
-
**The /setup command isn't available after installing.**
|
|
128
|
+
**The /specrails:setup command isn't available after installing.**
|
|
123
129
|
|
|
124
|
-
Claude Code loads commands from `.claude/commands
|
|
130
|
+
For the plugin method: make sure the plugin is installed (`claude plugin list` should show `sr`). For the scaffold method: Claude Code loads commands from `.claude/commands/` — make sure you opened Claude Code from inside your project directory.
|
|
125
131
|
|
|
126
132
|
**Generated files contain `{{PLACEHOLDER}}` text.**
|
|
127
133
|
|
|
128
|
-
The `/setup` wizard did not complete all phases. Re-run `/setup` — it will pick up where it left off.
|
|
134
|
+
The `/specrails:setup` wizard did not complete all phases. Re-run `/specrails:setup` — it will pick up where it left off.
|
|
129
135
|
|
|
130
136
|
**The pipeline created a PR but the CI checks failed.**
|
|
131
137
|
|
|
132
|
-
The reviewer agent runs your CI suite and attempts to fix failures automatically. If it can't fix them within its budget, it creates the PR with a note describing what failed and why. You can fix the remaining issues manually or run `/
|
|
138
|
+
The reviewer agent runs your CI suite and attempts to fix failures automatically. If it can't fix them within its budget, it creates the PR with a note describing what failed and why. You can fix the remaining issues manually or run `/specrails:retry` to try the reviewer phase again.
|
|
133
139
|
|
|
134
140
|
**I got a "409 Conflict" error during a pipeline run.**
|
|
135
141
|
|
|
@@ -64,7 +64,7 @@ The installer detects Codex CLI automatically and generates configuration in `.c
|
|
|
64
64
|
your-project/
|
|
65
65
|
├── AGENTS.md # SpecRails agent instructions for Codex
|
|
66
66
|
└── .codex/
|
|
67
|
-
├── skills/ # Workflow skills (/
|
|
67
|
+
├── skills/ # Workflow skills (/specrails:*, /opsx:*)
|
|
68
68
|
├── agents/ # Agent definitions (TOML)
|
|
69
69
|
├── rules/ # Per-layer coding conventions
|
|
70
70
|
├── agent-memory/ # Persistent agent memory
|
|
@@ -84,13 +84,13 @@ codex
|
|
|
84
84
|
Then invoke the setup skill:
|
|
85
85
|
|
|
86
86
|
```
|
|
87
|
-
/setup
|
|
87
|
+
/specrails:setup
|
|
88
88
|
```
|
|
89
89
|
|
|
90
90
|
Or run it non-interactively:
|
|
91
91
|
|
|
92
92
|
```bash
|
|
93
|
-
codex exec "run /setup --yes"
|
|
93
|
+
codex exec "run /specrails:setup --yes"
|
|
94
94
|
```
|
|
95
95
|
|
|
96
96
|
The wizard runs 5 phases:
|
|
@@ -114,13 +114,13 @@ codex
|
|
|
114
114
|
```
|
|
115
115
|
|
|
116
116
|
```
|
|
117
|
-
/
|
|
117
|
+
/specrails:implement "add a health check endpoint"
|
|
118
118
|
```
|
|
119
119
|
|
|
120
120
|
Or with a GitHub issue number:
|
|
121
121
|
|
|
122
122
|
```
|
|
123
|
-
/
|
|
123
|
+
/specrails:implement #42
|
|
124
124
|
```
|
|
125
125
|
|
|
126
126
|
This runs the full SpecRails pipeline: Architect → Developer → Reviewer → PR.
|
|
@@ -131,7 +131,7 @@ This runs the full SpecRails pipeline: Architect → Developer → Reviewer →
|
|
|
131
131
|
|
|
132
132
|
If you prefer the web interface, SpecRails Skills also work in **Codex Cloud** at [chatgpt.com/codex](https://chatgpt.com/codex). Connect your repository and use Skills from the UI.
|
|
133
133
|
|
|
134
|
-
Note that Codex Cloud runs asynchronously — long-running skills like `/
|
|
134
|
+
Note that Codex Cloud runs asynchronously — long-running skills like `/specrails:implement` are well-suited to this environment.
|
|
135
135
|
|
|
136
136
|
---
|
|
137
137
|
|
|
@@ -186,7 +186,7 @@ The installer warns if SpecRails artifacts already exist. You can merge or abort
|
|
|
186
186
|
|
|
187
187
|
### Placeholders not resolved
|
|
188
188
|
|
|
189
|
-
If you see `{{PLACEHOLDER}}` in generated files, `/setup` did not complete. Re-run `/setup` or fill the values manually.
|
|
189
|
+
If you see `{{PLACEHOLDER}}` in generated files, `/specrails:setup` did not complete. Re-run `/specrails:setup` or fill the values manually.
|
|
190
190
|
|
|
191
191
|
---
|
|
192
192
|
|