Orchestrata Ultimate / Specs / 101-ultimate-architecture

101-ultimate-architecture: Ultimate Hybrid Architecture

The Ultimate Hybrid Architecture combines multiple powerful technologies into a unified development environment. This architecture merges the terminal-based productivity of CheetahClaws TUI with the enterprise-grade multi-agent orchestration of Orchestrata, enhanced by VizInt web interface, OpenRouter model flexibility, and Todoist task management integration.

At a glance

Reading this spec

This is the umbrella architecture spec for the Ultimate Hybrid system. It combines the terminal productivity of the CheetahClaws TUI with Orchestrata's multi-agent orchestration, and adds the VizInt web interface, OpenRouter model flexibility and Todoist task management. Its stated goal is a unified development environment that surpasses Claude Code's capabilities. It ties together the component specs 050, 051, 052, 053 and 060.

The design: the CheetahClaws TUI is the terminal interface for file operations, the Orchestrata kernel manages multi-agent coordination over the CXP protocol, VizInt provides project management, task orchestration and configuration in the browser, and OpenRouter routes across providers. The spec offers both a terminal and a web workflow, parallel multi-agent execution with model routing, project and task management, and rollback, audit trails and knowledge graph integration.

Eight user stories give the scope: terminal TUI workflow, web UI project management, Todoist task integration, multi-agent file editing and model flexibility (all rated critical), plus parallel task execution, checkpoint and rollback, and knowledge graph integration (rated high). Five standardized acceptance criteria (SAC-001 to SAC-005) cover TUI integration, VizInt functionality, Todoist synchronization, multi-agent coordination and OpenRouter routing. The 245 requirement IDs (REQ-101-NNN) are grouped per user story and acceptance criterion, with a larger general group. Examples: all CheetahClaws commands are accessible through /command syntax; task priority and due date synchronize with Todoist; fallback models are used transparently when a model is unavailable; selective rollback is supported (files only, conversations only); a corrupted checkpoint is rejected and a new one created; checkpoint creation completes in under 500 ms at p95; an audit trail covers all agent interactions; role-based access control applies to projects; the API returns 429 on rate limit and 410 Gone with a migration guide for deprecated features; and the system degrades gracefully when components fail. Data models include UltimateProject and the volk configuration.

No code module cites this spec, which describes the whole system rather than one module. The requirements traceability matrix lists every ID. The spec's own status line reads Complete and it tracks 2 files. No src/ symbol cites any of the 245 requirements, so measured trace coverage is 0.0%, and in tests/, 0 requirements are cited by a test-side @traces. All 245 requirements have no citing symbol; untraced means no @traces names the ID, and the behaviour may still exist in code that was never annotated.

Requirements

Checkbox is the state recorded in the requirements checklist; Traced by is the count of src/ symbols whose @traces names the ID.

Code that traces this spec

No src/ symbol cites a requirement of this spec.

Other tracked files

• specs/101-ultimate-architecture/compliance-audit.md

Full spec text

Verbatim from specs/101-ultimate-architecture/spec.md; headings are pushed down two levels.

SPEC-101: Ultimate Hybrid Architecture

Metadata

• Spec ID: 101-ultimate-architecture
• Title: Ultimate Hybrid Architecture - CheetahClaws + Orchestrata + VizInt
• Author: Mohamed
• Status: Complete
• Created: 2026-04-08
• Last Updated: 2026-04-08
• Priority: P0
• Version: 1.0.0

Overview

The Ultimate Hybrid Architecture combines multiple powerful technologies into a unified development environment. This architecture merges the terminal-based productivity of CheetahClaws TUI with the enterprise-grade multi-agent orchestration of Orchestrata, enhanced by VizInt web interface, OpenRouter model flexibility, and Todoist task management integration.

What

The Ultimate Hybrid Architecture merges CheetahClaws' rich TUI and file editing capabilities with Orchestrata's multi-agent orchestration, enhanced with VizInt web UI, OpenRouter model flexibility, and Todoist task management. This creates a system that surpasses Claude Code's capabilities.

Why

• Combine CheetahClaws' usability with Orchestrata's enterprise features
• Provide both terminal TUI and modern web UI for different workflows
• Enable parallel multi-agent execution with intelligent model routing
• Implement comprehensive project and task management
• Support rollback, audit trails, and knowledge graph integration

How

• CheetahClaws TUI serves as the terminal interface for file operations
• Orchestrata kernel manages multi-agent coordination via CXP protocol
• VizInt web UI provides project management, task orchestration, and configuration
• OpenRouter enables model flexibility across all providers
• Todoist integration for task management workflow
• Neo4j knowledge graph for persistent context and audit trails

Terminology and Glossary

User Scenarios & Stories

This section defines the key user scenarios that the Ultimate Hybrid Architecture addresses. Each scenario follows the format of As a [role], I want to [action], So that [benefit], with acceptance criteria for verification.

US-001: Terminal TUI Workflow (Critical)

As a developer working in terminal I want to use CheetahClaws TUI for file operations So that I can leverage rich terminal interface with multi-agent coordination

Acceptance Criteria:

• REQ-101-US-001-001: The system SHALL make all CheetahClaws commands accessible via /command syntax.
• REQ-101-US-001-002: The system SHALL provide 40+ slash commands, including /checkpoint, /rewind and /memory.
• REQ-101-US-001-003: The system SHALL perform multi-agent coordination transparently in the background.
• REQ-101-US-001-004: The system SHALL render diffs in real time with rich formatting.
• REQ-101-US-001-005: The system SHALL provide checkpoint creation and rollback functionality.
• REQ-101-US-001-006: The system SHALL integrate the knowledge graph for context.

US-002: Web UI Project Management (Critical)

As a project manager I want to manage projects via VizInt web dashboard So that I can oversee multiple projects, tasks, and agent configurations

Acceptance Criteria:

• REQ-101-US-002-001: The system SHALL display all projects with their status and metrics.
• REQ-101-US-002-002: The system SHALL create new projects from templates.
• REQ-101-US-002-003: The system SHALL allow per-project agent settings to be configured.
• REQ-101-US-002-004: The system SHALL provide visual task management with drag-and-drop.
• REQ-101-US-002-005: The system SHALL deliver real-time updates over WebSocket.
• REQ-101-US-002-006: The system SHALL support export and import of project configurations.

US-003: Todoist Task Integration (Critical)

As a developer I want to sync tasks between Orchestrata and Todoist So that I can manage work in my preferred task management tool

Acceptance Criteria:

• REQ-101-US-003-001: The system SHALL synchronize bidirectionally between Orchestrata and Todoist.
• REQ-101-US-003-002: The system SHALL support task assignment to specific agents (U:Cd, U:Qa, etc.).
• REQ-101-US-003-003: The system SHALL synchronize task priority and due date.
• REQ-101-US-003-004: The system SHALL synchronize status updates (pending → in_progress → completed).
• REQ-101-US-003-005: The system SHALL carry custom fields for agent assignment.
• REQ-101-US-003-006: The system SHALL support webhooks for real-time updates.

