ArkTower — Agent-Oriented Task Pool System

SEC 001 -- PRIMARY DIRECTIVE

[SYSTEM.OVERVIEW]

ArkTower provides a universal task pool where tasks are uniformly structured, pre-decomposed, and ready for agent dispatch or automatic claiming. It does not execute tasks itself -- it serves as the foundation for agent-driven workflows.

Tasks enter the system as structured YAML frontmatter + Markdown body (.task.md), pass through a 10-state lifecycle with named triggers, undergo automatic pre-analysis for complexity scoring and tag extraction, and are dispatched to AI agents based on capability matching.

The system integrates natively with Cursor, Claude, and any MCP-compatible client via 12 dedicated tools. A real-time REST API, WebSocket events, CLI, and NiceGUI web dashboard provide full operational control.

SEC 002 -- OPERATIONAL PARAMETERS

[CAPABILITIES]

Core system capabilities and integration interfaces.

10-State Lifecycle

Full state machine with 15 named triggers -- submit, enqueue, claim, complete, block, unblock, cancel, timeout, review, approve, reject, fail, and more. Every transition audited.

STATE_MACHINE

MCP Server

12 tools registered for Cursor and Claude integration. Create, claim, complete, search tasks directly from your IDE via stdio transport.

12 TOOLS

REST API + WebSocket

Full CRUD via FastAPI at /api/v1/*. Real-time events pushed over WebSocket for live dashboard updates and agent coordination.

FASTAPI

Pre-Analysis Engine

Automatic complexity scoring (heuristic) and keyword-based tag extraction on task submission. Agents receive enriched, analysis-ready task data.

ANALYSIS

SQLite Local-First

WAL mode for concurrent reads, FTS5 full-text search, JSON1 extension, migration runner. Zero external database dependencies.

SQLITE_WAL

NiceGUI Dashboard

Real-time web dashboard with YoRHa Tower theme. Pool overview, task board, detail views, analytics charts, and dependency graph visualization.

NICEGUI

CLI Interface

Rich terminal interface via Typer. Task CRUD, pool operations, server management, and evaluation commands. JSON output mode for scripting.

TYPER+RICH

Self-Evaluation System

8-dimension benchmarking framework with weighted scoring, gap detection, golden task validation, and quality gates. Drives iteration cycles.

8 DIMENSIONS

SEC 003 -- SYSTEM TOPOLOGY

[ARCHITECTURE]

Multi-layer architecture with unified task service facade.

[EXTERNAL CONSUMERS]

Cursor (MCP) OpenClaw REST API Dashboard CLI

MCP Server

(stdio)

REST API

(FastAPI)

CLI

(Typer)

NiceGUI

Dashboard

Task Service ◄ EventBus (pub/sub)

State Machine 15 triggers × 10 states

SQLite (WAL mode) FTS5 · JSON1 · Indexes

TASK LIFECYCLE FLOW

SEC 004 -- DEPLOYMENT PROTOCOL

[INITIALIZATION]

Get operational in under 60 seconds.

BASH

# [INSTALL] Clone and install
pip install -e ".[dev]"

# [MIGRATE] Initialize the database
arktower server migrate

# [DEPLOY] Start the dashboard (NiceGUI + API)
arktower server start

# [DEPLOY] API-only mode
arktower server start --mode api

# [DEPLOY] MCP server for Cursor integration
arktower server mcp

OPERATIONS

# [CREATE] New task entry
arktower task create "Implement JWT authentication" \
  --priority high \
  --tags "python,api,auth" \
  --description "Add JWT-based auth to the API gateway"

# [QUERY] List and filter tasks
arktower task list --status queued --json

# [ADVANCE] Task lifecycle transitions
arktower task advance <task-id> enqueue
arktower task claim <task-id> agent-1
arktower task complete <task-id> --output "Implemented in PR #42"

MCP CONFIG

// .cursor/mcp.json
{
  "mcpServers": {
    "arktower": {
      "command": "python",
      "args": ["-m", "arktower.mcp.server"]
    }
  }
}

SEC 005 -- SYSTEM DIAGNOSTICS

[SYSTEM.STATUS]

Self-evaluation scores across 8 agent-oriented capability dimensions.

lifecycle_correctness

1.00

search_effectiveness

1.00

analysis_accuracy

1.00

archive_integrity

1.00

concurrency_safety

1.00

api_completeness

0.95

task_format_quality

0.87

dispatch_reliability

0.71

Composite Score

GATE: STANDARD (≥ 0.85) -- PASSED

0.9179

WEIGHTED AVERAGE / 8 DIMENSIONS