Issue maps & decisions

A dependency-first issue tracker, plus the decision channel your agent uses to ask you things.

An issue map is a dependency-first issue tracker drawn as a graph. Issues are nodes; blocks and contains are the edges. The headline isn't a backlog — it's what's ready to start right now.

The model

  • blocks — a real dependency. An issue turns ready the moment everything blocking it is done.
  • contains — grouping (an epic contains its tasks).
  • Status, priority, due date, assignee — the usual triage fields, editable on the web or over MCP/CLI.
  • Ready is derived. Not done + nothing unfinished blocks it + no open decision question = actionable. Agents use exactly this to pick their next task.

You can start with an empty project and plan in an issue map first — attach the scanned code map later. Issues can also point at code-map nodes ("this bug lives on /checkout"), and an issue targeting a screen that doesn't exist yet turns solid automatically when a publish finally ships that screen.

The decision channel

Every issue has a thread, and the thread has one special move: a question.

  1. Your agent hits a fork mid-task ("rotate tokens on every deploy, or keep them long-lived?").
  2. It posts the question on the issue (ask_issue over MCP). The issue stops being actionable.
  3. You get pulled in — Slack/Discord webhook, the terminal's "waiting on you" line, or the Needs you cards on your home page.
  4. You answer on the web (or from another agent session). The question is resolved; the agent picks the answer up and continues.

Decisions stay attached to the work they decided — six months later, the "why" is on the issue, not lost in a chat scrollback.

Threads also support plain notes, replies, @mentions (routes "waiting on you" to specific people), and answers/results.

From the terminal

alkahest issues pull            # list issues (ready/blocked/done derived)
alkahest issues add "Payment UI" --blocks <id>
alkahest issues status <id> doing
alkahest issues done <id>
alkahest issues comments <id>   # read a thread

Run alkahest issues --help for the full set (priority, due, assign, link, map, comment, reply, resolve).

On the web

The map view is graph-native: draw edges, see ready/blocked states at a glance, and open any issue's detail panel with its thread. The project's Issues page lists everything (including issues on no map) — a project can hold several issue maps, each a lens over the same pool of issues. Moving an issue between lenses works from an agent too — map_issue over MCP, or alkahest issues map <id> --map <slug> (--remove takes it off a map without deleting it).