gh-yebot-rad-cc-plugins-plugins-documentation-tools/commands/sync-agents-md.md

---
description: Synchronize all CLAUDE.md files to AGENTS.md files with generic AI agent language
allowed-tools:
  - Bash
  - Glob
  - Task
---

# Sync CLAUDE.md to AGENTS.md

Convert all CLAUDE.md files in the repository to generic AGENTS.md files that work with any AI coding assistant. This command transforms Claude-specific terminology to AI-agnostic language while preserving all technical content and maintaining documentation hierarchy.

## Instructions

1. **Find all CLAUDE.md files in the repository**:

   ```bash
   find . \( -name "CLAUDE.md" -o -name "claude.md" \) -type f | grep -v node_modules | grep -v .git | grep -v dist | grep -v build | sort
   ```

   - Identify all CLAUDE.md files (case variations)
   - Filter out build/dependency directories
   - Sort for organized processing

2. **Prepare for batch conversion**:

   a) **Display found files to user**:
   ```
   Found CLAUDE.md files:
   - ./CLAUDE.md
   - ./src/components/CLAUDE.md
   - ./packages/api/CLAUDE.md
   - ./services/auth/CLAUDE.md

   Total: X files
   ```

   b) **Confirm scope with user** (if many files):
   - If more than 5 files found, show the list
   - Let user know the conversion will begin
   - Note that AGENTS.md files will be created/updated in same directories

3. **Process each CLAUDE.md file using the claude-to-agents-converter agent**:

   a) **For each CLAUDE.md file found**:

   - Use the Task tool to launch the `claude-to-agents-converter` agent
   - Pass the specific file path to convert
   - Wait for conversion to complete
   - Track the result (success/failure)

   b) **Agent invocation format**:
   ```
   Task(
     subagent_type: "claude-to-agents-converter",
     description: "Convert CLAUDE.md to AGENTS.md",
     prompt: "Convert the CLAUDE.md file at [FILE_PATH] to AGENTS.md. Apply all transformation rules to make the documentation AI-agnostic. Report the transformations made."
   )
   ```

   c) **Process files in order** (root first, then nested):
   - Start with root CLAUDE.md (if exists)
   - Then process subdirectory CLAUDE.md files alphabetically
   - This ensures parent-child link consistency

4. **Track conversion results**:

   Keep a running tally:
   ```
   Conversion Progress:
   ✅ ./CLAUDE.md → ./AGENTS.md
   ✅ ./src/components/CLAUDE.md → ./src/components/AGENTS.md
   ✅ ./packages/api/CLAUDE.md → ./packages/api/AGENTS.md
   ⚠️  ./services/auth/CLAUDE.md → (warning: ...)
   ```

5. **Verify conversions**:

   After all conversions complete:

   a) **Count created/updated files**:
   ```bash
   find . \( -name "AGENTS.md" -o -name "agents.md" \) -type f | grep -v node_modules | grep -v .git | wc -l
   ```

   b) **Quick validation check** (optional):
   - Verify AGENTS.md files exist alongside CLAUDE.md files
   - Check file sizes are similar (content preserved)

6. **Report final results**:

   Provide comprehensive summary:

   ```
   📄 CLAUDE.md → AGENTS.md Synchronization Complete!

   Files Processed: X
   ✅ Successfully converted: Y
   ⚠️  Warnings: Z
   ❌ Failed: 0

   Created/Updated AGENTS.md files:
   - ./AGENTS.md (3,245 bytes)
   - ./src/components/AGENTS.md (1,892 bytes)
   - ./packages/api/AGENTS.md (2,456 bytes)
   - ./services/auth/AGENTS.md (1,234 bytes)

   Common transformations applied:
   - "Claude Code" → "AI coding assistants"
   - "Claude" → "AI agent" / "AI assistant"
   - CLAUDE.md links → AGENTS.md links
   - URLs to claude.ai/code removed

   ✅ All CLAUDE.md files now have corresponding AGENTS.md versions!

   Next Steps:
   - Review AGENTS.md files for accuracy
   - Commit both CLAUDE.md and AGENTS.md to version control
   - AGENTS.md files will auto-sync when CLAUDE.md is updated (via hooks)
   ```

