Claude Code ignores DeepWiki-first directives for OpenSpec research

[WesleyMFrederick]

Problem

Claude Code has three separate directives requiring DeepWiki-first for OpenSpec research (CLAUDE.md, MEMORY.md, user prompt). In this session, all three were ignored — Claude spawned an Explore agent instead of calling DeepWiki MCP tools.

Root Cause

Claude's tool selection pattern-matches "research task" → Explore agent as a strong default. Domain-specific overrides ("OpenSpec research → DeepWiki") fire at a lower priority than this default, so the directives are read but not acted on. Adding more text directives won't fix this — three already exist and failed.

Additionally, DeepWiki MCP tools (mcp__deepwiki__ask_question, etc.) are not available in all agent types. The main orchestrator session may lack them, requiring delegation to an agent type that has DeepWiki (e.g., application-tech-lead). This tooling gap makes the "just call DeepWiki directly" directive impossible to follow in some contexts.

Current State

Three directives exist:

1. CLAUDE.md: "ALWAYS use DeepWiki FIRST... Do NOT use Explore agents, Grep, or other tools for initial OpenSpec research"
2. MEMORY.md: "HARD RULE: Never use Explore agent or Grep-first for OpenSpec research. DeepWiki first, always. No exceptions."
3. User prompt (ad hoc): "use deepwiki research"

All three were ignored in the same session.

Solution

Text directives alone are insufficient. A structural enforcement mechanism is needed.

Option A: Pre-tool hook — Intercept Agent tool calls where the prompt contains "OpenSpec" and the subagent_type is Explore. Block with message: "Use DeepWiki MCP for OpenSpec research. Route via application-tech-lead agent if DeepWiki MCP is not in your direct tool set."

Option B: Skill-based routing — Create an openspec-research skill that is triggered by any OpenSpec research need. The skill explicitly spawns an application-tech-lead agent with DeepWiki tools, avoiding the Explore agent default entirely.

Option C: MCP availability fix — Ensure DeepWiki MCP tools are available in the main session's tool set (not just in specific agent types), so the directive "call DeepWiki directly" is always possible.

Files

• .claude/settings.json — if Option A (add pre-tool hook)
• .claude/skills/openspec-research/SKILL.md — if Option B (new skill)
• .mcp.json — if Option C (MCP server availability)

Constraints

• Fix must be structural (mechanical enforcement), not another text directive
• Must work in worktree sessions where MCP availability may vary
• Must not break non-OpenSpec research workflows (Explore agent is correct for other domains)

Success Criteria

• When Claude needs to research an OpenSpec question, DeepWiki is used before any other tool
• If DeepWiki MCP is unavailable in the current tool set, Claude routes through an agent type that has it (not Explore)
• The enforcement mechanism blocks the incorrect path, not just advises against it
• Non-OpenSpec research is unaffected