specrails-core 1.7.0 → 1.7.2

package/docs/changelog.md

@@ -0,0 +1,151 @@
+# Changelog
+
+All notable changes to SpecRails are listed here, newest first.
+
+---
+
+## [1.7.0](https://github.com/fjpulidop/specrails-core/compare/v1.6.1...v1.7.0) — 2026-03-20
+
+### New commands
+
+- **`/sr:merge-conflict`** — Smart merge conflict resolver. Analyzes conflict context, understands intent of both sides, and proposes the correct resolution with an explanation.
+- **`/sr:refactor-recommender` (enhanced)** — Now includes VPC context-aware scoring: debt items are ranked against persona Jobs/Pains/Gains for product-aligned prioritization.
+
+### Agents
+
+- **Performance Regression Detector** — New agent with CI workflow integration. Automatically detects performance regressions across runs and annotates PRs with regression reports.
+
+### Pipeline Monitor
+
+- **Zombie job detection and auto-termination** — The web-manager now detects stalled jobs and terminates them automatically to keep the queue healthy.
+
+---
+
+## [1.6.1](https://github.com/fjpulidop/specrails-core/compare/v1.6.0...v1.6.1) — 2026-03-20
+
+### Bug fixes
+
+- **Docs cleanup** — Removed DeckDex-contaminated documentation files that had been incorrectly included in the package.
+
+---
+
+## [1.6.0](https://github.com/fjpulidop/specrails-core/compare/v1.5.0...v1.6.0) — 2026-03-20
+
+### Improvements
+
+- **`/setup --update` template checksums** — The update command now checks command template checksums before overwriting, so manual customizations are detected and preserved rather than silently clobbered.
+
+---
+
+## [1.5.0](https://github.com/fjpulidop/specrails-core/compare/v1.4.0...v1.5.0) — 2026-03-20
+
+### New commands
+
+- **`/sr:opsx-diff`** — Change diff visualizer. Shows a structured, human-readable diff of what changed between two points in time across agents, commands, and templates.
+- **`/sr:telemetry`** — Agent telemetry and cost tracking. Reports per-agent token usage, run counts, and cost estimates with trend analysis.
+
+### Agents
+
+- **OSS Maintainer persona Kai** — Formalized the OSS Maintainer persona. Kai helps you think through open-source positioning, community management, and contributor onboarding.
+
+---
+
+## [1.4.0](https://github.com/fjpulidop/specrails-core/compare/v1.3.0...v1.4.0) — 2026-03-20
+
+### New commands
+
+- **`/sr:vpc-drift`** — Detects when your VPC personas have drifted from what your product actually delivers. Compares persona Jobs/Pains/Gains against the backlog and agent memory; produces per-persona alignment scores and concrete update recommendations.
+- **`/sr:memory-inspect`** — Inspect and manage agent memory directories. Shows per-agent stats, recent entries, and stale file detection with optional pruning.
+
+---
+
+## [1.3.0](https://github.com/fjpulidop/specrails-core/compare/v1.2.0...v1.3.0) — 2026-03-20
+
+### New commands
+
+- **`/sr:retry`** — Smart failure recovery. Resumes a failed `/sr:implement` pipeline from the last successful phase without restarting from scratch. Reads saved pipeline state to identify what completed, then re-executes only the remaining phases.
+
+### Agents
+
+- **Agent personality customization** — Edit agent prompts after installation to tune tone, priorities, and decision-making for your team's style. See [Customization](customization.md).
+
+---
+
+## [1.2.0](https://github.com/fjpulidop/specrails-core/compare/v1.1.0...v1.2.0) — 2026-03-20
+
+### Improvements
+
+- **`/sr:health-check` extended with static code analysis** — Now includes complexity metrics, dead code detection, and architectural pattern analysis in addition to test coverage and dependency health.
+
+---
+
+## [1.1.0](https://github.com/fjpulidop/specrails-core/compare/v1.0.1...v1.1.0) — 2026-03-20
+
+### Agents
+
+- **Doc Sync agent enhanced** — Added drift detection with severity levels. The agent now classifies documentation drift as `critical`, `major`, or `minor` and prioritizes accordingly.
+- **Test Writer wired into `/setup`** — New installations now include the Test Writer agent by default.
+- **Security Reviewer wired into `/setup`** — New installations now include the Security Reviewer agent by default.
+
+### Onboarding
+
+- **Onboarding v1 (RFC-001)** — Formalized the setup wizard flow and agent installation sequence.
+
+---
+
+## [1.0.1](https://github.com/fjpulidop/specrails-core/compare/v1.0.0...v1.0.1) — 2026-03-19
+
+### Bug fixes
+
+- Updated README and CLAUDE.md for the `specrails-core` rename.
+
+---
+
+## [1.0.0](https://github.com/fjpulidop/specrails-core/releases/tag/v1.0.0) — 2026-03-19
+
+Initial stable release.
+
+### ⚠ Breaking changes
+
+All commands renamed from `/<name>` to `/sr:<name>`. All agent files renamed from `<name>.md` to `sr-<name>.md`. Existing installations are auto-migrated by `update.sh`.
+
+### What shipped in 1.0
+
+**12 specialized agents**
+- Product Manager, Architect, Developer, Backend Developer, Frontend Developer
+- Test Writer, Reviewer, Backend Reviewer, Frontend Reviewer
+- Security Reviewer, Doc Sync, Product Analyst
+
+**11 commands**
+- `/sr:implement` — full 8-phase pipeline (architecture → code → tests → docs → review → PR)
+- `/sr:batch-implement` — parallel multi-feature orchestrator using git worktrees
+- `/sr:health-check` — codebase quality dashboard with regression detection
+- `/sr:compat-check` — backwards compatibility analyzer and migration guide generator
+- `/sr:product-backlog` — VPC-scored backlog view with safe implementation ordering
+- `/sr:update-product-driven-backlog` — AI-powered product discovery via personas
+- `/sr:refactor-recommender` — tech debt scanner ranked by impact/effort
+- `/sr:why` — semantic search over agent decision records
+- `/sr:retry` — smart failure recovery (added in 1.3)
+- `/sr:vpc-drift` — persona drift detection (added in 1.4)
+- `/sr:propose-spec` — structured feature proposal generator
+
+**Pipeline Monitor (web-manager)**
+- Real-time job queue dashboard
+- Live log streaming via WebSocket
+- Analytics: daily throughput, status breakdown, job history
+- Chat panel for in-context help
+
+**Update system**
+- Content-aware selective updates — only changed files are overwritten
+- Customizations (agent prompts, personas, layer rules) are preserved across updates
+- `update.sh` auto-migrates command namespace changes
+
+**Distribution**
+- `npx specrails@latest init`
+- `curl | bash` installer
+- `--root-dir` flag for monorepo support
+- `--yes` flag for non-interactive CI installs
+
+---
+
+[← Updating](updating.md)

package/docs/concepts.md

@@ -0,0 +1,183 @@
+# 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 `/sr:why` to search this memory in plain language:
+
+```
+/sr: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 `/sr:product-backlog` 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

@@ -0,0 +1,320 @@
+# Customization
+
+Everything SpecRails generates is editable markdown. Here's how to adapt it to your project.
+
+## What gets generated
+
+After running `/setup`, your `.claude/` directory looks like this:
+
+```
+.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 JSON/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
+
+Each agent specifies its model in YAML frontmatter:
+
+```yaml
+---
+model: sonnet
+---
+```
+
+Available 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)
+
+Change the model by editing the frontmatter.
+
+### 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 `/sr:compat-check --save` to snapshot your current API surface as a baseline:
+
+```
+/sr:compat-check --save
+```
+
+This writes the current API surface to `.claude/compat-baseline.json`. Future runs of `/sr: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)