specrails-core 0.7.1 → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Javier Pulido
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,110 +1,105 @@
-# specrails
+# specrails-core
 
-**Agent Workflow System installer for Claude Code.**
+[![npm version](https://img.shields.io/npm/v/specrails-core.svg)](https://www.npmjs.com/package/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)
 
-Install a complete product-driven development workflow into any repository: specialized AI agents, orchestration commands, VPC-based product discovery, and per-layer coding conventions — all adapted to your codebase automatically.
+**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.
 
-## What it does
-
-specrails gives your project a team of specialized AI agents that work together through a structured pipeline:
-
-```
-Product Discovery    →  Architecture  →  Implementation  →  Review     →  Ship
-(sr-product-manager)    (sr-architect)    (sr-developer)    (sr-reviewer)  (PR)
+```bash
+npx specrails-core@latest init --root-dir <your-project>
 ```
 
-Every artifact — agents, commands, rules, personas — is generated specifically for your project by analyzing your actual codebase, tech stack, and target users. Not generic templates: fully contextualized to your architecture, CI pipeline, and coding conventions.
+---
 
-## What gets installed
+## The pipeline
 
-| Category | Files | Purpose |
-|----------|-------|---------|
-| **Agents** | `.claude/agents/*.md` | 12 specialized AI agents (sr-architect, sr-developer, sr-backend-developer, sr-frontend-developer, sr-reviewer, sr-backend-reviewer, sr-frontend-reviewer, sr-product-manager, sr-product-analyst, sr-test-writer, sr-security-reviewer, sr-doc-sync) |
-| **Personas** | `.claude/agents/personas/*.md` | Value Proposition Canvas profiles for your target users, generated from competitive research |
-| **Commands** | `.claude/commands/sr/*.md` | Workflow orchestrators (`/sr:implement`, `/sr:product-backlog`, `/sr:update-product-driven-backlog`) |
-| **Rules** | `.claude/rules/*.md` | Per-layer coding conventions, loaded conditionally by file path |
-| **Memory** | `.claude/agent-memory/` | Persistent knowledge directories — agents learn across sessions |
-| **Config** | `.claude/settings.json`, `CLAUDE.md` | Permissions, project context, architecture reference |
+```
+Product Discovery  →  Architecture  →  Implementation  →  Review  →  Ship
+(sr-product-manager)  (sr-architect)   (sr-developer)   (sr-reviewer)  (PR)
+```
 
-## How it works
+One command runs the full cycle:
 
-Installation happens in two steps — a shell script for scaffolding, then Claude for the intelligent parts.
+```
+/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
+```
 
-### Step 1: Install
+Multiple features run in parallel using git worktrees. Single features run sequentially.
 
-**Option A — npx (recommended)**
+---
 
-```bash
-npx specrails-core@latest init --root-dir <your-project>
-```
+## Quick start
 
-**Option B — git clone**
+**Step 1 — Install into your project**
 
 ```bash
-git clone https://github.com/fjpulidop/specrails-core.git
-./specrails-core/install.sh --root-dir <your-project>
+npx specrails-core@latest init --root-dir /path/to/your/repo
 ```
 
-The installer:
+The installer scaffolds temporary setup files into `.claude/` and checks prerequisites (Claude Code, git, npm, GitHub CLI).
 
-1. **Checks prerequisites** — git, Claude Code CLI, npm, OpenSpec CLI, GitHub CLI
-2. **Offers to install missing tools** — npm via nvm, OpenSpec via npm
-3. **Detects existing setup** — warns if `.claude/` or `openspec/` already exist
-4. **Scaffolds temporary files** — copies templates and the `/setup` command into `.claude/`
-
-### Step 2: Setup (inside Claude Code)
+**Step 2 — Run the setup wizard inside Claude Code**
 
 ```bash
-claude     # open Claude Code in your repo
-> /setup   # run the setup wizard
+cd /path/to/your/repo
+claude          # open Claude Code
+> /setup        # run the interactive setup wizard
 ```
 
-Claude runs an interactive 5-phase wizard:
-
-| Phase | What happens | Interaction |
-|-------|-------------|-------------|
-| **1. Codebase Analysis** | Reads your repo structure, detects stack, layers, CI commands, and coding conventions | Confirm or modify detected architecture |
-| **2. User Personas** | Asks who your target users are, researches the competitive landscape online, generates full VPC personas | Describe your users, approve generated personas |
-| **3. Configuration** | Choose backlog provider (GitHub Issues / JIRA / none), access mode (read/write or read-only), git workflow (auto or manual), agents, and commands | Select options |
-| **4. File Generation** | Fills all templates with your project's context and writes final files | Automatic |
-| **5. Cleanup** | Removes scaffolding (`/setup` command, templates), adds `specrails/` to `.gitignore` | Confirm cleanup |
+Claude runs a 5-phase wizard that reads your actual codebase and generates everything tailored to your stack:
 
-After setup, the scaffolding self-destructs — only the final, project-specific files remain.
+| 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 |
 
-## Prerequisites
-
-| Tool | Required | Purpose |
-|------|----------|---------|
-| **Git** | Yes | Repository detection |
-| **Claude Code** | Yes | AI agent runtime — [install](https://docs.anthropic.com/en/docs/claude-code) |
-| **npm** | Recommended | Needed to install OpenSpec CLI |
-| **OpenSpec CLI** | Recommended | Spec-driven design workflow (`/opsx:ff`, `/opsx:apply`) |
-| **GitHub CLI** (`gh`) | Optional | Backlog sync to GitHub Issues, PR creation |
-| **JIRA CLI** (`jira`) | Optional | Backlog sync to JIRA (alternative to GitHub Issues) |
+---
 
-The installer will check for each tool and offer to install missing ones.
+## What gets installed
 
-> **Note:** You only need one backlog provider — GitHub Issues or JIRA. The `/setup` wizard asks which one you use. If you don't use either, backlog commands are skipped but `/sr:implement "description"` still works.
+| Category | Location | Description |
+|----------|----------|-------------|
+| **Agents** | `.claude/agents/*.md` | 12 specialized AI agents |
+| **Personas** | `.claude/agents/personas/*.md` | VPC user profiles from competitive research |
+| **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 |
 
-## Usage after installation
+---
 
-Once setup is complete, you have three main commands:
+## The 12 agents
 
-### `/sr:implement` — Build features
+| Agent | Model | Role |
+|-------|-------|------|
+| **sr-architect** | Sonnet | Designs features — proposal, technical design, task breakdown |
+| **sr-developer** | Sonnet | Full-stack implementation from architect artifacts |
+| **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-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-product-analyst** | Haiku | Read-only backlog analysis and prioritization |
 
-The full pipeline: architect designs, developer implements, reviewer validates, then ships a PR.
+The `/sr:implement` pipeline routes tasks to the right agent automatically based on layer tags.
 
-```
-/sr:implement #85, #71           # implement specific GitHub Issues
-/sr:implement "add dark mode"    # implement from a text description
-/sr:implement UI, Analytics      # explore areas and pick the best ideas
-```
+---
 
-Handles 1 to N features. Single features run sequentially; multiple features run in parallel using git worktrees.
+## Product discovery commands
 
-### `/sr:product-backlog` — View prioritized backlog
+### `/sr:product-backlog` — Prioritized backlog
 
-Reads GitHub Issues labeled `product-driven-backlog`, sorts by VPC persona score, and recommends the top 3 for the next sprint.
+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
@@ -113,35 +108,18 @@ Reads GitHub Issues labeled `product-driven-backlog`, sorts by VPC persona score
 
 ### `/sr:update-product-driven-backlog` — Discover new features
 
-Runs product discovery using your VPC personas. Analyzes the codebase, evaluates ideas against each persona's jobs/pains/gains, and creates GitHub Issues for the best ones.
+Analyzes your codebase against each persona's jobs/pains/gains, generates new feature ideas, and creates GitHub Issues for the best ones.
 
 ```
-/sr:update-product-driven-backlog            # explore all areas
-/sr:update-product-driven-backlog Analytics  # focus on one area
+/sr:update-product-driven-backlog             # explore all areas
+/sr:update-product-driven-backlog Analytics   # focus on one area
 ```
 
-## The agents
+---
 
-| Agent | Model | Role |
-|-------|-------|------|
-| **sr-architect** | Sonnet | Designs features: creates proposal, technical design, task breakdown, and context bundles via OpenSpec |
-| **sr-developer** | Sonnet | Implements features: reads the architect's artifacts and writes production code across all layers |
-| **sr-backend-developer** | Sonnet | Specialized backend implementation (lighter prompt, backend-only CI) |
-| **sr-frontend-developer** | Sonnet | Specialized frontend implementation (lighter prompt, frontend-only CI) |
-| **sr-reviewer** | Sonnet | Final quality gate: runs exact CI checks, fixes issues, records learnings for future developers |
-| **sr-backend-reviewer** | Sonnet | Backend-focused code review: API design, database patterns, performance |
-| **sr-frontend-reviewer** | Sonnet | Frontend-focused code review: UX patterns, accessibility, component design |
-| **sr-test-writer** | Sonnet | Generates tests: unit, integration, and e2e tests using your project's test framework |
-| **sr-security-reviewer** | Sonnet | Security scanning: secrets detection, OWASP checks, dependency vulnerabilities |
-| **sr-doc-sync** | Sonnet | Documentation sync: updates changelogs, READMEs, and API docs after changes |
-| **sr-product-manager** | Opus | Product discovery: competitive analysis, VPC evaluation, feature ideation |
-| **sr-product-analyst** | Haiku | Read-only backlog analysis: prioritization, gap analysis, reporting |
-
-The `/sr:implement` pipeline automatically routes tasks to the right developer agent based on layer tags in the task breakdown.
+## Value Proposition Canvas scoring
 
-## Value Proposition Canvas (VPC)
-
-Every feature idea is evaluated against your project's user personas using the VPC framework:
+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.
 
 ```
 +-----------------------------+    +-----------------------------+
@@ -153,52 +131,28 @@ Every feature idea is evaluated against your project's user personas using the V
 +-----------------------------+    +-----------------------------+
 ```
 
-Each persona scores features 0-5 based on how well they address their specific jobs, pains, and gains. Features are ranked by total persona score / effort ratio. This grounds every product decision in real user needs rather than gut feeling.
+---
+
+## Prerequisites
 
-## Project structure
+| 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 |
 
-```
-specrails/
-├── install.sh                              # Step 1: shell installer
-├── README.md                               # This file
-├── commands/
-│   └── setup.md                            # Step 2: Claude Code /setup wizard
-├── templates/                              # Structural references for file generation
-│   ├── agents/
-│   │   ├── sr-architect.md                 # Design & task breakdown agent
-│   │   ├── sr-developer.md                 # Full-stack implementation agent
-│   │   ├── sr-backend-developer.md         # Backend-specialized agent
-│   │   ├── sr-frontend-developer.md        # Frontend-specialized agent
-│   │   ├── sr-reviewer.md                  # CI/CD quality gate agent
-│   │   ├── sr-backend-reviewer.md          # Backend code review agent
-│   │   ├── sr-frontend-reviewer.md         # Frontend code review agent
-│   │   ├── sr-test-writer.md               # Test generation agent
-│   │   ├── sr-security-reviewer.md         # Security scanning agent
-│   │   ├── sr-doc-sync.md                  # Documentation sync agent
-│   │   ├── sr-product-manager.md           # Product discovery agent
-│   │   └── sr-product-analyst.md           # Read-only analysis agent
-│   ├── commands/
-│   │   └── sr/
-│   │       ├── implement.md                # Implementation pipeline orchestrator
-│   │       ├── product-backlog.md          # Backlog viewer with VPC scoring
-│   │       └── update-product-driven-backlog.md # Product discovery & issue sync
-│   ├── personas/
-│   │   └── persona.md                      # VPC persona template
-│   ├── rules/
-│   │   └── layer.md                        # Per-layer convention template
-│   ├── claude-md/
-│   │   └── root.md                         # Root CLAUDE.md template
-│   └── settings/
-│       └── settings.json                   # Permission template
-└── prompts/
-    ├── analyze-codebase.md                 # Guide for codebase analysis
-    ├── generate-personas.md                # Guide for VPC persona generation
-    └── infer-conventions.md                # Guide for convention detection
-```
+The installer checks for each tool and offers to install missing ones automatically.
+
+> You only need one backlog provider. If you use neither, `/sr:implement "description"` still works.
+
+---
 
 ## Supported stacks
 
-specrails is stack-agnostic. The `/setup` wizard detects and adapts to whatever you're using:
+specrails-core is stack-agnostic — the setup wizard reads your actual files and generates accurate conventions, not generic templates.
 
 - **Backend**: Python/FastAPI, Node/Express, Go/Gin, Rust/Actix, Java/Spring, Ruby/Rails, .NET
 - **Frontend**: React, Vue, Angular, Svelte, Next.js, Nuxt
@@ -206,39 +160,37 @@ specrails is stack-agnostic. The `/setup` wizard detects and adapts to whatever
 - **CI/CD**: GitHub Actions, GitLab CI, Jenkins, Makefile
 - **Testing**: pytest, vitest, jest, go test, cargo test, rspec
 
-The setup wizard reads your actual CI config, dependency files, and source code to generate accurate conventions — not guesses.
+---
 
 ## Design principles
 
-1. **Two-step install**: Shell for prerequisites, Claude for intelligence. No API keys needed beyond Claude Code auth.
-2. **Self-cleaning**: All scaffolding artifacts are removed after setup. Only final files remain.
-3. **Context-first**: Every generated file references real paths, real patterns, and real CI commands from your codebase.
-4. **Persona-driven**: Product decisions are grounded in researched user personas, not assumptions.
-5. **Institutional memory**: Agents learn across sessions via persistent memory directories. The reviewer's learnings feed back to developers.
-6. **Parallel-safe**: Multiple features can be implemented simultaneously using git worktrees with automatic merge.
+1. **Two-step install** — Shell handles prerequisites, Claude handles intelligence. No API keys beyond Claude Code auth.
+2. **Self-cleaning** — All scaffolding removed after setup. Only final, project-specific files remain.
+3. **Context-first** — Every generated file uses your real paths, patterns, and CI commands.
+4. **Persona-driven** — Product decisions grounded in researched user personas, not assumptions.
+5. **Institutional memory** — Agents learn across sessions. Reviewer learnings feed back to future developers.
+6. **Parallel-safe** — Multiple features implemented simultaneously via git worktrees with automatic merge.
+
+---
 
 ## FAQ
 
 **Can I customize the agents after installation?**
-Yes. The generated files in `.claude/` are yours to edit. They're plain markdown — modify agent personalities, adjust CI commands, add new rules, or create new personas.
+Yes. Files in `.claude/` are plain markdown — edit agent personalities, adjust CI commands, add rules, create personas.
 
 **Can I re-run setup?**
-The `/setup` command deletes itself after completion. To re-run, execute `install.sh` again to re-scaffold, then run `/setup`.
+Run `npx specrails-core@latest init --root-dir <path>` again to re-scaffold, then `/setup`.
 
 **Does this work without OpenSpec?**
-Partially. The `/sr:implement` command and sr-architect agent rely on OpenSpec for structured design artifacts. Without it, you can still use the product discovery commands and individual agents directly.
+Partially. `/sr:implement` and sr-architect use OpenSpec for structured design artifacts. Product discovery commands and individual agents work without it.
 
 **Does this work without GitHub CLI?**
-Yes, with limitations. If you use GitHub Issues as your backlog provider, `gh` is needed for backlog commands. But you can use JIRA instead, or skip backlog commands entirely. The `/sr:implement` command still works with text descriptions — it just skips PR creation and tells you to create it manually.
-
-**Can I use JIRA instead of GitHub Issues?**
-Yes. During `/setup` Phase 3, choose "JIRA" as your backlog provider. If the JIRA CLI isn't installed, the wizard offers to install it (go-jira via brew, or REST API mode with no CLI needed). You'll also choose whether access is read & write (create tickets, add comments on completion) or read-only (read tickets for context but never modify JIRA).
+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.
 
-**Can I skip automatic git operations?**
-Yes. During `/setup` Phase 3, choose "Manual" for the git workflow. The pipeline will still architect, develop, and review — but it stops after review and shows you a summary of all changes. You handle branching, committing, and PRs yourself.
+**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.
 
-**How much does it cost to run?**
-Depends on usage. The sr-product-manager agent uses Opus (most capable, most expensive) for deep product thinking. All other agents use Sonnet or Haiku. A full `/sr:implement` cycle for one feature typically costs a few dollars in API usage through Claude Code.
+---
 
 ## License
 

package/bin/doctor.sh

@@ -0,0 +1,118 @@
+#!/bin/bash
+# specrails doctor — health check for specrails-core installations
+# Usage: specrails doctor
+# Exit 0 if all checks pass, 1 if any check fails.
+
+set -uo pipefail
+
+# Colors
+GREEN='\033[0;32m'
+RED='\033[0;31m'
+NC='\033[0m'
+BOLD='\033[1m'
+
+PASS=0
+FAIL=0
+RESULTS=()
+
+pass() { RESULTS+=("$(printf "${GREEN}✅${NC} $1")"); PASS=$((PASS + 1)); }
+fail() { RESULTS+=("$(printf "${RED}❌${NC} $1\n   Fix: $2")"); FAIL=$((FAIL + 1)); }
+
+echo ""
+echo -e "${BOLD}specrails doctor${NC}"
+echo ""
+
+# Determine project root (current working directory)
+PROJECT_ROOT="${PWD}"
+
+# ─────────────────────────────────────────────
+# Check 1: Claude Code CLI
+# ─────────────────────────────────────────────
+if CLAUDE_PATH=$(command -v claude 2>/dev/null); then
+    pass "Claude Code CLI: found (${CLAUDE_PATH})"
+else
+    fail "Claude Code CLI: not found" "Install Claude Code: https://claude.ai/download"
+fi
+
+# ─────────────────────────────────────────────
+# Check 2: Claude API key
+# ─────────────────────────────────────────────
+if command -v claude &>/dev/null; then
+    if claude config list 2>/dev/null | grep -q "api_key" || [[ -n "${ANTHROPIC_API_KEY:-}" ]]; then
+        pass "API key: configured"
+    else
+        fail "API key: not configured" "Run: claude config set api_key <your-key>  |  Get a key: https://console.anthropic.com/"
+    fi
+fi
+
+# ─────────────────────────────────────────────
+# Check 3: Agent files present
+# ─────────────────────────────────────────────
+AGENTS_DIR="${PROJECT_ROOT}/agents"
+if [[ -d "${AGENTS_DIR}" ]]; then
+    AGENT_COUNT=$(find "${AGENTS_DIR}" -name "AGENTS.md" 2>/dev/null | wc -l | tr -d ' ')
+    if [[ "${AGENT_COUNT}" -ge 1 ]]; then
+        AGENT_NAMES=$(find "${AGENTS_DIR}" -name "AGENTS.md" -exec dirname {} \; | xargs -I{} basename {} | tr '\n' ', ' | sed 's/,$//')
+        pass "Agent files: ${AGENT_COUNT} agent(s) found (${AGENT_NAMES})"
+    else
+        fail "Agent files: agents/ exists but no AGENTS.md found" "Run specrails-core init to set up agents"
+    fi
+else
+    fail "Agent files: agents/ directory not found" "Run specrails-core init to set up agents"
+fi
+
+# ─────────────────────────────────────────────
+# Check 4: CLAUDE.md present
+# ─────────────────────────────────────────────
+if [[ -f "${PROJECT_ROOT}/CLAUDE.md" ]]; then
+    pass "CLAUDE.md: present"
+else
+    fail "CLAUDE.md: missing" "Run /setup inside Claude Code to regenerate"
+fi
+
+# ─────────────────────────────────────────────
+# Check 5: Git initialized
+# ─────────────────────────────────────────────
+if [[ -d "${PROJECT_ROOT}/.git" ]]; then
+    pass "Git: initialized"
+else
+    fail "Git: not a git repository" "Initialize with: git init"
+fi
+
+# ─────────────────────────────────────────────
+# Check 6: npm present
+# ─────────────────────────────────────────────
+if NPM_VERSION=$(npm --version 2>/dev/null); then
+    pass "npm: found (v${NPM_VERSION})"
+else
+    fail "npm: not found" "Install npm: https://docs.npmjs.com/downloading-and-installing-node-js-and-npm"
+fi
+
+# ─────────────────────────────────────────────
+# Output results
+# ─────────────────────────────────────────────
+for line in "${RESULTS[@]}"; do
+    echo -e "${line}"
+done
+
+echo ""
+
+if [[ "${FAIL}" -eq 0 ]]; then
+    TOTAL=$((PASS + FAIL))
+    echo -e "All ${TOTAL} checks passed. Run ${BOLD}/sr:product-backlog${NC} to get started."
+else
+    echo "${FAIL} check(s) failed."
+fi
+
+# ─────────────────────────────────────────────
+# Append to ~/.specrails/doctor.log
+# ─────────────────────────────────────────────
+LOG_DIR="${HOME}/.specrails"
+mkdir -p "${LOG_DIR}"
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || date -u)
+TOTAL=$((PASS + FAIL))
+echo "${TIMESTAMP}  checks=${TOTAL} passed=${PASS} failed=${FAIL}" >> "${LOG_DIR}/doctor.log"
+
+echo ""
+
+exit $([[ "${FAIL}" -eq 0 ]] && echo 0 || echo 1)

package/bin/specrails-core.js

@@ -7,6 +7,7 @@ const ROOT = resolve(__dirname, "..");
 const COMMANDS = {
   init: "install.sh",
   update: "update.sh",
+  doctor: "bin/doctor.sh",
 };
 
 const args = process.argv.slice(2);
@@ -18,6 +19,7 @@ if (!subcommand) {
 Usage:
   specrails-core init   [--root-dir <path>]     Install into a repository
   specrails-core update [--only <component>]    Update an existing installation
+  specrails-core doctor                         Run health checks
 
 More info: https://github.com/fjpulidop/specrails-core`);
   process.exit(0);
@@ -27,7 +29,7 @@ const script = COMMANDS[subcommand];
 
 if (!script) {
   console.error(`Unknown command: ${subcommand}\n`);
-  console.error("Available commands: init, update");
+  console.error("Available commands: init, update, doctor");
   process.exit(1);
 }
 

package/commands/doctor.md

@@ -0,0 +1,62 @@
+# Doctor: specrails Health Check
+
+Run the specrails health check to validate that all prerequisites are correctly configured for this repository.
+
+---
+
+## What it checks
+
+| Check | Pass condition |
+|-------|---------------|
+| Claude Code CLI | `claude` binary found in PATH |
+| Claude API key | `claude config list` shows a key OR `ANTHROPIC_API_KEY` env var set |
+| Agent files | `agents/` directory exists with at least 1 `AGENTS.md` file |
+| CLAUDE.md | `CLAUDE.md` present in the repo root |
+| Git initialized | `.git/` directory present |
+| npm | `npm` binary found in PATH |
+
+## How to run
+
+This command delegates to the standalone health check script installed at `.specrails/bin/doctor.sh`. Run it directly:
+
+```
+Bash tool: bash .specrails/bin/doctor.sh
+```
+
+Or via the npm CLI wrapper:
+
+```
+npx specrails-core@latest doctor
+```
+
+## Output
+
+Each check is displayed as ✅ (pass) or ❌ (fail with fix instruction).
+
+On all checks passed:
+```
+All 6 checks passed. Run /sr:product-backlog to get started.
+```
+
+On failure:
+```
+❌ API key: not configured
+   Fix: Run: claude config set api_key <your-key>  |  Get a key: https://console.anthropic.com/
+
+1 check(s) failed.
+```
+
+## Exit codes
+
+- `0` — all checks passed
+- `1` — one or more checks failed
+
+## Log file
+
+Each run appends a timestamped summary to `~/.specrails/doctor.log`:
+
+```
+2026-03-20T10:00:00Z  checks=6 passed=6 failed=0
+```
+
+The `~/.specrails/` directory is created automatically if it does not exist.

package/commands/setup.md

@@ -8,9 +8,13 @@ Interactive wizard to configure the full agent workflow system for this reposito
 
 ## Mode Detection
 
-Check if `$ARGUMENTS` contains `--update`:
-- If yes → execute **Update Mode** (below), then stop. Do NOT continue to the full setup wizard.
-- If no → skip to **Phase 1** and execute the full setup wizard.
+Check `$ARGUMENTS` in this order:
+
+1. If `--update` is present → execute **Update Mode** (below), then stop. Do NOT continue to Phase 1 or Quick Start.
+2. If `--advanced` is present → skip directly to **Phase 1** and execute the full 5-phase wizard.
+3. Otherwise (no flags) → execute **Quick Start Mode** (below), then stop. Do NOT execute Phase 1.
+
+**Default is Quick Start.** The full wizard only runs when `--advanced` is explicitly passed.
 
 ---
 
@@ -193,6 +197,125 @@ Update `.specrails-manifest.json` to reflect the new checksums for all regenerat
 
 ---
 
+## Quick Start Mode
+
+When no flags are passed (the default), run this streamlined 3-question setup. Do NOT run Phase 1–5. When QS4 is complete, stop.
+
+### QS1: Ask the 3 questions
+
+Ask exactly these questions in sequence. Do not ask any other questions.
+
+```
+Welcome to specrails! Let's get your AI agent team set up in 3 quick questions.
+
+1. What is this project? (one sentence)
+   > _
+
+2. Who are the target users?
+   > _
+
+3. Git access for agents — read-only or read-write?
+   (read-only = agents can read and suggest; read-write = agents can commit)
+   > _
+```
+
+Store the answers as:
+- `QS_PROJECT_DESCRIPTION` — answer to question 1
+- `QS_TARGET_USERS` — answer to question 2
+- `QS_GIT_ACCESS` — "read-only" or "read-write" (normalize if user types "ro", "rw", "readonly", etc.)
+
+### QS2: Apply opinionated defaults
+
+Use these defaults for all configuration not asked in QS1:
+
+| Setting | Quick Start Default |
+|---------|-------------------|
+| Agents enabled | sr-architect, sr-developer, sr-reviewer, sr-product-manager |
+| Git mode | Derived from QS_GIT_ACCESS |
+| CLAUDE.md template | `templates/CLAUDE-quickstart.md` |
+| OpenSpec enabled | Yes if `openspec` CLI is detected in PATH, No otherwise |
+| Telemetry | Not configured (deferred to PRD-002) |
+| Backlog provider | None (user can configure later with `/setup --advanced`) |
+
+Detect whether this is an existing codebase or new project:
+- **Existing codebase**: `package.json`, `Gemfile`, `pyproject.toml`, `go.mod`, or `pom.xml` found in the repo root
+- **New project**: none of the above found
+
+Store as `QS_IS_EXISTING_CODEBASE=true/false`.
+
+### QS3: Generate files
+
+Generate files using the Quick Start defaults.
+
+**1. CLAUDE.md**
+
+Read `setup-templates/claude-md/CLAUDE-quickstart.md` (or fall back to `setup-templates/claude-md/default.md` if quickstart template is not found).
+
+Replace placeholders:
+- `{{PROJECT_NAME}}` → derive from directory name or README.md first heading
+- `{{PROJECT_DESCRIPTION}}` → `QS_PROJECT_DESCRIPTION`
+- `{{TARGET_USERS}}` → `QS_TARGET_USERS`
+- `{{GIT_ACCESS}}` → `QS_GIT_ACCESS`
+
+Write to `CLAUDE.md` in the repo root. If `CLAUDE.md` already exists, ask:
+> "CLAUDE.md already exists. Overwrite? [Y/n]"
+Skip if user says no.
+
+**2. Agent files**
+
+For each default agent (sr-architect, sr-developer, sr-reviewer, sr-product-manager), read the template from `setup-templates/agents/<name>.md` and generate the adapted agent file at `.claude/agents/<name>.md`.
+
+Fill placeholders with best-effort values from the limited context available:
+- `{{PROJECT_NAME}}` → directory name or README first heading
+- `{{PROJECT_DESCRIPTION}}` → `QS_PROJECT_DESCRIPTION`
+- `{{TARGET_USERS}}` → `QS_TARGET_USERS`
+- `{{GIT_ACCESS}}` → `QS_GIT_ACCESS`
+- `{{ARCHITECTURE_DIAGRAM}}` → "(Quick Start — run `/setup --advanced` for full architecture analysis)"
+- `{{TECH_EXPERTISE}}` → "(Quick Start — run `/setup --advanced` for codebase-specific expertise)"
+- `{{LAYER_TAGS}}` → detect from package.json / Gemfile / go.mod if present; otherwise leave empty
+- All other placeholders → "(not configured — run `/setup --advanced`)"
+
+Create memory directories: `.claude/agent-memory/sr-<name>/`
+
+**3. Command files**
+
+Copy core commands from `setup-templates/commands/sr/` to `.claude/commands/sr/`:
+- `implement.md`
+- `batch-implement.md`
+- `propose-spec.md`
+- `health-check.md`
+- `compat-check.md`
+- `why.md`
+
+Do NOT copy `product-backlog.md` or `update-product-driven-backlog.md` (no backlog provider configured).
+
+**4. Cleanup**
+
+Remove `setup-templates/` from `.claude/` (same as full wizard cleanup in Phase 5).
+
+Remove `commands/setup.md` from `.claude/commands/` if it was copied there by the installer.
+
+### QS4: First Task Prompt
+
+After generating all files, display the setup complete message.
+
+Then, based on `QS_IS_EXISTING_CODEBASE`:
+- **Existing codebase** (`true`): recommend `/sr:health-check`
+- **New project** (`false`): recommend `/sr:product-backlog`
+
+```
+✅ Setup complete.
+
+Try your first command:
+  > /sr:product-backlog
+```
+
+(Replace `/sr:product-backlog` with `/sr:health-check` for existing codebases.)
+
+Then stop. Do not execute Phase 1.
+
+---
+
 ## Phase 1: Codebase Analysis
 
 Analyze the repository to understand its architecture, stack, and conventions.
@@ -379,6 +502,8 @@ Which agents do you want to install?
 | sr-architect | Design features, create implementation plans | Sonnet | Yes |
 | sr-developer (full-stack) | Implement features across all layers | Sonnet | Yes |
 | sr-reviewer | CI/CD quality gate, fix issues | Sonnet | Yes |
+| sr-test-writer | Generate unit, integration, and edge-case tests after implementation | Sonnet | Yes |
+| sr-security-reviewer | Scan for secrets, OWASP vulnerabilities, hardcoded credentials | Sonnet | Yes |
 | sr-product-manager | Product discovery, ideation, VPC evaluation | Opus | Recommended |
 | sr-product-analyst | Read-only backlog analysis | Haiku | Recommended |
 | sr-backend-developer | Specialized backend implementation | Sonnet | If backend layer exists |
@@ -615,6 +740,8 @@ For each selected agent, read the template and generate the adapted version:
 - `setup-templates/agents/sr-architect.md` → `.claude/agents/sr-architect.md`
 - `setup-templates/agents/sr-developer.md` → `.claude/agents/sr-developer.md`
 - `setup-templates/agents/sr-reviewer.md` → `.claude/agents/sr-reviewer.md`
+- `setup-templates/agents/sr-test-writer.md` → `.claude/agents/sr-test-writer.md`
+- `setup-templates/agents/sr-security-reviewer.md` → `.claude/agents/sr-security-reviewer.md`
 - `setup-templates/agents/sr-product-manager.md` → `.claude/agents/sr-product-manager.md`
 - `setup-templates/agents/sr-product-analyst.md` → `.claude/agents/sr-product-analyst.md`
 - `setup-templates/agents/sr-backend-developer.md` → `.claude/agents/sr-backend-developer.md` (if backend layer)
@@ -636,6 +763,9 @@ When generating each agent:
    - `{{KEY_FILE_PATHS}}` → important file paths detected in Phase 1
    - `{{WARNINGS}}` → project-specific warnings (from existing CLAUDE.md or detected)
    - `{{MEMORY_PATH}}` → agent memory directory path (e.g., `.claude/agent-memory/sr-<agent-name>/`)
+   - `{{TECH_EXPERTISE}}` → detected languages, frameworks, and test frameworks from Phase 1
+   - `{{LAYER_CLAUDE_MD_PATHS}}` → comma-separated paths to per-layer rules files (e.g., `.claude/rules/backend.md`, `.claude/rules/frontend.md`)
+   - `{{SECURITY_EXEMPTIONS_PATH}}` → `.claude/security-exemptions.yaml`
 3. Write the final file
 
 ### 4.2 Generate personas
@@ -819,6 +949,8 @@ Display the complete installation summary:
 | sr-architect | .claude/agents/sr-architect.md | Sonnet |
 | sr-developer | .claude/agents/sr-developer.md | Sonnet |
 | sr-reviewer | .claude/agents/sr-reviewer.md | Sonnet |
+| sr-test-writer | .claude/agents/sr-test-writer.md | Sonnet |
+| sr-security-reviewer | .claude/agents/sr-security-reviewer.md | Sonnet |
 | sr-product-manager | .claude/agents/sr-product-manager.md | Opus |
 
 ### Personas Created
@@ -869,3 +1001,25 @@ Note: Only commands selected during setup are shown. Backlog commands are exclud
 - `/sr:product-backlog` — see prioritized feature ideas
 - `/sr:update-product-driven-backlog` — discover new features using VPC
 ```
+
+## First Task Prompt (Advanced Mode)
+
+After displaying the setup complete summary above, detect the project type and output:
+
+**New project** (no `package.json`, `Gemfile`, `pyproject.toml`, `go.mod`, or `pom.xml` in root):
+```
+✅ Setup complete.
+
+Try your first spec:
+  > /sr:product-backlog
+```
+
+**Existing codebase** (one or more of the above files found in root):
+```
+✅ Setup complete.
+
+Try your first spec:
+  > /sr:health-check
+```
+
+Then stop.

package/install.sh

@@ -149,6 +149,12 @@ generate_manifest() {
     artifacts_json="${artifacts_json}
     \"commands/setup.md\": \"${setup_checksum}\""
 
+    # Include commands/doctor.md
+    local doctor_checksum
+    doctor_checksum="sha256:$(shasum -a 256 "$SCRIPT_DIR/commands/doctor.md" | awk '{print $1}')"
+    artifacts_json="${artifacts_json},
+    \"commands/doctor.md\": \"${doctor_checksum}\""
+
     cat > "$REPO_ROOT/.specrails-manifest.json" << EOF
 {
   "version": "${version}",
@@ -186,36 +192,33 @@ if command -v claude &> /dev/null; then
 else
     fail "Claude Code CLI not found."
     echo ""
-    echo "    Install it with: npm install -g @anthropic-ai/claude-code"
-    echo "    Or see: https://docs.anthropic.com/en/docs/claude-code"
+    echo "    Install it: https://claude.ai/download"
+    exit 1
+fi
+
+# 1.3 API key
+if claude config list 2>/dev/null | grep -q "api_key" || [[ -n "${ANTHROPIC_API_KEY:-}" ]]; then
+    ok "Claude API key: configured"
+else
+    fail "No Claude API key configured."
+    echo ""
+    echo "    Set it:  claude config set api_key <your-key>"
+    echo "    Get one: https://console.anthropic.com/"
     exit 1
 fi
 
-# 1.3 npm
+# 1.4 npm
 if command -v npm &> /dev/null; then
     NPM_VERSION=$(npm --version 2>/dev/null)
     ok "npm: v$NPM_VERSION"
     HAS_NPM=true
 else
-    warn "npm not found. Required for OpenSpec CLI."
-    echo ""
-    if [ "$AUTO_YES" = true ]; then INSTALL_NPM="y"; else read -p "    Install npm via nvm? (y/n): " INSTALL_NPM; fi
-    if [ "$INSTALL_NPM" = "y" ] || [ "$INSTALL_NPM" = "Y" ]; then
-        info "Installing nvm + node..."
-        curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
-        export NVM_DIR="$HOME/.nvm"
-        [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
-        nvm install --lts
-        nvm use --lts
-        ok "npm installed: v$(npm --version)"
-        HAS_NPM=true
-    else
-        warn "Skipping npm install. OpenSpec CLI will not be available."
-        HAS_NPM=false
-    fi
+    warn "npm not found. OpenSpec CLI will be unavailable."
+    echo "    Install npm: https://docs.npmjs.com/downloading-and-installing-node-js-and-npm"
+    HAS_NPM=false
 fi
 
-# 1.4 OpenSpec CLI
+# 1.5 OpenSpec CLI
 if command -v openspec &> /dev/null; then
     OPENSPEC_VERSION=$(openspec --version 2>/dev/null || echo "unknown")
     ok "OpenSpec CLI: $OPENSPEC_VERSION"
@@ -252,7 +255,7 @@ else
     fi
 fi
 
-# 1.5 GitHub CLI (optional)
+# 1.6 GitHub CLI (optional)
 if command -v gh &> /dev/null; then
     if gh auth status &> /dev/null; then
         ok "GitHub CLI: authenticated"
@@ -266,7 +269,7 @@ else
     HAS_GH=false
 fi
 
-# 1.6 OSS detection (requires gh auth; degrades gracefully)
+# 1.7 OSS detection (requires gh auth; degrades gracefully)
 IS_OSS=false
 HAS_PUBLIC_REPO=false
 HAS_CI=false
@@ -289,7 +292,7 @@ if [ "$HAS_GH" = true ]; then
     fi
 fi
 
-# 1.7 JIRA CLI (optional)
+# 1.8 JIRA CLI (optional)
 if command -v jira &> /dev/null; then
     ok "JIRA CLI: found"
     HAS_JIRA=true
@@ -362,6 +365,16 @@ mkdir -p "$REPO_ROOT/.claude/agent-memory/explanations"
 cp "$SCRIPT_DIR/commands/setup.md" "$REPO_ROOT/.claude/commands/setup.md"
 ok "Installed /setup command"
 
+# Copy the /doctor command
+cp "$SCRIPT_DIR/commands/doctor.md" "$REPO_ROOT/.claude/commands/doctor.md"
+ok "Installed /doctor command"
+
+# Install bin/doctor.sh for standalone use
+mkdir -p "$REPO_ROOT/.specrails/bin"
+cp "$SCRIPT_DIR/bin/doctor.sh" "$REPO_ROOT/.specrails/bin/doctor.sh"
+chmod +x "$REPO_ROOT/.specrails/bin/doctor.sh"
+ok "Installed specrails doctor (bin/doctor.sh)"
+
 # Copy templates
 cp -r "$SCRIPT_DIR/templates/"* "$REPO_ROOT/.claude/setup-templates/"
 ok "Installed setup templates"

package/integration-contract.json

@@ -0,0 +1,28 @@
+{
+  "schemaVersion": "1.0",
+  "coreVersion": "1.0.1",
+  "minimumHubVersion": "1.3.0",
+  "cli": {
+    "initArgs": ["init", "--yes"],
+    "updateArgs": ["update"]
+  },
+  "checkpoints": [
+    "base_install",
+    "repo_analysis",
+    "stack_conventions",
+    "product_discovery",
+    "agent_generation",
+    "command_config",
+    "final_verification"
+  ],
+  "commands": [
+    "implement",
+    "batch-implement",
+    "why",
+    "product-backlog",
+    "update-product-driven-backlog",
+    "refactor-recommender",
+    "health-check",
+    "compat-check"
+  ]
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "specrails-core",
-  "version": "0.7.1",
-  "description": "Agent Workflow System installer for Claude Code",
+  "version": "1.1.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"
   },
@@ -13,7 +13,8 @@
     "prompts/",
     ".claude/skills/",
     "commands/",
-    "VERSION"
+    "VERSION",
+    "integration-contract.json"
   ],
   "engines": {
     "node": ">=18.0.0"
@@ -27,8 +28,27 @@
     "claude-code",
     "ai-agents",
     "workflow",
-    "developer-tools"
+    "developer-tools",
+    "anthropic",
+    "llm",
+    "ai",
+    "automation",
+    "productivity",
+    "specrails",
+    "openspec",
+    "code-generation",
+    "product-management",
+    "vibe-coding",
+    "agents",
+    "multi-agent",
+    "software-engineering",
+    "devtools",
+    "ai-workflow"
   ],
+  "homepage": "https://github.com/fjpulidop/specrails-core#readme",
+  "bugs": {
+    "url": "https://github.com/fjpulidop/specrails-core/issues"
+  },
   "license": "MIT",
   "author": "fjpulidop"
 }

package/templates/agents/sr-doc-sync.md

@@ -1,22 +1,22 @@
 ---
 name: sr-doc-sync
-description: "Use this agent after tests are written to automatically update documentation — changelog entries, README updates, and API docs — keeping docs in sync with code changes. Runs as Phase 3d in the implement pipeline.
+description: "Use this agent after tests are written to detect documentation drift and update docs — changelog entries, README updates, and API docs — keeping docs in sync with code changes. Runs as Phase 3d in the implement pipeline.
 
 Examples:
 
 - Example 1:
   user: (orchestrator) Tests complete. Update docs for the implemented files.
-  assistant: \"Launching the doc-sync agent to update documentation for the implemented code.\"
+  assistant: \"Launching the doc-sync agent to detect drift and update documentation for the implemented code.\"
 
 - Example 2:
   user: (orchestrator) Implementation and tests done. Sync docs.
-  assistant: \"I'll use the doc-sync agent to generate changelog entries and update docs.\""
+  assistant: \"I'll use the doc-sync agent to detect drift, generate changelog entries, and update docs.\""
 model: sonnet
 color: yellow
 memory: project
 ---
 
-You are a documentation specialist. Your only job is to keep documentation in sync with code — you never modify implementation files or test files.
+You are a documentation specialist. Your only job is to detect documentation drift and keep docs in sync with code — you never modify implementation files or test files.
 
 ## Your Identity & Expertise
 
@@ -27,7 +27,13 @@ You write documentation that is accurate, concise, and consistent with the proje
 
 ## Your Mission
 
-Detect the project's existing documentation conventions and generate matching updates for newly implemented code. You update changelogs, README files, and API docs to reflect the changes described in IMPLEMENTED_FILES_LIST and TASK_DESCRIPTION. You never run code — you read and write documentation files only.
+Detect documentation drift between the implemented code and the existing docs, then generate matching updates. You:
+1. Compare function signatures/exports against existing docs to find drift
+2. Classify drift by severity (critical for API-facing surface, warning for internal)
+3. Propose targeted doc patches for each drift item
+4. Update changelogs, README files, and API docs to resolve all detected drift
+
+You never run code — you read and write documentation files only.
 
 ## What You Receive
 
@@ -37,6 +43,53 @@ The orchestrator injects these inputs into your invocation prompt:
 - **TASK_DESCRIPTION**: the original task or feature description that drove the implementation. Use this as the basis for changelog entries and summary text.
 - Layer conventions at `{{LAYER_CLAUDE_MD_PATHS}}`: read these before generating docs to understand project-specific patterns.
 
+## Drift Detection Protocol
+
+Before generating any documentation, analyze each file in IMPLEMENTED_FILES_LIST for documentation drift. Drift is the gap between what the code exposes and what the docs describe.
+
+### Step 1: Extract code signatures
+
+For each file in IMPLEMENTED_FILES_LIST, read the file and extract:
+
+| Language | What to extract |
+|----------|----------------|
+| TypeScript/JavaScript | Exported functions, classes, interfaces, constants, type aliases |
+| Python | Module-level functions, classes, and constants marked `__all__` or without leading `_` |
+| Ruby | Public methods, module-level constants, public class definitions |
+| Go | Exported identifiers (capitalized functions, types, variables) |
+| Other | Any symbol that is part of the module's public API |
+
+For each extracted signature, note:
+- **Name**: the identifier name
+- **Signature**: parameter types and return type (if typed), or parameter names (if not)
+- **Visibility**: `api-facing` if exported from a top-level index file, REST endpoint, or public interface; `internal` otherwise
+
+### Step 2: Locate existing documentation
+
+For each extracted signature, search for existing documentation in this order:
+1. `docs/api/` — look for `.md` files matching the module or class name
+2. `docs/` — look for any `.md` file with matching content
+3. Root `README.md` — look for the identifier in the API or usage sections
+4. Inline docstrings or JSDoc comments in the source file itself
+
+### Step 3: Classify drift
+
+For each extracted signature, classify the drift state:
+
+| Drift Type | Condition | Severity |
+|------------|-----------|----------|
+| `undocumented` | Exported symbol has no matching doc entry | Critical if `api-facing`, Warning if `internal` |
+| `stale-signature` | Doc entry exists but signature has changed (param names, types, return type) | Critical if `api-facing`, Warning if `internal` |
+| `stale-description` | Doc entry exists but description references removed behavior or old name | Warning (regardless of visibility) |
+| `phantom` | Doc entry exists for a symbol that no longer exists in the code | Critical if the phantom was `api-facing`, Warning if `internal` |
+| `current` | Doc entry exists and matches the current signature | No action needed |
+
+### Step 4: Build drift report
+
+Collect all non-`current` drift items. This report drives which documentation updates you will generate in the next phase.
+
+If no drift is found (all signatures are `current`): proceed directly to "Documentation Generation" for changelog-only updates, then emit `DOC_SYNC_STATUS: DONE` with a note that no structural drift was detected.
+
 ## Doc Style Detection Protocol
 
 Before writing any documentation, detect the project's existing conventions by reading the following (stop at the first match for each category):
@@ -103,10 +156,12 @@ If no `docs/` directory exists: skip and note the reason in output.
 
 1. **Never modify implementation files.** Read them to understand changes, but write only to documentation files.
 2. **Never modify test files.** Documentation only.
-3. **Match existing style exactly.** Do not introduce new heading levels, list styles, or formatting not already present in the file.
-4. **Skip gracefully.** If there are no user-visible changes to document (e.g., pure refactors, internal changes), output `DOC_SYNC_STATUS: SKIPPED` with a clear reason. Do not force documentation where none is needed.
-5. **Never ask for clarification.** Complete documentation generation with available information.
-6. **Always emit the `DOC_SYNC_STATUS:` line as the very last line of output.** Nothing may follow it.
+3. **Always run drift detection first.** Classify all drift before writing any documentation.
+4. **Critical drift must be resolved.** All `Critical` drift items (undocumented or phantom `api-facing` symbols) must have a corresponding doc update. Do not skip Critical items.
+5. **Match existing style exactly.** Do not introduce new heading levels, list styles, or formatting not already present in the file.
+6. **Skip gracefully.** If there are no user-visible changes to document (e.g., pure refactors, internal changes) AND no drift detected, output `DOC_SYNC_STATUS: SKIPPED` with a clear reason. Do not force documentation where none is needed.
+7. **Never ask for clarification.** Complete documentation generation with available information.
+8. **Always emit the `DOC_SYNC_STATUS:` line as the very last line of output.** Nothing may follow it.
 
 ## Output Format
 
@@ -115,6 +170,16 @@ After writing all documentation updates, produce this report:
 ```
 ## Doc Sync Results
 
+### Drift Analysis
+| Symbol | File | Drift Type | Severity | Resolution |
+|--------|------|-----------|----------|-----------|
+| <name> | <source file> | undocumented | Critical | Added to <doc file> |
+| <name> | <source file> | stale-signature | Warning | Updated in <doc file> |
+| <name> | <source file> | phantom | Critical | Removed from <doc file> |
+(rows or "No drift detected")
+
+**Drift summary**: X Critical, Y Warning
+
 ### Changelog
 - File: <path or "none found">
 - Action: <updated | skipped — reason>
@@ -139,7 +204,7 @@ DOC_SYNC_STATUS: DONE
 ```
 
 Set `DOC_SYNC_STATUS:` as follows:
-- `DONE` — one or more documentation files written successfully
+- `DONE` — drift analysis complete and any needed documentation written
 - `SKIPPED` — no documentation files found or no user-visible changes to document
 - `FAILED` — an unrecoverable error occurred
 
@@ -161,6 +226,8 @@ What to save:
 - README structure and section names discovered
 - API doc location and format discovered
 - Files or sections that are always skipped for this repo
+- Drift patterns discovered: which directories contain `api-facing` vs `internal` symbols
+- Top-level index file path (e.g., `src/index.ts`, `lib/index.rb`) for visibility classification
 
 ## MEMORY.md
 

package/templates/claude-md/CLAUDE-quickstart.md

@@ -0,0 +1,58 @@
+# {{PROJECT_NAME}}
+
+> {{PROJECT_DESCRIPTION}}
+
+**Target users:** {{TARGET_USERS}}
+
+---
+
+## Agent Team
+
+This project uses the specrails agent workflow. The following agents are active:
+
+- **CEO** — product direction and goal-setting
+- **CTO** — architecture decisions and technical standards
+- **Tech Lead** — implementation coordination
+- **Founding Engineer** — full-stack development
+
+Git access level: **{{GIT_ACCESS}}**
+
+---
+
+## Working with the Agent Team
+
+Start with a product backlog to discover what to build first:
+
+```
+/sr:product-backlog
+```
+
+Then implement features using the full pipeline:
+
+```
+/sr:implement #1 #2 #3
+```
+
+---
+
+## Health Check
+
+If something seems off, run:
+
+```
+specrails doctor
+```
+
+Or inside Claude Code:
+
+```
+/doctor
+```
+
+---
+
+## Engineering Standards
+
+- Write specs before code (OpenSpec for behavioral specs)
+- Conventional commits on all git commits
+- All PRs require review before merge