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)
- 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.
- 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.
- One write-capable worker at a time. While a worker is in flight the
iteration only reads. Never run two write-capable agents concurrently.
- 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.
- 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.
- 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.
- Completion is read, never trusted. A card advances only on evidence
this iteration actually read.
The iteration
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.
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).
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.
Choose the dispatchable card. The oldest picked item with no live
worker and no recorded blocker. queued items are not yours to pick.
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:
card: <id>
spec: <SPEC-ID> # only when the card carries one
cmd: <the card's work in one line; the phase command when a SPEC is attached>
evidence: .moai/reports/<card-id>/evidence.md
Route the spawn to the agent the card's work matches under the standard
delegation rules; where no specialist matches, a general-purpose spawn
with a domain whitelist. The worker prompt carries the block plus these
standing orders: rename the worktree branch to WT-<slug> (a
descriptive slug, never the card id) first;
implement the card; verify lane-locally; write the evidence file with
decisions, verbatim output tails of the checks run, explicit gaps, and
residual risk; commit by explicit pathspec; never push.
Collect on evidence. When the worker returns, read the evidence file
it names. Advance the card — moai todo done <t-id> — only when the
evidence shows the work complete: verbatim passing output present, gaps
named. A missing, unreadable, or stale evidence file is a gap: the card
stays picked, the report says why, and the card is not re-dispatched
this iteration. Absence of a failure signal is not a pass.
Report. Close with two to six lines: queue summary, what was
dispatched or collected, which evidence was read, blocked cards and the
decisions they wait on. This report is what the operator reads on
reattach — name what you read, not what you were told.
Factory seam (reserved, not implemented)
The single-worker dispatch above is the only mode. Fanning a card out to
numbered factory worker lanes — the multi-lane launcher surface — is
separate work; when the foreman grows that routing, it lands here as a
second dispatch mode chosen per card. Until then this loop spawns one
subagent per card, reads no factory state, and launches no lanes.
Failure handling
Stop the loop (ScheduleWakeup with stop: true), with a one-line reason,
when the loop cannot do its job: the queue file is repeatedly unreadable,
the queue watch cannot be armed, or this skill's own surface is broken. A
transient worker failure is not a loop failure — record it on the card and
let the next iteration decide whether to re-dispatch.
1---
2name: moai-kanban-foreman
3description: >
4 One unattended kanban foreman iteration: watch the backlog queue, dispatch
5 the next operator-picked card to an isolated worker, collect completion
6 evidence on read (not on claims), and report. This is the body the
7 project's loop.md driver invokes each iteration of a bare /loop; it can
8 also be invoked directly to test one cycle by hand.
9
10when_to_use: >
11 Use when a bare /loop kanban foreman iteration fires (the loop.md driver
12 points here), or when the operator asks for a single manual foreman pass
13 over the backlog queue.
14
15license: Apache-2.0
16compatibility: Designed for Claude Code
17allowed-tools: Read, Grep, Glob, Bash(moai todo:*), Bash(git status:*), Bash(git log:*), Bash(git rev-parse:*), Bash(git diff:*), Bash(git show:*)
18disallowed-tools: AskUserQuestion
19user-invocable: false
20metadata:
21 source: https://skillmd.com/skills/modu-ai/moai-kanban-foreman
22 version: "1.0.0"
23 category: "workflow"
24 status: "active"
25 tags: "kanban, foreman, loop, backlog, dispatch, unattended"
26
27# MoAI Extension: Progressive Disclosure
28progressive_disclosure:
29 enabled: true
30---
31
32# Kanban Foreman Loop Iteration
33
34One unattended pass of the kanban foreman: watch the backlog queue, dispatch
35the next operator-picked card to an isolated worker, collect completion
36evidence, report. The queue surface is `moai todo`; the dispatch protocol and
37card classes live in the kanban dispatch rule (`.claude/rules/moai/workflow/kanban-dispatch.md`).
38
39## Running unattended
40
41`AskUserQuestion` is removed from the tool pool while this skill is active —
42that is the mechanical guarantee that the loop cannot stop and ask. Anything
43that would have been a question becomes a line in the iteration report, and
44anything that genuinely needs the operator's decision becomes a blocked card
45under Boundaries below.
46
47Deployment: start a session in the project, run bare `/loop`, then
48background the session — loop tasks carry over to the background session and
49keep running without a terminal. `Esc` cancels the pending wakeup of a
50waiting loop. A recurring loop expires seven days after creation; restart it
51when the board still needs a foreman. Background monitors do not survive a
52session resume — the first iteration after a resume re-arms the queue watch.
53
54The session's permission settings must already allow what this loop uses
55(queue reads, git inspection, the worker spawn). A permission prompt that
56surfaces while unattended stalls the iteration until someone attaches;
57pre-approving that surface in project settings is the operator's setup step,
58not something this loop can do for itself.
59
60## Boundaries (hard)
61
621. **The operator admits and picks work.** Only backlog items whose state is
63 already `picked` are dispatchable. Never run `moai todo add`; never run
64 `moai todo next <n>` — that mutation is the operator's pick. Never invent,
65 reword, or reorder cards. An empty queue is a legitimate state: say so and
66 idle.
672. **No approval gate is answered on the operator's behalf.** When a card's
68 next step needs a human decision that is not already recorded as made
69 (plan-to-run kickoff approval, a review severity call, a scope choice),
70 do not proceed. Leave the card `picked`, name it blocked-for-operator in
71 the report together with the decision it waits on, and move on.
723. **One write-capable worker at a time.** While a worker is in flight the
73 iteration only reads. Never run two write-capable agents concurrently.
744. **Every worker runs in its own worktree** (`isolation: "worktree"` on the
75 spawn; relative paths in the prompt — the worker's CWD is its worktree
76 root). Nothing writes to the shared checkout.
775. **No integration actions.** No push, no pull request, no merge, no branch
78 deletion, no worktree disposal. The card's branch is unpushed and its
79 worktree is the work's only instance; both stay until the operator
80 integrates them. The report names the branch and the worktree path.
816. **Verification is lane-local.** The worker runs only the checks its own
82 change can affect; the full suite belongs to CI. Never spawn background
83 CPU load — the queue watch below is the only long-running process this
84 loop arms.
857. **Completion is read, never trusted.** A card advances only on evidence
86 this iteration actually read.
87
88## The iteration
89
901. **Queue watch.** If no backlog monitor is live (first iteration, or after
91 a resume), arm one persistent Monitor on the queue file:
92
93 - `command`:
94
95 ```sh
96 f=.moai/state/kanban/backlog.json
97 last=init
98 while true; do
99 if [ -f "$f" ]; then cur=$(cksum "$f"); else cur=missing; fi
100 if [ "$cur" != "$last" ]; then
101 [ "$last" != init ] && echo "backlog changed"
102 last=$cur
103 fi
104 sleep 5
105 done
106 ```
107
108 - `persistent: true`
109 - `description: backlog queue watch`
110
111 The queue file is replaced atomically on every mutation, so tools that
112 follow a single file handle are the wrong shape here; the checksum poll
113 emits one line per change and costs one tiny read every five seconds. Do
114 not tighten the interval, and do not arm a second watcher. Each emitted
115 line, like each scheduled wakeup, is a prompt to run this same idempotent
116 iteration — an iteration that finds nothing to do ends quickly.
117
1182. **Read the queue.** `moai todo list --json` (lock-free). A missing queue
119 file is an empty queue, never an error. Records carry `id`, `text`,
120 `spec_id`, and `state` (`queued` | `picked` | `dropped`).
121
1223. **Collect before dispatch.** If a worker dispatched by an earlier
123 iteration has returned, read its evidence file first (step 6). If a
124 worker is still running, end the iteration with a one-line status.
125
1264. **Choose the dispatchable card.** The oldest `picked` item with no live
127 worker and no recorded blocker. `queued` items are not yours to pick.
128
1295. **Dispatch one worker** with the Agent tool, `isolation: "worktree"`. The
130 dispatch is a fixed-field address block — a pointer, not a copy, ten
131 lines at most:
132
133 ```
134 card: <id>
135 spec: <SPEC-ID> # only when the card carries one
136 cmd: <the card's work in one line; the phase command when a SPEC is attached>
137 evidence: .moai/reports/<card-id>/evidence.md
138 ```
139
140 Route the spawn to the agent the card's work matches under the standard
141 delegation rules; where no specialist matches, a general-purpose spawn
142 with a domain whitelist. The worker prompt carries the block plus these
143 standing orders: rename the worktree branch to `WT-<slug>` (a
144 descriptive slug, never the card id) first;
145 implement the card; verify lane-locally; write the evidence file with
146 decisions, verbatim output tails of the checks run, explicit gaps, and
147 residual risk; commit by explicit pathspec; never push.
148
1496. **Collect on evidence.** When the worker returns, read the evidence file
150 it names. Advance the card — `moai todo done <t-id>` — only when the
151 evidence shows the work complete: verbatim passing output present, gaps
152 named. A missing, unreadable, or stale evidence file is a gap: the card
153 stays `picked`, the report says why, and the card is not re-dispatched
154 this iteration. Absence of a failure signal is not a pass.
155
1567. **Report.** Close with two to six lines: queue summary, what was
157 dispatched or collected, which evidence was read, blocked cards and the
158 decisions they wait on. This report is what the operator reads on
159 reattach — name what you read, not what you were told.
160
161## Factory seam (reserved, not implemented)
162
163The single-worker dispatch above is the only mode. Fanning a card out to
164numbered factory worker lanes — the multi-lane launcher surface — is
165separate work; when the foreman grows that routing, it lands here as a
166second dispatch mode chosen per card. Until then this loop spawns one
167subagent per card, reads no factory state, and launches no lanes.
168
169## Failure handling
170
171Stop the loop (`ScheduleWakeup` with `stop: true`), with a one-line reason,
172when the loop cannot do its job: the queue file is repeatedly unreadable,
173the queue watch cannot be armed, or this skill's own surface is broken. A
174transient worker failure is not a loop failure — record it on the card and
175let the next iteration decide whether to re-dispatch.