test-backend-router

Purpose: Demonstrate thin router pattern for on-demand documentation retrieval.

This is a proof-of-concept router skill showing how to replace automatic documentation injection with progressive disclosure via doc-lookup.

When to Use This Skill (NOT the Agent)

Use this skill for simple, focused tasks:

• ✅ Reading CLI help text
• ✅ Understanding server configuration
• ✅ Reviewing database schema structure
• ✅ Learning MCP tool signatures
• ✅ Small config changes (<20 lines, 1 file)
• ✅ Debugging with logs (read-only investigation)

Typical token usage: ~1,500 tokens (router + specific section)

When to Escalate to dipeo-backend Agent

Escalate for complex, multi-step work:

• ❌ Adding new CLI commands (multi-file changes)
• ❌ Database schema migrations
• ❌ New MCP tool implementation
• ❌ FastAPI route changes (>1 file)
• ❌ Background execution modifications
• ❌ Any task affecting >2 files

Agent token usage: Higher, but justified for complex work

Decision Workflow

1. Task received
     ↓
2. Is it simple? (1 file, <20 lines, read-only)
     ↓ YES                    ↓ NO
3. Use this skill          5. Escalate to agent
     ↓
4. Need detailed docs?
     ↓ YES
   Load doc-lookup with specific anchor

Key Documentation Sections

Use Skill(doc-lookup) with these anchors for targeted retrieval:

CLI Commands & Architecture

• Full guide: docs/agents/backend-development.md#cli-system
• Command examples: docs/agents/backend-development.md#cli-commands
• Architecture: docs/agents/backend-development.md#cli-architecture
• Background execution: docs/agents/backend-development.md#background-execution

Example lookup:

python .claude/skills/doc-lookup/scripts/section_search.py \
  --query "cli-commands" \
  --paths docs/agents/backend-development.md \
  --top 1

FastAPI Server

• Overview: docs/agents/backend-development.md#fastapi-server
• Core responsibilities: docs/agents/backend-development.md#core-responsibilities

Database & Persistence

• Database schema: docs/agents/backend-development.md#database-schema
• Message store: docs/agents/backend-development.md#message-store
• Full DB section: docs/agents/backend-development.md#database-persistence

Example lookup:

python .claude/skills/doc-lookup/scripts/section_search.py \
  --query "database-schema" \
  --paths docs/agents/backend-development.md \
  --top 1 \
  --max-lines 40

MCP Server Integration

• MCP overview: docs/agents/backend-development.md#mcp-server
• MCP tools: docs/agents/backend-development.md#mcp-tools
• MCP resources: docs/agents/backend-development.md#mcp-resources
• MCP architecture: docs/agents/backend-development.md#mcp-architecture

Example lookup:

python .claude/skills/doc-lookup/scripts/section_search.py \
  --query "mcp-tools" \
  --paths docs/agents/backend-development.md \
  --top 1

General Reference

• Common patterns: docs/agents/backend-development.md#common-patterns
• Troubleshooting: docs/agents/backend-development.md#troubleshooting
• Escalation: docs/agents/backend-development.md#escalation

Usage Examples

Example 1: Understanding CLI Flags

User request: "How do I add a --json flag to dipeo run?"

Router workflow:

1. Assess: Simple task, need CLI context
2. Load doc-lookup for CLI commands section:

   python .claude/skills/doc-lookup/scripts/section_search.py \
     --query "cli-commands" \
     --paths docs/agents/backend-development.md \
     --top 1
   

3. Review returned section (~50 lines)
4. Answer question or make simple change
5. Token cost: ~1,000 tokens (vs. 15,000 with auto-injection)

Example 2: Debugging MCP Tool Registration

User request: "The dipeo_run MCP tool isn't showing up"

Router workflow:

1. Assess: Debugging task, need MCP tool context
2. Load doc-lookup for MCP tools:

   python .claude/skills/doc-lookup/scripts/section_search.py \
     --query "mcp-tools" \
     --paths docs/agents/backend-development.md \
     --top 1 \
     --max-lines 50
   

3. Review MCP tool implementation section
4. Investigate registration logic
5. If fix is simple → handle directly
6. If complex (multi-file) → escalate to agent

Example 3: Database Schema Review

User request: "What columns are in the executions table?"

Router workflow:

1. Assess: Read-only, need database schema
2. Load doc-lookup for database schema:

   python .claude/skills/doc-lookup/scripts/section_search.py \
     --query "database-schema" \
     --paths docs/agents/backend-development.md \
     --top 1
   

3. Return schema information from section
4. Token cost: ~800 tokens (just the schema section)

Example 4: Complex Task → Escalate

User request: "Add support for background execution with progress callbacks"

Router workflow:

1. Assess: Complex (affects CLI, database, possibly execution engine)
2. Decision: This requires multi-file changes and architecture decisions
3. Escalate: Task(dipeo-backend, "Add background execution with progress callbacks")
4. Agent can then load specific sections as needed during implementation

Escalation Paths

To dipeo-package-maintainer

When task involves:

• Execution handler logic
• Service architecture (EventBus, ServiceRegistry)
• Domain models
• LLM infrastructure

To dipeo-codegen-pipeline

When task involves:

• GraphQL schema changes
• Generated type issues
• TypeScript model specs

Quick Reference: Files You Can Work With

Directly editable (if task is simple):

• apps/server/src/dipeo_server/cli/parser.py - CLI argument parsing
• apps/server/src/dipeo_server/api/router.py - API routes
• apps/server/main.py - Server initialization
• apps/server/src/dipeo_server/infra/db_schema.py - Database schema

Requires agent (if complex):

• Multiple files across CLI, API, and database
• New feature implementation
• Architecture changes

Testing the Router + Doc-Lookup Pattern

This test skill demonstrates:

1. ✅ Thin router: ~100 lines vs. 600+ lines of full docs
2. ✅ Anchor references: Stable links to specific sections
3. ✅ Decision criteria: Clear guidelines for skill vs. agent
4. ✅ Progressive disclosure: Load only needed sections via doc-lookup
5. ✅ Token efficiency: ~1,500 tokens vs. 15,000 with auto-injection

Token Savings Analysis

Before (auto-injection via PreToolUse hook):

• Backend agent invocation: 15,000 tokens automatic
• Total: 15,000 tokens (all-or-nothing)

After (router + doc-lookup):

• Router skill load: ~500 tokens
• Doc-lookup single section: ~500-1,000 tokens
• Total: ~1,000-1,500 tokens (on-demand)
• Savings: ~90% reduction for focused tasks

Version History

• v1.0.0 (2025-10-19): Initial test implementation demonstrating thin router pattern