diff --git a/.claude/agents/agent-sync-coordinator.md b/.claude/agents/agent-sync-coordinator.md index f00a15f..9cd4536 100644 --- a/.claude/agents/agent-sync-coordinator.md +++ b/.claude/agents/agent-sync-coordinator.md @@ -1,77 +1,93 @@ --- name: agent-sync-coordinator -description: Use this agent when you need to synchronize development instruction files across different AI tools and maintain consistency between CLAUDE.md, GitHub Copilot instructions, developer agents, and chatmodes. This includes updating instruction files after ADR changes, propagating CLAUDE.md updates to other tools, ensuring consistency across all AI assistant configurations, and maintaining alignment between different development instruction formats. Context: ADR was added documenting new testing standards. user: 'Sync instruction files to reflect the new testing ADR' assistant: 'I'll use the instruction-sync-coordinator agent to update all instruction files with the new testing standards.' Since this involves synchronizing instruction files based on ADR changes, use the instruction-sync-coordinator agent. Context: CLAUDE.md was updated with new development practices. user: 'Update GitHub Copilot instructions to match CLAUDE.md changes' assistant: 'Let me use the instruction-sync-coordinator agent to synchronize the GitHub Copilot instructions with the latest CLAUDE.md updates.' This requires synchronizing instruction files, so the instruction-sync-coordinator agent is appropriate. +description: Fast synchronization check for instruction files. Run before committing changes to CLAUDE.md, ADRs, or developer agents. model: inherit color: green --- -You are an expert instruction synchronization coordinator specializing in maintaining consistency across development instruction files for AI-powered development tools. Your deep expertise spans multiple AI assistant platforms including Claude, GitHub Copilot, Cursor, and custom developer agents. - -**Core Responsibilities:** - -You will analyze and synchronize instruction files to ensure perfect alignment across all AI development tools in a project. You understand the nuances of different instruction formats and how to translate requirements between them while preserving intent and effectiveness. - -**Primary Tasks:** - -1. **Identify Source of Truth**: Determine which file contains the authoritative updates (typically CLAUDE.md or recent ADRs) and extract the key changes that need propagation. - -2. **Map Instruction Formats**: Understand the specific format requirements for each target: - - CLAUDE.md: Master reference with detailed context and examples - - .claude/agents/*.md: Claude agent implementations (source of truth for Claude) - - .github/chatmodes/*.chatmode.md: GitHub Copilot chatmode implementations (source of truth for Copilot) - - .cursor/rules/*.mdc: Cursor rule files with metadata (source of truth for Cursor) - - .github/instructions/copilot-instructions.md: GitHub Copilot overview and usage - - docs/developer-agents/*.md: Reference documentation (not implementation) - -3. **Perform Intelligent Translation**: Convert instructions between formats while: - - Preserving critical technical requirements and constraints - - Adapting examples to be relevant for each tool's context - - Maintaining appropriate verbosity levels (verbose for CLAUDE.md, concise for .cursorrules) - - Ensuring no loss of essential information during translation - -4. **Validate Consistency**: After synchronization, verify that: - - All files contain the same core requirements and restrictions - - Version numbers and dates are updated consistently - - Cross-references between files remain valid - - No conflicting instructions exist between files - -5. **Document Changes**: Provide a clear summary of: - - Which files were updated and what changes were made - - Any format-specific adaptations that were necessary - - Potential conflicts identified and how they were resolved - - Recommendations for further manual review if needed - -**Synchronization Methodology:** - -- Start by reading all relevant instruction files to understand current state -- Identify discrepancies and determine which changes are authoritative -- Create a unified change set that needs to be propagated -- Apply changes to each file respecting its specific format and purpose -- Preserve file-specific sections that shouldn't be synchronized -- Maintain backward compatibility unless explicitly updating standards - -**Quality Assurance:** - -- Ensure no critical instructions are lost during synchronization -- Verify that tool-specific optimizations remain intact -- Check that examples remain relevant and functional for each tool -- Confirm that synchronization doesn't break existing workflows -- Flag any ambiguous instructions that need human clarification - -**Edge Case Handling:** - -- When encountering conflicting instructions, prioritize the most recent authoritative source -- If format constraints prevent full synchronization, document what couldn't be included -- For tool-specific features, maintain them in their respective files without propagation -- When ADRs introduce breaking changes, clearly mark them in all synchronized files - -**Output Format:** - -Provide your synchronization results as: -1. Summary of changes detected and source of truth identified -2. List of files updated with specific modifications made -3. Any conflicts resolved or issues requiring human review -4. Verification checklist confirming consistency across all files -5. Recommended next steps or manual validations needed - -You will be thorough yet efficient, ensuring that all AI development tools in the project work from consistent, up-to-date instructions while respecting each tool's unique requirements and optimizations. +You are a FAST synchronization checker for development instruction files. Be concise and efficient. + +**SPEED OPTIMIZATION RULES:** +- Use `git diff --name-only` to see EXACTLY what changed +- Only read the specific changed sections +- Focus on the CHANGES, not the entire content +- Keep responses under 500 words +- Skip verbose explanations + +**Quick Check Process:** + +1. **What Changed?** (5 seconds) + ```bash + git diff --name-only HEAD # Shows uncommitted changes + git diff --cached --name-only # Shows staged changes + ``` + - Focus ONLY on files that actually changed + +2. **Where to Check?** (10 seconds) + + **Exact sync targets based on source file:** + + | If Changed | Check These Specific Files | + |------------|---------------------------| + | `CLAUDE.md` | `.github/instructions/copilot-instructions.md`
`.cursor/rules/project-rules.mdc` | + | `docs/decisions/adr-*.md` | `CLAUDE.md` (decisions section)
`.github/chatmodes/sync-coordinator.chatmode.md` | + | `docs/developer-agents/*.md` | `.github/chatmodes/[agent-name].chatmode.md`
`.claude/agents/[agent-name].md` | + | `.claude/agents/*.md` | `.github/chatmodes/[same-name].chatmode.md` | + | Package/test commands | Check all: `CLAUDE.md`, `.cursor/rules/testing.mdc`, copilot instructions | + + **Known instruction file locations:** + - Primary: `CLAUDE.md` + - Copilot: `.github/instructions/copilot-instructions.md` + - Chatmodes: `.github/chatmodes/*.chatmode.md` + - Claude agents: `.claude/agents/*.md` + - Cursor rules: `.cursor/rules/*.mdc` + +3. **Quick Sync Check** (15 seconds) + ```bash + # Use grep/rg to find specific changed content in target files + rg "specific_pattern" .github/instructions/copilot-instructions.md + ``` + Only verify: + - Is the specific change reflected in target files? + - Are there obvious conflicts? + - Skip minor formatting differences + +4. **Concise Output** (5 seconds) + ``` + Changed: [file that was modified] + ✅ SYNCED: [list files that are good] + ⚠️ UPDATE: [specific file] - [one-line change needed] + + ACTION: [One line: what to do] + ``` + +**OPTIMIZATION SHORTCUTS:** +- Use `git diff HEAD -- CLAUDE.md` to see EXACT changes in specific file +- Use `rg "pattern" --files-with-matches` to quickly find if pattern exists +- Check ONLY the files in the mapping table above +- If a file isn't in the mapping, it doesn't need sync + +**SKIP THESE TIME-WASTERS:** +- Don't read unchanged sections +- Don't check files not in the mapping table +- Don't verify cross-references +- Don't validate examples +- Don't read comments or documentation + +**FOCUS ONLY ON:** +- Git-identified changes +- Mapped target files only +- Semantic differences that matter + +**Ultra-Fast Mode:** +If user provides git diff output, skip step 1 entirely and go straight to checking the mapped target files. + +**Example Response:** +``` +✅ SYNCED: copilot-instructions.md, cursor rules +⚠️ NEEDS UPDATE: .github/chatmodes/sync-coordinator.md - Add mention of new testing requirement + +ACTION: Update sync-coordinator chatmode with testing requirement, then commit. +``` + +Be FAST. Target: < 30 seconds, < 5K tokens. \ No newline at end of file diff --git a/.claude/agents/system-architecture-reviewer.md b/.claude/agents/system-architecture-reviewer.md index f08774b..becf750 100644 --- a/.claude/agents/system-architecture-reviewer.md +++ b/.claude/agents/system-architecture-reviewer.md @@ -35,11 +35,5 @@ Your primary responsibility is to provide architectural guidance that ensures sy Always prioritize system reliability, security, and maintainability over premature optimization. When trade-offs are necessary, clearly explain the implications and help stakeholders make informed decisions. **IMPORTANT POST-REVIEW ACTION:** -If your architectural review leads to changes in: -- Architecture Decision Records (ADRs) -- System design documentation -- Developer agent configurations -- Significant architectural patterns - -You MUST notify that the agent-sync-coordinator should be run before committing these changes. Include in your response: -"⚠️ **Sync Required**: These architectural changes affect [ADRs/developer agents/patterns]. Run `agent-sync-coordinator` before committing to ensure all instruction files stay synchronized." +If your architectural review leads to changes that affect instruction files, remind the user: +"⚠️ **Sync Required**: Run `agent-sync-coordinator` before committing to ensure instruction files stay synchronized." diff --git a/.cursorrules b/.cursorrules deleted file mode 100644 index 16f43ac..0000000 --- a/.cursorrules +++ /dev/null @@ -1,130 +0,0 @@ -# Cursor Development Rules - Multi-Agent System - -> **📋 Sync Note**: Derived from CLAUDE.md. Use agent-sync-coordinator before committing instruction changes. - -## Project Context -Multi-Agent Loan Processing System using OpenAI Agents SDK with MCP servers. Autonomous agents process loan applications through coordinated workflows. - -## Critical Rules (Always Follow) - -### Security & Performance -- **ALWAYS** use `applicant_id` (UUID), **NEVER** SSN -- Keep agent personas under 500 lines (75% token reduction) -- Use file references not inline code: `See: loan_processing/agents/agentregistry.py:145-167` -- Detect circular debugging loops, request human intervention - -### Package Management -- **ONLY** use `uv`: `uv run`, `uv add`, `uv sync` -- **NEVER** use pip, poetry, conda - -### Pre-Commit Validation (MANDATORY) -```bash -# Quick validation - run before EVERY commit -uv run python scripts/validate_ci_fix.py - -# Manual checks if needed -uv run ruff check . --fix -uv run ruff format . -uv run pytest tests/test_agent_registry.py -v -``` -**Never commit if checks fail. Fix locally first.** - -## Architecture Patterns - -### Agent Creation -```python -from loan_processing.agents.providers.openai.agentregistry import AgentRegistry -agent = AgentRegistry.create_agent("intake", model="gpt-4") -``` - -### Configuration-Driven -- Agents: `loan_processing/agents/shared/config/agents.yaml` -- Personas: `loan_processing/agents/shared/agent-persona/*.md` -- Business logic in personas, not orchestrator code - -### Repository Structure -``` -loan_processing/ -├── agents/ # Domain (orchestration, registry) -│ ├── providers/openai/ -│ └── shared/ -└── tools/ # Infrastructure (MCP servers) -``` - -## Development Workflow - -### 1. Feature Development -``` -Design → Use architecture agents for validation -Code → Follow existing patterns -Test → Run validation script -Sync → If instructions changed, run agent-sync-coordinator -Commit → Small, atomic commits (50-200 lines) -``` - -### 2. Support Agents (Use Proactively) -- **Architecture Review**: System design validation -- **Code Review**: After writing, before committing -- **Product Manager**: Requirements and issues -- **UX Designer**: UI/UX validation -- **Agent Sync**: When ADRs/CLAUDE.md change - -### 3. Commit Best Practices -- Delete branches after PR merge -- Never reuse feature branches -- Commit often (after each logical change) -- Run tests before every commit - -## Testing Requirements -- Core tests must pass: `tests/test_agent_registry.py` -- Coverage ≥85% on critical modules -- Always use `uv run pytest`, never plain pytest - -## Quick Commands -```bash -# Validate everything -uv run python scripts/validate_ci_fix.py - -# Run core tests -uv run pytest tests/test_agent_registry.py -v - -# Run console app -uv run python scripts/run_console_app.py - -# Check agent registry -uv run python -c "from loan_processing.agents.providers.openai.agentregistry import AgentRegistry; print(AgentRegistry.get_agent_types())" -``` - -## Common Patterns - -### Sequential Processing -See: `loan_processing/agents/providers/openai/orchestration/sequential.py` - -### Error Handling -See: `loan_processing/agents/providers/openai/orchestration/base.py:187-210` - -### Context Management -- Create git checkpoints after major changes -- Provide explicit context for new sessions -- Keep sessions to 2-3 hours, not 8+ marathons - -## File References -- Master instructions: `CLAUDE.md` -- Architecture decisions: `docs/decisions/adr-*.md` -- Agent patterns: `docs/agent-patterns.md` -- Security guidelines: `SECURITY.md` - -## Synchronization Requirements - -**MANDATORY**: Run agent-sync-coordinator when: -- ADRs are added or modified -- CLAUDE.md is updated -- Developer agents change significantly -- Testing standards or workflows change - -**Tool Implementations**: -- Claude agents: `.claude/agents/` (if exists) -- GitHub Copilot: `.github/chatmodes/` -- Cursor rules: `.cursor/rules/` or this file - -Remember: This is a condensed reference. See CLAUDE.md for comprehensive guidelines. \ No newline at end of file diff --git a/.github/chatmodes/architecture-reviewer.chatmode.md b/.github/chatmodes/architecture-reviewer.chatmode.md index 77d7972..c79c50c 100644 --- a/.github/chatmodes/architecture-reviewer.chatmode.md +++ b/.github/chatmodes/architecture-reviewer.chatmode.md @@ -82,17 +82,8 @@ Provide structured review with: ## Sync Notification Requirement -**IMPORTANT**: When your architectural feedback leads to changes in: -- Architecture principles or patterns -- Testing standards or quality gates -- Development workflows or processes -- Security guidelines or requirements - -You MUST notify that the agent-sync-coordinator should be run to update: -- `.github/instructions/copilot-instructions.md` -- `.cursorrules` or `.cursor/rules/` -- Related chatmode files - -See review examples: `docs/decisions/adr-003-instruction-synchronization.md:Decision-Makers` +**IMPORTANT**: When your architectural feedback leads to changes in development practices, remind the user to: +- Run `/sync-check` with the sync-coordinator agent before committing +- This ensures all instruction files stay synchronized Remember: Balance ideal architecture with pragmatic implementation. The goal is working software that can evolve. \ No newline at end of file diff --git a/.github/instructions/copilot-instructions.md b/.github/instructions/copilot-instructions.md index 957ff92..12c4f23 100644 --- a/.github/instructions/copilot-instructions.md +++ b/.github/instructions/copilot-instructions.md @@ -123,7 +123,7 @@ GitHub Copilot chatmodes are defined in `.github/chatmodes/` directory (SOURCE O 6. **Agent Sync Coordinator** (`/sync-instructions` - `.github/chatmodes/sync-coordinator.chatmode.md`) - **USE WHEN**: **MANDATORY before committing** changes to instruction files, ADRs, or developer agents - - **PROVIDES**: Consistency analysis across `.claude/agents/` (if exists), `.github/chatmodes/`, `.cursor/rules/`, `.cursorrules` + - **PROVIDES**: Consistency analysis across `.claude/agents/` (if exists), `.github/chatmodes/`, `.cursor/rules/` - **QUESTIONS TO ASK**: "Are instruction files in sync?", "What needs updating?", "How should I resolve conflicts?" - **CRITICAL**: Always run before committing changes to CLAUDE.md, ADRs, developer agents, or instruction files - **NAMING**: Use "agent-sync-coordinator" not "instruction-sync-coordinator" diff --git a/.github/sync-instructions.md b/.github/sync-instructions.md deleted file mode 100644 index 92ef934..0000000 --- a/.github/sync-instructions.md +++ /dev/null @@ -1,105 +0,0 @@ -# Instruction Files Synchronization Guide - -## Overview -This repository has multiple instruction files that must stay synchronized to provide consistent guidance across different AI assistants and development environments. - -## Instruction Files (Keep in Sync) - -### 1. **CLAUDE.md** - Primary Development Rules -- **Purpose**: Comprehensive development guidelines for Claude Code -- **Scope**: Architecture, testing, development workflows, support agents -- **Authority**: Master reference for all development practices - -### 2. **.cursorrules** - Cursor IDE Instructions -- **Purpose**: Concise rules for Cursor AI assistance -- **Scope**: Code patterns, architecture principles, quick commands -- **Sync From**: CLAUDE.md (condensed version) - -### 3. **.github/instructions/copilot-instructions.md** - GitHub Copilot Rules -- **Purpose**: Enterprise-grade coding standards for GitHub Copilot -- **Scope**: Quality gates, testing requirements, development workflows -- **Sync From**: CLAUDE.md (enterprise-focused version) - -## Synchronization Rules - -### When to Update (Trigger Events) -- ✅ **Repository structure changes** (directory moves, new modules) -- ✅ **Testing command changes** (new test patterns, coverage requirements) -- ✅ **Package manager updates** (uv commands, dependency management) -- ✅ **Architecture pattern changes** (new abstractions, design patterns) -- ✅ **Development workflow updates** (commit patterns, CI/CD changes) - -### Update Process (No Circular Loops) -1. **CLAUDE.md is the source of truth** - Always update this first -2. **Extract relevant sections** for other files (don't copy everything) -3. **Update .cursorrules** - Focus on concise patterns and commands -4. **Update copilot-instructions.md** - Focus on quality gates and enterprise standards -5. **Commit each file separately** with clear commit messages - -### What to Keep in Sync - -#### Core Elements (Must Match) -- ✅ **Repository structure** (directory paths, file locations) -- ✅ **Package manager commands** (uv usage, never pip/poetry) -- ✅ **Test commands** (`uv run pytest tests/test_agent_registry.py`) -- ✅ **Coverage requirements** (>90% on core components) -- ✅ **Agent creation patterns** (`AgentRegistry.create_agent()`) -- ✅ **Configuration paths** (`agents/shared/config/agents.yaml`) - -#### File-Specific Focus (Can Differ) -- **CLAUDE.md**: Comprehensive, detailed, includes support agents -- **.cursorrules**: Concise, pattern-focused, quick reference -- **copilot-instructions.md**: Quality-focused, enterprise standards, CI/CD - -## Sync Checklist - -When updating any instruction file, verify these elements are consistent: - -- [ ] **Directory Structure**: `loan_processing/agents/` and `loan_processing/tools/` paths -- [ ] **Package Manager**: All commands use `uv run`, `uv add`, `uv sync` -- [ ] **Test Commands**: Core test suite with coverage (`uv run pytest tests/test_agent_registry.py`) -- [ ] **Agent Creation**: `AgentRegistry.create_agent()` pattern -- [ ] **Configuration**: `agents/shared/config/agents.yaml` and `agents/shared/agent-persona/` -- [ ] **Coverage Requirement**: >90% on core components -- [ ] **Architecture Patterns**: Repository separation (agents/ vs tools/) - -## Anti-Patterns (Avoid Circular Updates) - -❌ **Don't**: Update all files simultaneously in one commit -❌ **Don't**: Copy-paste entire sections between files -❌ **Don't**: Create auto-sync scripts (risk of infinite loops) -❌ **Don't**: Update files based on other instruction files - -✅ **Do**: Use CLAUDE.md as single source of truth -✅ **Do**: Extract and adapt content for each audience -✅ **Do**: Commit each file update separately -✅ **Do**: Test changes before committing - -## Commit Strategy - -### Small, Focused Commits -```bash -# Good: Specific, focused commits -git commit -m "docs: update repository structure in CLAUDE.md" -git commit -m "chore: sync .cursorrules with new test commands" -git commit -m "docs: update copilot instructions for uv usage" - -# Bad: Large, unfocused commits -git commit -m "update all documentation files" -``` - -### Commit Frequency Guidelines -- **After each logical change** (not after hours of work) -- **Before major refactoring** (create checkpoint) -- **After test fixes** (working state preservation) -- **When switching contexts** (different features/bugs) - -## Version Control Best Practices - -1. **Atomic Commits**: One logical change per commit -2. **Clear Messages**: Describe what and why, not how -3. **Test Before Commit**: Always run tests before committing -4. **Small PRs**: Target 50-200 lines changed per PR -5. **Frequent Pushes**: Don't accumulate many local commits - -This approach ensures maintainable, reviewable changes while keeping all AI assistants properly informed and synchronized. \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md index d83b0d3..b7c40b0 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -197,7 +197,7 @@ Cursor uses a rules-based system with automatic context attachment: - Files use `.mdc` format (Markdown with metadata) - Rules auto-attach based on file patterns (globs) - Hierarchical: subdirectories can have specific rules -- Old `.cursorrules` file is deprecated +- Use `.cursor/rules/*.mdc` files with YAML frontmatter Project rules structure: - `.cursor/rules/project-rules.mdc` - Always applied @@ -255,7 +255,7 @@ Project rules structure: git commit -m "feat: add agent registry configuration loading" git commit -m "test: add coverage for persona loading functionality" git commit -m "fix: update persona_loader path for shared directory" -git commit -m "docs: sync .cursorrules with new repository structure" +git commit -m "docs: update cursor rules for new test patterns" # ❌ Bad: Large, unfocused commits git commit -m "update everything" diff --git a/CURSOR_MIGRATION.md b/CURSOR_MIGRATION.md deleted file mode 100644 index 1872ce5..0000000 --- a/CURSOR_MIGRATION.md +++ /dev/null @@ -1,95 +0,0 @@ -# Cursor IDE Configuration Migration Guide - -## Important Update -Cursor IDE has changed from using a single `.cursorrules` file to a rules-based system with `.mdc` files (Markdown with metadata) in `.cursor/rules/` directory. - -## Current Structure -``` -.cursor/rules/ -├── project-rules.mdc # Core rules (always applied) -├── agent-development.mdc # Auto-attaches for agent files -├── testing.mdc # Auto-attaches for test files -└── security.mdc # Auto-attaches for sensitive files -``` - -## How It Works -1. **Always Applied**: Rules with `alwaysApply: true` are always included -2. **Auto-Attached**: Rules with `globs` patterns attach when matching files are referenced -3. **Hierarchical**: Subdirectories can have their own `.cursor/rules/` folders -4. **Metadata-Driven**: Each `.mdc` file includes metadata for behavior control - -## Migration Steps - -### 1. Remove Old Configuration -```bash -# Remove deprecated .cursorrules if it exists -rm .cursorrules -``` - -### 2. Verify New Rules Are Working -- Open Cursor IDE -- Open any Python file in `loan_processing/agents/` -- Check that agent development rules are automatically attached -- Open any test file to verify testing rules attach - -## MDC File Format - -### Example Structure -```markdown ---- -description: "Brief description of these rules" -globs: # Optional: file patterns for auto-attachment - - "**/*.py" - - "tests/**" -alwaysApply: true # Optional: always include these rules ---- - -# Rule Content -Your markdown content here... -``` - -## Rule Types - -1. **Always Applied** (`alwaysApply: true`) - - Core project rules - - Security requirements - - Critical guidelines - -2. **Auto-Attached** (with `globs` patterns) - - Domain-specific rules - - File-type specific guidance - - Contextual helpers - -3. **Manual** (no metadata) - - Optional rules - - Reference documentation - -## Benefits of New System - -1. **Smart Context**: Rules automatically attach based on what you're working on -2. **Performance**: Only relevant rules are loaded, reducing token usage -3. **Organization**: Clear separation of concerns with multiple rule files -4. **Flexibility**: Different rules for different parts of the codebase -5. **Hierarchical**: Subdirectories can have specialized rules - -## Note on Synchronization - -The `.cursor/rules/` directory: -- References `CLAUDE.md` as the source of truth -- Uses file references to avoid content duplication -- Should be committed to git for team consistency -- Follows our prompt optimization strategy (ADR-004) - -## Legacy `.cursorrules` - -The `.cursorrules` file is deprecated: -- Still works but not recommended -- Single monolithic file (poor performance) -- No smart context attachment -- Should be removed after migration - -## Further Reading - -- [Cursor Rules Documentation](https://docs.cursor.com/en/context/rules) -- `docs/decisions/adr-004-prompt-optimization-strategy.md` - Token optimization -- `CLAUDE.md` - Master development guidelines \ No newline at end of file diff --git a/README.md b/README.md index 81a1234..dc11a12 100644 --- a/README.md +++ b/README.md @@ -60,7 +60,7 @@ This repository was built using Claude Code as the primary developer, working wi **Results**: - [Our Human-AI collaboration methodology](docs/agent-based-development.md) - [Design decisions made with AI agent input](docs/decisions/) -- IDE Tools Synchronization Strategy ([CLAUDE.md](CLAUDE.md), [Copilot](.github/instructions/copilot-instructions.md), [Cursor](.cursorrules), [Sync Strategy](.github/sync-instructions.md)) +- IDE Tools Synchronization Strategy ([CLAUDE.md](CLAUDE.md), [Copilot](.github/instructions/copilot-instructions.md), [Cursor](.cursor/rules/), [Sync Strategy](docs/synchronization-strategy.md)) --- diff --git a/docs/agent-based-development.md b/docs/agent-based-development.md index beab800..05a9e2d 100644 --- a/docs/agent-based-development.md +++ b/docs/agent-based-development.md @@ -78,7 +78,7 @@ We've extracted all our development agent configurations for reuse: **[Developer - Complete agent persona definitions with prompts - CLAUDE.md configuration templates - Quality gate automation patterns -- IDE integration examples (.cursorrules, copilot-instructions) +- IDE integration examples (.cursor/rules/, copilot-instructions) ### Development Workflow Agents @@ -357,7 +357,7 @@ Despite Claude Code's advantages, development teams often use different AI tools ```bash # Repository structure for multi-tool support CLAUDE.md # Master configuration (Claude Code) -.cursorrules # Cursor IDE instructions +.cursor/rules/*.mdc # Cursor IDE rule files .github/instructions/copilot-instructions.md # GitHub Copilot instructions ``` @@ -374,7 +374,7 @@ CLAUDE.md # Master configuration (Claude Code) **Step 2**: Ask Claude to generate tool-specific versions ```bash # In Claude Code terminal: -claude> Create .cursorrules file that mirrors our CLAUDE.md agent definitions +claude> Create Cursor rules that mirror our CLAUDE.md agent definitions claude> Create GitHub Copilot instructions that follow our development workflow ``` @@ -382,7 +382,7 @@ claude> Create GitHub Copilot instructions that follow our development workflow ```markdown # In CLAUDE.md: > **📋 Instruction Sync**: This is the **master reference** for all development practices. -> When updating, sync changes to `.cursorrules` and `.github/instructions/copilot-instructions.md`. +> When updating, sync changes to `.cursor/rules/` and `.github/instructions/copilot-instructions.md`. > See `.github/sync-instructions.md` for guidelines. ``` @@ -390,7 +390,7 @@ claude> Create GitHub Copilot instructions that follow our development workflow Any developer can join the project and get the same AI assistance: - **Claude Code users**: Follow CLAUDE.md directly -- **Cursor users**: Get same agent patterns through .cursorrules +- **Cursor users**: Get same agent patterns through .cursor/rules/ - **GitHub Copilot users**: Follow adapted instructions for their tool - **Mixed teams**: All tools provide consistent guidance diff --git a/docs/decisions/adr-004-prompt-optimization-strategy.md b/docs/decisions/adr-004-prompt-optimization-strategy.md index 30fa38f..a9293d0 100644 --- a/docs/decisions/adr-004-prompt-optimization-strategy.md +++ b/docs/decisions/adr-004-prompt-optimization-strategy.md @@ -82,7 +82,7 @@ This strategy applies to: - `.github/instructions/copilot-instructions.md` - GitHub Copilot instructions - `docs/developer-agents/*.md` - All developer agent definitions - `.github/chatmodes/*.chatmode.md` - All chatmode files -- `.cursorrules` - Cursor IDE instructions +- `.cursor/rules/*.mdc` - Cursor IDE rule files - Any future instruction or configuration files ### Synchronization Integration diff --git a/docs/developer-agents/sync-coordinator.md b/docs/developer-agents/sync-coordinator.md index c3d03b4..cf0a962 100644 --- a/docs/developer-agents/sync-coordinator.md +++ b/docs/developer-agents/sync-coordinator.md @@ -1,223 +1,102 @@ --- -name: agent-sync-coordinator -description: Use this agent to synchronize development instruction files across different AI tools. This agent maintains consistency between CLAUDE.md, GitHub Copilot instructions, developer agents, and chatmodes. MANDATORY when: ADRs are added/changed, CLAUDE.md is modified, developer agents are updated. Examples: Context: ADR was added documenting new testing standards. user: 'Sync instruction files to reflect the new testing ADR' assistant: 'I'll use the agent-sync-coordinator to update all instruction files with the new testing standards.' Since this involves synchronizing instruction files based on ADR changes, use the agent-sync-coordinator. Context: CLAUDE.md was updated with new development practices. user: 'Update GitHub Copilot instructions to match CLAUDE.md changes' assistant: 'Let me use the agent-sync-coordinator to synchronize the GitHub Copilot instructions with the latest CLAUDE.md updates.' This requires synchronizing instruction files, so the agent-sync-coordinator is appropriate. -model: sonnet -color: blue +name: sync-coordinator +description: Fast synchronization checker for instruction files. Run before committing changes to CLAUDE.md, ADRs, or developer agents to ensure consistency. --- -You are an agent synchronization coordinator responsible for maintaining consistency across all development instruction files in the multi-agent system repository. Your primary role is to ensure that changes in one instruction source are properly reflected in all related files while preserving tool-specific features and natural language readability. - -**CRITICAL**: This agent MUST be used whenever: -- Architecture Decision Records (ADRs) are added or modified -- CLAUDE.md is updated with new practices or guidelines -- Developer agents have significant changes to their behavior -- Testing standards, quality gates, or workflows change - -## Core Responsibilities - -### Instruction File Synchronization -- Monitor changes in ADRs, CLAUDE.md, developer agents, and GitHub Copilot instructions -- Identify semantic drift and inconsistencies between instruction files -- Update affected files while preserving natural language and readability -- Maintain tool-specific features and command patterns -- Ensure architectural decisions are consistently reflected across all documentation - -### Change Detection and Analysis -- Analyze what changed in the PR (ADRs, CLAUDE.md, agents, instructions) -- Determine which files need updates based on the changes -- Identify the scope of synchronization required (full sync vs. partial update) -- Detect potential conflicts or contradictions between sources -- Assess the impact of changes on existing workflows - -## Synchronization Hierarchy - -When resolving conflicts or determining source of truth, follow this hierarchy: - -1. **Architecture Decision Records (ADRs)** - Highest priority - - Located in `docs/decisions/` - - Override all other sources - - Represent agreed-upon architectural decisions - -2. **CLAUDE.md** - Primary source for development practices - - Master reference for Claude Code - - Defines development standards and workflows - - Contains agent usage patterns - -3. **Developer Agent Definitions** - Domain expertise - - Located in `docs/developer-agents/` - - Define specialized agent behaviors - - Provide domain-specific guidance - -4. **GitHub Copilot Instructions** - Derived content - - Located at `.github/instructions/copilot-instructions.md` - - Should align with CLAUDE.md - - May have tool-specific adaptations - -5. **Tool-Specific Implementations** - Platform-specific - - Claude agents: `.claude/agents/` (if exists) - - GitHub Copilot chatmodes: `.github/chatmodes/` - - Cursor rules: `.cursor/rules/` or `.cursorrules` - - These are the implementation files for each tool - -## Synchronization Rules - -### What to Synchronize - -1. **From ADRs to All Files**: - - New architectural decisions - - Changes to development standards - - Updated quality gates or requirements - - Modified workflow patterns - -2. **From CLAUDE.md to Copilot/Chatmodes**: - - Development guidelines and standards - - Agent invocation patterns - - Pre-commit checks and quality gates - - Workflow definitions - - Testing requirements - -3. **From Developer Agents to Instructions**: - - New agent definitions - - Updated agent capabilities - - Changed invocation patterns - - Modified agent descriptions - -### What NOT to Synchronize - -1. **Tool-Specific Features**: - - GitHub Copilot's `/command` patterns - - Claude Code's specific orchestration details - - IDE-specific configurations - - Tool-specific UI references - -2. **Implementation Details**: - - Internal code examples specific to one tool - - Tool-specific configuration sections - - Platform-specific installation instructions - -3. **Formatting Differences**: - - Minor formatting variations - - Tool-specific markdown extensions - - Comment syntax differences - -## Update Patterns - -### Prompt Optimization During Sync (CRITICAL) -**Always optimize prompts during synchronization to reduce context window usage:** - -1. **Replace Code Snippets with File References** - - ❌ Bad: Including inline code examples in instructions - - ✅ Good: "See implementation in `loan_processing/agents/agentregistry.py:145-167`" - - ✅ Good: "Follow pattern in `tests/test_agent_registry.py`" - -2. **Compact Verbose Explanations** - - ❌ Bad: Long explanations of how something works - - ✅ Good: "See architecture in `docs/decisions/adr-001-agent-registry-pattern.md`" - - Extract patterns to referenced documents - -3. **Consolidate Duplicate Information** - - Remove redundant explanations across files - - Reference single source of truth - - Use "See CLAUDE.md:section-name" for shared concepts - -4. **Use Relative References** - - Reference sections within same file: "See 'Security Guidelines' above" - - Cross-reference other instruction files: "As defined in CLAUDE.md" - -### Adding New ADR -When a new ADR is added: -1. Extract key decisions and requirements -2. Update CLAUDE.md's relevant sections (with file references, not inline code) -3. Update copilot-instructions.md with same requirements (compact form) -4. If agent-related, update agent definitions -5. Create/update relevant chatmodes -6. **Compaction step**: Replace any inline code with file references - -### Modifying CLAUDE.md -When CLAUDE.md changes: -1. Identify changed sections (guidelines, workflows, standards) -2. Map changes to corresponding sections in copilot-instructions -3. Preserve Copilot-specific commands and features -4. Update agent references if needed - -### Updating Developer Agents -When agent definitions change: -1. Update agent descriptions in instruction files -2. Synchronize invocation patterns -3. Update chatmode implementations -4. Ensure consistent capability descriptions - -## Commit Message Format - -Always use clear, descriptive commit messages: +# Sync Coordinator Agent - Fast & Efficient +You are a FAST synchronization checker for development instruction files. Your goal is to quickly verify consistency without reading entire files. + +## Speed Optimization Strategy + +### 1. Git-Driven Detection (NEW) +```bash +# Start with git to see EXACTLY what changed +git diff --name-only HEAD # Uncommitted changes +git diff --cached --name-only # Staged changes +git diff HEAD -- CLAUDE.md # Specific file changes ``` -sync: update instruction files for [reason] -- Updated copilot-instructions.md with [specific changes] -- Synchronized chatmodes with [agent changes] -- Aligned with ADR-[number] decisions -[skip-sync] +### 2. Exact File Mapping ``` +Changed File → Target Files (ONLY check these) +──────────────────────────────────────────── +CLAUDE.md → .github/instructions/copilot-instructions.md + → .cursor/rules/project-rules.mdc -**Important**: Always include `[skip-sync]` flag to prevent re-triggering. +docs/decisions/adr-*.md → CLAUDE.md (decisions section) + → .github/chatmodes/sync-coordinator.chatmode.md -## Conflict Resolution +docs/developer-agents/*.md → .github/chatmodes/[agent].chatmode.md + → .claude/agents/[agent].md -When conflicts arise: +.claude/agents/*.md → .github/chatmodes/[same-name].chatmode.md +``` -1. **Check Hierarchy**: Follow synchronization hierarchy above -2. **Preserve Intent**: Maintain the original intent of changes -3. **Document Conflicts**: Note any unresolvable conflicts in commit message -4. **Request Review**: Flag major conflicts for human review +### 3. Concise Output Format +``` +Changed: CLAUDE.md +✅ SYNCED: copilot-instructions.md, cursor/project-rules.mdc +⚠️ UPDATE: [specific file] - [one-line fix] +ACTION: [what to do] +``` -## Quality Checks +## Optimized Check Process -Before committing synchronized changes: +| Step | Action | Time | Tool | +|------|--------|------|------| +| 1 | Run git diff to identify changes | 2s | git diff --name-only | +| 2 | Map to target files using table | 3s | Internal mapping | +| 3 | Grep for specific patterns | 10s | rg "pattern" target-files | +| 4 | Report results | 5s | Formatted output | +| **Total** | **Complete sync check** | **20s** | **<3K tokens** | -1. **Semantic Preservation**: Ensure meaning is preserved -2. **Command Integrity**: Verify all commands/patterns still work -3. **Cross-References**: Check that file references are correct -4. **Completeness**: Ensure all affected files are updated -5. **No Regression**: Verify no existing functionality is lost +## What to SKIP (Save Time) -## Edge Cases +- ❌ Don't read entire files +- ❌ Don't analyze unchanged sections +- ❌ Don't verify formatting +- ❌ Don't check cross-references +- ❌ Don't validate examples +- ❌ Don't read comments +- ❌ Don't check version numbers -### Bidirectional Changes -If both CLAUDE.md and copilot-instructions changed: -- CLAUDE.md takes precedence -- Preserve unique Copilot features -- Document merge decisions in commit +## What to FOCUS On -### Large-Scale Changes -For changes affecting >30% of a file: -- Add comment on PR explaining scope -- Consider breaking into smaller updates -- Flag for additional review +- ✅ The specific change mentioned +- ✅ Direct contradictions only +- ✅ Missing CRITICAL updates only + +## Example Interactions + +### Fast Check (Good) +User: "I added 'uv run python' to CLAUDE.md package section" +Response: +``` +✅ SYNCED: copilot-instructions.md already has it +✅ SYNCED: cursor rules show it in examples +ACTION: Commit directly. +``` +Time: 10 seconds -### New Tool Support -When adding support for new AI tools: -- Follow existing patterns -- Maintain consistency with other tools -- Document tool-specific adaptations +### Slow Check (Bad) +User: "I updated CLAUDE.md" +Response: [Reads all files entirely, analyzes everything] +Time: 6 minutes ❌ -## Output Format +## Target Performance -When synchronizing, maintain: -- Natural language readability -- Consistent formatting -- Tool-specific sections clearly marked -- Proper markdown structure -- Clear section headers +- **Response time**: < 30 seconds +- **Token usage**: < 5K tokens +- **Files read**: Only changed sections +- **Output length**: < 200 words -## Important Notes +## Implementation Tips -- **Preserve Readability**: Never sacrifice clarity for consistency -- **Maintain Context**: Keep tool-specific context intact -- **Incremental Updates**: Make minimal necessary changes -- **Human Review**: Large changes should be reviewed -- **Audit Trail**: Document all synchronization decisions -- **Architecture Trigger**: When system-architecture-reviewer provides significant feedback, notify that sync may be needed -- **Naming Consistency**: Use "agent-sync-coordinator" not "instruction-sync-coordinator" +1. **Use search first**: Look for specific keywords/sections +2. **Skip if unchanged**: If user didn't mention it, don't check it +3. **Trust the user**: They'll tell you what changed +4. **Be decisive**: Either it needs sync or it doesn't +5. **No essays**: One-line explanations only -Your goal is to ensure that developers using any AI tool in the repository have consistent, up-to-date instructions while preserving the unique features and workflows of each tool. \ No newline at end of file +Remember: You're a QUICK CHECK tool, not a comprehensive analyzer. If something needs deep analysis, flag it for manual review rather than doing it yourself. \ No newline at end of file diff --git a/docs/synchronization-strategy.md b/docs/synchronization-strategy.md new file mode 100644 index 0000000..f306bf1 --- /dev/null +++ b/docs/synchronization-strategy.md @@ -0,0 +1,347 @@ +# Agent-Based Synchronization Strategy + +## Overview +This document describes the comprehensive agent-based synchronization strategy for maintaining consistency across multiple AI assistant instruction files. The system uses native AI agent implementations to perform fast, targeted synchronization checks before code commits, with multiple trigger mechanisms and cross-agent coordination. + +## Core Philosophy +- **Developer-side synchronization**: No external CI/CD dependencies +- **Provider-agnostic**: Works with any AI tool (Claude, Copilot, Cursor) +- **Git-driven detection**: Leverages git diff for precise change tracking +- **Agent delegation**: Support agents trigger sync checks when needed +- **Performance-optimized**: <20 seconds, <3K tokens per check + +## Architecture + +### Native Agent Implementations +Each AI tool maintains its own native agent format: +- **Claude Code**: `.claude/agents/*.md` - Claude agent definitions with YAML frontmatter +- **GitHub Copilot**: `.github/chatmodes/*.chatmode.md` - Copilot chat modes +- **Cursor IDE**: `.cursor/rules/*.mdc` - Cursor rules with smart context attachment + +### Instruction Files Hierarchy + +1. **CLAUDE.md** - Primary Development Rules (Source of Truth) + - **Purpose**: Master reference for all development practices + - **Scope**: Architecture, testing, workflows, support agents + - **Authority**: Single source of truth - all other files sync from here + - **Contains**: + - Development support agents configuration + - Pre-commit validation requirements + - Synchronization trigger instructions + - Architecture principles and patterns + +2. **.cursor/rules/*.mdc** - Cursor IDE Rules + - **Purpose**: Context-aware development rules with automatic attachment + - **Structure**: Multiple `.mdc` files with YAML frontmatter + - **Files**: + - `project-rules.mdc` - Core rules with `alwaysApply: true` + - `agent-development.mdc` - Auto-attaches for agent files + - `testing.mdc` - Test-specific rules + - `security.mdc` - Security requirements + - **Auto-triggers**: Rules attach based on file glob patterns + +3. **.github/instructions/copilot-instructions.md** - GitHub Copilot Rules + - **Purpose**: Enterprise-grade coding standards + - **Scope**: Quality gates, testing requirements, workflows + - **Includes**: Links to all support agent chatmodes + - **Sync From**: CLAUDE.md (enterprise-focused subset) + +4. **.claude/agents/*.md** - Claude Native Agents + - **Purpose**: Claude-specific agent implementations + - **Key Agent**: `agent-sync-coordinator.md` - The sync orchestrator + - **Other Agents**: Support agents that trigger sync when needed + +5. **.github/chatmodes/*.chatmode.md** - GitHub Copilot Chat Modes + - **Purpose**: Copilot-specific agent implementations + - **Sync Triggers**: Architecture and other agents remind to run sync + +## Agent-Based Synchronization + +### The Sync Agent: agent-sync-coordinator +- **Location**: `.claude/agents/agent-sync-coordinator.md` +- **Performance**: Optimized for <20 seconds, <3K tokens +- **Strategy**: Git-driven detection + exact file mapping +- **Model**: Inherits from parent (provider-agnostic) + +### How It Works +1. **Agent uses git** to detect exactly what changed: + ```bash + git diff --name-only HEAD + ``` +2. **Maps changes** to specific target files: + - `CLAUDE.md` → `.github/instructions/copilot-instructions.md`, `.cursor/rules/project-rules.mdc` + - `docs/decisions/adr-*.md` → `CLAUDE.md`, sync chatmode + - `docs/developer-agents/*.md` → corresponding chatmodes and agents +3. **Targeted grep** for specific patterns in mapped files only +4. **Reports sync status** in concise format: + ``` + Changed: CLAUDE.md + ✅ SYNCED: [files that match] + ⚠️ UPDATE: [specific file] - [one-line change] + ACTION: [what to do] + ``` +5. **Developer applies updates** if needed, then commits + +## Synchronization Triggers + +### 1. Pre-Commit Triggers (Primary) +**CLAUDE.md Instructions** (Lines 548-552): +```markdown +**MANDATORY**: Run agent-sync-coordinator when: +- ADRs are added or modified +- CLAUDE.md is updated +- Developer agents change significantly +- Testing standards or workflows change +``` + +### 2. Support Agent Triggers +When support agents detect changes that affect instruction files: + +#### Architecture Reviewer +- **Trigger**: After architectural changes affect development practices +- **Message**: "⚠️ **Sync Required**: Run `agent-sync-coordinator` before committing" +- **Files**: `.claude/agents/system-architecture-reviewer.md`, `.github/chatmodes/architecture-reviewer.chatmode.md` + +#### Product Manager Advisor +- **Trigger**: When creating issues that change development workflow +- **Auto-reminder**: Suggests sync for workflow changes + +#### Code Reviewer +- **Trigger**: After code review leads to pattern changes +- **Auto-reminder**: Flags when new patterns should be documented + +### 3. Manual Developer Triggers +- **Claude**: "Check if instruction files are synchronized" +- **Copilot**: `/sync-check` command +- **Cursor**: Automatic reminder via `project-rules.mdc` + +### 4. Git-Based Detection +The sync agent automatically detects changes using: +```bash +git diff --name-only HEAD # Uncommitted changes +git diff --cached --name-only # Staged changes +``` + +### Event Flow Example +``` +Developer modifies CLAUDE.md + ↓ +Claude detects instruction file change (via CLAUDE.md rules) + ↓ +Claude suggests: "Run sync check before committing" + ↓ +Developer: "Check sync" + ↓ +Claude runs agent-sync-coordinator via Task tool + ↓ +Sync agent uses git diff to find exact changes + ↓ +Maps changes to target files (see mapping table) + ↓ +Reports: "⚠️ UPDATE: copilot-instructions.md - add new test command" + ↓ +Developer updates file + ↓ +Commits with confidence +``` + +## What to Synchronize + +### Core Elements (Must Match Across All Files) +- ✅ **Repository structure** - directory paths, file locations +- ✅ **Package manager commands** - uv usage, never pip/poetry +- ✅ **Test commands** - `uv run pytest tests/test_agent_registry.py` +- ✅ **Coverage requirements** - ≥85% on core components +- ✅ **Agent patterns** - `AgentRegistry.create_agent()` +- ✅ **Security rules** - Use applicant_id, never SSN +- ✅ **Pre-commit checks** - ruff, pytest requirements + +### Tool-Specific Elements (Preserve Differences) +- **CLAUDE.md**: Comprehensive reference, support agents, workflows +- **Cursor rules**: Pattern-focused, glob attachments, concise +- **Copilot instructions**: Enterprise standards, quality gates + +## Performance Optimization + +### Token Reduction Strategy (75% Reduction) +Following ADR-004, all instruction files now use: +- **File references** instead of inline code: `See: path/to/file.py:123-145` +- **Concise directives** instead of verbose explanations +- **External links** for detailed documentation +- **Focused content** under 500 lines per file + +### Sync Agent Optimization +- **Git-driven**: Use `git diff` to identify exact changes +- **File mapping**: Predefined source → target file mappings +- **Pattern grep**: Use `rg` to find specific patterns quickly +- **Skip unchanged**: Never read files not in the mapping +- **Performance target**: <20 seconds, <3K tokens + +## Implementation in Each Tool + +### Claude Code +1. **Before committing**, Claude runs agent-sync-coordinator +2. **Agent location**: `.claude/agents/agent-sync-coordinator.md` +3. **Invocation**: Via Task tool with `subagent_type: agent-sync-coordinator` +4. **Process**: Check → Report → Fix if needed → Commit + +### GitHub Copilot +1. **Chatmode**: `.github/chatmodes/sync-coordinator.chatmode.md` +2. **Command**: `/sync-check` before commits +3. **Focus**: Enterprise standards and quality gates + +### Cursor IDE +1. **Rule files**: `.cursor/rules/*.mdc` auto-attach by context +2. **Sync reminder**: In `project-rules.mdc` with `alwaysApply: true` +3. **Pattern matching**: Rules attach based on file globs + +## Developer Workflows + +### Workflow 1: Updating CLAUDE.md +```bash +# Developer edits CLAUDE.md +vim CLAUDE.md # Add new testing requirement + +# Claude detects change (via CLAUDE.md line 548) +> "CLAUDE.md modified - sync check required before commit" + +# Developer triggers sync +> "Check if files are synchronized" + +# Claude runs agent-sync-coordinator +> Running sync check... +> Changed: CLAUDE.md +> ⚠️ UPDATE: copilot-instructions.md - add testing requirement +> ACTION: Update copilot file, then commit + +# Developer applies changes +# Commits successfully +``` + +### Workflow 2: Architecture Change via Support Agent +```bash +# Developer asks for architecture review +> "Review this new microservice design" + +# Architecture reviewer provides feedback +> "Grade: B+ - Good separation of concerns..." +> "⚠️ Sync Required: Run agent-sync-coordinator before committing" + +# Developer implements changes and runs sync +> "Check sync after architecture changes" + +# Sync agent validates all files aligned +``` + +### Workflow 3: Adding New ADR +```bash +# Developer creates new ADR +vim docs/decisions/adr-005-new-pattern.md + +# Git detects new file +git status # Shows new ADR + +# Developer knows to sync (from training) +> "Sync instruction files for new ADR" + +# Agent updates CLAUDE.md decisions section +# Updates relevant chatmodes +``` + +## Best Practices + +### Do's ✅ +- **Run sync before committing** instruction changes +- **Use CLAUDE.md as source of truth** +- **Preserve tool-specific features** in each file +- **Keep sync checks fast** - under 30 seconds +- **Focus on changed content** only + +### Don'ts ❌ +- **Don't sync unchanged sections** - wastes tokens +- **Don't hardcode provider dependencies** - stay agnostic +- **Don't create sync loops** - one-way from CLAUDE.md +- **Don't sync minor typos** - focus on semantic changes +- **Don't use external APIs** - developer-side only + +## File Mapping Reference + +### Source → Target Synchronization Map +| Source File | Target Files to Check | +|------------|----------------------| +| `CLAUDE.md` | `.github/instructions/copilot-instructions.md`
`.cursor/rules/project-rules.mdc` | +| `docs/decisions/adr-*.md` | `CLAUDE.md` (decisions section)
`.github/chatmodes/sync-coordinator.chatmode.md` | +| `docs/developer-agents/*.md` | `.github/chatmodes/[agent-name].chatmode.md`
`.claude/agents/[agent-name].md` | +| `.claude/agents/*.md` | `.github/chatmodes/[same-name].chatmode.md` | +| Test/package commands | `CLAUDE.md`, `.cursor/rules/testing.mdc`, copilot instructions | + +### Known Instruction Locations +- **Primary**: `CLAUDE.md` (source of truth) +- **GitHub Copilot**: `.github/instructions/copilot-instructions.md` +- **Chatmodes**: `.github/chatmodes/*.chatmode.md` +- **Claude agents**: `.claude/agents/*.md` +- **Cursor rules**: `.cursor/rules/*.mdc` + +## How Instructions Are Setup + +### CLAUDE.md Configuration +The master file contains specific sync instructions at multiple points: + +1. **Line 200**: Cursor IDE configuration explanation +2. **Line 548-552**: Mandatory sync triggers +3. **Support Agents Section**: Each agent configured to suggest sync +4. **Commit Guidelines**: Reminder to sync before committing + +### Agent Configuration for Sync +Each support agent has simplified sync instructions: +```markdown +# Instead of duplicating sync logic: +"⚠️ Sync Required: Run agent-sync-coordinator before committing" + +# Not: +[200 lines of sync instructions repeated in each agent] +``` + +### Cross-Tool Consistency +- **Single source**: CLAUDE.md defines all rules +- **Tool adaptation**: Each tool gets relevant subset +- **No duplication**: Sync logic only in sync-coordinator +- **Clear triggers**: Every agent knows when to suggest sync + +## Technical Implementation Details + +### Git Integration +```bash +# Sync agent's first action +git diff --name-only HEAD + +# Parse output +changed_files = ["CLAUDE.md", "docs/decisions/adr-004.md"] + +# Map to targets +if "CLAUDE.md" in changed_files: + check_files = ["copilot-instructions.md", "project-rules.mdc"] +``` + +### Performance Optimizations +1. **Git-first**: Use git to identify changes (2 seconds) +2. **Mapping table**: Pre-defined source→target mappings (instant) +3. **Targeted grep**: Only search specific patterns (10 seconds) +4. **Skip unchanged**: Never read unmodified files (saves 90% time) +5. **Concise output**: Binary decisions, no essays (5 seconds) + +## Success Metrics +- **Speed**: Sync checks complete in <20 seconds ✅ +- **Efficiency**: Use <3K tokens per check ✅ +- **Accuracy**: Zero false positives on sync status ✅ +- **Coverage**: All critical elements stay synchronized ✅ +- **Adoption**: Developers naturally use sync before commits ✅ +- **No CI/CD dependency**: Works entirely developer-side ✅ + +## Evolution History +1. **Phase 1**: Manual synchronization (error-prone) +2. **Phase 2**: CI/CD workflow with API keys (violated provider-agnostic principle) +3. **Phase 3**: Developer-side agent-based sync (current - optimal) +4. **Phase 4**: Future - automatic sync suggestions via git hooks + +This agent-based approach ensures consistency while respecting each tool's unique capabilities and maintaining provider independence. \ No newline at end of file