specrails-core 1.4.0 → 1.6.0

package/README.md

@@ -1,76 +1,85 @@
 # specrails-core
 
 [![npm version](https://img.shields.io/npm/v/specrails-core.svg)](https://www.npmjs.com/package/specrails-core)
+[![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)
-[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org)
+[![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)
 
-**AI agent workflow system for [Claude Code](https://claude.ai/code).** Installs a complete product-driven development pipeline into any repository — 12 specialized agents, orchestration commands, persona-based product discovery, and per-layer coding conventions — all generated specifically for your codebase.
+**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.
 
 ```bash
-npx specrails-core@latest init --root-dir <your-project>
+npx specrails-core@latest init --root-dir .
 ```
 
----
+> **Requirements:** [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (required), Node 18+, git
 
-## The pipeline
+<!--
+  BOARD: Add demo GIF here — this is the #1 conversion driver on Product Hunt and npm.
+  Record a 60-90s screen capture showing:
+    1. `npx specrails-core@latest init --root-dir .` running
+    2. The `/setup` wizard completing (phases 1-5)
+    3. `/sr:implement "add dark mode"` → agents working → PR created
+  Recommended tools: Loom or QuickTime to record; Kap (https://getkap.co) to export as GIF.
+  Then replace this comment with:
 
-```
-Product Discovery  →  Architecture  →  Implementation  →  Review  →  Ship
-(sr-product-manager)  (sr-architect)   (sr-developer)   (sr-reviewer)  (PR)
-```
+  ![specrails-core demo](./assets/demo.gif)
+-->
 
-One command runs the full cycle:
+---
+
+## How it works
 
 ```
-/sr:implement #85, #71           # implement GitHub Issues
-/sr:implement "add dark mode"    # implement from description
-/sr:implement UI, Analytics      # explore areas, pick the best ideas
+Idea  →  Architecture  →  Implementation  →  Review  →  PR
+         (sr-architect)   (sr-developer)    (sr-reviewer)
 ```
 
-Multiple features run in parallel using git worktrees. Single features run sequentially.
+Run `/sr: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
 
-**Step 1 — Install into your project**
+**1. Install**
 
 ```bash
-npx specrails-core@latest init --root-dir /path/to/your/repo
+npx specrails-core@latest init --root-dir .
 ```
 
-The installer scaffolds temporary setup files into `.claude/` and checks prerequisites (Claude Code, git, npm, GitHub CLI).
-
-**Step 2 — Run the setup wizard inside Claude Code**
+**2. Run setup inside Claude Code**
 
 ```bash
-cd /path/to/your/repo
-claude          # open Claude Code
-> /setup        # run the interactive setup wizard
+claude      # open Claude Code in your project
+> /setup    # run the 5-phase wizard (~5 min)
 ```
 
-Claude runs a 5-phase wizard that reads your actual codebase and generates everything tailored to your stack:
+**3. Start building**
 
-| Phase | What happens |
-|-------|-------------|
-| **1. Codebase Analysis** | Detects your stack, layers, CI commands, and coding conventions |
-| **2. User Personas** | Researches your competitive landscape, generates VPC personas |
-| **3. Configuration** | Choose backlog (GitHub Issues / JIRA / none), git workflow, agents |
-| **4. File Generation** | Writes all agents, commands, rules — fully contextualized |
-| **5. Cleanup** | Self-destructs scaffolding, only final files remain |
+```bash
+> /sr:implement "add user authentication"
+> /sr:implement #42, #43               # from GitHub Issues
+> /sr:update-product-driven-backlog    # discover new features with AI
+```
+
+That's it. The pipeline takes over.
 
 ---
 
 ## What gets installed
 
-| Category | Location | Description |
-|----------|----------|-------------|
+| Category | Files | Purpose |
+|----------|-------|---------|
 | **Agents** | `.claude/agents/*.md` | 12 specialized AI agents |
-| **Personas** | `.claude/agents/personas/*.md` | VPC user profiles from competitive research |
+| **Personas** | `.claude/agents/personas/*.md` | VPC user profiles, generated from your users |
 | **Commands** | `.claude/commands/sr/*.md` | `/sr:implement`, `/sr:product-backlog`, `/sr:update-product-driven-backlog` |
 | **Rules** | `.claude/rules/*.md` | Per-layer coding conventions, loaded by file path |
-| **Memory** | `.claude/agent-memory/` | Persistent agent knowledge across sessions |
-| **Config** | `.claude/settings.json`, `CLAUDE.md` | Permissions, project context, architecture reference |
+| **Memory** | `.claude/agent-memory/` | Persistent knowledge — agents learn across sessions |
+| **Config** | `.claude/settings.json`, `CLAUDE.md` | Permissions, architecture reference |
 
 ---
 
@@ -82,7 +91,6 @@ Claude runs a 5-phase wizard that reads your actual codebase and generates every
 | Adapts to your codebase | ✅ Reads your actual stack/CI | ⚠️ Prompts only | ❌ |
 | Product-driven backlog | ✅ VPC persona scoring | ❌ | ❌ |
 | Parallel feature builds | ✅ Git worktrees | ❌ | ❌ |
-| Dry-run / preview mode | ✅ Preview before committing | ❌ | ❌ |
 | Institutional memory | ✅ Agents learn across sessions | ❌ | ❌ |
 | Open source | ✅ MIT | N/A | ❌ |
 
@@ -94,37 +102,32 @@ SpecRails is not a chat interface. It's a **development pipeline** that coordina
 
 | Agent | Model | Role |
 |-------|-------|------|
-| **sr-architect** | Sonnet | Designs features — proposal, technical design, task breakdown |
-| **sr-developer** | Sonnet | Full-stack implementation from architect artifacts |
+| **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 | Final quality gate — runs CI, fixes issues, records learnings |
-| **sr-backend-reviewer** | Sonnet | API design, database patterns, performance review |
-| **sr-frontend-reviewer** | Sonnet | UX patterns, accessibility, component design review |
+| **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 audit |
-| **sr-doc-sync** | Sonnet | Changelogs, READMEs, API docs after every change |
-| **sr-product-manager** | Opus | Competitive analysis, VPC evaluation, feature ideation |
+| **sr-security-reviewer** | Sonnet | Secrets detection, OWASP checks, dependency vulnerabilities |
+| **sr-doc-sync** | Sonnet | Updates changelogs, READMEs, API docs |
+| **sr-product-manager** | Opus | Product discovery: competitive analysis, VPC evaluation |
 | **sr-product-analyst** | Haiku | Read-only backlog analysis and prioritization |
 
-The `/sr:implement` pipeline routes tasks to the right agent automatically based on layer tags.
-
 ---
 
-## Product discovery commands
+## Commands
 
-### `/sr:product-backlog` — Prioritized backlog
+### `/sr:implement` — Build features
 
-Reads GitHub Issues labeled `product-driven-backlog`, scores them against your VPC personas, and recommends the top 3 for the next sprint.
-
-```
-/sr:product-backlog               # show all areas
-/sr:product-backlog UI, Decks     # filter by area
+```bash
+/sr:implement "add dark mode"        # from a description
+/sr:implement #85, #71               # from GitHub Issues
+/sr:implement UI, Analytics          # explore areas, pick the best ideas
 ```
 
-### `/sr:update-product-driven-backlog` — Discover new features
-
-Analyzes your codebase against each persona's jobs/pains/gains, generates new feature ideas, and creates GitHub Issues for the best ones.
+Architect designs → developer builds → reviewer validates → PR created. Multiple features run in parallel with git worktrees.
 
 #### Dry-run / preview mode
 
@@ -135,7 +138,7 @@ Not ready to commit? Run the full pipeline without touching git or GitHub:
 /sr:implement #85 --preview            # --preview is an alias for --dry-run
 ```
 
-All agents run normally (architect, developer, tests, docs, review). Generated files land in `.claude/.dry-run/<feature-name>/` instead of your working tree. No branches, commits, PRs, or issue updates are created.
+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:
 
@@ -151,27 +154,39 @@ rm -rf .claude/.dry-run/add-dark-mode/
 
 ### `/sr:product-backlog` — View prioritized backlog
 
+```bash
+/sr:product-backlog                  # show all areas
+/sr:product-backlog UI, Decks        # filter by area
 ```
+
+Reads your GitHub Issues, scores by VPC persona match, recommends top 3 for next sprint.
+
+### `/sr:update-product-driven-backlog` — Discover features
+
+```bash
 /sr:update-product-driven-backlog             # explore all areas
 /sr:update-product-driven-backlog Analytics   # focus on one area
 ```
 
+AI product discovery using your personas. Evaluates ideas, creates GitHub Issues for the best ones.
+
 ---
 
-## Value Proposition Canvas scoring
+## VPC persona scoring
 
-Every feature is evaluated against your user personas before implementation. Features score 0–5 per persona based on jobs-to-be-done, pains, and gains — ranked by score / effort ratio. Product decisions stay grounded in real user needs.
+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
@@ -179,27 +194,25 @@ Every feature is evaluated against your user personas before implementation. Fea
 | Tool | Required | Purpose |
 |------|----------|---------|
 | **Claude Code** | Yes | AI agent runtime — [install](https://docs.anthropic.com/en/docs/claude-code) |
-| **Git** | Yes | Repository detection |
-| **npm** | Recommended | Install OpenSpec CLI |
-| **OpenSpec CLI** | Recommended | Spec-driven design workflow |
-| **GitHub CLI** (`gh`) | Optional | Backlog sync and PR creation |
-| **JIRA CLI** | Optional | JIRA as backlog alternative |
-
-The installer checks for each tool and offers to install missing ones automatically.
+| **git** | Yes | Repository detection |
+| **npm / Node 18+** | Recommended | Needed for npx install and OpenSpec CLI |
+| **OpenSpec CLI** | Recommended | Structured design artifacts for `/sr:implement` |
+| **GitHub CLI** (`gh`) | Optional | Backlog sync to GitHub Issues, PR creation |
+| **JIRA CLI** (`jira`) | Optional | Backlog sync to JIRA |
 
-> You only need one backlog provider. If you use neither, `/sr:implement "description"` still works.
+The installer checks for each tool and offers to install missing ones.
 
 ---
 
 ## Supported stacks
 
-specrails-core is stack-agnostic — the setup wizard reads your actual files and generates accurate conventions, not generic templates.
+Stack-agnostic. The `/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
+**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
 
 ---
 
@@ -217,34 +230,33 @@ specrails-core is stack-agnostic — the setup wizard reads your actual files an
 ## FAQ
 
 **Can I customize the agents after installation?**
-Yes. Files in `.claude/` are plain markdown — edit agent personalities, adjust CI commands, add rules, create personas.
-
-**How do I customize an agent's personality?**
-Each agent template (`sr-architect`, `sr-developer`, `sr-reviewer`) includes a `## Personality` section with four configurable settings:
-
-| Setting | Options | What it controls |
-|---|---|---|
-| `tone` | `terse` / `verbose` | How much explanation the agent includes in its output |
-| `risk_tolerance` | `conservative` / `aggressive` | How cautious the agent is when making decisions |
-| `detail_level` | `summary` / `full` | Granularity of output artifacts and reports |
-| `focus_areas` | comma-separated keywords | Areas the agent prioritizes (e.g. `security, performance`) |
-
-After running `/setup`, edit `.claude/agents/sr-architect.md` (or `sr-developer.md` / `sr-reviewer.md`) and change the values inline. Existing setups without a `## Personality` section continue to work unchanged — defaults apply.
+Yes. The generated files in `.claude/` are yours to edit — plain markdown. Edit agent personalities, adjust CI commands, add rules, create personas.
 
 **Can I re-run setup?**
 Run `npx specrails-core@latest init --root-dir <path>` again to re-scaffold, then `/setup`.
 
 **Does this work without OpenSpec?**
-Partially. `/sr:implement` and sr-architect use OpenSpec for structured design artifacts. Product discovery commands and individual agents work without it.
+Partially. Product discovery commands and individual agents work. `/sr:implement` and sr-architect rely on OpenSpec for structured design artifacts.
 
 **Does this work without GitHub CLI?**
-Yes. If you use GitHub Issues, `gh` is needed for backlog commands. Otherwise use JIRA, skip backlog entirely, or use `/sr:implement "description"` without a PR step.
+Yes. Use JIRA instead, or skip backlog commands. `/sr:implement "description"` works without `gh` — it just skips automated PR creation.
+
+**How much does it cost to run?**
+A full `/sr: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.
+
+---
+
+## Also in the SpecRails ecosystem
 
-**How much does it cost?**
-The sr-product-manager (Opus) is the most expensive agent. All others use Sonnet or Haiku. A full `/sr:implement` cycle for one feature typically costs a few dollars through Claude Code.
+- **[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.
+- **[specrails.dev](https://specrails.dev)** — Official website and documentation.
+- **Product Hunt** — [Vote for SpecRails on launch day](https://www.producthunt.com) _(link goes live on launch day — star this repo to get notified)_
 
 ---
 
 ## License
 
-MIT
+MIT — [fjpulidop](https://github.com/fjpulidop)

package/commands/setup.md

@@ -44,12 +44,21 @@ Read the following files to understand the current installation state:
 
 2. Read `.specrails-version` — contains the current version string (e.g., `0.2.0`). If it does not exist, treat version as `0.1.0 (legacy)`.
 
-3. List all template files in `.claude/setup-templates/agents/` — these are the NEW templates from the update:
+3. List all template files in `.claude/setup-templates/agents/` — these are the NEW agent templates from the update:
    ```bash
    ls .claude/setup-templates/agents/
    ```
    Template files are named with `sr-` prefix (e.g., `sr-architect.md`, `sr-developer.md`).
 
+4. List all template files in `.claude/setup-templates/commands/sr/` — these are the NEW command templates from the update:
+   ```bash
+   ls .claude/setup-templates/commands/sr/
+   ```
+   Command template files include `implement.md`, `batch-implement.md`, `health-check.md`, `compat-check.md`, `refactor-recommender.md`, `why.md`, `product-backlog.md`, `update-product-driven-backlog.md`.
+   If this directory does not exist, skip command template checking for this update.
+
+5. Read `.claude/backlog-config.json` if it exists — contains stored provider configuration needed for command placeholder substitution.
+
 ### Phase U2: Quick Codebase Re-Analysis
 
 Perform the same analysis as Phase 1 of the full setup wizard, but silently — do not prompt the user and do not show the findings table. Just execute and store results internally.
@@ -71,39 +80,62 @@ Store all results for use in Phases U4 and U5.
 
 ### Phase U3: Identify What Needs Regeneration
 
-For each agent template, find its entry in the manifest's `artifacts` map (keyed as `templates/agents/sr-<name>.md`). Compute the SHA-256 checksum of the corresponding file in `.claude/setup-templates/agents/`:
+**Agent templates:** For each agent template, find its entry in the manifest's `artifacts` map (keyed as `templates/agents/sr-<name>.md`). Compute the SHA-256 checksum of the corresponding file in `.claude/setup-templates/agents/`:
 
 ```bash
 sha256sum .claude/setup-templates/agents/sr-<name>.md
 ```
 
-Build three lists:
+Build three lists for agents:
 
 1. **Changed agents**: agent name exists in manifest AND the current template checksum differs from the manifest checksum → mark for regeneration
 2. **New agents**: template file exists in `.claude/setup-templates/agents/` but the agent name is NOT in the manifest → mark for evaluation
 3. **Unchanged agents**: agent name exists in manifest AND checksum matches → skip
 
-Display the analysis to the user:
+**Command templates:** If `.claude/setup-templates/commands/sr/` exists, for each command template file, find its entry in the manifest's `artifacts` map (keyed as `templates/commands/sr/<name>.md`). Compute the SHA-256 checksum of the corresponding file in `.claude/setup-templates/commands/sr/`:
 
+```bash
+sha256sum .claude/setup-templates/commands/sr/<name>.md
 ```
-## Agent Update Analysis
 
-### Changed Templates (will be regenerated)
+Build three lists for commands:
+
+1. **Changed commands**: command name exists in manifest AND the current template checksum differs from the manifest checksum → mark for update
+2. **New commands**: template file exists in `.claude/setup-templates/commands/sr/` but the command name is NOT in the manifest → mark for evaluation
+3. **Unchanged commands**: command name exists in manifest AND checksum matches → skip
+
+Display the combined analysis to the user:
+
+```
+## Update Analysis
+
+### Agents — Changed Templates (will be regenerated)
 - sr-architect.md (template modified)
 - sr-developer.md (template modified)
 
-### New Templates Available
+### Agents — New Templates Available
 - sr-frontend-developer.md
 - sr-backend-developer.md
 
-### Unchanged (keeping current)
+### Agents — Unchanged (keeping current)
 - sr-reviewer.md
 - sr-product-manager.md
+
+### Commands — Changed Templates (will be updated)
+- implement.md (template modified)
+
+### Commands — New Templates Available
+- refactor-recommender.md
+
+### Commands — Unchanged (keeping current)
+- health-check.md
+- compat-check.md
+- why.md
 ```
 
-If there are no changed agents and no new agents, display:
+If there are no changed agents, no new agents, no changed commands, and no new commands, display:
 ```
-All agents are already up to date. Nothing to regenerate.
+All agents and commands are already up to date. Nothing to regenerate.
 ```
 Then jump to Phase U7.
 
@@ -133,6 +165,36 @@ After regenerating all changed agents, verify no unresolved placeholders remain:
 grep -r '{{[A-Z_]*}}' .claude/agents/sr-*.md 2>/dev/null || echo "OK: no broken placeholders"
 ```
 
+### Phase U4b: Update Changed Commands
+
+For each command in the "changed commands" list from Phase U3:
+
+1. Read the NEW template from `.claude/setup-templates/commands/sr/<name>.md`
+2. Read stored backlog configuration from `.claude/backlog-config.json` (if it exists) to resolve provider-specific placeholders:
+   - `BACKLOG_PROVIDER` → `provider` field (`github`, `jira`, or `none`)
+   - `BACKLOG_WRITE` → `write_access` field
+   - `JIRA_BASE_URL` → `jira_base_url` field
+   - `JIRA_PROJECT_KEY` → `jira_project_key` field
+3. Substitute all `{{PLACEHOLDER}}` values using the same rules as Phase 4.3 of the full setup:
+   - `{{CI_COMMANDS_BACKEND}}` → backend CI commands detected in Phase U2
+   - `{{CI_COMMANDS_FRONTEND}}` → frontend CI commands detected in Phase U2
+   - `{{DEPENDENCY_CHECK_COMMANDS}}` → stack-specific dependency check commands from Phase U2
+   - `{{TEST_RUNNER_CHECK}}` → test runner commands from Phase U2
+   - `{{BACKLOG_FETCH_CMD}}` → provider-specific fetch command from backlog config
+   - `{{BACKLOG_CREATE_CMD}}` → provider-specific create command from backlog config
+   - `{{BACKLOG_VIEW_CMD}}` → provider-specific view command from backlog config
+   - `{{BACKLOG_PREFLIGHT}}` → provider-specific preflight check from backlog config
+   - Any other `{{PLACEHOLDER}}` values → use Phase U2 analysis data
+4. Write the updated command to `.claude/commands/sr/<name>.md`
+5. Show: `✓ Updated /sr:<name>`
+
+After updating all changed commands, verify no unresolved placeholders remain in the updated files:
+```bash
+grep -l '{{[A-Z_]*}}' .claude/commands/sr/*.md 2>/dev/null || echo "OK: no broken placeholders"
+```
+If any placeholders remain unresolved, warn the user:
+> "⚠ Some placeholders in `<filename>` could not be resolved automatically. Please review the file and fill them in manually."
+
 ### Phase U5: Evaluate New Agents
 
 For each agent in the "new" list:
@@ -150,6 +212,18 @@ For each agent in the "new" list:
 4. If the user declines:
    - Show: `→ Skipped sr-<name>`
 
+For each command in the "new commands" list from Phase U3:
+
+1. Read the template from `.claude/setup-templates/commands/sr/<name>.md` to understand what it does (read the title and description)
+2. Prompt the user:
+   > "New command available: `/sr:<name>` — [one-line description from template]. Install it? [Y/n]"
+3. If the user accepts (or presses Enter):
+   - Apply placeholder substitution using the same rules as Phase U4b (backlog config + codebase analysis)
+   - Write the command to `.claude/commands/sr/<name>.md`
+   - Show: `✓ Added /sr:<name>`
+4. If the user declines:
+   - Show: `→ Skipped /sr:<name>`
+
 ### Phase U6: Update Workflow Commands
 
 If any new agents were added in Phase U5:
@@ -171,28 +245,41 @@ Display the final summary and stop. Do not continue to Phase 1 of the full setup
 
 specrails updated from v<previous> to v<new>.
 
-| Action             | Count |
-|--------------------|-------|
-| Agents regenerated | N     |
-| Agents added       | N     |
-| Agents skipped     | N     |
-| Commands updated   | N     |
+| Action              | Count |
+|---------------------|-------|
+| Agents regenerated  | N     |
+| Agents added        | N     |
+| Agents skipped      | N     |
+| Commands updated    | N     |
+| Commands added      | N     |
+| Commands skipped    | N     |
 
-All agents are now up to date.
+All agents and commands are now up to date.
 
-### Regenerated
+### Agents Regenerated
 [list agent names, or "(none)"]
 
-### Added
+### Agents Added
 [list agent names, or "(none)"]
 
-### Skipped
+### Agents Skipped
 [list agent names, or "(none)"]
+
+### Commands Updated
+[list command names, or "(none)"]
+
+### Commands Added
+[list command names, or "(none)"]
+
+### Commands Skipped
+[list command names, or "(none)"]
 ```
 
-Update `.specrails-manifest.json` to reflect the new checksums for all regenerated and added agents:
-- For each regenerated agent: update its checksum entry to the new template's checksum
+Update `.specrails-manifest.json` to reflect the new checksums for all regenerated/updated and added agents and commands:
+- For each regenerated agent: update its checksum entry to the new template's checksum (keyed as `templates/agents/sr-<name>.md`)
 - For each added agent: add a new entry with its checksum
+- For each updated command: update its checksum entry to the new template's checksum (keyed as `templates/commands/sr/<name>.md`)
+- For each added command: add a new entry with its checksum
 - Update the `version` field to the version read from `.specrails-version`
 
 ---
@@ -801,11 +888,37 @@ For each selected command, read the template and adapt:
 
 Adapt:
 - CI commands to match detected stack
-- Persona references to match generated personas
+- **Persona references** to match generated personas (see substitution rules below)
 - File paths to match project structure
 - Layer tags to match detected layers
 - **Backlog provider commands** based on `BACKLOG_PROVIDER`:
 
+#### Backlog command persona placeholder substitution
+
+When adapting `update-product-driven-backlog.md` and `product-backlog.md`, substitute the persona placeholders based on the full persona set (user-generated personas + Maintainer if `IS_OSS=true`):
+
+| Placeholder | Substitution rule |
+|-------------|------------------|
+| `{{PERSONA_FILE_READ_LIST}}` | One bullet per persona file: `- Read \`.claude/agents/personas/{name}.md\`` |
+| `{{PERSONA_SCORE_HEADERS}}` | Column headers for each persona nickname: e.g., `Alex \| Sara \| Kai` |
+| `{{PERSONA_SCORE_SEPARATORS}}` | One `------` separator per persona column |
+| `{{PERSONA_FIT_FORMAT}}` | Inline score display: e.g., `Alex: X/5, Sara: X/5, Kai: X/5` |
+| `{{PERSONA_VPC_SECTIONS}}` | One VPC section block per persona (see format below) |
+| `{{MAX_SCORE}}` | Total max score = 5 × number of personas (e.g., `15` for 3 personas) |
+| `{{PERSONA_NAMES_WITH_ROLES}}` | Comma-separated: e.g., `Alex (Lead Dev), Sara (Product Founder), Kai (OSS Maintainer)` |
+
+**`{{PERSONA_VPC_SECTIONS}}` format** — repeat for each persona in order:
+```
+### "{Nickname}" — The {Role} (X/5)
+- **Jobs addressed**: {list}
+- **Pains relieved**: {list with severity}
+- **Gains created**: {list with impact}
+```
+
+**Kai inclusion rule**: When `IS_OSS=true`, Kai (`sr-the-maintainer.md`) is always the last entry in persona lists and the rightmost column in scoring tables. Kai uses the evaluation criteria defined in `.claude/agents/personas/sr-the-maintainer.md` — features score high (4-5/5) for Kai when they reduce async review burden, enforce project-specific conventions, or automate release/dependency coordination; features score low (0-1/5) when they add configuration complexity or require paid tiers.
+
+**When `IS_OSS=false`**: All Kai-related persona references are omitted. `{{MAX_SCORE}}` reduces by 5. Tables and inline scores contain only user-generated personas.
+
 #### GitHub Issues (`BACKLOG_PROVIDER=github`)
 - Issue fetch: `gh issue list --label "product-driven-backlog" --state open --limit 100 --json number,title,labels,body`
 - Issue create: `gh issue create --title "..." --label "..." --body "..."`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specrails-core",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "AI agent workflow system for Claude Code — installs 12 specialized agents, orchestration commands, and persona-driven product discovery into any repository",
   "bin": {
     "specrails-core": "bin/specrails-core.js"