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

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.