specrails-core 1.7.0 → 1.7.2

package/docs/playbook-parallel-dev.md

@@ -0,0 +1,124 @@
+# 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 `/sr: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 `/sr:product-backlog` 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 `/sr:product-backlog` 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.
+
+```
+/sr:product-backlog
+
+┌─ 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:
+
+```
+/sr:batch-implement #71, #63
+```
+
+Both pipelines run concurrently. Each produces a PR. After both PRs are merged, #85 is unblocked. Run it alone:
+
+```
+/sr: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 `/sr:product-backlog` 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 `/sr:batch-implement`, `/sr:implement`, and `/sr:product-backlog`
+
+---
+
+[← Product Discovery](playbook-product-discovery.md) · [OSS Maintainer Workflow →](playbook-oss-maintainer.md)

package/docs/playbook-product-discovery.md

@@ -0,0 +1,115 @@
+# 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 `/sr:product-backlog`, 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/updating.md

@@ -0,0 +1,96 @@
+# Updating
+
+SpecRails includes an update system that pulls new templates while preserving your customizations.
+
+## How updates work
+
+The update system uses a **manifest-based approach**:
+
+1. During installation, SpecRails generates `.specrails-manifest.json` — a checksum of every installed file
+2. On update, it compares the manifest against current files to detect what you've customized
+3. Customized files are preserved; unchanged files are updated to the latest version
+
+## Running an update
+
+```bash
+curl -sL https://raw.githubusercontent.com/fjpulidop/specrails/main/update.sh | bash
+```
+
+Or from a local clone:
+
+```bash
+bash /path/to/specrails/update.sh
+```
+
+### What happens
+
+1. **Backup** — creates `.claude.specrails.backup/` with your current files
+2. **Version check** — compares installed version (`.specrails-version`) with latest
+3. **Update files** — replaces unchanged files, preserves customized ones
+4. **Merge settings** — additively merges `settings.json` (your permissions are kept)
+5. **Update version** — writes new version and manifest
+
+If anything fails, the backup is restored automatically.
+
+## Selective updates
+
+Update only specific components with the `--only` flag:
+
+```bash
+# Update core files (setup command, templates, prompts, skills)
+bash update.sh --only core
+
+# Update Pipeline Monitor dashboard
+bash update.sh --only web-manager
+
+# Regenerate agents (prompts for confirmation if templates changed)
+bash update.sh --only agents
+
+# Full update (default)
+bash update.sh --only all
+```
+
+## What gets preserved
+
+| File type | Behavior |
+|-----------|----------|
+| **Agent prompts** (`.claude/agents/`) | Preserved if customized; updated if unchanged |
+| **Commands** (`.claude/commands/`) | Updated (commands are orchestration, not customized) |
+| **Rules** (`.claude/rules/`) | Preserved if customized |
+| **Settings** (`settings.json`) | Merged additively (your permissions kept, new ones added) |
+| **Agent memory** (`.claude/agent-memory/`) | Always preserved |
+| **Personas** (`.claude/agents/*.md`) | Always preserved |
+| **Security exemptions** | Always preserved |
+
+## Legacy installations
+
+If you installed SpecRails before the versioning system (pre-v0.1.0):
+
+- The updater detects missing `.specrails-version` and treats it as a legacy install
+- It migrates your installation to the versioned system
+- A manifest is generated from your current files
+- Future updates use the standard manifest comparison
+
+## Rolling back
+
+If something goes wrong, restore from the automatic backup:
+
+```bash
+# Backups are at .claude.specrails.backup/
+cp -r .claude.specrails.backup/.claude .claude
+cp .claude.specrails.backup/.specrails-version .specrails-version
+```
+
+---
+
+## What's next?
+
+That's the end of the docs. Here are some useful starting points:
+
+- [Getting Started](getting-started.md) — if you haven't installed yet
+- [Workflows & Commands](workflows.md) — to start using the pipeline
+- [Customization](customization.md) — to make SpecRails yours
+
+---
+
+[← Customization](customization.md) · [Back to Docs](README.md)