Sync Agents - Documentation Synchronization Command

Synchronizes all project documentation files to ensure consistency and accuracy across:

• CLAUDE.md - Machine instructions for Claude Code AI
• AGENTS.md - Repository guidelines and standards for OpenAI Codex
• GEMINI.md - Repository guidelines and standards for Google Gemini CLI
• README.md - Project overview and quick start for human developers
• .cursorrules - Cursor IDE-specific rules

Usage

/sync-agents                    # Synchronize existing files only
/sync-agents --create-missing   # Also create any missing documentation files

Instructions for Claude Code

When this command is invoked:

1. Check for arguments:

   • If user includes --create-missing or asks to create missing files, set createMissing: true
   • Otherwise, set createMissing: false (default)

2. Launch the agent-sync-specialist sub-agent:

   Use the Task tool with:
   - subagent_type: "general-purpose"
   - description: "Synchronize documentation files"
   - prompt: See below
   

3. Sub-agent prompt:

   You are a documentation synchronization expert. Your task is to synchronize all project documentation files to ensure consistency.
   
   ## Documentation Files to Synchronize
   
   - CLAUDE.md - Machine instructions for Claude Code AI
   - AGENTS.md - Repository guidelines for OpenAI Codex
   - GEMINI.md - Repository guidelines for Google Gemini CLI
   - README.md - Project overview for human developers
   - .cursorrules - Cursor IDE-specific rules
   
   ## Create Missing Files Mode: [true/false]
   
   If "true": Create any missing documentation files based on existing ones as the source of truth.
   If "false": Only synchronize files that already exist. Report which files are missing but do NOT create them.
   
   ## Your Task
   
   1. **Analyze**: Read all existing documentation files to identify the source of truth
   2. **Report Missing**: List any documentation files that don't exist
   3. **Compare**: Detect inconsistencies in directives across existing files
   4. **Synchronize**: Update existing files to ensure consistency while preserving each file's unique purpose
   5. **Create** (only if Create Missing Files Mode is true): Generate missing files based on existing documentation
   6. **Verify**: Confirm all existing files are consistent
   
   ## Critical Directives to Synchronize
   
   Ensure these key directives are consistent across all files:
   
   - **Code Quality**: DRY, KISS, YAGNI principles; TypeScript strict mode; no `any` types
   - **Testing**: Coverage requirements; test output modes; pre-commit validation
   - **Git Workflow**: Conventional Commits; never commit to main; never force push
   - **Development Environment**: Node.js version; tech stack; MCP setup
   - **Project Structure**: File organization; import aliases; naming conventions
   - **Security**: No secrets in code; input validation; authentication patterns
   
   ## Expected Output
   
   Provide:
   
   1. **Analysis Summary**: Which file is the source of truth
   2. **Missing Files**: List files that don't exist (and whether they were created)
   3. **Directive Comparison Table**: Status of each directive across existing files
   4. **Changes Required**: Specific updates needed for each file
   5. **Implementation**: Make actual file updates with explanations
   6. **Verification**: Confirm all files are synchronized
   
   ## Guidelines
   
   - Preserve each file's unique purpose and format
   - Do NOT create missing files unless Create Missing Files Mode is true
   - Don't remove content unless contradictory or outdated
   - Maintain cross-references between files
   - Ask for clarification when contradictions are found
   
   Now, analyze all documentation files and synchronize them.
   

4. After the sub-agent completes, summarize:

   • Files that were updated
   • Files that are missing (and whether they were created)
   • Key changes made
   • Any issues that need manual review

When to Use This Command

Run /sync-agents when:

• You've updated any documentation file (CLAUDE.md, AGENTS.md, GEMINI.md, README.md)
• You've added new development standards or workflows
• You want to ensure all documentation is consistent
• You've onboarded to a project and want to verify documentation integrity
• Before starting a new feature to ensure you have the latest guidelines
• After a major refactoring or architectural change

Run /sync-agents --create-missing when:

• You want to generate missing documentation files (GEMINI.md, .cursorrules, etc.)
• Setting up a new project that needs all documentation files

Notes

• By default, missing files are reported but NOT created
• Use --create-missing flag to create missing documentation files
• The agent preserves each file's unique purpose and format
• No content is removed unless it's contradictory or outdated
• Cross-references between files are maintained