zhongwei/gh-witt3rd-claude-plugins-plugins-azkg
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 09:06:41 +08:00
commit 9ddf7bc2c1
16 changed files with 3723 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

24
.claude-plugin/plugin.json Normal file
View File

@@ -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"
]
}

3
README.md Normal file
View File

@@ -0,0 +1,3 @@
# azkg
Agent-maintained Zettelkasten knowledge graph

254
commands/conform-note.md Normal file
View File

@@ -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: <original_url_or_path> # 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] <https://example.com>
[2] <https://example.com>
```
## 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] <https://example.com>
```
Execute this transformation for the note file specified by the user.

324
commands/create-note.md Normal file
View File

@@ -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.

730
commands/expand-graph.md Normal file
View File

@@ -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.

189
commands/graph-add-relationship.md Normal file
View File

@@ -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

203
commands/graph-moc.md Normal file
View File

@@ -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?
```

185
commands/graph-note.md Normal file
View File

@@ -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

198
commands/graph-stats.md Normal file
View File

@@ -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)

225
commands/graph-validate.md Normal file
View File

@@ -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)

446
commands/learning-path.md Normal file
View File

@@ -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.

117
commands/refresh-topic.md Normal file
View File

@@ -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.

232
commands/rename-note.md Normal file
View File

@@ -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

315
commands/search-notes.md Normal file
View File

@@ -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: <user's search term>
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 <N> matches across <M> 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 "<search-pattern>"
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📊 Statistics:
- Total matches: <N>
- Files with matches: <M>
- Most matches: <filename> (<X> 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.

185
commands/update-note.md Normal file
View File

@@ -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

93
plugin.lock.json Normal file
View File

@@ -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": []
}
}