specrails-core 5.6.0 → 6.0.1

package/docs/user-docs/cli-reference.md

@@ -1,428 +0,0 @@
-# CLI Reference
-
-SpecRails installs provider-native workflows for Claude Code, Codex CLI,
-Gemini CLI, and Kimi Code. The workflow names and flags are shared, while each
-provider uses its own activation syntax and project directory.
-
-**Platform support key used in this reference:**
-
-| Badge | Meaning |
-|-------|---------|
-| ✅ Providers | Works in Claude Code, Codex CLI, Gemini CLI, and Kimi Code |
-| 🔵 Claude Code | Claude Code only |
-| ⚠️ Limited | Works, but with known limitations (see notes) |
-
-Run commands inside your AI CLI from your project directory:
-
-```bash
-claude   # Claude Code
-codex    # Codex
-gemini   # Gemini CLI
-kimi     # Kimi Code
-```
-
-Claude and Gemini use `/specrails:<command>`. Codex activates the generated
-skill from `.codex/skills/`. Kimi's interactive TUI uses
-`/skill:specrails-<command>`; headless Kimi runs must use the managed
-`.kimi-code/specrails/run-skill.mjs` helper, not a literal `/skill:` prompt.
-
----
-
-## Core workflow
-
-### `/specrails:implement` ✅ Providers
-
-Implement a feature through the full agent pipeline: design → code → tests → docs → review → PR.
-
-```
-/specrails:implement #85
-/specrails:implement #85, #71, #63
-/specrails:implement "add a health check endpoint"
-/specrails:implement UI, Analytics
-```
-
-**Flags:**
-
-| Flag | Effect |
-|------|--------|
-| `--dry-run` / `--preview` | Run the full pipeline without git operations or PR creation |
-| `--apply <name>` | Apply a previously cached dry-run |
-
-**Pipeline phases:**
-
-| Phase | Agent | What happens |
-|-------|-------|-------------|
-| 3a | Architect | Designs the implementation, creates a task list |
-| 3b | Developer | Writes code across all affected layers |
-| 3c | Test Writer | Generates tests for new code |
-| 3d | Doc Sync | Updates CHANGELOG and relevant docs |
-| 4 | Security Reviewer | Scans for secrets and vulnerabilities |
-| 4b | Reviewer | Runs your CI suite, fixes lint/type errors |
-| 4b-conf | — | Confidence gate: scores implementation across 5 dimensions |
-| 5 | — | Creates a pull request |
-
-**Single vs. parallel:**
-
-A single issue runs sequentially on the current branch. Multiple issues run in parallel — each gets an isolated git worktree, and results are merged automatically.
-
-> **Codex note**: Parallel worktree isolation is limited in Codex CLI beta. For reliable parallel execution use Codex Cloud, or run one issue at a time with Codex CLI.
-
----
-
-### `/specrails:telemetry` ✅ Providers
-
-Inspect per-agent execution metrics: token usage, estimated API cost, run count, average duration, and success/failure rate.
-
-Kimi reads persisted `usage.record` events for real input/output/cache token
-counts and session duration. Its logs do not contain an authoritative USD rate
-or role outcome, so the Kimi dashboard reports cost and success rate as
-unavailable instead of applying another provider's rate card.
-
-```
-/specrails:telemetry
-/specrails:telemetry --period today
-/specrails:telemetry --agent sr-developer
-/specrails:telemetry --format json
-/specrails:telemetry --save
-```
-
-**Flags:**
-
-| Flag | Effect |
-|------|--------|
-| `--period <filter>` | Time window: `today`, `week` (default), or `all` |
-| `--agent <name>` | Focus on a single agent (e.g. `sr-developer`) |
-| `--format <fmt>` | Output format: `markdown` (default) or `json` |
-| `--save` | Write a snapshot under the active provider directory after display |
-
----
-
-### `/specrails:merge-resolve` ✅ Providers
-
-Resolve git conflict markers using AI-powered context analysis.
-
-```
-/specrails:merge-resolve
-/specrails:merge-resolve --files src/api/routes.ts
-/specrails:merge-resolve --context openspec/changes/
-```
-
-**Flags:**
-
-| Flag | Effect |
-|------|--------|
-| `--files <paths>` | File paths or globs to process (default: auto-detect from working tree) |
-| `--context <dir>` | Directory containing OpenSpec context bundles (default: `openspec/changes/`) |
-| `--threshold <n>` | Minimum confidence to auto-apply a resolution |
-
-Reads OpenSpec context bundles from the features that produced each conflict, infers the correct resolution, and writes it in place. Conflicts it cannot safely resolve are left with clean markers for manual review.
-
----
-
-### `/specrails:retry` ✅ Providers
-
-Resume a failed `/specrails:implement` run from the last successful phase.
-
-```
-/specrails:retry <feature-name>
-/specrails:retry --list
-/specrails:retry <feature-name> --from architect
-/specrails:retry <feature-name> --dry-run
-```
-
-**Flags:**
-
-| Flag | Effect |
-|------|--------|
-| `--list` | List all saved pipeline states |
-| `--from <phase>` | Force resume from a specific phase |
-| `--dry-run` | Resume in preview mode |
-
-**Valid `--from` values:** `architect`, `developer`, `test-writer`, `doc-sync`, `reviewer`, `ship`, `ci`
-
-Pipeline state is saved under the active provider directory after each phase.
-
----
-
-### `/specrails:batch-implement` ⚠️ Limited on Codex
-
-Implement multiple independent features in parallel using git worktrees.
-
-```
-/specrails:batch-implement #85, #71, #63
-```
-
-Each feature gets its own worktree, its own agent pipeline, and its own PR. Use this instead of `/specrails:implement` with multiple issues when you want explicit control over parallel execution.
-
-> **Codex note**: Worktree isolation is limited in Codex CLI beta. Prefer Codex Cloud for parallel batch work.
-
----
-
-## Product and backlog
-
-### `/specrails:get-backlog-specs` ✅ Providers
-
-View your prioritized product backlog, ranked by VPC persona fit and estimated effort.
-
-```
-/specrails:get-backlog-specs
-/specrails:get-backlog-specs UI, API
-```
-
-Reads GitHub Issues labeled `product-driven-backlog`. Produces a ranked table per area, top 3 recommendations, and a safe implementation order based on issue dependencies.
-
----
-
-### `/specrails:auto-propose-backlog-specs` ✅ Providers
-
-Generate new feature ideas through product discovery and create GitHub Issues.
-
-```
-/specrails:auto-propose-backlog-specs
-/specrails:auto-propose-backlog-specs UI, API
-```
-
-The Product Manager researches your competitive landscape, generates 2–4 feature ideas per area, and scores each against your user personas. Creates GitHub Issues with full VPC evaluation if write access is available.
-
----
-
-## Analysis and inspection
-
-### `/specrails:refactor-recommender` ✅ Providers
-
-Scan the codebase for refactoring opportunities, ranked by impact/effort ratio.
-
-```
-/specrails:refactor-recommender
-```
-
-Identifies duplicates, overly long functions, large files, dead code, outdated patterns, and complex logic. Optionally creates GitHub Issues for tracking.
-
----
-
-### `/specrails:compat-check` ✅ Providers
-
-Analyze the backwards-compatibility impact of a proposed change.
-
-```
-/specrails:compat-check #85
-/specrails:compat-check #85 --save
-```
-
-Detects removed endpoints, changed method signatures, changed response shapes, and behavioral changes. When breaking changes are found, generates a migration guide.
-
-`--save` updates the stored API baseline so future checks compare against the new surface.
-
-The Architect runs this automatically as part of every `/specrails:implement` pipeline.
-
----
-
-### `/specrails:why` ✅ Providers
-
-Search agent explanation records in plain language.
-
-```
-/specrails:why "why did we choose this database schema"
-/specrails:why "explain the auth middleware design"
-/specrails:why "why is pagination implemented this way"
-```
-
-Agents write decision rationale under the active provider's `agent-memory/`
-directory as they work. `/specrails:why` searches these records semantically.
-Useful for onboarding, code review, and revisiting past decisions.
-
----
-
-### `/specrails:vpc-drift` ✅ Providers
-
-Detect when your VPC personas have drifted from what your product actually delivers.
-
-```
-/specrails:vpc-drift
-/specrails:vpc-drift --persona "Alex,Sara"
-/specrails:vpc-drift --verbose
-/specrails:vpc-drift --format json
-```
-
-Compares persona Jobs/Pains/Gains against your backlog, implemented features, and agent memory. Produces a per-persona alignment score and recommendations for updating your VPC.
-
----
-
-### `/specrails:memory-inspect` ✅ Providers
-
-Inspect and clean up agent memory directories.
-
-```
-/specrails:memory-inspect
-/specrails:memory-inspect sr-developer
-/specrails:memory-inspect --stale 14
-/specrails:memory-inspect --prune
-```
-
-**Flags:**
-
-| Flag | Effect |
-|------|--------|
-| `--stale <days>` | Flag files older than N days |
-| `--prune` | Delete stale files (prompts for confirmation) |
-
-Agent memory lives below the provider root:
-
-| Provider | Memory root |
-|----------|-------------|
-| Claude Code | `.claude/agent-memory/` |
-| Codex CLI | `.codex/agent-memory/` |
-| Gemini CLI | `.gemini/agent-memory/` |
-| Kimi Code | `.kimi-code/agent-memory/` |
-
----
-
-### `/specrails:propose-spec` ✅ Providers
-
-Explore a feature idea and produce a structured proposal ready for the OpenSpec pipeline.
-
-```
-/specrails:propose-spec "add rate limiting to the API"
-```
-
-Produces: problem statement, proposed solution, out-of-scope items, acceptance criteria, technical considerations, and a complexity estimate.
-
----
-
-## OpenSpec commands
-
-OpenSpec is the structured design-to-code workflow. Use these commands when you want explicit control over each artifact: proposal → design → tasks → implementation.
-
-OpenSpec commands are generated for all four providers (✅ Providers).
-
-### `/opsx:ff` — Fast Forward
-
-Create all OpenSpec artifacts at once (proposal + design + tasks + context bundle), then hand off to the developer.
-
-```
-/opsx:ff
-```
-
-Use this when you know what you want to build and don't need to review each artifact step by step.
-
----
-
-### `/opsx:new` — New Change
-
-Start a new change by creating a proposal. Advances through artifacts one at a time.
-
-```
-/opsx:new
-```
-
----
-
-### `/opsx:continue` — Continue Change
-
-Create the next artifact in the sequence for the current in-progress change.
-
-```
-/opsx:continue
-```
-
-Typical sequence: proposal → design → tasks → context bundle.
-
----
-
-### `/opsx:apply` — Apply Change
-
-Implement the tasks from a designed change. Hands off to the Developer agent.
-
-```
-/opsx:apply
-```
-
----
-
-### `/opsx:verify` — Verify Change
-
-Validate that the implementation matches the change artifacts before archiving.
-
-```
-/opsx:verify
-```
-
----
-
-### `/opsx:archive` — Archive Change
-
-Finalize and archive a completed change.
-
-```
-/opsx:archive
-```
-
----
-
-### `/opsx:explore` — Explore
-
-Open-ended thinking mode for brainstorming, investigating problems, or clarifying requirements before starting a change.
-
-```
-/opsx:explore
-```
-
----
-
-### `/specrails:opsx-diff` — Spec Change Diff
-
-Visualize the before/after diff of an OpenSpec change.
-
-```
-/specrails:opsx-diff <change-name>
-/specrails:opsx-diff my-feature --format json
-/specrails:opsx-diff my-feature --summary-only
-```
-
-**Flags:**
-
-| Flag | Effect |
-|------|--------|
-| `<change-name>` | Kebab-case name of the change to diff (required) |
-| `--format json` | Structured JSON output |
-| `--summary-only` | File-level summary only, skip inline diff |
-
-Compares the current specs against the named change. Use during review to confirm a change matches its design intent before archiving.
-
----
-
-### Typical OpenSpec flows
-
-**Fast path:**
-```
-/opsx:ff       → create all artifacts
-/opsx:apply    → implement
-/opsx:verify   → validate
-/opsx:archive  → finalize
-```
-
-**Step by step:**
-```
-/opsx:new      → proposal
-/opsx:continue → design
-/opsx:continue → tasks
-/opsx:continue → context bundle
-/opsx:apply    → implement
-/opsx:archive  → finalize
-```
-
----
-
-## Installer flags
-
-The `npx specrails-core@latest init` command accepts:
-
-| Flag | Effect |
-|------|--------|
-| `--root-dir <path>` | Install into this directory (default: current directory) |
-| `--yes` / `-y` | Skip confirmation prompts |
-| `--provider <claude\|codex\|gemini\|kimi>` | Force a specific AI CLI (default: auto-detect) |
-
----
-
-[← Quick Start](quick-start.md) · [FAQ →](faq.md) · [← Installation](installation.md) · [Codex vs Claude Code →](codex-vs-claude-code.md)

