AI-Assisted Development

HORUS is built for vibe coding. Every error includes a fix command. Every API is extractable as JSON. AI agents can understand, build, test, and fix your robotics project without human intervention.

The AI Development Loop

An AI agent working on a HORUS project follows this loop:

1. Understand the project    horus doc --extract --json
2. Build and check           horus build --json-diagnostics
3. Parse errors              (structured JSON, one per line)
4. Auto-fix                  Execute the "fix" command from each diagnostic
5. Run tests                 horus test
6. Check what changed        horus doc --extract --diff baseline.json
7. Repeat

Every step produces machine-readable output. No regex parsing of compiler errors needed.

Structured Error Diagnostics

Enable JSON diagnostics

horus build --json-diagnostics
horus run --json-diagnostics

Every error, warning, and hint is emitted as a JSON object on stderr:

{"tool":"cargo","code":"H001","severity":"error","message":"Crate 'serde' not found on crates.io","hint":"Check the name or add it with:\n  horus add serde","fix":{"type":"command","command":"horus add serde"},"docs_url":"https://horus.dev/errors/missing-crate"}

The Fix Field

Every diagnostic includes a fix field that the AI agent can execute directly:

{
  "fix": {
    "type": "command",
    "command": "horus add serde"
  }
}

The agent parses this, runs horus add serde, and the dependency is installed. No guessing.

Error Code Catalog

Diagnostics use standardized codes (H001-H064) grouped by tool:

JSON Output for Build/Test Results

# Build with JSON result
horus build --json
# Output: {"success": true, "command": "build"}
# Or:     {"success": false, "command": "build", "errors": [{"message": "..."}]}

# Test with JSON result
horus test --json
# Output: {"success": true, "command": "test"}

API Extraction for Context

AI agents need to understand the project's API surface before making changes. horus doc --extract provides this in a single command.

Quick Overview

# Brief text summary (fits in any context window)
horus doc --extract

Output:

# my_robot v0.1.0 — 24 symbols, 78% documented
# 3 nodes, 4 messages, 5 topics

## Message Types
  CmdVel { linear: f32, angular: f32 }
  Odometry { x: f64, y: f64, theta: f64 }

## Nodes
  ControllerNode (impl Node) [100hz, Rt]
    pub -> cmd_vel: CmdVel
    sub <- odom: Odometry
  SensorNode (impl Node) [200hz, Rt]
    pub -> imu: ImuReading

## Topic Graph
  cmd_vel: CmdVel      ControllerNode -> MotorDriver
  odom: Odometry        MotorDriver -> ControllerNode

## src/controller.rs — PID controller
  struct ControllerNode { pid: PidState }
    impl Node
    fn new(kp: f64, ki: f64, kd: f64) -> Result<Self>

Full JSON for Programmatic Access

horus doc --extract --json

Returns a ProjectDoc with:

• All symbols (functions, structs, enums, traits, messages, services, actions)
• Doc comments and deprecation annotations
• Trait implementations and method associations
• Message flow graph (which nodes publish/subscribe to which topics)
• Entry points (main functions, Node implementations)
• Documentation coverage statistics

Markdown for LLM System Prompts

horus doc --extract --md > api.md

Produces markdown suitable for injecting into an LLM's context window. Include in your CLAUDE.md or system prompt:

# Project API Reference
Run `horus doc --extract --md` for current API surface.

Write to File

horus doc --extract --json -o api.json
horus doc --extract --html -o docs/api.html

Filter by Language

horus doc --extract --lang rust      # Only Rust symbols
horus doc --extract --lang python    # Only Python symbols

API Diff for Change Detection

Compare the current API against a saved baseline to detect breaking changes:

# Save baseline (e.g., on main branch)
horus doc --extract --json -o baseline.json

# After changes, diff against baseline
horus doc --extract --diff baseline.json

Output:

API Changes:

  Added:
    + src/sensors/lidar.rs: function pub fn calibrate(&mut self)

  Removed:  [!] BREAKING
    - src/legacy.rs: function pub fn old_handler()

  Changed:
    ~ src/controller.rs: function compute
      was: pub fn compute(&mut self, setpoint: f64, measurement: f64) -> f64
      now: pub fn compute(&mut self, setpoint: f64, measurement: f64, dt: f64) -> f64
      [!] BREAKING: added parameter `dt: f64`

  Summary: +1 added, -1 removed, ~1 changed, 1 breaking changes

CI Integration

# Fail CI if breaking changes detected
horus doc --extract --diff baseline.json
# Exit code 1 if breaking changes found, 0 otherwise

Documentation Coverage Gate

# Fail if coverage drops below 60%
horus doc --extract --coverage --fail-under 60

Watch Mode for Live Development

# Regenerate docs on every file save
horus doc --extract --watch

# Write to file on every change
horus doc --extract --json --watch -o api.json

The agent can poll api.json to stay updated as the code changes.

Self-Contained HTML Report

horus doc --extract --html -o api-docs.html

Generates a single HTML file with:

• Embedded CSS (dark mode support)
• Client-side search
• Collapsible module sections
• SVG topic flow graph
• Coverage table
• TODO/FIXME list

No external dependencies — works offline, safe to share.

Typical Agent Workflow

Step 1: Understand the project

horus doc --extract --json -o api.json
# Agent reads api.json, understands:
# - What nodes exist and their topics
# - What message types are defined
# - What the public API surface looks like

Step 2: Make changes

The agent edits source files based on the API understanding.

Step 3: Build and auto-fix

horus build --json-diagnostics 2> errors.jsonl
# Agent parses each line, extracts "fix" commands, executes them
# Example: {"fix": {"type": "command", "command": "horus add tokio"}}
#   Agent runs: horus add tokio
# Rebuild until no errors

Step 4: Verify

horus test --json
horus doc --extract --diff baseline.json --json
# Agent checks: tests pass? Any breaking changes?

Step 5: Report

horus doc --extract --coverage
# Agent reports: documentation coverage, new symbols, changes

CLAUDE.md Integration

Add to your project's CLAUDE.md for AI agents:

## Build Commands
horus build --json-diagnostics  # Build with structured errors
horus test --json               # Run tests
horus doc --extract --json      # Get API surface

## Auto-Fix Workflow
When build fails, parse stderr JSON lines.
Each diagnostic has a "fix" field with a command to run.
Execute fix commands, then rebuild.

## API Understanding
Run `horus doc --extract --brief` to see the project API.
The topic graph shows message flow between nodes.

See Also

• CLI Reference — Full command documentation
• Testing Guide — Writing and running tests
• Error Handling — Error codes and diagnostics