agent-tasks: Instructions file for Claude Code

agent-tasks

Architecture

Layered architecture with explicit dependency injection (no global state):

src/
  index.ts    MCP stdio entry point; one process serves the REST API (leader election on the port; the others retry and take over)
  server.ts   REST server (standalone: node dist/server.js [--port] [--db])
  domain/     tasks (stages, dependencies, artifacts, claiming), events, validation
  storage/    SQLite (better-sqlite3, WAL mode)
  transport/  REST (node:http, JSON only) + guard.ts (Host/Origin/Content-Type), MCP (official SDK `Server` over stdio, mcp.ts)
plugin/       Claude Code plugin (.mcp.json + one mod: hooks/register.tsx + view.tsx = /pipeline pane)

• No frameworks — no React, Vue, Express. Pure Node.js + TypeScript; runtime deps are the official MCP SDK (@modelcontextprotocol/server) and better-sqlite3. No agent-common.
• context.ts is the DI root — wires all services together.
• src/ stays host-agnostic; Claude-specific glue belongs in plugin/ (the mod) or scripts/hooks/ (command hooks wired by scripts/setup.js).
• Soft deps: AgentBridge → agent-comm (notifications), KnowledgeBridge → agent-knowledge (push learnings/decisions on task completion). Both HTTP-only, fail-open.

UI surfaces

There is no web dashboard (removed in 2.0, with the WebSocket, the UI files and the agent-desk plugin).

• Claude Code pane (plugin/hooks/register.tsx + view.tsx, Claude Code 2.1.289+ function hooks): /pipeline opens it (the built-in /tasks is taken); /pipeline 12 opens task 12, /pipeline <text> filters the board. Tabs Board (open tasks by stage, Find over id, title, agent, project and tags, waits for #N on blocked rows), Done (recently closed, who and where, the result beneath), New (title, project, priority, tags, description; Enter walks the fields). Task detail: stage strip, actions for a task in progress (Advance › next, Complete, ‹ Send back with a stage, Fail; Cancel, Delete with a confirmation), facts, description, subtasks, artifacts (unfold as Markdown), comments + a comment field. No Claim: agents claim with task_stage, and an assignee that is no live agent-comm agent gets reaped by the cleanup; an unclaimed task has no Advance either (it would sit in progress with nobody on it). A blocked task shows no Advance or Complete (the domain refuses both while a blocks dependency is open), only what it waits for. A stage gate is said under the actions from task_get's gate_needs (TaskService.gateNeeds, the gate's one reader; checkStageGate refuses Advance and Complete on it), said with who gives it (gateHint); Advance and Complete lose primary while it holds. The ring never lands in a text field when /pipeline opens or moves to a view (a later /pipeline N would be typed into it and posted): a comment gate sends it to the comment field only after a press the gate refused (toCommentIfGated, which also shortens that refusal to ✗ #N can't leave <stage> yet since the hint says why, and keeps a refused Complete's form open with its words and the hint under it); the New tab is the one view that starts in a field. A stage nobody works on folds past 10 rows (boardGroups; board folds survive opening a task); unfolded, its toggle stays after row 10 and the ring goes to the first row it showed. Status line entry and the board's summary are the same text (headline() in view.tsx); toasts only for tasks that finished or reached review since the last poll; one prompt.context block with what is in flight. Acts as AGENT_TASKS_USER, else the OS user (created_by, comment author, by). Polls GET /api/board every 5 s while open, 30 s while closed. REST only, through $.http.fetch on AGENT_TASKS_PORT (default 3422). View state in $.state (contract plugin/types/index.d.ts). Opened as a plain sidebar (no closeOnEscape); /pipeline reports isPlaced: false with the reason. Focus lands explicitly after every navigation and action, a fold's toggle included (landing(), toggle() in register.tsx): the engine keeps the ring at its place in the focus order across a redraw, not on a key, so a redraw that adds or drops a control above it would move it; a key that names the new state (foldKey, advance:<stage>, complete:<stage> from completeKey, the fresh comment:<rev>, Refresh's refresh:<rev> from refreshKey) makes the focus wait for the drawing that shows it; landOnNewBoard waits on Refresh, a button, so nothing typed meanwhile lands in a field. Back up after the server was away, the ring returns where it was before (landBack), else lands as on a fresh open. The pane's own moves and its autoFocus taking the ring both reach ui.focus as origin plugin; focusOn marks its own (ownMoves, a set: moves overlap), so a take (ctrl+x tab) is put back on the last focused key while it is drawn, and openPane clears focused so a command's view starts at its landing. The element landing() names is also drawn autoFocus, and /pipeline closes and reopens an open pane after setting the view, because a take would otherwise put the ring back on the element it last held. Every function that takes $ must be a top-level declaration (claude plugin validate enforces it). Tests: plugin/tests/*.test.ts under claude plugin test plugin (npm run plugin:check); vitest excludes plugin/. Type-check with a tsconfig outside the folder (never tsc -p plugin, it emits .js into plugin/).
• MCP tool results (JSON + the pipeline footer) for every other host.