specrails-core 4.4.0 → 4.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specrails-core",
-  "version": "4.4.0",
+  "version": "4.5.0",
   "description": "AI agent workflow system for Claude Code — installs 12 specialized agents, orchestration commands, and persona-driven product discovery into any repository",
   "type": "module",
   "bin": {

package/templates/agents/sr-architect.md

@@ -218,10 +218,15 @@ Guidelines:
 
 Your MEMORY.md is currently empty. When you notice a pattern worth preserving across sessions, save it here.
 
-## Tool Selection — Honor Project-Documented MCP Tools
+## Tool Selection — MCP-First for Codebase Tasks
 
-The project's `CLAUDE.md` may list MCP tools made available via plugin systems (e.g., specrails-hub Integrations). Each entry typically declares (a) tool names, (b) when to use them, (c) what they return.
+**Mandatory step BEFORE any code-navigation tool call**: scan the project's `CLAUDE.md` for MCP tool blocks (typically headed `## Plugin: <name>` and listing `mcp__*` tool names with declared use-cases).
 
-Before defaulting to built-in tools (`Read`, `Grep`, `Bash`, `WebFetch`, etc.), scan that documentation. When a project-documented MCP tool's declared use-case matches your current need, prefer it over the built-in equivalent — the plugin author chose it for a measurable advantage (lower token cost, higher precision, fresher data, semantic awareness, etc.).
+If a project-documented MCP tool's "When to use" matches your current need, you **MUST** call it instead of the built-in equivalent (`Read`, `Grep`, `WebFetch`, etc.). Built-in fallbacks are reserved for cases the documented tools explicitly exclude (binary files, free-form prose, unstructured logs) or for non-codebase concerns (project-state files, config inspection, system commands).
 
-Fall back to built-ins when no plugin tool fits, or when the documented tool fails to execute in the current environment.
+This is non-negotiable for code-navigation work: plugin authors choose tools because they have a measurable advantage (40–60% input-token reduction is typical). Skipping them defaults the project to the most expensive code-reading path.
+
+**Quick decision check at every code-related tool call**:
+- Is this a symbol/reference/definition lookup? → MCP tool, not `Grep`/`Read`.
+- Am I about to read a file just to edit one function? → MCP tool, not `Read` + `Edit`.
+- No documented MCP tool fits the current need? → built-in, document why in your reasoning.

package/templates/agents/sr-backend-developer.md

@@ -53,10 +53,15 @@ Guidelines:
 
 Your MEMORY.md is currently empty.
 
-## Tool Selection — Honor Project-Documented MCP Tools
+## Tool Selection — MCP-First for Codebase Tasks
 
-The project's `CLAUDE.md` may list MCP tools made available via plugin systems (e.g., specrails-hub Integrations). Each entry typically declares (a) tool names, (b) when to use them, (c) what they return.
+**Mandatory step BEFORE any code-navigation tool call**: scan the project's `CLAUDE.md` for MCP tool blocks (typically headed `## Plugin: <name>` and listing `mcp__*` tool names with declared use-cases).
 
-Before defaulting to built-in tools (`Read`, `Grep`, `Bash`, `WebFetch`, etc.), scan that documentation. When a project-documented MCP tool's declared use-case matches your current need, prefer it over the built-in equivalent — the plugin author chose it for a measurable advantage (lower token cost, higher precision, fresher data, semantic awareness, etc.).
+If a project-documented MCP tool's "When to use" matches your current need, you **MUST** call it instead of the built-in equivalent (`Read`, `Grep`, `WebFetch`, etc.). Built-in fallbacks are reserved for cases the documented tools explicitly exclude (binary files, free-form prose, unstructured logs) or for non-codebase concerns (project-state files, config inspection, system commands).
 
-Fall back to built-ins when no plugin tool fits, or when the documented tool fails to execute in the current environment.
+This is non-negotiable for code-navigation work: plugin authors choose tools because they have a measurable advantage (40–60% input-token reduction is typical). Skipping them defaults the project to the most expensive code-reading path.
+
+**Quick decision check at every code-related tool call**:
+- Is this a symbol/reference/definition lookup? → MCP tool, not `Grep`/`Read`.
+- Am I about to read a file just to edit one function? → MCP tool, not `Read` + `Edit`.
+- No documented MCP tool fits the current need? → built-in, document why in your reasoning.

package/templates/agents/sr-backend-reviewer.md

@@ -138,10 +138,15 @@ What to save:
 
 Your MEMORY.md is currently empty.
 
-## Tool Selection — Honor Project-Documented MCP Tools
+## Tool Selection — MCP-First for Codebase Tasks
 
-The project's `CLAUDE.md` may list MCP tools made available via plugin systems (e.g., specrails-hub Integrations). Each entry typically declares (a) tool names, (b) when to use them, (c) what they return.
+**Mandatory step BEFORE any code-navigation tool call**: scan the project's `CLAUDE.md` for MCP tool blocks (typically headed `## Plugin: <name>` and listing `mcp__*` tool names with declared use-cases).
 
-Before defaulting to built-in tools (`Read`, `Grep`, `Bash`, `WebFetch`, etc.), scan that documentation. When a project-documented MCP tool's declared use-case matches your current need, prefer it over the built-in equivalent — the plugin author chose it for a measurable advantage (lower token cost, higher precision, fresher data, semantic awareness, etc.).
+If a project-documented MCP tool's "When to use" matches your current need, you **MUST** call it instead of the built-in equivalent (`Read`, `Grep`, `WebFetch`, etc.). Built-in fallbacks are reserved for cases the documented tools explicitly exclude (binary files, free-form prose, unstructured logs) or for non-codebase concerns (project-state files, config inspection, system commands).
 
-Fall back to built-ins when no plugin tool fits, or when the documented tool fails to execute in the current environment.
+This is non-negotiable for code-navigation work: plugin authors choose tools because they have a measurable advantage (40–60% input-token reduction is typical). Skipping them defaults the project to the most expensive code-reading path.
+
+**Quick decision check at every code-related tool call**:
+- Is this a symbol/reference/definition lookup? → MCP tool, not `Grep`/`Read`.
+- Am I about to read a file just to edit one function? → MCP tool, not `Read` + `Edit`.
+- No documented MCP tool fits the current need? → built-in, document why in your reasoning.

package/templates/agents/sr-developer.md

@@ -49,19 +49,25 @@ When an OpenSpec change is being applied, you:
 4. **Implement the changes** with surgical precision across all affected layers
 5. **Ensure consistency** with the existing codebase style, patterns, and architecture
 
-## Tool Selection — Honor Project-Documented MCP Tools
+## Tool Selection — MCP-First for Codebase Tasks
 
-The project's `CLAUDE.md` may list MCP tools made available via plugin systems (e.g., specrails-hub Integrations). Each entry typically declares (a) tool names, (b) when to use them, (c) what they return.
+**Mandatory step BEFORE any code-navigation tool call**: scan the project's `CLAUDE.md` for MCP tool blocks (typically headed `## Plugin: <name>` and listing `mcp__*` tool names with declared use-cases).
 
-Before defaulting to built-in tools (`Read`, `Grep`, `Bash`, `WebFetch`, etc.), scan that documentation. When a project-documented MCP tool's declared use-case matches your current need, prefer it over the built-in equivalent — the plugin author chose it for a measurable advantage (lower token cost, higher precision, fresher data, semantic awareness, etc.).
+If a project-documented MCP tool's "When to use" matches your current need, you **MUST** call it instead of the built-in equivalent (`Read`, `Grep`, `WebFetch`, etc.). Built-in fallbacks are reserved for cases the documented tools explicitly exclude (binary files, free-form prose, unstructured logs) or for non-codebase concerns (project-state files, config inspection, system commands).
 
-Fall back to built-ins when no plugin tool fits, or when the documented tool fails to execute in the current environment.
+This is non-negotiable for code-navigation work: plugin authors choose tools because they have a measurable advantage (40–60% input-token reduction is typical). Skipping them defaults the project to the most expensive code-reading path.
+
+**Quick decision check at every code-related tool call**:
+- Is this a symbol/reference/definition lookup? → MCP tool, not `Grep`/`Read`.
+- Am I about to read a file just to edit one function? → MCP tool, not `Read` + `Edit`.
+- No documented MCP tool fits the current need? → built-in, document why in your reasoning.
 
 ## Workflow Protocol — Strict TDD
 
 You MUST follow Test-Driven Development. This is non-negotiable. The cycle is: **Red → Green → Refactor**. Never write production code without a failing test first.
 
 ### Phase 1: Understand
+- **First, scan the project's `CLAUDE.md` for MCP tool blocks** (headed `## Plugin: <name>`) — these define the code-navigation primitives you must reach for in this and every later phase. See "Tool Selection — MCP-First" above. Internalise the available tools BEFORE you start reading files.
 - Read the OpenSpec change spec thoroughly
 - Read referenced base specs
 - Read layer-specific CLAUDE.md files ({{LAYER_CLAUDE_MD_PATHS}})

package/templates/agents/sr-doc-sync.md

@@ -233,10 +233,15 @@ What to save:
 
 Your MEMORY.md is currently empty.
 
-## Tool Selection — Honor Project-Documented MCP Tools
+## Tool Selection — MCP-First for Codebase Tasks
 
-The project's `CLAUDE.md` may list MCP tools made available via plugin systems (e.g., specrails-hub Integrations). Each entry typically declares (a) tool names, (b) when to use them, (c) what they return.
+**Mandatory step BEFORE any code-navigation tool call**: scan the project's `CLAUDE.md` for MCP tool blocks (typically headed `## Plugin: <name>` and listing `mcp__*` tool names with declared use-cases).
 
-Before defaulting to built-in tools (`Read`, `Grep`, `Bash`, `WebFetch`, etc.), scan that documentation. When a project-documented MCP tool's declared use-case matches your current need, prefer it over the built-in equivalent — the plugin author chose it for a measurable advantage (lower token cost, higher precision, fresher data, semantic awareness, etc.).
+If a project-documented MCP tool's "When to use" matches your current need, you **MUST** call it instead of the built-in equivalent (`Read`, `Grep`, `WebFetch`, etc.). Built-in fallbacks are reserved for cases the documented tools explicitly exclude (binary files, free-form prose, unstructured logs) or for non-codebase concerns (project-state files, config inspection, system commands).
 
-Fall back to built-ins when no plugin tool fits, or when the documented tool fails to execute in the current environment.
+This is non-negotiable for code-navigation work: plugin authors choose tools because they have a measurable advantage (40–60% input-token reduction is typical). Skipping them defaults the project to the most expensive code-reading path.
+
+**Quick decision check at every code-related tool call**:
+- Is this a symbol/reference/definition lookup? → MCP tool, not `Grep`/`Read`.
+- Am I about to read a file just to edit one function? → MCP tool, not `Read` + `Edit`.
+- No documented MCP tool fits the current need? → built-in, document why in your reasoning.

package/templates/agents/sr-frontend-developer.md

@@ -47,10 +47,15 @@ Guidelines:
 
 Your MEMORY.md is currently empty.
 
-## Tool Selection — Honor Project-Documented MCP Tools
+## Tool Selection — MCP-First for Codebase Tasks
 
-The project's `CLAUDE.md` may list MCP tools made available via plugin systems (e.g., specrails-hub Integrations). Each entry typically declares (a) tool names, (b) when to use them, (c) what they return.
+**Mandatory step BEFORE any code-navigation tool call**: scan the project's `CLAUDE.md` for MCP tool blocks (typically headed `## Plugin: <name>` and listing `mcp__*` tool names with declared use-cases).
 
-Before defaulting to built-in tools (`Read`, `Grep`, `Bash`, `WebFetch`, etc.), scan that documentation. When a project-documented MCP tool's declared use-case matches your current need, prefer it over the built-in equivalent — the plugin author chose it for a measurable advantage (lower token cost, higher precision, fresher data, semantic awareness, etc.).
+If a project-documented MCP tool's "When to use" matches your current need, you **MUST** call it instead of the built-in equivalent (`Read`, `Grep`, `WebFetch`, etc.). Built-in fallbacks are reserved for cases the documented tools explicitly exclude (binary files, free-form prose, unstructured logs) or for non-codebase concerns (project-state files, config inspection, system commands).
 
-Fall back to built-ins when no plugin tool fits, or when the documented tool fails to execute in the current environment.
+This is non-negotiable for code-navigation work: plugin authors choose tools because they have a measurable advantage (40–60% input-token reduction is typical). Skipping them defaults the project to the most expensive code-reading path.
+
+**Quick decision check at every code-related tool call**:
+- Is this a symbol/reference/definition lookup? → MCP tool, not `Grep`/`Read`.
+- Am I about to read a file just to edit one function? → MCP tool, not `Read` + `Edit`.
+- No documented MCP tool fits the current need? → built-in, document why in your reasoning.

package/templates/agents/sr-frontend-reviewer.md

@@ -131,10 +131,15 @@ What to save:
 
 Your MEMORY.md is currently empty.
 
-## Tool Selection — Honor Project-Documented MCP Tools
+## Tool Selection — MCP-First for Codebase Tasks
 
-The project's `CLAUDE.md` may list MCP tools made available via plugin systems (e.g., specrails-hub Integrations). Each entry typically declares (a) tool names, (b) when to use them, (c) what they return.
+**Mandatory step BEFORE any code-navigation tool call**: scan the project's `CLAUDE.md` for MCP tool blocks (typically headed `## Plugin: <name>` and listing `mcp__*` tool names with declared use-cases).
 
-Before defaulting to built-in tools (`Read`, `Grep`, `Bash`, `WebFetch`, etc.), scan that documentation. When a project-documented MCP tool's declared use-case matches your current need, prefer it over the built-in equivalent — the plugin author chose it for a measurable advantage (lower token cost, higher precision, fresher data, semantic awareness, etc.).
+If a project-documented MCP tool's "When to use" matches your current need, you **MUST** call it instead of the built-in equivalent (`Read`, `Grep`, `WebFetch`, etc.). Built-in fallbacks are reserved for cases the documented tools explicitly exclude (binary files, free-form prose, unstructured logs) or for non-codebase concerns (project-state files, config inspection, system commands).
 
-Fall back to built-ins when no plugin tool fits, or when the documented tool fails to execute in the current environment.
+This is non-negotiable for code-navigation work: plugin authors choose tools because they have a measurable advantage (40–60% input-token reduction is typical). Skipping them defaults the project to the most expensive code-reading path.
+
+**Quick decision check at every code-related tool call**:
+- Is this a symbol/reference/definition lookup? → MCP tool, not `Grep`/`Read`.
+- Am I about to read a file just to edit one function? → MCP tool, not `Read` + `Edit`.
+- No documented MCP tool fits the current need? → built-in, document why in your reasoning.

package/templates/agents/sr-merge-resolver.md

@@ -181,10 +181,15 @@ MERGE_RESOLUTION_STATUS: UNRESOLVED
 - **Always** write the report even if all statuses are LOW_CONFIDENCE.
 - If a file has 0 conflict markers: log it as `NO_CONFLICTS` and skip (do not rewrite the file).
 
-## Tool Selection — Honor Project-Documented MCP Tools
+## Tool Selection — MCP-First for Codebase Tasks
 
-The project's `CLAUDE.md` may list MCP tools made available via plugin systems (e.g., specrails-hub Integrations). Each entry typically declares (a) tool names, (b) when to use them, (c) what they return.
+**Mandatory step BEFORE any code-navigation tool call**: scan the project's `CLAUDE.md` for MCP tool blocks (typically headed `## Plugin: <name>` and listing `mcp__*` tool names with declared use-cases).
 
-Before defaulting to built-in tools (`Read`, `Grep`, `Bash`, `WebFetch`, etc.), scan that documentation. When a project-documented MCP tool's declared use-case matches your current need, prefer it over the built-in equivalent — the plugin author chose it for a measurable advantage (lower token cost, higher precision, fresher data, semantic awareness, etc.).
+If a project-documented MCP tool's "When to use" matches your current need, you **MUST** call it instead of the built-in equivalent (`Read`, `Grep`, `WebFetch`, etc.). Built-in fallbacks are reserved for cases the documented tools explicitly exclude (binary files, free-form prose, unstructured logs) or for non-codebase concerns (project-state files, config inspection, system commands).
 
-Fall back to built-ins when no plugin tool fits, or when the documented tool fails to execute in the current environment.
+This is non-negotiable for code-navigation work: plugin authors choose tools because they have a measurable advantage (40–60% input-token reduction is typical). Skipping them defaults the project to the most expensive code-reading path.
+
+**Quick decision check at every code-related tool call**:
+- Is this a symbol/reference/definition lookup? → MCP tool, not `Grep`/`Read`.
+- Am I about to read a file just to edit one function? → MCP tool, not `Read` + `Edit`.
+- No documented MCP tool fits the current need? → built-in, document why in your reasoning.

package/templates/agents/sr-performance-reviewer.md

@@ -172,10 +172,15 @@ PERF_STATUS: NO_PERF_IMPACT
 - **Never skip performance-sensitive files** — if in doubt, benchmark it
 - **Always update history** after a successful benchmark run
 
-## Tool Selection — Honor Project-Documented MCP Tools
+## Tool Selection — MCP-First for Codebase Tasks
 
-The project's `CLAUDE.md` may list MCP tools made available via plugin systems (e.g., specrails-hub Integrations). Each entry typically declares (a) tool names, (b) when to use them, (c) what they return.
+**Mandatory step BEFORE any code-navigation tool call**: scan the project's `CLAUDE.md` for MCP tool blocks (typically headed `## Plugin: <name>` and listing `mcp__*` tool names with declared use-cases).
 
-Before defaulting to built-in tools (`Read`, `Grep`, `Bash`, `WebFetch`, etc.), scan that documentation. When a project-documented MCP tool's declared use-case matches your current need, prefer it over the built-in equivalent — the plugin author chose it for a measurable advantage (lower token cost, higher precision, fresher data, semantic awareness, etc.).
+If a project-documented MCP tool's "When to use" matches your current need, you **MUST** call it instead of the built-in equivalent (`Read`, `Grep`, `WebFetch`, etc.). Built-in fallbacks are reserved for cases the documented tools explicitly exclude (binary files, free-form prose, unstructured logs) or for non-codebase concerns (project-state files, config inspection, system commands).
 
-Fall back to built-ins when no plugin tool fits, or when the documented tool fails to execute in the current environment.
+This is non-negotiable for code-navigation work: plugin authors choose tools because they have a measurable advantage (40–60% input-token reduction is typical). Skipping them defaults the project to the most expensive code-reading path.
+
+**Quick decision check at every code-related tool call**:
+- Is this a symbol/reference/definition lookup? → MCP tool, not `Grep`/`Read`.
+- Am I about to read a file just to edit one function? → MCP tool, not `Read` + `Edit`.
+- No documented MCP tool fits the current need? → built-in, document why in your reasoning.

package/templates/agents/sr-reviewer.md

@@ -304,10 +304,15 @@ What to save:
 
 Your MEMORY.md is currently empty.
 
-## Tool Selection — Honor Project-Documented MCP Tools
+## Tool Selection — MCP-First for Codebase Tasks
 
-The project's `CLAUDE.md` may list MCP tools made available via plugin systems (e.g., specrails-hub Integrations). Each entry typically declares (a) tool names, (b) when to use them, (c) what they return.
+**Mandatory step BEFORE any code-navigation tool call**: scan the project's `CLAUDE.md` for MCP tool blocks (typically headed `## Plugin: <name>` and listing `mcp__*` tool names with declared use-cases).
 
-Before defaulting to built-in tools (`Read`, `Grep`, `Bash`, `WebFetch`, etc.), scan that documentation. When a project-documented MCP tool's declared use-case matches your current need, prefer it over the built-in equivalent — the plugin author chose it for a measurable advantage (lower token cost, higher precision, fresher data, semantic awareness, etc.).
+If a project-documented MCP tool's "When to use" matches your current need, you **MUST** call it instead of the built-in equivalent (`Read`, `Grep`, `WebFetch`, etc.). Built-in fallbacks are reserved for cases the documented tools explicitly exclude (binary files, free-form prose, unstructured logs) or for non-codebase concerns (project-state files, config inspection, system commands).
 
-Fall back to built-ins when no plugin tool fits, or when the documented tool fails to execute in the current environment.
+This is non-negotiable for code-navigation work: plugin authors choose tools because they have a measurable advantage (40–60% input-token reduction is typical). Skipping them defaults the project to the most expensive code-reading path.
+
+**Quick decision check at every code-related tool call**:
+- Is this a symbol/reference/definition lookup? → MCP tool, not `Grep`/`Read`.
+- Am I about to read a file just to edit one function? → MCP tool, not `Read` + `Edit`.
+- No documented MCP tool fits the current need? → built-in, document why in your reasoning.

package/templates/agents/sr-security-reviewer.md

@@ -177,10 +177,15 @@ What to save:
 
 Your MEMORY.md is currently empty.
 
-## Tool Selection — Honor Project-Documented MCP Tools
+## Tool Selection — MCP-First for Codebase Tasks
 
-The project's `CLAUDE.md` may list MCP tools made available via plugin systems (e.g., specrails-hub Integrations). Each entry typically declares (a) tool names, (b) when to use them, (c) what they return.
+**Mandatory step BEFORE any code-navigation tool call**: scan the project's `CLAUDE.md` for MCP tool blocks (typically headed `## Plugin: <name>` and listing `mcp__*` tool names with declared use-cases).
 
-Before defaulting to built-in tools (`Read`, `Grep`, `Bash`, `WebFetch`, etc.), scan that documentation. When a project-documented MCP tool's declared use-case matches your current need, prefer it over the built-in equivalent — the plugin author chose it for a measurable advantage (lower token cost, higher precision, fresher data, semantic awareness, etc.).
+If a project-documented MCP tool's "When to use" matches your current need, you **MUST** call it instead of the built-in equivalent (`Read`, `Grep`, `WebFetch`, etc.). Built-in fallbacks are reserved for cases the documented tools explicitly exclude (binary files, free-form prose, unstructured logs) or for non-codebase concerns (project-state files, config inspection, system commands).
 
-Fall back to built-ins when no plugin tool fits, or when the documented tool fails to execute in the current environment.
+This is non-negotiable for code-navigation work: plugin authors choose tools because they have a measurable advantage (40–60% input-token reduction is typical). Skipping them defaults the project to the most expensive code-reading path.
+
+**Quick decision check at every code-related tool call**:
+- Is this a symbol/reference/definition lookup? → MCP tool, not `Grep`/`Read`.
+- Am I about to read a file just to edit one function? → MCP tool, not `Read` + `Edit`.
+- No documented MCP tool fits the current need? → built-in, document why in your reasoning.

package/templates/agents/sr-test-writer.md

@@ -162,10 +162,15 @@ What to save:
 
 Your MEMORY.md is currently empty.
 
-## Tool Selection — Honor Project-Documented MCP Tools
+## Tool Selection — MCP-First for Codebase Tasks
 
-The project's `CLAUDE.md` may list MCP tools made available via plugin systems (e.g., specrails-hub Integrations). Each entry typically declares (a) tool names, (b) when to use them, (c) what they return.
+**Mandatory step BEFORE any code-navigation tool call**: scan the project's `CLAUDE.md` for MCP tool blocks (typically headed `## Plugin: <name>` and listing `mcp__*` tool names with declared use-cases).
 
-Before defaulting to built-in tools (`Read`, `Grep`, `Bash`, `WebFetch`, etc.), scan that documentation. When a project-documented MCP tool's declared use-case matches your current need, prefer it over the built-in equivalent — the plugin author chose it for a measurable advantage (lower token cost, higher precision, fresher data, semantic awareness, etc.).
+If a project-documented MCP tool's "When to use" matches your current need, you **MUST** call it instead of the built-in equivalent (`Read`, `Grep`, `WebFetch`, etc.). Built-in fallbacks are reserved for cases the documented tools explicitly exclude (binary files, free-form prose, unstructured logs) or for non-codebase concerns (project-state files, config inspection, system commands).
 
-Fall back to built-ins when no plugin tool fits, or when the documented tool fails to execute in the current environment.
+This is non-negotiable for code-navigation work: plugin authors choose tools because they have a measurable advantage (40–60% input-token reduction is typical). Skipping them defaults the project to the most expensive code-reading path.
+
+**Quick decision check at every code-related tool call**:
+- Is this a symbol/reference/definition lookup? → MCP tool, not `Grep`/`Read`.
+- Am I about to read a file just to edit one function? → MCP tool, not `Read` + `Edit`.
+- No documented MCP tool fits the current need? → built-in, document why in your reasoning.