7.8 KiB

Raw Blame History

Router-Based Agent System - Architecture

🎯 Why Router Pattern?

Problem with Sequential Flow: ❌ Agents improvise and skip steps
❌ Agents combine instructions from multiple files
❌ Agents take initiatives in wrong order
❌ Unpredictable behavior

Solution: Router Pattern: ✅ Check condition → Route to ONE file → Follow ONLY that file
✅ No flow to skip
✅ No improvisation
✅ Predictable, consistent behavior

🔀 Router Architecture

┌─────────────────────────────────┐
│  USER ACTIVATES AGENT           │
│  @freya / @saga / @idunn       │
└────────────┬────────────────────┘
             │
             ▼
┌─────────────────────────────────┐
│  STEP 1: Show Presentation      │
│  → freya-presentation.md       │
│  → saga-presentation.md         │
│  → idunn-presentation.md        │
└────────────┬────────────────────┘
             │
             ▼
┌─────────────────────────────────┐
│  STEP 2: ROUTER                 │
│  instructions.md (router only)  │
│                                 │
│  Check conditions in order:     │
│  A → B → C → D → E              │
│  STOP at first match            │
└────────────┬────────────────────┘
             │
      ┌──────┴──────┬──────┬──────┬──────┐
      │             │      │      │      │
   COND A        COND B  COND C COND D COND E
      │             │      │      │      │
      ▼             ▼      ▼      ▼      ▼
┌─────────┐  ┌─────────┐ ┌──────┐ ┌────┐ ┌────┐
│Outline  │  │ Folder  │ │Empty │ │New │ │Unkn│
│Exists   │  │Structure│ │Docs  │ │Proj│ │own │
└────┬────┘  └────┬────┘ └───┬──┘ └─┬──┘ └─┬──┘
     │            │           │      │      │
     ▼            ▼           ▼      ▼      ▼
┌──────────┐ ┌──────────┐ ┌─────┐ ┌────┐ ┌────┐
│outline-  │ │folder-   │ │empty│ │new-│ │unkn│
│based-    │ │based-    │ │proj │ │proj│ │own-│
│analysis  │ │analysis  │ │resp │ │resp│ │resp│
│.md       │ │.md       │ │.md  │ │.md │ │.md │
└────┬─────┘ └────┬─────┘ └──┬──┘ └─┬──┘ └─┬──┘
     │            │            │      │      │
     │            │            │      │      │
     └────────────┴────────────┴──────┴──────┘
                  │
                  ▼
         ┌────────────────┐
         │ Present Status │
         │ + Options      │
         └────────┬───────┘
                  │
                  ▼
         ┌────────────────────┐
         │ User Selects Task  │
         └────────┬───────────┘
                  │
          ┌───────┴────────┐
          │                │
    In YOUR Domain   Other Domain
          │                │
          ▼                ▼
    ┌──────────┐    ┌──────────────┐
    │Continue  │    │agent-handoff-│
    │in same   │    │guide.md      │
    │convo     │    │              │
    └──────────┘    └──────┬───────┘
                           │
                           ▼
                    ┌──────────────┐
                    │ Hand Over to │
                    │ Other Agent  │
                    └──────────────┘

📁 File Structure

project-analysis/
├── instructions.md                    ← ROUTER ONLY
├── agent-handoff-guide.md             ← Handoff instructions
├── analysis-types/                    ← Routed destinations
│   ├── outline-based-analysis.md      ← FAST (Condition A)
│   ├── folder-based-analysis.md       ← FALLBACK (Condition B)
│   ├── empty-project-response.md      ← Quick response (Condition C)
│   ├── new-project-response.md        ← Quick response (Condition D)
│   └── unknown-structure-response.md  ← Quick response (Condition E)
└── agent-domains/                     ← Agent expertise
    ├── saga-domain.md                 ← Phases 1-2
    ├── freya-domain.md               ← Phases 4-5, 7
    └── idunn-domain.md                ← Phases 3, 6

🎯 Router Conditions

Checked in order. First match wins.

A: Project Outline Exists?
   → docs/.wds-project-outline.yaml
   → .wds-project-outline.yaml
   IF YES → outline-based-analysis.md (FAST!)

B: Docs Folder with Structure?
   → docs/1-*, docs/A-* folders exist
   IF YES → folder-based-analysis.md (FALLBACK)

C: Empty Docs Folder?
   → docs/ exists but empty
   IF YES → empty-project-response.md (QUICK)

D: No Docs Folder?
   → No docs/ folder at all
   IF YES → new-project-response.md (QUICK)

E: Unknown Structure?
   → docs/ exists but no pattern match
   IF YES → unknown-structure-response.md (QUICK)

🔑 Key Principles

1. Router is NOT a Flow

Router checks conditions
Router routes to ONE file
Agent follows ONLY that ONE file
No combining files

2. Routed Files are Complete

Each analysis file is standalone
Contains all instructions needed
Tells agent exactly what to present
No references back to router

3. Agent Domain Files are Reference

Loaded AFTER analysis complete
Used for generating recommendations
Lists "when to stay" vs "when to hand over"

4. Handoff Guide is Universal

One handoff pattern for all agents
Clear 4-step process
No copy/paste needed
Seamless agent switch

✅ Benefits of Router Pattern

Sequential Flow	Router Pattern
Agent improvises	Agent follows ONE file
Skips steps	No steps to skip
Unpredictable	Predictable
Takes initiatives	Follows instructions
Combines files	Uses ONE file only

🎨 Example: Freya Activation

User: @freya help me

Router checks:

Outline exists? → YES ✅
Route to: outline-based-analysis.md
STOP (don't check B, C, D, E)

Freya follows outline-based-analysis.md ONLY:

Reads outline
Presents status
Shows user intentions
Suggests 2-4 options

User: "I need technical requirements"

Freya checks: freya-domain.md
→ "Technical requirements" = Phase 3 = Idunn's domain

Freya uses: agent-handoff-guide.md
→ Hands over to Idunn seamlessly

Idunn activates automatically:

Shows presentation
Router checks → Outline exists
Routes to: outline-based-analysis.md
Reads SAME outline
Continues helping!

Router pattern = Predictable, consistent agent behavior! 🎯

7.8 KiB Raw Blame History