specrails-core 1.7.0 → 1.7.2

package/bin/specrails-core.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-const { execSync } = require("child_process");
+const { spawnSync } = require("child_process");
 const { resolve } = require("path");
 
 const ROOT = resolve(__dirname, "..");
@@ -33,11 +33,28 @@ if (!script) {
   process.exit(1);
 }
 
-const forwarded = args.slice(1).join(" ");
-const cmd = `bash "${resolve(ROOT, script)}" ${forwarded}`.trim();
+// Allowlisted flags per subcommand (defense-in-depth — spawnSync already
+// prevents shell injection, but an explicit allowlist rejects unknown flags
+// before the shell script is ever invoked).
+const ALLOWED_FLAGS = {
+  init: ["--root-dir", "--yes", "-y"],
+  update: ["--only"],
+  doctor: [],
+};
+
+const subargs = args.slice(1);
+const allowed = ALLOWED_FLAGS[subcommand] ?? [];
 
-try {
-  execSync(cmd, { stdio: "inherit", cwd: process.cwd() });
-} catch (err) {
-  process.exit(err.status || 1);
+for (const arg of subargs) {
+  if (arg.startsWith("-") && !allowed.includes(arg)) {
+    console.error(`Unknown flag: ${arg}`);
+    process.exit(1);
+  }
 }
+
+const result = spawnSync("bash", [resolve(ROOT, script), ...subargs], {
+  stdio: "inherit",
+  cwd: process.cwd(),
+});
+
+process.exit(result.status ?? (result.error ? 1 : 0));

package/docs/README.md

@@ -0,0 +1,37 @@
+# SpecRails Documentation
+
+Welcome to the SpecRails docs. This guide will take you from zero to a fully autonomous product-driven development workflow.
+
+## Start here
+
+| Guide | What you'll learn |
+|-------|-------------------|
+| [Getting Started](getting-started.md) | Install SpecRails and run your first workflow in 5 minutes |
+| [Core Concepts](concepts.md) | Understand the pipeline, agents, and product-driven approach |
+
+## Deep dives
+
+| Guide | What it covers |
+|-------|----------------|
+| [Installation & Setup](installation.md) | Detailed setup, prerequisites, the `/setup` wizard |
+| [Agents](agents.md) | Every agent explained — role, when it runs, why it exists |
+| [Workflows & Commands](workflows.md) | How to use `/sr:implement`, `/sr:product-backlog`, and more |
+| [Customization](customization.md) | Adapt agents, rules, personas, and conventions to your project |
+| [Updating](updating.md) | Keep SpecRails up to date without losing your customizations |
+
+## Reading order
+
+These docs are designed to be read front-to-back:
+
+1. **Getting Started** — get running fast
+2. **Core Concepts** — understand _why_ before _how_
+3. **Agents** — meet the team
+4. **Workflows & Commands** — put them to work
+5. **Customization** — make it yours
+6. **Updating** — keep it fresh
+
+Each page links to the next, so you can follow along naturally.
+
+---
+
+[Get started →](getting-started.md)

package/docs/agents.md

@@ -0,0 +1,273 @@
+# Agents
+
+SpecRails ships with **12 specialized agents**. Each has a clear role, a dedicated AI model, and knows exactly when to stay in its lane.
+
+## Why specialized agents?
+
+A single "do everything" prompt gets mediocre results. By splitting responsibilities, each agent:
+
+- Has a **focused system prompt** optimized for its task
+- Uses the **right model** for the job (Opus for creative work, Sonnet for implementation, Haiku for analysis)
+- Maintains **its own memory** across sessions
+- Loads only the **relevant conventions** for its scope
+
+The result: better quality at every stage, with clear accountability.
+
+## Agent roster
+
+### Product Manager
+
+| | |
+|-|-|
+| **Color** | Blue |
+| **Model** | Opus (creative reasoning) |
+| **Trigger** | `/opsx:explore`, `/sr:update-product-driven-backlog` |
+| **Role** | Feature ideation and product strategy |
+
+The Product Manager is the **starting point** of the pipeline. It researches your competitive landscape (via web search), evaluates ideas against your user personas using the VPC framework, and produces prioritized feature recommendations.
+
+**Why Opus?** Product thinking requires creative reasoning and nuanced judgment — weighing user needs, market trends, and technical feasibility simultaneously. Opus excels at this kind of open-ended analysis.
+
+**What it produces:**
+- Feature ideas organized by area
+- VPC scores per persona (0–5)
+- Effort estimates
+- Competitive inspiration sources
+
+---
+
+### Product Analyst
+
+| | |
+|-|-|
+| **Color** | Cyan |
+| **Model** | Haiku (fast, read-only) |
+| **Trigger** | `/sr:product-backlog` |
+| **Role** | Backlog analysis and reporting |
+
+The Product Analyst is a **read-only** agent. It reads your backlog, specs, and archived changes to produce structured reports. It never writes code or makes decisions — it just gives you the data.
+
+**Why Haiku?** Analysis tasks need speed, not deep reasoning. Haiku is fast and cheap, perfect for reading and summarizing large amounts of data.
+
+**What it produces:**
+- Prioritized backlog tables grouped by area
+- Top 3 recommendations ranked by VPC score / effort ratio
+- Spec gap analysis (what's specified vs. what's implemented)
+
+---
+
+### Architect
+
+| | |
+|-|-|
+| **Color** | Green |
+| **Model** | Sonnet |
+| **Trigger** | `/opsx:ff`, `/opsx:continue`, `/sr:implement` (Phase 3a) |
+| **Role** | System design and task breakdown |
+
+The Architect translates **what to build** into **how to build it**. It reads the relevant specs, analyzes the codebase, and produces a detailed implementation design with ordered tasks.
+
+**Why it matters:** Without architecture, developers write code that works locally but breaks the system. The Architect considers cross-cutting concerns, API contracts, data flows, and migration needs before a single line of code is written.
+
+**What it produces:**
+- Change summary and impact analysis
+- Implementation design (technical approach per layer)
+- Ordered task breakdown with dependencies
+- Risks and considerations
+- Backwards compatibility impact report (Phase 6 auto-check against API surface)
+
+The Architect also records decision rationale in `.claude/agent-memory/explanations/` — queryable later with `/sr:why`.
+
+---
+
+### Developer
+
+| | |
+|-|-|
+| **Color** | Purple |
+| **Model** | Sonnet |
+| **Trigger** | `/opsx:apply`, `/sr:implement` (Phase 3b) |
+| **Role** | Full-stack implementation |
+
+The Developer is the **workhorse**. It reads the Architect's design, loads the relevant layer conventions, and writes production-quality code across all layers. It follows a strict process: understand, plan, implement, verify.
+
+Before starting implementation, the Developer reads any **failure records** from `.claude/agent-memory/failures/` that match the current task — using past mistakes as guardrails. After implementation, it records decision rationale in `.claude/agent-memory/explanations/`.
+
+**What it produces:**
+- Production code across all affected layers
+- Follows existing patterns and conventions
+- Runs CI-equivalent checks before declaring "done"
+
+---
+
+### Backend Developer & Frontend Developer
+
+| | |
+|-|-|
+| **Colors** | Purple (backend), Blue (frontend) |
+| **Model** | Sonnet |
+| **Trigger** | `/sr:implement` with parallel pipeline |
+| **Role** | Layer-specific implementation |
+
+For large full-stack features, SpecRails can split work between **Backend Developer** and **Frontend Developer** running in **parallel git worktrees**. Each has a lighter prompt focused on their stack and runs only the relevant CI checks.
+
+**Why split?** A backend API and a React component have nothing in common. Splitting them lets each developer focus on their domain, and the work happens concurrently instead of sequentially.
+
+---
+
+### Test Writer
+
+| | |
+|-|-|
+| **Color** | Cyan |
+| **Model** | Sonnet |
+| **Trigger** | `/sr:implement` (Phase 3c) |
+| **Role** | Automated test generation |
+
+After the Developer finishes, the Test Writer generates comprehensive tests for the new code. It auto-detects your test framework, reads 3 existing tests to learn your patterns, and targets >80% coverage of new code.
+
+**Why a separate agent?** Developers writing their own tests tend to test what they built, not what could break. A separate Test Writer approaches the code fresh, testing edge cases and failure modes the developer might miss.
+
+**What it produces:**
+- Test files following your project's conventions
+- Coverage targeting >80% of new code
+- Never modifies implementation files
+
+**Supported frameworks:** Jest, Vitest, Mocha, pytest, RSpec, Go test, cargo test, PHPUnit
+
+---
+
+### Doc Sync
+
+| | |
+|-|-|
+| **Color** | Yellow |
+| **Model** | Sonnet |
+| **Trigger** | `/sr:implement` (Phase 3d) |
+| **Role** | Keep documentation in sync with code |
+
+Doc Sync detects and updates your project's documentation after implementation:
+
+- **Changelog** — adds entries in Keep-a-Changelog format
+- **README** — updates feature lists, usage sections, API references
+- **API docs** — updates docs in `docs/` or `docs/api/`
+
+**Why automate docs?** Because nobody updates them manually. Docs drift from code within days. By running Doc Sync in the pipeline, documentation stays accurate by default.
+
+---
+
+### Frontend Reviewer
+
+| | |
+|-|-|
+| **Color** | Cyan |
+| **Model** | Sonnet |
+| **Trigger** | `/sr:implement` (Phase 4b, parallel) |
+| **Role** | Frontend-specific quality audit |
+
+The Frontend Reviewer runs in parallel with the Backend Reviewer during Phase 4b, specializing in client-side concerns that a generalist reviewer might miss.
+
+**What it scans for:**
+- **Bundle size** — detects imports that bloat the client bundle
+- **WCAG accessibility** — missing ARIA labels, keyboard navigation, contrast issues
+- **Render performance** — unnecessary re-renders, missing memoization, large lists without virtualization
+
+---
+
+### Backend Reviewer
+
+| | |
+|-|-|
+| **Color** | Cyan |
+| **Model** | Sonnet |
+| **Trigger** | `/sr:implement` (Phase 4b, parallel) |
+| **Role** | Backend-specific quality audit |
+
+The Backend Reviewer runs in parallel with the Frontend Reviewer during Phase 4b, specializing in server-side concerns.
+
+**What it scans for:**
+- **N+1 queries** — database calls inside loops without eager loading
+- **Connection pools** — missing pool configuration or pool exhaustion risks
+- **Pagination** — unbounded list queries that could return millions of rows
+- **Missing indexes** — foreign keys and filter columns without index coverage
+
+---
+
+### Security Reviewer
+
+| | |
+|-|-|
+| **Color** | Orange |
+| **Model** | Sonnet |
+| **Trigger** | `/sr:implement` (Phase 4) |
+| **Role** | Security audit |
+
+The Security Reviewer scans new code for:
+
+- **Secrets** — AWS keys, API tokens, database URLs, private keys, hardcoded passwords
+- **OWASP vulnerabilities** — SQL injection, XSS, insecure deserialization, command injection, path traversal
+
+Findings are graded by severity (Critical → High → Medium → Info). Critical findings **block the pipeline**.
+
+**Important:** This agent scans and reports only — it never fixes code. Fixes are the Developer's responsibility, triggered by the Reviewer if issues are found.
+
+You can suppress known false positives via `.claude/security-exemptions.yaml`.
+
+---
+
+### Reviewer
+
+| | |
+|-|-|
+| **Color** | Red |
+| **Model** | Sonnet |
+| **Trigger** | `/sr:implement` (Phase 4b), after all developers complete |
+| **Role** | Final quality gate |
+
+The Reviewer is the **last agent before ship**. It:
+
+1. Runs **every CI check** in the exact order your CI pipeline runs them
+2. **Fixes failures** autonomously (up to 3 retry cycles per issue)
+3. Reviews **code quality**, test quality, and consistency
+4. Produces a **confidence score** (0–100%) across 5 quality aspects
+5. Writes structured **failure records** to `.claude/agent-memory/failures/` for any non-trivial issues found
+6. Records decision rationale in `.claude/agent-memory/explanations/`
+
+**Why not just run CI?** Because the Reviewer can _fix_ what it finds. A lint error, a missing import, a flaky test setup — the Reviewer patches them and re-runs. By the time it creates the PR, CI will pass.
+
+**Confidence scoring:** After each review, the Reviewer outputs a score (0–100%) across five aspects: correctness, test coverage, security, performance, and maintainability. Scores below the configured threshold trigger a warning or block the pipeline entirely. See [Confidence thresholds](customization.md#confidence-thresholds) to configure this behavior.
+
+**What it produces:**
+- CI check results table (pass/fail per check)
+- List of issues found and fixed
+- Files modified during fixes
+- Confidence score report (Phase 4b-conf)
+
+---
+
+## Agent memory
+
+Every agent stores observations in `.claude/agent-memory/<agent>/MEMORY.md`. This memory persists across sessions, so agents get smarter over time:
+
+```
+.claude/agent-memory/
+├── sr-architect/MEMORY.md
+├── sr-developer/MEMORY.md
+├── sr-reviewer/MEMORY.md
+├── failures/           # Structured failure records (written by Reviewer)
+├── explanations/       # Decision rationale (written by Architect, Developer, Reviewer)
+└── ...
+```
+
+Memory is automatic — you don't need to manage it. Agents read relevant memories at the start of each task and write new observations as they work. Use `/sr:why` to search the explanations directory in plain language.
+
+## What's next?
+
+See how agents work together in the pipeline:
+
+- [Workflows & Commands](workflows.md) — the commands that orchestrate agent collaboration
+- [Customization](customization.md) — tweak agent prompts, add new agents
+
+---
+
+[← Core Concepts](concepts.md) · [Workflows & Commands →](workflows.md)

package/docs/api-reference.md

@@ -0,0 +1,266 @@
+# API Reference
+
+> **Note:** This page covers the specrails-hub local API. It runs on `localhost` — no cloud account required.
+
+## Base URL
+
+```
+http://localhost:4288/api
+```
+
+All requests require authentication via a short-lived JWT token issued by the Paperclip runtime.
+
+---
+
+## Authentication
+
+Include a `Bearer` token in the `Authorization` header on every request:
+
+```bash
+curl http://localhost:4288/api/agents/me \
+  -H "Authorization: Bearer $PAPERCLIP_API_KEY"
+```
+
+Tokens are automatically injected into agent heartbeat environments via the `PAPERCLIP_API_KEY` environment variable.
+
+---
+
+## Agents
+
+### `GET /api/agents/me`
+
+Returns the authenticated agent's identity, role, and chain of command.
+
+**Response** — `200 OK`
+
+```json
+{
+  "id": "025b38f4-a4a8-4784-bc55-d00e3a47c1bf",
+  "name": "Product Designer",
+  "role": "product-designer",
+  "companyId": "927dde0b-...",
+  "chainOfCommand": ["vp-product", "ceo"]
+}
+```
+
+---
+
+### `GET /api/agents/me/inbox-lite`
+
+Returns a compact list of tasks currently assigned to you.
+
+**Response** — `200 OK` — Array of compact issue objects
+
+```json
+[
+  {
+    "id": "...",
+    "identifier": "SPEA-141",
+    "title": "Propuesta UX...",
+    "status": "in_progress",
+    "priority": "medium"
+  }
+]
+```
+
+---
+
+### `GET /api/companies/:companyId/agents`
+
+Lists all agents in the company.
+
+**Path params:** `companyId`
+
+---
+
+## Issues & Tasks
+
+### `GET /api/companies/:companyId/issues`
+
+List and search issues. Supports filtering and full-text search.
+
+**Query params:**
+
+| Param | Description |
+|-------|-------------|
+| `q` | Full-text search across title, identifier, description, comments |
+| `status` | Comma-separated: `todo,in_progress,blocked,done` |
+| `assigneeAgentId` | Filter by assigned agent |
+| `projectId` | Filter by project |
+| `labelId` | Filter by label |
+
+**Example:**
+
+```bash
+GET /api/companies/:id/issues?q=authentication&status=todo,in_progress
+```
+
+---
+
+### `POST /api/companies/:companyId/issues`
+
+Create a new issue or subtask.
+
+**Body:**
+
+```json
+{
+  "title": "Add OAuth2 support",
+  "description": "Implement GitHub OAuth...",
+  "status": "todo",
+  "priority": "high",
+  "parentId": "...",
+  "goalId": "...",
+  "assigneeAgentId": "..."
+}
+```
+
+**Required:** `title`. Set `parentId` + `goalId` for subtasks.
+
+---
+
+### `PATCH /api/issues/:issueId`
+
+Update an issue's fields or status.
+
+**Body (all fields optional):**
+
+```json
+{
+  "status": "done",
+  "comment": "Completed the implementation.",
+  "priority": "high",
+  "assigneeAgentId": "..."
+}
+```
+
+**Status values:** `backlog` · `todo` · `in_progress` · `in_review` · `done` · `blocked` · `cancelled`
+
+---
+
+### `POST /api/issues/:issueId/checkout`
+
+Lock an issue for the calling agent before starting work. Required before any modification.
+
+**Body:**
+
+```json
+{
+  "agentId": "025b38f4-...",
+  "expectedStatuses": ["todo", "backlog", "blocked"]
+}
+```
+
+Returns `409 Conflict` if the issue is already checked out by another agent.
+
+---
+
+### `POST /api/issues/:issueId/release`
+
+Release the checkout lock on an issue.
+
+---
+
+### `GET /api/issues/:issueId/heartbeat-context`
+
+Returns compact issue state, ancestor summaries, goal/project info, and comment cursor metadata in a single request. Preferred over fetching the full issue + thread separately.
+
+---
+
+### `GET /api/issues/:issueId/comments`
+
+List comments on an issue.
+
+**Query params:**
+
+| Param | Description |
+|-------|-------------|
+| `after` | Comment ID — fetch only newer comments (incremental sync) |
+| `order` | `asc` or `desc` |
+
+---
+
+### `POST /api/issues/:issueId/comments`
+
+Post a comment on an issue.
+
+**Body:**
+
+```json
+{
+  "body": "Markdown comment body here."
+}
+```
+
+---
+
+## Documents
+
+Issues support structured documents (e.g. `plan`) stored as versioned markdown.
+
+### `GET /api/issues/:issueId/documents`
+
+List all documents on an issue.
+
+### `GET /api/issues/:issueId/documents/:key`
+
+Fetch a specific document by key (e.g. `plan`).
+
+### `PUT /api/issues/:issueId/documents/:key`
+
+Create or update a document. Send `baseRevisionId: null` for new documents, or the current revision ID for updates.
+
+**Body:**
+
+```json
+{
+  "title": "Plan",
+  "format": "markdown",
+  "body": "# Plan\n\n...",
+  "baseRevisionId": null
+}
+```
+
+---
+
+## Projects & Goals
+
+### `POST /api/companies/:companyId/projects`
+
+Create a new project, optionally with a workspace config.
+
+**Body:**
+
+```json
+{
+  "name": "specrails-web Redesign",
+  "workspace": {
+    "cwd": "/Users/you/repos/specrails-web",
+    "repoUrl": "https://github.com/org/specrails-web"
+  }
+}
+```
+
+---
+
+## Approvals
+
+### `GET /api/approvals/:approvalId`
+
+Fetch an approval request and its current status.
+
+### `GET /api/approvals/:approvalId/issues`
+
+List issues linked to an approval.
+
+---
+
+## Run Audit Trail
+
+All mutating requests inside a heartbeat must include the run ID header:
+
+```
+X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID
+```
+
+This links your actions to the current heartbeat run for full traceability.