specrails-core 5.6.0 → 6.0.1

package/docs/migration-guide.md

@@ -1,140 +0,0 @@
-# Migration Guide: Switching to Local Tickets
-
-This guide is for teams currently using GitHub Issues or JIRA as their specrails backlog provider who want to switch to the built-in local ticket system.
-
-Switching is optional. GitHub Issues and JIRA remain fully supported. Local tickets are the recommended default for new projects.
-
----
-
-## Should you switch?
-
-**Switch to local tickets if:**
-- Your team prefers a simple, zero-dependency setup
-- You want tickets version-controlled alongside your code
-- You don't need GitHub/JIRA for other workflows (project boards, external stakeholders)
-
-**Stay on GitHub Issues / JIRA if:**
-- Other teams or stakeholders manage tickets in those tools
-- You rely on GitHub Projects, Milestones, or JIRA sprints
-- You want PR auto-close on issue merge (requires GitHub Issues)
-
----
-
-## Step 1: Switch the provider
-
-Edit `.specrails/backlog-config.json` in your project root:
-
-```json
-{
-  "provider": "local",
-  "write_access": true,
-  "git_auto": true
-}
-```
-
-Then initialize the ticket store if it doesn't exist yet:
-
-```bash
-# Inside Claude Code or Codex
-/specrails:implement --setup-local-tickets
-```
-
-Or create the file manually:
-
-```bash
-cat > .specrails/local-tickets.json << 'EOF'
-{
-  "schema_version": "1.0",
-  "revision": 0,
-  "last_updated": null,
-  "next_id": 1,
-  "tickets": {}
-}
-EOF
-```
-
----
-
-## Step 2: Import existing issues (one-time migration)
-
-### From GitHub Issues
-
-Use the `sr:migrate-from-github` command (requires `gh` CLI):
-
-```bash
-# Inside Claude Code
-/specrails:migrate-from-github
-```
-
-This command:
-1. Fetches all open issues labeled `product-driven-backlog` (the label specrails uses)
-2. Maps GitHub issue fields to local ticket schema:
-   - `number` → `id` (uses next available local ID)
-   - `title` → `title`
-   - `body` → `description`
-   - `labels` → `labels`
-   - `state: open` → `status: todo`
-3. Writes each ticket to `local-tickets.json`
-4. Prints a summary: `Imported 14 tickets from GitHub Issues`
-
-To import all open issues regardless of label:
-
-```bash
-/specrails:migrate-from-github --all
-```
-
-To do a dry run (preview without writing):
-
-```bash
-/specrails:migrate-from-github --dry-run
-```
-
-**After import:** Your GitHub Issues are unchanged. The migration is additive — it only creates local tickets. You can continue using GitHub Issues in parallel until you're ready to stop.
-
-### From JIRA
-
-Use the `sr:migrate-from-jira` command (requires `jira` CLI or REST API credentials in `.specrails/backlog-config.json`):
-
-```bash
-# Inside Claude Code
-/specrails:migrate-from-jira
-```
-
-This command:
-1. Fetches all open issues from the configured JIRA project
-2. Maps JIRA fields to local ticket schema:
-   - Issue key (`PROJECT-123`) → stored in `metadata.jira_key`
-   - `summary` → `title`
-   - `description` → `description`
-   - `priority` → `priority` (Critical/High/Medium/Low mapped directly)
-   - `status: To Do / Backlog` → `status: todo`
-   - `status: In Progress` → `status: in_progress`
-   - `labels` → `labels`
-3. Writes each ticket to `local-tickets.json`
-
-The original JIRA key is preserved in `metadata.jira_key` so you can cross-reference during the transition.
-
----
-
-## Step 3: Regenerate commands (optional but recommended)
-
-Command templates are generated at `/specrails:enrich` time with provider-specific instructions baked in. After switching providers, regenerate them so commands use the local file operations instead of GitHub/JIRA CLI calls:
-
-```bash
-npx specrails-core@latest init --root-dir .
-> /specrails:enrich --update
-```
-
-The `--update` flag regenerates only the backlog commands (`get-backlog-specs`, `auto-propose-backlog-specs`, `implement`) without re-running the full stack analysis.
-
----
-
-## Rollback
-
-To revert to GitHub Issues:
-
-1. Edit `.specrails/config.yaml` (or `.specrails/backlog-config.json` for scaffold installs) and set `provider: github`
-2. Re-run `/specrails:enrich --update` to regenerate commands
-3. Your `local-tickets.json` is preserved — switch back any time
-
-Local tickets and external provider data are independent. Switching providers does not delete tickets from either system.

