RUSVEL

The Solo Builder’s AI-Powered Virtual Agency One binary, one human, infinite leverage.

RUSVEL is an AI-powered virtual agency built with Rust + SvelteKit. It gives a single person the leverage of an entire agency through 14 autonomous departments, each powered by AI agents.

Quick Start

git clone https://github.com/mbaneshi/rusvel
cd rusvel
cargo run
# Open http://localhost:3000

What’s Inside

• God Agent — Your AI companion that knows your identity, products, and mission
• 14 Departments — Forge, Code, Content, Harvest, GTM, Finance, Product, Growth, Distribution, Legal, Support, Infra, Flow, Messaging
• Knowledge/RAG — fastembed + lancedb for semantic search over your documents
• Self-Improvement — The app can analyze and improve its own codebase
• 55 workspace members — Hexagonal architecture; 22 port traits in rusvel-core/src/ports.rs (15 primary + 5 *Store + ChannelPort + BrowserPort + RusvelBasePort)
• ~645 tests (workspace sum); full cargo test passes in a normal dev environment

See Repository status for canonical metrics and links to docs/status/current-state.md on GitHub.

Architecture

God Agent (Chat — full authority + visibility)
├── Forge      — Mission planning, goals, reviews
├── Code       — Full Claude Code capabilities
├── Content    — Draft, adapt, publish across platforms
├── Harvest    — Find opportunities, score, propose
├── GTM        — CRM, outreach, invoicing, deals
├── Finance    — Ledger, runway, tax estimation
├── Product    — Roadmap, pricing, feedback
├── Growth     — Funnel, cohorts, KPIs
├── Distribution — SEO, marketplace, affiliates
├── Legal      — Contracts, compliance, IP
├── Support    — Tickets, knowledge base, NPS
├── Infra      — Deploy, monitor, incidents
├── Flow       — DAG workflow engine
└── Messaging  — Notification channels

Each department is autonomous — own config, own chat, own agents, own events. God sees everything and can orchestrate any combination.

Stack

• Rust edition 2024, SQLite WAL, Axum, Clap 4, tokio
• SvelteKit 5, Tailwind CSS 4
• LLM: Claude CLI (Max subscription), Ollama, OpenAI, Claude API
• RAG: fastembed (local ONNX embeddings) + lancedb (vector search)

Getting Started

Get RUSVEL running in under 5 minutes.

1. Installation — Build from source or use Docker
2. First Run — Start the server and explore the dashboard
3. First Mission — Create a session and generate your first daily plan

Installation

Prerequisites

RUSVEL is a Rust + SvelteKit application. You need the following installed:

Install Rust

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Install Node.js + pnpm

Use your preferred method (nvm, fnm, or direct install):

# With nvm
nvm install 22
nvm use 22

# Install pnpm
corepack enable
corepack prepare pnpm@9.15.4 --activate
# Or: npm install -g pnpm

Install Ollama (optional)

Ollama provides free local LLM inference. RUSVEL auto-detects it on first run.

# macOS
brew install ollama

# Linux
curl -fsSL https://ollama.com/install.sh | sh

# Start the service
ollama serve

If you skip Ollama, you can configure Claude API or OpenAI keys instead.

Clone and Build

git clone https://github.com/mbaneshi/rusvel.git
cd rusvel
cargo build

The workspace has 50 members (see Repository status). First build takes a few minutes; subsequent builds are incremental.

Build the Frontend

cd frontend
pnpm install
pnpm build

The built frontend is served by the Rust binary at runtime. During development you can run pnpm dev for hot-reload on port 5173.

Verify the Installation

Run the full test suite to confirm everything works:

cargo test

You should see on the order of ~399 tests passing (exact count changes over time). Use cargo test exit code 0 as the gate.

test result: ok. … passed; 0 failed

Test individual crates

cargo test -p rusvel-core       # Core domain types and port traits
cargo test -p rusvel-db         # SQLite stores (41 tests)
cargo test -p forge-engine      # Agent orchestration (15 tests)
cargo test -p content-engine    # Content creation (7 tests)
cargo test -p harvest-engine    # Opportunity discovery (12 tests)

Next Steps

Once installed, proceed to First Run to launch RUSVEL for the first time.

First Run

Start the Server

From the project root, run:

cargo run

RUSVEL starts the API server on port 3000. You will see:

RUSVEL API listening on 0.0.0.0:3000

Open your browser to http://localhost:3000.

Create Your First Session

Sessions are RUSVEL’s workspaces. Everything – goals, events, conversations, agent runs – lives inside a session.

Via the Web UI

The frontend guides you through creating a session on first load. The onboarding checklist tracks your progress:

1. Create a session
2. Add a goal
3. Generate a daily plan
4. Chat with a department
5. Create an agent

Via the CLI

# Create a session
cargo run -- session create "My Startup"

# Output:
# Session created: My Startup
#   ID: a1b2c3d4-...  (set as active session)

The session ID is saved to ~/.rusvel/active_session and used by all subsequent CLI commands.

List and Switch Sessions

# List all sessions
cargo run -- session list

# Switch active session
cargo run -- session switch <session-id>

LLM Configuration

RUSVEL supports four LLM providers. On first run, it auto-detects Ollama if running locally.

You can configure the default model per department in the Settings page or via the API:

curl -X PUT http://localhost:3000/api/config \
  -H "Content-Type: application/json" \
  -d '{"model": "claude-sonnet-4-20250514"}'

The MCP Server

RUSVEL can also run as an MCP (Model Context Protocol) server for integration with Claude Desktop or other MCP clients:

cargo run -- --mcp

This starts a stdio JSON-RPC server instead of the web server.

Directory Structure

After first run, RUSVEL creates:

~/.rusvel/
├── active_session    # UUID of the current session
├── config.toml       # Global configuration
└── rusvel.db         # SQLite database (WAL mode)

Next Steps

With your session created, head to First Mission to set goals and generate your first daily plan.

First Mission

What is a Mission?

A mission is RUSVEL’s daily planning system, powered by the Forge engine. It reads your active goals, checks the state of all departments, and generates a prioritized task list for the day.

The workflow is: set goals > generate daily plan > execute > review progress.

Set Goals

Goals are high-level objectives with a timeframe. They drive what the daily plan prioritizes.

Via the Web UI

1. Navigate to the Forge department from the sidebar
2. Click the “Set new goal” quick action
3. The Forge agent will ask for context and help you define the goal

Via the CLI

# Add a goal with default month timeframe
cargo run -- forge mission goal add "Launch MVP"

# Add a goal with specific timeframe and description
cargo run -- forge mission goal add "Get 10 beta users" \
  --description "Recruit beta testers from HN and Reddit" \
  --timeframe week

# List all goals
cargo run -- forge mission goals

Output from goals:

ID                                      TITLE                      TIMEFRAME   STATUS      PROGRESS
----------------------------------------------------------------------------------------------------
a1b2c3d4-...                            Launch MVP                 Month       Active      0%
e5f6g7h8-...                            Get 10 beta users          Week        Active      0%

Goal Timeframes

Generate a Daily Plan

The daily plan is an AI-generated prioritized task list based on your goals and current state.

Via the Web UI

1. Open the Forge department
2. Click “Daily plan” quick action
3. The agent generates tasks with priorities and focus areas

Via the CLI

cargo run -- forge mission today

Output:

Generating daily plan...

Daily Plan -- 2026-03-23
==================================================
  1. [High] Finalize API endpoint documentation
  2. [High] Write integration tests for auth flow
  3. [Medium] Draft landing page copy
  4. [Medium] Set up CI pipeline
  5. [Low] Review dependency updates

Focus areas:
  - Ship the authentication feature
  - Prepare for beta launch

Notes: Focus on high-priority items first. The auth flow is blocking beta signups.

Review Progress

Periodic reviews summarize what was accomplished and identify blockers.

Via the CLI

# Weekly review (default)
cargo run -- forge mission review

# Monthly review
cargo run -- forge mission review --period month

# Quarterly review
cargo run -- forge mission review --period quarter

Output:

Generating Week review...

Review (Week)
==================================================

Accomplishments:
  - Completed API authentication flow
  - Deployed staging environment
  - Drafted 3 blog posts

Blockers:
  - Waiting on SSL certificate for production
  - Need feedback on pricing page design

Insights:
  - Code velocity increased 40% after adding test automation
  - Content pipeline is 2 days behind schedule

Next actions:
  - Follow up on SSL certificate
  - Schedule design review for pricing page

Explore Other Departments

With your mission set, explore the 14 department apps. Each has its own AI agent specialized for that domain:

• Code – implement features, analyze code, run tests
• Content – write blog posts, adapt for social platforms
• Harvest – find freelance opportunities, draft proposals
• GTM – manage CRM, send outreach, track deals

See the full list in Departments.

Concepts

Core building blocks of the RUSVEL system.

• Sessions — Workspace contexts that scope all data
• Departments — 14 autonomous business functions
• Agents — AI workers that execute tasks
• Skills & Rules — Reusable actions and behavioral constraints
• Workflows — Multi-step orchestrated processes
• Domain Concepts Map — How concepts relate to each other

Sessions

What Are Sessions?

Sessions are RUSVEL’s top-level organizational unit. Think of them as workspaces or projects. All data in RUSVEL – goals, events, conversations, agent runs, content items, opportunities – is scoped to a session.

You always have one active session. All CLI commands and API calls operate on the active session by default.

Session Kinds

Each session has a kind that hints at its purpose:

The session kind is informational. It does not restrict which departments or features you can use.

Creating Sessions

CLI

cargo run -- session create "My Startup"

This creates a new session and sets it as active. The session ID is stored in ~/.rusvel/active_session.

API

curl -X POST http://localhost:3000/api/sessions \
  -H "Content-Type: application/json" \
  -d '{"name": "My Startup", "kind": "Project"}'

Listing Sessions

CLI

cargo run -- session list

Output shows all sessions with the active one marked:

ID                                      NAME                  KIND        UPDATED
------------------------------------------------------------------------------------------
a1b2c3d4-e5f6-...                       My Startup            Project     2026-03-23 14:30 *
b2c3d4e5-f6g7-...                       Blog Series           Content..   2026-03-22 09:15

API

curl http://localhost:3000/api/sessions

Switching Sessions

CLI

cargo run -- session switch <session-id>

API

Load a specific session by ID:

curl http://localhost:3000/api/sessions/<session-id>

Data Stored Per Session

Each session contains:

• Goals – strategic objectives with timeframes and progress tracking
• Events – an immutable, append-only log of everything that happens
• Conversations – chat history with each department agent
• Agent runs – records of every agent execution (input, output, tokens used)
• Content items – blog posts, tweets, proposals in various states
• Opportunities – leads, gigs, and deals in the pipeline
• Contacts – CRM entries tied to the session
• Tasks – generated from daily plans, linked to goals

Session Configuration

Sessions can override global configuration. The config cascade is:

Global config  →  Department config  →  Session config

This lets you use different LLM models, approval policies, or tool permissions per session.

Departments

Overview

RUSVEL organizes work into 14 department apps (dept-* crates), each with its own specialized AI agent surface. Together they form a virtual agency that a solo founder can command from a single interface.

Departments follow the DepartmentApp pattern (ADR-014). Each department lives in its own dept-* crate that implements the DepartmentApp trait, declares its capabilities via a DepartmentManifest, and registers with the host at boot. Adding a new department means adding a new dept-* crate – zero changes to rusvel-core.

The DepartmentApp Trait

Every department crate implements this contract:

#![allow(unused)]
fn main() {
pub trait DepartmentApp: Send + Sync {
    fn manifest(&self) -> DepartmentManifest;
    fn register(&self, ctx: &mut RegistrationContext) -> Result<()>;
}
}

The DepartmentManifest declares the department’s ID, name, icon, color, system prompt, capabilities, tabs, quick actions, routes, tools, and CLI commands. The host collects all manifests to generate the DepartmentRegistry, API routes, CLI subcommands, and frontend navigation.

The 14 dept-* Crates

Department UI Structure

Each department page has two panels:

Chat Panel (right side)

The AI agent for this department. Send messages, get responses, use quick actions. The agent has access to department-specific tools via the ScopedToolRegistry – each department only sees tools relevant to its domain.

Department Panel (left side)

A tabbed panel with up to 9 tabs depending on the department:

The God Agent

The main Chat page (not tied to any department) runs the God Agent. This agent has full authority and visibility over all departments. Use it for cross-cutting tasks:

• “What is the status across all departments?”
• “Move the proposal from Harvest to Content for editing”
• “Generate a weekly summary of all activity”

Quick Actions

Each department has predefined quick-action buttons that send a prompt to the agent with one click. These are declared in the department’s DepartmentManifest and can be customized.

Department Configuration

Each department inherits global config and can override:

• Model – which LLM to use for this department’s agent
• Effort – low, medium, or high (controls response depth)
• Permission mode – what tools the agent can use
• Working directories – for code-operating departments

Configure via the Settings page or the API:

curl -X PUT http://localhost:3000/api/dept/code/config \
  -H "Content-Type: application/json" \
  -d '{"model": "claude-sonnet-4-20250514", "effort": "high"}'

Agents

What Are Agents?

Agents are AI personas with specific roles, instructions, tools, and budgets. Each department has a default agent, and you can create custom agents for specialized tasks.

Agents are powered by the AgentRuntime (in rusvel-agent), which wraps LLM access, tool execution, streaming, and memory into a single orchestration layer.

Agent Profile Structure

Every agent has:

name            — Display name (e.g., "rust-engine")
role            — One-line role description
instructions    — System prompt guiding behavior
model           — Which LLM to use (provider + model name)
allowed_tools   — List of tools the agent can invoke
capabilities    — What the agent can do (code_analysis, content_creation, etc.)
budget_limit    — Optional spending cap per run
department      — Which department this agent belongs to

Seeded Agents

RUSVEL ships with 5 pre-configured agents:

Creating Custom Agents

Via the Web UI

1. Navigate to any department
2. Open the Agents tab in the department panel
3. Click “Add Agent”
4. Fill in name, role, instructions, and model
5. Save

Via the API

curl -X POST http://localhost:3000/api/agents \
  -H "Content-Type: application/json" \
  -d '{
    "name": "seo-analyst",
    "role": "SEO and keyword research specialist",
    "instructions": "You analyze websites for SEO performance...",
    "model": "claude-sonnet-4-20250514",
    "department": "distro",
    "capabilities": ["seo"]
  }'

Managing Agents

# List all agents
curl http://localhost:3000/api/agents

# Get a specific agent
curl http://localhost:3000/api/agents/<id>

# Update an agent
curl -X PUT http://localhost:3000/api/agents/<id> \
  -H "Content-Type: application/json" \
  -d '{"instructions": "Updated instructions..."}'

# Delete an agent
curl -X DELETE http://localhost:3000/api/agents/<id>

Model Selection and ModelTier Routing

Agents can use any configured LLM provider:

The model is set per agent and falls back to the department default, then the global default.

ModelTier routing automatically classifies models into three tiers – Haiku (fast/cheap), Sonnet (balanced), Opus (powerful/expensive). The CostTracker in MetricStore logs token usage and costs per tier, enabling budget-aware model selection.

Tools and ScopedToolRegistry

Agents have access to 22+ tools:

• 10 built-in tools: read_file, write_file, edit_file, glob, grep, bash, git_status, git_diff, git_log, and tool_search (meta-tool)
• 12 engine tools: harvest (5: scan, score, propose, list, pipeline), content (5: draft, adapt, publish, list, approve), code (2: analyze, search)

The ScopedToolRegistry filters tools per department – the Content department sees content tools, the Code department sees code tools. This prevents tool overload and keeps agents focused.

