Orchestrata Ultimate / Specs / 061-cheetahclaws-volk

061-cheetahclaws-volk: CheetahClaws Volk Agent Integration

Integration of CheetahClaws Volk agent into Orchestrata as the primary code generation and editing agent (U:Cd). CheetahClaws provides the terminal-based AI assistant capabilities.

At a glance

Reading this spec

This spec integrates CheetahClaws as the Code Director volk (U:Cd), the primary code generation and editing agent in Orchestrata. CheetahClaws supplies the terminal-based AI assistant: a rich TUI editing experience and a mature codebase. Orchestrata adds multi-agent coordination, so several agents can work in parallel with CheetahClaws acting as code director. It is the agent-level companion to spec 050, which covers the terminal interface and file tools.

The spec has three user stories: terminal code editing, multi-agent code generation, and checkpoint and rollback. Its design imports CheetahClaws as the U:Cd volk, integrates file-editing tools through the Orchestrata kernel, enables parallel agent coordination, and routes code tasks to CheetahClaws over the CXP protocol. The 50 requirement IDs are numbered REQ-061-NNN and cover the functional requirements, error conditions (for example a permission error when there is no write access, and retry with backoff when an external API is unavailable), an API contract for the CheetahClawsService, and non-functional requirements.

Concrete constraints include: all CheetahClaws slash commands are available through Orchestrata; the volk is configured by a CheetahClawsConfig object that requires agent_id, model and permission_mode; rollback restores files; the model provider is OpenRouter; all file operations are logged; file edits complete in under 100 ms; and the CheetahClawsTUI class exposes asynchronous operations including create_checkpoint, rewind, query_memory and edit_file.

No code module cites this spec. 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 50 requirements, so measured trace coverage is 0.0%, and in tests/, 0 requirements are cited by a test-side @traces. All 50 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/061-cheetahclaws-volk/compliance-audit.md

Full spec text

Verbatim from specs/061-cheetahclaws-volk/spec.md; headings are pushed down two levels.

SPEC-061: CheetahClaws Volk Agent Integration

Metadata

• Spec ID: 061-cheetahclaws-volk
• Title: CheetahClaws Volk Agent Integration
• Author: Mohamed
• Status: Complete
• Created: 2026-04-08
• Last Updated: 2026-04-08
• Priority: P0
• Version: 1.0.0

Overview

What

Integration of CheetahClaws Volk agent into Orchestrata as the primary code generation and editing agent (U:Cd). CheetahClaws provides the terminal-based AI assistant capabilities.

Why

• Leverage CheetahClaws' mature codebase (460+ stars)
• Provide rich TUI-based code editing experience
• Enable multi-agent parallel execution with CheetahClaws as code director
• Combine with Orchestrata's multi-agent coordination

How

• Import CheetahClaws as U:Cd (Code Director) Volk agent
• Integrate file editing tools through Orchestrata kernel
• Enable parallel agent coordination
• Route code tasks to CheetahClaws via CXP protocol

User Scenarios

US-001: Terminal Code Editing

As a developer I want to edit files via CheetahClaws TUI So that I can leverage rich terminal interface for code changes

Acceptance Criteria:

• All CheetahClaws slash commands available
• Real-time diff rendering
• Multi-file edits supported

REQ-061-001: All CheetahClaws slash commands SHALL be available through Orchestrata.

REQ-061-002: The integration SHALL render diffs in real time.

REQ-061-003: The integration SHALL support multi-file edits.

US-002: Multi-Agent Code Generation

As a developer I want to have CheetahClaws work with other agents So that I can generate code in parallel with code review

Acceptance Criteria:

• CXP protocol integration
• Agent coordination works
• Results aggregated correctly

REQ-061-004: Results produced by agents working in parallel SHALL be aggregated correctly.

CXP protocol integration and agent coordination are carried by REQ-061-012 and REQ-061-013 (FR-005, FR-006).

US-003: Checkpoint and Rollback

As a developer
I want to create checkpoints before risky edits So that I can rollback if needed

Acceptance Criteria:

• Checkpoint creation works
• Rollback restores files correctly
• Checkpoint metadata persisted

REQ-061-005: Checkpoint metadata SHALL be persisted.

Checkpoint creation and rollback correctness are carried by REQ-061-010 and REQ-061-011 (FR-003, FR-004).

Terminology

Data Models

CheetahClawsConfig

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["agent_id", "model", "permission_mode"],
  "properties": {
    "agent_id": {
      "type": "string",
      "pattern": "^U:Cd$"
    },
    "model": {
      "type": "string",
      "enum": ["claude-3-5-sonnet", "claude-3-opus", "gpt-4o"]
    },
    "permission_mode": {
      "type": "string",
      "enum": ["ask", "bypass", "strict"]
    }
  }
}