package/docs/playbook-oss-maintainer.md

@@ -1,112 +0,0 @@
-# OSS Maintainer Workflow
-
-> For maintainers who want to merge AI-generated PRs quickly without sacrificing quality — and who want to define the conditions under which they trust the pipeline's output.
-
-## The review burden problem
-
-Without guardrails, AI-generated code requires the same review depth as human code. You read every file, verify every edge case, and check every type. The throughput advantage of automation disappears at review time.
-
-specrails adds observable quality signals to every PR: a confidence score from the Reviewer, a security scan from the Security Reviewer, CI results (lint, typecheck, tests), and structured reviewer annotations. These signals are machine-generated and reproducible — not "it looks fine to me."
-
-The goal is not to eliminate code review. It is to define the conditions under which you can trust those signals and reduce manual review to **intent verification**: does this PR do what the original issue asked for? Everything else — correctness, type safety, test coverage, security posture — is covered by the pipeline.
-
-## Setting confidence thresholds
-
-The Reviewer agent scores its own output on a 0–100 scale before creating the PR. You control what happens when that score falls below your threshold via `.claude/confidence-config.json`:
-
-```json
-{
-  "threshold": 85,
-  "on_below_threshold": "block",
-  "aspects": {
-    "security": { "threshold": 90, "on_below_threshold": "block" },
-    "correctness": { "threshold": 80, "on_below_threshold": "warn" }
-  }
-}
-```
-
-The three modes for `on_below_threshold`:
-
-- **`block`** — the pipeline stops before creating the PR. The Reviewer surfaces its concerns and waits. You review the specific low-confidence areas, then add an override comment to the issue to resume.
-- **`warn`** — the pipeline continues and creates the PR, but the PR description includes a prominently flagged section listing the low-confidence aspects and the Reviewer's reasoning.
-- **`override`** — used by the maintainer at runtime. Add a comment to the issue to explicitly bypass a block for a specific run.
-
-**Recommended starting thresholds for OSS projects**: overall 85 with `block`, security aspect 90 with `block`. The correctness aspect at 80 with `warn` is a reasonable starting point — correctness issues are easier to catch in review than security issues.
-
-Set thresholds based on your risk tolerance, not aspirationally. A threshold of 95 that constantly blocks the pipeline trains you to lower it. A threshold of 85 that rarely blocks but surfaces genuine concerns trains you to trust it.
-
-## Layer convention files as policy
-
-`.claude/rules/frontend.md` is read by the Frontend Reviewer before every review pass. The equivalent files exist for other layers your setup detected. These files are not documentation — they are review policy that the Reviewer enforces on every PR.
-
-Put rules in convention files that you would enforce in a human code review:
-- Naming conventions that aren't captured by ESLint (`PascalCase` for component files, `use-` prefix for hook files)
-- Required patterns (`cn()` for class merging, `@/` path alias for all imports)
-- Forbidden patterns (inline styles, hardcoded color values, `any` types)
-- Structural requirements (exported functions must have explicit return types)
-
-What doesn't belong in convention files:
-- Style preferences that ESLint or Prettier already enforce (semicolons, trailing commas, quote style)
-- Rules that require runtime context to evaluate ("don't use this API in production environments")
-- Aspirational guidelines that you don't actually enforce on every PR
-
-The distinction matters because the Reviewer treats convention files as hard rules. A rule in `.claude/rules/frontend.md` that you don't actually enforce in human review creates noise — the Reviewer will flag violations that you approve anyway, eroding trust in the signal.
-
-## The Failure Learning Loop
-
-When the Reviewer finds a non-trivial issue — a pattern that will recur if not captured — it writes a failure record to `.claude/agent-memory/`. Before implementing, the Developer reads failure records matching the current domain and uses them as guardrails.
-
-Over time, systematic mistakes stop appearing in PRs. If the Developer consistently produces type errors in a specific module, the Reviewer notes it, and the next Developer run avoids the pattern. This is not perfect — agents have context limits and memory records are text, not code — but it measurably reduces repeating defects in long-running projects.
-
-As a maintainer, you can seed this loop manually. When you reject a PR for a repeating issue, write a brief failure record in `.claude/agent-memory/` describing the pattern and the correct approach. The Developer will read it on the next relevant implementation. This is particularly effective for project-specific patterns that don't appear in training data — unusual framework choices, internal library conventions, domain-specific invariants.
-
-The memory directory is part of your repository. Reviewing and pruning it periodically keeps the signal quality high. Outdated failure records from refactored code should be removed so they don't mislead future Developers.
-
-## What CI and specrails don't catch
-
-The confidence gate and CI verify quality — not intent. A PR that scores 92 on confidence and passes all CI checks can still be wrong in ways that require human judgment. As a maintainer, the things that remain your responsibility are:
-
-- **Product intent**: does this implementation match what the original issue asked for? The Reviewer verifies the implementation against the spec, but the spec may not have captured the full product intent.
-- **UX feel**: for UI features, does the result look and behave right? Automated checks don't evaluate visual weight, interaction feel, or whether the layout works in realistic data conditions.
-- **Business logic edge cases**: are there edge cases the spec didn't cover that would produce incorrect behavior for real users? Specs are written before implementation — they capture known cases, not unknown ones.
-- **PR description accuracy**: does the PR description accurately describe what changed? This matters for changelog generation and future developers reading git history.
-
-These checks are fast when the pipeline is working well. A PR where the confidence score is high, CI is green, and the implementation is clearly scoped should take 5–10 minutes to verify for intent. That is the target review cost for a well-specced, well-pipelined feature.
-
-## The safe-to-merge checklist
-
-A PR from specrails is safe to merge without deep review when all of the following hold:
-
-- [ ] Overall confidence score is at or above your configured threshold
-- [ ] Security aspect score is at or above your configured threshold
-- [ ] CI is green: lint, typecheck, and tests all pass
-- [ ] No `TODO` or `FIXME` markers were introduced by the implementation
-- [ ] PR description matches the original issue intent (read the issue, then the PR — do they describe the same thing?)
-- [ ] No new dependencies added without justification in the PR body
-
-When any of these conditions fails, do not skip the review — investigate the specific failure. A `TODO` introduced by the Developer is a signal that it encountered a constraint it couldn't resolve. A CI failure that the Reviewer didn't fix is a signal that the pipeline exited early. A PR description that doesn't match the issue is a signal that scope drifted during implementation.
-
-## Patterns & Anti-patterns
-
-| Pattern | Why it works |
-|---------|-------------|
-| Setting `security` threshold higher than `overall` | Security issues are harder to catch in a quick review pass — the pipeline should surface them before the PR is created |
-| Putting naming conventions in `.claude/rules/` files | The Reviewer enforces them consistently on every PR, so you never see naming violations in review |
-| Seeding `.claude/agent-memory/` with project-specific failure records | Prevents the same class of defect from appearing repeatedly; teaches the pipeline your codebase's specific constraints |
-| Using `warn` for `correctness` and `block` for `security` | Lets low-stakes correctness issues through for quick human review while stopping security concerns cold |
-
-| Anti-pattern | Why it fails |
-|-------------|-------------|
-| Treating a high confidence score as a substitute for intent review | Confidence measures implementation quality against the spec, not the spec's alignment with product intent |
-| Adding aspirational rules to `.claude/rules/` files | Reviewer flags violations you'd approve anyway, creating noise that erodes trust in the rule set |
-| Never pruning `.claude/agent-memory/` | Outdated failure records from refactored code mislead future Developers, causing them to avoid patterns that are now correct |
-| Raising thresholds after every blocked PR instead of investigating | The block exists because the pipeline found something; raising the threshold to get the PR through skips the investigation |
-
-## What's next?
-
-- [Customization](customization.md) — configure agents, rules, personas, and confidence thresholds for your project
-- [Core Concepts](concepts.md) — understand the pipeline phases and the agent roles that produce the quality signals you're reviewing
-
----
-
-[← Parallel Development](playbook-parallel-dev.md)