Deferred tool loading via the tool_search meta-tool saves ~85% of tool-description tokens. Instead of loading all tool schemas upfront, agents discover tools on-demand by searching for capabilities they need.

Agent Budgets

Set a budget_limit to cap how much an agent can spend per run. This is useful for expensive operations like long code generation sessions.

When the budget is exceeded, the agent pauses and requests approval to continue.

How Agents Execute

When you chat with a department, here is what happens:

1. Your message goes to the department’s agent
2. The AgentRuntime loads the system prompt (department prompt + active rules via load_rules_for_engine())
3. The ScopedToolRegistry provides department-specific tools
4. The LLM generates a response via run_streaming(), emitting AgentEvents (text chunks, tool calls, tool results)
5. Tool calls are executed and results fed back to the LLM in a tool-use loop
6. LlmStreamEvent provides character-by-character SSE streaming to the frontend
7. An event is logged with tokens used and tools called

Engines never call the LLM directly (ADR-009). They always go through the AgentPort, which handles prompt construction, tool routing, retries, and memory injection.

Frontend Components

The chat interface includes:

• ToolCallCard – renders tool invocations inline in the chat
• ApprovalCard – shows approval requests for sensitive operations
• ApprovalQueue – sidebar badge showing pending approvals across all departments

Skills & Rules

Skills

Skills are reusable prompt templates with variable placeholders. They let you save common prompts and re-invoke them with different inputs.

Skill Structure

name        — Display name (e.g., "Write Blog Post")
template    — Prompt text with {variable} placeholders
department  — Which department this skill belongs to
variables   — List of variable names used in the template

Example Skill

Name: Draft Technical Blog Post
Template: |
  Write a technical blog post about {topic}.
  Target audience: {audience}.
  Length: {length} words.
  Include code examples in {language}.
  Tone: educational but practical.

When invoked, you fill in {topic}, {audience}, {length}, and {language}.

Managing Skills

Via the Web UI

1. Navigate to a department
2. Open the Skills tab in the department panel
3. Click “Add Skill”
4. Write the template with {variable} placeholders
5. Save

Via the API

# Create a skill
curl -X POST http://localhost:3000/api/skills \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Proposal Template",
    "template": "Write a proposal for {gig_title} on {platform}...",
    "department": "harvest"
  }'

# List all skills
curl http://localhost:3000/api/skills

# Update a skill
curl -X PUT http://localhost:3000/api/skills/<id> \
  -H "Content-Type: application/json" \
  -d '{"template": "Updated template..."}'

# Delete a skill
curl -X DELETE http://localhost:3000/api/skills/<id>

Rules

Rules are constraints injected into agent system prompts. They enforce policies, coding standards, or business logic across all interactions with a department.

Rule Structure

name        — Display name (e.g., "Hexagonal Architecture")
content     — The constraint text injected into system prompts
department  — Which department this rule applies to
enabled     — Whether this rule is currently active

Seeded Rules

RUSVEL ships with 3 pre-configured rules:

How Rules Work

When a department’s agent processes a message:

1. All enabled rules for that department are loaded
2. Rule content is appended to the department system prompt
3. The combined prompt guides the agent’s behavior

This means rules are “always on” constraints, not one-time instructions.

Managing Rules

Via the Web UI

1. Navigate to a department
2. Open the Rules tab
3. Toggle rules on/off with the enable switch
4. Add new rules with “Add Rule”

Via the API

# Create a rule
curl -X POST http://localhost:3000/api/rules \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Always Write Tests",
    "content": "Every code change must include corresponding unit tests.",
    "department": "code",
    "enabled": true
  }'

# List all rules
curl http://localhost:3000/api/rules

# Toggle a rule off
curl -X PUT http://localhost:3000/api/rules/<id> \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'

Skills vs Rules

Workflows

What Are Workflows?

Workflows chain multiple agents together to accomplish multi-step tasks. Instead of manually prompting one agent at a time, you define a flow that routes work between agents automatically.

Workflow Patterns

RUSVEL supports four execution patterns:

Sequential

Agents run one after another. Each agent’s output feeds into the next as input.

Agent A → Agent B → Agent C → Result

Example: Research a topic (Agent A) > write a blog post (Agent B) > adapt for Twitter (Agent C).

Parallel

Multiple agents run simultaneously. Results are collected and merged.

Agent A ─┐
Agent B ─┤→ Merge → Result
Agent C ─┘

Example: Analyze code quality (Agent A), run security scan (Agent B), check dependencies (Agent C) – all at once.

Loop

An agent runs repeatedly until a condition is met or a maximum iteration count is reached.

Agent A → Check → (repeat or done)

Example: Iterate on a draft until it meets quality criteria.

Graph

A directed acyclic graph of agents with conditional branching. The most flexible pattern.

Agent A → [if pass] → Agent B → Agent D
       → [if fail] → Agent C → Agent D

Example: Analyze an opportunity, route to different proposal strategies based on the score.

Creating Workflows

Via the Web UI

1. Navigate to a department that supports workflows (Forge, Code, GTM)
2. Open the Workflows tab (labeled “Flows”)
3. Click “Add Workflow”
4. Define the steps, agents, and pattern
5. Save

Via the API

# Create a workflow
curl -X POST http://localhost:3000/api/workflows \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Blog Pipeline",
    "department": "content",
    "pattern": "sequential",
    "steps": [
      {"agent": "content-writer", "prompt": "Research and outline: {topic}"},
      {"agent": "content-writer", "prompt": "Write full draft from outline"},
      {"agent": "content-writer", "prompt": "Adapt for Twitter thread"}
    ]
  }'

# List workflows
curl http://localhost:3000/api/workflows

# Get a specific workflow
curl http://localhost:3000/api/workflows/<id>

Running Workflows

Via the API

curl -X POST http://localhost:3000/api/workflows/<id>/run \
  -H "Content-Type: application/json" \
  -d '{"variables": {"topic": "Hexagonal Architecture in Rust"}}'

The workflow executes each step in order, passing context between agents. Results are streamed back as events.

Workflow Variables

Workflows accept variables at execution time. Use {variable_name} in step prompts:

{
  "steps": [
    {"prompt": "Analyze the {language} codebase in {directory}"},
    {"prompt": "Write tests for any uncovered functions"}
  ]
}

When running, provide the variables:

{"variables": {"language": "Rust", "directory": "crates/rusvel-core"}}

Managing Workflows

# Update a workflow
curl -X PUT http://localhost:3000/api/workflows/<id> \
  -H "Content-Type: application/json" \
  -d '{"name": "Updated Pipeline", "steps": [...]}'

# Delete a workflow
curl -X DELETE http://localhost:3000/api/workflows/<id>

RUSVEL Domain Concepts — How Everything Fits Together

The Mental Model

Everything in RUSVEL is scoped to a Department. Each department owns its agents, skills, rules, hooks, and MCP servers. When a user chats with a department, all these pieces compose into a single agent execution. Session is the work boundary that tracks cost, memory, goals, and events across departments. Events are the glue — hooks react to events, enabling cross-department automation without coupling.

The Hierarchy

Session                          ← your work context (project, lead, campaign)
 ├── has Goals                   ← what you're trying to achieve
 ├── has Budget                  ← spending limit across all departments
 ├── scopes Events              ← everything that happens is tagged to session
 ├── scopes Memory              ← what the system remembers, per session
 │
 └── talks to Departments ──────← the 14 organizational units
      │
      ├── owns Agents            ← personas (@security-reviewer)
      ├── owns Skills            ← prompt shortcuts (/research topic)
      ├── owns Rules             ← "always do X" injected into every chat
      ├── owns Hooks             ← "when X happens, do Y"
      ├── owns MCP Servers       ← external tool providers
      ├── owns Config            ← model, temperature, per-dept settings
      ├── owns Chat History      ← conversation per department
      │
      └── can trigger:
           ├── Workflow          ← simple: step1 → step2 → step3
           ├── Playbook          ← rich: Agent → Approval → Flow
           └── Flow              ← DAG: parallel branches, conditions

JSON Manifest Shape

{
  "session": {
    "id": "uuid",
    "kind": "project",
    "goals": ["Launch MVP by April"],
    "budget_limit_usd": 50.0,
    "departments": {
      "forge": {
        "agents": [
          { "name": "strategist", "role": "Plan daily missions", "model": "opus" }
        ],
        "skills": [
          { "name": "daily-brief", "template": "Generate executive brief for {{input}}" }
        ],
        "rules": [
          { "name": "concise", "content": "Keep responses under 200 words", "enabled": true }
        ],
        "hooks": [
          { "event": "forge.chat.completed", "type": "http", "action": "https://slack.com/webhook" }
        ],
        "mcp_servers": [
          { "name": "github", "type": "stdio", "command": "mcp-github" }
        ],
        "chat_history": "dept_msg_forge",
        "config": { "default_model": "sonnet", "temperature": 0.7 }
      },
      "content": { "...same shape..." },
      "harvest": { "...same shape..." }
    },
    "workflows": [
      { "name": "publish-pipeline", "steps": ["draft", "review", "publish"] }
    ],
    "playbooks": [
      {
        "name": "content-from-code",
        "steps": [
          { "action": "Agent", "persona": "code-analyst", "prompt": "Analyze {{input}}" },
          { "action": "Approval", "message": "Proceed with draft?" },
          { "action": "Agent", "persona": "writer", "prompt": "Write article from {{last_output}}" }
        ]
      }
    ],
    "flows": [
      {
        "name": "opportunity-pipeline",
        "nodes": ["scan", "score", "decide", "propose"],
        "connections": [
          { "scan": "score" },
          { "score": "decide" },
          { "decide[true]": "propose" },
          { "decide[false]": "archive" }
        ]
      }
    ]
  }
}

Visual Diagrams

System Overview

graph TB
    subgraph Session["SESSION (work context)"]
        Goals["Goals"]
        Budget["Budget"]
        Memory["Memory (FTS5)"]
        EventBus["Event Bus"]
    end

    subgraph Departments["DEPARTMENTS (14 units)"]
        subgraph Forge["Forge"]
            FA["Agents"]
            FS["Skills"]
            FR["Rules"]
            FH["Hooks"]
            FM["MCP Servers"]
            FC["Chat History"]
        end
        subgraph Content["Content"]
            CA["Agents"]
            CS["Skills"]
            CR["Rules"]
            CH["Hooks"]
        end
        subgraph Harvest["Harvest"]
            HA["Agents"]
            HS["Skills"]
            HR["Rules"]
            HH["Hooks"]
        end
        Other["+ 11 more departments"]
    end

    subgraph Orchestration["ORCHESTRATION (cross-department)"]
        Workflow["Workflow\n(sequential)"]
        Playbook["Playbook\n(Agent + Approval + Flow)"]
        Flow["Flow\n(DAG with branches)"]
    end

    Session --> Departments
    Departments --> Orchestration
    EventBus --> FH & CH & HH
    Forge & Content & Harvest --> EventBus
    Orchestration --> EventBus

Chat Request Flow

sequenceDiagram
    actor User
    participant API as Department API
    participant Config as Config Cascade
    participant Skill as Skill Resolver
    participant Agent as Agent Override
    participant Rules as Rule Loader
    participant RAG as Knowledge/RAG
    participant Runtime as AgentRuntime
    participant LLM as LLM Provider
    participant Hooks as Hook Dispatch
    participant Events as Event Bus

    User->>API: POST /api/dept/{id}/chat
    API->>Config: Load dept config (registry + stored + user)
    API->>API: Load conversation history

    alt message starts with /skill-name
        API->>Skill: resolve_skill(message)
        Skill-->>API: expanded template with {{input}}
    end

    alt message mentions @agent-name
        API->>Agent: lookup AgentProfile
        Agent-->>API: override system prompt + model
    end

    API->>Rules: load_rules_for_engine(dept_id)
    Rules-->>API: enabled rules appended to system prompt

    API->>RAG: embed query + vector search
    RAG-->>API: knowledge snippets injected

    API->>Runtime: create(AgentConfig) + run_streaming()

    loop Tool-use loop
        Runtime->>LLM: prompt + tools
        LLM-->>Runtime: text or tool_call
        Runtime-->>User: SSE: text_delta / tool_call
    end

    Runtime-->>API: Done (final text)
    API->>API: Store assistant message
    API->>Events: emit("{dept}.chat.completed")
    API->>Hooks: dispatch_hooks(event)

    par Hook execution (fire-and-forget)
        Hooks->>Hooks: command: sh -c "..."
        Hooks->>Hooks: http: POST webhook
        Hooks->>Hooks: prompt: claude -p "..."
    end

    API-->>User: SSE: run_completed

Entity Scoping

graph LR
    subgraph Global
        Sessions["Sessions"]
        Workflows["Workflows"]
        Playbooks["Playbooks"]
        Flows["Flows"]
    end

    subgraph "Scoped by metadata.engine"
        Agents["Agents"]
        Skills["Skills"]
        Rules["Rules"]
        Hooks["Hooks"]
        MCP["MCP Servers"]
        Chat["Chat History\n(dept_msg_{id})"]
        DeptConfig["Dept Config"]
    end

    subgraph "Scoped by session_id"
        Events["Events"]
        Memory["Memory"]
        Goals["Goals"]
        Runs["Runs"]
        Threads["Threads"]
    end

    Sessions --> Events & Memory & Goals & Runs
    Runs --> Threads

Three Orchestration Levels

graph TB
    subgraph Workflow["WORKFLOW (simple)"]
        direction LR
        W1["Step 1:\nagent + prompt"] --> W2["Step 2:\nagent + prompt"] --> W3["Step 3:\nagent + prompt"]
    end

    subgraph Playbook["PLAYBOOK (rich)"]
        direction LR
        P1["Agent Step:\ncode-analyst\nanalyzes repo"] --> P2["Approval Step:\nhuman reviews"] --> P3["Agent Step:\nwriter creates\narticle"] --> P4["Flow Step:\npublish pipeline"]
    end

    subgraph Flow["FLOW (DAG)"]
        direction TB
        F1["Scan\n(code node)"] --> F2["Score\n(agent node)"]
        F2 --> F3{"Score > 80?\n(condition)"}
        F3 -->|true| F4["Generate Proposal\n(agent node)"]
        F3 -->|false| F5["Archive\n(code node)"]
        F4 --> F6["Notify\n(code node)"]
        F5 --> F6
    end

    style Workflow fill:#e8f5e9
    style Playbook fill:#e3f2fd
    style Flow fill:#fce4ec

Event-Driven Automation

graph LR
    subgraph Triggers
        ChatDone["chat.completed"]
        Published["content.published"]
        Scanned["harvest.scan.completed"]
        JobDone["job.completed"]
    end

    subgraph Hooks
        H1["Hook: command\nsh -c 'notify.sh'"]
        H2["Hook: http\nPOST slack webhook"]
        H3["Hook: prompt\nclaude -p 'summarize'"]
    end

    subgraph Downstream
        Slack["Slack notification"]
        Flow2["Trigger a Flow"]
        Job["Enqueue a Job"]
    end

    ChatDone --> H1 & H2
    Published --> H2 & H3
    Scanned --> H1
    H1 --> Job
    H2 --> Slack
    H3 --> Flow2

Storage Map

When To Use What

The Key Insights

1. Department is the scoping boundary. Agents, skills, rules, hooks, MCP servers, and chat are all scoped by metadata.engine matching the department ID. Creating an agent in Content means it only appears in Content chat.

2. Session is the work boundary. Events, memory, goals, and budget are scoped to a session. You talk to any department within a session, but the session tracks total cost and context.

