specrails-core 4.0.2 → 4.0.4

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 +73 -85
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -7,16 +7,16 @@
7
7
  [![Claude Code](https://img.shields.io/badge/Built%20for-Claude%20Code-blueviolet)](https://docs.anthropic.com/en/docs/claude-code)
8
8
  [![Codex](https://img.shields.io/badge/Built%20for-OpenAI%20Codex-412991)](https://github.com/openai/codex)
9
9
 
10
- **Your AI development team. From idea to production code.**
10
+ **Your agentic development team. From idea to production code.**
11
11
 
12
- One command gives your repo a full team of specialized AI agents: architect, developer, reviewer, product manager — all working together through a structured pipeline, fully adapted to your codebase.
12
+ One command turns your repo into a spec-driven pipeline with a team of specialized AI agents — architect, developers, reviewers, product manager — all adapted to your codebase.
13
13
 
14
14
  ```bash
15
- claude plugin install sr # Claude Code plugin (recommended)
16
- /specrails:enrich # configure for your project
15
+ npx specrails-core@latest init # install into the current repo
16
+ /specrails:enrich # optional: deep codebase analysis
17
17
  ```
18
18
 
19
- > **Requirements:** [Claude Code](https://docs.anthropic.com/en/docs/claude-code) or [Codex CLI](https://github.com/openai/codex) (choose one), git
19
+ > **Requirements:** [Claude Code](https://docs.anthropic.com/en/docs/claude-code) or [Codex CLI](https://github.com/openai/codex) (one of them), git, Node 18+.
20
20
 
21
21
  ---
22
22
 
@@ -27,93 +27,75 @@ Idea → Architecture → Implementation → Review → PR
27
27
  (sr-architect) (sr-developer) (sr-reviewer)
28
28
  ```
29
29
 
30
- Run `/specrails:implement "add dark mode"` — the pipeline designs, builds, reviews, and ships a pull request. No hand-holding required.
30
+ Run `/specrails:implement "add dark mode"` — the pipeline designs, builds, reviews, and ships a pull request. No hand-holding.
31
31
 
32
- Every artifact (agents, rules, personas) is generated **specifically for your project** by analyzing your actual codebase, tech stack, and CI setup. Not generic templates.
32
+ Every artifact (agents, rules, personas) is generated **specifically for your project** by analysing your actual codebase, tech stack, and CI setup. Not generic templates.
33
33
 
34
34
  ---
35
35
 
36
36
  ## Quick start
37
37
 
38
- ### Claude Code plugin (recommended)
39
-
40
38
  ```bash
41
- claude plugin install sr # install the sr plugin
42
- /specrails:enrich # run the 5-phase wizard (~5 min)
39
+ # 1. Install into the current repo
40
+ npx specrails-core@latest init
43
41
  ```
44
42
 
45
- Updates automatically: `claude plugin update sr`
43
+ The TUI asks you to pick a tier:
46
44
 
47
- ### Scaffold method (alternative)
45
+ - **Quick** (default) — agents and commands installed straight to `.claude/`, ready to use immediately. No AI interaction.
46
+ - **Full** — same as Quick plus `/specrails:enrich` (5-phase deep analysis: stack detection, VPC personas, competitive research). ~5 min.
48
47
 
49
48
  ```bash
50
- npx specrails-core@latest init --root-dir . # TUI: select agents, choose tier
51
- ```
52
-
53
- **Quick tier** (default) — agents installed directly, ready to use immediately. No AI interaction.
54
- **Full tier** — run `/specrails:enrich` after install for deep codebase analysis, VPC personas, and competitive research.
49
+ # 2. Optional — run enrich later if you picked Quick
50
+ /specrails:enrich
55
51
 
56
- ### Start building
57
-
58
- ```bash
52
+ # 3. Start building
59
53
  > /specrails:implement "add user authentication"
60
- > /specrails:implement #1, #2 # from local tickets (default)
61
- > /specrails:implement #42, #43 # from GitHub Issues (if configured)
54
+ > /specrails:implement #1, #2 # from local tickets (default)
55
+ > /specrails:implement #42 # from GitHub Issues (if configured)
62
56
  ```
63
57
 
64
58
  That's it. The pipeline takes over.
65
59
 
66
60
  ---
67
61
 
68
- ## Plugin vs scaffold
69
-
70
- | | Plugin | Scaffold |
71
- |--|--------|---------|
72
- | **What it contains** | Agents, skills, hooks, references | Nothing — project data only |
73
- | **Install** | `claude plugin install sr` | `npx specrails-core@latest init` |
74
- | **Updates** | `claude plugin update sr` | Re-run npx |
75
- | **Project data** | Generated by `/specrails:enrich` into `.specrails/` | Same |
76
- | **Use case** | Recommended for most projects | When you need full offline control |
77
-
78
- The plugin contains the logic (agent prompts, skills, commands). Running `/specrails:enrich` generates the project-specific data files (~8–10 files in `.specrails/`) — config, personas, memory, pipeline state. These are yours to edit and commit.
79
-
80
- ---
81
-
82
62
  ## What gets installed
83
63
 
84
- ### Plugin (logic — auto-updated via `claude plugin update sr`)
64
+ Everything lands in your repo — nothing auto-updates, nothing phones home. You own it, you commit it.
85
65
 
86
66
  | Category | Location | Purpose |
87
67
  |----------|----------|---------|
88
- | **Agents** | Plugin | 14 specialized AI agents |
89
- | **Commands** | Plugin | 17 workflow commands: `/specrails:implement`, `/specrails:get-backlog-specs`, `/specrails:why`, and more |
90
- | **Skills** | Plugin | OpenSpec skills (`/opsx:*`) included |
91
- | **Hooks & References** | Plugin | Agent hooks, reference docs |
92
-
93
- ### Project data (generated by `/specrails:enrich` — lives in your repo)
94
-
95
- | Category | Files | Purpose |
96
- |----------|-------|---------|
68
+ | **Agents** | `.claude/agents/` | 14 specialised AI agents |
69
+ | **Commands** | `.claude/commands/specrails/` | 17 workflow commands (`/specrails:implement`, `/specrails:get-backlog-specs`, `/specrails:why`, …) |
70
+ | **OpenSpec skills** | `.claude/commands/opsx/` | `/opsx:*` commands for spec artefacts |
97
71
  | **Config** | `.specrails/config.yaml` | Stack, CI commands, git workflow |
98
72
  | **Personas** | `.specrails/personas/*.md` | VPC user profiles, generated from your users |
99
73
  | **Rules** | `.specrails/rules/*.md` | Per-layer coding conventions |
100
74
  | **Memory** | `.specrails/agent-memory/` | Persistent knowledge — agents learn across sessions |
101
75
  | **Pipeline state** | `.specrails/pipeline/` | In-flight feature state for parallel builds |
102
76
 
77
+ To update, re-run the installer:
78
+
79
+ ```bash
80
+ npx specrails-core@latest init
81
+ ```
82
+
83
+ It refreshes the agents/commands while leaving your `.specrails/` data untouched.
84
+
103
85
  ---
104
86
 
105
- ## Why SpecRails
87
+ ## Why specrails
106
88
 
107
- | | SpecRails | Plain Claude Code | Cursor / Copilot |
89
+ | | specrails | Plain Claude Code | Cursor / Copilot |
108
90
  |---|---|---|---|
109
91
  | Structured pipeline | ✅ Architect → Dev → Review → PR | ❌ Manual | ❌ Manual |
110
- | Adapts to your codebase | ✅ Reads your actual stack/CI | ⚠️ Prompts only | ❌ |
92
+ | Adapts to your codebase | ✅ Reads your real stack/CI | ⚠️ Prompts only | ❌ |
111
93
  | Product-driven backlog | ✅ VPC persona scoring | ❌ | ❌ |
112
94
  | Parallel feature builds | ✅ Git worktrees | ❌ | ❌ |
113
95
  | Institutional memory | ✅ Agents learn across sessions | ❌ | ❌ |
114
96
  | Open source | ✅ MIT | N/A | ❌ |
115
97
 
116
- SpecRails is not a chat interface. It's a **development pipeline** that coordinates multiple specialized agents through your existing tools (GitHub Issues, JIRA, git, CI).
98
+ specrails is not a chat interface. It's a **development pipeline** that coordinates multiple specialised agents through your existing tools (GitHub Issues, JIRA, git, CI).
117
99
 
118
100
  ---
119
101
 
@@ -123,8 +105,8 @@ SpecRails is not a chat interface. It's a **development pipeline** that coordina
123
105
  |-------|-------|------|
124
106
  | **sr-architect** | Sonnet | Designs features: proposal, technical design, task breakdown |
125
107
  | **sr-developer** | Sonnet | Full-stack implementation |
126
- | **sr-backend-developer** | Sonnet | Backend-specialized implementation |
127
- | **sr-frontend-developer** | Sonnet | Frontend-specialized implementation |
108
+ | **sr-backend-developer** | Sonnet | Backend-specialised implementation |
109
+ | **sr-frontend-developer** | Sonnet | Frontend-specialised implementation |
128
110
  | **sr-reviewer** | Sonnet | Quality gate: runs CI, fixes issues, records learnings |
129
111
  | **sr-backend-reviewer** | Sonnet | Backend code review: API design, DB patterns, performance |
130
112
  | **sr-frontend-reviewer** | Sonnet | Frontend code review: UX, accessibility, component design |
@@ -134,7 +116,7 @@ SpecRails is not a chat interface. It's a **development pipeline** that coordina
134
116
  | **sr-merge-resolver** | Sonnet | AI-powered merge conflict resolution for multi-feature pipelines |
135
117
  | **sr-performance-reviewer** | Sonnet | Performance regression detection after implementation |
136
118
  | **sr-product-manager** | Opus | Product discovery: competitive analysis, VPC evaluation |
137
- | **sr-product-analyst** | Haiku | Read-only backlog analysis and prioritization |
119
+ | **sr-product-analyst** | Haiku | Read-only backlog analysis and prioritisation |
138
120
 
139
121
  ---
140
122
 
@@ -144,7 +126,7 @@ SpecRails is not a chat interface. It's a **development pipeline** that coordina
144
126
 
145
127
  ```bash
146
128
  /specrails:implement "add dark mode" # from a description
147
- /specrails:implement #85, #71 # from GitHub Issues
129
+ /specrails:implement #85, #71 # from tickets
148
130
  /specrails:implement UI, Analytics # explore areas, pick the best ideas
149
131
  ```
150
132
 
@@ -173,14 +155,14 @@ To discard without applying:
173
155
  rm -rf .claude/.dry-run/add-dark-mode/
174
156
  ```
175
157
 
176
- ### `/specrails:get-backlog-specs` — View prioritized backlog
158
+ ### `/specrails:get-backlog-specs` — View prioritised backlog
177
159
 
178
160
  ```bash
179
161
  /specrails:get-backlog-specs # show all areas
180
162
  /specrails:get-backlog-specs UI, Decks # filter by area
181
163
  ```
182
164
 
183
- Reads your tickets (local or GitHub Issues), scores by VPC persona match, recommends top 3 for next sprint.
165
+ Reads your tickets (local or GitHub Issues), scores by VPC persona match, recommends top 3 for the next sprint.
184
166
 
185
167
  ### `/specrails:auto-propose-backlog-specs` — Discover features
186
168
 
@@ -199,13 +181,13 @@ specrails-core ships with a built-in ticket system — no GitHub account or exte
199
181
 
200
182
  Tickets live in `.specrails/local-tickets.json` alongside your code. They're plain JSON and git-friendly.
201
183
 
202
- **Local tickets are the default.** The `/specrails:enrich` wizard defaults to local tickets and skips GitHub/JIRA credential setup unless you opt in.
184
+ **Local tickets are the default.** The `/specrails:enrich` wizard skips GitHub/JIRA credential setup unless you opt in.
203
185
 
204
186
  ```bash
205
- /specrails:implement #1, #4 # implement by ticket ID
206
- /specrails:get-backlog-specs # view prioritized backlog
207
- /specrails:auto-propose-backlog-specs # discover and create tickets with AI
208
- /specrails:propose-spec # create a ticket from a spec proposal
187
+ /specrails:implement #1, #4 # implement by ticket ID
188
+ /specrails:get-backlog-specs # view prioritised backlog
189
+ /specrails:auto-propose-backlog-specs # discover and create tickets with AI
190
+ /specrails:propose-spec # create a ticket from a spec proposal
209
191
  ```
210
192
 
211
193
  See [docs/local-tickets.md](./docs/local-tickets.md) for the full schema reference, concurrency model, and command integration details.
@@ -216,7 +198,7 @@ Migrating from GitHub Issues or JIRA? See [docs/migration-guide.md](./docs/migra
216
198
 
217
199
  ## VPC persona scoring
218
200
 
219
- Features are scored against your user personas using the VPC framework:
201
+ Features are scored against your user personas using the Value Proposition Canvas framework:
220
202
 
221
203
  ```
222
204
  +-----------------------------+ +-----------------------------+
@@ -227,7 +209,7 @@ Features are scored against your user personas using the VPC framework:
227
209
  +-----------------------------+ +-----------------------------+
228
210
  ```
229
211
 
230
- Each persona scores features 0-5. Features are ranked by score/effort ratio. No gut-feel product decisions.
212
+ Each persona scores features 0–5. Features are ranked by score / effort ratio. No gut-feel product decisions.
231
213
 
232
214
  ---
233
215
 
@@ -235,13 +217,13 @@ Each persona scores features 0-5. Features are ranked by score/effort ratio. No
235
217
 
236
218
  | Tool | Required | Purpose |
237
219
  |------|----------|---------|
238
- | **Claude Code** | Yes | AI agent runtime — [install](https://docs.anthropic.com/en/docs/claude-code) |
220
+ | **Claude Code** or **Codex CLI** | Yes (one of them) | AI agent runtime |
239
221
  | **git** | Yes | Repository detection |
240
- | **npm / Node 18+** | For scaffold method only | Needed for `npx specrails-core@latest init` |
222
+ | **Node 18+** | Yes | Needed for `npx specrails-core@latest init` |
241
223
  | **GitHub CLI** (`gh`) | Optional | Backlog sync to GitHub Issues, PR creation. Not needed with local tickets. |
242
224
  | **JIRA CLI** (`jira`) | Optional | Backlog sync to JIRA. Not needed with local tickets. |
243
225
 
244
- The plugin method has no Node.js requirement. The scaffold method checks for prerequisites and offers to install missing ones.
226
+ The installer checks for prerequisites and offers to install missing ones.
245
227
 
246
228
  ---
247
229
 
@@ -249,18 +231,18 @@ The plugin method has no Node.js requirement. The scaffold method checks for pre
249
231
 
250
232
  Stack-agnostic. The `/specrails:enrich` wizard detects and adapts to whatever you're running:
251
233
 
252
- **Backend:** Python/FastAPI, Node/Express, Go/Gin, Rust/Actix, Java/Spring, Ruby/Rails, .NET
253
- **Frontend:** React, Vue, Angular, Svelte, Next.js, Nuxt
254
- **Database:** PostgreSQL, MySQL, SQLite, MongoDB, Redis
255
- **CI/CD:** GitHub Actions, GitLab CI, Jenkins, Makefile
256
- **Testing:** pytest, vitest, jest, go test, cargo test, rspec
234
+ - **Backend:** Python/FastAPI, Node/Express, Go/Gin, Rust/Actix, Java/Spring, Ruby/Rails, .NET
235
+ - **Frontend:** React, Vue, Angular, Svelte, Next.js, Nuxt
236
+ - **Database:** PostgreSQL, MySQL, SQLite, MongoDB, Redis
237
+ - **CI/CD:** GitHub Actions, GitLab CI, Jenkins, Makefile
238
+ - **Testing:** pytest, vitest, jest, go test, cargo test, rspec
257
239
 
258
240
  ---
259
241
 
260
242
  ## Design principles
261
243
 
262
- 1. **Two-step install** — Shell handles prerequisites, Claude handles intelligence. No API keys beyond Claude Code auth.
263
- 2. **Self-cleaning** — All scaffolding removed after setup. Only final, project-specific files remain.
244
+ 1. **Local by default** — Everything lives in your repo. No cloud services, no telemetry, no phone home.
245
+ 2. **Self-cleaning** — Installer scaffolding is removed after setup. Only final, project-specific files remain.
264
246
  3. **Context-first** — Every generated file uses your real paths, patterns, and CI commands.
265
247
  4. **Persona-driven** — Product decisions grounded in researched user personas, not assumptions.
266
248
  5. **Institutional memory** — Agents learn across sessions. Reviewer learnings feed back to future developers.
@@ -270,14 +252,11 @@ Stack-agnostic. The `/specrails:enrich` wizard detects and adapts to whatever yo
270
252
 
271
253
  ## FAQ
272
254
 
273
- **Can I customize the agents after installation?**
274
- With the plugin method, project data files in `.specrails/` are yours to edit — personas, rules, config. With the scaffold method, `.claude/` agent files are also editable. To update plugin logic, run `claude plugin update sr`.
255
+ **Can I customise the agents after installation?**
256
+ Yes. Everything under `.claude/` and `.specrails/` is yours to edit — agent prompts, personas, rules, config. Commit what makes sense, gitignore what's transient.
275
257
 
276
258
  **Can I re-run the wizard?**
277
- Run `/specrails:enrich` again at any time to regenerate or update project data files.
278
-
279
- **Plugin vs scaffold — which should I use?**
280
- Plugin is recommended: it has no Node.js requirement, updates automatically, and separates logic from project data. Use scaffold if you need full offline control or want to version the agent prompts themselves.
259
+ Run `/specrails:enrich` again at any time to regenerate or update project data files. Re-running `npx specrails-core@latest init` refreshes the agents/commands without touching `.specrails/`.
281
260
 
282
261
  **Does this work without GitHub CLI?**
283
262
  Yes. Local tickets are the default and need no external tools. `/specrails:implement "description"` also works without `gh` — it just skips automated PR creation.
@@ -289,16 +268,25 @@ Not simultaneously for the same project — backlog commands use one active prov
289
268
  A full `/specrails:implement` cycle for one feature typically costs a few dollars in Claude API usage. The sr-product-manager uses Opus; all other agents use Sonnet or Haiku.
290
269
 
291
270
  **Does it work with private repos?**
292
- Yes. Everything runs locally through Claude Code. No external services beyond the Claude API.
271
+ Yes. Everything runs locally through Claude Code (or Codex). No external services beyond the model API.
293
272
 
294
- **How do I use SpecRails with Codex?**
295
- Codex uses the scaffold method: `npx specrails-core@latest init --root-dir .`. See [docs/user-docs/getting-started-codex.md](./docs/user-docs/getting-started-codex.md).
273
+ **How do I use specrails with Codex?**
274
+ Same install path: `npx specrails-core@latest init --root-dir .`. The TUI detects Codex and adjusts the agent configuration. See [docs/user-docs/getting-started-codex.md](./docs/user-docs/getting-started-codex.md).
296
275
 
297
276
  ---
298
277
 
299
- ## Also in the SpecRails ecosystem
278
+ ## Related
279
+
280
+ - **[specrails-hub](https://github.com/fjpulidop/specrails-hub)** — desktop dashboard that visualises specrails pipelines (macOS, open source).
281
+ - **[specrails.dev](https://specrails.dev)** — landing page and documentation.
282
+
283
+ ---
284
+
285
+ ## Support
286
+
287
+ If specrails-core is useful to you, you can donate on [Ko-fi](https://ko-fi.com/D1D81Y002C) ☕ to support ongoing development.
300
288
 
301
- - **Product Hunt** — [Vote for SpecRails on launch day](https://www.producthunt.com) _(link goes live on launch day — star this repo to get notified)_
289
+ [![Donate on Ko-fi](https://img.shields.io/badge/Donate-Ko--fi-FF5E5B?logo=kofi&logoColor=white&style=flat-square)](https://ko-fi.com/D1D81Y002C)
302
290
 
303
291
  ---
304
292
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "specrails-core",
3
- "version": "4.0.2",
3
+ "version": "4.0.4",
4
4
  "description": "AI agent workflow system for Claude Code — installs 12 specialized agents, orchestration commands, and persona-driven product discovery into any repository",
5
5
  "bin": {
6
6
  "specrails-core": "bin/specrails-core.js"