aio-kanban-monitor

Kanban Auto-Dispatch Monitor

Watches .kanban/board.md for changes. For each task in column <status> whose content (as judged by you, inline) contributes to free-text mission <goal>, spawns a sub-agent with a full self-contained prompt. Sub-agent owns the task lifecycle (Todo→Doing→Done) — this skill only orchestrates.

Dependency: fswatch is required. Install it before starting: brew install fswatch. The monitor script exits with code 3 if fswatch is not found — the skill will detect this and tell you.

This skill REQUIRES the v3 kanban storage layout (index board + per-task files). See the aio-kanban skill.

---

Arguments

• <status> (required): one of Backlog, Todo, Doing, Done, Blocked. Typically Todo.
• <goal> (required): free-text mission statement, e.g. "ship v2 release", "reduce p99 latency under 200ms". Used both to filter tasks (you judge relevance) and to anchor the spawned sub-agent's mission.

If either is missing, STOP and ask the user. Do NOT guess.

---

Preconditions (check before starting the loop)

1. .kanban/board.md exists. If not → tell user to run aio-kanban init first. EXIT.
2. .kanban/tasks/ directory exists. If not → board is v2, not v3. Tell user to migrate (manually re-init with aio-kanban, then re-create tasks as files). EXIT.
3. fswatch is installed (the monitor script will exit 3 if not — install via brew install fswatch). If missing → tell user how to install, EXIT.
4. <status> is one of the allowed columns. If not → STOP, ask user.
5. <goal> is non-empty. If not → STOP, ask user.

---

Algorithm

state:
  dispatched: Set<TaskID>     # IDs we've already spawned this session
  judged_no:  Map<TaskID, hash-of-task-content>  # IDs we judged irrelevant; key on content hash so edits re-judge
  running:    TaskID | null   # the one currently-running sub-agent, if any
  watch_id:   string          # task id of the board watch

setup:
  1. Validate args + preconditions.
  2. Arm the board watch:
       Monitor(command="bash ${CLAUDE_PLUGIN_ROOT}/skills/aio-kanban-monitor/scripts/kanban-monitor.sh 2>&1",
               description="kanban board changes (<status> / <goal>)",
               persistent=true)
     Capture the returned task id as watch_id. `persistent` is required: this watch must
     live as long as the session, and a timeout would end it mid-mission in silence.
     `2>&1` routes the script's FATAL lines into the event stream where you can see them.
  3. Tell the user: "Monitoring .kanban/board.md for tasks in <status> matching goal '<goal>'.
                    Send /cancel to stop."

loop (event-driven — the watch pushes to you; never poll it):
  4. Each stdout line arrives on its own as a notification. The synthetic `start` line
     fires the first pass; each later line is one "board changed" event.
     On each → run a PARSE PASS (see below).
  5. If a sub-agent is `running`, do NOT spawn another. Wait for it to finish
     (Claude Code auto-notifies on background-agent completion). When it
     completes, clear `running` and run another PARSE PASS immediately.
  6. If the watch exits, its exit code is reported: 2 = board missing, 3 = fswatch
     missing, other = unexpected. Surface it and stop — once the watch is gone no
     events arrive, and that silence is indistinguishable from "no new tasks".
  7. Continue indefinitely until the user cancels.

cleanup (when user cancels):
  - Stop the board watch: TaskStop(watch_id).
  - Print a summary: tasks dispatched this session, any still in Doing.