Skip to content

0002 - Custom Task Management System with Agent Integration

Status

Accepted

Date

2026-03-30

Context

The current interaction model between operator and agent is fully conversational: the operator opens the Claude Cowork session and manually types each task. This creates several friction points:

  • Tasks cannot be queued ahead of time or prioritised asynchronously
  • There is no persistent record of what work was requested, what the agent did, or what was completed
  • The operator must be present to initiate every piece of work
  • The Claude context window fills up across a long session, and there is no mechanism to hand off to a fresh context cleanly between tasks
  • Token usage is invisible — the operator has no way to budget work across a session or project

The goal is a lightweight, agent-native task management system where:

  1. An operator creates tasks (with context, priority, and acceptance criteria) in a management UI
  2. The agent autonomously picks up queued tasks in priority order
  3. Each task runs in its own context window budget, with token usage tracked in real time
  4. When the remaining token budget for a context falls below a configurable threshold, the agent completes or checkpoints the current task, marks it done or pauses it, and pulls the next task into a fresh context
  5. Completed tasks, findings, and outputs are persisted back to the task record

Decision Drivers

  • Kubernetes-first: the system should run inside the cluster alongside other platform services, not locally on the Mac mini
  • Isolation: the initial implementation is self-contained with no external integrations; Gitea or other tool integrations can be added later
  • Agent autonomy: once a task queue exists, the agent should be able to work through it without the operator being present
  • Agent-native API: the management system must expose a clean, structured API (or MCP interface) that an agent can query and update without scraping a UI
  • Task visibility: the operator needs a management view — queue status, task history, what the agent is currently working on, token consumption
  • Token budget awareness: the system must track Claude API token consumption per task and per session to avoid context overflow
  • Auditability: every action the agent takes on a task should be traceable — what was asked, what was done, what tokens were consumed
  • Extensibility: Gitea webhook integration, Slack notifications, or other connectors can be bolted on later without re-architecting the core

Considered Options

  • Option A — Gitea Issues as task source + dedicated MCP server on Mac mini + Claude API usage tracking
  • Option B — Custom task management web app deployed to Kubernetes, isolated from external tools, with agent-friendly REST/MCP API (Selected)
  • Option C — Gitea Projects (native kanban board) + polling daemon + local token counting

Decision Outcome

Chosen option: Option B — Custom task management web app on Kubernetes, because:

  • It runs entirely inside the cluster, keeping the architecture consistent with the principle of minimising local dependencies
  • Starting isolated (no Gitea integration) keeps the initial scope small and deliverable; external integrations are addable incrementally
  • A purpose-built data model (task, status, priority, token budget, agent log) is a better fit for agent consumption than adapting Gitea Issues
  • The management UI gives the operator a clear overview of the queue, active work, and history without relying on a third-party tool
  • The REST/MCP API surface can be designed specifically for agent interaction — structured task pickup, status updates, and token reporting — rather than being constrained by Gitea's issue API shape

Option A — Gitea Issues + MCP server on Mac mini

Architecture: - Gitea Issues as task source (labels for status, priority; milestones for sprints) - MCP server running on Mac mini exposes get_next_task, update_task_status, report_token_usage tools - Token tracking via Claude API usage object written to a local SQLite file

Pros: - Zero new infrastructure — Gitea and the Mac mini already exist - Issues are human-readable and familiar - No deployment work required

Cons: - Runs locally on Mac mini — not aligned with the Kubernetes-first direction - Gitea Issues is not designed for agent consumption; status transitions require label manipulation - Token tracking is local and not visible in the management UI - Local MCP server has no HA; if the Mac mini is offline, the agent cannot pull tasks

Option B — Custom task management web app on Kubernetes (Selected)

Architecture: - Lightweight web application deployed as a Kubernetes Deployment in the tools namespace - Postgres backend (CloudNativePG) for task persistence - REST API (and optionally MCP server endpoint) for agent interaction: GET /tasks/next, PATCH /tasks/{id}, POST /tasks/{id}/logs - Management UI: queue view, task detail, agent activity log, token usage per task - No Gitea integration in v1 — tasks are created directly in the UI or via the API - Token budget tracked per task via reported usage from the Claude API response

Agent interaction flow: 1. Agent calls GET /tasks/next → receives highest-priority pending task with context and acceptance criteria 2. Agent works the task, periodically calling POST /tasks/{id}/logs with progress and token usage 3. When context budget threshold is reached, agent calls PATCH /tasks/{id} with status paused or done and a summary 4. Agent pulls next task in a fresh context

Future integrations (out of scope for v1): - Gitea webhook → auto-create tasks from labelled issues - Slack notifications on task completion - MCP server wrapping the REST API for richer agent tooling

Pros: - Kubernetes-native — consistent with platform architecture - Self-contained and easy to reason about in isolation - Data model purpose-built for agent workflows - Management UI gives operator full visibility - Token tracking is centralised and visible

Cons: - Requires building and maintaining a new service - Needs a Postgres instance (though CloudNativePG is already in the cluster) - More upfront work than Option A

Option C — Gitea Projects + polling daemon

Architecture: - Gitea Projects kanban board as task queue - Polling daemon (cron job or sidecar) on Mac mini checks board state and calls the agent - Token counting done locally via log scraping

Pros: - Native Gitea UI, nothing new to build - Familiar kanban metaphor

Cons: - Gitea Projects has poor API support for programmatic state transitions - Polling is fragile and introduces latency - Token tracking requires scraping logs — unreliable - Runs locally — same availability concerns as Option A