mirror of
https://github.com/boxpositron/absolute-dotfiles.git
synced 2026-02-28 03:30:37 +00:00
feat(opencode): add with-context custom commands for documentation management
- Add commands: setup-notes, sync-notes, ingest-notes, teleport-notes - Add commands: validate-notes-config, preview-notes-delegation - Add vault organization commands: analyze-vault, reorganize-notes - Update .withcontextconfig.jsonc with delegation patterns - Archive deprecated with-context.ts plugin
This commit is contained in:
David Ibia
294
.config/opencode/command/analyze-vault.md
Normal file
294
.config/opencode/command/analyze-vault.md
Normal file
@@ -0,0 +1,294 @@
|
||||
---
|
||||
description: Analyze vault structure and organization
|
||||
agent: general
|
||||
subtask: true
|
||||
---
|
||||
|
||||
# Analyze Vault Structure
|
||||
|
||||
This command performs a comprehensive analysis of your vault's structure, content, and organization. It scans all markdown files, extracts metadata, categorizes content, and identifies opportunities for improvement.
|
||||
|
||||
## What This Command Does
|
||||
|
||||
The vault analyzer performs deep structural analysis:
|
||||
|
||||
### Content Scanning
|
||||
|
||||
- Scans all markdown files in the project folder
|
||||
- Extracts frontmatter metadata (tags, dates, categories)
|
||||
- Analyzes headings hierarchy and structure
|
||||
- Identifies internal and external links
|
||||
- Extracts inline tags and keywords
|
||||
- Calculates file statistics (size, word count, etc.)
|
||||
|
||||
### Organization Analysis
|
||||
|
||||
- Categorizes files by type (guides, tutorials, reference, architecture, etc.)
|
||||
- Analyzes folder structure and depth
|
||||
- Identifies orphaned files (no incoming/outgoing links)
|
||||
- Detects naming patterns and conventions
|
||||
- Builds link graph showing connections between notes
|
||||
- Calculates organization health metrics
|
||||
|
||||
### Output Includes
|
||||
|
||||
- **Summary**: Total files, folders, size, and health score
|
||||
- **Folder Statistics**: File counts, average depth, naming patterns
|
||||
- **Categories**: Files grouped by content type with statistics
|
||||
- **Orphans**: Isolated files that could be better connected
|
||||
- **Link Analysis**: Most referenced files, broken links
|
||||
- **Recommendations**: Suggestions for improving organization
|
||||
|
||||
## Example Output
|
||||
|
||||
```
|
||||
=== Vault Structure Analysis ===
|
||||
|
||||
Project: my-awesome-project
|
||||
Total Files: 45 markdown files
|
||||
Total Size: 2.34 MB
|
||||
Health Score: 78/100
|
||||
|
||||
=== Folder Structure ===
|
||||
|
||||
docs/ (32 files, 1.8 MB)
|
||||
guides/ (12 files)
|
||||
tutorials/ (8 files)
|
||||
architecture/ (6 files)
|
||||
decisions/ (5 files)
|
||||
reference/ (6 files)
|
||||
|
||||
=== Content Categories ===
|
||||
|
||||
Guides (task-oriented): 12 files (26.7%)
|
||||
Tutorials (learning): 8 files (17.8%)
|
||||
Architecture (explanation): 11 files (24.4%)
|
||||
Reference (information): 6 files (13.3%)
|
||||
Uncategorized: 8 files (17.8%)
|
||||
|
||||
=== Orphaned Files ===
|
||||
|
||||
Found 4 orphaned files with no links:
|
||||
- docs/old-notes.md (0 incoming, 0 outgoing)
|
||||
- drafts/temp.md (0 incoming, 0 outgoing)
|
||||
- research/abandoned.md (1 outgoing, 0 incoming)
|
||||
|
||||
=== Link Analysis ===
|
||||
|
||||
Total Links: 234
|
||||
Internal: 198 (84.6%)
|
||||
External: 36 (15.4%)
|
||||
|
||||
Most Referenced Files:
|
||||
1. docs/architecture/overview.md (23 incoming links)
|
||||
2. docs/guides/quick-start.md (18 incoming links)
|
||||
3. README.md (15 incoming links)
|
||||
|
||||
=== Recommendations ===
|
||||
|
||||
1. Connect orphaned files or consider archiving
|
||||
2. Add more cross-references between guides and tutorials
|
||||
3. Create index files for large folders (guides/, reference/)
|
||||
4. Consider moving 3 files to more appropriate categories
|
||||
5. Standardize file naming (found mixed conventions)
|
||||
```
|
||||
|
||||
## Your Task
|
||||
|
||||
Execute the analyze_vault_structure tool immediately with options based on user arguments:
|
||||
|
||||
```javascript
|
||||
// Parse optional arguments
|
||||
const args = '$ARGUMENTS';
|
||||
const noCategories = args.includes('--no-categories');
|
||||
const noOrphans = args.includes('--no-orphans');
|
||||
const maxFilesMatch = args.match(/--max-files[=\s](\d+)/);
|
||||
const maxFiles = maxFilesMatch ? parseInt(maxFilesMatch[1]) : undefined;
|
||||
|
||||
const result = await analyze_vault_structure({
|
||||
include_categories: !noCategories,
|
||||
include_orphans: !noOrphans,
|
||||
max_file_size_mb: 10,
|
||||
max_files: maxFiles,
|
||||
exclude_patterns: ['drafts/*', '*.tmp', 'archive/*'],
|
||||
});
|
||||
|
||||
return result;
|
||||
```
|
||||
|
||||
**Usage Examples:**
|
||||
|
||||
- `/analyze-vault` - Full analysis with all features
|
||||
- `/analyze-vault --no-categories` - Skip content categorization
|
||||
- `/analyze-vault --no-orphans` - Skip orphan detection
|
||||
- `/analyze-vault --max-files 500` - Limit to 500 files
|
||||
|
||||
## Analysis Options
|
||||
|
||||
### exclude_patterns (optional)
|
||||
|
||||
Glob patterns for files/folders to skip:
|
||||
|
||||
```javascript
|
||||
exclude_patterns: ['drafts/*', '*.tmp', 'archive/*', '.trash/*'];
|
||||
```
|
||||
|
||||
### include_categories (optional, default: true)
|
||||
|
||||
Whether to categorize files by content type (guides, tutorials, reference, etc.):
|
||||
|
||||
```javascript
|
||||
include_categories: true; // Analyze and group by category
|
||||
include_categories: false; // Skip categorization
|
||||
```
|
||||
|
||||
### include_orphans (optional, default: true)
|
||||
|
||||
Whether to identify orphaned files with no links:
|
||||
|
||||
```javascript
|
||||
include_orphans: true; // Find isolated files
|
||||
include_orphans: false; // Skip orphan detection
|
||||
```
|
||||
|
||||
### max_file_size_mb (optional, default: 10)
|
||||
|
||||
Skip files larger than this size:
|
||||
|
||||
```javascript
|
||||
max_file_size_mb: 10; // Skip files over 10 MB
|
||||
```
|
||||
|
||||
### max_files (optional)
|
||||
|
||||
Limit total number of files analyzed (useful for large vaults):
|
||||
|
||||
```javascript
|
||||
max_files: 500; // Analyze first 500 files only
|
||||
```
|
||||
|
||||
## Understanding the Results
|
||||
|
||||
### Health Score (0-100)
|
||||
|
||||
Indicates overall vault organization quality:
|
||||
|
||||
- **90-100**: Excellent organization, consistent structure
|
||||
- **70-89**: Good organization, minor improvements possible
|
||||
- **50-69**: Moderate organization, several areas need attention
|
||||
- **Below 50**: Poor organization, significant restructuring recommended
|
||||
|
||||
### Categories
|
||||
|
||||
Files are classified using the Diátaxis framework:
|
||||
|
||||
- **Guides** (task-oriented): How-to documentation
|
||||
- **Tutorials** (learning-oriented): Step-by-step learning paths
|
||||
- **Reference** (information-oriented): API docs, specifications
|
||||
- **Architecture** (understanding-oriented): Design decisions, explanations
|
||||
- **Uncategorized**: Files that don't fit clear patterns
|
||||
|
||||
### Orphaned Files
|
||||
|
||||
Files with no connections to the rest of your vault:
|
||||
|
||||
- **No incoming links**: Nothing references this file
|
||||
- **No outgoing links**: This file doesn't reference others
|
||||
- **Both**: Completely isolated
|
||||
|
||||
Consider linking orphans or archiving if obsolete.
|
||||
|
||||
### Link Analysis
|
||||
|
||||
Shows how notes connect:
|
||||
|
||||
- **High incoming links**: Core reference documents
|
||||
- **High outgoing links**: Hub or index pages
|
||||
- **Broken links**: References to missing files
|
||||
|
||||
## Common Use Cases
|
||||
|
||||
### 1. Initial Vault Assessment
|
||||
|
||||
```javascript
|
||||
analyze_vault_structure({
|
||||
project_folder: 'my-project',
|
||||
include_categories: true,
|
||||
include_orphans: true,
|
||||
});
|
||||
```
|
||||
|
||||
Understand current state before reorganization.
|
||||
|
||||
### 2. Identify Cleanup Targets
|
||||
|
||||
```javascript
|
||||
analyze_vault_structure({
|
||||
project_folder: 'my-project',
|
||||
include_orphans: true,
|
||||
exclude_patterns: ['archive/*'],
|
||||
});
|
||||
```
|
||||
|
||||
Find files to archive or delete.
|
||||
|
||||
### 3. Verify Organization
|
||||
|
||||
```javascript
|
||||
analyze_vault_structure({
|
||||
project_folder: 'my-project',
|
||||
include_categories: true,
|
||||
});
|
||||
```
|
||||
|
||||
Check if files are properly categorized.
|
||||
|
||||
### 4. Performance Analysis
|
||||
|
||||
```javascript
|
||||
analyze_vault_structure({
|
||||
project_folder: 'large-project',
|
||||
max_files: 1000,
|
||||
max_file_size_mb: 5,
|
||||
});
|
||||
```
|
||||
|
||||
Analyze large vaults efficiently.
|
||||
|
||||
## Guidelines for Agents
|
||||
|
||||
When running this command:
|
||||
|
||||
1. **ONLY use the analyze_vault_structure tool** - Do NOT perform manual analysis
|
||||
2. **Present results clearly** - Show full output with key highlights
|
||||
3. **Explain findings** - Help user understand what the analysis means
|
||||
4. **Do NOT**:
|
||||
- Manually read files or scan directories
|
||||
- Parse markdown or extract metadata yourself
|
||||
- Build statistics or link graphs manually
|
||||
- The tool does everything automatically
|
||||
5. **Your role is to**:
|
||||
- Call the tool with appropriate parameters
|
||||
- Present and explain the results
|
||||
- Suggest next steps based on findings
|
||||
|
||||
## Next Steps After Analysis
|
||||
|
||||
Based on the analysis results:
|
||||
|
||||
1. **If orphans found**: Review and either link or archive them
|
||||
2. **If health score low**: Consider running `/reorganize-notes`
|
||||
3. **If categories mixed**: Move files to appropriate folders
|
||||
4. **If broken links**: Fix or remove invalid references
|
||||
5. **If naming inconsistent**: Standardize file names
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `/reorganize-notes` - Execute reorganization plan based on analysis
|
||||
- `/setup-notes` - Configure documentation architecture
|
||||
- `/validate-config` - Validate configuration
|
||||
- `/sync-notes` - Sync files between local and vault
|
||||
|
||||
---
|
||||
|
||||
_The analyze-vault-structure tool uses intelligent content analysis to provide actionable insights about your vault's organization and health._
|
||||
Reference in New Issue
Block a user