specrails-desktop 2.0.0

package/.claude/commands/specrails/propose-spec.md

@@ -0,0 +1,102 @@
+---
+description: Explore a spec idea and produce a structured proposal
+---
+
+You are a senior product engineer helping evaluate and structure a spec proposal for this codebase.
+
+The user's raw idea is:
+
+$ARGUMENTS
+
+## Your Task
+
+Before proposing anything, explore the codebase to understand:
+1. What already exists that relates to this idea
+2. What the current architecture looks like in the relevant area
+3. What constraints or patterns you must respect
+
+Use Read, Glob, and Grep to explore. Take at least 3 codebase reads before writing the proposal.
+
+## Required Output
+
+Output ONLY the following structured markdown. Do not add any preamble or explanation outside these sections.
+
+## Spec Title
+[A concise, action-oriented title, e.g., "Add Real-Time Cost Alerts"]
+
+## Problem Statement
+[2-3 sentences: what problem does this solve? Who experiences it? What is the current workaround?]
+
+## Proposed Solution
+[3-5 sentences: what exactly will be built? Be specific about the UI, API, and data changes.]
+
+## Out of Scope
+[Bullet list of things this proposal deliberately does NOT cover]
+
+## Acceptance Criteria
+[Numbered list of testable outcomes. Each criterion must be independently verifiable.]
+
+## Technical Considerations
+[Bullet list of implementation notes, constraints from the existing architecture, risks, and dependencies]
+
+## Estimated Complexity
+[One of: Low (< 1 day) / Medium (1-3 days) / High (3-7 days) / Very High (> 1 week)]
+[One sentence justifying the estimate]
+
+---
+
+## Backlog Sync
+
+After generating the proposal, read `.specrails/backlog-config.json` to determine `BACKLOG_PROVIDER` and `BACKLOG_WRITE`.
+
+If `.specrails/backlog-config.json` does not exist, default to `provider=local` and `write_access=true`. Initialize `.specrails/local-tickets.json` if it does not exist (empty store with `schema_version: "1.0"`, `revision: 0`, `next_id: 1`, `tickets: {}`).
+
+### If provider=local — Create Local Ticket
+
+Create a local ticket from the proposal output:
+
+```
+
+```
+
+Set the following fields:
+- `title`: The Spec Title from the proposal
+- `description`: The full structured proposal markdown (all sections from Problem Statement through Estimated Complexity)
+- `status`: `"todo"`
+- `priority`: Map Estimated Complexity — Low → `"low"`, Medium → `"medium"`, High/Very High → `"high"`
+- `labels`: `["spec-proposal"]`
+- `source`: `"propose-spec"`
+- `created_by`: `"sr-product-engineer"`
+
+Print: `Created local ticket #{id}: {title}`
+
+### If provider=github and BACKLOG_WRITE=true — Create GitHub Issue
+
+```bash
+
+```
+
+Create a GitHub Issue with:
+- Title: The Spec Title
+- Body: Full structured proposal markdown
+- Labels: `spec-proposal`
+
+Print: `Created GitHub Issue #{number}: {title}`
+
+### If provider=jira and BACKLOG_WRITE=true — Create JIRA Story
+
+Create a JIRA Story using the same authentication and API pattern as `/specrails:auto-propose-backlog-specs`:
+- Summary: The Spec Title
+- Description: Full structured proposal in Atlassian Document Format
+- Labels: `spec-proposal`
+
+Print: `Created JIRA ticket {key}: {title}`
+
+### If BACKLOG_WRITE=false or provider=none
+
+Do NOT create any tickets. Print:
+```
+Spec proposal ready. Create a ticket manually if desired:
+  Title: {Spec Title}
+  Complexity: {Estimated Complexity}
+```

package/.claude/commands/specrails/reconfig.md