package/docs/user-docs/codex-vs-claude-code.md

@@ -1,23 +0,0 @@
-# Codex and Claude Code execution
-
-Both providers support the SpecRails design, implementation, review and archive
-workflow. Their adapters differ; native role APIs and conversation memory are not
-interchangeable.
-
-| Concern | Claude Code | Codex |
-|---|---|---|
-| Role definitions | `.claude/agents/sr-*.md` | `.codex/skills/rails/sr-*/SKILL.md` |
-| Workflow entry | `/specrails:implement` | `$implement` |
-| Multiple tickets | Aggregate change and shared journal | Routes directly to `$batch-implement` |
-| Retry | Durable pipeline journal | Same journal, direct role calls; no nested coordinator |
-| Role models | Configured role/profile model | Inherited model on full-history forks; overrides require a compatible native transport |
-| Verification | Scoped development checks and candidate-bound full gate | Same evidence contract |
-| Hosted worktrees/delivery | Owned by the host | Owned by the host |
-
-The installed `.specrails/runtime/pipeline.mjs` helper coordinates both providers.
-Its execution context identifies the frozen specs, repositories, shared backlog,
-OpenSpec artifact root and ownership. Skills must not infer those roots from cwd.
-
-A completed process is not an implementation verdict. Design confidence, checked
-tasks, semantic review, fresh verification and an authorized archive are required
-before success. See [provider pipeline contracts](provider-pipelines.md).

