Dev Agent - Engineering Assistant AI

The Dev Agent is an AI-powered engineering assistant that helps developers navigate the Olympus Cloud codebase, understand architecture, debug issues, and find documentation.

Overview

Attribute	Value
Agent Name	Dev Agent
Primary Users	NebusAI Engineers, Partner Developers
Model Tiers	T3-T5 (Gemini 3 Flash → Claude Sonnet 4.5)
Knowledge Base	`dev-kb`
Availability	Internal only (IDE + Slack + CLI)

┌─────────────────────────────────────────────────────────────────┐
│  DEV AGENT ARCHITECTURE                                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  DEVELOPER                  DEV AGENT                           │
│  ─────────────────────────────────────────────────────────────  │
│                                                                  │
│  ┌─────────┐              ┌─────────────────┐                  │
│  │ VS Code │──────────────│                 │                  │
│  │ Extension│   Query     │   ACP Router    │                  │
│  └─────────┘              │   (T3-T5)       │                  │
│                           │                 │                  │
│  ┌─────────┐              │   ┌──────────┐  │    ┌──────────┐ │
│  │ Slack   │──────────────│   │ LangGraph│  │────│ dev-kb   │ │
│  │ Bot     │              │   │ Agent    │  │    │ Vectorize│ │
│  └─────────┘              │   └──────────┘  │    └──────────┘ │
│                           │                 │                  │
│  ┌─────────┐              │   ┌──────────┐  │    ┌──────────┐ │
│  │ CLI     │──────────────│   │ Tools    │  │────│ Codebase │ │
│  │ (claude)│              │   └──────────┘  │    │ Search   │ │
│  └─────────┘              └─────────────────┘    └──────────┘ │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Capabilities

Code Understanding

Capability	Description	Example Query
Architecture Explanation	Explain system design	"How does the payment flow work?"
Code Search	Find relevant code	"Where is order validation handled?"
Function Explanation	Explain what code does	"What does process_payment do?"
Dependency Tracing	Track data flow	"What calls the inventory service?"

Debugging Assistance

Capability	Description	Example Query
Error Analysis	Explain errors	"What causes this Spanner error?"
Log Interpretation	Parse log messages	"What does this trace mean?"
Stack Trace Analysis	Decode stack traces	"Explain this panic trace"
Performance Issues	Identify bottlenecks	"Why is this query slow?"

Documentation Search

Capability	Description	Example Query
API Reference	Find API docs	"How do I authenticate?"
Guide Search	Find how-to guides	"How to add a new endpoint?"
Architecture Docs	Find design docs	"Where's the tenancy design?"
Runbook Search	Find operational docs	"What's the incident process?"

Code Generation

Capability	Description	Example Query
Boilerplate	Generate scaffolding	"Create a new Rust service"
Tests	Generate test cases	"Write tests for this function"
Documentation	Generate docs	"Document this module"
Migrations	Database changes	"Create migration for this schema"

Model Tier Routing

Dev Agent uses intelligent routing based on query complexity:

Query Type	Tier	Model	Cost	Latency
Simple lookup	T3	Gemini 3 Flash	$0.50/M	200ms
Code explanation	T4	Claude Haiku 4.5	$1.00/M	400ms
Complex analysis	T5	Claude Sonnet 4.5	$3.00/M	800ms
Architecture design	T5	Claude Sonnet 4.5	$3.00/M	1200ms

Routing Logic

def route_dev_query(query: str, context: dict) -> ModelTier:
    # Simple lookups
    if is_api_lookup(query) or is_config_question(query):
        return Tier.T3

    # Code explanation with context
    if has_code_snippet(context) and is_explanation_request(query):
        return Tier.T4

    # Complex multi-file analysis
    if requires_cross_file_analysis(query):
        return Tier.T5

    # Architecture and design questions
    if is_architecture_question(query):
        return Tier.T5

    # Default to T4 for balanced quality/cost
    return Tier.T4

Knowledge Base (dev-kb)

Indexed Content

Source	Type	Update Frequency
olympus-docs	API reference, guides	Real-time
Architecture docs	Design documents	On commit
ADRs	Architecture decisions	On commit
Runbooks	Operational guides	On commit
Code comments	In-code documentation	Daily
README files	Project documentation	On commit

Knowledge Domains

