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:

# 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

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

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

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

# 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

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

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

# 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?