US-004: Multi-Agent File Editing (Critical)

As a developer I want to edit files with multiple agents collaborating So that I get code generation, review, and architecture feedback simultaneously

Acceptance Criteria:

• REQ-101-US-004-001: The system SHALL route an edit request to multiple agents in parallel.
• REQ-101-US-004-002: U:Cd (CheetahClaws) SHALL perform the actual edit.
• REQ-101-US-004-003: U:Qa SHALL perform the security/quality review.
• REQ-101-US-004-004: U:Ar SHALL check architecture compliance.
• REQ-101-US-004-005: U:Ux SHALL review UX implications.
• REQ-101-US-004-006: The system SHALL merge the agent results into a single response.
• REQ-101-US-004-007: The system SHALL record a full audit trail in the knowledge graph.

US-005: Model Flexibility (Critical)

As a developer I want to choose different models for different tasks So that I can optimize for quality, speed, or cost

Acceptance Criteria:

• REQ-101-US-005-001: The system SHALL support per-agent model configuration.
• REQ-101-US-005-002: The system SHALL integrate OpenRouter for all providers.
• REQ-101-US-005-003: The system SHALL support dynamic model switching via CLI and UI.
• REQ-101-US-005-004: The system SHALL support fallback models.
• REQ-101-US-005-005: The system SHALL track cost per model.
• REQ-101-US-005-006: The system SHALL support specialized models for specialized agents.

US-006: Parallel Task Execution (High)

As a developer I want to execute multiple tasks in parallel So that I can complete work faster

Acceptance Criteria:

• REQ-101-US-006-001: The system SHALL resolve task dependencies.
• REQ-101-US-006-002: The system SHALL execute independent tasks in parallel.
• REQ-101-US-006-003: The system SHALL make dependent tasks wait for their dependencies.
• REQ-101-US-006-004: The system SHALL track task progress in real time.
• REQ-101-US-006-005: The system SHALL aggregate and report task results.
• REQ-101-US-006-006: The system SHALL handle failed tasks and retry them.

US-007: Checkpoint and Rollback (High)

As a developer I want to create checkpoints and rollback to previous states So that I can experiment safely

Acceptance Criteria:

• REQ-101-US-007-001: The system SHALL snapshot file state.
• REQ-101-US-007-002: The system SHALL snapshot conversation state.
• REQ-101-US-007-003: The system SHALL snapshot knowledge graph events.
• REQ-101-US-007-004: The system SHALL roll back multi-agent state.
• REQ-101-US-007-005: The system SHALL manage checkpoints per project.
• REQ-101-US-007-006: The system SHALL support selective rollback (files only, conversations only, etc.).

US-008: Knowledge Graph Integration (High)

As a developer I want to leverage context from previous work So that I can build on past decisions and artifacts

Acceptance Criteria:

• REQ-101-US-008-001: The system SHALL log all actions to the Neo4j knowledge graph.
• REQ-101-US-008-002: The system SHALL allow past decisions and artifacts to be queried.
• REQ-101-US-008-003: The system SHALL retain context across sessions.
• REQ-101-US-008-004: The system SHALL provide semantic search across project history.
• REQ-101-US-008-005: The system SHALL track relationships between components.
• REQ-101-US-008-006: The system SHALL provide AI-powered context retrieval.

Standardized Acceptance Criteria

SAC-001: CheetahClaws TUI Integration

• REQ-101-AC1-001: Given a terminal session, when /command is invoked, the system SHALL route it to the appropriate agent(s).
• REQ-101-AC1-002: Given a file edit request, when submitted, U:Cd SHALL edit and U:Qa/U:Ar/U:Ux SHALL review in parallel.
• REQ-101-AC1-003: Given checkpoint creation, when /checkpoint is called, the system SHALL save file + conversation + KG state.
• REQ-101-AC1-004: Given a rollback request, when /rewind N is called, the system SHALL restore all components to checkpoint N.
• REQ-101-AC1-005: Given a knowledge query, when /memory <query> is invoked, the system SHALL retrieve the relevant context from the KG.

SAC-002: VizInt UI Functionality

• REQ-101-AC2-001: Given the project dashboard, when loaded, the system SHALL display all projects with status metrics.
• REQ-101-AC2-002: Given new project creation, when the form is submitted, the system SHALL create the project with the template applied.
• REQ-101-AC2-003: Given agent configuration, when settings are changed, the system SHALL validate and apply the config.
• REQ-101-AC2-004: Given the task view, when a task is dragged to a new column, the system SHALL update the status and notify the agents.
• REQ-101-AC2-005: Given the rules screen, when a rule is added, the system SHALL create and validate the Prolog policy.

SAC-003: Todoist Synchronization

• REQ-101-AC3-001: Given Todoist task creation, when the webhook is received, the system SHALL create the Orchestrata task.
• REQ-101-AC3-002: Given Orchestrata task completion, when the status changes, the system SHALL update the Todoist task.
• REQ-101-AC3-003: Given a task assignment, when the task is assigned to an agent, the system SHALL update the custom field in Todoist.
• REQ-101-AC3-004: Given a priority change, when updated in either system, the system SHALL synchronize it bi-directionally.
• REQ-101-AC3-005: Given a deletion, when a task is deleted, the system SHALL remove the counterpart and write an audit log entry.

SAC-004: Multi-Agent Coordination

• REQ-101-AC4-001: Given an edit request, when submitted, the system SHALL create a CXP packet with the fix_issues subject.
• REQ-101-AC4-002: Given U:Cd receives the packet, when processing, the system SHALL send parallel review requests to U:Qa/U:Ar/U:Ux.
• REQ-101-AC4-003: Given the reviews complete, when all return, the system SHALL aggregate and present the results.
• REQ-101-AC4-004: Given conflicting reviews, when detected, the system SHALL trigger the conflict resolution workflow.
• REQ-101-AC4-005: Given approval, when granted, the system SHALL set work_status to resolved and log the audit entry.

SAC-005: OpenRouter Model Routing

• REQ-101-AC5-001: Given an agent request, when submitted, the system SHALL select the best model based on agent type.
• REQ-101-AC5-002: Given a model is unavailable, when detected, the system SHALL use the fallback model transparently.
• REQ-101-AC5-003: Given a cost threshold, when exceeded, the system SHALL suggest a lower-cost model.
• REQ-101-AC5-004: Given a performance requirement, when specified, the system SHALL prioritize a high-performance model.
• REQ-101-AC5-005: Given custom routing, when configured, the system SHALL apply the custom rules before the defaults.

Data Models

The following JSON schemas define the core data structures used throughout the Ultimate Hybrid Architecture. These models cover projects, tasks, agent configurations, and multi-agent edit operations.

UltimateProject

