shopdb-flask/.claude/plans/TOOL-ENGAGEMENT-PROTOCOL.md

Tool Engagement Protocol

Purpose: Force Claude Code to actually USE the MCP tools, skills, and workflows that have been configured.

Critical Rule

BEFORE starting ANY task, check this file and follow the protocol for that task type.

---

Protocol by Task Type

1. File Editing (ANY file in repo)

REQUIRED BEFORE EDITING:

// Step 1: Announce work to coordinator
mcp__coordinator__announce_work({
  agent_id: "flask-shopdb-wj-claude-sonnet",
  subject: "<brief description of what you're doing>",
  target_modules: ["<module-name>"],  // e.g., "backend", "frontend", "plugins"
  target_files: ["<relative-file-path>"],  // e.g., "shopdb/core/api/settings.py"
  plan: "<detailed plan with file names and line numbers>"
})

// Step 2: Check for conflicts
// If conflicts returned, coordinate with other agents FIRST

// Step 3: Only then proceed with Edit/Write

NO EXCEPTIONS. Even for "quick fixes" or "one-line changes".

---

2. Code Analysis / Architecture Questions

REQUIRED BEFORE GREP:

// Step 1: Load Gortex tools
ToolSearch({query: "select:mcp__gortex__explore,mcp__gortex__read,mcp__gortex__relations,mcp__gortex__change"})

// Step 2: Use Gortex for analysis
// INSTEAD OF: grep "from plugins" 
// USE: mcp__gortex__relations({operation: "dependencies", target: {file: "..."}})

// INSTEAD OF: Read + manual analysis
// USE: mcp__gortex__explore({operation: "task", task: "Find all circular dependencies"})

// INSTEAD OF: Multiple Read calls to understand blast radius
// USE: mcp__gortex__change({operation: "impact", target: {file: "..."}})

When to skip: Simple file existence checks (ls, cat). But if you're analyzing STRUCTURE or RELATIONSHIPS, use Gortex.

---

3. Data Visualization / Charts

REQUIRED BEFORE CREATING ANY CHART:

// Step 1: Invoke dataviz skill
Skill({skill: "dataviz"})

// Step 2: Follow the guidance it provides for:
// - Chart type selection
// - Color palette
// - Accessibility
// - Data format

Applies to: HTML artifacts, React components, matplotlib, plotly, d3, Recharts, inline SVG, any visualization.

---

4. Security/Performance Review

REQUIRED FOR:

• Reviewing endpoint plugin, C# agent, or tray application code
• Performance analysis of database queries
• Security audit requests

// Step 1: Invoke security audit skill
Skill({skill: "endpoint-agent-security-audit"})

Applies to: Any request containing words "security", "audit", "performance", "vulnerability", "optimize".

---

5. Code Review

REQUIRED FOR:

• Reviewing diffs before commit
• Reviewing PR changes
• Checking for bugs or simplifications

// Step 1: Invoke code-review skill
Skill({skill: "code-review", args: "--level=medium"})
// Or for quick reviews: --level=low
// For thorough reviews: --level=high

Applies to: Any request containing "review", "check", "validate", "verify changes".

---

6. Multi-Step Complex Tasks

REQUIRED FOR:

• Tasks requiring 5+ agents
• Parallel analysis (multiple dimensions)
• Exhaustive searches (find ALL bugs, review ALL files)
• Tasks where user says "be thorough" or "comprehensive"

// Step 1: Propose workflow
// "This task would benefit from a workflow with N agents analyzing in parallel.
//  Estimated: X agents, Y minutes, ~Z tokens.
//  Would you like me to create a workflow for this?"

// Step 2: If user approves, use Workflow tool
Workflow({
  description: "...",
  script: `
    export const meta = {...}
    // ... workflow code
  `
})

Applies to: Any request that would require >30 minutes of manual analysis or >10 sequential tool calls.

---

Enforcement

If You (Claude) Forget

User will say: "PROTOCOL"

You must:

1. Stop what you're doing
2. Check which protocol applies
3. Restart the task correctly using the required tools

If User Wants to Skip Protocol

User will say: "SKIP PROTOCOL"

Then proceed without the required tools (but note that you're skipping for this specific task).

---

Why Each Tool Matters

Coordinator MCP

• Prevents: File collision when multiple agents edit same code
• Enables: Parallel work without conflicts
• Cost: 2 seconds per announce_work call
• Benefit: Avoid hours of merge conflict resolution

Gortex MCP

• Prevents: Missed dependencies, incomplete analysis, false conclusions
• Enables: Structural queries (find ALL callers, show FULL blast radius)
• Cost: 5-10 seconds per query
• Benefit: Correctness - Gortex parses AST, grep just matches text

Dataviz Skill

• Prevents: Inaccessible charts, inconsistent styling, poor color choices
• Enables: Professional, accessible, brand-consistent visualizations
• Cost: 30 seconds to load skill guidance
• Benefit: Charts that actually communicate data effectively

Security Audit Skill

• Prevents: Shipping vulnerabilities, missing performance optimizations
• Enables: Multi-lens review (security, performance, correctness)
• Cost: 10-20 minutes for full audit workflow
• Benefit: Production-ready code with security/performance validated

Workflow Tool

• Prevents: Incomplete analysis, sequential bottlenecks, missed edge cases
• Enables: Parallel agent orchestration, exhaustive coverage, adversarial verification
• Cost: 5-20 minutes depending on workflow size
• Benefit: Thoroughness - don't miss the critical bug or risk

---

Quick Reference

Task	Required Tool	When to Skip
Edit any file	coordinator.announce_work	Never
Find dependencies	gortex.relations	Simple ls or existence check
Understand coupling	gortex.explore	Just reading one file for context
Blast radius analysis	gortex.change	Trivial changes (typo fix)
Create chart/graph	dataviz skill	Never
Security/perf review	endpoint-agent-security-audit skill	Not security-related
Review diff/PR	code-review skill	Trivial changes
Complex multi-step	Workflow tool	Task <5 agents or <10 tool calls

---

Success Metrics

Good Engagement

• ✅ Coordinator used before every file edit
• ✅ Gortex used for architectural queries
• ✅ Skills invoked when task matches their domain
• ✅ Workflows proposed for complex tasks

Poor Engagement

• ❌ Editing files without announce_work
• ❌ Using grep when Gortex would be more accurate
• ❌ Creating charts without dataviz skill guidance
• ❌ Manual sequential analysis when workflow would parallelize

---

User Configuration

To enforce this protocol strictly:

Add to your Claude Code messages:

"Follow TOOL-ENGAGEMENT-PROTOCOL.md strictly. If you skip required tools, I'll say PROTOCOL and you restart correctly."

To relax enforcement:

Add to your messages:

"Use TOOL-ENGAGEMENT-PROTOCOL.md as guidance, not hard requirement. Use tools when they add clear value."

---

Version History

• 2026-09-11: Initial protocol created after maintenance footprint analysis revealed pattern of tool underutilization
• Issue: Gortex MCP configured but unused, coordinator MCP configured but not called proactively, skills created but not invoked
• Goal: Force actual engagement with infrastructure, not just acknowledgment of its existence