specrails 0.2.0

package/templates/commands/sr/why.md

@@ -0,0 +1,96 @@
+# /sr:why — In-Context Help
+
+Searches explanation records written by sr-architect, sr-developer, and sr-reviewer agents
+during the OpenSpec implementation pipeline.
+
+Records are stored in `.claude/agent-memory/explanations/` as Markdown files with
+YAML frontmatter (agent, feature, tags, date).
+
+**Usage:**
+- `/sr:why` — list the 20 most recent explanation records
+- `/sr:why <query>` — search records by keyword or tag
+
+---
+
+## Step 1: Find explanation records
+
+Glob all files matching `.claude/agent-memory/explanations/*.md`.
+
+If the directory does not exist or contains no files:
+Print:
+```
+No explanation records found yet.
+
+Explanation records are written by the sr-architect, sr-developer, and sr-reviewer agents
+when they make significant decisions during feature implementation.
+
+Run `/sr:implement` on a feature to generate your first explanation records.
+```
+Then stop.
+
+## Step 2: Handle no-argument mode (listing)
+
+If `$ARGUMENTS` is empty:
+
+Read each explanation record file. Extract from frontmatter: `date`, `agent`, `feature`, `tags`.
+Extract the first sentence of the `## Decision` section as the decision summary.
+
+Sort records by `date` descending. Print the 20 most recent as a Markdown table:
+
+```
+## Recent Explanation Records
+
+| Date | Agent | Feature | Tags | Decision |
+|------|-------|---------|------|----------|
+| 2026-03-14 | sr-architect | in-context-help | [templates, commands] | Chose flat directory over per-agent subdirectories. |
+| ...  | ...   | ...     | ...  | ...      |
+```
+
+Then stop.
+
+## Step 3: Handle query mode (search)
+
+If `$ARGUMENTS` is non-empty, treat the full string as the search query.
+
+For each explanation record file:
+1. Read the full file content
+2. Score the record against the query:
+   - Filename contains a query word: +3 points per matching word
+   - Frontmatter `tags` array contains an exact query word: +3 points per matching tag
+   - Frontmatter `feature` contains a query word: +2 points
+   - Body text contains a query word: +1 point per occurrence (case-insensitive)
+3. Sum the score
+
+Sort records by score descending. Take the top 5 records with score > 0.
+
+If no records score > 0:
+Print:
+```
+No explanation records match "<query>".
+```
+Then list all unique tags from existing records:
+```
+## Available Tags
+
+[sorted list of all unique tags from all explanation records]
+
+Try `/sr:why <tag>` with one of the tags above, or `/sr:why` to browse all records.
+```
+
+If records match, print each matching record in full, separated by `---`:
+
+```
+## Results for "<query>" (N matches)
+
+---
+
+**[date] [agent] — [feature]**
+Tags: [tag1, tag2]
+
+[full record body]
+
+---
+
+**[date] [agent] — [feature]**
+...
+```

package/templates/personas/persona.md

@@ -0,0 +1,43 @@
+# Persona: {{PERSONA_NAME}}
+
+> {{PERSONA_TAGLINE}}
+
+## Profile
+
+| Field | Value |
+|-------|-------|
+| **Name** | "{{PERSONA_NICKNAME}}" — The {{PERSONA_ROLE}} |
+| **Age** | {{PERSONA_AGE_RANGE}} |
+{{PERSONA_PROFILE_FIELDS}}
+
+## Behaviors
+
+{{PERSONA_BEHAVIORS}}
+
+## Value Proposition Canvas
+
+### Customer Jobs
+
+| Type | Job |
+|------|-----|
+{{PERSONA_JOBS}}
+
+### Pains
+
+| Severity | Pain |
+|----------|------|
+{{PERSONA_PAINS}}
+
+### Gains
+
+| Impact | Gain |
+|--------|------|
+{{PERSONA_GAINS}}
+
+## Key Insight
+
+> {{PERSONA_KEY_INSIGHT}}
+
+## Sources
+
+{{PERSONA_SOURCES}}

package/templates/personas/the-maintainer.md