package/docs/playbook-parallel-dev.md

@@ -1,124 +0,0 @@
-# Parallel Development
-
-> For maintainers shipping multiple features in a sprint who want to maximize throughput without introducing merge conflicts.
-
-## How specrails parallelizes work
-
-When you pass multiple issue numbers to `/specrails:batch-implement`, specrails spawns one git worktree per feature. Each worktree has its own branch, its own isolated copy of the working tree, and its own full agent pipeline running concurrently. Features do not queue — they run in parallel from Phase 3a (Architecture) through Phase 5 (PR creation).
-
-This is not a simulation of parallelism. Each pipeline is a separate Claude Code session with no shared state. The Architect for issue #71 has no visibility into the Architect for issue #63. Each Developer commits to its own branch. Each Reviewer runs CI independently. The worktrees are merged into the base branch at the end of the batch run.
-
-The speed advantage over sequential implementation is significant. For a batch of three medium-effort features, sequential implementation might take 90 minutes. Parallel implementation takes roughly as long as the slowest single feature — often 30–40 minutes. The constraint is wall-clock time, not the number of features.
-
-## What's safe to parallelize
-
-Not every combination of features is safe to run in parallel. A feature is safe to include in a parallel batch when all four conditions hold:
-
-1. **File isolation**: the feature touches different files from the other features in the batch. Two features that both modify `src/api/middleware.ts` will produce a merge conflict.
-
-2. **No shared data model changes**: the feature does not depend on a schema migration, new database table, or new shared utility introduced by another feature in the same batch. If feature A adds a `users.rate_limit_tier` column and feature B reads that column, B depends on A.
-
-3. **Spec is complete**: the feature's OpenSpec change is fully approved before the batch runs. Specs that are still being revised during implementation produce inconsistent results.
-
-4. **Wave 1 in the dependency DAG**: the feature has no unimplemented prerequisites. A feature with `Prerequisites: #71` cannot run in the same batch as #71 — it must wait for #71 to ship first.
-
-When in doubt, run `/specrails:get-backlog-specs` to see the dependency ordering before composing your batch.
-
-## What's not safe
-
-Some combinations look independent but are not:
-
-**Two features that both modify the same schema file.** Even if the migrations are logically independent (adding different columns to different tables), they both touch `db/schema.sql` or the migration directory. The merge will conflict or produce an incorrect combined schema.
-
-**A feature that requires a utility extracted by another feature in the same batch.** If issue #71 refactors authentication middleware into a shared utility, and issue #85 uses that utility, #85 cannot run in the same batch as #71. At the time #85's Developer runs, the shared utility doesn't exist yet.
-
-**Features with a `Prerequisites:` relationship to each other.** If issue #85 has `Prerequisites: #71` in its issue body, the Product Analyst's dependency DAG already captures this. Running them together ignores the declared ordering.
-
-**Features where the spec says "depends on the outcome of X".** This phrasing signals a runtime dependency that may not be captured in the `Prerequisites:` field. Treat it as an explicit exclusion from the current batch.
-
-## Reading the dependency DAG
-
-Run `/specrails:get-backlog-specs` before composing any parallel batch. The output includes a prioritized backlog table with dependency metadata. Wave 1 features — those with no unimplemented prerequisites — are your safe parallel batch candidates.
-
-```
-/specrails:get-backlog-specs
-
-┌─ API ──────────────────────────────────────────┐
-│ #  Issue   Score  Effort  Description           │
-│ 1  #85     12/15  Medium  Health check endpoint │
-│ 2  #71     10/15  Low     Rate limiting          │
-│ 3  #63      8/15  High    GraphQL migration      │
-└─────────────────────────────────────────────────┘
-
-Top 3 for next sprint:
-1. #71 — Rate limiting (score/effort: 3.33)
-2. #85 — Health check (score/effort: 2.40)
-3. #63 — GraphQL (score/effort: 0.53)
-```
-
-The backlog output shows effort and score, but it does not explicitly label Wave 1 vs. Wave 2. You determine Wave 1 by reading the `Prerequisites:` field on each issue. Any issue whose prerequisites are all already merged is a Wave 1 candidate.
-
-Use the Product Analyst's reasoning section (shown when running with verbose output) to confirm the dependency ordering before batching.
-
-## Practical example
-
-Three issues are in your sprint: #85 (health check endpoint), #71 (rate limiting middleware), and #63 (GraphQL migration).
-
-Reading the issue bodies:
-- #85 has `Prerequisites: #71` — the health check reads the rate limit status, so it needs the middleware to exist first.
-- #71 has no prerequisites.
-- #63 has no prerequisites.
-
-#71 and #63 are independent of each other and have no prerequisites. They are Wave 1. Run them in parallel:
-
-```
-/specrails:batch-implement #71, #63
-```
-
-Both pipelines run concurrently. Each produces a PR. After both PRs are merged, #85 is unblocked. Run it alone:
-
-```
-/specrails:implement #85
-```
-
-Attempting to include #85 in the first batch would have caused the Developer for #85 to run without the rate limiting middleware in place, producing code that imports a module that doesn't exist yet.
-
-## When auto-merge fails
-
-After all worktree pipelines complete, specrails attempts to merge each feature branch into the base. When the merge succeeds automatically, each feature gets its own PR. When it fails, specrails surfaces the conflict and stops.
-
-**Symptom**: merge conflict reported in the worktree merge step, pipeline exits before PR creation for one or more features.
-
-**Cause**: two features edited the same region of the same file. This happens most often in configuration files, shared utilities, or index files that aggregate exports.
-
-**Recovery**:
-1. Note which features conflicted.
-2. Pick one feature's branch as the base. Merge it into the base branch first (it will succeed — the conflict is between the two feature branches, not between either and base).
-3. For the conflicting feature branch, manually resolve the conflict by merging the base branch into it.
-4. Once the conflict is resolved, the Developer can rerun from Phase 5 (PR creation) to create the PR with the resolved branch.
-
-**Prevention**: run the safe parallelization criteria before batching. Index files and configuration files are common conflict sources — if two features both register something in the same registry or config object, consider whether they should be sequenced instead.
-
-## Patterns & Anti-patterns
-
-| Pattern | Why it works |
-|---------|-------------|
-| Run `/specrails:get-backlog-specs` before composing a batch | Surfaces the dependency DAG so you batch only Wave 1 features |
-| Keep batches to 2–4 features | Smaller batches reduce conflict surface area and keep the merge step fast |
-| Ensure all specs are approved before starting the batch | Prevents mid-batch spec revisions that invalidate a running pipeline |
-| Sequence database migration features before features that consume the schema | Eliminates the most common class of parallel dev failures |
-
-| Anti-pattern | Why it fails |
-|-------------|-------------|
-| Batching features that share a configuration or registry file | Almost guarantees a merge conflict in a file that both features modified |
-| Including a feature whose prerequisite is also in the batch | The dependent feature's Developer runs before the prerequisite exists, producing broken imports and missing types |
-| Running a batch before all specs are written | An incomplete spec causes the Architect to make assumptions; you may get a PR for a feature that was redefined mid-run |
-| Treating all "unrelated" features as parallelizable | "Unrelated" at the product level can still mean "touching the same file" at the code level — verify file isolation, not just feature isolation |
-
-## What's next?
-
-- [Workflows & Commands](workflows.md) — full reference for `/specrails:batch-implement`, `/specrails:implement`, and `/specrails:get-backlog-specs`
-
----
-
-[← Product Discovery](playbook-product-discovery.md) · [OSS Maintainer Workflow →](playbook-oss-maintainer.md)

