specrails-hub 1.27.0 → 1.28.0

package/.claude/commands/specrails/auto-propose-backlog-specs.md

@@ -0,0 +1,214 @@
+---
+name: "Update Product-Driven Backlog"
+description: "Generate new feature ideas through product discovery, create Local Tickets"
+category: Workflow
+tags: [workflow, explore, priorities, backlog, product-discovery]
+model: opus
+---
+
+Analyze the project from a **product perspective** to generate new feature ideas. Syncs results to Local Tickets. Use `/specrails:get-backlog-specs` to view current ideas.
+
+**Input:** $ARGUMENTS (optional: comma-separated areas to focus on. If empty, analyze all areas.)
+
+**IMPORTANT: This command only creates tickets.** You may read files and search code to understand current capabilities, but you must NEVER write application code.
+
+---
+
+## Areas
+
+| Area | Description | Key Files |
+|------|-------------|-----------|
+| backend | Express server, API routes, SQLite, WebSocket | server/ |
+| frontend | React dashboard, components, pages | client/src/ |
+| cli | CLI bridge commands | cli/ |
+| analytics | Job cost/duration/token metrics | server/analytics.ts, client/src/pages/AnalyticsPage.tsx |
+| tickets | Local ticket management, kanban views | .specrails/local-tickets.json, client/src/components/ |
+| pipeline | AI pipeline phases (Architect/Developer/Reviewer) | server/queue-manager.ts |
+
+---
+
+## Execution
+
+Launch a **single** explorer subagent (`subagent_type: Explore`, `run_in_background: true`) for product discovery.
+
+The Explore agent receives this prompt:
+
+> You are a product strategist analyzing the **specrails-hub** project to generate new feature ideas using the **Value Proposition Canvas** framework.
+>
+> **Your goal:** For each area, propose 2-4 new features that would significantly improve the user experience. Every feature MUST be evaluated against the project's personas.
+>
+> **Areas to analyze:** {all areas or filtered by user input}
+>
+> ### Step 0: Read Personas
+>
+> **Before anything else**, read all persona files:
+> - Read `.claude/agents/personas/the-multi-project-developer.md`
+> - Read `.claude/agents/personas/the-solo-dev.md`
+> - Read `.claude/agents/personas/the-tech-lead.md`
+> - Read `.claude/agents/personas/the-maintainer.md`
+>
+> These contain full Value Proposition Canvas profiles (jobs, pains, gains).
+>
+> ### Research steps
+>
+> 1. **Understand current capabilities** — Read codebase structure
+> 2. **Check existing backlog** — Avoid duplicating existing issues
+> 3. **Think through each persona's day** — For each area:
+>    - What does each persona need here?
+>    - What would a competitive tool offer?
+>    - What data is available but not surfaced?
+>
+> 4. **For each idea, produce a VPC evaluation:**
+>    - **Feature name** (short, descriptive)
+>    - **User story** ("As a [user type], I want to [action] so that [benefit]")
+>    - **Feature description** (2-3 sentences)
+>    - **VPC Fit** per persona: Jobs, Pains relieved, Gains created, Score (0-5)
+>    - **Total Persona Score**: sum of all persona scores / 20
+>    - **Effort** (High/Medium/Low)
+>    - **Inspiration** (competitor or product pattern)
+>    - **Prerequisites**
+>    - **Area**
+
+---
+
+## Assembly — Backlog Sync
+
+After the Explore agent completes:
+
+1. **Display** results to the user.
+
+2. Read `.claude/backlog-config.json` and extract:
+   - `BACKLOG_PROVIDER` (`local`, `github`, `jira`, or `none`)
+   - `BACKLOG_WRITE` (from `write_access`)
+
+### If `BACKLOG_WRITE=false` — Display only (no sync)
+
+Display all proposed features in a structured format. Do NOT create any tickets.
+
+```
+## Product Discovery Results (not synced)
+
+Backlog access is set to **read-only**. The following features were discovered
+but NOT created. Create them manually if desired.
+
+### Feature 1: {name}
+- **Area:** {area}
+- **Persona Fit:** Alex: X/5, Sam: X/5, Morgan: X/5, Kai: X/5
+- **Effort:** {level}
+- **User Story:** As a {user}, I want to {action} so that {benefit}
+- **Description:** {2-3 sentences}
+```
+
+### If provider=local — Sync to Local Tickets
+
+Local tickets are always read-write.
+
+3. **Fetch existing local tickets** to avoid duplicates:
+   Read `.specrails/local-tickets.json`. Parse the `tickets` map and return all entries regardless of status.
+   Collect all ticket titles into a duplicate-check set.
+
+4. **Initialize labels** (idempotent):
+   No label initialization required. Local tickets use freeform label strings. Standard label conventions: `area:frontend`, `area:backend`, `area:api`, `effort:low`, `effort:medium`, `effort:high`.
+
+5. **For each proposed feature, create a local ticket** (skip if title matches an existing ticket):
+   Write to `.specrails/local-tickets.json` using the advisory locking protocol:
+   acquire lock → read file → set `id = next_id`, increment `next_id`, set all ticket fields, set `created_at` and `updated_at` to now, bump `revision`, update `last_updated` → write → release lock.
+
+   Set the following fields:
+   - `title`: Feature name
+   - `description`: Full VPC body markdown
+   - `status`: `"todo"`
+   - `priority`: Map effort — Low → `"high"`, Medium → `"medium"`, High → `"low"`
+   - `labels`: `["product-driven-backlog", "area:{area}"]`
+   - `metadata.vpc_scores`: Per-persona scores from VPC evaluation
+   - `metadata.effort_level`: `"High"`, `"Medium"`, or `"Low"`
+   - `metadata.user_story`: The user story text
+   - `metadata.area`: The area name
+   - `prerequisites`: Array of ticket IDs for dependencies (empty if none)
+   - `source`: `"get-backlog-specs"`
+   - `created_by`: `"sr-product-manager"`
+
+6. **Report** sync results:
+   ```
+   Product discovery complete:
+   - Created: {N} new feature ideas as local tickets
+   - Skipped: {N} duplicates (already exist)
+   ```
+
+### If provider=github and BACKLOG_WRITE=true — Sync to GitHub Issues
+
+3. Fetch existing product-driven backlog items:
+   ```bash
+   gh issue list --label "product-driven-backlog" --state open --limit 100 --json number,title
+   ```
+
+4. Initialize labels:
+   ```bash
+   gh label create "product-driven-backlog" --color "6E40C9" --force
+   ```
+
+5. For each proposed feature, create a GitHub Issue (skip duplicates):
+   ```bash
+   gh issue create --title "{feature name}" --label "product-driven-backlog,area:{area}" --body "..."
+   ```
+
+6. Report sync results.
+
+### If provider=jira and BACKLOG_WRITE=true — Sync to JIRA
+
+Read `.claude/backlog-config.json` for JIRA config, authenticate, and create Story tickets using the JIRA REST API.
+
+### VPC Body Format
+
+The description/body for each ticket:
+
+```markdown
+> **This is a product feature idea.** Generated through VPC-based product discovery.
+
+## Overview
+
+| Field | Value |
+|-------|-------|
+| **Area** | {Area} |
+| **Persona Fit** | Alex: X/5, Sam: X/5, Morgan: X/5, Kai: X/5 |
+| **Effort** | {High/Medium/Low} — {justification} |
+| **Inspiration** | {source or "Original idea"} |
+| **Prerequisites** | {list or "None"} |
+
+## User Story
+
+As a **{user type}**, I want to **{action}** so that **{benefit}**.
+
+## Feature Description
+
+{2-3 sentence description}
+
+## Value Proposition Canvas
+
+### "Alex" — The Multi-Project Developer (X/5)
+- **Jobs addressed**: {list}
+- **Pains relieved**: {list with severity}
+- **Gains created**: {list with impact}
+
+### "Sam" — The Solo Dev (X/5)
+- **Jobs addressed**: {list}
+- **Pains relieved**: {list with severity}
+- **Gains created**: {list with impact}
+
+### "Morgan" — The Tech Lead (X/5)
+- **Jobs addressed**: {list}
+- **Pains relieved**: {list with severity}
+- **Gains created**: {list with impact}
+
+### "Kai" — The Maintainer (X/5)
+- **Jobs addressed**: {list}
+- **Pains relieved**: {list with severity}
+- **Gains created**: {list with impact}
+
+## Implementation Notes
+
+{Brief notes on existing infrastructure and what needs to be built}
+
+---
+_Auto-generated by `/specrails:auto-propose-backlog-specs` on {DATE}_
+```

