shopdb-flask/.claude/plans/AI-COLLABORATION.md

# 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. [X] Create `memory/active_work.md` (5 min)
2. [X] Adopt branch naming: `<user>/<ai-tool>/<feature>` (0 min)
3. [X] 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?