Initial commit

2025-11-30 09:07:50 +08:00
commit 5ae7faad9c
8 changed files with 1567 additions and 0 deletions
--- a/commands/link-docs-to-claude.md
+++ b/commands/link-docs-to-claude.md
@@ -0,0 +1,430 @@
+---
+description: Link all documentation files to CLAUDE.md for better context availability
+allowed-tools:
+  - Bash
+  - Glob
+  - Grep
+  - Read
+  - Edit
+---
+
+# Link All Documentation to CLAUDE.md
+
+Ensure all documentation files in the repository are properly referenced in CLAUDE.md files for maximum context availability.
+
+## Instructions
+
+1. **Find all CLAUDE.md files in the repository**:
+   ```bash
+   find . -name "CLAUDE.md" -o -name "claude.md" | grep -v node_modules | grep -v .git
+   ```
+
+   - Identify the root CLAUDE.md (typically at repository root)
+   - Note any subdirectory CLAUDE.md files
+   - These will be the target files for adding documentation references
+
+2. **Inventory all markdown documentation files**:
+
+   Use the Glob tool to find all markdown files:
+   ```
+   pattern: "**/*.md"
+   ```
+
+   **Filter the results to exclude:**
+   - `node_modules/` directories
+   - `.git/` directories
+   - Hidden directories (`.*/`)
+   - The CLAUDE.md files themselves
+   - Common non-documentation files:
+     - `README.md` (usually already referenced)
+     - `CHANGELOG.md`
+     - `LICENSE.md`
+     - Package/build files
+
+   **Focus on documentation files like:**
+   - `docs/**/*.md`
+   - `documentation/**/*.md`
+   - Architecture documents
+   - API documentation
+   - How-to guides
+   - Technical specifications
+   - Any `.md` files in project subdirectories
+
+3. **For each documentation file found**:
+
+   a) **Read the file to understand its purpose**:
+      - Use the Read tool to examine the first 20-50 lines
+      - Identify the document's primary topic/purpose
+      - Note any key sections or headings
+
+   b) **Check if it's already referenced in any CLAUDE.md**:
+      - Use Grep to search all CLAUDE.md files for the document's path
+      - Search for both absolute and relative path references
+      - Check for variations (with/without leading `./`, etc.)
+      ```bash
+      # Example grep pattern
+      grep -r "path/to/doc.md" . --include="CLAUDE.md" --include="claude.md"
+      ```
+
+   c) **If NOT already referenced**:
+      - Mark this file as needing a reference
+      - Determine the best CLAUDE.md file to add it to (see step 4)
+
+4. **Determine the best CLAUDE.md file for each unreferenced doc**:
+
+   **Decision logic:**
+
+   - **Root CLAUDE.md**: Use for:
+     - Repository-wide documentation
+     - Architecture documents
+     - Top-level guides
+     - Cross-cutting concerns
+     - Docs in `docs/` or `documentation/` at root level
+
+   - **Subdirectory CLAUDE.md**: Use for:
+     - Documentation specific to that subdirectory's domain
+     - Component-specific guides
+     - Module-level technical docs
+     - When a CLAUDE.md exists in or near the doc's directory
+
+   **When in doubt**: Default to root CLAUDE.md for broader visibility.
+
+5. **Add references to the appropriate CLAUDE.md file(s)**:
+
+   a) **Read the target CLAUDE.md file** to understand its structure
+
+   b) **Find or create an appropriate section** for documentation references:
+      - Look for existing sections like:
+        - "## Documentation"
+        - "## Additional Resources"
+        - "## Reference Materials"
+        - "## Related Documentation"
+      - If none exist, create a new section near the end:
+        ```markdown
+        ## Related Documentation
+
+        Additional documentation files in this repository:
+        ```
+
+   c) **Add the reference with a brief context note**:
+      ```markdown
+      - [Relative/Path/To/Doc.md](Relative/Path/To/Doc.md) - Brief description of what this doc covers
+      ```
+
+   **Guidelines for the brief description:**
+   - One line, 5-15 words
+   - Describe the purpose or content
+   - Use active language
+   - Examples:
+     - "API endpoint specifications and request/response formats"
+     - "Database schema design and migration guide"
+     - "Component architecture and design patterns"
+     - "Deployment procedures and environment configuration"
+
+   d) **Use the Edit tool** to add the reference to the CLAUDE.md file
+      - Add to existing documentation section if present
+      - Maintain alphabetical or logical ordering
+      - Keep consistent formatting with existing references
+
+6. **Optimize documentation link hierarchy** (handle subdirectory CLAUDE.md files):
+
+   **Scenario**: A parent CLAUDE.md may contain links to documentation that would be more appropriately referenced in a newly created subdirectory CLAUDE.md file (closer to the relevant code).
+
+   a) **For each subdirectory CLAUDE.md file** (if any exist):
+
+      - Identify its directory path (e.g., `components/auth/CLAUDE.md`)
+      - Determine its "scope" (the subdirectory it covers)
+
+   b) **Review parent CLAUDE.md files for potentially misplaced references**:
+
+      - Read each parent CLAUDE.md (especially root CLAUDE.md)
+      - Examine all documentation references in the "Related Documentation" or similar sections
+
+   c) **Evaluate each reference for relocation**:
+
+      For each documentation link in a parent CLAUDE.md, check:
+
+      - **Is the referenced file within or closely related to a subdirectory that has its own CLAUDE.md?**
+
+        Example scenarios where relocation makes sense:
+        - Root CLAUDE.md links to `components/auth/README.md` → Move to `components/auth/CLAUDE.md`
+        - Root CLAUDE.md links to `services/api/endpoints.md` → Move to `services/CLAUDE.md` or `services/api/CLAUDE.md`
+        - `src/CLAUDE.md` links to `src/utils/helpers/guide.md` → Move to `src/utils/CLAUDE.md`
+
+      - **Would the reference provide more value at the lower level?**
+
+        Consider:
+        - Proximity to relevant code
+        - Specificity of the documentation (component-specific vs. project-wide)
+        - Whether the subdirectory CLAUDE.md is missing critical context
+
+      - **Should it remain at the parent level?**
+
+        Keep references in parent CLAUDE.md if:
+        - Documentation covers cross-cutting concerns
+        - File provides repository-wide context
+        - Documentation spans multiple subdirectories
+        - The doc is a top-level architecture/overview document
+
+   d) **Move references when appropriate**:
+
+      For references that should be relocated:
+
+      1. **Read the subdirectory CLAUDE.md** to understand its structure
+      2. **Add the reference** to the subdirectory CLAUDE.md:
+         - Adjust the relative path from the new location
+         - Place in appropriate section (create "## Related Documentation" if needed)
+         - Keep the same description or refine it for local context
+      3. **Remove the reference** from the parent CLAUDE.md:
+         - Use Edit tool to cleanly remove the line
+         - Preserve formatting and surrounding references
+         - Don't leave empty sections (remove section if last item)
+
+   e) **Document moved references**:
+
+      Keep track of relocations for the summary report:
+      ```
+      Moved references:
+      - docs/auth/oauth.md: CLAUDE.md → components/auth/CLAUDE.md
+      - services/api/endpoints.md: CLAUDE.md → services/CLAUDE.md
+      ```
+
+   **Important considerations**:
+   - Don't create duplicate references (check subdirectory CLAUDE.md first)
+   - Relative paths will change when moving between CLAUDE.md files
+   - When in doubt, leave the reference in the parent (no harm in redundancy)
+   - This is an optimization step—only move references when clearly beneficial
+
+7. **Group related documentation** (optional enhancement):
+
+   If multiple documentation files share a common theme or directory:
+   - Group them together in the CLAUDE.md
+   - Use subheadings or bullet point hierarchy
+   - Example:
+     ```markdown
+     ## Related Documentation
+
+     ### API Documentation
+     - [docs/api/endpoints.md](docs/api/endpoints.md) - REST API endpoint reference
+     - [docs/api/authentication.md](docs/api/authentication.md) - Auth flows and token management
+
+     ### Development Guides
+     - [docs/setup.md](docs/setup.md) - Local development environment setup
+     - [docs/testing.md](docs/testing.md) - Testing strategy and guidelines
+     ```
+
+8. **Link child CLAUDE.md files to parent CLAUDE.md files**:
+
+   **Purpose**: Create navigation links from parent CLAUDE.md files to child CLAUDE.md files for easy context discovery.
+
+   a) **Identify CLAUDE.md hierarchy**:
+      - From step 1, you have a list of all CLAUDE.md files
+      - Identify which is the root CLAUDE.md (typically `./CLAUDE.md`)
+      - Identify all subdirectory CLAUDE.md files (e.g., `./src/components/CLAUDE.md`)
+
+   b) **For the root CLAUDE.md** (and any parent CLAUDE.md files):
+
+      - **Find all child CLAUDE.md files**:
+        - Any CLAUDE.md file in a subdirectory relative to this parent
+        - Example: If parent is `./CLAUDE.md`, children include:
+          - `./src/components/design/CLAUDE.md`
+          - `./packages/api/CLAUDE.md`
+          - `./services/auth/CLAUDE.md`
+
+      - **Read each child CLAUDE.md to get context**:
+        - Read the first 5-10 lines of the child CLAUDE.md
+        - Extract the title (first `# Heading`) if present
+        - Infer purpose from title or path if no clear title
+
+      - **Check if child is already referenced**:
+        - Search parent CLAUDE.md for references to the child file path
+        - Look for existing "## Subdirectory Context Files" or similar section
+
+      - **Add or update the "Subdirectory Context Files" section**:
+
+        In the parent CLAUDE.md, find or create this section (typically after main content, before "Related Documentation"):
+
+        ```markdown
+        ## Subdirectory Context Files
+
+        Additional CLAUDE.md files in subdirectories provide focused context for specific areas:
+
+        - [src/components/design/CLAUDE.md](src/components/design/CLAUDE.md) - Design system components
+        - [packages/api/CLAUDE.md](packages/api/CLAUDE.md) - Backend API service
+        - [services/auth/CLAUDE.md](services/auth/CLAUDE.md) - Authentication service
+        ```
+
+        **Guidelines for child CLAUDE.md descriptions**:
+        - Use the title from the child file if available
+        - Or describe the subdirectory's purpose (e.g., "Backend API service", "Design system components")
+        - Keep descriptions brief (3-8 words)
+        - Focus on what that area contains or does
+
+      - **Use relative paths**:
+        - All paths should be relative to the parent CLAUDE.md location
+        - Example: Root `./CLAUDE.md` → child `./src/auth/CLAUDE.md` = link path `src/auth/CLAUDE.md`
+
+      - **Use Edit tool to add the section**:
+        - If section doesn't exist, add it before "## Related Documentation"
+        - If section exists, add missing child references
+        - Keep links alphabetically sorted or grouped logically by area
+        - Don't duplicate existing references
+
+   c) **Handle nested hierarchies** (if applicable):
+
+      - If a subdirectory CLAUDE.md also has children (e.g., `src/CLAUDE.md` and `src/components/CLAUDE.md`):
+        - Link `./CLAUDE.md` → `src/CLAUDE.md` (child)
+        - Link `src/CLAUDE.md` → `src/components/CLAUDE.md` (grandchild)
+        - Each parent only links to its direct children, not grandchildren
+
+      - This creates a natural navigation hierarchy:
+        ```
+        ./CLAUDE.md
+        └── links to: src/CLAUDE.md, packages/CLAUDE.md
+
+        src/CLAUDE.md
+        └── links to: src/components/CLAUDE.md, src/utils/CLAUDE.md
+        ```
+
+   d) **Track child CLAUDE.md links for reporting**:
+
+      Keep count of:
+      - Child CLAUDE.md files found
+      - Child CLAUDE.md links already present
+      - New child CLAUDE.md links added
+      - Which parent files were updated
+
+9. **Report results to the user**:
+
+   Provide a summary:
+   ```
+   📚 Documentation Linking Complete!
+
+   Total markdown files found: X
+   Already referenced in CLAUDE.md: Y
+   Newly added references: Z
+   References relocated: M
+
+   Child CLAUDE.md files:
+   - Total child CLAUDE.md files found: N
+   - Child CLAUDE.md links added: P
+
+   Updated files:
+   - CLAUDE.md (+Z references, -M moved, +P child CLAUDE.md links)
+   - path/to/subdirectory/CLAUDE.md (+N references, +M moved in)
+
+   New references added:
+   - docs/api/endpoints.md → CLAUDE.md
+   - docs/setup.md → CLAUDE.md
+   - components/auth/README.md → components/CLAUDE.md
+
+   References relocated for better hierarchy:
+   - components/auth/oauth-guide.md: CLAUDE.md → components/auth/CLAUDE.md
+   - services/api/endpoints.md: CLAUDE.md → services/CLAUDE.md
+
+   Child CLAUDE.md links added:
+   - src/components/design/CLAUDE.md → CLAUDE.md
+   - packages/api/CLAUDE.md → CLAUDE.md
+   ```
+
+10. **Suggest next steps**:
+   - "Review the added references for accuracy"
+   - "Consider updating the brief descriptions if needed"
+   - "Run this command periodically to catch new documentation"
+
+## Important Guidelines
+
+### What to Reference
+- ✅ Technical documentation files
+- ✅ Architecture and design docs
+- ✅ API specifications
+- ✅ How-to guides and tutorials
+- ✅ Developer onboarding docs
+- ✅ Configuration references
+
+### What to Skip
+- ❌ CLAUDE.md files in "Related Documentation" sections (but DO link them in "Subdirectory Context Files")
+- ❌ README.md at root (usually already referenced or primary doc)
+- ❌ CHANGELOG.md (version history, not context)
+- ❌ LICENSE.md (legal, not development context)
+- ❌ node_modules/ and vendor directories
+- ❌ Build output or generated files
+- ❌ Package manager files (package.json, etc.)
+
+### Reference Format
+- Always use relative paths from the CLAUDE.md location
+- Use markdown link syntax: `[display text](path/to/file.md)`
+- Include brief, helpful descriptions
+- Maintain consistent formatting with existing references
+
+### Best Practices
+- Group related documentation together
+- Use clear section headers
+- Keep descriptions concise but informative
+- Alphabetize or logically order references
+- Use Edit tool to maintain file formatting
+- Don't duplicate references (check first!)
+
+## Error Handling
+
+| Issue | Solution |
+|-------|----------|
+| No CLAUDE.md found | Create one at root with basic structure |
+| CLAUDE.md has no documentation section | Create "## Related Documentation" section |
+| Ambiguous best location | Default to root CLAUDE.md, note in description |
+| File already referenced | Skip, note in summary |
+| Circular reference risk | Never reference CLAUDE.md in itself |
+| Binary or non-text .md files | Skip after read attempt fails |
+
+## Example Output Structure
+
+For a root CLAUDE.md file after running this command:
+
+```markdown
+# Project Name
+
+Project overview and instructions...
+
+## Repository Structure
+
+...existing content...
+
+## Subdirectory Context Files
+
+Additional CLAUDE.md files in subdirectories provide focused context for specific areas:
+
+- [src/components/design/CLAUDE.md](src/components/design/CLAUDE.md) - Design system components
+- [packages/api/CLAUDE.md](packages/api/CLAUDE.md) - Backend API service
+- [services/auth/CLAUDE.md](services/auth/CLAUDE.md) - Authentication service
+
+## Related Documentation
+
+Additional documentation files in this repository:
+
+- [docs/api/endpoints.md](docs/api/endpoints.md) - REST API endpoint specifications
+- [docs/api/authentication.md](docs/api/authentication.md) - OAuth2 authentication flow
+- [docs/architecture/database.md](docs/architecture/database.md) - Database schema and design patterns
+- [docs/deployment.md](docs/deployment.md) - Production deployment procedures
+- [docs/setup.md](docs/setup.md) - Local development environment setup
+- [docs/testing.md](docs/testing.md) - Testing strategy and CI/CD integration
+```
+
+## Definition of Done
+
+- [ ] All CLAUDE.md files identified
+- [ ] All markdown documentation files inventoried
+- [ ] Each doc checked for existing references
+- [ ] Unreferenced docs identified
+- [ ] Best CLAUDE.md target determined for each unreferenced doc
+- [ ] References added with appropriate brief descriptions
+- [ ] Documentation link hierarchy optimized (references moved to subdirectory CLAUDE.md files where appropriate)
+- [ ] Relative paths updated correctly for any moved references
+- [ ] Child CLAUDE.md files identified and hierarchy established
+- [ ] Parent CLAUDE.md files updated with "Subdirectory Context Files" section
+- [ ] All child CLAUDE.md files linked from appropriate parent CLAUDE.md files
+- [ ] Child CLAUDE.md descriptions extracted or inferred
+- [ ] CLAUDE.md files updated using Edit tool
+- [ ] Summary report provided to user (including child CLAUDE.md links)
+- [ ] No duplicate references created
+- [ ] No circular references created
+- [ ] User informed of next steps
--- a/commands/plan-claude-md.md
+++ b/commands/plan-claude-md.md
@@ -0,0 +1,552 @@
+---
+description: Analyze repository structure and recommend optimal CLAUDE.md placement strategy
+allowed-tools:
+  - Bash
+  - Glob
+  - Grep
+  - Read
+  - Write
+---
+
+# Plan CLAUDE.md Strategy
+
+Analyze the repository structure and recommend optimal CLAUDE.md file placement for context management. Determine whether a single root CLAUDE.md is sufficient or if multiple strategically-placed files would improve Claude Code's effectiveness.
+
+## Instructions
+
+### Phase 1: Repository Analysis
+
+1. **Understand the repository structure at a high level**:
+
+   a) **Get directory structure overview**:
+   ```bash
+   tree -L 3 -d -I 'node_modules|.git|dist|build|coverage|.next|.nuxt|vendor' | head -100
+   ```
+
+   b) **Identify repository type and scale**:
+   - Is this a monorepo? (Look for `packages/`, `apps/`, `services/`, workspaces)
+   - Is this a large library? (Check for multiple major modules/components)
+   - Is this a standard single-app repo?
+   - Count total directories: `find . -type d | grep -v node_modules | grep -v .git | wc -l`
+   - Estimate codebase size: `find . -type f \( -name "*.js" -o -name "*.ts" -o -name "*.py" -o -name "*.go" -o -name "*.java" -o -name "*.rb" -o -name "*.php" \) | grep -v node_modules | wc -l`
+
+2. **Identify major architectural boundaries**:
+
+   a) **Scan for monorepo indicators**:
+   - Look for `packages/`, `apps/`, `services/`, `modules/`, `libs/` directories
+   - Check for workspace files: `package.json` (workspaces), `pnpm-workspace.yaml`, `lerna.json`, `nx.json`
+   - Read these files to understand workspace structure
+
+   b) **Identify distinct domains/modules**:
+   - Use Glob to find top-level source directories: `src/**/`, `lib/**/`, `components/**/`, etc.
+   - Look for clear separation of concerns (frontend/backend, api/web, services/core)
+   - Identify independent subsystems that could be developed separately
+
+   c) **Assess component independence**:
+   - Can developers work on one area without needing context from others?
+   - Are there clear boundaries between domains?
+   - Do subdirectories have their own dependencies/configs? (e.g., separate package.json files)
+
+3. **Analyze existing documentation patterns**:
+
+   a) **Find existing CLAUDE.md files**:
+   ```bash
+   find . -name "CLAUDE.md" -o -name "claude.md" | grep -v node_modules
+   ```
+
+   b) **Find README files throughout the repo**:
+   ```bash
+   find . -name "README.md" | grep -v node_modules | head -20
+   ```
+
+   c) **Identify documentation concentrations**:
+   - Are there subdirectories with substantial documentation already?
+   - Do subdirectories have their own docs/ folders?
+   - Read a few README files to understand local context needs
+
+4. **Assess workflow patterns**:
+
+   a) **Check for independent build/test configurations**:
+   - Multiple `package.json`, `Cargo.toml`, `go.mod`, `pom.xml` files
+   - Separate CI/CD configs per directory
+   - Independent deployment configs
+
+   b) **Evaluate development isolation**:
+   - Would a developer working in `services/auth/` need constant context from `services/payments/`?
+   - Are there teams that own specific parts of the codebase?
+
+### Phase 2: Decision Analysis
+
+5. **Apply decision criteria**:
+
+   **Single CLAUDE.md is sufficient when:**
+   - ✅ Small to medium codebase (<500 files, <50 directories)
+   - ✅ Single unified application with tight coupling
+   - ✅ No clear architectural boundaries
+   - ✅ All code shares common context and patterns
+   - ✅ Simple project structure (e.g., typical web app)
+   - ✅ Developers need full repository context for most tasks
+
+   **Multiple CLAUDE.md files are beneficial when:**
+   - 📂 **Monorepo**: Multiple packages/apps with independent lifecycles
+   - 📂 **Large library**: Distinct modules that can be understood independently
+   - 📂 **Microservices**: Separate services with different tech stacks/patterns
+   - 📂 **Domain boundaries**: Clear DDD-style bounded contexts
+   - 📂 **Team ownership**: Different teams own different parts
+   - 📂 **Scale**: >1000 files or >100 directories
+   - 📂 **Context overload**: Root CLAUDE.md would be >500 lines to cover everything
+   - 📂 **Independent workflows**: Subdirectories have own build/test/deploy cycles
+
+6. **Determine recommendation**:
+
+   Based on the analysis, decide:
+   - **Option A**: Single root CLAUDE.md is optimal
+   - **Option B**: Multiple CLAUDE.md files recommended with specific locations
+
+### Phase 3: Recommendations
+
+7. **For Option A (Single CLAUDE.md):**
+
+   Inform the user:
+   ```
+   📋 CLAUDE.md Strategy Recommendation: Single File
+
+   Analysis Results:
+   - Repository type: [standard app / small library / etc.]
+   - Total files: [count]
+   - Architectural complexity: [low / moderate]
+
+   ✅ Recommendation: A single CLAUDE.md at the repository root is sufficient.
+
+   Reasoning:
+   - [List 2-3 key reasons based on analysis]
+   - [e.g., "Codebase is tightly coupled with shared context"]
+   - [e.g., "No clear architectural boundaries found"]
+
+   Next Steps:
+   1. Ensure root CLAUDE.md exists and is comprehensive
+   2. Run `/link-docs-to-claude` to ensure all docs are referenced
+   3. Keep CLAUDE.md updated as the project evolves
+   ```
+
+8. **For Option B (Multiple CLAUDE.md files):**
+
+   a) **Identify specific locations for CLAUDE.md files**:
+
+   For each recommended location, provide:
+   - **Path**: Exact directory path (e.g., `packages/web-app/`)
+   - **Scope**: What this CLAUDE.md would cover
+   - **Rationale**: Why this location benefits from dedicated context
+   - **Key topics**: What should be documented here
+
+   Example structure:
+   ```
+   Recommended CLAUDE.md locations:
+
+   1. 📍 packages/web-app/CLAUDE.md
+      Scope: Frontend web application
+      Rationale: Independent React app with own build pipeline
+      Key topics: Component architecture, routing, state management
+
+   2. 📍 packages/api/CLAUDE.md
+      Scope: Backend API service
+      Rationale: Separate Express.js service with own deployment
+      Key topics: API endpoints, authentication, database models
+
+   3. 📍 packages/shared/CLAUDE.md
+      Scope: Shared utilities and types
+      Rationale: Common code used across packages
+      Key topics: Utility functions, TypeScript types, constants
+   ```
+
+   b) **Create a detailed recommendation report**:
+
+   ```markdown
+   📋 CLAUDE.md Strategy Recommendation: Multi-File Approach
+
+   ## Analysis Results
+
+   - Repository type: [monorepo / large library / microservices]
+   - Total files: [count]
+   - Total directories: [count]
+   - Architectural complexity: [high / very high]
+   - Major subsystems identified: [count]
+
+   ## Assessment
+
+   ✅ Recommendation: Multiple CLAUDE.md files recommended
+
+   ### Why Multiple Files?
+   - [List 3-5 key findings from analysis]
+   - [e.g., "Monorepo with 5 independent packages"]
+   - [e.g., "Clear domain boundaries between services"]
+   - [e.g., "Each package has own dependencies and workflows"]
+   - [e.g., "Root CLAUDE.md would exceed 800 lines to cover all context"]
+
+   ### Proposed Structure
+
+   Root: ./CLAUDE.md
+   ├── Purpose: Repository overview, monorepo patterns, cross-cutting concerns
+   ├── Content: Workspace structure, shared tooling, contribution guidelines
+   └── Scope: High-level architecture and repository navigation
+
+   [For each recommended location]:
+   Location: [path]
+   ├── Purpose: [Brief description]
+   ├── Rationale: [Why this location needs dedicated context]
+   ├── Scope: [What code/domains it covers]
+   └── Key Topics to Document:
+       • [Topic 1]
+       • [Topic 2]
+       • [Topic 3]
+
+   ## Implementation Guide
+
+   ### Standard CLAUDE.md Template Structure
+
+   Each CLAUDE.md file should include these standard sections:
+
+   ```markdown
+   # [Module/Package Name]
+
+   [Brief description]
+
+   ## Purpose
+   [What this code does and why it exists]
+
+   ## Architecture
+   [Key patterns, frameworks, and structure]
+
+   ## Key Concepts
+   [Domain-specific concepts and terminology]
+
+   ## Development Workflow
+   [How to build, test, run this code]
+
+   ## Related Documentation
+   [Links to relevant docs - populated by /link-docs-to-claude]
+
+   ## Integration Points
+   [How this integrates with other parts]
+   ```
+
+   ### Implementation Steps
+
+   For each recommended CLAUDE.md location, use Claude Code's "!" bash mode to navigate and initialize:
+
+   **Process:**
+   1. Navigate to the directory: `!cd path/to/directory`
+   2. Run the init command: `/init`
+   3. Repeat for each recommended location
+
+   **Recommended initialization order:**
+   1. Start with root directory: `!cd ./` then `/init`
+   2. Initialize each subdirectory in order listed above
+   3. After all files created, run `/link-docs-to-claude` from root
+
+   ## Maintenance Guidelines
+
+   - Keep each CLAUDE.md focused on its specific domain
+   - Avoid duplicating information across files
+   - Root CLAUDE.md provides navigation and overview
+   - Subdirectory CLAUDE.md files provide deep context
+   - Update CLAUDE.md files when architecture changes
+   - Run `/link-docs-to-claude` periodically to maintain doc references
+
+   ## Expected Benefits
+
+   ✅ **Reduced context overload**: Claude Code loads only relevant context
+   ✅ **Faster comprehension**: Focused documentation for specific areas
+   ✅ **Better scalability**: Documentation grows with codebase structure
+   ✅ **Team alignment**: Clear ownership and documentation boundaries
+   ✅ **Improved accuracy**: Context matches developer mental models
+   ```
+
+9. **Provide initialization checklist (if multiple files recommended)**:
+
+   Create a simple checklist for the user to follow:
+
+   ```markdown
+   ## CLAUDE.md Initialization Checklist
+
+   For each location below, use "!" bash mode to navigate and initialize:
+
+   ### Root Directory
+   - [ ] `!cd ./`
+   - [ ] `/init`
+
+   ### Subdirectories
+   - [ ] `!cd packages/web-app/`
+   - [ ] `/init`
+
+   - [ ] `!cd packages/api/`
+   - [ ] `/init`
+
+   - [ ] `!cd packages/shared/`
+   - [ ] `/init`
+
+   [Continue for each recommended location...]
+
+   ### Final Step
+   - [ ] Return to root: `!cd ./`
+   - [ ] Link documentation: `/link-docs-to-claude`
+   ```
+
+   Customize the checklist with the actual recommended paths from your analysis.
+
+### Phase 4: Validation and Summary
+
+10. **Validate recommendations**:
+
+   - Do the recommended locations align with actual architectural boundaries?
+   - Are there any edge cases or special considerations?
+   - Would this strategy scale with likely repository growth?
+
+11. **Provide final summary**:
+
+   Recap the recommendation with:
+   - Clear decision (single vs. multiple)
+   - Number of files recommended (if multiple)
+   - Estimated effort to implement
+   - Expected benefits
+   - Any caveats or considerations
+
+## Decision Logic Reference
+
+### Indicators for Single CLAUDE.md
+
+| Indicator | Description |
+|-----------|-------------|
+| Small scale | <500 files, <50 directories |
+| Tight coupling | No clear separation between modules |
+| Single app | Standard web app, CLI tool, or small library |
+| Shared context | All code needs similar background knowledge |
+| Simple structure | Flat or shallow directory hierarchy |
+
+### Indicators for Multiple CLAUDE.md Files
+
+| Indicator | Description |
+|-----------|-------------|
+| Monorepo | Multiple packages/apps/services |
+| Large scale | >1000 files or >100 directories |
+| Domain boundaries | Clear DDD-style bounded contexts |
+| Team ownership | Different teams own different areas |
+| Independent workflows | Separate build/test/deploy per area |
+| Tech diversity | Different tech stacks in different areas |
+| Context overload | Single file would be >500 lines |
+| Documentation concentration | Subdirectories have substantial local docs |
+
+### Recommended CLAUDE.md Placement Patterns
+
+**Monorepo Pattern:**
+```
+./CLAUDE.md (overview, workspace structure)
+./packages/*/CLAUDE.md (per-package context)
+```
+
+**Microservices Pattern:**
+```
+./CLAUDE.md (architecture overview)
+./services/*/CLAUDE.md (per-service context)
+```
+
+**Large Library Pattern:**
+```
+./CLAUDE.md (library overview, getting started)
+./src/*/CLAUDE.md (per-major-module context)
+```
+
+**Full-Stack Pattern:**
+```
+./CLAUDE.md (project overview)
+./frontend/CLAUDE.md (frontend-specific)
+./backend/CLAUDE.md (backend-specific)
+```
+
+## Important Guidelines
+
+### Analysis Best Practices
+
+- **Be thorough**: Don't rush the analysis phase
+- **Look for patterns**: Identify recurring structures
+- **Consider growth**: Think about how the repo will evolve
+- **Validate boundaries**: Ensure recommended locations make sense
+- **Think like a developer**: Where would context be most useful?
+
+### Recommendation Best Practices
+
+- **Be specific**: Provide exact paths, not vague suggestions
+- **Explain rationale**: Help users understand the "why"
+- **Provide templates**: Make implementation easy
+- **Consider maintenance**: Recommend sustainable patterns
+- **Balance granularity**: Not too few, not too many files
+
+### Communication Best Practices
+
+- **Be clear and decisive**: Don't hedge unnecessarily
+- **Provide actionable steps**: Make it easy to implement
+- **Show your work**: Explain how you reached conclusions
+- **Use visual formatting**: Make recommendations scannable
+- **Offer alternatives**: Note when single vs. multiple is borderline
+
+## Error Handling
+
+| Issue | Solution |
+|-------|----------|
+| Cannot determine structure | Use `tree` and `find` commands to explore |
+| Ambiguous boundaries | Err on side of fewer files, note uncertainty |
+| No clear monorepo structure | Check for workspace configs, separate package.json files |
+| Very flat structure | Likely single CLAUDE.md is best |
+| Extremely large repo | May need >10 CLAUDE.md files, group by major domains |
+
+## Example Outputs
+
+### Example 1: Small Project (Single File)
+
+```
+📋 CLAUDE.md Strategy Recommendation: Single File
+
+Analysis Results:
+- Repository type: Standard web application
+- Total files: 234
+- Total directories: 28
+- Architectural complexity: Low
+
+✅ Recommendation: A single CLAUDE.md at the repository root is sufficient.
+
+Reasoning:
+- Small, tightly-coupled codebase with shared patterns
+- No clear architectural boundaries between components
+- All developers need full context for most tasks
+- Current structure is simple and well-organized
+
+Next Steps:
+1. Ensure root CLAUDE.md exists and covers key patterns
+2. Run `/link-docs-to-claude` to reference all docs
+3. Keep CLAUDE.md updated as project grows
+```
+
+### Example 2: Monorepo (Multiple Files)
+
+```
+📋 CLAUDE.md Strategy Recommendation: Multi-File Approach
+
+Analysis Results:
+- Repository type: Monorepo (Turborepo workspace)
+- Total files: 2,847
+- Total directories: 312
+- Architectural complexity: High
+- Major subsystems identified: 5 packages
+
+✅ Recommendation: Multiple CLAUDE.md files (6 total)
+
+Why Multiple Files?
+- Monorepo with 5 independent packages (web, api, mobile, admin, shared)
+- Each package has own dependencies, build config, and team ownership
+- Different tech stacks (React, Node.js, React Native)
+- Root CLAUDE.md would need 1000+ lines to cover everything
+- Developers typically work within single package boundaries
+
+Proposed Structure:
+
+Root: ./CLAUDE.md
+├── Purpose: Monorepo overview, tooling, workspace management
+├── Content: Turborepo config, shared scripts, CI/CD, contribution guide
+└── Scope: Cross-package patterns and repository navigation
+
+Location: apps/web/CLAUDE.md
+├── Purpose: Customer-facing web application
+├── Rationale: Independent Next.js app with own deployment pipeline
+├── Scope: Frontend components, pages, routing, state management
+└── Key Topics:
+    • Next.js app router patterns
+    • Component architecture and design system
+    • API integration with backend
+    • Authentication and user flows
+
+Location: apps/api/CLAUDE.md
+├── Purpose: Backend API service
+├── Rationale: Separate Express.js service with own database
+├── Scope: REST endpoints, business logic, database models
+└── Key Topics:
+    • API endpoint structure and patterns
+    • Database schema and migrations
+    • Authentication/authorization
+    • Background jobs and queues
+
+Location: apps/mobile/CLAUDE.md
+├── Purpose: Mobile application
+├── Rationale: React Native app with platform-specific patterns
+├── Scope: Mobile screens, navigation, native modules
+└── Key Topics:
+    • React Native patterns
+    • Native module integration
+    • Push notifications
+    • App store deployment
+
+Location: apps/admin/CLAUDE.md
+├── Purpose: Admin dashboard
+├── Rationale: Separate React app for internal users
+├── Scope: Admin UI, data management, analytics
+└── Key Topics:
+    • Admin component patterns
+    • Data tables and forms
+    • User management
+    • Reporting features
+
+Location: packages/shared/CLAUDE.md
+├── Purpose: Shared code library
+├── Rationale: Common utilities and types used across apps
+├── Scope: Utility functions, TypeScript types, constants, UI components
+└── Key Topics:
+    • Shared TypeScript types
+    • Utility function library
+    • Shared UI components
+    • Configuration constants
+
+## CLAUDE.md Initialization Checklist
+
+For each location below, use "!" bash mode to navigate and initialize:
+
+### Root Directory
+- [ ] `!cd ./`
+- [ ] `/init`
+
+### Subdirectories
+- [ ] `!cd apps/web/`
+- [ ] `/init`
+
+- [ ] `!cd apps/api/`
+- [ ] `/init`
+
+- [ ] `!cd apps/mobile/`
+- [ ] `/init`
+
+- [ ] `!cd apps/admin/`
+- [ ] `/init`
+
+- [ ] `!cd packages/shared/`
+- [ ] `/init`
+
+### Final Step
+- [ ] Return to root: `!cd ./`
+- [ ] Link documentation: `/link-docs-to-claude`
+```
+
+## Definition of Done
+
+- [ ] Repository structure analyzed comprehensively
+- [ ] Repository type identified (monorepo, library, standard app, etc.)
+- [ ] Scale metrics gathered (file count, directory count)
+- [ ] Architectural boundaries identified
+- [ ] Existing documentation patterns assessed
+- [ ] Workflow patterns evaluated
+- [ ] Decision criteria applied systematically
+- [ ] Clear recommendation made (single vs. multiple)
+- [ ] Specific locations identified (if multiple recommended)
+- [ ] Rationale provided for each recommended location
+- [ ] Implementation guide created (templates, steps, or script)
+- [ ] Expected benefits communicated
+- [ ] User provided with actionable next steps
+- [ ] Validation performed on recommendations
+- [ ] Final summary delivered clearly
--- a/commands/sync-agents-md.md
+++ b/commands/sync-agents-md.md
@@ -0,0 +1,254 @@
+---
+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