From 9ddf7bc2c1d226e4126a08eaed4b4cf719f598e3 Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sun, 30 Nov 2025 09:06:41 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 24 + README.md | 3 + commands/conform-note.md | 254 ++++++++++ commands/create-note.md | 324 +++++++++++++ commands/expand-graph.md | 730 +++++++++++++++++++++++++++++ commands/graph-add-relationship.md | 189 ++++++++ commands/graph-moc.md | 203 ++++++++ commands/graph-note.md | 185 ++++++++ commands/graph-stats.md | 198 ++++++++ commands/graph-validate.md | 225 +++++++++ commands/learning-path.md | 446 ++++++++++++++++++ commands/refresh-topic.md | 117 +++++ commands/rename-note.md | 232 +++++++++ commands/search-notes.md | 315 +++++++++++++ commands/update-note.md | 185 ++++++++ plugin.lock.json | 93 ++++ 16 files changed, 3723 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 commands/conform-note.md create mode 100644 commands/create-note.md create mode 100644 commands/expand-graph.md create mode 100644 commands/graph-add-relationship.md create mode 100644 commands/graph-moc.md create mode 100644 commands/graph-note.md create mode 100644 commands/graph-stats.md create mode 100644 commands/graph-validate.md create mode 100644 commands/learning-path.md create mode 100644 commands/refresh-topic.md create mode 100644 commands/rename-note.md create mode 100644 commands/search-notes.md create mode 100644 commands/update-note.md create mode 100644 plugin.lock.json diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..ca40975 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,24 @@ +{ + "name": "azkg", + "description": "Agent-maintained Zettelkasten knowledge graph", + "version": "0.1.0", + "author": { + "name": "Donald Thompson", + "email": "dthompson@witt3rd.com" + }, + "commands": [ + "./commands/conform-note.md", + "./commands/create-note.md", + "./commands/expand-graph.md", + "./commands/graph-add-relationship.md", + "./commands/graph-moc.md", + "./commands/graph-note.md", + "./commands/graph-stats.md", + "./commands/graph-validate.md", + "./commands/learning-path.md", + "./commands/refresh-topic.md", + "./commands/rename-note.md", + "./commands/search-notes.md", + "./commands/update-note.md" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..4d464ff --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# azkg + +Agent-maintained Zettelkasten knowledge graph diff --git a/commands/conform-note.md b/commands/conform-note.md new file mode 100644 index 0000000..d7d2fe7 --- /dev/null +++ b/commands/conform-note.md @@ -0,0 +1,254 @@ +--- +description: Restructure a note to follow standard repository format +--- + +# Conform Note + +Restructure a note to follow the standard repository format as defined in CLAUDE.md and README.md. + +## 0. Locate AZKG Repository + +**Check for AZKG_REPO_PATH environment variable:** + +- Use bash conditional: `if [ -z "$AZKG_REPO_PATH" ]; then REPO_PATH=$(pwd); else REPO_PATH="$AZKG_REPO_PATH"; fi` +- **If AZKG_REPO_PATH is set:** Use that path as the repository root +- **If AZKG_REPO_PATH is not set:** Use current working directory (pwd) +- Store result as REPO_PATH for all subsequent file operations + +**All file operations must use REPO_PATH:** + +- Read: `Read(REPO_PATH/filename.md)` or `Read("$REPO_PATH/filename.md")` +- Write: `Write(REPO_PATH/filename.md)` or `Write("$REPO_PATH/filename.md")` +- Edit: `Edit(REPO_PATH/filename.md)` or `Edit("$REPO_PATH/filename.md")` +- Grep: `Grep(pattern, path=REPO_PATH)` or with explicit path +- Glob: `Glob(pattern, path=REPO_PATH)` or with explicit path + +**Example usage:** + +``` +# Check environment variable +if [ -z "$AZKG_REPO_PATH" ]; then + REPO_PATH=$(pwd) +else + REPO_PATH="$AZKG_REPO_PATH" +fi + +# Then use REPO_PATH for all operations +Read("$REPO_PATH/agents.md") +``` + +**Concrete examples:** + +- If AZKG_REPO_PATH="/c/Users/dothompson/OneDrive/src/witt3rd/donald-azkg" + → Read("/c/Users/dothompson/OneDrive/src/witt3rd/donald-azkg/agents.md") +- If AZKG_REPO_PATH is not set and pwd is /c/Users/dothompson/OneDrive/src/witt3rd/donald-azkg + → Read("agents.md") or use full path from pwd + +## Task + +**IMPORTANT**: Transform the provided note to follow the question-oriented content synthesis approach defined in `_shared_content_synthesis.md`. + +The target structure should be: + +```markdown +--- +tags: [domain, technology, content-type] +last_refresh: YYYY-MM-DD # Optional, preserve if exists +source: # Optional, preserve if exists +--- + +# Note Title (Based on Central Question) + +## Central Question + +**Question**: [The single overarching question this note addresses] + +**Executive Summary**: 2-3 paragraphs previewing key insights and how the content resolves the central question. + +## Part I: [Domain Question 1] + +### [Specific Question 1.1] + +**Question**: [Clear, specific question from this section] + +**Answer**: [Comprehensive response including: +- Direct answer to the question +- Supporting evidence from content (specific quotes, examples, data) +- Technical details and concrete information +- Implications and connections to broader themes] + +### [Specific Question 1.2] + +**Question**: [Next specific question] + +**Answer**: [Evidence-based response...] + +## Part II: [Domain Question 2] + +### [Specific Question 2.1] + +**Question**: [Clear question] + +**Answer**: [Comprehensive response with content evidence...] + +[Continue with additional parts and sections as needed] + +## Resolution: [Answer to Central Question] + +Synthesize domain insights to definitively resolve the central question posed at the beginning. + +## Related Concepts + +### Prerequisites +- [[note]] - Why it's needed first + +### Related Topics +- [[note]] - Why it connects + +### Extends +- [[note]] - What this builds upon + +### Extended By +- [[note]] - What builds upon this + +### Examples +- [[note]] - Concrete implementation + +### Alternatives +- [[note]] - Different approach + +## References + +[1] +[2] +``` + +## Steps + +### 1. Read and Analyze + +- Read the specified note file +- Identify existing sections and their purpose +- Analyze the content to identify: + - The central question the note addresses + - Domain areas and their questions + - Specific questions within each section +- Preserve all valuable content + +### 2. Fix YAML Frontmatter + +- Ensure proper YAML format with `tags: [tag1, tag2, tag3]` +- Preserve `last_refresh` if it exists +- Ensure tags follow conventions: lowercase with hyphens + +### 3. Restructure Title and Central Question + +- Ensure single H1 title (update to reflect central question if needed) +- Add "## Central Question" section immediately after title +- Identify and state the single overarching question the note addresses +- Create executive summary (2-3 paragraphs) previewing key insights + +### 4. Transform Main Content to Question-Answer Format + +**Apply question-oriented synthesis** (from `_shared_content_synthesis.md`): + +- Organize existing content into Part I, Part II, etc. (domain questions) +- Within each part, create subsections with specific questions +- For each subsection: + - **Question**: State the specific question clearly + - **Answer**: Provide comprehensive response with evidence from content +- Preserve all substantive content, reorganized into Q&A format +- Maintain technical details, examples, and concrete information +- Add "## Resolution" section that synthesizes insights to answer central question + +### 5. Fix References Section + +- Change "Citations:" to "## References" +- Remove any "---" separator lines between content and references +- Remove attribution lines like "Answer from Perplexity: pplx.ai/share" +- Keep all citation links properly formatted +- Ensure References section comes AFTER Related Concepts + +### 6. Preserve Related Concepts + +- The "## Related Concepts" section contains typed relationships - be careful when editing +- This section IS the knowledge graph - relationships live directly in markdown files +- Ensure it appears before References section +- When conforming structure, preserve all existing relationships exactly as they are + +### 7. Final Structure Check + +The final order should be: + +1. YAML frontmatter +2. Title (H1) +3. ## Central Question (H2) with executive summary +4. ## Part I, Part II, etc. (H2) - Domain questions with Q&A subsections +5. ## Resolution (H2) - Answer to central question +6. ## Related Concepts (H2) - preserve existing relationships +7. ## References (H2) + +## Execution + +1. Use Read tool to load the note +2. Use Edit tool to make surgical changes OR Write tool if complete restructure needed +3. Preserve all wikilinks in format `[[note]]` NOT `[[note.md]]` +4. Maintain all existing content - only reorganize, don't remove substance + +## Important Rules + +- **Preserve content**: Only reorganize, don't delete valuable information +- **Preserve Related Concepts**: Keep all existing relationships exactly as written +- **Maintain wikilinks**: Use `[[note]]` format +- **Keep citations**: Transform format but preserve all references +- **Clean formatting**: Remove extraneous separators and attribution lines +- **Consistent headings**: Use H2 (##) for major sections + +## Example Transformations + +**Before:** + +```markdown +# Some Note + +Lots of intro text... + +## Content + +... + +Citations: +[1] https://example.com + +--- + +Answer from Perplexity: pplx.ai/share + +## Related Concepts +... +``` + +**After:** + +```markdown +--- +tags: [relevant, tags] +--- + +# Some Note + +Brief summary extracted from intro. + +## Content + +... + +## Related Concepts +... + +## References + +[1] +``` + +Execute this transformation for the note file specified by the user. diff --git a/commands/create-note.md b/commands/create-note.md new file mode 100644 index 0000000..d8a845e --- /dev/null +++ b/commands/create-note.md @@ -0,0 +1,324 @@ +--- +description: Create a new atomic note in the Zettelkasten knowledge graph +--- + +# Create Note + +You are tasked with creating a new atomic note in the Zettelkasten knowledge graph. Follow these steps systematically: + +## 0. Locate AZKG Repository + +**Check for AZKG_REPO_PATH environment variable:** + +- Use bash conditional: `if [ -z "$AZKG_REPO_PATH" ]; then REPO_PATH=$(pwd); else REPO_PATH="$AZKG_REPO_PATH"; fi` +- **If AZKG_REPO_PATH is set:** Use that path as the repository root +- **If AZKG_REPO_PATH is not set:** Use current working directory (pwd) +- Store result as REPO_PATH for all subsequent file operations + +**All file operations must use REPO_PATH:** + +- Read: `Read(REPO_PATH/filename.md)` or `Read("$REPO_PATH/filename.md")` +- Write: `Write(REPO_PATH/filename.md)` or `Write("$REPO_PATH/filename.md")` +- Edit: `Edit(REPO_PATH/filename.md)` or `Edit("$REPO_PATH/filename.md")` +- Grep: `Grep(pattern, path=REPO_PATH)` or with explicit path +- Glob: `Glob(pattern, path=REPO_PATH)` or with explicit path + +**Example usage:** + +``` +# Check environment variable +if [ -z "$AZKG_REPO_PATH" ]; then + REPO_PATH=$(pwd) +else + REPO_PATH="$AZKG_REPO_PATH" +fi + +# Then use REPO_PATH for all operations +Read("$REPO_PATH/agents.md") +``` + +**Concrete examples:** + +- If AZKG_REPO_PATH="/c/Users/dothompson/OneDrive/src/witt3rd/donald-azkg" + → Read("/c/Users/dothompson/OneDrive/src/witt3rd/donald-azkg/agents.md") +- If AZKG_REPO_PATH is not set and pwd is /c/Users/dothompson/OneDrive/src/witt3rd/donald-azkg + → Read("agents.md") or use full path from pwd + +## 1. Parse Input and Check for Duplicates + +**Input format:** User provides either: + +- A topic name: `/create-note semantic_routing` +- A descriptive phrase: `/create-note "Rust async runtime comparison"` + +**Duplicate detection:** + +- Search existing notes using Glob for similar filenames +- Search content using Grep for similar concepts +- If potential duplicate found, ask user: + - "Found existing note `similar_note.md`. Would you like to: + - Expand/refresh that note instead? + - Create a new distinct note (explain the difference)? + - Cancel?" + +## 2. Generate Filename + +**Naming convention:** + +- `topic_specific_concept.md` - lowercase with underscores +- Descriptive, not generic: `python_mcp_sdk.md` NOT `sdk.md` +- No folder prefixes in filename +- All notes go in repository root + +**Examples:** + +- Input: "semantic routing" → `semantic_routing.md` +- Input: "Rust async runtime comparison" → `rust_async_runtime_comparison.md` +- Input: "First principles thinking" → `first_principles_thinking.md` + +## 3. Research the Topic + +**Use Perplexity for comprehensive research:** + +- Formulate focused query: "Provide comprehensive, technical information about [TOPIC] including: definition, key concepts, how it works, common use cases, best practices, related technologies, and current state as of 2025. Focus on technical accuracy and concrete details." +- Use `mcp__perplexity-ask__perplexity_ask` tool +- Gather sufficient material for complete, self-contained note +- Capture citation sources for references section + +**Research depth:** + +- Note should be atomic (one concept) but complete +- Include enough context to be standalone +- Technical and specific, not superficial + +## 4. Discover Relationships + +**Analyze against existing knowledge graph using Grep and Read:** + +**Prerequisites:** What must be understood first? + +- Grep for foundational concepts this topic mentions +- Check existing notes for topics that should come before this +- Example: `mcp_security.md` requires `mcp_overview.md` first + +**Related concepts:** What connects at the same level? + +- Find complementary or adjacent topics via tag search +- Technologies that integrate or compare +- Example: `semantic_routing.md` relates to `agents.md` + +**Extends:** What does this build upon? + +- Specific notes this concept directly extends +- Base concepts or patterns this implements +- Example: `python_mcp_sdk.md` extends `mcp_overview.md` + +**Examples:** What concrete implementations exist? + +- Look for specific tool/framework notes +- Implementation patterns +- Example: `agents.md` has examples like `alita.md` + +**Alternatives:** Different approaches to same problem? + +- Competing technologies or patterns +- Different paradigms for same goal + +## 5. Generate Tag Recommendations + +**Read `tag_system.md` for complete tag catalog** + +**Select 3-6 tags across multiple dimensions:** + +1. **Technology/Language:** `#python`, `#rust`, `#typescript`, etc. +2. **Framework/Tool:** `#react`, `#mcp`, `#fastmcp`, etc. +3. **Domain/Discipline:** `#agents`, `#llm`, `#security`, etc. +4. **Content Type:** `#api`, `#guide`, `#pattern`, `#reference`, etc. +5. **Cross-cutting Themes:** `#async`, `#optimization`, `#testing`, etc. +6. **Method/Thinking:** `#first-principles`, `#systems-thinking`, etc. + +**Tag format:** lowercase with hyphens in YAML array + +```yaml +tags: [python, mcp, agents, sdk, api] +``` + +## 6. Write the Note + +**IMPORTANT**: Follow the question-oriented content synthesis approach defined in `_shared_content_synthesis.md`. + +**Note Structure Requirements:** + +The note MUST follow this question-answering paradigm: + +```markdown +--- +tags: [tag1, tag2, tag3, tag4, tag5] +--- + +# Note Title (Based on Central Question) + +## Central Question + +**Question**: [The single overarching question this note addresses] + +**Executive Summary**: 2-3 paragraphs previewing key insights and how the content resolves the central question. + +## Part I: [Domain Question 1] + +### [Specific Question 1.1] + +**Question**: [Clear, specific question from this section] + +**Answer**: [Comprehensive response including: +- Direct answer to the question +- Supporting evidence (specific quotes, examples, data from research) +- Technical details and concrete information +- Implications and connections to broader themes] + +### [Specific Question 1.2] + +**Question**: [Next specific question] + +**Answer**: [Evidence-based response...] + +## Part II: [Domain Question 2] + +### [Specific Question 2.1] + +**Question**: [Clear question] + +**Answer**: [Comprehensive response with evidence...] + +[Continue with additional parts and sections as needed] + +## Resolution: [Answer to Central Question] + +Synthesize domain insights to definitively resolve the central question posed at the beginning. + +## Related Concepts + +### Prerequisites +- [[prerequisite_note]] - Why it's needed first + +### Related Topics +- [[related_note]] - Connection explanation + +### Extends +- [[base_note]] - What this builds upon + +## References + +[1] Source URL from Perplexity research +[2] Source URL from Perplexity research +``` + +**Content Synthesis Guidelines** (from `_shared_content_synthesis.md`): + +**DO**: +- Create complete educational document that systematically answers questions +- Include specific details, quotes, examples, data points from research +- Build understanding progressively from atomic to central question +- Provide standalone educational value for readers learning the topic +- Write for LLM context consumption and human reading +- Use wikilinks `[[note]]` to reference existing notes +- Include code examples where appropriate +- Be technical and specific with concrete, actionable information + +**DO NOT**: +- Simply analyze the question structure or list questions without substantial answers +- Use vague generalities or hyperbolic language +- Include marketing claims or unsupported assertions + +## 7. Add Bidirectional Relationships + +**Update connected notes using Edit tool:** + +For each relationship discovered: + +1. **Read the target note** to find its "Related Concepts" section +2. **Add inverse relationship:** + - If new note extends X → Add new note to X's "Extended By" section + - If new note has prerequisite X → Add new note to X's "Extended By" or "Related Topics" + - If new note relates to X → Add new note to X's "Related Topics" + +**Example:** + +```markdown +# In agents.md - add to "Related Topics" section: +- [[semantic_routing]] - Enables intelligent model selection for agent tasks +``` + +## 8. Update MOC Files + +**Identify relevant MOC files using Glob:** + +- Check tags to determine which MOCs apply +- Common MOCs: `agents_moc.md`, `mcp_moc.md`, `rust_moc.md`, `typescript_moc.md`, `python_moc.md`, `writing_moc.md` + +**For each relevant MOC:** + +- Read the MOC file +- Find appropriate section to add link +- Add wikilink with brief context: `- [[new_note]] - Brief description` +- Maintain MOC organization and structure +- Use Edit tool for surgical updates + +## 9. Provide Summary + +**Report to user:** + +``` +Created new note: `new_note.md` + +**Tags:** tag1, tag2, tag3, tag4, tag5 + +**Relationships established:** +- Prerequisites: 2 notes +- Related concepts: 3 notes +- Extends: 1 note +- Examples: 2 notes + +**Bidirectional links updated:** +- Updated 5 notes with inverse relationships + +**MOCs updated:** +- moc_name_moc.md (added to "Section Name") +- other_moc.md (added to "Other Section") + +**Next steps:** +- Review the note at `new_note.md` +- Use `/graph-note new_note.md` to verify relationships +- Use `/expand-graph new_note.md` to discover additional connections +``` + +## Important Constraints + +**Critical rules:** + +- ALWAYS use wikilink format `[[note]]` not `[[note.md]]` +- MAINTAIN bidirectionality - update both notes in every relationship +- ENSURE atomicity - one complete, usable concept per note +- NO hyperbolic language or marketing claims +- ALL notes go in repository root (no subdirectories) +- Use Write for new files, Edit for updating existing files +- Use Grep/Glob for discovery, Read for content analysis + +**Tools to use:** + +- **Write** - Create new markdown file +- **Edit** - Update existing notes (add relationships, update MOCs) +- **Read** - Read tag_system.md, MOC files, existing notes +- **Grep** - Search for similar concepts, find notes by tag +- **Glob** - Find MOC files, check for duplicates +- **mcp__perplexity-ask** - Research the topic + +**Quality checks before writing:** + +- Is this truly atomic (one concept)? +- Is it complete enough to stand alone? +- Are relationships meaningful and justified? +- Do tags span multiple dimensions? +- Is content technical and specific? + +Execute these steps for the topic provided by the user. diff --git a/commands/expand-graph.md b/commands/expand-graph.md new file mode 100644 index 0000000..8251929 --- /dev/null +++ b/commands/expand-graph.md @@ -0,0 +1,730 @@ +--- +description: Discover missing relationships for a note via multi-strategy analysis +--- + +# Expand Graph + +Discover missing relationships between a note and the rest of the knowledge graph through multi-strategy analysis. + +## 0. Locate AZKG Repository + +**Check for AZKG_REPO_PATH environment variable:** + +- Use bash conditional: `if [ -z "$AZKG_REPO_PATH" ]; then REPO_PATH=$(pwd); else REPO_PATH="$AZKG_REPO_PATH"; fi` +- **If AZKG_REPO_PATH is set:** Use that path as the repository root +- **If AZKG_REPO_PATH is not set:** Use current working directory (pwd) +- Store result as REPO_PATH for all subsequent file operations + +**All file operations must use REPO_PATH:** + +- Read: `Read(REPO_PATH/filename.md)` or `Read("$REPO_PATH/filename.md")` +- Write: `Write(REPO_PATH/filename.md)` or `Write("$REPO_PATH/filename.md")` +- Edit: `Edit(REPO_PATH/filename.md)` or `Edit("$REPO_PATH/filename.md")` +- Grep: `Grep(pattern, path=REPO_PATH)` or with explicit path +- Glob: `Glob(pattern, path=REPO_PATH)` or with explicit path + +**Example usage:** + +``` +# Check environment variable +if [ -z "$AZKG_REPO_PATH" ]; then + REPO_PATH=$(pwd) +else + REPO_PATH="$AZKG_REPO_PATH" +fi + +# Then use REPO_PATH for all operations +Read("$REPO_PATH/agents.md") +``` + +**Concrete examples:** + +- If AZKG_REPO_PATH="/c/Users/dothompson/OneDrive/src/witt3rd/donald-azkg" + → Read("/c/Users/dothompson/OneDrive/src/witt3rd/donald-azkg/agents.md") +- If AZKG_REPO_PATH is not set and pwd is /c/Users/dothompson/OneDrive/src/witt3rd/donald-azkg + → Read("agents.md") or use full path from pwd + +## 1. Parse Input and Load Note + +**Input format:** User provides: + +- A note name: `/expand-graph mcp_security.md` +- Or just the topic: `/expand-graph mcp_security` + +**Normalize and validate:** + +- Add `.md` extension if missing +- Use Glob to verify the target note exists +- If not found, suggest similar notes using Glob + +**Read the target note:** + +- Use Read tool to get full content +- Extract YAML tags +- Extract main concepts and topics +- Parse current "Related Concepts" section to see existing relationships + +## 2. Extract Key Concepts + +**Analyze note content for:** + +**Technical terms:** + +- Technologies mentioned (Python, Rust, MCP, OAuth, etc.) +- Frameworks and tools (FastMCP, React, etc.) +- Protocols and standards (HTTP, JWT, RFC 8707, etc.) + +**Domain concepts:** + +- Core ideas discussed (authentication, security, agents, etc.) +- Patterns mentioned (observer, factory, reactive, etc.) +- Problem domains (enterprise, web, async, etc.) + +**Wikilinks:** + +- Existing wikilinks in content `[[note]]` +- Are these also in "Related Concepts"? If not, they're candidates to add + +**Tags:** + +- YAML frontmatter tags provide high-level domains + +**Output concept extraction:** + +``` +📖 Analyzing mcp_security.md... + +🔍 Key concepts identified: + Technologies: OAuth, JWT, SAML, Active Directory + Domains: security, authentication, authorization, privacy + Protocols: RFC 8707, Resource Indicators, OAuth flows + Patterns: least privilege, defense in depth, audit logging + Tags: #mcp #protocol #security #authentication #authorization + +📊 Current relationships: + ✅ Prerequisites: 2 (mcp_overview, mcp_architecture) + ✅ Related Topics: 3 + ✅ Extends: 1 + ✅ Examples: 0 + ✅ Alternatives: 0 +``` + +## 3. Multi-Strategy Relationship Discovery + +**Strategy 1: Content-Based Search (Grep)** + +For each key concept, search other notes: + +``` +Searching for "OAuth" across knowledge base... +Found in: +- oauth_fundamentals.md (15 mentions) +- api_security.md (8 mentions) +- enterprise_auth.md (12 mentions) + +Searching for "authentication" across knowledge base... +Found in: +- fastmcp_auth.md (20 mentions) +- api_security.md (18 mentions) +- enterprise_auth.md (25 mentions) +``` + +**Filter out:** + +- The target note itself +- Notes already in "Related Concepts" section +- Low-relevance matches (1-2 mentions) + +**Strategy 2: Tag-Based Discovery** + +Use Grep to find notes with overlapping tags: + +``` +Target has tags: #mcp #security #authentication + +Finding notes with overlapping tags... +Use Grep to search for "tags: [" in YAML frontmatter +Parse out tags and find overlaps: +- #mcp + #security: mcp_implementation.md, mcp_tools.md +- #security + #authentication: api_security.md, zero_trust.md +- #mcp (any): 12 other MCP-related notes +``` + +**Strategy 3: Wikilink Analysis** + +Use Grep to find wikilinks in target note content: + +``` +Checking wikilinks in content vs "Related Concepts" section... + +Found in content but NOT in "Related Concepts": +- [[mcp_overview]] - mentioned in text but not in prerequisites +- [[oauth_fundamentals]] - referenced but not linked formally + +Use Grep to find backlinks (other notes linking to this note): +Found in other notes' "Related Concepts" sections pointing here: +- fastmcp_auth.md lists this as "related" (we should reciprocate) +``` + +**Strategy 4: Research with Perplexity** + +Ask targeted questions: + +``` +Query 1: "What foundational knowledge is required to understand [main topic of note]?" +Query 2: "What concepts are commonly related to [main topic] in practice?" +Query 3: "What are concrete examples or implementations of [main topic]?" +Query 4: "What are alternative approaches to [main topic]?" +``` + +Use Perplexity responses to: + +- Discover conceptual prerequisites +- Find related domains +- Identify common patterns +- Suggest examples and alternatives + +## 4. Classify and Score Relationships + +**For each discovered note, determine:** + +### Relationship Type + +**Prerequisites:** Does target need this first? + +- Contains foundational concepts mentioned in target +- Target assumes knowledge from this note +- Complexity: This note is simpler/more basic +- Example: mcp_overview → mcp_security + +**Related Topics:** Parallel/complementary topics? + +- Same level of complexity +- Different but connected domain +- Solve similar problems differently +- Example: api_security ↔ mcp_security + +**Extends:** Does target build on this? + +- Target is specialized version +- Adds capabilities to base concept +- Target assumes this as foundation +- Example: mcp_security extends mcp_architecture + +**Examples:** Is this a concrete implementation? + +- Shows practical application of target concepts +- Code/pattern implementing target ideas +- Case study of target in practice +- Example: fastmcp_auth is example of mcp_security + +**Alternatives:** Different approach to same problem? + +- Solves same problem differently +- Competing technology or pattern +- Different paradigm +- Example: zero_trust vs traditional_security + +### Confidence Score + +**High (★★★★★):** + +- Many shared concepts (10+) +- Strong semantic relationship +- Confirmed by Perplexity research +- Explicitly mentioned in content +- Example: OAuth fundamentals for OAuth-heavy security note + +**Medium (★★★☆☆):** + +- Moderate overlap (5-9 concepts) +- Reasonable semantic connection +- Supported by tag overlap +- Mentioned indirectly +- Example: General API security for MCP security + +**Low (★★☆☆☆):** + +- Minimal overlap (2-4 concepts) +- Weak semantic connection +- Speculative relationship +- Not mentioned in content +- Example: Zero trust model for MCP (valid but tangential) + +### Evidence Collection + +**For each relationship, capture:** + +- **Frequency:** How many concept matches? +- **Quotes:** Specific text showing connection +- **Location:** Where in note is this relevant? +- **Research:** What did Perplexity say? +- **Reasoning:** Why should these be linked? + +## 5. Present Suggestions + +**Format as organized report:** + +```markdown +# Graph Expansion: mcp_security.md + +Found **12 potential relationships** across 8 notes + +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +## 📚 Suggested Prerequisites (2) + +### 1. [[mcp_overview]] → prerequisite +**Confidence:** ★★★★★ High + +**Evidence:** +- Mentioned 3 times in target note +- Target references "MCP fundamentals" and "protocol basics" +- Research confirms: "Understanding MCP basics required before security" + +**Reasoning:** Can't understand MCP security without knowing what MCP is. +The security model builds directly on protocol concepts. + +**Current status:** Referenced in content but missing from "Related Concepts" + +--- + +### 2. [[oauth_fundamentals]] → prerequisite +**Confidence:** ★★★★★ High + +**Evidence:** +- 15 mentions of "OAuth" in target note +- Entire section dedicated to "OAuth Flows" +- Tags overlap: #authentication, #security +- Research confirms: "OAuth knowledge essential for MCP auth" + +**Reasoning:** OAuth is the primary authentication mechanism. Deep understanding +needed before tackling MCP-specific OAuth implementation. + +**Current status:** Not currently linked + +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +## 🔗 Suggested Related Topics (4) + +### 3. [[enterprise_architecture]] → related +**Confidence:** ★★★☆☆ Medium + +**Evidence:** +- Both discuss: VNet integration, DLP, enterprise deployment +- 8 shared concepts +- Tags overlap: #enterprise + +**Reasoning:** Both address enterprise concerns at similar abstraction level. +MCP security is part of broader enterprise architecture. + +**Current status:** Not currently linked + +--- + +### 4. [[api_security_best_practices]] → related +**Confidence:** ★★★☆☆ Medium + +**Evidence:** +- MCP is API protocol +- 12 security best practices mentioned in both +- Research: "General API security principles apply to MCP" + +**Reasoning:** MCP security inherits from general API security principles. +Provides broader context for MCP-specific patterns. + +**Current status:** Not currently linked + +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +## 🏗️ Suggested "Extends" (1) + +### 5. mcp_security extends [[mcp_architecture]] +**Confidence:** ★★★★★ High + +**Evidence:** +- Security is explicit layer on architecture diagram +- Target states: "Security model built on top of MCP architecture" +- Architecture defines components, security defines protections + +**Reasoning:** Security adds protection layer to architectural components. +Cannot exist without the architecture it secures. + +**Current status:** Architecture listed as prerequisite, should be "extends" + +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +## 💡 Suggested Examples (3) + +### 6. [[fastmcp_authentication]] → example +**Confidence:** ★★★★★ High + +**Evidence:** +- Python implementation of MCP auth patterns +- Shows OAuth flow implementation +- Research: "FastMCP demonstrates MCP security in practice" + +**Reasoning:** Concrete Python code implementing concepts discussed in target. +Shows theory in action. + +**Current status:** Not currently linked + +--- + +### 7. [[csharp_mcp_auth]] → example +**Confidence:** ★★★★☆ High + +**Evidence:** +- C# implementation of same patterns +- Demonstrates enterprise auth integration +- Tags: #csharp, #mcp, #authentication + +**Reasoning:** Alternative language implementation showing same concepts. +Useful for enterprise/.NET developers. + +**Current status:** Not currently linked + +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +## 🔄 Suggested Alternatives (2) + +### 8. [[zero_trust_security_model]] → alternative +**Confidence:** ★★☆☆☆ Low + +**Evidence:** +- Different security paradigm +- Both address: authentication, authorization, least privilege +- Research: "Zero trust can be applied to MCP deployments" + +**Reasoning:** Alternative security philosophy applicable to MCP. +Different approach to similar goals. + +**Current status:** Not currently linked + +--- + +## 📊 Discovery Statistics + +- **Total candidates examined:** 93 notes +- **Content matches found:** 23 notes +- **Tag overlaps found:** 15 notes +- **After filtering:** 12 high-quality suggestions +- **Confidence breakdown:** + - High (★★★★★): 5 suggestions + - Medium (★★★☆☆): 5 suggestions + - Low (★★☆☆☆): 2 suggestions + +## 💡 Insights + +**Critical missing prerequisite:** oauth_fundamentals +This note is heavily referenced but not formally linked. High priority addition. + +**Weak example coverage:** Only 0 examples currently +Consider adding fastmcp_authentication and csharp_mcp_auth to show practical application. + +**Architecture relationship:** Currently listed as prerequisite +Should be "extends" relationship - security is layer on architecture. + +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +## 6. User Review and Approval + +**Offer interaction modes:** + +``` +How would you like to proceed? + +[A] Accept all high-confidence suggestions (★★★★★) +[R] Review each suggestion individually +[C] Custom selection (specify which to add) +[S] Save suggestions to file for later review +[Q] Quit without changes + +Choice: █ +``` + +**If user chooses [R] (Review):** + +``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +Review 1 of 12 + +Add [[mcp_overview]] as prerequisite? + +Confidence: ★★★★★ High +Evidence: Referenced 3 times, foundational concept +Reasoning: Must understand MCP basics before security + +[Y] Yes, add this relationship +[N] No, skip this one +[E] Edit relationship type (suggest different type) +[?] Show full context from both notes +[S] Skip remaining and finish + +Choice: █ +``` + +**Track decisions:** + +- Accepted relationships +- Rejected relationships (with reasons) +- Modified relationships (type changes) + +## 7. Update Markdown Files + +**For each accepted relationship:** + +### Update Target Note + +Use Edit tool to update target note's "Related Concepts" section: + +**Read the target note:** + +``` +Use Read tool to get full content +Parse "Related Concepts" section +``` + +**Add forward relationship:** + +```markdown +## Related Concepts + +### Prerequisites +- [[mcp_overview]] - Must understand MCP basics first +- [[oauth_fundamentals]] - OAuth is primary auth mechanism +``` + +**Use Edit tool** to surgically insert new relationships in appropriate subsections. + +### Update Related Notes + +**For each note mentioned, add inverse relationship:** + +**Read the related note:** + +``` +Use Read tool to get its "Related Concepts" section +``` + +**Add bidirectional inverse:** + +If target has "Prerequisites: [[mcp_overview]]" +Then mcp_overview gets "Extended By: [[target]]" + +If target has "Related Topics: [[api_security]]" +Then api_security gets "Related Topics: [[target]]" + +If target has "Extends: [[mcp_architecture]]" +Then mcp_architecture gets "Extended By: [[target]]" + +**Use Edit tool** to add inverse relationships to each related note. + +### Maintain Bidirectionality + +**Ensure every relationship has an inverse:** + +| Forward Type | Inverse Type | +|--------------|--------------| +| Prerequisites | Extended By or Related Topics | +| Related Topics | Related Topics (symmetric) | +| Extends | Extended By | +| Examples | Extended By | +| Alternatives | Alternatives (symmetric) | + +## 8. Provide Completion Report + +```markdown +✅ Graph Expansion Complete! + +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +## Changes Applied + +### mcp_security.md + +**Added relationships:** +✅ Prerequisites: 2 + - [[mcp_overview]] - Must understand MCP basics first + - [[oauth_fundamentals]] - OAuth is primary auth mechanism + +✅ Related Topics: 3 + - [[enterprise_architecture]] - Parallel enterprise concerns + - [[api_security_best_practices]] - General API security principles + - [[fastmcp_authentication]] - Moved from suggested examples + +✅ Extends: 1 (modified) + - [[mcp_architecture]] - Changed from prerequisite to extends + +✅ Examples: 2 + - [[fastmcp_authentication]] - Python implementation + - [[csharp_mcp_auth]] - C# implementation + +**Rejected:** +❌ [[zero_trust_security_model]] - User declined (too tangential) + +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +## Bidirectional Updates + +Updated 9 additional notes with inverse relationships: +- mcp_overview.md → added to Extended By +- oauth_fundamentals.md → added to Extended By +- enterprise_architecture.md → added to Related Topics +- api_security_best_practices.md → added to Related Topics +- mcp_architecture.md → moved to Extended By (from prerequisite inverse) +- fastmcp_authentication.md → added to Extended By +- csharp_mcp_auth.md → added to Extended By + +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +## Knowledge Graph Stats + +**Before expansion:** +- Total relationships in mcp_security.md: 6 + +**After expansion:** +- Total relationships in mcp_security.md: 12 (+6) +- Files modified: 10 (target + 9 related notes) + +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +## Quality Improvements + +🎯 **Closed gaps:** + - Connected heavily-referenced OAuth concepts + - Added missing example implementations + - Corrected architecture relationship type + +📈 **Coverage increase:** + - Prerequisites: 2 → 4 (+100%) + - Examples: 0 → 2 (new coverage) + - Related Topics: 3 → 6 (+100%) + +🔗 **Network density:** + - mcp_security.md now has 12 total relationships (was 6) + - Better integrated into knowledge graph + +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +## Next Steps + +💡 **Suggestions:** +1. Run `/learning-path mcp_security` to see updated prerequisite chain +2. Run `/expand-graph oauth_fundamentals` to enrich that critical note +3. Run `/graph-validate` to verify all bidirectional links + +🔄 **Consider expanding:** +- fastmcp_authentication.md (added as example, may need more connections) +- csharp_mcp_auth.md (added as example, may need more connections) + +📊 **Graph health:** +✅ All relationships bidirectional +✅ No orphaned nodes created +✅ Relationship types semantically appropriate +``` + +## 9. Handle Edge Cases + +**No new relationships found:** + +``` +✅ Graph Analysis Complete + +No new high-confidence relationships discovered for mcp_security.md + +**Current coverage:** +- Prerequisites: 3 (comprehensive) +- Related Topics: 5 (well-connected) +- Extends: 1 (appropriate) +- Examples: 2 (good coverage) +- Alternatives: 1 (adequate) + +**Analysis:** +- 93 notes examined +- 0 high-confidence matches found +- This note appears well-integrated + +💡 This is actually good news - the note is already well-connected! +``` + +**Conflicting relationships:** + +``` +⚠️ Potential Conflict Detected + +[[mcp_architecture]] appears as both: +- Prerequisite (current) +- Should extend (suggested) + +**Analysis:** +A note cannot both be a prerequisite AND be extended by the same note. + +**Recommendation:** +Change to "extends" because: +- Security is specialized layer on architecture +- "extends" captures that security builds upon architecture +- Prerequisites should be for foundational knowledge + +**Action:** +[Y] Accept recommendation (change to extends) +[N] Keep as prerequisite +[?] Explain difference between prerequisite and extends + +Choice: █ +``` + +**Circular dependency risk:** + +``` +⚠️ Circular Dependency Warning + +Adding [[note_a]] as prerequisite would create cycle: + mcp_security → oauth_fundamentals → mcp_implementation → mcp_security + +**Options:** +1. Don't add this relationship +2. Add as "related" instead of "prerequisite" +3. Review and break the existing cycle + +Recommended: Option 2 (related instead) + +Choice: █ +``` + +## 10. Tools Used + +- **Read** - Get full note content, parse "Related Concepts" sections +- **Edit** - Update "Related Concepts" sections in target and related notes +- **Grep** - Search for concepts across notes, find tag overlaps, find wikilinks +- **Glob** - Verify notes exist, find candidates by file patterns +- **mcp__perplexity-ask** - Research relationships using LLM reasoning +- **Parse logic** - Extract concepts, classify relationships, score confidence + +## 11. Important Notes + +**Quality principles:** + +- Evidence over guessing +- Confidence scoring for transparency +- User control over changes +- Bidirectional integrity always +- Clear reasoning for every suggestion + +**Performance considerations:** + +- Grep can search 93 notes quickly +- Perplexity queries in parallel where possible +- Cache concept extractions +- Filter aggressively before showing to user + +**User experience:** + +- Make suggestions actionable +- Provide escape hatches +- Allow customization +- Show clear before/after +- Celebrate improvements + +Execute graph expansion for the note provided by the user. diff --git a/commands/graph-add-relationship.md b/commands/graph-add-relationship.md new file mode 100644 index 0000000..fe7a0f5 --- /dev/null +++ b/commands/graph-add-relationship.md @@ -0,0 +1,189 @@ +--- +description: Add a typed bidirectional relationship between two notes +--- + +# Graph Add Relationship + +Manually add a typed relationship between two notes with bidirectional update. + +## 0. Locate AZKG Repository + +**Check for AZKG_REPO_PATH environment variable:** + +- Use bash conditional: `if [ -z "$AZKG_REPO_PATH" ]; then REPO_PATH=$(pwd); else REPO_PATH="$AZKG_REPO_PATH"; fi` +- **If AZKG_REPO_PATH is set:** Use that path as the repository root +- **If AZKG_REPO_PATH is not set:** Use current working directory (pwd) +- Store result as REPO_PATH for all subsequent file operations + +**All file operations must use REPO_PATH:** + +- Read: `Read(REPO_PATH/filename.md)` or `Read("$REPO_PATH/filename.md")` +- Write: `Write(REPO_PATH/filename.md)` or `Write("$REPO_PATH/filename.md")` +- Edit: `Edit(REPO_PATH/filename.md)` or `Edit("$REPO_PATH/filename.md")` +- Grep: `Grep(pattern, path=REPO_PATH)` or with explicit path +- Glob: `Glob(pattern, path=REPO_PATH)` or with explicit path + +**Example usage:** + +``` +# Check environment variable +if [ -z "$AZKG_REPO_PATH" ]; then + REPO_PATH=$(pwd) +else + REPO_PATH="$AZKG_REPO_PATH" +fi + +# Then use REPO_PATH for all operations +Read("$REPO_PATH/agents.md") +``` + +**Concrete examples:** + +- If AZKG_REPO_PATH="/c/Users/dothompson/OneDrive/src/witt3rd/donald-azkg" + → Read("/c/Users/dothompson/OneDrive/src/witt3rd/donald-azkg/agents.md") +- If AZKG_REPO_PATH is not set and pwd is /c/Users/dothompson/OneDrive/src/witt3rd/donald-azkg + → Read("agents.md") or use full path from pwd + +## Input + +User provides: + +- Source note: `agents.md` +- Target note: `semantic_routing.md` +- Relationship type: `related_topics` (or `prerequisites`, `extends`, `alternatives`, `examples`) +- Why: "Semantic routing enables intelligent model selection for agent tasks" + +Example: `/graph-add-relationship agents semantic_routing related_topics "Enables model selection"` + +## Valid Relationship Types + +- `prerequisites` - Target must be understood first +- `related_topics` - Connected ideas at same level +- `extends` - Source builds upon target +- `alternatives` - Different approaches to same problem +- `examples` - Target is concrete implementation of source + +## Execution Steps + +### 1. Normalize Filenames + +Ensure both filenames have `.md` extension. + +### 2. Verify Both Notes Exist + +Use Glob to verify both files exist: + +```bash +Glob "agents.md" +Glob "semantic_routing.md" +``` + +### 3. Read Source Note + +Use Read tool to get source note content, including current "Related Concepts" section. + +### 4. Update Source Note + +Use Edit tool to add relationship to appropriate section in source note: + +```markdown +## Related Concepts + +### Related Topics +- [[existing_note]] - Existing relationship +- [[semantic_routing]] - Enables intelligent model selection for agent tasks +``` + +### 5. Read Target Note + +Use Read tool to get target note content, including current "Related Concepts" section. + +### 6. Add Inverse Relationship + +Determine inverse relationship type: + +- `prerequisites` in A → add A to `related_topics` or `extended_by` in B (depending on context) +- `related_topics` in A → add A to `related_topics` in B +- `extends` in A → add A to `extended_by` in B +- `alternatives` in A → add A to `alternatives` in B +- `examples` in A → add A to `extended_by` or `related_topics` in B + +Use Edit tool to add inverse relationship to target note. + +### 7. Report Success + +Show what was added to both files. + +## Output Format + +``` +Added Relationship +============================================================ + +✓ Forward relationship: + agents.md → semantic_routing.md + Type: related_topics + Why: Enables intelligent model selection for agent tasks + +✓ Inverse relationship: + semantic_routing.md → agents.md + Type: related_topics + Why: Agents use semantic routing for task delegation + +============================================================ +✅ Relationship Added! +============================================================ + +Updated files: +• agents.md - Added to "Related Topics" section +• semantic_routing.md - Added to "Related Topics" section + +💡 Next steps: +• Review both notes to verify relationships make sense +• Use `/graph-note agents.md` to see all relationships +• Use `/graph-validate` to check bidirectionality +``` + +## Validation + +Before adding: + +- Both notes must exist +- Relationship type must be valid +- "Why" explanation should be provided (required for quality) + +After adding: + +- Both notes should have matching inverse relationships +- No duplicate relationships in either file + +## Inverse Relationship Rules + +| Forward Type | Inverse Type | Notes | +|--------------|--------------|-------| +| prerequisites | related_topics or extended_by | Context dependent | +| related_topics | related_topics | Symmetric | +| extends | extended_by | Clear inverse | +| alternatives | alternatives | Symmetric | +| examples | extended_by | Examples extend the concept | + +## Use Cases + +- **Fill gaps**: Add relationships discovered through usage +- **Manual correction**: Fix missing inverse relationships +- **Connect new notes**: Link newly created note to existing ones +- **Cross-domain links**: Connect concepts from different areas + +## Tools Used + +- **Glob** - Verify notes exist +- **Read** - Get current note content +- **Edit** - Update "Related Concepts" sections in both notes +- **Logic** - Determine inverse relationship type + +## Important Notes + +- Always provide meaningful "why" explanation +- Use consistent relationship types (follow conventions) +- Check both notes after adding to verify correctness +- Run `/graph-validate` if unsure about bidirectionality diff --git a/commands/graph-moc.md b/commands/graph-moc.md new file mode 100644 index 0000000..c1ce490 --- /dev/null +++ b/commands/graph-moc.md @@ -0,0 +1,203 @@ +--- +description: Display information about a Map of Content (MOC) file +--- + +# Graph MOC (Map of Content) + +Display information about a specific MOC (Map of Content) file, which serves as a thematic navigation hub. + +## 0. Locate AZKG Repository + +**Check for AZKG_REPO_PATH environment variable:** + +- Use bash conditional: `if [ -z "$AZKG_REPO_PATH" ]; then REPO_PATH=$(pwd); else REPO_PATH="$AZKG_REPO_PATH"; fi` +- **If AZKG_REPO_PATH is set:** Use that path as the repository root +- **If AZKG_REPO_PATH is not set:** Use current working directory (pwd) +- Store result as REPO_PATH for all subsequent file operations + +**All file operations must use REPO_PATH:** + +- Read: `Read(REPO_PATH/filename.md)` or `Read("$REPO_PATH/filename.md")` +- Write: `Write(REPO_PATH/filename.md)` or `Write("$REPO_PATH/filename.md")` +- Edit: `Edit(REPO_PATH/filename.md)` or `Edit("$REPO_PATH/filename.md")` +- Grep: `Grep(pattern, path=REPO_PATH)` or with explicit path +- Glob: `Glob(pattern, path=REPO_PATH)` or with explicit path + +**Example usage:** + +``` +# Check environment variable +if [ -z "$AZKG_REPO_PATH" ]; then + REPO_PATH=$(pwd) +else + REPO_PATH="$AZKG_REPO_PATH" +fi + +# Then use REPO_PATH for all operations +Read("$REPO_PATH/agents.md") +``` + +**Concrete examples:** + +- If AZKG_REPO_PATH="/c/Users/dothompson/OneDrive/src/witt3rd/donald-azkg" + → Read("/c/Users/dothompson/OneDrive/src/witt3rd/donald-azkg/agents.md") +- If AZKG_REPO_PATH is not set and pwd is /c/Users/dothompson/OneDrive/src/witt3rd/donald-azkg + → Read("agents.md") or use full path from pwd + +## Task + +Show: + +- MOC name and theme +- Total notes linked in this MOC +- List of all notes with their brief descriptions +- Section organization within the MOC + +## Input + +User provides the MOC name (e.g., "agents", "mcp", "python", "rust") + +Common MOCs: + +- agents_moc.md - AI agents and agentic systems +- mcp_moc.md - Model Context Protocol +- python_moc.md - Python development +- rust_moc.md - Rust programming +- typescript_moc.md - TypeScript and React +- windows_moc.md - Windows development +- writing_moc.md - Writing and communication +- csharp_moc.md - C# development + +## Execution Steps + +### 1. Normalize MOC Name + +Ensure filename has `_moc.md` suffix: + +- Input: "agents" → "agents_moc.md" +- Input: "agents_moc" → "agents_moc.md" +- Input: "agents_moc.md" → "agents_moc.md" + +### 2. Verify MOC Exists + +Use Glob to check if MOC file exists: + +```bash +Glob "agents_moc.md" +``` + +If not found, list available MOCs and suggest closest match. + +### 3. Read MOC Content + +Use Read tool to get full MOC content. + +### 4. Parse MOC Structure + +Extract: + +- **Title** (H1 heading) +- **Sections** (H2 headings) +- **Wikilinks** in each section +- **Brief descriptions** next to each wikilink + +Example MOC structure: + +```markdown +# Agents - Map of Content + +## Core Concepts +- [[agents]] - AI agents powered by LLMs +- [[semantic_routing]] - Intelligent model selection + +## Coding Assistants +- [[claude_code]] - Agentic AI coding assistant +- [[claude_code_agents]] - Subagent system +``` + +### 5. Count Notes + +Count total wikilinks across all sections. + +## Output Format + +``` +MOC: agents_moc.md +============================================================ + +Theme: AI agents and agentic systems +Total notes: 15 + +## Sections and Notes: + +### Core Concepts (5 notes) +- [[agents]] - AI agents powered by LLMs for autonomous action +- [[semantic_routing]] - Intelligent model selection based on query +- [[react_agent_pattern]] - Design pattern for agent UIs +- [[llm_self_talk_optimization]] - Token-efficient agent communication +- [[agentic_development_context]] - Comprehensive development ecosystems + +### Coding Assistants (5 notes) +- [[claude_code]] - Anthropic's agentic AI coding assistant +- [[claude_code_agents]] - Subagent system for parallel tasks +- [[claude_code_plugins]] - Extensibility via slash commands +- [[claude_code_hooks]] - Lifecycle event system +- [[zettelkasten_claude_plugin]] - Knowledge graph plugin + +### Integration & APIs (2 notes) +- [[agent_mcp_apis]] - MCP APIs for agent tool integration +- [[adding_mcp_to_claude_code]] - Adding custom agents + +### Related Topics (3 notes) +- [[mcp_overview]] - Protocol for agent tool integration +- [[react_framework]] - UI framework for agents + +============================================================ + +💡 Next steps: +• Use `/graph-note [filename]` to explore any note in this MOC +• Use `/create-note` to add new notes to this domain +• Use `/search-notes #agents` to find all agent-tagged notes +``` + +## Use Cases + +- **Explore a domain**: See all notes in a specific theme +- **Find related notes**: Discover notes you didn't know existed +- **Assess coverage**: Check if a topic area is well-covered +- **Navigate efficiently**: Jump to specific concepts in a domain +- **Plan additions**: Identify gaps where new notes are needed + +## Tools Used + +- **Glob** - Verify MOC file exists, list all MOCs +- **Read** - Get full MOC content +- **Parse logic** - Extract sections, wikilinks, descriptions + +## Present Results + +After displaying MOC information: + +- Assess coverage (comprehensive vs sparse) +- Comment on organization (clear sections vs needs structure) +- Suggest if MOC is getting too large (might need splitting) +- Identify potential notes to add based on theme +- Note any wikilinks that point to non-existent notes + +## If MOC Not Found + +``` +MOC not found: unknown_moc.md + +Available MOCs: +- agents_moc.md - AI agents and agentic systems +- mcp_moc.md - Model Context Protocol +- python_moc.md - Python development +- rust_moc.md - Rust programming +- typescript_moc.md - TypeScript and React +- windows_moc.md - Windows development +- writing_moc.md - Writing and communication +- csharp_moc.md - C# development + +Did you mean one of these? +``` diff --git a/commands/graph-note.md b/commands/graph-note.md new file mode 100644 index 0000000..5921192 --- /dev/null +++ b/commands/graph-note.md @@ -0,0 +1,185 @@ +--- +description: Display detailed information about a specific note +--- + +# Graph Note + +Show detailed information about a specific note, including all relationships and backlinks. + +## 0. Locate AZKG Repository + +**Check for AZKG_REPO_PATH environment variable:** + +- Use bash conditional: `if [ -z "$AZKG_REPO_PATH" ]; then REPO_PATH=$(pwd); else REPO_PATH="$AZKG_REPO_PATH"; fi` +- **If AZKG_REPO_PATH is set:** Use that path as the repository root +- **If AZKG_REPO_PATH is not set:** Use current working directory (pwd) +- Store result as REPO_PATH for all subsequent file operations + +**All file operations must use REPO_PATH:** + +- Read: `Read(REPO_PATH/filename.md)` or `Read("$REPO_PATH/filename.md")` +- Write: `Write(REPO_PATH/filename.md)` or `Write("$REPO_PATH/filename.md")` +- Edit: `Edit(REPO_PATH/filename.md)` or `Edit("$REPO_PATH/filename.md")` +- Grep: `Grep(pattern, path=REPO_PATH)` or with explicit path +- Glob: `Glob(pattern, path=REPO_PATH)` or with explicit path + +**Example usage:** + +``` +# Check environment variable +if [ -z "$AZKG_REPO_PATH" ]; then + REPO_PATH=$(pwd) +else + REPO_PATH="$AZKG_REPO_PATH" +fi + +# Then use REPO_PATH for all operations +Read("$REPO_PATH/agents.md") +``` + +**Concrete examples:** + +- If AZKG_REPO_PATH="/c/Users/dothompson/OneDrive/src/witt3rd/donald-azkg" + → Read("/c/Users/dothompson/OneDrive/src/witt3rd/donald-azkg/agents.md") +- If AZKG_REPO_PATH is not set and pwd is /c/Users/dothompson/OneDrive/src/witt3rd/donald-azkg + → Read("agents.md") or use full path from pwd + +## Task + +Display: + +- Note title, tags, and summary (from YAML frontmatter and heading) +- All relationships from "Related Concepts" section +- Backlinks (other notes that reference this note) + +## Input + +User provides filename: `/graph-note agents.md` or `/graph-note agents` + +## Execution Steps + +### 1. Normalize Filename + +Ensure filename has `.md` extension. + +### 2. Verify Note Exists + +Use Glob to check if note exists: + +```bash +Glob "agents.md" +``` + +If not found, report error. + +### 3. Read Note Content + +Use Read tool to get full note content. + +### 4. Extract Metadata + +From the note content: + +- **Title**: First `# Heading` after YAML frontmatter +- **Tags**: From `tags:` field in YAML frontmatter +- **Summary**: First paragraph after title (before `##` sections) + +### 5. Parse "Related Concepts" Section + +From note content, extract all relationships: + +- Prerequisites +- Related Topics +- Extends +- Extended By +- Alternatives +- Examples + +For each relationship, capture the target note and "why" explanation. + +### 6. Find Backlinks + +Use Grep to find all notes that reference this note: + +```bash +# Find all wikilinks to this note +Grep "\[\[agents\]\]" --glob="*.md" --output_mode="files_with_matches" +``` + +Count and list the files that link to this note. + +## Output Format + +``` +Note: agents.md +============================================================ + +## Metadata +Title: AI Agents +Tags: #agents, #ai, #llm, #architecture +Summary: AI agents are autonomous systems powered by LLMs that can perceive, +decide, and act to achieve goals. + +## Relationships (Total: 8) + +### Prerequisites (0) +(None) + +### Related Topics (3) +- [[semantic_routing]] - Enables intelligent model selection for agent tasks +- [[llm_self_talk_optimization]] - Token-efficient communication between agents +- [[react_agent_pattern]] - UI pattern for building agent interfaces + +### Extends (0) +(None) + +### Extended By (2) +- [[claude_code]] - Implements agentic coding assistant +- [[alita]] - Example implementation of AI agent system + +### Alternatives (0) +(None) + +### Examples (3) +- [[alita]] - Production AI agent implementation +- [[claude_code]] - Agentic coding assistant +- [[another_example]] - Another implementation + +## Backlinks (12 notes reference this) + +Files that link to [[agents]]: +- semantic_routing.md +- react_agent_pattern.md +- mcp_overview.md +- claude_code.md +- agents_moc.md +- ... + +============================================================ +💡 Next Steps: +• Use `/expand-graph agents.md` to discover more relationships +• Review backlinks to understand how this note is used +• Check if "Extended By" relationships should be in "Examples" instead +``` + +## Use Cases + +- **Understand connections**: See how a note fits into the knowledge graph +- **Find usage**: See where a concept is referenced (backlinks) +- **Verify relationships**: Check if relationships are accurate and complete +- **Discover gaps**: Find missing prerequisite or extension relationships + +## Tools Used + +- **Glob** - Verify note exists +- **Read** - Get full note content +- **Grep** - Find backlinks (wikilinks to this note) +- **Parse logic** - Extract YAML, title, summary, relationships + +## Present Results + +- Show clear breakdown of relationship types +- Highlight if note has no prerequisites (might be foundational) +- Highlight if note has many Extended By (indicates it's a base concept) +- Show backlink count to indicate note importance/usage +- Suggest using `/expand-graph` if relationship count seems low diff --git a/commands/graph-stats.md b/commands/graph-stats.md new file mode 100644 index 0000000..d4fb12b --- /dev/null +++ b/commands/graph-stats.md @@ -0,0 +1,198 @@ +--- +description: Display comprehensive statistics about the knowledge graph +--- + +# Graph Stats + +Display comprehensive statistics about the knowledge graph. + +## 0. Locate AZKG Repository + +**Check for AZKG_REPO_PATH environment variable:** + +- Use bash conditional: `if [ -z "$AZKG_REPO_PATH" ]; then REPO_PATH=$(pwd); else REPO_PATH="$AZKG_REPO_PATH"; fi` +- **If AZKG_REPO_PATH is set:** Use that path as the repository root +- **If AZKG_REPO_PATH is not set:** Use current working directory (pwd) +- Store result as REPO_PATH for all subsequent file operations + +**All file operations must use REPO_PATH:** + +- Read: `Read(REPO_PATH/filename.md)` or `Read("$REPO_PATH/filename.md")` +- Write: `Write(REPO_PATH/filename.md)` or `Write("$REPO_PATH/filename.md")` +- Edit: `Edit(REPO_PATH/filename.md)` or `Edit("$REPO_PATH/filename.md")` +- Grep: `Grep(pattern, path=REPO_PATH)` or with explicit path +- Glob: `Glob(pattern, path=REPO_PATH)` or with explicit path + +**Example usage:** + +``` +# Check environment variable +if [ -z "$AZKG_REPO_PATH" ]; then + REPO_PATH=$(pwd) +else + REPO_PATH="$AZKG_REPO_PATH" +fi + +# Then use REPO_PATH for all operations +Read("$REPO_PATH/agents.md") +``` + +**Concrete examples:** + +- If AZKG_REPO_PATH="/c/Users/dothompson/OneDrive/src/witt3rd/donald-azkg" + → Read("/c/Users/dothompson/OneDrive/src/witt3rd/donald-azkg/agents.md") +- If AZKG_REPO_PATH is not set and pwd is /c/Users/dothompson/OneDrive/src/witt3rd/donald-azkg + → Read("agents.md") or use full path from pwd + +## Task + +Use Grep and Glob to calculate: + +- Total notes count +- Total MOC files count +- Relationship counts by type +- Unique tag count and top 10 tags +- Notes per MOC + +## Execution Steps + +### 1. Count Total Notes + +Use Glob to count all markdown files (excluding MOCs): + +```bash +# Count all .md files +Glob "*.md" +``` + +Filter out MOC files (files ending in `_moc.md`) for pure note count. + +### 2. Count MOC Files + +Use Glob to find MOC files: + +```bash +# Find all MOC files +Glob "*_moc.md" +``` + +### 3. Count Relationships by Type + +Use Grep to find each relationship type in "Related Concepts" sections: + +```bash +# Count Prerequisites +Grep "### Prerequisites" --glob="*.md" --output_mode="count" + +# Count Related Topics +Grep "### Related Topics" --glob="*.md" --output_mode="count" + +# Count Extends +Grep "### Extends" --glob="*.md" --output_mode="count" + +# Count Extended By +Grep "### Extended By" --glob="*.md" --output_mode="count" + +# Count Alternatives +Grep "### Alternatives" --glob="*.md" --output_mode="count" + +# Count Examples +Grep "### Examples" --glob="*.md" --output_mode="count" +``` + +For each type, also count individual relationship entries by counting lines starting with `- [[` within those sections. + +### 4. Extract and Count Tags + +Use Grep to find all tags in YAML frontmatter: + +```bash +# Find all tags lines +Grep "^tags: \[" --glob="*.md" --output_mode="content" +``` + +Parse out individual tags, count occurrences, and sort by frequency. + +### 5. Calculate Additional Metrics + +- Average tags per note +- Average relationships per note +- Notes without "Related Concepts" section (orphaned) +- Most connected notes (top 5 by relationship count) + +## Output Format + +``` +Graph Statistics +============================================================ +Total notes: N +Total MOCs: M +Pure notes (excluding MOCs): X + +Relationship counts: + Prerequisites: X notes have prerequisites (Y total relationships) + Related Topics: X notes have related topics (Y total relationships) + Extends: X notes extend others (Y total relationships) + Extended By: X notes are extended by others (Y total relationships) + Alternatives: X notes have alternatives (Y total relationships) + Examples: X notes have examples (Y total relationships) + +Total relationships: Z + +Tag Statistics: + Unique tags: N + Average tags per note: X.Y + +Top 10 tags: + #python: 25 notes + #mcp: 18 notes + #agents: 15 notes + #rust: 12 notes + #typescript: 10 notes + ... + +Graph Health: + ✓ Well-connected notes: X (>3 relationships) + ! Sparsely connected: Y (1-2 relationships) + ⚠ Orphaned notes: Z (0 relationships) +``` + +## Analysis and Insights + +After displaying stats, provide brief analysis: + +**Good signs:** + +- Balanced relationship distribution (no single type dominates) +- High average tags per note (3-6 ideal) +- Few orphaned notes (<5%) +- Diverse tag usage (no extreme tag concentration) + +**Potential issues:** + +- Many orphaned notes → Use `/expand-graph` to discover relationships +- Imbalanced relationships → Consider adding missing relationship types +- Tag concentration → Some notes may need more specific tags +- Low relationship count → Graph may not be well-connected + +## Use Cases + +- **Growth tracking**: Monitor note and relationship count over time +- **Health check**: Identify orphaned or poorly connected notes +- **Tag consistency**: Find most-used tags for standardization +- **Balance analysis**: Ensure relationship types are balanced +- **Discover trends**: See which domains are growing fastest + +## Tools Used + +- **Glob** - Count files (notes, MOCs) +- **Grep** - Find relationship sections, count relationships, extract tags +- **Parse logic** - Extract tags from YAML, calculate statistics, sort and rank + +## Present Results + +After displaying stats: + +- Highlight any concerning metrics (too many orphaned notes, imbalanced relationships) +- Suggest actions (use `/expand-graph` on orphaned notes, add missing relationship types) +- Celebrate growth (if note count is increasing, congratulate user on knowledge expansion) diff --git a/commands/graph-validate.md b/commands/graph-validate.md new file mode 100644 index 0000000..4fd12a6 --- /dev/null +++ b/commands/graph-validate.md @@ -0,0 +1,225 @@ +--- +description: Run validation checks on the knowledge graph +--- + +# Validate Graph + +Run validation checks on the knowledge graph to ensure integrity. + +## 0. Locate AZKG Repository + +**Check for AZKG_REPO_PATH environment variable:** + +- Use bash conditional: `if [ -z "$AZKG_REPO_PATH" ]; then REPO_PATH=$(pwd); else REPO_PATH="$AZKG_REPO_PATH"; fi` +- **If AZKG_REPO_PATH is set:** Use that path as the repository root +- **If AZKG_REPO_PATH is not set:** Use current working directory (pwd) +- Store result as REPO_PATH for all subsequent file operations + +**All file operations must use REPO_PATH:** + +- Read: `Read(REPO_PATH/filename.md)` or `Read("$REPO_PATH/filename.md")` +- Write: `Write(REPO_PATH/filename.md)` or `Write("$REPO_PATH/filename.md")` +- Edit: `Edit(REPO_PATH/filename.md)` or `Edit("$REPO_PATH/filename.md")` +- Grep: `Grep(pattern, path=REPO_PATH)` or with explicit path +- Glob: `Glob(pattern, path=REPO_PATH)` or with explicit path + +**Example usage:** + +``` +# Check environment variable +if [ -z "$AZKG_REPO_PATH" ]; then + REPO_PATH=$(pwd) +else + REPO_PATH="$AZKG_REPO_PATH" +fi + +# Then use REPO_PATH for all operations +Read("$REPO_PATH/agents.md") +``` + +**Concrete examples:** + +- If AZKG_REPO_PATH="/c/Users/dothompson/OneDrive/src/witt3rd/donald-azkg" + → Read("/c/Users/dothompson/OneDrive/src/witt3rd/donald-azkg/agents.md") +- If AZKG_REPO_PATH is not set and pwd is /c/Users/dothompson/OneDrive/src/witt3rd/donald-azkg + → Read("agents.md") or use full path from pwd + +## Task + +Check markdown files for: + +- All wikilinks point to existing notes (no broken links) +- "Related Concepts" sections are well-formed +- Bidirectional relationships are consistent +- YAML frontmatter is valid + +## Execution Steps + +### 1. Find All Wikilinks + +Use Grep to extract all wikilinks from all markdown files: + +```bash +# Find all wikilinks in the format [[note_name]] +Grep "\[\[([^\]]+)\]\]" --glob="*.md" --output_mode="content" -n +``` + +Extract unique note names from results. + +### 2. Verify All Wikilinks Point to Existing Files + +For each unique wikilink target found: + +- Use Glob to check if `target.md` exists in repository root +- Record any broken links (wikilink but no corresponding file) + +### 3. Check Bidirectional Consistency + +For notes with "Related Concepts" sections: + +- Read notes with "Extends" relationships +- Verify target notes have "Extended By" back-reference +- Read notes with "Prerequisites" relationships +- Verify reasonable consistency (prerequisites should be foundational) + +### 4. Validate YAML Frontmatter + +Use Read tool to check a sample of notes: + +- YAML frontmatter starts with `---` and ends with `---` +- `tags:` field is present and is an array +- Tags use lowercase-with-hyphens format + +### 5. Check for Common Issues + +- Notes without any "Related Concepts" section (orphaned notes) +- Notes with empty tags array +- Duplicate note filenames (shouldn't happen but check) +- MOC files that reference non-existent notes + +## Output Format + +**Success:** + +``` +Graph Validation +============================================================ +[OK] Knowledge graph is valid + +All checks passed: + ✓ All wikilinks point to existing notes (N wikilinks checked) + ✓ No broken links found + ✓ Bidirectional relationships are consistent + ✓ YAML frontmatter is well-formed + ✓ No orphaned notes detected + +Statistics: + • Total notes: N + • Total wikilinks: M + • Total relationships: X + • MOC files: Y +``` + +**Failure:** + +``` +Graph Validation +============================================================ +[ERROR] Found N issue(s): + +1. Broken wikilink: file1.md:42 references [[non_existent_note]] +2. Broken wikilink: file2.md:18 references [[another_missing]] +3. Missing inverse: agents.md extends [[semantic_routing]] but inverse not found +4. Orphaned note: lonely_note.md has no "Related Concepts" section +5. Invalid YAML: broken_note.md frontmatter is malformed + +Recommendations: + • Fix or remove broken wikilinks + • Add "Extended By" section to semantic_routing.md + • Consider adding relationships to lonely_note.md + • Fix YAML frontmatter in broken_note.md +``` + +## Validation Rules + +**Wikilink validation:** + +- Every `[[note_name]]` must have corresponding `note_name.md` file +- Case-sensitive matching +- Should NOT include `.md` in wikilink (use `[[note]]` not `[[note.md]]`) + +**Bidirectional validation:** + +- If A extends B, then B should have "Extended By" section mentioning A +- If A is prerequisite for B, then B should mention A in "Prerequisites" +- Not always perfectly symmetric, but should be logically consistent + +**YAML validation:** + +- Well-formed YAML with proper delimiters +- Tags field exists and is array +- Tags follow naming convention (lowercase-with-hyphens) + +**Structural validation:** + +- Notes should have "Related Concepts" section (unless intentionally standalone) +- MOC files should only reference existing notes +- No circular dependencies in prerequisite chains (optional advanced check) + +## If Validation Fails + +For each error type, suggest fixes: + +**Broken wikilinks:** + +``` +File: example.md:42 +Issue: References [[missing_note]] +Fixes: + • Create the missing note + • Remove the wikilink + • Change to reference an existing note +``` + +**Missing inverse relationships:** + +``` +File: agents.md +Issue: Extends [[semantic_routing]] but inverse not found +Fix: + • Add to semantic_routing.md "Related Concepts" section: + ### Extended By + - [[agents]] - Uses routing for agent task selection +``` + +**Orphaned notes:** + +``` +File: lonely_note.md +Issue: No "Related Concepts" section +Fix: + • Add "Related Concepts" section with at least one relationship + • Link to appropriate MOC + • Use /expand-graph to discover relationships +``` + +## Tools Used + +- **Grep** - Find all wikilinks across all markdown files +- **Glob** - Check if wikilink targets exist as files +- **Read** - Read notes to check "Related Concepts" sections and YAML frontmatter +- **Parse logic** - Extract wikilinks, validate YAML, check consistency + +## Success Criteria + +- All wikilinks resolve to existing files +- No malformed YAML frontmatter +- Bidirectional relationships are logically consistent +- Minimal orphaned notes + +## When to Run + +- After creating new notes (check new relationships valid) +- After renaming notes (check wikilinks updated correctly) +- After bulk operations (check graph still consistent) +- Periodically (ensure graph health over time) diff --git a/commands/learning-path.md b/commands/learning-path.md new file mode 100644 index 0000000..aed8528 --- /dev/null +++ b/commands/learning-path.md @@ -0,0 +1,446 @@ +--- +description: Generate an optimal learning sequence for a target note +--- + +# Learning Path + +Generate an optimal learning sequence for a target note by tracing prerequisite chains through the knowledge graph. + +## 0. Locate AZKG Repository + +**Check for AZKG_REPO_PATH environment variable:** + +- Use bash conditional: `if [ -z "$AZKG_REPO_PATH" ]; then REPO_PATH=$(pwd); else REPO_PATH="$AZKG_REPO_PATH"; fi` +- **If AZKG_REPO_PATH is set:** Use that path as the repository root +- **If AZKG_REPO_PATH is not set:** Use current working directory (pwd) +- Store result as REPO_PATH for all subsequent file operations + +**All file operations must use REPO_PATH:** + +- Read: `Read(REPO_PATH/filename.md)` or `Read("$REPO_PATH/filename.md")` +- Write: `Write(REPO_PATH/filename.md)` or `Write("$REPO_PATH/filename.md")` +- Edit: `Edit(REPO_PATH/filename.md)` or `Edit("$REPO_PATH/filename.md")` +- Grep: `Grep(pattern, path=REPO_PATH)` or with explicit path +- Glob: `Glob(pattern, path=REPO_PATH)` or with explicit path + +**Example usage:** + +``` +# Check environment variable +if [ -z "$AZKG_REPO_PATH" ]; then + REPO_PATH=$(pwd) +else + REPO_PATH="$AZKG_REPO_PATH" +fi + +# Then use REPO_PATH for all operations +Read("$REPO_PATH/agents.md") +``` + +**Concrete examples:** + +- If AZKG_REPO_PATH="/c/Users/dothompson/OneDrive/src/witt3rd/donald-azkg" + → Read("/c/Users/dothompson/OneDrive/src/witt3rd/donald-azkg/agents.md") +- If AZKG_REPO_PATH is not set and pwd is /c/Users/dothompson/OneDrive/src/witt3rd/donald-azkg + → Read("agents.md") or use full path from pwd + +## 1. Parse Input + +**Input format:** User provides: + +- A note name: `/learning-path mcp_security.md` +- Or just the topic: `/learning-path mcp_security` + +**Normalize input:** + +- Add `.md` extension if missing +- Use Glob to verify the target note exists +- If not found, suggest similar notes using Glob + +## 2. Load Target Note + +**Read the target note:** + +- Use Read tool to get full content +- Extract YAML tags and title +- Parse "Related Concepts" section to get prerequisites + +**Example:** + +```markdown +## Related Concepts + +### Prerequisites +- [[mcp_overview]] - Must understand MCP basics first +- [[oauth_fundamentals]] - OAuth is primary auth mechanism + +### Related Topics +- [[api_security]] - General API security principles +``` + +## 3. Trace Prerequisite Chains + +**Algorithm: Depth-First Traversal** + +Starting from the target note, recursively follow prerequisite relationships: + +``` +function buildPrerequisiteTree(note, visited = new Set()): + if note in visited: + return [] // Cycle detection + + visited.add(note) + + // Read the note and parse "Related Concepts" → "Prerequisites" + prerequisites = readNote(note).prerequisites + + if prerequisites is empty: + return [note] // Foundation reached + + tree = [] + for prereq in prerequisites: + subtree = buildPrerequisiteTree(prereq.note, visited) + tree.extend(subtree) + + tree.append(note) + return tree +``` + +**Implementation with tools:** + +1. **Read** target note to get prerequisites +2. For each prerequisite, **Read** that note to get its prerequisites +3. Recursively traverse until reaching foundation notes (no prerequisites) +4. Track visited nodes to detect cycles + +**Key features:** + +- **Cycle detection:** Track visited nodes to prevent infinite loops +- **Multiple paths:** Handle notes with multiple prerequisites +- **Foundation detection:** Identify notes with no prerequisites +- **Depth tracking:** Calculate how many levels deep each note is + +## 4. Build Learning Sequence + +**Create ordered learning path:** + +1. **Topological sort:** Order notes so prerequisites always come before dependents +2. **Remove duplicates:** Each note appears once, at earliest possible position +3. **Group by depth level:** Show conceptual layers + +**Example structure:** + +``` +Level 0 (Foundations): +- note_a.md +- note_b.md + +Level 1 (Builds on foundations): +- note_c.md (requires: note_a) +- note_d.md (requires: note_b) + +Level 2 (Intermediate): +- note_e.md (requires: note_c, note_d) + +Level 3 (Target): +- target_note.md (requires: note_e) +``` + +## 5. Read Note Summaries + +**For each note in the learning path:** + +- Use Read tool to get first 3-5 lines (the summary) +- Extract the brief description after the title +- This provides context for each step + +**Example:** + +``` +## mcp_overview.md +"Introduction to Model Context Protocol, a standardized way for AI assistants to connect to data sources and tools." +``` + +## 6. Analyze Learning Path + +**Calculate metrics:** + +**Path statistics:** + +- Total notes in sequence: `N` +- Depth levels: `M` (foundation to target) +- Estimated reading time: `N × 10 minutes = X minutes` +- Foundational notes: Count of level 0 notes +- Branching factor: Average prerequisites per note + +**Complexity assessment:** + +- **Simple path (1-3 notes):** "Quick learning path" +- **Moderate path (4-7 notes):** "Intermediate learning sequence" +- **Complex path (8+ notes):** "Comprehensive learning journey" + +**Identify critical concepts:** + +- Notes that multiple paths converge through +- "Bottleneck" concepts that are prerequisites for many others + +## 7. Suggest Related Learning + +**Enrich the path with optional content:** + +**Parallel reading (Related Topics):** + +- Read "Related Topics" sections from notes in path +- Notes at same level that provide additional context +- Not strictly required but enhance understanding + +**Deeper dives (Extended By):** + +- Read "Extended By" sections from notes in path +- Advanced topics that build on concepts in the path +- "After mastering this path, explore..." + +**Alternative approaches (Alternatives):** + +- Read "Alternatives" sections from notes in path +- Different ways to achieve similar understanding +- "For a different perspective, consider..." + +**Practical examples (Examples):** + +- Read "Examples" sections from notes in path +- Concrete implementations to solidify understanding +- "Apply these concepts with..." + +## 8. Generate Output + +**Format the learning path:** + +```markdown +# Learning Path: [Target Note Title] + +🎯 **Goal:** Understand [target topic] +📚 **Total Notes:** N notes across M levels +⏱️ **Estimated Time:** X minutes +🏗️ **Complexity:** [Simple|Moderate|Complex] + +--- + +## Prerequisites Sequence + +### Level 0: Foundations +Start here if you're new to this topic. + +1. **[[note_a]]** (5 min read) + Brief description from note. + *Why it's needed:* Foundation for understanding [concept] + +2. **[[note_b]]** (8 min read) + Brief description from note. + *Why it's needed:* Introduces core [concept] + +### Level 1: Core Concepts +Once you understand the foundations, proceed here. + +3. **[[note_c]]** (10 min read) + Brief description from note. + *Builds on:* note_a + *Why it's needed:* Extends [concept] with [new idea] + +4. **[[note_d]]** (7 min read) + Brief description from note. + *Builds on:* note_b + *Why it's needed:* Applies [concept] to [domain] + +### Level 2: Integration +Combining concepts from previous levels. + +5. **[[note_e]]** (12 min read) + Brief description from note. + *Builds on:* note_c, note_d + *Why it's needed:* Synthesizes [concepts] for [purpose] + +### Level 3: Target Concept +Your destination! + +6. **[[target_note]]** (15 min read) + Brief description from note. + *Builds on:* note_e + *This is your goal:* Complete understanding of [target topic] + +--- + +## Optional Enrichment + +### Parallel Reading (Same Level) +Enhance understanding at each level: +- **[[related_a]]** - Provides additional context on [concept] +- **[[related_b]]** - Alternative perspective on [concept] + +### Go Deeper (Beyond Target) +After mastering this path: +- **[[advanced_a]]** - Builds on target with [advanced concept] +- **[[advanced_b]]** - Applies target to [specific domain] + +### Practical Applications +See these concepts in action: +- **[[example_a]]** - Real implementation of [concept] +- **[[example_b]]** - Case study using [concept] + +### Alternative Paths +Different approaches to similar understanding: +- **[[alternative_a]]** - [Different approach] to achieving similar goals + +--- + +## Critical Concepts + +These notes are central to this learning path: +- **[[critical_note]]** - Required by X other notes in this path + +--- + +## Visual Path + +``` + +Foundations Core Concepts Integration Target +───────────── ───────────── ─────────── ────── + +note_a ──────────┐ + ├──> note_c ────────┐ + │ │ +note_b ──────────┴──> note_d ────────┴──> note_e ──> target_note + +``` + +--- + +## Next Steps + +1. **Start with Level 0** if concepts are new +2. **Skip familiar sections** if you have background knowledge +3. **Use `/graph-note`** to inspect relationships for each note +4. **Use `/expand-graph`** to discover more connections +5. **Review in Obsidian** for visual graph navigation + +**Pro tip:** Open multiple notes in tabs and read through the sequence in order! +``` + +## 9. Handle Edge Cases + +**No prerequisites:** + +``` +Learning Path: [Target Note] + +✅ This note has no prerequisites! + +This is a foundational concept that can be learned directly. +No background knowledge required. + +**Estimated reading time:** X minutes + +**What builds on this:** +After understanding this note, you can explore: +- [[note_x]] - Extends this concept +- [[note_y]] - Applies this concept +``` + +**Circular dependencies:** + +``` +⚠️ Circular Dependency Detected + +The following notes form a dependency cycle: +- [[note_a]] requires [[note_b]] +- [[note_b]] requires [[note_c]] +- [[note_c]] requires [[note_a]] + +**Suggested reading order:** +Read these notes together as an interconnected group: +1. [[note_a]] - Brief overview +2. [[note_b]] - Builds on understanding from note_a +3. [[note_c]] - Completes the cycle +4. Re-read all three for full understanding + +**Action needed:** Consider refactoring these notes to break the cycle. +Use `/graph-validate` to check for more circular dependencies. +``` + +**Very long path (>15 notes):** + +``` +📚 Complex Learning Path Detected + +This path contains N notes across M levels. + +**Suggested approach:** +- Break into smaller milestones +- Focus on one level at a time +- Take breaks between levels +- Consider creating intermediate checkpoints + +**Milestones:** +🎯 Milestone 1: Foundations (Notes 1-5) +🎯 Milestone 2: Core Concepts (Notes 6-10) +🎯 Milestone 3: Advanced Topics (Notes 11-15) +🎯 Milestone 4: Target Mastery (Notes 16-N) +``` + +## 10. Provide Summary Stats + +**Output concise metrics:** + +``` +Learning Path Summary +━━━━━━━━━━━━━━━━━━━━━ + +📊 Path Metrics: +- Total notes: N +- Depth levels: M +- Estimated time: X minutes +- Foundation notes: Y +- Average prerequisites per note: Z + +🎯 Complexity: [Simple|Moderate|Complex] + +💡 Key Insight: [Most important observation about this path] + +🔗 Critical Concept: [Note that appears most frequently as prerequisite] +``` + +## Tools Used + +- **Read** - Get note content, parse "Related Concepts" sections, extract summaries +- **Glob** - Verify notes exist, find similar notes if target not found +- **Parse logic** - Traverse prerequisite chains, topological sort, depth calculation +- **Graph traversal** - Depth-first search with cycle detection + +## Important Notes + +**Quality guidelines:** + +- Clear level progression +- Justify why each prerequisite is needed +- Provide time estimates (realistic reading + comprehension) +- Make path scannable with good formatting +- Include visual representation when helpful +- Handle edge cases gracefully + +**User experience:** + +- Make it easy to start learning immediately +- Show progress milestones +- Suggest checkpoints for complex paths +- Provide escape hatches (skip, alternative paths) +- Encourage practical application + +**Graph integrity:** + +- Report any issues found (cycles, broken links) +- Suggest graph improvements +- Validate prerequisite chains make semantic sense +- Use `/graph-validate` to check bidirectionality + +Execute the learning path generation for the note provided by the user. diff --git a/commands/refresh-topic.md b/commands/refresh-topic.md new file mode 100644 index 0000000..a8df9cd --- /dev/null +++ b/commands/refresh-topic.md @@ -0,0 +1,117 @@ +--- +description: Refresh a topic page with latest information from Perplexity +--- + +# Refresh Topic + +You are tasked with refreshing a topic page with the latest information. Follow these steps: + +## 0. Locate AZKG Repository + +**Check for AZKG_REPO_PATH environment variable:** + +- Use bash conditional: `if [ -z "$AZKG_REPO_PATH" ]; then REPO_PATH=$(pwd); else REPO_PATH="$AZKG_REPO_PATH"; fi` +- **If AZKG_REPO_PATH is set:** Use that path as the repository root +- **If AZKG_REPO_PATH is not set:** Use current working directory (pwd) +- Store result as REPO_PATH for all subsequent file operations + +**All file operations must use REPO_PATH:** + +- Read: `Read(REPO_PATH/filename.md)` or `Read("$REPO_PATH/filename.md")` +- Write: `Write(REPO_PATH/filename.md)` or `Write("$REPO_PATH/filename.md")` +- Edit: `Edit(REPO_PATH/filename.md)` or `Edit("$REPO_PATH/filename.md")` +- Grep: `Grep(pattern, path=REPO_PATH)` or with explicit path +- Glob: `Glob(pattern, path=REPO_PATH)` or with explicit path + +**Example usage:** + +``` +# Check environment variable +if [ -z "$AZKG_REPO_PATH" ]; then + REPO_PATH=$(pwd) +else + REPO_PATH="$AZKG_REPO_PATH" +fi + +# Then use REPO_PATH for all operations +Read("$REPO_PATH/agents.md") +``` + +**Concrete examples:** + +- If AZKG_REPO_PATH="/c/Users/dothompson/OneDrive/src/witt3rd/donald-azkg" + → Read("/c/Users/dothompson/OneDrive/src/witt3rd/donald-azkg/agents.md") +- If AZKG_REPO_PATH is not set and pwd is /c/Users/dothompson/OneDrive/src/witt3rd/donald-azkg + → Read("agents.md") or use full path from pwd + +## 1. Read the Topic File + +- The user will provide a filename (e.g., `agents.md` or just `agents`) +- Read the file from REPO_PATH (not current directory) +- Parse the YAML frontmatter and main content + +## 2. Formulate Perplexity Query + +- Analyze the topic content to understand the main subject +- Extract key concepts, technologies, or themes +- Create a focused query to find: + - Recent developments (last 6-12 months) + - New research or papers + - Updated best practices + - Emerging trends + - Deprecated or outdated information + +Example query format: "What are the latest developments, research, and best practices for [TOPIC] as of 2025? Include any significant changes, new tools, or deprecated approaches." + +## 3. Query Perplexity + +- Use the `mcp__perplexity-ask__perplexity_ask` tool +- Provide a clear, focused query based on the topic analysis +- Request comprehensive, up-to-date information + +## 4. Incorporate Updates + +- Review the Perplexity response carefully +- Identify genuinely new or updated information that should be added +- For each update: + - Determine the appropriate section to update + - Maintain the existing structure and format + - Add new information without removing valuable existing content + - Preserve all existing citations and references + - Add new citations for updated information if provided + +## 5. Update Metadata + +- Add or update the YAML frontmatter with: + + ```yaml + last_refresh: 2025-10-11 # Use today's date + ``` + +- Preserve all existing YAML fields (tags, etc.) +- Maintain YAML formatting + +## 6. Write Updated File + +- Use the Edit tool to make surgical updates to specific sections +- OR use the Write tool if comprehensive rewrite is needed +- Ensure all formatting is preserved (markdown, wikilinks, etc.) + +## 7. Summary + +- Provide a brief summary of: + - What updates were found + - Which sections were modified + - Any significant new information added + - Any outdated information identified (but keep unless contradicted) + +## Important Notes + +- **Preserve existing content**: Only add or update, don't remove unless information is clearly outdated or contradicted +- **Maintain structure**: Keep the same section organization +- **Keep relationships**: Don't modify the "Related Concepts" section +- **Respect format**: Maintain wikilink format `[[note]]`, YAML format, etc. +- **Be conservative**: Only incorporate high-quality, verifiable updates +- **No hyperbole**: Don't add marketing language or grandiose claims + +Execute these steps for the topic file provided by the user. diff --git a/commands/rename-note.md b/commands/rename-note.md new file mode 100644 index 0000000..4cd4412 --- /dev/null +++ b/commands/rename-note.md @@ -0,0 +1,232 @@ +--- +description: Rename a note and update all wikilink references +--- + +# Rename Note Command + +Rename a note file and update all wikilink references throughout the knowledge base. + +## 0. Locate AZKG Repository + +**Check for AZKG_REPO_PATH environment variable:** + +- Use bash conditional: `if [ -z "$AZKG_REPO_PATH" ]; then REPO_PATH=$(pwd); else REPO_PATH="$AZKG_REPO_PATH"; fi` +- **If AZKG_REPO_PATH is set:** Use that path as the repository root +- **If AZKG_REPO_PATH is not set:** Use current working directory (pwd) +- Store result as REPO_PATH for all subsequent file operations + +**All file operations must use REPO_PATH:** + +- Read: `Read(REPO_PATH/filename.md)` or `Read("$REPO_PATH/filename.md")` +- Write: `Write(REPO_PATH/filename.md)` or `Write("$REPO_PATH/filename.md")` +- Edit: `Edit(REPO_PATH/filename.md)` or `Edit("$REPO_PATH/filename.md")` +- Grep: `Grep(pattern, path=REPO_PATH)` or with explicit path +- Glob: `Glob(pattern, path=REPO_PATH)` or with explicit path + +**Example usage:** + +``` +# Check environment variable +if [ -z "$AZKG_REPO_PATH" ]; then + REPO_PATH=$(pwd) +else + REPO_PATH="$AZKG_REPO_PATH" +fi + +# Then use REPO_PATH for all operations +Read("$REPO_PATH/agents.md") +``` + +**Concrete examples:** + +- If AZKG_REPO_PATH="/c/Users/dothompson/OneDrive/src/witt3rd/donald-azkg" + → Read("/c/Users/dothompson/OneDrive/src/witt3rd/donald-azkg/agents.md") +- If AZKG_REPO_PATH is not set and pwd is /c/Users/dothompson/OneDrive/src/witt3rd/donald-azkg + → Read("agents.md") or use full path from pwd + +## Task + +1. Rename the physical markdown file (using Bash mv) +2. Update all wikilinks `[[old_filename]]` → `[[new_filename]]` in all markdown files (using Grep + Edit) +3. Update MOC files if needed (using Edit) + +## Input + +User provides: + +- Old filename (e.g., "mcp_sdk.md" or just "mcp_sdk") +- New filename (e.g., "python_mcp_sdk.md" or just "python_mcp_sdk") + +## Execution Steps + +### 1. Normalize Filenames + +Ensure both filenames have `.md` extension: + +``` +old_filename = "mcp_sdk" → "mcp_sdk.md" +new_filename = "python_mcp_sdk" → "python_mcp_sdk.md" +``` + +### 2. Verify Old File Exists + +Use Glob to check if old file exists: + +```bash +# Check if file exists +Glob mcp_sdk.md +``` + +If not found, report error to user. + +### 3. Check New Filename Not In Use + +Use Glob to ensure new filename doesn't already exist: + +```bash +# Check if new filename is available +Glob python_mcp_sdk.md +``` + +If exists, report error to user. + +### 4. Find All Wikilinks to Old Note + +Use Grep to find all markdown files containing wikilinks to the old note: + +```bash +# Find all files with wikilinks to old note +Grep "\[\[mcp_sdk\]\]" --glob="*.md" --output_mode="files_with_matches" +``` + +Store list of files that need updating. + +### 5. Rename the Physical File + +Use Bash to rename the file: + +```bash +# Rename the file +mv "mcp_sdk.md" "python_mcp_sdk.md" +``` + +### 6. Update Wikilinks in All Files + +For each file found in step 4, use Edit tool to replace wikilinks: + +```markdown +# Old wikilink +[[mcp_sdk]] + +# New wikilink +[[python_mcp_sdk]] +``` + +Use Edit tool for each file: + +- old_string: `[[mcp_sdk]]` +- new_string: `[[python_mcp_sdk]]` +- replace_all: true (to catch all occurrences in the file) + +Track how many files were updated. + +### 7. Update MOC Files + +Check if any MOC files were updated in step 6. If so, verify the context around the wikilink makes sense with the new name. + +## Output Format + +Report to user: + +``` +============================================================ +Renamed Note: mcp_sdk.md → python_mcp_sdk.md +============================================================ + +📝 Physical file renamed + ✓ mcp_sdk.md → python_mcp_sdk.md + +📄 Updated wikilinks in N files: + ✓ file1.md: X reference(s) + ✓ file2.md: Y reference(s) + ✓ file3.md: Z reference(s) + +============================================================ +✅ Rename Complete! +============================================================ + +📋 Summary: + • File renamed: mcp_sdk.md → python_mcp_sdk.md + • Markdown files updated: N + • Total wikilink updates: M + +💡 Next steps: + • Review changes with git diff + • Update note title if needed to match new filename + • Update note tags if needed + • Verify MOC entries make sense with new name +``` + +## Validation + +After renaming: + +- Old file no longer exists (verify with Glob) +- New file exists (verify with Glob) +- No remaining wikilinks to old filename (verify with Grep) +- All "Related Concepts" sections still valid (Read a few files to spot check) + +## Safety Features + +- Check old file exists before renaming +- Check new filename not in use before renaming +- Use replace_all to catch all wikilinks in each file +- Report which files were updated for transparency +- All changes visible in git diff + +## Use Cases + +- **Clarify naming**: Rename `mcp_sdk.md` → `python_mcp_sdk.md` to be more specific +- **Fix typos**: Rename `agnet.md` → `agent.md` +- **Reorganize**: Rename `notes.md` → `note_taking_systems.md` for better descriptiveness +- **Language consistency**: Ensure all filenames follow `language_topic.md` pattern + +## Present Results + +After renaming: + +- Show summary of changes made +- Highlight number of files and references updated +- Suggest reviewing MOC files to ensure context still makes sense +- Recommend updating note title/tags if needed to match new filename + +## Common Patterns + +**Language-specific SDK notes:** + +``` +mcp_sdk.md → python_mcp_sdk.md +(leaves room for typescript_mcp_sdk.md, rust_mcp_sdk.md, etc.) +``` + +**Generic to specific:** + +``` +agents.md → ai_agents.md +deployment.md → docker_deployment.md +``` + +**Consistency with existing patterns:** + +``` +mcp-overview.md → mcp_overview.md (underscore convention) +llm_agents.md → agents.md (when already specific enough) +``` + +## Tools Used + +- **Glob** - Check if files exist +- **Grep** - Find all wikilinks to old filename +- **Bash** - Rename the physical file (mv command) +- **Edit** - Update wikilinks in each markdown file +- **Read** - Spot check updated files for correctness diff --git a/commands/search-notes.md b/commands/search-notes.md new file mode 100644 index 0000000..ac2dcf0 --- /dev/null +++ b/commands/search-notes.md @@ -0,0 +1,315 @@ +--- +description: Search across all notes for a phrase or pattern with context +--- + +# Search Notes + +You are tasked with searching across all notes in the Zettelkasten for a specific phrase or pattern, showing context for each match. + +## 0. Locate AZKG Repository + +**Check for AZKG_REPO_PATH environment variable:** + +- Use bash conditional: `if [ -z "$AZKG_REPO_PATH" ]; then REPO_PATH=$(pwd); else REPO_PATH="$AZKG_REPO_PATH"; fi` +- **If AZKG_REPO_PATH is set:** Use that path as the repository root +- **If AZKG_REPO_PATH is not set:** Use current working directory (pwd) +- Store result as REPO_PATH for all subsequent file operations + +**All file operations must use REPO_PATH:** + +- Read: `Read(REPO_PATH/filename.md)` or `Read("$REPO_PATH/filename.md")` +- Write: `Write(REPO_PATH/filename.md)` or `Write("$REPO_PATH/filename.md")` +- Edit: `Edit(REPO_PATH/filename.md)` or `Edit("$REPO_PATH/filename.md")` +- Grep: `Grep(pattern, path=REPO_PATH)` or with explicit path +- Glob: `Glob(pattern, path=REPO_PATH)` or with explicit path + +**Example usage:** + +``` +# Check environment variable +if [ -z "$AZKG_REPO_PATH" ]; then + REPO_PATH=$(pwd) +else + REPO_PATH="$AZKG_REPO_PATH" +fi + +# Then use REPO_PATH for all operations +Read("$REPO_PATH/agents.md") +``` + +**Concrete examples:** + +- If AZKG_REPO_PATH="/c/Users/dothompson/OneDrive/src/witt3rd/donald-azkg" + → Read("/c/Users/dothompson/OneDrive/src/witt3rd/donald-azkg/agents.md") +- If AZKG_REPO_PATH is not set and pwd is /c/Users/dothompson/OneDrive/src/witt3rd/donald-azkg + → Read("agents.md") or use full path from pwd + +## 1. Parse Search Input + +**Input format:** User provides either: + +- A simple phrase: `/search-notes "semantic routing"` +- A regex pattern: `/search-notes "async.*await"` +- Multiple terms: `/search-notes "MCP security authentication"` + +**Extract:** + +- Search pattern (the phrase or regex) +- Optional flags (case-sensitive, whole word, etc.) + +## 2. Execute Search with Context + +**Use Grep tool to search all markdown files:** + +``` +pattern: +glob: "*.md" +output_mode: "content" +-n: true (show line numbers) +-C: 2 (show 2 lines of context before and after) +-i: true (case insensitive by default) +``` + +**Search strategy:** + +- Search all `.md` files in repository root +- Include line numbers for reference +- Show 2 lines context before and after each match +- Case-insensitive by default (unless user specifies otherwise) + +## 3. Format Results + +**Group results by file and present clearly:** + +``` +Found matches across notes: + +## note_name.md (X matches) + +Match 1 (line 45): +43: context before +44: more context +45: **matching line with PATTERN highlighted** +46: context after +47: more context + +Match 2 (line 120): +118: context before +119: more context +120: **matching line with PATTERN highlighted** +121: context after +122: more context + +--- + +## another_note.md (Y matches) + +Match 1 (line 78): +... +``` + +**Formatting guidelines:** + +- Use `##` headers for each file +- Show match count per file +- Include line numbers for easy navigation +- Bold or highlight the matching text +- Separate files with `---` +- Show total stats at top + +## 4. Analyze Results + +**Provide insights:** + +**Thematic clustering:** + +- Which tags/domains show up most? +- Are matches concentrated in certain batches? +- Example: "Most matches in MCP Protocol notes (5 files)" + +**Related concepts:** + +- Which notes frequently appear together in results? +- Suggest wikilinks between related notes if not already linked + +**Coverage assessment:** + +- Is this concept well-covered or sparse? +- Suggest potential new notes or expansions + +## 5. Suggest Next Actions + +**Based on search results, suggest:** + +**If many matches (>10):** + +- "This concept is well-covered. Consider creating a MOC for [topic]" +- "Consider using `/generate-moc` for this theme" + +**If few matches (1-3):** + +- "Limited coverage found. Consider `/create-note` for deeper treatment" +- "Consider `/expand-graph` on existing notes to add related content" + +**If related concepts found:** + +- "Found related notes that aren't linked. Consider `/link-notes`" +- List specific note pairs that should be connected + +**If search term in multiple contexts:** + +- "This term appears in different contexts: [list domains]" +- "Consider creating separate atomic notes for each context" + +## 6. Advanced Search Options + +**Support optional flags:** + +**Case-sensitive search:** + +- User specifies: `/search-notes --case-sensitive "Python"` +- Set `-i: false` in Grep + +**Whole word only:** + +- User specifies: `/search-notes --whole-word "test"` +- Adjust pattern to: `\btest\b` + +**Regex mode:** + +- User specifies: `/search-notes --regex "mcp.*server"` +- Pass pattern directly to Grep + +**More context:** + +- User specifies: `/search-notes --context 5 "pattern"` +- Set `-C: 5` for 5 lines of context + +**Files only (no content):** + +- User specifies: `/search-notes --files-only "pattern"` +- Set `output_mode: "files_with_matches"` + +## 7. Output Summary + +**Provide concise summary:** + +``` +Search Summary for "" +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +📊 Statistics: +- Total matches: +- Files with matches: +- Most matches: ( matches) + +📁 Distribution by batch: +- MCP Protocol: 5 notes +- Python Stack: 3 notes +- Core AI/Agents: 2 notes + +🏷️ Common tags in results: +#mcp, #python, #security, #api + +💡 Suggestions: +- [Specific actionable next step based on results] +- [Another suggestion] + +🔗 Potentially missing links: +- [[note_a]] ↔ [[note_b]] - both discuss same concept +``` + +## 8. Special Search Patterns + +**Recognize common search needs:** + +**Tag search:** + +- Input: `/search-notes "#mcp"` +- Search in YAML frontmatter tags specifically +- List all notes with that tag + +**Broken wikilinks:** + +- Input: `/search-notes --broken-links` +- Find `[[wikilinks]]` that don't point to existing files +- Report with locations + +**TODOs and incomplete sections:** + +- Input: `/search-notes --todos` +- Find `TODO`, `FIXME`, `[placeholder]`, etc. +- Report what needs completion + +**Missing related concepts:** + +- Input: `/search-notes --no-relationships` +- Find notes with empty "Related Concepts" sections +- Suggest running `/expand-graph` on them + +## Usage Examples + +**Simple search:** + +``` +/search-notes "semantic routing" +``` + +**Regex search:** + +``` +/search-notes --regex "async.*(await|runtime)" +``` + +**Case-sensitive search:** + +``` +/search-notes --case-sensitive "Python" +``` + +**Find all notes about a technology:** + +``` +/search-notes --context 3 "FastMCP" +``` + +**Tag search:** + +``` +/search-notes "#agents" +``` + +**Find broken links:** + +``` +/search-notes --broken-links +``` + +**Find incomplete notes:** + +``` +/search-notes --todos +``` + +## Important Notes + +**Performance:** + +- Grep is fast even across 93+ notes +- Results should return quickly +- If >100 matches, consider limiting output or grouping + +**Formatting:** + +- Keep results scannable +- Use consistent formatting +- Include enough context to understand match +- Link to line numbers for easy navigation: `note.md:45` + +**Accuracy:** + +- Match user's search term exactly as specified +- Don't modify regex patterns unless clarifying with user +- Report if pattern yields no results + +Execute the search for the pattern provided by the user. diff --git a/commands/update-note.md b/commands/update-note.md new file mode 100644 index 0000000..e096d6a --- /dev/null +++ b/commands/update-note.md @@ -0,0 +1,185 @@ +--- +description: Update a note's metadata (title, tags, or summary) +--- + +# Update Note + +Update a note's metadata (title, tags, or summary) in the YAML frontmatter. + +## 0. Locate AZKG Repository + +**Check for AZKG_REPO_PATH environment variable:** + +- Use bash conditional: `if [ -z "$AZKG_REPO_PATH" ]; then REPO_PATH=$(pwd); else REPO_PATH="$AZKG_REPO_PATH"; fi` +- **If AZKG_REPO_PATH is set:** Use that path as the repository root +- **If AZKG_REPO_PATH is not set:** Use current working directory (pwd) +- Store result as REPO_PATH for all subsequent file operations + +**All file operations must use REPO_PATH:** + +- Read: `Read(REPO_PATH/filename.md)` or `Read("$REPO_PATH/filename.md")` +- Write: `Write(REPO_PATH/filename.md)` or `Write("$REPO_PATH/filename.md")` +- Edit: `Edit(REPO_PATH/filename.md)` or `Edit("$REPO_PATH/filename.md")` +- Grep: `Grep(pattern, path=REPO_PATH)` or with explicit path +- Glob: `Glob(pattern, path=REPO_PATH)` or with explicit path + +**Example usage:** + +``` +# Check environment variable +if [ -z "$AZKG_REPO_PATH" ]; then + REPO_PATH=$(pwd) +else + REPO_PATH="$AZKG_REPO_PATH" +fi + +# Then use REPO_PATH for all operations +Read("$REPO_PATH/agents.md") +``` + +**Concrete examples:** + +- If AZKG_REPO_PATH="/c/Users/dothompson/OneDrive/src/witt3rd/donald-azkg" + → Read("/c/Users/dothompson/OneDrive/src/witt3rd/donald-azkg/agents.md") +- If AZKG_REPO_PATH is not set and pwd is /c/Users/dothompson/OneDrive/src/witt3rd/donald-azkg + → Read("agents.md") or use full path from pwd + +## Input + +User provides filename and fields to update: + +- `/update-note agents.md --title "AI Agents: Autonomous Intelligence Systems"` +- `/update-note agents.md --tags "ai,agents,llm,autonomous"` +- `/update-note agents.md --summary "Brief new summary"` + +Can update multiple fields in one command: + +- `/update-note agents.md --title "New Title" --tags "new,tags"` + +## Execution Steps + +### 1. Normalize Filename + +Ensure filename has `.md` extension. + +### 2. Verify Note Exists + +Use Glob to check note exists: + +```bash +Glob "agents.md" +``` + +### 3. Read Current Note + +Use Read tool to get full note content, including current YAML frontmatter. + +### 4. Update YAML Frontmatter + +Use Edit tool to update the specific fields: + +**For title update:** + +- No YAML field for title (title is the first `#` heading) +- Update the first `# Heading` line after YAML frontmatter + +**For tags update:** + +```yaml +--- +tags: [old, tags] +--- +``` + +becomes: + +```yaml +--- +tags: [new, tags, here] +--- +``` + +**For summary update:** + +- Summary is the first paragraph after title (not in YAML) +- Replace first paragraph after title heading + +### 5. Report Changes + +Show old vs new values for updated fields. + +## Output Format + +``` +Updated Note: agents.md +============================================================ + +Title: + Old: AI Agents + New: AI Agents: Autonomous Intelligence Systems + +Tags: + Old: [agents, ai, llm] + New: [ai, agents, llm, autonomous, architecture] + +Summary: + Old: AI agents are autonomous systems... + New: AI agents are autonomous, goal-directed systems... + +============================================================ +✅ Metadata Updated! +============================================================ + +💡 Next steps: +• Review the updated note at agents.md +• Ensure title matches filename semantically +• Verify tags span multiple dimensions (see tag_system.md) +• Consider if related notes need similar updates +``` + +## Validation + +Before updating: + +- Note must exist +- At least one field (title, tags, or summary) must be specified + +After updating: + +- YAML frontmatter remains well-formed +- Tags follow naming convention (lowercase-with-hyphens) +- Title and summary are non-empty + +## Tag Guidelines + +When updating tags, follow best practices: + +- **3-6 tags** per note (enough for discovery, not too many) +- **Mix dimensions**: technology + domain + content type +- **Lowercase with hyphens**: `first-principles` not `FirstPrinciples` +- **Specific over generic**: `mcp` better than `protocol` + +See `tag_system.md` for complete tag catalog. + +## Use Cases + +- **Clarify title**: Make note title more specific or descriptive +- **Add tags**: Add missing tags to improve discoverability +- **Refine summary**: Update summary to better reflect current content +- **Standardize**: Ensure tags follow consistent naming conventions +- **Tag migration**: Update tags when tag system evolves + +## Tools Used + +- **Glob** - Verify note exists +- **Read** - Get current note content +- **Edit** - Update YAML frontmatter and note content +- **Parse logic** - Extract and modify YAML fields + +## Important Notes + +- Changes affect only metadata, not main content +- "Related Concepts" section is never modified by this command +- Title should semantically match filename (e.g., `agents.md` → "AI Agents") +- Tags should be comma-separated when provided +- Use `/conform-note` for structural changes beyond metadata diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..31dc53a --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,93 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:witt3rd/claude-plugins:plugins/azkg", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "fca22364c0e2deb681206bbfb532c49723a39249", + "treeHash": "da524f9b06f6405dc75e379724a8dddab4324a492f3f7662ae67e19a8ba40414", + "generatedAt": "2025-11-28T10:29:03.908620Z", + "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": "azkg", + "description": "Agent-maintained Zettelkasten knowledge graph", + "version": "0.1.0" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "f48f8255c41c87663c5092e4a64691e26c9ee4c9b4303394a258c5df74afcee6" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "e013f2cfca1999e723405853998da668180b4778483fd2ca6ce179df03ab5dad" + }, + { + "path": "commands/learning-path.md", + "sha256": "8aec08c9ac21b894567e9d3fce490df6986f93dfd0576251f67a20697be06111" + }, + { + "path": "commands/graph-moc.md", + "sha256": "0169eb085a980849f5ae4f218ce208d098e754b6fd1aa1e003cc324cded8c4a3" + }, + { + "path": "commands/create-note.md", + "sha256": "76b3db54f1cdbc01ed580ed3461bba6ccc0a596a68559b8d8e03a4b10281f9fb" + }, + { + "path": "commands/search-notes.md", + "sha256": "d2e019e63773a4f1aed6f341c8c0d24e8f4070ac16cc30c2ba7b85c6ddb8eee9" + }, + { + "path": "commands/graph-validate.md", + "sha256": "c614470adfb9f8ccb5ed95f70a597065e0b3f864b5b757f372379863ecb57095" + }, + { + "path": "commands/graph-add-relationship.md", + "sha256": "2b94a399c75de562274180d307108a1998e17484694813aa0a6a6ef19e772c97" + }, + { + "path": "commands/expand-graph.md", + "sha256": "0b8f03913023d91dcd62cd58a53767fdd683c8b0f69e8a8979ea9aec7302fbe3" + }, + { + "path": "commands/graph-stats.md", + "sha256": "abd720f37061e274c11bef240e9648bba3789e7f13ea7f9bc8b4f4bf51d5b1c2" + }, + { + "path": "commands/rename-note.md", + "sha256": "a95ec63b022ca7ce9c5d284dd5668898921f2ff651334f1361cc00129d9c874d" + }, + { + "path": "commands/graph-note.md", + "sha256": "b61e7bd38873e5370132ad300032e29100c67c3ccaf822dc9caea6ff2eb30300" + }, + { + "path": "commands/refresh-topic.md", + "sha256": "544d6df796f9753e20566ba72b278073467d51683a7e41cb69f2ee768679bb1b" + }, + { + "path": "commands/conform-note.md", + "sha256": "4d51e3620ff1e7fc2b657ffe1a52087fab0534345296ce74505e8d0d1c2988a0" + }, + { + "path": "commands/update-note.md", + "sha256": "137a3e43d0a0e2d6db085a4ba2a622714cc35c04caf6b229e255aa64d15f65ab" + } + ], + "dirSha256": "da524f9b06f6405dc75e379724a8dddab4324a492f3f7662ae67e19a8ba40414" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file