Technical references, architecture guides, and API specifications
Multi-layer architecture with unified task service facade, event bus, and pluggable storage.
Domain models (Task, TaskStatus, Trigger), StateMachine (15 triggers × 10 states), EventBus, TaskService facade, TaskNormalizer.
DOMAINTaskRepository protocol, SqliteTaskRepository (CRUD, FTS5, atomic claim), migration runner with 3 migrations.
PERSISTENCEFastAPI app factory, REST routes at /api/v1/*, WebSocket manager for real-time events.
HTTPMCP server with 12 tools, 1 resource, 2 prompts. Stdio transport for Cursor and Claude.
AI_INTEGRATIONTyper CLI with Rich output: task, pool, server, eval subcommands. JSON output mode.
TERMINALNiceGUI dashboard with YoRHa theme, i18n (EN/ZH), dark/light toggle, pool overview, task board, analytics.
DASHBOARDREST API endpoints, MCP tools, and WebSocket events.
| Method | Path | Description |
|---|---|---|
GET | /api/v1/health | Health check -- returns system status |
POST | /api/v1/tasks | Create a new task |
GET | /api/v1/tasks | List tasks with optional filters (status, priority, tags, search) |
GET | /api/v1/tasks/{id} | Get full details of a specific task |
PATCH | /api/v1/tasks/{id} | Update task fields (title, description, priority, tags, etc.) |
DELETE | /api/v1/tasks/{id} | Delete a task from the pool |
POST | /api/v1/tasks/{id}/advance | Advance task via state machine trigger |
POST | /api/v1/tasks/{id}/claim | Atomically claim a queued task for an agent |
POST | /api/v1/tasks/{id}/complete | Mark task as completed with optional output |
GET | /api/v1/tasks/{id}/history | Get task event history (audit trail) |
GET | /api/v1/pool/stats | Pool statistics -- counts by status, priority, queue age |
GET | /api/v1/pool/next | Get highest-priority queued task (capability matching) |
POST | /api/v1/templates | Create a task template |
GET | /api/v1/templates | List all task templates |
POST | /api/v1/archives/{id} | Archive a terminal task to JSON snapshot |
WS | /ws | WebSocket -- real-time task lifecycle events |
| Tool Name | Description | Key Parameters |
|---|---|---|
create_task | Create a new task in the pool | title, description, priority, tags |
list_tasks | List tasks with optional filters | status, priority, tags, limit, offset |
get_task | Get full details of a task | task_id |
claim_task | Claim a queued task for an agent | task_id, agent_id |
complete_task | Mark a task as completed | task_id, output |
search_tasks | Full-text search across tasks | query, limit |
get_pool_stats | Get pool statistics | (none) |
get_next_task | Get highest-priority queued task | (none) |
advance_task | Advance via state machine trigger | task_id, trigger, actor, notes |
fail_task | Mark a task as failed | task_id, error |
archive_task | Archive a terminal task | task_id, format |
create_from_template | Create task from a template | template_name, overrides |
Fired on every state machine transition. Payload includes task_id, trigger, from_status, to_status, actor.
LIFECYCLEFired when a new task is created. Payload includes the full task object.
CRUDFired on task field updates. Payload includes task_id and changed fields.
CRUDFired when a task is removed from the pool. Payload includes task_id.
CRUD8-dimension self-benchmarking framework with weighted scoring and quality gates.
| Dimension | Weight | Description |
|---|---|---|
lifecycle_correctness | 20% | State machine transitions, terminal state enforcement, audit trail |
dispatch_reliability | 20% | Lifecycle flows, atomic claims, capability matching, dependency gates |
task_format_quality | 15% | Task model completeness, agent fields, .task.md parser, normalizer |
search_effectiveness | 10% | FTS5 retrieval, tag filtering, combined filter accuracy |
api_completeness | 10% | REST endpoints, MCP tools, health check, authentication |
analysis_accuracy | 10% | Complexity scoring calibration, tag extraction recall |
archive_integrity | 10% | Snapshot roundtrip, export format correctness (JSON/NDJSON/CSV/MD) |
concurrency_safety | 5% | SQLite pragmas, atomic operations, FK enforcement |
| Gate | Composite ≥ | Coverage ≥ |
|---|---|---|
| Relaxed | 0.70 | 60% |
| Standard | 0.85 | 80% |
| Strict | 0.90 | 90% |
All CLI commands via the arktower entry point. Powered by Typer + Rich.
# Create a new task
arktower task create "Task title" \
--priority high \
--tags "python,api" \
--description "Detailed description"
# List tasks with filters
arktower task list --status queued --priority high --json
# Show task details
arktower task show <task-id>
# Advance via trigger
arktower task advance <task-id> enqueue
# Claim a task
arktower task claim <task-id> agent-1
# Complete a task
arktower task complete <task-id> --output "Done in PR #42"
# Search tasks (FTS5)
arktower task search "authentication api"
# Delete a task
arktower task delete <task-id># View pool statistics
arktower pool stats
# Get next task for claiming
arktower pool next
# Pool stats in JSON format
arktower pool stats --json# Run database migrations
arktower server migrate
# Start dashboard (NiceGUI + API)
arktower server start
# API-only mode (no dashboard)
arktower server start --mode api
# MCP server for Cursor/Claude
arktower server mcp# Run full evaluation
arktower eval run
# Evaluate specific dimension
arktower eval run --dimension lifecycle_correctness
# JSON output for CI/CD
arktower eval run --json
# View latest report
arktower eval report
# Validate golden tasks
arktower eval goldenIntegration configuration files for Cursor, NineS, and DevolaFlow.
{
"mcpServers": {
"arktower": {
"command": "python",
"args": ["-m", "arktower.mcp.server"]
}
}
}# NineS self-evaluation configuration
[project]
name = "arktower"
description = "Agent-oriented task pool system"
[eval]
command = "arktower eval run --json"
dimensions = [
"lifecycle_correctness",
"task_format_quality",
"dispatch_reliability",
"search_effectiveness",
"api_completeness",
"analysis_accuracy",
"archive_integrity",
"concurrency_safety"
]
[gates]
standard = { composite = 0.85, coverage = 80 }
strict = { composite = 0.90, coverage = 90 }# DevolaFlow configuration
project:
name: arktower
type: python
quality_gates:
relaxed:
composite_score: 0.70
test_coverage: 60
standard:
composite_score: 0.85
test_coverage: 80
strict:
composite_score: 0.90
test_coverage: 90
hooks:
pre_commit:
- "python -m pytest tests/ -x -q"
post_iteration:
- "arktower eval run"2026-04-14
Core System
Storage
Interfaces
Quality