specrails-core
Chain-of-agents system to develop software.
specrails-core
Your AI development team. From idea to production code.
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.
claude plugin install sr # Claude Code plugin (recommended)
/specrails:setup # configure for your project
Requirements: Claude Code or Codex CLI (choose one), git
How it works
Idea → Architecture → Implementation → Review → PR
(sr-architect) (sr-developer) (sr-reviewer)
Run /specrails:implement "add dark mode" — the pipeline designs, builds, reviews, and ships a pull request. No hand-holding required.
Every artifact (agents, rules, personas) is generated specifically for your project by analyzing your actual codebase, tech stack, and CI setup. Not generic templates.
Quick start
Claude Code plugin (recommended)
claude plugin install sr # install the sr plugin
/specrails:setup # run the 5-phase wizard (~5 min)
Updates automatically: claude plugin update sr
Scaffold method (alternative)
npx specrails-core@latest init --root-dir . # copy project files
/specrails:setup # run the wizard
Start building
> /specrails:implement "add user authentication"
> /specrails:implement #1, #2 # from local tickets (default)
> /specrails:implement #42, #43 # from GitHub Issues (if configured)
> /specrails:auto-propose-backlog-specs # discover new features with AI
That's it. The pipeline takes over.
Plugin vs scaffold
| Plugin | Scaffold | |
|---|---|---|
| What it contains | Agents, skills, hooks, references | Nothing — project data only |
| Install | claude plugin install sr |
npx specrails-core@latest init |
| Updates | claude plugin update sr |
Re-run npx |
| Project data | Generated by /specrails:setup into .specrails/ |
Same |
| Use case | Recommended for most projects | When you need full offline control |
The plugin contains the logic (agent prompts, skills, commands). Running /specrails:setup generates the project-specific data files (~8–10 files in .specrails/) — config, personas, memory, pipeline state. These are yours to edit and commit.
What gets installed
Plugin (logic — auto-updated via claude plugin update sr)
| Category | Location | Purpose |
|---|---|---|
| Agents | Plugin | 14 specialized AI agents |
| Commands | Plugin | 17 workflow commands: /specrails:implement, /specrails:get-backlog-specs, /specrails:why, and more |
| Skills | Plugin | OpenSpec skills (/opsx:*) included |
| Hooks & References | Plugin | Agent hooks, reference docs |
Project data (generated by /specrails:setup — lives in your repo)
| Category | Files | Purpose |
|---|---|---|
| Config | .specrails/config.yaml |
Stack, CI commands, git workflow |
| Personas | .specrails/personas/*.md |
VPC user profiles, generated from your users |
| Rules | .specrails/rules/*.md |
Per-layer coding conventions |
| Memory | .specrails/agent-memory/ |
Persistent knowledge — agents learn across sessions |
| Pipeline state | .specrails/pipeline/ |
In-flight feature state for parallel builds |
Why SpecRails
| SpecRails | Plain Claude Code | Cursor / Copilot | |
|---|---|---|---|
| Structured pipeline | ✅ Architect → Dev → Review → PR | ❌ Manual | ❌ Manual |
| Adapts to your codebase | ✅ Reads your actual stack/CI | ⚠️ Prompts only | ❌ |
| Product-driven backlog | ✅ VPC persona scoring | ❌ | ❌ |
| Parallel feature builds | ✅ Git worktrees | ❌ | ❌ |
| Institutional memory | ✅ Agents learn across sessions | ❌ | ❌ |
| Open source | ✅ MIT | N/A | ❌ |
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).
The agents
| Agent | Model | Role |
|---|---|---|
| sr-architect | Sonnet | Designs features: proposal, technical design, task breakdown |
| sr-developer | Sonnet | Full-stack implementation |
| sr-backend-developer | Sonnet | Backend-specialized implementation |
| sr-frontend-developer | Sonnet | Frontend-specialized implementation |
| sr-reviewer | Sonnet | Quality gate: runs CI, fixes issues, records learnings |
| sr-backend-reviewer | Sonnet | Backend code review: API design, DB patterns, performance |
| sr-frontend-reviewer | Sonnet | Frontend code review: UX, accessibility, component design |
| sr-test-writer | Sonnet | Generates unit, integration, and e2e tests |
| sr-security-reviewer | Sonnet | Secrets detection, OWASP checks, dependency vulnerabilities |
| sr-doc-sync | Sonnet | Updates changelogs, READMEs, API docs |
| sr-merge-resolver | Sonnet | AI-powered merge conflict resolution for multi-feature pipelines |
| sr-performance-reviewer | Sonnet | Performance regression detection after implementation |
| sr-product-manager | Opus | Product discovery: competitive analysis, VPC evaluation |
| sr-product-analyst | Haiku | Read-only backlog analysis and prioritization |
Commands
/specrails:implement — Build features
/specrails:implement "add dark mode" # from a description
/specrails:implement #85, #71 # from GitHub Issues
/specrails:implement UI, Analytics # explore areas, pick the best ideas
Architect designs → developer builds → reviewer validates → PR created. Multiple features run in parallel with git worktrees.
Dry-run / preview mode
Not ready to commit? Run the full pipeline without touching git or GitHub:
/specrails:implement "add dark mode" --dry-run
/specrails:implement #85 --preview # --preview is an alias for --dry-run
All agents run normally. Generated files land in .claude/.dry-run/<feature-name>/ instead of your working tree. No branches, commits, PRs, or issue updates are created.
When you're happy with the preview, apply the cached output:
/specrails:implement --apply add-dark-mode # copies files to real paths, then ships
To discard without applying:
rm -rf .claude/.dry-run/add-dark-mode/
/specrails:get-backlog-specs — View prioritized backlog
/specrails:get-backlog-specs # show all areas
/specrails:get-backlog-specs UI, Decks # filter by area
Reads your tickets (local or GitHub Issues), scores by VPC persona match, recommends top 3 for next sprint.
/specrails:auto-propose-backlog-specs — Discover features
/specrails:auto-propose-backlog-specs # explore all areas
/specrails:auto-propose-backlog-specs Analytics # focus on one area
AI product discovery using your personas. Evaluates ideas, creates tickets (local or GitHub Issues) for the best ones.
Local ticket management
specrails-core ships with a built-in ticket system — no GitHub account or external tools required.
Tickets live in .claude/local-tickets.json alongside your code. They're plain JSON and git-friendly.
Local tickets are the default. The /specrails:setup wizard defaults to local tickets and skips GitHub/JIRA credential setup unless you opt in.
/specrails:implement #1, #4 # implement by ticket ID
/specrails:get-backlog-specs # view prioritized backlog
/specrails:auto-propose-backlog-specs # discover and create tickets with AI
/specrails:propose-spec # create a ticket from a spec proposal
See docs/local-tickets.md for the full schema reference, concurrency model, and command integration details.
Migrating from GitHub Issues or JIRA? See docs/migration-guide.md.
VPC persona scoring
Features are scored against your user personas using the VPC framework:
+-----------------------------+ +-----------------------------+
| VALUE PROPOSITION | | CUSTOMER SEGMENT |
| Products & Services <---+--->| Customer Jobs |
| Pain Relievers <---+--->| Pains |
| Gain Creators <---+--->| Gains |
+-----------------------------+ +-----------------------------+
Each persona scores features 0-5. Features are ranked by score/effort ratio. No gut-feel product decisions.
Prerequisites
| Tool | Required | Purpose |
|---|---|---|
| Claude Code | Yes | AI agent runtime — install |
| git | Yes | Repository detection |
| npm / Node 18+ | For scaffold method only | Needed for npx specrails-core@latest init |
GitHub CLI (gh) |
Optional | Backlog sync to GitHub Issues, PR creation. Not needed with local tickets. |
JIRA CLI (jira) |
Optional | Backlog sync to JIRA. Not needed with local tickets. |
The plugin method has no Node.js requirement. The scaffold method checks for prerequisites and offers to install missing ones.
Supported stacks
Stack-agnostic. The /specrails:setup wizard detects and adapts to whatever you're running:
Backend: Python/FastAPI, Node/Express, Go/Gin, Rust/Actix, Java/Spring, Ruby/Rails, .NET
Frontend: React, Vue, Angular, Svelte, Next.js, Nuxt
Database: PostgreSQL, MySQL, SQLite, MongoDB, Redis
CI/CD: GitHub Actions, GitLab CI, Jenkins, Makefile
Testing: pytest, vitest, jest, go test, cargo test, rspec
Design principles
- Two-step install — Shell handles prerequisites, Claude handles intelligence. No API keys beyond Claude Code auth.
- Self-cleaning — All scaffolding removed after setup. Only final, project-specific files remain.
- Context-first — Every generated file uses your real paths, patterns, and CI commands.
- Persona-driven — Product decisions grounded in researched user personas, not assumptions.
- Institutional memory — Agents learn across sessions. Reviewer learnings feed back to future developers.
- Parallel-safe — Multiple features implemented simultaneously via git worktrees with automatic merge.
FAQ
Can I customize the agents after installation?
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.
Can I re-run setup?
Run /specrails:setup again at any time to regenerate or update project data files.
Plugin vs scaffold — which should I use?
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.
Does this work without GitHub CLI?
Yes. Local tickets are the default and need no external tools. /specrails:implement "description" also works without gh — it just skips automated PR creation.
Can I use local tickets and GitHub Issues together?
Not simultaneously for the same project — backlog commands use one active provider at a time. You can migrate from GitHub Issues to local tickets using the migration guide.
How much does it cost to run?
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.
Does it work with private repos?
Yes. Everything runs locally through Claude Code. No external services beyond the Claude API.
How do I use SpecRails with Codex?
Codex uses the scaffold method: npx specrails-core@latest init --root-dir .. See docs/user-docs/getting-started-codex.md.
Also in the SpecRails ecosystem
- Product Hunt — Vote for SpecRails on launch day (link goes live on launch day — star this repo to get notified)
License
MIT — fjpulidop
Yorumlar (0)
Yorum birakmak icin giris yap.
Yorum birakSonuc bulunamadi