specrails-core 1.7.2 → 2.0.0

package/docs/user-docs/getting-started-codex.md

@@ -0,0 +1,193 @@
+# Getting Started with SpecRails + Codex
+
+This guide gets you running SpecRails using OpenAI Codex as your AI agent. If you are using Claude Code instead, see the [standard installation guide](installation.md).
+
+> **Beta**: Codex support is available in SpecRails 1.x as a beta feature. Core Skills work out of the box. See [Codex vs Claude Code](codex-vs-claude-code.md) for what is and is not supported.
+
+---
+
+## Requirements
+
+| Tool | Version | Notes |
+|------|---------|-------|
+| **Node.js** | 18+ | Required for the installer |
+| **Codex CLI** | Latest | `npm i -g @openai/codex` |
+| **Git** | Any | Your project must be a git repository |
+
+Optional but recommended:
+
+| Tool | Why |
+|------|-----|
+| **GitHub CLI** (`gh`) | Automatic PR creation and Issue integration |
+
+### Install Codex CLI
+
+```bash
+npm i -g @openai/codex
+```
+
+Verify the install:
+
+```bash
+codex --version
+```
+
+You need an OpenAI account with Codex access. Sign in with:
+
+```bash
+codex auth login
+```
+
+---
+
+## Install SpecRails
+
+Run the installer from inside your project directory:
+
+```bash
+cd your-project
+npx specrails-core@latest init --root-dir .
+```
+
+The installer detects Codex CLI automatically and generates configuration in `.codex/` instead of `.claude/`.
+
+### Flags
+
+| Flag | Effect |
+|------|--------|
+| `--root-dir <path>` | Target directory (default: current directory) |
+| `--yes` / `-y` | Skip confirmation prompts |
+
+### What gets installed
+
+```
+your-project/
+├── AGENTS.md                          # SpecRails agent instructions for Codex
+└── .codex/
+    ├── skills/                        # Workflow skills (/sr:*, /opsx:*)
+    ├── agents/                        # Agent definitions (TOML)
+    ├── rules/                         # Per-layer coding conventions
+    ├── agent-memory/                  # Persistent agent memory
+    └── config.toml                    # Permissions and configuration
+```
+
+---
+
+## Configure with setup
+
+After installation, open Codex and run the setup skill:
+
+```bash
+codex
+```
+
+Then invoke the setup skill:
+
+```
+/setup
+```
+
+Or run it non-interactively:
+
+```bash
+codex exec "run /setup --yes"
+```
+
+The wizard runs 5 phases:
+
+| Phase | What happens |
+|-------|-------------|
+| **1. Analyze** | Detects your tech stack, architecture layers, and CI commands |
+| **2. Personas** | Researches your domain and generates VPC user profiles |
+| **3. Configure** | Asks about your backlog provider, git workflow, and agent selection |
+| **4. Generate** | Fills all templates with your project-specific context |
+| **5. Cleanup** | Removes setup files, leaving only your tailored workflow |
+
+---
+
+## Use your first skill
+
+Once setup is complete, try generating a feature:
+
+```bash
+codex
+```
+
+```
+/sr:implement "add a health check endpoint"
+```
+
+Or with a GitHub issue number:
+
+```
+/sr:implement #42
+```
+
+This runs the full SpecRails pipeline: Architect → Developer → Reviewer → PR.
+
+---
+
+## Codex Cloud (alternative)
+
+If you prefer the web interface, SpecRails Skills also work in **Codex Cloud** at [chatgpt.com/codex](https://chatgpt.com/codex). Connect your repository and use Skills from the UI.
+
+Note that Codex Cloud runs asynchronously — long-running skills like `/sr:implement` are well-suited to this environment.
+
+---
+
+## Verify
+
+Check that everything installed correctly:
+
+```bash
+# List generated agent configs
+ls .codex/agents/
+
+# List installed skills
+ls .codex/skills/
+
+# Check for unresolved placeholders (should return nothing)
+grep -r '{{[A-Z_]*}}' .codex/agents/ .codex/skills/ 2>/dev/null
+
+# Check the installed version
+cat .specrails-version
+```
+
+---
+
+## Troubleshooting
+
+### "No AI CLI found"
+
+Neither `claude` nor `codex` was found in your `PATH`. Install Codex CLI:
+
+```bash
+npm i -g @openai/codex
+```
+
+### Codex CLI not detected
+
+The installer looks for `codex` in your `PATH`. If it is installed but not found, verify:
+
+```bash
+which codex
+codex --version
+```
+
+If Codex is installed via a custom path, pass the provider explicitly:
+
+```bash
+CLI_PROVIDER=codex npx specrails-core@latest init --root-dir .
+```
+
+### Existing `.codex/` directory detected
+
+The installer warns if SpecRails artifacts already exist. You can merge or abort to review manually.
+
+### Placeholders not resolved
+
+If you see `{{PLACEHOLDER}}` in generated files, `/setup` did not complete. Re-run `/setup` or fill the values manually.
+
+---
+
+[← Installation](installation.md) · [Codex vs Claude Code →](codex-vs-claude-code.md) · [CLI Reference →](cli-reference.md)

package/docs/user-docs/installation.md

@@ -0,0 +1,177 @@
+# Installation
+
+Install SpecRails into any git repository in two steps: run the installer, then run `/setup` inside your AI CLI.
+
+SpecRails supports both **Claude Code** and **OpenAI Codex**. The installer detects which CLI you have and configures accordingly. See [Codex vs Claude Code](codex-vs-claude-code.md) for a feature comparison.
+
+## Requirements
+
+| Tool | Version | Notes |
+|------|---------|-------|
+| **Node.js** | 18+ | Required for the installer |
+| **Claude Code** | Latest | Stable — [install guide](https://docs.anthropic.com/en/docs/claude-code) |
+| **Codex CLI** | Latest | Beta — `npm i -g @openai/codex` |
+| **Git** | Any | Your project must be a git repository |
+
+You need at least one of Claude Code or Codex CLI. If both are installed, the installer uses Claude Code by default. Override with `CLI_PROVIDER=codex`.
+
+Optional but recommended:
+
+| Tool | Why |
+|------|-----|
+| **GitHub CLI** (`gh`) | Automatic PR creation and Issue integration |
+
+## Install
+
+Run the installer from inside your project directory:
+
+```bash
+cd your-project
+npx specrails-core@latest init --root-dir .
+```
+
+The installer copies agent templates, skills, and configuration files into `.claude/` (Claude Code) or `.codex/` (Codex). It does not modify your existing code.
+
+### Flags
+
+| Flag | Effect |
+|------|--------|
+| `--root-dir <path>` | Target directory (default: current directory) |
+| `--yes` / `-y` | Skip confirmation prompts |
+
+You can also force a specific provider:
+
+```bash
+CLI_PROVIDER=codex npx specrails-core@latest init --root-dir .
+```
+
+### What gets installed
+
+**Claude Code:**
+
+```
+your-project/
+└── .claude/
+    ├── commands/setup.md         # The /setup wizard
+    ├── skills/                   # Workflow skills (/sr:*, /opsx:*)
+    ├── agents/                   # Agent definitions
+    ├── rules/                    # Per-layer coding conventions
+    ├── web-manager/              # Pipeline Monitor dashboard (optional)
+    └── settings.json             # Permissions
+```
+
+**Codex (beta):**
+
+```
+your-project/
+├── AGENTS.md                     # SpecRails agent instructions for Codex
+└── .codex/
+    ├── skills/                   # Workflow skills (/sr:*, /opsx:*)
+    ├── agents/                   # Agent definitions (TOML)
+    ├── rules/                    # Per-layer coding conventions
+    └── config.toml               # Permissions
+```
+
+The installer also writes `.specrails-version` and `.specrails-manifest.json` to track the installed version.
+
+## Configure with /setup
+
+After installation, open your AI CLI in your project and run the setup wizard:
+
+```bash
+claude    # Claude Code
+# or
+codex     # Codex
+```
+
+```
+/setup
+```
+
+The wizard runs 5 phases:
+
+| Phase | What happens |
+|-------|-------------|
+| **1. Analyze** | Detects your tech stack, architecture layers, and CI commands |
+| **2. Personas** | Researches your domain and generates VPC user profiles |
+| **3. Configure** | Asks about your backlog provider, git workflow, and agent selection |
+| **4. Generate** | Fills all templates with your project-specific context |
+| **5. Cleanup** | Removes setup files, leaving only your tailored workflow |
+
+After setup, `.claude/` contains fully configured agents and commands ready to use. The `/setup` command removes itself — it only runs once.
+
+## Verify
+
+Check that everything installed correctly:
+
+```bash
+# List generated agents
+ls .claude/agents/
+
+# Check for unresolved placeholders (should return nothing)
+grep -r '{{[A-Z_]*}}' .claude/agents/ .claude/commands/ .claude/rules/
+
+# Check the installed version
+cat .specrails-version
+```
+
+## Troubleshooting
+
+### "This appears to be the specrails source repository"
+
+You ran the installer from inside the SpecRails source repo. Run it from your target project instead:
+
+```bash
+cd /path/to/your-project
+npx specrails-core@latest init --root-dir .
+```
+
+### Existing `.claude/` directory detected
+
+The installer warns if SpecRails artifacts already exist. You can merge (install alongside existing files) or abort to review manually.
+
+### Placeholders not resolved
+
+If you see `{{PLACEHOLDER}}` in generated files, the `/setup` wizard did not complete. Re-run `/setup` or fill the values manually.
+
+### "No Claude API key configured"
+
+Claude Code supports two authentication modes:
+
+- **OAuth** — the default for new installs (`claude auth login`). No API key appears in `claude config`.
+- **API key** — explicit key set via `claude config set api_key <key>` or `ANTHROPIC_API_KEY`.
+
+If you authenticated via OAuth, the installer's prerequisite check still fails even though Claude Code is working. Bypass it with:
+
+```bash
+SPECRAILS_SKIP_PREREQS=1 npx specrails-core@latest init --root-dir .
+```
+
+Or set an API key explicitly if you prefer:
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+npx specrails-core@latest init --root-dir .
+```
+
+### Claude Code not found
+
+Install Claude Code following [Anthropic's guide](https://docs.anthropic.com/en/docs/claude-code), then re-run the installer.
+
+### Codex CLI not found
+
+Install Codex CLI and re-run:
+
+```bash
+npm i -g @openai/codex
+```
+
+Or force the provider if Codex is installed at a non-standard path:
+
+```bash
+CLI_PROVIDER=codex npx specrails-core@latest init --root-dir .
+```
+
+---
+
+[Quick Start →](quick-start.md) · [Getting Started (Codex) →](getting-started-codex.md) · [CLI Reference →](cli-reference.md)

package/docs/user-docs/quick-start.md

@@ -0,0 +1,158 @@
+# Quick Start
+
+Get SpecRails running in your project in under 10 minutes.
+
+## Before you begin
+
+You need:
+- **Node.js 18+** — check with `node --version`
+- **Claude Code** — install from [docs.anthropic.com/en/docs/claude-code](https://docs.anthropic.com/en/docs/claude-code)
+- **A git repository** — your project must have a `.git` directory
+
+Optional:
+- **GitHub CLI** (`gh`) — enables automatic PR creation
+
+## Step 1: Install
+
+From inside your project directory:
+
+```bash
+npx specrails-core@latest init --root-dir .
+```
+
+Expected output:
+
+```
+✓ Prerequisites checked
+✓ Templates installed → .claude/
+✓ Version tracked → .specrails-version
+```
+
+This copies agent templates and commands into `.claude/`. Your existing code is not touched.
+
+## Step 2: Run the setup wizard
+
+Open Claude Code in your project:
+
+```bash
+claude
+```
+
+Then run:
+
+```
+/setup
+```
+
+The wizard runs automatically and takes about 5 minutes. It analyzes your codebase and configures SpecRails for your specific project:
+
+```
+Phase 1/5  Analyzing codebase...
+           → Detected: TypeScript, Express, PostgreSQL
+           → Found 3 architecture layers
+           → Identified CI commands: npm test, npm run lint
+
+Phase 2/5  Generating user personas...
+           → Researching your domain
+           → Created 3 VPC profiles
+
+Phase 3/5  Configuration...
+           → Backlog provider: GitHub Issues
+           → Git workflow: trunk-based
+
+Phase 4/5  Generating files...
+           → sr-architect.md (adapted to your stack)
+           → sr-developer.md (knows your CI commands)
+           → sr-reviewer.md (runs your specific checks)
+           → 9 more agents
+
+Phase 5/5  Cleanup complete. /setup removed.
+
+✓ SpecRails is ready. Run /sr:implement to start building.
+```
+
+After setup, the `/setup` command is gone — it's a one-time wizard.
+
+## Step 3: Implement your first feature
+
+Pick something small. Either reference a GitHub Issue or describe it in plain text:
+
+```
+/sr:implement #42
+```
+
+or:
+
+```
+/sr:implement "add a health check endpoint to the API"
+```
+
+The pipeline runs automatically:
+
+```
+Phase 3a  Architect designing...
+          → Design: GET /health endpoint + middleware
+          → Tasks: 3 steps
+
+Phase 3b  Developer implementing...
+          → src/routes/health.ts (created)
+          → src/middleware/health.ts (created)
+          → src/app.ts (modified)
+
+Phase 3c  Test Writer generating...
+          → tests/routes/health.test.ts (created)
+          → 5 tests, all passing
+
+Phase 3d  Doc Sync updating...
+          → CHANGELOG.md updated
+
+Phase 4   Security Reviewer scanning...
+          → No critical findings
+
+Phase 4b  Reviewer running CI...
+          → ✓ lint   ✓ typecheck   ✓ tests
+
+Phase 4b-conf  Confidence: 91% — threshold met
+
+PR #43 created: feat: add health check endpoint
+```
+
+One command. The PR is ready for human review.
+
+## What's next?
+
+**Explore the backlog:**
+
+```
+/sr:product-backlog
+```
+
+See your GitHub Issues ranked by persona fit and effort. The top 3 are safe to implement next.
+
+**Generate new feature ideas:**
+
+```
+/sr:update-product-driven-backlog
+```
+
+The Product Manager researches your competitive landscape and creates well-formed GitHub Issues for new features.
+
+**Run multiple features in parallel:**
+
+```
+/sr:implement #42, #43, #44
+```
+
+Each feature gets its own git worktree. Pipelines run concurrently and merge automatically.
+
+**Ask why a decision was made:**
+
+```
+/sr:why "why did we choose this database schema"
+```
+
+Agents record their reasoning as they work. `/sr:why` searches those records in plain language.
+
+---
+
+[← Installation](installation.md) · [CLI Reference →](cli-reference.md) · [FAQ →](faq.md)

package/docs/workflows.md

@@ -294,6 +294,24 @@ Open-ended thinking mode. Use for brainstorming, investigating problems, or clar
 /opsx:explore
 ```
 
+### `/sr:opsx-diff` — Spec Change Diff
+
+Visualize the before/after diff of an OpenSpec change — what behavioral requirements are being added, modified, or removed.
+
+```
+/sr:opsx-diff <change-name>
+/sr:opsx-diff my-feature --format json
+/sr:opsx-diff my-feature --summary-only
+```
+
+| Flag | Effect |
+|------|--------|
+| `<change-name>` | Kebab-case name of the change to diff (required) |
+| `--format json` | Emit structured JSON instead of markdown |
+| `--summary-only` | Show file-level summary only, skip inline line-level diff |
+
+Compares the current specs against the named OpenSpec change. Useful during review to confirm a change matches its design intent before archiving.
+
 ### Typical OpenSpec flow
 
 ```
@@ -316,6 +334,53 @@ Or step by step:
 
 ---
 
+## `/sr:telemetry`
+
+Inspect per-agent execution metrics: token usage, estimated API cost, run count, average duration, and success/failure rate.
+
+```
+/sr:telemetry
+/sr:telemetry --period today
+/sr:telemetry --agent sr-developer
+/sr:telemetry --format json
+/sr:telemetry --save
+```
+
+### Flags
+
+| Flag | Effect |
+|------|--------|
+| `--period <filter>` | Time window: `today`, `week` (default), or `all` |
+| `--agent <name>` | Focus on a single agent (e.g. `sr-developer`) |
+| `--format <fmt>` | Output format: `markdown` (default) or `json` |
+| `--save` | Write a snapshot to `.claude/telemetry/` after display |
+
+Reads Claude CLI JSONL session logs and agent-memory files to produce a cost dashboard with trend indicators and optimization recommendations.
+
+---
+
+## `/sr:merge-resolve`
+
+Resolve git conflict markers using AI-powered context analysis.
+
+```
+/sr:merge-resolve
+/sr:merge-resolve --files src/api/routes.ts src/db/schema.ts
+/sr:merge-resolve --context openspec/changes/
+```
+
+### Flags
+
+| Flag | Effect |
+|------|--------|
+| `--files <paths>` | Explicit file paths or globs to process (default: auto-detect from working tree) |
+| `--context <dir>` | Directory of OpenSpec context bundles (default: `openspec/changes/`) |
+| `--threshold <n>` | Minimum confidence threshold to auto-apply a resolution |
+
+For each conflict block, the command reads the OpenSpec context bundles from the features that produced the conflict, infers the correct resolution, and writes it in place. Conflicts it cannot safely resolve are left with clean markers for manual review. Always review the result before committing.
+
+---
+
 ## `/sr:retry`
 
 Resume a failed `/sr:implement` run from the last successful phase — without restarting from scratch.