specrails-core 4.11.3 → 5.0.0

package/README.md

@@ -4,21 +4,19 @@
 [![GitHub Stars](https://img.shields.io/github/stars/fjpulidop/specrails-core?style=social)](https://github.com/fjpulidop/specrails-core)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![npm downloads](https://img.shields.io/npm/dw/specrails-core.svg)](https://www.npmjs.com/package/specrails-core)
-[![Claude Code](https://img.shields.io/badge/Built%20for-Claude%20Code-blueviolet)](https://docs.anthropic.com/en/docs/claude-code)
-[![Codex — Coming Soon](https://img.shields.io/badge/OpenAI%20Codex-Coming%20Soon%20(in%20lab)-lightgrey)](https://github.com/openai/codex)
+[![AI providers](https://img.shields.io/badge/providers-Claude%20%7C%20Codex%20%7C%20Gemini%20%7C%20Kimi-6f42c1)](#provider-support)
 
 **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.
+One command turns your repo into a spec-driven pipeline with three specialized AI agents working together through OpenSpec — architect, developer, reviewer — all adapted to your codebase. Need more specialists? Add your own via a profile.
 
 ```bash
-npx specrails-core@latest init   # install into the current repo
-/specrails:enrich                # optional: deep codebase analysis
+npx specrails-core@latest init   # install into the current repo — ready to use immediately
 ```
 
-> **Requirements:** [Claude Code](https://docs.anthropic.com/en/docs/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.
+> **Requirements:** one supported AI CLI, git, and Node 20.19.0+. Cross-platform:
+> macOS, Linux, and Windows. Use `--provider claude|codex|gemini|kimi` to
+> override auto-detection.
 
 ---
 
@@ -31,50 +29,59 @@ Idea  →  Architecture  →  Implementation  →  Review  →  PR
 
 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.
+The three core agents are adapted to your project's stack and conventions at install time, and the per-layer rules carry your codebase's patterns. Extend the trio with your own specialists through a [profile](#agent-profiles).
 
 ---
 
 ## Quick start
 
 ```bash
-# 1. Install into the current repo
+# 1. Install into the current repo — one pass, no follow-up step
 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.
 
-```bash
-# 2. Optional — run enrich later if you picked Quick
-/specrails:enrich
-
-# 3. Start building
+# 2. 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.
+That's it. Installation places the three agents, commands, rules, and OpenSpec skills directly — no wizard, no AI step. The pipeline takes over.
 
 ---
 
+## Provider support
+
+| Provider | Runtime command | Project surface | Workflow syntax |
+|----------|-----------------|-----------------|-----------------|
+| Claude Code | `claude` | `.claude/` | `/specrails:<command>` |
+| Codex CLI | `codex` | `.codex/` | provider-native skills |
+| Gemini CLI | `gemini` | `.gemini/` | `/specrails:<command>` |
+| Kimi Code | managed Node skill runner → external `kimi -p` | `.kimi-code/` | `/skill:specrails-<command>` in the TUI |
+
+Kimi is an external CLI dependency, just like the other providers. SpecRails
+does not bundle a Kimi binary, start `kimi web`, or own a Kimi server. Install
+Kimi Code separately, run `kimi login` once, then select it explicitly or let
+the installer detect it. Parallel Kimi roles are submitted as one bounded
+foreground wave; Core creates/reuses their git worktrees, attributes each
+child stream, and waits for aggregate completion—without a server. See the
+[Kimi setup guide](./docs/user-docs/getting-started-kimi.md).
+
 ## 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 |
+| **Agents** | `.claude/agents/` (Claude) or the provider-native skills tree (`.codex/`, `.gemini/`, `.kimi-code/`) | The three core agents (sr-architect, sr-developer, sr-reviewer) |
+| **Commands** | `.claude/commands/specrails/` | Workflow commands (`/specrails:implement`, `/specrails:why`, ...) |
+| **Kimi workflow skills** | `.kimi-code/skills/specrails-*/SKILL.md` | `/skill:specrails-*` directory-form skills |
+| **Kimi headless runner** | `.kimi-code/specrails/run-skill.mjs` | Materializes Kimi's native skill-activation flow for headless runs |
+| **OpenSpec skills** | `.claude/commands/opsx/` (or the provider-native skills directory) | `/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 |
+| **Profiles** _(optional, yours)_ | `.specrails/profiles/*.json` | Add custom specialists + task routing |
 
 To update, re-run the installer:
 
@@ -82,7 +89,7 @@ To update, re-run the installer:
 npx specrails-core@latest init
 ```
 
-It refreshes the agents/commands while leaving your `.specrails/` data untouched.
+Or run `npx specrails-core@latest update` to refresh in place. Update leaves your `.specrails/` data, profiles, and `custom-*` agents untouched. Upgrading from v4? Update also removes the artefacts v5 no longer ships (the enrich wizard, install tiers, and the non-core agents) and prints exactly what it removed — see [Migrating from v4](#migrating-from-v4).
 
 ---
 
@@ -92,33 +99,26 @@ It refreshes the agents/commands while leaving your `.specrails/` data untouched
 |---|---|---|---|
 | 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 | ❌ | ❌ |
+| Spec-driven (OpenSpec) | ✅ Proposal → design → tasks → specs | ❌ | ❌ |
 | 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).
+specrails is not a chat interface. It's a **development pipeline** that coordinates specialised agents through your existing tools (GitHub Issues, git, CI).
 
 ---
 
 ## The agents
 
+Three agents, tightly integrated through the OpenSpec lifecycle (`/opsx:ff` → `/opsx:apply` → `/opsx:archive`):
+
 | 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 |
+| **sr-developer** | Sonnet | Full-stack implementation (tests and docs included per task) |
+| **sr-reviewer** | Sonnet | Single quality gate: correctness, TDD/spec completeness, security, and performance; runs CI, fixes issues, records learnings |
+
+Need a specialist — a dedicated security reviewer, a data-engineering developer, a docs agent? Author it as a `custom-*` agent and declare it in a [profile](#agent-profiles); the pipeline routes to it. The installer never ships or manages non-core agents, so your custom agents are always yours.
 
 ---
 
@@ -129,7 +129,6 @@ specrails is not a chat interface. It's a **development pipeline** that coordina
 ```bash
 /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.
@@ -163,31 +162,21 @@ To discard without applying:
 rm -rf .claude/.dry-run/add-dark-mode/
 ```
 
-### `/specrails:get-backlog-specs` — View prioritised backlog
+### `/specrails:retry` — Resume a failed pipeline
 
 ```bash
-/specrails:get-backlog-specs                  # show all areas
-/specrails:get-backlog-specs UI, Decks        # filter by area
+/specrails:retry add-dark-mode                # resume from the failed phase
+/specrails:retry add-dark-mode --from reviewer
+/specrails:retry --list                       # show resumable pipeline states
 ```
 
-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
-
-```bash
-/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.
+Picks up a `/specrails:implement` run from where it stopped, reusing the OpenSpec artefacts already produced.
 
 ---
 
 ## 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`.
+Profiles are **the way to extend the core trio**. They 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. Without a profile the pipeline runs the three baseline agents; with one, you add your own `custom-*` agents and routing. 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
 
@@ -204,8 +193,9 @@ Profiles are declarative JSON files that tell `/specrails:implement` which agent
 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)
+2. Provider default: `<cwd>/.specrails/profiles/project-default.json` for
+   Claude, or `<cwd>/.specrails/profiles/kimi-default.json` for Kimi
+3. No profile — the three baseline agents (`sr-architect`, `sr-developer`, `sr-reviewer`)
 
 Tools such as [specrails-desktop](https://github.com/fjpulidop/specrails-desktop) set `$SPECRAILS_PROFILE_PATH` to a job-scoped snapshot so concurrent rails can run independent profiles.
 
@@ -240,6 +230,9 @@ The following paths are **reserved** — `specrails-core update` will never crea
 
 - `.specrails/profiles/**` — profile JSON files (yours and desktop-authored).
 - `.claude/agents/custom-*.md` — your custom agents. Use the `custom-` prefix to opt in to this protection.
+- `.kimi-code/skills/custom-*/**` — your custom Kimi role skills. Pre-release
+  `.kimi-code/skills/rails/custom-*` roles are also reserved while Core safely
+  migrates them into this discoverable direct-child layout.
 
 This contract is what lets you safely hand-author (or let specrails-desktop 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.
 
@@ -251,12 +244,10 @@ specrails-core ships with a built-in ticket system — no GitHub account or exte
 
 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.
+**Local tickets are the default** — no GitHub account or credential setup required.
 
 ```bash
 /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
 ```
 
@@ -266,20 +257,21 @@ Migrating from GitHub Issues or JIRA? See [docs/migration-guide.md](./docs/migra
 
 ---
 
-## VPC persona scoring
+## Migrating from v4
 
-Features are scored against your user personas using the Value Proposition Canvas framework:
+v5 is a breaking release. It removes the `/specrails:enrich` wizard, the quick/full install tiers, and the nine non-core agents (product manager/analyst, layer-specific developers and reviewers, test-writer, doc-sync, merge-resolver). The installer is now mode-less: `init` places the three core agents directly, in one pass.
 
-```
-+-----------------------------+    +-----------------------------+
-|     VALUE PROPOSITION       |    |     CUSTOMER SEGMENT        |
-|  Products & Services    <---+--->|  Customer Jobs              |
-|  Pain Relievers         <---+--->|  Pains                      |
-|  Gain Creators          <---+--->|  Gains                      |
-+-----------------------------+    +-----------------------------+
+To upgrade an existing install:
+
+```bash
+npx specrails-core@latest update
 ```
 
-Each persona scores features 0–5. Features are ranked by score / effort ratio. No gut-feel product decisions.
+Update removes the artefacts v5 no longer ships (installer-owned agents, commands, and enrich staging) and prints the exact list of removed files. It never touches your `.specrails/profiles/**` or `.claude/agents/custom-*.md`.
+
+- **Relied on a removed agent?** Its body is plain Markdown — copy the v4 agent to `.claude/agents/custom-<name>.md` and declare it in a [profile](#agent-profiles). Same behaviour, now user-owned.
+- **Have a v4 profile that lists removed agents?** It keeps working: the pipeline warns and skips any profile agent whose file no longer exists, and continues with the rest. The three baseline agents remain required.
+- **Using specrails-desktop?** Pin it to `specrails-core@^4` until a desktop release adopts the mode-less `init --from-config` flow.
 
 ---
 
@@ -287,12 +279,11 @@ Each persona scores features 0–5. Features are ranked by score / effort ratio.
 
 | 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. |
+| **One supported AI CLI** | Yes | Claude Code, Codex CLI, Gemini CLI, or Kimi Code |
+| **Kimi Code 0.27.0+** | For Kimi projects | Install from the [official Kimi Code guide](https://www.kimi.com/code/docs/en/kimi-code-cli/guides/getting-started), then run `kimi login` |
 | **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). |
+| **Node 20.19.0+** | Yes | Needed for `npx specrails-core@latest init` (the floor required by the pinned OpenSpec 1.4.1 CLI). 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.
 
@@ -300,7 +291,7 @@ 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:
+Stack-agnostic. The installer detects and adapts the agents and rules 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
@@ -313,21 +304,26 @@ Stack-agnostic. The `/specrails:enrich` wizard detects and adapts to whatever yo
 ## 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.
+2. **Mode-less** — One install path. `init` places everything directly; there is no follow-up wizard.
 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.
+4. **Spec-driven** — Every feature flows through OpenSpec (proposal → design → tasks → specs), not ad-hoc prompts.
 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.
+7. **Yours to extend** — The core is three agents; specialists come from profiles + `custom-*` agents the installer never touches.
 
 ---
 
 ## 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.
+Yes. Everything in the selected provider tree and `.specrails/` is yours to
+edit — agent prompts, rules, config. For Kimi, customize `.kimi-code/skills/`,
+`.kimi-code/rules/`, and the managed block in `.kimi-code/AGENTS.md`;
+`custom-*` role skills are preserved. To add a specialist, declare a
+`custom-*` agent in a profile.
 
-**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/`.
+**How do I update an install?**
+Run `npx specrails-core@latest update` (or re-run `init`) to refresh the agents/commands. Both leave your `.specrails/` data, profiles, and `custom-*` agents untouched.
 
 **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.
@@ -336,13 +332,24 @@ Yes. Local tickets are the default and need no external tools. `/specrails:imple
 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](./docs/migration-guide.md).
 
 **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.
+Cost depends on the selected provider, model, and workload. SpecRails does not
+add a model surcharge. Kimi's stream output does not currently report a native
+USD cost, so consumers must display it as unavailable rather than inventing an
+estimate.
 
 **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](./docs/user-docs/getting-started-codex.md) for the preview documentation.
+Yes. Orchestration runs through the selected local CLI. The provider still
+connects to its model API and any MCP/integration endpoints you configure.
+
+**How do I use specrails with Kimi?**
+Install and authenticate Kimi Code, then run
+`npx specrails-core@latest init --provider kimi`. Invoke the generated workflows
+as `/skill:specrails-implement`, `/skill:specrails-enrich`, and so on in Kimi's
+interactive TUI. Headless callers use the managed
+`.kimi-code/specrails/run-skill.mjs` helper: Kimi 0.27 sends a slash command
+passed directly to `kimi -p` as literal text, so the helper first renders the
+same skill prompt as Kimi's native activation path and then starts external
+`kimi -p --output-format stream-json`. No server installation is required.
 
 ---