agent-tasks

Enforced workflows for human-agent delivery.

Let humans and AI agents collaborate on tasks with explicit claim gates, transition preconditions, review signals, audit trails, and team-scoped permissions.

Most tools help agents manage tasks. agent-tasks helps teams control when agent work may actually move forward.

Live: agent-tasks.opentriologue.ai. Free tier; sign in, create a team, generate an API token in Team settings → API Tokens, and your local Claude Code (or CLI, or curl) can claim work in under a minute.

Overview

AI agents are fast; without workflow control that speed is plausible chaos: tasks claimed on vague descriptions, transitions that skip review, hand-offs nobody can audit. agent-tasks enforces the rules server-side instead of relying on prompt discipline: a confidence-scored claim gate, declarative per-transition preconditions (branchPresent, prPresent, prMerged, ciGreen), a durable pull-based signal inbox for human-agent hand-offs, and an audit row on every claim, transition, update, and admin override. Full mechanism in docs/governance.md.

Key features

The monorepo holds five workspace packages. backend, frontend, and cli version together as one deployable surface; mcp-server and mcp-bridge version independently as separate npm artefacts on their own release cadence. The version skew between the two groups is intentional.

Package	Purpose	Docs
backend	Hono + Prisma REST API: routes, services, gate registry, auth middleware	docs/architecture.md
frontend	Next.js board and list UI	docs/architecture.md
cli	Standalone @agent-tasks/cli REST client	cli/docs/commands.md
mcp-server	Stdio MCP server wrapping the backend API over a bearer token	docs/response-contract-v1.md
mcp-bridge	CLI wrapper resolving a token (env/keychain/file) and handing off to mcp-server	same file

Highlights, each detailed in Next steps below:

• Deterministic, heuristic confidence scoring of agent claims on vague tasks; no LLM in the loop. It blocks such a claim only when the project's enforcementMode is BLOCK; the default WARN records it and lets it through.
• Backlog routing: agent-created tasks land in backlog, invisible to task_pickup, until a human promotes them.
• Configurable workflows: in-browser editor for states, transitions, required roles, gates, labels and agent instructions, with reachability analysis. The editor adds, renames, removes and marks terminal custom states (open stays the fixed initial state; backlog and abandoned are reserved).
• GitHub integration: repo sync, branch/PR linking, and optional PR delegation with explicit human consent.
• Per-project sharing via short-lived hashed share-links, three role tiers, automatic solo-to-dual-control flip.
• OIDC SSO alongside email/GitHub, team-scoped, PKCE + JWKS.

More detail (task-template fields and dependencies, CSV/Excel import with Jira column auto-detection, board/list filters and search, admin project-share listing): docs/features.md.

Quick start

Local dev stack (prerequisites: Docker with Compose, git, openssl):

git clone https://github.com/LanNguyenSi/agent-tasks.git
cd agent-tasks
cp .env.example .env
echo "SESSION_SECRET=$(openssl rand -hex 32)" >> .env   # required, >= 32 chars
make dev-docker          # docker compose up: db + redis + backend + frontend, all on 127.0.0.1

This is a local development stack (NODE_ENV=development, compose project agent-tasks-dev), not a self-hosting path: it uses dev database credentials, Redis has no auth, and every published port (3000, 3001, 5432, 6379) binds the host side to 127.0.0.1, so none of them is published on the machine's other network interfaces; TRUSTED_PROXY_HOPS defaults to 0 because no reverse proxy is in front of the backend. A bare docker compose command uses this file. To self-host on a server use docker-compose.prod.yml (deploy notes: docs/okf/deploy.md); it has its own project name and always needs -f: docker compose -f docker-compose.prod.yml up -d --build. Volumes from a dev stack started before the project had an explicit name keep their old prefix and are not picked up: re-seed, or remove them with docker compose -p <old-project> down -v.

Open http://localhost:3000, register the first user, create a team, and generate an API token in Team settings → API Tokens. Full local-dev guide, a host-only setup (Node >= 22 and a reachable PostgreSQL; Docker optional), and Make targets: docs/development.md.

