gh-witt3rd-claude-plugins-plugins-azkg/commands/graph-add-relationship.md

description

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:

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:

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