Reorganize repository structure and clean up documentation
Clean up and organize the flask-shopdb repository for better maintainability and discoverability: ## Changes - Update .gitignore for build artifacts (publish/, data/, 122M total) - Reorganize .claude/ into 6 subdirectories with README navigation - Consolidate overlapping MCP setup guides into MCP-QUICK-START.md - Move deployment docs from root to docs/deployment/ - Archive dated status reports to .claude/archived/ - Delete temporary files (logs, backups, empty reports, ~50K) ## New Structure .claude/ organized into: - setup/ - MCP, VM, Hyper-V, GitHub setup guides + scripts (17 files) - plans/ - Feature plans and protocols (5 files) - maintenance/ - Deployment checklists and reports (4 files) - archived/ - Historical documentation (9 files) - skills/ - Claude Code automation (5 files) - workflows/ - Security audit workflow (1 file) docs/deployment/ created with 6 deployment guides: - LOCAL-DEV-SETUP.md, DOCKER-SETUP.md, DOCKER-PREBUILT-APPROACH.md - PRODUCTION-READINESS.md, DEPLOY-TO-VM.md, README.md Root directory cleaned to essential docs only: - CLAUDE.md, README.md, CONTRIBUTING.md, CHANGELOG.md Benefits: - Clear navigation via README.md in each subdirectory - No duplicate/overlapping documentation - Large artifacts properly gitignored (won't bloat repository) - Historical context preserved in archived/ See .claude/CLEANUP-SUMMARY.md for complete details. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Proudlock
242
.claude/plans/TOOL-ENGAGEMENT-PROTOCOL.md
Normal file
242
.claude/plans/TOOL-ENGAGEMENT-PROTOCOL.md
Normal file
@@ -0,0 +1,242 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user