Initial commit
This commit is contained in:
18
.claude-plugin/plugin.json
Normal file
18
.claude-plugin/plugin.json
Normal file
@@ -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"
|
||||
]
|
||||
}
|
||||
3
README.md
Normal file
3
README.md
Normal file
@@ -0,0 +1,3 @@
|
||||
# guard
|
||||
|
||||
Unified guardian that protects sensitive files, prevents bloated code, and enforces architectural best practices
|
||||
314
agents/markdown-splitter.md
Normal file
314
agents/markdown-splitter.md
Normal file
@@ -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-<basename>.md`) - Table of contents with navigation
|
||||
- **Section files** (`01-<basename>.md`, `02-<basename>.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 <file> | head -100 # Preview the beginning
|
||||
grep -n "^#" <file> # Find all headers
|
||||
wc -l <file> # 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 <file-path>
|
||||
```
|
||||
|
||||
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-<basename>.md) should contain:
|
||||
|
||||
```markdown
|
||||
# <Document> - Index
|
||||
|
||||
> This document has been split into manageable sections for better context handling.
|
||||
|
||||
## 📑 Table of Contents
|
||||
|
||||
1. [Section 1](./01-<basename>.md) - Brief description (line count)
|
||||
2. [Section 2](./02-<basename>.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-<basename>.md) | [← Previous](./0N-<basename>.md) | [Next →](./0M-<basename>.md)
|
||||
|
||||
---
|
||||
|
||||
[Section content...]
|
||||
|
||||
---
|
||||
|
||||
> **Navigation**: [← Index](./00-<basename>.md) | [← Previous](./0N-<basename>.md) | [Next →](./0M-<basename>.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.
|
||||
86
agents/refactoring-architect.md
Normal file
86
agents/refactoring-architect.md
Normal file
@@ -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"
|
||||
```
|
||||
42
commands/config.md
Normal file
42
commands/config.md
Normal file
@@ -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
|
||||
```
|
||||
42
commands/disable.md
Normal file
42
commands/disable.md
Normal file
@@ -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 <guardian-name>
|
||||
/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}}
|
||||
```
|
||||
42
commands/enable.md
Normal file
42
commands/enable.md
Normal file
@@ -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 <guardian-name>
|
||||
/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}}
|
||||
```
|
||||
64
commands/init.md
Normal file
64
commands/init.md
Normal file
@@ -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
|
||||
```
|
||||
36
commands/protect.md
Normal file
36
commands/protect.md
Normal file
@@ -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 <pattern>
|
||||
/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}}
|
||||
```
|
||||
275
commands/split-markdown.md
Normal file
275
commands/split-markdown.md
Normal file
@@ -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 <file-path>
|
||||
|
||||
# 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-<basename>.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 `<filename>.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 `<filename>.backup`
|
||||
- Set to false to remove original after split
|
||||
|
||||
- **`create_index`** (default: true)
|
||||
- Generate `00-<basename>.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.
|
||||
43
commands/status.md
Normal file
43
commands/status.md
Normal file
@@ -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
|
||||
```
|
||||
33
commands/unprotect.md
Normal file
33
commands/unprotect.md
Normal file
@@ -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 <pattern>
|
||||
/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}}
|
||||
```
|
||||
50
hooks/hooks.json
Normal file
50
hooks/hooks.json
Normal file
@@ -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"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
85
plugin.lock.json
Normal file
85
plugin.lock.json
Normal file
@@ -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": []
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user