package/docs/playbook-product-discovery.md

@@ -1,115 +0,0 @@
-# Product Discovery
-
-> For OSS maintainers using specrails with OpenSpec who want every implementation to land right the first time.
-
-## Why spec quality determines implementation quality
-
-The Architect agent reads your spec before writing a single task. It has no other source of truth. If your proposal is ambiguous, the design it produces will be ambiguous. If the design is ambiguous, the Developer will fill the gaps with assumptions — and those assumptions may not match your intent.
-
-The pipeline is only as good as the spec that enters it. A vague feature request produces code that technically compiles and tests pass, but misses the product intent entirely. A precise, well-structured spec produces a design artifact that the Developer can follow without guessing.
-
-This isn't unique to AI agents. The same dynamic plays out in human teams: the clearer the ticket, the fewer the back-and-forths. With specrails, the cost of ambiguity is higher because there is no back-and-forth — the pipeline runs to completion and surfaces a PR. At that point, the cost to correct a wrong assumption is much higher than the cost to write a better spec upfront.
-
-## Anatomy of a good OpenSpec proposal
-
-OpenSpec proposals have four required fields: What, Why, Non-goals, and Success criteria. Each field should be concrete enough that a reader who has never touched your codebase understands the full scope of the change.
-
-**Vague proposal:**
-```
-Add a dashboard page showing user stats.
-```
-
-This leaves every significant question unanswered: which stats, which users, what layout, what data source, what defines "done"?
-
-**Good proposal:**
-```
-What: Add a /dashboard route that renders a stats panel for the authenticated user.
-The panel shows: total API calls in the last 30 days, current rate limit window status,
-and top 3 endpoints by call volume. Data comes from the existing /api/usage endpoint.
-
-Why: OSS users need to self-diagnose rate limit issues without opening a support ticket.
-The Product Analyst scored this High on the Developer persona (pain: "I don't know when
-I'm about to hit a rate limit").
-
-Non-goals: Historical charts, export functionality, and admin views are out of scope.
-This is a read-only display panel.
-
-Success criteria: Authenticated user loads /dashboard and sees accurate stats within 2s.
-Unauthenticated user is redirected to /login. All three stat types render correctly
-in a 375px viewport. Zero console errors.
-```
-
-The difference is not length — it is specificity. The Architect can produce a task breakdown from the good proposal without making a single assumption.
-
-## Writing GitHub Issues the Product Analyst can parse
-
-The Product Analyst reads your GitHub Issues labeled `product-driven-backlog` to build the dependency DAG and score your backlog. The issue body structure matters.
-
-**The `Prerequisites:` field** is how you tell the Product Analyst that one issue depends on another. When you run `/specrails:get-backlog-specs`, the dependency DAG is built from these declarations. Issues without prerequisites are Wave 1 candidates — safe to implement in parallel. Issues with prerequisites are scheduled after their dependencies complete.
-
-```
-Prerequisites: #71 (rate limiting middleware must exist before we can display rate limit status)
-```
-
-Write this field even when the dependency seems obvious. The Product Analyst reads issues in isolation — it doesn't infer dependencies from context.
-
-**VPC-aligned descriptions** help the Product Analyst score your issue accurately. Mention which persona benefits and describe the pain or gain being addressed. "As a developer debugging API integration issues, I need to see my current rate limit window status without making a test request" gives the Product Analyst enough context to score correctly. "Add rate limit display" does not.
-
-**Effort labels** (Low / Medium / High) affect priority scoring. The Product Analyst uses the score-to-effort ratio to rank recommendations. A Low-effort feature with a High score ranks above a High-effort feature with the same score. Set realistic effort labels — optimistic labels inflate priority and create scheduling surprises.
-
-## Choosing your entry point
-
-specrails offers two paths into the OpenSpec pipeline:
-
-**`/opsx:ff` (Fast Forward)** generates all artifacts in one pass: proposal, design, tasks, and context bundle. The Architect runs through each artifact without stopping for review. Use this when:
-- You know exactly what you want to build
-- The approach is well-understood and not architecturally novel
-- You'd approve the design without reading it carefully
-
-**`/opsx:new` + `/opsx:continue`** creates artifacts one at a time, pausing after each. You review the proposal before the design is written, and the design before tasks are generated. Use this when:
-- Requirements are still being refined
-- The feature touches sensitive architecture areas
-- You want to redirect the design approach before tasks are committed
-- The feature has security or data-model implications worth reviewing before code is written
-
-Rule of thumb: if you'd accept the Architect's first draft without edits, use `/opsx:ff`. If you want a checkpoint between "what we're building" and "how we're building it," use the step-by-step path.
-
-Once artifacts are complete, `/opsx:apply` hands them to the Developer. After implementation, `/opsx:archive` closes the change.
-
-## The context bundle matters
-
-The context bundle is the set of files, interfaces, and decisions that the Developer reads before writing code. A thin context bundle forces the Developer to explore the codebase independently — and exploration introduces risk. The Developer may read an outdated version of a file, miss a constraint documented elsewhere, or invent types that conflict with existing ones.
-
-A good context bundle includes:
-- **Files to read**: specific file paths, not directory globs
-- **Key interfaces**: paste the exact TypeScript interface or API contract, not a link to it
-- **Architectural decisions**: what approach was chosen and why, so the Developer doesn't choose a different approach that conflicts with the rest of the system
-- **Known constraints**: anything that would make the naive implementation wrong (auth requirements, transaction boundaries, rate limits, backward-compatibility rules)
-
-The context bundle is generated automatically by `/opsx:ff` and `/opsx:continue`. You can edit it before running `/opsx:apply`. Investing 10 minutes in tightening the context bundle typically saves 30 minutes of review on the resulting PR.
-
-## Patterns & Anti-patterns
-
-| Pattern | Why it works |
-|---------|-------------|
-| Proposal includes explicit Non-goals | Prevents scope creep during implementation — the Developer doesn't add "nice to have" features that weren't requested |
-| Design artifact describes the approach per layer | Developer has no ambiguity about which files to touch and in what order |
-| Context bundle includes exact TypeScript interfaces | Developer doesn't invent types that conflict with existing ones, reducing type errors and review cycles |
-| Success criteria are binary (pass/fail) | Easier to verify at review time — "redirects to /login when unauthenticated" is verifiable; "handles auth correctly" is not |
-
-| Anti-pattern | Why it fails |
-|-------------|-------------|
-| Skipping the design artifact and going straight to tasks | Tasks without design rationale produce code that passes tests but breaks the architecture — the Developer follows the task list without understanding the system intent |
-| Spec written after implementation | The spec becomes documentation, not a contract — the pipeline can't use it to validate the implementation against product intent |
-| Vague acceptance criteria ("looks good", "works correctly") | The Reviewer can't determine done-ness and the Developer can't verify its own output against a clear bar |
-| Missing cross-references in context bundle | Developer reads the wrong version of a file or misses a constraint, producing a PR that requires significant rework |
-
-## What's next?
-
-- [Core Concepts](concepts.md) — understand the pipeline phases and agent roles
-- [Workflows & Commands](workflows.md) — the full command reference including OpenSpec commands
-- [Customization](customization.md) — adapt the Architect and Developer agents to your project conventions
-
----
-
-[← Updating](updating.md) · [Parallel Development →](playbook-parallel-dev.md)

