s9n-devops-agent 1.2.1 → 1.3.1

package/README.md

@@ -1,10 +1,26 @@
-# CS_DevOpsAgent 🚀
+# CS_DevOpsAgent 🚀 v1.3.1
 
 [![npm version](https://badge.fury.io/js/s9n-devops-agent.svg)](https://badge.fury.io/js/s9n-devops-agent)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![GitHub](https://img.shields.io/badge/GitHub-Repository-blue)](https://github.com/SecondBrainAICo/CS_DevOpsAgent)
 
-An intelligent Git automation system with multi-agent support, session management, and seamless integration with AI coding assistants like Claude, GitHub Copilot, and Cursor.
+An intelligent Git automation system with multi-agent support, real-time file coordination, session management, and seamless integration with AI coding assistants like Claude, GitHub Copilot, and Cursor.
+
+## 🆕 What's New in v1.3.1
+
+### Latest Updates (v1.3.1)
+- **🔒 Enhanced File Locking**: Improved coordination scripts with proper empty directory handling
+- **🧪 File Locking Demo**: New comprehensive test showing how multi-agent coordination prevents conflicts
+- **📁 Better Organization**: Coordination scripts moved to `scripts/coordination/` for clarity
+- **🐛 Bug Fixes**: Fixed glob expansion issues in file coordination scripts
+
+### Previous Features (v1.3.0)
+- **📚 Intelligent House Rules System**: Auto-creates and updates project conventions for AI agents
+- **🟧 Real-time Undeclared Edit Detection**: Instantly alerts when files are edited without declaration
+- **🔴 File Conflict Prevention**: Detects and reports when multiple agents try to edit the same files
+- **🔄 Smart Version Updates**: House rules sections update independently while preserving user content
+- **🚀 Streamlined Setup**: One-command setup with `npm start` - handles everything automatically
+- **🔧 Self-Healing**: Automatically recovers if house rules are deleted
 
 ## 🔗 Quick Links
 
@@ -15,49 +31,51 @@ An intelligent Git automation system with multi-agent support, session managemen
 
 ## Features ✨
 
+### Core Features
 - **🤖 Multi-Agent Support**: Work with Claude, GitHub Copilot, Cursor, and other AI coding assistants
 - **📁 Git Worktree Management**: Isolated workspaces for each session to prevent conflicts
 - **🔄 Automatic Commits & Push**: Monitors changes and commits with proper messages
 - **📅 Daily Version Rollover**: Automatic version management with customizable increments
 - **🎯 Session Management**: Create, manage, and track multiple development sessions
 - **⚙️ VS Code Integration**: Seamlessly integrates with VS Code tasks
-- **🔐 Safe Concurrent Development**: Multiple agents can work simultaneously without conflicts
 - **🏷️ Smart Branching**: Automatic branch creation with configurable naming patterns
+
+### File Coordination (v1.3.0) 🆕
+- **🟧 Undeclared Edit Detection**: Orange alerts when agents edit files without declaring them
+- **🔴 Conflict Detection**: Red alerts when multiple agents try to edit the same files
+- **📝 Declaration Protocol**: Agents must declare files before editing to prevent conflicts
+- **⚡ Real-time Monitoring**: Detects violations within 2 seconds
+- **📋 Actionable Instructions**: Provides copy-paste commands to correct agent behavior
+- **🔒 Advisory Locks**: File-level coordination without blocking legitimate work
+
+### Infrastructure
+- **🔐 Safe Concurrent Development**: Multiple agents can work simultaneously without conflicts
 - **🐋 Docker Auto-Restart**: Automatically restart Docker containers after code push (v1.2.0)
 
 ## Installation 📦
 
-### Option 1: NPM Package (Recommended for Users)
+> **📖 Detailed Guide**: See [INSTALLATION_GUIDE.md](docs/INSTALLATION_GUIDE.md) for complete setup instructions
+
+### Quick Install (NPM Package)
 
-#### Global Installation
 ```bash
+# Install globally (recommended)
 npm install -g s9n-devops-agent
-```
 
-#### Local Installation
-```bash
-npm install s9n-devops-agent --save-dev
+# Verify installation
+s9n-devops-agent --help
 ```
 
-### Option 2: From Source (For Contributors)
-
-#### Clone the Repository
-```bash
-# Clone the repository
-git clone https://github.com/SecondBrainAICo/CS_DevOpsAgent.git
-cd CS_DevOpsAgent
+### What Gets Installed
 
-# Install dependencies
-npm install
+The NPM package installs:
+- ✅ **CLI Binary**: `s9n-devops-agent` command available globally
+- ✅ **Core Files**: Worker, session manager, and utilities in npm's global node_modules
+- ✅ **Dependencies**: `chokidar` for file watching, `execa` for git operations
+- ❌ **No Project Modifications**: Your project stays clean until you run setup
 
-# Link globally for development
-npm link
+### From Source (For Contributors)
 
-# Now you can use s9n-devops-agent command globally
-s9n-devops-agent --help
-```
-
-#### Development Setup
 ```bash
 # Clone and setup for development
 git clone https://github.com/SecondBrainAICo/CS_DevOpsAgent.git
@@ -66,35 +84,42 @@ cd CS_DevOpsAgent
 # Install dependencies
 npm install
 
+# Link globally for development
+npm link
+
 # Run tests
 npm test
-
-# Start development session
-npm run dev
 ```
 
 ## Quick Start 🚀
 
-### First-Time Setup
+### One-Command Setup & Start
 
 ```bash
-# Run the interactive setup wizard
-s9n-devops-agent setup
-
-# This will configure:
-# - Your developer initials (used in branch names)
-# - Version numbering strategy
-# - Default timezone for daily rollover
+# Just run npm start - it handles everything!
+npm start
+
+# On first run, it will:
+# ✅ Set up house rules for AI agents
+# ✅ Configure file coordination system
+# ✅ Set up your developer initials
+# ✅ Configure version strategy
+# ✅ Start the session manager
 ```
 
-### Start a DevOps Session
+That's it! No separate setup commands needed.
+
+### Alternative Setup Methods
 
 ```bash
-# Start the interactive session manager
-s9n-devops-agent start
+# Navigate to your project
+cd /path/to/your/project
 
-# Or create a new session directly
-s9n-devops-agent create --task "implement-api"
+# Run the interactive setup wizard (for manual setup)
+s9n-devops-agent setup
+
+# Or start a session directly
+s9n-devops-agent start
 ```
 
 ### Working with AI Assistants
@@ -107,13 +132,113 @@ I'm working in a DevOps-managed session with the following setup:
 - Working Directory: /path/to/worktree
 - Task: implement-api
 
-Please switch to this directory before making any changes:
-cd "/path/to/worktree"
+CRITICAL FIRST STEP:
+1. Read and follow the house rules: cat "/path/to/worktree/houserules.md"
+2. Switch to the working directory: cd "/path/to/worktree"
+
+FILE COORDINATION PROTOCOL (from house rules):
+Before editing ANY files, you MUST:
+- Declare your intent in .file-coordination/active-edits/<agent>-8a3s-45b1.json
+- Check for conflicts with other agents
+- Only edit files you've declared
+- Release files when done
 
 Write commit messages to: .devops-commit-8a3s-45b1.msg
 The DevOps agent will automatically commit and push changes.
 ```
 
+## House Rules & File Coordination System 📚🔒
+
+### House Rules System (NEW!)
+
+The DevOps Agent automatically manages "house rules" that teach AI agents your project conventions:
+
+**Features:**
+- **Auto-Creation**: Created automatically on first run
+- **Smart Updates**: Updates only DevOps sections, preserves your custom rules
+- **Version Tracking**: Each section independently versioned with checksums
+- **Self-Healing**: Automatically recreates if deleted
+- **CI/CD Ready**: Works in automated environments
+
+**House Rules Commands:**
+```bash
+# Check status
+npm run house-rules:status
+
+# Update or create
+npm run house-rules:update
+
+# Health check and repair
+npm run house-rules:repair
+```
+
+### File Coordination System
+
+Prevents multiple AI agents from editing the same files simultaneously:
+
+1. **Declaration Phase**: Agents declare which files they'll modify
+2. **Conflict Check**: System checks if files are already being edited
+3. **Real-time Monitoring**: Detects violations within 2 seconds
+4. **Alert System**: 
+   - 🟧 **Orange Alert**: Files edited without declaration
+   - 🔴 **Red Alert**: Files being edited by another agent
+5. **Copy-Paste Instructions**: Provides exact commands to correct agent behavior
+
+**Coordination Commands:**
+```bash
+# Check if files are available
+./scripts/coordination/check-file-availability.sh src/main.js src/utils.js
+
+# Declare intent to edit files
+./scripts/coordination/declare-file-edits.sh <agent-name> <session-id> file1.js file2.js
+
+# Release files after editing
+./scripts/coordination/release-file-edits.sh <agent-name> <session-id>
+
+# Run file locking demo
+./test_scripts/multi-agent/test-file-locking.sh
+```
+
+### For AI Agents
+
+Agents should follow this protocol:
+
+```json
+// Before editing, create: .file-coordination/active-edits/<agent>-<session>.json
+{
+  "agent": "claude",
+  "session": "8a3s-45b1",
+  "files": ["src/main.js", "src/utils.js"],
+  "operation": "edit",
+  "reason": "Implementing authentication feature",
+  "declaredAt": "2025-09-30T12:00:00Z",
+  "estimatedDuration": 300
+}
+```
+
+### Alert Examples
+
+#### Undeclared Edit Alert (🟧 Orange)
+```
+🟧🟧🟧🟧🟧🟧🟧🟧🟧🟧🟧🟧🟧🟧🟧
+🟧  UNDECLARED FILE EDIT DETECTED!
+🟧🟧🟧🟧🟧🟧🟧🟧🟧🟧🟧🟧🟧🟧🟧
+
+❌ File "src/main.js" was modified WITHOUT declaration!
+📋 COPY THIS INSTRUCTION TO YOUR CODING AGENT:
+[Instructions on how to declare the file]
+```
+
+#### Conflict Alert (🔴 Red)
+```
+🔴🔴🔴🔴🔴🔴🔴🔴🔴🔴🔴🔴🔴🔴🔴
+🔴  FILE CONFLICT DETECTED!
+🔴🔴🔴🔴🔴🔴🔴🔴🔴🔴🔴🔴🔴🔴🔴
+
+❌ File "src/main.js" is being edited by: claude-session-abc123
+[Instructions on how to resolve]
+```
+
 ## Commands 📝
 
 ### Session Management
@@ -151,6 +276,8 @@ s9n-devops-agent setup
 
 ## Configuration 🔧
 
+> **📖 Complete Configuration Guide**: See [INSTALLATION_GUIDE.md](docs/INSTALLATION_GUIDE.md#configuration-files)
+
 ### Environment Variables
 
 ```bash
@@ -174,9 +301,23 @@ export AC_VERSION_INCREMENT="1"  # 1 = 0.01, 10 = 0.1
 
 ### Configuration Files
 
-Configuration is stored in:
-- **Global settings**: `~/.devops-agent/settings.json` (developer initials, email)
-- **Project settings**: `local_deploy/project-settings.json` (version strategy, auto-merge)
+**Global Configuration** (`~/.devops-agent/settings.json`):
+- Developer initials and email
+- Default timezone settings
+- Created on first setup
+
+**Project Configuration** (`local_deploy/project-settings.json`):
+- Version numbering strategy
+- Auto-merge settings
+- Docker restart configuration
+- Created per project
+
+**House Rules** (`docs/houserules.md`):
+- Instructions for AI assistants
+- Testing requirements
+- Commit message format
+- Multi-agent coordination rules
+- **Must be created manually** ([see template](docs/INSTALLATION_GUIDE.md#house-rules-setup))
 
 ## Workflow Example 💡
 
@@ -289,29 +430,42 @@ At midnight (configurable timezone):
 
 ## Troubleshooting 🔍
 
+> **📖 Detailed Troubleshooting**: See [INSTALLATION_GUIDE.md](docs/INSTALLATION_GUIDE.md#troubleshooting)
+
 ### Common Issues
 
-**Session files showing as uncommitted**:
+**After npm install - command not found**:
 ```bash
-# Files are automatically gitignored
-# If issue persists, run:
-s9n-devops-agent cleanup
+# Check npm global bin directory
+npm bin -g
+# Add to PATH if needed
+export PATH="$PATH:$(npm bin -g)"
 ```
 
-**Permission denied errors**:
+**Setup wizard issues**:
 ```bash
-# Ensure scripts are executable
-chmod +x $(npm root -g)/s9n-devops-agent/bin/s9n-devops-agent
+# Ensure you're in a git repository
+git init
+# Run setup in project directory
+cd /your/project && s9n-devops-agent setup
 ```
 
 **Agent not detecting changes**:
 ```bash
-# Check if running in correct directory
-pwd
-# Ensure message file exists
+# Enable debug mode
+AC_DEBUG=true s9n-devops-agent start
+# Check message file exists and has content
 ls -la .devops-commit-*.msg
 ```
 
+**Multi-agent conflicts**:
+```bash
+# Check coordination files
+ls -la .ac-prep/ .ac/ack/
+# Clear if stuck
+rm -rf .ac-prep .ac
+```
+
 ## Contributing 🤝
 
 Contributions are welcome! Please feel free to submit a Pull Request.