7. **Handle edge cases**:

   | Issue | Solution |
   |-------|----------|
   | No CLAUDE.md files found | Report "No CLAUDE.md files found in repository" |
   | Agent conversion fails | Report specific file and error, continue with others |
   | AGENTS.md already exists | Overwrite with new conversion (sync means update) |
   | Nested CLAUDE.md hierarchy | Process root first to ensure link consistency |

## Important Guidelines

### Processing Order

**Why order matters:**
- Parent CLAUDE.md files often reference child CLAUDE.md files
- Converting parent first ensures child references are updated consistently
- Alphabetical processing of subdirectories maintains predictable order

**Recommended order:**
1. `./CLAUDE.md` (root - always first)
2. First-level subdirectories (e.g., `./src/CLAUDE.md`, `./packages/CLAUDE.md`)
3. Deeper nesting (e.g., `./src/components/CLAUDE.md`)

### Transformation Consistency

All files should receive identical transformation rules:
- ✅ Same terminology replacements across all files
- ✅ All CLAUDE.md → AGENTS.md link updates
- ✅ Consistent handling of Claude Code specific features
- ✅ Preservation of technical content in all files

### Agent Delegation

- **Always use the Task tool** to invoke the `claude-to-agents-converter` agent
- **Do NOT attempt manual conversion** - the agent has specialized logic
- **Let the agent handle** each file independently for robustness

### Error Handling

If a conversion fails:
- Report the specific file and error
- Continue processing remaining files
- Include failed files in final summary
- Suggest manual review for failed conversions

## Use Cases

### Initial Setup
First time creating AGENTS.md versions of existing CLAUDE.md files:
```
/sync-agents-md
```

### After Bulk CLAUDE.md Updates
Multiple CLAUDE.md files were updated, need to sync all:
```
/sync-agents-md
```

### Recovery
AGENTS.md files got out of sync or were deleted:
```
/sync-agents-md
```

### Verification
Check that all CLAUDE.md files have corresponding AGENTS.md:
```
/sync-agents-md
```

## Best Practices

1. **Run after major CLAUDE.md changes**: If you've restructured or significantly updated CLAUDE.md files

2. **Commit both versions**: Always commit both CLAUDE.md and AGENTS.md to version control together

3. **Review first conversion**: On initial setup, review the generated AGENTS.md files to ensure quality

4. **Use hooks for maintenance**: After initial setup, the hooks will keep files in sync automatically

5. **Periodic sync**: Run occasionally to catch any files that might have been missed

## Example Scenarios

### Scenario 1: New Repository Setup

```
User has been using CLAUDE.md files, wants to add AGENTS.md versions.

1. Run: /sync-agents-md
2. Review generated AGENTS.md files
3. Commit all AGENTS.md files
4. Hooks will maintain sync going forward
```

### Scenario 2: Monorepo with Multiple CLAUDE.md Files

```
Monorepo with CLAUDE.md in:
- ./CLAUDE.md (root)
- ./packages/web/CLAUDE.md
- ./packages/api/CLAUDE.md
- ./packages/shared/CLAUDE.md

1. Run: /sync-agents-md
2. Agent processes all 4 files
3. Creates 4 corresponding AGENTS.md files
4. All child references updated consistently
```

### Scenario 3: AGENTS.md Out of Sync

```
User updated CLAUDE.md files manually, AGENTS.md is outdated.

1. Run: /sync-agents-md
2. All AGENTS.md files overwritten with fresh conversions
3. Sync restored
```

## Definition of Done

- [ ] All CLAUDE.md files found in repository
- [ ] Each CLAUDE.md file processed by claude-to-agents-converter agent
- [ ] Conversions completed in correct order (root first)
- [ ] All successful conversions tracked
- [ ] Any failures or warnings noted
- [ ] AGENTS.md files verified to exist
- [ ] Comprehensive summary report provided
- [ ] User informed of next steps
- [ ] Total file counts match expectations
- [ ] No CLAUDE.md files left without corresponding AGENTS.md