@@ -0,0 +1,89 @@
+# Reconfig: Apply Agent Config to Generated Files
+
+Reads `.specrails/agents.yaml` and updates the `model:` frontmatter field in all generated `.claude/agents/sr-*.md` files to match. No full re-setup needed — only model frontmatter is changed.
+
+---
+
+## Step 1: Locate generated agents directory
+
+Determine `$SPECRAILS_DIR`:
+
+1. If `.codex/agents/` exists, set `cli_provider = "codex"` and `specrails_dir = ".codex"`.
+2. Otherwise set `cli_provider = "claude"` and `specrails_dir = ".claude"`.
+3. Set `$AGENTS_DIR = $SPECRAILS_DIR/agents`
+
+## Step 2: Read agent config
+
+Read `.specrails/agents.yaml`.
+
+If the file does not exist, stop and display:
+
+```
+No .specrails/agents.yaml found.
+
+Run /specrails:enrich to generate the config file, then edit it before running /specrails:reconfig.
+```
+
+If the file exists, parse it. Validate all `model:` values — only `opus`, `sonnet`, and `haiku` are accepted. If an invalid value is found, display a warning and skip that agent:
+
+```
+Warning: unknown model "gpt-4" for sr-developer — skipping (valid values: opus, sonnet, haiku)
+```
+
+## Step 3: Resolve model for each agent
+
+For each agent file found in `$AGENTS_DIR/sr-*.md`:
+
+1. Extract the agent name from the filename (e.g., `sr-developer.md` → `sr-developer`)
+2. Resolve the target model:
+   - Check `agents.<agent-name>.model` in config (per-agent override)
+   - If not present, check `defaults.model` in config (global default)
+   - If neither is present, skip this agent
+3. Read the current `model:` value from the file's YAML frontmatter
+4. If the current model matches the target model, mark as **unchanged**
+5. If they differ, record the change: `sr-<name>: <current> → <target>`
+
+## Step 4: Apply changes
+
+For each agent with a recorded change:
+
+1. Read the file
+2. Replace the `model:` line in the YAML frontmatter with the resolved value
+3. Write the file back
+
+The `model:` line is always in the frontmatter block (between the first `---` and second `---`). Replace only that specific line — do not modify any other content.
+
+**Codex format:** If `cli_provider == "codex"`, apply the same logic to `.codex/agents/sr-*.toml` files. Replace the `model = "..."` line with the mapped Codex model:
+- `sonnet` → `codex-mini-latest`
+- `opus` → `o3`
+- `haiku` → `codex-mini-latest`
+
+## Step 5: Report results
+
+Display a summary of what changed:
+
+```
+## Reconfig complete
+
+Updated 2 agent(s):
+  sr-developer:       sonnet → opus
+  sr-product-analyst: haiku  → sonnet
+
+Unchanged (3):
+  sr-architect, sr-reviewer, sr-product-manager
+
+Skipped (1):
+  sr-custom-agent (not in config)
+```
+
+If nothing changed:
+
+```
+All agents already match .specrails/agents.yaml — nothing to update.
+```
+
+If all agents were skipped due to validation errors, display:
+
+```
+No agents updated. Fix the validation errors in .specrails/agents.yaml and retry.
+```

package/.claude/commands/specrails/refactor-recommender.md

