specrails-core 3.3.0 → 3.3.1
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 +2 -16
- package/VERSION +1 -1
- package/bin/perf-check.sh +21 -0
- package/bin/specrails-core.js +7 -4
- package/commands/setup.md +5 -12
- package/docs/deployment.md +4 -4
- package/docs/getting-started.md +8 -4
- package/docs/installation.md +6 -30
- package/docs/local-tickets.md +3 -29
- package/docs/migration-guide.md +0 -1
- package/docs/testing/test-matrix-codex.md +0 -1
- package/docs/user-docs/cli-reference.md +0 -12
- package/docs/user-docs/codex-vs-claude-code.md +0 -1
- package/docs/user-docs/installation.md +3 -2
- package/docs/user-docs/quick-start.md +1 -1
- package/docs/workflows.md +0 -12
- package/package.json +1 -1
- package/update.sh +0 -1
- package/docs/api-reference.md +0 -266
- package/integration-contract.json +0 -45
- package/templates/local-tickets-schema.json +0 -7
- package/templates/skills/sr-health-check/SKILL.md +0 -531
- package/templates/web-manager/package-lock.json +0 -3740
- package/templates/web-manager/server/queue-manager.test.ts +0 -607
- package/templates/web-manager/server/queue-manager.ts +0 -565
package/README.md
CHANGED
|
@@ -17,18 +17,6 @@ npx specrails-core@latest init --root-dir .
|
|
|
17
17
|
|
|
18
18
|
> **Requirements:** [Claude Code](https://docs.anthropic.com/en/docs/claude-code) or [Codex CLI](https://github.com/openai/codex) (choose one), Node 18+, git
|
|
19
19
|
|
|
20
|
-
<!--
|
|
21
|
-
BOARD: Add demo GIF here — this is the #1 conversion driver on Product Hunt and npm.
|
|
22
|
-
Record a 60-90s screen capture showing:
|
|
23
|
-
1. `npx specrails-core@latest init --root-dir .` running
|
|
24
|
-
2. The `/setup` wizard completing (phases 1-5)
|
|
25
|
-
3. `/sr:implement "add dark mode"` → agents working → PR created
|
|
26
|
-
Recommended tools: Loom or QuickTime to record; Kap (https://getkap.co) to export as GIF.
|
|
27
|
-
Then replace this comment with:
|
|
28
|
-
|
|
29
|
-

|
|
30
|
-
-->
|
|
31
|
-
|
|
32
20
|
---
|
|
33
21
|
|
|
34
22
|
## How it works
|
|
@@ -80,7 +68,7 @@ That's it. The pipeline takes over.
|
|
|
80
68
|
|----------|-------|---------|
|
|
81
69
|
| **Agents** | `.claude/agents/*.md` | 14 specialized AI agents |
|
|
82
70
|
| **Personas** | `.claude/agents/personas/*.md` | VPC user profiles, generated from your users |
|
|
83
|
-
| **Commands** | `.claude/commands/sr/*.md` | 17 workflow commands: `/sr:implement`, `/sr:product-backlog`, `/sr:
|
|
71
|
+
| **Commands** | `.claude/commands/sr/*.md` | 17 workflow commands: `/sr:implement`, `/sr:product-backlog`, `/sr:why`, and more |
|
|
84
72
|
| **Rules** | `.claude/rules/*.md` | Per-layer coding conventions, loaded by file path |
|
|
85
73
|
| **Memory** | `.claude/agent-memory/` | Persistent knowledge — agents learn across sessions |
|
|
86
74
|
| **Config** | `.claude/settings.json`, `CLAUDE.md` | Permissions, architecture reference |
|
|
@@ -182,7 +170,7 @@ AI product discovery using your personas. Evaluates ideas, creates tickets (loca
|
|
|
182
170
|
|
|
183
171
|
specrails-core ships with a built-in ticket system — no GitHub account or external tools required.
|
|
184
172
|
|
|
185
|
-
Tickets live in `.claude/local-tickets.json` alongside your code. They're plain JSON
|
|
173
|
+
Tickets live in `.claude/local-tickets.json` alongside your code. They're plain JSON and git-friendly.
|
|
186
174
|
|
|
187
175
|
**Local tickets are the default.** The `/setup` wizard defaults to local tickets and skips GitHub/JIRA credential setup unless you opt in.
|
|
188
176
|
|
|
@@ -281,8 +269,6 @@ Yes. Everything runs locally through Claude Code. No external services beyond th
|
|
|
281
269
|
|
|
282
270
|
## Also in the SpecRails ecosystem
|
|
283
271
|
|
|
284
|
-
- **[specrails-hub](https://github.com/fjpulidop/specrails-hub)** — GUI for specrails-core. Manage your agents, run commands, and view pipeline results from a web interface.
|
|
285
|
-
- **[specrails.dev](https://specrails.dev)** — Official website and documentation.
|
|
286
272
|
- **Product Hunt** — [Vote for SpecRails on launch day](https://www.producthunt.com) _(link goes live on launch day — star this repo to get notified)_
|
|
287
273
|
|
|
288
274
|
---
|
package/VERSION
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
|
|
1
|
+
3.3.0
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
#!/bin/bash
|
|
2
|
+
# Performance regression check for specrails-core.
|
|
3
|
+
# This is a template/installer repo — no runtime benchmarks apply.
|
|
4
|
+
# Reports NO_PERF_IMPACT so the CI workflow exits cleanly.
|
|
5
|
+
set -euo pipefail
|
|
6
|
+
|
|
7
|
+
FILES="${MODIFIED_FILES_LIST:-}"
|
|
8
|
+
CONTEXT="${2:-}"
|
|
9
|
+
|
|
10
|
+
# Determine if any performance-sensitive files were modified.
|
|
11
|
+
# For specrails-core (a shell installer + markdown template repo), there are
|
|
12
|
+
# no runtime execution paths to benchmark. All changes are to installer scripts
|
|
13
|
+
# or template files that have no measurable latency or throughput impact.
|
|
14
|
+
|
|
15
|
+
echo "specrails-core performance check"
|
|
16
|
+
echo "Modified files: ${FILES:-<none>}"
|
|
17
|
+
echo ""
|
|
18
|
+
echo "This repository contains shell installer scripts and Markdown templates."
|
|
19
|
+
echo "No runtime benchmarks apply — skipping performance regression analysis."
|
|
20
|
+
echo ""
|
|
21
|
+
echo "PERF_STATUS: NO_PERF_IMPACT"
|
package/bin/specrails-core.js
CHANGED
|
@@ -8,6 +8,7 @@ const COMMANDS = {
|
|
|
8
8
|
init: "install.sh",
|
|
9
9
|
update: "update.sh",
|
|
10
10
|
doctor: "bin/doctor.sh",
|
|
11
|
+
"perf-check": "bin/perf-check.sh",
|
|
11
12
|
};
|
|
12
13
|
|
|
13
14
|
const args = process.argv.slice(2);
|
|
@@ -17,9 +18,10 @@ if (!subcommand) {
|
|
|
17
18
|
console.log(`specrails-core — Agent Workflow System for Claude Code
|
|
18
19
|
|
|
19
20
|
Usage:
|
|
20
|
-
specrails-core init
|
|
21
|
-
specrails-core update
|
|
22
|
-
specrails-core doctor
|
|
21
|
+
specrails-core init [--root-dir <path>] Install into a repository
|
|
22
|
+
specrails-core update [--only <component>] Update an existing installation
|
|
23
|
+
specrails-core doctor Run health checks
|
|
24
|
+
specrails-core perf-check [--files <list>] Performance regression check (CI)
|
|
23
25
|
|
|
24
26
|
More info: https://github.com/fjpulidop/specrails-core`);
|
|
25
27
|
process.exit(0);
|
|
@@ -29,7 +31,7 @@ const script = COMMANDS[subcommand];
|
|
|
29
31
|
|
|
30
32
|
if (!script) {
|
|
31
33
|
console.error(`Unknown command: ${subcommand}\n`);
|
|
32
|
-
console.error("Available commands: init, update, doctor");
|
|
34
|
+
console.error("Available commands: init, update, doctor, perf-check");
|
|
33
35
|
process.exit(1);
|
|
34
36
|
}
|
|
35
37
|
|
|
@@ -40,6 +42,7 @@ const ALLOWED_FLAGS = {
|
|
|
40
42
|
init: ["--root-dir", "--yes", "-y"],
|
|
41
43
|
update: ["--only"],
|
|
42
44
|
doctor: [],
|
|
45
|
+
"perf-check": ["--files", "--context"],
|
|
43
46
|
};
|
|
44
47
|
|
|
45
48
|
const subargs = args.slice(1);
|
package/commands/setup.md
CHANGED
|
@@ -56,7 +56,7 @@ Read the following files to understand the current installation state:
|
|
|
56
56
|
```bash
|
|
57
57
|
ls $SPECRAILS_DIR/setup-templates/commands/sr/
|
|
58
58
|
```
|
|
59
|
-
Command template files include `implement.md`, `batch-implement.md`, `
|
|
59
|
+
Command template files include `implement.md`, `batch-implement.md`, `compat-check.md`, `refactor-recommender.md`, `why.md`, `product-backlog.md`, `update-product-driven-backlog.md`.
|
|
60
60
|
If this directory does not exist, skip command template checking for this update.
|
|
61
61
|
|
|
62
62
|
6. Read `$SPECRAILS_DIR/backlog-config.json` if it exists — contains stored provider configuration needed for command placeholder substitution.
|
|
@@ -130,7 +130,6 @@ Display the combined analysis to the user:
|
|
|
130
130
|
- refactor-recommender.md
|
|
131
131
|
|
|
132
132
|
### Commands — Unchanged (keeping current)
|
|
133
|
-
- health-check.md
|
|
134
133
|
- compat-check.md
|
|
135
134
|
- why.md
|
|
136
135
|
```
|
|
@@ -419,7 +418,6 @@ Core commands (always install if missing):
|
|
|
419
418
|
- `implement.md`
|
|
420
419
|
- `batch-implement.md`
|
|
421
420
|
- `propose-spec.md`
|
|
422
|
-
- `health-check.md`
|
|
423
421
|
- `compat-check.md`
|
|
424
422
|
- `why.md`
|
|
425
423
|
- `product-backlog.md`
|
|
@@ -463,7 +461,7 @@ Remove `commands/setup.md` from `.claude/commands/` if it was copied there by th
|
|
|
463
461
|
After generating all files, display the setup complete message.
|
|
464
462
|
|
|
465
463
|
Then, based on `QS_IS_EXISTING_CODEBASE`:
|
|
466
|
-
- **Existing codebase** (`true`): recommend `/sr:
|
|
464
|
+
- **Existing codebase** (`true`): recommend `/sr:refactor-recommender`
|
|
467
465
|
- **New project** (`false`): recommend `/sr:product-backlog`
|
|
468
466
|
|
|
469
467
|
If `QS_IS_RERUN=false`, display:
|
|
@@ -473,7 +471,7 @@ If `QS_IS_RERUN=false`, display:
|
|
|
473
471
|
Try your first command:
|
|
474
472
|
> /sr:product-backlog
|
|
475
473
|
```
|
|
476
|
-
(Replace `/sr:product-backlog` with `/sr:
|
|
474
|
+
(Replace `/sr:product-backlog` with `/sr:refactor-recommender` for existing codebases.)
|
|
477
475
|
|
|
478
476
|
If `QS_IS_RERUN=true`, display the gap-fill summary and stop:
|
|
479
477
|
```
|
|
@@ -950,7 +948,6 @@ If automatic, also check if `gh` is authenticated (for PR creation). If not, war
|
|
|
950
948
|
| /sr:propose-spec | Interactively propose and refine a feature spec, then create a GitHub issue | GitHub CLI |
|
|
951
949
|
| /sr:product-backlog | View prioritized backlog with VPC scores | sr-product-analyst + Backlog provider |
|
|
952
950
|
| /sr:update-product-driven-backlog | Generate new feature ideas via product discovery | sr-product-manager + Backlog provider |
|
|
953
|
-
| /sr:health-check | Run tests, linting, coverage, complexity, and dependency audit | None |
|
|
954
951
|
| /sr:compat-check | Snapshot API surface and detect breaking changes | None |
|
|
955
952
|
| /sr:refactor-recommender | Scan for refactoring opportunities ranked by impact/effort | None |
|
|
956
953
|
| /sr:why | Search past architectural decisions from agent memory | None |
|
|
@@ -1086,7 +1083,6 @@ For each selected command, read the template and adapt.
|
|
|
1086
1083
|
- `setup-templates/commands/sr/propose-spec.md` → `.claude/commands/sr/propose-spec.md`
|
|
1087
1084
|
- `setup-templates/commands/sr/product-backlog.md` → `.claude/commands/sr/product-backlog.md` (if `BACKLOG_PROVIDER != none`)
|
|
1088
1085
|
- `setup-templates/commands/sr/update-product-driven-backlog.md` → `.claude/commands/sr/update-product-driven-backlog.md` (if `BACKLOG_PROVIDER != none`)
|
|
1089
|
-
- `setup-templates/commands/sr/health-check.md` → `.claude/commands/sr/health-check.md`
|
|
1090
1086
|
- `setup-templates/commands/sr/compat-check.md` → `.claude/commands/sr/compat-check.md`
|
|
1091
1087
|
- `setup-templates/commands/sr/refactor-recommender.md` → `.claude/commands/sr/refactor-recommender.md`
|
|
1092
1088
|
- `setup-templates/commands/sr/why.md` → `.claude/commands/sr/why.md`
|
|
@@ -1097,7 +1093,6 @@ For each selected command, read the template and adapt.
|
|
|
1097
1093
|
- `setup-templates/commands/sr/propose-spec.md` → `.agents/skills/sr-propose-spec/SKILL.md` (wrap with YAML frontmatter if no skill template exists)
|
|
1098
1094
|
- `setup-templates/commands/sr/product-backlog.md` → `.agents/skills/sr-product-backlog/SKILL.md` (if `BACKLOG_PROVIDER != none`; wrap with frontmatter)
|
|
1099
1095
|
- `setup-templates/commands/sr/update-product-driven-backlog.md` → `.agents/skills/sr-update-product-driven-backlog/SKILL.md` (if `BACKLOG_PROVIDER != none`; wrap with frontmatter)
|
|
1100
|
-
- `setup-templates/skills/sr-health-check/SKILL.md` → `.agents/skills/sr-health-check/SKILL.md`
|
|
1101
1096
|
- `setup-templates/skills/sr-compat-check/SKILL.md` → `.agents/skills/sr-compat-check/SKILL.md`
|
|
1102
1097
|
- `setup-templates/skills/sr-refactor-recommender/SKILL.md` → `.agents/skills/sr-refactor-recommender/SKILL.md`
|
|
1103
1098
|
- `setup-templates/skills/sr-why/SKILL.md` → `.agents/skills/sr-why/SKILL.md`
|
|
@@ -1381,7 +1376,6 @@ Display the complete installation summary:
|
|
|
1381
1376
|
| /sr:propose-spec | .claude/commands/sr/propose-spec.md |
|
|
1382
1377
|
| /sr:product-backlog | .claude/commands/sr/product-backlog.md |
|
|
1383
1378
|
| /sr:update-product-driven-backlog | .claude/commands/sr/update-product-driven-backlog.md |
|
|
1384
|
-
| /sr:health-check | .claude/commands/sr/health-check.md |
|
|
1385
1379
|
| /sr:compat-check | .claude/commands/sr/compat-check.md |
|
|
1386
1380
|
| /sr:refactor-recommender | .claude/commands/sr/refactor-recommender.md |
|
|
1387
1381
|
| /sr:why | .claude/commands/sr/why.md |
|
|
@@ -1393,7 +1387,6 @@ Display the complete installation summary:
|
|
|
1393
1387
|
| $sr-propose-spec | .agents/skills/sr-propose-spec/SKILL.md |
|
|
1394
1388
|
| $sr-product-backlog | .agents/skills/sr-product-backlog/SKILL.md |
|
|
1395
1389
|
| $sr-update-product-driven-backlog | .agents/skills/sr-update-product-driven-backlog/SKILL.md |
|
|
1396
|
-
| $sr-health-check | .agents/skills/sr-health-check/SKILL.md |
|
|
1397
1390
|
| $sr-compat-check | .agents/skills/sr-compat-check/SKILL.md |
|
|
1398
1391
|
| $sr-refactor-recommender | .agents/skills/sr-refactor-recommender/SKILL.md |
|
|
1399
1392
|
| $sr-why | .agents/skills/sr-why/SKILL.md |
|
|
@@ -1460,9 +1453,9 @@ Try your first spec:
|
|
|
1460
1453
|
|
|
1461
1454
|
Try your first spec:
|
|
1462
1455
|
[If cli_provider == "claude":]
|
|
1463
|
-
> /sr:
|
|
1456
|
+
> /sr:refactor-recommender
|
|
1464
1457
|
[If cli_provider == "codex":]
|
|
1465
|
-
> $sr-
|
|
1458
|
+
> $sr-refactor-recommender
|
|
1466
1459
|
```
|
|
1467
1460
|
|
|
1468
1461
|
Then stop.
|
package/docs/deployment.md
CHANGED
|
@@ -18,7 +18,7 @@ SpecRails runs locally — no cloud infrastructure required. Choose the setup th
|
|
|
18
18
|
The fastest way to get started. No install required.
|
|
19
19
|
|
|
20
20
|
```bash
|
|
21
|
-
npx specrails-core@latest
|
|
21
|
+
npx specrails-core@latest init --root-dir .
|
|
22
22
|
```
|
|
23
23
|
|
|
24
24
|
This will:
|
|
@@ -35,10 +35,10 @@ This will:
|
|
|
35
35
|
Clone the repository for full control and the ability to customize agents.
|
|
36
36
|
|
|
37
37
|
```bash
|
|
38
|
-
git clone https://github.com/
|
|
38
|
+
git clone https://github.com/fjpulidop/specrails-core
|
|
39
39
|
cd specrails-core
|
|
40
40
|
npm install
|
|
41
|
-
|
|
41
|
+
./install.sh --root-dir <your-project>
|
|
42
42
|
```
|
|
43
43
|
|
|
44
44
|
### Updating
|
|
@@ -90,7 +90,7 @@ docker compose run specrails setup
|
|
|
90
90
|
### Building locally
|
|
91
91
|
|
|
92
92
|
```bash
|
|
93
|
-
git clone https://github.com/
|
|
93
|
+
git clone https://github.com/fjpulidop/specrails-core
|
|
94
94
|
cd specrails-core
|
|
95
95
|
docker build -t specrails:local .
|
|
96
96
|
docker run -it \
|
package/docs/getting-started.md
CHANGED
|
@@ -10,16 +10,18 @@ Think of it as hiring a full engineering team that lives inside your CLI.
|
|
|
10
10
|
|
|
11
11
|
## Prerequisites
|
|
12
12
|
|
|
13
|
-
You
|
|
13
|
+
You need:
|
|
14
14
|
|
|
15
|
+
- **Node.js 18+** — required for the installer (`node --version` to check)
|
|
15
16
|
- **Git** — your project must be a git repository
|
|
16
17
|
- **[Claude Code](https://claude.ai/claude-code)** — Anthropic's CLI tool
|
|
17
18
|
|
|
18
19
|
Optional (recommended):
|
|
19
20
|
|
|
20
|
-
- **npm** — for installing the Pipeline Monitor dashboard
|
|
21
21
|
- **[GitHub CLI](https://cli.github.com/)** (`gh`) — for automatic PR creation and issue tracking
|
|
22
22
|
|
|
23
|
+
> **Using OpenAI Codex instead of Claude Code?** See [Installation](user-docs/installation.md) for Codex-specific setup.
|
|
24
|
+
|
|
23
25
|
## Install
|
|
24
26
|
|
|
25
27
|
Pick your preferred method:
|
|
@@ -33,8 +35,8 @@ npx specrails-core@latest init --root-dir <your-project>
|
|
|
33
35
|
**git clone**
|
|
34
36
|
|
|
35
37
|
```bash
|
|
36
|
-
git clone https://github.com/fjpulidop/specrails.git
|
|
37
|
-
./specrails/install.sh --root-dir <your-project>
|
|
38
|
+
git clone https://github.com/fjpulidop/specrails-core.git
|
|
39
|
+
./specrails-core/install.sh --root-dir <your-project>
|
|
38
40
|
```
|
|
39
41
|
|
|
40
42
|
The installer will:
|
|
@@ -114,4 +116,6 @@ Now that you're running, learn how the system thinks:
|
|
|
114
116
|
|
|
115
117
|
---
|
|
116
118
|
|
|
119
|
+
**Looking for step-by-step guides?** See [Quick Start](user-docs/quick-start.md) for a walkthrough of your first feature, or [Installation](user-docs/installation.md) for detailed install options including Codex support.
|
|
120
|
+
|
|
117
121
|
[← Back to Docs](README.md) · [Core Concepts →](concepts.md)
|
package/docs/installation.md
CHANGED
|
@@ -8,6 +8,7 @@ This guide covers the complete installation process in detail. For the quick ver
|
|
|
8
8
|
|
|
9
9
|
| Tool | Why | Install |
|
|
10
10
|
|------|-----|---------|
|
|
11
|
+
| **Node.js 18+** | Required for the installer | [nodejs.org](https://nodejs.org/) or via [nvm](https://github.com/nvm-sh/nvm) |
|
|
11
12
|
| **Git** | SpecRails operates on git repositories | [git-scm.com](https://git-scm.com/) |
|
|
12
13
|
| **Claude Code** | The AI CLI that runs the agents | `npm install -g @anthropic-ai/claude-code` |
|
|
13
14
|
|
|
@@ -15,9 +16,7 @@ This guide covers the complete installation process in detail. For the quick ver
|
|
|
15
16
|
|
|
16
17
|
| Tool | Why | Install |
|
|
17
18
|
|------|-----|---------|
|
|
18
|
-
| **npm** | Pipeline Monitor dashboard, OpenSpec CLI | Via [nvm](https://github.com/nvm-sh/nvm) |
|
|
19
19
|
| **GitHub CLI** | Auto-create PRs, manage issues | `brew install gh` or [cli.github.com](https://cli.github.com/) |
|
|
20
|
-
| **OpenSpec CLI** | Structured spec workflow | `npm install -g @openspec/cli` |
|
|
21
20
|
|
|
22
21
|
### Optional
|
|
23
22
|
|
|
@@ -42,8 +41,8 @@ No cloning required. Downloads the latest version and runs the installer automat
|
|
|
42
41
|
If you prefer to clone the repo first:
|
|
43
42
|
|
|
44
43
|
```bash
|
|
45
|
-
git clone https://github.com/fjpulidop/specrails.git
|
|
46
|
-
./specrails/install.sh --root-dir <your-project>
|
|
44
|
+
git clone https://github.com/fjpulidop/specrails-core.git
|
|
45
|
+
./specrails-core/install.sh --root-dir <your-project>
|
|
47
46
|
```
|
|
48
47
|
|
|
49
48
|
### From curl
|
|
@@ -51,7 +50,7 @@ git clone https://github.com/fjpulidop/specrails.git
|
|
|
51
50
|
Alternatively, pipe the installer directly:
|
|
52
51
|
|
|
53
52
|
```bash
|
|
54
|
-
curl -sL https://raw.githubusercontent.com/fjpulidop/specrails/main/install.sh | bash
|
|
53
|
+
curl -sL https://raw.githubusercontent.com/fjpulidop/specrails-core/main/install.sh | bash
|
|
55
54
|
```
|
|
56
55
|
|
|
57
56
|
> **Important:** Always run the installer from the **target repository** — the project where you want SpecRails installed. If you run it from inside the SpecRails source repo, the installer will detect this and prompt you for the correct target path.
|
|
@@ -62,8 +61,7 @@ curl -sL https://raw.githubusercontent.com/fjpulidop/specrails/main/install.sh |
|
|
|
62
61
|
2. **Detects existing setup** — warns if `.claude/agents/`, `.claude/commands/`, or `openspec/` already exist
|
|
63
62
|
3. **Installs artifacts:**
|
|
64
63
|
- `.claude/commands/setup.md` — the `/setup` wizard
|
|
65
|
-
- `.claude/setup-templates/` —
|
|
66
|
-
- `.claude/web-manager/` — Pipeline Monitor dashboard
|
|
64
|
+
- `.claude/setup-templates/` — agent and command templates (temporary, removed after `/setup`)
|
|
67
65
|
- `.claude/security-exemptions.yaml` — security scanner config
|
|
68
66
|
- OpenSpec initialization (if CLI available)
|
|
69
67
|
4. **Tracks version** — writes `.specrails-version` and `.specrails-manifest.json`
|
|
@@ -75,7 +73,6 @@ The installer only copies files. It does not:
|
|
|
75
73
|
- Modify your existing code
|
|
76
74
|
- Create commits
|
|
77
75
|
- Push to any remote
|
|
78
|
-
- Install npm dependencies (you do this manually for the web manager)
|
|
79
76
|
|
|
80
77
|
---
|
|
81
78
|
|
|
@@ -203,7 +200,7 @@ The quick path — three questions, sensible defaults, done in under a minute.
|
|
|
203
200
|
| Item | Detail |
|
|
204
201
|
|------|--------|
|
|
205
202
|
| Core agents | sr-architect, sr-developer, sr-reviewer, sr-product-manager |
|
|
206
|
-
| All workflow commands | `/sr:implement`, `/sr:
|
|
203
|
+
| All workflow commands | `/sr:implement`, `/sr:product-backlog`, and 14 more |
|
|
207
204
|
| Backlog storage | Local tickets (`.claude/local-tickets.json`) — no GitHub or JIRA required |
|
|
208
205
|
| CLAUDE.md | Project-level context for agents |
|
|
209
206
|
|
|
@@ -211,27 +208,6 @@ You can run the full wizard later to deepen configuration: personas, stack analy
|
|
|
211
208
|
|
|
212
209
|
---
|
|
213
210
|
|
|
214
|
-
## Pipeline Monitor (optional)
|
|
215
|
-
|
|
216
|
-
SpecRails includes a web dashboard for visualizing pipeline execution.
|
|
217
|
-
|
|
218
|
-
### Install
|
|
219
|
-
|
|
220
|
-
```bash
|
|
221
|
-
cd .claude/web-manager && npm install
|
|
222
|
-
cd client && npm install
|
|
223
|
-
```
|
|
224
|
-
|
|
225
|
-
### Run
|
|
226
|
-
|
|
227
|
-
```bash
|
|
228
|
-
cd .claude/web-manager && npm run dev
|
|
229
|
-
```
|
|
230
|
-
|
|
231
|
-
Opens at `http://localhost:4201` by default.
|
|
232
|
-
|
|
233
|
-
---
|
|
234
|
-
|
|
235
211
|
## Verify installation
|
|
236
212
|
|
|
237
213
|
After setup, verify everything is in place:
|
package/docs/local-tickets.md
CHANGED
|
@@ -12,7 +12,7 @@ Tickets live in `.claude/local-tickets.json` at your project root. Because it's
|
|
|
12
12
|
- **Offline-first** — no network calls, no rate limits
|
|
13
13
|
- **Tool-agnostic** — readable by any script or editor
|
|
14
14
|
|
|
15
|
-
The file is
|
|
15
|
+
The file is read and written by specrails-core during command execution.
|
|
16
16
|
|
|
17
17
|
---
|
|
18
18
|
|
|
@@ -120,7 +120,7 @@ npx specrails-core@latest init --root-dir .
|
|
|
120
120
|
|
|
121
121
|
## Concurrency model
|
|
122
122
|
|
|
123
|
-
|
|
123
|
+
Multiple agents can modify `local-tickets.json` simultaneously. The system uses two complementary mechanisms:
|
|
124
124
|
|
|
125
125
|
### Advisory file lock
|
|
126
126
|
|
|
@@ -141,7 +141,7 @@ The lock is deleted immediately after the write completes. The window is minimal
|
|
|
141
141
|
|
|
142
142
|
### Revision counter
|
|
143
143
|
|
|
144
|
-
Every write increments `revision`. Readers that want to detect external changes compare the `revision` they last saw against the current value.
|
|
144
|
+
Every write increments `revision`. Readers that want to detect external changes compare the `revision` they last saw against the current value.
|
|
145
145
|
|
|
146
146
|
---
|
|
147
147
|
|
|
@@ -187,32 +187,6 @@ The ticket captures the full proposal as its description and is tagged `source:
|
|
|
187
187
|
|
|
188
188
|
---
|
|
189
189
|
|
|
190
|
-
## integration-contract.json
|
|
191
|
-
|
|
192
|
-
The `ticketProvider` section tells specrails-hub where to find and how to use the ticket store:
|
|
193
|
-
|
|
194
|
-
```json
|
|
195
|
-
{
|
|
196
|
-
"ticketProvider": {
|
|
197
|
-
"type": "local",
|
|
198
|
-
"storageFile": "local-tickets.json",
|
|
199
|
-
"lockFile": "local-tickets.json.lock",
|
|
200
|
-
"capabilities": ["crud", "labels", "status", "priorities", "dependencies", "comments"]
|
|
201
|
-
}
|
|
202
|
-
}
|
|
203
|
-
```
|
|
204
|
-
|
|
205
|
-
| Field | Description |
|
|
206
|
-
|-------|-------------|
|
|
207
|
-
| `type` | `"local"` — file-based storage (the only supported type currently) |
|
|
208
|
-
| `storageFile` | Filename relative to the project's specrails dir (`.claude/` or `.codex/`) |
|
|
209
|
-
| `lockFile` | Advisory lock filename, same directory |
|
|
210
|
-
| `capabilities` | Features the hub enables based on what the provider supports |
|
|
211
|
-
|
|
212
|
-
specrails-hub reads this file when it loads a project. If the file is missing or the `ticketProvider` key is absent, hub falls back to safe defaults (`type: "local"`, `storageFile: "local-tickets.json"`).
|
|
213
|
-
|
|
214
|
-
---
|
|
215
|
-
|
|
216
190
|
## Migrating from GitHub Issues or JIRA
|
|
217
191
|
|
|
218
192
|
See the [Migration Guide](./migration-guide.md).
|
package/docs/migration-guide.md
CHANGED
|
@@ -11,7 +11,6 @@ Switching is optional. GitHub Issues and JIRA remain fully supported. Local tick
|
|
|
11
11
|
**Switch to local tickets if:**
|
|
12
12
|
- Your team prefers a simple, zero-dependency setup
|
|
13
13
|
- You want tickets version-controlled alongside your code
|
|
14
|
-
- You use specrails-hub and want the visual ticket panel
|
|
15
14
|
- You don't need GitHub/JIRA for other workflows (project boards, external stakeholders)
|
|
16
15
|
|
|
17
16
|
**Stay on GitHub Issues / JIRA if:**
|
|
@@ -40,7 +40,6 @@ Epic: [SPEA-505](/SPEA/issues/SPEA-505) — Codex Compatibility Approach B
|
|
|
40
40
|
| SKILL.md format `.claude/skills/sr-*/` | ✅ | ✅ |
|
|
41
41
|
| `sr:implement` skill | ✅ | ✅ |
|
|
42
42
|
| `sr:product-backlog` skill | ✅ | ✅ |
|
|
43
|
-
| `sr:health-check` skill | ✅ | ✅ |
|
|
44
43
|
| `sr:compat-check` skill | ✅ | ✅ |
|
|
45
44
|
| `sr:why` skill | ✅ | ✅ |
|
|
46
45
|
| `sr:refactor-recommender` skill | ✅ | ✅ |
|
|
@@ -174,18 +174,6 @@ The Product Manager researches your competitive landscape, generates 2–4 featu
|
|
|
174
174
|
|
|
175
175
|
## Analysis and inspection
|
|
176
176
|
|
|
177
|
-
### `/sr:health-check` ✅ Both
|
|
178
|
-
|
|
179
|
-
Run a comprehensive codebase quality analysis.
|
|
180
|
-
|
|
181
|
-
```
|
|
182
|
-
/sr:health-check
|
|
183
|
-
```
|
|
184
|
-
|
|
185
|
-
Analyzes code quality, test coverage, technical debt, complexity, and dependency health. Compares with previous runs to detect regressions.
|
|
186
|
-
|
|
187
|
-
---
|
|
188
|
-
|
|
189
177
|
### `/sr:refactor-recommender` ✅ Both
|
|
190
178
|
|
|
191
179
|
Scan the codebase for refactoring opportunities, ranked by impact/effort ratio.
|
|
@@ -31,7 +31,6 @@ SpecRails Skills use `SKILL.md` format, which is shared between Codex and Claude
|
|
|
31
31
|
|
|
32
32
|
- `/sr:implement` — full pipeline (design → code → review → PR)
|
|
33
33
|
- `/sr:product-backlog` — VPC-ranked backlog view
|
|
34
|
-
- `/sr:health-check` — codebase quality analysis
|
|
35
34
|
- `/opsx:ff` — OpenSpec fast-forward
|
|
36
35
|
- All other workflow skills
|
|
37
36
|
|
|
@@ -4,6 +4,8 @@ Install SpecRails into any git repository in two steps: run the installer, then
|
|
|
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
|
|
|
7
|
+
> **Looking for the comprehensive reference?** See [Installation & Setup](../installation.md) for full wizard phase details and advanced configuration.
|
|
8
|
+
|
|
7
9
|
## Requirements
|
|
8
10
|
|
|
9
11
|
| Tool | Version | Notes |
|
|
@@ -63,7 +65,6 @@ your-project/
|
|
|
63
65
|
├── skills/ # Workflow skills (/sr:*, /opsx:*)
|
|
64
66
|
├── agents/ # Agent definitions
|
|
65
67
|
├── rules/ # Per-layer coding conventions
|
|
66
|
-
├── web-manager/ # Pipeline Monitor dashboard (optional)
|
|
67
68
|
└── settings.json # Permissions
|
|
68
69
|
```
|
|
69
70
|
|
|
@@ -183,4 +184,4 @@ npx specrails-core@latest init --root-dir . --provider codex
|
|
|
183
184
|
|
|
184
185
|
---
|
|
185
186
|
|
|
186
|
-
[Quick Start →](quick-start.md) · [Getting Started (Codex) →](getting-started-codex.md) · [CLI Reference →](cli-reference.md)
|
|
187
|
+
[← Getting Started](../getting-started.md) · [Quick Start →](quick-start.md) · [Getting Started (Codex) →](getting-started-codex.md) · [CLI Reference →](cli-reference.md)
|
|
@@ -159,4 +159,4 @@ Agents record their reasoning as they work. `/sr:why` searches those records in
|
|
|
159
159
|
|
|
160
160
|
---
|
|
161
161
|
|
|
162
|
-
[← Installation](installation.md) · [CLI Reference →](cli-reference.md) · [FAQ →](faq.md)
|
|
162
|
+
[← Getting Started](../getting-started.md) · [← Installation](installation.md) · [CLI Reference →](cli-reference.md) · [FAQ →](faq.md)
|
package/docs/workflows.md
CHANGED
|
@@ -170,18 +170,6 @@ Generate new feature ideas through product discovery. The Product Manager (Opus)
|
|
|
170
170
|
|
|
171
171
|
---
|
|
172
172
|
|
|
173
|
-
## `/sr:health-check`
|
|
174
|
-
|
|
175
|
-
Run a comprehensive codebase quality analysis.
|
|
176
|
-
|
|
177
|
-
```
|
|
178
|
-
/sr:health-check
|
|
179
|
-
```
|
|
180
|
-
|
|
181
|
-
Analyzes code quality, test coverage, technical debt, and dependency health. Compares with previous runs to detect regressions.
|
|
182
|
-
|
|
183
|
-
---
|
|
184
|
-
|
|
185
173
|
## `/sr:refactor-recommender`
|
|
186
174
|
|
|
187
175
|
Scan for refactoring opportunities ranked by impact/effort ratio.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "specrails-core",
|
|
3
|
-
"version": "3.3.
|
|
3
|
+
"version": "3.3.1",
|
|
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"
|