REQ-101-001: The system SHALL implement the UltimateProject project-configuration structure exactly as defined by the JSON schema below, requiring name, path, volk_configs, rules and tasks, and carrying project_id, template, session_id, knowledge_graph_namespace, todoist_project_id, created_at and updated_at.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "UltimateProject",
  "description": "Project configuration for Ultimate Hybrid system",
  "type": "object",
  "required": ["name", "path", "volk_configs", "rules", "tasks"],
  "properties": {
    "project_id": {
      "type": "string",
      "format": "uuid",
      "description": "Unique project identifier"
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "Project name"
    },
    "path": {
      "type": "string",
      "description": "Local filesystem path"
    },
    "template": {
      "type": "string",
      "enum": ["blank", "webapp", "api", "library", "fullstack"],
      "description": "Project template"
    },
    "volk_configs": {
      "type": "object",
      "description": "Per-agent configuration",
      "properties": {
        "U:Cd": { "$ref": "#/$defs/VolkConfig" },
        "U:Qa": { "$ref": "#/$defs/VolkConfig" },
        "U:Ar": { "$ref": "#/$defs/VolkConfig" },
        "U:Ux": { "$ref": "#/$defs/VolkConfig" },
        "U:PM": { "$ref": "#/$defs/VolkConfig" }
      }
    },
    "rules": {
      "type": "array",
      "items": { "$ref": "007-prolog-governance/spec.md#/definitions/PolicyRule" },
      "description": "Project-specific governance rules"
    },
    "tasks": {
      "type": "array",
      "items": { "$ref": "#/$defs/UltimateTask" },
      "description": "Project tasks"
    },
    "session_id": {
      "type": "string",
      "format": "uuid",
      "description": "Associated Orchestrata session"
    },
    "knowledge_graph_namespace": {
      "type": "string",
      "pattern": "^[a-z0-9_]+$",
      "description": "Neo4j namespace for project context"
    },
    "todoist_project_id": {
      "type": "string",
      "description": "Associated Todoist project ID"
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time"
    }
  }
}

VolkConfig

REQ-101-002: The system SHALL implement the VolkConfig per-agent configuration structure exactly as defined by the JSON schema below, requiring enabled, model and tools, and carrying fallback_model, max_concurrent (1-10, default 3), timeout (30-3600 s, default 300), cost_limit and custom_instructions.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "VolkConfig",
  "description": "Configuration for a specific Volk agent",
  "type": "object",
  "required": ["enabled", "model", "tools"],
  "properties": {
    "enabled": {
      "type": "boolean",
      "description": "Whether this agent is enabled for the project"
    },
    "model": {
      "type": "string",
      "description": "OpenRouter model identifier (e.g., claude-3-5-sonnet)"
    },
    "fallback_model": {
      "type": "string",
      "description": "Fallback model if primary unavailable"
    },
    "tools": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Available tools for this agent"
    },
    "max_concurrent": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10,
      "default": 3,
      "description": "Maximum concurrent tasks"
    },
    "timeout": {
      "type": "integer",
      "minimum": 30,
      "maximum": 3600,
      "default": 300,
      "description": "Task timeout in seconds"
    },
    "cost_limit": {
      "type": "number",
      "minimum": 0,
      "description": "Maximum cost per task in USD"
    },
    "custom_instructions": {
      "type": "string",
      "description": "Custom system instructions for this agent"
    }
  }
}

UltimateTask

REQ-101-003: The system SHALL implement the UltimateTask structure exactly as defined by the JSON schema below, requiring task_id, title, status and assigned_volk, restricting status to pending/in_progress/completed/cancelled, assigned_volk to the pattern ^U:[A-Z][a-z]$ and priority to 1-4 (default 3), and carrying todoist_id, project_id, description, due_date, tags, depends_on, estimated_hours, actual_hours, created_at and updated_at.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "UltimateTask",
  "description": "Task managed in Ultimate Hybrid system",
  "type": "object",
  "required": ["task_id", "title", "status", "assigned_volk"],
  "properties": {
    "task_id": {
      "type": "string",
      "format": "uuid",
      "description": "Internal task ID"
    },
    "todoist_id": {
      "type": "string",
      "description": "Corresponding Todoist task ID"
    },
    "project_id": {
      "type": "string",
      "format": "uuid",
      "description": "Associated project ID"
    },
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Task title"
    },
    "description": {
      "type": "string",
      "description": "Detailed task description"
    },
    "status": {
      "type": "string",
      "enum": ["pending", "in_progress", "completed", "cancelled"],
      "description": "Task status"
    },
    "assigned_volk": {
      "type": "string",
      "pattern": "^U:[A-Z][a-z]$",
      "description": "Assigned Volk agent"
    },
    "priority": {
      "type": "integer",
      "minimum": 1,
      "maximum": 4,
      "default": 3,
      "description": "Priority level (1=highest, 4=lowest)"
    },
    "due_date": {
      "type": "string",
      "format": "date-time",
      "description": "Due date"
    },
    "tags": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Task tags"
    },
    "depends_on": {
      "type": "array",
      "items": { "type": "string", "format": "uuid" },
      "description": "Task IDs this task depends on"
    },
    "estimated_hours": {
      "type": "number",
      "minimum": 0,
      "description": "Estimated effort in hours"
    },
    "actual_hours": {
      "type": "number",
      "minimum": 0,
      "description": "Actual effort in hours"
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time"
    }
  }
}

MultiAgentEdit

REQ-101-004: The system SHALL implement the MultiAgentEdit structure exactly as defined by the JSON schema below, requiring edit_id, file_path, old_string, new_string and agents, where agents carries a primary Volk and a reviewers list, and carrying governance_check (allowed, rule, article), results and audit_trail.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "MultiAgentEdit",
  "description": "Multi-agent file edit operation",
  "type": "object",
  "required": ["edit_id", "file_path", "old_string", "new_string", "agents"],
  "properties": {
    "edit_id": {
      "type": "string",
      "format": "uuid",
      "description": "Unique edit identifier"
    },
    "file_path": {
      "type": "string",
      "description": "Path to file being edited"
    },
    "old_string": {
      "type": "string",
      "description": "Content being replaced"
    },
    "new_string": {
      "type": "string",
      "description": "New content"
    },
    "agents": {
      "type": "object",
      "properties": {
        "primary": { "type": "string", "pattern": "^U:[A-Z][a-z]$" },
        "reviewers": {
          "type": "array",
          "items": { "type": "string", "pattern": "^U:[A-Z][a-z]$" }
        }
      }
    },
    "governance_check": {
      "type": "object",
      "properties": {
        "allowed": { "type": "boolean" },
        "rule": { "type": "string" },
        "article": { "type": "string" }
      }
    },
    "results": {
      "type": "object",
      "description": "Results from each agent"
    },
    "audit_trail": {
      "type": "array",
      "items": { "type": "object" },
      "description": "Complete audit trail"
    }
  }
}

ModelRouting