3. Events are the glue. Hooks react to events. Departments emit events. Jobs emit events. This is how automation chains together without departments knowing about each other.

4. Three orchestration levels exist for a reason:

   • Workflow — when you know the exact steps and just need sequential execution
   • Playbook — when you need human-in-the-loop approval or mixed AI/Flow steps
   • Flow — when you need conditional logic, parallel branches, or complex DAGs

5. Everything composes in the chat handler. A single chat request resolves skills, loads agents, injects rules, searches knowledge, runs the LLM, and dispatches hooks — all in one request/response cycle.

Departments

RUSVEL organizes business functions into 14 departments, each backed by a domain engine and an AI agent.

Wired (6): Forge, Code, Content, Harvest, GTM, Flow

Extended (8): Finance, Product, Growth, Distribution, Legal, Support, Infra, Messaging

Forge Department

Agent orchestration, goal planning, mission management, daily plans, reviews

Overview

The Forge Department is the meta-engine of RUSVEL. It orchestrates AI agents across all departments, manages strategic goals, generates prioritized daily mission plans, and produces periodic reviews. It also houses a catalog of 10 built-in agent personas that can be “hired” into any session, and a safety guard system (budget caps, concurrency slots, circuit breaker) to protect against runaway LLM spend. Forge is the department a solo builder uses to plan their day, track progress, and coordinate work across the entire virtual agency.

Engine (forge-engine)

• Crate: crates/forge-engine/src/lib.rs
• Lines: 483 (lib.rs) + 712 (mission.rs) + 264 (personas.rs) + 23 (events.rs) + submodules
• Status: Wired (real business logic)

Public API

Internal Structure

• PersonaManager (personas.rs) – Manages the catalog of 10 built-in agent personas. Supports lookup by name (case-insensitive), filtering by capability, and runtime additions.
• SafetyGuard (safety.rs) – Budget enforcement (soft ceiling with 80% warning threshold), concurrency slot limiter, and circuit breaker (opens after repeated failures).
• Mission module (mission.rs) – Goals, daily plans, reviews, and executive briefs. All LLM calls go through run_agent_with_mission_safety.
• Pipeline module (pipeline.rs) – Multi-step pipeline orchestration for forge workflows.
• Artifacts module (artifacts.rs) – Persistent artifact records for pipeline outputs.
• Events module (events.rs) – String constants for all emitted event kinds.

Department Wrapper (dept-forge)

• Crate: crates/dept-forge/src/lib.rs
• Lines: 276
• Manifest: crates/dept-forge/src/manifest.rs

The wrapper creates a ForgeEngine during registration, wires all 7 ports, and registers 5 agent tools. It is a thin delegation layer with no business logic.

Manifest Declaration

System Prompt

You are the Forge department of RUSVEL.

Focus: agent orchestration, goal planning, mission management, daily plans, reviews.

Capabilities

• planning
• orchestration

Quick Actions

Registered Tools

Personas

Skills

Rules

Jobs

No jobs are declared in the Forge manifest. Mission and review work is executed synchronously via run_agent_with_mission_safety.

Events

Produced

Consumed

The Forge department does not consume events from other departments. It is triggered by direct API/CLI calls and webhook-dispatched forge.pipeline.requested events (processed by the job worker in rusvel-app).

API Routes

CLI Commands

rusvel forge mission today       # Generate today's daily plan
rusvel forge mission goals       # List goals
rusvel forge mission goal <title> # Create a new goal
rusvel forge mission review      # Generate a periodic review (default: week)

Entity Auto-Discovery

Agents, skills, rules, hooks, and MCP servers scoped to the Forge department are stored in the object store with metadata.engine = "forge". The shared CRUD API routes (/api/dept/{id}/agents, /api/dept/{id}/skills, etc.) filter by this metadata key, so each department sees only its own entities.

Chat Flow

sequenceDiagram
    participant User
    participant API as rusvel-api
    participant Chat as Chat Handler
    participant Config as ConfigPort
    participant Skills as Skill Resolver
    participant Rules as Rule Loader
    participant Agent as AgentRuntime
    participant Forge as ForgeEngine
    participant Events as EventPort
    participant Hooks as Hook Dispatcher

    User->>API: POST /api/dept/forge/chat {message}
    API->>Chat: route to department chat handler
    Chat->>Config: load department config (model, effort, permissions)
    Chat->>Skills: resolve_skill() -- check for {{input}} interpolation
    Chat->>Chat: check agent override (custom agent for forge)
    Chat->>Rules: load_rules_for_engine("forge") -- append to system prompt
    Note over Chat: Inject capabilities: planning, orchestration
    Note over Chat: System prompt: "You are the Forge department..."
    Chat->>Agent: AgentRuntime::run_streaming(config, tools, prompt)
    Agent->>Forge: tool calls (forge.mission.today, forge.persona.hire, etc.)
    Forge->>Events: emit forge.* events
    Agent-->>Chat: SSE stream (AgentEvent chunks)
    Chat-->>User: SSE response
    Chat->>Events: emit chat completion event
    Chat->>Hooks: tokio::spawn hook dispatch

Extending This Department

1. Add a new tool

Register the tool in crates/dept-forge/src/lib.rs inside the register() method using ctx.tools.add("forge", "forge.new_tool", ...). Add a matching ToolContribution entry in forge_engine::mission::mission_tool_contributions_for_manifest() so the manifest stays consistent.

2. Add a new event kind

Add a new pub const in crates/forge-engine/src/events.rs. Emit it from the engine method using self.events.emit(...). Add the event kind string to the events_produced vec in crates/dept-forge/src/manifest.rs.

3. Add a new persona

Add a new profile(...) call in crates/forge-engine/src/personas.rs inside default_personas(). The persona will automatically appear in the manifest via persona_contributions_for_manifest().

4. Add a new skill

Add a SkillContribution entry in the skills vec in crates/dept-forge/src/manifest.rs. Use {{variable}} placeholders in the prompt_template field for runtime interpolation.

5. Add a new API route

Add a RouteContribution entry in forge_engine::mission::forge_route_contributions_for_manifest(). Implement the handler in crates/rusvel-api/src/engine_routes.rs (or a new handler module) and wire the route in crates/rusvel-api/src/lib.rs.

Port Dependencies

Safety Guard System

The Forge engine includes a SafetyGuard that wraps all LLM calls made through run_agent_with_mission_safety():

Budget Enforcement

• Every mission/review LLM call estimates cost via config.budget_limit (default: $0.10 per call).
• Aggregate spend is tracked across the session lifetime.
• When spend crosses 80% of the configured ceiling, the engine emits forge.safety.budget_warning.
• When spend would exceed the ceiling, the call is rejected with a clear error before any LLM work begins.

Concurrency Slots

• A semaphore limits concurrent mission agent runs (prevents parallel LLM calls from overwhelming providers).
• Each call acquires a slot; the slot is released when the call completes or fails.

Circuit Breaker

• Consecutive failures are tracked. After a threshold of repeated failures, the circuit opens.
• When open, all subsequent mission agent calls are rejected immediately without contacting the LLM.
• The engine emits forge.safety.circuit_open when the circuit opens.
• Successful calls reset the failure counter and close the circuit.

Executive Brief System

The generate_brief() method produces a cross-department daily digest:

1. Department scans: For each of the 14 department apps, the engine selects an appropriate persona (e.g., CodeWriter for code, Researcher for harvest/finance/legal) and runs a brief-section LLM call asking for status (green/yellow/red), highlights, and metrics.
2. Strategist synthesis: An Architect persona processes all department sections and produces a 2-3 sentence executive summary plus 3-5 cross-cutting action items.
3. Persistence: The brief is saved to ObjectStore as executive_brief kind and a forge.brief.generated event is emitted.
4. Retrieval: latest_brief() returns the most recent brief, sorted by created_at.

Department-to-Persona Mapping

Pipeline Orchestration

The Forge engine supports multi-step pipeline orchestration triggered by webhook events:

• Webhook registration with event_kind = "forge.pipeline.requested" enqueues JobKind::Custom("forge.pipeline").
• The job worker in rusvel-app calls ForgeEngine::orchestrate_pipeline().
• Pipeline steps emit forge.pipeline.step_started and forge.pipeline.step_completed events.
• The full pipeline emits forge.pipeline.started and forge.pipeline.completed (or forge.pipeline.failed).

Object Store Kinds

UI Integration

The manifest declares a dashboard card and 7 tabs:

• Dashboard card: “Mission Status” (large) – Active goals, today’s plan, recent reviews
• Tabs: actions, engine, agents, workflows, skills, rules, events

Testing

cargo test -p forge-engine    # 15 tests (all use mock ports)

Key test scenarios:

• Engine metadata (kind, name, capabilities)
• Engine lifecycle (initialize, health, shutdown)
• Set and list goals (persistence + event emission)
• Mission today generates plan (LLM mock returns JSON, plan parsed)
• Default personas (10 built-in, lookup by name)
• Hire persona creates AgentConfig (session binding, tool list)
• Safety guard initialization (budget check, circuit check)

Code Department

Code intelligence, implementation, debugging, testing, refactoring

Overview

The Code Department provides AI-powered code intelligence for RUSVEL. It parses Rust source files, builds a symbol dependency graph, computes project metrics (file counts, symbol counts, largest function), and exposes BM25-ranked symbol search. It is the department a developer uses to understand a codebase before making changes, and it produces code.analyzed events that the Content department consumes to auto-generate technical blog posts from code snapshots.

Engine (code-engine)

• Crate: crates/code-engine/src/lib.rs
• Lines: 307 (lib.rs) + submodules (parser, graph, metrics, search, error)
• Status: Wired (real business logic)

Public API

Internal Structure

• parser (parser.rs) – Rust source file parser that extracts Symbol structs (functions, structs, enums, traits, impls) with name, kind, file path, line number, and body text.
• graph (graph.rs) – SymbolGraph built from parsed symbols representing call/dependency relationships.
• metrics (metrics.rs) – count_lines() per file and compute_project_metrics() aggregate: total files, total symbols, largest function.
• search (search.rs) – SearchIndex with BM25 ranking. Built from (name, file_path, body, line) tuples.
• error (error.rs) – Engine-specific error types.

Data Types

#![allow(unused)]
fn main() {
pub struct CodeAnalysis {
    pub snapshot: CodeSnapshotRef,   // ID + repo path + analyzed_at timestamp
    pub symbols: Vec<Symbol>,        // All parsed symbols
    pub graph: SymbolGraph,          // Dependency graph
    pub metrics: ProjectMetrics,     // Aggregate metrics
}
}

CodeAnalysis::summary() produces a CodeAnalysisSummary (snapshot_id, repo_path, total_files, total_symbols, top 10 function names, largest function) that the Content engine uses for code-to-content generation.

Department Wrapper (dept-code)

• Crate: crates/dept-code/src/lib.rs
• Lines: 154
• Manifest: crates/dept-code/src/manifest.rs

The wrapper creates a CodeEngine during registration with StoragePort and EventPort, then registers 2 agent tools. No event handlers or job handlers are registered.

Manifest Declaration

System Prompt

You are the Code department of RUSVEL.

You have full access to Claude Code tools:

• Read, Write, Edit files across all project directories
• Run shell commands (build, test, git, pnpm, cargo, etc.)
• Search codebases with grep and glob
• Fetch web content and search the web
• Spawn sub-agents for parallel work
• Manage background tasks

Focus: code intelligence, implementation, debugging, testing, refactoring. When writing code, follow existing patterns. Be thorough.

Capabilities

• code_analysis
• tool_use

Quick Actions

Registered Tools

Personas

Skills

Rules

No rules are declared for the Code department.

Jobs

Events

Produced

Consumed

The Code department does not consume events from other departments.

API Routes

CLI Commands

rusvel code analyze [path]   # Analyze a codebase (default: current directory)
rusvel code search <query>   # Search indexed symbols

Entity Auto-Discovery

Agents, skills, rules, hooks, and MCP servers scoped to the Code department are stored with metadata.engine = "code". The shared CRUD API routes filter by this key so each department sees only its own entities.

Chat Flow

sequenceDiagram
    participant User
    participant API as rusvel-api
    participant Chat as Chat Handler
    participant Config as ConfigPort
    participant Skills as Skill Resolver
    participant Rules as Rule Loader
    participant Agent as AgentRuntime
    participant Code as CodeEngine
    participant Events as EventPort
    participant Hooks as Hook Dispatcher

    User->>API: POST /api/dept/code/chat {message}
    API->>Chat: route to department chat handler
    Chat->>Config: load department config (model, effort, add_dirs)
    Chat->>Skills: resolve_skill() -- check for {{input}} interpolation
    Chat->>Chat: check agent override (custom agent for code)
    Chat->>Rules: load_rules_for_engine("code") -- append to system prompt
    Note over Chat: Inject capabilities: code_analysis, tool_use
    Note over Chat: System prompt: "You are the Code department..."
    Note over Chat: Default config: effort=high, add_dirs=["."]
    Chat->>Agent: AgentRuntime::run_streaming(config, tools, prompt)
    Agent->>Code: tool calls (code.analyze, code.search)
    Code->>Events: emit code.analyzed
    Agent-->>Chat: SSE stream (AgentEvent chunks)
    Chat-->>User: SSE response
    Chat->>Events: emit chat completion event
    Chat->>Hooks: tokio::spawn hook dispatch

Extending This Department

1. Add a new tool

Register the tool in crates/dept-code/src/lib.rs inside the register() method using ctx.tools.add("code", "code.new_tool", ...). Add a matching ToolContribution entry in crates/dept-code/src/manifest.rs in the tools vec.

2. Add a new event kind

Add a new pub const in the events module inside crates/code-engine/src/lib.rs. Emit it from the engine method. Add the event kind string to events_produced in crates/dept-code/src/manifest.rs.

3. Add a new persona

Add a PersonaContribution entry in the personas vec in crates/dept-code/src/manifest.rs.

4. Add a new skill

Add a SkillContribution entry in the skills vec in crates/dept-code/src/manifest.rs. Use {{variable}} placeholders for runtime interpolation.

5. Add a new API route

Add a RouteContribution entry in the routes vec in crates/dept-code/src/manifest.rs. Implement the handler in crates/rusvel-api/src/engine_routes.rs and wire the route in crates/rusvel-api/src/lib.rs.

Port Dependencies

Default Configuration

The Code department ships with a non-default LayeredConfig:

• effort: "high" – maximizes analysis thoroughness
• permission_mode: "default"
• add_dirs: ["."] – adds the current directory to the agent’s working set

Object Store Kinds

Cross-Department Integration

The Code department is a producer in the code-to-content pipeline:

1. Code -> Content: When analyze() completes, it emits code.analyzed with snapshot_id, total_symbols, and total_files in the payload. The Content department’s event handler receives this and calls draft_blog_from_code_snapshot() to generate a technical blog post.

2. Code -> Forge: The Forge department can use the CodeWriter persona to analyze code during executive brief generation for the code department section.

This is achieved entirely through the event system – the Code engine never imports the Content engine.

Parser Details

The parser module handles Rust source file parsing:

• Scans .rs files in the given directory (recursive)
• Extracts symbols: functions (fn), structs, enums, traits, impl blocks
• Each Symbol includes: name, SymbolKind, file_path, line number, body text
• Used by SymbolGraph::build() to construct a dependency graph
• Used by SearchIndex::build() to create BM25-searchable index

Symbol Kinds

Function, Struct, Enum, Trait, Impl

Search Index

The BM25 search index is built from tuples of (name, file_path, body, line):

