setup

name	setup
description	Initialize a project with the SpecRails workflow. Generates project-specific data files: .specrails/config.yaml, personas, memory directories, backlog config, and CLAUDE.md snippet. Does NOT copy logic files — the sr plugin already provides all agents, skills, and commands.
license	MIT
compatibility	Requires git.
metadata	{"author":"specrails","version":"1.0"}

SpecRails Setup

Initialize this project with the specrails workflow by generating project-specific configuration files. The sr plugin already provides all agents, skills, and commands — this skill generates the data layer that adapts the workflow to your project.

Input: $ARGUMENTS — optional flags:

• --name <name> — project name (defaults to directory name)
• --stack <stack> — primary tech stack description (e.g. "Next.js + Rails + PostgreSQL")
• --domain <domain> — product domain (e.g. "SaaS analytics", "developer tooling")
• --skip-claude-md — skip CLAUDE.md generation

---

Phase 1: Gather Project Context

If $ARGUMENTS is empty, interactively gather:

1. Project name — default: current directory basename
2. Tech stack — ask: "What is your primary stack? (e.g. Next.js + Rails, Django + React, Go + gRPC)"
3. Domain — ask: "What domain is this product in? (e.g. developer tooling, SaaS analytics, e-commerce)"
4. Backend layer — ask: "What are your backend technologies?" (can be same as stack)
5. Frontend layer — ask: "What are your frontend technologies?" (can be same as stack)
6. CI commands — ask: "What command runs your full CI? (e.g. npm test, make test, ./scripts/ci.sh)"

If --name, --stack, --domain flags are provided, use those values and skip the interactive prompts.

Confirm the gathered values before proceeding:

About to set up specrails for:
  Project: <name>
  Stack: <stack>
  Domain: <domain>
  Backend: <backend>
  Frontend: <frontend>
  CI: <ci_command>

Proceed? [Y/n]

---

Phase 2: Create Directory Structure

mkdir -p .specrails/personas
mkdir -p .claude/agent-memory/sr-architect
mkdir -p .claude/agent-memory/sr-developer
mkdir -p .claude/agent-memory/sr-reviewer
mkdir -p .claude/agent-memory/sr-product-manager
mkdir -p .claude/agent-memory/sr-product-analyst
mkdir -p .claude/agent-memory/sr-test-writer
mkdir -p .claude/agent-memory/sr-doc-sync
mkdir -p .claude/agent-memory/sr-merge-resolver
mkdir -p .claude/agent-memory/sr-security-reviewer
mkdir -p .claude/agent-memory/sr-backend-developer
mkdir -p .claude/agent-memory/sr-frontend-developer
mkdir -p .claude/agent-memory/sr-backend-reviewer
mkdir -p .claude/agent-memory/sr-frontend-reviewer
mkdir -p .claude/agent-memory/sr-performance-reviewer
mkdir -p .claude/agent-memory/explanations
mkdir -p .claude/agent-memory/failures

---

Phase 3: Generate .specrails/config.yaml

Write the project configuration file:

# SpecRails Project Configuration
# Generated by /specrails:setup — edit this file to customize your workflow

project:
  name: "<PROJECT_NAME>"
  domain: "<DOMAIN>"

stack:
  description: "<STACK>"
  backend: "<BACKEND>"
  frontend: "<FRONTEND>"

ci:
  command: "<CI_COMMAND>"

backlog:
  provider: local  # options: github, local, none
  write: true       # whether agents can create issues

openspec:
  specs_dir: openspec/specs
  changes_dir: openspec/changes

Replace <PROJECT_NAME>, <DOMAIN>, <STACK>, <BACKEND>, <FRONTEND>, <CI_COMMAND> with gathered values.

---

Phase 4: Generate .specrails/personas/ starter files

Create two starter persona files.

File: .specrails/personas/primary-user.md

---
name: Primary User
role: <role based on domain>
---

# Value Proposition Canvas