REQ-101-005: The system SHALL implement the ModelRouting structure exactly as defined by the JSON schema below, requiring agent, task_type and primary_model, restricting task_type to code_generation/code_review/architecture/ux_review/testing/security/planning, and carrying fallback_models, cost_optimization (max_cost_per_request, prefer_cheaper_on_high_load) and performance (max_latency_ms, required_quality_score).

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "ModelRouting",
  "description": "Model routing configuration",
  "type": "object",
  "required": ["agent", "task_type", "primary_model"],
  "properties": {
    "agent": {
      "type": "string",
      "pattern": "^U:[A-Z][a-z]$",
      "description": "Volk agent identifier"
    },
    "task_type": {
      "type": "string",
      "enum": ["code_generation", "code_review", "architecture", "ux_review", "testing", "security", "planning"],
      "description": "Type of task"
    },
    "primary_model": {
      "type": "string",
      "description": "Primary model identifier"
    },
    "fallback_models": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Fallback model identifiers"
    },
    "cost_optimization": {
      "type": "object",
      "properties": {
        "max_cost_per_request": { "type": "number" },
        "prefer_cheaper_on_high_load": { "type": "boolean" }
      }
    },
    "performance": {
      "type": "object",
      "properties": {
        "max_latency_ms": { "type": "integer" },
        "required_quality_score": { "type": "number", "minimum": 0, "maximum": 1 }
      }
    }
  }
}

Error Conditions and Edge Cases

REQ-101-006: On E-001 (terminal session without Rich TUI support), the system SHALL fall back to basic CLI mode.

REQ-101-007: On E-002 (WebSocket connection to localhost:8765 fails), the system SHALL retry with exponential backoff and fall back to the TUI.

REQ-101-008: On E-003 (Todoist webhook or API call fails), the system SHALL queue the sync for later retry and log a warning.

REQ-101-009: On E-004 (requested model returns an error), the system SHALL fall back automatically to the configured fallback model.

REQ-101-010: On E-005 (parallel agent execution exceeds the timeout), the system SHALL abort the pending agents and return partial results.

REQ-101-011: On E-006 (checkpoint file corrupted or invalid), the system SHALL reject the rollback and create a new checkpoint.

REQ-101-012: On E-007 (Neo4j connection fails), the system SHALL continue operating without knowledge-graph context and log a warning.

REQ-101-013: On E-008 (circular dependency detected in the task graph), the system SHALL reject the task submission and suggest a dependency resolution.

REQ-101-014: On E-009 (conflicting PAM++ policies evaluate differently), the system SHALL apply deny-wins and log the conflict for admin review.

REQ-101-015: On E-010 (model usage exceeds the configured cost limit), the system SHALL block additional requests and notify the admin.

REQ-101-016: On E-011 (OpenRouter or provider API rate limited), the system SHALL switch to an alternate provider and apply exponential backoff.

REQ-101-017: On E-012 (attempt to edit a file without permissions), the system SHALL deny the edit and suggest sudo or a permission change.

REQ-101-018: On E-013 (duplicate knowledge-graph namespace), the system SHALL generate a unique namespace and log a warning.

REQ-101-019: On E-014 (Todoist and Orchestrata task states conflict), the system SHALL prompt for manual resolution and apply last-write-wins with an audit entry.

REQ-101-020: On E-015 (assigned model not available for the agent), the system SHALL auto-select the best available model and notify the user.

Functional Requirements

This section specifies the functional requirements for the Ultimate Hybrid Architecture, organized by component. Each requirement uses SHALL language to indicate mandatory functionality.

FR-001: CheetahClaws Integration

• REQ-101-021: System SHALL provide CheetahClaws TUI as primary terminal interface
• REQ-101-022: System SHALL support 40+ slash commands from CheetahClaws
• REQ-101-023: System SHALL enable multi-agent coordination for all file operations
• REQ-101-024: System SHALL provide rich diff rendering with rollback support
• REQ-101-025: System SHALL integrate checkpoint system with Orchestrata sessions

FR-001.1: Large File Handling

• REQ-101-026: System SHALL handle files up to 10MB directly
• REQ-101-027: System SHALL reject files >10MB with clear error message
• REQ-101-028: System SHALL support chunked reading for files 1-10MB
• REQ-101-029: System SHALL warn user when editing files >1MB

FR-001.2: Binary File Handling

• REQ-101-030: System SHALL detect binary files automatically
• REQ-101-031: System SHALL reject binary file edits with clear error message
• REQ-101-032: System SHALL support binary file read with hex dump option
• REQ-101-033: System SHALL skip binary files in grep/glob operations

FR-002: VizInt Web UI

• REQ-101-034: System SHALL provide web-based dashboard at localhost:8765
• REQ-101-035: System SHALL support project management with CRUD operations
• REQ-101-036: System SHALL provide real-time WebSocket updates
• REQ-101-037: System SHALL enable visual task management with drag-and-drop
• REQ-101-038: System SHALL support agent configuration and rules management

FR-003: Todoist Integration

• REQ-101-039: System SHALL synchronize tasks bi-directionally with Todoist
• REQ-101-040: System SHALL support task assignment to specific agents
• REQ-101-041: System SHALL maintain priority and due date synchronization
• REQ-101-042: System SHALL provide webhook support for real-time updates
• REQ-101-043: System SHALL preserve custom fields and labels

FR-004: OpenRouter Provider

• REQ-101-044: System SHALL abstract all LLM providers via OpenRouter
• REQ-101-045: System SHALL support model selection per agent type
• REQ-101-046: System SHALL provide automatic fallback model support
• REQ-101-047: System SHALL track cost and usage per model
• REQ-101-048: System SHALL optimize routing based on task type

FR-005: Multi-Agent Coordination

• REQ-101-049: System SHALL enable parallel execution of multiple agents
• REQ-101-050: System SHALL coordinate file editing across agents
• REQ-101-051: System SHALL aggregate results from all participating agents
• REQ-101-052: System SHALL provide real-time status updates
• REQ-101-053: System SHALL maintain audit trail for all agent interactions

FR-005.1: Multi-Agent Rollback

• REQ-101-054: System SHALL implement rollback mechanism for multi-agent operations
• REQ-101-055: System SHALL track all changes made by each agent during parallel execution
• REQ-101-056: System SHALL revert all changes if any agent fails critically
• REQ-101-057: System SHALL support partial rollback (revert specific agents only)
• REQ-101-058: System SHALL create automatic checkpoint before multi-agent operations
• REQ-101-059: System SHALL log rollback operations for audit trail

FR-006: Project Management

• REQ-101-060: System SHALL support multiple projects simultaneously
• REQ-101-061: System SHALL provide per-project agent configurations
• REQ-101-062: System SHALL maintain project-specific knowledge graph namespaces
• REQ-101-063: System SHALL enable project templates and scaffolding
• REQ-101-064: System SHALL support project archiving and deletion

Security Requirements

The Ultimate Hybrid Architecture implements comprehensive security measures across all components, including authentication, authorization, rate limiting, data retention, and secure communication. All security controls are enforced through the PAM++ governance system and logged for audit purposes.

