specrails-core 1.3.0 → 1.5.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

@@ -801,11 +801,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.3.0",
+  "version": "1.5.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"

package/templates/commands/sr/memory-inspect.md

@@ -0,0 +1,259 @@
+---
+name: "Agent Memory Inspector"
+description: "Inspect and manage agent memory directories. Lists all sr-* agent memory stores, shows per-agent stats (file count, size, last modified), displays recent entries, and detects stale or orphaned files."
+category: Workflow
+tags: [workflow, memory, agents, maintenance, diagnostics]
+---
+
+Inspect agent memory directories under `.claude/agent-memory/sr-*/` for **{{PROJECT_NAME}}**. Show per-agent stats, recent entries, and actionable recommendations.
+
+**Input:** `$ARGUMENTS` — optional:
+- `<agent-name>` — inspect a specific agent's memory (e.g. `sr-developer`, `sr-reviewer`)
+- `--stale <days>` — flag files not modified in more than N days as stale (default: 30)
+- `--prune` — delete stale files after confirmation (prints the list first, then asks)
+
+---
+
+## Phase 0: Argument Parsing
+
+Parse `$ARGUMENTS` to set runtime variables.
+
+**Variables to set:**
+
+- `AGENT_FILTER` — string or empty string. Default: `""` (inspect all agents).
+- `STALE_DAYS` — integer. Default: `30`.
+- `PRUNE_MODE` — boolean. Default: `false`.
+
+**Parsing rules:**
+
+1. Scan `$ARGUMENTS` for `--stale <N>`. If found, set `STALE_DAYS=<N>`. Validate that `<N>` is a positive integer; if not, print `Error: --stale requires a positive integer (e.g. --stale 14)` and stop. Strip from arguments.
+2. Scan for `--prune`. If found, set `PRUNE_MODE=true`. Strip from arguments.
+3. Remaining non-flag text (if any) is treated as `AGENT_FILTER`. Strip leading/trailing whitespace.
+
+**Print active configuration:**
+
+```
+Scanning: <all agents | agent: AGENT_FILTER> | Stale threshold: STALE_DAYS days | Prune: yes/no
+```
+
+---
+
+## Phase 1: Discover Memory Directories
+
+Glob all directories matching `.claude/agent-memory/sr-*/`.
+
+If no directories are found:
+```
+No agent memory directories found under .claude/agent-memory/.
+
+Agent memory is written by sr-* agents during the /sr:implement pipeline.
+Run /sr:implement on a feature to generate your first memory entries.
+```
+Then stop.
+
+If `AGENT_FILTER` is set, filter to only the directory `.claude/agent-memory/<AGENT_FILTER>/`. If that directory does not exist:
+```
+No memory directory found for agent: <AGENT_FILTER>
+
+Available agents:
+  <list of discovered sr-* directory names>
+```
+Then stop.
+
+Set `AGENT_DIRS` = list of matching directories (full paths), sorted alphabetically.
+
+---
+
+## Phase 2: Collect Per-Agent Stats
+
+For each directory in `AGENT_DIRS`, collect:
+
+- `AGENT_NAME` — directory name (e.g. `sr-developer`)
+- `FILE_COUNT` — total number of files (recursive, all types)
+- `TOTAL_SIZE` — total size in bytes; display as human-readable (KB, MB)
+- `LAST_MODIFIED` — ISO date of the most recently modified file
+- `OLDEST_MODIFIED` — ISO date of the least recently modified file
+- `STALE_FILES` — list of files not modified in more than `STALE_DAYS` days (full paths)
+- `STALE_COUNT` — count of stale files
+
+Use the current date to compute stale age. A file is stale if `(today - last_modified) > STALE_DAYS`.
+
+Print a summary table after collecting all stats:
+
+```
+## Agent Memory Overview
+
+| Agent | Files | Size | Last Modified | Stale (>STALE_DAYS days) |
+|-------|-------|------|---------------|--------------------------|
+| sr-developer   | N | N KB | YYYY-MM-DD | N files |
+| sr-reviewer    | N | N KB | YYYY-MM-DD | N files |
+| ...            | ... | ... | ...        | ...     |
+
+Total: N agents | N files | N KB
+```
+
+---
+
+## Phase 3: Display Recent Entries
+
+For each agent in `AGENT_DIRS`, show the 5 most recently modified files.
+
+Print per agent:
+
+```
+### <agent-name>
+
+Recent entries (5 most recent):
+
+| File | Size | Last Modified |
+|------|------|---------------|
+| common-fixes.md | 2.1 KB | 2026-03-18 |
+| ...             | ...    | ...         |
+```
+
+If the agent directory has fewer than 5 files, show all of them.
+
+If `AGENT_FILTER` is set (single-agent mode), show the full content of each file up to 50 lines. For files exceeding 50 lines, print the first 50 lines followed by:
+```
+... (N more lines — view full file at <relative-path>)
+```
+
+---
+
+## Phase 4: Orphan Detection
+
+An **orphaned** memory directory is one whose agent name does not correspond to a known sr-agent persona.
+
+Known sr-agent names (check for exact match):
+`sr-architect`, `sr-developer`, `sr-test-writer`, `sr-reviewer`, `sr-frontend-reviewer`, `sr-backend-reviewer`, `sr-security-reviewer`, `sr-doc-sync`, `sr-product-manager`
+
+For each directory in `AGENT_DIRS`, check whether its `AGENT_NAME` is in the known list. Collect non-matching directories as `ORPHANED_DIRS`.
+
+If `ORPHANED_DIRS` is non-empty, print:
+
+```
+### Orphaned Memory Directories
+
+The following directories do not match any known sr-agent name and may be leftover from renamed or removed agents:
+
+| Directory | Files | Size | Recommendation |
+|-----------|-------|------|----------------|
+| sr-old-agent | N | N KB | Review and delete if no longer needed |
+```
+
+If `ORPHANED_DIRS` is empty: skip this section entirely.
+
+---
+
+## Phase 5: Stale File Report
+
+Collect all stale files across all agents (from Phase 2 `STALE_FILES` lists).
+
+If no stale files exist:
+```
+No stale files found (threshold: STALE_DAYS days). Memory is up to date.
+```
+Skip the rest of Phase 5.
+
+Otherwise, print:
+
+```
+### Stale Files (not modified in >STALE_DAYS days)
+
+| Agent | File | Size | Last Modified | Age (days) |
+|-------|------|------|---------------|------------|
+| sr-developer | common-fixes.md | 1.2 KB | 2026-01-10 | 69 |
+| ...          | ...             | ...    | ...        | ...        |
+
+N stale files total (N KB).
+```
+
+---
+
+## Phase 6: Prune (if --prune)
+
+Skip this phase if `PRUNE_MODE=false`.
+
+If `PRUNE_MODE=true` and there are no stale files and no orphaned directories:
+```
+Nothing to prune. All memory files are within the STALE_DAYS-day threshold.
+```
+Then stop.
+
+Otherwise, print the full list of files and directories that will be deleted:
+
+```
+## Files to Delete
+
+The following N files will be permanently deleted:
+
+Stale files:
+  - .claude/agent-memory/sr-developer/common-fixes.md (69 days old)
+  - ...
+
+Orphaned directories:
+  - .claude/agent-memory/sr-old-agent/ (N files, N KB)
+
+Proceed? [y/N]:
+```
+
+Wait for user input.
+
+- If the user enters `y` or `Y`:
+  - Delete each stale file individually.
+  - Delete each orphaned directory recursively.
+  - Print a confirmation for each deletion: `Deleted: <path>`
+  - Print a summary:
+    ```
+    Pruned N files (N KB freed).
+    ```
+- If the user enters anything else (or presses Enter):
+  - Print: `Prune cancelled. No files were deleted.`
+  - Stop.
+
+---
+
+## Phase 7: Recommendations
+
+Print a final recommendations section based on findings:
+
+```
+## Recommendations
+
+<one or more of the following, based on findings>
+```
+
+**Recommendation rules (print only applicable ones):**
+
+1. **Prune stale data** — if `STALE_COUNT > 0` across any agent and `PRUNE_MODE=false`:
+   ```
+   - N stale files detected. Run `/sr:memory-inspect --prune` to remove them and free N KB.
+   ```
+
+2. **Investigate large memory** — if any single agent's `TOTAL_SIZE > 1 MB`:
+   ```
+   - <agent-name> memory exceeds 1 MB (TOTAL_SIZE). Consider reviewing large files:
+     <list files over 100 KB>
+   ```
+
+3. **Orphaned directories** — if `ORPHANED_DIRS` is non-empty:
+   ```
+   - N orphaned director(y|ies) found. Review and delete manually if no longer needed.
+   ```
+
+4. **Empty memory directories** — if any agent directory has `FILE_COUNT = 0`:
+   ```
+   - <agent-name> memory directory is empty. It may be safe to delete:
+     rm -rf .claude/agent-memory/<agent-name>/
+   ```
+
+5. **Gitignore advisory** — check whether `.claude/agent-memory` appears in `.gitignore`. If not:
+   ```
+   - Agent memory is local runtime state. Add to .gitignore:
+       echo '.claude/agent-memory/' >> .gitignore
+   ```
+
+If no recommendations apply, print:
+```
+All agent memory looks healthy. No action required.
+```