Add VPN configuration tools and agent documentation
Created comprehensive VPN setup tooling for Peaceful Spirit L2TP/IPsec connection and enhanced agent documentation framework. VPN Configuration (PST-NW-VPN): - Setup-PST-L2TP-VPN.ps1: Automated L2TP/IPsec setup with split-tunnel and DNS - Connect-PST-VPN.ps1: Connection helper with PPP adapter detection, DNS (192.168.0.2), and route config (192.168.0.0/24) - Connect-PST-VPN-Standalone.ps1: Self-contained connection script for remote deployment - Fix-PST-VPN-Auth.ps1: Authentication troubleshooting for CHAP/MSChapv2 - Diagnose-VPN-Interface.ps1: Comprehensive VPN interface and routing diagnostic - Quick-Test-VPN.ps1: Fast connectivity verification (DNS/router/routes) - Add-PST-VPN-Route-Manual.ps1: Manual route configuration helper - vpn-connect.bat, vpn-disconnect.bat: Simple batch file shortcuts - OpenVPN config files (Windows-compatible, abandoned for L2TP) Key VPN Implementation Details: - L2TP creates PPP adapter with connection name as interface description - UniFi auto-configures DNS (192.168.0.2) but requires manual route to 192.168.0.0/24 - Split-tunnel enabled (only remote traffic through VPN) - All-user connection for pre-login auto-connect via scheduled task - Authentication: CHAP + MSChapv2 for UniFi compatibility Agent Documentation: - AGENT_QUICK_REFERENCE.md: Quick reference for all specialized agents - documentation-squire.md: Documentation and task management specialist agent - Updated all agent markdown files with standardized formatting Project Organization: - Moved conversation logs to dedicated directories (guru-connect-conversation-logs, guru-rmm-conversation-logs) - Cleaned up old session JSONL files from projects/msp-tools/ - Added guru-connect infrastructure (agent, dashboard, proto, scripts, .gitea workflows) - Added guru-rmm server components and deployment configs Technical Notes: - VPN IP pool: 192.168.4.x (client gets 192.168.4.6) - Remote network: 192.168.0.0/24 (router at 192.168.0.10) - PSK: rrClvnmUeXEFo90Ol+z7tfsAZHeSK6w7 - Credentials: pst-admin / 24Hearts$ Files: 15 VPN scripts, 2 agent docs, conversation log reorganization, guru-connect/guru-rmm infrastructure additions Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
434
.claude/agents/AGENT_QUICK_REFERENCE.md
Normal file
434
.claude/agents/AGENT_QUICK_REFERENCE.md
Normal file
@@ -0,0 +1,434 @@
|
||||
---
|
||||
name: "Agent Quick Reference"
|
||||
description: "Quick reference guide for all available specialized agents"
|
||||
---
|
||||
|
||||
# Agent Quick Reference
|
||||
|
||||
**Last Updated:** 2026-01-18
|
||||
|
||||
---
|
||||
|
||||
## Available Specialized Agents
|
||||
|
||||
### Documentation Squire (documentation-squire)
|
||||
**Purpose:** Handle all documentation and keep Main Claude organized
|
||||
**When to Use:**
|
||||
- Creating/updating .md files (guides, summaries, trackers)
|
||||
- Need task checklist for complex work
|
||||
- Main Claude forgetting TodoWrite
|
||||
- Documentation getting out of sync
|
||||
- Need completion summaries
|
||||
|
||||
**Invocation:**
|
||||
```
|
||||
Task tool:
|
||||
subagent_type: "documentation-squire"
|
||||
model: "haiku" (cost-efficient)
|
||||
prompt: "Create [type] documentation for [work]"
|
||||
```
|
||||
|
||||
**Example:**
|
||||
```
|
||||
User: "Create a technical debt tracker"
|
||||
|
||||
Main Claude invokes:
|
||||
subagent_type: "documentation-squire"
|
||||
prompt: "Create comprehensive technical debt tracker for GuruConnect, including all pending items from Phase 1"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Agent Delegation Rules
|
||||
|
||||
### Main Claude Should Delegate When:
|
||||
|
||||
**Documentation Work:**
|
||||
- ✓ Creating README, guides, summaries
|
||||
- ✓ Updating technical debt trackers
|
||||
- ✓ Writing installation instructions
|
||||
- ✓ Creating troubleshooting guides
|
||||
- ✗ Inline code comments (Main Claude handles)
|
||||
- ✗ Quick status messages to user (Main Claude handles)
|
||||
|
||||
**Task Organization:**
|
||||
- ✓ Complex tasks (>3 steps) - Let Doc Squire create checklist
|
||||
- ✓ Multiple parallel tasks - Doc Squire manages
|
||||
- ✗ Simple single-step tasks (Main Claude uses TodoWrite directly)
|
||||
|
||||
**Specialized Work:**
|
||||
- ✓ Code review - Invoke code review agent
|
||||
- ✓ Testing - Invoke testing agent
|
||||
- ✓ Frontend - Invoke frontend design skill
|
||||
- ✓ Infrastructure setup - Invoke infrastructure agent
|
||||
- ✗ Simple edits (Main Claude handles directly)
|
||||
|
||||
---
|
||||
|
||||
## Invocation Patterns
|
||||
|
||||
### Pattern 1: Documentation Creation (Most Common)
|
||||
```
|
||||
User: "Document the CI/CD setup"
|
||||
|
||||
Main Claude:
|
||||
1. Invokes Documentation Squire
|
||||
2. Provides context (what was built, key details)
|
||||
3. Receives completed documentation
|
||||
4. Shows user summary and file location
|
||||
```
|
||||
|
||||
### Pattern 2: Task Management Reminder
|
||||
```
|
||||
Main Claude: [Starting complex work without TodoWrite]
|
||||
|
||||
Documentation Squire: [Auto-reminder]
|
||||
"You're starting complex CI/CD work without a task list.
|
||||
Consider using TodoWrite to track progress."
|
||||
|
||||
Main Claude: [Uses TodoWrite or delegates to Doc Squire for checklist]
|
||||
```
|
||||
|
||||
### Pattern 3: Agent Coordination
|
||||
```
|
||||
Code Review Agent: [Completes review]
|
||||
"Documentation needed: Update technical debt tracker"
|
||||
|
||||
Main Claude: [Invokes Documentation Squire]
|
||||
"Update TECHNICAL_DEBT.md with code review findings"
|
||||
|
||||
Documentation Squire: [Updates tracker]
|
||||
Main Claude: "Tracker updated. Proceeding with fixes..."
|
||||
```
|
||||
|
||||
### Pattern 4: Status Check
|
||||
```
|
||||
User: "What's the current status?"
|
||||
|
||||
Main Claude: [Invokes Documentation Squire]
|
||||
"Generate current project status summary"
|
||||
|
||||
Documentation Squire:
|
||||
- Reads PHASE1_COMPLETE.md, TECHNICAL_DEBT.md, etc.
|
||||
- Creates unified status report
|
||||
- Returns summary
|
||||
|
||||
Main Claude: [Shows user the summary]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## When NOT to Use Agents
|
||||
|
||||
### Main Claude Should Handle Directly:
|
||||
|
||||
**Simple Tasks:**
|
||||
- Single file edits
|
||||
- Quick code changes
|
||||
- Simple questions
|
||||
- User responses
|
||||
- Status updates
|
||||
|
||||
**Interactive Work:**
|
||||
- Debugging with user
|
||||
- Asking clarifying questions
|
||||
- Real-time troubleshooting
|
||||
- Immediate user requests
|
||||
|
||||
**Code Work:**
|
||||
- Writing code (unless specialized like frontend)
|
||||
- Code comments
|
||||
- Simple refactoring
|
||||
- Bug fixes
|
||||
|
||||
---
|
||||
|
||||
## Agent Communication Protocol
|
||||
|
||||
### Requesting Documentation from Agent
|
||||
|
||||
**Template:**
|
||||
```
|
||||
Task tool:
|
||||
subagent_type: "documentation-squire"
|
||||
model: "haiku"
|
||||
prompt: "[Action] [Type] for [Context]
|
||||
|
||||
Details:
|
||||
- [Key detail 1]
|
||||
- [Key detail 2]
|
||||
- [Key detail 3]
|
||||
|
||||
Output format: [What you want]"
|
||||
```
|
||||
|
||||
**Example:**
|
||||
```
|
||||
Task tool:
|
||||
subagent_type: "documentation-squire"
|
||||
model: "haiku"
|
||||
prompt: "Create CI/CD activation guide for GuruConnect
|
||||
|
||||
Details:
|
||||
- 3 workflows created (build, test, deploy)
|
||||
- Runner installed but not registered
|
||||
- Need step-by-step activation instructions
|
||||
|
||||
Output format: Comprehensive guide with troubleshooting section"
|
||||
```
|
||||
|
||||
### Agent Signaling Documentation Needed
|
||||
|
||||
**Template:**
|
||||
```
|
||||
[DOCUMENTATION NEEDED]
|
||||
|
||||
Work completed: [description]
|
||||
Documentation type: [guide/summary/tracker update]
|
||||
Key information:
|
||||
- [point 1]
|
||||
- [point 2]
|
||||
- [point 3]
|
||||
|
||||
Files to update: [file list]
|
||||
Suggested filename: [name]
|
||||
|
||||
Passing to Documentation Squire agent...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## TodoWrite Best Practices
|
||||
|
||||
### When to Use TodoWrite
|
||||
|
||||
**YES - Use TodoWrite:**
|
||||
- Complex tasks with 3+ steps
|
||||
- Multi-file changes
|
||||
- Long-running work (>10 minutes)
|
||||
- Tasks with dependencies
|
||||
- Work that might span messages
|
||||
|
||||
**NO - Don't Use TodoWrite:**
|
||||
- Single-step tasks
|
||||
- Quick responses
|
||||
- Simple questions
|
||||
- Already delegated to agent
|
||||
|
||||
### TodoWrite Format
|
||||
|
||||
```
|
||||
TodoWrite:
|
||||
todos:
|
||||
- content: "Action in imperative form"
|
||||
activeForm: "Action in present continuous"
|
||||
status: "pending" | "in_progress" | "completed"
|
||||
```
|
||||
|
||||
**Example:**
|
||||
```
|
||||
todos:
|
||||
- content: "Create build workflow"
|
||||
activeForm: "Creating build workflow"
|
||||
status: "in_progress"
|
||||
|
||||
- content: "Test workflow triggers"
|
||||
activeForm: "Testing workflow triggers"
|
||||
status: "pending"
|
||||
```
|
||||
|
||||
### TodoWrite Rules
|
||||
|
||||
1. **Exactly ONE task in_progress at a time**
|
||||
2. **Mark complete immediately after finishing**
|
||||
3. **Update before switching tasks**
|
||||
4. **Remove irrelevant tasks**
|
||||
5. **Break down complex tasks**
|
||||
|
||||
---
|
||||
|
||||
## Documentation Standards
|
||||
|
||||
### File Naming
|
||||
- `ALL_CAPS.md` - Major documents (TECHNICAL_DEBT.md)
|
||||
- `lowercase-dashed.md` - Specific guides (activation-guide.md)
|
||||
- `PascalCase.md` - Code-related docs (APIReference.md)
|
||||
- `PHASE#_WEEKN_STATUS.md` - Phase tracking
|
||||
|
||||
### Document Headers
|
||||
```markdown
|
||||
# Title
|
||||
|
||||
**Status:** [Active/Complete/Deprecated]
|
||||
**Last Updated:** YYYY-MM-DD
|
||||
**Related Docs:** [Links]
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
...
|
||||
```
|
||||
|
||||
### Formatting Rules
|
||||
- ✓ Headers for hierarchy (##, ###)
|
||||
- ✓ Code blocks with language tags
|
||||
- ✓ Tables for structured data
|
||||
- ✓ Lists for sequences
|
||||
- ✓ Bold for emphasis
|
||||
- ✗ NO EMOJIS (project guideline)
|
||||
- ✗ No ALL CAPS in prose
|
||||
- ✓ Clear section breaks (---)
|
||||
|
||||
---
|
||||
|
||||
## Decision Matrix: Should I Delegate?
|
||||
|
||||
| Task Type | Delegate To | Direct Handle |
|
||||
|-----------|-------------|---------------|
|
||||
| Create README | Documentation Squire | - |
|
||||
| Update tech debt | Documentation Squire | - |
|
||||
| Write guide | Documentation Squire | - |
|
||||
| Code review | Code Review Agent | - |
|
||||
| Run tests | Testing Agent | - |
|
||||
| Frontend design | Frontend Skill | - |
|
||||
| Simple code edit | - | Main Claude |
|
||||
| Answer question | - | Main Claude |
|
||||
| Debug with user | - | Main Claude |
|
||||
| Quick status | - | Main Claude |
|
||||
|
||||
**Rule of Thumb:**
|
||||
- **Specialized work** → Delegate to specialist
|
||||
- **Documentation** → Documentation Squire
|
||||
- **Simple/interactive** → Main Claude
|
||||
- **When unsure** → Ask Documentation Squire for advice
|
||||
|
||||
---
|
||||
|
||||
## Common Scenarios
|
||||
|
||||
### Scenario 1: User Asks for Status
|
||||
```
|
||||
User: "What's the current status?"
|
||||
|
||||
Main Claude options:
|
||||
A) Quick status → Answer directly from memory
|
||||
B) Comprehensive status → Invoke Documentation Squire to generate report
|
||||
C) Unknown status → Invoke Doc Squire to research and report
|
||||
|
||||
Choose: Based on complexity and detail needed
|
||||
```
|
||||
|
||||
### Scenario 2: Completed Major Work
|
||||
```
|
||||
Main Claude: [Just completed CI/CD setup]
|
||||
|
||||
Next steps:
|
||||
1. Mark todos complete
|
||||
2. Invoke Documentation Squire to create completion summary
|
||||
3. Update TECHNICAL_DEBT.md (via Doc Squire)
|
||||
4. Tell user what was accomplished
|
||||
|
||||
DON'T: Write completion summary inline (delegate to Doc Squire)
|
||||
```
|
||||
|
||||
### Scenario 3: Starting Complex Task
|
||||
```
|
||||
User: "Implement CI/CD pipeline"
|
||||
|
||||
Main Claude:
|
||||
1. Invoke Documentation Squire: "Create task checklist for CI/CD implementation"
|
||||
2. Doc Squire returns checklist
|
||||
3. Use TodoWrite with checklist items
|
||||
4. Begin implementation
|
||||
|
||||
DON'T: Skip straight to implementation without task list
|
||||
```
|
||||
|
||||
### Scenario 4: Found Technical Debt
|
||||
```
|
||||
Main Claude: [Discovers systemd watchdog issue]
|
||||
|
||||
Next steps:
|
||||
1. Fix immediate problem
|
||||
2. Note need for proper implementation
|
||||
3. Invoke Documentation Squire: "Add systemd watchdog implementation to TECHNICAL_DEBT.md"
|
||||
4. Continue with main work
|
||||
|
||||
DON'T: Manually edit TECHNICAL_DEBT.md (let Doc Squire maintain it)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "When should I invoke vs handle directly?"
|
||||
|
||||
**Invoke agent when:**
|
||||
- Specialized knowledge needed
|
||||
- Large documentation work
|
||||
- Want to save context
|
||||
- Task will take multiple steps
|
||||
- Need consistency across files
|
||||
|
||||
**Handle directly when:**
|
||||
- Simple one-off task
|
||||
- Need immediate response
|
||||
- Interactive with user
|
||||
- Already know exactly what to do
|
||||
|
||||
### "Agent not available?"
|
||||
|
||||
If agent doesn't exist, Main Claude should handle directly but note:
|
||||
```
|
||||
[FUTURE AGENT OPPORTUNITY]
|
||||
|
||||
Task: [description]
|
||||
Would benefit from: [agent type]
|
||||
Reason: [why specialized agent would help]
|
||||
|
||||
Add to future agent development list.
|
||||
```
|
||||
|
||||
### "Multiple agents needed?"
|
||||
|
||||
**Coordination approach:**
|
||||
1. Break down work by specialty
|
||||
2. Invoke agents sequentially
|
||||
3. Use Documentation Squire to coordinate outputs
|
||||
4. Main Claude integrates results
|
||||
|
||||
---
|
||||
|
||||
## Quick Commands
|
||||
|
||||
### Invoke Documentation Squire
|
||||
```
|
||||
Task with subagent_type="documentation-squire", prompt="[task]"
|
||||
```
|
||||
|
||||
### Create Task Checklist
|
||||
```
|
||||
Invoke Doc Squire: "Create task checklist for [work]"
|
||||
Then use TodoWrite with checklist
|
||||
```
|
||||
|
||||
### Update Technical Debt
|
||||
```
|
||||
Invoke Doc Squire: "Add [item] to TECHNICAL_DEBT.md under [priority] priority"
|
||||
```
|
||||
|
||||
### Generate Status Report
|
||||
```
|
||||
Invoke Doc Squire: "Generate current project status summary"
|
||||
```
|
||||
|
||||
### Create Completion Summary
|
||||
```
|
||||
Invoke Doc Squire: "Create completion summary for [work done]"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Document Version:** 1.0
|
||||
**Purpose:** Quick reference for agent delegation
|
||||
**Audience:** Main Claude, future agent developers
|
||||
Reference in New Issue
Block a user