Or skip the install: open the Live link above and click Connect an agent in Team settings → API Tokens. The modal generates a team-scoped API token and a copy-paste install snippet for Claude Code (MCP), the CLI, or raw curl.

First five minutes as an agent

Once an MCP client is connected, the canonical verb order is task_pickup (find work) then task_start (claim it) then implement, gh pr create, task_submit_pr (record branch/PR metadata), task_finish (advance the task). One boundary to know from the start: agents claim tasks in open status only; a task an agent creates via task_create lands in backlog, unclaimable (403 backlog_not_promoted) until a human promotes it. A human can also take a promoted task back: demote moves an open task with no work or review claim to backlog (PATCH /api/tasks/:id { "status": "backlog" }, project write tier). It answers 409 while the task holds a claim, 400 from any status other than open, and the same rules apply to a grounding-enrolled task. See docs/governance.md.

task_pickup                                          # find work: signal, review-ready task, or claimable task
task_start     { taskId, branchName? }               # claim it, transition to in_progress
task_submit_pr { taskId, branchName, prUrl, prNumber } # after `gh pr create`
task_finish    { taskId, result?, prUrl? }           # advance to review, or to done with autoMerge in AUTONOMOUS projects

A project with a multi-stage workflow (for example the AI Coding Agent Pipeline template) adds task_advance { taskId, to? } between task_start and task_finish: it moves the claimed task one forward stage at a time. See docs/workflow-preconditions.md.

The four-step MCP cold-start path (initialize handshake, workflow_primer, projects_get_effective_gates, task_pickup), the full MCP tool table, CLI and curl equivalents, and the response/receipt shapes: docs/getting-started.md, docs/agent-workflow.md, and docs/response-contract-v1.md.

Next steps

Getting started

• docs/getting-started.md: connect an agent (Claude Code/MCP, CLI, curl), tokens, scopes.
• docs/development.md: local dev stack, Make targets, Docker vs. host setup.
• CONTRIBUTING.md: how to propose a change.

Agent workflow and governance

• docs/agent-workflow.md: the v2 verb surface end to end, with CLI/curl equivalents.
• docs/governance.md: confidence-scoring claim gate, backlog routing, transition preconditions, governance modes.
• docs/workflow-preconditions.md: per-transition rule reference and authoring guide.
• docs/permissions.md: role/action permission matrix.
• docs/state-machines.md: task and workflow state charts.

API and contracts

• docs/features.md: task templates and dependencies, CSV/Excel import with Jira column auto-detection, board/list views, admin project-share listing.
• docs/v2-api.md: REST route overview; the live OpenAPI doc (Swagger UI) describes a subset of the API.
• docs/api-contract.md: what the OpenAPI document covers and where the rest of the API is documented.
• docs/response-contract-v1.md: MCP receipt shapes, include, and error catalog.
• docs/domain-model.md: entities, relations, and the fields that drive governance.
• docs/events.md: domain events.
• docs/signal-payload-design.md: the agent signal inbox payload design.

Operations

• docs/architecture.md: runtime topology, modules, boundary rules.
• docs/deploy-verify-strategy.md: deploy and verification approach.
• docs/webhook-setup.md: optional GitHub webhook setup.
• docs/ops-backups.md: production database and uploads volume backup/restore runbook.
• docs/review-automation-policy.md / docs/review-notification-policy.md: review automation and notification policy.
• docs/enterprise-sso.md: OIDC SSO configuration.
• docs/roadmap.md: shipped and planned work.

Further reference material (use cases, sequence flows, ADRs, design notes, the OKF knowledge bundle) lives under docs/.

Development and contributing

make install   # all workspace deps (npm ci)
make setup     # .env + Prisma client
make test      # frontend, cli, backend test suites (backend needs PostgreSQL)
make lint      # backend + frontend lint

Full guide: docs/development.md. Contribution process: CONTRIBUTING.md.

License

MIT.