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
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Installation
|
|
2
2
|
|
|
3
|
-
Install SpecRails into any git repository in two steps:
|
|
3
|
+
Install SpecRails into any git repository in two steps: install, then run `/specrails:setup` inside your AI CLI.
|
|
4
4
|
|
|
5
5
|
SpecRails supports both **Claude Code** and **OpenAI Codex**. The installer detects which CLI you have and configures accordingly. See [Codex vs Claude Code](codex-vs-claude-code.md) for a feature comparison.
|
|
6
6
|
|
|
@@ -8,16 +8,24 @@ SpecRails supports both **Claude Code** and **OpenAI Codex**. The installer dete
|
|
|
8
8
|
|
|
9
9
|
## Requirements
|
|
10
10
|
|
|
11
|
+
### Plugin method (recommended)
|
|
12
|
+
|
|
11
13
|
| Tool | Version | Notes |
|
|
12
14
|
|------|---------|-------|
|
|
13
|
-
| **
|
|
14
|
-
| **Claude Code** | Latest | Stable — [install guide](https://docs.anthropic.com/en/docs/claude-code) |
|
|
15
|
-
| **Codex CLI** | Latest | Beta — `npm i -g @openai/codex` |
|
|
15
|
+
| **Claude Code** | Latest | [install guide](https://docs.anthropic.com/en/docs/claude-code) |
|
|
16
16
|
| **Git** | Any | Your project must be a git repository |
|
|
17
17
|
|
|
18
|
-
|
|
18
|
+
No Node.js required.
|
|
19
19
|
|
|
20
|
-
|
|
20
|
+
### Scaffold method (npx / Codex)
|
|
21
|
+
|
|
22
|
+
| Tool | Version | Notes |
|
|
23
|
+
|------|---------|-------|
|
|
24
|
+
| **Node.js** | 18+ | Required for the installer |
|
|
25
|
+
| **Claude Code** or **Codex CLI** | Latest | See [Codex vs Claude Code](codex-vs-claude-code.md) |
|
|
26
|
+
| **Git** | Any | Your project must be a git repository |
|
|
27
|
+
|
|
28
|
+
Optional but recommended (both methods):
|
|
21
29
|
|
|
22
30
|
| Tool | Why |
|
|
23
31
|
|------|-----|
|
|
@@ -25,16 +33,28 @@ Optional but recommended:
|
|
|
25
33
|
|
|
26
34
|
## Install
|
|
27
35
|
|
|
28
|
-
|
|
36
|
+
### Plugin method (Claude Code)
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
claude plugin install sr
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
No cloning, no npm, nothing else. The plugin is now ready in all your Claude Code sessions.
|
|
43
|
+
|
|
44
|
+
To update later: `claude plugin update sr`
|
|
45
|
+
|
|
46
|
+
### Scaffold method (Claude Code or Codex)
|
|
47
|
+
|
|
48
|
+
Run from inside your project directory:
|
|
29
49
|
|
|
30
50
|
```bash
|
|
31
51
|
cd your-project
|
|
32
52
|
npx specrails-core@latest init --root-dir .
|
|
33
53
|
```
|
|
34
54
|
|
|
35
|
-
The installer copies
|
|
55
|
+
The installer copies templates and commands into `.claude/` (Claude Code) or `.codex/` (Codex). It does not modify your existing code.
|
|
36
56
|
|
|
37
|
-
|
|
57
|
+
#### Flags
|
|
38
58
|
|
|
39
59
|
| Flag | Effect |
|
|
40
60
|
|------|--------|
|
|
@@ -42,27 +62,15 @@ The installer copies agent templates, skills, and configuration files into `.cla
|
|
|
42
62
|
| `--yes` / `-y` | Skip confirmation prompts |
|
|
43
63
|
| `--provider <claude\|codex>` | Force a specific AI CLI (default: auto-detect) |
|
|
44
64
|
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
```bash
|
|
48
|
-
npx specrails-core@latest init --root-dir . --provider codex
|
|
49
|
-
```
|
|
50
|
-
|
|
51
|
-
Alternatively, use the `CLI_PROVIDER` env var (legacy):
|
|
52
|
-
|
|
53
|
-
```bash
|
|
54
|
-
CLI_PROVIDER=codex npx specrails-core@latest init --root-dir .
|
|
55
|
-
```
|
|
56
|
-
|
|
57
|
-
### What gets installed
|
|
65
|
+
#### What gets installed (scaffold method)
|
|
58
66
|
|
|
59
67
|
**Claude Code:**
|
|
60
68
|
|
|
61
69
|
```
|
|
62
70
|
your-project/
|
|
63
71
|
└── .claude/
|
|
64
|
-
├── commands/setup.md
|
|
65
|
-
├── skills/ # Workflow skills (/
|
|
72
|
+
├── commands/specrails/setup.md # The /specrails:setup wizard
|
|
73
|
+
├── skills/ # Workflow skills (/specrails:*, /opsx:*)
|
|
66
74
|
├── agents/ # Agent definitions
|
|
67
75
|
├── rules/ # Per-layer coding conventions
|
|
68
76
|
└── settings.json # Permissions
|
|
@@ -74,7 +82,7 @@ your-project/
|
|
|
74
82
|
your-project/
|
|
75
83
|
├── AGENTS.md # SpecRails agent instructions for Codex
|
|
76
84
|
└── .codex/
|
|
77
|
-
├── skills/ # Workflow skills (/
|
|
85
|
+
├── skills/ # Workflow skills (/specrails:*, /opsx:*)
|
|
78
86
|
├── agents/ # Agent definitions (TOML)
|
|
79
87
|
├── rules/ # Per-layer coding conventions
|
|
80
88
|
└── config.toml # Permissions
|
|
@@ -82,9 +90,9 @@ your-project/
|
|
|
82
90
|
|
|
83
91
|
The installer also writes `.specrails-version` and `.specrails-manifest.json` to track the installed version.
|
|
84
92
|
|
|
85
|
-
## Configure with /setup
|
|
93
|
+
## Configure with /specrails:setup
|
|
86
94
|
|
|
87
|
-
After installation, open your AI CLI in your project and run
|
|
95
|
+
After either installation method, open your AI CLI in your project and run:
|
|
88
96
|
|
|
89
97
|
```bash
|
|
90
98
|
claude # Claude Code
|
|
@@ -93,35 +101,36 @@ codex # Codex
|
|
|
93
101
|
```
|
|
94
102
|
|
|
95
103
|
```
|
|
96
|
-
/setup
|
|
104
|
+
/specrails:setup
|
|
97
105
|
```
|
|
98
106
|
|
|
99
|
-
By default, `/setup` runs the full 5-phase wizard:
|
|
107
|
+
By default, `/specrails:setup` runs the full 5-phase wizard:
|
|
100
108
|
|
|
101
109
|
| Phase | What happens |
|
|
102
110
|
|-------|-------------|
|
|
103
111
|
| **1. Analyze** | Detects your tech stack, architecture layers, and CI commands |
|
|
104
112
|
| **2. Personas** | Researches your domain and generates VPC user profiles |
|
|
105
113
|
| **3. Configure** | Asks about your backlog provider, git workflow, and agent selection |
|
|
106
|
-
| **4. Generate** |
|
|
107
|
-
| **5. Cleanup** | Removes setup
|
|
108
|
-
|
|
109
|
-
**In a hurry?** Run `/setup --lite` instead — three questions, sensible defaults, done in under a minute.
|
|
114
|
+
| **4. Generate** | Generates project data files (`.specrails/` or `.claude/`) with your context |
|
|
115
|
+
| **5. Cleanup** | Removes setup scaffolding, leaving only your tailored workflow |
|
|
110
116
|
|
|
111
|
-
|
|
117
|
+
**In a hurry?** Run `/specrails:setup --lite` instead — three questions, sensible defaults, done in under a minute.
|
|
112
118
|
|
|
113
119
|
## Verify
|
|
114
120
|
|
|
115
121
|
Check that everything installed correctly:
|
|
116
122
|
|
|
117
123
|
```bash
|
|
118
|
-
#
|
|
124
|
+
# Plugin method: check project data was generated
|
|
125
|
+
ls .specrails/
|
|
126
|
+
|
|
127
|
+
# Scaffold method: list generated agents
|
|
119
128
|
ls .claude/agents/
|
|
120
129
|
|
|
121
|
-
#
|
|
130
|
+
# Scaffold method: check for unresolved placeholders (should return nothing)
|
|
122
131
|
grep -r '{{[A-Z_]*}}' .claude/agents/ .claude/commands/ .claude/rules/
|
|
123
132
|
|
|
124
|
-
#
|
|
133
|
+
# Scaffold method: check the installed version
|
|
125
134
|
cat .specrails-version
|
|
126
135
|
```
|
|
127
136
|
|
|
@@ -142,7 +151,7 @@ The installer warns if SpecRails artifacts already exist. You can merge (install
|
|
|
142
151
|
|
|
143
152
|
### Placeholders not resolved
|
|
144
153
|
|
|
145
|
-
If you see `{{PLACEHOLDER}}` in generated files, the `/setup` wizard did not complete. Re-run `/setup` or fill the values manually.
|
|
154
|
+
If you see `{{PLACEHOLDER}}` in generated files (scaffold method), the `/specrails:setup` wizard did not complete. Re-run `/specrails:setup` or fill the values manually.
|
|
146
155
|
|
|
147
156
|
### "No Claude API key configured"
|
|
148
157
|
|
|
@@ -7,7 +7,6 @@ Get SpecRails running in your project in under 10 minutes.
|
|
|
7
7
|
## Before you begin
|
|
8
8
|
|
|
9
9
|
You need:
|
|
10
|
-
- **Node.js 18+** — check with `node --version`
|
|
11
10
|
- **Claude Code** — install from [docs.anthropic.com/en/docs/claude-code](https://docs.anthropic.com/en/docs/claude-code)
|
|
12
11
|
- **A git repository** — your project must have a `.git` directory
|
|
13
12
|
|
|
@@ -16,21 +15,19 @@ Optional:
|
|
|
16
15
|
|
|
17
16
|
## Step 1: Install
|
|
18
17
|
|
|
19
|
-
|
|
18
|
+
### Plugin method (recommended — no Node.js required)
|
|
20
19
|
|
|
21
20
|
```bash
|
|
22
|
-
|
|
21
|
+
claude plugin install sr
|
|
23
22
|
```
|
|
24
23
|
|
|
25
|
-
|
|
24
|
+
### Scaffold method (if you need Node.js / Codex)
|
|
26
25
|
|
|
27
|
-
```
|
|
28
|
-
|
|
29
|
-
✓ Templates installed → .claude/
|
|
30
|
-
✓ Version tracked → .specrails-version
|
|
26
|
+
```bash
|
|
27
|
+
npx specrails-core@latest init --root-dir .
|
|
31
28
|
```
|
|
32
29
|
|
|
33
|
-
|
|
30
|
+
Your existing code is not touched by either method.
|
|
34
31
|
|
|
35
32
|
## Step 2: Run the setup wizard
|
|
36
33
|
|
|
@@ -43,7 +40,7 @@ claude
|
|
|
43
40
|
Then run:
|
|
44
41
|
|
|
45
42
|
```
|
|
46
|
-
/setup
|
|
43
|
+
/specrails:setup
|
|
47
44
|
```
|
|
48
45
|
|
|
49
46
|
The wizard runs the full 5-phase setup (about 5 minutes). It analyzes your codebase and configures SpecRails for your specific project:
|
|
@@ -63,32 +60,29 @@ Phase 3/5 Configuration...
|
|
|
63
60
|
→ Git workflow: trunk-based
|
|
64
61
|
|
|
65
62
|
Phase 4/5 Generating files...
|
|
66
|
-
→
|
|
67
|
-
→
|
|
68
|
-
→
|
|
69
|
-
→ 11 more agents
|
|
63
|
+
→ .specrails/config.yaml
|
|
64
|
+
→ .specrails/personas/ (3 VPC profiles)
|
|
65
|
+
→ .specrails/rules/ (per-layer conventions)
|
|
70
66
|
|
|
71
|
-
Phase 5/5 Cleanup complete.
|
|
67
|
+
Phase 5/5 Cleanup complete.
|
|
72
68
|
|
|
73
|
-
✓ SpecRails is ready. Run /
|
|
69
|
+
✓ SpecRails is ready. Run /specrails:implement to start building.
|
|
74
70
|
```
|
|
75
71
|
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
**In a hurry?** Use `/setup --lite` for a 3-question quick setup (under a minute). You can always run the full wizard later.
|
|
72
|
+
**In a hurry?** Use `/specrails:setup --lite` for a 3-question quick setup (under a minute). You can always run the full wizard later.
|
|
79
73
|
|
|
80
74
|
## Step 3: Implement your first feature
|
|
81
75
|
|
|
82
76
|
Pick something small. Either reference a GitHub Issue or describe it in plain text:
|
|
83
77
|
|
|
84
78
|
```
|
|
85
|
-
/
|
|
79
|
+
/specrails:implement #42
|
|
86
80
|
```
|
|
87
81
|
|
|
88
82
|
or:
|
|
89
83
|
|
|
90
84
|
```
|
|
91
|
-
/
|
|
85
|
+
/specrails:implement "add a health check endpoint to the API"
|
|
92
86
|
```
|
|
93
87
|
|
|
94
88
|
The pipeline runs automatically:
|
|
@@ -128,7 +122,7 @@ One command. The PR is ready for human review.
|
|
|
128
122
|
**Explore the backlog:**
|
|
129
123
|
|
|
130
124
|
```
|
|
131
|
-
/
|
|
125
|
+
/specrails:product-backlog
|
|
132
126
|
```
|
|
133
127
|
|
|
134
128
|
See your tickets ranked by persona fit and effort. The top 3 are safe to implement next. Uses local tickets by default.
|
|
@@ -136,7 +130,7 @@ See your tickets ranked by persona fit and effort. The top 3 are safe to impleme
|
|
|
136
130
|
**Generate new feature ideas:**
|
|
137
131
|
|
|
138
132
|
```
|
|
139
|
-
/
|
|
133
|
+
/specrails:update-product-driven-backlog
|
|
140
134
|
```
|
|
141
135
|
|
|
142
136
|
The Product Manager researches your competitive landscape and creates new tickets (local by default, or GitHub Issues if configured).
|
|
@@ -144,7 +138,7 @@ The Product Manager researches your competitive landscape and creates new ticket
|
|
|
144
138
|
**Run multiple features in parallel:**
|
|
145
139
|
|
|
146
140
|
```
|
|
147
|
-
/
|
|
141
|
+
/specrails:implement #42, #43, #44
|
|
148
142
|
```
|
|
149
143
|
|
|
150
144
|
Each feature gets its own git worktree. Pipelines run concurrently and merge automatically.
|
|
@@ -152,10 +146,10 @@ Each feature gets its own git worktree. Pipelines run concurrently and merge aut
|
|
|
152
146
|
**Ask why a decision was made:**
|
|
153
147
|
|
|
154
148
|
```
|
|
155
|
-
/
|
|
149
|
+
/specrails:why "why did we choose this database schema"
|
|
156
150
|
```
|
|
157
151
|
|
|
158
|
-
Agents record their reasoning as they work. `/
|
|
152
|
+
Agents record their reasoning as they work. `/specrails:why` searches those records in plain language.
|
|
159
153
|
|
|
160
154
|
---
|
|
161
155
|
|
package/docs/workflows.md
CHANGED
|
@@ -2,17 +2,17 @@
|
|
|
2
2
|
|
|
3
3
|
SpecRails commands are Claude Code slash commands that orchestrate the agent pipeline. Here's every command, what it does, and when to use it.
|
|
4
4
|
|
|
5
|
-
## The main workflow: `/
|
|
5
|
+
## The main workflow: `/specrails:implement`
|
|
6
6
|
|
|
7
7
|
This is the command you'll use most. It takes a feature request and drives it through the entire pipeline — from architecture to shipped PR.
|
|
8
8
|
|
|
9
9
|
### Usage
|
|
10
10
|
|
|
11
11
|
```
|
|
12
|
-
/
|
|
13
|
-
/
|
|
14
|
-
/
|
|
15
|
-
/
|
|
12
|
+
/specrails:implement #85 # From a GitHub Issue
|
|
13
|
+
/specrails:implement #85, #71, #63 # Multiple issues (parallel)
|
|
14
|
+
/specrails:implement "add dark mode toggle" # Text description
|
|
15
|
+
/specrails:implement UI, Analytics # By area (explores + selects)
|
|
16
16
|
```
|
|
17
17
|
|
|
18
18
|
### Flags
|
|
@@ -24,7 +24,7 @@ This is the command you'll use most. It takes a feature request and drives it th
|
|
|
24
24
|
|
|
25
25
|
### Pipeline phases
|
|
26
26
|
|
|
27
|
-
When you run `/
|
|
27
|
+
When you run `/specrails:implement #85`, here's what happens:
|
|
28
28
|
|
|
29
29
|
```
|
|
30
30
|
Phase -1 Environment check
|
|
@@ -65,7 +65,7 @@ For multiple features, each gets its own isolated worktree. Agents run concurren
|
|
|
65
65
|
### Example output
|
|
66
66
|
|
|
67
67
|
```
|
|
68
|
-
/
|
|
68
|
+
/specrails:implement #85
|
|
69
69
|
```
|
|
70
70
|
|
|
71
71
|
```
|
|
@@ -103,25 +103,25 @@ PR #42 created: feat: add health check endpoint
|
|
|
103
103
|
|
|
104
104
|
---
|
|
105
105
|
|
|
106
|
-
## `/
|
|
106
|
+
## `/specrails:batch-implement`
|
|
107
107
|
|
|
108
108
|
Orchestrates **multiple independent features** in parallel using git worktrees. Use this when you have several unrelated features to ship at once.
|
|
109
109
|
|
|
110
110
|
```
|
|
111
|
-
/
|
|
111
|
+
/specrails:batch-implement #85, #71, #63
|
|
112
112
|
```
|
|
113
113
|
|
|
114
114
|
Each feature gets its own worktree, its own agent pipeline, and its own PR. Features run concurrently for maximum speed.
|
|
115
115
|
|
|
116
116
|
---
|
|
117
117
|
|
|
118
|
-
## `/
|
|
118
|
+
## `/specrails:product-backlog`
|
|
119
119
|
|
|
120
120
|
View your prioritized product backlog, ranked by VPC fit and effort.
|
|
121
121
|
|
|
122
122
|
```
|
|
123
|
-
/
|
|
124
|
-
/
|
|
123
|
+
/specrails:product-backlog # Full backlog
|
|
124
|
+
/specrails:product-backlog UI, API # Filter by area
|
|
125
125
|
```
|
|
126
126
|
|
|
127
127
|
### What it shows
|
|
@@ -151,13 +151,13 @@ Safe Implementation Order (Wave 1):
|
|
|
151
151
|
|
|
152
152
|
---
|
|
153
153
|
|
|
154
|
-
## `/
|
|
154
|
+
## `/specrails:update-product-driven-backlog`
|
|
155
155
|
|
|
156
156
|
Generate new feature ideas through product discovery. The Product Manager (Opus) researches your competitive landscape and generates ideas evaluated against your personas.
|
|
157
157
|
|
|
158
158
|
```
|
|
159
|
-
/
|
|
160
|
-
/
|
|
159
|
+
/specrails:update-product-driven-backlog # All areas
|
|
160
|
+
/specrails:update-product-driven-backlog UI, API # Focus areas
|
|
161
161
|
```
|
|
162
162
|
|
|
163
163
|
### What it does
|
|
@@ -170,28 +170,28 @@ Generate new feature ideas through product discovery. The Product Manager (Opus)
|
|
|
170
170
|
|
|
171
171
|
---
|
|
172
172
|
|
|
173
|
-
## `/
|
|
173
|
+
## `/specrails:refactor-recommender`
|
|
174
174
|
|
|
175
175
|
Scan for refactoring opportunities ranked by impact/effort ratio.
|
|
176
176
|
|
|
177
177
|
```
|
|
178
|
-
/
|
|
178
|
+
/specrails:refactor-recommender
|
|
179
179
|
```
|
|
180
180
|
|
|
181
181
|
Identifies duplicates, long functions, large files, dead code, outdated patterns, and complex logic. Optionally creates GitHub Issues for tracking.
|
|
182
182
|
|
|
183
183
|
---
|
|
184
184
|
|
|
185
|
-
## `/
|
|
185
|
+
## `/specrails:compat-check`
|
|
186
186
|
|
|
187
187
|
Analyze the backwards compatibility impact of a proposed change before implementation.
|
|
188
188
|
|
|
189
189
|
```
|
|
190
|
-
/
|
|
191
|
-
/
|
|
190
|
+
/specrails:compat-check #85 # Check a specific issue
|
|
191
|
+
/specrails:compat-check #85 --save # Check and save as the new API baseline
|
|
192
192
|
```
|
|
193
193
|
|
|
194
|
-
The Architect's Phase 6 auto-check runs this analysis as part of every `/
|
|
194
|
+
The Architect's Phase 6 auto-check runs this analysis as part of every `/specrails:implement` pipeline. You can also run it standalone to evaluate a change before committing to it.
|
|
195
195
|
|
|
196
196
|
### What it detects
|
|
197
197
|
|
|
@@ -206,17 +206,17 @@ When breaking changes are found, `compat-check` generates a **migration guide**
|
|
|
206
206
|
|
|
207
207
|
---
|
|
208
208
|
|
|
209
|
-
## `/
|
|
209
|
+
## `/specrails:why`
|
|
210
210
|
|
|
211
211
|
Search agent explanation records in plain language.
|
|
212
212
|
|
|
213
213
|
```
|
|
214
|
-
/
|
|
215
|
-
/
|
|
216
|
-
/
|
|
214
|
+
/specrails:why "why did we switch to event sourcing"
|
|
215
|
+
/specrails:why "why is pagination implemented this way"
|
|
216
|
+
/specrails:why "explain the auth middleware design"
|
|
217
217
|
```
|
|
218
218
|
|
|
219
|
-
The Architect, Developer, and Reviewer record decision rationale in `.claude/agent-memory/explanations/` as they work. `/
|
|
219
|
+
The Architect, Developer, and Reviewer record decision rationale in `.claude/agent-memory/explanations/` as they work. `/specrails:why` searches these records semantically and surfaces the relevant context.
|
|
220
220
|
|
|
221
221
|
This is useful for onboarding, code review, and revisiting past decisions without digging through git history.
|
|
222
222
|
|
|
@@ -282,14 +282,14 @@ Open-ended thinking mode. Use for brainstorming, investigating problems, or clar
|
|
|
282
282
|
/opsx:explore
|
|
283
283
|
```
|
|
284
284
|
|
|
285
|
-
### `/
|
|
285
|
+
### `/specrails:opsx-diff` — Spec Change Diff
|
|
286
286
|
|
|
287
287
|
Visualize the before/after diff of an OpenSpec change — what behavioral requirements are being added, modified, or removed.
|
|
288
288
|
|
|
289
289
|
```
|
|
290
|
-
/
|
|
291
|
-
/
|
|
292
|
-
/
|
|
290
|
+
/specrails:opsx-diff <change-name>
|
|
291
|
+
/specrails:opsx-diff my-feature --format json
|
|
292
|
+
/specrails:opsx-diff my-feature --summary-only
|
|
293
293
|
```
|
|
294
294
|
|
|
295
295
|
| Flag | Effect |
|
|
@@ -322,16 +322,16 @@ Or step by step:
|
|
|
322
322
|
|
|
323
323
|
---
|
|
324
324
|
|
|
325
|
-
## `/
|
|
325
|
+
## `/specrails:telemetry`
|
|
326
326
|
|
|
327
327
|
Inspect per-agent execution metrics: token usage, estimated API cost, run count, average duration, and success/failure rate.
|
|
328
328
|
|
|
329
329
|
```
|
|
330
|
-
/
|
|
331
|
-
/
|
|
332
|
-
/
|
|
333
|
-
/
|
|
334
|
-
/
|
|
330
|
+
/specrails:telemetry
|
|
331
|
+
/specrails:telemetry --period today
|
|
332
|
+
/specrails:telemetry --agent sr-developer
|
|
333
|
+
/specrails:telemetry --format json
|
|
334
|
+
/specrails:telemetry --save
|
|
335
335
|
```
|
|
336
336
|
|
|
337
337
|
### Flags
|
|
@@ -347,14 +347,14 @@ Reads Claude CLI JSONL session logs and agent-memory files to produce a cost das
|
|
|
347
347
|
|
|
348
348
|
---
|
|
349
349
|
|
|
350
|
-
## `/
|
|
350
|
+
## `/specrails:merge-resolve`
|
|
351
351
|
|
|
352
352
|
Resolve git conflict markers using AI-powered context analysis.
|
|
353
353
|
|
|
354
354
|
```
|
|
355
|
-
/
|
|
356
|
-
/
|
|
357
|
-
/
|
|
355
|
+
/specrails:merge-resolve
|
|
356
|
+
/specrails:merge-resolve --files src/api/routes.ts src/db/schema.ts
|
|
357
|
+
/specrails:merge-resolve --context openspec/changes/
|
|
358
358
|
```
|
|
359
359
|
|
|
360
360
|
### Flags
|
|
@@ -369,32 +369,32 @@ For each conflict block, the command reads the OpenSpec context bundles from the
|
|
|
369
369
|
|
|
370
370
|
---
|
|
371
371
|
|
|
372
|
-
## `/
|
|
372
|
+
## `/specrails:retry`
|
|
373
373
|
|
|
374
|
-
Resume a failed `/
|
|
374
|
+
Resume a failed `/specrails:implement` run from the last successful phase — without restarting from scratch.
|
|
375
375
|
|
|
376
376
|
```
|
|
377
|
-
/
|
|
378
|
-
/
|
|
379
|
-
/
|
|
380
|
-
/
|
|
377
|
+
/specrails:retry <feature-name> # Resume from the failed phase
|
|
378
|
+
/specrails:retry --list # List all available pipeline states
|
|
379
|
+
/specrails:retry <feature-name> --from architect # Force resume from a specific phase
|
|
380
|
+
/specrails:retry <feature-name> --dry-run # Resume in preview mode
|
|
381
381
|
```
|
|
382
382
|
|
|
383
|
-
When a pipeline fails mid-run (e.g., the reviewer hits a flaky CI issue), SpecRails saves pipeline state to `.claude/pipeline-state/<feature-name>.json`. `/
|
|
383
|
+
When a pipeline fails mid-run (e.g., the reviewer hits a flaky CI issue), SpecRails saves pipeline state to `.claude/pipeline-state/<feature-name>.json`. `/specrails:retry` reads that state, identifies which phases completed, and re-executes only the remaining phases.
|
|
384
384
|
|
|
385
385
|
Valid `--from` phase values: `architect`, `developer`, `test-writer`, `doc-sync`, `reviewer`, `ship`, `ci`.
|
|
386
386
|
|
|
387
387
|
---
|
|
388
388
|
|
|
389
|
-
## `/
|
|
389
|
+
## `/specrails:vpc-drift`
|
|
390
390
|
|
|
391
391
|
Detect when your VPC personas have drifted from what your product actually delivers.
|
|
392
392
|
|
|
393
393
|
```
|
|
394
|
-
/
|
|
395
|
-
/
|
|
396
|
-
/
|
|
397
|
-
/
|
|
394
|
+
/specrails:vpc-drift # Analyze all personas
|
|
395
|
+
/specrails:vpc-drift --persona "Alex,Sara" # Filter to specific personas
|
|
396
|
+
/specrails:vpc-drift --verbose # Show full attribute lists
|
|
397
|
+
/specrails:vpc-drift --format json # Emit report as JSON
|
|
398
398
|
```
|
|
399
399
|
|
|
400
400
|
Compares persona Jobs/Pains/Gains against the product backlog, implemented features, and agent memory to surface alignment gaps. Produces a per-persona alignment score and concrete recommendations for updating your VPC.
|
|
@@ -403,27 +403,27 @@ Run this when your backlog feels disconnected from your users, or after a major
|
|
|
403
403
|
|
|
404
404
|
---
|
|
405
405
|
|
|
406
|
-
## `/
|
|
406
|
+
## `/specrails:memory-inspect`
|
|
407
407
|
|
|
408
408
|
Inspect agent memory directories to understand what your agents remember and clean up stale data.
|
|
409
409
|
|
|
410
410
|
```
|
|
411
|
-
/
|
|
412
|
-
/
|
|
413
|
-
/
|
|
414
|
-
/
|
|
411
|
+
/specrails:memory-inspect # Inspect all agent memory
|
|
412
|
+
/specrails:memory-inspect sr-developer # Inspect a specific agent
|
|
413
|
+
/specrails:memory-inspect --stale 14 # Flag files older than 14 days
|
|
414
|
+
/specrails:memory-inspect --prune # Delete stale files (after confirmation)
|
|
415
415
|
```
|
|
416
416
|
|
|
417
|
-
Agents write persistent memory to `.claude/agent-memory/sr-*/`. Over time this can accumulate stale or orphaned files. `/
|
|
417
|
+
Agents write persistent memory to `.claude/agent-memory/sr-*/`. Over time this can accumulate stale or orphaned files. `/specrails:memory-inspect` shows per-agent stats (file count, size, last modified), recent entries, and actionable cleanup recommendations.
|
|
418
418
|
|
|
419
419
|
---
|
|
420
420
|
|
|
421
|
-
## `/
|
|
421
|
+
## `/specrails:propose-spec`
|
|
422
422
|
|
|
423
423
|
Explore a feature idea and produce a structured proposal ready for the OpenSpec pipeline.
|
|
424
424
|
|
|
425
425
|
```
|
|
426
|
-
/
|
|
426
|
+
/specrails:propose-spec "add rate limiting to the API"
|
|
427
427
|
```
|
|
428
428
|
|
|
429
429
|
The command explores your codebase to understand existing patterns, then produces a structured proposal with: problem statement, proposed solution, out-of-scope items, acceptance criteria, technical considerations, and a complexity estimate.
|
|
@@ -437,7 +437,7 @@ Use this before creating a GitHub Issue when you want a well-formed spec rather
|
|
|
437
437
|
Any workflow can be run in preview mode to see what would happen without making changes:
|
|
438
438
|
|
|
439
439
|
```
|
|
440
|
-
/
|
|
440
|
+
/specrails:implement --dry-run #85
|
|
441
441
|
```
|
|
442
442
|
|
|
443
443
|
Preview mode runs the full pipeline but skips:
|
|
@@ -448,7 +448,7 @@ Preview mode runs the full pipeline but skips:
|
|
|
448
448
|
The results are cached. Apply them later with:
|
|
449
449
|
|
|
450
450
|
```
|
|
451
|
-
/
|
|
451
|
+
/specrails:implement --apply health-check-endpoint
|
|
452
452
|
```
|
|
453
453
|
|
|
454
454
|
---
|
package/install.sh
CHANGED
|
@@ -276,8 +276,8 @@ if [[ "$CLI_PROVIDER" == "claude" ]]; then
|
|
|
276
276
|
info "Agent Teams commands: skipped (opt-in, use interactive mode to enable)"
|
|
277
277
|
else
|
|
278
278
|
echo -e " ${BOLD}Agent Teams commands are available (experimental):${NC}"
|
|
279
|
-
echo " /
|
|
280
|
-
echo " /
|
|
279
|
+
echo " /specrails:team-review — Multi-perspective code review with AI reviewers"
|
|
280
|
+
echo " /specrails:team-debug — Collaborative debugging with competing hypotheses"
|
|
281
281
|
echo ""
|
|
282
282
|
echo " These require Claude Code Agent Teams (experimental feature)."
|
|
283
283
|
read -p " Install Agent Teams commands? (y/n, default: n): " INSTALL_AGENT_TEAMS || INSTALL_AGENT_TEAMS="n"
|
|
@@ -623,7 +623,7 @@ echo -e "${BOLD}${GREEN}Installation summary:${NC}"
|
|
|
623
623
|
echo ""
|
|
624
624
|
echo " Provider: $CLI_PROVIDER → output to $SPECRAILS_DIR/"
|
|
625
625
|
if [[ "$AGENT_TEAMS" == "true" ]]; then
|
|
626
|
-
echo " Agent Teams: installed (/
|
|
626
|
+
echo " Agent Teams: installed (/specrails:team-review, /specrails:team-debug)"
|
|
627
627
|
echo " Feature flag: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 (required)"
|
|
628
628
|
fi
|
|
629
629
|
echo ""
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "specrails-core",
|
|
3
|
-
"version": "3.
|
|
3
|
+
"version": "3.4.0",
|
|
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"
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: sr-merge-resolver
|
|
3
|
-
description: "Use this agent when the /
|
|
3
|
+
description: "Use this agent when the /specrails:implement pipeline produces conflict markers in Phase 4a (worktree merge), or when the user runs /specrails:merge-resolve directly. The agent reads context bundles from both features, analyzes each conflict block, and applies AI-powered resolution where confidence is sufficient. Falls back to clean marker format for low-confidence conflicts.\n\nExamples:\n\n- Example 1:\n user: (orchestrator) Phase 4a found 3 conflicted files. Resolve them.\n assistant: \"Launching sr-merge-resolver with conflicted files and context bundles from both features.\"\n\n- Example 2:\n user: /specrails:merge-resolve --files src/config.ts\n assistant: \"Launching the merge resolver agent to analyze and resolve conflicts in src/config.ts.\""
|
|
4
4
|
model: sonnet
|
|
5
5
|
color: yellow
|
|
6
6
|
memory: project
|
|
@@ -24,13 +24,13 @@ Git access level: **{{GIT_ACCESS}}**
|
|
|
24
24
|
Start with a product backlog to discover what to build first:
|
|
25
25
|
|
|
26
26
|
```
|
|
27
|
-
/
|
|
27
|
+
/specrails:product-backlog
|
|
28
28
|
```
|
|
29
29
|
|
|
30
30
|
Then implement features using the full pipeline:
|
|
31
31
|
|
|
32
32
|
```
|
|
33
|
-
/
|
|
33
|
+
/specrails:implement #1 #2 #3
|
|
34
34
|
```
|
|
35
35
|
|
|
36
36
|
---
|