package/docs/plugin-architecture.md

@@ -1,144 +0,0 @@
-# Plugin Architecture
-
-SpecRails is distributed as a **Claude Code plugin** (`sr`). This document explains what that means, how the plugin relates to your project, and the three available distribution channels.
-
-## Two-layer model
-
-SpecRails separates **logic** (the plugin) from **project data** (your repo).
-
-```
-┌─────────────────────────────────────┐
-│         sr plugin (logic)           │
-│  agents · skills · hooks · refs     │
-│  updated via: claude plugin update  │
-└────────────────┬────────────────────┘
-                 │  /specrails:enrich generates
-                 ▼
-┌─────────────────────────────────────┐
-│       .specrails/ (project data)    │
-│  config · personas · rules · memory │
-│  lives in your repo, yours to edit  │
-└─────────────────────────────────────┘
-```
-
-### What lives in the plugin
-
-The plugin contains everything that doesn't change per project:
-
-| Component | Description |
-|-----------|-------------|
-| **Agent prompts** | sr-architect, sr-developer, sr-reviewer, sr-product-manager, and 10 more |
-| **Skills** | OpenSpec skills (`/opsx:*`), workflow commands (`/specrails:*`) |
-| **Hooks** | Pre/post-tool hooks for agent coordination |
-| **References** | Agent reference docs, API patterns, test conventions |
-
-You never edit these directly. To update them, run `claude plugin update sr`.
-
-### What lives in your project (`.specrails/`)
-
-`/specrails:enrich` generates ~8–10 files adapted to your specific codebase:
-
-| File | Description |
-|------|-------------|
-| `config.yaml` | Stack overview, CI commands, git workflow, backlog provider |
-| `personas/*.md` | VPC user personas — researched from your domain |
-| `rules/*.md` | Per-layer coding conventions (backend, frontend, etc.) |
-| `agent-memory/` | Persistent agent knowledge — grows across sessions |
-| `pipeline/` | In-flight state for parallel feature builds |
-| `CLAUDE.md` (root) | Project architecture reference for agents |
-
-These files are committed to your repo. They are the "project intelligence" that makes agents adapt to your stack.
-
-## Distribution channels
-
-SpecRails supports three installation paths:
-
-### 1. Claude Code plugin (recommended)
-
-```bash
-claude plugin install sr   # install
-/specrails:enrich                 # configure for your project
-claude plugin update sr    # update logic anytime
-```
-
-**Best for:** Most projects. No Node.js required. Plugin updates are one command and don't touch your project data.
-
-### 2. Claude Code scaffold
-
-```bash
-npx specrails-core@latest init --root-dir .   # TUI agent selection + copy templates
-/specrails:enrich --from-config               # AI analysis using your saved config
-```
-
-The scaffold copies the full agent+command set into `.claude/` — you own and version those files. The `init` command now includes a TUI installer that lets you select agents and model preset. Updates require re-running `npx` and re-running `/specrails:enrich`.
-
-**Best for:** Teams that want to version the agent prompts themselves, or projects that need full offline control.
-
-### 3. Provider scaffold
-
-```bash
-npx specrails-core@latest init --root-dir . --provider codex
-npx specrails-core@latest init --root-dir . --provider gemini
-npx specrails-core@latest init --root-dir . --provider kimi
-```
-
-Codex, Gemini, and Kimi do not use the Claude Code plugin package. The
-scaffold renders their native project surfaces under `.codex/`, `.gemini/`,
-and `.kimi-code/` respectively. Kimi interactive workflows use
-`/skill:specrails-*`; its headless workflows use the managed runner installed
-under `.kimi-code/specrails/`.
-
-**Best for:** Codex, Gemini, or Kimi users and teams that version generated
-provider artifacts.
-
-## The `/specrails:enrich` wizard
-
-`/specrails:enrich` is a 5-phase wizard that generates your project data. It runs once (or re-runs to regenerate).
-
-| Phase | Output |
-|-------|--------|
-| **1. Analyze** | Detects stack, CI commands, architecture layers |
-| **2. Personas** | Researches domain, generates VPC user personas |
-| **3. Configure** | Backlog provider, git workflow, agent selection |
-| **4. Generate** | Writes `.specrails/config.yaml`, personas, rules, CLAUDE.md |
-| **5. Cleanup** | Removes wizard scaffolding |
-
-Quick mode: `/specrails:enrich --quick` — three questions, done in under a minute.
-
-From-config mode: `/specrails:enrich --from-config` — reads `.specrails/install-config.yaml` (written by the TUI installer) and runs non-interactively.
-
-## OpenSpec skills
-
-The `sr` plugin bundles the full OpenSpec skill set. These are available as `/opsx:*` commands:
-
-| Skill | Purpose |
-|-------|---------|
-| `/opsx:ff` | Fast-forward through all change artifacts |
-| `/opsx:apply` | Implement an OpenSpec change |
-| `/opsx:verify` | Verify implementation matches spec |
-| `/opsx:archive` | Archive a completed change |
-| `/opsx:explore` | Explore ideas before writing a spec |
-
-OpenSpec is the structured design layer that powers `/specrails:implement` — the architect uses it to produce a technical design before the developer begins coding.
-
-## Updating
-
-### Update plugin logic
-
-```bash
-claude plugin update sr
-```
-
-Updates agents, skills, hooks, and references. Does not touch `.specrails/` project data.
-
-### Regenerate project data
-
-```bash
-/specrails:enrich
-```
-
-Re-runs the wizard and regenerates `.specrails/`. Useful when your stack changes significantly or you want to refresh personas.
-
----
-
-[← Installation](installation.md) · [Core Concepts →](concepts.md)