NFR-004: Security

• REQ-101-101: System SHALL store API keys and tokens securely
• REQ-101-102: System SHALL encrypt communication via TLS
• REQ-101-103: System SHALL enforce role-based access control for projects
• REQ-101-104: System SHALL write audit logs for all sensitive operations

NFR-004.1: Authentication

• REQ-101-105: System SHALL support API key authentication for CLI and API access
• REQ-101-106: System SHALL support OAuth2 for web UI authentication
• REQ-101-107: System SHALL validate credentials against configured identity provider
• REQ-101-108: System SHALL expire sessions after configurable timeout (default: 24 hours)
• REQ-101-109: System SHALL require re-authentication for sensitive operations

NFR-004.2: Authorization

• REQ-101-110: System SHALL enforce PAM++ policy rules for all operations
• REQ-101-111: System SHALL support role-based access control (RBAC)
• REQ-101-112: System SHALL support project-scoped permissions
• REQ-101-113: System SHALL support per-agent permissions
• REQ-101-114: System SHALL deny-by-default for unauthorized operations

NFR-004.3: Rate Limiting

• REQ-101-115: System SHALL enforce global rate limit of 60 requests/minute per user
• REQ-101-116: System SHALL allow burst of 10 requests
• REQ-101-117: System SHALL return 429 status when limit exceeded
• REQ-101-118: System SHALL include Retry-After header in 429 responses
• REQ-101-119: System SHALL enforce per-component rate limits:
  • CLI: 60 req/min
  • Web API: 120 req/min
  • WebSocket: 60 messages/min
  • Todoist Sync: 30 req/min

NFR-004.4: Data Retention

• REQ-101-120: System SHALL retain checkpoints for 30 days by default (configurable)
• REQ-101-121: System SHALL retain audit logs for 90 days by default (configurable)
• REQ-101-122: System SHALL retain knowledge graph data indefinitely (configurable)
• REQ-101-123: System SHALL support data purge via CLI command
• REQ-101-124: System SHALL export data before purge
• REQ-101-125: System SHALL log all purge operations

Governance

The Ultimate Hybrid Architecture implements PAM++ (Prolog Argumentation Machine) as the governance engine for all system operations. Every action is evaluated against a comprehensive policy framework before execution, ensuring compliance, security, and adherence to organizational rules.

PAM++ Policy Integration

The Ultimate Hybrid Architecture integrates PAM++ (Prolog Argumentation Machine) governance for all operations. Governance decisions are made through the Enhanced CXP Protocol and enforced at the orchestration layer.

REQ-101-065: The system SHALL apply PAM++ (Prolog Argumentation Machine) governance to all operations; governance decisions SHALL be made through the Enhanced CXP Protocol and enforced at the orchestration layer.

Policy Categories

Governance Flow

User Request → Governance Check (PAM++) → Allow/Deny → Execution
                                          ↓
                              Decision logged to Knowledge Graph

REQ-101-066: Every user request SHALL pass a PAM++ governance check that yields allow or deny before execution, and the decision SHALL be logged to the knowledge graph.

Rule Precedence

1. REQ-101-067: Project-specific rules SHALL override global rules
2. REQ-101-068: Explicit deny rules SHALL always take precedence
3. REQ-101-069: Rules SHALL be evaluated in the order: File → Agent → Resource → Data → External
4. REQ-101-070: Conflicting rules SHALL trigger the admin review workflow

Compliance

• REQ-101-071: All governance decisions SHALL be logged with a full audit trail
• REQ-101-072: Policy changes SHALL require admin authentication
• REQ-101-073: Emergency override SHALL be available with additional logging

Non-Functional Requirements

This section defines the non-functional requirements covering performance, scalability, reliability, security, and usability characteristics of the Ultimate Hybrid Architecture.

NFR-001: Performance

• REQ-101-126: TUI response time SHALL be < 100ms for slash commands
• REQ-101-127: Web UI page load SHALL be < 500ms
• REQ-101-128: Task sync latency SHALL be < 1s
• REQ-101-129: Multi-agent coordination SHALL be < 2s for a 3-agent edit
• REQ-101-130: Model routing SHALL be < 50ms

NFR-002: Scalability

• REQ-101-131: System SHALL support 100+ concurrent projects
• REQ-101-132: System SHALL handle 1000+ tasks simultaneously
• REQ-101-133: System SHALL support 10+ agents per project
• REQ-101-134: System SHALL maintain performance with 10K+ knowledge graph nodes

NFR-003: Reliability

• REQ-101-135: System SHALL sustain 99.9% uptime for core functionality
• REQ-101-136: System SHALL degrade gracefully when components fail
• REQ-101-137: System SHALL retry transient failures automatically
• REQ-101-138: System SHALL provide comprehensive error handling and logging

NFR-004: Security

• REQ-101-101: System SHALL store API keys and tokens securely
• REQ-101-102: System SHALL encrypt communication via TLS
• REQ-101-103: System SHALL enforce role-based access control for projects
• REQ-101-104: System SHALL write audit logs for all sensitive operations

NFR-004.1: Authentication

• REQ-101-105: System SHALL support API key authentication for CLI and API access
• REQ-101-106: System SHALL support OAuth2 for web UI authentication
• REQ-101-107: System SHALL validate credentials against configured identity provider
• REQ-101-108: System SHALL expire sessions after configurable timeout (default: 24 hours)
• REQ-101-109: System SHALL require re-authentication for sensitive operations

NFR-004.2: Authorization

• REQ-101-110: System SHALL enforce PAM++ policy rules for all operations
• REQ-101-111: System SHALL support role-based access control (RBAC)
• REQ-101-112: System SHALL support project-scoped permissions
• REQ-101-113: System SHALL support per-agent permissions
• REQ-101-114: System SHALL deny-by-default for unauthorized operations

NFR-004.3: Rate Limiting

• REQ-101-115: System SHALL enforce global rate limit of 60 requests/minute per user
• REQ-101-116: System SHALL allow burst of 10 requests
• REQ-101-117: System SHALL return 429 status when limit exceeded
• REQ-101-118: System SHALL include Retry-After header in 429 responses
• REQ-101-119: System SHALL enforce per-component rate limits:
  • CLI: 60 req/min
  • Web API: 120 req/min
  • WebSocket: 60 messages/min
  • Todoist Sync: 30 req/min

NFR-004.4: Data Retention

• REQ-101-120: System SHALL retain checkpoints for 30 days by default (configurable)
• REQ-101-121: System SHALL retain audit logs for 90 days by default (configurable)
• REQ-101-122: System SHALL retain knowledge graph data indefinitely (configurable)
• REQ-101-123: System SHALL support data purge via CLI command
• REQ-101-124: System SHALL export data before purge
• REQ-101-125: System SHALL log all purge operations

NFR-005: Usability

