skate/DESIGN.md

Design Decisions

Stack

• Language: Rust
• TUI Framework: Ratatui + Crossterm
• Async Runtime: Tokio

Architecture

• Channel boundary between TUI and core (fully decoupled)
• Module decomposition: app, tui, core, provider, tools, sandbox, session
• Headless mode: core without TUI, driven by script (enables benchmarking and CI)

Model Integration

• Claude-first, multi-model via ModelProvider trait
• Common StreamEvent internal representation across providers
• Prompt caching-aware message construction

UI

• Agent view: Tree-based hierarchy (not flat tabs) for sub-agent inspection
• Modes: Normal, Insert, Command (: prefix from Normal mode)
• Activity modes: Plan and Execute are visually distinct activities in the TUI
• Streaming: Barebones styled text initially, full markdown rendering deferred
• Token usage: Per-turn display (between user inputs), cumulative in status bar
• Status bar: Mode indicator, current activity (Plan/Execute), token totals, network policy state

Planning Mode

• Distinct activity from execution — planner agent produces a plan file, does not execute
• Plan file is structured markdown: steps with descriptions, files involved, acceptance criteria
• Plan is reviewable and editable before execution (:edit-plan opens $EDITOR)
• User explicitly approves plan before execution begins
• Executor agent receives the plan file + project context, not the planning conversation
• Plan-step progress tracked during execution (complete/in-progress/failed)

Sub-Agents

• Independent context windows with summary passed back to parent
• Fully autonomous once spawned
• Hard deny on unpermitted actions
• Plan executor is a specialized sub-agent where the plan replaces the summary
• Direct user interaction with sub-agents deferred

Tool System

• Built-in tool system with Tool trait
• Core tools: read_file, write_file, edit_file, shell_exec, list_directory, search_files
• Approval gates by risk level: auto-approve (reads), confirm (writes/shell), deny
• MCP not implemented but interface designed to allow future adapter

Sandboxing

• Landlock (Linux kernel-level):
  • Read-only: system-wide (/)
  • Read-write: project directory, temp directory
  • Network: blocked by default, toggleable via :net on/off
• Graceful degradation on older kernels
• All tool execution goes through Sandbox — tools never touch filesystem directly

Session Logging

• JSONL format, one event per line
• Events: user message, assistant message, tool call, tool result, sub-agent spawn/result, plan created, plan step status
• Tree-addressable via parent IDs (enables conversation branching later)
• Token usage stored per event
• Linear UX for now, branching deferred

Testing Strategy

Unit Tests

• provider: SSE stream parsing from byte fixtures, message/tool serialization, StreamEvent variant correctness
• tools: Path canonicalization, traversal prevention, risk level classification, registry dispatch
• sandbox: Landlock policy construction, path validation logic (without applying kernel rules)
• core: Conversation tree operations (insert, query by parent, turn computation, token totals), orchestrator state machine transitions against mock StreamEvent sequences
• session: JSONL serialization roundtrips, parent ID chain reconstruction
• tui: Widget rendering via Ratatui TestBackend

Integration Tests — Component Boundaries

• Core ↔ Provider: Mock ModelProvider replaying recorded API sessions (full SSE streams with tool use). Tests the complete orchestration loop deterministically without network.
• Core ↔ TUI (channel boundary): Orchestrator with mock provider connected to channels. Assert correct UIEvent sequence, inject UserAction messages, verify approval/denial flow.
• Tools ↔ Sandbox: Real file operations and shell commands in temp directories. Verify write confinement, path traversal rejection, network blocking. Skip Landlock-specific tests on older kernels in CI.

Integration Tests — End to End

• Recorded session replay: Capture real Claude API HTTP request/response pairs, replay deterministically. Exercises full stack (core + channel + mock TUI) without cost or network dependency. Primary E2E test strategy.
• Live API tests: Small suite behind feature flag / env var. Verifies real API integration. Run manually before releases, not in CI.

Benchmarking — SWE-bench

• Target: SWE-bench Verified (500 curated problems) as primary benchmark
• Secondary: SWE-bench Pro for testing planning mode on longer-horizon tasks
• Approach: Headless mode (core without TUI) produces unified diff patches, evaluated via SWE-bench Docker harness
• Baseline: mini-swe-agent (~100 lines Python, >74% on Verified) as calibration — if we score significantly below with same model, the issue is scaffolding
• Cadence: Milestone checks, not continuous CI (too expensive/slow)
• Requirements: x86_64, 120GB+ storage, 16GB RAM, 8 CPU cores

Test Sequencing

• Phase 1: Unit tests for SSE parser, event types, message serialization
• Phase 4: Recorded session replay infrastructure (core loop complex enough to warrant it)
• Phase 6-7: Headless mode + first SWE-bench Verified run

Configuration (Deferred)

• Single-user, hardcoded defaults for now
• Designed for later: global config, per-project .agent.toml, configurable keybindings

Deferred Features

• Conversation branching (tree structure in log, linear UX for now)
• Direct sub-agent interaction
• MCP adapter
• Full markdown/syntax-highlighted rendering
• Session log viewer
• Per-project configuration
• Structured plan editor in TUI (use $EDITOR for now)