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?
|
||||
Reference in New Issue
Block a user