• Index: Built once per analyze() call, stored in-memory behind a Mutex
• Query: search(query, limit) returns ranked SearchResult entries
• Error: Returns RusvelError::Internal if called before analyze()

#![allow(unused)]
fn main() {
pub struct SearchResult {
    pub symbol_name: String,
    pub file_path: String,
    pub line: usize,
    pub score: f64,
}
}

Metrics

The metrics module computes:

• Per-file: count_lines() returns FileMetrics (total lines, code lines, comment lines, blank lines)
• Project-wide: compute_project_metrics() aggregates across all files:

#![allow(unused)]
fn main() {
pub struct ProjectMetrics {
    pub total_files: usize,
    pub total_symbols: usize,
    pub largest_function: Option<String>,
    // ... additional fields
}
}

UI Integration

The manifest declares a dashboard card and 10 tabs:

• Dashboard card: “Code Intelligence” (medium) – Symbol index, metrics, and search
• Tabs: actions, engine, agents, workflows, skills, rules, mcp, hooks, dirs, events
• has_settings: true (supports department-level settings)

Testing

cargo test -p code-engine    # Tests in lib.rs

Key test scenarios:

• Analyze a temp directory with Rust files, verify symbol count
• Search after analysis, verify results
• Health returns healthy (with and without index)
• Event emission on analyze

cargo test -p dept-code      # Department wrapper tests

Key test scenarios:

• Department creates with correct manifest ID
• Manifest declares 2 routes, 2 tools, 2 events
• Manifest requires StoragePort and EventPort
• Manifest serializes to valid JSON

Content Department

Content creation, platform adaptation, publishing strategy

Overview

The Content Department handles the full content lifecycle for RUSVEL: AI-powered drafting, multi-platform adaptation (LinkedIn, Twitter/X, DEV.to, Substack), calendar scheduling, human-approved publishing, and engagement analytics. It consumes code.analyzed events from the Code department to automatically generate technical blog posts from code snapshots, creating a seamless code-to-content pipeline. Every piece of content must pass a human approval gate (ADR-008) before it can be published.

Engine (content-engine)

• Crate: crates/content-engine/src/lib.rs
• Lines: 424 (lib.rs) + submodules (writer, calendar, analytics, adapters, platform, code_bridge)
• Status: Wired (real business logic)

Public API

Internal Structure

• ContentWriter (writer.rs) – AI-powered drafting and adaptation. Uses AgentPort to generate content. build_code_prompt() builds prompts from CodeAnalysisSummary for code-to-content.
• ContentCalendar (calendar.rs) – Scheduling engine. Uses StoragePort for persistence and JobPort for scheduling future publish jobs.
• ContentAnalytics (analytics.rs) – Engagement metrics tracking per content item per platform.
• PlatformAdapter trait (platform.rs) – Interface for platform-specific publishing. Returns PublishResult with URL and timestamp. Has max_length() for character-limited platforms.
• Platform adapters (adapters/) – Real implementations for LinkedIn, Twitter, and DEV.to. Each reads API credentials from ConfigPort.
• code_bridge (code_bridge.rs) – Converts stored code_analysis JSON to CodeAnalysisSummary for the writer.

Content Kinds

LongForm, Tweet, Thread, LinkedInPost, Blog, VideoScript, Email, Proposal

Content Statuses

Draft, Adapted, Approved, Published, Cancelled

Supported Platforms

Twitter, LinkedIn, DevTo, Medium, YouTube, Substack, Email, Custom(String)

Department Wrapper (dept-content)

• Crate: crates/dept-content/src/lib.rs
• Lines: 131
• Manifest: crates/dept-content/src/manifest.rs

The wrapper creates a ContentEngine, registers 3 real platform adapters (LinkedIn, Twitter, DEV.to), registers 2 agent tools, wires an event handler for code.analyzed, and registers a job handler for content.publish.

Registration Details

- Platform adapters: LinkedInAdapter, TwitterAdapter, DevToAdapter (all from content_engine::adapters)
- Tools: content.draft, content.adapt (via tools::register_tools)
- Event handler: "code.analyzed" -> triggers code-to-content pipeline
- Job handler: "content.publish" -> executes content_engine.execute_content_publish_job

Manifest Declaration

System Prompt

You are the Content department of RUSVEL.

Focus: content creation, platform adaptation, publishing strategy. Draft in Markdown. Adapt for LinkedIn, Twitter/X, DEV.to, Substack.

Capabilities

• content_creation

Quick Actions

Registered Tools

Personas

Skills

Rules

Jobs

Events

Produced

Consumed

API Routes

CLI Commands

rusvel content draft <topic>    # Draft content from a topic
rusvel content from-code        # Generate content from code analysis

Entity Auto-Discovery

Agents, skills, rules, hooks, and MCP servers scoped to the Content department are stored with metadata.engine = "content". The shared CRUD API routes filter by this key so each department sees only its own entities.

Chat Flow

sequenceDiagram
    participant User
    participant API as rusvel-api
    participant Chat as Chat Handler
    participant Config as ConfigPort
    participant Skills as Skill Resolver
    participant Rules as Rule Loader
    participant Agent as AgentRuntime
    participant Content as ContentEngine
    participant Events as EventPort
    participant Hooks as Hook Dispatcher

    User->>API: POST /api/dept/content/chat {message}
    API->>Chat: route to department chat handler
    Chat->>Config: load department config (model, platform tokens)
    Chat->>Skills: resolve_skill() -- check for {{input}} interpolation
    Chat->>Chat: check agent override (custom agent for content)
    Chat->>Rules: load_rules_for_engine("content") -- append "Human Approval Gate" rule
    Note over Chat: Inject capabilities: content_creation
    Note over Chat: System prompt: "You are the Content department..."
    Chat->>Agent: AgentRuntime::run_streaming(config, tools, prompt)
    Agent->>Content: tool calls (content.draft, content.adapt)
    Content->>Events: emit content.drafted / content.adapted
    Agent-->>Chat: SSE stream (AgentEvent chunks)
    Chat-->>User: SSE response
    Chat->>Events: emit chat completion event
    Chat->>Hooks: tokio::spawn hook dispatch

Code-to-Content Pipeline

sequenceDiagram
    participant Code as CodeEngine
    participant Events as EventPort
    participant ContentHandler as on_code_analyzed handler
    participant Content as ContentEngine

    Code->>Events: emit code.analyzed {snapshot_id}
    Events->>ContentHandler: dispatch event
    ContentHandler->>Content: draft_blog_from_code_snapshot(session_id, snapshot_id)
    Content->>Content: load code_analysis from ObjectStore
    Content->>Content: build CodeAnalysisSummary
    Content->>Content: draft(session_id, code_prompt, Blog)
    Content->>Events: emit content.drafted

Extending This Department

1. Add a new tool

Register the tool in crates/dept-content/src/tools.rs inside register_tools(). Add a matching ToolContribution entry in crates/dept-content/src/manifest.rs.

2. Add a new event kind

Add a new pub const in the events module inside crates/content-engine/src/lib.rs. Emit it from the engine method. Add the event kind string to events_produced in crates/dept-content/src/manifest.rs.

3. Add a new persona

Add a PersonaContribution entry in the personas vec in crates/dept-content/src/manifest.rs.

4. Add a new skill

Add a SkillContribution entry in the skills vec in crates/dept-content/src/manifest.rs.

5. Add a new API route

Add a RouteContribution entry in the routes vec in crates/dept-content/src/manifest.rs. Implement the handler in crates/rusvel-api/src/engine_routes.rs and wire the route in crates/rusvel-api/src/lib.rs.

6. Add a new platform adapter

Implement the PlatformAdapter trait in a new file under crates/content-engine/src/adapters/. Register it in crates/dept-content/src/lib.rs inside register() with engine.register_platform(Arc::new(NewAdapter::new(ctx.config.clone()))).

Port Dependencies

Object Store Kinds

Platform Adapter Details

PlatformAdapter Trait

#![allow(unused)]
fn main() {
pub trait PlatformAdapter: Send + Sync + Debug {
    fn platform(&self) -> Platform;
    fn max_length(&self) -> Option<usize>;
    async fn publish(&self, item: &ContentItem) -> Result<PublishResult>;
}
}

Registered Adapters

PublishResult

#![allow(unused)]
fn main() {
pub struct PublishResult {
    pub url: Option<String>,
    pub published_at: DateTime<Utc>,
    pub metadata: Value,
}
}

Content Approval Flow (ADR-008)

Content must be explicitly approved before it can be published:

stateDiagram-v2
    [*] --> Draft: draft()
    Draft --> Adapted: adapt()
    Draft --> Approved: approve_content()
    Adapted --> Approved: approve_content()
    Approved --> Published: publish()
    Draft --> Cancelled: cancel
    Adapted --> Cancelled: cancel

Attempting to call publish() on content that is not Approved or AutoApproved returns RusvelError::Validation.

Content Calendar

The ContentCalendar manages future publication scheduling:

• schedule() creates a ScheduledPost and enqueues a content.publish job with a scheduled time
• list_scheduled() returns all scheduled posts for a session
• list_scheduled_in_range() filters by date range (inclusive)
• Jobs are processed by the job worker, which calls execute_content_publish_job()

ContentWriter AI Integration

The ContentWriter uses AgentPort for two operations:

1. Draft: Given a topic and content kind, generates markdown content via an AI agent
2. Adapt: Given existing content and a target platform, rewrites to fit the platform’s format and length constraints

For code-to-content, build_code_prompt() constructs a rich prompt from CodeAnalysisSummary including repository path, symbol counts, top functions, and the largest function name.

UI Integration

The manifest declares a dashboard card and 6 tabs:

• Dashboard card: “Content Pipeline” (medium) – Drafts, scheduled, and published content
• Tabs: actions, engine, agents, skills, rules, events
• has_settings: true (supports platform credential configuration)

Configuration Schema

{
  "devto_api_key": "string",
  "twitter_bearer_token": "string",
  "linkedin_bearer_token": "string",
  "default_format": "markdown | html"
}

Testing

cargo test -p content-engine    # 7 tests

Key test scenarios:

• Draft creates content item and emits event
• Adapt creates platform-adapted version
• Publish requires approval status
• Calendar scheduling
• Code-to-content pipeline integration

cargo test -p dept-content      # Department wrapper tests

Key test scenarios:

• Department creates with correct manifest ID
• Manifest declares 5 routes, 2 tools, 7 events
• Manifest requires AgentPort (non-optional)
• Manifest serializes to valid JSON

Harvest Department

Opportunity discovery, scoring, proposal generation, pipeline management

Overview

The Harvest Department is RUSVEL’s freelance opportunity engine. It scans sources (Upwork, LinkedIn, GitHub, RSS feeds), scores discovered opportunities using keyword matching or LLM-based evaluation, generates tailored proposals via an AI agent, and manages a Kanban pipeline (Cold -> Warm -> Hot -> Won/Lost). It also records deal outcomes (won/lost/withdrawn) that feed back into the scoring model, and supports optional RAG via embedding and vector store for similarity-based scoring hints. Browser-captured data from CDP sessions (Upwork job listings, client profiles) is normalized into opportunities and CRM contacts.

Engine (harvest-engine)

• Crate: crates/harvest-engine/src/lib.rs
• Lines: 1013 (lib.rs) + submodules (source, scorer, proposal, pipeline, events, outcomes, cdp_source)
• Status: Wired (real business logic)

Public API

Internal Structure

• HarvestSource trait (source.rs) – Interface for scanning opportunity sources. Returns Vec<RawOpportunity>. Includes MockSource for testing.
• CdpSource (cdp_source.rs) – CDP/browser-based source for Upwork. Includes default JavaScript extraction script.
• OpportunityScorer (scorer.rs) – Scores raw opportunities. Two methods: ScoringMethod::Keyword (fast, pattern-based) and ScoringMethod::Llm (uses AgentPort for AI evaluation). Accepts outcome hints for calibration.
• ProposalGenerator (proposal.rs) – Generates proposals using AgentPort. Produces Proposal with body, estimated value, tone, and metadata.
• Pipeline (pipeline.rs) – Kanban pipeline management via ObjectStore. add(), list(), advance(), stats().
• outcomes (outcomes.rs) – Deal outcome recording and retrieval. record_outcome(), list_outcomes(), recent_outcome_prompt_lines() for LLM hints.
• events (events.rs) – Event kind constants.

Data Types

#![allow(unused)]
fn main() {
pub struct HarvestConfig {
    pub skills: Vec<String>,      // Skills to match (default: ["rust"])
    pub min_budget: Option<f64>,  // Minimum budget filter
}

pub struct OpportunityScoreUpdate {
    pub score: f64,
    pub reasoning: String,
}

pub enum HarvestDealOutcome { Won, Lost, Withdrawn }

pub struct HarvestOutcomeRecord {
    pub id: String,
    pub session_id: SessionId,
    pub opportunity_snapshot: Value,
    pub result: HarvestDealOutcome,
    pub notes: String,
}
}

RAG Integration

When configure_rag() is called with both an EmbeddingPort and VectorStorePort:

1. Scoring hints: Before scoring, the engine embeds the opportunity title+description, searches the vector store for similar past outcomes, and includes the top 5 matches as prompt hints.
2. Outcome indexing: When record_opportunity_outcome() is called, the outcome is embedded and upserted into the vector store with kind: "harvest_outcome" metadata.

Department Wrapper (dept-harvest)

• Crate: crates/dept-harvest/src/lib.rs
• Lines: 99
• Manifest: crates/dept-harvest/src/manifest.rs

The wrapper creates a HarvestEngine with builder pattern (with_events, with_agent), calls configure_rag() to wire optional embedding and vector store from the registration context, and persists the engine reference.

Manifest Declaration

System Prompt

You are the Harvest department of RUSVEL.

Focus: finding opportunities, scoring gigs, drafting proposals. Sources: Upwork, LinkedIn, GitHub.

Capabilities

• opportunity_discovery

Quick Actions

Registered Tools

Personas

Skills

Rules

Jobs

Events

Produced

Consumed

The Harvest department does not consume events from other departments. It is triggered by direct API/CLI calls and browser capture events.

API Routes

CLI Commands

rusvel harvest pipeline    # Show pipeline statistics
rusvel harvest status      # Department status
rusvel harvest list        # List items
rusvel harvest events      # Show recent events

Entity Auto-Discovery

Agents, skills, rules, hooks, and MCP servers scoped to the Harvest department are stored with metadata.engine = "harvest". The shared CRUD API routes filter by this key so each department sees only its own entities.

Chat Flow

sequenceDiagram
    participant User
    participant API as rusvel-api
    participant Chat as Chat Handler
    participant Config as ConfigPort
    participant Skills as Skill Resolver
    participant Rules as Rule Loader
    participant Agent as AgentRuntime
    participant Harvest as HarvestEngine
    participant Events as EventPort
    participant VectorStore as VectorStorePort
    participant Hooks as Hook Dispatcher

    User->>API: POST /api/dept/harvest/chat {message}
    API->>Chat: route to department chat handler
    Chat->>Config: load department config (skills, min_budget)
    Chat->>Skills: resolve_skill() -- check for {{input}} interpolation
    Chat->>Chat: check agent override (custom agent for harvest)
    Chat->>Rules: load_rules_for_engine("harvest") -- append "Human Approval Gate" rule
    Note over Chat: Inject capabilities: opportunity_discovery
    Note over Chat: System prompt: "You are the Harvest department..."
    Chat->>Agent: AgentRuntime::run_streaming(config, tools, prompt)
    Agent->>Harvest: tool calls (harvest.scan, harvest.score, harvest.proposal)
    Harvest->>VectorStore: similarity search for outcome hints (if RAG configured)
    Harvest->>Events: emit harvest.* events
    Agent-->>Chat: SSE stream (AgentEvent chunks)
    Chat-->>User: SSE response
    Chat->>Events: emit chat completion event
    Chat->>Hooks: tokio::spawn hook dispatch

