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:**

```javascript
// 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:**

```javascript
// 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:**

```javascript
// 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

```javascript
// 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

```javascript
// 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"

```javascript
// 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