feat: add ClaudeKit configuration

Add agent definitions, slash commands, hooks, and settings for Claude Code project tooling.
2026-04-17 19:22:28 +00:00 · 2026-04-12 10:02:12 +07:00
parent e389311a2e
commit 00d6bb117b
59 changed files with 23205 additions and 0 deletions
--- a/.claude/commands/agents-md/cli.md
+++ b/.claude/commands/agents-md/cli.md
@@ -0,0 +1,85 @@
+---
+description: Capture CLI tool help documentation and add it to CLAUDE.md for AI assistant reference
+category: claude-setup
+allowed-tools: Bash(*:--help), Bash(*:-h), Bash(*:help), Bash(which:*), Bash(echo:*), Bash(sed:*), Edit, Read
+argument-hint: "<cli-tool-name>"
+---
+
+# Add CLI Tool Documentation to CLAUDE.md
+
+Capture help documentation from CLI tools and add it to CLAUDE.md for future reference.
+
+## Usage
+`/agents-md:cli <tool-name>`
+
+Examples:
+- `/agents-md:cli npm`
+- `/agents-md:cli git`
+- `/agents-md:cli cargo`
+
+## Task
+
+### 1. Check Tool Availability
+First, verify the CLI tool exists:
+!`which $ARGUMENTS 2>/dev/null && echo "✅ $ARGUMENTS is available" || echo "❌ $ARGUMENTS not found"`
+
+### 2. Capture Help Documentation
+If the tool exists, capture its help output. Try different help flags in order:
+
+```bash
+# Try common help flags
+$ARGUMENTS --help 2>&1 || $ARGUMENTS -h 2>&1 || $ARGUMENTS help 2>&1
+```
+
+### 3. Update CLAUDE.md
+Add or update the CLI tool documentation in CLAUDE.md following these steps:
+
+1. **Check for existing CLI Tools Reference section**
+   - If it doesn't exist, create it after the Configuration section
+   - If it exists, add the new tool in alphabetical order
+
+2. **Format the documentation** as a collapsible section:
+   ```markdown
+   ## CLI Tools Reference
+   
+   Documentation for CLI tools used in this project.
+   
+   <details>
+   <summary><strong>$ARGUMENTS</strong> - [Brief description from help output]</summary>
+   
+   ```
+   [Help output here, with ANSI codes stripped]
+   ```
+   
+   </details>
+   ```
+
+3. **Clean the output**:
+   - Remove ANSI escape codes (color codes, cursor movements)
+   - Preserve the structure and formatting
+   - Keep command examples and options intact
+
+4. **Extract key information**:
+   - Tool version if shown in help output
+   - Primary purpose/description
+   - Most commonly used commands or options
+
+### 4. Provide Summary
+After updating CLAUDE.md, show:
+- ✅ Tool documentation added to CLAUDE.md
+- Location in file where it was added
+- Brief summary of what was captured
+- Suggest reviewing CLAUDE.md to ensure formatting is correct
+
+## Error Handling
+- If tool not found: Suggest checking if it's installed and in PATH
+- If no help output: Try running the tool without arguments
+- If help output is extremely long (>500 lines): Capture key sections only
+- If CLAUDE.md is a symlink: Update the target file (likely AGENTS.md)
+
+## Implementation Notes
+When processing help output:
+1. Strip ANSI codes: `sed 's/\x1b\[[0-9;]*m//g'`
+2. Handle tools that output to stderr by using `2>&1`
+3. Preserve important formatting like tables and lists
+4. Keep code examples and command syntax intact
--- a/.claude/commands/agents-md/init.md
+++ b/.claude/commands/agents-md/init.md
@@ -0,0 +1,434 @@
+---
+description: Initialize project with AGENTS.md and create symlinks for all AI assistants
+category: claude-setup
+allowed-tools: Write, Bash(ln:*), Bash(mkdir:*), Bash(test:*), Bash(echo:*), Read, Glob, Task
+---
+
+# Initialize AGENTS.md for Your Project
+
+Create a comprehensive AGENTS.md file following the universal standard, with symlinks for all AI assistants.
+
+## Current Status
+!`test -f AGENTS.md && echo "⚠️  AGENTS.md already exists" || echo "✅ Ready to create AGENTS.md"`
+
+## Task
+
+Please analyze this codebase and create an AGENTS.md file containing:
+1. Build/lint/test commands - especially for running a single test
+2. Code style guidelines including imports, formatting, types, naming conventions, error handling, etc.
+
+Usage notes:
+- The file you create will be given to agentic coding agents (such as yourself) that operate in this repository
+- If there's already an AGENTS.md, improve it
+- If there are Cursor rules (in .cursor/rules/ or .cursorrules) or Copilot rules (in .github/copilot-instructions.md), make sure to include them
+- Start the file with: "# AGENTS.md\nThis file provides guidance to AI coding assistants working in this repository."
+
+### 1. Gather Repository Information
+Use Task tool with description "Gather repository information" to run these Glob patterns in parallel:
+- `package*.json` - Node.js project files
+- `*.md` - Documentation files
+- `.github/workflows/*.yml` - GitHub Actions workflows
+- `.github/workflows/*.yaml` - GitHub Actions workflows (alternate extension)
+- `.cursor/rules/**` - Cursor rules
+- `.cursorrules` - Cursor rules (alternate location)
+- `.github/copilot-instructions.md` - GitHub Copilot rules
+- `.claude/agents/**/*.md` - Specialized AI subagents
+- `requirements.txt`, `setup.py`, `pyproject.toml` - Python projects
+- `go.mod` - Go projects
+- `Cargo.toml` - Rust projects
+- `Gemfile` - Ruby projects
+- `pom.xml`, `build.gradle` - Java projects
+- `*.csproj` - .NET projects
+- `Makefile` - Build automation
+- `.eslintrc*`, `.prettierrc*` - Code style configs
+- `tsconfig.json` - TypeScript config
+- `.env.example` - Environment configuration
+- `**/*.test.*`, `**/*.spec.*` - Test files (limit to a few)
+- `Dockerfile`, `docker-compose*.yml` - Docker configuration
+
+Also examine:
+- README.md for project overview and command documentation
+- package.json scripts to document all available commands
+- GitHub workflows to identify CI/CD commands
+- A few source files to infer coding conventions
+- Test files to understand testing patterns
+- `.claude/agents/` directory to discover available subagents
+
+**Script Consistency Check**: When documenting npm scripts from package.json, verify they match references in:
+- GitHub Actions workflows (npm run, npm test, etc.)
+- README.md installation and usage sections
+- Docker configuration files
+- Any setup or deployment scripts
+
+### 2. Check for Existing Configs
+- If AGENTS.md exists, improve it based on analysis
+- If .cursorrules or .cursor/rules/* exist, incorporate them
+- If .github/copilot-instructions.md exists, include its content
+- If other AI configs exist (.clinerules, .windsurfrules), merge them
+- If `.claude/agents/` directory exists, document available subagents with their descriptions and usage examples
+
+### 3. Create AGENTS.md
+Based on your analysis, create AGENTS.md with this structure:
+
+```markdown
+# AGENTS.md
+This file provides guidance to AI coding assistants working in this repository.
+
+**Note:** [Document if CLAUDE.md or other AI config files are symlinks to AGENTS.md]
+
+# [Project Name]
+
+[Project Overview: Brief description of the project's purpose and architecture]
+
+## Build & Commands
+
+[Development, testing, and deployment commands with EXACT script names:]
+
+**CRITICAL**: Document the EXACT script names from package.json, not generic placeholders.
+For example:
+- Build: `npm run build` (if package.json has "build": "webpack")
+- Test: `npm test` (if package.json has "test": "jest")
+- Type check: `npm run typecheck` (if package.json has "typecheck": "tsc --noEmit")
+- Lint: `npm run lint` (if package.json has "lint": "eslint .")
+
+If the project uses different names, document those:
+- Type check: `npm run tsc` (if that's what's in package.json)
+- Lint: `npm run eslint` (if that's what's in package.json)
+- Format: `npm run prettier` (if that's what's in package.json)
+
+[Include ALL commands from package.json scripts, even if they have non-standard names]
+
+### Script Command Consistency
+**Important**: When modifying npm scripts in package.json, ensure all references are updated:
+- GitHub Actions workflows (.github/workflows/*.yml)
+- README.md documentation
+- Contributing guides
+- Dockerfile/docker-compose.yml
+- CI/CD configuration files
+- Setup/installation scripts
+
+Common places that reference npm scripts:
+- Build commands → Check: workflows, README, Dockerfile
+- Test commands → Check: workflows, contributing docs
+- Lint commands → Check: pre-commit hooks, workflows
+- Start commands → Check: README, deployment docs
+
+**Note**: Always use the EXACT script names from package.json, not assumed names
+
+## Code Style
+
+[Formatting rules, naming conventions, and best practices:]
+- Language/framework specifics
+- Import conventions
+- Formatting rules
+- Naming conventions
+- Type usage patterns
+- Error handling patterns
+[Be specific based on actual code analysis]
+
+## Testing
+
+[Testing frameworks, conventions, and execution guidelines:]
+- Framework: [Jest/Vitest/Pytest/etc]
+- Test file patterns: [*.test.ts, *.spec.js, etc]
+- Testing conventions
+- Coverage requirements
+- How to run specific test suites
+
+### Testing Philosophy
+**When tests fail, fix the code, not the test.**
+
+Key principles:
+- **Tests should be meaningful** - Avoid tests that always pass regardless of behavior
+- **Test actual functionality** - Call the functions being tested, don't just check side effects
+- **Failing tests are valuable** - They reveal bugs or missing features
+- **Fix the root cause** - When a test fails, fix the underlying issue, don't hide the test
+- **Test edge cases** - Tests that reveal limitations help improve the code
+- **Document test purpose** - Each test should include a comment explaining why it exists and what it validates
+
+## Security
+
+[Security considerations and data protection guidelines:]
+- Authentication/authorization patterns
+- Data validation requirements
+- Secret management
+- Security best practices specific to this project
+
+## Directory Structure & File Organization
+
+### Reports Directory
+ALL project reports and documentation should be saved to the `reports/` directory:
+
+```
+your-project/
+├── reports/              # All project reports and documentation
+│   └── *.md             # Various report types
+├── temp/                # Temporary files and debugging
+└── [other directories]
+```
+
+### Report Generation Guidelines
+**Important**: ALL reports should be saved to the `reports/` directory with descriptive names:
+
+**Implementation Reports:**
+- Phase validation: `PHASE_X_VALIDATION_REPORT.md`
+- Implementation summaries: `IMPLEMENTATION_SUMMARY_[FEATURE].md`
+- Feature completion: `FEATURE_[NAME]_REPORT.md`
+
+**Testing & Analysis Reports:**
+- Test results: `TEST_RESULTS_[DATE].md`
+- Coverage reports: `COVERAGE_REPORT_[DATE].md`
+- Performance analysis: `PERFORMANCE_ANALYSIS_[SCENARIO].md`
+- Security scans: `SECURITY_SCAN_[DATE].md`
+
+**Quality & Validation:**
+- Code quality: `CODE_QUALITY_REPORT.md`
+- Dependency analysis: `DEPENDENCY_REPORT.md`
+- API compatibility: `API_COMPATIBILITY_REPORT.md`
+
+**Report Naming Conventions:**
+- Use descriptive names: `[TYPE]_[SCOPE]_[DATE].md`
+- Include dates: `YYYY-MM-DD` format
+- Group with prefixes: `TEST_`, `PERFORMANCE_`, `SECURITY_`
+- Markdown format: All reports end in `.md`
+
+### Temporary Files & Debugging
+All temporary files, debugging scripts, and test artifacts should be organized in a `/temp` folder:
+
+**Temporary File Organization:**
+- **Debug scripts**: `temp/debug-*.js`, `temp/analyze-*.py`
+- **Test artifacts**: `temp/test-results/`, `temp/coverage/`
+- **Generated files**: `temp/generated/`, `temp/build-artifacts/`
+- **Logs**: `temp/logs/debug.log`, `temp/logs/error.log`
+
+**Guidelines:**
+- Never commit files from `/temp` directory
+- Use `/temp` for all debugging and analysis scripts created during development
+- Clean up `/temp` directory regularly or use automated cleanup
+- Include `/temp/` in `.gitignore` to prevent accidental commits
+
+### Example `.gitignore` patterns
+```
+# Temporary files and debugging
+/temp/
+temp/
+**/temp/
+debug-*.js
+test-*.py
+analyze-*.sh
+*-debug.*
+*.debug
+
+# Claude settings
+.claude/settings.local.json
+
+# Don't ignore reports directory
+!reports/
+!reports/**
+```
+
+### Claude Code Settings (.claude Directory)
+
+The `.claude` directory contains Claude Code configuration files with specific version control rules:
+
+#### Version Controlled Files (commit these):
+- `.claude/settings.json` - Shared team settings for hooks, tools, and environment
+- `.claude/commands/*.md` - Custom slash commands available to all team members
+- `.claude/hooks/*.sh` - Hook scripts for automated validations and actions
+
+#### Ignored Files (do NOT commit):
+- `.claude/settings.local.json` - Personal preferences and local overrides
+- Any `*.local.json` files - Personal configuration not meant for sharing
+
+**Important Notes:**
+- Claude Code automatically adds `.claude/settings.local.json` to `.gitignore`
+- The shared `settings.json` should contain team-wide standards (linting, type checking, etc.)
+- Personal preferences or experimental settings belong in `settings.local.json`
+- Hook scripts in `.claude/hooks/` should be executable (`chmod +x`)
+
+## Configuration
+
+[Environment setup and configuration management:]
+- Required environment variables
+- Configuration files and their purposes
+- Development environment setup
+- Dependencies and version requirements
+
+## Agent Delegation & Tool Execution
+
+### ⚠️ MANDATORY: Always Delegate to Specialists & Execute in Parallel
+
+**When specialized agents are available, you MUST use them instead of attempting tasks yourself.**
+
+**When performing multiple operations, send all tool calls (including Task calls for agent delegation) in a single message to execute them concurrently for optimal performance.**
+
+#### Why Agent Delegation Matters:
+- Specialists have deeper, more focused knowledge
+- They're aware of edge cases and subtle bugs  
+- They follow established patterns and best practices
+- They can provide more comprehensive solutions
+
+#### Key Principles:
+- **Agent Delegation**: Always check if a specialized agent exists for your task domain
+- **Complex Problems**: Delegate to domain experts, use diagnostic agents when scope is unclear
+- **Multiple Agents**: Send multiple Task tool calls in a single message to delegate to specialists in parallel
+- **DEFAULT TO PARALLEL**: Unless you have a specific reason why operations MUST be sequential (output of A required for input of B), always execute multiple tools simultaneously
+- **Plan Upfront**: Think "What information do I need to fully answer this question?" Then execute all searches together
+
+#### Discovering Available Agents:
+```bash
+# Quick check: List agents if claudekit is installed
+command -v claudekit >/dev/null 2>&1 && claudekit list agents || echo "claudekit not installed"
+
+# If claudekit is installed, you can explore available agents:
+claudekit list agents
+```
+
+#### Critical: Always Use Parallel Tool Calls
+
+**Err on the side of maximizing parallel tool calls rather than running sequentially.**
+
+**IMPORTANT: Send all tool calls in a single message to execute them in parallel.**
+
+**These cases MUST use parallel tool calls:**
+- Searching for different patterns (imports, usage, definitions)
+- Multiple grep searches with different regex patterns
+- Reading multiple files or searching different directories
+- Combining Glob with Grep for comprehensive results
+- Searching for multiple independent concepts with codebase_search_agent
+- Any information gathering where you know upfront what you're looking for
+- Agent delegations with multiple Task calls to different specialists
+
+**Sequential calls ONLY when:**
+You genuinely REQUIRE the output of one tool to determine the usage of the next tool.
+
+**Planning Approach:**
+1. Before making tool calls, think: "What information do I need to fully answer this question?"
+2. Send all tool calls in a single message to execute them in parallel
+3. Execute all those searches together rather than waiting for each result
+4. Most of the time, parallel tool calls can be used rather than sequential
+
+**Performance Impact:** Parallel tool execution is 3-5x faster than sequential calls, significantly improving user experience.
+
+**Remember:** This is not just an optimization—it's the expected behavior. Both delegation and parallel execution are requirements, not suggestions.
+```
+
+Think about what you'd tell a new team member on their first day. Include these key sections:
+
+1. **Project Overview** - Brief description of purpose and architecture
+2. **Build & Commands** - All development, testing, and deployment commands
+3. **Code Style** - Formatting rules, naming conventions, best practices
+4. **Testing** - Testing frameworks, conventions, execution guidelines
+5. **Security** - Security considerations and data protection
+6. **Configuration** - Environment setup and configuration management
+7. **Available AI Subagents** - Document relevant specialized agents for the project
+
+Additional sections based on project needs:
+- Architecture details for complex projects
+- API documentation
+- Database schemas
+- Deployment procedures
+- Contributing guidelines
+
+**Important:** 
+- Include content from any existing .cursorrules or copilot-instructions.md files
+- Focus on practical information that helps AI assistants write better code
+- Be specific and concrete based on actual code analysis
+
+### 4. Create Directory Structure
+Create the reports directory and documentation structure:
+
+```bash
+# Create reports directory
+mkdir -p reports
+
+# Create reports README template
+cat > reports/README.md << 'EOF'
+# Reports Directory
+
+This directory contains ALL project reports including validation, testing, analysis, performance benchmarks, and any other documentation generated during development.
+
+## Report Categories
+
+### Implementation Reports
+- Phase/milestone completion reports
+- Feature implementation summaries
+- Technical implementation details
+
+### Testing & Analysis Reports
+- Test execution results
+- Code coverage analysis
+- Performance test results
+- Security analysis reports
+
+### Quality & Validation
+- Code quality metrics
+- Dependency analysis
+- API compatibility reports
+- Build and deployment validation
+
+## Purpose
+
+These reports serve as:
+1. **Progress tracking** - Document completion of development phases
+2. **Quality assurance** - Validate implementations meet requirements
+3. **Knowledge preservation** - Capture decisions and findings
+4. **Audit trail** - Historical record of project evolution
+
+## Naming Conventions
+
+- Use descriptive names: `[TYPE]_[SCOPE]_[DATE].md`
+- Include dates: `YYYY-MM-DD` format
+- Group with prefixes: `TEST_`, `PERFORMANCE_`, `SECURITY_`
+- Markdown format: All reports end in `.md`
+
+## Version Control
+
+All reports are tracked in git to maintain historical records.
+EOF
+```
+
+### 5. Create Symlinks
+After creating AGENTS.md and directory structure, create symlinks for all AI assistants and document this in AGENTS.md:
+
+```bash
+# Claude Code
+ln -sf AGENTS.md CLAUDE.md
+
+# Cline
+ln -sf AGENTS.md .clinerules
+
+# Cursor
+ln -sf AGENTS.md .cursorrules
+
+# Windsurf
+ln -sf AGENTS.md .windsurfrules
+
+# Replit
+ln -sf AGENTS.md .replit.md
+
+# Gemini CLI, OpenAI Codex, OpenCode
+ln -sf AGENTS.md GEMINI.md
+
+# GitHub Copilot (needs directory)
+mkdir -p .github
+ln -sf ../AGENTS.md .github/copilot-instructions.md
+
+# Firebase Studio (needs directory)
+mkdir -p .idx
+ln -sf ../AGENTS.md .idx/airules.md
+```
+
+### 6. Show Results
+Display:
+- Created/updated AGENTS.md
+- Created reports directory structure
+- List of symlinks created
+- Key information included in the file
+- Suggest reviewing and customizing if needed
+
+**Important:** Make sure to add a note at the top of AGENTS.md documenting which files are symlinks to AGENTS.md. For example:
+```markdown
+**Note:** CLAUDE.md, .clinerules, .cursorrules, and other AI config files are symlinks to AGENTS.md in this project.
+```
+
--- a/.claude/commands/agents-md/migration.md
+++ b/.claude/commands/agents-md/migration.md
@@ -0,0 +1,175 @@
+---
+description: Migrate AI assistant configuration to AGENTS.md standard with universal compatibility
+category: claude-setup
+allowed-tools: Bash(mv:*), Bash(ln:*), Bash(ls:*), Bash(test:*), Bash(grep:*), Bash(echo:*), Read
+---
+
+# Convert to Universal AGENTS.md Format
+
+This command helps you adopt the AGENTS.md standard by converting your existing CLAUDE.md file and creating symlinks for compatibility with various AI assistants.
+
+## Current Project State
+!`ls -la CLAUDE.md AGENTS.md AGENT.md GEMINI.md .cursorrules .clinerules .windsurfrules .replit.md .github/copilot-instructions.md 2>/dev/null | grep -E "(CLAUDE|AGENT|AGENTS|GEMINI|cursor|cline|windsurf|replit|copilot)" || echo "Checking for AI configuration files..."`
+
+## Task
+
+Convert this project to use the AGENTS.md standard following these steps:
+
+### 1. Pre-flight Checks
+Check for existing AI configuration files:
+- CLAUDE.md (Claude Code)
+- .clinerules (Cline)
+- .cursorrules (Cursor)
+- .windsurfrules (Windsurf)
+- .replit.md (Replit)
+- .github/copilot-instructions.md (GitHub Copilot)
+- GEMINI.md (Gemini CLI)
+- AGENTS.md (if already exists)
+- AGENT.md (legacy, to be symlinked)
+
+### 2. Analyze Existing Files
+Check all AI config files and their content to determine migration strategy:
+
+**Priority order for analysis:**
+1. CLAUDE.md (Claude Code)
+2. .clinerules (Cline)
+3. .cursorrules (Cursor)
+4. .windsurfrules (Windsurf)
+5. .github/copilot-instructions.md (GitHub Copilot)
+6. .replit.md (Replit)
+7. GEMINI.md (Gemini CLI)
+
+**Content Analysis:**
+- Compare file sizes and content
+- Identify identical files (can be safely symlinked)
+- Detect different content (needs merging or user decision)
+
+### 3. Perform Smart Migration
+
+**Scenario A: Single file found**
+```bash
+# Simple case - move to AGENTS.md
+mv CLAUDE.md AGENTS.md  # or whichever file exists
+```
+
+**Scenario B: Multiple identical files**
+```bash
+# Keep the priority file, symlink others
+mv CLAUDE.md AGENTS.md
+ln -sf AGENTS.md .cursorrules  # if .cursorrules was identical
+```
+
+**Scenario C: Multiple files with different content**
+1. **Automatic merging** (when possible):
+   - Different sections can be combined
+   - No conflicting information
+   - Clear structure boundaries
+
+2. **User guidance** (when conflicts exist):
+   - Show content differences
+   - Provide merge recommendations
+   - Offer options:
+     - Keep primary file, backup others
+     - Manual merge with assistance
+     - Selective migration
+
+### 4. Handle Conflicts Intelligently
+
+**When conflicts detected:**
+1. **Display differences:**
+   ```
+   ⚠️  Multiple AI config files with different content found:
+   
+   📄 CLAUDE.md (1,234 bytes)
+   - Build commands: npm run build
+   - Testing: vitest
+   
+   📄 .cursorrules (856 bytes)  
+   - Code style: Prettier + ESLint
+   - TypeScript: strict mode
+   
+   📄 .github/copilot-instructions.md (567 bytes)
+   - Security guidelines
+   - No secrets in code
+   ```
+
+2. **Provide merge options:**
+   ```
+   Choose migration approach:
+   1. 🔄 Auto-merge (recommended) - Combine all unique content
+   2. 📋 Keep CLAUDE.md, backup others (.cursorrules.bak, copilot-instructions.md.bak)
+   3. 🎯 Selective - Choose which sections to include
+   4. 🛠️  Manual - Guide me through merging step-by-step
+   ```
+
+3. **Execute chosen strategy:**
+   - **Auto-merge**: Combine sections intelligently
+   - **Backup**: Keep primary, rename others with .bak extension
+   - **Selective**: Interactive selection of content blocks
+   - **Manual**: Step-by-step merge assistance
+
+### 5. Create AGENTS.md and Symlinks
+After handling content merging, create the final structure:
+```bash
+# Claude Code
+ln -s AGENTS.md CLAUDE.md
+
+# Cline
+ln -s AGENTS.md .clinerules
+
+# Cursor
+ln -s AGENTS.md .cursorrules
+
+# Windsurf
+ln -s AGENTS.md .windsurfrules
+
+# Replit
+ln -s AGENTS.md .replit.md
+
+# Gemini CLI, OpenAI Codex, OpenCode
+ln -s AGENTS.md GEMINI.md
+
+# Legacy AGENT.md symlink for backward compatibility
+ln -s AGENTS.md AGENT.md
+
+# GitHub Copilot (special case - needs directory)
+mkdir -p .github
+ln -s ../AGENTS.md .github/copilot-instructions.md
+
+# Firebase Studio (special case - needs .idx directory)
+mkdir -p .idx
+ln -s ../AGENTS.md .idx/airules.md
+```
+
+### 6. Verify Results
+- Use `ls -la` to show all created symlinks
+- Display which AI assistants are now configured
+- Show any backup files created (.bak extensions)
+- Confirm that AGENTS.md includes the symlink documentation note
+- Verify content completeness (all important sections included)
+
+### 7. Git Guidance
+If in a git repository:
+- Show git status (including new AGENTS.md and any .bak files)
+- Suggest adding AGENTS.md and symlinks to git
+- Recommend reviewing .bak files before deleting them
+- Remind to update .gitignore if needed (some teams ignore certain config files)
+
+### 8. Post-Migration Cleanup
+After successful migration and git commit:
+1. **Review backup files** (.bak extensions) to ensure nothing important was missed
+2. **Delete backup files** once satisfied with AGENTS.md content
+3. **Test with different AI assistants** to ensure all symlinks work correctly
+4. **Run `/agents-md:init`** if you want to add directory structure and latest best practices
+
+## Why AGENTS.md?
+
+AGENTS.md is becoming the standard for AI assistant configuration because:
+- Single source of truth for all AI tools
+- No more duplicating content across multiple files
+- Consistent experience across Claude Code, Cursor, Windsurf, and other tools
+- Future-proof as new AI tools emerge
+
+AGENTS.md emerged from collaborative efforts across the AI software development ecosystem, including OpenAI Codex, Amp, Jules from Google, Cursor, and Factory.
+
+Learn more at https://agents.md