/moai-kanban-foreman

name: moai-kanban-foreman
description: >
  One unattended kanban foreman iteration: watch the backlog queue, dispatch
  the next operator-picked card to an isolated worker, collect completion
  evidence on read (not on claims), and report. This is the body the
  project's loop.md driver invokes each iteration of a bare /loop; it can
  also be invoked directly to test one cycle by hand.

when_to_use: >
  Use when a bare /loop kanban foreman iteration fires (the loop.md driver
  points here), or when the operator asks for a single manual foreman pass
  over the backlog queue.

license: Apache-2.0
compatibility: Designed for Claude Code
allowed-tools: Read, Grep, Glob, Bash(moai todo:*), Bash(git status:*), Bash(git log:*), Bash(git rev-parse:*), Bash(git diff:*), Bash(git show:*)
disallowed-tools: AskUserQuestion
user-invocable: false
metadata:
  version: "1.0.0"
  category: "workflow"
  status: "active"
  tags: "kanban, foreman, loop, backlog, dispatch, unattended"

# MoAI Extension: Progressive Disclosure
progressive_disclosure:
  enabled: true

Kanban Foreman Loop Iteration

One unattended pass of the kanban foreman: watch the backlog queue, dispatch the next operator-picked card to an isolated worker, collect completion evidence, report. The queue surface is `moai todo`; the dispatch protocol and card classes live in the kanban dispatch rule (`.claude/rules/moai/workflow/kanban-dispatch.md`).

Running unattended

`AskUserQuestion` is removed from the tool pool while this skill is active — that is the mechanical guarantee that the loop cannot stop and ask. Anything that would have been a question becomes a line in the iteration report, and anything that genuinely needs the operator's decision becomes a blocked card under Boundaries below.

Deployment: start a session in the project, run bare `/loop`, then background the session — loop tasks carry over to the background session and keep running without a terminal. `Esc` cancels the pending wakeup of a waiting loop. A recurring loop expires seven days after creation; restart it when the board still needs a foreman. Background monitors do not survive a session resume — the first iteration after a resume re-arms the queue watch.

The session's permission settings must already allow what this loop uses (queue reads, git inspection, the worker spawn). A permission prompt that surfaces while unattended stalls the iteration until someone attaches; pre-approving that surface in project settings is the operator's setup step, not something this loop can do for itself.

Boundaries (hard)

1. **The operator admits and picks work.** Only backlog items whose state is already `picked` are dispatchable. Never run `moai todo add`; never run `moai todo next <n>` — that mutation is the operator's pick. Never invent, reword, or reorder cards. An empty queue is a legitimate state: say so and idle. 2. **No approval gate is answered on the operator's behalf.** When a card's next step needs a human decision that is not already recorded as made (plan-to-run kickoff approval, a review severity call, a scope choice), do not proceed. Leave the card `picked`, name it blocked-for-operator in the report together with the decision it waits on, and move on. 3. **One write-capable worker at a time.** While a worker is in flight the iteration only reads. Never run two write-capable agents concurrently. 4. **Every worker runs in its own worktree** (`isolation: "worktree"` on the spawn; relative paths in the prompt — the worker's CWD is its worktree root). Nothing writes to the shared checkout. 5. **No integration actions.** No push, no pull request, no merge, no branch deletion, no worktree disposal. The card's branch is unpushed and its worktree is the work's only instance; both stay until the operator integrates them. The report names the branch and the worktree path. 6. **Verification is lane-local.** The worker runs only the checks its own change can affect; the full suite belongs to CI. Never spawn background CPU load — the queue watch below is the only long-running process this loop arms. 7. **Completion is read, never trusted.** A card advances only on evidence this iteration actually read.

The iteration

1. **Queue watch.** If no backlog monitor is live (first iteration, or after a resume), arm one persistent Monitor on the queue file:

• `command`:

     f=.moai/state/kanban/backlog.json
     last=init
     while true; do
       if [ -f "$f" ]; then cur=$(cksum "$f"); else cur=missing; fi
       if [ "$cur" != "$last" ]; then
         [ "$last" != init ] && echo "backlog changed"
         last=$cur
       fi
       sleep 5
     done

• `persistent: true`
• `description: backlog queue watch`

The queue file is replaced atomically on every mutation, so tools that follow a single file handle are the wrong shape here; the checksum poll emits one line per change and costs one tiny read every five seconds. Do not tighten the interval, and do not arm a second watcher. Each emitted line, like each scheduled wakeup, is a prompt to run this same idempotent iteration — an iteration that finds nothing to do ends quickly.

2. **Read the queue.** `moai todo list --json` (lock-free). A missing queue file is an empty queue, never an error. Records carry `id`, `text`, `spec_id`, and `state` (`queued` | `picked` | `dropped`).

3. **Collect before dispatch.** If a worker dispatched by an earlier iteration has returned, read its evidence file first (step 6). If a worker is still running, end the iteration with a one-line status.

4. **Choose the dispatchable card.** The oldest `picked` item with no live worker and no recorded blocker. `queued` items are not yours to pick.

5. **Dispatch one worker** with the Agent tool, `isolation: "worktree"`. The dispatch is a fixed-field address block — a pointer, not a copy, ten lines at most: