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
503
.claude/plans/AI-COLLABORATION.md
Normal file
503
.claude/plans/AI-COLLABORATION.md
Normal file
@@ -0,0 +1,503 @@
|
||||
# AI Collaboration Guide for ShopDB Team
|
||||
|
||||
Guide for coordinating multiple developers using AI assistants (Claude, ChatGPT, Cursor, etc.) on the same codebase.
|
||||
|
||||
---
|
||||
|
||||
## The Challenge
|
||||
|
||||
**Problem:** Multiple people using AI to work on ShopDB simultaneously.
|
||||
|
||||
**Risks:**
|
||||
- Two AIs editing the same file
|
||||
- Duplicate work (both fixing the same bug)
|
||||
- Context loss (each AI session starts fresh)
|
||||
- No visibility into "what is the AI working on?"
|
||||
- Merge conflicts from parallel AI-generated changes
|
||||
|
||||
---
|
||||
|
||||
## Solution 1: Shared AI Context (Memory Files)
|
||||
|
||||
**What:** Centralized knowledge base that all AIs can read.
|
||||
|
||||
**Implementation:**
|
||||
|
||||
### A) Project Memory (Already Started)
|
||||
Location: `C:\Users\270015376\.claude\projects\C--Users-270015376-Documents-github\memory\`
|
||||
|
||||
**Current files:**
|
||||
- `adr_core_principles.md` - ADR rules
|
||||
- `architecture_plugins.md` - Plugin architecture
|
||||
- `workflow_versions.md` - Version coordination
|
||||
- `workflow_branches.md` - Git workflow
|
||||
|
||||
**Add team memory:**
|
||||
```markdown
|
||||
# memory/active_work.md
|
||||
---
|
||||
name: active-work
|
||||
description: What each team member (or their AI) is currently working on
|
||||
metadata:
|
||||
type: project
|
||||
---
|
||||
|
||||
## Active Work (Updated: 2026-09-09)
|
||||
|
||||
### 270015376 (You)
|
||||
- **Branch:** wj
|
||||
- **Task:** Operator report email alerts with machine relationships
|
||||
- **Status:** Merged to wj, testing
|
||||
- **AI Session:** Claude Code (Sonnet 4.5)
|
||||
- **ETA:** Complete
|
||||
|
||||
### [Coworker Name]
|
||||
- **Branch:** dev/feature-xyz
|
||||
- **Task:** Description
|
||||
- **Status:** In progress
|
||||
- **Files touched:** List key files
|
||||
- **AI tool:** ChatGPT / Cursor / Claude
|
||||
- **ETA:** Date
|
||||
|
||||
### [Another Coworker]
|
||||
- **Branch:** wilm
|
||||
- **Task:** Endpoint log collection
|
||||
- **Status:** Complete, ready to merge
|
||||
- **AI tool:** None (manual)
|
||||
- **ETA:** N/A
|
||||
|
||||
## How to Update
|
||||
|
||||
**Before starting AI-assisted work:**
|
||||
1. Read this file to see what others are working on
|
||||
2. Add your entry with branch, task, files
|
||||
3. Commit: "docs: Update active work tracker"
|
||||
|
||||
**When done:**
|
||||
1. Mark status as "Complete" or remove entry
|
||||
2. Commit update
|
||||
|
||||
**Why:** Prevents two AIs from working on overlapping tasks.
|
||||
```
|
||||
|
||||
### B) AI Session Notes
|
||||
Location: `.claude/sessions/YYYY-MM-DD-session-name.md`
|
||||
|
||||
```markdown
|
||||
# 2026-09-09: Operator Report Email Improvements
|
||||
|
||||
## Goal
|
||||
Add machine relationship to operator report alert emails.
|
||||
|
||||
## Changes Made
|
||||
- Modified `plugins/endpoints/api/routes.py:_send_operator_report_alert`
|
||||
- Added AssetRelationship query
|
||||
- Added FQDN generation via pc_access_domain setting
|
||||
- Simplified email body (Device, Machine#, Reason, Reported, Details, Screenshot)
|
||||
|
||||
## Files Modified
|
||||
- `plugins/endpoints/api/routes.py` (lines 450-520)
|
||||
|
||||
## Testing
|
||||
- [ ] Send test operator report
|
||||
- [ ] Verify email contains machine link
|
||||
- [ ] Check FQDN format
|
||||
|
||||
## AI Used
|
||||
- Claude Code (Sonnet 4.5)
|
||||
- Token usage: ~40K
|
||||
|
||||
## Handoff Notes
|
||||
If someone else picks this up:
|
||||
- Email template is inline in _send_operator_report_alert
|
||||
- Machine relationship uses label LIKE '%machine%'
|
||||
- FQDN comes from Setting key='pc_access_domain'
|
||||
```
|
||||
|
||||
**Benefit:** Next person (or AI) can read this to understand what was done.
|
||||
|
||||
---
|
||||
|
||||
## Solution 2: Real-Time AI Activity Tracking
|
||||
|
||||
**Option A: Git Branch Naming**
|
||||
```
|
||||
Branch format: <user>/<ai-tool>/<feature>
|
||||
|
||||
Examples:
|
||||
- 270015376/claude/operator-email-alerts
|
||||
- jdoe/cursor/machine-dashboard
|
||||
- asmith/manual/fix-typo
|
||||
|
||||
Benefits:
|
||||
- See at a glance who's working on what
|
||||
- Know if AI is involved
|
||||
- Easy to filter: git branch --list "**/claude/*"
|
||||
```
|
||||
|
||||
**Option B: AI Commit Message Prefix**
|
||||
```
|
||||
Format: [AI: tool] Regular commit message
|
||||
|
||||
Examples:
|
||||
- [AI: Claude] Fix operator report email links
|
||||
- [AI: ChatGPT] Add machine relationship query
|
||||
- [Manual] Update README
|
||||
|
||||
Benefits:
|
||||
- Git log shows AI involvement
|
||||
- Audit trail for AI-generated code
|
||||
- Easy to search: git log --grep "AI:"
|
||||
```
|
||||
|
||||
**Option C: Commit Co-Author (Modified)**
|
||||
```
|
||||
Add AI tool as co-author:
|
||||
|
||||
Operator report email improvements
|
||||
|
||||
- Add machine relationship
|
||||
- Fix FQDN generation
|
||||
|
||||
Co-Authored-By: Claude Sonnet 4.5 <claude@anthropic.com>
|
||||
AI-Session-ID: 2ed10748-a558-4df8-bf1a-4b924392ea23
|
||||
```
|
||||
|
||||
**Note:** Your ADR says "no LLM attribution comments" - this is in commit metadata, not code comments.
|
||||
|
||||
---
|
||||
|
||||
## Solution 3: Shared MCP Server for Coordination
|
||||
|
||||
**Idea:** Create a ShopDB-specific MCP server that tracks AI activity.
|
||||
|
||||
**What it would do:**
|
||||
```javascript
|
||||
// MCP server running on shared dev machine or gitea
|
||||
mcpServers: {
|
||||
"shopdb-coordinator": {
|
||||
"command": "node",
|
||||
"args": ["shopdb-mcp-coordinator.js"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Tools it exposes:**
|
||||
- `register_ai_session(user, task, files, branch)`
|
||||
- `list_active_ai_sessions()`
|
||||
- `mark_session_complete(session_id)`
|
||||
- `check_file_locks(file_path)` - warn if another AI is editing
|
||||
|
||||
**Usage:**
|
||||
```
|
||||
You: "Starting work on fleet alerts"
|
||||
Claude: [Calls register_ai_session]
|
||||
Claude: "Registered. No conflicts. Two other active sessions on wilm branch."
|
||||
|
||||
You: "Edit plugins/notifications/models/notification.py"
|
||||
Claude: [Calls check_file_locks]
|
||||
Claude: "Warning: jdoe's AI (Cursor) is also editing this file on dev branch."
|
||||
```
|
||||
|
||||
**Implementation:**
|
||||
```javascript
|
||||
// shopdb-mcp-coordinator.js
|
||||
const express = require('express');
|
||||
const fs = require('fs');
|
||||
|
||||
const sessions = new Map();
|
||||
|
||||
// Register AI session
|
||||
function registerSession(user, task, files, branch) {
|
||||
const id = Date.now().toString();
|
||||
sessions.set(id, {
|
||||
user, task, files, branch,
|
||||
started: new Date(),
|
||||
status: 'active'
|
||||
});
|
||||
|
||||
// Check for conflicts
|
||||
const conflicts = [];
|
||||
for (const [otherId, other] of sessions) {
|
||||
if (other.status === 'active' && otherId !== id) {
|
||||
const overlap = files.filter(f => other.files.includes(f));
|
||||
if (overlap.length > 0) {
|
||||
conflicts.push({user: other.user, files: overlap});
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return {id, conflicts};
|
||||
}
|
||||
|
||||
// MCP tool definitions
|
||||
const tools = [
|
||||
{
|
||||
name: 'register_ai_session',
|
||||
description: 'Register that an AI is starting work',
|
||||
inputSchema: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
user: {type: 'string'},
|
||||
task: {type: 'string'},
|
||||
files: {type: 'array', items: {type: 'string'}},
|
||||
branch: {type: 'string'}
|
||||
}
|
||||
}
|
||||
},
|
||||
// ... more tools
|
||||
];
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
- Real-time conflict detection
|
||||
- Visibility into all AI activity
|
||||
- Automatic "who's working on what"
|
||||
- Can warn before conflicts happen
|
||||
|
||||
---
|
||||
|
||||
## Solution 4: Shared Knowledge Base (Wiki Integration)
|
||||
|
||||
**Current:** ShopDB wiki at `C:\Users\270015376\Documents\github\shopdb-flask.wiki\`
|
||||
|
||||
**Add AI sections:**
|
||||
|
||||
### A) `AI-SESSIONS.md` in Wiki
|
||||
```markdown
|
||||
# Active AI Sessions
|
||||
|
||||
Last updated: 2026-09-09 23:45
|
||||
|
||||
| User | AI Tool | Task | Branch | Files | Started | ETA |
|
||||
|------|---------|------|--------|-------|---------|-----|
|
||||
| 270015376 | Claude Code | Operator emails | wj | routes.py | 2026-09-09 | Done |
|
||||
| jdoe | Cursor | Dashboard | dev | views/machines.vue | 2026-09-09 | In progress |
|
||||
```
|
||||
|
||||
### B) `AI-GENERATED-CODE.md` in Wiki
|
||||
```markdown
|
||||
# AI-Generated Code Registry
|
||||
|
||||
Track significant AI contributions for audit/review.
|
||||
|
||||
## 2026-09-09: Operator Report Email Alerts
|
||||
- **Author:** 270015376
|
||||
- **AI:** Claude Code (Sonnet 4.5)
|
||||
- **Files:** plugins/endpoints/api/routes.py
|
||||
- **Lines:** 450-520
|
||||
- **Reviewed:** Yes (by author)
|
||||
- **Tested:** Yes (pytest passed)
|
||||
- **Notes:** Machine relationship query, FQDN generation
|
||||
|
||||
## 2026-09-08: Fleet Alert Scope Filtering
|
||||
- **Author:** 270015376
|
||||
- **AI:** Claude Code (Sonnet 4.5)
|
||||
- **Files:** plugins/notifications/models/notification.py
|
||||
- **Reviewed:** Yes
|
||||
- **Tested:** Yes
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
- Audit trail for compliance
|
||||
- Easy to review AI contributions
|
||||
- Searchable history
|
||||
|
||||
---
|
||||
|
||||
## Solution 5: Pre-Commit Hook with AI Coordination
|
||||
|
||||
**Add to `scripts/check-naming-and-style.sh`:**
|
||||
|
||||
```bash
|
||||
# Check for active AI sessions on modified files
|
||||
echo "==> Checking for AI session conflicts..."
|
||||
|
||||
MODIFIED_FILES=$(git diff --cached --name-only)
|
||||
|
||||
# Read active work from memory file
|
||||
ACTIVE_WORK="$HOME/.claude/projects/*/memory/active_work.md"
|
||||
|
||||
if [ -f "$ACTIVE_WORK" ]; then
|
||||
for file in $MODIFIED_FILES; do
|
||||
# Check if file is mentioned in active work by someone else
|
||||
CONFLICTS=$(grep -l "$file" "$ACTIVE_WORK" | grep -v "$USER" || true)
|
||||
if [ -n "$CONFLICTS" ]; then
|
||||
echo "WARNING: $file is being worked on by another AI session"
|
||||
echo "Check: $ACTIVE_WORK"
|
||||
read -p "Continue anyway? (y/n) " -n 1 -r
|
||||
echo
|
||||
if [[ ! $REPLY =~ ^[Yy]$ ]]; then
|
||||
exit 1
|
||||
fi
|
||||
fi
|
||||
done
|
||||
fi
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Solution 6: Slack/Teams Integration
|
||||
|
||||
**For real-time coordination:**
|
||||
|
||||
```bash
|
||||
# Post to Slack when AI session starts
|
||||
curl -X POST $SLACK_WEBHOOK_URL -d '{
|
||||
"text": "270015376 AI session started",
|
||||
"attachments": [{
|
||||
"title": "Task: Operator report emails",
|
||||
"fields": [
|
||||
{"title": "AI Tool", "value": "Claude Code", "short": true},
|
||||
{"title": "Branch", "value": "wj", "short": true},
|
||||
{"title": "Files", "value": "routes.py", "short": false}
|
||||
]
|
||||
}]
|
||||
}'
|
||||
|
||||
# Post when done
|
||||
curl -X POST $SLACK_WEBHOOK_URL -d '{
|
||||
"text": "270015376 AI session complete: Operator report emails"
|
||||
}'
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
- Team sees activity in real-time
|
||||
- No need to check git branches
|
||||
- Can ask questions: "Hey, your AI is editing the same file as mine"
|
||||
|
||||
---
|
||||
|
||||
## Recommended Setup for ShopDB Team
|
||||
|
||||
### Phase 1: Minimal (This Week)
|
||||
1. ✅ Create `memory/active_work.md` (5 min)
|
||||
2. ✅ Adopt branch naming: `<user>/<ai-tool>/<feature>` (0 min)
|
||||
3. ✅ Add AI commit prefix: `[AI: tool] message` (0 min)
|
||||
|
||||
### Phase 2: Enhanced (Next Sprint)
|
||||
4. Create `.claude/sessions/` with session notes (15 min)
|
||||
5. Add AI-SESSIONS.md to wiki (10 min)
|
||||
6. Update pre-commit hook to check conflicts (30 min)
|
||||
|
||||
### Phase 3: Advanced (Future)
|
||||
7. Build ShopDB MCP coordinator server (2-4 hours)
|
||||
8. Integrate with Slack/Teams (1 hour)
|
||||
9. Add AI code review checklist (30 min)
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Before Starting AI-Assisted Work:
|
||||
1. Read `memory/active_work.md`
|
||||
2. Check git branches: `git branch --list --all`
|
||||
3. Update active work file with your task
|
||||
4. Use branch naming: `<you>/<ai-tool>/<feature>`
|
||||
|
||||
### During AI Session:
|
||||
1. Commit frequently (AI should commit after each logical change)
|
||||
2. Use descriptive commit messages with [AI: tool] prefix
|
||||
3. Update active work file if scope changes
|
||||
|
||||
### After AI Session:
|
||||
1. Mark work complete in active work file
|
||||
2. Create session notes in `.claude/sessions/`
|
||||
3. Review AI-generated code manually
|
||||
4. Run full test suite: `pytest -v`
|
||||
5. Run pre-commit checks: `scripts/check-naming-and-style.sh`
|
||||
|
||||
### If Conflict Detected:
|
||||
1. Check who else is working on the file
|
||||
2. Coordinate: Slack, email, or in-person
|
||||
3. Decide who continues (usually first-started wins)
|
||||
4. Other person rebases or works on different files
|
||||
|
||||
---
|
||||
|
||||
## Tools Comparison
|
||||
|
||||
| Tool | Setup | Real-Time | Conflict Detection | Cost |
|
||||
|------|-------|-----------|-------------------|------|
|
||||
| Memory files | 5 min | No | Manual | Free |
|
||||
| Branch naming | 0 min | Via `git branch` | Manual | Free |
|
||||
| Commit prefixes | 0 min | Via `git log` | Manual | Free |
|
||||
| Session notes | 15 min | No | Manual | Free |
|
||||
| MCP coordinator | 2-4 hours | Yes | Automatic | Free |
|
||||
| Slack integration | 1 hour | Yes | Manual | Free |
|
||||
|
||||
**Recommendation:** Start with free/fast options (Phase 1), evaluate, then add automation if needed.
|
||||
|
||||
---
|
||||
|
||||
## Example Workflow
|
||||
|
||||
**User starts work:**
|
||||
```
|
||||
You: "I want to work on adding machine relationships to operator reports"
|
||||
|
||||
Claude: [Reads memory/active_work.md]
|
||||
Claude: "Checking active work... No conflicts. Creating branch."
|
||||
|
||||
Claude: [Runs] git checkout -b 270015376/claude/operator-report-machines
|
||||
|
||||
Claude: [Updates memory/active_work.md]
|
||||
Claude: "Registered session. You're clear to work."
|
||||
```
|
||||
|
||||
**User commits:**
|
||||
```
|
||||
Claude: [Makes changes to routes.py]
|
||||
Claude: [Runs] git add plugins/endpoints/api/routes.py
|
||||
Claude: [Runs] git commit -m "[AI: Claude] Add machine relationship to operator report alerts"
|
||||
```
|
||||
|
||||
**User finishes:**
|
||||
```
|
||||
You: "Done, create PR"
|
||||
|
||||
Claude: [Updates memory/active_work.md to mark complete]
|
||||
Claude: [Creates .claude/sessions/2026-09-09-operator-reports.md]
|
||||
Claude: [Runs] gh pr create --title "..." --body "..."
|
||||
Claude: "PR created. Session notes saved. Active work updated."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Security Note
|
||||
|
||||
**If using shared MCP coordinator:**
|
||||
- Run on trusted internal server (not public)
|
||||
- Use token auth (don't allow anonymous registration)
|
||||
- Log all activity for audit
|
||||
- Don't expose sensitive file contents, just paths
|
||||
|
||||
**If using Slack webhooks:**
|
||||
- Don't post code snippets (may contain secrets)
|
||||
- Post only: user, task, files, branch
|
||||
- Use private channel (not public)
|
||||
|
||||
---
|
||||
|
||||
## Questions to Decide
|
||||
|
||||
1. **How many devs use AI?** (Determines if automation is worth it)
|
||||
2. **What AI tools?** (Claude, ChatGPT, Cursor, Copilot, etc.)
|
||||
3. **Coordination preference?** (Manual check vs automatic warnings)
|
||||
4. **Real-time needs?** (Slack notifications vs git log)
|
||||
5. **Audit requirements?** (Do you need to track AI contributions?)
|
||||
|
||||
---
|
||||
|
||||
## Try It: Minimal Setup (5 Minutes)
|
||||
|
||||
Want to try the simplest version? I can:
|
||||
|
||||
1. Create `memory/active_work.md` with your current session
|
||||
2. Set up branch naming convention in CLAUDE.md
|
||||
3. Add commit message format to CLAUDE.md
|
||||
4. Create example session notes template
|
||||
|
||||
This gives immediate value with zero automation complexity.
|
||||
|
||||
Want me to set this up now?
|
||||
11
.claude/plans/README.md
Normal file
11
.claude/plans/README.md
Normal file
@@ -0,0 +1,11 @@
|
||||
# Feature Plans and Protocols
|
||||
|
||||
Design documents and operational protocols for major features.
|
||||
|
||||
## Feature Plans
|
||||
- `SAML-FEATURE-PLAN.md` - M365 SAML/SSO implementation plan
|
||||
- `security-improvements.md` - Security audit remediation plan
|
||||
|
||||
## Operational Protocols
|
||||
- `TOOL-ENGAGEMENT-PROTOCOL.md` - Claude Code MCP tool usage directive
|
||||
- `AI-COLLABORATION.md` - Guidelines for AI-assisted development
|
||||
1456
.claude/plans/SAML-FEATURE-PLAN.md
Normal file
1456
.claude/plans/SAML-FEATURE-PLAN.md
Normal file
File diff suppressed because it is too large
Load Diff
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
|
||||
194
.claude/plans/security-improvements.md
Normal file
194
.claude/plans/security-improvements.md
Normal file
@@ -0,0 +1,194 @@
|
||||
# ShopDB Security Improvements
|
||||
|
||||
## Priority 1: Enable GitHub Secret Scanning
|
||||
|
||||
**Status:** Currently disabled
|
||||
|
||||
**How to enable:**
|
||||
1. Go to: https://github.com/ge-aero/shopdb-flask/settings/security_analysis
|
||||
2. Enable "Secret scanning"
|
||||
3. Enable "Push protection" (blocks pushes with secrets)
|
||||
|
||||
**What it catches:**
|
||||
- GitHub tokens (ghp_, gho_, etc.)
|
||||
- AWS keys
|
||||
- API keys from 200+ services
|
||||
- Private keys
|
||||
|
||||
**Why:** Would have caught the token pasted in Claude conversation.
|
||||
|
||||
---
|
||||
|
||||
## Priority 2: Install Pre-Commit Hook
|
||||
|
||||
**Current state:** `scripts/check-naming-and-style.sh` exists but not installed as git hook.
|
||||
|
||||
**Install:**
|
||||
```bash
|
||||
cd C:\Users\270015376\Documents\github\flask-shopdb
|
||||
ln -s ../../scripts/check-naming-and-style.sh .git/hooks/pre-commit
|
||||
chmod +x .git/hooks/pre-commit
|
||||
```
|
||||
|
||||
**Or use pre-commit framework:**
|
||||
```bash
|
||||
pip install pre-commit
|
||||
```
|
||||
|
||||
Create `.pre-commit-config.yaml`:
|
||||
```yaml
|
||||
repos:
|
||||
- repo: local
|
||||
hooks:
|
||||
- id: naming-and-style
|
||||
name: Check naming and style
|
||||
entry: scripts/check-naming-and-style.sh
|
||||
language: system
|
||||
pass_filenames: false
|
||||
|
||||
- id: gitleaks
|
||||
name: Detect secrets
|
||||
entry: gitleaks
|
||||
args: ['protect', '--verbose', '--redact', '--staged']
|
||||
language: system
|
||||
pass_filenames: false
|
||||
```
|
||||
|
||||
**Install:** `pre-commit install`
|
||||
|
||||
---
|
||||
|
||||
## Priority 3: Add gitleaks for Secret Detection
|
||||
|
||||
**Install:**
|
||||
```bash
|
||||
winget install gitleaks
|
||||
```
|
||||
|
||||
**Configure:** `.gitleaks.toml`
|
||||
```toml
|
||||
title = "ShopDB gitleaks config"
|
||||
|
||||
[allowlist]
|
||||
description = "Known safe patterns"
|
||||
paths = [
|
||||
# Example tokens in docs
|
||||
'''docs/.*\.md''',
|
||||
'''README\.md''',
|
||||
]
|
||||
|
||||
# Custom rules for ShopDB
|
||||
[[rules]]
|
||||
id = "shopdb-collector-token"
|
||||
description = "ShopDB collector token"
|
||||
regex = '''[0-9a-f]{64}'''
|
||||
path = '''plugins/endpoints/'''
|
||||
|
||||
[[rules]]
|
||||
id = "github-token"
|
||||
description = "GitHub Personal Access Token"
|
||||
regex = '''ghp_[0-9a-zA-Z]{36}'''
|
||||
|
||||
[[rules]]
|
||||
id = "mysql-connection"
|
||||
description = "MySQL connection string with password"
|
||||
regex = '''mysql://[^:]+:([^@\s]+)@'''
|
||||
```
|
||||
|
||||
**Run manually:** `gitleaks detect --verbose`
|
||||
**Run on commit:** (via pre-commit hook above)
|
||||
|
||||
---
|
||||
|
||||
## Priority 4: Rotate Exposed Token
|
||||
|
||||
**Action:** The token `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` was exposed in Claude conversation.
|
||||
|
||||
**Steps:**
|
||||
1. Revoke: https://github.com/settings/tokens
|
||||
2. Generate new token with same scopes (repo, workflow, read:org)
|
||||
3. Update environment variable: `setx GITHUB_PERSONAL_ACCESS_TOKEN "NEW_TOKEN"`
|
||||
4. Restart Claude Code
|
||||
|
||||
---
|
||||
|
||||
## Priority 5: Add Security Policy
|
||||
|
||||
Create `SECURITY.md`:
|
||||
```markdown
|
||||
# Security Policy
|
||||
|
||||
## Reporting a Vulnerability
|
||||
|
||||
Contact: [internal security team email]
|
||||
|
||||
## What NOT to commit:
|
||||
|
||||
- `.env` files with real credentials
|
||||
- Database dumps with real data
|
||||
- API tokens, GitHub tokens, SSH keys
|
||||
- Collector tokens (generate per-site)
|
||||
- Site-specific hostnames, IPs (use settings)
|
||||
|
||||
## Pre-commit checklist:
|
||||
|
||||
1. Run `scripts/check-naming-and-style.sh`
|
||||
2. Run `gitleaks detect`
|
||||
3. Check no secrets in diff: `git diff --cached`
|
||||
4. Verify .gitignore caught sensitive files
|
||||
|
||||
## GitHub scanning:
|
||||
|
||||
- Secret scanning: Enabled (blocks pushes with secrets)
|
||||
- Darkwing: Runs on all PRs
|
||||
- Dependency scanning: Enabled (Dependabot alerts)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## What's Already Good:
|
||||
|
||||
✅ Strong .gitignore (lines 64-86 cover most credential patterns)
|
||||
✅ Darkwing scanning on PRs
|
||||
✅ Air-gapped deployment (secrets never in GitHub)
|
||||
✅ ADR-016: Device tokens instead of user credentials for kiosks
|
||||
✅ Collector tokens are 64-char hashes, not readable passwords
|
||||
|
||||
---
|
||||
|
||||
## Implementation Order:
|
||||
|
||||
1. **Today:** Enable GitHub secret scanning + push protection (5 min)
|
||||
2. **Today:** Rotate the exposed GitHub token (3 min)
|
||||
3. **This week:** Install gitleaks and pre-commit hook (30 min)
|
||||
4. **This week:** Add SECURITY.md (15 min)
|
||||
5. **Next sprint:** Train team on new workflow
|
||||
|
||||
---
|
||||
|
||||
## Testing the Setup:
|
||||
|
||||
```bash
|
||||
# Test 1: Try to commit a fake token
|
||||
echo "ghp_FAKE1234567890123456789012345678" > test-secret.txt
|
||||
git add test-secret.txt
|
||||
git commit -m "test"
|
||||
# Expected: Pre-commit hook blocks it
|
||||
|
||||
# Test 2: Try to push a secret (if pre-commit bypassed)
|
||||
git push
|
||||
# Expected: GitHub push protection blocks it
|
||||
|
||||
# Test 3: Scan existing history
|
||||
gitleaks detect --verbose
|
||||
# Expected: No secrets found (or only known safe ones)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Monitoring:
|
||||
|
||||
- GitHub Security tab: https://github.com/ge-aero/shopdb-flask/security
|
||||
- Secret scanning alerts: (once enabled)
|
||||
- Darkwing findings: Security → Code scanning
|
||||
- Dependabot alerts: Security → Dependabot
|
||||
Reference in New Issue
Block a user