┌─────────────────────────────────────────────────────────────────┐
│  DEV-KB KNOWLEDGE DOMAINS                                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  RUST SERVICES                        FLUTTER SHELLS            │
│  ─────────────────────               ─────────────────────      │
│  • Auth Service                      • Staff Shell               │
│  • Platform Service                  • Customer Shell            │
│  • Commerce Service                  • Kiosk Shell               │
│  • Data models & migrations          • Platform Portal           │
│                                      • Cockpit                   │
│  GO SERVICES                                                     │
│  ─────────────────────               INFRASTRUCTURE              │
│  • API Gateway                       ─────────────────────       │
│  • Rate limiting                     • Terraform configs         │
│  • Authentication                    • Cloud Run deployment      │
│  • WebSocket handling                • Cloudflare Workers        │
│                                      • OlympusEdge               │
│  PYTHON SERVICES                                                 │
│  ─────────────────────               AI/ML                       │
│  • AI/ML pipelines                   ─────────────────────       │
│  • LangGraph agents                  • ACP Router                │
│  • Embeddings service                • Model configs             │
│  • Vision AI                         • RAG pipelines             │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Embedding Configuration

Parameter	Value
Model	`@cf/baai/bge-base-en-v1.5`
Chunk Size	512 tokens
Chunk Overlap	50 tokens
Similarity Threshold	0.75
Top-K Results	10

Tools

The Dev Agent has access to specialized tools:

Code Search Tools

Tool	Description	Parameters
`search_codebase`	Semantic code search	`query`, `language`, `path_filter`
`find_definition`	Find symbol definition	`symbol`, `scope`
`find_references`	Find symbol usages	`symbol`, `include_tests`
`get_file_content`	Read file contents	`path`, `line_start`, `line_end`

Documentation Tools

Tool	Description	Parameters
`search_docs`	Search documentation	`query`, `doc_type`
`get_api_spec`	Get OpenAPI spec	`service`, `endpoint`
`get_adr`	Get architecture decision	`adr_number`
`get_runbook`	Get operational runbook	`topic`

Analysis Tools

Tool	Description	Parameters
`analyze_error`	Parse error message	`error_text`, `context`
`trace_dependency`	Track call chain	`function`, `depth`
`explain_code`	Explain code block	`code`, `language`
`suggest_fix`	Suggest bug fix	`error`, `context`

Example Interactions

Architecture Question

Developer: "How does multi-tenancy work in the platform service?"

Dev Agent:

Multi-tenancy in the Platform Service is implemented using these key patterns:

Tenant Isolation (platform_service/src/tenancy/mod.rs)

Each request includes tenant_id in JWT claims

Middleware extracts and validates tenant context

All queries are scoped to tenant via row-level security

Data Model (platform_service/src/models/tenant.rs:45)

Tenant struct with id, slug, settings, subscription_tier

Cross-Tenant Prevention

Spanner interleaved tables enforce parent-child relationships

API Gateway validates tenant access before routing

No cross-tenant queries possible without explicit override

See: docs/architecture/multi-tenancy.md for full design.

Debugging Help

Developer: "I'm getting 'DEADLINE_EXCEEDED' errors from Spanner. What should I check?"

Dev Agent:

DEADLINE_EXCEEDED from Spanner typically means queries are timing out. Check these areas:

1. **Query Performance** (Most Common)
   - Missing indexes on filtered columns
   - Full table scans on large tables
   - Complex JOINs without proper key ordering

   Run: `EXPLAIN ANALYZE` on your query in Spanner console

