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)