Skip to content

QUICK_START.md

Latest commit

 

History

History
317 lines (235 loc) · 8.21 KB

QUICK_START.md

File metadata and controls

317 lines (235 loc) · 8.21 KB

Quick Start Guide

Get started troubleshooting network, VoIP, and security issues in 5 minutes

📥 Installation (2 minutes)

Option 1: Copy to RooCode Directory

# Navigate to this directory
cd /Users/bhunt/development/claude/claude-saas-framework/roocode-network-engineering

# Copy orchestrators
cp orchestrators/*.yaml ~/.roo/custom-modes/

# Copy specialists
cp specialists/troubleshooting/*.yaml ~/.roo/custom-modes/

# Done!

Option 2: Import via RooCode UI

  1. Open RooCode
  2. Go to Settings → Custom Modes
  3. Click "Import"
  4. Select YAML files from orchestrators/ and specialists/troubleshooting/
  5. Click "Import"

🚀 Basic Usage (3 minutes to first result)

Example 1: OSPF Neighbors Not Forming

In RooCode chat:

User: "OSPF neighbors not coming up between R1 and R2"

@network-orchestrator

Network Orchestrator will:
  1. Ask clarifying questions (if needed)
  2. Launch Network Troubleshooter
  3. Analyze the issue systematically
  4. Provide root cause and fix
  5. Generate validation steps

Result: Complete diagnosis in ~2 minutes

Example 2: Choppy Audio on VoIP Calls

In RooCode chat:

User: "Users complaining about choppy audio on calls"

@voip-orchestrator

VoIP Orchestrator will:
  1. Detect platform (CUCM vs AWS Connect vs SBC)
  2. Launch VoIP Troubleshooter
  3. Analyze call quality metrics
  4. Check QoS, codecs, network path
  5. Provide fix with validation

Result: Root cause + fix in ~3 minutes

Example 3: ISE Authentication Failures

In RooCode chat:

User: "Users getting authentication failures on ISE"

@security-orchestrator

Security Orchestrator will:
  1. Launch ISE Troubleshooter
  2. Ask for ISE live logs
  3. Analyze auth flow
  4. Identify root cause (cert, AD, policy)
  5. Provide step-by-step fix

Result: Root cause identified in ~2 minutes

🔌 Offline Mode (For Remote Sites)

Generate Diagnostic Script

When you'll be at a site with no internet:

User: "I need to troubleshoot BGP but I'll be offline at the site"

@network-orchestrator

Network Orchestrator will:
  1. Detect offline mode
  2. Generate diagnostic-bgp.sh
  3. Script includes all commands with logging
  4. You copy script to USB or print it

At site:
  - Run: bash diagnostic-bgp.sh
  - Script creates: diagnostic-YYYYMMDD-HHMMSS.log
  - Bring log file back

Back online:
  - Paste log to @network-orchestrator
  - Orchestrator analyzes logs
  - Provides root cause and fix

Result: Full diagnosis from offline evidence

🎯 Which Orchestrator to Use?

Issue Type Orchestrator Examples
Routing/Switching @network-orchestrator OSPF neighbors down, BGP stuck, VLAN issues, STP loops
VoIP/Voice @voip-orchestrator Call quality, one-way audio, registration failures, SIP issues
Security/Auth @security-orchestrator 802.1X failures, wrong VLAN, ISE errors, certificate issues

Not sure? Start with the most relevant one - orchestrators can handoff to each other if needed.

📊 What You'll Get

Every orchestrator provides:

  1. Issue Summary

    • Problem description
    • Affected components
    • Impact assessment

  2. Diagnostic Results

    • Step-by-step analysis
    • Command outputs or log excerpts
    • Evidence collected

  3. Root Cause

    • Specific issue identified
    • Why it's happening
    • Evidence supporting diagnosis

  4. Resolution Steps

    • Step-by-step fix
    • CLI commands (if applicable)
    • Configuration changes

  5. Validation

    • How to verify fix worked
    • Commands to check status
    • What to monitor

  6. Prevention

    • Recommendations to prevent recurrence
    • Monitoring suggestions
    • Best practices

💡 Pro Tips

Get Better Results:

  1. Provide Context

    Good: "OSPF neighbors not forming between R1 gi0/1 and R2 gi0/2"
Better: "OSPF neighbors stuck in INIT state between R1 gi0/1 (10.1.1.1/24) and R2 gi0/2 (10.1.1.2/24). Both in Area 0. Started after switch replacement."

  2. Answer Clarifying Questions

    • Orchestrators may ask for platform details
    • Provide specific information (CUCM vs AWS Connect, ISE vs Firewall)
    • Better answers = faster diagnosis

  3. Provide Logs/Outputs

    "Here's the output of show ip ospf neighbor:
[paste output]"

  4. Use Offline Mode Wisely

    • Generate scripts BEFORE traveling to site
    • Run scripts at site with comprehensive logging
    • Bring back COMPLETE log file (don't truncate)

  5. Follow Specialist Recommendations

    • If specialist says "launch packet analyzer", do it
    • Specialists know when deep-dive analysis is needed
    • Trust the systematic approach

🔧 Common Workflows

Workflow: Network Issue

1. @network-orchestrator
2. Describe issue
3. Provide show command outputs if available
4. Orchestrator launches Network Troubleshooter
5. If packet analysis needed → Packet Analyzer launched
6. Get complete diagnosis + fix

Workflow: VoIP Call Quality

1. @voip-orchestrator
2. Describe symptoms (choppy, one-way, echo)
3. Specify platform (CUCM, AWS Connect, SBC)
4. Orchestrator launches VoIP Troubleshooter
5. If needed → Packet Analyzer for SIP/RTP analysis
6. Get root cause + QoS/codec fix

Workflow: ISE Authentication

1. @security-orchestrator
2. Describe auth failure
3. Provide ISE live logs (or orchestrator will ask)
4. Orchestrator launches ISE Troubleshooter
5. If needed → Authentication Analyzer for RADIUS flow
6. Get root cause (cert, AD, policy) + fix

Workflow: Offline Troubleshooting

1. @[any-orchestrator]
2. Say "I'll be offline" or "no connectivity at site"
3. Orchestrator generates diagnostic script
4. Copy script to site
5. Run script → captures all outputs to log
6. Bring log back
7. Paste log to orchestrator
8. Get root cause + fix from offline evidence

📚 Need More Help?

✅ Checklist: First Use

  • Install orchestrators and specialists (copy YAMLs to RooCode)
  • Test with simple issue: @network-orchestrator → "How do I troubleshoot OSPF?"
  • Verify orchestrator responds and can launch specialists
  • Try offline mode: "Generate offline script for BGP troubleshooting"
  • Verify script is generated with logging commands
  • Ready for production use!

🎓 Learning Path

Beginner (First Hour):

  1. Install files
  2. Run simple test: Ask orchestrator a question
  3. Try one real issue from your network
  4. Review the output format

Intermediate (First Day):

  1. Use all 3 orchestrators (Network, VoIP, Security)
  2. Try offline mode workflow
  3. Understand when each specialist is launched
  4. Learn to provide better context for faster results

Advanced (First Week):

  1. Create custom context files in .network-config/ for your environment
  2. Save offline scripts for reuse
  3. Build runbook library from resolutions
  4. Optimize workflows for your common issues

🚨 Troubleshooting the System

Orchestrator Not Responding?

  • Verify YAML imported correctly in RooCode settings
  • Check for syntax errors in YAML (validate with yamllint)
  • Ensure @orchestrator-name matches slug in YAML

Specialists Not Launching?

  • Orchestrators are read-only (correct behavior)
  • Specialists should have groups: [read, edit, command]
  • Check RooCode logs for errors

Context Files Not Loading?

  • Verify paths in specialist YAML: contexts/filename.md
  • Ensure context files are in correct directory
  • Check file permissions (readable)

Offline Scripts Not Working?

  • Ensure bash is available on target system
  • Check script permissions: chmod +x script.sh
  • Verify tee command available (standard on most systems)

You're ready to go! Start with @network-orchestrator and try your first issue. 🚀

Questions? Check README.md or PHASE_2_SUMMARY.md for detailed documentation.