## Customer Jobs (what they need to accomplish)
- [ ] Job 1 — describe a primary task this persona needs to do
- [ ] Job 2 — describe another key task
- [ ] Job 3 — describe a supporting task

## Pains (frustrations, risks, obstacles)
| Pain | Severity |
|------|----------|
| Pain 1 description | Critical |
| Pain 2 description | High |
| Pain 3 description | Medium |

## Gains (desired outcomes, benefits)
| Gain | Impact |
|------|--------|
| Gain 1 description | High |
| Gain 2 description | Medium |

---
*Edit this file to reflect your actual user persona. Run `/specrails:get-backlog-specs` to see how ideas align with this persona.*

File: .specrails/personas/maintainer.md

---
name: Maintainer / Developer
role: Engineer or team member who builds and maintains the product
---

# Value Proposition Canvas

## Customer Jobs
- [ ] Implement features reliably without breaking existing behavior
- [ ] Understand codebase context quickly
- [ ] Get AI assistance that follows project conventions

## Pains
| Pain | Severity |
|------|----------|
| AI agents that ignore project conventions | High |
| Having to re-explain context every session | High |
| Inconsistent code patterns across features | Medium |

## Gains
| Gain | Impact |
|------|--------|
| AI-generated code that passes CI first time | High |
| Automated documentation kept in sync | Medium |
| Consistent architecture across features | Medium |

---
*Edit this file to reflect your actual maintainer persona.*

---

Phase 5: Generate .specrails/backlog-config.json

{
  "BACKLOG_PROVIDER": "local",
  "BACKLOG_WRITE": true,
  "BACKLOG_LABEL": "product-driven-backlog"
}

---

Phase 6: Generate .specrails/security-exemptions.yaml

# Security Exemptions for sr:security-reviewer
# Add patterns here that should be suppressed from the security scan
exemptions:
  secrets: []
    # - pattern: "PATTERN_REGEX"
    #   reason: "Why this is a false positive"
    #   file: "path/to/file.ts"
  vulnerabilities: []
    # - rule: "sql-injection"
    #   file: "src/legacy/old-query.ts"
    #   reason: "Legacy code, no user input reaches this path"
    #   expiry: "2026-12-31"

---

Phase 7: CLAUDE.md snippet (optional)

Unless --skip-claude-md is specified:

Check if a CLAUDE.md exists at the project root.

If CLAUDE.md exists: Append the following snippet to the end:

If CLAUDE.md does not exist: Create it with just the snippet:

## SpecRails Workflow

This project uses the SpecRails agent workflow system (sr plugin).

### Stack
<STACK>

### Architecture
<!-- Add your architecture diagram or description here -->

### CI Commands
```bash
<CI_COMMAND>

Agents

The following agents are available via the sr plugin:

• /specrails:implement — full pipeline: architect → developer → reviewer
• /specrails:get-backlog-specs — view prioritized backlog
• /specrails:health-check — run full codebase health check
• /specrails:opsx:ff → /specrails:opsx:apply → /specrails:opsx:archive — OpenSpec workflow

Warnings

Replace `<STACK>` and `<CI_COMMAND>` with gathered values.

---

## Phase 8: Summary

Print a setup summary:

SpecRails Setup Complete

Project: <PROJECT_NAME> Stack:

Files created: .specrails/config.yaml .specrails/personas/primary-user.md .specrails/personas/maintainer.md .specrails/security-exemptions.yaml .specrails/backlog-config.json .claude/agent-memory/ (14 agent directories) CLAUDE.md (created or updated)

Next steps:

1. Edit .specrails/config.yaml to refine your project settings
2. Edit .specrails/personas/*.md to accurately describe your users
3. Run /specrails:get-backlog-specs to see backlog ideas for your domain
4. Run /specrails:implement #1 to start implementing a GitHub Issue
5. Run /specrails:opsx:ff to fast-forward an OpenSpec change