mirror of
https://github.com/boxpositron/absolute-dotfiles.git
synced 2026-02-28 11:40: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._
|
||||
99
.config/opencode/command/ingest-notes.md
Normal file
99
.config/opencode/command/ingest-notes.md
Normal file
@@ -0,0 +1,99 @@
|
||||
---
|
||||
description: Ingest local documentation files to Obsidian vault
|
||||
agent: general
|
||||
subtask: true
|
||||
---
|
||||
|
||||
# Ingest Notes
|
||||
|
||||
Scans the current project for documentation files based on `.withcontextconfig.jsonc` delegation rules and copies them to the Obsidian vault.
|
||||
|
||||
## What This Command Does
|
||||
|
||||
This command copies documentation files from your local project to the Obsidian vault:
|
||||
|
||||
- Scans project for files matching vault patterns in `.withcontextconfig.jsonc`
|
||||
- Copies matched files to vault preserving directory structure
|
||||
- Optionally deletes local files after successful copy
|
||||
- Provides dry-run preview mode
|
||||
|
||||
**Prerequisites:**
|
||||
|
||||
- `.withcontextconfig.jsonc` must exist (run `/setup-notes` first if not)
|
||||
- Configuration defines which files have delegation decision "vault"
|
||||
|
||||
## Your Task
|
||||
|
||||
Execute the ingest_notes tool immediately with dry-run by default for safety:
|
||||
|
||||
```javascript
|
||||
// Check for flags in arguments
|
||||
const args = '$ARGUMENTS';
|
||||
const shouldExecute = args.includes('--execute');
|
||||
const shouldDelete = args.includes('--delete');
|
||||
const forceDelete = args.includes('--force-delete');
|
||||
|
||||
const result = await ingest_notes({
|
||||
dry_run: !shouldExecute,
|
||||
delete_local_files: shouldDelete,
|
||||
force_delete: forceDelete,
|
||||
});
|
||||
|
||||
return result;
|
||||
```
|
||||
|
||||
**Usage:**
|
||||
|
||||
- `/ingest-notes` - Preview what will be copied (safe, dry-run mode)
|
||||
- `/ingest-notes --execute` - Copy files to vault (keeps local files)
|
||||
- `/ingest-notes --execute --delete` - Copy and delete local files
|
||||
- `/ingest-notes --execute --delete --force-delete` - Force delete even on errors
|
||||
|
||||
**Important:** Use `--delete` flag only if you want to remove local files after copying!
|
||||
|
||||
## Parameters
|
||||
|
||||
### dry_run (optional, default: false)
|
||||
|
||||
Preview mode - shows what will happen without making changes:
|
||||
|
||||
```javascript
|
||||
dry_run: true; // Preview only
|
||||
dry_run: false; // Execute for real
|
||||
```
|
||||
|
||||
### delete_local_files (optional, default: false)
|
||||
|
||||
Whether to delete local files after successful copy to vault:
|
||||
|
||||
```javascript
|
||||
delete_local_files: false; // Keep local files (default)
|
||||
delete_local_files: true; // Delete local files after copy
|
||||
```
|
||||
|
||||
### force_delete (optional, default: false)
|
||||
|
||||
Force deletion of local files even if some files had errors:
|
||||
|
||||
```javascript
|
||||
force_delete: false; // Don't delete if errors occurred (default)
|
||||
force_delete: true; // Delete even if some files failed
|
||||
```
|
||||
|
||||
## Important Notes
|
||||
|
||||
- **Local files are NOT deleted by default** - set `delete_local_files: true` explicitly if desired
|
||||
- **Always preview first** - Use `dry_run: true` before executing
|
||||
- **The tool automatically checks** for `.withcontextconfig.jsonc` existence
|
||||
- **Directory structure is preserved** in the vault
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `/setup-notes` - Create configuration file
|
||||
- `/preview-notes-delegation` - Preview which files will be ingested
|
||||
- `/sync-notes` - Bidirectional sync (moves files both ways)
|
||||
- `/validate-notes-config` - Validate configuration
|
||||
|
||||
---
|
||||
|
||||
_The ingest-notes tool copies local documentation to vault based on delegation rules._
|
||||
193
.config/opencode/command/preview-notes-delegation.md
Normal file
193
.config/opencode/command/preview-notes-delegation.md
Normal file
@@ -0,0 +1,193 @@
|
||||
---
|
||||
description: Preview which documentation files will be delegated to vault vs local
|
||||
agent: general
|
||||
subtask: true
|
||||
---
|
||||
|
||||
# Preview Notes Delegation
|
||||
|
||||
Previews which files in your project will be delegated to the Obsidian vault versus kept in the local repository based on `.withcontextconfig.jsonc` patterns.
|
||||
|
||||
## What This Command Does
|
||||
|
||||
This command analyzes your project files and shows delegation decisions **before** performing any sync operations:
|
||||
|
||||
**Analysis Features:**
|
||||
|
||||
1. **File Discovery** - Scans project for documentation files matching patterns
|
||||
2. **Delegation Decision** - Applies configuration rules to determine vault vs local
|
||||
3. **Categorization** - Groups files by destination (vault/local)
|
||||
4. **Reasoning** - Optionally shows why each file was categorized
|
||||
5. **Filtering** - Can show only vault files or only local files
|
||||
|
||||
**Prerequisites:**
|
||||
|
||||
- `.withcontextconfig.jsonc` must exist (run `/setup-notes` first if not)
|
||||
|
||||
**Tool Priority:**
|
||||
First try to use the WithContext plugin's `preview_delegation` tool. If not available, fallback to the with-context MCP server's `preview_delegation` tool.
|
||||
|
||||
## Your Task
|
||||
|
||||
Execute the preview_delegation tool immediately with options based on user arguments:
|
||||
|
||||
```javascript
|
||||
// Parse optional arguments
|
||||
const args = '$ARGUMENTS';
|
||||
const vaultOnly = args.includes('--vault-only');
|
||||
const localOnly = args.includes('--local-only');
|
||||
const noReasoning = args.includes('--no-reasoning');
|
||||
const limitMatch = args.match(/--limit[=\s](\d+)/);
|
||||
const limit = limitMatch ? parseInt(limitMatch[1]) : 100;
|
||||
|
||||
const result = await preview_delegation({
|
||||
project_root: process.cwd(),
|
||||
show_reasoning: !noReasoning,
|
||||
limit: limit,
|
||||
vault_only: vaultOnly,
|
||||
local_only: localOnly,
|
||||
});
|
||||
|
||||
return result;
|
||||
```
|
||||
|
||||
**Usage Examples:**
|
||||
|
||||
- `/preview-notes-delegation` - Full preview with reasoning
|
||||
- `/preview-notes-delegation --vault-only` - Show only vault files
|
||||
- `/preview-notes-delegation --local-only` - Show only local files
|
||||
- `/preview-notes-delegation --limit 20` - Limit to 20 files per category
|
||||
- `/preview-notes-delegation --no-reasoning` - Hide detailed reasoning
|
||||
|
||||
## Optional Parameters
|
||||
|
||||
The user can customize the preview with flags:
|
||||
|
||||
**`--vault-only`** - Show only files going to vault
|
||||
|
||||
```javascript
|
||||
preview_delegation({
|
||||
project_root: '/path/to/project',
|
||||
vault_only: true,
|
||||
});
|
||||
```
|
||||
|
||||
**`--local-only`** - Show only files staying local
|
||||
|
||||
```javascript
|
||||
preview_delegation({
|
||||
project_root: '/path/to/project',
|
||||
local_only: true,
|
||||
});
|
||||
```
|
||||
|
||||
**`--limit N`** - Limit results per category (default: 100)
|
||||
|
||||
```javascript
|
||||
preview_delegation({
|
||||
project_root: '/path/to/project',
|
||||
limit: 20,
|
||||
});
|
||||
```
|
||||
|
||||
**`--no-reasoning`** - Hide reasoning details
|
||||
|
||||
```javascript
|
||||
preview_delegation({
|
||||
project_root: '/path/to/project',
|
||||
show_reasoning: false,
|
||||
});
|
||||
```
|
||||
|
||||
## Example Output
|
||||
|
||||
```
|
||||
================================================================================
|
||||
DELEGATION PREVIEW
|
||||
================================================================================
|
||||
|
||||
Configuration: /path/to/project/.withcontextconfig.jsonc
|
||||
Total files: 23
|
||||
• Vault: 15
|
||||
• Local: 8
|
||||
|
||||
--------------------------------------------------------------------------------
|
||||
FILES TO DELEGATE TO VAULT (15 total, showing 15)
|
||||
--------------------------------------------------------------------------------
|
||||
|
||||
→ docs/guides/getting-started.md
|
||||
Reason: Matches vault pattern 'docs/guides/**'
|
||||
→ docs/tutorials/installation.md
|
||||
Reason: Matches vault pattern 'docs/tutorials/**'
|
||||
→ CHANGELOG.md
|
||||
Reason: Matches vault pattern 'CHANGELOG.md'
|
||||
→ docs/architecture/decisions/001-use-typescript.md
|
||||
Reason: Matches vault pattern 'docs/architecture/**'
|
||||
|
||||
... and 11 more files
|
||||
|
||||
--------------------------------------------------------------------------------
|
||||
FILES TO KEEP LOCAL (8 total, showing 8)
|
||||
--------------------------------------------------------------------------------
|
||||
|
||||
[OK] README.md
|
||||
Reason: Matches local pattern 'README.md'
|
||||
[OK] CONTRIBUTING.md
|
||||
Reason: Matches local pattern 'CONTRIBUTING.md'
|
||||
[OK] src/utils/README.md
|
||||
Reason: Matches local pattern 'src/**/*.md'
|
||||
[OK] tests/fixtures/sample.md
|
||||
Reason: Matches local pattern 'tests/**/*.md'
|
||||
|
||||
... and 4 more files
|
||||
|
||||
================================================================================
|
||||
```
|
||||
|
||||
## Important
|
||||
|
||||
- **Execute autonomously** - Parse user flags and call the tool with correct parameters
|
||||
- **No file modifications** - This is a preview-only command (safe to run anytime)
|
||||
- **Trust the tool output** - Delegation logic is comprehensive
|
||||
- **Show full preview** - Don't truncate unless using --limit flag
|
||||
- **DO NOT manually scan** directories - rely entirely on the tool
|
||||
|
||||
## Use Cases
|
||||
|
||||
**Before first sync:**
|
||||
|
||||
```
|
||||
/preview-notes-delegation
|
||||
```
|
||||
|
||||
Verify patterns work as expected before moving files.
|
||||
|
||||
**Testing new patterns:**
|
||||
After editing `.withcontextconfig.jsonc`, preview to verify changes.
|
||||
|
||||
**Debugging delegation:**
|
||||
|
||||
```
|
||||
/preview-notes-delegation --vault-only
|
||||
```
|
||||
|
||||
See only files that will be moved to vault.
|
||||
|
||||
**Quick summary:**
|
||||
|
||||
```
|
||||
/preview-notes-delegation --limit 10 --no-reasoning
|
||||
```
|
||||
|
||||
Get a quick overview without detailed reasoning.
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `/validate-notes-config` - Validate configuration before previewing
|
||||
- `/setup-notes` - Create or regenerate configuration
|
||||
- `/sync-notes` - Perform actual synchronization after previewing
|
||||
- `/ingest-notes` - Move files to vault after previewing
|
||||
|
||||
---
|
||||
|
||||
_The preview-notes-delegation command helps you test and verify delegation patterns before making any file changes._
|
||||
623
.config/opencode/command/reorganize-notes.md
Normal file
623
.config/opencode/command/reorganize-notes.md
Normal file
@@ -0,0 +1,623 @@
|
||||
---
|
||||
description: Reorganize vault with AI-assisted suggestions
|
||||
agent: general
|
||||
subtask: true
|
||||
---
|
||||
|
||||
# Reorganize Notes
|
||||
|
||||
This command executes a comprehensive vault reorganization based on an intelligent organization plan. It supports moving and renaming files with automatic link updates, dry-run preview, rollback capability, and safety checks.
|
||||
|
||||
## Quick Start (Ideal Workflow)
|
||||
|
||||
This command generates and executes vault reorganization plans instantly using presets:
|
||||
|
||||
```javascript
|
||||
// Check for preset and execution flags
|
||||
const args = '$ARGUMENTS';
|
||||
const shouldExecute = args.includes('--execute');
|
||||
const presetMatch = args.match(/--preset[=\s](\w+)/);
|
||||
const preset = presetMatch ? presetMatch[1] : 'clean';
|
||||
const minConfMatch = args.match(/--min-confidence[=\s](0\.\d+)/);
|
||||
const minConfidence = minConfMatch ? parseFloat(minConfMatch[1]) : 0.7;
|
||||
|
||||
// Generate organization plan with preset
|
||||
const planResult = await generate_organization_plan({
|
||||
preset_id: preset,
|
||||
min_confidence: minConfidence,
|
||||
});
|
||||
|
||||
// Parse plan from result
|
||||
const planData = JSON.parse(planResult);
|
||||
const plan = planData.plan;
|
||||
|
||||
// Execute reorganization (dry-run by default for safety)
|
||||
const result = await reorganize_notes({
|
||||
plan: plan,
|
||||
dry_run: !shouldExecute,
|
||||
update_links: true,
|
||||
create_backup: true,
|
||||
min_confidence: minConfidence,
|
||||
});
|
||||
|
||||
return result;
|
||||
```
|
||||
|
||||
**Usage:**
|
||||
|
||||
- `/reorganize-notes` - Preview with 'clean' preset (dry-run)
|
||||
- `/reorganize-notes --execute` - Execute with 'clean' preset
|
||||
- `/reorganize-notes --preset minimal` - Preview with 'minimal' preset
|
||||
- `/reorganize-notes --preset docs-as-code --execute` - Execute with custom preset
|
||||
- `/reorganize-notes --min-confidence 0.9` - Use higher confidence threshold
|
||||
|
||||
**Available Presets:**
|
||||
|
||||
- `clean` (default) - Moves docs to vault, keeps README/LICENSE local
|
||||
- `minimal` - Keep most local, only move ADRs and research
|
||||
- `docs-as-code` - Mirrors repository structure in vault
|
||||
- `research` - Heavy vault usage with cross-linking
|
||||
|
||||
## What This Command Does
|
||||
|
||||
The vault reorganizer performs safe, intelligent file operations:
|
||||
|
||||
### Reorganization Operations
|
||||
|
||||
- **Move**: Relocate files to more appropriate folders
|
||||
- **Rename**: Standardize file naming conventions
|
||||
- **Both**: Move and rename simultaneously
|
||||
- **Link Updates**: Automatically fix all references to moved/renamed files
|
||||
- **Validation**: Check for conflicts and potential issues before execution
|
||||
|
||||
### Safety Features
|
||||
|
||||
- **Dry-Run Mode**: Preview all operations without making changes (enabled by default)
|
||||
- **Confidence Filtering**: Only execute high-confidence suggestions
|
||||
- **Automatic Backups**: Create backups before modifying files (optional)
|
||||
- **Rollback Support**: Undo operations if something goes wrong
|
||||
- **Link Integrity**: Ensure no links break during reorganization
|
||||
- **Impact Assessment**: Show affected files and potential issues
|
||||
|
||||
### Workflow
|
||||
|
||||
1. **Analyze** → Run `/analyze-vault` to understand current structure
|
||||
2. **Plan** → Create reorganization plan (manual or AI-generated)
|
||||
3. **Preview** → Run with `dry_run: true` to see what will happen
|
||||
4. **Execute** → Run with `dry_run: false` to apply changes
|
||||
5. **Verify** → Check results and ensure links are intact
|
||||
|
||||
## Example Output
|
||||
|
||||
### Dry-Run Preview
|
||||
|
||||
```
|
||||
=== Vault Reorganization (DRY RUN) ===
|
||||
|
||||
Project: my-project
|
||||
Plan: 12 operations (8 moves, 4 renames)
|
||||
Confidence Threshold: 0.7
|
||||
|
||||
=== Operations to Execute ===
|
||||
|
||||
1. MOVE docs/random-notes.md → docs/guides/getting-started.md
|
||||
Reason: Content is a task-oriented guide
|
||||
Confidence: 0.92
|
||||
Impact: 3 files will need link updates
|
||||
|
||||
2. RENAME docs/guide.md → docs/guides/api-guide.md
|
||||
Reason: Standardize naming convention
|
||||
Confidence: 0.85
|
||||
Impact: 5 files will need link updates
|
||||
|
||||
3. MOVE docs/architecture-notes.md → docs/architecture/decisions/001-database-choice.md
|
||||
Reason: Fits ADR format
|
||||
Confidence: 0.88
|
||||
Impact: 2 files will need link updates
|
||||
|
||||
... (9 more operations)
|
||||
|
||||
=== Impact Summary ===
|
||||
|
||||
Total Operations: 12
|
||||
Files to Move: 8
|
||||
Files to Rename: 4
|
||||
Links to Update: 47 across 23 files
|
||||
Estimated Duration: 5 seconds
|
||||
Risky Operations: 0
|
||||
|
||||
=== Warnings ===
|
||||
|
||||
⚠️ WARNING: File "docs/old-guide.md" is referenced by external projects
|
||||
Suggestion: Update external references manually after reorganization
|
||||
|
||||
✓ All operations passed validation checks
|
||||
✓ No conflicts detected
|
||||
✓ Link integrity will be maintained
|
||||
|
||||
=== Next Steps ===
|
||||
|
||||
To execute this plan, run:
|
||||
reorganize_notes({ ..., dry_run: false })
|
||||
|
||||
IMPORTANT: Dry-run mode is ENABLED by default for safety!
|
||||
```
|
||||
|
||||
### Execution Results
|
||||
|
||||
```
|
||||
=== Vault Reorganization Complete ===
|
||||
|
||||
Project: my-project
|
||||
Mode: EXECUTION (changes applied)
|
||||
|
||||
=== Operations Executed ===
|
||||
|
||||
✓ Moved docs/random-notes.md → docs/guides/getting-started.md
|
||||
Updated 3 links in other files
|
||||
✓ Renamed docs/guide.md → docs/guides/api-guide.md
|
||||
Updated 5 links in other files
|
||||
✓ Moved docs/architecture-notes.md → docs/architecture/decisions/001-database-choice.md
|
||||
Updated 2 links in other files
|
||||
|
||||
... (9 more successful operations)
|
||||
|
||||
=== Summary ===
|
||||
|
||||
Total Operations: 12
|
||||
Successful: 12 (100%)
|
||||
Failed: 0
|
||||
Links Updated: 47 across 23 files
|
||||
Duration: 3.2 seconds
|
||||
|
||||
✓ All operations completed successfully
|
||||
✓ All links updated and verified
|
||||
✓ No broken links detected
|
||||
```
|
||||
|
||||
## Your Task
|
||||
|
||||
Execute the reorganization workflow immediately with instant preset-based planning:
|
||||
|
||||
The command generates a plan and executes it in one call, with dry-run by default for safety.
|
||||
|
||||
See "Quick Start" section above for the complete implementation.
|
||||
|
||||
**Important Notes:**
|
||||
|
||||
- Always preview first (dry-run mode is the default)
|
||||
- Use `--execute` flag to apply changes
|
||||
- Backups are created automatically when executing
|
||||
- Links are updated automatically to prevent breakage
|
||||
|
||||
## Alternative: Manual Plan (Advanced)
|
||||
|
||||
If you need custom organization beyond presets, you can create a manual plan. See full documentation for plan structure format.
|
||||
|
||||
**Still follow the same workflow: Generate → Preview → Confirm → Execute**
|
||||
|
||||
---
|
||||
|
||||
## Advanced: Create Manual Plan
|
||||
|
||||
Based on the analysis, create a reorganization plan manually. The plan structure:
|
||||
|
||||
```javascript
|
||||
{
|
||||
suggestions: [
|
||||
{
|
||||
type: "move", // or "rename" or "both"
|
||||
currentPath: "docs/random-file.md",
|
||||
suggestedPath: "docs/guides/proper-location.md", // for move
|
||||
suggestedName: "standardized-name.md", // for rename
|
||||
reason: "Content is a task-oriented guide",
|
||||
confidence: 0.92, // 0-1 scale
|
||||
impact: {
|
||||
affectedFiles: 3,
|
||||
linksToUpdate: 5,
|
||||
potentialBrokenLinks: [],
|
||||
complexity: "low" // or "medium", "high"
|
||||
},
|
||||
targetCategory: "guides"
|
||||
},
|
||||
// ... more suggestions
|
||||
],
|
||||
estimatedImpact: {
|
||||
filesToMove: 8,
|
||||
filesToRename: 4,
|
||||
linksToUpdate: 47,
|
||||
filesRequiringLinkUpdates: 23,
|
||||
estimatedDuration: 5, // seconds
|
||||
hasRiskyOperations: false
|
||||
},
|
||||
warnings: [
|
||||
{
|
||||
severity: "warning",
|
||||
filePath: "docs/old-guide.md",
|
||||
message: "File is referenced by external projects",
|
||||
suggestion: "Update external references manually"
|
||||
}
|
||||
],
|
||||
summary: "Reorganize 12 files to improve vault structure",
|
||||
requiresManualReview: false
|
||||
}
|
||||
```
|
||||
|
||||
### Step 3: Preview & Execute
|
||||
|
||||
**ALWAYS preview first!** Then get user confirmation before executing:
|
||||
|
||||
```javascript
|
||||
// Preview
|
||||
const preview = await reorganize_notes({
|
||||
project_folder: 'my-project',
|
||||
plan: manualPlan,
|
||||
dry_run: true, // CRITICAL: Preview first!
|
||||
update_links: true,
|
||||
create_backup: true,
|
||||
min_confidence: 0.7,
|
||||
});
|
||||
|
||||
// Show preview to user, get confirmation
|
||||
|
||||
// Execute (only after user confirms)
|
||||
const result = await reorganize_notes({
|
||||
project_folder: 'my-project',
|
||||
plan: manualPlan,
|
||||
dry_run: false,
|
||||
update_links: true,
|
||||
create_backup: true,
|
||||
min_confidence: 0.7,
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Safety Requirements
|
||||
|
||||
**⚠️ CRITICAL SAFETY RULES ⚠️**
|
||||
|
||||
1. **NEVER** execute with `dry_run: false` without explicit user confirmation!
|
||||
|
||||
2. **ALWAYS** run dry-run preview first
|
||||
3. **ALWAYS** show user the preview results including:
|
||||
- Number of operations (moves, renames)
|
||||
- Files that will be affected
|
||||
- Links that will be updated
|
||||
- Any warnings or risks
|
||||
4. **ALWAYS** ask user for explicit confirmation:
|
||||
|
||||
**User Confirmation Template:**
|
||||
|
||||
> "I've previewed the reorganization plan using the **[preset_name]** preset. Here's what will happen:
|
||||
>
|
||||
> **Operations:**
|
||||
>
|
||||
> - Move X files to appropriate folders
|
||||
> - Rename Y files for consistency
|
||||
> - Update Z links across N files
|
||||
>
|
||||
> **Key Changes:**
|
||||
> [Show 3-5 most significant operations]
|
||||
>
|
||||
> **Safety:**
|
||||
>
|
||||
> - ✓ Backups will be created
|
||||
> - ✓ Links will be automatically updated
|
||||
> - ✓ Rollback available if needed
|
||||
>
|
||||
> **This operation will modify your vault!**
|
||||
>
|
||||
> Do you want to proceed with the reorganization? (yes/no)"
|
||||
|
||||
Only if user confirms "yes", then execute:
|
||||
|
||||
```javascript
|
||||
reorganize_notes({
|
||||
project_folder: 'my-project',
|
||||
plan: {
|
||||
/* same plan */
|
||||
},
|
||||
dry_run: false, // Execute for real
|
||||
update_links: true,
|
||||
create_backup: true,
|
||||
min_confidence: 0.7,
|
||||
});
|
||||
```
|
||||
|
||||
### Step 5: Verify Results
|
||||
|
||||
After execution, verify the results:
|
||||
|
||||
- Show summary of operations
|
||||
- Confirm all links updated successfully
|
||||
- Report any failures or warnings
|
||||
- Suggest running `/analyze-vault` again to verify improvements
|
||||
|
||||
## Plan Structure Details
|
||||
|
||||
### Suggestion Object
|
||||
|
||||
Each suggestion must include:
|
||||
|
||||
- **type**: `"move"`, `"rename"`, or `"both"`
|
||||
- **currentPath**: Current file path (relative to vault root)
|
||||
- **suggestedPath**: New path for move operations (optional)
|
||||
- **suggestedName**: New name for rename operations (optional)
|
||||
- **reason**: Why this change is suggested (human-readable)
|
||||
- **confidence**: Score from 0.0 to 1.0 (higher = more confident)
|
||||
- **impact**: Assessment of operation impact (optional but recommended)
|
||||
- **targetCategory**: Target category after reorganization (optional)
|
||||
|
||||
### Impact Assessment
|
||||
|
||||
- **affectedFiles**: How many files reference this file
|
||||
- **linksToUpdate**: How many links will need updating
|
||||
- **potentialBrokenLinks**: Paths that might break
|
||||
- **complexity**: `"low"`, `"medium"`, or `"high"`
|
||||
|
||||
### Confidence Scoring
|
||||
|
||||
- **0.9-1.0**: Very high confidence, safe to auto-execute
|
||||
- **0.7-0.9**: High confidence, review recommended
|
||||
- **0.5-0.7**: Medium confidence, manual review required
|
||||
- **Below 0.5**: Low confidence, skip unless manually approved
|
||||
|
||||
Use `min_confidence` parameter to filter operations.
|
||||
|
||||
## Safety Parameters
|
||||
|
||||
### dry_run (default: true)
|
||||
|
||||
**ALWAYS TRUE BY DEFAULT FOR SAFETY!**
|
||||
|
||||
```javascript
|
||||
dry_run: true; // Preview only, no changes (DEFAULT)
|
||||
dry_run: false; // Execute for real (requires confirmation!)
|
||||
```
|
||||
|
||||
### update_links (default: true)
|
||||
|
||||
```javascript
|
||||
update_links: true; // Fix all links automatically (recommended)
|
||||
update_links: false; // Don't update links (may break references)
|
||||
```
|
||||
|
||||
### create_backup (default: true)
|
||||
|
||||
```javascript
|
||||
create_backup: true; // Create backups before changes (recommended)
|
||||
create_backup: false; // Skip backups (faster but riskier)
|
||||
```
|
||||
|
||||
### min_confidence (default: 0.7)
|
||||
|
||||
```javascript
|
||||
min_confidence: 0.7; // Only execute high-confidence operations
|
||||
min_confidence: 0.5; // Include medium-confidence operations
|
||||
min_confidence: 0.9; // Only very high-confidence operations
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### ✅ DO:
|
||||
|
||||
1. **Use presets** - Start with `generate_organization_plan` and a preset
|
||||
2. **Preview first** - Always run with `dry_run: true` before executing
|
||||
3. **Get confirmation** - Show user the preview and wait for approval
|
||||
4. **Enable backups** - Keep `create_backup: true` (default)
|
||||
5. **Update links** - Keep `update_links: true` (default) to maintain integrity
|
||||
6. **Start conservative** - Use `min_confidence: 0.8` or higher for first run
|
||||
7. **Test incrementally** - Start with a small subset if unsure
|
||||
|
||||
### ❌ DON'T:
|
||||
|
||||
1. **Don't skip dry-run** - Never execute without previewing first
|
||||
2. **Don't ignore warnings** - Review and address all warnings in the plan
|
||||
3. **Don't disable backups** - Always keep backups enabled unless very confident
|
||||
4. **Don't rush execution** - Give user time to review preview
|
||||
5. **Don't skip link updates** - Links will break if you don't update them
|
||||
6. **Don't use low confidence** - Avoid `min_confidence < 0.7` unless you've reviewed manually
|
||||
|
||||
### Ideal Workflow Summary:
|
||||
|
||||
```
|
||||
generate_organization_plan (preset)
|
||||
→ reorganize_notes (dry_run=true)
|
||||
→ SHOW TO USER + GET CONFIRMATION
|
||||
→ reorganize_notes (dry_run=false)
|
||||
```
|
||||
|
||||
## Example Usage Scenarios
|
||||
|
||||
### Scenario 1: Quick Reorganization with Preset (RECOMMENDED)
|
||||
|
||||
```javascript
|
||||
// Single command generates smart plan
|
||||
const plan = await generate_organization_plan({
|
||||
project_folder: 'my-project',
|
||||
preset_id: 'clean',
|
||||
min_confidence: 0.8,
|
||||
});
|
||||
|
||||
// Preview
|
||||
const preview = await reorganize_notes({
|
||||
project_folder: 'my-project',
|
||||
plan: plan,
|
||||
dry_run: true,
|
||||
});
|
||||
|
||||
// [Show to user, get confirmation]
|
||||
|
||||
// Execute
|
||||
const result = await reorganize_notes({
|
||||
project_folder: 'my-project',
|
||||
plan: plan,
|
||||
dry_run: false, // Only after user confirms!
|
||||
});
|
||||
```
|
||||
|
||||
### Scenario 2: Conservative Reorganization
|
||||
|
||||
```javascript
|
||||
// Only execute very high-confidence operations
|
||||
await reorganize_notes({
|
||||
project_folder: 'my-project',
|
||||
plan: plan,
|
||||
dry_run: false,
|
||||
min_confidence: 0.9, // Very conservative
|
||||
create_backup: true, // Extra safety
|
||||
update_links: true,
|
||||
});
|
||||
```
|
||||
|
||||
### Scenario 3: Targeted Reorganization
|
||||
|
||||
```javascript
|
||||
// Move specific files to better locations
|
||||
const plan = {
|
||||
suggestions: [
|
||||
{
|
||||
type: 'move',
|
||||
currentPath: 'docs/random-notes.md',
|
||||
suggestedPath: 'docs/guides/getting-started.md',
|
||||
reason: 'Content is a getting started guide',
|
||||
confidence: 0.95,
|
||||
impact: { complexity: 'low' },
|
||||
},
|
||||
{
|
||||
type: 'rename',
|
||||
currentPath: 'docs/guide.md',
|
||||
suggestedName: 'api-guide.md',
|
||||
reason: 'Standardize naming',
|
||||
confidence: 0.9,
|
||||
impact: { complexity: 'low' },
|
||||
},
|
||||
],
|
||||
summary: 'Move and rename 2 files',
|
||||
};
|
||||
```
|
||||
|
||||
## Guidelines for Agents
|
||||
|
||||
When running this command:
|
||||
|
||||
1. **ALWAYS follow the workflow**:
|
||||
- Analyze → Plan → Preview → Confirm → Execute → Verify
|
||||
2. **NEVER skip dry-run preview**:
|
||||
- Always show user what will happen before executing
|
||||
3. **NEVER execute without confirmation**:
|
||||
- Explicitly ask user to confirm before `dry_run: false`
|
||||
4. **Present clear summaries**:
|
||||
- Show what operations will be performed
|
||||
- Explain impact and risks
|
||||
- Highlight warnings
|
||||
5. **Do NOT**:
|
||||
- Move or rename files manually
|
||||
- Update links yourself
|
||||
- Skip validation steps
|
||||
- Execute destructive operations without permission
|
||||
6. **Your role is to**:
|
||||
- Orchestrate the workflow safely
|
||||
- Present information clearly
|
||||
- Protect user from mistakes
|
||||
- Ensure vault integrity
|
||||
|
||||
## Safety Reminders
|
||||
|
||||
### ⚠️ CRITICAL SAFETY RULES ⚠️
|
||||
|
||||
1. **Dry-run is DEFAULT**: `dry_run: true` unless explicitly set to `false`
|
||||
2. **Always preview first**: Show user dry-run results before executing
|
||||
3. **Require confirmation**: Never execute with `dry_run: false` without asking
|
||||
4. **Backups recommended**: Keep `create_backup: true` unless user explicitly disables
|
||||
5. **Link integrity**: Keep `update_links: true` to prevent broken references
|
||||
6. **Test with low confidence**: Start with `min_confidence: 0.9` for first run
|
||||
|
||||
### What Can Go Wrong?
|
||||
|
||||
- **Broken links**: If `update_links: false`, references will break
|
||||
- **Lost files**: If backups disabled and operation fails mid-way
|
||||
- **Name conflicts**: Moving to path that already exists
|
||||
- **External references**: Links from outside the vault won't be updated
|
||||
|
||||
## Common Reorganization Patterns
|
||||
|
||||
### Pattern 1: Category-Based Organization
|
||||
|
||||
Move files to folders by content type:
|
||||
|
||||
```
|
||||
docs/
|
||||
guides/ # Task-oriented how-to docs
|
||||
tutorials/ # Learning-oriented step-by-step
|
||||
reference/ # Information-oriented API docs
|
||||
architecture/ # Understanding-oriented design docs
|
||||
decisions/ # ADRs (Architecture Decision Records)
|
||||
```
|
||||
|
||||
### Pattern 2: Feature-Based Organization
|
||||
|
||||
Group by project feature or module:
|
||||
|
||||
```
|
||||
docs/
|
||||
auth/ # Authentication docs
|
||||
database/ # Database docs
|
||||
api/ # API docs
|
||||
deployment/ # Deployment docs
|
||||
```
|
||||
|
||||
### Pattern 3: Audience-Based Organization
|
||||
|
||||
Organize by reader type:
|
||||
|
||||
```
|
||||
docs/
|
||||
users/ # End-user documentation
|
||||
developers/ # Developer guides
|
||||
operators/ # Operations/deployment docs
|
||||
contributors/ # Contribution guides
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
The tool handles errors gracefully:
|
||||
|
||||
- **Conflict detection**: Prevents overwriting existing files
|
||||
- **Rollback support**: Reverts changes if operation fails mid-way
|
||||
- **Partial success**: Reports which operations succeeded/failed
|
||||
- **Link validation**: Verifies no links broke after reorganization
|
||||
|
||||
If errors occur:
|
||||
|
||||
1. Check the error messages for details
|
||||
2. Review the failed operations list
|
||||
3. Fix conflicts manually if needed
|
||||
4. Re-run with adjusted plan
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `/analyze-vault` - Analyze vault structure before reorganizing
|
||||
- `/setup-notes` - Configure documentation architecture
|
||||
- `/validate-config` - Validate configuration
|
||||
- `/sync-notes` - Sync files after reorganization
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
Large reorganizations may take time:
|
||||
|
||||
- **Small vaults** (< 100 files): Nearly instant
|
||||
- **Medium vaults** (100-500 files): Few seconds
|
||||
- **Large vaults** (500+ files): 10-30 seconds
|
||||
- **Very large vaults** (1000+ files): 30-60 seconds
|
||||
|
||||
Link updates are the slowest part. Consider:
|
||||
|
||||
- Batch similar operations together
|
||||
- Use `max_files` in analysis to limit scope
|
||||
- Run during off-hours for very large vaults
|
||||
|
||||
---
|
||||
|
||||
_The reorganize-notes tool provides safe, intelligent vault reorganization with automatic link updates, dry-run preview, and rollback support to maintain vault integrity._
|
||||
300
.config/opencode/command/setup-notes.md
Normal file
300
.config/opencode/command/setup-notes.md
Normal file
@@ -0,0 +1,300 @@
|
||||
---
|
||||
description: Intelligently analyze and setup documentation architecture for the project
|
||||
agent: general
|
||||
subtask: true
|
||||
---
|
||||
|
||||
# Intelligent Documentation Setup
|
||||
|
||||
**NEW in v2.1**: This command now uses intelligent analysis to understand your project and recommend optimal documentation architecture based on best practices!
|
||||
|
||||
## What This Command Does
|
||||
|
||||
This enhanced command performs a **4-phase intelligent analysis**:
|
||||
|
||||
### Phase 1: Repository Analysis
|
||||
|
||||
- Scans your project to identify all documentation files
|
||||
- Detects project type (MCP server, library, monorepo, CLI, web app, etc.)
|
||||
- Catalogs existing documentation patterns and folders
|
||||
- Identifies framework (React, Next.js, Express, etc.)
|
||||
|
||||
### Phase 2: README Validation
|
||||
|
||||
- Analyzes README.md completeness and health (0-100 score)
|
||||
- Validates all markdown links to ensure they won't break
|
||||
- Checks for self-containment (README must work without vault access)
|
||||
- Identifies missing sections (badges, quick start, installation, usage)
|
||||
- **Ensures README links won't point to files that will move to vault**
|
||||
|
||||
### Phase 3: Intelligent Recommendations
|
||||
|
||||
- Recommends LOCAL vs VAULT delegation based on:
|
||||
- **Diátaxis framework** (tutorials, guides, reference, explanation)
|
||||
- Project type and structure
|
||||
- Best practices for documentation organization
|
||||
- **LOCAL (Repository)**: Essential files that must work without vault
|
||||
- README.md, CONTRIBUTING.md, LICENSE, AGENTS.md
|
||||
- Inline code documentation (src/\*\*/\*.md)
|
||||
- Quick references and getting started guides
|
||||
- **VAULT (Obsidian)**: Deep research and detailed exploration
|
||||
- Detailed guides and tutorials
|
||||
- Architecture Decision Records (ADRs)
|
||||
- Research notes and investigations
|
||||
- Meeting notes and explorations
|
||||
|
||||
### Phase 4: Configuration & Setup
|
||||
|
||||
- Creates intelligent `.withcontextconfig.jsonc` based on analysis
|
||||
- Suggests vault folder structure (docs/guides, docs/architecture, etc.)
|
||||
- Provides actionable next steps and README fixes
|
||||
- Optionally creates recommended folder structure in vault
|
||||
|
||||
## Documentation Delegation Philosophy
|
||||
|
||||
### LOCAL = Essential & Quick Reference
|
||||
|
||||
**Purpose**: Files critical for onboarding and getting started, must work without vault
|
||||
|
||||
**Examples**:
|
||||
|
||||
- README.md - Project overview, badges, installation, quick start
|
||||
- CONTRIBUTING.md - How to contribute
|
||||
- LICENSE - Legal requirements
|
||||
- src/\*\*/\*.md - Inline code documentation
|
||||
- Quick reference guides (1-2 pages)
|
||||
|
||||
**Key Rule**: README must be **self-contained** - no broken links to vault files!
|
||||
|
||||
### VAULT = Deep Research & Exploration
|
||||
|
||||
**Purpose**: Detailed exploration, architecture decisions, research notes
|
||||
|
||||
**Examples**:
|
||||
|
||||
- docs/guides/\*\* - Detailed how-to guides (task-oriented)
|
||||
- docs/tutorials/\*\* - Step-by-step learning paths (learning-oriented)
|
||||
- docs/architecture/\*\* - Architecture docs and ADRs (understanding-oriented)
|
||||
- docs/reference/\*\* - API documentation (information-oriented)
|
||||
- docs/research/\*\* - Research notes and investigations
|
||||
- CHANGELOG.md - Detailed change history
|
||||
|
||||
## Example Output
|
||||
|
||||
```
|
||||
=== Intelligent Documentation Setup ===
|
||||
|
||||
✓ No existing configuration found
|
||||
|
||||
📊 Analyzing repository documentation...
|
||||
|
||||
=== Documentation Analysis ===
|
||||
|
||||
Project: my-awesome-project
|
||||
Type: library
|
||||
Total Docs: 15 files
|
||||
|
||||
✓ README.md (234 lines)
|
||||
Health Score: 75/100
|
||||
Links: 8 total
|
||||
⚠ 2 warning(s)
|
||||
|
||||
=== README Health Report ===
|
||||
|
||||
Health Score: 75/100
|
||||
✓ Has badges
|
||||
⚠ Missing quick start section
|
||||
✓ Has installation instructions
|
||||
✓ Has usage examples
|
||||
⚠ Has dependencies on vault content
|
||||
|
||||
Warnings:
|
||||
No quick start or getting started section found
|
||||
Found 1 broken or problematic link(s)
|
||||
Line 45: Link target will move to vault: docs/architecture/decisions.md
|
||||
|
||||
=== Documentation Architecture Recommendations ===
|
||||
|
||||
Project Type: library
|
||||
Total Documentation Files: 15
|
||||
|
||||
Recommendations based on:
|
||||
- Diátaxis framework (tutorials, guides, reference, explanation)
|
||||
- Local = Essential (README, contributing, inline docs, quick reference)
|
||||
- Vault = Deep Research (detailed guides, architecture, ADRs, explorations)
|
||||
- README must be self-contained and work without vault access
|
||||
|
||||
⚠ README currently has dependencies on vault content - needs fixing
|
||||
|
||||
Keep LOCAL: 18 pattern(s)
|
||||
Move to VAULT: 12 pattern(s)
|
||||
|
||||
Suggested vault folders:
|
||||
- docs/guides
|
||||
- docs/tutorials
|
||||
- docs/architecture/decisions
|
||||
|
||||
README changes needed:
|
||||
Fix 1 broken or problematic link(s):
|
||||
- Line 45: Remove or update link to "docs/architecture/decisions.md" (will move to vault)
|
||||
Add a "Quick Start" or "Getting Started" section
|
||||
|
||||
=== Next Steps ===
|
||||
|
||||
1. Review .withcontextconfig.jsonc and customize if needed
|
||||
2. Fix README issues highlighted above
|
||||
3. Apply recommended README changes:
|
||||
Fix broken link at line 45
|
||||
Add a "Quick Start" or "Getting Started" section
|
||||
4. Use /sync-notes or /ingest-notes to migrate files to vault
|
||||
5. Run /validate-config to ensure configuration is valid
|
||||
```
|
||||
|
||||
## Your Task
|
||||
|
||||
Execute the setup_notes tool immediately with options based on user arguments:
|
||||
|
||||
```javascript
|
||||
// Parse optional arguments
|
||||
const args = '$ARGUMENTS';
|
||||
const noStructure = args.includes('--no-structure');
|
||||
const force = args.includes('--force');
|
||||
|
||||
// Get project folder name from current directory
|
||||
const projectFolder = process.cwd().split('/').pop();
|
||||
|
||||
const result = await setup_notes({
|
||||
project_folder: projectFolder,
|
||||
create_structure: !noStructure,
|
||||
force: force,
|
||||
});
|
||||
|
||||
return result;
|
||||
```
|
||||
|
||||
**Usage Examples:**
|
||||
|
||||
- `/setup-notes` - Full setup with vault folder creation
|
||||
- `/setup-notes --no-structure` - Skip creating vault folders
|
||||
- `/setup-notes --force` - Overwrite existing configuration
|
||||
|
||||
## Configuration Format (v2.1.0)
|
||||
|
||||
The generated `.withcontextconfig.jsonc` will have:
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"$schema": "https://raw.githubusercontent.com/boxpositron/with-context-mcp/main/src/config/config-schema.json",
|
||||
|
||||
// Configuration generated based on repository analysis
|
||||
// Project: [detected-project-name]
|
||||
// Type: [mcp-server|library|application|monorepo|cli]
|
||||
|
||||
"version": "2.1",
|
||||
"defaultBehavior": "local",
|
||||
|
||||
// Intelligent vault patterns based on analysis
|
||||
"vault": [
|
||||
// Patterns recommended based on your project structure
|
||||
],
|
||||
|
||||
// Intelligent local patterns based on analysis
|
||||
"local": [
|
||||
// Essential repository files and inline docs
|
||||
],
|
||||
|
||||
"conflictResolution": "local-wins",
|
||||
}
|
||||
```
|
||||
|
||||
## Best Practices Applied
|
||||
|
||||
The intelligent setup follows these frameworks and principles:
|
||||
|
||||
### Diátaxis Framework
|
||||
|
||||
- **Tutorials** (learning-oriented) → vault: docs/tutorials/
|
||||
- **How-to guides** (task-oriented) → vault: docs/guides/
|
||||
- **Reference** (information-oriented) → vault: docs/reference/, local: quick-ref.md
|
||||
- **Explanation** (understanding-oriented) → vault: docs/architecture/
|
||||
|
||||
### Architecture Decision Records (ADRs)
|
||||
|
||||
- Store in `docs/architecture/decisions/` or `architecture/decisions/`
|
||||
- Keep template: context, decision, consequences
|
||||
- Use Michael Nygard's format
|
||||
|
||||
### README Best Practices
|
||||
|
||||
- Must be self-contained (works without vault)
|
||||
- No broken links to vault-delegated files
|
||||
- Has badges, installation, usage, quick start
|
||||
- Links only to files that stay in repository
|
||||
|
||||
### Docs-as-Code
|
||||
|
||||
- Markdown format
|
||||
- Version controlled
|
||||
- Clear organization
|
||||
- Consistent naming
|
||||
|
||||
## Guidelines for Agents
|
||||
|
||||
When running this command:
|
||||
|
||||
1. **ONLY use the setup_notes tool** - Do NOT perform manual analysis or file operations
|
||||
2. **Trust the tool's output** - The intelligent engine has scanned the repo and knows what it found
|
||||
3. **Present the results clearly** - Show the full tool output to the user
|
||||
4. **Do NOT**:
|
||||
- Manually read files to analyze the project
|
||||
- Create configuration files directly
|
||||
- Parse README or validate links manually
|
||||
- Scan directories yourself
|
||||
5. **The tool handles everything**:
|
||||
- Repository scanning
|
||||
- README validation
|
||||
- Link integrity checks
|
||||
- Configuration generation
|
||||
- Folder structure creation
|
||||
6. **Your role is to**:
|
||||
- Call the tool with appropriate parameters
|
||||
- Present the results to the user
|
||||
- Suggest next steps based on tool output
|
||||
|
||||
## Migration from Legacy Format
|
||||
|
||||
If `.withcontextignore` exists:
|
||||
|
||||
- Automatically migrates to new `.withcontextconfig.jsonc` format
|
||||
- Creates backup as `.withcontextignore.backup`
|
||||
- Preserves pattern intent (negations become `local` patterns)
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `/validate-config` - Validate configuration against schema
|
||||
- `/preview-delegation` - Preview which files will be delegated
|
||||
- `/sync-notes` - Bidirectional sync between local and vault
|
||||
- `/ingest-notes` - Copy local documentation to vault
|
||||
- `/teleport-notes` - Download documentation from vault to local
|
||||
|
||||
## Key Differences from Old Version
|
||||
|
||||
**Old behavior** (v2.0):
|
||||
|
||||
- Used generic template configuration
|
||||
- No project analysis
|
||||
- No README validation
|
||||
- Manual pattern selection
|
||||
|
||||
**New behavior** (v2.1+):
|
||||
|
||||
- Intelligent analysis of actual project structure
|
||||
- README health scoring and link validation
|
||||
- Project-type-specific recommendations
|
||||
- Ensures README self-containment
|
||||
- Follows documentation best practices (Diátaxis, ADRs)
|
||||
- Actionable, specific feedback
|
||||
|
||||
---
|
||||
|
||||
_The intelligent setup-notes uses the documentation analyzer to provide context-aware recommendations based on your actual repository structure and best practices._
|
||||
111
.config/opencode/command/sync-notes.md
Normal file
111
.config/opencode/command/sync-notes.md
Normal file
@@ -0,0 +1,111 @@
|
||||
---
|
||||
description: Bidirectionally sync documentation files between local project and Obsidian vault
|
||||
agent: general
|
||||
subtask: true
|
||||
---
|
||||
|
||||
# Sync Notes
|
||||
|
||||
Bidirectionally synchronizes documentation files between local project and Obsidian vault. Files are moved based on delegation rules (deleted from source after successful copy).
|
||||
|
||||
## What This Command Does
|
||||
|
||||
This command performs bidirectional synchronization:
|
||||
|
||||
- **Local → Vault**: Files matching "vault" patterns are moved from local to vault
|
||||
- **Vault → Local**: Files matching "local" patterns are moved from vault to local
|
||||
- **Move operation**: Files are DELETED from source after successful copy
|
||||
- **Structure preserved**: Directory structure is maintained in both directions
|
||||
- **Dry-run preview**: See what will happen before executing
|
||||
|
||||
**Prerequisites:**
|
||||
|
||||
- `.withcontextconfig.jsonc` must exist (run `/setup-notes` first if not)
|
||||
- Configuration defines which files are delegated to vault vs local
|
||||
|
||||
## Your Task
|
||||
|
||||
Execute the sync_notes tool immediately with dry-run by default for safety:
|
||||
|
||||
```javascript
|
||||
// Check for --execute flag in arguments
|
||||
const args = '$ARGUMENTS';
|
||||
const shouldExecute = args.includes('--execute');
|
||||
|
||||
const result = await sync_notes({
|
||||
dry_run: !shouldExecute,
|
||||
});
|
||||
|
||||
return result;
|
||||
```
|
||||
|
||||
**Usage:**
|
||||
|
||||
- `/sync-notes` - Preview changes (safe, dry-run mode)
|
||||
- `/sync-notes --execute` - Execute sync for real (moves and deletes files)
|
||||
|
||||
**Important:** This is a destructive operation - files are DELETED from source after successful copy. Always preview first!
|
||||
|
||||
## Parameters
|
||||
|
||||
### dry_run (optional, default: false)
|
||||
|
||||
Preview mode - shows what will happen without making changes:
|
||||
|
||||
```javascript
|
||||
dry_run: true; // Preview only
|
||||
dry_run: false; // Execute for real
|
||||
```
|
||||
|
||||
## Sync Behavior
|
||||
|
||||
**Files with delegation decision "vault":**
|
||||
|
||||
- Moved from local → vault
|
||||
- Deleted from local after successful copy
|
||||
|
||||
**Files with delegation decision "local":**
|
||||
|
||||
- Moved from vault → local
|
||||
- Deleted from vault after successful copy
|
||||
|
||||
**Important notes:**
|
||||
|
||||
- Only files matching `.withcontextconfig.jsonc` patterns are synced
|
||||
- Directory structure is preserved in both locations
|
||||
- Files are DELETED from source automatically (this is a MOVE operation, not COPY)
|
||||
- The tool checks for configuration existence automatically
|
||||
|
||||
## Example Output
|
||||
|
||||
```
|
||||
=== Sync Results ===
|
||||
|
||||
Files moved from local to vault: 12
|
||||
- docs/guides/getting-started.md
|
||||
- docs/architecture/decisions/001-use-typescript.md
|
||||
- CHANGELOG.md
|
||||
... (9 more files)
|
||||
|
||||
Files moved from vault to local: 3
|
||||
- README.md
|
||||
- CONTRIBUTING.md
|
||||
- src/utils/README.md
|
||||
|
||||
Total files deleted from source: 15
|
||||
Errors: 0
|
||||
|
||||
⚠️ Source files were deleted after successful copy (expected behavior)
|
||||
```
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `/setup-notes` - Create configuration file
|
||||
- `/preview-notes-delegation` - Preview sync decisions
|
||||
- `/ingest-notes` - One-way copy to vault (keeps local files)
|
||||
- `/teleport-notes` - One-way download from vault (keeps vault files)
|
||||
- `/validate-notes-config` - Validate configuration
|
||||
|
||||
---
|
||||
|
||||
_The sync-notes tool performs bidirectional synchronization with automatic source deletion._
|
||||
115
.config/opencode/command/teleport-notes.md
Normal file
115
.config/opencode/command/teleport-notes.md
Normal file
@@ -0,0 +1,115 @@
|
||||
---
|
||||
description: Teleport documentation files from Obsidian vault to local project
|
||||
agent: general
|
||||
subtask: true
|
||||
---
|
||||
|
||||
# Teleport Notes
|
||||
|
||||
Downloads documentation files from the Obsidian vault back to the local project based on `.withcontextconfig.jsonc` delegation rules.
|
||||
|
||||
## What This Command Does
|
||||
|
||||
This command downloads files from vault to local project:
|
||||
|
||||
- Scans vault for files matching vault patterns in `.withcontextconfig.jsonc`
|
||||
- Copies matched files to local project preserving directory structure
|
||||
- Optionally deletes vault files after successful copy
|
||||
- Provides dry-run preview mode
|
||||
|
||||
**Prerequisites:**
|
||||
|
||||
- `.withcontextconfig.jsonc` must exist (run `/setup-notes` first if not)
|
||||
- Configuration defines which files have delegation decision "vault"
|
||||
|
||||
## Your Task
|
||||
|
||||
Execute the teleport_notes tool immediately with dry-run by default for safety:
|
||||
|
||||
```javascript
|
||||
// Check for flags in arguments
|
||||
const args = '$ARGUMENTS';
|
||||
const shouldExecute = args.includes('--execute');
|
||||
const shouldDelete = args.includes('--delete');
|
||||
const forceDelete = args.includes('--force-delete');
|
||||
|
||||
const result = await teleport_notes({
|
||||
dry_run: !shouldExecute,
|
||||
delete_from_vault: shouldDelete,
|
||||
force_delete: forceDelete,
|
||||
});
|
||||
|
||||
return result;
|
||||
```
|
||||
|
||||
**Usage:**
|
||||
|
||||
- `/teleport-notes` - Preview what will be downloaded (safe, dry-run mode)
|
||||
- `/teleport-notes --execute` - Download files from vault (keeps vault files)
|
||||
- `/teleport-notes --execute --delete` - Download and delete vault files
|
||||
- `/teleport-notes --execute --delete --force-delete` - Force delete even on errors
|
||||
|
||||
**Important:** Use `--delete` flag only if you want to remove vault files after downloading!
|
||||
|
||||
## Parameters
|
||||
|
||||
### dry_run (optional, default: false)
|
||||
|
||||
Preview mode - shows what will happen without making changes:
|
||||
|
||||
```javascript
|
||||
dry_run: true; // Preview only
|
||||
dry_run: false; // Execute for real
|
||||
```
|
||||
|
||||
### delete_from_vault (optional, default: false)
|
||||
|
||||
Whether to delete vault files after successful copy to local:
|
||||
|
||||
```javascript
|
||||
delete_from_vault: false; // Keep vault files (default)
|
||||
delete_from_vault: true; // Delete vault files after copy
|
||||
```
|
||||
|
||||
### force_delete (optional, default: false)
|
||||
|
||||
Force deletion of vault files even if some files had errors:
|
||||
|
||||
```javascript
|
||||
force_delete: false; // Don't delete if errors occurred (default)
|
||||
force_delete: true; // Delete even if some files failed
|
||||
```
|
||||
|
||||
## Important Notes
|
||||
|
||||
- **Vault files are NOT deleted by default** - set `delete_from_vault: true` explicitly if desired
|
||||
- **Always preview first** - Use `dry_run: true` before executing
|
||||
- **The tool automatically checks** for `.withcontextconfig.jsonc` existence
|
||||
- **Directory structure is preserved** in the local project
|
||||
|
||||
## Example Output
|
||||
|
||||
```
|
||||
=== Teleport Results ===
|
||||
|
||||
Files teleported from vault: 15
|
||||
- docs/guides/getting-started.md → docs/guides/getting-started.md
|
||||
- docs/architecture/decisions/001-use-typescript.md → docs/architecture/decisions/001-use-typescript.md
|
||||
- CHANGELOG.md → CHANGELOG.md
|
||||
... (12 more files)
|
||||
|
||||
Vault files deleted: 0 (kept in vault)
|
||||
Errors: 0
|
||||
```
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `/setup-notes` - Create configuration file
|
||||
- `/preview-notes-delegation` - Preview which files will be teleported
|
||||
- `/sync-notes` - Bidirectional sync (moves files both ways)
|
||||
- `/ingest-notes` - One-way copy to vault
|
||||
- `/validate-notes-config` - Validate configuration
|
||||
|
||||
---
|
||||
|
||||
_The teleport-notes tool downloads vault documentation to local project based on delegation rules._
|
||||
113
.config/opencode/command/validate-notes-config.md
Normal file
113
.config/opencode/command/validate-notes-config.md
Normal file
@@ -0,0 +1,113 @@
|
||||
---
|
||||
description: Validate .withcontextconfig.jsonc for errors and warnings
|
||||
agent: general
|
||||
subtask: true
|
||||
---
|
||||
|
||||
# Validate Notes Configuration
|
||||
|
||||
Validates the `.withcontextconfig.jsonc` file for syntax errors, structural issues, and provides detailed feedback on configuration problems.
|
||||
|
||||
## What This Command Does
|
||||
|
||||
This command performs comprehensive validation of your documentation delegation configuration:
|
||||
|
||||
**Validation Checks:**
|
||||
|
||||
1. **File Existence** - Verifies `.withcontextconfig.jsonc` exists
|
||||
2. **Syntax Validation** - Checks for valid JSON/JSONC syntax
|
||||
3. **Schema Validation** - Validates against the configuration schema
|
||||
4. **Semantic Validation** - Checks for logical issues:
|
||||
- Pattern conflicts between `vault` and `local` arrays
|
||||
- Invalid glob patterns
|
||||
- Missing required fields
|
||||
- Deprecated or unknown configuration options
|
||||
5. **Best Practices** - Provides recommendations and warnings
|
||||
|
||||
**Prerequisites:**
|
||||
|
||||
- `.withcontextconfig.jsonc` must exist (run `/setup-notes` first if not)
|
||||
|
||||
**Tool Priority:**
|
||||
First try to use the WithContext plugin's `validate_config` tool. If not available, fallback to the with-context MCP server's `validate_config` tool.
|
||||
|
||||
## Your Task
|
||||
|
||||
Execute the validate_config tool immediately:
|
||||
|
||||
```javascript
|
||||
const result = await validate_config({
|
||||
project_root: process.cwd(),
|
||||
});
|
||||
|
||||
return result;
|
||||
```
|
||||
|
||||
The tool output includes:
|
||||
|
||||
- Configuration path and validation status
|
||||
- All errors (critical issues that must be fixed)
|
||||
- All warnings (non-critical issues to address)
|
||||
- Info messages (helpful suggestions)
|
||||
- Suggested next steps
|
||||
|
||||
## Example Output
|
||||
|
||||
```
|
||||
=== Configuration Validation ===
|
||||
|
||||
Configuration: /path/to/project/.withcontextconfig.jsonc
|
||||
Status: ✓ Valid
|
||||
|
||||
Warnings (2):
|
||||
• Pattern 'docs/**/*.md' in vault array may conflict with 'docs/internal/**' in local array
|
||||
Resolution: 'local-wins' strategy will prioritize local patterns
|
||||
• Consider adding more specific patterns for better control
|
||||
|
||||
Info (1):
|
||||
• Configuration follows v2.1 format
|
||||
• Using recommended 'local-wins' conflict resolution
|
||||
|
||||
Next Steps:
|
||||
1. Review pattern conflicts highlighted above
|
||||
2. Run /preview-notes-delegation to see how files will be categorized
|
||||
3. Use /sync-notes when ready to synchronize files
|
||||
```
|
||||
|
||||
## Important
|
||||
|
||||
- **Execute autonomously** - Do NOT ask questions, just call the tool and report results
|
||||
- **Trust the tool output** - The validator has comprehensive checks built-in
|
||||
- **Show full validation report** - Include all errors, warnings, and info messages
|
||||
- **Provide context** - Explain what each issue means and how to fix it
|
||||
- **DO NOT manually parse** the config file - rely entirely on the tool
|
||||
|
||||
## Common Validation Issues
|
||||
|
||||
**Syntax Errors:**
|
||||
|
||||
- Missing commas, quotes, or brackets
|
||||
- Invalid JSONC comments
|
||||
- Trailing commas in wrong places
|
||||
|
||||
**Schema Errors:**
|
||||
|
||||
- Missing `version` field
|
||||
- Invalid `defaultBehavior` value (must be "local" or "vault")
|
||||
- Invalid `conflictResolution` value
|
||||
|
||||
**Semantic Errors:**
|
||||
|
||||
- Overlapping patterns in `vault` and `local` arrays
|
||||
- Invalid glob patterns
|
||||
- Patterns that will never match any files
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `/setup-notes` - Create or regenerate configuration
|
||||
- `/preview-notes-delegation` - Preview delegation decisions
|
||||
- `/sync-notes` - Synchronize files based on validated configuration
|
||||
|
||||
---
|
||||
|
||||
_The validate-notes-config command ensures your configuration is correct before performing sync operations._
|
||||
Reference in New Issue
Block a user