specrails-core 5.6.0 → 6.0.0

package/docs/installation.md

@@ -1,395 +0,0 @@
-# Installation & Setup
-
-This guide covers the complete installation process in detail. For the quick version, see [Getting Started](getting-started.md).
-
-## Installation methods
-
-SpecRails offers a Claude plugin and a provider-independent scaffold:
-
-| Method | Command | Best for |
-|--------|---------|----------|
-| **Claude Code plugin** (recommended) | `claude plugin install sr` | Most projects — no Node.js required, auto-updates |
-| **Claude Code scaffold** | `npx specrails-core@latest init` | Full offline control, custom agent edits |
-| **Provider scaffold** | `npx specrails-core@latest init` | Claude, Codex, Gemini, or Kimi Code projects |
-
----
-
-## Method 1: Claude Code plugin (recommended)
-
-### Prerequisites
-
-| Tool | Why | Install |
-|------|-----|---------|
-| **Claude Code** | The AI CLI that runs the agents | `npm install -g @anthropic-ai/claude-code` |
-| **Git** | SpecRails operates on git repositories | [git-scm.com](https://git-scm.com/) |
-
-### Recommended
-
-| Tool | Why | Install |
-|------|-----|---------|
-| **GitHub CLI** | Auto-create PRs, manage issues | `brew install gh` or [cli.github.com](https://cli.github.com/) |
-
-### Install
-
-```bash
-claude plugin install sr
-```
-
-That's it. No cloning, no npm, no Node.js required.
-
-To update the plugin later:
-
-```bash
-claude plugin update sr
-```
-
-### What the plugin contains
-
-The plugin bundles the logic layer — agents, skills, commands, hooks, and references. It does **not** touch your project files.
-
----
-
-## Method 2: Scaffold (npx)
-
-### Prerequisites
-
-| Tool | Why | Install |
-|------|-----|---------|
-| **Node.js 20.19.0+** | Required for the installer and pinned OpenSpec 1.4.1 CLI (macOS, Linux, Windows) | [nodejs.org](https://nodejs.org/) or via [nvm](https://github.com/nvm-sh/nvm) |
-| **Git** | SpecRails operates on git repositories | [git-scm.com](https://git-scm.com/) |
-| **Supported AI CLI** | The runtime that runs the agents | Claude, Codex, Gemini, or [Kimi Code](user-docs/getting-started-kimi.md) |
-
-### Install
-
-```bash
-npx specrails-core@latest init --root-dir <your-project>
-```
-
-No cloning required. Downloads the latest version and runs the installer automatically.
-
-### From a local clone
-
-```bash
-git clone https://github.com/fjpulidop/specrails-core.git
-cd specrails-core
-npm install
-npm run build
-node bin/specrails-core.mjs init --root-dir <your-project>
-```
-
-> **Important:** Always run the installer from the **target repository** — the project where you want SpecRails installed.
-
-### What the scaffold installer does
-
-The `npx specrails-core@latest init` command now includes a **TUI installer** that runs before copying files:
-
-1. **TUI agent selection** — Interactive terminal UI lets you select which agents to install and choose a model preset (balanced/budget/max). Writes `.specrails/install-config.yaml`.
-2. **Checks prerequisites** — validates Git and the selected provider CLI;
-   optionally installs npm and gh
-3. **Detects existing setup** — warns if SpecRails artifacts already exist
-4. **Installs artifacts:**
-   - `.claude/commands/specrails/enrich.md` — the `/specrails:enrich` wizard
-   - `.specrails/setup-templates/` — agent and command templates (temporary, removed after `/specrails:enrich`)
-   - `.claude/security-exemptions.yaml` — security scanner config
-5. **Tracks version** — writes `.specrails/specrails-version` and `.specrails/specrails-manifest.json`
-
-To skip the TUI and use an existing config: `npx specrails-core@latest init --from-config`
-To skip the TUI and use all defaults: `npx specrails-core@latest init --yes`
-
-The scaffold installer only copies files. It does not modify your existing code, create commits, or push to any remote.
-
----
-
-## The Enrich Wizard
-
-After either installation method, open the selected AI CLI. Claude and Gemini
-use:
-
-```
-/specrails:enrich
-```
-
-Kimi uses:
-
-```text
-/skill:specrails-enrich
-```
-
-That slash form is Kimi TUI syntax. Automated callers use the managed
-`.kimi-code/specrails/run-skill.mjs` helper installed beside the skills; passing
-the slash form directly to `kimi -p` does not activate it in Kimi 0.27.
-Generated multi-role workflows give that helper one structured foreground
-role wave. It owns parallel child processes and reusable worktrees, so no
-Kimi daemon or bundled provider binary is required.
-
-There are three modes:
-
-| Mode | Command | When to use |
-|------|---------|-------------|
-| **Full wizard** (default) | `/specrails:enrich` | Deep stack analysis, researched personas, fully adapted agents — takes 5–10 min |
-| **Quick** | `/specrails:enrich --quick` | Fastest path — 3 questions, sensible defaults, done in under a minute |
-| **From-config** | `/specrails:enrich --from-config` | Non-interactive — reads `.specrails/install-config.yaml` from TUI installer |
-
----
-
-### Full Wizard (default)
-
-The full 5-phase wizard — takes 5–10 minutes and produces deeply adapted agents.
-
-> **Note:** If the TUI installer already captured agent and model preferences, use `/specrails:enrich --from-config` to apply them non-interactively.
-
-### Phase 1: Codebase Analysis
-
-The wizard scans your project to detect:
-
-- **Languages & frameworks** — from file extensions, dependency files, imports
-- **Architecture layers** — name, path, tech stack, tags (e.g., `backend/` → Python/FastAPI)
-- **CI/CD commands** — lint, format, test, build, type-check commands
-- **Conventions** — naming, imports, error handling, testing patterns
-- **Warnings** — concurrency issues, auth patterns, state management
-
-**Output:** A YAML analysis used by all subsequent phases.
-
-### Phase 2: User Personas
-
-The wizard researches your project's domain and generates **user personas** with complete VPC profiles. It:
-
-1. Identifies your target user segments
-2. Researches competitors and alternatives via web search
-3. Creates 2–4 personas with jobs, pains, and gains
-4. Extracts a key insight per persona
-
-You can edit these later (see [Customization → Personas](customization.md#personas)).
-
-### Phase 3: Configuration
-
-Interactive prompts for:
-
-| Setting | Options |
-|---------|---------|
-| **Backlog provider** | Local tickets (default), GitHub Issues, JIRA, or none |
-| **Access mode** | Read-write or read-only |
-| **Git workflow** | Trunk-based, Git Flow, or custom |
-| **Agents** | Which agents to enable (up to 14) |
-| **Commands** | Which commands to install |
-
-### Phase 4: File Generation
-
-The wizard fills all templates with your project-specific context:
-
-- `{{STACK_OVERVIEW}}` → your detected tech stack
-- `{{CI_COMMANDS}}` → your actual CI command list
-- `{{LAYER_CONVENTIONS}}` → conventions per layer
-- `{{BACKEND_TECH_LIST}}` → your backend technologies
-- Every `{{PLACEHOLDER}}` resolved with real data
-
-**Generated files (full set, plugin method):**
-
-```
-.specrails/
-├── config.yaml               # Stack, CI commands, git workflow
-├── personas/
-│   ├── [persona-1].md        # Your user personas (VPC profiles)
-│   └── [persona-2].md
-├── rules/
-│   ├── backend.md            # Per-layer coding conventions
-│   ├── frontend.md
-│   └── ...
-├── agent-memory/             # Persistent agent knowledge
-└── pipeline/                 # In-flight feature state
-```
-
-**Generated files (full set, scaffold method):**
-
-```
-.claude/
-├── agents/
-│   ├── sr-architect.md          # Adapted to your stack
-│   ├── sr-developer.md          # Knows your CI commands
-│   ├── sr-reviewer.md           # Runs your specific checks
-│   ├── sr-product-manager.md    # Knows your domain
-│   ├── sr-product-analyst.md    # Reads your backlog
-│   ├── sr-test-writer.md        # Uses your test framework
-│   ├── sr-security-reviewer.md  # Scans your patterns
-│   ├── sr-doc-sync.md           # Updates your doc format
-│   ├── sr-backend-developer.md  # Backend-specialized
-│   ├── sr-frontend-developer.md # Frontend-specialized
-│   ├── sr-backend-reviewer.md   # Backend quality audit
-│   ├── sr-frontend-reviewer.md  # Frontend quality audit
-│   ├── sr-merge-resolver.md     # AI-powered conflict resolution
-│   ├── sr-performance-reviewer.md # Performance regression detection
-│   └── [personas].md            # Your user personas
-├── commands/
-│   └── sr/
-│       ├── implement.md
-│       ├── get-backlog-specs.md
-│       ├── batch-implement.md
-│       └── ...                  # 17 commands total
-├── rules/
-│   ├── backend.md
-│   ├── frontend.md
-│   └── ...
-└── settings.json
-```
-
-### Phase 5: Cleanup
-
-The wizard removes itself:
-
-- Deletes `.claude/commands/specrails/enrich.md`
-- Deletes `.specrails/setup-templates/`
-- Leaves only the final generated files
-
-After this phase, `/specrails:enrich` is no longer available until re-run — your workflow is ready.
-
----
-
-### Quick Install (TUI → `tier: quick`)
-
-The quick path — select agents in the TUI, answer two context questions, done in seconds. No AI interaction required.
-
-1. Select which agents to install (from 14 available)
-2. Choose a model preset (balanced, budget, or max)
-3. Provide a short product description and target users
-
-**What gets installed:**
-
-| Item | Detail |
-|------|--------|
-| Selected agents | Placed directly in `.claude/agents/` with template defaults |
-| Workflow commands | `/specrails:implement`, `/specrails:doctor`, and more (18 commands) |
-| Rules & settings | Layer conventions, settings.json, security exemptions |
-| Agent memory | `.claude/agent-memory/<agent>/` directories |
-| Skills | OpenSpec skills in `.claude/skills/` |
-
-**What is NOT installed (requires full enrichment):**
-
-| Item | Reason |
-|------|--------|
-| VPC personas | Require competitive research and AI analysis |
-| sr-product-manager | Drives VPC persona creation — needs enrichment |
-| sr-product-analyst | Analyzes personas — needs enrichment |
-| `/specrails:auto-propose-backlog-specs` | Depends on personas |
-| `/specrails:vpc-drift` | Depends on personas |
-| `/specrails:get-backlog-specs` | References personas for prioritization |
-
-Agents work immediately with template defaults. Run `/specrails:enrich` later to add personas, competitive analysis, and codebase-specific customization.
-
----
-
-### From-Config Mode (`/specrails:enrich --from-config`)
-
-Runs a fully automated installation using `.specrails/install-config.yaml`. No interactive prompts — all decisions come from the config file written by the TUI installer.
-
-**Config schema** (`.specrails/install-config.yaml`):
-
-```yaml
-version: 1
-provider: claude        # claude | codex | gemini | kimi
-tier: full              # full (requires /specrails:enrich) | quick (agents placed directly)
-agents:
-  selected:             # unique lowercase kebab-case ids (1-64 chars)
-    - sr-architect
-    - sr-developer
-    - sr-reviewer
-    - sr-test-writer
-    - sr-product-manager
-  excluded: []          # unique ids to skip; must not overlap selected
-models:
-  preset: balanced      # balanced | budget | max
-  defaults:
-    model: sonnet       # exact provider model/alias; Kimi defaults to k3
-  overrides: {}         # exact per-agent models: { sr-architect: opus }
-```
-
-**Model presets:**
-
-| Preset | Description |
-|--------|-------------|
-| `balanced` (default) | Sonnet for all Claude agents |
-| `budget` | Haiku for all agents |
-| `max` | Opus for Claude architect + PM, Sonnet for all others |
-
-Other providers resolve the same preset names within their own catalog. Kimi
-presets default to `k3`; exact official ids and configured aliases are retained.
-Kimi ids must be 1–128 characters matching
-`[A-Za-z0-9][A-Za-z0-9._/:-]*`, the same grammar enforced at process launch.
-
----
-
-## Verify installation
-
-After setup, verify everything is in place:
-
-```bash
-# Plugin method: check generated project data
-ls .specrails/
-
-# Scaffold method: check generated agents
-ls .claude/agents/
-
-# Scaffold method: check for unresolved placeholders (should return nothing)
-grep -r '{{[A-Z_]*}}' .claude/agents/ .claude/commands/ .claude/rules/
-
-# Scaffold method: check version
-cat .specrails/specrails-version
-```
-
----
-
-## Troubleshooting
-
-### Claude Code authentication: OAuth vs API key
-
-Claude Code supports two authentication modes:
-
-- **OAuth** — the default for new installs (`claude auth login`). No API key in `claude config`.
-- **API key** — explicit key set via `claude config set api_key <key>` or the `ANTHROPIC_API_KEY` environment variable.
-
-The installer checks for an API key in `claude config` or `ANTHROPIC_API_KEY`. If you are using OAuth (the default), this check fails even though Claude Code is fully authenticated.
-
-**Workaround:** pass `SPECRAILS_SKIP_PREREQS=1` to bypass the prerequisite gate:
-
-```bash
-SPECRAILS_SKIP_PREREQS=1 npx specrails-core@latest init --root-dir .
-```
-
-Or, if you prefer to authenticate with an API key explicitly:
-
-```bash
-export ANTHROPIC_API_KEY=sk-ant-...
-npx specrails-core@latest init --root-dir .
-```
-
-`SPECRAILS_SKIP_PREREQS=1` skips all hard-exit prerequisite checks (Claude Code presence, API key, and tool availability). Use it only when you know the prerequisites are met.
-
-### "This appears to be the specrails source repository"
-
-You're running the installer from inside the SpecRails repo. Run it from your target project instead:
-
-```bash
-cd /path/to/your-project
-npx specrails-core@latest init
-```
-
-### Existing `.claude/` directory detected
-
-The installer warns if SpecRails artifacts already exist. You can:
-
-- **Merge** — install alongside existing files (may overwrite conflicts)
-- **Abort** — cancel and review manually
-
-### Placeholders not resolved
-
-If you see `{{PLACEHOLDER}}` in generated files (scaffold method), the `/specrails:enrich` wizard didn't complete. Re-run `/specrails:enrich` or manually fill the values.
-
----
-
-## What's next?
-
-- [Core Concepts](concepts.md) — understand the pipeline and agent architecture
-- [Getting Started](getting-started.md) — run your first feature implementation
-
----
-
-[← Getting Started](getting-started.md) · [Core Concepts →](concepts.md)

package/docs/local-tickets.md

@@ -1,191 +0,0 @@
-# Local Ticket Management
-
-specrails-core ships with a built-in, file-based ticket management system. It is the **default backlog provider** — no GitHub account, CLI tool, or external service required.
-
----
-
-## Overview
-
-Tickets live in `.specrails/local-tickets.json` at your project root. Because it's a plain JSON file, tickets are:
-
-- **Version-controlled** — tracked by git, diffable in PRs
-- **Offline-first** — no network calls, no rate limits
-- **Tool-agnostic** — readable by any script or editor
-
-The file is read and written by specrails-core during command execution.
-
----
-
-## Storage format
-
-`.specrails/local-tickets.json`:
-
-```json
-{
-  "schema_version": "1.0",
-  "revision": 7,
-  "last_updated": "2026-03-23T10:00:00.000Z",
-  "next_id": 8,
-  "tickets": {
-    "1": {
-      "id": 1,
-      "title": "Add dark mode",
-      "description": "Support system-level dark mode preference via CSS variables.",
-      "status": "todo",
-      "priority": "medium",
-      "labels": ["area:frontend", "effort:medium"],
-      "assignee": null,
-      "prerequisites": [],
-      "metadata": {
-        "vpc_scores": { "persona-a": 4, "persona-b": 3 },
-        "effort_level": "Medium",
-        "user_story": "As a user working at night, I want dark mode...",
-        "area": "frontend"
-      },
-      "comments": [],
-      "created_at": "2026-03-20T09:00:00.000Z",
-      "updated_at": "2026-03-20T09:00:00.000Z",
-      "created_by": "sr-product-manager",
-      "source": "get-backlog-specs"
-    }
-  }
-}
-```
-
-### Field reference
-
-**Root fields**
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `schema_version` | string | Always `"1.0"` for the current format |
-| `revision` | number | Incremented on every write — used for optimistic concurrency control |
-| `last_updated` | ISO-8601 | Timestamp of the most recent mutation |
-| `next_id` | number | Auto-increment counter for new ticket IDs |
-| `tickets` | object | Map of ticket ID (as string) → ticket object |
-
-**Ticket fields**
-
-| Field | Type | Values | Description |
-|-------|------|--------|-------------|
-| `id` | number | Auto-assigned | Numeric ID, referenced as `#<id>` |
-| `title` | string | — | Short title |
-| `description` | string | Markdown | Full description |
-| `status` | string | `todo`, `in_progress`, `done`, `cancelled` | Current state |
-| `priority` | string | `critical`, `high`, `medium`, `low` | Priority level |
-| `labels` | string[] | Freeform | Tag strings; convention: `area:*`, `effort:*` |
-| `assignee` | string\|null | — | Agent name or user, if assigned |
-| `prerequisites` | number[] | — | IDs of tickets that must be done first |
-| `metadata` | object | — | VPC scores, effort level, user story, area (set by agents) |
-| `comments` | array | — | Progress notes appended during implementation |
-| `created_at` | ISO-8601 | — | Creation timestamp |
-| `updated_at` | ISO-8601 | — | Last mutation timestamp |
-| `created_by` | string | — | Agent name or `"user"` |
-| `source` | string | `manual`, `get-backlog-specs`, `propose-spec` | How the ticket was created |
-
----
-
-## Setup
-
-Local tickets become the default during `/specrails:setup`. The wizard prompts:
-
-```
-## Backlog Provider
-
-Use local ticket management or connect an external provider?
-
-1. Local tickets (default, recommended) — lightweight JSON-based ticket management.
-   No external tools or accounts required.
-2. External provider — connect GitHub Issues, JIRA, or disable backlog commands
-```
-
-Pressing **Enter** or selecting **1** initializes `.specrails/local-tickets.json` with an empty ticket store and writes `.specrails/backlog-config.json`:
-
-```json
-{
-  "provider": "local",
-  "write_access": true,
-  "git_auto": true
-}
-```
-
-To switch providers later, re-run the setup wizard:
-
-```bash
-> /specrails:setup
-```
-
----
-
-## Concurrency model
-
-Multiple agents can modify `local-tickets.json` simultaneously. The system uses two complementary mechanisms:
-
-### Advisory file lock
-
-Before every write, the agent creates `.specrails/local-tickets.json.lock`:
-
-```json
-{
-  "agent": "sr-product-manager",
-  "timestamp": "2026-03-23T10:00:00.000Z"
-}
-```
-
-If the lock file already exists:
-- **Fresh lock** (< 30 seconds old): wait 500 ms and retry, up to 5 attempts
-- **Stale lock** (≥ 30 seconds old): treat as orphaned, delete it, proceed
-
-The lock is deleted immediately after the write completes. The window is minimal: read → modify in memory → write → release.
-
-### Revision counter
-
-Every write increments `revision`. Readers that want to detect external changes compare the `revision` they last saw against the current value.
-
----
-
-## Command integration
-
-### `/specrails:implement`
-
-Pass local ticket IDs the same way you would GitHub issue numbers:
-
-```bash
-/specrails:implement #1, #4, #7
-```
-
-The command reads each ticket from `local-tickets.json`, extracts metadata (area, effort, description), and tracks the ticket through the pipeline — updating status to `in_progress` on start and `done` on successful completion.
-
-### `/specrails:get-backlog-specs`
-
-```bash
-/specrails:get-backlog-specs              # all areas
-/specrails:get-backlog-specs UI, Backend  # filter by area
-```
-
-Reads all `todo` and `in_progress` tickets, scores them by VPC match, respects the `prerequisites` dependency graph, and recommends the top 3 for your next sprint.
-
-### `/specrails:auto-propose-backlog-specs`
-
-```bash
-/specrails:auto-propose-backlog-specs            # explore all areas
-/specrails:auto-propose-backlog-specs Analytics  # focus on one area
-```
-
-Runs product discovery using your VPC personas. Creates new local tickets for discovered feature ideas, tagged with `source: "get-backlog-specs"` and `labels: ["product-driven-backlog", "area:<area>"]`. Existing tickets are checked for duplicates before creating new ones.
-
-### `/specrails:propose-spec`
-
-When a proposal is finalized, a local ticket is created automatically:
-
-```
-Created local ticket #12: Add analytics export
-```
-
-The ticket captures the full proposal as its description and is tagged `source: "propose-spec"` with the label `spec-proposal`.
-
----
-
-## Migrating from GitHub Issues or JIRA
-
-See the [Migration Guide](./migration-guide.md).