package/.claude/commands/specrails/batch-implement.md

@@ -0,0 +1,282 @@
+# Batch Implementation Orchestrator
+
+Macro-orchestrator above `/specrails:implement`. Accepts a set of feature references, computes a dependency-aware wave execution plan, invokes `/specrails:implement` per wave, and produces a batch-level progress dashboard and final report. All per-feature pipeline work (sr-architect, sr-developer, sr-reviewer, git, CI) is fully delegated to `/specrails:implement`.
+
+**MANDATORY: Always follow this pipeline exactly as written. NEVER skip, shortcut, or "optimize away" any phase — even if the batch seems small enough to handle directly. The orchestrator MUST compute waves, confirm with the user, and invoke `/specrails:implement` per wave as specified. Do NOT implement any feature yourself in the main conversation. No exceptions.**
+
+**Input:** $ARGUMENTS — one or more feature references with optional flags:
+
+- **Feature refs**: `#85 #71 #63` (GitHub issue numbers) — required, at least two
+- **`--deps "<spec>"`**: inline dependency spec, e.g. `"#71 -> #85, #63 -> #85"` (meaning #71 and #63 must complete before #85)
+- **`--concurrency N`**: max features running in parallel across waves (default: 3)
+- **`--wave-size N`**: max features per wave regardless of concurrency (default: unlimited)
+- **`--dry-run` / `--preview`**: passed through to each `/specrails:implement` invocation; no git or backlog operations will run
+
+**IMPORTANT:** Before running, ensure Read/Write/Bash/Glob/Grep permissions are set to "allow" — background agents cannot request permissions interactively.
+
+---
+
+## Phase 0: Parse Input
+
+### Step 1: Extract feature refs
+
+Scan `$ARGUMENTS` for issue/ticket references (e.g. `#85`, `#71`). Collect into `FEATURE_REFS` list. If fewer than 2 refs are found, stop and print:
+
+```
+[batch-implement] Error: at least 2 feature refs are required. For a single feature, use /specrails:implement directly.
+```
+
+### Step 2: Extract flags
+
+Scan `$ARGUMENTS` for control flags:
+
+- If `--dry-run` or `--preview` is present: set `DRY_RUN=true`. This flag is forwarded to every `/specrails:implement` call.
+- If `--deps "<spec>"` is present: capture the quoted string as `DEPS_SPEC`. Strip from arguments.
+- If `--concurrency N` is present: set `CONCURRENCY=N` (integer ≥ 1). Default: 3.
+- If `--wave-size N` is present: set `WAVE_SIZE=N` (integer ≥ 1). Default: unlimited (no per-wave cap).
+
+**If `DRY_RUN=true`**, print:
+```
+[dry-run] Preview mode active — /specrails:implement will be called with --dry-run for each wave.
+```
+
+### Step 3: Fetch issue titles
+
+For each ref in `FEATURE_REFS`, fetch the issue title to use in progress output:
+
+```bash
+Read `.specrails/local-tickets.json`. Parse JSON and return the full ticket object at `tickets["{id}"]`, or an error if not found. --json number,title
+```
+
+Store as `FEATURE_TITLES` map: `{ref: title}`.
+
+---
+
+## Phase 1: Wave Planning
+
+### Step 1: Parse dependency graph
+
+Build a directed graph `DEP_GRAPH` where an edge `A -> B` means "A must complete before B starts".
+
+Parse `DEPS_SPEC` (if provided) by splitting on `,` and parsing each token as `<ref> -> <ref>`.
+
+```
+for each token in DEPS_SPEC.split(","):
+    left, right = token.split("->")
+    DEP_GRAPH.add_edge(left.strip(), right.strip())
+```
+
+All refs in `FEATURE_REFS` that appear in no edge are treated as independent (no dependencies).
+
+### Step 2: Detect circular dependencies
+
+Run cycle detection on `DEP_GRAPH`:
+
+```
+visited = {}
+rec_stack = {}
+
+function has_cycle(node):
+    visited[node] = true
+    rec_stack[node] = true
+    for neighbor in DEP_GRAPH.neighbors(node):
+        if not visited[neighbor] and has_cycle(neighbor):
+            return true
+        elif rec_stack[neighbor]:
+            return true
+    rec_stack[node] = false
+    return false
+
+CYCLES = [node for node in FEATURE_REFS if not visited[node] and has_cycle(node)]
+```
+
+If `CYCLES` is non-empty: stop and print:
+
+```
+[batch-implement] Error: circular dependency detected.
+Cycle involves: <ref-list>
+Fix the --deps spec and re-run.
+```
+
+### Step 3: Compute waves via Kahn's algorithm
+
+```
+in_degree = {ref: 0 for ref in FEATURE_REFS}
+for each edge (A -> B) in DEP_GRAPH:
+    in_degree[B] += 1
+
+WAVES = []
+ready = [ref for ref in FEATURE_REFS if in_degree[ref] == 0]
+sort ready alphabetically (stable ordering)
+
+while ready is non-empty:
+    wave = ready[:WAVE_SIZE]  # cap at WAVE_SIZE if set; else take all
+    remaining = ready[WAVE_SIZE:] if WAVE_SIZE else []
+    WAVES.append(wave)
+    for ref in wave:
+        for neighbor in DEP_GRAPH.neighbors(ref):
+            in_degree[neighbor] -= 1
+            if in_degree[neighbor] == 0:
+                remaining.append(neighbor)
+    sort remaining alphabetically
+    ready = remaining
+```
+
+Set `TOTAL_WAVES = len(WAVES)`.
+
+### Step 4: Print execution plan and ask for confirmation
+
+Print the wave execution plan:
+
+```
+## Batch Execution Plan
+
+Total features : <N>
+Total waves    : <TOTAL_WAVES>
+Max concurrency: <CONCURRENCY>
+Dry-run        : <yes / no>
+
+| Wave | Features | Depends On |
+|------|----------|------------|
+| 1    | #85, #71 | —          |
+| 2    | #63      | #85, #71   |
+
+Dependency graph:
+  #71 -> #63
+  #85 -> #63
+
+Proceed? (yes / no / edit-deps)
+```
+
+Wait for user confirmation.
+
+- **`yes`**: proceed to Phase 2.
+- **`no`**: stop. Print `[batch-implement] Aborted by user.`
+- **`edit-deps`**: ask the user to provide a corrected `--deps` spec, re-run Phase 1 from Step 1.
+
+---
+
+## Phase 2: Wave Execution Loop
+
+Execute waves sequentially. Within each wave, invoke `/specrails:implement` for all features in parallel (up to `CONCURRENCY` at a time).
+
+### Progress Dashboard
+
+Before starting each wave, print the current dashboard state:
+
+```
+## Batch Progress
+
+| # | Feature | Title | Wave | Status | Notes |
+|---|---------|-------|------|--------|-------|
+| 1 | #85     | <title> | 1  | done   |       |
+| 2 | #71     | <title> | 1  | done   |       |
+| 3 | #63     | <title> | 2  | running|       |
+| 4 | #42     | <title> | 2  | blocked| depends on #63 |
+| 5 | #17     | <title> | 3  | pending|       |
+```
+
+Status values:
+- `pending` — not yet started
+- `running` — `/specrails:implement` invocation is active
+- `done` — `/specrails:implement` completed successfully
+- `failed` — `/specrails:implement` exited with an error
+- `blocked` — a dependency failed; this feature will not run
+
+### Wave invocation
+
+For each wave `W`:
+
+1. Print: `[wave W/TOTAL_WAVES] Starting — features: <ref-list>`
+2. For each feature batch of size ≤ `CONCURRENCY` within the wave:
+   - Invoke `/specrails:implement` with the feature refs and forwarded flags:
+     ```
+     /specrails:implement <ref1> <ref2> ... [--dry-run]
+     ```
+   - Run invocations in the batch in parallel (`run_in_background: true`).
+   - Wait for all in the batch to complete before starting the next batch.
+3. For each completed invocation, record outcome in `WAVE_RESULTS`:
+   - `{ref, wave, status: "done" | "failed", error_summary: "..." | null}`
+
+### Failure isolation
+
+After each wave completes:
+
+```
+FAILED_THIS_WAVE = [ref for ref in wave if WAVE_RESULTS[ref].status == "failed"]
+
+for each ref in FAILED_THIS_WAVE:
+    BLOCKED = all refs in DEP_GRAPH.descendants(ref)
+    for each blocked_ref in BLOCKED:
+        WAVE_RESULTS[blocked_ref] = {status: "blocked", reason: "depends on failed " + ref}
+        remove blocked_ref from all future waves
+```
+
+A failed feature blocks ONLY its transitive dependents. Features in other branches of the dependency graph continue unaffected.
+
+Print updated dashboard after each wave.
+
+### Wave completion gate
+
+Before starting wave W+1, confirm all features in wave W have status `done` or `blocked`. Never start a downstream wave while upstream features are still running.
+
+---
+
+## Phase 3: Batch Report
+
+After all waves complete (or all remaining features are blocked), print the final batch report.
+
+```
+## Batch Implementation Report
+
+Run completed: <ISO 8601 timestamp>
+Dry-run: <yes / no>
+
+### Summary
+
+| Metric | Count |
+|--------|-------|
+| Total features | N |
+| Succeeded | N |
+| Failed | N |
+| Blocked (dep failure) | N |
+
+### Per-Feature Results
+
+| # | Feature | Title | Wave | Status | Notes |
+|---|---------|-------|------|--------|-------|
+| 1 | #85     | <title> | 1  | done   |       |
+| 2 | #71     | <title> | 1  | failed | see /specrails:implement output |
+| 3 | #63     | <title> | 2  | blocked| depends on #71 |
+
+### Merge Conflicts
+
+[List any merge conflicts reported by /specrails:implement across all waves. If none: "No merge conflicts detected."]
+
+| Feature | File | Conflicting Region |
+|---------|------|--------------------|
+| #85     | src/utils/parser.ts | function parseQuery |
+
+### Next Steps
+
+[If all features succeeded:]
+All features implemented. Review open PRs and monitor CI.
+
+[If any features failed:]
+Re-run failed features individually:
+  /specrails:implement <failed-ref>
+  /specrails:implement <failed-ref>
+
+[If any features were blocked:]
+Once failed features are fixed, re-run blocked features:
+  /specrails:implement <blocked-ref> [--deps "..."]
+```
+
+---
+
+## Error Handling
+
+- If a `/specrails:implement` invocation fails: record failure, apply failure isolation, continue remaining waves
+- If GitHub CLI is unavailable (detected during issue title fetch): proceed without titles, show refs only
+- If `--deps` spec contains unknown refs: warn and continue — unknown refs are ignored in graph construction
+- Never block the entire batch on a single feature failure. Always produce a final report.

package/.claude/commands/specrails/compat-check.md

@@ -0,0 +1,132 @@
+---
+name: "Compatibility Impact Analyzer"
+description: "Snapshot the current API surface and detect breaking changes against a prior baseline. Generates a migration guide when breaking changes are found."
+category: Workflow
+tags: [workflow, compatibility, breaking-changes, migration]
+---
+
+Analyze the API surface of **specrails-hub** for backwards compatibility. Extracts the current contract surface (CLI flags, template placeholders, command names, argument flags, agent names, config keys), compares against a stored baseline, classifies each change by severity, and generates a migration guide when breaking changes are found.
+
+**Input:** `$ARGUMENTS` — optional flags:
+- `--diff` — compare current surface to most recent snapshot (default when snapshots exist)
+- `--snapshot` — capture current surface and save without diffing (default on first run)
+- `--since <date>` — diff against snapshot from this date (ISO format: YYYY-MM-DD)
+- `--propose <change-dir>` — diff proposed changes in `openspec/changes/<change-dir>/` against current surface
+- `--dry-run` — run all phases but skip saving the snapshot
+
+---
+
+## Phase 0: Argument Parsing
+
+Parse `$ARGUMENTS` to set runtime variables.
+
+**Variables to set:**
+
+- `MODE` — string, one of `"snapshot"`, `"diff"`, `"propose"`. Default: `"diff"` if `.claude/compat-snapshots/` contains any `.json` files; `"snapshot"` otherwise.
+- `COMPARE_DATE` — string (ISO date) or empty string. Default: `""` (use most recent snapshot).
+- `PROPOSE_DIR` — string or empty string. Default: `""`.
+- `DRY_RUN` — boolean. Default: `false`.
+
+**Parsing rules:**
+
+1. Scan `$ARGUMENTS` for `--snapshot`. If found, set `MODE=snapshot`.
+2. Scan for `--diff`. If found, set `MODE=diff`.
+3. Scan for `--since <date>`. If found, set `COMPARE_DATE=<date>` and (if `MODE` not already set to `snapshot`) set `MODE=diff`.
+4. Scan for `--propose <change-dir>`. If found, set `PROPOSE_DIR=<change-dir>` and `MODE=propose`.
+   - Verify `openspec/changes/<change-dir>/` exists. If not: print `Error: no change found at openspec/changes/<change-dir>/` and stop.
+5. Scan for `--dry-run`. If found, set `DRY_RUN=true`.
+6. Apply default-mode logic if `MODE` is not yet set: check whether `.claude/compat-snapshots/` exists and contains `.json` files. If yes: `MODE=diff`. If no: `MODE=snapshot`.
+
+**Verify prerequisites:**
+
+- Check whether `templates/` directory exists. If not: print `Error: templates/ not found — is this a specrails repo?` and stop.
+- Check whether `install.sh` exists. If not: set `INSTALLER_AVAILABLE=false`. Otherwise set `INSTALLER_AVAILABLE=true`.
+
+**Print active configuration:**
+
+```
+Mode: <MODE> | Compare date: <COMPARE_DATE or "latest"> | Dry-run: <true/false>
+```
+
+---
+
+## Phase 1: Extract Current Surface
+
+Read the codebase and build the surface snapshot.
+
+**Surface categories:** `installer_flags`, `template_placeholders`, `command_names`, `command_arguments`, `agent_names`, `config_keys`
+
+Build the surface object:
+
+```json
+{
+  "schema_version": "1",
+  "captured_at": "<ISO 8601 datetime>",
+  "git_sha": "<git rev-parse HEAD or 'unknown'>",
+  "git_branch": "<git rev-parse --abbrev-ref HEAD or 'unknown'>",
+  "surfaces": {
+    "installer_flags": [...],
+    "template_placeholders": [...],
+    "command_names": [...],
+    "command_arguments": [...],
+    "agent_names": [...],
+    "config_keys": [...]
+  }
+}
+```
+
+If `MODE=snapshot`: proceed directly to Phase 5.
+
+---
+
+## Phase 2: Load Baseline
+
+For `diff` mode: load most recent snapshot (or by `COMPARE_DATE`) from `.claude/compat-snapshots/`.
+For `propose` mode: load most recent snapshot + read `openspec/changes/<PROPOSE_DIR>/design.md`.
+
+---
+
+## Phase 3: Diff and Classify
+
+For each surface category, compute removed/added/changed elements and classify:
+- Category 1: Removal (BREAKING — MAJOR)
+- Category 2: Rename (BREAKING — MAJOR)
+- Category 3: Signature Change (BREAKING or MINOR)
+- Category 4: Behavioral Change (ADVISORY)
+
+---
+
+## Phase 4: Generate Report
+
+```
+## Compatibility Impact Report — specrails-hub
+Date: <ISO date> | Commit: <git_short_sha or "unknown">
+
+### Surface Snapshot
+| Category | Elements Found |
+|----------|---------------|
+| Installer flags | N |
+| Template placeholders | N |
+| Command names | N |
+| Command argument flags | N |
+| Agent names | N |
+| Config keys | N |
+
+### Breaking Changes (N found)
+[list or "None detected."]
+
+### Advisory Changes (N found)
+[list or "None detected."]
+```
+
+Include Migration Guide blocks for each breaking change.
+
+---
+
+## Phase 5: Save Snapshot
+
+If `DRY_RUN=true`: print `Snapshot not saved — dry-run mode`.
+
+Otherwise: save to `.claude/compat-snapshots/<YYYY-MM-DD>-<git_short_sha>.json`.
+
+Check `.gitignore` — suggest adding `.claude/compat-snapshots/` if missing.

package/.claude/commands/specrails/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 /specrails:get-backlog-specs 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.