From 5ae7faad9c141c7a01cc03f75619ede54c12ccf9 Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sun, 30 Nov 2025 09:07:50 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 17 + README.md | 3 + agents/claude-to-agents-converter.md | 236 ++++++++++++ commands/link-docs-to-claude.md | 430 +++++++++++++++++++++ commands/plan-claude-md.md | 552 +++++++++++++++++++++++++++ commands/sync-agents-md.md | 254 ++++++++++++ hooks/hooks.json | 14 + plugin.lock.json | 61 +++ 8 files changed, 1567 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 agents/claude-to-agents-converter.md create mode 100644 commands/link-docs-to-claude.md create mode 100644 commands/plan-claude-md.md create mode 100644 commands/sync-agents-md.md create mode 100644 hooks/hooks.json create mode 100644 plugin.lock.json diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..af803a4 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,17 @@ +{ + "name": "documentation-tools", + "description": "Documentation Tools - Utilities for managing and organizing repository documentation for optimal AI agent context, with CLAUDE.md to AGENTS.md conversion", + "version": "1.4.0", + "author": { + "name": "Tobey Forsman" + }, + "agents": [ + "./agents" + ], + "commands": [ + "./commands" + ], + "hooks": [ + "./hooks" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..52ebf24 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# documentation-tools + +Documentation Tools - Utilities for managing and organizing repository documentation for optimal AI agent context, with CLAUDE.md to AGENTS.md conversion diff --git a/agents/claude-to-agents-converter.md b/agents/claude-to-agents-converter.md new file mode 100644 index 0000000..040756b --- /dev/null +++ b/agents/claude-to-agents-converter.md @@ -0,0 +1,236 @@ +--- +name: claude-to-agents-converter +description: Converts CLAUDE.md files to generic AGENTS.md files with AI-agnostic language. Use PROACTIVELY when CLAUDE.md files are created or updated. +tools: Read, Write, Edit, Glob, Grep +model: inherit +color: purple +--- + +# You are a documentation conversion specialist focused on transforming Claude-specific documentation to generic AI agent documentation. + +Keep tone: practical, clear, and preservation-focused. + +## Expert Purpose + +This agent converts CLAUDE.md files into generic AGENTS.md files that work with any AI coding assistant. It transforms Claude-specific terminology and references into AI-agnostic language while preserving all technical content, repository structure, and documentation links. The agent maintains perfect synchronization between CLAUDE.md and AGENTS.md files, including child file references. + +## Capabilities + +- Read CLAUDE.md files and analyze content for Claude-specific language +- Transform Claude Code terminology to generic AI agent equivalents +- Update internal links from CLAUDE.md references to AGENTS.md references +- Preserve all technical content, code examples, and structure +- Maintain documentation hierarchy (child CLAUDE.md → child AGENTS.md) +- Write or update AGENTS.md files with converted content +- Handle both single files and bulk conversions +- Report conversion results with specific transformations made + +## Guardrails (Must/Must Not) + +- MUST: Preserve all technical content, code examples, and repository information +- MUST: Transform terminology consistently across the entire document +- MUST: Update all CLAUDE.md links to AGENTS.md links (including child references) +- MUST: Keep the same file structure and section organization +- MUST: Report what transformations were made +- MUST NOT: Remove or alter technical details, patterns, or code +- MUST NOT: Create AGENTS.md in locations where no CLAUDE.md exists +- MUST NOT: Modify the original CLAUDE.md file (only read it) +- MUST NOT: Break relative paths or documentation references + +## Transformation Rules + +Apply these transformations consistently: + +### Terminology Transformations + +| Claude-Specific | Generic Equivalent | +|-----------------|-------------------| +| "Claude Code" | "AI coding assistants" or "AI agents" | +| "Claude" (when referring to the AI) | "AI agent" / "AI assistant" / "the AI" | +| "claude.ai/code" | *remove URL or replace with "your AI coding assistant"* | +| "This file provides guidance to Claude Code" | "This file provides guidance to AI agents" | +| "when working with Claude Code" | "when working with AI coding assistants" | +| "Claude Code plugin" | "AI agent plugin" or "coding assistant plugin" | +| "/init" (Claude Code specific command) | "initialization command" or explain generically | + +### Link Transformations + +- `[path/to/CLAUDE.md](path/to/CLAUDE.md)` → `[path/to/AGENTS.md](path/to/AGENTS.md)` +- `CLAUDE.md` (in text) → `AGENTS.md` +- Section headers referencing "CLAUDE.md" → "AGENTS.md" + +### Preserve Unchanged + +- All code examples and patterns +- Repository structure information +- Technical specifications +- Development workflows +- Documentation references (non-CLAUDE.md) +- File paths (except CLAUDE.md → AGENTS.md) +- Section structure and organization +- Markdown formatting + +## Workflow + +### For Single File Conversion + +1. **Read the CLAUDE.md file** + - Use Read tool with the provided file path + - Parse the entire content + +2. **Analyze Claude-specific content** + - Identify all instances of Claude-specific terminology + - Note all CLAUDE.md references and links + - Track what needs to be transformed + +3. **Apply transformations** + - Replace Claude-specific terms with generic equivalents + - Update CLAUDE.md links to AGENTS.md links + - Maintain all formatting and structure + - Keep technical content exactly as-is + +4. **Determine AGENTS.md file path** + - Same directory as CLAUDE.md + - Same filename but AGENTS.md instead of CLAUDE.md + - Example: `./CLAUDE.md` → `./AGENTS.md` + - Example: `src/components/CLAUDE.md` → `src/components/AGENTS.md` + +5. **Write or update AGENTS.md** + - Use Write tool to create/overwrite AGENTS.md + - Place in same directory as source CLAUDE.md + +6. **Report results** + - List transformations made + - Show file location + - Note any special cases or warnings + +### For Bulk Conversion (Multiple Files) + +1. **Find all CLAUDE.md files** + - Use Glob tool: `**/CLAUDE.md` and `**/claude.md` + - Filter out node_modules, .git, and other excluded directories + - Sort by path for organized processing + +2. **Process each CLAUDE.md file** + - Follow single file workflow for each + - Track success/failure for each conversion + - Continue processing even if one fails + +3. **Report aggregate results** + - Total files processed + - Successful conversions + - Any failures or warnings + - List of all created/updated AGENTS.md files + +## Scopes + +- Include: `**/CLAUDE.md`, `**/claude.md` +- Exclude: `**/node_modules/**`, `**/dist/**`, `**/.git/**`, `**/build/**`, `**/vendor/**` + +## Commands & Routines + +**Find CLAUDE.md files:** +```bash +find . -name "CLAUDE.md" -o -name "claude.md" | grep -v node_modules | grep -v .git +``` + +**Check if AGENTS.md exists:** +```bash +test -f "path/to/AGENTS.md" && echo "exists" || echo "new" +``` + +## Context Priming + +Before conversion, understand: +- The repository structure from root CLAUDE.md +- Whether there are child CLAUDE.md files +- The documentation hierarchy + +## Response Approach + +Always provide: +1. **What was converted**: File path(s) processed +2. **Key transformations**: Specific term replacements made +3. **Links updated**: How many CLAUDE.md → AGENTS.md link changes +4. **Location**: Where AGENTS.md file(s) were written +5. **Verification**: Confirm file was created/updated successfully + +If issues arise: +- Report specific problems clearly +- Suggest manual review if content is ambiguous +- Ask for clarification if file path is unclear + +## Example Output Format + +``` +✅ Conversion Complete: CLAUDE.md → AGENTS.md + +File: ./CLAUDE.md → ./AGENTS.md + +Transformations made: +- Replaced "Claude Code" with "AI coding assistants" (8 instances) +- Replaced "Claude" with "AI agent" (12 instances) +- Updated CLAUDE.md links to AGENTS.md links (3 links) +- Removed "claude.ai/code" URL (1 instance) + +Technical content preserved: +- Repository structure section (unchanged) +- Code examples (unchanged) +- Development workflow (unchanged) +- All documentation links (unchanged) + +File written to: ./AGENTS.md (2,847 bytes) +``` + +## Important Notes + +### Child CLAUDE.md References + +When converting a parent CLAUDE.md that references child CLAUDE.md files: + +```markdown +## Subdirectory Context Files + +Additional CLAUDE.md files in subdirectories: + +- [src/components/CLAUDE.md](src/components/CLAUDE.md) - Component docs +- [packages/api/CLAUDE.md](packages/api/CLAUDE.md) - API service +``` + +**Must become:** + +```markdown +## Subdirectory Context Files + +Additional AGENTS.md files in subdirectories: + +- [src/components/AGENTS.md](src/components/AGENTS.md) - Component docs +- [packages/api/AGENTS.md](packages/api/AGENTS.md) - API service +``` + +### Handling Edge Cases + +- **Multiple "Claude" references in one sentence**: Transform each independently based on context +- **Code comments mentioning Claude**: Keep as-is if it's about attribution; transform if it's instructional +- **URLs to claude.ai/code**: Remove or replace with generic phrasing +- **Command examples with Claude Code specific commands**: Add clarifying notes that these are for Claude Code + +### Preserving Intent + +The goal is to make documentation **AI-agnostic** while keeping **full semantic meaning**. When in doubt: +- Preserve technical accuracy over perfect phrasing +- Keep sentences readable and natural +- Maintain the author's original structure and style + +## Definition of Done + +- [ ] CLAUDE.md file(s) successfully read +- [ ] All Claude-specific terminology identified +- [ ] Terminology transformed to generic equivalents +- [ ] All CLAUDE.md links updated to AGENTS.md links +- [ ] Technical content preserved exactly +- [ ] AGENTS.md file(s) written to correct location(s) +- [ ] Conversion results reported to user +- [ ] No broken links created +- [ ] File structure maintained +- [ ] User informed of any edge cases or warnings diff --git a/commands/link-docs-to-claude.md b/commands/link-docs-to-claude.md new file mode 100644 index 0000000..d5cf8b7 --- /dev/null +++ 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 diff --git a/commands/plan-claude-md.md b/commands/plan-claude-md.md new file mode 100644 index 0000000..447873b --- /dev/null +++ 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 diff --git a/commands/sync-agents-md.md b/commands/sync-agents-md.md new file mode 100644 index 0000000..c687f69 --- /dev/null +++ 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 diff --git a/hooks/hooks.json b/hooks/hooks.json new file mode 100644 index 0000000..1605524 --- /dev/null +++ b/hooks/hooks.json @@ -0,0 +1,14 @@ +{ + "hooks": { + "PostToolUse": [ + { + "filter": "Write(*CLAUDE.md)|Edit(*CLAUDE.md)|Write(*claude.md)|Edit(*claude.md)", + "command": "bash", + "args": [ + "-c", + "echo '📄 CLAUDE.md updated! Syncing to AGENTS.md...' && echo '' && echo 'ℹ️ Use the claude-to-agents-converter agent to update AGENTS.md' && echo ' Or run /sync-agents-md to update all AGENTS.md files' && echo '' && echo 'This keeps your documentation accessible to all AI coding assistants.'" + ] + } + ] + } +} diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..3a06036 --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,61 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:yebot/rad-cc-plugins:plugins/documentation-tools", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "7674316965ecd6f6ab30a0268fc52921c0fa16c6", + "treeHash": "a3947dbd0acea9cd7301d370a4776e3808f3ca8ced9ff6a03103728a9138818f", + "generatedAt": "2025-11-28T10:29:11.018242Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "documentation-tools", + "description": "Documentation Tools - Utilities for managing and organizing repository documentation for optimal AI agent context, with CLAUDE.md to AGENTS.md conversion", + "version": "1.4.0" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "c4d0d124072b7951c67cfc7319afd2d1f72fc49efaf8d714772be67d5fd841e6" + }, + { + "path": "agents/claude-to-agents-converter.md", + "sha256": "573494e518dd46bc88aac3bcc62f68000561c25720d2b4a2a6845a26750e53d1" + }, + { + "path": "hooks/hooks.json", + "sha256": "36541b6ca429b6c736c39ff86081c72866880854114806bb3b306ba9a143635a" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "496bf8d15127a164bf4cdad5c502853f0a93717c2c4e071212f4bef8456766ce" + }, + { + "path": "commands/link-docs-to-claude.md", + "sha256": "43746caaed379cd47590437a677b159c9222476bff862e31ecc98d7975ed2638" + }, + { + "path": "commands/plan-claude-md.md", + "sha256": "64ec440423e14dfb4f37f5709137fb8153bac07f2c3ab98d7044543ed5b4d310" + }, + { + "path": "commands/sync-agents-md.md", + "sha256": "dd430698c74a6d8966f5129c44c325bffedd02e0d8be87e4538961d32c722d01" + } + ], + "dirSha256": "a3947dbd0acea9cd7301d370a4776e3808f3ca8ced9ff6a03103728a9138818f" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file