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.
Files changed (56) hide show
  1. package/README.md +76 -48
  2. package/bin/doctor.sh +1 -1
  3. package/commands/doctor.md +1 -1
  4. package/commands/setup.md +70 -70
  5. package/docs/README.md +3 -2
  6. package/docs/agents.md +15 -15
  7. package/docs/changelog.md +20 -20
  8. package/docs/concepts.md +3 -3
  9. package/docs/customization.md +18 -5
  10. package/docs/deployment.md +20 -5
  11. package/docs/getting-started.md +16 -27
  12. package/docs/installation.md +81 -48
  13. package/docs/local-tickets.md +11 -12
  14. package/docs/migration-guide.md +9 -9
  15. package/docs/playbook-parallel-dev.md +8 -8
  16. package/docs/playbook-product-discovery.md +1 -1
  17. package/docs/plugin-architecture.md +137 -0
  18. package/docs/research/codex-compatibility-analysis.md +11 -11
  19. package/docs/research/mcp-feasibility-analysis.md +5 -5
  20. package/docs/testing/test-matrix-codex.md +1 -1
  21. package/docs/user-docs/cli-reference.md +57 -57
  22. package/docs/user-docs/codex-vs-claude-code.md +7 -7
  23. package/docs/user-docs/faq.md +32 -26
  24. package/docs/user-docs/getting-started-codex.md +7 -7
  25. package/docs/user-docs/installation.md +47 -38
  26. package/docs/user-docs/quick-start.md +20 -26
  27. package/docs/workflows.md +62 -62
  28. package/install.sh +3 -3
  29. package/package.json +1 -1
  30. package/templates/agents/sr-merge-resolver.md +1 -1
  31. package/templates/claude-md/CLAUDE-quickstart.md +2 -2
  32. package/templates/commands/{sr → specrails}/batch-implement.md +18 -18
  33. package/templates/commands/{sr → specrails}/implement.md +8 -8
  34. package/templates/commands/{sr → specrails}/memory-inspect.md +3 -3
  35. package/templates/commands/{sr → specrails}/merge-resolve.md +1 -1
  36. package/templates/commands/{sr → specrails}/opsx-diff.md +1 -1
  37. package/templates/commands/{sr → specrails}/product-backlog.md +7 -7
  38. package/templates/commands/{sr → specrails}/propose-spec.md +1 -1
  39. package/templates/commands/{sr → specrails}/refactor-recommender.md +1 -1
  40. package/templates/commands/{sr → specrails}/retry.md +13 -13
  41. package/templates/commands/{sr → specrails}/team-debug.md +5 -5
  42. package/templates/commands/{sr → specrails}/team-review.md +4 -4
  43. package/templates/commands/{sr → specrails}/telemetry.md +2 -2
  44. package/templates/commands/{sr → specrails}/update-product-driven-backlog.md +2 -2
  45. package/templates/commands/{sr → specrails}/vpc-drift.md +4 -4
  46. package/templates/commands/{sr → specrails}/why.md +5 -5
  47. package/templates/commands/test.md +2 -2
  48. package/templates/skills/sr-batch-implement/SKILL.md +18 -18
  49. package/templates/skills/sr-implement/SKILL.md +8 -8
  50. package/templates/skills/sr-product-backlog/SKILL.md +7 -7
  51. package/templates/skills/sr-refactor-recommender/SKILL.md +1 -1
  52. package/templates/skills/sr-update-backlog/SKILL.md +2 -2
  53. package/templates/skills/sr-why/SKILL.md +5 -5
  54. package/update.sh +2 -2
  55. /package/templates/commands/{sr → specrails}/compat-check.md +0 -0
  56. /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 (/sr:implement, /sr:product-backlog, ...)
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
- │ /sr:implement, /sr:batch-implement, agents │
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 `/sr: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.
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
- | `/sr:implement` pipeline | Requires Agent tool (subagent spawning) |
337
- | `/sr:batch-implement` | Requires git worktree isolation |
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/sr/` | ✅ | ❌ |
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
- ### `/sr:implement` ✅ Both
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
- /sr:implement #85
30
- /sr:implement #85, #71, #63
31
- /sr:implement "add a health check endpoint"
32
- /sr:implement UI, Analytics
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
- ### `/sr:telemetry` ✅ Both
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
- /sr:telemetry
69
- /sr:telemetry --period today
70
- /sr:telemetry --agent sr-developer
71
- /sr:telemetry --format json
72
- /sr:telemetry --save
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
- ### `/sr:merge-resolve` ✅ Both
86
+ ### `/specrails:merge-resolve` ✅ Both
87
87
 
88
88
  Resolve git conflict markers using AI-powered context analysis.
89
89
 
90
90
  ```
91
- /sr:merge-resolve
92
- /sr:merge-resolve --files src/api/routes.ts
93
- /sr:merge-resolve --context openspec/changes/
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
- ### `/sr:retry` ✅ Both
108
+ ### `/specrails:retry` ✅ Both
109
109
 
110
- Resume a failed `/sr:implement` run from the last successful phase.
110
+ Resume a failed `/specrails:implement` run from the last successful phase.
111
111
 
112
112
  ```