2. **Transaction Scope** (commerce_service/src/orders/mod.rs:234)
   - Transactions holding locks too long
   - Read-write transactions when read-only would work

   Fix: Use read-only transactions for queries:
   ```rust
   let ro_txn = client.read_only_transaction().await?;

Connection Pool
- Pool exhaustion under load
- Check: SPANNER_MAX_SESSIONS env var (default: 100)
Network/Region
- Cross-region latency
- Check Cloud Run region matches Spanner region

For detailed troubleshooting: docs/operations/runbooks/database.md

### Code Generation

**Developer:** "Generate a new API endpoint for fetching user preferences"

**Dev Agent:**

Here's the endpoint following our patterns:

1. Add route (api_gateway/src/routes/users.rs)

func (r *UserRoutes) RegisterRoutes(router *gin.RouterGroup) {
    users := router.Group("/users")
    {
        users.GET("/:id/preferences", r.GetPreferences)
    }
}

func (r *UserRoutes) GetPreferences(c *gin.Context) {
    userID := c.Param("id")
    tenantID := middleware.GetTenantID(c)

    prefs, err := r.userService.GetPreferences(c, tenantID, userID)
    if err != nil {
        response.Error(c, err)
        return
    }

    response.Success(c, prefs)
}

2. Add service method (platform_service/src/users/preferences.rs)

pub async fn get_preferences(
    &self,
    tenant_id: Uuid,
    user_id: Uuid,
) -> Result<UserPreferences, ServiceError> {
    let prefs = sqlx::query_as!(
        UserPreferences,
        r#"SELECT * FROM user_preferences
           WHERE tenant_id = $1 AND user_id = $2"#,
        tenant_id,
        user_id
    )
    .fetch_optional(&self.pool)
    .await?
    .ok_or(ServiceError::NotFound)?;

    Ok(prefs)
}

3. Add test (platform_service/tests/users/preferences_test.rs)

#[tokio::test]
async fn test_get_preferences() {
    let ctx = TestContext::new().await;
    let prefs = ctx.service.get_preferences(
        ctx.tenant_id,
        ctx.user_id
    ).await.unwrap();

    assert_eq!(prefs.user_id, ctx.user_id);
}

Follow the PR checklist in docs/development/pr-checklist.md

### API Reference Lookup

**Developer:** "What's the request format for creating an order?"

**Dev Agent:**

POST /api/v1/orders

Request Body:

{
  "location_id": "uuid",
  "order_type": "DINE_IN | TAKEOUT | DELIVERY",
  "table_id": "uuid (optional, for DINE_IN)",
  "customer_id": "uuid (optional)",
  "items": [
    {
      "menu_item_id": "uuid",
      "quantity": 1,
      "modifiers": [
        {
          "modifier_id": "uuid",
          "quantity": 1
        }
      ],
      "special_instructions": "string"
    }
  ],
  "notes": "string (optional)"
}

Response (201 Created):

{
  "id": "uuid",
  "order_number": "A-0042",
  "status": "PENDING",
  "items": [...],
  "subtotal": 24.99,
  "tax": 2.25,
  "total": 27.24,
  "created_at": "2026-01-23T12:00:00Z"
}

Authentication: Bearer token with orders:write scope

Full spec: docs/api/commerce/orders.yaml

---

## Access Methods

### VS Code Extension (Olympus Lens)

1. Install "Olympus Lens" from VS Code marketplace
2. Authenticate with NebusAI SSO
3. Use keyboard shortcut: `Cmd+Shift+D` (Mac) / `Ctrl+Shift+D` (Windows)
4. Or right-click → "Ask Dev Agent"

### Slack Integration

1. Direct message `@dev-agent` in Slack
2. Or mention in any channel: `@dev-agent how do I...`
3. Threads maintained for context

### CLI (Claude Code)

```bash
# In any Olympus repo directory
claude "How does the payment service handle refunds?"

# With file context
claude "Explain this code" --file src/payments/refund.rs

Configuration

Environment Variables

Variable	Description	Default
`DEV_AGENT_MODEL_TIER`	Default model tier	`T4`
`DEV_AGENT_MAX_TOKENS`	Max response tokens	`4096`
`DEV_AGENT_TEMPERATURE`	Response creativity	`0.2`
`DEV_AGENT_KB_THRESHOLD`	RAG similarity threshold	`0.75`

User Preferences

# ~/.olympus/dev-agent.yaml
preferences:
  default_language: rust
  include_tests: true
  verbose_explanations: false
  preferred_examples: code_first

Best Practices

Effective Queries

tip

Be specific in your queries and include file paths, service names, or error messages. The Dev Agent performs best when it can narrow its search to a specific domain rather than searching the entire codebase.

Good:

"How does order validation work in commerce service?"
"What's the pattern for adding a new gRPC endpoint?"
"Explain the LangGraph agent for voice ordering"

Less Effective:

"Help me with code" (too vague)
"Fix my bug" (no context)
"Write everything for me" (scope too large)

Providing Context

Include error messages - Full stack trace helps
Mention file paths - "In src/orders/validation.rs..."
Describe what you tried - "I attempted X but got Y"
Specify language/service - "In the Go gateway..."

When to Escalate

warning

The Dev Agent is not a substitute for human judgment on security-sensitive decisions, breaking API changes, production incidents, or architecture changes. Always escalate these to the appropriate human engineer.

Use human engineers when:

Security-sensitive decisions
Breaking API changes
Production incidents
Architecture changes

Monitoring & Metrics

Usage Metrics

Metric	Description
`dev_agent_queries_total`	Total queries
`dev_agent_latency_p99`	99th percentile latency
`dev_agent_tier_usage`	Queries by model tier
`dev_agent_satisfaction`	User feedback scores

Quality Metrics

Metric	Target
Accuracy	>90% helpful responses
Latency (p50)	<500ms
Latency (p99)	<2000ms
KB Hit Rate	>80% queries find relevant docs

ACP Router - Model routing system
LangGraph Agents - Agent orchestration
RAG Knowledge Base - Vector search
AI Safety - Guardrails and safety

Overview​

Capabilities​

Code Understanding​

Debugging Assistance​

Documentation Search​

Code Generation​

Model Tier Routing​

Routing Logic​

Knowledge Base (dev-kb)​

Indexed Content​

Knowledge Domains​

Embedding Configuration​

Tools​

Code Search Tools​

Documentation Tools​

Analysis Tools​

Example Interactions​

Architecture Question​

Debugging Help​

Configuration​

Environment Variables​

User Preferences​

Best Practices​

Effective Queries​

Providing Context​

When to Escalate​

Monitoring & Metrics​

Usage Metrics​

Quality Metrics​

Related Documentation​