documentation

agenKic-orKistrator

A magic tower AI orchestrator. Fantasy character classes working inside a vertical tower. Each floor is a project workspace — multi-model routing, real-time coordination.

Epics
1
Go Orchestrator Core
Supervisor, agent state machine, DAG engine, gRPC service, Redis state
2
Terminal Substrate Layer
tmux session management, command injection, output capture
3
Model Gateway / Judge-Router
LiteLLM proxy, 3-tier routing, provider adapters, fallback chains, cost tracking
4
Magic Tower UI
Godot 4 magic tower, fantasy character agents, floor-based workspaces, HTTP/SSE bridge
Features
Epic 1
CAS Optimistic Locking
Compare-and-swap state transitions for agent lifecycle without distributed locks
Epic 3
Judge-Router
Haiku classifies task complexity, routes to appropriate model tier
Epic 3
Config Loader & Fallback Chains
YAML-driven tier definitions with automatic provider failover
Epic 3
Cost Tracking
Per-request token logging, daily and period cost reports
CI/CD
Dynamic Docs Index & Publish Workflow
Manifest-driven index, GitHub Actions auto-publish, nested hierarchy
Architecture Decisions
#1
Orchestration Pattern
Supervisor/Worker + DAG over LangGraph, CrewAI, or AutoGen
#2
Inter-Process Communication
gRPC + Redis Streams over Unix sockets, shared memory, or ZeroMQ
#3
State Management
Redis (Streams + Hashes + Sorted Sets) over PostgreSQL, SQLite, or blackboard
#4
Process Supervision
OTP-style “let it crash” over defensive coding, supervisord, or PM2
#5
Terminal Substrate
tmux CLI wrapper over WezTerm Lua, raw PTY, or X11/Wayland
#6
Desktop Rendering
Godot 4 + godot-xterm over Tauri, egui, raylib, or SDL2
#7
Model Gateway
LiteLLM + Judge-Router over OpenRouter, direct APIs, or manual thresholds
#8
TUI Alternative
Bubbletea + Lip Gloss as the headless fallback to the magic tower
Roadmap
Project Roadmap
Interactive timeline — from orchestrator core to magic tower, four epics building a visual AI agent coordination platform