{"id":47608507,"url":"https://github.com/fjpulidop/specrails-core","last_synced_at":"2026-04-26T10:02:03.367Z","repository":{"id":344129469,"uuid":"1180181576","full_name":"fjpulidop/specrails-core","owner":"fjpulidop","description":"Chain-of-agents system to develop software.","archived":false,"fork":false,"pushed_at":"2026-04-11T20:02:24.000Z","size":2093,"stargazers_count":7,"open_issues_count":5,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-11T22:24:50.695Z","etag":null,"topics":["ai-agents","anthropic","claude","claude-code","code-generation","developer-tools","llm","multi-agent","productivity","workflow-automation"],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fjpulidop.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"docs/agents.md","dco":null,"cla":null}},"created_at":"2026-03-12T19:33:29.000Z","updated_at":"2026-04-11T20:02:16.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/fjpulidop/specrails-core","commit_stats":null,"previous_names":["fjpulidop/specrails","fjpulidop/specrails-core"],"tags_count":34,"template":false,"template_full_name":null,"purl":"pkg:github/fjpulidop/specrails-core","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fjpulidop%2Fspecrails-core","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fjpulidop%2Fspecrails-core/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fjpulidop%2Fspecrails-core/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fjpulidop%2Fspecrails-core/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fjpulidop","download_url":"https://codeload.github.com/fjpulidop/specrails-core/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fjpulidop%2Fspecrails-core/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31945987,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-17T17:29:20.459Z","status":"ssl_error","status_checked_at":"2026-04-17T17:28:47.801Z","response_time":62,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","anthropic","claude","claude-code","code-generation","developer-tools","llm","multi-agent","productivity","workflow-automation"],"created_at":"2026-04-01T19:42:50.536Z","updated_at":"2026-04-26T10:02:03.360Z","avatar_url":"https://github.com/fjpulidop.png","language":"Shell","funding_links":["https://ko-fi.com/D1D81Y002C"],"categories":[],"sub_categories":[],"readme":"# specrails-core\n\n[![npm version](https://img.shields.io/npm/v/specrails-core.svg)](https://www.npmjs.com/package/specrails-core)\n[![GitHub Stars](https://img.shields.io/github/stars/fjpulidop/specrails-core?style=social)](https://github.com/fjpulidop/specrails-core)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![npm downloads](https://img.shields.io/npm/dw/specrails-core.svg)](https://www.npmjs.com/package/specrails-core)\n[![Claude Code](https://img.shields.io/badge/Built%20for-Claude%20Code-blueviolet)](https://docs.anthropic.com/en/docs/claude-code)\n[![Codex — Coming Soon](https://img.shields.io/badge/OpenAI%20Codex-Coming%20Soon%20(in%20lab)-lightgrey)](https://github.com/openai/codex)\n\n**Your agentic development team. From idea to production code.**\n\nOne 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.\n\n```bash\nnpx specrails-core@latest init   # install into the current repo\n/specrails:enrich                # optional: deep codebase analysis\n```\n\n\u003e **Requirements:** [Claude Code](https://docs.anthropic.com/en/docs/claude-code), git, Node 20+. Cross-platform: macOS, Linux, Windows.\n\u003e\n\u003e **🧪 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.\n\n---\n\n## How it works\n\n```\nIdea  →  Architecture  →  Implementation  →  Review  →  PR\n         (sr-architect)   (sr-developer)    (sr-reviewer)\n```\n\nRun `/specrails:implement \"add dark mode\"` — the pipeline designs, builds, reviews, and ships a pull request. No hand-holding.\n\nEvery artifact (agents, rules, personas) is generated **specifically for your project** by analysing your actual codebase, tech stack, and CI setup. Not generic templates.\n\n---\n\n## Quick start\n\n```bash\n# 1. Install into the current repo\nnpx specrails-core@latest init\n```\n\nThe TUI asks you to pick a tier:\n\n- **Quick** (default) — agents and commands installed straight to `.claude/`, ready to use immediately. No AI interaction.\n- **Full** — same as Quick plus `/specrails:enrich` (5-phase deep analysis: stack detection, VPC personas, competitive research). ~5 min.\n\n```bash\n# 2. Optional — run enrich later if you picked Quick\n/specrails:enrich\n\n# 3. Start building\n\u003e /specrails:implement \"add user authentication\"\n\u003e /specrails:implement #1, #2          # from local tickets (default)\n\u003e /specrails:implement #42             # from GitHub Issues (if configured)\n```\n\nThat's it. The pipeline takes over.\n\n---\n\n## What gets installed\n\nEverything lands in your repo — nothing auto-updates, nothing phones home. You own it, you commit it.\n\n| Category | Location | Purpose |\n|----------|----------|---------|\n| **Agents** | `.claude/agents/` | 14 specialised AI agents |\n| **Commands** | `.claude/commands/specrails/` | 17 workflow commands (`/specrails:implement`, `/specrails:get-backlog-specs`, `/specrails:why`, …) |\n| **OpenSpec skills** | `.claude/commands/opsx/` | `/opsx:*` commands for spec artefacts |\n| **Config** | `.specrails/config.yaml` | Stack, CI commands, git workflow |\n| **Personas** | `.specrails/personas/*.md` | VPC user profiles, generated from your users |\n| **Rules** | `.specrails/rules/*.md` | Per-layer coding conventions |\n| **Memory** | `.specrails/agent-memory/` | Persistent knowledge — agents learn across sessions |\n| **Pipeline state** | `.specrails/pipeline/` | In-flight feature state for parallel builds |\n\nTo update, re-run the installer:\n\n```bash\nnpx specrails-core@latest init\n```\n\nIt refreshes the agents/commands while leaving your `.specrails/` data untouched.\n\n---\n\n## Why specrails\n\n| | specrails | Plain Claude Code | Cursor / Copilot |\n|---|---|---|---|\n| Structured pipeline | ✅ Architect → Dev → Review → PR | ❌ Manual | ❌ Manual |\n| Adapts to your codebase | ✅ Reads your real stack/CI | ⚠️ Prompts only | ❌ |\n| Product-driven backlog | ✅ VPC persona scoring | ❌ | ❌ |\n| Parallel feature builds | ✅ Git worktrees | ❌ | ❌ |\n| Institutional memory | ✅ Agents learn across sessions | ❌ | ❌ |\n| Open source | ✅ MIT | N/A | ❌ |\n\nspecrails is not a chat interface. It's a **development pipeline** that coordinates multiple specialised agents through your existing tools (GitHub Issues, JIRA, git, CI).\n\n---\n\n## The agents\n\n| Agent | Model | Role |\n|-------|-------|------|\n| **sr-architect** | Sonnet | Designs features: proposal, technical design, task breakdown |\n| **sr-developer** | Sonnet | Full-stack implementation |\n| **sr-backend-developer** | Sonnet | Backend-specialised implementation |\n| **sr-frontend-developer** | Sonnet | Frontend-specialised implementation |\n| **sr-reviewer** | Sonnet | Quality gate: runs CI, fixes issues, records learnings |\n| **sr-backend-reviewer** | Sonnet | Backend code review: API design, DB patterns, performance |\n| **sr-frontend-reviewer** | Sonnet | Frontend code review: UX, accessibility, component design |\n| **sr-test-writer** | Sonnet | Generates unit, integration, and e2e tests |\n| **sr-security-reviewer** | Sonnet | Secrets detection, OWASP checks, dependency vulnerabilities |\n| **sr-doc-sync** | Sonnet | Updates changelogs, READMEs, API docs |\n| **sr-merge-resolver** | Sonnet | AI-powered merge conflict resolution for multi-feature pipelines |\n| **sr-performance-reviewer** | Sonnet | Performance regression detection after implementation |\n| **sr-product-manager** | Opus | Product discovery: competitive analysis, VPC evaluation |\n| **sr-product-analyst** | Haiku | Read-only backlog analysis and prioritisation |\n\n---\n\n## Commands\n\n### `/specrails:implement` — Build features\n\n```bash\n/specrails:implement \"add dark mode\"        # from a description\n/specrails:implement #85, #71               # from tickets\n/specrails:implement UI, Analytics          # explore areas, pick the best ideas\n```\n\nArchitect designs → developer builds → reviewer validates → PR created. Multiple features run in parallel with git worktrees.\n\n#### Dry-run / preview mode\n\nNot ready to commit? Run the full pipeline without touching git or GitHub:\n\n```bash\n/specrails:implement \"add dark mode\" --dry-run\n/specrails:implement #85 --preview            # --preview is an alias for --dry-run\n```\n\nAll agents run normally. Generated files land in `.claude/.dry-run/\u003cfeature-name\u003e/` instead of your working tree. No branches, commits, PRs, or issue updates are created.\n\nWhen you're happy with the preview, apply the cached output:\n\n```bash\n/specrails:implement --apply add-dark-mode    # copies files to real paths, then ships\n```\n\nTo discard without applying:\n\n```bash\nrm -rf .claude/.dry-run/add-dark-mode/\n```\n\n### `/specrails:get-backlog-specs` — View prioritised backlog\n\n```bash\n/specrails:get-backlog-specs                  # show all areas\n/specrails:get-backlog-specs UI, Decks        # filter by area\n```\n\nReads your tickets (local or GitHub Issues), scores by VPC persona match, recommends top 3 for the next sprint.\n\n### `/specrails:auto-propose-backlog-specs` — Discover features\n\n```bash\n/specrails:auto-propose-backlog-specs             # explore all areas\n/specrails:auto-propose-backlog-specs Analytics   # focus on one area\n```\n\nAI product discovery using your personas. Evaluates ideas, creates tickets (local or GitHub Issues) for the best ones.\n\n---\n\n## Agent profiles\n\n\u003e Available in `specrails-core \u003e= 4.1.0`. Optional — without a profile, the pipeline behaves exactly as before.\n\nProfiles 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`.\n\n### File layout\n\n```\n\u003cproject\u003e/.specrails/\n  profiles/\n    default.json          # checked into git, team-shared\n    data-heavy.json       # checked into git, team-shared\n    .user-preferred.json  # gitignored, your personal default\n```\n\n### Resolution order\n\nWhen running the pipeline, the active profile is resolved in this order:\n\n1. `$SPECRAILS_PROFILE_PATH` environment variable (absolute path to a JSON snapshot)\n2. `\u003ccwd\u003e/.specrails/profiles/project-default.json`\n3. No profile — legacy behavior (identical to pre-4.1.0)\n\nTools such as [specrails-hub](https://github.com/fjpulidop/specrails-hub) set `$SPECRAILS_PROFILE_PATH` to a job-scoped snapshot so concurrent rails can run independent profiles.\n\n### Schema\n\nThe v1 profile schema is published at [`schemas/profile.v1.json`](./schemas/profile.v1.json). Example:\n\n```json\n{\n  \"schemaVersion\": 1,\n  \"name\": \"data-heavy\",\n  \"description\": \"Data engineering rail with stricter review\",\n  \"orchestrator\": { \"model\": \"opus\" },\n  \"agents\": [\n    { \"id\": \"sr-architect\",     \"model\": \"opus\",   \"required\": true },\n    { \"id\": \"sr-data-engineer\", \"model\": \"sonnet\" },\n    { \"id\": \"sr-developer\",     \"model\": \"sonnet\", \"required\": true },\n    { \"id\": \"sr-reviewer\",      \"model\": \"opus\",   \"required\": true }\n  ],\n  \"routing\": [\n    { \"tags\": [\"etl\", \"schema\", \"data\"], \"agent\": \"sr-data-engineer\" },\n    { \"default\": true, \"agent\": \"sr-developer\" }\n  ]\n}\n```\n\nBaseline 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.\n\n### Reserved paths\n\nThe following paths are **reserved** — `specrails-core update` will never create, modify, or delete anything inside them:\n\n- `.specrails/profiles/**` — profile JSON files (yours and hub-authored).\n- `.claude/agents/custom-*.md` — your custom agents. Use the `custom-` prefix to opt in to this protection.\n\nThis 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.\n\n---\n\n## Local ticket management\n\nspecrails-core ships with a built-in ticket system — no GitHub account or external tools required.\n\nTickets live in `.specrails/local-tickets.json` alongside your code. They're plain JSON and git-friendly.\n\n**Local tickets are the default.** The `/specrails:enrich` wizard skips GitHub/JIRA credential setup unless you opt in.\n\n```bash\n/specrails:implement #1, #4                # implement by ticket ID\n/specrails:get-backlog-specs               # view prioritised backlog\n/specrails:auto-propose-backlog-specs      # discover and create tickets with AI\n/specrails:propose-spec                    # create a ticket from a spec proposal\n```\n\nSee [docs/local-tickets.md](./docs/local-tickets.md) for the full schema reference, concurrency model, and command integration details.\n\nMigrating from GitHub Issues or JIRA? See [docs/migration-guide.md](./docs/migration-guide.md).\n\n---\n\n## VPC persona scoring\n\nFeatures are scored against your user personas using the Value Proposition Canvas framework:\n\n```\n+-----------------------------+    +-----------------------------+\n|     VALUE PROPOSITION       |    |     CUSTOMER SEGMENT        |\n|  Products \u0026 Services    \u003c---+---\u003e|  Customer Jobs              |\n|  Pain Relievers         \u003c---+---\u003e|  Pains                      |\n|  Gain Creators          \u003c---+---\u003e|  Gains                      |\n+-----------------------------+    +-----------------------------+\n```\n\nEach persona scores features 0–5. Features are ranked by score / effort ratio. No gut-feel product decisions.\n\n---\n\n## Prerequisites\n\n| Tool | Required | Purpose |\n|------|----------|---------|\n| **Claude Code** | Yes | AI agent runtime |\n| **Codex CLI** _(coming soon — in lab)_ | 🧪 Not yet | OpenAI Codex support is being tested in our lab and will be available shortly. |\n| **git** | Yes | Repository detection |\n| **Node 20+** | Yes | Needed for `npx specrails-core@latest init`. Cross-platform: macOS, Linux, Windows (10/11, x64 + ARM64 via emulation). |\n| **GitHub CLI** (`gh`) | Optional | Backlog sync to GitHub Issues, PR creation. Not needed with local tickets. |\n| **JIRA CLI** (`jira`) | Optional | Backlog sync to JIRA. Not needed with local tickets. |\n\nThe installer checks for prerequisites and offers to install missing ones.\n\n---\n\n## Supported stacks\n\nStack-agnostic. The `/specrails:enrich` wizard detects and adapts to whatever you're running:\n\n- **Backend:** Python/FastAPI, Node/Express, Go/Gin, Rust/Actix, Java/Spring, Ruby/Rails, .NET\n- **Frontend:** React, Vue, Angular, Svelte, Next.js, Nuxt\n- **Database:** PostgreSQL, MySQL, SQLite, MongoDB, Redis\n- **CI/CD:** GitHub Actions, GitLab CI, Jenkins, Makefile\n- **Testing:** pytest, vitest, jest, go test, cargo test, rspec\n\n---\n\n## Design principles\n\n1. **Local by default** — Everything lives in your repo. No cloud services, no telemetry, no phone home.\n2. **Self-cleaning** — Installer scaffolding is removed after setup. Only final, project-specific files remain.\n3. **Context-first** — Every generated file uses your real paths, patterns, and CI commands.\n4. **Persona-driven** — Product decisions grounded in researched user personas, not assumptions.\n5. **Institutional memory** — Agents learn across sessions. Reviewer learnings feed back to future developers.\n6. **Parallel-safe** — Multiple features implemented simultaneously via git worktrees with automatic merge.\n\n---\n\n## FAQ\n\n**Can I customise the agents after installation?**\nYes. Everything under `.claude/` and `.specrails/` is yours to edit — agent prompts, personas, rules, config. Commit what makes sense, gitignore what's transient.\n\n**Can I re-run the wizard?**\nRun `/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/`.\n\n**Does this work without GitHub CLI?**\nYes. Local tickets are the default and need no external tools. `/specrails:implement \"description\"` also works without `gh` — it just skips automated PR creation.\n\n**Can I use local tickets and GitHub Issues together?**\nNot 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](./docs/migration-guide.md).\n\n**How much does it cost to run?**\nA 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.\n\n**Does it work with private repos?**\nYes. Everything runs locally through Claude Code. No external services beyond the model API.\n\n**How do I use specrails with Codex?**\n🧪 **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](./docs/user-docs/getting-started-codex.md) for the preview documentation.\n\n---\n\n## Related\n\n- **[specrails-hub](https://github.com/fjpulidop/specrails-hub)** — desktop dashboard that visualises specrails pipelines (macOS, open source).\n- **[specrails.dev](https://specrails.dev)** — landing page and documentation.\n\n---\n\n## Support\n\nIf specrails-core is useful to you, you can donate on [Ko-fi](https://ko-fi.com/D1D81Y002C) ☕ to support ongoing development.\n\n[![Donate on Ko-fi](https://img.shields.io/badge/Donate-Ko--fi-FF5E5B?logo=kofi\u0026logoColor=white\u0026style=flat-square)](https://ko-fi.com/D1D81Y002C)\n\n---\n\n## License\n\nMIT — [fjpulidop](https://github.com/fjpulidop)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffjpulidop%2Fspecrails-core","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffjpulidop%2Fspecrails-core","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffjpulidop%2Fspecrails-core/lists"}