specrails-core

Your agentic development team. From idea to production code.

One command turns your repo into a spec-driven pipeline with a team of specialized AI agents — architect, developers, reviewers, product manager — all adapted to your codebase.

npx specrails-core@latest init   # install into the current repo
/specrails:enrich                # optional: deep codebase analysis

Requirements: Claude Code, git, Node 20+. Cross-platform: macOS, Linux, Windows.

🧪 Codex (OpenAI) support — Coming Soon: We are testing Codex integration in our lab. Installation is disabled for now, but the feature will be available shortly. Follow the repo for updates.

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.

Every artifact (agents, rules, personas) is generated specifically for your project by analysing your actual codebase, tech stack, and CI setup. Not generic templates.

Quick start

# 1. Install into the current repo
npx specrails-core@latest init

The TUI asks you to pick a tier:

• Quick (default) — agents and commands installed straight to .claude/, ready to use immediately. No AI interaction.
• Full — same as Quick plus /specrails:enrich (5-phase deep analysis: stack detection, VPC personas, competitive research). ~5 min.

# 2. Optional — run enrich later if you picked Quick
/specrails:enrich

# 3. Start building
> /specrails:implement "add user authentication"
> /specrails:implement #1, #2          # from local tickets (default)
> /specrails:implement #42             # from GitHub Issues (if configured)

That's it. The pipeline takes over.

What gets installed

Everything lands in your repo — nothing auto-updates, nothing phones home. You own it, you commit it.

| Category | Location | Purpose | |----------|----------|---------| | Agents | .claude/agents/ | 14 specialised AI agents | | Commands | .claude/commands/specrails/ | 17 workflow commands (/specrails:implement, /specrails:get-backlog-specs, /specrails:why, …) | | OpenSpec skills | .claude/commands/opsx/ | /opsx:* commands for spec artefacts | | 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 |

To update, re-run the installer:

npx specrails-core@latest init

It refreshes the agents/commands while leaving your .specrails/ data untouched.

Why specrails

| | specrails | Plain Claude Code | Cursor / Copilot | |---|---|---|---| | Structured pipeline | ✅ Architect → Dev → Review → PR | ❌ Manual | ❌ Manual | | Adapts to your codebase | ✅ Reads your real 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 specialised 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-specialised implementation | | sr-frontend-developer | Sonnet | Frontend-specialised 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 prioritisation |

Commands

/specrails:implement — Build features

/specrails:implement "add dark mode"        # from a description
/specrails:implement #85, #71               # from tickets
/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 prioritised 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 the 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.

Agent profiles

Available in specrails-core >= 4.1.0. Optional — without a profile, the pipeline behaves exactly as before.

Profiles are declarative JSON files that tell /specrails:implement which agents to use, which models to run them with, and how to route tasks to specialists. One project can define many profiles (e.g. default, data-heavy, security-heavy) and run different features with different profiles — useful for concurrent rails in /specrails:batch-implement.

File layout

<project>/.specrails/
  profiles/
    default.json          # checked into git, team-shared
    data-heavy.json       # checked into git, team-shared
    .user-preferred.json  # gitignored, your personal default

Resolution order

When running the pipeline, the active profile is resolved in this order:

1. $SPECRAILS_PROFILE_PATH environment variable (absolute path to a JSON snapshot)
2. <cwd>/.specrails/profiles/project-default.json
3. No profile — legacy behavior (identical to pre-4.1.0)

Tools such as specrails-hub set $SPECRAILS_PROFILE_PATH to a job-scoped snapshot so concurrent rails can run independent profiles.

Schema

The v1 profile schema is published at schemas/profile.v1.json. Example:

{
  "schemaVersion": 1,
  "name": "data-heavy",
  "description": "Data engineering rail with stricter review",
  "orchestrator": { "model": "opus" },
  "agents": [
    { "id": "sr-architect",     "model": "opus",   "required": true },
    { "id": "sr-data-engineer", "model": "sonnet" },
    { "id": "sr-developer",     "model": "sonnet", "required": true },
    { "id": "sr-reviewer",      "model": "opus",   "required": true }
  ],
  "routing": [
    { "tags": ["etl", "schema", "data"], "agent": "sr-data-engineer" },
    { "default": true, "agent": "sr-developer" }
  ]
}

Baseline agents (sr-architect, sr-developer, sr-reviewer) MUST appear in agents[]. The routing array is ordered — first rule whose tags intersects the task's tags wins; the terminal default: true rule catches everything else.

Reserved paths

The following paths are reserved — specrails-core update will never create, modify, or delete anything inside them:

• .specrails/profiles/** — profile JSON files (yours and hub-authored).
• .claude/agents/custom-*.md — your custom agents. Use the custom- prefix to opt in to this protection.

This contract is what lets you safely hand-author (or let specrails-hub author) profiles and custom agents without fear of the next update overwriting your work. Other paths managed by specrails-core (.specrails/install-config.yaml, .specrails/specrails-version, etc.) remain under update's control. Audited by src/installer/__tests__/reserved-paths.test.ts on every CI run.

Local ticket management

specrails-core ships with a built-in ticket system — no GitHub account or external tools required.

Tickets live in .specrails/local-tickets.json alongside your code. They're plain JSON and git-friendly.

Local tickets are the default. The /specrails:enrich wizard skips GitHub/JIRA credential setup unless you opt in.

/specrails:implement #1, #4                # implement by ticket ID
/specrails:get-backlog-specs               # view prioritised 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 Value Proposition Canvas 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 | | Codex CLI (coming soon — in lab) | 🧪 Not yet | OpenAI Codex support is being tested in our lab and will be available shortly. | | git | Yes | Repository detection | | Node 20+ | Yes | Needed for npx specrails-core@latest init. Cross-platform: macOS, Linux, Windows (10/11, x64 + ARM64 via emulation). | | 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 installer checks for prerequisites and offers to install missing ones.

Supported stacks

Stack-agnostic. The /specrails:enrich 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

1. Local by default — Everything lives in your repo. No cloud services, no telemetry, no phone home.
2. Self-cleaning — Installer scaffolding is removed after setup. Only final, project-specific files remain.
3. Context-first — Every generated file uses your real paths, patterns, and CI commands.
4. Persona-driven — Product decisions grounded in researched user personas, not assumptions.
5. Institutional memory — Agents learn across sessions. Reviewer learnings feed back to future developers.
6. Parallel-safe — Multiple features implemented simultaneously via git worktrees with automatic merge.

FAQ

Can I customise the agents after installation? Yes. Everything under .claude/ and .specrails/ is yours to edit — agent prompts, personas, rules, config. Commit what makes sense, gitignore what's transient.

Can I re-run the wizard? Run /specrails:enrich again at any time to regenerate or update project data files. Re-running npx specrails-core@latest init refreshes the agents/commands without touching .specrails/.

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 model API.

How do I use specrails with Codex? 🧪 Coming Soon — in lab. OpenAI Codex support is currently being tested in our lab and will be available shortly. The install path will remain the same (npx specrails-core@latest init --root-dir .) — the installer will detect Codex and adjust the agent configuration automatically. See docs/user-docs/getting-started-codex.md for the preview documentation.

Related

• specrails-hub — desktop dashboard that visualises specrails pipelines (macOS, open source).
• specrails.dev — landing page and documentation.

Support

If specrails-core is useful to you, you can donate on Ko-fi ☕ to support ongoing development.

License

MIT — fjpulidop