From fedac466b2fc76ceb3d5720b9339ab1f1f05e2b6 Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sun, 30 Nov 2025 08:40:52 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 18 ++ README.md | 3 + agents/markdown-splitter.md | 314 ++++++++++++++++++++++++++++++++ agents/refactoring-architect.md | 86 +++++++++ commands/config.md | 42 +++++ commands/disable.md | 42 +++++ commands/enable.md | 42 +++++ commands/init.md | 64 +++++++ commands/protect.md | 36 ++++ commands/split-markdown.md | 275 ++++++++++++++++++++++++++++ commands/status.md | 43 +++++ commands/unprotect.md | 33 ++++ hooks/hooks.json | 50 +++++ plugin.lock.json | 85 +++++++++ 14 files changed, 1133 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 agents/markdown-splitter.md create mode 100644 agents/refactoring-architect.md create mode 100644 commands/config.md create mode 100644 commands/disable.md create mode 100644 commands/enable.md create mode 100644 commands/init.md create mode 100644 commands/protect.md create mode 100644 commands/split-markdown.md create mode 100644 commands/status.md create mode 100644 commands/unprotect.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..1f5e289 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,18 @@ +{ + "name": "guard", + "description": "Unified guardian that protects sensitive files, prevents bloated code, and enforces architectural best practices", + "version": "2.0.0", + "author": { + "name": "Ulrich Diedrichsen", + "email": "[email protected]" + }, + "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..50bcb64 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# guard + +Unified guardian that protects sensitive files, prevents bloated code, and enforces architectural best practices diff --git a/agents/markdown-splitter.md b/agents/markdown-splitter.md new file mode 100644 index 0000000..dbcf414 --- /dev/null +++ b/agents/markdown-splitter.md @@ -0,0 +1,314 @@ +--- +name: markdown-splitter +description: Expert agent for splitting large markdown files into manageable, context-friendly sections +--- + +# Markdown Splitter Agent + +You are an expert at analyzing and splitting large markdown documents into manageable sections optimized for LLM context windows. + +## Your Mission + +When a large markdown file exceeds recommended size thresholds, you help split it into: +- **Index file** (`00-.md`) - Table of contents with navigation +- **Section files** (`01-.md`, `02-.md`, etc.) - Logically organized content chunks + +## Core Principles + +1. **Preserve Structure** - Maintain all formatting, code blocks, links, and images +2. **Logical Boundaries** - Split at natural section breaks (headers) +3. **Navigation** - Add bidirectional links between sections and index +4. **Context Preservation** - Each section should be self-contained and readable +5. **Backup Safety** - Always preserve the original file + +## Analysis Process + +When you receive a large markdown file to split: + +### 1. Analyze Document Structure + +```bash +# First, examine the file structure +cat | head -100 # Preview the beginning +grep -n "^#" # Find all headers +wc -l # Count total lines +``` + +Parse the document to identify: +- Top-level sections (# headers) +- Subsections (## ### headers) +- Natural breaking points +- Content density per section + +### 2. Determine Split Strategy + +Ask yourself: +- **How many top-level sections?** (aim for 3-10 sections) +- **Are sections balanced?** (try to keep sections 500-1000 lines) +- **Are there natural groupings?** (related content should stay together) +- **Any special content?** (large code blocks, tables, etc.) + +### 3. Present Proposed Split + +Before splitting, show the user: + +``` +📊 Proposed Split for: task.md (3000 lines) + +00-task.md Index + TOC +01-task.md Introduction (450 lines) +02-task.md Requirements (650 lines) +03-task.md Implementation (850 lines) +04-task.md Testing & Deployment (550 lines) +05-task.md Appendices (500 lines) + +Total: 6 files +Strategy: Split by top-level headers +Backup: task.md.backup +``` + +Ask for confirmation before proceeding. + +### 4. Execute Split + +Use the split_markdown.py script: + +```bash +python3 ${CLAUDE_PLUGIN_ROOT}/scripts/split_markdown.py +``` + +The script will: +- Parse markdown structure +- Group sections intelligently +- Create index with TOC +- Generate section files with navigation +- Backup original file +- Report results + +### 5. Verify Results + +After splitting: +- Check that all files were created +- Verify navigation links work +- Ensure no content was lost +- Confirm formatting is preserved + +## Index File Template + +The index file (00-.md) should contain: + +```markdown +# - Index + +> This document has been split into manageable sections for better context handling. + +## 📑 Table of Contents + +1. [Section 1](./01-.md) - Brief description (line count) +2. [Section 2](./02-.md) - Brief description (line count) +... + +## 🔍 Quick Navigation + +- **Total Sections**: N +- **Original Size**: X lines +- **Average Section**: Y lines +- **Split Date**: YYYY-MM-DD + +## 📝 Overview + +[Brief summary of the document and why it was split] + +--- +*Generated by Guard Markdown Splitter* +``` + +## Section File Template + +Each section file should include: + +```markdown +# Section Title + +> **Navigation**: [← Index](./00-.md) | [← Previous](./0N-.md) | [Next →](./0M-.md) + +--- + +[Section content...] + +--- + +> **Navigation**: [← Index](./00-.md) | [← Previous](./0N-.md) | [Next →](./0M-.md) +``` + +## Configuration + +Respect the markdown splitter configuration in `.claude/quality_config.json`: + +```json +{ + "markdown_splitter": { + "enabled": true, + "auto_suggest_threshold": 2000, + "target_chunk_size": 800, + "split_strategy": "headers", + "preserve_original": true, + "create_index": true + } +} +``` + +- **auto_suggest_threshold**: When to suggest splitting (line count) +- **target_chunk_size**: Target lines per section (for 'smart' strategy) +- **split_strategy**: "headers" (by # headers) or "smart" (by size) +- **preserve_original**: Keep .backup file +- **create_index**: Generate 00- index file + +## Split Strategies + +### Strategy: "headers" (Default) + +Split at every top-level header (# title): +- ✅ Preserves logical document structure +- ✅ Sections are semantically meaningful +- ⚠️ May create uneven section sizes + +**Use when**: Document has clear top-level sections + +### Strategy: "smart" + +Group sections to target chunk size: +- ✅ More consistent section sizes +- ✅ Respects header boundaries +- ⚠️ May split unrelated topics together + +**Use when**: Document has many small sections or uneven structure + +## Common Scenarios + +### Scenario 1: PRD Document (Product Requirements) + +``` +Original: PRD.md (2500 lines) +Structure: + # Overview (200 lines) + # User Stories (800 lines) + # Technical Requirements (900 lines) + # Design (400 lines) + # Testing (200 lines) + +Split into: + 00-PRD.md (index) + 01-PRD.md (Overview) + 02-PRD.md (User Stories) + 03-PRD.md (Technical Requirements) + 04-PRD.md (Design) + 05-PRD.md (Testing) +``` + +### Scenario 2: Task List (Implementation Tasks) + +``` +Original: tasks.md (3500 lines) +Structure: Many ## headers under # categories + +Split into: + 00-tasks.md (index) + 01-tasks.md (Backend Tasks - 800 lines) + 02-tasks.md (Frontend Tasks - 850 lines) + 03-tasks.md (Database Tasks - 600 lines) + 04-tasks.md (Testing Tasks - 650 lines) + 05-tasks.md (Deployment Tasks - 600 lines) +``` + +### Scenario 3: Documentation + +``` +Original: API-docs.md (4000 lines) +Many endpoints, each with ## header + +Use "smart" strategy to group related endpoints: + 00-API-docs.md (index) + 01-API-docs.md (Authentication - 800 lines) + 02-API-docs.md (User Endpoints - 900 lines) + 03-API-docs.md (Data Endpoints - 1000 lines) + 04-API-docs.md (Admin Endpoints - 800 lines) + 05-API-docs.md (Webhooks - 500 lines) +``` + +## Error Handling + +If splitting fails: +- Check file exists and is readable +- Verify it's a valid markdown file +- Ensure output directory is writable +- Check for malformed headers +- Look for unusual formatting + +## Post-Split Actions + +After successful split: + +1. **Verify integrity**: Open index and a few sections +2. **Test navigation**: Click through links +3. **Update references**: If other files reference the original, update them +4. **Inform user**: Explain the new structure +5. **Suggest workflow**: How to work with split files + +## Communication Style + +- Be clear and concise +- Show the proposed structure visually +- Always ask for confirmation before splitting +- Provide useful statistics (line counts, section counts) +- Explain the reasoning behind split decisions + +## Tools Available + +- `split_markdown.py` - Core splitting script +- Standard file tools (Read, Write, etc.) +- Bash for analysis (grep, wc, etc.) + +## Example Interaction + +``` +User: This markdown file is getting too large +Agent: Let me analyze the file... + +[Reads file and analyzes structure] + +I found that task.md is 3200 lines. I can split it into manageable sections: + +📊 Proposed Split: + 00-task.md Index (TOC) + 01-task.md Phase 1: Foundation (650 lines) + 02-task.md Phase 2: Core Features (800 lines) + 03-task.md Phase 3: Integration (720 lines) + 04-task.md Phase 4: Polish (580 lines) + 05-task.md Testing & Deployment (450 lines) + +This will create 6 files with navigation between them. +Original will be backed up as task.md.backup. + +Shall I proceed with the split? + +User: Yes +Agent: [Executes split_markdown.py] + +✅ Split complete! Created 6 files: + • 00-task.md (index) + • 01-task.md through 05-task.md (sections) + • task.md.backup (original) + +You can now navigate through the index to access each section. +``` + +## Remember + +- **Ask before acting** - Always confirm the split plan +- **Explain your reasoning** - Why these split points? +- **Verify results** - Check that everything worked +- **Guide the user** - Help them understand the new structure +- **Be helpful** - Suggest the best strategy for their document + +Your goal is to make large markdown files more manageable and context-friendly while preserving all content and structure. diff --git a/agents/refactoring-architect.md b/agents/refactoring-architect.md new file mode 100644 index 0000000..c71d74c --- /dev/null +++ b/agents/refactoring-architect.md @@ -0,0 +1,86 @@ +--- +description: Expert architect for refactoring large files into maintainable modules +capabilities: ["refactoring", "architecture", "module-design", "domain-modeling"] +--- + +# Refactoring Architect + +A specialized agent for breaking down large, monolithic files into well-structured, maintainable modules following domain-driven design principles. + +## Expertise + +This agent excels at: +- **Code Architecture**: Analyzing large files and identifying natural boundaries +- **Domain Modeling**: Applying domain-driven design to organize code +- **Separation of Concerns**: Splitting logic, data, and presentation layers +- **Module Design**: Creating focused, single-responsibility modules +- **Dependency Management**: Organizing imports and reducing coupling + +## When to Invoke + +Use this agent when: +- A file exceeds recommended size limits (typically >500-1000 lines) +- Code has multiple responsibilities mixed together +- You need architectural guidance on splitting a module +- You want to improve code maintainability and testability +- The Code Quality Guardian blocks a file creation + +## Approach + +The agent follows this methodology: + +1. **Analyze Structure**: Understand the current file's responsibilities +2. **Identify Domains**: Find natural boundaries and concerns +3. **Design Architecture**: Propose a modular structure +4. **Create Modules**: Generate well-organized, focused files +5. **Handle Dependencies**: Set up proper imports and exports + +## Examples of Refactoring + +### Before: Large monolithic file +``` +user_service.dart (1200 lines) +- User model +- User repository +- User API client +- User validation logic +- User UI components +- User state management +``` + +### After: Well-structured modules +``` +models/user.dart (50 lines) +repositories/user_repository.dart (120 lines) +services/user_api_client.dart (100 lines) +validators/user_validator.dart (80 lines) +ui/user_profile_widget.dart (150 lines) +state/user_state.dart (100 lines) +``` + +## Domain-Driven Design Principles + +Applies these architectural patterns: +- **Entities & Value Objects**: Core domain models +- **Repositories**: Data access abstraction +- **Services**: Business logic coordination +- **Use Cases**: Application-specific workflows +- **DTOs**: Data transfer objects for APIs +- **Presentation**: UI components and state + +## Integration with Code Quality Guardian + +When the Code Quality Guardian blocks a large file: +1. It suggests using this refactoring agent +2. You can invoke with: "Help me refactor this into modules" +3. The agent analyzes your intent and proposes structure +4. Creates multiple focused files that pass quality checks + +## Sample Invocations + +``` +"Refactor this 1500-line service into proper modules" +"Split this file following domain-driven design" +"I need architectural guidance for organizing this code" +"Break this into data, logic, and presentation layers" +``` diff --git a/commands/config.md b/commands/config.md new file mode 100644 index 0000000..4c69d0f --- /dev/null +++ b/commands/config.md @@ -0,0 +1,42 @@ +--- +description: View and configure code quality thresholds +--- + +# config + +View and customize file size thresholds for different file types. + +## Usage + +```bash +# View current configuration +/guard:config + +# Show available options +/guard:config help +``` + +## Configuration + +Edit `.claude/quality_config.json` in your project root to customize thresholds. + +## Example Configuration + +```json +{ + "default": 1000, + "extensions": { + ".dart": 800, + ".py": 800, + ".ts": 800, + ".tsx": 600, + ".jsx": 600 + } +} +``` + +## Implementation + +```bash +${CLAUDE_PLUGIN_ROOT}/scripts/show_config.py +``` diff --git a/commands/disable.md b/commands/disable.md new file mode 100644 index 0000000..96f5367 --- /dev/null +++ b/commands/disable.md @@ -0,0 +1,42 @@ +--- +description: Temporarily disable a guardian +--- + +# disable + +Temporarily disable specific guardians or all guardians. Changes persist until explicitly re-enabled. + +## Usage + +```bash +/guard:disable +/guard:disable all +``` + +## Available Guardians + +- `file-protection` - File blacklist protection +- `markdown-control` - Unsolicited markdown blocking +- `code-quality` - File size and TODO enforcement +- `generated-files` - Generated file protection +- `tool-guardian` - Package manager enforcement +- `package-guardian` - Package manifest warnings + +## Examples + +```bash +# Disable package manifest warnings +/guard:disable package-guardian + +# Disable all guardians +/guard:disable all + +# Disable file protection temporarily +/guard:disable file-protection +``` + +## Implementation + +```bash +${CLAUDE_PLUGIN_ROOT}/scripts/manage_overrides.py disable {{guardian-name}} +``` diff --git a/commands/enable.md b/commands/enable.md new file mode 100644 index 0000000..8b38ebd --- /dev/null +++ b/commands/enable.md @@ -0,0 +1,42 @@ +--- +description: Re-enable a disabled guardian +--- + +# enable + +Re-enable specific guardians or all guardians that were previously disabled. + +## Usage + +```bash +/guard:enable +/guard:enable all +``` + +## Available Guardians + +- `file-protection` - File blacklist protection +- `markdown-control` - Unsolicited markdown blocking +- `code-quality` - File size and TODO enforcement +- `generated-files` - Generated file protection +- `tool-guardian` - Package manager enforcement +- `package-guardian` - Package manifest warnings + +## Examples + +```bash +# Re-enable package manifest warnings +/guard:enable package-guardian + +# Re-enable all guardians +/guard:enable all + +# Re-enable file protection +/guard:enable file-protection +``` + +## Implementation + +```bash +${CLAUDE_PLUGIN_ROOT}/scripts/manage_overrides.py enable {{guardian-name}} +``` diff --git a/commands/init.md b/commands/init.md new file mode 100644 index 0000000..d6185c0 --- /dev/null +++ b/commands/init.md @@ -0,0 +1,64 @@ +--- +description: Initialize Guard plugin with file protection and code quality features +--- + +# init + +Initialize the Guard plugin by: +- Creating `.claude/forbidden_paths.txt` with default protected patterns +- Creating `.claude/file_guardian_config.json` with markdown blocking settings +- Creating `.claude/quality_config.json` with code quality thresholds +- Setting up hooks in `.claude/hooks.json` +- Making scripts executable + +## Usage + +```bash +/guard:init +``` + +## What Gets Created + +1. **Blacklist File** (`.claude/forbidden_paths.txt`) + - Default patterns for sensitive files (.env, secrets/, *.key, etc.) + - Lock files (package-lock.json, yarn.lock, etc.) + - Git internals and build artifacts + +2. **File Guardian Configuration** (`.claude/file_guardian_config.json`) + - Markdown blocking settings + - Allowed patterns for documentation + +3. **Quality Configuration** (`.claude/quality_config.json`) + - Default file size thresholds for different extensions + - TODO/FIXME blocking settings + +4. **Hooks** (`.claude/hooks.json`) + - PreToolUse hooks for Write/Edit/MultiEdit operations + - Merges with existing hooks from other plugins + +5. **Script Permissions** + - Makes all hook scripts executable + +## Default Protections + +### File Protection +After initialization, Guard will automatically protect: +- Environment files (`.env`, `.env.*`) +- Secrets directory +- Credential files (`*.key`, `*.pem`, `*credentials*.json`) +- Lock files (`package-lock.json`, `pubspec.lock`, etc.) +- Git internals (`.git/`) +- Build artifacts (`build/`, `dist/`, `node_modules/`) +- Unsolicited markdown summaries (`SUMMARY.md`, `RECAP.md`) + +### Code Quality +Guard will enforce: +- File size limits (800 lines for code, 600 for components, 5000 for docs) +- TODO/FIXME/HACK comment blocking +- Architectural best practices + +## Implementation + +```bash +${CLAUDE_PLUGIN_ROOT}/scripts/init_plugin.py +``` diff --git a/commands/protect.md b/commands/protect.md new file mode 100644 index 0000000..fdcc54e --- /dev/null +++ b/commands/protect.md @@ -0,0 +1,36 @@ +--- +description: Add files or patterns to the protection blacklist +--- + +# protect + +Protect files from accidental edits by adding them to the blacklist. + +## Usage + +```bash +/protect +/protect list +``` + +## Examples + +```bash +# Protect environment files +/protect .env + +# Protect entire directory +/protect secrets/ + +# Protect by extension +/protect *.key + +# Show current protections +/protect list +``` + +## Implementation + +```bash +${CLAUDE_PLUGIN_ROOT}/scripts/manage_blacklist.py add {{pattern}} +``` diff --git a/commands/split-markdown.md b/commands/split-markdown.md new file mode 100644 index 0000000..bcaf2a6 --- /dev/null +++ b/commands/split-markdown.md @@ -0,0 +1,275 @@ +--- +description: Split large markdown files into manageable sections with automatic navigation +--- + +# split-markdown + +Intelligently split a large markdown file into context-friendly sections with automatic table of contents and navigation. + +## Usage + +```bash +# Split a specific markdown file +/guard:split-markdown + +# Examples +/guard:split-markdown task.md +/guard:split-markdown docs/PRD.md +/guard:split-markdown ./planning/requirements.md +``` + +## What It Does + +When you split a markdown file, the Guard plugin will: + +1. **Analyze Structure** - Parse the document to identify logical sections based on headers +2. **Propose Split** - Show you how the file will be divided before making changes +3. **Create Index** - Generate `00-.md` with table of contents and navigation +4. **Create Sections** - Generate numbered files (`01-`, `02-`, etc.) for each section +5. **Add Navigation** - Include bidirectional links between index and sections +6. **Backup Original** - Save the original file as `.backup` + +## Output Structure + +For a file named `task.md`, you'll get: + +``` +task.md.backup # Original file (backup) +00-task.md # Index with TOC +01-task.md # First section +02-task.md # Second section +03-task.md # Third section +... +``` + +### Index File (00-task.md) + +Contains: +- Document title +- Table of contents with links to all sections +- Quick navigation statistics (total sections, line counts) +- Overview explaining why the split was done +- Metadata (split date, strategy used) + +### Section Files (01-task.md, 02-task.md, etc.) + +Each section includes: +- Section title +- Navigation header (links to index, previous, next) +- Full section content (preserved formatting) +- Navigation footer (same links as header) + +## Configuration + +The splitting behavior is controlled by `.claude/quality_config.json`: + +```json +{ + "markdown_splitter": { + "enabled": true, + "auto_suggest_threshold": 2000, + "target_chunk_size": 800, + "split_strategy": "headers", + "preserve_original": true, + "create_index": true + } +} +``` + +### Configuration Options + +- **`auto_suggest_threshold`** (default: 2000) + - Line count threshold for automatic split suggestions + - When a markdown file exceeds this, Guard will offer to split it + +- **`target_chunk_size`** (default: 800) + - Target lines per section (used with "smart" strategy) + - Helps keep sections at manageable sizes + +- **`split_strategy`** (default: "headers") + - `"headers"` - Split at each top-level header (# title) + - `"smart"` - Group sections to target chunk size while respecting boundaries + +- **`preserve_original`** (default: true) + - Keep backup of original file as `.backup` + - Set to false to remove original after split + +- **`create_index`** (default: true) + - Generate `00-.md` index file + - Set to false to only create section files + +## Split Strategies + +### Headers Strategy (Default) + +Splits at every top-level header (`# Title`): + +**Pros:** +- Preserves logical document structure +- Sections are semantically meaningful +- Easy to understand split points + +**Cons:** +- May create uneven section sizes + +**Best for:** +- Well-structured documents with clear top-level sections +- PRDs, design docs, technical specifications + +### Smart Strategy + +Groups sections to target chunk size while respecting header boundaries: + +**Pros:** +- More consistent section sizes +- Still respects logical boundaries +- Better for documents with many small sections + +**Cons:** +- May group unrelated content together + +**Best for:** +- Documents with many small sections +- Task lists with many items +- API documentation with many endpoints + +## Examples + +### Example 1: Large PRD Document + +```bash +/guard:split-markdown requirements.md +``` + +**Before:** +``` +requirements.md (3500 lines) + # Overview + # User Stories + # Technical Requirements + # Architecture + # Testing Strategy +``` + +**After:** +``` +requirements.md.backup +00-requirements.md (index) +01-requirements.md (Overview - 400 lines) +02-requirements.md (User Stories - 900 lines) +03-requirements.md (Technical Requirements - 1100 lines) +04-requirements.md (Architecture - 700 lines) +05-requirements.md (Testing Strategy - 400 lines) +``` + +### Example 2: Implementation Task List + +```bash +/guard:split-markdown tasks.md +``` + +**Before:** +``` +tasks.md (4200 lines) + # Backend Tasks + ## API Endpoints (many subtasks) + ## Database Schema (many subtasks) + # Frontend Tasks + ## Components (many subtasks) + ## Pages (many subtasks) +``` + +**After:** +``` +tasks.md.backup +00-tasks.md (index) +01-tasks.md (Backend Tasks - 2100 lines) +02-tasks.md (Frontend Tasks - 2100 lines) +``` + +### Example 3: API Documentation + +```bash +/guard:split-markdown api-docs.md +``` + +With `"split_strategy": "smart"` in config: + +**Before:** +``` +api-docs.md (5000 lines) + # Authentication + # User Endpoints (50+ endpoints) + # Data Endpoints (40+ endpoints) + # Admin Endpoints (30+ endpoints) +``` + +**After:** +``` +api-docs.backup +00-api-docs.md (index) +01-api-docs.md (Authentication - 600 lines) +02-api-docs.md (User Endpoints Part 1 - 800 lines) +03-api-docs.md (User Endpoints Part 2 - 850 lines) +04-api-docs.md (Data Endpoints Part 1 - 800 lines) +05-api-docs.md (Data Endpoints Part 2 - 750 lines) +06-api-docs.md (Admin Endpoints - 700 lines) +``` + +## When to Use + +Split a markdown file when: + +- 📄 **File exceeds 2000 lines** - May hit LLM context limits +- 🔍 **Hard to navigate** - Takes too long to find sections +- ⚡ **Performance issues** - Editor or tools slow down with large file +- 👥 **Team collaboration** - Easier to work on separate sections +- 📝 **Documentation** - Better organization for large docs + +## Integration with Guard + +The markdown splitter integrates with Guard's file size checking: + +1. When you try to write a large markdown file (>2000 lines) +2. Guard detects it exceeds the threshold +3. Guard offers: "This file is large. Would you like to split it?" +4. If you say "yes", the markdown-splitter agent is automatically launched +5. The agent analyzes, proposes a split, and executes with your approval + +This provides **proactive** splitting suggestions without manual command invocation. + +## Implementation + +This command launches the **markdown-splitter agent** with the specified file: + +```bash +# The agent will: +# 1. Read and analyze the file structure +# 2. Present a proposed split plan +# 3. Ask for confirmation +# 4. Execute the split using split_markdown.py +# 5. Verify results and report success +``` + +## Tips + +1. **Review before splitting** - Always check the proposed split plan +2. **Adjust strategy** - Switch between "headers" and "smart" for different results +3. **Update references** - If other files link to the original, update them +4. **Commit original first** - Use git to track changes before splitting +5. **Test navigation** - After splitting, click through a few section links + +## Related Commands + +- `/guard:config` - View and configure splitting thresholds +- `/guard:init` - Initialize Guard with default configuration + +## See Also + +- **markdown-splitter agent** - The AI agent that performs the analysis and splitting +- **split_markdown.py** - The underlying Python script +- `.claude/quality_config.json` - Configuration file + +--- + +**Need help?** The markdown-splitter agent will guide you through the process and explain each step. diff --git a/commands/status.md b/commands/status.md new file mode 100644 index 0000000..91a82e9 --- /dev/null +++ b/commands/status.md @@ -0,0 +1,43 @@ +--- +description: View guardian status +--- + +# status + +Display the current enabled/disabled state of all guardians. + +## Usage + +```bash +/guard:status +``` + +## What It Shows + +For each guardian: +- Current status (enabled/disabled) +- Guardian name and description +- Configuration file location + +## Example Output + +``` +🛡️ Guard Plugin - Guardian Status + +🛡️ File Protection ✅ enabled + Prevents editing forbidden files (blacklist) + +📄 Markdown Control ❌ disabled + Blocks unsolicited markdown summaries + +📏 Code Quality ✅ enabled + Enforces file size limits and TODO blocking + +... +``` + +## Implementation + +```bash +${CLAUDE_PLUGIN_ROOT}/scripts/show_status.py +``` diff --git a/commands/unprotect.md b/commands/unprotect.md new file mode 100644 index 0000000..681d5b1 --- /dev/null +++ b/commands/unprotect.md @@ -0,0 +1,33 @@ +--- +description: Remove files or patterns from the protection blacklist +--- + +# unprotect + +Remove protection from files, allowing them to be edited. + +## Usage + +```bash +/unprotect +/unprotect list +``` + +## Examples + +```bash +# Unprotect a file +/unprotect .env.example + +# Unprotect directory +/unprotect build/ + +# Show all protections +/unprotect list +``` + +## Implementation + +```bash +${CLAUDE_PLUGIN_ROOT}/scripts/manage_blacklist.py remove {{pattern}} +``` diff --git a/hooks/hooks.json b/hooks/hooks.json new file mode 100644 index 0000000..473d11a --- /dev/null +++ b/hooks/hooks.json @@ -0,0 +1,50 @@ +{ + "hooks": { + "PreToolUse": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate_tool_usage.py" + } + ] + }, + { + "matcher": "Read|Write|Edit|MultiEdit", + "hooks": [ + { + "type": "command", + "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate_generated_files.py" + } + ] + }, + { + "matcher": "Write|Edit|MultiEdit", + "hooks": [ + { + "type": "command", + "command": "${CLAUDE_PLUGIN_ROOT}/scripts/check_file_size.py" + }, + { + "type": "command", + "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate_blacklist.py" + }, + { + "type": "command", + "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate_package_edits.py" + } + ] + }, + { + "matcher": "Write", + "hooks": [ + { + "type": "command", + "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate_markdown.py" + } + ] + } + ] + } +} diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..716a826 --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,85 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:moinsen-dev/claude_code_marketplace:plugins/guard", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "84feb2109a66d025a1742098a2c9e70c29a13e94", + "treeHash": "b7683db4df5d88349e5c45d88a2423d06f1f135954f5329cee7f4846065f9aae", + "generatedAt": "2025-11-28T10:27:08.291219Z", + "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": "guard", + "description": "Unified guardian that protects sensitive files, prevents bloated code, and enforces architectural best practices", + "version": "2.0.0" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "3015a8ada9373eb989aecd3d95d36d0c3fff2315c9824287b7cdef61b8476511" + }, + { + "path": "agents/refactoring-architect.md", + "sha256": "393bc38981479b95041d2751418ba7c46d31719911c7198ddcb73a6b3c2cdeb0" + }, + { + "path": "agents/markdown-splitter.md", + "sha256": "51314ba9d6e3fd30a704b12f6040a4014ce500b61d87bcc00f74baef01ca533a" + }, + { + "path": "hooks/hooks.json", + "sha256": "c1db43be02dfd0a95d8706b341dc4825d4fbbeb9e54e7739d51b542b629ce8c8" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "c2ea433e12bdb864bc81a81d7e45e53ad9dcfb76eccae0a9158ccf28a173ad05" + }, + { + "path": "commands/protect.md", + "sha256": "3f755ff2de2b7a54d843f2710f60baf717eb77e34ebe406b650163cc4056d2e2" + }, + { + "path": "commands/disable.md", + "sha256": "d5a0a152a685eacc032e6599f65287e6a82c292b5c54061019d0a76390258f70" + }, + { + "path": "commands/unprotect.md", + "sha256": "222503834d80aa37f87c7c6b1e6adc826372fefe8bb1efa9299e22709b1ae2eb" + }, + { + "path": "commands/status.md", + "sha256": "6f185328000c7d9b794c953f88482d15eb1d7e73c7c467840ee4210df4f39822" + }, + { + "path": "commands/enable.md", + "sha256": "a8172f54ed43b9c0e2908bad0c72c46d8cc2b1d985ec4b9ce5170e62ec04e960" + }, + { + "path": "commands/split-markdown.md", + "sha256": "26a1b6c60e92c038631ba11dcbcf930674ccaafd08bbfc865b3ece45e380a6ba" + }, + { + "path": "commands/init.md", + "sha256": "248f71685a674c3a97520a57d36040850fe95b65abf6200866e8dfd5fde3f519" + }, + { + "path": "commands/config.md", + "sha256": "0a8661074e461435aa73b91d92adc7b3f2fdffebc366377d776d3671a3c94fe3" + } + ], + "dirSha256": "b7683db4df5d88349e5c45d88a2423d06f1f135954f5329cee7f4846065f9aae" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file