sova AGENTS.md

AI Agent Guidance for SOVA

This file provides cross-cutting guidance for any AI agent (Claude Code, Cursor, CodeRabbit, etc.) working in this repository.

SOVA (Software Orchestration Via Agents) is a standalone application that any software project can install to gain autonomous AI-assisted development capabilities. It takes issues from your tracker, develops solutions using TDD, self-reviews, creates PRs, monitors CI, addresses review feedback, and learns from mistakes. The system is written in Python (CLI, roles, scheduler, dashboard).

Context Index

Project Structure

sova/
  sova/                            # Python package (SOVA)
    cli/                           # Typer CLI (sova run, sova triage, etc.)
      app.py                       # Main app, subcommand registration
      commands/                    # Command modules (run, triage, harden, project, pr, admin, briefing, memory, migrate, commands, server, mcp, supervisor)
    core/                          # Workflow engine, steps, state machine, context, output writer, DAG executor
    roles/                         # Agent roles (triage, researcher, developer, reviewer, custom, planner, dispatcher)
    adapters/                      # Task source plugins (github; jira, linear, manual planned)
    llm/                           # Claude CLI wrapper, cost tracking
    git/                           # Git operations (branch, pr, rebase), worktree management
    ipc/                           # Inter-process: handoff protocol, process control, notifications
    knowledge/                     # Memory CRUD, tier loading, personas, review patterns
    scheduler/                     # Watch loop, parallel executor, server daemon
    dashboard/                     # FastAPI web UI
      app.py                       # App factory
      routers/                     # 28 API routers (overview, runs, costs, control, feed, handoff, lifecycle, memory, logs, tasks, queue, quota, settings, setup, agents, work, roles, spec, prs, dependencies, resources, supervisor, oversight, fleet_manager, fleet_insights, telemetry, a2a, mcp)
      services/                    # 40 services (run, cost, memory, control, feed, handoff, lifecycle, queue, batch, work, work_item, task, log, settings, setup, agent_lifecycle, agent_output, agent_recovery, agent_handoff, agent_pool, agent_db, agent_status, agent_context, agent_progress, agent_validation, output, role, spec, pr, pr_metrics, resource, llm_suggestion, output_stream, fleet, fleet_manager, supervisor, oversight, telemetry_push, merge_queue_monitor, mcp_service)
      templates/                   # Jinja2 HTML (Catppuccin dark + Tailwind)
      static/                      # JS + CSS + favicon + logo
    a2a/                           # A2A (Agent-to-Agent) protocol: agent card generation, task state mapping
    mcp/                           # MCP stdio server (provider-agnostic agent tools via Model Context Protocol)
    dashboard/routers/mcp.py       # MCP HTTP endpoint for agent self-inspection (read-only runtime queries)
    dashboard/services/mcp_service.py  # MCP token generation/validation and tool handlers
    awareness/                     # Awareness subsystem (AwarenessProvider ABC, AwarenessItem, ItemCategory, provider registry, BriefingService aggregation engine, rendering models, rendering/cli_renderer.py Rich terminal output)
    oversight/                     # Oversight agent: background daemon, operations persona (user-maintained LLM guidance)
    supervisor/                    # Supervisor-level services (TaskProgressionEngine, CodeRabbit quota, task dependency graph)
      gates/                       # Gate check functions (one per module): rate_limit, memory_pressure, dependency, human_involvement, quota, ci_budget, slots, budget, already_running, repeated_failure, ownership, merge_conflict, file_conflict, circuit_breaker
    commands/                      # Command + guideline distribution (catalog, templates, manifest, distribution)
    config/                        # Pydantic Settings + TOML config + project registry + request context
    monitoring/                     # Resource monitoring (psutil-based CPU, memory, I/O tracking)
    db/                            # SQLAlchemy ORM models + async session
    utils/                         # Logging, shell, formatting
  commands/                        # 28 standardized commands (markdown with category frontmatter)
  .githooks/                       # Git hooks (tracked, mirroring CI checks)
  invariants/                      # Pre-push constraint check scripts (bash)
  guidelines/                      # Distributable guideline templates (installed to .claude/rules/)
  skills/                          # Distributable skill templates (installed to .claude/skills/)
  personas/                        # Tech-stack-specific guidance (markdown)
  knowledge/
    KNOWLEDGE.md                   # 4-tier knowledge management system
  templates/                       # Project scaffolding templates
  deploy/                          # systemd + launchd service files
  tests/                           # pytest suite (3200+ tests, 7288 at last count)
  docs/
    VISION.md                      # Product vision and roadmap
    ARCHITECTURE.md                # Architecture overview (points to .claude/rules/)
    *-guidelines.md                # Domain-specific guidelines (7 files)
    design-system.md               # Dashboard design system reference
    handoff-protocol.md            # Agent handoff protocol
    naming-journey.md              # How SOVA got its name
  assets/
    agent-icon.png                 # Notification icon