package/docs/user-docs/core-updates.md

@@ -1,70 +0,0 @@
-# Core installation and update consistency
-
-`specrails-core init` and `specrails-core update` use the version of the package
-that actually provides the CLI. Updating an npm package and updating a workspace
-are separate operations: run the selected CLI's `update --root-dir <repository>`
-to refresh that project's managed artifacts. `--provider` selects the additional
-provider to include; existing managed provider selections are preserved and
-reassembled, including in-repository copies and Windows copy fallbacks. Provider
-inventory is checked against installed Core artifacts; an unrelated directory
-containing only user files is not enrolled automatically.
-
-Core 5 installation is deterministic. It installs the baseline roles, commands,
-OpenSpec integration and declared local execution helper without an AI enrichment
-phase. `integration-contract.json` describes the supported lifecycle and providers.
-
-## Version and rollback rules
-
-A CLI older than the workspace marker or shared active framework refuses ordinary
-init/update. This protects an updated installation from an old global executable.
-Use the intended Core package rather than editing a version marker to bypass the
-check. Low-level explicit pointer changes are administrative rollback operations;
-they do not imply that project copies have been restored.
-
-Managed framework bytes are generated in an isolated staging directory, validated
-and stamped before publication. The content/source hashes include the compiled
-pipeline helper, so a same-version development rebuild is repaired when runtime
-bytes change. The previous framework directory is retained as
-`.previous-<version>-<id>` for recovery. A failed generation leaves the active
-framework untouched.
-
-Init/update snapshot the managed workspace surfaces and framework pointer. Failure
-restores those snapshots, including symlinks, and does not publish a successful
-workspace version or Core-owned registry version. If restoration itself fails,
-the error identifies the retained backup for recovery. Reserved custom agents
-stay in place during rollback: edits, new custom files and deliberate deletions
-made while OpenSpec runs are preserved. Profiles remain outside the snapshot
-surfaces; provider configuration is restored with the managed workspace snapshot.
-
-A separate framework lifecycle lock covers admission, version revalidation,
-snapshots, asynchronous OpenSpec provisioning and final commit or rollback. The
-same lock protects Desktop's low-level install-framework, swap-current and
-assemble commands. A concurrent operation fails immediately with a retry message
-instead of waiting while holding another lock. This prevents a failed installer
-from rolling back a framework that a second installer already reported as ready.
-A positively dead process owner can be recovered; concurrent recovery attempts
-are serialized, and an unidentified or live owner is never taken over.
-
-`update --dry-run` reports the intended change without allocating or rewriting
-registry entries. Partial `--only rules` or `--only agents` refreshes do not claim
-that the entire framework has moved to the executing CLI's version. The returned
-`installedVersion` describes the actual workspace marker.
-
-The low-level `install-framework --version` command requires the requested label
-to match the package version supplying its bytes. `assemble --version` requires
-the matching complete active framework before recording that version in a project.
-
-## Desktop
-
-Desktop keeps the selected package and its dependencies after an update. Its
-Settings page reports runtime, framework, bundled and latest-known versions
-separately. Partial workspace migration remains pending across restart and can be
-retried using the retained package offline. A CLI installed outside Desktop can
-also be discovered through PATH; an explicit `SPECRAILS_CORE_BIN` takes precedence.
-
-Changes in this branch require a Core package build and distribution before an
-already installed Desktop can consume them. The source changes alone do not
-upgrade any user installation or publish a new package.
-
-See [Provider pipeline contracts](provider-pipelines.md) for the resumable
-implementation journal and verification behavior.