• REQ-101-139: System SHALL provide an intuitive terminal interface with helpful prompts
• REQ-101-140: System SHALL provide a modern web UI with responsive design
• REQ-101-141: System SHALL provide comprehensive documentation and examples
• REQ-101-142: System SHALL provide an onboarding wizard for new users

Technical Design

This section provides detailed technical design specifications for the Ultimate Hybrid Architecture, including system architecture diagrams, component integration patterns, and implementation code examples.

Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                   Ultimate Hybrid System                         │
├─────────────────────────────────────────────────────────────────┤
│  UI Layer                                                        │
│  ┌──────────────────────┐  ┌──────────────────────────────────┐ │
│  │  CheetahClaws TUI    │  │        VizInt Web UI             │ │
│  │  (Terminal)          │  │    (localhost:8765)              │ │
│  │  40+ slash commands  │  │  Project Mgmt + Tasks + Config   │ │
│  └──────────────────────┘  └──────────────────────────────────┘ │
├─────────────────────────────────────────────────────────────────┤
│  Orchestration Layer                                             │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │        Orchestrata Kernel (CXP Protocol)                   │ │
│  │  ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐  │ │
│  │  │  U:Ox  │ │  U:PS  │ │  U:Cd  │ │  U:Qa  │ │  U:Ar  │  │ │
│  │  │ (Exec) │ │ (Route)│ │(Cheetah)│ │ (Review)│ │ (Arch)│  │ │
│  │  └────────┘ └────────┘ └────────┘ └────────┘ └────────┘  │ │
│  └────────────────────────────────────────────────────────────┘ │
├─────────────────────────────────────────────────────────────────┤
│  Integration Layer                                               │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐         │
│  │ OpenRouter   │  │  Todoist     │  │ Checkpoint   │         │
│  │ Provider     │  │  Sync        │  │  System      │         │
│  └──────────────┘  └──────────────┘  └──────────────┘         │
├─────────────────────────────────────────────────────────────────┤
│  Infrastructure                                                  │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │  Neo4j (KG) │ Redis (Cache) │ SWI-Prolog (PAM++)            │ │
│  └────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘

REQ-101-074: The system SHALL be composed of four layers as shown above: a UI layer (CheetahClaws TUI with 40+ slash commands, and the VizInt Web UI on localhost:8765 for project management, tasks and configuration); an orchestration layer (the Orchestrata kernel speaking the CXP protocol, hosting U:Ox, U:PS, U:Cd, U:Qa and U:Ar); an integration layer (OpenRouter provider, Todoist sync, checkpoint system); and an infrastructure layer (Neo4j knowledge graph, Redis cache, SWI-Prolog PAM++).

Component Integration

class UltimateOrchestrator:
    """Main orchestrator coordinating all Ultimate Hybrid components."""
    
    def __init__(self):
        self.cheetahclaws = CheetahClawsTUI()
        self.vizint = VizIntWebUI()
        self.todoist = TodoistIntegration()
        self.openrouter = OpenRouterProvider()
        self.orchestrata = OrchestrataKernel()
        self.knowledge_graph = Neo4jGraph()
        
    async def execute_multi_agent_edit(
        self,
        file_path: str,
        old_string: str,
        new_string: str
    ) -> MultiAgentEditResult:
        # 1. Governance check
        if not await self.orchestrata.governance.check(
            action="edit_file",
            context={"path": file_path}
        ):
            raise GovernanceError("Edit blocked by policy")
        
        # 2. Get context from knowledge graph
        context = await self.knowledge_graph.get_file_context(file_path)
        
        # 3. Route to multiple agents in parallel
        tasks = [
            self.orchestrata.agents["U:Cd"].execute_edit,
            self.orchestrata.agents["U:Qa"].review_edit,
            self.orchestrata.agents["U:Ar"].analyze_impact,
            self.orchestrata.agents["U:Ux"].review_ux
        ]
        
        results = await asyncio.gather(*tasks)
        
        # 4. Aggregate results
        aggregated = self._aggregate_agent_results(results)
        
        # 5. Log to knowledge graph
        await self.knowledge_graph.log_edit_event(
            file=file_path,
            change=new_string,
            agents=results,
            timestamp=datetime.now()
        )
        
        # 6. Update UI
        await self.vizint.broadcast_edit_complete(file_path, aggregated)
        
        return aggregated

Data Flow

User Input (TUI/UI)
        ↓
Command Parsing
        ↓
Governance Check (PAM++)
        ↓
Model Routing (OpenRouter)
        ↓
Agent Coordination (CXP)
        ↓
Parallel Execution
        ↓
Result Aggregation
        ↓
Knowledge Graph Update
        ↓
UI Update (WebSocket)
        ↓
Todoist Sync (if applicable)

REQ-101-075: The system SHALL process user input through the stages shown above, in order: command parsing, PAM++ governance check, OpenRouter model routing, CXP agent coordination, parallel execution, result aggregation, knowledge graph update, WebSocket UI update, and Todoist sync where applicable.

Performance Benchmarks

REQ-101-143: TUI command execution SHALL complete in < 100ms p95, measured by benchmarking 1000 commands (PR-001).

REQ-101-144: Web UI page load SHALL complete in < 500ms p95, measured as full page load time (PR-002).

REQ-101-145: Multi-agent edit coordination SHALL complete in < 2s p95, measured from edit request to result (PR-003).

REQ-101-146: Todoist task sync SHALL complete in < 1s p95, measured from task change to sync (PR-004).

REQ-101-147: A model routing decision SHALL complete in < 50ms p95, measured as time to select a model (PR-005).

REQ-101-148: Checkpoint creation SHALL complete in < 500ms p95, measured as time to snapshot all state (PR-006).

REQ-101-149: Rollback execution SHALL complete in < 1s p95, measured as time to restore a checkpoint (PR-007).

REQ-101-150: A knowledge graph query SHALL complete in < 200ms p95, measured as query response time (PR-008).

REQ-101-151: Parallel task execution SHALL complete in < 5s p95 for 5 independent tasks, measured by throughput (PR-009).

REQ-101-152: WebSocket message delivery SHALL complete in < 50ms p95, measured as round-trip latency (PR-010).

REQ-101-153: Cost calculation SHALL complete in < 10ms p95, measured over model usage cost tracking (PR-011).

REQ-101-154: Project creation SHALL complete in < 1s p95, measured as full project initialization (PR-012).

Testability Guidelines

Examples and Sample Data

This section provides concrete examples of how the Ultimate Hybrid Architecture works in practice, including CLI commands, API requests, and integration scenarios.

Example 1: Multi-Agent File Edit via TUI

Request (Terminal):

[myproject] ❯ /edit authentication.py - add OAuth2 support

U:Cd (CheetahClaws): Writing OAuth2 implementation...
U:Qa (Review): Running security scan...
U:Ar (Architect): Checking architecture compliance...
U:Ux (UX): Reviewing user experience...

✅ OAuth2 implementation added
✅ Security scan: PASS (no vulnerabilities)
✅ Architecture: APPROVED (follows patterns)
⚠️  UX note: Consider adding loading states