REQ-061-006: The CheetahClaws Volk SHALL be configured by a CheetahClawsConfig object that requires agent_id, model and permission_mode; agent_id SHALL match ^U:Cd$, model SHALL be one of claude-3-5-sonnet, claude-3-opus or gpt-4o, and permission_mode SHALL be one of ask, bypass or strict.

Checkpoint

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["id", "files", "timestamp"],
  "properties": {
    "id": {
      "type": "string"
    },
    "files": {
      "type": "array",
      "items": {"type": "string"}
    },
    "timestamp": {
      "type": "string",
      "format": "date-time"
    }
  }
}

REQ-061-007: A Checkpoint SHALL be an object that requires id (string), files (array of strings) and timestamp (string, date-time format).

Functional Requirements

REQ-061-008: The CheetahClaws TUI SHALL launch via Orchestrata. (FR-001, P0)

REQ-061-009: File edit commands SHALL route to CheetahClaws. (FR-002, P0)

REQ-061-010: The checkpoint system SHALL be functional. (FR-003, P0)

REQ-061-011: Rollback SHALL restore files. (FR-004, P0)

REQ-061-012: The Volk SHALL integrate with the CXP protocol. (FR-005, P1)

REQ-061-013: Multi-agent coordination SHALL be supported. (FR-006, P1)

REQ-061-014: Model selection SHALL be configurable. (FR-007, P2)

Error Conditions

REQ-061-015: On an edit of a non-existent file (E-001, file not found) the system SHALL return an error.

REQ-061-016: When there is no write access (E-002, permission denied) the system SHALL show a permission error.

REQ-061-017: When a path contains ../ (E-003, path traversal) the system SHALL reject it with a warning.

REQ-061-018: When a file is larger than 10MB (E-004, file too large) the system SHALL reject it with the size information.

REQ-061-019: On an attempt to edit a binary file (E-005) the system SHALL reject it by binary detection.

REQ-061-020: When a checkpoint file is corrupted (E-006, checkpoint corrupt) the system SHALL reject the rollback.

REQ-061-021: When an external API is unavailable (E-007, network failure) the system SHALL retry with backoff.

REQ-061-022: When the requested model is not available (E-008, model unavailable) the system SHALL fall back to the default model.

REQ-061-023: When an agent exceeds its timeout (E-009, agent timeout) the system SHALL return partial results.

REQ-061-024: When old_string does not match (E-010, invalid edit) the system SHALL show the actual content.

API Contracts

CheetahClawsService

interface: CheetahClawsService
methods:
  - name: edit_file
    parameters:
      - name: path
        type: string
      - name: old_string
        type: string
      - name: new_string
        type: string
    returns:
      type: EditResult

  - name: create_checkpoint
    parameters:
      - name: description
        type: string
    returns:
      type: Checkpoint

  - name: rollback
    parameters:
      - name: checkpoint_id
        type: string
    returns:
      type: boolean

REQ-061-025: The CheetahClawsService interface SHALL expose edit_file(path: string, old_string: string, new_string: string) -> EditResult, create_checkpoint(description: string) -> Checkpoint, and rollback(checkpoint_id: string) -> boolean.

Non-Functional Requirements

• Performance: File edits < 100ms
• Reliability: 99.9% uptime
• Security: Path validation required
• Usability: Rich diff rendering

REQ-061-101: File edits SHALL complete in under 100ms. (Performance)

REQ-061-102: The integration SHALL sustain 99.9% uptime. (Reliability)

REQ-061-103: Path validation SHALL be required. (Security)

REQ-061-104: The integration SHALL provide rich diff rendering. (Usability)

Technical Design

Architecture

Orchestrata Kernel
    |
    +-- CXP Protocol
    |       |
    |       +-- U:Cd (CheetahClaws)
    |
    +-- File Operations
    |       |
    |       +-- Edit/Read/Write

Integration Points

• Via CXP protocol to Orchestrata kernel
• File system access through sandboxed operations
• Model provider via OpenRouter

REQ-061-026: File-system access SHALL go through sandboxed operations.

REQ-061-027: The model provider SHALL be OpenRouter.

Kernel integration via the CXP protocol is carried by REQ-061-012 (FR-005).

Examples

Edit Command

/edit src/main.py "def hello():" -> "def hello_world():"

Checkpoint

/checkpoint "Add OAuth support"

Security Requirements

Authentication

• API key required for model access
• Session-based authentication

REQ-061-028: An API key SHALL be required for model access.

REQ-061-029: Authentication SHALL be session-based.

Authorization

• Permission mode: ask/bypass/strict
• File operation policies enforced

