specrails-core 1.7.0 → 1.7.1

package/docs/deployment.md

@@ -0,0 +1,217 @@
+# Deployment
+
+SpecRails runs locally — no cloud infrastructure required. Choose the setup that fits your workflow.
+
+## Options at a glance
+
+| Option | Best for | Setup time |
+|--------|----------|------------|
+| [Local (npx)](#local-npx) | Quick start, individual developers | ~2 minutes |
+| [Local (git clone)](#local-git-clone) | Customization, contributing | ~5 minutes |
+| [Docker](#docker) | Reproducible environments, teams | ~5 minutes |
+| [CI/CD](#cicd-github-actions) | Automated workflows, GitHub Actions | ~10 minutes |
+
+---
+
+## Local — npx
+
+The fastest way to get started. No install required.
+
+```bash
+npx specrails@latest setup
+```
+
+This will:
+1. Scaffold a `.claude/` directory in your project
+2. Install the default agent set
+3. Run the `/setup` wizard to configure your preferences
+
+**Requirements:** Node.js ≥18, Claude API key
+
+---
+
+## Local — git clone
+
+Clone the repository for full control and the ability to customize agents.
+
+```bash
+git clone https://github.com/specrails-ai/specrails-core
+cd specrails-core
+npm install
+npm run setup
+```
+
+### Updating
+
+```bash
+git pull origin main
+npm install
+```
+
+See [Updating](./updating.md) for details on preserving local customizations during updates.
+
+---
+
+## Docker
+
+Run SpecRails in a container for portable, reproducible environments.
+
+### Quick start
+
+```bash
+docker run -it \
+  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
+  -v $(pwd):/workspace \
+  ghcr.io/specrails-ai/specrails:latest \
+  setup
+```
+
+### docker-compose
+
+Create a `docker-compose.yml` in your project root:
+
+```yaml
+services:
+  specrails:
+    image: ghcr.io/specrails-ai/specrails:latest
+    environment:
+      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
+    volumes:
+      - .:/workspace
+    working_dir: /workspace
+```
+
+Then run:
+
+```bash
+docker compose run specrails setup
+```
+
+### Building locally
+
+```bash
+git clone https://github.com/specrails-ai/specrails-core
+cd specrails-core
+docker build -t specrails:local .
+docker run -it \
+  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
+  -v $(pwd):/workspace \
+  specrails:local setup
+```
+
+---
+
+## CI/CD — GitHub Actions
+
+Automate SpecRails workflows in your GitHub Actions pipeline.
+
+### Prerequisites
+
+1. Add `ANTHROPIC_API_KEY` to your repository secrets
+2. (Optional) Add `GITHUB_TOKEN` with write access for PR creation
+
+### Basic workflow
+
+```yaml
+# .github/workflows/specrails.yml
+name: SpecRails AI Review
+
+on:
+  pull_request:
+    types: [opened, synchronize]
+
+jobs:
+  review:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install SpecRails
+        run: npm install -g specrails
+
+      - name: Run AI review
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: specrails review --pr ${{ github.event.pull_request.number }}
+```
+
+### Scheduled batch implementation
+
+```yaml
+name: SpecRails Batch Implement
+
+on:
+  schedule:
+    - cron: '0 9 * * 1-5'   # Weekdays at 9am UTC
+  workflow_dispatch:
+
+jobs:
+  implement:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install SpecRails
+        run: npm install -g specrails
+
+      - name: Run batch implementation
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: specrails sr:batch-implement --max 3
+```
+
+---
+
+## Environment variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `ANTHROPIC_API_KEY` | Yes | Your Claude API key |
+| `GITHUB_TOKEN` | For PR creation | GitHub personal access token or Actions token |
+| `SPECRAILS_LOG_LEVEL` | No | `debug`, `info` (default), `warn`, `error` |
+| `SPECRAILS_MODEL` | No | Override default model (e.g. `claude-opus-4-6`) |
+
+---
+
+## Troubleshooting
+
+### Permission errors on macOS
+
+```bash
+sudo npm install -g specrails
+# or use a node version manager (nvm, volta) to avoid sudo
+```
+
+### Docker volume permissions
+
+If agents cannot write files inside the container:
+
+```bash
+docker run -it \
+  --user $(id -u):$(id -g) \
+  -v $(pwd):/workspace \
+  ghcr.io/specrails-ai/specrails:latest
+```
+
+### API key not found
+
+Ensure `ANTHROPIC_API_KEY` is exported in your shell:
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+# Add to ~/.zshrc or ~/.bashrc to persist
+```

package/docs/getting-started.md

@@ -0,0 +1,107 @@
+# Getting Started
+
+Get SpecRails running in your project in under 5 minutes.
+
+## What is SpecRails?
+
+SpecRails installs a **product-driven development workflow** into any repository. It gives Claude Code a team of **12 specialized AI agents** — an architect, developers, layer reviewers, a reviewer, a product manager — that work together to go from idea to shipped PR automatically.
+
+Think of it as hiring a full engineering team that lives inside your CLI.
+
+## Prerequisites
+
+You only need two things:
+
+- **Git** — your project must be a git repository
+- **[Claude Code](https://claude.ai/claude-code)** — Anthropic's CLI tool
+
+Optional (recommended):
+
+- **npm** — for installing the Pipeline Monitor dashboard
+- **[GitHub CLI](https://cli.github.com/)** (`gh`) — for automatic PR creation and issue tracking
+
+## Install
+
+Pick your preferred method:
+
+**npx (recommended)**
+
+```bash
+npx specrails@latest init --root-dir <your-project>
+```
+
+**git clone**
+
+```bash
+git clone https://github.com/fjpulidop/specrails.git
+./specrails/install.sh --root-dir <your-project>
+```
+
+The installer will:
+
+1. Check your prerequisites
+2. Copy templates and commands into `.claude/`
+3. Initialize OpenSpec (if available)
+4. Track the installed version for future updates
+
+> **Note:** Run this from the repo where you want SpecRails — not from the SpecRails source repo itself.
+
+## Run the Setup Wizard
+
+Open Claude Code in your project and run:
+
+```
+/setup
+```
+
+The wizard walks you through 5 phases:
+
+| Phase | What happens |
+|-------|-------------|
+| **1. Analyze** | Detects your tech stack, architecture layers, CI commands, and conventions |
+| **2. Personas** | Researches your competitive landscape and generates user personas (VPC profiles) |
+| **3. Configure** | Asks about your backlog provider, git workflow, and which agents/commands to enable |
+| **4. Generate** | Fills all templates with your project-specific context |
+| **5. Cleanup** | Removes the wizard and templates, leaving only your tailored workflow files |
+
+After setup, your `.claude/` directory contains fully adapted agents, commands, and rules — ready to use.
+
+## Your first feature
+
+Let's implement something. Pick an issue from your backlog, or describe a feature:
+
+```
+/sr:implement "add a health check endpoint"
+```
+
+SpecRails will:
+
+1. **Architect** analyzes the request and designs the implementation
+2. **Developer** writes the code across all layers
+3. **Test Writer** generates tests for the new code
+4. **Doc Sync** updates your changelog and docs
+5. **Security Reviewer** scans for secrets and vulnerabilities
+6. **Reviewer** runs your full CI suite and fixes any issues
+7. Creates a **Pull Request** ready for human review
+
+That's it. One command, full pipeline.
+
+## Useful commands for newcomers
+
+Once you have a feature running, a few commands help you understand what's happening and why:
+
+- `/sr:why "question"` — search agent explanation records in plain language. Ask why a design decision was made, why a library was chosen, or why a particular pattern is used. Agents record their reasoning as they work.
+- `/sr:product-backlog` — see your prioritized backlog with safe implementation ordering. Good first stop before picking what to build next.
+- `/sr:compat-check #N` — check whether an issue's implementation would break existing API consumers before you commit to it.
+
+## What's next?
+
+Now that you're running, learn how the system thinks:
+
+- [Core Concepts](concepts.md) — understand the pipeline architecture and product-driven approach
+- [Agents](agents.md) — meet each agent and understand their role
+- [Workflows & Commands](workflows.md) — master the full command set
+
+---
+
+[← Back to Docs](README.md) · [Core Concepts →](concepts.md)

package/docs/installation.md

@@ -0,0 +1,243 @@
+# Installation & Setup
+
+This guide covers the complete installation process in detail. For the quick version, see [Getting Started](getting-started.md).
+
+## Prerequisites
+
+### Required
+
+| Tool | Why | Install |
+|------|-----|---------|
+| **Git** | SpecRails operates on git repositories | [git-scm.com](https://git-scm.com/) |
+| **Claude Code** | The AI CLI that runs the agents | `npm install -g @anthropic-ai/claude-code` |
+
+### Recommended
+
+| Tool | Why | Install |
+|------|-----|---------|
+| **npm** | Pipeline Monitor dashboard, OpenSpec CLI | Via [nvm](https://github.com/nvm-sh/nvm) |
+| **GitHub CLI** | Auto-create PRs, manage issues | `brew install gh` or [cli.github.com](https://cli.github.com/) |
+| **OpenSpec CLI** | Structured spec workflow | `npm install -g @openspec/cli` |
+
+### Optional
+
+| Tool | Why |
+|------|-----|
+| **JIRA CLI** | If using JIRA for backlog instead of GitHub Issues |
+
+The installer checks for all of these and offers to install missing tools.
+
+## Installation
+
+### From npx (recommended)
+
+```bash
+npx specrails@latest init --root-dir <your-project>
+```
+
+No cloning required. Downloads the latest version and runs the installer automatically.
+
+### From a local clone
+
+If you prefer to clone the repo first:
+
+```bash
+git clone https://github.com/fjpulidop/specrails.git
+./specrails/install.sh --root-dir <your-project>
+```
+
+### From curl
+
+Alternatively, pipe the installer directly:
+
+```bash
+curl -sL https://raw.githubusercontent.com/fjpulidop/specrails/main/install.sh | bash
+```
+
+> **Important:** Always run the installer from the **target repository** — the project where you want SpecRails installed. If you run it from inside the SpecRails source repo, the installer will detect this and prompt you for the correct target path.
+
+### What the installer does
+
+1. **Checks prerequisites** — validates Git, Claude Code; optionally installs npm, gh, OpenSpec
+2. **Detects existing setup** — warns if `.claude/agents/`, `.claude/commands/`, or `openspec/` already exist
+3. **Installs artifacts:**
+   - `.claude/commands/setup.md` — the `/setup` wizard
+   - `.claude/setup-templates/` — all template files
+   - `.claude/web-manager/` — Pipeline Monitor dashboard
+   - `.claude/security-exemptions.yaml` — security scanner config
+   - OpenSpec initialization (if CLI available)
+4. **Tracks version** — writes `.specrails-version` and `.specrails-manifest.json`
+
+### What it does NOT do
+
+The installer only copies files. It does not:
+
+- Modify your existing code
+- Create commits
+- Push to any remote
+- Install npm dependencies (you do this manually for the web manager)
+
+---
+
+## The Setup Wizard
+
+After installation, open Claude Code in your project and run:
+
+```
+/setup
+```
+
+### Phase 1: Codebase Analysis
+
+The wizard scans your project to detect:
+
+- **Languages & frameworks** — from file extensions, dependency files, imports
+- **Architecture layers** — name, path, tech stack, tags (e.g., `backend/` → Python/FastAPI)
+- **CI/CD commands** — lint, format, test, build, type-check commands
+- **Conventions** — naming, imports, error handling, testing patterns
+- **Warnings** — concurrency issues, auth patterns, state management
+
+**Output:** A YAML analysis used by all subsequent phases.
+
+### Phase 2: User Personas
+
+The wizard researches your project's domain and generates **user personas** with complete VPC profiles. It:
+
+1. Identifies your target user segments
+2. Researches competitors and alternatives via web search
+3. Creates 2–4 personas with jobs, pains, and gains
+4. Extracts a key insight per persona
+
+You can edit these later (see [Customization → Personas](customization.md#personas)).
+
+### Phase 3: Configuration
+
+Interactive prompts for:
+
+| Setting | Options |
+|---------|---------|
+| **Backlog provider** | GitHub Issues, JIRA, or none |
+| **Access mode** | Read-write or read-only |
+| **Git workflow** | Trunk-based, Git Flow, or custom |
+| **Agents** | Which agents to enable |
+| **Commands** | Which commands to install |
+
+### Phase 4: File Generation
+
+The wizard fills all templates with your project-specific context:
+
+- `{{STACK_OVERVIEW}}` → your detected tech stack
+- `{{CI_COMMANDS}}` → your actual CI command list
+- `{{LAYER_CONVENTIONS}}` → conventions per layer
+- `{{BACKEND_TECH_LIST}}` → your backend technologies
+- Every `{{PLACEHOLDER}}` resolved with real data
+
+**Generated files:**
+
+```
+.claude/
+├── agents/
+│   ├── sr-architect.md          # Adapted to your stack
+│   ├── sr-developer.md          # Knows your CI commands
+│   ├── sr-reviewer.md           # Runs your specific checks
+│   ├── sr-product-manager.md    # Knows your domain
+│   ├── sr-product-analyst.md    # Reads your backlog
+│   ├── sr-test-writer.md        # Uses your test framework
+│   ├── sr-security-reviewer.md  # Scans your patterns
+│   ├── sr-doc-sync.md           # Updates your doc format
+│   └── [personas].md            # Your user personas
+├── commands/
+│   └── sr/
+│       ├── implement.md
+│       ├── product-backlog.md
+│       ├── batch-implement.md
+│       └── ...
+├── rules/
+│   ├── backend.md
+│   ├── frontend.md
+│   └── ...
+└── settings.json
+```
+
+### Phase 5: Cleanup
+
+The wizard removes itself:
+
+- Deletes `.claude/commands/setup.md`
+- Deletes `.claude/setup-templates/`
+- Leaves only the final generated files
+
+After this phase, `/setup` is no longer available — your workflow is ready.
+
+---
+
+## Pipeline Monitor (optional)
+
+SpecRails includes a web dashboard for visualizing pipeline execution.
+
+### Install
+
+```bash
+cd .claude/web-manager && npm install
+cd client && npm install
+```
+
+### Run
+
+```bash
+cd .claude/web-manager && npm run dev
+```
+
+Opens at `http://localhost:4201` by default.
+
+---
+
+## Verify installation
+
+After setup, verify everything is in place:
+
+```bash
+# Check generated agents
+ls .claude/agents/
+
+# Check for unresolved placeholders (should return nothing)
+grep -r '{{[A-Z_]*}}' .claude/agents/ .claude/commands/ .claude/rules/
+
+# Check version
+cat .specrails-version
+```
+
+---
+
+## Troubleshooting
+
+### "This appears to be the specrails source repository"
+
+You're running the installer from inside the SpecRails repo. Run it from your target project instead:
+
+```bash
+cd /path/to/your-project
+bash /path/to/specrails/install.sh
+```
+
+### Existing `.claude/` directory detected
+
+The installer warns if SpecRails artifacts already exist. You can:
+
+- **Merge** — install alongside existing files (may overwrite conflicts)
+- **Abort** — cancel and review manually
+
+### Placeholders not resolved
+
+If you see `{{PLACEHOLDER}}` in generated files, the `/setup` wizard didn't complete. Re-run `/setup` or manually fill the values.
+
+---
+
+## What's next?
+
+- [Core Concepts](concepts.md) — understand the pipeline and agent architecture
+- [Getting Started](getting-started.md) — run your first feature implementation
+
+---
+
+[← Getting Started](getting-started.md) · [Core Concepts →](concepts.md)

package/docs/playbook-oss-maintainer.md

@@ -0,0 +1,112 @@
+# OSS Maintainer Workflow
+
+> For maintainers who want to merge AI-generated PRs quickly without sacrificing quality — and who want to define the conditions under which they trust the pipeline's output.
+
+## The review burden problem
+
+Without guardrails, AI-generated code requires the same review depth as human code. You read every file, verify every edge case, and check every type. The throughput advantage of automation disappears at review time.
+
+specrails adds observable quality signals to every PR: a confidence score from the Reviewer, a security scan from the Security Reviewer, CI results (lint, typecheck, tests), and structured reviewer annotations. These signals are machine-generated and reproducible — not "it looks fine to me."
+
+The goal is not to eliminate code review. It is to define the conditions under which you can trust those signals and reduce manual review to **intent verification**: does this PR do what the original issue asked for? Everything else — correctness, type safety, test coverage, security posture — is covered by the pipeline.
+
+## Setting confidence thresholds
+
+The Reviewer agent scores its own output on a 0–100 scale before creating the PR. You control what happens when that score falls below your threshold via `.claude/confidence-config.json`:
+
+```json
+{
+  "threshold": 85,
+  "on_below_threshold": "block",
+  "aspects": {
+    "security": { "threshold": 90, "on_below_threshold": "block" },
+    "correctness": { "threshold": 80, "on_below_threshold": "warn" }
+  }
+}
+```
+
+The three modes for `on_below_threshold`:
+
+- **`block`** — the pipeline stops before creating the PR. The Reviewer surfaces its concerns and waits. You review the specific low-confidence areas, then add an override comment to the issue to resume.
+- **`warn`** — the pipeline continues and creates the PR, but the PR description includes a prominently flagged section listing the low-confidence aspects and the Reviewer's reasoning.
+- **`override`** — used by the maintainer at runtime. Add a comment to the issue to explicitly bypass a block for a specific run.
+
+**Recommended starting thresholds for OSS projects**: overall 85 with `block`, security aspect 90 with `block`. The correctness aspect at 80 with `warn` is a reasonable starting point — correctness issues are easier to catch in review than security issues.
+
+Set thresholds based on your risk tolerance, not aspirationally. A threshold of 95 that constantly blocks the pipeline trains you to lower it. A threshold of 85 that rarely blocks but surfaces genuine concerns trains you to trust it.
+
+## Layer convention files as policy
+
+`.claude/rules/frontend.md` is read by the Frontend Reviewer before every review pass. The equivalent files exist for other layers your setup detected. These files are not documentation — they are review policy that the Reviewer enforces on every PR.
+
+Put rules in convention files that you would enforce in a human code review:
+- Naming conventions that aren't captured by ESLint (`PascalCase` for component files, `use-` prefix for hook files)
+- Required patterns (`cn()` for class merging, `@/` path alias for all imports)
+- Forbidden patterns (inline styles, hardcoded color values, `any` types)
+- Structural requirements (exported functions must have explicit return types)
+
+What doesn't belong in convention files:
+- Style preferences that ESLint or Prettier already enforce (semicolons, trailing commas, quote style)
+- Rules that require runtime context to evaluate ("don't use this API in production environments")
+- Aspirational guidelines that you don't actually enforce on every PR
+
+The distinction matters because the Reviewer treats convention files as hard rules. A rule in `.claude/rules/frontend.md` that you don't actually enforce in human review creates noise — the Reviewer will flag violations that you approve anyway, eroding trust in the signal.
+
+## The Failure Learning Loop
+
+When the Reviewer finds a non-trivial issue — a pattern that will recur if not captured — it writes a failure record to `.claude/agent-memory/`. Before implementing, the Developer reads failure records matching the current domain and uses them as guardrails.
+
+Over time, systematic mistakes stop appearing in PRs. If the Developer consistently produces type errors in a specific module, the Reviewer notes it, and the next Developer run avoids the pattern. This is not perfect — agents have context limits and memory records are text, not code — but it measurably reduces repeating defects in long-running projects.
+
+As a maintainer, you can seed this loop manually. When you reject a PR for a repeating issue, write a brief failure record in `.claude/agent-memory/` describing the pattern and the correct approach. The Developer will read it on the next relevant implementation. This is particularly effective for project-specific patterns that don't appear in training data — unusual framework choices, internal library conventions, domain-specific invariants.
+
+The memory directory is part of your repository. Reviewing and pruning it periodically keeps the signal quality high. Outdated failure records from refactored code should be removed so they don't mislead future Developers.
+
+## What CI and specrails don't catch
+
+The confidence gate and CI verify quality — not intent. A PR that scores 92 on confidence and passes all CI checks can still be wrong in ways that require human judgment. As a maintainer, the things that remain your responsibility are:
+
+- **Product intent**: does this implementation match what the original issue asked for? The Reviewer verifies the implementation against the spec, but the spec may not have captured the full product intent.
+- **UX feel**: for UI features, does the result look and behave right? Automated checks don't evaluate visual weight, interaction feel, or whether the layout works in realistic data conditions.
+- **Business logic edge cases**: are there edge cases the spec didn't cover that would produce incorrect behavior for real users? Specs are written before implementation — they capture known cases, not unknown ones.
+- **PR description accuracy**: does the PR description accurately describe what changed? This matters for changelog generation and future developers reading git history.
+
+These checks are fast when the pipeline is working well. A PR where the confidence score is high, CI is green, and the implementation is clearly scoped should take 5–10 minutes to verify for intent. That is the target review cost for a well-specced, well-pipelined feature.
+
+## The safe-to-merge checklist
+
+A PR from specrails is safe to merge without deep review when all of the following hold:
+
+- [ ] Overall confidence score is at or above your configured threshold
+- [ ] Security aspect score is at or above your configured threshold
+- [ ] CI is green: lint, typecheck, and tests all pass
+- [ ] No `TODO` or `FIXME` markers were introduced by the implementation
+- [ ] PR description matches the original issue intent (read the issue, then the PR — do they describe the same thing?)
+- [ ] No new dependencies added without justification in the PR body
+
+When any of these conditions fails, do not skip the review — investigate the specific failure. A `TODO` introduced by the Developer is a signal that it encountered a constraint it couldn't resolve. A CI failure that the Reviewer didn't fix is a signal that the pipeline exited early. A PR description that doesn't match the issue is a signal that scope drifted during implementation.
+
+## Patterns & Anti-patterns
+
+| Pattern | Why it works |
+|---------|-------------|
+| Setting `security` threshold higher than `overall` | Security issues are harder to catch in a quick review pass — the pipeline should surface them before the PR is created |
+| Putting naming conventions in `.claude/rules/` files | The Reviewer enforces them consistently on every PR, so you never see naming violations in review |
+| Seeding `.claude/agent-memory/` with project-specific failure records | Prevents the same class of defect from appearing repeatedly; teaches the pipeline your codebase's specific constraints |
+| Using `warn` for `correctness` and `block` for `security` | Lets low-stakes correctness issues through for quick human review while stopping security concerns cold |
+
+| Anti-pattern | Why it fails |
+|-------------|-------------|
+| Treating a high confidence score as a substitute for intent review | Confidence measures implementation quality against the spec, not the spec's alignment with product intent |
+| Adding aspirational rules to `.claude/rules/` files | Reviewer flags violations you'd approve anyway, creating noise that erodes trust in the rule set |
+| Never pruning `.claude/agent-memory/` | Outdated failure records from refactored code mislead future Developers, causing them to avoid patterns that are now correct |
+| Raising thresholds after every blocked PR instead of investigating | The block exists because the pipeline found something; raising the threshold to get the PR through skips the investigation |
+
+## What's next?
+
+- [Customization](customization.md) — configure agents, rules, personas, and confidence thresholds for your project
+- [Core Concepts](concepts.md) — understand the pipeline phases and the agent roles that produce the quality signals you're reviewing
+
+---
+
+[← Parallel Development](playbook-parallel-dev.md)