Extending This Department

1. Add a new tool

Register the tool in crates/dept-harvest/src/lib.rs inside the register() method using ctx.tools.add("harvest", "harvest.new_tool", ...). Add a matching ToolContribution entry in crates/dept-harvest/src/manifest.rs.

2. Add a new event kind

Add a new pub const in crates/harvest-engine/src/events.rs. Emit it from the engine method. Add the event kind string to events_produced in crates/dept-harvest/src/manifest.rs.

3. Add a new persona

Add a PersonaContribution entry in the personas vec in crates/dept-harvest/src/manifest.rs.

4. Add a new skill

Add a SkillContribution entry in the skills vec in crates/dept-harvest/src/manifest.rs.

5. Add a new API route

Add a RouteContribution entry in the routes vec in crates/dept-harvest/src/manifest.rs. Implement the handler in crates/rusvel-api/src/engine_routes.rs and wire the route in crates/rusvel-api/src/lib.rs.

6. Add a new harvest source

Implement the HarvestSource trait in a new file under crates/harvest-engine/src/. Return Vec<RawOpportunity> from scan(). The engine’s scan() method will automatically score and persist results.

Port Dependencies

Configuration

{
  "skills": ["rust", "axum", "tokio"],
  "min_budget": 1000.0
}

• skills – Skills to match when scoring opportunities and expanding RSS queries. Default: ["rust"].
• min_budget – Minimum budget filter. Opportunities below this are scored lower.

Object Store Kinds

Scoring System

The OpportunityScorer supports two scoring methods:

Keyword Scoring (ScoringMethod::Keyword)

Fast, pattern-based scoring used when no AgentPort is configured:

• Matches opportunity title and description against configured skills
• Applies budget multiplier based on min_budget threshold
• Returns a normalized score (0.0 to 1.0)

LLM Scoring (ScoringMethod::Llm)

AI-powered scoring used when AgentPort is available:

• Sends opportunity details plus configured skills to the agent
• Includes outcome hints (recent outcomes + vector similarity matches) for calibration
• Agent returns a score and reasoning

Outcome-Based Calibration

When RAG is configured, scoring includes:

1. Recent outcomes: The last 12 HarvestOutcomeRecord entries for the session, formatted as prompt lines
2. Vector similarity: The opportunity title+description is embedded and searched against indexed outcomes; top 5 matches with similarity scores are included

This creates a feedback loop: won/lost outcomes improve future scoring accuracy.

Pipeline Stages

Opportunities flow through a Kanban pipeline:

Cold -> Warm -> Hot -> Won
                   -> Lost
                   -> Withdrawn

• Cold: Newly discovered, not yet evaluated
• Warm: Scored positively, under consideration
• Hot: Actively pursuing, proposal sent
• Won: Deal closed successfully
• Lost: Opportunity not won
• Withdrawn: Withdrawn from consideration

advance_opportunity() moves an opportunity to any valid stage and emits harvest.pipeline.advanced.

Browser Data Capture (CDP)

The on_data_captured() method handles BrowserEvent::DataCaptured payloads from CDP sessions:

Upwork Job Listings (kind: "job_listing")

• Accepts single job or {jobs: [...]} array
• Extracts: title, description, url, budget, skills, posted_at
• Runs through the scorer
• Creates Opportunity in Cold stage
• Emits harvest.opportunity.discovered

Upwork Client Profiles (kind: "client_profile")

• Extracts: name, profile_url, company
• Creates Contact in ObjectStore
• Emits harvest.contact.captured

CDP Extract JavaScript

DEFAULT_CDP_EXTRACT_JS provides a default JavaScript snippet for extracting job listing cards from Upwork pages via Chrome DevTools Protocol.

UI Integration

The manifest declares a dashboard card and 6 tabs:

• Dashboard card: “Opportunity Pipeline” (medium) – Cold, warm, and hot opportunities
• Tabs: actions, engine, agents, skills, rules, events
• has_settings: true (supports skills and budget configuration)

Testing

cargo test -p harvest-engine    # 12 tests

Key test scenarios:

• Scan with mock source returns 3 opportunities
• Pipeline stores and lists correctly
• Pipeline stats match (all Cold after scan)
• Health returns healthy
• Proposals respect session filter
• Outcome recording and retrieval

cargo test -p dept-harvest      # Department wrapper tests

Key test scenarios:

• Department creates with correct manifest ID
• Manifest declares 5 routes, 3 tools, 3 events
• Manifest requires StoragePort, EventPort, AgentPort (non-optional) + ConfigPort (optional)
• Manifest serializes to valid JSON

GoToMarket Department

CRM, outreach sequences, deal management, invoicing

Overview

The GoToMarket (GTM) Department handles the full sales pipeline for RUSVEL: contact management (CRM), multi-step outreach sequences with human approval gates, deal tracking through pipeline stages (Lead -> Qualified -> Proposal -> Negotiation -> Won/Lost), and invoicing with line items and payment tracking. Outreach sequences draft emails via the AI agent, hold them for human approval (ADR-008), then send via SMTP and auto-schedule the next step in the sequence. This is the department a solo builder uses to manage client relationships from first contact through paid invoice.

Engine (gtm-engine)

• Crate: crates/gtm-engine/src/lib.rs
• Lines: 710 (lib.rs) + submodules (crm, outreach, invoice, email)
• Status: Wired (real business logic)

Public API

CrmManager API

OutreachManager API

InvoiceManager API

Internal Structure

• CrmManager (crm.rs) – Contact and deal CRUD. Deals have stages: Lead, Qualified, Proposal, Negotiation, Won, Lost.
• OutreachManager (outreach.rs) – Multi-step sequence management. Steps have delay_days, channel, and template. Sequences must be activated before execution. Execution enqueues JobKind::OutreachSend jobs.
• InvoiceManager (invoice.rs) – Invoice creation with LineItem (description, quantity, unit_price). Tracks status: Draft, Sent, Paid, Overdue.
• EmailAdapter trait (email.rs) – Interface for sending emails. Implementations: SmtpEmailAdapter (uses RUSVEL_SMTP_* env vars) and MockEmailAdapter (for testing).
• OutreachSendDispatch – Result enum from processing an outreach job: HoldForApproval(result) (first pass, draft held), Complete { result, next } (approved, sent, next step scheduled if any).

Data Types

#![allow(unused)]
fn main() {
pub struct Deal {
    pub id: DealId,
    pub session_id: SessionId,
    pub contact_id: ContactId,
    pub title: String,
    pub value: f64,
    pub stage: DealStage,   // Lead | Qualified | Proposal | Negotiation | Won | Lost
    pub notes: String,
    pub created_at: DateTime<Utc>,
    pub metadata: Value,
}

pub struct OutreachSequence {
    pub id: SequenceId,
    pub session_id: SessionId,
    pub name: String,
    pub steps: Vec<SequenceStep>,
    pub status: SequenceStatus,  // Draft | Active | Paused | Completed
    pub metadata: Value,
}

pub struct SequenceStep {
    pub delay_days: u32,
    pub channel: String,     // "email", "linkedin", etc.
    pub template: String,
}

pub struct Invoice {
    pub id: InvoiceId,
    pub session_id: SessionId,
    pub contact_id: ContactId,
    pub items: Vec<LineItem>,
    pub status: InvoiceStatus,  // Draft | Sent | Paid | Overdue
    pub total: f64,
    pub due_date: DateTime<Utc>,
    pub metadata: Value,
}
}

Department Wrapper (dept-gtm)

• Crate: crates/dept-gtm/src/lib.rs
• Lines: 95
• Manifest: crates/dept-gtm/src/manifest.rs
• Tools: crates/dept-gtm/src/tools.rs

The wrapper creates a GtmEngine with all 4 ports during registration and registers 5 agent tools via tools::register().

Manifest Declaration

System Prompt

You are the GoToMarket department of RUSVEL.

Focus: CRM, outreach sequences, deal management, invoicing.

Capabilities

• outreach
• crm
• invoicing

Quick Actions

Registered Tools

Personas

No personas are declared in the GTM manifest. The department uses the default agent configuration.

Skills

No skills are declared in the GTM manifest.

Rules

No rules are declared in the GTM manifest. Outreach approval is enforced at the job processing level (ADR-008 via OutreachSendDispatch::HoldForApproval).

Jobs

No jobs are declared in the GTM manifest. JobKind::OutreachSend is processed by the job worker in rusvel-app which calls GtmEngine::process_outreach_send_job().

Events

Produced

Consumed

The GTM department does not consume events from other departments.

API Routes

The GTM manifest declares no route contributions. GTM functionality is accessed through:

• Agent tools: The 5 registered tools are available during chat sessions
• Generic department routes: /api/dept/gtm/status, /api/dept/gtm/list, /api/dept/gtm/events
• Job worker: JobKind::OutreachSend processed in the rusvel-app job worker

CLI Commands

rusvel gtm status       # Department status
rusvel gtm list         # List items
rusvel gtm events       # Show recent events

Outreach Approval Flow

The GTM outreach system enforces human approval (ADR-008) through a two-pass job processing model:

sequenceDiagram
    participant User
    participant Outreach as OutreachManager
    participant Jobs as JobPort
    participant Worker as Job Worker
    participant GTM as GtmEngine
    participant Email as EmailAdapter
    participant Events as EventPort

    User->>Outreach: execute_sequence(session, seq_id, contact_id)
    Outreach->>Jobs: enqueue OutreachSend job (step 0)

    Note over Worker: Pass 1: Draft
    Worker->>GTM: process_outreach_send_job(job, email)
    GTM->>GTM: draft email via AgentPort
    GTM-->>Worker: HoldForApproval(result)
    Worker->>Jobs: hold_for_approval(job_id, result)

    Note over User: User reviews and approves
    User->>Jobs: approve(job_id)

    Note over Worker: Pass 2: Send
    Worker->>GTM: process_outreach_send_job(job_with_approval, email)
    GTM->>Email: send(to, subject, body)
    GTM->>Events: emit gtm.email.sent
    GTM->>Events: emit gtm.outreach.sent
    GTM-->>Worker: Complete { result, next: Some(step 1 job) }
    Worker->>Jobs: schedule next step (delay_days offset)

Entity Auto-Discovery

Agents, skills, rules, hooks, and MCP servers scoped to the GTM department are stored with metadata.engine = "gtm". The shared CRUD API routes filter by this key so each department sees only its own entities.

Chat Flow

sequenceDiagram
    participant User
    participant API as rusvel-api
    participant Chat as Chat Handler
    participant Config as ConfigPort
    participant Skills as Skill Resolver
    participant Rules as Rule Loader
    participant Agent as AgentRuntime
    participant GTM as GtmEngine
    participant Events as EventPort
    participant Hooks as Hook Dispatcher

    User->>API: POST /api/dept/gtm/chat {message}
    API->>Chat: route to department chat handler
    Chat->>Config: load department config
    Chat->>Skills: resolve_skill() -- check for {{input}} interpolation
    Chat->>Chat: check agent override (custom agent for gtm)
    Chat->>Rules: load_rules_for_engine("gtm") -- append to system prompt
    Note over Chat: Inject capabilities: outreach, crm, invoicing
    Note over Chat: System prompt: "You are the GoToMarket department..."
    Chat->>Agent: AgentRuntime::run_streaming(config, tools, prompt)
    Agent->>GTM: tool calls (gtm.crm.add_contact, gtm.outreach.create_sequence, etc.)
    GTM->>Events: emit gtm.* events
    Agent-->>Chat: SSE stream (AgentEvent chunks)
    Chat-->>User: SSE response
    Chat->>Events: emit chat completion event
    Chat->>Hooks: tokio::spawn hook dispatch

Extending This Department

1. Add a new tool

Register the tool in crates/dept-gtm/src/tools.rs inside register(). Add the tool ID to the GTM_TOOL_IDS constant. No manifest ToolContribution is needed since the GTM manifest currently declares an empty tools vec (tools are registered dynamically).

2. Add a new event kind

Add a new pub const in the events module inside crates/gtm-engine/src/lib.rs. Emit it from the engine method. Optionally add it to events_produced in crates/dept-gtm/src/manifest.rs.

3. Add a new persona

Add a PersonaContribution entry in the personas vec in crates/dept-gtm/src/manifest.rs.

4. Add a new skill

Add a SkillContribution entry in the skills vec in crates/dept-gtm/src/manifest.rs.

5. Add a new API route

Add a RouteContribution entry in the routes vec in crates/dept-gtm/src/manifest.rs. Implement the handler in crates/rusvel-api/src/engine_routes.rs and wire the route in crates/rusvel-api/src/lib.rs.

6. Add a new email adapter

Implement the EmailAdapter trait in crates/gtm-engine/src/email.rs. The trait requires a single send() method that takes an EmailMessage and returns Result<()>.

Port Dependencies

Environment Variables

Finance Department

Revenue tracking, expense management, tax optimization, runway forecasting.

Overview

The Finance department handles financial operations for a solo SaaS business: ledger transactions (income/expenses), tax estimation, and runway forecasting. The engine provides three manager subsystems, each backed by ObjectStore for persistence.

Current Status: Skeleton

The finance engine has manager structures but minimal business logic (~400 lines total across lib.rs and three manager modules). The managers provide CRUD operations:

• LedgerManager – record(), balance(), list_transactions(). Records income and expense transactions, computes net balance.
• TaxManager – add_estimate(), total_liability(), list_estimates(). Stores per-category tax estimates and sums liability (estimates minus deductions).
• RunwayManager – calculate(), list_snapshots(). Computes runway from cash and burn rate, persists snapshots.

The department is fully registered and bootable – it appears in the department registry, responds to chat, and has 4 agent tools wired. However, it needs the following to be production-ready:

• P&L report generation (aggregate by category/period)
• Recurring transaction support
• Multi-currency handling
• Budget alerts and threshold notifications
• Integration with real accounting data sources
• Scheduled runway recalculation via job queue

Engine Details

Crate: finance-engine (~400 lines)

Struct: FinanceEngine

Constructor:

#![allow(unused)]
fn main() {
FinanceEngine::new(
    storage: Arc<dyn StoragePort>,
    events: Arc<dyn EventPort>,
    agent: Arc<dyn AgentPort>,
    jobs: Arc<dyn JobPort>,
)
}

Managers:

Implements: rusvel_core::engine::Engine trait (kind: "finance", name: "Finance Engine")

Manifest

Declared in dept-finance/src/manifest.rs:

id:            "finance"
name:          "Finance Department"
description:   "Revenue tracking, expense management, tax optimization, runway forecasting, P&L reports, unit economics"
icon:          "%"
color:         "green"
capabilities:  ["ledger", "tax", "runway"]

System Prompt

You are the Finance department of RUSVEL.

Focus: revenue tracking, expense management, tax optimization, runway forecasting, P&L reports, unit economics.

Tools

Tools registered at runtime via dept-finance/src/lib.rs (4 tools):

Personas

None declared in the manifest. The department uses the default system prompt for chat interactions.

Skills

None declared in the manifest.

Rules

None declared in the manifest.

Jobs

None declared in the manifest. Future candidates:

• Scheduled runway recalculation
• Periodic P&L report generation
• Tax deadline reminders

Events

Defined Constants (engine)

These constants are defined in the engine but are not yet emitted automatically by the manager methods (emitting requires calling engine.emit_event() explicitly). They are also not listed in the manifest’s events_produced.

