specrails-core 1.0.1 → 1.2.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/LICENSE +21 -0
- package/README.md +144 -151
- package/bin/doctor.sh +118 -0
- package/bin/specrails-core.js +3 -1
- package/commands/doctor.md +62 -0
- package/commands/setup.md +157 -3
- package/install.sh +36 -23
- package/integration-contract.json +28 -0
- package/package.json +24 -4
- package/templates/agents/sr-doc-sync.md +77 -10
- package/templates/claude-md/CLAUDE-quickstart.md +58 -0
- package/templates/commands/sr/health-check.md +135 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Javier Pulido
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,110 +1,121 @@
|
|
|
1
1
|
# specrails-core
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/specrails-core)
|
|
4
|
+
[](https://opensource.org/licenses/MIT)
|
|
5
|
+
[](https://nodejs.org)
|
|
4
6
|
|
|
5
|
-
|
|
7
|
+
**AI agent workflow system for [Claude Code](https://claude.ai/code).** Installs a complete product-driven development pipeline into any repository — 12 specialized agents, orchestration commands, persona-based product discovery, and per-layer coding conventions — all generated specifically for your codebase.
|
|
6
8
|
|
|
7
|
-
|
|
9
|
+
```bash
|
|
10
|
+
npx specrails-core@latest init --root-dir <your-project>
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
---
|
|
8
14
|
|
|
9
|
-
|
|
15
|
+
## The pipeline
|
|
10
16
|
|
|
11
17
|
```
|
|
12
|
-
Product Discovery
|
|
13
|
-
(sr-product-manager)
|
|
18
|
+
Product Discovery → Architecture → Implementation → Review → Ship
|
|
19
|
+
(sr-product-manager) (sr-architect) (sr-developer) (sr-reviewer) (PR)
|
|
14
20
|
```
|
|
15
21
|
|
|
16
|
-
|
|
22
|
+
One command runs the full cycle:
|
|
17
23
|
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
| **Personas** | `.claude/agents/personas/*.md` | Value Proposition Canvas profiles for your target users, generated from competitive research |
|
|
24
|
-
| **Commands** | `.claude/commands/sr/*.md` | Workflow orchestrators (`/sr:implement`, `/sr:product-backlog`, `/sr:update-product-driven-backlog`) |
|
|
25
|
-
| **Rules** | `.claude/rules/*.md` | Per-layer coding conventions, loaded conditionally by file path |
|
|
26
|
-
| **Memory** | `.claude/agent-memory/` | Persistent knowledge directories — agents learn across sessions |
|
|
27
|
-
| **Config** | `.claude/settings.json`, `CLAUDE.md` | Permissions, project context, architecture reference |
|
|
24
|
+
```
|
|
25
|
+
/sr:implement #85, #71 # implement GitHub Issues
|
|
26
|
+
/sr:implement "add dark mode" # implement from description
|
|
27
|
+
/sr:implement UI, Analytics # explore areas, pick the best ideas
|
|
28
|
+
```
|
|
28
29
|
|
|
29
|
-
|
|
30
|
+
Multiple features run in parallel using git worktrees. Single features run sequentially.
|
|
30
31
|
|
|
31
|
-
|
|
32
|
+
---
|
|
32
33
|
|
|
33
|
-
|
|
34
|
+
## Quick start
|
|
34
35
|
|
|
35
|
-
**
|
|
36
|
+
**Step 1 — Install into your project**
|
|
36
37
|
|
|
37
38
|
```bash
|
|
38
|
-
npx specrails-core@latest init --root-dir
|
|
39
|
+
npx specrails-core@latest init --root-dir /path/to/your/repo
|
|
39
40
|
```
|
|
40
41
|
|
|
41
|
-
|
|
42
|
+
The installer scaffolds temporary setup files into `.claude/` and checks prerequisites (Claude Code, git, npm, GitHub CLI).
|
|
43
|
+
|
|
44
|
+
**Step 2 — Run the setup wizard inside Claude Code**
|
|
42
45
|
|
|
43
46
|
```bash
|
|
44
|
-
|
|
45
|
-
|
|
47
|
+
cd /path/to/your/repo
|
|
48
|
+
claude # open Claude Code
|
|
49
|
+
> /setup # run the interactive setup wizard
|
|
46
50
|
```
|
|
47
51
|
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
1. **Checks prerequisites** — git, Claude Code CLI, npm, OpenSpec CLI, GitHub CLI
|
|
51
|
-
2. **Offers to install missing tools** — npm via nvm, OpenSpec via npm
|
|
52
|
-
3. **Detects existing setup** — warns if `.claude/` or `openspec/` already exist
|
|
53
|
-
4. **Scaffolds temporary files** — copies templates and the `/setup` command into `.claude/`
|
|
52
|
+
Claude runs a 5-phase wizard that reads your actual codebase and generates everything tailored to your stack:
|
|
54
53
|
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
54
|
+
| Phase | What happens |
|
|
55
|
+
|-------|-------------|
|
|
56
|
+
| **1. Codebase Analysis** | Detects your stack, layers, CI commands, and coding conventions |
|
|
57
|
+
| **2. User Personas** | Researches your competitive landscape, generates VPC personas |
|
|
58
|
+
| **3. Configuration** | Choose backlog (GitHub Issues / JIRA / none), git workflow, agents |
|
|
59
|
+
| **4. File Generation** | Writes all agents, commands, rules — fully contextualized |
|
|
60
|
+
| **5. Cleanup** | Self-destructs scaffolding, only final files remain |
|
|
61
61
|
|
|
62
|
-
|
|
62
|
+
---
|
|
63
63
|
|
|
64
|
-
|
|
65
|
-
|-------|-------------|-------------|
|
|
66
|
-
| **1. Codebase Analysis** | Reads your repo structure, detects stack, layers, CI commands, and coding conventions | Confirm or modify detected architecture |
|
|
67
|
-
| **2. User Personas** | Asks who your target users are, researches the competitive landscape online, generates full VPC personas | Describe your users, approve generated personas |
|
|
68
|
-
| **3. Configuration** | Choose backlog provider (GitHub Issues / JIRA / none), access mode (read/write or read-only), git workflow (auto or manual), agents, and commands | Select options |
|
|
69
|
-
| **4. File Generation** | Fills all templates with your project's context and writes final files | Automatic |
|
|
70
|
-
| **5. Cleanup** | Removes scaffolding (`/setup` command, templates), adds `specrails/` to `.gitignore` | Confirm cleanup |
|
|
64
|
+
## What gets installed
|
|
71
65
|
|
|
72
|
-
|
|
66
|
+
| Category | Location | Description |
|
|
67
|
+
|----------|----------|-------------|
|
|
68
|
+
| **Agents** | `.claude/agents/*.md` | 12 specialized AI agents |
|
|
69
|
+
| **Personas** | `.claude/agents/personas/*.md` | VPC user profiles from competitive research |
|
|
70
|
+
| **Commands** | `.claude/commands/sr/*.md` | `/sr:implement`, `/sr:product-backlog`, `/sr:update-product-driven-backlog` |
|
|
71
|
+
| **Rules** | `.claude/rules/*.md` | Per-layer coding conventions, loaded by file path |
|
|
72
|
+
| **Memory** | `.claude/agent-memory/` | Persistent agent knowledge across sessions |
|
|
73
|
+
| **Config** | `.claude/settings.json`, `CLAUDE.md` | Permissions, project context, architecture reference |
|
|
73
74
|
|
|
74
|
-
|
|
75
|
+
---
|
|
75
76
|
|
|
76
|
-
|
|
77
|
-
|------|----------|---------|
|
|
78
|
-
| **Git** | Yes | Repository detection |
|
|
79
|
-
| **Claude Code** | Yes | AI agent runtime — [install](https://docs.anthropic.com/en/docs/claude-code) |
|
|
80
|
-
| **npm** | Recommended | Needed to install OpenSpec CLI |
|
|
81
|
-
| **OpenSpec CLI** | Recommended | Spec-driven design workflow (`/opsx:ff`, `/opsx:apply`) |
|
|
82
|
-
| **GitHub CLI** (`gh`) | Optional | Backlog sync to GitHub Issues, PR creation |
|
|
83
|
-
| **JIRA CLI** (`jira`) | Optional | Backlog sync to JIRA (alternative to GitHub Issues) |
|
|
77
|
+
## Why SpecRails
|
|
84
78
|
|
|
85
|
-
|
|
79
|
+
| | SpecRails | Plain Claude Code | Cursor / Copilot |
|
|
80
|
+
|---|---|---|---|
|
|
81
|
+
| Structured pipeline | ✅ Architect → Dev → Review → PR | ❌ Manual | ❌ Manual |
|
|
82
|
+
| Adapts to your codebase | ✅ Reads your actual stack/CI | ⚠️ Prompts only | ❌ |
|
|
83
|
+
| Product-driven backlog | ✅ VPC persona scoring | ❌ | ❌ |
|
|
84
|
+
| Parallel feature builds | ✅ Git worktrees | ❌ | ❌ |
|
|
85
|
+
| Dry-run / preview mode | ✅ Preview before committing | ❌ | ❌ |
|
|
86
|
+
| Institutional memory | ✅ Agents learn across sessions | ❌ | ❌ |
|
|
87
|
+
| Open source | ✅ MIT | N/A | ❌ |
|
|
86
88
|
|
|
87
|
-
|
|
89
|
+
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).
|
|
88
90
|
|
|
89
|
-
|
|
91
|
+
---
|
|
90
92
|
|
|
91
|
-
|
|
93
|
+
## The agents
|
|
92
94
|
|
|
93
|
-
|
|
95
|
+
| Agent | Model | Role |
|
|
96
|
+
|-------|-------|------|
|
|
97
|
+
| **sr-architect** | Sonnet | Designs features — proposal, technical design, task breakdown |
|
|
98
|
+
| **sr-developer** | Sonnet | Full-stack implementation from architect artifacts |
|
|
99
|
+
| **sr-backend-developer** | Sonnet | Backend-specialized implementation |
|
|
100
|
+
| **sr-frontend-developer** | Sonnet | Frontend-specialized implementation |
|
|
101
|
+
| **sr-reviewer** | Sonnet | Final quality gate — runs CI, fixes issues, records learnings |
|
|
102
|
+
| **sr-backend-reviewer** | Sonnet | API design, database patterns, performance review |
|
|
103
|
+
| **sr-frontend-reviewer** | Sonnet | UX patterns, accessibility, component design review |
|
|
104
|
+
| **sr-test-writer** | Sonnet | Generates unit, integration, and e2e tests |
|
|
105
|
+
| **sr-security-reviewer** | Sonnet | Secrets detection, OWASP checks, dependency audit |
|
|
106
|
+
| **sr-doc-sync** | Sonnet | Changelogs, READMEs, API docs after every change |
|
|
107
|
+
| **sr-product-manager** | Opus | Competitive analysis, VPC evaluation, feature ideation |
|
|
108
|
+
| **sr-product-analyst** | Haiku | Read-only backlog analysis and prioritization |
|
|
94
109
|
|
|
95
|
-
The
|
|
110
|
+
The `/sr:implement` pipeline routes tasks to the right agent automatically based on layer tags.
|
|
96
111
|
|
|
97
|
-
|
|
98
|
-
/sr:implement #85, #71 # implement specific GitHub Issues
|
|
99
|
-
/sr:implement "add dark mode" # implement from a text description
|
|
100
|
-
/sr:implement UI, Analytics # explore areas and pick the best ideas
|
|
101
|
-
```
|
|
112
|
+
---
|
|
102
113
|
|
|
103
|
-
|
|
114
|
+
## Product discovery commands
|
|
104
115
|
|
|
105
|
-
### `/sr:product-backlog` —
|
|
116
|
+
### `/sr:product-backlog` — Prioritized backlog
|
|
106
117
|
|
|
107
|
-
Reads GitHub Issues labeled `product-driven-backlog`,
|
|
118
|
+
Reads GitHub Issues labeled `product-driven-backlog`, scores them against your VPC personas, and recommends the top 3 for the next sprint.
|
|
108
119
|
|
|
109
120
|
```
|
|
110
121
|
/sr:product-backlog # show all areas
|
|
@@ -113,35 +124,43 @@ Reads GitHub Issues labeled `product-driven-backlog`, sorts by VPC persona score
|
|
|
113
124
|
|
|
114
125
|
### `/sr:update-product-driven-backlog` — Discover new features
|
|
115
126
|
|
|
116
|
-
|
|
127
|
+
Analyzes your codebase against each persona's jobs/pains/gains, generates new feature ideas, and creates GitHub Issues for the best ones.
|
|
128
|
+
|
|
129
|
+
#### Dry-run / preview mode
|
|
117
130
|
|
|
131
|
+
Not ready to commit? Run the full pipeline without touching git or GitHub:
|
|
132
|
+
|
|
133
|
+
```bash
|
|
134
|
+
/sr:implement "add dark mode" --dry-run
|
|
135
|
+
/sr:implement #85 --preview # --preview is an alias for --dry-run
|
|
118
136
|
```
|
|
119
|
-
|
|
120
|
-
|
|
137
|
+
|
|
138
|
+
All agents run normally (architect, developer, tests, docs, review). Generated files land in `.claude/.dry-run/<feature-name>/` instead of your working tree. No branches, commits, PRs, or issue updates are created.
|
|
139
|
+
|
|
140
|
+
When you're happy with the preview, apply the cached output:
|
|
141
|
+
|
|
142
|
+
```bash
|
|
143
|
+
/sr:implement --apply add-dark-mode # copies files to real paths, then ships
|
|
121
144
|
```
|
|
122
145
|
|
|
123
|
-
|
|
146
|
+
To discard without applying:
|
|
124
147
|
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
| **sr-developer** | Sonnet | Implements features: reads the architect's artifacts and writes production code across all layers |
|
|
129
|
-
| **sr-backend-developer** | Sonnet | Specialized backend implementation (lighter prompt, backend-only CI) |
|
|
130
|
-
| **sr-frontend-developer** | Sonnet | Specialized frontend implementation (lighter prompt, frontend-only CI) |
|
|
131
|
-
| **sr-reviewer** | Sonnet | Final quality gate: runs exact CI checks, fixes issues, records learnings for future developers |
|
|
132
|
-
| **sr-backend-reviewer** | Sonnet | Backend-focused code review: API design, database patterns, performance |
|
|
133
|
-
| **sr-frontend-reviewer** | Sonnet | Frontend-focused code review: UX patterns, accessibility, component design |
|
|
134
|
-
| **sr-test-writer** | Sonnet | Generates tests: unit, integration, and e2e tests using your project's test framework |
|
|
135
|
-
| **sr-security-reviewer** | Sonnet | Security scanning: secrets detection, OWASP checks, dependency vulnerabilities |
|
|
136
|
-
| **sr-doc-sync** | Sonnet | Documentation sync: updates changelogs, READMEs, and API docs after changes |
|
|
137
|
-
| **sr-product-manager** | Opus | Product discovery: competitive analysis, VPC evaluation, feature ideation |
|
|
138
|
-
| **sr-product-analyst** | Haiku | Read-only backlog analysis: prioritization, gap analysis, reporting |
|
|
148
|
+
```bash
|
|
149
|
+
rm -rf .claude/.dry-run/add-dark-mode/
|
|
150
|
+
```
|
|
139
151
|
|
|
140
|
-
|
|
152
|
+
### `/sr:product-backlog` — View prioritized backlog
|
|
153
|
+
|
|
154
|
+
```
|
|
155
|
+
/sr:update-product-driven-backlog # explore all areas
|
|
156
|
+
/sr:update-product-driven-backlog Analytics # focus on one area
|
|
157
|
+
```
|
|
141
158
|
|
|
142
|
-
|
|
159
|
+
---
|
|
143
160
|
|
|
144
|
-
|
|
161
|
+
## Value Proposition Canvas scoring
|
|
162
|
+
|
|
163
|
+
Every feature is evaluated against your user personas before implementation. Features score 0–5 per persona based on jobs-to-be-done, pains, and gains — ranked by score / effort ratio. Product decisions stay grounded in real user needs.
|
|
145
164
|
|
|
146
165
|
```
|
|
147
166
|
+-----------------------------+ +-----------------------------+
|
|
@@ -153,52 +172,28 @@ Every feature idea is evaluated against your project's user personas using the V
|
|
|
153
172
|
+-----------------------------+ +-----------------------------+
|
|
154
173
|
```
|
|
155
174
|
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
##
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
│ │ ├── sr-frontend-reviewer.md # Frontend code review agent
|
|
175
|
-
│ │ ├── sr-test-writer.md # Test generation agent
|
|
176
|
-
│ │ ├── sr-security-reviewer.md # Security scanning agent
|
|
177
|
-
│ │ ├── sr-doc-sync.md # Documentation sync agent
|
|
178
|
-
│ │ ├── sr-product-manager.md # Product discovery agent
|
|
179
|
-
│ │ └── sr-product-analyst.md # Read-only analysis agent
|
|
180
|
-
│ ├── commands/
|
|
181
|
-
│ │ └── sr/
|
|
182
|
-
│ │ ├── implement.md # Implementation pipeline orchestrator
|
|
183
|
-
│ │ ├── product-backlog.md # Backlog viewer with VPC scoring
|
|
184
|
-
│ │ └── update-product-driven-backlog.md # Product discovery & issue sync
|
|
185
|
-
│ ├── personas/
|
|
186
|
-
│ │ └── persona.md # VPC persona template
|
|
187
|
-
│ ├── rules/
|
|
188
|
-
│ │ └── layer.md # Per-layer convention template
|
|
189
|
-
│ ├── claude-md/
|
|
190
|
-
│ │ └── root.md # Root CLAUDE.md template
|
|
191
|
-
│ └── settings/
|
|
192
|
-
│ └── settings.json # Permission template
|
|
193
|
-
└── prompts/
|
|
194
|
-
├── analyze-codebase.md # Guide for codebase analysis
|
|
195
|
-
├── generate-personas.md # Guide for VPC persona generation
|
|
196
|
-
└── infer-conventions.md # Guide for convention detection
|
|
197
|
-
```
|
|
175
|
+
---
|
|
176
|
+
|
|
177
|
+
## Prerequisites
|
|
178
|
+
|
|
179
|
+
| Tool | Required | Purpose |
|
|
180
|
+
|------|----------|---------|
|
|
181
|
+
| **Claude Code** | Yes | AI agent runtime — [install](https://docs.anthropic.com/en/docs/claude-code) |
|
|
182
|
+
| **Git** | Yes | Repository detection |
|
|
183
|
+
| **npm** | Recommended | Install OpenSpec CLI |
|
|
184
|
+
| **OpenSpec CLI** | Recommended | Spec-driven design workflow |
|
|
185
|
+
| **GitHub CLI** (`gh`) | Optional | Backlog sync and PR creation |
|
|
186
|
+
| **JIRA CLI** | Optional | JIRA as backlog alternative |
|
|
187
|
+
|
|
188
|
+
The installer checks for each tool and offers to install missing ones automatically.
|
|
189
|
+
|
|
190
|
+
> You only need one backlog provider. If you use neither, `/sr:implement "description"` still works.
|
|
191
|
+
|
|
192
|
+
---
|
|
198
193
|
|
|
199
194
|
## Supported stacks
|
|
200
195
|
|
|
201
|
-
specrails-core is stack-agnostic
|
|
196
|
+
specrails-core is stack-agnostic — the setup wizard reads your actual files and generates accurate conventions, not generic templates.
|
|
202
197
|
|
|
203
198
|
- **Backend**: Python/FastAPI, Node/Express, Go/Gin, Rust/Actix, Java/Spring, Ruby/Rails, .NET
|
|
204
199
|
- **Frontend**: React, Vue, Angular, Svelte, Next.js, Nuxt
|
|
@@ -206,39 +201,37 @@ specrails-core is stack-agnostic. The `/setup` wizard detects and adapts to what
|
|
|
206
201
|
- **CI/CD**: GitHub Actions, GitLab CI, Jenkins, Makefile
|
|
207
202
|
- **Testing**: pytest, vitest, jest, go test, cargo test, rspec
|
|
208
203
|
|
|
209
|
-
|
|
204
|
+
---
|
|
210
205
|
|
|
211
206
|
## Design principles
|
|
212
207
|
|
|
213
|
-
1. **Two-step install
|
|
214
|
-
2. **Self-cleaning
|
|
215
|
-
3. **Context-first
|
|
216
|
-
4. **Persona-driven
|
|
217
|
-
5. **Institutional memory
|
|
218
|
-
6. **Parallel-safe
|
|
208
|
+
1. **Two-step install** — Shell handles prerequisites, Claude handles intelligence. No API keys beyond Claude Code auth.
|
|
209
|
+
2. **Self-cleaning** — All scaffolding removed after setup. Only final, project-specific files remain.
|
|
210
|
+
3. **Context-first** — Every generated file uses your real paths, patterns, and CI commands.
|
|
211
|
+
4. **Persona-driven** — Product decisions grounded in researched user personas, not assumptions.
|
|
212
|
+
5. **Institutional memory** — Agents learn across sessions. Reviewer learnings feed back to future developers.
|
|
213
|
+
6. **Parallel-safe** — Multiple features implemented simultaneously via git worktrees with automatic merge.
|
|
214
|
+
|
|
215
|
+
---
|
|
219
216
|
|
|
220
217
|
## FAQ
|
|
221
218
|
|
|
222
219
|
**Can I customize the agents after installation?**
|
|
223
|
-
Yes.
|
|
220
|
+
Yes. Files in `.claude/` are plain markdown — edit agent personalities, adjust CI commands, add rules, create personas.
|
|
224
221
|
|
|
225
222
|
**Can I re-run setup?**
|
|
226
|
-
|
|
223
|
+
Run `npx specrails-core@latest init --root-dir <path>` again to re-scaffold, then `/setup`.
|
|
227
224
|
|
|
228
225
|
**Does this work without OpenSpec?**
|
|
229
|
-
Partially.
|
|
226
|
+
Partially. `/sr:implement` and sr-architect use OpenSpec for structured design artifacts. Product discovery commands and individual agents work without it.
|
|
230
227
|
|
|
231
228
|
**Does this work without GitHub CLI?**
|
|
232
|
-
Yes
|
|
233
|
-
|
|
234
|
-
**Can I use JIRA instead of GitHub Issues?**
|
|
235
|
-
Yes. During `/setup` Phase 3, choose "JIRA" as your backlog provider. If the JIRA CLI isn't installed, the wizard offers to install it (go-jira via brew, or REST API mode with no CLI needed). You'll also choose whether access is read & write (create tickets, add comments on completion) or read-only (read tickets for context but never modify JIRA).
|
|
229
|
+
Yes. If you use GitHub Issues, `gh` is needed for backlog commands. Otherwise use JIRA, skip backlog entirely, or use `/sr:implement "description"` without a PR step.
|
|
236
230
|
|
|
237
|
-
**
|
|
238
|
-
|
|
231
|
+
**How much does it cost?**
|
|
232
|
+
The sr-product-manager (Opus) is the most expensive agent. All others use Sonnet or Haiku. A full `/sr:implement` cycle for one feature typically costs a few dollars through Claude Code.
|
|
239
233
|
|
|
240
|
-
|
|
241
|
-
Depends on usage. The sr-product-manager agent uses Opus (most capable, most expensive) for deep product thinking. All other agents use Sonnet or Haiku. A full `/sr:implement` cycle for one feature typically costs a few dollars in API usage through Claude Code.
|
|
234
|
+
---
|
|
242
235
|
|
|
243
236
|
## License
|
|
244
237
|
|
package/bin/doctor.sh
ADDED
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
#!/bin/bash
|
|
2
|
+
# specrails doctor — health check for specrails-core installations
|
|
3
|
+
# Usage: specrails doctor
|
|
4
|
+
# Exit 0 if all checks pass, 1 if any check fails.
|
|
5
|
+
|
|
6
|
+
set -uo pipefail
|
|
7
|
+
|
|
8
|
+
# Colors
|
|
9
|
+
GREEN='\033[0;32m'
|
|
10
|
+
RED='\033[0;31m'
|
|
11
|
+
NC='\033[0m'
|
|
12
|
+
BOLD='\033[1m'
|
|
13
|
+
|
|
14
|
+
PASS=0
|
|
15
|
+
FAIL=0
|
|
16
|
+
RESULTS=()
|
|
17
|
+
|
|
18
|
+
pass() { RESULTS+=("$(printf "${GREEN}✅${NC} $1")"); PASS=$((PASS + 1)); }
|
|
19
|
+
fail() { RESULTS+=("$(printf "${RED}❌${NC} $1\n Fix: $2")"); FAIL=$((FAIL + 1)); }
|
|
20
|
+
|
|
21
|
+
echo ""
|
|
22
|
+
echo -e "${BOLD}specrails doctor${NC}"
|
|
23
|
+
echo ""
|
|
24
|
+
|
|
25
|
+
# Determine project root (current working directory)
|
|
26
|
+
PROJECT_ROOT="${PWD}"
|
|
27
|
+
|
|
28
|
+
# ─────────────────────────────────────────────
|
|
29
|
+
# Check 1: Claude Code CLI
|
|
30
|
+
# ─────────────────────────────────────────────
|
|
31
|
+
if CLAUDE_PATH=$(command -v claude 2>/dev/null); then
|
|
32
|
+
pass "Claude Code CLI: found (${CLAUDE_PATH})"
|
|
33
|
+
else
|
|
34
|
+
fail "Claude Code CLI: not found" "Install Claude Code: https://claude.ai/download"
|
|
35
|
+
fi
|
|
36
|
+
|
|
37
|
+
# ─────────────────────────────────────────────
|
|
38
|
+
# Check 2: Claude API key
|
|
39
|
+
# ─────────────────────────────────────────────
|
|
40
|
+
if command -v claude &>/dev/null; then
|
|
41
|
+
if claude config list 2>/dev/null | grep -q "api_key" || [[ -n "${ANTHROPIC_API_KEY:-}" ]]; then
|
|
42
|
+
pass "API key: configured"
|
|
43
|
+
else
|
|
44
|
+
fail "API key: not configured" "Run: claude config set api_key <your-key> | Get a key: https://console.anthropic.com/"
|
|
45
|
+
fi
|
|
46
|
+
fi
|
|
47
|
+
|
|
48
|
+
# ─────────────────────────────────────────────
|
|
49
|
+
# Check 3: Agent files present
|
|
50
|
+
# ─────────────────────────────────────────────
|
|
51
|
+
AGENTS_DIR="${PROJECT_ROOT}/agents"
|
|
52
|
+
if [[ -d "${AGENTS_DIR}" ]]; then
|
|
53
|
+
AGENT_COUNT=$(find "${AGENTS_DIR}" -name "AGENTS.md" 2>/dev/null | wc -l | tr -d ' ')
|
|
54
|
+
if [[ "${AGENT_COUNT}" -ge 1 ]]; then
|
|
55
|
+
AGENT_NAMES=$(find "${AGENTS_DIR}" -name "AGENTS.md" -exec dirname {} \; | xargs -I{} basename {} | tr '\n' ', ' | sed 's/,$//')
|
|
56
|
+
pass "Agent files: ${AGENT_COUNT} agent(s) found (${AGENT_NAMES})"
|
|
57
|
+
else
|
|
58
|
+
fail "Agent files: agents/ exists but no AGENTS.md found" "Run specrails-core init to set up agents"
|
|
59
|
+
fi
|
|
60
|
+
else
|
|
61
|
+
fail "Agent files: agents/ directory not found" "Run specrails-core init to set up agents"
|
|
62
|
+
fi
|
|
63
|
+
|
|
64
|
+
# ─────────────────────────────────────────────
|
|
65
|
+
# Check 4: CLAUDE.md present
|
|
66
|
+
# ─────────────────────────────────────────────
|
|
67
|
+
if [[ -f "${PROJECT_ROOT}/CLAUDE.md" ]]; then
|
|
68
|
+
pass "CLAUDE.md: present"
|
|
69
|
+
else
|
|
70
|
+
fail "CLAUDE.md: missing" "Run /setup inside Claude Code to regenerate"
|
|
71
|
+
fi
|
|
72
|
+
|
|
73
|
+
# ─────────────────────────────────────────────
|
|
74
|
+
# Check 5: Git initialized
|
|
75
|
+
# ─────────────────────────────────────────────
|
|
76
|
+
if [[ -d "${PROJECT_ROOT}/.git" ]]; then
|
|
77
|
+
pass "Git: initialized"
|
|
78
|
+
else
|
|
79
|
+
fail "Git: not a git repository" "Initialize with: git init"
|
|
80
|
+
fi
|
|
81
|
+
|
|
82
|
+
# ─────────────────────────────────────────────
|
|
83
|
+
# Check 6: npm present
|
|
84
|
+
# ─────────────────────────────────────────────
|
|
85
|
+
if NPM_VERSION=$(npm --version 2>/dev/null); then
|
|
86
|
+
pass "npm: found (v${NPM_VERSION})"
|
|
87
|
+
else
|
|
88
|
+
fail "npm: not found" "Install npm: https://docs.npmjs.com/downloading-and-installing-node-js-and-npm"
|
|
89
|
+
fi
|
|
90
|
+
|
|
91
|
+
# ─────────────────────────────────────────────
|
|
92
|
+
# Output results
|
|
93
|
+
# ─────────────────────────────────────────────
|
|
94
|
+
for line in "${RESULTS[@]}"; do
|
|
95
|
+
echo -e "${line}"
|
|
96
|
+
done
|
|
97
|
+
|
|
98
|
+
echo ""
|
|
99
|
+
|
|
100
|
+
if [[ "${FAIL}" -eq 0 ]]; then
|
|
101
|
+
TOTAL=$((PASS + FAIL))
|
|
102
|
+
echo -e "All ${TOTAL} checks passed. Run ${BOLD}/sr:product-backlog${NC} to get started."
|
|
103
|
+
else
|
|
104
|
+
echo "${FAIL} check(s) failed."
|
|
105
|
+
fi
|
|
106
|
+
|
|
107
|
+
# ─────────────────────────────────────────────
|
|
108
|
+
# Append to ~/.specrails/doctor.log
|
|
109
|
+
# ─────────────────────────────────────────────
|
|
110
|
+
LOG_DIR="${HOME}/.specrails"
|
|
111
|
+
mkdir -p "${LOG_DIR}"
|
|
112
|
+
TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || date -u)
|
|
113
|
+
TOTAL=$((PASS + FAIL))
|
|
114
|
+
echo "${TIMESTAMP} checks=${TOTAL} passed=${PASS} failed=${FAIL}" >> "${LOG_DIR}/doctor.log"
|
|
115
|
+
|
|
116
|
+
echo ""
|
|
117
|
+
|
|
118
|
+
exit $([[ "${FAIL}" -eq 0 ]] && echo 0 || echo 1)
|
package/bin/specrails-core.js
CHANGED
|
@@ -7,6 +7,7 @@ const ROOT = resolve(__dirname, "..");
|
|
|
7
7
|
const COMMANDS = {
|
|
8
8
|
init: "install.sh",
|
|
9
9
|
update: "update.sh",
|
|
10
|
+
doctor: "bin/doctor.sh",
|
|
10
11
|
};
|
|
11
12
|
|
|
12
13
|
const args = process.argv.slice(2);
|
|
@@ -18,6 +19,7 @@ if (!subcommand) {
|
|
|
18
19
|
Usage:
|
|
19
20
|
specrails-core init [--root-dir <path>] Install into a repository
|
|
20
21
|
specrails-core update [--only <component>] Update an existing installation
|
|
22
|
+
specrails-core doctor Run health checks
|
|
21
23
|
|
|
22
24
|
More info: https://github.com/fjpulidop/specrails-core`);
|
|
23
25
|
process.exit(0);
|
|
@@ -27,7 +29,7 @@ const script = COMMANDS[subcommand];
|
|
|
27
29
|
|
|
28
30
|
if (!script) {
|
|
29
31
|
console.error(`Unknown command: ${subcommand}\n`);
|
|
30
|
-
console.error("Available commands: init, update");
|
|
32
|
+
console.error("Available commands: init, update, doctor");
|
|
31
33
|
process.exit(1);
|
|
32
34
|
}
|
|
33
35
|
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
# Doctor: specrails Health Check
|
|
2
|
+
|
|
3
|
+
Run the specrails health check to validate that all prerequisites are correctly configured for this repository.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## What it checks
|
|
8
|
+
|
|
9
|
+
| Check | Pass condition |
|
|
10
|
+
|-------|---------------|
|
|
11
|
+
| Claude Code CLI | `claude` binary found in PATH |
|
|
12
|
+
| Claude API key | `claude config list` shows a key OR `ANTHROPIC_API_KEY` env var set |
|
|
13
|
+
| Agent files | `agents/` directory exists with at least 1 `AGENTS.md` file |
|
|
14
|
+
| CLAUDE.md | `CLAUDE.md` present in the repo root |
|
|
15
|
+
| Git initialized | `.git/` directory present |
|
|
16
|
+
| npm | `npm` binary found in PATH |
|
|
17
|
+
|
|
18
|
+
## How to run
|
|
19
|
+
|
|
20
|
+
This command delegates to the standalone health check script installed at `.specrails/bin/doctor.sh`. Run it directly:
|
|
21
|
+
|
|
22
|
+
```
|
|
23
|
+
Bash tool: bash .specrails/bin/doctor.sh
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
Or via the npm CLI wrapper:
|
|
27
|
+
|
|
28
|
+
```
|
|
29
|
+
npx specrails-core@latest doctor
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
## Output
|
|
33
|
+
|
|
34
|
+
Each check is displayed as ✅ (pass) or ❌ (fail with fix instruction).
|
|
35
|
+
|
|
36
|
+
On all checks passed:
|
|
37
|
+
```
|
|
38
|
+
All 6 checks passed. Run /sr:product-backlog to get started.
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
On failure:
|
|
42
|
+
```
|
|
43
|
+
❌ API key: not configured
|
|
44
|
+
Fix: Run: claude config set api_key <your-key> | Get a key: https://console.anthropic.com/
|
|
45
|
+
|
|
46
|
+
1 check(s) failed.
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
## Exit codes
|
|
50
|
+
|
|
51
|
+
- `0` — all checks passed
|
|
52
|
+
- `1` — one or more checks failed
|
|
53
|
+
|
|
54
|
+
## Log file
|
|
55
|
+
|
|
56
|
+
Each run appends a timestamped summary to `~/.specrails/doctor.log`:
|
|
57
|
+
|
|
58
|
+
```
|
|
59
|
+
2026-03-20T10:00:00Z checks=6 passed=6 failed=0
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
The `~/.specrails/` directory is created automatically if it does not exist.
|