Skip to content

Architecture

System design principles and patterns for the coding infrastructure.

Complete System Overview

Key Principles

1. Agent-Agnostic Design

Multi-Agent Support

Both Claude Code and GitHub CoPilot are fully supported with identical infrastructure (containerized services + stdio proxies on the host) and a unified launcher. Adding new agents follows a documented adapter pattern.

The architecture supports multiple AI coding assistants through a unified adapter pattern:

Agent-Agnostic Architecture

Agent-Agnostic Architecture Sequence

Layers:

  1. Agent Layer - AI assistants (Claude Code, GitHub CoPilot, OpenCode, future agents)
  2. Tmux Wrapper Layer - Unified session wrapping via tmux-session-wrapper.sh — status bar, nesting guard, env propagation, optional pipe-pane I/O capture
  3. Config Layer - Agent definitions in config/agents/<name>.sh (10-30 lines each)
  4. Orchestration Layer - launch-agent-common.sh handles all shared startup (Docker detection, service startup, monitoring, session management)
  5. Common Setup Layer - Shared initialization (agent-common-setup.sh)
  6. Shared Services - VKB, Semantic Analysis, Constraint Monitor, LSL
  7. Adapter Layer - Abstract interface + agent implementations (dynamic import by convention)

2. Knowledge Persistence

Multi-tier storage for reliability and performance:

Runtime (Fast):

  • MCP Memory (Claude)
  • Graphology Graph (in-memory)

Persistence (Reliable):

  • LevelDB (persistent graph storage)
  • JSON exports (git-tracked)
  • .specstory/history/ (session logs)

3. Real-Time Quality Enforcement

PreToolUse hooks intercept tool calls BEFORE execution:

flowchart LR
    A[Claude Tool Call] --> B[PreToolUse Hook]
    B --> C[Constraint Monitor]
    C -->|Violation| D[BLOCK]
    C -->|Clean| E[ALLOW]
    E --> F[Tool Execution]

4. 4-Layer Monitoring

Progressive escalation for reliability:

Layer Component Function
4 Service Health UKB, VKB, Semantic Analysis
3 System Verifier LSL, Constraints
2 System Coordinator Overall health, metrics
1 System Watchdog Critical failures, alerts

Deployment

MCP servers run as HTTP/SSE services in Docker containers; the host-side Claude/Copilot CLI talks to them via lightweight stdio proxies. Docker Desktop must be installed and running. The stack is launched automatically by coding --claude. See the Docker Deployment Guide for container details.

Development Patterns

Constraint-Based Development

Define constraints before implementation:

constraints:
  - id: no-parallel-versions
    pattern: /(v\d+|enhanced|improved|new|fixed)_/
    severity: CRITICAL
    message: Never create parallel versions - edit originals

Agent Detection

const detector = new AgentDetector();
const available = await detector.detectAll();
// { claude: true, copilot: true }

const best = await detector.getBest();
// 'claude'

Knowledge Capture

# Auto-analysis from git commits
ukb

# Structured interactive capture
ukb --interactive

# Visualization
vkb

Adding New Agents

Adding a new agent requires only a single config file — zero changes to shared code.

Agent Integration Flow

Create config/agents/<name>.sh defining AGENT_NAME, AGENT_COMMAND, and optional hook functions. Agent detection, launcher routing, and tmux wrapping all happen automatically.

Proof: The OpenCode agent (config/agents/opencode.sh) is a 25-line file providing full integration.

See the Agent Integration Guide for the complete walkthrough, config reference, and API contract.