[View diff? y/N] y

--- a/authentication.py
+++ b/authentication.py
@@ -10,6 +10,8 @@
+def oauth2_flow():
+    """OAuth2 authentication flow."""
+    # Implementation here
+    pass

Example 2: Web UI Project Configuration

Request (VizInt):

POST /api/projects
{
  "name": "webapp-ecommerce",
  "template": "fullstack",
  "volk_configs": {
    "U:Cd": {
      "enabled": true,
      "model": "claude-3-5-sonnet",
      "tools": ["Read", "Write", "Edit", "Bash"]
    },
    "U:Qa": {
      "enabled": true,
      "model": "gpt-4o",
      "tools": ["Test", "Lint", "SecurityScan"]
    }
  }
}

Response:

{
  "project_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "webapp-ecommerce",
  "status": "created",
  "session_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "knowledge_graph_namespace": "webapp_ecommerce"
}

Example 3: Todoist Task Assignment

Request:

task = UltimateTask(
    task_id="task-123",
    title="Implement user authentication",
    assigned_volk="U:Cd",
    priority=1,
    due_date="2026-04-15T00:00:00Z",
    depends_on=[]
)

await orchestrator.todoist.create_task(task)

Todoist Result:

Implement user authentication
  ├─ Priority: 🔴
  ├─ Due: April 15
  ├─ Agent: U:Cd (CheetahClaws)
  └─ Status: Orchestrata Linked

Example 4: Checkpoint and Rollback

Request (Terminal):

[myproject] ❯ /checkpoint

✓ Checkpoint 5 created
  Files: 12 changed
  Conversation: 47 messages
  Knowledge Graph: 23 events
  Timestamp: 2026-04-08 14:30:22

[myproject] ❯ /edit main.py - add logging
... (edit performed) ...

[myproject] ❯ /rewind 5

⏪ Rolling back to checkpoint 5...
✓ Restored: main.py (removed logging)
✓ Restored: conversation to checkpoint 5 state
✓ Restored: Knowledge Graph (removed 3 events)

⚠️  Warning: Checkpoint 6 changes will be lost

Example 5: Model Routing

Request:

[myproject] ❯ /model show

Active agents:
  U:Cd: claude-3-5-sonnet (best for code generation)
  U:Qa: gpt-4o (best for code review)
  U:Ar: claude-3-opus (best for architecture)
  U:Ux: gpt-4o (best for UX)

[myproject] ❯ /model U:Cd gpt-4o-turbo

⚠️  Model switched for U:Cd: claude-3-5-sonnet → gpt-4o-turbo
💰 Cost impact: -$0.02 per request
📊 Performance impact: -5% quality, +10% speed

API Versioning Strategy

Version Header

• REQ-101-076: System SHALL use X-API-Version header for API requests
• REQ-101-077: The default API version SHALL be 1.0.0
• REQ-101-078: The supported API versions SHALL be 1.0.0, 1.1.0 and 2.0.0

Version URL Path

• REQ-101-079: REST endpoints SHALL include version in path: /api/v1/...
• REQ-101-080: WebSocket endpoints SHALL include version: ws://host:port/ws/v1/...

Deprecation Policy

• REQ-101-081: Deprecated features SHALL be marked with Deprecation header
• REQ-101-082: A deprecated feature SHALL be given a minimum 90-day notice before removal
• REQ-101-083: Deprecated features SHALL return 410 Gone with migration guide

Version Negotiation

• REQ-101-084: System SHALL accept a client-requested version supplied in the Accept header: application/vnd.orchestrata.v1+json
• REQ-101-085: Server SHALL return 406 Not Acceptable if version not supported

Contract Definitions

UltimateOrchestrator Interface

interface: UltimateOrchestrator
version: "1.0.0"
description: "Main orchestrator for Ultimate Hybrid system"
methods:
  execute_multi_agent_edit:
    description: "Execute file edit with multiple agents in parallel"
    parameters:
      - name: file_path
        type: string
        required: true
      - name: old_string
        type: string
        required: true
      - name: new_string
        type: string
        required: true
    returns:
      type: MultiAgentEditResult
    errors:
      - GovernanceError
      - AgentTimeoutError
    performance: "< 2s p95"
  
  create_project:
    description: "Create new project with template"
    parameters:
      - name: name
        type: string
        required: true
      - name: template
        type: string
        required: true
    returns:
      type: UltimateProject
    errors:
      - ValidationError
    performance: "< 1s p95"
  
  sync_todoist_tasks:
    description: "Synchronize tasks with Todoist"
    parameters:
      - name: project_id
        type: string
        required: true
    returns:
      type: list[UltimateTask]
    errors:
      - TodoistAPIError
    performance: "< 1s p95"
  
  route_to_model:
    description: "Route request to appropriate model"
    parameters:
      - name: agent
        type: string
        required: true
      - name: task_type
        type: string
        required: true
    returns:
      type: ModelRouting
    errors: []
    performance: "< 50ms p95"

REQ-101-086: The UltimateOrchestrator interface SHALL expose execute_multi_agent_edit(file_path: string, old_string: string, new_string: string) — all three parameters required — returning MultiAgentEditResult, raising GovernanceError or AgentTimeoutError, within < 2s p95.

REQ-101-087: The UltimateOrchestrator interface SHALL expose create_project(name: string, template: string) — both parameters required — returning UltimateProject, raising ValidationError, within < 1s p95.

REQ-101-088: The UltimateOrchestrator interface SHALL expose sync_todoist_tasks(project_id: string) — the parameter required — returning list[UltimateTask], raising TodoistAPIError, within < 1s p95.

REQ-101-089: The UltimateOrchestrator interface SHALL expose route_to_model(agent: string, task_type: string) — both parameters required — returning ModelRouting, raising no errors, within < 50ms p95.

Integration Points

REQ-101-090: The system SHALL integrate the CheetahClaws TUI as the terminal interface for file operations, over Rich/Textual.

REQ-101-091: The system SHALL integrate the VizInt Web UI for project and task management, over FastAPI + WebSocket.

REQ-101-092: The system SHALL integrate the Orchestrata kernel for multi-agent coordination, over the CXP protocol.

REQ-101-093: The system SHALL integrate OpenRouter for model abstraction, over its REST API.

REQ-101-094: The system SHALL integrate Todoist for task synchronization, over webhooks and its REST API.

REQ-101-095: The system SHALL integrate Neo4j as the knowledge graph, over the Bolt protocol.

REQ-101-096: The system SHALL integrate SWI-Prolog as the governance engine, over pyswip.

Visual Architecture

Class Diagram

Diagram source shown as text: Mermaid could not parse it (Error: Parse error on line 15:).

