specrails-core 4.11.3 → 5.0.0

package/templates/commands/specrails/get-backlog-specs.md

@@ -1,226 +0,0 @@
----
-name: "Product Backlog"
-description: "View product-driven backlog from GitHub Issues and propose top 3 for implementation"
-category: Workflow
-tags: [workflow, backlog, viewer, product-driven]
----
-
-Display the product-driven backlog by reading issues/tickets from the configured backlog provider ({{BACKLOG_PROVIDER_NAME}}). These are feature ideas generated through VPC-based product discovery — evaluated against user personas. Use `/specrails:auto-propose-backlog-specs` to generate new ideas.
-
-**Input:** $ARGUMENTS (optional: comma-separated areas to filter. If empty, show all.)
-
----
-
-## Phase 0: Environment Pre-flight
-
-Verify the backlog provider is accessible:
-
-```bash
-{{BACKLOG_PREFLIGHT}}
-```
-
-If the backlog provider is unavailable, stop and inform the user.
-
----
-
-## Execution
-
-Launch a **single** sr-product-analyst agent (`subagent_type: sr-product-analyst`) to read and prioritize the backlog.
-
-The product-analyst receives this prompt:
-
-> You are reading the product-driven backlog from {{BACKLOG_PROVIDER_NAME}} and producing a prioritized view.
-
-1. **Fetch all open product-driven backlog items:**
-   ```bash
-   {{BACKLOG_FETCH_CMD}}
-   ```
-
-2. **Parse each issue/ticket** to extract metadata from the body:
-   - **Area**: from `area:*` label
-   - **Persona Fit**: from the body's Overview table — extract per-persona scores and total
-   - **Effort**: from the body's Overview table (High/Medium/Low)
-   - **Description**: from the body's "Feature Description" section
-   - **User Story**: from the body's "User Story" section
-
-3. **Parse prerequisites for each issue:**
-   - Locate the row whose first cell matches `**Prerequisites**` in the issue body's Overview table.
-   - If the cell value is `None`, `-`, or empty: set `prereqs = []` for this issue.
-   - Otherwise: extract all tokens matching `#\d+` from the cell and set `prereqs = [<numbers>]`.
-   - If a prerequisite number does not appear in the fetched issue list, treat it as already satisfied (externally closed). Do not include it in the DAG.
-
-4. **Build dependency graph and detect cycles:**
-   - Construct a directed graph where edge `(A → B)` means "issue A must complete before issue B".
-   - For each issue with a non-empty `prereqs` list, add an edge from each prerequisite to the issue.
-   - Run depth-first cycle detection:
-     - Maintain `visited` and `rec_stack` sets.
-     - For each unvisited node, run DFS. If a node in `rec_stack` is encountered, a cycle exists.
-   - Collect all cycle members into `CYCLE_MEMBERS`.
-   - If `CYCLE_MEMBERS` is non-empty, prepare a warning block to render before the backlog table:
-     ```
-     > **Warning: Circular dependency detected in backlog.**
-     > The following issues form a cycle and cannot be safely ordered:
-     > #A -> #B -> #A
-     > Review these issues and correct the Prerequisites fields.
-     ```
-   - Compute `in_degree[issue]` for all issues (count of prerequisite edges pointing to each issue from other open backlog issues).
-
-5. **Compute safe implementation order (Kahn's topological sort):**
-   - Exclude `CYCLE_MEMBERS` from this computation.
-   - Initialize `ready` = all non-cycle issues where `in_degree == 0`.
-   - Sort `ready` by Total Persona Score descending.
-   - Build `WAVES = []`:
-     ```
-     while ready is non-empty:
-         WAVES.append(copy of ready)
-         next_ready = []
-         for each issue in ready:
-             for each dependent D of issue (edges issue → D):
-                 in_degree[D] -= 1
-                 if in_degree[D] == 0: next_ready.append(D)
-         sort next_ready by Total Persona Score descending
-         ready = next_ready
-     ```
-   - Store `WAVE_1 = WAVES[0]` (the set of immediately startable features).
-
-6. **Group by area**.
-
-7. **Sort within each area by Total Persona Score (descending)**, then by Effort (Low > Medium > High) as tiebreaker.
-
-8. **Display** as a formatted table per area, then **propose the top 3 items from `WAVE_1`** (features with all prerequisites satisfied) for implementation. If fewer than 3 are in `WAVE_1`, show as many as available and add: "Note: Only {N} feature(s) are available to start immediately — remaining features have unmet prerequisites."
-
-   [If `CYCLE_MEMBERS` is non-empty, render the cycle warning block immediately before the first area table.]
-
-   Render each area table with the following format:
-   - Append `[blocked]` to the issue title cell if `in_degree[issue] > 0` and the issue is not in `CYCLE_MEMBERS`.
-   - Append `[cycle]` to the issue title cell if the issue is in `CYCLE_MEMBERS`.
-   - `Prereqs` cell: list prerequisite issue numbers as `#N, #M`, or `—` if none.
-
-   ```
-   ## Product-Driven Backlog
-
-   {N} open issues | Source: VPC-based product discovery
-   Personas: {{PERSONA_NAMES_WITH_ROLES}}
-
-   ### {Area Name}
-
-   | # | Issue | {{PERSONA_SCORE_HEADERS}} | Total | Effort | Prereqs |
-   |---|-------|{{PERSONA_SCORE_SEPARATORS}}|-------|--------|---------|
-   | 1 | #42 Feature name [blocked] | ... | X/{{MAX_SCORE}} | Low | #12, #17 |
-   | 2 | #43 Other feature | ... | X/{{MAX_SCORE}} | High | — |
-
-   ---
-
-   ## Recommended Next Sprint (Top 3)
-
-   Ranked by VPC persona score / effort ratio:
-
-   | Priority | Issue | Area | {{PERSONA_SCORE_HEADERS}} | Total | Effort | Rationale |
-   |----------|-------|------|{{PERSONA_SCORE_SEPARATORS}}|-------|--------|-----------|
-
-   ### Selection criteria
-   - Cross-persona features (both 4+/5) prioritized over single-persona
-   - Low effort preferred over high effort at same score
-   - Critical pain relief weighted higher than gain creation
-
-   Run `/specrails:implement` to start implementing these items.
-   ```
-
-9. **Render Safe Implementation Order section** after the Recommended Next Sprint table:
-
-   ```
-   ---
-
-   ## Safe Implementation Order
-
-   Features grouped by wave. All features in a wave can start in parallel.
-   Features in wave N must complete before wave N+1 begins.
-
-   | Wave | Issue | Title | Prereqs | Score | Effort |
-   |------|-------|-------|---------|-------|--------|
-   | 1    | #N    | ...   | —       | X/{{MAX_SCORE}} | Low |
-   | 2    | #M    | ...   | #N      | X/{{MAX_SCORE}} | Medium |
-
-   To implement in this order:
-     /specrails:batch-implement <issue-refs in wave order> --deps "<A> -> <B>, <C> -> <D>, ..."
-
-   [If no edges exist in the DAG, omit the --deps clause:]
-     /specrails:batch-implement <issue-refs>
-
-   [If CYCLE_MEMBERS is non-empty, append:]
-   Cycle members excluded from ordering: #A, #B
-   Fix the Prerequisites fields in these issues to include them.
-   ```
-
-   Issue refs in the `/specrails:batch-implement` command are listed in wave order (wave 1 first, then wave 2, etc.), sorted by persona score within each wave. The `--deps` string is constructed from all edges in the DAG: `"A -> B"` for each edge, comma-separated. If the backlog has no dependencies at all (DAG has no edges), the section still renders showing all features in wave 1 and the `--deps` clause is omitted.
-
-10. If no issues exist:
-    ```
-    No product-driven backlog issues found. Run `/specrails:auto-propose-backlog-specs` to generate feature ideas.
-    ```
-
-7. **[Orchestrator]** After the product-analyst completes, write issue snapshots to `.claude/backlog-cache.json`.
-
-   #### If provider=local — Cache from Local Tickets
-
-   Read `.specrails/local-tickets.json` and parse the `tickets` map. For each ticket with `"product-driven-backlog"` in its `labels` array and `status` not `"cancelled"`, build a snapshot object:
-   - `number`: ticket `id` (integer)
-   - `title`: ticket `title` string
-   - `state`: map ticket `status` — `"done"` or `"cancelled"` → `"closed"`, otherwise → `"open"`
-   - `assignees`: `[ticket.assignee]` if non-null, else `[]`
-   - `labels`: ticket `labels` array, sorted alphabetically
-   - `body_sha`: SHA-256 of the ticket `description` string — compute with:
-     ```bash
-     echo -n "{description}" | sha256sum | cut -d' ' -f1
-     ```
-     If `sha256sum` is not available, fall back to `openssl dgst -sha256 -r` or `shasum -a 256`.
-   - `updated_at`: ticket `updated_at` value
-   - `captured_at`: current local time in ISO 8601 format
-
-   Write to `.claude/backlog-cache.json` with:
-   - `schema_version`: `"1"`
-   - `provider`: `"local"`
-   - `last_updated`: current ISO 8601 timestamp
-   - `written_by`: `"get-backlog-specs"`
-   - `issues`: the map keyed by string ticket ID
-
-   If the write fails: print `[backlog-cache] Warning: could not write cache. Continuing.` Do not abort.
-
-   #### If provider=github — Cache from GitHub Issues
-
-   **Guard:** If `GH_AVAILABLE=false` (from Phase 0 pre-flight), print `[backlog-cache] Skipped — GH unavailable.` and return. Do not attempt the write.
-
-   **Fetch all open backlog issues in one call:**
-
-   ```bash
-   gh issue list --label "product-driven-backlog" --state open --json number,title,state,assignees,labels,body,updatedAt
-   ```
-
-   For each issue in the result, build a snapshot object:
-   - `number`: integer issue number
-   - `title`: issue title string
-   - `state`: `"open"` or `"closed"`
-   - `assignees`: array of assignee login names, sorted alphabetically
-   - `labels`: array of label names, sorted alphabetically
-   - `body_sha`: SHA-256 of the raw body string — compute with:
-     ```bash
-     echo -n "{body}" | sha256sum | cut -d' ' -f1
-     ```
-     If `sha256sum` is not available, fall back to `openssl dgst -sha256 -r` or `shasum -a 256`.
-   - `updated_at`: the `updatedAt` value from the GitHub API response
-   - `captured_at`: current local time in ISO 8601 format
-
-   **Merge strategy:** If `.claude/backlog-cache.json` already exists and is valid JSON, read it and merge: new snapshot entries overwrite existing entries by issue number key; entries for issue numbers not in the current fetch are preserved (they may be needed by an in-progress `/specrails:implement` run). If the file does not exist or is malformed, create it fresh.
-
-   Write the merged result back to `.claude/backlog-cache.json` with:
-   - `schema_version`: `"1"`
-   - `provider`: `"github"`
-   - `last_updated`: current ISO 8601 timestamp
-   - `written_by`: `"get-backlog-specs"`
-   - `issues`: the merged map keyed by string issue number
-
-   If the write fails (e.g., `.claude/` directory does not exist): print `[backlog-cache] Warning: could not write cache. Continuing.` Do not abort.
-
-   #### If provider=jira or provider=none
-
-   Print `[backlog-cache] Skipped — provider does not support cache.` Do not attempt the write.

package/templates/commands/specrails/merge-resolve.md

@@ -1,172 +0,0 @@
-# Smart Merge Conflict Resolver
-
-Resolves git conflict markers in working tree files using AI-powered context analysis. For each conflict block, reads OpenSpec context bundles from the features that produced the conflict, infers the correct resolution, and writes it in place — or preserves clean markers for conflicts it cannot safely resolve.
-
-**IMPORTANT: Always follow this procedure exactly as written. Launch the sr-merge-resolver agent as specified. Do NOT attempt to resolve conflicts yourself in the main conversation.**
-
-**Input:** `$ARGUMENTS` — flags controlling which files to process, where to find context, and resolution behavior.
-
----
-
-## Step 1: Parse flags
-
-Scan `$ARGUMENTS` for the following flags:
-
-### `--files <paths>`
-
-**Type:** space-separated file paths or glob patterns
-**Default:** auto-detect (scan working tree)
-
-Explicit list of files to process. If a path contains `*` or `?`, treat it as a glob and expand it. Strip this flag and its value from `$ARGUMENTS` before further processing.
-
-### `--context <directory>`
-
-**Type:** directory path
-**Default:** `openspec/changes/`
-
-Directory to scan for context bundles. The command globs `<directory>/*/context-bundle.md`. Strip this flag and its value from `$ARGUMENTS` before further processing.
-
-### `--threshold N`
-
-**Type:** integer 0–100
-**Default:** 70
-
-Minimum confidence score for the resolver to apply an AI resolution. Below this threshold, the resolver preserves conflict markers in normalized format. Strip this flag and its value from `$ARGUMENTS` before further processing.
-
-### `--mode auto|manual-fallback-only`
-
-**Type:** enum
-**Default:** `auto`
-
-- `auto`: attempt AI resolution for each conflict block
-- `manual-fallback-only`: only normalize conflict marker format; do not attempt AI resolution
-
-Strip this flag and its value from `$ARGUMENTS` before further processing.
-
-After parsing, if any unrecognized flags remain in `$ARGUMENTS`: print a warning:
-```
-[merge-resolve] Warning: unrecognized flags ignored: <remaining>
-```
-
----
-
-## Step 2: Detect conflicted files
-
-### If `--files` was provided:
-
-For each path (or expanded glob): check that the file exists. If a path does not exist: print `[merge-resolve] Warning: <path> not found — skipped.` and remove it from the list.
-
-Filter to only files containing `<<<<<<<`. For any file in the provided list that does NOT contain `<<<<<<<`: print `[merge-resolve] <path>: no conflict markers found — skipped.`
-
-### If `--files` was NOT provided:
-
-Scan the entire working tree for files containing `<<<<<<<`:
-
-```bash
-grep -rl "<<<<<<< " . --include="*" 2>/dev/null
-```
-
-Exclude `.git/` directory from results.
-
-If no conflicted files are found (either from explicit list or auto-detect):
-
-```
-[merge-resolve] No conflict markers found in the working tree.
-Nothing to do.
-```
-
-Exit cleanly.
-
-Otherwise, print:
-```
-[merge-resolve] Found N conflicted file(s):
-  - path/to/file.ts
-  - path/to/other.md
-```
-
----
-
-## Step 3: Load context bundles
-
-Glob `<context-directory>/*/context-bundle.md`.
-
-Build `CONTEXT_BUNDLES` map: for each matched path, the key is the subdirectory name (the feature name), the value is the file path.
-
-Example:
-```
-openspec/changes/feature-a/context-bundle.md  →  { "feature-a": "openspec/changes/feature-a/context-bundle.md" }
-openspec/changes/feature-b/context-bundle.md  →  { "feature-b": "openspec/changes/feature-b/context-bundle.md" }
-```
-
-If no context bundles are found:
-```
-[merge-resolve] No context bundles found at <context-directory>.
-The resolver will use structural analysis only (no feature-intent context).
-```
-
-Set `CONTEXT_BUNDLES = {}`.
-
----
-
-## Step 4: Launch sr-merge-resolver agent
-
-Construct the agent prompt with:
-
-- `CONFLICTED_FILES`: the list of conflicted file paths
-- `CONTEXT_BUNDLES`: the map built in Step 3
-- `CONFIDENCE_THRESHOLD`: the `--threshold` value (default 70)
-- `RESOLUTION_MODE`: the `--mode` value (default `auto`)
-- `REPORT_PATH`: `openspec/changes/<first-feature>/merge-resolution-report.md` if CONTEXT_BUNDLES has entries; otherwise `merge-resolution-report.md` in the working directory root
-
-Launch the **sr-merge-resolver** agent (`subagent_type: sr-merge-resolver`, foreground, `run_in_background: false`). Wait for it to complete.
-
-Read the final `MERGE_RESOLUTION_STATUS` line from the agent's output.
-
----
-
-## Step 5: Print summary
-
-After the agent completes, print:
-
-```
-## Merge Resolution Complete
-
-| Metric | Count |
-|--------|-------|
-| Files processed | N |
-| Conflicts found | N |
-| Auto-resolved | N |
-| Low-confidence (kept) | N |
-| Skipped | N |
-
-Resolution report: <REPORT_PATH>
-```
-
-If `MERGE_RESOLUTION_STATUS = PARTIAL` or `UNRESOLVED`:
-
-```
-## Remaining Conflicts
-
-The following files still contain conflict markers that require manual resolution:
-
-  - path/to/file.ts (N block(s))
-
-Search for `<<<<<<<` in each file to locate the markers.
-Run `/specrails:merge-resolve` again after addressing the low-confidence conflicts,
-or resolve them manually and commit.
-```
-
-If `MERGE_RESOLUTION_STATUS = CLEAN`:
-
-```
-All conflict markers resolved. Working tree is clean.
-You can now stage and commit the resolved files.
-```
-
----
-
-## Error Handling
-
-- If the agent fails or times out: print `[merge-resolve] Error: sr-merge-resolver did not complete. Files may be partially modified — check for remaining conflict markers before committing.` Exit with a non-zero status.
-- If a file becomes unreadable mid-run (e.g. deleted): log `[merge-resolve] Warning: <path> disappeared during processing — skipped.`
-- Never abort silently. Always print a final status.

package/templates/commands/specrails/reconfig.md

@@ -1,80 +0,0 @@
-# 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
-
-This command targets the Claude install: set `$AGENTS_DIR = .claude/agents`. (Codex agents are codex-native rails under `.codex/skills/rails/` and carry no per-agent `model:` config — codex `spawn_agent` forks don't accept a model — so reconfig does not apply to codex projects.)
-
-## 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.
-
-## 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.
-```