@@ -0,0 +1,78 @@
+# Persona: The Maintainer
+
+> "I maintain this project in my spare time. Every hour I save on routine work is an hour I can spend on what actually matters."
+
+## Profile
+
+| Field | Value |
+|-------|-------|
+| **Name** | "Kai" — The Maintainer |
+| **Age** | 25-45 |
+| **Role** | Open-source maintainer, often solo or with 1-3 co-maintainers |
+| **Projects** | 1-5 active repos, ranging from 100 to 50k+ stars |
+| **Experience** | Deep expertise in their project's domain; variable breadth across stacks |
+| **Tools today** | GitHub (Issues, PRs, Actions), Dependabot, CodeQL, Claude Code or Copilot |
+| **Spending** | $0-20/month (OSS maintainers are cost-sensitive; many rely on free tiers/sponsorships) |
+| **Tech comfort** | Very high — but time-poor; optimizes for efficiency above all |
+
+## Behaviors
+
+- Reviews 5-50 PRs per week, most from contributors they've never met
+- Spends disproportionate time on triage — labeling issues, requesting info, closing duplicates
+- Deeply skeptical of AI-generated PRs and "drive-by" contributions
+- Values consistency and backwards compatibility over new features
+- Writes detailed contributing guides but contributors rarely read them
+- Burns out from the imbalance: contribution volume grows but maintainer capacity doesn't
+- Will adopt automation that reduces their review burden without sacrificing quality
+
+## Value Proposition Canvas
+
+### Customer Jobs
+
+| Type | Job |
+|------|-----|
+| Functional | Review and merge contributions efficiently without sacrificing quality |
+| Functional | Maintain coding standards across a growing contributor base |
+| Functional | Triage issues and PRs — separate signal from noise |
+| Functional | Keep CI/CD green and catch regressions early |
+| Social | Build a healthy community where contributors feel welcomed and guided |
+| Emotional | Avoid burnout from the growing volume of contributions and issues |
+| Emotional | Feel that their project is sustainable, not just surviving |
+
+### Pains
+
+| Severity | Pain |
+|----------|------|
+| Critical | "Eternal September" — AI lowers contribution friction, flooding maintainers with low-quality PRs |
+| Critical | Review burden scales with contributors but maintainer time doesn't |
+| High | AI-generated contributions that look plausible but miss project conventions or architectural intent |
+| High | No way to enforce project-specific coding standards automatically beyond basic linting |
+| Medium | Automated scanning tools (security, code quality) generate noise — hard to distinguish real issues |
+| Medium | Onboarding contributors to the project's specific patterns and conventions is time-consuming |
+| Medium | Feature requests pile up with no framework to evaluate which ones matter most to users |
+| Low | Sponsorship/funding doesn't scale with project popularity or maintenance burden |
+
+### Gains
+
+| Impact | Gain |
+|--------|------|
+| High | Automated review that enforces project-specific conventions, not just generic lint rules |
+| High | AI reviewer that knows the codebase deeply — catches architectural violations, not just style issues |
+| High | Reduced time spent on routine reviews, freeing time for design decisions and community |
+| Medium | Structured feature prioritization based on actual user needs (not loudest voices) |
+| Medium | Implementation pipeline that lets maintainers describe features and get convention-compliant PRs |
+| Medium | Institutional memory — the AI system remembers past decisions and enforces them consistently |
+| Low | Easy setup that works with existing GitHub-based workflows (Issues, Actions, PRs) |
+| Low | Free or very low cost for open-source projects |
+
+## Key Insight
+
+> Open-source maintainers are the most **time-constrained** users in the software ecosystem. They don't need more AI to *write* code — they need AI that *understands their project deeply enough* to review contributions, enforce conventions, and handle routine tasks so they can focus on architecture and community. The key unlock is project-specific intelligence, not generic coding ability.
+
+## Sources
+
+- [GitHub Blog — Welcome to the Eternal September of Open Source](https://github.blog/open-source/maintainers/welcome-to-the-eternal-september-of-open-source-heres-what-we-plan-to-do-for-maintainers/)
+- [st0012.dev — AI and Open Source: A Maintainer's Take (End of 2025)](https://st0012.dev/2025/12/30/ai-and-open-source-a-maintainers-take-end-of-2025/)
+- [The New Stack — Open Source: Inside 2025's 4 Biggest Trends](https://thenewstack.io/open-source-inside-2025s-4-biggest-trends/)
+- [Anthropic — 2026 Agentic Coding Trends Report](https://resources.anthropic.com/hubfs/2026%20Agentic%20Coding%20Trends%20Report.pdf)
+- [Augment Code — 6 Best Devin Alternatives for AI Agent Orchestration](https://www.augmentcode.com/tools/best-devin-alternatives)

package/templates/rules/layer.md

@@ -0,0 +1,8 @@
+---
+paths:
+  - "{{LAYER_PATH}}/**"
+---
+
+# {{LAYER_NAME}} Conventions
+
+{{LAYER_CONVENTIONS}}

package/templates/security/security-exemptions.yaml

@@ -0,0 +1,20 @@
+# Security scan exemptions
+#
+# Add entries here to suppress known false positives from the security-reviewer agent.
+# All exemptions are tracked in git — every addition is auditable.
+#
+# Fields:
+#   secrets.pattern   - Description of the pattern being exempted (for documentation)
+#   secrets.reason    - Required: why this is a known false positive
+#   secrets.added_by  - Required: who added this exemption
+#   secrets.added_on  - Required: ISO 8601 date (YYYY-MM-DD)
+#
+#   vulnerabilities.rule    - The vulnerability rule name being exempted
+#   vulnerabilities.file    - Optional: scope exemption to a specific file path
+#   vulnerabilities.reason  - Required: justification
+#   vulnerabilities.added_by - Required
+#   vulnerabilities.added_on - Required
+
+exemptions:
+  secrets: []
+  vulnerabilities: []

package/templates/settings/confidence-config.json

@@ -0,0 +1,17 @@
+{
+  "_docs": "specrails confidence gate configuration. Installed to .claude/confidence-config.json by /setup.",
+  "schema_version": "1",
+  "enabled": true,
+  "thresholds": {
+    "overall": 70,
+    "aspects": {
+      "type_correctness": 60,
+      "pattern_adherence": 60,
+      "test_coverage": 60,
+      "security": 75,
+      "architectural_alignment": 60
+    }
+  },
+  "on_breach": "block",
+  "override_allowed": true
+}

package/templates/settings/settings.json

@@ -0,0 +1,15 @@
+{
+  "permissions": {
+    "allow": [
+      "Read",
+      "Write",
+      "Edit",
+      "Glob",
+      "Grep",
+      "Agent",
+      "Skill",
+      "ToolSearch",
+      "{{PERMISSION_ENTRIES}}"
+    ]
+  }
+}

package/templates/web-manager/README.md

@@ -0,0 +1,107 @@
+# specrails Web Manager
+
+## Overview
+
+The specrails web manager is a locally-run dashboard that monitors and controls the specrails pipeline. It visualizes the four pipeline phases (Architect, Developer, Reviewer, Ship) with live state indicators, streams logs in real-time from spawned `claude` CLI processes, and lets you launch pipeline commands directly from the browser.
+
+## Prerequisites
+
+- Node.js 18 or later
+- `claude` CLI on your PATH (the `claude` binary from the Claude Code CLI)
+
+## Setup
+
+```bash
+cd web
+npm install
+```
+
+This installs both the server dependencies (Express, WebSocket) and the client dependencies (React, Vite).
+
+## Start
+
+```bash
+npm run dev
+```
+
+This starts two processes concurrently:
+- **Backend server** on `http://127.0.0.1:4200`
+- **Frontend client** on `http://localhost:4201`
+
+Open `http://localhost:4201` in your browser to view the dashboard.
+
+## CLI Options
+
+The server accepts these CLI flags (used with `npm run dev:server` or `tsx server/index.ts`):
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--project <name>` | `specrails` | Project name displayed in the dashboard header |
+| `--port <n>` | `4200` | Port the backend server listens on |
+
+Example:
+
+```bash
+tsx server/index.ts --project my-app --port 4000
+```
+
+## Hook Integration
+
+The web manager accepts Claude Code hook events at `POST /hooks/events`. Configure hooks in the target project's `.claude/settings.json` to POST phase transitions as the pipeline runs.
+
+Example `.claude/settings.json` entry for the target repo:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [],
+    "PostToolUse": []
+  }
+}
+```
+
+To manually fire a hook event (useful for testing):
+
+```bash
+# Mark the architect phase as running
+curl -X POST http://localhost:4200/hooks/events \
+  -H 'Content-Type: application/json' \
+  -d '{"event":"agent_start","agent":"architect"}'
+
+# Mark the architect phase as done
+curl -X POST http://localhost:4200/hooks/events \
+  -H 'Content-Type: application/json' \
+  -d '{"event":"agent_stop","agent":"architect"}'
+
+# Mark the developer phase as errored
+curl -X POST http://localhost:4200/hooks/events \
+  -H 'Content-Type: application/json' \
+  -d '{"event":"agent_error","agent":"developer"}'
+```
+
+Supported `agent` values: `architect`, `developer`, `reviewer`, `ship`
+
+Supported `event` values: `agent_start`, `agent_stop`, `agent_error`
+
+Unknown agents or events are ignored (the server returns 200 and logs a warning).
+
+## Command Examples
+
+Type these in the Actions input at the bottom of the sidebar and press Enter or click Run:
+
+```
+/implement #42
+/opsx:ff
+/review
+```
+
+The dashboard spawns `claude --dangerously-skip-permissions <command>` and streams all output to the log panel.
+
+## MVP Limitations
+
+The following are explicitly out of scope for this MVP:
+
+- **No log persistence** — logs are in-memory only; restarting the server clears all history
+- **No authentication** — the server binds to `127.0.0.1` (loopback only); do not expose it to a network
+- **No multi-project UI** — one project per server instance; run multiple servers on different ports for multiple projects
+- **One active process at a time** — submitting a command while one is running returns a 409 error; wait for the current process to finish

package/templates/web-manager/client/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>specrails manager</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>