mirror of
https://github.com/boxpositron/absolute-dotfiles.git
synced 2026-10-24 08:23:19 +00:00
feat(omo): retire opencode and move its skills and commands to omo
- Move the vendored skills from .config/opencode/skills to .config/omo/skills, with provenance and local changes in its README - Rewrite Impeccable's script paths to ~/.omo/agent/skills/impeccable so its detector and live-server verbs resolve under omo - frontend-workflow hands screenshots to a visual-engineering task instead of opencode run - Move the notes commands and /impeccable to .config/omo/prompts as omo prompt templates; setup-mcp stays behind because it writes opencode.json - Archive DEVELOPMENT-WORKFLOW.md and UI-WORKFLOW.md under .config/omo/archive; nothing loads them - link-ai-configs.sh links the skills into omo and Claude Code only and stops linking OpenCode's config, TUI, plugins and workflow docs - setup-mac.sh and Brewfile.apps stop installing OpenCode; README and .withcontextconfig.jsonc follow the new layout ~/.config/opencode/AGENTS.md stays linked: omo's rules engine reads it before ~/.claude/CLAUDE.md and stops at the first hit, so it carries the shared preferences and keeps OMC's instructions out of omo.
This commit is contained in:
David Ibia
@@ -1,294 +0,0 @@
|
||||
---
|
||||
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._
|
||||
@@ -1,6 +0,0 @@
|
||||
---
|
||||
description: Use when the user wants to design, redesign, shape, critique, audit, polish, clarify, distill, harden, optimize, adapt, animate, colorize, extract, or otherwise improve a frontend interface. Covers websites, landing pages, dashboards, product UI, app shells, components, forms, settings, onboarding, and empty states. Handles UX review, visual hierarchy, information architecture, cognitive load, accessibility, performance, responsive behavior, theming, anti-patterns, typography, fonts, spacing, layout, alignment, color, motion, micro-interactions, UX copy, error states, edge cases, i18n, and reusable design systems or tokens. Also use for bland designs that need to become bolder or more delightful, loud designs that should become quieter, live browser iteration on UI elements, or ambitious visual effects that should feel technically extraordinary. Not for backend-only or non-UI tasks.
|
||||
agent: build
|
||||
subtask: true
|
||||
---
|
||||
Call skill({ name: "impeccable" }) and follow its `Setup` and `Commands` sections to handle $ARGUMENTS.
|
||||
@@ -1,99 +0,0 @@
|
||||
---
|
||||
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._
|
||||
@@ -1,193 +0,0 @@
|
||||
---
|
||||
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._
|
||||
@@ -1,623 +0,0 @@
|
||||
---
|
||||
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._
|
||||
@@ -1,300 +0,0 @@
|
||||
---
|
||||
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._
|
||||
@@ -1,111 +0,0 @@
|
||||
---
|
||||
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._
|
||||
@@ -1,115 +0,0 @@
|
||||
---
|
||||
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._
|
||||
@@ -1,113 +0,0 @@
|
||||
---
|
||||
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