113
- /sr:retry <feature-name>
114
- /sr:retry --list
115
- /sr:retry <feature-name> --from architect
116
- /sr:retry <feature-name> --dry-run
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
- ### `/sr:batch-implement` ⚠️ Limited on Codex
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
- /sr:batch-implement #85, #71, #63
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 `/sr:implement` with multiple issues when you want explicit control over parallel execution.
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
- ### `/sr:product-backlog` ✅ Both
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
- /sr:product-backlog
155
- /sr:product-backlog UI, API
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
- ### `/sr:update-product-driven-backlog` ✅ Both
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
- /sr:update-product-driven-backlog
168
- /sr:update-product-driven-backlog UI, API
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
- ### `/sr:refactor-recommender` ✅ Both
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
- /sr:refactor-recommender
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
- ### `/sr:compat-check` ✅ Both
189
+ ### `/specrails:compat-check` ✅ Both
190
190
 
191
191
  Analyze the backwards-compatibility impact of a proposed change.
192
192
 
193
193
  ```
194
- /sr:compat-check #85
195
- /sr:compat-check #85 --save
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 `/sr:implement` pipeline.
202
+ The Architect runs this automatically as part of every `/specrails:implement` pipeline.
203
203
 
204
204
  ---
205
205
 
206
- ### `/sr:why` ✅ Both
206
+ ### `/specrails:why` ✅ Both
207
207
 
208
208
  Search agent explanation records in plain language.
209
209
 
210
210
  ```
211
- /sr:why "why did we choose this database schema"
212
- /sr:why "explain the auth middleware design"
213
- /sr:why "why is pagination implemented this way"
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. `/sr:why` searches these records semantically. Useful for onboarding, code review, and revisiting past decisions.
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
- ### `/sr:vpc-drift` ✅ Both
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
- /sr:vpc-drift
226
- /sr:vpc-drift --persona "Alex,Sara"
227
- /sr:vpc-drift --verbose
228
- /sr:vpc-drift --format json
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
- ### `/sr:memory-inspect` ✅ Both
235
+ ### `/specrails:memory-inspect` ✅ Both
236
236
 
237
237
  Inspect and clean up agent memory directories.
238
238
 
239
239
  ```
240
- /sr:memory-inspect
241
- /sr:memory-inspect sr-developer
242
- /sr:memory-inspect --stale 14
243
- /sr:memory-inspect --prune
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
- ### `/sr:propose-spec` ✅ Both
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
- /sr:propose-spec "add rate limiting to the API"
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
- ### `/sr:opsx-diff` — Spec Change Diff
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
- /sr:opsx-diff <change-name>
355
- /sr:opsx-diff my-feature --format json
356
- /sr:opsx-diff my-feature --summary-only
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 (`/sr:*`, `/opsx:*`)** | ✅ Full support | ✅ Full support |
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 `/sr:*` and `/opsx:*` skills run identically on both platforms:
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
- - `/sr:implement` — full pipeline (design → code → review → PR)
33
- - `/sr:product-backlog` — VPC-ranked backlog view
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
- `/sr:batch-implement` (multiple issues in parallel) uses git worktree isolation. On Claude Code this runs locally with full isolation. On Codex:
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 /sr:implement #42"
86
+ claude --print "run /specrails:implement #42"
87
87
 
88
88
  # Codex
89
- codex exec "run /sr:implement #42"
89
+ codex exec "run /specrails:implement #42"
90
90
  ```
91
91
 
92
92
  Skills themselves are the same — only the CLI invocation differs.
@@ -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
- It creates a `.claude/` directory with agent templates, commands, and configuration files. It does not modify your source code, create commits, or push anything. Your project is unchanged `.claude/` is the only addition.
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
- Yes. Node 18+ is required to run `npx specrails-core@latest`. Once installed, SpecRails works with any language or framework — the agents adapt to whatever stack your project uses.
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 `/sr:implement` accept ticket IDs or plain text:
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
- /sr:implement #1, #4
23
- /sr:implement "add rate limiting to the API"
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 /sr:implement always create a PR?**
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
- /sr:implement --dry-run "add dark mode"
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
- /sr:implement --apply dark-mode
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 `/sr:retry` to resume from the last successful phase instead of starting over:
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
- /sr:retry dark-mode
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
- /sr:implement #42, #43, #44
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. After setup, the generated agent files are in `.claude/agents/`. Edit them directly to change behavior, add constraints, or update instructions. Changes take effect on the next run.
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
- Run the installer again in your project:
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 agents with any new templates. See the [updating guide](../updating.md) for details.
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/`. Make sure you opened Claude Code from inside your project directory (the one where you ran `npx specrails-core@latest init`).
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 `/sr:retry` to try the reviewer phase again.
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 (/sr:*, /opsx:*)
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
- /sr:implement "add a health check endpoint"
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
- /sr:implement #42
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 `/sr:implement` are well-suited to this environment.
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