classDiagram-direction LR
    class ArchitectAgent {
        $agent_type: ClassVar[str] = 'U:Ar'
        ---
        +__init__(model: str = 'claude-3-5-haiku', agent_name: str = '')
        +async analyze_impact(file_path: str, old_string: str, new_string: str, context: dict[str, Any] | None = None): dict[str, Any]
        +async design_solution(requirements: dict[str, Any]): dict[str, Any]
        +async review_architecture(architecture: dict[str, Any]): dict[str, Any]
    }
    class BaseAgent <<pydantic>> {
        -model: str = Field(default='claude-3-5-haiku', description='Model identifier for the agent', min_length=1, strict=True)
        -agent_id: str = Field(default='', description='Unique agent identifier', strict=True)
        -agent_name: str = Field(default='', description='Human-readable agent name', strict=True)
        $agent_type: ClassVar[str] = 'U:Base'
        $_instance_counters: ClassVar[dict[str, int]] = {}
        ---
        {@classmethod} +validate_model(v: str): str
        +__init__(**data: Any): None
        #_generate_unique_id(): str
        +model_post_init(__context: Any): None
        +async receive_message(message: Any, sender: str | None = None): Any
    }
    class CodeDirectorAgent {
        $agent_type: ClassVar[str] = 'U:Cd'
        ---
        +__init__(model: str = 'claude-3-5-sonnet', agent_name: str = '')
        +async execute_edit(file_path: str, old_string: str, new_string: str, context: dict[str, Any] | None = None): dict[str, Any]
        +async review_code(code: str, requirements: dict[str, Any]): dict[str, Any]
        +async implement_feature(spec: dict[str, Any]): dict[str, Any]
    }
    class QualityAssuranceAgent {
        $agent_type: ClassVar[str] = 'U:Qa'
        ---
        +__init__(model: str = 'claude-3-5-sonnet', agent_name: str = '')
        +async review_edit(file_path: str, old_string: str, new_string: str, context: dict[str, Any] | None = None): dict[str, Any]
        +async run_tests(test_suite: str): dict[str, Any]
        +async audit_security(code: str): dict[str, Any]
    }
    class UserExperienceAgent {
        $agent_type: ClassVar[str] = 'U:Ux'
        ---
        +__init__(model: str = 'claude-3-5-haiku', agent_name: str = '')
        +async review_ux(file_path: str, old_string: str, new_string: str, context: dict[str, Any] | None = None): dict[str, Any]
        +async design_ui(requirements: dict[str, Any]): dict[str, Any]
        +async evaluate_accessibility(ui: dict[str, Any]): dict[str, Any]
    }
    class MultiAgentEditResult <<pydantic>> {
        -file_path: str
        -old_string: str
        -new_string: str
        -agent_results: dict[str, Any]
        -aggregated_result: dict[str, Any]
        -timestamp: datetime = Field(default_factory=datetime.now)
        -success: bool = True
        ---
    }
    class GovernanceError {
    }
    class OrchestrataKernel {
        +__init__(): None
        #_initialize_agents(): None
        +get_agents_by_type(agent_type: str): list[Any]
        +get_agent_by_id(agent_id: str): Any | None
        +async broadcast_to_type(agent_type: str, message: Any): list[Any]
        +async broadcast_to_all(message: Any): list[Any]
        +async send_to_agent(agent_id: str, message: Any, sender: str | None = None): Any | None
    }
    class UltimateOrchestrator {
        +__init__(): None
        +async execute_multi_agent_edit(file_path: str, old_string: str, new_string: str): MultiAgentEditResult
        #_aggregate_agent_results(results: list[Any]): dict[str, Any]
        +async create_project(name: str, path: str, template: str = 'blank'): dict[str, Any]
        +async shutdown(): None
    }
    class GovernanceError {
    }
    BaseAgent <|-- ArchitectAgent
    BaseModel <|-- BaseAgent
    BaseAgent <|-- CodeDirectorAgent
    BaseAgent <|-- QualityAssuranceAgent
    BaseAgent <|-- UserExperienceAgent
    BaseModel <|-- MultiAgentEditResult
    Exception <|-- GovernanceError
    UltimateBaseError <|-- GovernanceError
    UltimateOrchestrator ..> MultiAgentEditResult "execute_multi_agent_edit returns"
    UltimateOrchestrator ..> OrchestrataKernel "OrchestrataKernel"
    UltimateOrchestrator ..> MultiAgentEditResult "MultiAgentEditResult"
    UltimateOrchestrator ..> GovernanceError "GovernanceError"

REST API Endpoints

# Example endpoint definition
GET /api/v1/resource/{id}
Response (200):
  type: object
  required:
    - id
    - name
  properties:
    id: { type: string }
    name: { type: string }
Response (404):
  $ref: '#/components/schemas/ErrorResponse'

Error Response Schema

components:
  schemas:
    ErrorResponse:
      type: object
      required:
        - error
        - message
        - timestamp
      properties:
        error: { type: string }
        message: { type: string }
        timestamp: { type: string, format: date-time }
        request_id: { type: string }
        trace_id: { type: string }
        details: { type: array, items: { type: object } }

REQ-101-097: The system SHALL return errors as the ErrorResponse object defined above, requiring error, message and timestamp, and carrying request_id, trace_id and details.

API Versioning

All APIs use path-based versioning (/api/v1/). Breaking changes require increment to v2.

REQ-101-098: All APIs SHALL use path-based versioning (/api/v1/), and a breaking change SHALL increment the major version to v2.

Observability

Logging Requirements

1. Component Logging
   • REQ-101-155: System SHALL log all major operations with appropriate log levels
   • REQ-101-156: System SHALL include correlation IDs for request tracing
   • REQ-101-157: System SHALL log performance metrics for critical operations
   • REQ-101-158: System SHALL log errors with full context for debugging

Metrics Requirements

1. Performance Metrics
   • REQ-101-159: System SHALL emit operation duration histograms
   • REQ-101-160: System SHALL emit request/error rate counters
   • REQ-101-161: System SHALL emit resource utilization gauges
   • REQ-101-162: System SHALL emit business metrics relevant to the domain

Tracing Requirements

1. Distributed Tracing
   • REQ-101-163: System SHALL propagate traces across component boundaries
   • REQ-101-164: System SHALL attach span attributes for domain-specific context
   • REQ-101-165: System SHALL sample traces based on operational needs

Alerting Requirements

1. Critical Alerts
   • REQ-101-166: System SHALL alert on error rate spikes
   • REQ-101-167: System SHALL alert on performance degradation
   • REQ-101-168: System SHALL alert on resource exhaustion
   • REQ-101-169: System SHALL alert on business metric anomalies

Dashboard Requirements

1. Operational Dashboard
   • REQ-101-170: System SHALL present real-time system health
   • REQ-101-171: System SHALL present performance trends
   • REQ-101-172: System SHALL present error analysis
   • REQ-101-173: System SHALL present resource monitoring

Revision History

End of SPEC-001-ULTIMATE: Ultimate Hybrid Architecture

Related

• RTM page for 101-ultimate-architecture
• All specs
• RTM overview
• Gates