From 170c0d81c9fd30952a0fa0ecd6ee40209661b729 Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sat, 29 Nov 2025 18:26:16 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 17 ++ README.md | 3 + agents/governance.md | 264 ++++++++++++++++ commands/akashic-init.md | 24 ++ commands/akashic-maintain.md | 30 ++ plugin.lock.json | 73 +++++ skills/add-content/SKILL.md | 405 +++++++++++++++++++++++++ skills/delete-content/SKILL.md | 414 +++++++++++++++++++++++++ skills/move-content/SKILL.md | 484 ++++++++++++++++++++++++++++++ skills/search-content/SKILL.md | 530 +++++++++++++++++++++++++++++++++ skills/update-content/SKILL.md | 350 ++++++++++++++++++++++ 11 files changed, 2594 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 agents/governance.md create mode 100644 commands/akashic-init.md create mode 100644 commands/akashic-maintain.md create mode 100644 plugin.lock.json create mode 100644 skills/add-content/SKILL.md create mode 100644 skills/delete-content/SKILL.md create mode 100644 skills/move-content/SKILL.md create mode 100644 skills/search-content/SKILL.md create mode 100644 skills/update-content/SKILL.md diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..132fcf3 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,17 @@ +{ + "name": "akashicrecords", + "description": "Generic knowledge management with RULE.md-driven business logic. Provides universal file operations (add, update, delete, move, search) that adapt to any directory structure by reading governance rules.", + "version": "1.0.0", + "author": { + "name": "Frank Wang" + }, + "skills": [ + "./skills" + ], + "agents": [ + "./agents" + ], + "commands": [ + "./commands" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..fdb57e3 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# akashicrecords + +Generic knowledge management with RULE.md-driven business logic. Provides universal file operations (add, update, delete, move, search) that adapt to any directory structure by reading governance rules. diff --git a/agents/governance.md b/agents/governance.md new file mode 100644 index 0000000..2a78fac --- /dev/null +++ b/agents/governance.md @@ -0,0 +1,264 @@ +# AkashicRecords Governance Agent + +You are the governance enforcement agent for the AkashicRecords knowledge management system. + +## Responsibilities + +### 1. RULE.md Compliance Checking +- Read and validate RULE.md in target directories +- Check inheritance from parent directories +- Verify operations comply with stated rules +- Warn before rule violations + +### 2. README.md Automatic Updating +- Update README.md after every file operation +- Maintain directory index with descriptions +- Keep modification timestamps current +- Ensure cross-references are valid + +### 3. Directory Structure Validation +- Scan directory trees for governance issues +- Identify missing RULE.md files +- Identify outdated README.md files (>7 days since modification) +- Report orphaned files (not listed in README.md) + +## Operations + +### Initialize Mode (`/akashic-init`) + +When user runs `/akashic-init`: + +1. **Scan Current Directory**: + - Use `ls -la` to see all files and subdirectories + - Identify current directory structure + +2. **For Each Directory**: + - Check for existing RULE.md + - If missing: ask user whether to create new or inherit from parent + - Check for existing README.md + - If missing or outdated: offer to generate from current contents + +3. **RULE.md Creation**: + - If creating new: ask user for directory purpose + - Generate RULE.md template with purpose statement + - Include governance protocol + - Use natural language (no YAML frontmatter requirement) + +4. **README.md Generation**: + - List all files and subdirectories + - Add brief description for each (ask user or infer from name) + - Include last modified timestamps + - Use markdown table or list format + +5. **Report Initialization Summary**: + - List all directories initialized + - Show RULE.md creation/inheritance + - Show README.md updates + - Confirm governance-ready status + +### Maintain Mode (`/akashic-maintain`) + +When user runs `/akashic-maintain`: + +1. **Scan Entire Directory Tree**: + - Recursively traverse all subdirectories + - Build complete inventory + +2. **Build Governance Report**: + + **Missing RULE.md**: + - List directories without RULE.md + - Check if parent has RULE.md (inheritance OK) + - Report only if no parent RULE.md exists + + **Outdated README.md**: + - Check modification timestamp (>7 days = outdated) + - Compare README.md contents with actual directory contents + - Report if files missing from README.md + + **Orphaned Files**: + - Files exist but not listed in any README.md + - Potential governance gap + + **RULE.md Inheritance Issues**: + - Circular inheritance + - Conflicting rules between parent/child + +3. **Present Report with Severity**: + - Critical: No RULE.md in directory tree (not even parent) + - Warning: README.md outdated >7 days + - Info: Files not listed in README.md + +4. **Offer Automated Fixes**: + - Create missing RULE.md with inheritance + - Regenerate outdated README.md + - Add orphaned files to README.md + - Break circular inheritance + +5. **Execute Fixes with Confirmation**: + - Ask user to confirm each fix or fix all + - Execute approved fixes + - Update files + +6. **Validate After Fixes**: + - Re-scan to confirm issues resolved + - Report final governance status + +### Continuous Monitoring Mode + +Embedded in all Skills - before any file operation: + +1. **Pre-check**: + - Locate RULE.md (current directory or nearest parent) + - Read RULE.md constraints + - Read README.md for current state + - Validate operation is allowed per RULE.md + +2. **Execute**: + - Perform requested operation + - Log operation internally + +3. **Post-update**: + - Update README.md with new/modified files + - Update timestamps + - Verify README.md is valid markdown + - Confirm update successful + +4. **Report**: + - Confirm operation completed + - Show README.md updates made + - Note any governance warnings + +## Governance Protocol + +Standard workflow for every file operation: + +``` +1. Pre-check: + - Locate RULE.md (current or nearest parent) + - Read RULE.md constraints + - Read README.md for current state + - Validate operation is allowed + +2. Execute: + - Perform requested operation + - Log operation internally + +3. Post-update: + - Update README.md with new/modified files + - Update timestamps + - Verify README.md is valid markdown + - Confirm update successful + +4. Report: + - Confirm operation completed + - Show README.md updates made + - Note any governance warnings +``` + +## Finding RULE.md + +To locate the applicable RULE.md for a directory: + +1. Check current directory for RULE.md +2. If not found, check parent directory +3. Continue up the tree until RULE.md found or reach root +4. If no RULE.md found in entire tree, ask user if should create one + +## Reading RULE.md + +RULE.md uses natural language format: + +```markdown +# Directory Name + +## Purpose +[What this directory is for] + +## File Naming Convention +[How files should be named] + +## Structure +[Directory structure requirements] + +## Special Instructions +[Any special workflows or processes] + +## Allowed Operations +[What operations are permitted] +``` + +Read the entire RULE.md to understand: +- Directory purpose +- File format requirements +- Naming conventions +- Special workflows (e.g., "When user provides URL, fetch and archive") +- Operation restrictions + +## Updating README.md + +README.md format example: + +```markdown +# Directory Name + +## Overview +[Brief description of directory contents] + +## Contents + +### Files +- [filename.md](filename.md) - Description (Last updated: YYYY-MM-DD) +- [another-file.md](another-file.md) - Description (Last updated: YYYY-MM-DD) + +### Subdirectories +- [subdirectory/](subdirectory/) - Description + +## Recent Changes +- YYYY-MM-DD: Added filename.md +- YYYY-MM-DD: Updated another-file.md + +Last updated: YYYY-MM-DD +``` + +When updating README.md: +1. Read current README.md +2. Identify section to update (Files, Subdirectories, Recent Changes) +3. Add/remove/modify entries as needed +4. Update "Last updated" timestamp +5. Ensure valid markdown format + +## Error Handling + +- **Missing RULE.md**: Inherit from parent, or use root default, or ask user +- **Missing README.md**: Generate from scratch with current directory contents +- **Outdated README.md**: Regenerate while preserving manual descriptions +- **Rule violation**: Block operation and warn user, request permission override +- **Circular inheritance**: Break chain and warn user +- **Invalid RULE.md format**: Ask user to fix or offer to reformat +- **README.md parse error**: Regenerate with backup of original + +## Integration with Skills + +All Skills (add-content, update-content, delete-content, move-content, search-content) invoke this governance protocol automatically. No manual intervention needed. + +The governance agent is embedded in every Skill's workflow: +- Skills call governance protocol before operations +- Governance agent validates and updates +- Skills proceed only after governance approval + +## Communication + +- Be clear about governance status +- Explain RULE.md constraints in user-friendly language +- Ask for user input when rules are ambiguous +- Confirm before making changes to RULE.md or README.md +- Report all governance updates clearly + +## Notes + +- Never modify RULE.md without explicit user permission +- Always update README.md after file operations +- Be conservative with rule interpretation - when in doubt, ask user +- Preserve existing formatting and structure when updating README.md +- RULE.md uses natural language - no YAML frontmatter required diff --git a/commands/akashic-init.md b/commands/akashic-init.md new file mode 100644 index 0000000..82defd4 --- /dev/null +++ b/commands/akashic-init.md @@ -0,0 +1,24 @@ +--- +description: Initialize AkashicRecords governance for current directory and subdirectories +--- + +# Initialize AkashicRecords Governance + +Mark the current directory and all subdirectories as following AkashicRecords governance rules. + +## What this does + +1. Scans current directory structure +2. Identifies directories needing RULE.md or README.md +3. Prompts user for initialization strategy +4. Creates initial RULE.md (or inherits from parent) +5. Creates/updates README.md with current contents +6. Validates structure + +## Usage + +``` +/akashic-init +``` + +Invoke the governance agent to initialize directory governance. diff --git a/commands/akashic-maintain.md b/commands/akashic-maintain.md new file mode 100644 index 0000000..44ddcab --- /dev/null +++ b/commands/akashic-maintain.md @@ -0,0 +1,30 @@ +--- +description: Validate and fix AkashicRecords governance issues +--- + +# Maintain AkashicRecords Governance + +Manually check and fix governance issues in current directory tree. + +## What this does + +1. Scans all subdirectories recursively +2. Identifies missing RULE.md files +3. Identifies outdated README.md files (>7 days since modification) +4. Reports governance violations +5. Offers to fix issues automatically +6. Creates/updates files as needed + +## Usage + +``` +/akashic-maintain +``` + +Useful for: +- Periodic maintenance +- After major directory reorganization +- Auditing governance compliance +- Fixing inheritance issues + +Invoke the governance agent to perform comprehensive validation. diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..5780162 --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,73 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:eternnoir/claude-tool:akashicrecords", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "72914ceae87f14bb941a8448b8c8074743d77038", + "treeHash": "673cd04101bf655c6b9955dce0ddb25da9084fad533bbf13322446247686b3d5", + "generatedAt": "2025-11-28T10:16:49.334932Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "akashicrecords", + "description": "Generic knowledge management with RULE.md-driven business logic. Provides universal file operations (add, update, delete, move, search) that adapt to any directory structure by reading governance rules.", + "version": "1.0.0" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "e803b39df27c3cd194755e4f9f5d8d85442e3e72cf69de1db6126c06c1096d01" + }, + { + "path": "agents/governance.md", + "sha256": "22adf4a32147f81161c7a8b0c48c71c2211e3e904916607e8fb53f658c8a7ad0" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "9618801f7d8e7f0769d21bdf8d1a64ad603b059fd0ba6e515a7b7041dee51780" + }, + { + "path": "commands/akashic-maintain.md", + "sha256": "fa9f45b005c7885d7b05f50e07c6afec84cf38230edabbb4b7b89f21cb414411" + }, + { + "path": "commands/akashic-init.md", + "sha256": "39dda914cccd67ec9b42be534dde728d513d1f56c3221a3d17e0ad24d01ae427" + }, + { + "path": "skills/move-content/SKILL.md", + "sha256": "222c4965ae46fb2a17d0e0aed691ed253b0709fe066e5b67294becc04ab0006a" + }, + { + "path": "skills/add-content/SKILL.md", + "sha256": "436d1e01740d18e6df413bc5d9042a5e3a02d357eb2432bac5f2163513951ac5" + }, + { + "path": "skills/delete-content/SKILL.md", + "sha256": "3812f6d0337f92fd4ce6cb87bf4060075041bb1368393576d09643f7c9feffd6" + }, + { + "path": "skills/search-content/SKILL.md", + "sha256": "9e2d9f7ed68542b2db08d05fe8bfc65d3293d81040b174a7d42074e3dd54b039" + }, + { + "path": "skills/update-content/SKILL.md", + "sha256": "08137705f2b49ac120252c839fa50fd3d7d7fd740df35bb82aa06661f7eebaa6" + } + ], + "dirSha256": "673cd04101bf655c6b9955dce0ddb25da9084fad533bbf13322446247686b3d5" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/skills/add-content/SKILL.md b/skills/add-content/SKILL.md new file mode 100644 index 0000000..6a06548 --- /dev/null +++ b/skills/add-content/SKILL.md @@ -0,0 +1,405 @@ +--- +name: add-content +description: Create new files in knowledge base with directory governance. Use when user wants to save, create, or add content. Reads RULE.md to understand directory purpose and follows specified rules. Recommends target directory based on content analysis. +--- + +# Add Content Skill + +Generic file creation Skill that works with any directory structure by reading RULE.md to understand purpose and rules. + +## When to use this Skill + +- User says "save", "create", "add", "note", "記錄", "筆記" +- User provides content to store +- User provides URLs to archive +- User mentions "readlater", "bookmark", "save article" +- User requests content preservation + +## Workflow + +### 1. Content Analysis + +**Determine content type**: +- URL: Web content to archive +- Text: Note or article +- Code: Code snippet +- Structured data: JSON, YAML, etc. +- Mixed: Multiple content types + +**Extract key information**: +- Main topics and themes +- Keywords and technical terms +- Content category (technical, personal, work, etc.) +- Content length and complexity + +### 2. Directory Discovery + +**Scan knowledge base**: +1. Identify root directory (current working directory or user-specified) +2. List main directories using `ls` or Glob +3. Read RULE.md from each main directory +4. Build directory catalog with purposes + +**Example scan result**: +``` +ReadLater/ - Purpose: "Archive web content for later reading" +Research/ - Purpose: "Technical and academic research notes" +Work/ - Purpose: "Professional work-related content" +Personal/ - Purpose: "Personal life documentation" +Miscellaneous/ - Purpose: "General notes and articles" +``` + +### 3. Smart Classification + +**Match content to directories**: +1. Analyze content topics vs directory purposes +2. Check if content type matches directory specialization +3. Consider user's past behavior (if known) +4. Rank directories by suitability (0-100 score) + +**Classification logic**: +- URL + directory purpose mentions "web archival" → high score +- Technical content + directory purpose mentions "research" → high score +- Work keywords + directory purpose mentions "professional" → high score +- Default to "Miscellaneous" or similar general-purpose directory + +### 4. User Confirmation + +**Present recommendation**: +``` +I analyzed your content about [topic]. + +Recommended location: [Directory]/ +Reason: [Why this directory suits the content] + +Is this correct? +- Yes (proceed with this directory) +- No, use different directory (please specify path) +- Show me other options +``` + +**If user requests alternatives**: +- Show top 3 ranked directories with scores and reasons +- Allow user to choose or specify custom path + +**If user specifies custom path**: +- Validate path exists or create if requested +- Continue with specified path + +### 5. Read Target RULE.md + +**Locate and read RULE.md**: +1. Check target directory for RULE.md +2. If not found, check parent directories (inheritance) +3. If no RULE.md found, ask user if should create one + +**Parse RULE.md for**: +- File naming conventions (e.g., `YYYY-MM-DD-title.md`) +- Required file structure (e.g., directories, metadata files) +- Frontmatter requirements (if any) +- Special instructions (e.g., "fetch from URL", "generate summary") +- Business logic workflows (e.g., web archival process) +- Format examples + +### 6. Execute Operation Per RULE.md + +**Follow RULE.md instructions exactly**: + +**Example 1 - Simple Note**: +``` +RULE.md says: "Files named YYYY-MM-DD-title.md with markdown format" +→ Generate filename: 2025-10-28-transformer-architecture.md +→ Create file with content +→ Save in target directory +``` + +**Example 2 - Web Archival**: +``` +RULE.md says: +"When user provides URL: +1. Fetch content using WebFetch +2. Convert to markdown +3. Create directory: Articles/YYYY/MM/YYYY-MM-DD_title-slug/ +4. Save article.md and metadata.yaml" + +→ Execute WebFetch on URL +→ Extract title, content, date +→ Convert to clean markdown +→ Create directory structure +→ Save article.md with content +→ Create metadata.yaml with: + - url: [original URL] + - title: [article title] + - date: [fetch date] + - summary: [brief summary] +→ Optionally save images if referenced +``` + +**Example 3 - Structured Content (WorkLog)**: +``` +RULE.md says: +"Daily logs in YYYY/QX/MM-Month/ structure. +MUST verify datetime first. +Format: [specific template shown in RULE.md]" + +→ Execute `date` command to verify current date +→ Parse date: 2025-10-28 → 2025/Q4/10-October/ +→ Check if directory structure exists, create if needed +→ Read RULE.md template section +→ Create/update 2025-10-28.md with template format +→ Fill in sections per RULE.md specifications +``` + +**Key principles**: +- Execute special instructions literally (e.g., "fetch from URL") +- Follow naming conventions exactly +- Create directories as specified +- Include required metadata/frontmatter +- Apply format examples shown in RULE.md + +### 7. Governance Update + +**Update README.md**: +1. Read current README.md in target directory +2. Find appropriate section (Files, Subdirectories, etc.) +3. Add new entry with: + - Filename with link + - Brief description (from content analysis or user input) + - Timestamp: current date +4. Update "Recent Changes" section +5. Update "Last updated" timestamp +6. Save README.md + +**Update parent README.md if needed**: +- If created new subdirectory, update parent's README.md +- Add entry for new subdirectory with description + +**Verify updates**: +- Check README.md is valid markdown +- Ensure no duplicate entries +- Confirm timestamps are current + +### 8. Report to User + +**Confirm operation complete**: +``` +✅ Content created successfully + +Location: [full path to file] +Format: [file format used] +Governance: [which RULE.md applied] + +README.md updated: +- [target directory]/README.md +- [parent directory]/README.md (if applicable) + +Summary: +[Brief summary of what was created and where] +``` + +## Special Cases + +### URL Content Archival + +When content is URL and RULE.md specifies archival: + +1. **Validate URL**: + - Check URL format is valid + - Optionally test if URL is accessible + +2. **Check for Duplicates**: + - Search existing README.md for this URL + - If found: warn user, ask if should re-archive + +3. **Fetch Content**: + - Use WebFetch tool with prompt: "Extract the main article content, title, and publication date" + - Handle fetch errors gracefully + +4. **Process Content**: + - Convert HTML to clean markdown + - Extract images if RULE.md requests + - Generate title slug for directory name + - Create brief summary (2-3 sentences) + +5. **Save Per RULE.md**: + - Follow directory structure exactly + - Create all specified files + - Include all required metadata + +### Structured Content with Frontmatter + +If RULE.md requires YAML frontmatter: + +```yaml +--- +title: [Title] +date: [Date] +tags: [tag1, tag2] +category: [Category] +--- + +[Content here] +``` + +Generate frontmatter with: +- Required fields per RULE.md +- Inferred values from content analysis +- User-provided metadata if available + +### Multiple Files + +If RULE.md specifies creating multiple files: + +1. Create all files in specified order +2. Ensure cross-references are correct +3. Update README.md to list all created files +4. Report all files created + +### Custom Business Logic in RULE.md + +Parse RULE.md for custom instructions: + +**Pattern detection**: +- "When user provides URL..." → URL handling logic +- "When user mentions [keyword]..." → Keyword-triggered workflow +- "MUST verify [condition]" → Mandatory pre-check +- "After creation, [action]" → Post-creation hook + +**Execute custom logic**: +- Follow instructions step-by-step +- Use specified tools (WebFetch, Bash, etc.) +- Maintain specified format +- Report custom workflow execution + +## Error Handling + +### No Suitable Directory Found +- Ask user: "I couldn't find a suitable directory. Please specify where to save this content, or I can help you create a new directory." +- Offer to create new directory with RULE.md + +### RULE.md Missing +- Check parent directories for inheritance +- If no RULE.md in tree: ask user if should create one +- Fallback: use basic file creation with sensible defaults + +### Ambiguous Classification +- Present multiple options with scores +- Explain reasoning for each +- Let user choose or specify custom path + +### RULE.md Instructions Unclear +- Ask user for clarification +- Offer to interpret instructions and ask for confirmation +- Document unclear instructions for future improvement + +### File Already Exists +- Check if filename conflicts with existing file +- Offer to: append timestamp, rename, overwrite, or choose different name +- Never overwrite without confirmation + +### Operation Fails +- Report error clearly +- Explain what went wrong +- Suggest alternatives or fixes +- Don't leave partial state (clean up if needed) + +## Integration with Governance + +This Skill automatically invokes the governance protocol: + +**Before operation**: +- Locate and read RULE.md +- Validate operation is allowed +- Check README.md for context + +**During operation**: +- Follow RULE.md specifications +- Execute any special workflows + +**After operation**: +- Update README.md +- Update parent README.md if needed +- Verify updates successful + +## Examples + +### Example 1: Simple Note + +**User**: "Save this note: Today I learned about transformer architecture in deep learning" + +**Skill workflow**: +1. Analyzes content → Technical/AI topic +2. Scans directories → Finds Research/AI/, Research/DeepLearning/, Miscellaneous/ +3. Reads RULE.md files → Research/AI/ purpose: "AI and machine learning research" +4. Recommends Research/AI/ (score: 95) +5. User confirms +6. Reads Research/AI/RULE.md → Files named `YYYY-MM-DD-topic.md` +7. Creates `2025-10-28-transformer-architecture.md` +8. Updates Research/AI/README.md +9. Reports success with file location + +### Example 2: Web Archival + +**User**: "readlater https://example.com/interesting-article" + +**Skill workflow**: +1. Detects URL +2. Scans directories → Finds ReadLater/ +3. Reads ReadLater/RULE.md → Purpose: "Archive web content" + - Instructions: "Fetch URL, convert to markdown, save in Articles/YYYY/MM/" +4. Recommends ReadLater/ (score: 100, exact match) +5. User confirms (or auto-confirm for obvious match) +6. Executes RULE.md instructions: + - WebFetch URL + - Extracts title: "Interesting Article About AI" + - Converts to markdown + - Creates `ReadLater/Articles/2025/10/2025-10-28_interesting-article-about-ai/` + - Saves article.md and metadata.yaml +7. Updates ReadLater/README.md and ReadLater/Articles/2025/10/README.md +8. Reports success with summary + +### Example 3: WorkLog Entry + +**User**: "Update my worklog" + +**Skill workflow**: +1. Detects worklog keyword +2. Scans directories → Finds Work/WorkLog/ +3. Reads Work/WorkLog/RULE.md: + - Purpose: "Daily work logs" + - Structure: YYYY/QX/MM-Month/ + - MUST verify datetime first + - Format: [specific template] +4. Recommends Work/WorkLog/ (score: 100) +5. User confirms +6. Executes RULE.md instructions: + - Runs `date` → 2025-10-28 + - Parses to 2025/Q4/10-October/ + - Checks if directory exists, creates if needed + - Checks if 2025-10-28.md exists + - Creates/updates file with template from RULE.md +7. Updates hierarchical README.md files: + - Work/WorkLog/2025/Q4/10-October/README.md + - Work/WorkLog/2025/Q4/README.md + - Work/WorkLog/README.md +8. Reports success with daily log location + +## Best Practices + +1. **Always read RULE.md completely** - Don't assume, read the full file +2. **Ask for confirmation on ambiguous choices** - User knows their needs +3. **Follow RULE.md exactly** - It's the contract for directory behavior +4. **Update README.md immediately** - Don't batch updates +5. **Report clearly** - User should know exactly what happened +6. **Handle errors gracefully** - Don't leave broken state +7. **Preserve existing structure** - Don't modify unrelated files +8. **Document custom workflows** - If RULE.md has special instructions, note them + +## Notes + +- This Skill is generic - it works with ANY directory structure +- Business logic comes from RULE.md, not hardcoded in Skill +- Classification is smart but always asks for user confirmation +- RULE.md format is natural language - no strict schema required +- Integration with governance agent is automatic +- Works in parallel with CLAUDE.md subagents independently diff --git a/skills/delete-content/SKILL.md b/skills/delete-content/SKILL.md new file mode 100644 index 0000000..d8955bc --- /dev/null +++ b/skills/delete-content/SKILL.md @@ -0,0 +1,414 @@ +--- +name: delete-content +description: Delete files from knowledge base with directory governance. Use when user wants to remove or delete content. Reads RULE.md to check deletion permissions and handles dependencies. +--- + +# Delete Content Skill + +Generic file deletion Skill that checks RULE.md permissions and handles dependencies safely. + +## When to use this Skill + +- User says "delete", "remove", "trash" +- User requests content deletion +- User wants to clean up old files + +## Workflow + +### 1. Identify Target File + +**If user provides file path**: +- Verify file exists using `ls` or Read +- Confirm file identity + +**If user provides topic/title only**: +- Search for file using Grep or Glob +- Pattern: `**/*keyword*.md` +- If multiple matches: present list, ask user to choose +- If no matches: report not found + +**Search strategies**: +1. Filename match: `find . -name "*keyword*"` +2. Content match: `grep -r "keyword" .` +3. README.md index: Search README.md files for references + +### 2. Read Directory RULE.md + +**Locate and read RULE.md**: +1. Check file's directory for RULE.md +2. If not found, check parent directories (inheritance) +3. Parse RULE.md for deletion rules + +**Check for**: +- Are deletions allowed? (some directories may be immutable or archive-only) +- Archive-instead rules (move to archive instead of delete) +- Backup requirements (create backup before delete) +- Dependency rules (check cross-references) +- Confirmation requirements + +**Example RULE.md deletion rules**: +```markdown +## Deletion Rules +- Deletions allowed with confirmation +- Check for cross-references before deleting +- Move to Archive/ subdirectory instead of permanent deletion +``` + +### 3. Check Dependencies + +**Search for cross-references**: +1. Use Grep to find links to this file: `grep -r "filename" .` +2. Search for references in README.md files +3. Check for reverse links (files this file links to) +4. Identify files that depend on this content + +**Categorize dependencies**: +- **Incoming**: Files that link to this file (will break if deleted) +- **Outgoing**: Files this file links to (won't break, but orphans references) +- **Bidirectional**: Cross-referenced files (mutual dependencies) + +**Severity assessment**: +- Critical: Many incoming links, part of important workflow +- Warning: Some incoming links, moderately used +- Low: Few or no dependencies + +### 4. User Confirmation + +**Present deletion summary**: +``` +⚠️ Delete confirmation required + +File: [path to file] +Size: [file size] +Last modified: [timestamp] + +Dependencies found: +- [file1.md] links to this file +- [file2.md] links to this file +(Total: X files reference this content) + +RULE.md policy: [deletion policy summary] + +Are you sure you want to delete this file? +- Yes, delete permanently +- Yes, move to archive (if RULE.md allows) +- No, cancel +- Show me the dependencies first +``` + +**If user requests dependency review**: +- Show each file that references this content +- Show the context (line where reference appears) +- Allow user to reconsider + +### 5. Execute Deletion + +**Based on RULE.md policy**: + +**Permanent deletion**: +```bash +rm [file path] +``` +- Only if RULE.md allows or user explicitly overrides +- Use Bash tool with rm command +- Verify deletion successful + +**Archive instead**: +```bash +# Create archive directory if not exists +mkdir -p Archive/ +# Move file to archive +mv [file path] Archive/[filename] +``` +- Follow RULE.md archive structure +- Preserve filename or add timestamp +- Update archive README.md + +**Backup then delete**: +```bash +# Create backup +cp [file path] [backup path] +# Then delete original +rm [file path] +``` +- Create backup per RULE.md specification +- Verify backup successful before deleting + +### 6. Governance Update + +**Update README.md**: +1. Read current README.md +2. Find entry for deleted file +3. Remove entry from file list +4. Add to "Recent Changes" section: + ```markdown + - YYYY-MM-DD: Removed filename.md + ``` +5. Update "Last updated" timestamp +6. Save README.md + +**Update parent README.md if needed**: +- If directory now empty, update parent +- Note directory is empty or removed + +**Handle cross-references**: +- Update files that referenced deleted content (if possible) +- Or add note in README.md: "Files with broken references: [list]" +- Offer to update broken links + +**Verify cleanup**: +- Ensure no orphaned references +- Check README.md is valid markdown +- Confirm directory structure intact + +### 7. Report to User + +**Confirm deletion complete**: +``` +✅ File deleted successfully + +Deleted: [path to file] +Method: [permanent deletion / moved to archive / backed up then deleted] + +README.md updated: +- [directory]/README.md + +Dependencies handled: +- [X] files need attention (broken links) +- [List of affected files] + +Recommendation: Review affected files to update/remove broken links +``` + +**If archived instead**: +``` +✅ File archived successfully + +Original: [original path] +Archived to: [archive path] +Archive method: [per RULE.md policy] + +README.md updated: +- [directory]/README.md +- Archive/README.md + +Note: File preserved in archive, not permanently deleted +``` + +## Special Cases + +### Immutable Directory + +If RULE.md specifies immutable: +```markdown +## RULE.md says: "This directory is immutable - no deletions allowed" +``` + +**Process**: +1. Warn user: "RULE.md indicates this directory should not have deletions" +2. Explain policy reasoning +3. Ask: "Do you want to override this rule?" +4. If yes: proceed with deletion and log rule override +5. If no: cancel operation + +### Archive-Only Policy + +If RULE.md requires archival instead: +```markdown +## RULE.md says: "Move to Archive/ instead of deleting" +``` + +**Process**: +1. Don't offer permanent deletion +2. Execute archive operation +3. Update both original and archive README.md +4. Report archive location + +### Batch Deletion + +If user requests deleting multiple files: +``` +User: "Delete all old notes from last year" +``` + +**Process**: +1. Identify all matching files +2. Check each file's RULE.md +3. Check dependencies for each +4. Present summary: "X files match, Y have dependencies" +5. Request batch confirmation +6. Execute deletions one by one +7. Report summary of all deletions + +### Directory Deletion + +If user wants to delete entire directory: +``` +User: "Delete the old-project directory" +``` + +**Process**: +1. Read directory RULE.md for deletion rules +2. Check parent directory RULE.md for subdirectory rules +3. Scan all files in directory for external dependencies +4. Present comprehensive summary +5. Warn: "This will delete X files and Y subdirectories" +6. Request explicit confirmation +7. Execute recursive deletion or archive +8. Update parent README.md + +### Soft Delete (Mark as Deleted) + +If RULE.md specifies soft delete: +```markdown +## RULE.md says: "Mark files as deleted in frontmatter instead of removing" +``` + +**Process**: +1. Don't delete file physically +2. Update frontmatter: `status: deleted` +3. Update README.md: mark as `[DELETED] filename.md` +4. File stays but marked as obsolete + +## Error Handling + +### File Not Found +``` +User: "Delete the transformer note" +→ Search for file +→ No matches found +→ Report: "I couldn't find a file about transformers. Nothing to delete." +``` + +### Multiple Matches +``` +User: "Delete the transformer note" +→ Find 3 files with "transformer" +→ Present list: "I found 3 files. Which one to delete?" +→ User selects → Proceed +``` + +### RULE.md Forbids Deletion +``` +RULE.md says: "Immutable directory" +→ Warn: "RULE.md forbids deletions in this directory" +→ Explain reasoning +→ Ask for override confirmation +→ If confirmed: proceed with warning note +``` + +### High-Impact Dependencies +``` +File has 50+ incoming references +→ Warn: "⚠️ HIGH IMPACT: 50+ files reference this content" +→ Show most critical dependencies +→ Recommend: "Consider archiving instead of deleting" +→ Require explicit "yes, delete anyway" confirmation +``` + +### Deletion Fails +``` +Bash rm command fails (permissions, file locked, etc.) +→ Report error clearly +→ Show exact error message +→ Suggest: "Check file permissions or if file is open in another program" +→ Offer alternatives: archive, rename, mark as deleted +``` + +### Broken References After Deletion +``` +Deletion successful but broken links remain +→ Report: "Deletion complete, but broken references detected in:" +→ List affected files +→ Offer: "Would you like me to update these files to remove broken links?" +→ If yes: update files to remove/fix references +``` + +## Integration with Governance + +This Skill automatically invokes the governance protocol: + +**Before deletion**: +- Locate and read RULE.md +- Validate deletion is allowed +- Check dependency policy + +**During deletion**: +- Follow RULE.md deletion method (delete, archive, backup) +- Execute safely + +**After deletion**: +- Update README.md +- Handle broken references +- Verify cleanup complete + +## Examples + +### Example 1: Simple Deletion + +**User**: "Delete the old transformer draft" + +**Skill workflow**: +1. Searches for file → Finds `Research/AI/2025-10-15-transformer-draft.md` +2. Reads Research/AI/RULE.md → Deletions allowed with confirmation +3. Checks dependencies → No references found +4. Asks confirmation: "Delete transformer-draft.md? No dependencies found." +5. User confirms +6. Executes `rm Research/AI/2025-10-15-transformer-draft.md` +7. Updates Research/AI/README.md (removes entry) +8. Reports: "✅ Deleted transformer-draft.md" + +### Example 2: Archive Instead + +**User**: "Delete the 2024 work logs" + +**Skill workflow**: +1. Finds Work/WorkLog/2024/ directory +2. Reads Work/WorkLog/RULE.md → "Move old logs to Archive/ instead of deleting" +3. Checks dependencies → Some cross-references to meeting notes +4. Presents: "Found 2024 logs (52 files). RULE.md policy: archive instead of delete" +5. User confirms +6. Creates `Work/WorkLog/Archive/2024/` if not exists +7. Executes `mv Work/WorkLog/2024/* Work/WorkLog/Archive/2024/` +8. Updates README.md files +9. Reports: "✅ Archived 52 log files to Archive/2024/" + +### Example 3: High-Impact Deletion + +**User**: "Delete the core-concepts document" + +**Skill workflow**: +1. Finds `Research/core-concepts.md` +2. Reads Research/RULE.md → Deletions allowed +3. Checks dependencies → 25 files reference this document +4. Warns: "⚠️ HIGH IMPACT: 25 files reference core-concepts.md" +5. Shows first 5 most critical dependencies +6. Recommends: "This is a foundational document. Consider archiving instead?" +7. User still chooses delete +8. Asks: "Are you absolutely sure? Type 'delete core-concepts' to confirm" +9. User confirms +10. Executes deletion +11. Updates README.md +12. Reports broken references: "25 files need attention" +13. Offers to help fix broken links + +## Best Practices + +1. **Always check dependencies** - Prevent broken knowledge base +2. **Read RULE.md first** - Respect deletion policies +3. **Archive when possible** - Preserve content instead of permanent deletion +4. **Confirm before deleting** - No accidental deletions +5. **Update README.md immediately** - Keep index accurate +6. **Handle broken links** - Offer to fix cross-references +7. **Report clearly** - User should know what was deleted and impact +8. **Follow RULE.md policies** - Even if user requests override + +## Notes + +- This Skill works with any directory structure by reading RULE.md +- Checks for dependencies to prevent broken knowledge base +- Offers archival as safer alternative to permanent deletion +- Always requires confirmation for destructive operations +- Maintains README.md index integrity +- Works in parallel with CLAUDE.md subagents +- Never deletes RULE.md files (requires explicit governance agent action) diff --git a/skills/move-content/SKILL.md b/skills/move-content/SKILL.md new file mode 100644 index 0000000..a1f0d24 --- /dev/null +++ b/skills/move-content/SKILL.md @@ -0,0 +1,484 @@ +--- +name: move-content +description: Move or rename files in knowledge base with directory governance. Use when user wants to move, relocate, or rename content. Reads RULE.md of both source and target directories. +--- + +# Move Content Skill + +Generic file move/rename Skill that respects both source and target RULE.md requirements. + +## When to use this Skill + +- User says "move", "relocate", "transfer", "rename" +- User requests reorganization +- User wants to reclassify content to different directory + +## Workflow + +### 1. Identify Source File + +**If user provides file path**: +- Verify file exists +- Confirm file identity + +**If user provides topic/title only**: +- Search for file using Grep or Glob +- Pattern: `**/*keyword*.md` +- If multiple matches: present list, ask user to choose +- If no matches: report not found + +**Search strategies**: +1. Filename match: `find . -name "*keyword*"` +2. Content match: `grep -r "keyword" .` +3. README.md index: Search README.md files for references + +### 2. Determine Target Location + +**If user specifies target**: +- Parse target path +- Verify target directory exists (or offer to create) +- Confirm target path with user + +**If user doesn't specify target**: +- Analyze content (read source file) +- Scan available directories +- Read RULE.md files to understand purposes +- Recommend target directory based on content +- Ask user for confirmation or alternative + +**Recommendation logic** (similar to add-content): +1. Analyze file content +2. Read RULE.md of potential target directories +3. Match content to directory purposes +4. Rank by suitability +5. Present top recommendation + +### 3. Read Both RULE.md Files + +**Read source directory RULE.md**: +1. Check if moving out is allowed +2. Check if any special handling required (e.g., "notify when file moved") +3. Understand current file format + +**Read target directory RULE.md**: +1. Check if moving in is allowed +2. Check file format requirements +3. Check naming conventions +4. Check if transformation needed +5. Understand target directory structure + +**Compare requirements**: +- Source format vs target format +- Source naming vs target naming +- Compatibility check + +### 4. Check Compatibility + +**Format compatibility**: +- Both use markdown → Compatible +- Source has frontmatter, target doesn't require → Compatible (but may want to remove) +- Source plain, target requires frontmatter → Needs transformation +- Different metadata requirements → Needs update + +**Naming compatibility**: +- Source: `topic-name.md` +- Target requires: `YYYY-MM-DD-topic-name.md` +- → Needs rename during move + +**Structure compatibility**: +- Source is single file +- Target requires directory structure (file + metadata) +- → Needs structure creation + +**Identify required transformations**: +1. Rename (filename format change) +2. Format conversion (add/remove frontmatter) +3. Structure change (file → directory with multiple files) +4. Content adaptation (modify to fit target requirements) + +### 5. User Confirmation + +**Present move summary**: +``` +📦 Move confirmation + +Source: [source path] +Target: [target path] + +Compatibility check: +✅ Format: Compatible (or ⚠️ Needs transformation) +✅ Naming: Compatible (or ⚠️ Will rename to: [new name]) +✅ Structure: Compatible (or ⚠️ Will restructure) + +RULE.md policies: +- Source: [policy summary] +- Target: [policy summary] + +Transformations needed: +- [List of changes required] + +Cross-references: +- [X] files reference this content + +Proceed with move? +- Yes (execute move with transformations) +- No (cancel) +- Show me what will change +``` + +**If transformations needed**: +- Explain each transformation clearly +- Show before/after examples +- Get explicit confirmation + +### 6. Execute Move + +**Basic move** (no transformation needed): +```bash +mv [source path] [target path] +``` + +**Move with rename**: +```bash +mv [source path] [target directory]/[new filename] +``` + +**Move with transformation**: +1. Read source file +2. Apply transformations: + - Add/remove/modify frontmatter + - Adjust content format + - Update internal references +3. Write to target location with new format +4. Verify target file created successfully +5. Delete source file (only after target verified) + +**Move with restructure**: +1. Create target directory structure +2. Split/reorganize content per target RULE.md +3. Create all required files in target +4. Verify all files created successfully +5. Delete source file/directory + +**Preserve metadata** (when possible): +- Modification timestamps +- Creation date (in frontmatter if present) +- Author information +- Tags and categories + +### 7. Update Cross-References + +**Find references to moved file**: +```bash +grep -r "[old path]" . +grep -r "[old filename]" . +``` + +**Update strategies**: +- **Relative paths**: Update to new relative path +- **Absolute paths**: Update to new absolute path +- **Title references**: No change needed if file title unchanged + +**Offer to update**: +``` +Found references in: +- [file1.md] (line 45) +- [file2.md] (line 12, 89) + +Would you like me to update these references? +- Yes, update all +- Yes, but let me review each +- No, I'll update manually +``` + +**Execute reference updates**: +- Use Edit tool to update each file +- Change old path to new path +- Verify updates successful +- Report which files were updated + +### 8. Governance Update + +**Update source directory README.md**: +1. Read source README.md +2. Remove entry for moved file +3. Add to "Recent Changes": "Moved filename.md to [target]" +4. Update "Last updated" timestamp +5. Save source README.md + +**Update target directory README.md**: +1. Read target README.md +2. Add entry for moved file (with description) +3. Add to "Recent Changes": "Added filename.md from [source]" +4. Update "Last updated" timestamp +5. Save target README.md + +**Update parent README.md files if needed**: +- If directories changed significance +- If directory now empty/no longer empty + +**Verify updates**: +- Both README.md files valid markdown +- Entry removed from source, added to target +- Timestamps current + +### 9. Report to User + +**Confirm move complete**: +``` +✅ File moved successfully + +From: [old path] +To: [new path] + +Transformations applied: +- [List of changes] + +Cross-references updated: +- [X] files updated +- [List of files] + +README.md updated: +- [source directory]/README.md (removed entry) +- [target directory]/README.md (added entry) + +Note: [Any important notes, e.g., "Format changed to match target requirements"] +``` + +## Special Cases + +### Rename in Same Directory + +If user only wants to rename (not move): +``` +User: "Rename transformer-draft to transformer-architecture" +``` + +**Process**: +1. Identify source file +2. Check RULE.md for naming conventions +3. Verify new name follows conventions +4. Execute rename: `mv old-name.md new-name.md` +5. Update references to this file +6. Update README.md (change entry name) +7. Report rename complete + +### Move Entire Directory + +If user wants to move entire directory: +``` +User: "Move the AI research folder to Projects" +``` + +**Process**: +1. Identify source directory +2. Read source and target RULE.md +3. Check all files in directory for compatibility +4. Identify all external references +5. Present comprehensive summary +6. Request confirmation +7. Execute directory move: `mv [source dir] [target dir]/` +8. Update all cross-references +9. Update README.md in both locations +10. Update parent README.md files + +### Incompatible Format Requires Manual Intervention + +If automatic transformation not possible: +``` +Source: Complex structured data +Target: Requires specific format that can't be auto-converted +``` + +**Process**: +1. Detect incompatibility +2. Warn user: "Automatic conversion not possible" +3. Explain what manual changes needed +4. Offer: "I can move the file, but you'll need to manually reformat" +5. Or: "I can create target structure and copy content, but you'll need to reorganize" +6. User decides next steps + +### Move with Merging + +If target already has file with same name: +``` +User: "Move note.md to Research/" +Research/note.md already exists +``` + +**Process**: +1. Detect name conflict +2. Read both files +3. Options: + - Rename: "note-2.md" or "note-YYYYMMDD.md" + - Merge: Combine contents (if compatible) + - Replace: Overwrite existing (with backup) +4. Present options to user +5. Execute chosen strategy + +### Preserve Directory Structure + +If moving subdirectory that has its own structure: +``` +Moving: Research/AI/transformers/ +Target: Projects/AIResearch/ +``` + +**Process**: +1. Check if should preserve subdirectory structure +2. Option A: `Projects/AIResearch/transformers/` (preserve) +3. Option B: `Projects/AIResearch/` (flatten) +4. Ask user preference +5. Execute accordingly +6. Update all README.md in hierarchy + +## Error Handling + +### Source File Not Found +``` +User: "Move transformer note to Projects" +→ Search for file +→ No matches +→ Report: "I couldn't find transformer note to move" +``` + +### Target Directory Doesn't Exist +``` +User: "Move file.md to NewCategory/" +NewCategory/ doesn't exist +→ Ask: "NewCategory doesn't exist. Create it?" +→ If yes: create directory, create RULE.md/README.md, then move +→ If no: cancel +``` + +### RULE.md Forbids Moving Out +``` +Source RULE.md: "Files cannot be moved out of this directory" +→ Warn: "Source RULE.md forbids moving files out" +→ Ask: "Override this rule?" +→ If yes: proceed with warning note +→ If no: cancel +``` + +### RULE.md Forbids Moving In +``` +Target RULE.md: "Only specific file types allowed" +Source file doesn't match +→ Warn: "Target RULE.md restrictions prevent this move" +→ Explain restrictions +→ Suggest: "Convert file format first or choose different target" +``` + +### Transformation Fails +``` +Attempting to add required frontmatter +Transformation fails (invalid YAML, etc.) +→ Report error +→ Keep source file intact +→ Don't create partial target +→ Suggest manual review +``` + +### Cross-Reference Update Fails +``` +Move successful but can't update all references +Some files locked, permission denied, etc. +→ Report: "Move complete, but couldn't update all references" +→ List files that need manual update +→ Provide old and new paths for manual fixing +``` + +## Integration with Governance + +This Skill automatically invokes the governance protocol: + +**Before move**: +- Read both source and target RULE.md +- Validate move is allowed +- Check compatibility + +**During move**: +- Apply required transformations +- Preserve important metadata +- Execute safely (verify target before deleting source) + +**After move**: +- Update both source and target README.md +- Update cross-references +- Verify complete + +## Examples + +### Example 1: Simple Move + +**User**: "Move transformer-draft from Research/AI to Projects/" + +**Skill workflow**: +1. Finds `Research/AI/transformer-draft.md` +2. Reads Research/AI/RULE.md → Moves allowed +3. Reads Projects/RULE.md → Files named `project-name.md`, requires frontmatter +4. Detects: needs frontmatter addition +5. Confirms: "Move to Projects/, will add required frontmatter" +6. User confirms +7. Reads source file +8. Adds frontmatter with title, date, status +9. Writes to `Projects/transformer-draft.md` +10. Updates cross-references (found 2) +11. Updates both README.md files +12. Reports: "✅ Moved with frontmatter added" + +### Example 2: Move with Rename + +**User**: "Move the old transformer note to ReadLater" + +**Skill workflow**: +1. Finds `Research/transformer-old.md` +2. Reads Research/RULE.md and ReadLater/RULE.md +3. ReadLater requires: `Articles/YYYY/MM/YYYY-MM-DD_title/article.md` +4. Detects: needs complete restructure +5. Warns: "Target requires directory structure, not single file" +6. Shows transformation: `transformer-old.md` → `Articles/2025/10/2025-10-28_transformer-old/article.md` +7. User confirms +8. Creates directory structure +9. Moves and renames file +10. Creates metadata.yaml (as ReadLater requires) +11. Updates README.md files +12. Reports: "✅ Moved and restructured per ReadLater requirements" + +### Example 3: Directory Move + +**User**: "Move the old-research folder to Archive" + +**Skill workflow**: +1. Finds `Research/old-research/` (15 files) +2. Reads Research/RULE.md and Archive/RULE.md +3. Checks all 15 files for external references → Found 3 references +4. Confirms: "Move old-research/ (15 files) to Archive/? 3 external references found" +5. User confirms +6. Executes: `mv Research/old-research/ Archive/` +7. Updates 3 files with broken references +8. Updates README.md: + - Research/README.md (removes subdirectory) + - Archive/README.md (adds subdirectory) +9. Reports: "✅ Moved 15 files, updated 3 references" + +## Best Practices + +1. **Check both RULE.md files** - Source and target may have different rules +2. **Verify compatibility** - Ensure file can fit in target format +3. **Transform carefully** - Preserve content integrity during format changes +4. **Update cross-references** - Prevent broken links +5. **Update both README.md** - Source (remove) and target (add) +6. **Verify before deleting source** - Ensure target created successfully +7. **Report transformations clearly** - User should know what changed +8. **Handle errors gracefully** - Don't leave partial state + +## Notes + +- This Skill works with any directory structure by reading RULE.md +- Respects both source and target governance rules +- Handles format transformations automatically when possible +- Updates cross-references to prevent broken knowledge base +- Maintains README.md indexes in both locations +- Works in parallel with CLAUDE.md subagents +- Can rename, move, and restructure all in one operation diff --git a/skills/search-content/SKILL.md b/skills/search-content/SKILL.md new file mode 100644 index 0000000..32b61a1 --- /dev/null +++ b/skills/search-content/SKILL.md @@ -0,0 +1,530 @@ +--- +name: search-content +description: Search and navigate knowledge base using README.md indexes, pattern matching, and directory tree analysis. Use when user searches for files, topics, mentions "where is", "find", "search for", or asks content location queries. +--- + +# Search Content Skill + +Navigate and search the knowledge base efficiently using AkashicRecords directory governance structure. + +## When to use this Skill + +- User asks "where is", "find", "search for" +- User queries file locations +- User looks for specific topics or content +- User needs to navigate knowledge base +- User asks "do I have notes about..." + +## Workflow + +### 1. Analyze Query + +**Parse user request**: +- Extract keywords and topics +- Identify search scope (specific directory or entire knowledge base) +- Determine search type (filename, content, topic, date-based) +- Assess query specificity (exact match vs fuzzy search) + +**Examples**: +``` +"Where are my transformer notes?" → Topic search, keyword: "transformer" +"Find files modified last week" → Date-based search +"Search for 'attention mechanism' in Research" → Content search, scoped to Research/ +"List all meeting notes from October" → Category + date search +``` + +### 2. Choose Search Strategy + +Select appropriate strategy based on query: + +#### Strategy 1: Structured Navigation (Preferred) +**When to use**: +- Query mentions directory names (Work, Research, Personal, etc.) +- Looking for specific categories or types +- Query has clear organizational clues + +**Method**: +- Start at root README.md or specified directory +- Follow directory index structure +- Use README.md files as curated navigation guides +- Narrow down systematically + +**Advantages**: +- Fast and efficient +- Leverages existing organization +- Follows curated structure + +#### Strategy 2: Pattern Search +**When to use**: +- Looking for filenames matching patterns +- User provides specific naming clues +- Need to find files by naming convention + +**Method**: +- Use Glob for filename patterns: `**/*keyword*.md` +- Filter by date if needed: files modified in last N days +- Use multiple patterns for comprehensive search + +**Advantages**: +- Direct filename matching +- Fast for filename-based queries +- Good for date-based searches + +#### Strategy 3: Deep Content Search +**When to use**: +- Looking for specific text or code within files +- Pattern/structured search insufficient +- Need comprehensive text search + +**Method**: +- Use Grep for content search: `grep -r "keyword" .` +- Search within specific file types +- Use Task subagent for complex multi-step searches + +**Advantages**: +- Finds content regardless of organization +- Comprehensive coverage +- Good for forgotten file locations + +### 3. Execute Search + +**Structured Navigation example**: +``` +User: "Find my AI research notes" + +1. Start at root, read README.md +2. Identify Research/ directory (purpose: "Technical and academic research") +3. Read Research/README.md +4. Find AI/ or DeepLearning/ subdirectories +5. Read Research/AI/README.md +6. List all files in index +7. Filter by relevance +8. Return matching files +``` + +**Pattern Search example**: +``` +User: "Find files about transformers" + +1. Use Glob: `**/*transformer*.md` +2. Results: + - Research/AI/2025-10-28-transformer-architecture.md + - Research/AI/2025-10-20-transformer-applications.md + - Work/Projects/transformer-project.md +3. Rank by modification date (most recent first) +4. Return results +``` + +**Deep Content Search example**: +``` +User: "Search for 'attention mechanism'" + +1. Use Grep: grep -r "attention mechanism" . --include="*.md" +2. Results (with context): + - Research/AI/transformer-architecture.md (3 matches) + - Research/AI/neural-networks.md (1 match) +3. Extract surrounding context for each match +4. Rank by relevance (match count, recency) +5. Return results with context snippets +``` + +### 4. Check Governance + +**For each result**: +1. Check directory RULE.md for read permissions +2. Skip files in restricted directories +3. Note if file requires special access + +**Permission check**: +``` +RULE.md says: "Restricted access - confidential" +→ Skip this file or warn user about restrictions +``` + +**Privacy considerations**: +- Respect RULE.md access restrictions +- Don't expose content from restricted directories +- Warn if search includes restricted areas + +### 5. Rank Results + +**Ranking criteria**: +1. **Relevance**: Keyword matches, topic similarity +2. **Recency**: Recently modified files ranked higher +3. **Location**: Files in expected directories ranked higher +4. **Completeness**: README.md-indexed files ranked higher (curated) + +**Scoring example**: +``` +File A: transformer-architecture.md +- Title match: +50 +- Recent (3 days): +30 +- In expected directory (Research/AI): +20 +- Listed in README: +10 +- Total: 110 + +File B: old-notes.md +- Content match only: +30 +- Old (3 months): +5 +- In Miscellaneous: +10 +- Not in README: +0 +- Total: 45 + +Result order: File A, then File B +``` + +### 6. Present Results + +**Clear result format**: +``` +📚 Search results for "[query]" + +Found [X] matches: + +1. [filename.md](path/to/file.md) ★★★★☆ + Location: [directory path] + Last modified: [date] + Description: [from README.md or first line] + Match: [Context snippet if content search] + +2. [another-file.md](path/to/another.md) ★★★☆☆ + Location: [directory path] + Last modified: [date] + Description: [description] + Match: [Context snippet] + +[More results...] + +Didn't find what you need? +- Try broader keywords +- Search in specific directory +- Check Archive/ for old content +``` + +**Include helpful metadata**: +- File location (full path) +- Last modified date +- Brief description from README.md +- Relevance score (stars or percentage) +- Context snippet (for content searches) + +### 7. Follow-up Options + +**After presenting results**: +``` +What would you like to do? +- Read [filename] +- Search within these results +- Refine search with different keywords +- Search in different directory +- Show more results +``` + +**Interactive refinement**: +- User can narrow down results +- Ask follow-up questions +- Navigate to related files +- Explore directory structure + +## Search Strategies in Detail + +### Structured Navigation + +**Step-by-step process**: +1. Identify starting point (root or specific directory) +2. Read starting README.md +3. Parse directory structure from README.md +4. Match query keywords to directory names/descriptions +5. Descend into most relevant subdirectory +6. Repeat until finding target files +7. List files from README.md index + +**Example**: +``` +Query: "Find meeting notes from October" + +1. Read root README.md +2. Find Work/ directory +3. Read Work/README.md +4. Find Meetings/ subdirectory +5. Read Work/Meetings/README.md +6. Filter entries by date (October) +7. Return matching files +``` + +**Advantages**: +- Leverages human-curated organization +- Fast and efficient +- Follows logical structure + +**Limitations**: +- Requires good README.md maintenance +- May miss files not indexed +- Depends on consistent organization + +### Pattern Search + +**Glob patterns**: +``` +**/*keyword*.md → Find files with "keyword" in name +**/*YYYY-MM-DD*.md → Find files with specific date format +Research/**/*.md → Find all markdown in Research/ +Work/Projects/**/*.md → Find all markdown in Work/Projects/ +``` + +**Advanced patterns**: +``` +**/{transformer,attention,neural}*.md → Multiple keywords +**/*2025-10*.md → October 2025 files +**/*.{md,txt} → Multiple extensions +``` + +**Date-based search**: +```bash +# Files modified in last 7 days +find . -name "*.md" -mtime -7 + +# Files modified in October 2025 +find . -name "*2025-10*.md" +``` + +**Advantages**: +- Direct filename matching +- Fast execution +- Good for date/name patterns + +**Limitations**: +- Only searches filenames +- Misses content matches +- Requires knowing naming conventions + +### Deep Content Search + +**Grep search**: +```bash +# Basic content search +grep -r "keyword" . --include="*.md" + +# Case-insensitive +grep -ri "keyword" . --include="*.md" + +# Multiple keywords (OR) +grep -rE "keyword1|keyword2" . --include="*.md" + +# With context lines +grep -r "keyword" . --include="*.md" -A 2 -B 2 +``` + +**Task subagent for complex searches**: +``` +User: "Find all notes about transformers that mention attention mechanism and were created in the last month" + +→ Too complex for single grep +→ Invoke Task subagent: + 1. Grep for "transformer" + 2. Filter results by "attention mechanism" + 3. Filter by date (last month) + 4. Return consolidated results +``` + +**Advantages**: +- Comprehensive text search +- Finds content regardless of location +- Good for forgotten file locations + +**Limitations**: +- Slower than other methods +- May return too many results +- High context consumption (use Task subagent for complex cases) + +## Search Optimization + +### Start Specific, Expand if Needed + +**Progression**: +1. Try structured navigation first (if logical directory exists) +2. If no results: try pattern search +3. If still no results: try deep content search +4. If still nothing: suggest broader keywords or check Archive/ + +**Example**: +``` +Query: "Find transformer notes" + +1. Structured: Check Research/AI/README.md → Found 2 files ✅ +2. Pattern: Not needed (found with structured) +3. Content: Not needed + +vs. + +Query: "Find notes about neural attention" + +1. Structured: Check Research/AI/README.md → No exact match +2. Pattern: **/*attention*.md → Found 1 file +3. Content: grep "neural attention" → Found 3 more files +4. Combined results, ranked by relevance +``` + +### Use README.md as Primary Index + +**README.md advantages**: +- Curated by user (most important files listed) +- Includes descriptions (better context) +- Organized logically (related files grouped) +- Faster than filesystem traversal + +**Always check README.md first** before deep searches. + +### Minimize Context Consumption + +**For simple searches**: +- Use Glob/Grep directly +- Return results without reading full files +- Only read files user wants to open + +**For complex searches**: +- Use Task subagent to handle complexity +- Subagent consumes context, not main agent +- Return only summarized results to user + +## Error Handling + +### No Results Found +``` +Query: "Find transformer notes" +→ No matches in any strategy + +→ Response: +"I couldn't find notes about transformers. + +Suggestions: +- Try broader keywords (AI, neural networks) +- Search in Archive/ for old content +- Check if files use different terminology +- Create new note if content doesn't exist" +``` + +### Too Many Results +``` +Query: "Find notes" +→ Returns 500+ matches + +→ Response: +"Found 500+ files matching 'notes'. + +Please narrow your search: +- Add more specific keywords +- Specify directory (Research, Work, Personal) +- Add date filter (from last week, October, etc.) +- Provide more context about what you're looking for" +``` + +### Ambiguous Query +``` +Query: "Find it" +→ Query too vague + +→ Response: +"Could you provide more details? + +What are you looking for? +- File name or topic keywords +- Approximate date or time period +- Which directory (Research, Work, etc.) +- Type of content (meeting notes, research, etc.)" +``` + +### Permission Denied +``` +Search encounters restricted directory +RULE.md: "Access restricted" + +→ Skip directory in results +→ Note: "Some directories were excluded due to access restrictions" +``` + +## Integration with Governance + +This Skill respects directory governance: + +**Before searching**: +- Check RULE.md for search permissions +- Respect access restrictions +- Note privacy constraints + +**During search**: +- Skip restricted directories +- Follow governance rules +- Maintain confidentiality + +**In results**: +- Only show accessible files +- Note if restricted areas skipped +- Respect RULE.md read permissions + +## Examples + +### Example 1: Topic Search + +**User**: "Where are my transformer architecture notes?" + +**Skill workflow**: +1. Analyzes query → Topic: transformer architecture +2. Chooses structured navigation (research topic) +3. Reads root README.md → Finds Research/ +4. Reads Research/README.md → Finds AI/ +5. Reads Research/AI/README.md +6. Finds 2 matches: + - transformer-architecture.md (3 days ago) + - transformer-applications.md (2 weeks ago) +7. Ranks by recency +8. Presents results with descriptions + +### Example 2: Date-Based Search + +**User**: "Find my meeting notes from last week" + +**Skill workflow**: +1. Analyzes query → Category: meetings, Date: last week +2. Chooses structured navigation + date filter +3. Reads root README.md → Finds Work/ +4. Reads Work/README.md → Finds Meetings/ +5. Reads Work/Meetings/README.md +6. Filters entries by date (last 7 days) +7. Finds 3 meetings +8. Presents chronologically + +### Example 3: Content Search + +**User**: "Search for 'attention mechanism' in my notes" + +**Skill workflow**: +1. Analyzes query → Content search, keyword: "attention mechanism" +2. Chooses deep content search +3. Executes: `grep -ri "attention mechanism" . --include="*.md"` +4. Finds 5 matches across 3 files +5. Extracts context snippets +6. Checks RULE.md permissions for each file +7. Ranks by relevance (match count + recency) +8. Presents with context snippets + +## Best Practices + +1. **Start with structured navigation** - Fastest and most relevant +2. **Use README.md indexes** - Curated by user, most important +3. **Minimize context** - Don't read files unless needed +4. **Rank results meaningfully** - Relevance + recency + location +5. **Provide context** - Show why files matched +6. **Offer follow-up** - Help user refine search +7. **Respect governance** - Check RULE.md permissions +8. **Handle edge cases** - No results, too many results, ambiguous queries + +## Notes + +- This Skill works with any directory structure +- Leverages README.md indexes for curated navigation +- Uses multiple search strategies for comprehensive coverage +- Respects RULE.md governance and access restrictions +- Minimizes context consumption with Task subagent for complex searches +- Works in parallel with CLAUDE.md subagents independently +- Provides interactive refinement for better results diff --git a/skills/update-content/SKILL.md b/skills/update-content/SKILL.md new file mode 100644 index 0000000..fe4d224 --- /dev/null +++ b/skills/update-content/SKILL.md @@ -0,0 +1,350 @@ +--- +name: update-content +description: Update existing files in knowledge base with directory governance. Use when user wants to modify, edit, or update existing content. Reads RULE.md to maintain format consistency and follows update rules. +--- + +# Update Content Skill + +Generic file update Skill that respects RULE.md constraints and maintains format consistency. + +## When to use this Skill + +- User says "update", "edit", "modify", "change" +- User references existing file or content +- User requests content revision +- User mentions specific file to update + +## Workflow + +### 1. Identify Target File + +**If user provides file path**: +- Verify file exists +- Confirm with user if ambiguous + +**If user provides topic/title only**: +- Search for file using Grep or Glob +- Pattern: `**/*keyword*.md` +- If multiple matches: present list, ask user to choose +- If no matches: report not found, offer to create instead + +**Search strategies**: +1. Filename match: `find . -name "*keyword*"` +2. Content match: `grep -r "keyword" .` +3. README.md index: Search README.md files for references + +### 2. Read Current Content + +**Load existing file**: +- Use Read tool to load full content +- Understand current structure: + - Frontmatter (if present) + - Section headings + - Content organization + - Formatting style + +**Analyze format**: +- Identify markdown structure +- Note any special formatting +- Detect metadata or frontmatter +- Understand content layout + +### 3. Read Directory RULE.md + +**Locate and read RULE.md**: +1. Check file's directory for RULE.md +2. If not found, check parent directories (inheritance) +3. Parse RULE.md for update rules + +**Check for**: +- Are updates allowed? (some directories may be append-only or immutable) +- Format requirements to maintain +- Required fields that must be preserved +- Update workflow (e.g., "always add changelog entry") +- Versioning requirements + +**Example RULE.md update rules**: +```markdown +## Update Rules +- Preserve frontmatter fields: title, date, tags +- Add "Last updated" timestamp to frontmatter +- Append changes to "Changelog" section +- Maintain markdown heading structure +``` + +### 4. Execute Update + +**Apply requested changes**: +- Use Edit tool for targeted changes +- Or Write tool for complete rewrites (if needed) +- Maintain existing format per RULE.md +- Preserve required fields/structure + +**Update modification metadata**: +- Update "Last updated" field (if present) +- Update modification timestamp in frontmatter +- Add changelog entry (if RULE.md requires) +- Preserve original creation date + +**Maintain consistency**: +- Keep same formatting style (indentation, line breaks, etc.) +- Preserve markdown structure (headings hierarchy) +- Maintain frontmatter format (if present) +- Keep cross-references valid + +### 5. Governance Update + +**Update README.md**: +1. Read current README.md +2. Find entry for this file +3. Update description if content changed significantly +4. Update "Last modified" timestamp +5. Add to "Recent Changes" section +6. Save README.md + +**Update parent README.md if needed**: +- If file significance changed +- If file moved to different category + +**Verify updates**: +- Check README.md is valid markdown +- Ensure timestamps are current +- Verify file is still listed correctly + +### 6. Report to User + +**Confirm update complete**: +``` +✅ File updated successfully + +File: [path to file] +Changes: [summary of changes made] +Format: [maintained per RULE.md] + +README.md updated: +- [directory]/README.md + +What changed: +[Brief description of modifications] +``` + +## Special Cases + +### Frontmatter Updates + +If file has YAML frontmatter: + +```yaml +--- +title: Original Title +date: 2025-10-20 +updated: 2025-10-28 # ← Update this +tags: [ai, ml] +--- + +[Content] +``` + +**Update process**: +1. Parse frontmatter +2. Preserve required fields (per RULE.md) +3. Update modification fields +4. Update content +5. Regenerate frontmatter with updates + +### Versioned Content + +If RULE.md requires versioning: + +```markdown +## Changelog + +### v1.2.0 (2025-10-28) +- [Changes made] + +### v1.1.0 (2025-10-25) +- [Previous changes] +``` + +**Update process**: +1. Read current version +2. Increment version number (per RULE.md versioning scheme) +3. Add changelog entry +4. Update content +5. Update version in frontmatter + +### Structured Content + +If content has specific structure (sections, tables, etc.): + +**Preserve structure**: +1. Identify section to modify +2. Update only targeted section +3. Maintain heading hierarchy +4. Keep other sections unchanged +5. Ensure valid markdown + +### Append-Only Updates + +If RULE.md specifies append-only (like logs): + +```markdown +## RULE.md says: "This directory is append-only" +``` + +**Update process**: +1. Read current content +2. Append new content at end +3. Don't modify existing content +4. Add timestamp for new entry +5. Update README.md + +### Cross-Reference Updates + +If file contains links to other files: + +**After update**: +1. Verify cross-references still valid +2. If file renamed/moved: update references +3. Check both directions (incoming and outgoing links) +4. Report any broken links + +## Error Handling + +### File Not Found +``` +User: "Update the transformer note" +→ Search for file with "transformer" keyword +→ No matches found +→ Ask: "I couldn't find a file about transformers. Would you like to create one instead?" +``` + +### Multiple Matches +``` +User: "Update the transformer note" +→ Find 3 files with "transformer": + 1. Research/AI/2025-10-28-transformer-architecture.md + 2. Research/AI/2025-10-20-transformer-applications.md + 3. Work/Projects/transformer-project.md +→ Present list: "I found 3 files. Which one?" +→ User selects → Proceed +``` + +### RULE.md Forbids Updates +``` +RULE.md says: "This directory is immutable" +→ Warn user: "RULE.md indicates this directory should not be modified" +→ Ask: "Do you want to proceed anyway (override rule)?" +→ If yes: update and note rule override in README.md +→ If no: cancel operation +``` + +### Format Unclear +``` +Current file has unusual format +→ Ask user: "This file has custom formatting. Should I: + 1. Maintain exact current format + 2. Apply standard format per RULE.md + 3. Let you specify format" +``` + +### Conflicting Changes +``` +File was modified since user last viewed +→ Warn: "This file was modified recently (timestamp)" +→ Show recent changes +→ Ask: "Proceed with update or review changes first?" +``` + +### Update Breaks Structure +``` +Proposed update would break markdown structure or frontmatter +→ Warn: "This update would create invalid structure" +→ Suggest: "I can apply a modified version that maintains structure" +→ Ask for confirmation +``` + +## Integration with Governance + +This Skill automatically invokes the governance protocol: + +**Before update**: +- Locate and read RULE.md +- Validate update is allowed +- Check format requirements + +**During update**: +- Maintain format per RULE.md +- Preserve required fields +- Follow update workflows + +**After update**: +- Update README.md +- Update modification timestamps +- Verify structure maintained + +## Examples + +### Example 1: Simple Update + +**User**: "Update the transformer architecture note with new information about attention mechanisms" + +**Skill workflow**: +1. Searches for file → Finds `Research/AI/2025-10-28-transformer-architecture.md` +2. Reads current content +3. Reads Research/AI/RULE.md → Updates allowed, maintain frontmatter +4. Applies changes using Edit tool +5. Updates "updated" field in frontmatter to 2025-10-28 +6. Updates Research/AI/README.md timestamp +7. Reports: "✅ Updated transformer-architecture.md with attention mechanisms section" + +### Example 2: Append-Only Log + +**User**: "Add today's entry to my worklog" + +**Skill workflow**: +1. Finds Work/WorkLog/2025/Q4/10-October/2025-10-28.md +2. Reads current content +3. Reads Work/WorkLog/RULE.md → Append-only, add timestamp +4. Appends new entry at end with timestamp +5. Updates hierarchical README.md files +6. Reports: "✅ Added entry to today's worklog" + +### Example 3: Versioned Document + +**User**: "Update the project spec with new requirements" + +**Skill workflow**: +1. Finds Work/Projects/project-spec.md +2. Reads current version → v1.1.0 +3. Reads Work/Projects/RULE.md → Requires versioning and changelog +4. Increments version → v1.2.0 +5. Adds changelog entry: + ```markdown + ### v1.2.0 (2025-10-28) + - Added new requirements section + ``` +6. Updates content +7. Updates frontmatter version field +8. Updates README.md +9. Reports: "✅ Updated project-spec.md to v1.2.0" + +## Best Practices + +1. **Always preserve existing structure** - Don't reformat unless requested +2. **Read RULE.md first** - Understand update constraints +3. **Use Edit for precision** - Target specific changes, don't rewrite entire file +4. **Maintain metadata** - Update timestamps, versions, changelog +5. **Update README.md immediately** - Keep index current +6. **Verify cross-references** - Ensure links still work +7. **Report clearly** - User should know what changed +8. **Handle conflicts gracefully** - Warn about concurrent modifications + +## Notes + +- This Skill works with any file structure by reading RULE.md +- Preserves format by default, changes only what's requested +- Respects update rules defined in RULE.md +- Automatically maintains README.md index +- Works in parallel with CLAUDE.md subagents +- Never updates RULE.md itself (that requires explicit permission via governance agent)