package/docs/user-docs/faq.md

@@ -1,146 +0,0 @@
-# FAQ
-
-## Setup and installation
-
-**Do I need a Claude API account to use SpecRails?**
-
-Yes. SpecRails runs on top of Claude Code, which requires an Anthropic account. Claude Code handles authentication — SpecRails just orchestrates it. See [Claude Code's installation guide](https://docs.anthropic.com/en/docs/claude-code) for setup.
-
-**What does the installer actually do to my project?**
-
-The plugin method (`claude plugin install sr`) installs logic into Claude Code's plugin system — nothing is added to your project until you run `/specrails:enrich`. The scaffold method (`npx specrails-core@latest init`) launches a TUI to select agents and model preset, writes `.specrails/install-config.yaml`, then copies templates into `.claude/`. Neither method modifies your source code, creates commits, or pushes anything.
-
-**Do I need Node.js if my project is not JavaScript?**
-
-Not for the plugin method (`claude plugin install sr`). Node.js 20.19.0+ is only required for the scaffold method (`npx specrails-core@latest init`), because its pinned OpenSpec 1.4.1 CLI uses that runtime floor. Once installed, SpecRails works with any language or framework, on macOS, Linux, or Windows.
-
-**Do I need GitHub Issues?**
-
-No. SpecRails ships with a built-in local ticket system — no GitHub account required. Local tickets are the default. Commands like `/specrails:implement` accept ticket IDs or plain text:
-
-```
-/specrails:implement #1, #4
-/specrails:implement "add rate limiting to the API"
-```
-
-You can switch to GitHub Issues or JIRA during `/specrails:enrich` (Phase 3) if you prefer.
-
-**How long does /specrails:enrich take?**
-
-The full wizard takes about 5 minutes — most of the time is Phase 2 (persona research via web search). For a faster start, use `/specrails:enrich --quick`: three questions, under a minute, no web research.
-
----
-
-## Using SpecRails
-
-**Can I run SpecRails on an existing project with existing code?**
-
-Yes, that's the intended use case. The `/specrails:enrich` wizard analyzes your existing codebase — your tech stack, layers, CI commands, and conventions — and generates agents configured specifically for it.
-
-**Does /specrails:implement always create a PR?**
-
-By default, yes. If you want to preview the changes first without creating commits or a PR, use dry-run mode:
-
-```
-/specrails:implement --dry-run "add dark mode"
-```
-
-Then apply the cached result when you're ready:
-
-```
-/specrails:implement --apply dark-mode
-```
-
-**What happens if the pipeline fails mid-run?**
-
-SpecRails saves pipeline state after each phase. If a run fails, use `/specrails:retry` to resume from the last successful phase instead of starting over:
-
-```
-/specrails:retry dark-mode
-```
-
-**Can I implement multiple features at once?**
-
-Yes. Pass multiple issue numbers or descriptions:
-
-```
-/specrails:implement #42, #43, #44
-```
-
-Each feature gets an isolated git worktree. Pipelines run concurrently and the results are merged automatically at the end.
-
-**Can I customize the agents?**
-
-Yes. With the plugin method, edit your project data files in `.specrails/` — personas, rules, config. With the scaffold method, agent files in `.claude/agents/` are also directly editable. Changes take effect on the next run.
-
-For layer-specific coding conventions, edit `.specrails/rules/*.md` (plugin) or `.claude/rules/*.md` (scaffold).
-
-**What is a VPC persona?**
-
-VPC stands for Value Proposition Canvas. Personas are structured profiles of your target users with their Jobs (what they're trying to accomplish), Pains (what frustrates them), and Gains (what they want). The Product Manager and Architect use these to make better design decisions. They're generated during `/specrails:enrich` and stored in `.specrails/personas/` (plugin) or `.claude/agents/personas/` (scaffold).
-
----
-
-## Project compatibility
-
-**Does SpecRails work with monorepos?**
-
-Yes. During `/specrails:enrich`, the architect detects your monorepo structure and generates separate layer configurations for each package or service.
-
-**Which languages and frameworks are supported?**
-
-SpecRails works with any stack. The agents are general-purpose and adapt based on what `/specrails:enrich` detects in your codebase. It's been used with Node.js, Python, Go, Ruby, Rust, and mixed-stack projects.
-
-**Does it work with private repositories?**
-
-Yes, for code generation. For features that require GitHub integration (PR creation, Issue reading), you need the GitHub CLI authenticated against your private repo.
-
----
-
-## Keeping SpecRails up to date
-
-**How do I update SpecRails?**
-
-Plugin method:
-
-```bash
-claude plugin update sr
-```
-
-Scaffold method:
-
-```bash
-npx specrails-core@latest init --root-dir .
-```
-
-Then re-run `/specrails:enrich` to regenerate project data with any new templates. See the [updating guide](../updating.md) for details.
-
-**How do I know which version is installed?**
-
-```bash
-cat .specrails/specrails-version
-```
-
----
-
-## Troubleshooting
-
-**The /specrails:enrich command isn't available after installing.**
-
-For the plugin method: make sure the plugin is installed (`claude plugin list` should show `sr`). For the scaffold method: Claude Code loads commands from `.claude/commands/` — make sure you opened Claude Code from inside your project directory.
-
-**Generated files contain `{{PLACEHOLDER}}` text.**
-
-The `/specrails:enrich` wizard did not complete all phases. Re-run `/specrails:enrich` — it will pick up where it left off.
-
-**The pipeline created a PR but the CI checks failed.**
-
-The reviewer agent runs your CI suite and attempts to fix failures automatically. If it can't fix them within its budget, it creates the PR with a note describing what failed and why. You can fix the remaining issues manually or run `/specrails:retry` to try the reviewer phase again.
-
-**I got a "409 Conflict" error during a pipeline run.**
-
-This means another agent tried to check out the same issue simultaneously. The pipeline will detect this and stop — re-run the command after the conflicting run finishes.
-
----
-
-[← Quick Start](quick-start.md) · [CLI Reference →](cli-reference.md)