agent_specifications - lgcorzo/rust_CACD_autonomous_factory GitHub Wiki

iso_doc_type: "Description" iso_viewpoint: "ArchitectureDescription" type: "architecture" title: "Agent Specifications โ€” Dark Gravity CA/CD Autonomous Factory" description: "ISO 42010 ArchitectureDescription / ISO 15289 Description documentation for Agent Specifications โ€” Dark Gravity CA/CD Autonomous Factory." tags: ['iso42010', 'okf', 'architecture_description', 'c4'] timestamp: "2026-10-01T14:00:00Z" generated: "agent:okf-professional-documenter" verified: "true" last_verified_commit: "fbdc5848"

Agent Specifications โ€” Dark Gravity CA/CD Autonomous Factory

Purpose: Consolidated specification of all 6 factory agents with shared trait interface, behavioral descriptions, tool authorization, and comparative analysis.

1. Agent Trait Interface

All agents implement the shared Agent trait defined in factory-application/src/lib.rs:

classDiagram
    class Agent {
        <<trait>>
        +name() String
        +execute(task_description) Result~Value~
    }

    class RustantAgent {
        -Arc~McpClient~ mcp_client
        -Arc~R2rClient~ r2r_client
        +plan_mission(mission_id, goal) Result~Value~
        +review_mission(mission_id, results) Result~Value~
        +parse_sdd_tasks(content)$ Vec~SddTaskItem~
    }

    class ZeroClawAgent {
        -Arc~McpClient~ mcp_client
        -Arc~AethalgardClient~ aethalgard_client
        +execute_task(mission_id, description, files) Result~Value~
        +execute_tdd_task(mission_id, task) Result~Value~
        +validate_mission(mission_id, test_command) Result~Value~
        +introspect_k8s(mission_id) Result~Value~
        +validate_sandbox_constraints(app, sidecar)$ Result
    }

    class AuditorAgent {
        +analyze_dag_logs(mission_id) Result~Vec~Value~~
        +audit_mission(mission_id, failures) Result~Value~
        +evaluate_prompts(mission_id, targets, recs) Result~String~
    }

    class FinOpsAgent {
        -String litellm_base_url
        -String api_key
        -Client client
        -FinOpsTag tag
        +inject_vtags(request) RequestBuilder
        +evaluate_spend_delta(current, previous, max) BudgetEvaluation
        +dispatch_budget_exceeded_event(kafka, mission, spend, max) Result
        +monitor_budget() Result
    }

    class QAObserverAgent {
        +observe_quality(mission_id) Result~Value~
    }

    class DocumentationAgent {
        +generate_wiki(mission_id) Result~Value~
        +calculate_osr(mission_id) Result~OsrMetric~
    }

    Agent <|.. RustantAgent
    Agent <|.. ZeroClawAgent
    Agent <|.. AuditorAgent
    Agent <|.. FinOpsAgent
    Agent <|.. QAObserverAgent
    Agent <|.. DocumentationAgent
Loading

2. Agent Behavioral Specifications

RustantAgent โ€” Strategic Planner

Attribute Value
Role Mission planner: decomposes goals into Spec-Kit SDD task sequences
DAG Phase Phase 2 (Plan) + Phase 5 (Review)
Dependencies McpClient (MCP tools), R2rClient (GraphRAG context)
Key Flow R2R context retrieval โ†’ 6-phase Spec-Kit sequence โ†’ Parse tasks.md โ†’ Emit SddMissionPlan
SDD Phases init โ†’ specify โ†’ plan โ†’ execute โ†’ verify โ†’ git-commit

ZeroClawAgent โ€” TDD Developer

Attribute Value
Role Code developer: executes tasks in gVisor sandboxes with TDD discipline
DAG Phase Phase 3 (Code) + Phase 4 (Validation)
Dependencies McpClient (sandbox tools), AethalgardClient (circuit breaker)
Key Flow Load checkpoint โ†’ SAST pre-scan โ†’ Sandbox execution โ†’ TDD Red/Green โ†’ Validation
Circuit Breaker 3 retries max; escalates to Aethalgard on stagnant diff hash

AuditorAgent โ€” Security & Quality Auditor

Attribute Value
Role Audits DAG failures, generates recommendations, optimizes agent prompts
DAG Phase Phase 5 (Review)
Dependencies Hatchet API (failure logs), LiteLLM (analysis), async-openai
Key Flow Fetch failed DAG logs โ†’ LLM analysis โ†’ Generate recommendations โ†’ Prompt engineering loop
FinOps Tags x-vtags-team: dark-gravity-ops, x-vtags-epic: E6.3

FinOpsAgent โ€” Financial Operations

Attribute Value
Role Monitors LLM token spend, enforces budget limits, detects anomalies
DAG Phase Cross-cutting (runs continuously)
Dependencies LiteLLM spend API, KafkaClient (budget events)
Key Flow Poll LiteLLM /spend/logs โ†’ Evaluate spend delta โ†’ Alert/Hardstop
Thresholds Velocity: > $1.00/min โ†’ Alert; 90% of daily budget โ†’ Hardstop

QAObserverAgent โ€” Quality Assurance

Attribute Value
Role Monitors test coverage, enforces quality gates
DAG Phase Phase 4 (Validation)

DocumentationAgent โ€” Wiki Generator

Attribute Value
Role Generates wiki content, calculates OSR, triggers doc-sync
DAG Phase Phase 6 (Delivery)
Quality Gate OSR < 5% (all public AST symbols documented)

3. Tool Authorization Matrix

Tool Rustant ZeroClaw Auditor FinOps QA Doc
plan_mission โœ… โŒ โŒ โŒ โŒ โŒ
invoke_spec_kit โœ… โŒ โŒ โŒ โŒ โŒ
security_review โœ… โœ… โŒ โŒ โŒ โŒ
launch_sandbox_pod โŒ โœ… โŒ โŒ โŒ โŒ
execute_code โŒ โœ… โŒ โŒ โŒ โŒ
run_tests โŒ โœ… โŒ โŒ โŒ โŒ
sync_bridge_state โŒ โœ… โŒ โŒ โŒ โŒ
introspect_k8s โŒ โœ… โŒ โŒ โŒ โŒ
retrieve_context โœ… โŒ โŒ โŒ โŒ โœ…
search_jira โœ… โŒ โŒ โŒ โŒ โŒ

4. Comparative Behavioral Matrix

graph TB
    subgraph "Planning Agents"
        RUST["RustantAgent<br/>SDD Planner"]
    end
    subgraph "Execution Agents"
        ZC["ZeroClawAgent<br/>TDD Developer"]
    end
    subgraph "Verification Agents"
        AUD["AuditorAgent<br/>Security Review"]
        QA["QAObserverAgent<br/>Quality Gates"]
    end
    subgraph "Cross-Cutting Agents"
        FIN["FinOpsAgent<br/>Budget Control"]
        DOC["DocumentationAgent<br/>Wiki Sync"]
    end

    RUST -->|"SddMissionPlan"| ZC
    ZC -->|"Code Changes"| AUD
    ZC -->|"Test Results"| QA
    FIN -.->|"Budget Check"| ZC
    DOC -.->|"OSR Check"| RUST

    style RUST fill:#2196F3,stroke:#1565C0,color:#fff
    style ZC fill:#FF9800,stroke:#E65100,color:#fff
    style AUD fill:#f44336,stroke:#c62828,color:#fff
    style FIN fill:#4CAF50,stroke:#2E7D32,color:#fff
Loading

Related: Tactical Design ยท Experiment Lifecycle

โš ๏ธ **GitHub.com Fallback** โš ๏ธ