Consumed

None.

API Routes

None declared in the manifest. The department is accessible via the standard parameterized routes:

• GET /api/dept/finance/status – department status
• POST /api/dept/finance/chat – SSE chat

CLI Commands

Standard department CLI:

rusvel finance status    # One-shot status
rusvel finance list      # List items
rusvel finance events    # Show events

Entity Auto-Discovery

The standard CRUD subsystems are available at /api/dept/finance/*:

• Agents, Skills, Rules, Hooks, Workflows, MCP Servers

Chat Flow

sequenceDiagram
    participant U as User
    participant API as /api/dept/finance/chat
    participant Agent as AgentRuntime
    participant Tool as finance.* tools
    participant Engine as FinanceEngine
    participant Store as StoragePort

    U->>API: POST "Record $5000 income from consulting"
    API->>Agent: run_streaming(system_prompt, tools)
    Agent->>Tool: finance.ledger.record(kind=Income, amount=5000, ...)
    Tool->>Engine: ledger().record(sid, Income, 5000, ...)
    Engine->>Store: objects.put("transactions", id, value)
    Store-->>Engine: Ok
    Engine-->>Tool: transaction_id
    Tool-->>Agent: "Transaction recorded: {id}"
    Agent->>Tool: finance.ledger.balance(session_id)
    Tool->>Engine: ledger().balance(sid)
    Engine->>Store: objects.list("transactions")
    Store-->>Engine: Vec<Transaction>
    Engine-->>Tool: balance
    Tool-->>Agent: "5000.00"
    Agent-->>API: SSE chunks
    API-->>U: "Recorded $5000 income. Current balance: $5000.00"

Extending the Department

Adding P&L reports

1. Add a PnlManager to finance-engine with generate_report(sid, period) method
2. Register a finance.pnl.report tool in dept-finance/src/lib.rs
3. Add a quick action to the manifest for “P&L report”
4. Optionally add a scheduled job kind for periodic report generation

Adding event emission

The event constants are already defined. To wire them:

1. Call self.emit_event(events::INCOME_RECORDED, payload) inside LedgerManager::record() when the transaction kind is Income
2. Add the event kinds to the manifest’s events_produced vector
3. Other departments can then subscribe via events_consumed

Adding API routes

1. Add route contributions to the manifest in dept-finance/src/manifest.rs
2. Implement handler functions in rusvel-api/src/engine_routes.rs
3. Wire the routes in rusvel-api/src/lib.rs

Port Dependencies

Product Department

Product roadmaps, feature prioritization, pricing strategy, user feedback analysis.

Overview

The Product department manages the product lifecycle: roadmap features with priorities and milestones, pricing tier definitions, and user feedback collection. The engine provides three manager subsystems backed by ObjectStore.

Current Status: Skeleton

The product engine has manager structures but minimal business logic (~388 lines total across lib.rs and three manager modules). The managers provide CRUD operations:

• RoadmapManager – add_feature(sid, title, description, priority, milestone), list_features(sid), mark_feature_done(sid, feature_id). Tracks features with Priority (Critical/High/Medium/Low) and FeatureStatus (Planned/InProgress/Done/Cancelled).
• PricingManager – create_tier(sid, name, price, annual_price, features), list_tiers(sid), update_tier(sid, tier_id, updates). Manages pricing tiers with monthly/annual pricing and feature lists.
• FeedbackManager – add_feedback(sid, source, kind, content), list_feedback(sid), analyze_feedback(sid). Collects feedback categorized by FeedbackKind (FeatureRequest/Bug/Praise/Complaint).

The department is fully registered and bootable – it appears in the department registry, responds to chat, and has 4 agent tools wired. However, it needs the following to be production-ready:

• Feature dependency tracking and critical path analysis
• Milestone timeline visualization data
• Pricing A/B test support
• Feedback sentiment analysis via AgentPort
• Feature voting and prioritization scoring
• Integration with issue trackers (GitHub, Linear)

Engine Details

Crate: product-engine (~388 lines)

Struct: ProductEngine

Constructor:

#![allow(unused)]
fn main() {
ProductEngine::new(
    storage: Arc<dyn StoragePort>,
    events: Arc<dyn EventPort>,
    agent: Arc<dyn AgentPort>,
    jobs: Arc<dyn JobPort>,
)
}

Managers:

Implements: rusvel_core::engine::Engine trait (kind: "product", name: "Product Engine")

Manifest

Declared in dept-product/src/manifest.rs:

id:            "product"
name:          "Product Department"
description:   "Product roadmaps, feature prioritization, pricing strategy, user feedback analysis, A/B testing"
icon:          "@"
color:         "rose"
capabilities:  ["roadmap", "pricing", "feedback"]

System Prompt

You are the Product department of RUSVEL.

Focus: product roadmaps, feature prioritization, pricing strategy, user feedback analysis, A/B testing.

Tools

Tools registered at runtime via dept-product/src/lib.rs (4 tools):

Personas

None declared in the manifest.

Skills

None declared in the manifest.

Rules

None declared in the manifest.

Jobs

None declared in the manifest. Future candidates:

• Periodic feedback analysis aggregation
• Roadmap progress reports
• Pricing optimization suggestions

Events

Defined Constants (engine)

These constants are defined in the engine but are not yet emitted automatically by the manager methods. They are not listed in the manifest’s events_produced.

Consumed

None.

API Routes

None declared in the manifest. The department is accessible via the standard parameterized routes:

• GET /api/dept/product/status – department status
• POST /api/dept/product/chat – SSE chat

CLI Commands

Standard department CLI:

rusvel product status    # One-shot status
rusvel product list      # List items
rusvel product events    # Show events

Entity Auto-Discovery

The standard CRUD subsystems are available at /api/dept/product/*:

• Agents, Skills, Rules, Hooks, Workflows, MCP Servers

Chat Flow

sequenceDiagram
    participant U as User
    participant API as /api/dept/product/chat
    participant Agent as AgentRuntime
    participant Tool as product.* tools
    participant Engine as ProductEngine
    participant Store as StoragePort

    U->>API: POST "Add OAuth2 feature, high priority, for v1.0"
    API->>Agent: run_streaming(system_prompt, tools)
    Agent->>Tool: product.roadmap.add_feature(title="OAuth2", priority="High", status="v1.0")
    Tool->>Engine: roadmap().add_feature(sid, "OAuth2", ..., High, Some("v1.0"))
    Engine->>Store: objects.put("features", id, value)
    Store-->>Engine: Ok
    Engine-->>Tool: feature_id
    Tool-->>Agent: "Feature created: {id}"
    Agent->>Tool: product.roadmap.list_features(session_id)
    Tool->>Engine: roadmap().list_features(sid)
    Engine->>Store: objects.list("features")
    Store-->>Engine: Vec<Feature>
    Engine-->>Tool: features JSON
    Tool-->>Agent: formatted list
    Agent-->>API: SSE chunks
    API-->>U: "Added OAuth2 (High) to v1.0 milestone. Roadmap now has N features."

Extending the Department

Adding feature dependency tracking

1. Add a dependencies: Vec<FeatureId> field to the Feature struct in product-engine/src/roadmap.rs
2. Add a critical_path(sid) method to RoadmapManager that computes the longest dependency chain
3. Register a product.roadmap.critical_path tool in dept-product/src/lib.rs

Adding AI-powered feedback analysis

1. Implement analyze_feedback(sid) in FeedbackManager to call AgentPort with all feedback items
2. The agent can categorize, extract themes, and suggest feature priorities
3. Register a product.feedback.analyze tool

Adding event emission

Wire the defined constants by calling self.emit_event() in the relevant manager methods. Add the event kinds to the manifest’s events_produced vector.

Port Dependencies

Growth Department

Funnel optimization, conversion tracking, cohort analysis, KPI dashboards.

Overview

The Growth department tracks growth metrics for a solo SaaS business: conversion funnels with ordered stages, user cohorts for retention analysis, and KPI time-series recording. The engine provides three manager subsystems backed by ObjectStore.

Current Status: Skeleton

The growth engine has manager structures but minimal business logic (~375 lines total across lib.rs and three manager modules). The managers provide CRUD operations:

• FunnelManager – add_stage(sid, name, order), list_stages(sid), record_conversion(sid, stage_id, count). Defines ordered funnel stages and records conversion counts per stage.
• CohortManager – create_cohort(sid, name, size), list_cohorts(sid), analyze_retention(sid, cohort_id). Creates named cohorts with initial size for retention tracking.
• KpiManager – record_kpi(sid, name, value, unit), list_kpis(sid), get_kpi_trend(sid, name). Records time-series KPI measurements and computes simple two-point trend (delta between last two readings).

The department is fully registered and bootable – it appears in the department registry, responds to chat, and has 4 agent tools wired. However, it needs the following to be production-ready:

• Funnel drop-off rate calculation and visualization data
• Cohort retention matrix computation
• KPI alerting (threshold-based notifications)
• Churn prediction models via AgentPort
• Historical trend analysis beyond two-point comparison
• Dashboard data aggregation endpoints

Engine Details

Crate: growth-engine (~375 lines)

Struct: GrowthEngine

Constructor:

#![allow(unused)]
fn main() {
GrowthEngine::new(
    storage: Arc<dyn StoragePort>,
    events: Arc<dyn EventPort>,
    agent: Arc<dyn AgentPort>,
    jobs: Arc<dyn JobPort>,
)
}

Managers:

Implements: rusvel_core::engine::Engine trait (kind: "growth", name: "Growth Engine")

Manifest

Declared in dept-growth/src/manifest.rs:

id:            "growth"
name:          "Growth Department"
description:   "Funnel optimization, conversion tracking, cohort analysis, churn prediction, retention strategies, KPI dashboards"
icon:          "&"
color:         "orange"
capabilities:  ["funnel", "cohort", "kpi"]

System Prompt

You are the Growth department of RUSVEL.

Focus: funnel optimization, conversion tracking, cohort analysis, churn prediction, retention strategies, KPI dashboards.

Tools

Tools registered at runtime via dept-growth/src/tools.rs (4 tools):

Personas

None declared in the manifest.

Skills

None declared in the manifest.

Rules

None declared in the manifest.

Jobs

None declared in the manifest. Future candidates:

• Scheduled KPI snapshot collection
• Periodic cohort retention analysis
• Churn detection scans

Events

Defined Constants (engine)

These constants are defined in the engine but are not yet emitted automatically by the manager methods. They are not listed in the manifest’s events_produced.

Consumed

None.

API Routes

None declared in the manifest. The department is accessible via the standard parameterized routes:

• GET /api/dept/growth/status – department status
• POST /api/dept/growth/chat – SSE chat

CLI Commands

Standard department CLI:

rusvel growth status    # One-shot status
rusvel growth list      # List items
rusvel growth events    # Show events

Entity Auto-Discovery

The standard CRUD subsystems are available at /api/dept/growth/*:

• Agents, Skills, Rules, Hooks, Workflows, MCP Servers

Chat Flow

sequenceDiagram
    participant U as User
    participant API as /api/dept/growth/chat
    participant Agent as AgentRuntime
    participant Tool as growth.* tools
    participant Engine as GrowthEngine
    participant Store as StoragePort

    U->>API: POST "Record MRR of $12,000"
    API->>Agent: run_streaming(system_prompt, tools)
    Agent->>Tool: growth.kpi.record_kpi(name="MRR", value=12000, unit="USD")
    Tool->>Engine: kpi().record_kpi(sid, "MRR", 12000.0, "USD")
    Engine->>Store: objects.put("kpis", id, value)
    Store-->>Engine: Ok
    Engine-->>Tool: kpi_id
    Tool-->>Agent: {"kpi_id": "..."}
    Agent->>Tool: growth.kpi.get_trend(kpi_name="MRR")
    Tool->>Engine: kpi().list_kpis(sid)
    Engine->>Store: objects.list("kpis")
    Store-->>Engine: Vec<KpiEntry>
    Tool->>Tool: filter by name, sort, compute delta
    Tool-->>Agent: {"previous": 10000, "latest": 12000, "delta": 2000}
    Agent-->>API: SSE chunks
    API-->>U: "MRR recorded at $12,000. Up $2,000 from last reading."

Extending the Department

Adding funnel drop-off analysis

1. Add a drop_off_rates(sid) method to FunnelManager that computes conversion percentages between consecutive stages
2. Register a growth.funnel.analyze tool in dept-growth/src/tools.rs
3. Add a quick action to the manifest

Adding churn detection

1. Implement a detect_churn(sid) method in CohortManager that identifies cohorts with declining retention
2. Wire events::CHURN_DETECTED emission when thresholds are crossed
3. Optionally use AgentPort for AI-powered churn prediction
4. Add to the manifest’s events_produced

Adding dashboard data endpoints

1. Add route contributions to the manifest for /api/dept/growth/dashboard
2. Implement a handler that aggregates funnel, cohort, and KPI data into a single response
3. Wire the route in rusvel-api

Port Dependencies

Distribution Department

Marketplace listings, SEO optimization, affiliate programs, partnerships.

Overview

The Distribution department manages distribution channels for a solo SaaS business: marketplace listings across platforms, SEO keyword tracking with position monitoring, and affiliate partner management with commission tracking. The engine provides three manager subsystems backed by ObjectStore.

Current Status: Skeleton

The distro engine has manager structures but minimal business logic (~390 lines total across lib.rs and three manager modules). The managers provide CRUD operations:

• MarketplaceManager – add_listing(sid, platform, name, url), list_listings(sid), publish_listing(sid, listing_id). Creates listings with ListingStatus (Draft/Published/Archived) and tracks revenue per listing.
• SeoManager – add_keyword(sid, keyword, position, volume), list_keywords(sid), track_ranking(sid, keyword_id, new_position). Tracks keyword positions and search volume.
• AffiliateManager – add_partner(sid, name, commission_rate), list_partners(sid), track_commission(sid, partner_id, amount). Manages affiliate partners with commission rates.

The department is fully registered and bootable – it appears in the department registry, responds to chat, and has 4 agent tools wired. However, it needs the following to be production-ready:

• Automated marketplace listing sync with real platforms
• SEO position history and trend analysis
• Affiliate link generation and click tracking
• Revenue attribution across channels
• Automated SEO audit recommendations via AgentPort
• Scheduled ranking checks via job queue

Engine Details

Crate: distro-engine (~390 lines)

Struct: DistroEngine

Constructor:

#![allow(unused)]
fn main() {
DistroEngine::new(
    storage: Arc<dyn StoragePort>,
    events: Arc<dyn EventPort>,
    agent: Arc<dyn AgentPort>,
    jobs: Arc<dyn JobPort>,
)
}

Managers:

Implements: rusvel_core::engine::Engine trait (kind: "distro", name: "Distribution Engine")

Manifest

Declared in dept-distro/src/manifest.rs:

id:            "distro"
name:          "Distribution Department"
description:   "Marketplace listings, SEO optimization, affiliate programs, partnerships, API distribution channels"
icon:          "!"
color:         "teal"
capabilities:  ["marketplace", "seo", "affiliate"]

System Prompt

You are the Distribution department of RUSVEL.

Focus: marketplace listings, SEO optimization, affiliate programs, partnerships, API distribution channels.

Tools

Tools registered at runtime via dept-distro/src/tools.rs (4 tools):

Personas

None declared in the manifest.

Skills

None declared in the manifest.

Rules

None declared in the manifest.

Jobs

None declared in the manifest. Future candidates:

• Scheduled SEO position checks
• Marketplace listing status sync
• Affiliate commission payouts

Events

Defined Constants (engine)

These constants are defined in the engine but are not yet emitted automatically by the manager methods. They are not listed in the manifest’s events_produced.

Consumed

None.

API Routes

None declared in the manifest. The department is accessible via the standard parameterized routes:

• GET /api/dept/distro/status – department status
• POST /api/dept/distro/chat – SSE chat

CLI Commands

Standard department CLI:

rusvel distro status    # One-shot status (alias: "distribution")
rusvel distro list      # List items
rusvel distro events    # Show events

Entity Auto-Discovery

The standard CRUD subsystems are available at /api/dept/distro/*:

• Agents, Skills, Rules, Hooks, Workflows, MCP Servers

Chat Flow

sequenceDiagram
    participant U as User
    participant API as /api/dept/distro/chat
    participant Agent as AgentRuntime
    participant Tool as distro.* tools
    participant Engine as DistroEngine
    participant Store as StoragePort

    U->>API: POST "Show me an SEO report"
    API->>Agent: run_streaming(system_prompt, tools)
    Agent->>Tool: distro.seo.analyze(session_id)
    Tool->>Engine: seo().list_keywords(sid)
    Engine->>Store: objects.list("keywords")
    Store-->>Engine: Vec<Keyword>
    Tool->>Tool: compute avg position, aggregate
    Tool-->>Agent: {"keyword_count": 5, "avg_position": 12.4, "keywords": [...]}
    Agent->>Tool: distro.analytics.report(session_id)
    Tool->>Engine: marketplace().list_listings(sid)
    Tool->>Engine: affiliate().list_partners(sid)
    Tool->>Engine: seo().list_keywords(sid)
    Engine-->>Tool: aggregated data
    Tool-->>Agent: full analytics report JSON
    Agent-->>API: SSE chunks
    API-->>U: "SEO Report: 5 keywords tracked, avg position 12.4. ..."

Extending the Department

Adding automated SEO audits

1. Add an audit(sid) method to SeoManager that calls AgentPort with keyword data for AI-powered recommendations
2. Register a distro.seo.audit tool in dept-distro/src/tools.rs
3. Add a scheduled job kind for periodic audits
4. Emit distro.seo.ranked events when position changes are detected

Adding marketplace sync

1. Implement platform-specific adapters (similar to content-engine’s LinkedIn/Twitter adapters)
2. Add a sync_listing(sid, listing_id) method that fetches live data from the platform
3. Wire a job kind for periodic sync

Adding revenue attribution

1. Extend MarketplaceManager to track revenue per listing over time
2. Extend AffiliateManager to compute total commissions earned per partner
3. Add a distro.revenue.attribution tool that breaks down revenue by channel
4. Wire the data into the analytics report tool

Port Dependencies

Legal Department

Contracts, IP protection, terms of service, GDPR compliance, licensing, privacy policies.

Overview

The Legal department manages the full contract lifecycle, compliance audits, and intellectual property tracking. It wraps legal-engine via the ADR-014 DepartmentApp pattern and is registered in the composition root alongside the other skeleton departments.

System Prompt

You are the Legal department of RUSVEL.

Focus: contracts, IP protection, terms of service, GDPR compliance, licensing, privacy policies.

Capabilities

Quick Actions

Architecture

Engine: legal-engine

Three manager structs compose the engine, each backed by ObjectStore via StoragePort:

Domain Types

Contract – ContractId (UUIDv7), ContractStatus enum (Draft, Sent, Signed, Expired, Cancelled), fields: title, counterparty, template, signed_at, expires_at, created_at, metadata.

ComplianceCheck – ComplianceCheckId (UUIDv7), ComplianceArea enum (GDPR, Privacy, Licensing, Tax), fields: description, passed, checked_at, notes, metadata.

IpAsset – IpAssetId (UUIDv7), IpKind enum (Patent, Trademark, Copyright, TradeSecret), fields: name, description, filed_at, status, metadata.

Wrapper: dept-legal

• LegalDepartment struct with OnceLock<Arc<LegalEngine>> for lazy initialization
• register() creates the engine, stores it, and registers agent tools
• shutdown() delegates to engine
• 2 unit tests (department creation, manifest purity)

Registered Tools

Events

Note: event constants are defined in legal_engine::events but emission is not yet wired into manager methods (skeleton status).

Required Ports

UI Contribution

Tabs: actions, agents, rules, events

No dashboard cards, settings panel, or custom components.

Chat Flow

sequenceDiagram
    participant User
    participant Frontend
    participant API as /api/dept/legal/chat
    participant Agent as AgentPort
    participant Engine as LegalEngine
    participant Store as ObjectStore

    User->>Frontend: "Draft an NDA for Acme Corp"
    Frontend->>API: POST (SSE)
    API->>Agent: run(system_prompt + user message)
    Agent->>Engine: legal.contracts.create(title, counterparty, template)
    Engine->>Store: objects().put("legal_contract", ...)
    Store-->>Engine: Ok
    Engine-->>Agent: { contract_id }
    Agent-->>API: SSE token stream
    API-->>Frontend: SSE events
    Frontend-->>User: "Created contract draft [id]"

CLI Usage

rusvel legal status          # Show department status
rusvel legal list             # List all legal items
rusvel legal list --kind contract  # List contracts only
rusvel legal events           # Show recent legal events

Testing

cargo test -p legal-engine    # Engine tests (contract CRUD, health check)
cargo test -p dept-legal      # Wrapper tests (manifest, department creation)

Current Status: Skeleton

The Legal department is fully registered and bootable within the RUSVEL department registry, but its business logic is minimal. Here is what exists and what remains to be built:

What exists:

• Manager structures with basic CRUD operations (create + list for each domain)
• Domain types with full serialization (Contract, ComplianceCheck, IpAsset)
• 4 agent tools registered in the scoped tool registry
• Event kind constants defined (but not yet emitted from manager methods)
• Engine implements the Engine trait with health check
• Unit tests for engine and wrapper

What needs to be built for production readiness:

• Wire emit_event() calls into manager methods so domain events actually fire
• Add review_contract, sign_contract operations to ContractManager
• Add mark_passed operation to ComplianceManager
• Add file_ip (full filing workflow with status transitions) to IpManager
• Implement AI-assisted contract drafting via AgentPort (template expansion)
• Add job kinds for async legal review workflows (e.g., JobKind::Custom("legal.review"))
• Build compliance report generation (aggregate check results into a report)
• Add engine-specific API routes (e.g., /api/dept/legal/contracts, /api/dept/legal/compliance)
• Add engine-specific CLI commands (e.g., rusvel legal draft, rusvel legal audit)
• Add personas for legal agent specialization
• Add skills and rules for legal workflows

Source Files

Support Department

Customer support tickets, knowledge base, NPS tracking, auto-triage, customer success.

Overview

The Support department handles customer-facing operations: ticket management with priority-based triage, a knowledge base for self-service articles, and Net Promoter Score (NPS) tracking for customer satisfaction measurement. It wraps support-engine via the ADR-014 DepartmentApp pattern.

System Prompt

You are the Support department of RUSVEL.

Focus: customer support tickets, knowledge base, NPS tracking, auto-triage, customer success.

Capabilities

Quick Actions

Architecture

Engine: support-engine

Three manager structs compose the engine, each backed by ObjectStore via StoragePort:

Domain Types

Ticket – TicketId (UUIDv7), TicketStatus enum (Open, InProgress, Resolved, Closed), TicketPriority enum (Low, Medium, High, Urgent), fields: subject, description, requester_email, assignee, created_at, resolved_at, metadata.

Article – ArticleId (UUIDv7), fields: title, content, tags, published, created_at, metadata.

NpsResponse – NpsResponseId (UUIDv7), fields: score (0-10), feedback, respondent, created_at, metadata.

Wrapper: dept-support

• SupportDepartment struct with OnceLock<Arc<SupportEngine>> for lazy initialization
• register() creates the engine, stores it, and registers agent tools
• shutdown() delegates to engine
• 2 unit tests (department creation, manifest purity)

Registered Tools

Events

Note: event constants are defined in support_engine::events but emission is not yet wired into manager methods (skeleton status).

Required Ports

UI Contribution

Tabs: actions, agents, skills, rules, events

No dashboard cards, settings panel, or custom components.

Chat Flow

sequenceDiagram
    participant User
    participant Frontend
    participant API as /api/dept/support/chat
    participant Agent as AgentPort
    participant Engine as SupportEngine
    participant Store as ObjectStore

    User->>Frontend: "Show open tickets sorted by priority"
    Frontend->>API: POST (SSE)
    API->>Agent: run(system_prompt + user message)
    Agent->>Engine: support.tickets.list(session_id)
    Engine->>Store: objects().list("support_ticket", filter)
    Store-->>Engine: Vec<Ticket>
    Engine-->>Agent: ticket list JSON
    Agent-->>API: SSE token stream
    API-->>Frontend: SSE events
    Frontend-->>User: Formatted ticket list with priorities

CLI Usage

rusvel support status         # Show department status
rusvel support list            # List all support items
rusvel support list --kind ticket  # List tickets only
rusvel support events          # Show recent support events

Testing

cargo test -p support-engine   # Engine tests (ticket CRUD, health check)
cargo test -p dept-support     # Wrapper tests (manifest, department creation)

Current Status: Skeleton

The Support department is fully registered and bootable within the RUSVEL department registry, but its business logic is minimal. Here is what exists and what remains to be built:

What exists:

• Manager structures with basic CRUD operations (create + list for tickets, articles, NPS)
• Domain types with full serialization (Ticket, Article, NpsResponse)
• NPS score calculation logic (promoters minus detractors percentage)
• 4 agent tools registered in the scoped tool registry
• Knowledge base search with keyword filtering (in-memory, case-insensitive)
• Event kind constants defined (but not yet emitted from manager methods)
• Engine implements the Engine trait with health check
• Unit tests for engine and wrapper

What needs to be built for production readiness:

• Wire emit_event() calls into manager methods so domain events actually fire
• Add resolve_ticket, assign_ticket operations to TicketManager
• Implement auto-triage: use AgentPort to classify incoming tickets by priority/category
• Add search_articles with proper full-text search (currently keyword match only)
• Build customer success metrics aggregation (ticket resolution time, first-response time)
• Add job kinds for async support workflows (e.g., JobKind::Custom("support.auto_triage"))
• Implement AI-assisted KB article generation via AgentPort
• Add engine-specific API routes (e.g., /api/dept/support/tickets, /api/dept/support/nps)
• Add engine-specific CLI commands (e.g., rusvel support triage, rusvel support kb)
• Add personas for support agent specialization (triage agent, KB writer)
• Add skills and rules for support workflows
• Build NPS trend analysis and reporting

Source Files

Infra Department

CI/CD pipelines, deployments, monitoring, incident response, performance, cost analysis.

Overview

The Infra department manages infrastructure operations: deployment tracking, health monitoring, and incident management. It wraps infra-engine via the ADR-014 DepartmentApp pattern and provides tools for recording deployments, running health checks, and managing incidents with severity levels.

System Prompt

You are the Infrastructure department of RUSVEL.

Focus: CI/CD pipelines, deployments, monitoring, incident response, performance, cost analysis.

Capabilities

Quick Actions

Architecture

Engine: infra-engine

Three manager structs compose the engine, each backed by ObjectStore via StoragePort:

Domain Types

Deployment – DeploymentId (UUIDv7), DeployStatus enum (Pending, InProgress, Deployed, Failed, RolledBack), fields: service, version, environment, deployed_at, created_at, metadata.

HealthCheck – HealthCheckId (UUIDv7), CheckStatus enum (Up, Down, Degraded), fields: service, endpoint, status, last_checked, response_ms, metadata.

Incident – IncidentId (UUIDv7), IncidentStatus enum (Open, Investigating, Mitigated, Resolved), Severity enum (P1, P2, P3, P4), fields: title, description, severity, status, opened_at, resolved_at, metadata.

Wrapper: dept-infra

• InfraDepartment struct with OnceLock<Arc<InfraEngine>> for lazy initialization
• register() creates the engine, stores it, and registers agent tools
• shutdown() delegates to engine
• 2 unit tests (department creation, manifest purity)

Registered Tools

Events

Note: event constants are defined in infra_engine::events but emission is not yet wired into manager methods (skeleton status).

Required Ports

UI Contribution

Tabs: actions, agents, rules, events

No dashboard cards, settings panel, or custom components.

Chat Flow

sequenceDiagram
    participant User
    participant Frontend
    participant API as /api/dept/infra/chat
    participant Agent as AgentPort
    participant Engine as InfraEngine
    participant Store as ObjectStore

    User->>Frontend: "Deploy rusvel-api v0.3.0 to production"
    Frontend->>API: POST (SSE)
    API->>Agent: run(system_prompt + user message)
    Agent->>Engine: infra.deploy.trigger(service, version, environment)
    Engine->>Store: objects().put("infra_deploy", ...)
    Store-->>Engine: Ok
    Engine-->>Agent: { deployment_id }
    Agent->>Engine: infra.monitor.status(session_id)
    Engine->>Store: objects().list("infra_healthcheck", filter)
    Store-->>Engine: Vec<HealthCheck>
    Engine-->>Agent: health summary JSON
    Agent-->>API: SSE token stream
    API-->>Frontend: SSE events
    Frontend-->>User: "Deployment recorded. All services healthy."

CLI Usage

rusvel infra status           # Show department status
rusvel infra list              # List all infra items
rusvel infra list --kind deploy  # List deployments only
rusvel infra events            # Show recent infra events

Testing

cargo test -p infra-engine     # Engine tests (deployment CRUD, health check)
cargo test -p dept-infra       # Wrapper tests (manifest, department creation)

Current Status: Skeleton

The Infra department is fully registered and bootable within the RUSVEL department registry, but its business logic is minimal. Here is what exists and what remains to be built:

What exists:

• Manager structures with basic CRUD operations (create + list for each domain)
• Domain types with full serialization (Deployment, HealthCheck, Incident)
• Health check status summary tool (counts down/degraded services)
• 4 agent tools registered in the scoped tool registry
• Event kind constants defined (but not yet emitted from manager methods)
• Engine implements the Engine trait with health check
• Unit tests for engine and wrapper

What needs to be built for production readiness:

• Wire emit_event() calls into manager methods so domain events actually fire
• Add mark_deployed, rollback operations to DeployManager
• Add run_health_check (actual HTTP probe) to MonitorManager
• Add resolve_incident, status transition logic to IncidentManager
• Implement deployment pipeline orchestration via AgentPort + JobPort
• Add job kinds for async infra workflows (e.g., JobKind::Custom("infra.deploy"), JobKind::Custom("infra.health_scan"))
• Build real monitoring: periodic health check scheduling via job queue
• Integrate with rusvel-deploy crate for actual deployment execution
• Add incident timeline tracking (status change history)
• Add engine-specific API routes (e.g., /api/dept/infra/deploys, /api/dept/infra/incidents)
• Add engine-specific CLI commands (e.g., rusvel infra deploy, rusvel infra health)
• Add personas for infra agent specialization (SRE agent, incident commander)
• Add skills and rules for incident response runbooks
• Build cost analysis and performance metrics aggregation

Source Files

Flow Department

DAG-based workflow automation – create, execute, and monitor directed acyclic graph workflows.

Overview

The Flow department provides a general-purpose DAG workflow engine built on petgraph. Workflows are defined as directed acyclic graphs of typed nodes (code, condition, agent, browser, parallel) connected by edges. The engine supports:

• Topological execution with parallel branch support
• Condition-based branching (true/false output ports)
• Agent nodes that delegate to AgentPort for LLM-driven steps
• Browser trigger and action nodes (CDP integration)
• Parallel evaluate nodes for multi-agent comparison
• Checkpoint persistence for resume after failure
• Single-node retry from checkpoint state

Engine Details

Crate: flow-engine (~600 lines in lib.rs, plus submodules for executor, expression, nodes, templates)

Struct: FlowEngine

Constructor:

#![allow(unused)]
fn main() {
FlowEngine::new(
    storage: Arc<dyn StoragePort>,
    events: Arc<dyn EventPort>,
    agent: Arc<dyn AgentPort>,
    terminal: Option<Arc<dyn TerminalPort>>,
    browser: Option<Arc<dyn BrowserPort>>,
)
}

Public methods:

Storage keys: flows, flow_executions, flow_checkpoints

Node Types

Manifest

Declared in dept-flow/src/manifest.rs:

id:            "flow"
name:          "Flow Department"
description:   "DAG workflow automation -- create, execute, and monitor workflows"
icon:          "~"
color:         "sky"
capabilities:  ["workflow_automation"]

System Prompt

You are the Flow department of RUSVEL.

Focus: DAG-based workflow automation.
Create, execute, and monitor directed acyclic graph workflows
with code, condition, and agent nodes.

Tools

Tools registered at runtime via dept-flow/src/tools.rs (7 tools):

Manifest also declares 3 tool contributions for discovery:

• flow.create – Create a new DAG workflow definition
• flow.execute – Execute a saved workflow by ID
• flow.list – List all saved workflows

Personas

Skills

Rules

None declared in the manifest.

Jobs

Events

Produced (manifest)

• flow.started
• flow.completed
• flow.failed

Emitted (engine runtime)

• flow.execution.completed – emitted after run_flow() and resume_flow() with payload { flow_id, execution_id, status }

Consumed

None.

API Routes

Declared in manifest (7 routes):

Additional route in rusvel-api (not in manifest):

• GET /api/flows/node-types – returns available node types (filters parallel_evaluate unless RUSVEL_FLOW_PARALLEL_EVALUATE=1)

CLI Commands

Manifest declares one command:

Entity Auto-Discovery

The standard CRUD subsystems are available for the Flow department at the parameterized /api/dept/flow/* routes:

• Agents, Skills, Rules, Hooks, Workflows, MCP Servers

These are auto-discovered from the department registry. No additional engine-specific entities.

Chat Flow

sequenceDiagram
    participant U as User
    participant API as /api/dept/flow/chat
    participant Agent as AgentRuntime
    participant Tool as flow.* tools
    participant Engine as FlowEngine
    participant Store as StoragePort
    participant Bus as EventPort

    U->>API: POST message (SSE)
    API->>Agent: run_streaming(system_prompt, tools)
    Agent->>Tool: flow.list()
    Tool->>Engine: list_flows()
    Engine->>Store: objects.list("flows")
    Store-->>Engine: Vec<FlowDef>
    Engine-->>Tool: flows
    Tool-->>Agent: JSON response
    Agent->>Tool: flow.run(flow_id, trigger_data)
    Tool->>Engine: run_flow(id, data)
    Engine->>Store: get_flow(id)
    Engine->>Engine: execute DAG (topological order)
    Engine->>Store: put execution record
    Engine->>Bus: emit flow.execution.completed
    Bus-->>Engine: EventId
    Engine-->>Tool: FlowExecution
    Tool-->>Agent: execution result
    Agent-->>API: SSE chunks
    API-->>U: streamed response

Extending the Department

Adding a new node type

1. Create a new module under flow-engine/src/nodes/ implementing the FlowNode trait
2. Register it in FlowEngine::new() via registry.register(Arc::new(YourNode))
3. The node becomes available in node_types() and usable in flow definitions

Adding new tools

Add tool registrations in dept-flow/src/tools.rs inside the register() function. Follow the existing pattern of cloning the engine Arc and using ctx.tools.add().

Adding events

Define event kind constants in the engine and emit them via self.events.emit(Event { ... }). Add the event kind strings to the manifest’s events_produced vector.

Port Dependencies

Optional ports (not in manifest requires_ports but accepted by engine constructor):

• TerminalPort – PTY management for terminal-based nodes
• BrowserPort – CDP browser automation for browser trigger/action nodes

Messaging Department

Outbound notifications and channel adapters (e.g. Telegram) when configured.

Overview

The Messaging department is a lightweight department shell with no dedicated engine crate. It exists to represent outbound notification capabilities in the department registry and provide a namespace for future multi-channel routing. Channel composition (Telegram, future Slack/Discord/email) is handled at the rusvel-app composition root, not inside an engine.

System Prompt

You are the Messaging department of RUSVEL.

Focus: outbound notifications, channel configuration, delivery status, and integration with external chat platforms when available.

Capabilities

Quick Actions

Why There Is No Engine

Unlike other departments that wrap a dedicated *-engine crate, Messaging has no messaging-engine. This is an intentional architectural choice:

1. Channel composition belongs at the app level. The ChannelPort trait is defined in rusvel-core and implemented by adapter crates (e.g., rusvel-channel). The composition root (rusvel-app/src/main.rs) wires the channel adapter into AppState based on environment variables. This follows the hexagonal pattern: the port lives in core, the adapter lives in its own crate, and wiring happens at the composition root.

2. No domain logic yet. Sending a notification is a single send_message() call on ChannelPort. There is no complex domain state (no entities to CRUD, no workflows to orchestrate) that would justify an engine crate.

3. Registered last. dept-messaging is the last entry in installed_departments() in rusvel-app/src/boot.rs, ensuring all domain departments are registered before the channel shell.

ChannelPort and rusvel-channel

The Port (rusvel-core)

#![allow(unused)]
fn main() {
// crates/rusvel-core/src/ports.rs
#[async_trait]
pub trait ChannelPort: Send + Sync {
    fn channel_kind(&self) -> &'static str;
    async fn send_message(&self, session_id: &SessionId, payload: serde_json::Value) -> Result<()>;
}
}

ChannelPort is one of the 22 port traits in rusvel-core. It defines a minimal interface: identify the channel kind (e.g., "telegram") and send a message with a JSON payload scoped to a session.

The Adapter: TelegramChannel (rusvel-channel)

rusvel-channel provides TelegramChannel, the first ChannelPort implementation. It sends messages via the Telegram Bot API (sendMessage endpoint).

Configuration (environment variables):

Initialization: TelegramChannel::from_env() returns Option<Arc<TelegramChannel>>. It returns None when RUSVEL_TELEGRAM_BOT_TOKEN is unset or empty, so the app gracefully degrades when Telegram is not configured.

Payload format:

{
  "text": "Message body (required; 'message' is also accepted as alias)",
  "chat_id": "Optional override for default chat ID"
}

Message format sent to Telegram: [session <session_id>] <text>

Wiring in the Composition Root

In rusvel-app/src/main.rs, the channel is wired into AppState:

#![allow(unused)]
fn main() {
let channel: Option<Arc<dyn ChannelPort>> = TelegramChannel::from_env()
    .map(|t| t as Arc<dyn ChannelPort>);
}

The AppState.channel field is Option<Arc<dyn ChannelPort>>, making it available to API handlers.

The Notify API Endpoint

POST /api/system/notify

Request body:

{
  "session_id": "uuid",
  "text": "Notification message"
}

Behavior:

• If state.channel is Some, wraps text into {"text": text} and calls channel.send_message()
• If state.channel is None, returns 503 Service Unavailable with "notify channel not configured"
• On Telegram API failure, returns 502 Bad Gateway with the error message
• On success, returns 204 No Content

Example:

curl -X POST http://localhost:3000/api/system/notify \
  -H "Content-Type: application/json" \
  -d '{"session_id": "...", "text": "Build completed successfully"}'

Required Ports

These ports are inherited defaults from the DepartmentManifest structure. The messaging department does not currently use any of them directly – it has no register() logic beyond logging.

UI Contribution

Tabs: actions, agents, rules, events

No dashboard cards, settings panel, or custom components.

Chat Flow

sequenceDiagram
    participant User
    participant Frontend
    participant API as /api/dept/messaging/chat
    participant Agent as AgentPort

    User->>Frontend: "What channels are configured?"
    Frontend->>API: POST (SSE)
    API->>Agent: run(system_prompt + user message)
    Note over Agent: No engine tools available.<br/>Agent answers from system prompt<br/>and general knowledge.
    Agent-->>API: SSE token stream
    API-->>Frontend: SSE events
    Frontend-->>User: Channel configuration explanation

Note: since no engine tools are registered, the messaging agent operates purely through its system prompt and general knowledge. It cannot currently inspect actual channel configuration at runtime.

Notify Flow (System Endpoint)

sequenceDiagram
    participant Caller
    participant API as POST /api/system/notify
    participant State as AppState
    participant Channel as ChannelPort
    participant Telegram as Telegram API

    Caller->>API: { session_id, text }
    API->>State: state.channel?
    alt Channel configured
        State-->>API: Some(channel)
        API->>Channel: send_message(session_id, {text})
        Channel->>Telegram: POST /bot<token>/sendMessage
        Telegram-->>Channel: 200 OK
        Channel-->>API: Ok
        API-->>Caller: 204 No Content
    else No channel
        State-->>API: None
        API-->>Caller: 503 Service Unavailable
    end

Boot Order

installed_departments() order:
  1. forge       (core)
  2. code        (core)
  3. content     (cross-dept events)
  4. harvest     (cross-dept events)
  5. flow        (cross-dept events)
  6. gtm         (progressive enhancement)
  7. finance     (progressive enhancement)
  8. product     (progressive enhancement)
  9. growth      (progressive enhancement)
 10. distro      (progressive enhancement)
 11. legal       (skeleton)
 12. support     (skeleton)
 13. infra       (skeleton)
 14. messaging   <-- registered last

CLI Usage

rusvel messaging status       # Show department status (via generic dept handler)
rusvel messaging list          # List items (empty -- no domain objects)
rusvel messaging events        # Show recent messaging events (none emitted currently)

Testing

cargo test -p dept-messaging   # Wrapper test (manifest ID check, port requirements)

No engine tests since there is no engine crate.

Future: Multi-Channel Routing

This is where multi-channel routing would live as the department matures:

• Slack adapter – Implement ChannelPort for Slack Webhook/API, register in rusvel-channel
• Discord adapter – Implement ChannelPort for Discord Webhook
• Email adapter – Implement ChannelPort for SMTP (complement to the RUSVEL_SMTP_* config already used by GTM outreach)
• Channel router – A MultiChannelRouter that wraps multiple ChannelPort implementations and routes based on message type, urgency, or user preference
• Messaging engine – Once routing logic becomes complex enough, extract a messaging-engine crate with delivery queuing, retry policies, and delivery status tracking
• Delivery events – Emit messaging.sent, messaging.failed, messaging.delivered events for observability
• Department tools – Register tools like messaging.send, messaging.channels.list, messaging.delivery.status

Source Files

Reference

Technical reference documentation for RUSVEL’s interfaces.

• Repository Status — Current metrics and build health
• CLI — Command-line interface reference
• API — REST API endpoints
• Configuration — Settings and environment variables

Repository status

The canonical metrics, feature inventory, and gaps for the RUSVEL codebase live in the main repository under docs/. This page summarizes what shipped as of the last audit and links to the full Markdown (always current on main).

Canonical sources (GitHub)

When this mdBook page and the repo diverge, trust the repo files above and refresh the tables below on the next audit.

Metric definitions (abbrev.)

Numbers at a glance (2026-03-30)

Gaps (explicit)

• GTM / CRM depth — OutreachSend job path is wired (approval-gated, gtm-engine); more CRM surfaces and polish remain.
• Auth — not full API middleware; env/in-memory style for many paths.
• Depth — Several business engines are thinner than Forge/Code/Content/Harvest/Flow; department chat still works via DepartmentApp.

How to re-verify

cargo build
cargo test
cargo metadata --format-version 1 --no-deps | python3 -c "import json,sys; print(len(json.load(sys.stdin)['workspace_members']))"
find crates -name '*.rs' | wc -l
wc -l $(find crates -name '*.rs') | tail -1
rg '\.route\(' crates/rusvel-api/src/lib.rs | wc -l

Some tests (e.g. terminal PTY) may fail in restricted environments.

CLI

Overview

RUSVEL provides a three-tier CLI using Clap 4. The binary is rusvel (or cargo run -- during development).

rusvel <dept> <action>     # Tier 1: One-shot commands (12 depts; 14 apps in API/UI — see below)
rusvel shell               # Tier 2: Interactive REPL (reedline, autocomplete, history)
rusvel --tui               # Tier 3: TUI dashboard (ratatui, 4-panel layout)

Global Options

Starting the Server

rusvel (no subcommand)

Starts the API web server on 0.0.0.0:3000. Serves the REST API and the embedded SvelteKit frontend.

cargo run

rusvel --mcp

Starts the MCP (Model Context Protocol) server over stdio. Used for integration with Claude Desktop and other MCP clients.

cargo run -- --mcp

rusvel --tui

Launches the TUI dashboard with 4 panels: Tasks, Goals, Pipeline, Events. Press q to exit.

cargo run -- --tui

Tier 1: Department One-Shot Commands

These one-shot actions are registered for 12 departments (Tier 1). The web app and API register 14 DepartmentApp instances (flow and messaging are not in this Tier 1 list).

rusvel <dept> status              # Show department status summary
rusvel <dept> list [--kind X]     # List department items
rusvel <dept> events              # Show recent events for department

Tier 1 departments: forge, code, content, harvest, gtm, finance, product, growth, distro, legal, support, infra

Engine-Specific Commands

Some departments have additional commands powered by their wired engines:

# Code department
rusvel code analyze [path]        # Analyze code: parser, dependency graph, metrics
rusvel code search <query>        # BM25 search across codebase

# Content department
rusvel content draft <topic>      # Draft content on a topic
rusvel content from-code          # Generate content from code analysis

# Harvest department
rusvel harvest pipeline           # Show opportunity pipeline

Forge Commands

rusvel forge mission today        # Generate a prioritized daily plan
rusvel forge mission goals        # List all goals for active session
rusvel forge mission goal add <title>  # Add a new goal
rusvel forge mission review       # Generate a periodic review

Options for goal add:

Options for review:

Tier 2: Interactive REPL

rusvel shell

Launches an interactive shell powered by reedline with:

• Tab completion for commands and department names
• Ctrl+R history search
• use <dept> to switch department context
• All Tier 1 commands available without the rusvel prefix

Session Management

rusvel session create <name>      # Create a new session
rusvel session list               # List all sessions
rusvel session switch <id>        # Switch active session

The CLI stores the active session ID in ~/.rusvel/active_session. All forge commands operate on this session.

If no active session is set, commands that require one will error:

Error: No active session. Run `rusvel session create <name>` first.

Active Session

The CLI stores the active session ID in ~/.rusvel/active_session. All forge commands operate on this session. Change it with session switch.

API

Overview

RUSVEL exposes a JSON REST API on port 3000 via Axum. All endpoints use the /api/ prefix. CORS is enabled for all origins.

Scale (verify on main): the main router in crates/rusvel-api/src/lib.rs registers 153 .route( chains. Handler logic is split across 39 modules (one *.rs per module, excluding lib.rs). That is not the same as “153 HTTP methods” — a single chain can register get().post().

Router modules: agents, analytics, approvals, auth, browser, build_cmd, capability, chat, config, cron, db_routes, department, engine_routes, flow_routes, help, hook_dispatch, hooks, jobs, kits, knowledge, mcp_servers, pipeline_runner, playbooks, routes, rules, skills, system, terminal, visual_report, webhooks, workflows.