specrails-core 5.6.0 → 6.0.0

package/docs/concepts.md

@@ -1,183 +0,0 @@
-# Core Concepts
-
-Before diving into commands and agents, it helps to understand the ideas behind SpecRails.
-
-## The pipeline
-
-SpecRails organizes development as a **linear pipeline** where each phase produces artifacts for the next:
-
-```
-Discovery → Architecture → Implementation → Quality → Ship
-```
-
-| Phase | Agent | Input | Output |
-|-------|-------|-------|--------|
-| Discovery | Product Manager | User personas, market research | Feature ideas with VPC scores |
-| Architecture | Architect | Feature spec | Design doc + task breakdown |
-| Implementation | Developer(s) | Tasks + conventions | Production code |
-| Quality | Test Writer → Doc Sync → Security → Reviewer | Code changes | Tests, docs, security report, CI pass |
-| Ship | Reviewer | Verified code | Pull Request |
-
-Each phase has a **dedicated agent** with a narrow scope. Agents don't step on each other — the architect never writes code, the developer never runs CI, the reviewer never designs architecture.
-
-## Product-driven development
-
-Most AI coding tools start from code. SpecRails starts from **users**.
-
-### Value Proposition Canvas (VPC)
-
-Every feature is evaluated against user personas using the [Value Proposition Canvas](https://www.strategyzer.com/library/the-value-proposition-canvas) framework:
-
-```
-┌─────────────────────────────────┐
-│        Customer Segment         │
-│  ┌─────────┬────────┬────────┐  │
-│  │  Jobs   │ Pains  │ Gains  │  │
-│  └─────────┴────────┴────────┘  │
-└─────────────────────────────────┘
-                 ↕ fit
-┌─────────────────────────────────┐
-│       Value Proposition         │
-│  ┌─────────┬────────┬────────┐  │
-│  │Products │ Pain   │ Gain   │  │
-│  │& Svc    │Relievers│Creators│  │
-│  └─────────┴────────┴────────┘  │
-└─────────────────────────────────┘
-```
-
-- **Customer Jobs** — what your users need to accomplish (functional, social, emotional)
-- **Pains** — frustrations, risks, and obstacles they face
-- **Gains** — outcomes and benefits they desire
-
-Each persona scores features 0–5 on how well they address their needs. Features with high scores across multiple personas get prioritized.
-
-### Personas
-
-During setup, SpecRails generates **user personas** based on competitive research. Each persona has a complete VPC profile. When the Product Manager proposes features, they're evaluated against these personas — not gut feelings.
-
-See [Customization → Personas](customization.md#personas) for how to edit and add personas.
-
-## Agents, not prompts
-
-SpecRails doesn't use generic prompts. It uses **specialized agents** — each with:
-
-- A **narrow role** (architect designs, developer codes, reviewer validates)
-- A **persistent memory** that grows across sessions
-- **Layer-aware conventions** loaded per file path
-- A specific **AI model** matched to the task complexity
-
-This specialization means each agent is optimized for its job. The architect thinks in terms of systems and trade-offs. The developer thinks in terms of implementation patterns. The reviewer thinks in terms of CI pipelines and edge cases.
-
-See [Agents](agents.md) for the full roster.
-
-## OpenSpec
-
-SpecRails uses [OpenSpec](https://openspec.dev) as its specification system. OpenSpec provides a structured way to go from idea to implementation:
-
-```
-Spec (source of truth)
-  └── Change
-        ├── Proposal     — what and why
-        ├── Design       — how (technical approach)
-        ├── Tasks        — ordered implementation steps
-        ├── Context Bundle — files the developer needs
-        └── Delta Spec   — spec updates after implementation
-```
-
-The architect reads specs before designing. The developer reads the design before coding. After shipping, the change is archived and the spec is updated.
-
-This creates a **paper trail** from product decision to shipped code.
-
-## Layer conventions
-
-Different parts of your codebase have different rules. Your backend might use snake_case while your frontend uses camelCase. Your API layer might require OpenAPI annotations while your tests just need clear naming.
-
-SpecRails detects your **architecture layers** during setup and generates per-layer convention files:
-
-```
-.claude/rules/
-├── backend.md      # Loaded for backend/**
-├── frontend.md     # Loaded for frontend/**
-└── shared.md       # Loaded for shared/**
-```
-
-Agents automatically load the right conventions based on which files they're modifying. No manual context-switching needed.
-
-## Agent memory
-
-Each agent maintains a **persistent memory** at `.claude/agent-memory/<agent>/MEMORY.md`. This memory survives across sessions, so agents learn from past work:
-
-- The architect remembers architectural decisions and trade-offs
-- The developer remembers patterns and gotchas in your codebase
-- The reviewer remembers common CI failures and fixes
-
-Memory is automatic — agents write observations as they work and read them in future sessions.
-
-In addition to per-agent memory, two shared directories accumulate institutional knowledge over time:
-
-```
-.claude/agent-memory/
-├── failures/       # Structured failure records (see Failure Learning Loop)
-└── explanations/   # Decision rationale records (see Explanation Recording)
-```
-
-## Confidence Scoring
-
-After every review cycle, the Reviewer outputs a **confidence score** (0–100%) across five quality aspects:
-
-| Aspect | What it measures |
-|--------|-----------------|
-| Correctness | Does the implementation match the spec? |
-| Test Coverage | Are edge cases and failure modes covered? |
-| Security | No secrets, injections, or OWASP vulnerabilities? |
-| Performance | No obvious bottlenecks introduced? |
-| Maintainability | Is the code readable, consistent, and well-structured? |
-
-The pipeline behavior at Phase 4b-conf is controlled by `.claude/confidence-config.json`. Scores below the configured threshold can warn, block, or require an explicit override. See [Confidence thresholds](customization.md#confidence-thresholds).
-
-## Failure Learning Loop
-
-When the Reviewer finds a non-trivial issue during Phase 4b, it writes a structured failure record to `.claude/agent-memory/failures/`. Each record captures:
-
-```json
-{
-  "error_type": "missing-index",
-  "root_cause": "Foreign key column added without a corresponding index",
-  "prevention_rule": "Always create an index for every new foreign key column"
-}
-```
-
-Before starting implementation, the Developer reads matching failure records as **guardrails** — so the same class of mistake is not repeated. Over time this creates an institutional memory of what has gone wrong and how to avoid it.
-
-## Explanation Recording
-
-The Architect, Developer, and Reviewer record **decision rationale** in `.claude/agent-memory/explanations/` as they work. These records capture the "why" behind implementation choices — which library was chosen and why, which trade-off was accepted, which alternative was rejected.
-
-Use `/specrails:why` to search this memory in plain language:
-
-```
-/specrails:why "why did we switch to event sourcing"
-```
-
-This gives you an audit trail from product decision to implementation choice, without digging through git history or asking the original author.
-
-## Dependency-Aware Ordering
-
-When `/specrails:get-backlog-specs` is run, the Product Analyst parses `Prerequisites:` fields from GitHub Issue bodies and builds a **dependency DAG** (directed acyclic graph). It then:
-
-1. Detects cycles and reports them as errors (circular dependencies block ordering)
-2. Computes a safe implementation order via topological sort
-3. Presents the top 3 Wave 1 issues — features with no unimplemented prerequisites
-
-This prevents shipping features that depend on other features not yet built, and makes sprint planning safe by default.
-
-## What's next?
-
-Now that you understand the concepts, meet the agents:
-
-- [Agents](agents.md) — every agent explained in detail
-- [Workflows & Commands](workflows.md) — the commands that orchestrate the pipeline
-
----
-
-[← Getting Started](getting-started.md) · [Agents →](agents.md)

package/docs/customization.md

@@ -1,363 +0,0 @@
-# Customization
-
-Everything SpecRails generates is editable markdown. Here's how to adapt it to your project.
-
-## What gets generated
-
-After running `/specrails:enrich`, your project data lives in `.specrails/` (plugin method) or `.claude/` (scaffold method):
-
-**Plugin method — `.specrails/`**
-
-```
-.specrails/
-├── config.yaml           # Stack, CI commands, git workflow
-├── personas/             # VPC user personas
-├── rules/                # Per-layer conventions
-├── agent-memory/         # Persistent agent memory
-└── pipeline/             # In-flight feature state
-```
-
-**Scaffold method — `.claude/`**
-
-```
-.claude/
-├── agents/               # Agent prompts (one per agent)
-├── commands/             # Workflow commands
-├── rules/                # Per-layer conventions
-├── skills/               # OpenSpec skills
-├── agent-memory/         # Persistent agent memory
-├── settings.json         # Permissions
-└── security-exemptions.yaml
-```
-
-All files are standard Markdown or YAML. Edit them directly — no special tools needed.
-
-## Agents
-
-Agent prompts live in `.claude/agents/<name>.md`. Each file is the full system prompt for that agent.
-
-### Editing an agent
-
-Open any agent file and modify it. Common customizations:
-
-- **Add domain knowledge** — tell the architect about your microservice boundaries, or the developer about your ORM patterns
-- **Change behavior** — make the reviewer stricter, or the test writer target a different coverage threshold
-- **Add constraints** — "never use library X", "always use repository pattern for data access"
-
-Example — adding a constraint to the developer:
-
-```markdown
-## Additional Rules
-- Always use the repository pattern for database access
-- Never import directly from internal packages — use the public API
-```
-
-### Agent model selection
-
-Agent models are controlled by `.specrails/agents.yaml`, generated automatically when you first run `/specrails:enrich`. The model preset can also be set ahead of time in `.specrails/install-config.yaml` (written by the TUI installer).
-
-```yaml
-# specrails agent configuration
-# Valid models: opus, sonnet, haiku
-
-defaults:
-  model: sonnet
-
-agents:
-  sr-architect:
-    model: sonnet
-  sr-product-manager:
-    model: opus
-  sr-product-analyst:
-    model: haiku
-  # ... all 14 agents listed
-```
-
-**Valid models:**
-- `opus` — best for creative/strategic tasks (Product Manager)
-- `sonnet` — balanced for implementation tasks (most agents)
-- `haiku` — fast and cheap for analysis tasks (Product Analyst)
-
-**Precedence rules:**
-1. Per-agent entry in `agents:` section overrides everything
-2. `defaults.model` applies to any agent not explicitly listed
-3. Template hard-coded value is the fallback when no config exists
-
-**Applying config changes:** After editing `.specrails/agents.yaml`, run `/specrails:reconfig` to update the generated agent files without re-running the full setup wizard:
-
-```
-/specrails:reconfig
-```
-
-Output example:
-```
-Updated 1 agent(s):
-  sr-developer: sonnet → opus
-
-Unchanged (13): sr-architect, sr-reviewer, ...
-```
-
-**Important:** `/specrails:reconfig` wins over direct edits to `.claude/agents/sr-*.md`. If you edit an agent file directly, that change will be overwritten the next time you run reconfig or setup. For permanent per-agent overrides, edit `.specrails/agents.yaml` instead.
-
-### Adding a new agent
-
-Create a new file in `.claude/agents/`:
-
-```markdown
----
-model: sonnet
----
-
-# My Custom Agent
-
-You are a specialized agent for [your purpose].
-
-## Role
-[What this agent does]
-
-## Rules
-[What this agent must follow]
-```
-
-Reference it from a command using the Agent tool with `subagent_type: "your-agent-name"`.
-
----
-
-## Layer conventions
-
-Convention files live in `.claude/rules/<layer>.md`. They're loaded automatically based on file paths.
-
-### How rules are scoped
-
-Each rule file has a `paths` field in its frontmatter:
-
-```yaml
----
-paths:
-  - "backend/**"
----
-```
-
-When an agent modifies a file matching `backend/**`, this rule is automatically loaded into its context. No manual loading needed.
-
-### Editing conventions
-
-Add or modify rules for any layer:
-
-```markdown
----
-paths:
-  - "src/api/**"
----
-
-# API Layer Conventions
-
-- All endpoints must return JSON with `{ data, error, meta }` envelope
-- Use middleware for authentication — never check tokens in handlers
-- Rate limiting is handled at the gateway level — don't implement it per-endpoint
-- Error responses must include a machine-readable `code` field
-```
-
-### Adding a new layer
-
-Create a new file in `.claude/rules/`:
-
-```markdown
----
-paths:
-  - "infrastructure/**"
----
-
-# Infrastructure Conventions
-
-- Use Terraform for all cloud resources
-- Never hardcode region or account IDs
-- All resources must be tagged with `team` and `environment`
-```
-
----
-
-## Personas
-
-Persona files live in `.claude/agents/` (generated during setup). Each persona is a complete VPC profile used for feature evaluation.
-
-### Editing a persona
-
-Personas have three key sections for feature scoring:
-
-```markdown
-### Customer Jobs
-| Type | Job |
-|------|-----|
-| Functional | Deploy changes without downtime |
-| Social | Be seen as technically competent by the team |
-| Emotional | Feel confident that deploys won't break production |
-
-### Pains
-| Severity | Pain |
-|----------|------|
-| High | Manual deploys take 2+ hours |
-| Medium | Rollback process is undocumented |
-
-### Gains
-| Impact | Gain |
-|--------|------|
-| High | Zero-downtime deployments |
-| Medium | Automated rollback on failure |
-```
-
-Edit jobs, pains, and gains to match your actual users. The more accurate these are, the better the Product Manager's recommendations.
-
-### Adding a persona
-
-Create a new persona file following the template structure. Include:
-
-1. **Profile** — name, role, age range, behaviors
-2. **Customer Jobs** — functional, social, and emotional jobs
-3. **Pains** — graded by severity (High/Medium/Low)
-4. **Gains** — graded by impact (High/Medium/Low)
-5. **Key Insight** — the single most important unmet need
-
----
-
-## Confidence thresholds
-
-The confidence gate at Phase 4b-conf is controlled by `.claude/confidence-config.json`:
-
-```json
-{
-  "thresholds": {
-    "overall": 80,
-    "correctness": 85,
-    "test_coverage": 75,
-    "security": 90,
-    "performance": 70,
-    "maintainability": 75
-  },
-  "on_failure": "block"
-}
-```
-
-| `on_failure` value | Behavior |
-|--------------------|---------|
-| `"block"` | Pipeline stops; fix required before PR creation |
-| `"warn"` | Pipeline continues; warning added to PR description |
-| `"override"` | Always continue regardless of score |
-
-Adjust thresholds per aspect to match your team's quality bar. Set `"on_failure": "warn"` during initial rollout if you want visibility without blocking.
-
----
-
-## Layer reviewers
-
-The Frontend Reviewer and Backend Reviewer agents live in `.claude/agents/`:
-
-- `.claude/agents/frontend-reviewer.md`
-- `.claude/agents/backend-reviewer.md`
-
-Customize them the same way as any other agent — add domain-specific checks, change what's flagged as a finding, or adjust severity thresholds.
-
-Example — adding a project-specific frontend rule:
-
-```markdown
-## Additional Checks
-- Flag any component that fetches data directly (use React Query hooks instead)
-- Warn on inline styles with more than 3 properties (extract to CSS module)
-```
-
-Both agents run in parallel during Phase 4b and feed their findings into the generalist Reviewer's final report.
-
----
-
-## Backwards compatibility baseline
-
-Use `/specrails:compat-check --save` to snapshot your current API surface as a baseline:
-
-```
-/specrails:compat-check --save
-```
-
-This writes the current API surface to `.claude/compat-baseline.json`. Future runs of `/specrails:compat-check` and the Architect's Phase 6 auto-check compare against this baseline to detect breaking changes. Re-run `--save` after any intentional breaking release to advance the baseline.
-
----
-
-## Security exemptions
-
-The Security Reviewer can produce false positives. Suppress known safe patterns in `.claude/security-exemptions.yaml`:
-
-```yaml
-exemptions:
-  - pattern: "NEXT_PUBLIC_.*"
-    reason: "Next.js public env vars are intentionally client-exposed"
-  - file: "tests/fixtures/mock-keys.json"
-    reason: "Test fixtures with fake keys"
-  - severity_override:
-      pattern: "console\\.log"
-      from: "medium"
-      to: "info"
-      reason: "Dev-only logging, stripped in production build"
-```
-
----
-
-## Settings
-
-`.claude/settings.json` controls tool permissions:
-
-```json
-{
-  "permissions": {
-    "allow": [
-      "Read", "Write", "Edit",
-      "Glob", "Grep", "Agent",
-      "Skill", "ToolSearch"
-    ]
-  }
-}
-```
-
-Add or remove tools to control what agents can do. The update system preserves your permission customizations when pulling new versions.
-
----
-
-## Agent memory
-
-Agent memory at `.claude/agent-memory/<agent>/MEMORY.md` is automatic but editable.
-
-### Clearing memory
-
-Delete entries from an agent's `MEMORY.md` to reset specific knowledge:
-
-```bash
-# Clear all architect memory
-> .claude/agent-memory/architect/MEMORY.md
-
-# Or edit selectively
-code .claude/agent-memory/architect/MEMORY.md
-```
-
-### Seeding memory
-
-Pre-populate agent memory with project knowledge:
-
-```markdown
-# Memory Index
-
-## Architecture decisions
-- [adr-001.md](adr-001.md) — We use event sourcing for the order domain
-
-## Known gotchas
-- [gotcha-db.md](gotcha-db.md) — PostgreSQL connection pool maxes at 20 in dev
-```
-
-This is useful when onboarding SpecRails to a complex project.
-
----
-
-## What's next?
-
-- [Updating](updating.md) — keep SpecRails up to date without losing your customizations
-
----
-
-[← Workflows & Commands](workflows.md) · [Updating →](updating.md)