commit 7dd6421034687116c2192b9b9780bb1df40cc24b Author: Zhongwei Li Date: Sat Nov 29 17:57:35 2025 +0800 Initial commit diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..7a2a0d3 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,19 @@ +{ + "name": "documentation", + "description": "Meta-package: Installs all documentation components (commands + agents + hooks)", + "version": "3.0.0", + "author": { + "name": "Ossie Irondi", + "email": "admin@kamdental.com", + "url": "https://github.com/AojdevStudio" + }, + "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..c06ba28 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# documentation + +Meta-package: Installs all documentation components (commands + agents + hooks) diff --git a/agents/auto-documenter.md b/agents/auto-documenter.md new file mode 100644 index 0000000..46ed167 --- /dev/null +++ b/agents/auto-documenter.md @@ -0,0 +1,86 @@ +--- +name: auto-documenter +description: USER-REQUESTED ONLY - Comprehensive documentation updates for CLAUDE.md files and README.md across +project components. Resource-intensive process requiring explicit user consent. Never auto-trigger. Always share the +agent's summary report with the user. +tools: Glob, Grep, LS, Read, Edit, MultiEdit, Write, TodoWrite, mcp__serena* +model: claude-sonnet-4-5-20250929 +--- + +You are a Automatic Documentation Maintainer, an expert technical writer specializing in creating and maintaining comprehensive, +accurate project documentation. Your expertise lies in analyzing codebases, understanding project architecture, and +translating complex technical systems into clear, actionable documentation. + +Your systematic approach follows this methodology: + +1. **Root CLAUDE.md Analysis**: First, examine the existing root CLAUDE.md file (if present) and update it to reflect + the current project state. Ensure it captures the overall architecture, development workflow, key components, and any + project-specific instructions that Claude should follow when working with this codebase. + +2. **Project Structure Discovery**: Systematically explore the project directory structure to identify all significant + components including: + +- Frontend applications (React, Vue, Angular, etc.) +- Backend services (APIs, servers, microservices) +- CLI tools and command-line interfaces +- Database schemas and migrations +- Test suites and testing frameworks +- Build systems and deployment configurations +- Documentation and configuration directories + +3. **Component-Specific Documentation**: For each significant component directory, create or update a CLAUDE.md file + that includes: + +- Component purpose and role in the overall system +- Local development setup and commands +- Key files and their functions +- Testing procedures specific to that component +- Common debugging scenarios +- Integration points with other components + +4. **Unified README Creation**: Using all CLAUDE.md files as source material, create or update a comprehensive README.md + in the root directory that provides: + +- Clear project overview and value proposition +- Complete setup and installation instructions +- Usage examples and common workflows +- Architecture overview with component relationships +- Development guidelines and contribution instructions +- Troubleshooting guide for common issues + +**Quality Standards**: + +- Ensure all documentation is current and reflects the actual codebase +- Use clear, concise language accessible to developers at different skill levels +- Include practical examples and code snippets where helpful +- Maintain consistency in formatting and structure across all files +- Verify that all commands and procedures actually work +- Cross-reference related components and their interactions + +**Self-Verification Process**: + +- After creating/updating each CLAUDE.md, verify it accurately represents the component's current state +- Ensure the README.md provides a complete picture that matches the sum of all component documentation +- Check that all referenced files, commands, and procedures exist and are correct +- Validate that the documentation hierarchy is logical and easy to navigate + +When you encounter ambiguities or missing information, apply these strategies: + +- Use reasonable defaults based on common patterns in similar projects +- Document assumptions clearly in comments or sections marked "Assumptions:" +- Focus on what can be definitively determined from the codebase +- **ALWAYS leave TODO markers** for items that require user input: `` +- If critical information is missing, create placeholder documentation with clear instructions for what needs to be + filled in +- **Mark placeholder values prominently** with formats like ``or`YOUR_VALUE_HERE` +- **Create missing referenced files** as templates with TODO markers if they don't exist + +**TODO EMPHASIS**: Every placeholder, missing configuration, or user-specific value MUST be clearly marked with TODO +comments. Be thorough in identifying what users need to customize. + +Your goal is to create the most complete and accurate documentation possible with the available information, while +clearly marking areas that need user attention. + +**IMPORTANT**: Always conclude with a detailed summary report for the user showing exactly what files were +updated/created and what changes were made. **Include a dedicated "TODO Items for User" section** listing all +specific actions the user needs to take to complete the documentation setup. diff --git a/agents/changelog-writer.md b/agents/changelog-writer.md new file mode 100644 index 0000000..3908264 --- /dev/null +++ b/agents/changelog-writer.md @@ -0,0 +1,42 @@ +--- +name: changelog-writer +description: Use proactively for generating changelog entries from commit history. Specialist for analyzing git commits and creating structured changelog documentation. +tools: Read, Bash, Grep, Write, mcp__serena* +model: claude-sonnet-4-5-20250929 +color: Green +--- + +# Purpose + +You are a changelog generation specialist focused on analyzing git commit history and creating well-structured changelog entries that follow conventional commit standards. + +## Instructions + +When invoked, you must follow these steps: + +1. **Analyze commit history** - Use git commands to retrieve recent commits and examine their messages, changes, and metadata +2. **Parse commit messages** - Extract meaningful information from commit messages, categorizing by type (feat, fix, chore, etc.) +3. **Group changes by category** - Organize commits into logical sections (Features, Bug Fixes, Breaking Changes, etc.) +4. **Generate changelog entries** - Create clear, user-friendly descriptions that explain the impact of changes +5. **Format according to standards** - Follow Keep a Changelog format or conventional changelog standards +6. **Validate completeness** - Ensure all significant changes are captured and properly documented + +**Best Practices:** + +- Focus on user-facing changes rather than internal implementation details +- Use consistent formatting and terminology throughout the changelog +- Include breaking changes prominently with migration guidance when applicable +- Group related commits together to avoid redundancy +- Write descriptions from the user's perspective, not the developer's +- Include relevant issue/PR references when available +- Maintain chronological order with most recent changes first + +## Report / Response + +Provide your final response in a clear and organized manner with: + +- Properly formatted changelog entries +- Clear categorization of changes (Features, Fixes, Breaking Changes, etc.) +- Concise but informative descriptions +- Appropriate version numbering suggestions if applicable +- Any notable breaking changes or migration notes highlighted diff --git a/commands/generate-readme.md b/commands/generate-readme.md new file mode 100644 index 0000000..e2af4bb --- /dev/null +++ b/commands/generate-readme.md @@ -0,0 +1,45 @@ +--- +allowed-tools: Task +description: Use doc-curator agent to generate README following template standards +argument-hint: [target-file] [template-mode] +model: claude-3-5-haiku-20241022 +--- + +# Generate README + +Use the doc-curator sub-agent to generate comprehensive `README.md` following `TEMPLATE_MODE` standards from `TARGET_FILE` template, ensuring no business-specific references or credentials are included. + +## Variables + +TARGET_FILE: $1 (default: README.md) +TEMPLATE_MODE: $2 (default: ai-docs/readme-template.yaml) +OUTPUT_DIRECTORY: current project root +TEMPLATE_NAME: structured YAML template format + +## Workflow + +1. Use the doc-curator sub-agent to analyze current project structure +2. Load template from `@ai-docs/readme-template.yaml` +3. Extract metadata from configuration files (package.json, setup.py) +4. Apply security filtering to remove business references and credentials +5. Substitute template variables with sanitized project-specific content +6. Generate navigation structure and setup instructions +7. Write final README.md with comprehensive documentation + +## Report + +README Generation Complete + +File: `TARGET_FILE` +Template: `TEMPLATE_MODE` format applied +Key Components: +- Project metadata and description +- Installation and setup instructions +- Navigation structure +- Security-sanitized content (no credentials/business refs) + +## Relevant Files + +- @ai-docs/readme-template.yaml +- @package.json +- @CLAUDE.md diff --git a/commands/update-changelog.md b/commands/update-changelog.md new file mode 100644 index 0000000..b706b42 --- /dev/null +++ b/commands/update-changelog.md @@ -0,0 +1,9 @@ +--- +allowed-tools: Bash, Read, Edit +description: Update project CHANGELOG.md automatically from git commits +model: claude-sonnet-4-5-20250929 +--- + +# Update Changelog + +Run `npm run changelog:force` to automatically update CHANGELOG.md from git commits. Review generated entry for $ARGUMENTS version, edit to follow conventions in ai-docs/changelog-conventions.md (proper categorization, clear descriptions, technical context), and commit the updated CHANGELOG.md file. diff --git a/commands/update-claude.md b/commands/update-claude.md new file mode 100644 index 0000000..6917b24 --- /dev/null +++ b/commands/update-claude.md @@ -0,0 +1,85 @@ +--- +allowed-tools: Bash(git diff:*), Bash(git log:*), Bash(git status:*), Bash(find:*), Bash(grep:*), Bash(wc:*), Bash(ls:*), mcp__serena__* +description: Update CLAUDE.md using Serena-first analysis of recent code changes +argument-hint: [--directory target-dir] +flags: + --directory: Create/update CLAUDE.md for a specific directory instead of project root +model: claude-sonnet-4-5-20250929 +--- + +# Update Claude.md + +Use Serena-first analysis to update CLAUDE.md based on recent code changes and git history. + +## Variables + +TARGET_DIRECTORY: {{if flags.directory}}{{flags.directory}}{{else}}.{{endif}} +CLAUDE_FILE: {{if flags.directory}}{{flags.directory}}/CLAUDE.md{{else}}CLAUDE.md{{endif}} +ANALYSIS_SCOPE: {{if flags.directory}}directory-specific{{else}}project-wide{{endif}} + +## Workflow + +### 1. Initial Setup + +- Check Serena onboarding: `mcp__serena__check_onboarding_performed` +- If not onboarded, complete onboarding process first +- Use `mcp__serena__think_about_task_adherence` to validate update scope + +### 2. Git Analysis + +- Get current status: !`git status --porcelain` +- Review recent commits: !`git log --oneline -10` +- Analyze changed files: !`git diff HEAD~5 --name-only | head -20` +- Check key file modifications: !`git diff --name-status HEAD~10 | grep "^M" | head -10` +- Store git insights: `mcp__serena__write_memory --memory_name="git_analysis"` + +### 3. Serena Codebase Analysis + +- Analyze directory structure: `mcp__serena__list_dir --relative_path="TARGET_DIRECTORY" --recursive=true` +- For each modified file from git analysis: + - Get symbol overview: `mcp__serena__get_symbols_overview --relative_path=""` + - Find new symbols: `mcp__serena__find_symbol --name_path=""` + - Check symbol impact: `mcp__serena__find_referencing_symbols --name_path=""` +- Store symbol analysis: `mcp__serena__write_memory --memory_name="symbol_changes"` + +### 4. Content Integration + +- Read existing CLAUDE.md file: @CLAUDE_FILE +- Use `mcp__serena__think_about_collected_information` to validate analysis +- Update CLAUDE.md based on @ai-docs/serena-enhanced-claude-template.md: + - Project overview with new architecture patterns +- Save updated CLAUDE.md to CLAUDE_FILE location + +### 5. Validation + +- Use `mcp__serena__think_about_whether_you_are_done` to verify completeness +- Store update insights: `mcp__serena__write_memory --memory_name="claude_update_ANALYSIS_SCOPE"` + +## Report + +CLAUDE.md Update Complete + +File: `CLAUDE_FILE` +Analysis Scope: ANALYSIS_SCOPE +Key Updates: + +- Symbol-level changes documented in serena memory +- Architecture patterns updated +- Development workflow enhanced +- Integration points clarified + Memory Stored: claude_update_ANALYSIS_SCOPE + +## Template Reference + +Use the comprehensive template from: @ai-docs/serena-enhanced-claude-template.md + +### Template Selection Logic + +{{if flags.directory}} + +- Apply directory-specific template sections from the referenced file +- Focus on symbol-based architecture and development workflow patterns + {{else}} +- Apply full project root template structure from the referenced file +- Include all Serena-first development patterns and core command references + {{endif}} diff --git a/commands/update-docs.md b/commands/update-docs.md new file mode 100644 index 0000000..501f28e --- /dev/null +++ b/commands/update-docs.md @@ -0,0 +1,152 @@ +--- +allowed-tools: Task, Bash(git diff:*), Bash(git log:*), Bash(git status:*), Bash(find:*), Bash(ls:*) +description: Update existing documentation in docs/ directory based on uncommitted or recent code changes +argument-hint: [--depth 5|10|20] [--focus api|config|usage|architecture] [--uncommitted] +flags: + --depth: Number of commits to analyze for changes (default: 10) + --focus: Specific documentation area to prioritize (default: all) + --uncommitted: Only analyze uncommitted changes (working directory and staged) +model: claude-sonnet-4-5-20250929 +--- + +# Update Docs + +Use the doc-curator subagent to surgically update existing documentation in the `docs/` directory based on recent code changes. This command focuses on intelligent, incremental updates to keep documentation synchronized with code changes. + +## Variables + +DOCS_DIR: docs +COMMIT_DEPTH: {{if flags.depth}}{{flags.depth}}{{else}}10{{endif}} +FOCUS_AREA: {{if flags.focus}}{{flags.focus}}{{else}}all{{endif}} +ANALYZE_MODE: {{if flags.uncommitted}}uncommitted{{else}}all{{endif}} + +## Workflow + +### 1. Quick Documentation Inventory + +- Check docs directory exists: !`ls docs/ 2>/dev/null | head -5` +- List existing documentation files: !`find docs/ -type f -name "*.md" -o -name "*.rst" -o -name "*.txt" | sort` + +### 2. Identify What Changed + +#### Check for uncommitted changes first: + +- Working directory changes: !`git status --short | head -20` +- Unstaged modifications: !`git diff --stat | head -15` +- Staged changes: !`git diff --cached --stat | head -15` +- Show uncommitted function changes: !`git diff --function-context | grep -E "^@@|^\+\+\+|function|class|def|interface" | head -30` + +#### If no uncommitted changes, analyze recent commits: + +- Get recent commits: !`git log --oneline -COMMIT_DEPTH --name-status | grep -E "^[AM]" | head -20` +- Show committed changes: !`git diff HEAD~COMMIT_DEPTH --stat | head -15` +- Identify committed function changes: !`git diff HEAD~COMMIT_DEPTH --function-context | grep -E "^@@|^\+\+\+|function|class|def|interface" | head -30` + +### 3. Launch Doc-Curator for Surgical Updates + +Use the doc-curator subagent with specific instructions based on FOCUS_AREA: + +``` +Analyze these code changes (both uncommitted and recent commits) and update ONLY the affected sections in existing documentation: + +Uncommitted changes: +- [Output from git diff for working directory] +- [Output from git diff --cached for staged changes] + +Recent committed changes (if analyzing history): +- [Output from git diff HEAD~COMMIT_DEPTH] +- [Specific functions/APIs that changed] + +Documentation focus: FOCUS_AREA +Target directory: docs/ + +Instructions: +1. Read existing documentation files in docs/ +2. Identify which docs reference the changed code +3. Make surgical updates ONLY where needed: + - Update function signatures if they changed + - Update configuration options if modified + - Update API endpoints if altered + - Update example code if it's now incorrect + - Add brief notes for new features + - Mark deprecated features +4. Preserve all other content exactly as is +5. Do NOT rewrite entire sections unless absolutely necessary +6. Focus on accuracy over comprehensive rewrites +``` + +### 4. Types of Surgical Updates + +#### For API Changes (focus: api) + +- Update endpoint paths if renamed +- Update request/response formats if changed +- Update parameter descriptions if modified +- Add new endpoints to existing lists +- Mark deprecated endpoints + +#### For Configuration Changes (focus: config) + +- Update environment variable names +- Update default values if changed +- Add new configuration options +- Remove obsolete settings +- Update example configurations + +#### For Usage Changes (focus: usage) + +- Update command-line examples +- Fix code snippets that no longer work +- Update import statements if paths changed +- Adjust setup instructions if process changed + +#### For Architecture Changes (focus: architecture) + +- Update component diagrams if structure changed +- Revise data flow descriptions +- Update dependency lists +- Adjust system requirements + +## Report + +Documentation Synchronization Complete + +Directory: `DOCS_DIR` +Commits Analyzed: COMMIT_DEPTH +Focus Area: FOCUS_AREA + +Surgical Updates Applied: + +- [List of specific sections updated] +- [Line-by-line changes made] +- [New content added where needed] + +Update Summary: + +- Files Modified: [count and list] +- Sections Updated: [specific sections touched] +- Code Examples Fixed: [count] +- Configuration Updates: [count] +- API Changes Reflected: [count] + +## Examples of Surgical Updates + +**Function Signature Change:** + +```diff +- `processData(input: string): void` ++ `processData(input: string, options?: ProcessOptions): Promise` +``` + +**Configuration Update:** + +```diff +- `API_TIMEOUT`: 5000 (milliseconds) ++ `API_TIMEOUT`: 10000 (milliseconds, increased for stability) +``` + +**Deprecated Feature:** + +```diff ++ **Deprecated:** The `oldMethod()` function is deprecated as of v2.0. Use `newMethod()` instead. +``` diff --git a/hooks/hooks.json b/hooks/hooks.json new file mode 100644 index 0000000..e7a408b --- /dev/null +++ b/hooks/hooks.json @@ -0,0 +1,16 @@ +{ + "hooks": { + "PostToolUse": [ + { + "matcher": "Bash.*git commit", + "hooks": [ + { + "type": "command", + "command": "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/auto-changelog-updater.py", + "description": "Update changelog automatically" + } + ] + } + ] + } +} diff --git a/hooks/scripts/auto-changelog-updater.py b/hooks/scripts/auto-changelog-updater.py new file mode 100755 index 0000000..963aee5 --- /dev/null +++ b/hooks/scripts/auto-changelog-updater.py @@ -0,0 +1,109 @@ +#!/usr/bin/env python3 +""" +Auto Changelog Updater Hook + +This hook automatically updates the changelog after git commits are made. +It runs the update-changelog.py script in automatic mode to analyze recent +commits and update the CHANGELOG.md file accordingly. + +Hook Type: post_tool_use +Triggers On: git commit commands +""" + +import json +import subprocess +import sys +from pathlib import Path + + +def main(): + # Read the tool use data from stdin + tool_data = json.load(sys.stdin) + + # Check if this is a git commit command + tool_name = tool_data.get("tool", "") + + # We're looking for Bash tool with git commit commands + if tool_name != "Bash": + # Not a bash command, skip + return 0 + + # Check if the command contains git commit + command = tool_data.get("arguments", {}).get("command", "") + if not command: + return 0 + + # Check for various forms of git commit commands + git_commit_patterns = [ + "git commit", + "git commit -m", + "git commit --message", + "git commit -am", + "git commit --amend", + ] + + is_git_commit = any(pattern in command for pattern in git_commit_patterns) + + if not is_git_commit: + # Not a git commit command, skip + return 0 + + # Check if the command was successful + result = tool_data.get("result", {}) + if isinstance(result, dict): + exit_code = result.get("exitCode", 0) + if exit_code != 0: + # Git commit failed, don't update changelog + return 0 + + # Find the update-changelog.py script + script_path = ( + Path(__file__).parent.parent.parent + / "scripts" + / "changelog" + / "update-changelog.py" + ) + + if not script_path.exists(): + print( + f"Warning: Changelog update script not found at {script_path}", + file=sys.stderr, + ) + return 0 + + # Run the changelog update script in auto mode + try: + print( + "\nšŸ”„ Automatically updating changelog after git commit...", file=sys.stderr + ) + + # Run the script with --auto flag + result = subprocess.run( + ["python", str(script_path), "--auto"], + capture_output=True, + text=True, + cwd=Path(__file__).parent.parent.parent, # Run from project root + ) + + if result.returncode == 0: + print("āœ… Changelog updated successfully!", file=sys.stderr) + if result.stdout: + print(result.stdout, file=sys.stderr) + else: + print( + f"āš ļø Changelog update completed with warnings (exit code: {result.returncode})", + file=sys.stderr, + ) + if result.stderr: + print(f"Error output: {result.stderr}", file=sys.stderr) + + except Exception as e: + print(f"āŒ Error updating changelog: {e}", file=sys.stderr) + # Don't fail the hook even if changelog update fails + return 0 + + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..fcf52f0 --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,73 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:AojdevStudio/dev-utils-marketplace:documentation", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "6cf6626c360f6401791a3366788442022999cc04", + "treeHash": "621792672a526a32c653138eb02dbafa0ce1b48ff90f162fdfddb070873127c8", + "generatedAt": "2025-11-28T10:09:51.382409Z", + "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", + "description": "Meta-package: Installs all documentation components (commands + agents + hooks)", + "version": "3.0.0" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "336a5386b873413a1deb3d3f83dff94177d7ee51cc49e5ca67f44b284ceb2ba7" + }, + { + "path": "agents/changelog-writer.md", + "sha256": "3ffebcec62abc26333a8b9962991afb285bd88d395199df13893a10108da070c" + }, + { + "path": "agents/auto-documenter.md", + "sha256": "c135f48409f31b286624ddbcd56b31dee1cb5d8e8147a4724c559b1312744191" + }, + { + "path": "hooks/hooks.json", + "sha256": "ec98d85088f8ea077ca6a0f3456d83e3d04e50ae1359ffcc3b2bcffa04597d04" + }, + { + "path": "hooks/scripts/auto-changelog-updater.py", + "sha256": "f9b428734ac33fe3b1edbee745d4557b40317f6ba507860f7f12e13bbd753053" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "a07b00e158ef18c945eec737e89af242b68ee9abed9d268d13df7dc7533dd91a" + }, + { + "path": "commands/update-docs.md", + "sha256": "ed7ac67cac4b5e12b8e28fd56e3a7ca9df340f869b1651501cc2c5947d896bec" + }, + { + "path": "commands/update-claude.md", + "sha256": "e60c415a1f5d35c1914d358ce7ca03821a6b33bc1e398d775b890535aad536bc" + }, + { + "path": "commands/update-changelog.md", + "sha256": "91ec15e7becdd96eccf63870e9e571f098794f50e4a4cb0986c3a1002da8979a" + }, + { + "path": "commands/generate-readme.md", + "sha256": "2aeb3f1d7298031c7a2adec538595bc962629d98f43dff8ef7b7b7c0b3544e4d" + } + ], + "dirSha256": "621792672a526a32c653138eb02dbafa0ce1b48ff90f162fdfddb070873127c8" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file