specrails-core 4.3.0 → 4.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specrails-core",
-  "version": "4.3.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

@@ -217,3 +217,16 @@ Guidelines:
 ## MEMORY.md
 
 Your MEMORY.md is currently empty. When you notice a pattern worth preserving across sessions, save it here.
+
+## Tool Selection — MCP-First for Codebase Tasks
+
+**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).
+
+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).
+
+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

@@ -52,3 +52,16 @@ Guidelines:
 ## MEMORY.md
 
 Your MEMORY.md is currently empty.
+
+## Tool Selection — MCP-First for Codebase Tasks
+
+**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).
+
+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).
+
+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

@@ -137,3 +137,16 @@ What to save:
 ## MEMORY.md
 
 Your MEMORY.md is currently empty.
+
+## Tool Selection — MCP-First for Codebase Tasks
+
+**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).
+
+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).
+
+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,11 +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 — MCP-First for Codebase Tasks
+
+**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).
+
+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).
+
+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

@@ -232,3 +232,16 @@ What to save:
 ## MEMORY.md
 
 Your MEMORY.md is currently empty.
+
+## Tool Selection — MCP-First for Codebase Tasks
+
+**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).
+
+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).
+
+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

@@ -46,3 +46,16 @@ Guidelines:
 ## MEMORY.md
 
 Your MEMORY.md is currently empty.
+
+## Tool Selection — MCP-First for Codebase Tasks
+
+**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).
+
+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).
+
+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

@@ -130,3 +130,16 @@ What to save:
 ## MEMORY.md
 
 Your MEMORY.md is currently empty.
+
+## Tool Selection — MCP-First for Codebase Tasks
+
+**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).
+
+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).
+
+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

@@ -180,3 +180,16 @@ MERGE_RESOLUTION_STATUS: UNRESOLVED
 - **Never** run tests, git commands, or make commits.
 - **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 — MCP-First for Codebase Tasks
+
+**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).
+
+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).
+
+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

@@ -171,3 +171,16 @@ PERF_STATUS: NO_PERF_IMPACT
 - **Never ask for clarification** — use defaults when config is missing
 - **Never skip performance-sensitive files** — if in doubt, benchmark it
 - **Always update history** after a successful benchmark run
+
+## Tool Selection — MCP-First for Codebase Tasks
+
+**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).
+
+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).
+
+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

@@ -303,3 +303,16 @@ What to save:
 ## MEMORY.md
 
 Your MEMORY.md is currently empty.
+
+## Tool Selection — MCP-First for Codebase Tasks
+
+**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).
+
+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).
+
+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

@@ -176,3 +176,16 @@ What to save:
 ## MEMORY.md
 
 Your MEMORY.md is currently empty.
+
+## Tool Selection — MCP-First for Codebase Tasks
+
+**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).
+
+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).
+
+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

@@ -161,3 +161,16 @@ What to save:
 ## MEMORY.md
 
 Your MEMORY.md is currently empty.
+
+## Tool Selection — MCP-First for Codebase Tasks
+
+**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).
+
+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).
+
+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.