@@ -0,0 +1,212 @@
+---
+name: "Refactor Recommender"
+description: "Scan the codebase for refactoring opportunities ranked by impact/effort ratio and VPC persona value. Analyzes code for duplicates, long functions, large files, dead code, outdated patterns, and complex logic. Optionally creates GitHub Issues for tracking."
+category: Workflow
+tags: [workflow, refactoring, code-quality, tech-debt, vpc]
+---
+
+Scan the codebase for refactoring opportunities, score each by impact/effort ratio and VPC persona value, and optionally create GitHub Issues for the top findings in .
+
+**Input:** `$ARGUMENTS` — optional: comma-separated paths to scope the analysis. Flags: `--dry-run` (print findings without creating issues).
+
+---
+
+## Phase 0: Pre-flight
+
+Check whether the GitHub CLI is available:
+
+```bash
+
+```
+
+Set `GH_AVAILABLE=true` if the command succeeds, `GH_AVAILABLE=false` otherwise. Do not stop — analysis proceeds regardless. Parse `--dry-run` from `$ARGUMENTS` and set `DRY_RUN=true` if present.
+
+---
+
+## Phase 1: Scope
+
+Parse paths from `$ARGUMENTS` after stripping any flags. If no paths are provided, scan the entire repository.
+
+Always exclude the following from all analysis:
+
+- `node_modules/`
+- `.git/`
+- `.claude/`
+- `vendor/`
+- `dist/`
+- `build/`
+
+---
+
+## Phase 1.5: VPC Context
+
+Check whether persona files exist at `.claude/agents/personas/`. This path is present in any repo that has run `/specrails:enrich`.
+
+```bash
+ls .claude/agents/personas/ 2>/dev/null
+```
+
+If the directory exists and contains persona files, set `VPC_AVAILABLE=true`. Otherwise set `VPC_AVAILABLE=false` and skip all VPC steps (they are optional enrichment, not blockers).
+
+When `VPC_AVAILABLE=true`, read each persona file and extract a compact VPC summary. For each persona record:
+
+- **name** — persona display name (e.g. "Alex — The Lead Dev")
+- **top_jobs** — up to 3 functional jobs relevant to code quality and maintainability
+- **critical_pains** — up to 3 pains marked Critical or High related to code reliability, complexity, or developer experience
+- **high_gains** — up to 3 gains marked High related to code clarity, speed, or confidence
+
+Store these as an in-memory `VPC_PROFILES` list. You will use it in Phase 3 to score persona fit.
+
+---
+
+## Phase 2: Analysis
+
+Analyze the scoped files across six categories. For each finding record:
+
+- **file** — relative path
+- **line_range** — start and end line numbers
+- **current_snippet** — the problematic code as-is
+- **proposed_snippet** — concrete refactored version
+- **rationale** — one sentence explaining the improvement
+
+### Duplicate Code
+
+Find code blocks larger than 10 lines that are substantially similar across two or more files. Consolidation into a shared function or module is the expected refactoring.
+
+### Long Functions
+
+Find functions or methods exceeding 50 lines. Extraction into smaller, single-purpose functions is the expected refactoring.
+
+### Large Files
+
+Find files exceeding 300 lines. Splitting into cohesive modules is the expected refactoring.
+
+### Dead Code
+
+Find unused exports, unreferenced functions, and commented-out blocks that have not been active for the lifetime of the file. Deletion or archival is the expected refactoring.
+
+### Outdated Patterns
+
+Find deprecated APIs and old language syntax: `var` instead of `let`/`const`, callbacks instead of `async`/`await`, legacy framework APIs with documented replacements, etc. Modernisation to current idioms is the expected refactoring.
+
+### Complex Logic
+
+Find deeply nested conditionals (more than 3 levels) and functions with high cyclomatic complexity. Extraction, early-return guards, or strategy patterns are the expected refactoring.
+
+---
+
+## Phase 3: Score and Rank
+
+Score every finding on three dimensions (1–5 each):
+
+- **Impact** — how much the refactoring improves code quality, readability, or maintainability
+- **Effort** — how hard the refactoring is to implement (1 = trivial, 5 = major)
+- **VPC Value** — how directly this refactoring addresses persona jobs, pains, or gains (1 = no relevance, 5 = resolves a critical persona pain or delivers a high-value gain). Set to 3 when `VPC_AVAILABLE=false`.
+
+**Scoring VPC Value** (only when `VPC_AVAILABLE=true`):
+
+For each finding, reason over `VPC_PROFILES`:
+
+- Does fixing this reduce a **Critical/High pain** for any persona? (e.g. complex logic → harder to trust AI output → Alex's "agents go off the rails" pain) → score 4–5
+- Does fixing this deliver a **High gain** for any persona? (e.g. extracting a function → cleaner API surface → easier onboarding → Sara's gain) → score 3–4
+- Is there indirect persona value? (e.g. dead code removal → smaller codebase → easier contributor review → Kai) → score 2–3
+- No clear persona relevance → score 1–2
+
+Assign one `vpc_value` integer per finding, and note the **primary persona** and **rationale** (one sentence).
+
+**Composite score**: `impact * 2 + (6 - effort) + vpc_value`. Higher is better.
+
+Sort all findings by composite score descending. If the same code block was flagged by multiple categories, keep only the highest-scored entry and discard the duplicates.
+
+---
+
+## Phase 4: Create GitHub Issues
+
+Skip this phase if `GH_AVAILABLE=false` or `DRY_RUN=true`.
+
+First ensure the tracking labels exist:
+
+```bash
+gh label create "refactor-opportunity" --color "B60205" --force
+```
+
+Fetch existing open issues that already carry the label to avoid duplicates:
+
+```bash
+gh issue list --label "refactor-opportunity" --state open --limit 100 --json number,title
+```
+
+For each of the **top 5** findings (by composite score) that does not already have a matching open issue, create a GitHub Issue with the following body:
+
+```
+## Refactoring Opportunity: {description}
+
+**Category**: {category}
+**File**: {file}:{line_range}
+**Impact**: {impact}/5 | **Effort**: {effort}/5 | **Score**: {composite}
+{vpc_line}
+
+### Current Code
+```{lang}
+{current_snippet}
+```
+
+### Proposed Refactoring
+```{lang}
+{proposed_snippet}
+```
+
+### Rationale
+{rationale}
+
+---
+_Generated by `/specrails:refactor-recommender` in specrails-desktop_
+```
+
+Where `{vpc_line}` is included only when `VPC_AVAILABLE=true`:
+`**VPC Value**: {vpc_value}/5 — {vpc_persona}: {vpc_rationale}`
+
+---
+
+## Phase 5: Output Summary
+
+Print the following report:
+
+```
+## Refactoring Opportunities — specrails-desktop
+
+{N} opportunities found | Sorted by composite score
+{vpc_header}
+
+| # | Category | File | Impact | Effort | VPC | Score | Description |
+|---|----------|------|--------|--------|-----|-------|-------------|
+| 1 | {category} | {file}:{line_range} | {impact}/5 | {effort}/5 | {vpc_value}/5 | {composite} | {description} |
+...
+
+### Top 3 Detailed Recommendations
+
+#### 1. {description}
+**File**: {file}:{line_range}
+**Category**: {category} | **Score**: {composite}
+{vpc_detail}
+
+**Current:**
+```{lang}
+{current_snippet}
+```
+
+**Proposed:**
+```{lang}
+{proposed_snippet}
+```
+
+**Rationale:** {rationale}
+
+(repeat for #2 and #3)
+
+Issues created: {N}  (or "dry-run: no issues created")
+```
+
+Where:
+- `{vpc_header}` is `VPC personas loaded: {persona names}` when `VPC_AVAILABLE=true`, or `VPC personas: not found (run /specrails:enrich to enable)` otherwise.
+- `{vpc_detail}` is `**VPC Value**: {vpc_value}/5 — {vpc_persona}: {vpc_rationale}` when `VPC_AVAILABLE=true`, omitted otherwise.