REQ-061-030: Authorization SHALL be governed by the permission mode (ask, bypass or strict).

REQ-061-031: File operation policies SHALL be enforced.

Input Validation

• Path traversal prevention
• File size limits
• Binary file detection

Path-traversal prevention, file-size limits and binary-file detection are carried by REQ-061-017, REQ-061-018 and REQ-061-019 (E-003, E-004, E-005).

Audit Logging

• All file operations logged
• Checkpoint history maintained

REQ-061-032: All file operations SHALL be logged.

REQ-061-033: Checkpoint history SHALL be maintained.

Governance

Policy Points

• File operation approvals
• Dangerous command blocking
• Rate limiting per user

REQ-061-034: File operations SHALL be subject to an approval policy point.

REQ-061-035: Dangerous commands SHALL be blocked.

REQ-061-036: Requests SHALL be rate-limited per user.

Visual Architecture

Class Diagram

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

classDiagram-direction LR
    class CheetahClawsTUI {
        +__init__()
        #_load_commands(): dict[str, Any]
        +async create_checkpoint(name: str): dict[str, Any]
        +async rewind(steps: int = 1): dict[str, Any]
        +async query_memory(query: str, depth: int = 1): dict[str, Any]
        +async edit_file(file_path: str, old_string: str, new_string: str): dict[str, Any]
        +async search_files(pattern: str, path: str = '.'): list[str]
        +async execute_command(command: str, args: list[str] | None = None): dict[str, Any]
    }

REQ-061-037: The CheetahClawsTUI class SHALL expose the async operations create_checkpoint(name), rewind(steps=1), query_memory(query, depth=1), edit_file(file_path, old_string, new_string), search_files(pattern, path='.') and execute_command(command, args=None), and SHALL load its command set via _load_commands().

Unit Tests

• File edit operations
• Checkpoint creation/rollback
• Path validation

REQ-061-038: Unit tests SHALL cover file edit operations, checkpoint creation/rollback, and path validation.

Integration Tests

• CXP protocol
• Multi-agent coordination

REQ-061-039: Integration tests SHALL cover the CXP protocol and multi-agent coordination.

E2E Tests

• Full edit workflow
• Checkpoint/rollback flow

REQ-061-040: E2E tests SHALL cover the full edit workflow and the checkpoint/rollback flow.

Integration Points

• Orchestrata Kernel: CXP protocol
• File System: Sandboxed operations
• Models: OpenRouter provider

These restate the Technical Design integration points: REQ-061-012 (CXP protocol to the Orchestrata kernel), REQ-061-026 (sandboxed file-system operations) and REQ-061-027 (OpenRouter model provider).

Success Criteria

1. All CheetahClaws commands available via Orchestrata
2. Checkpoint/rollback fully functional
3. Multi-agent coordination working
4. 100% test coverage for critical paths

REQ-061-105: Critical paths SHALL have 100% test coverage.

Criteria 1-3 are carried by REQ-061-001 (all commands available), REQ-061-010 and REQ-061-011 (checkpoint/rollback), and REQ-061-013 (multi-agent coordination).

Observability

Logging Requirements

1. Component Logging
   • Log all major operations with appropriate log levels
   • Include correlation IDs for request tracing
   • Log performance metrics for critical operations
   • Log errors with full context for debugging

REQ-061-106: Component logging SHALL log all major operations with appropriate log levels, include correlation IDs for request tracing, log performance metrics for critical operations, and log errors with full context for debugging.

Metrics Requirements

1. Performance Metrics
   • Operation duration histograms
   • Request/error rate counters
   • Resource utilization gauges
   • Business metrics relevant to domain

REQ-061-107: Performance metrics SHALL comprise operation duration histograms, request/error rate counters, resource utilization gauges, and business metrics relevant to the domain.

Tracing Requirements

1. Distributed Tracing
   • Trace propagation across component boundaries
   • Span attributes for domain-specific context
   • Trace sampling based on operational needs

REQ-061-108: Distributed tracing SHALL propagate traces across component boundaries, carry span attributes for domain-specific context, and sample traces based on operational needs.

Alerting Requirements

1. Critical Alerts
   • Error rate spikes
   • Performance degradation
   • Resource exhaustion
   • Business metric anomalies

REQ-061-109: Critical alerts SHALL fire on error rate spikes, performance degradation, resource exhaustion, and business metric anomalies.

Dashboard Requirements

1. Operational Dashboard
   • Real-time system health
   • Performance trends
   • Error analysis
   • Resource monitoring

REQ-061-110: The operational dashboard SHALL present real-time system health, performance trends, error analysis, and resource monitoring.

Revision History

Related

• RTM page for 061-cheetahclaws-volk
• All specs
• RTM overview
• Gates