moai-kanban-foreman

Dispatches picked backlog cards to isolated worktree workers and verifies completion evidence.

1.2k|222|Updated Sep 16, 2025
One-click install
npx skills add https://github.com/modu-ai/moai-adk --skill moai-kanban-foreman
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: moai-kanban-foreman
Source: https://github.com/modu-ai/moai-adk/tree/main/internal/template/templates/.claude/skills/moai-kanban-foreman
Command: npx skills add https://github.com/modu-ai/moai-adk --skill moai-kanban-foreman

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Running an unattended kanban loop requires a disciplined foreman that watches the backlog queue, dispatches only operator-picked work to isolated workers, and refuses to trust completion claims without reading actual evidence — all without ever stopping to ask questions.

Core Features & Use Cases

  • Unattended Queue Watching: Arms a persistent checksum-based monitor on the backlog file and runs idempotent iterations triggered by queue changes or scheduled wakeups.
  • Isolated Worker Dispatch: Spawns one write-capable worker per card in its own git worktree with a fixed-field dispatch block, standing orders, and lane-local verification.
  • Evidence-Based Completion: Advances a card only after reading the worker's evidence file containing verbatim check output, named gaps, and residual risk — never on claims alone.
  • Use Case: An operator backgrounds a Claude Code session running a bare /loop; each iteration the foreman reads the moai todo queue, dispatches the oldest picked card to a worktree worker, collects its evidence on return, and reports blocked cards awaiting operator decisions.

Quick Start

Run a bare /loop in the project session and background it so the kanban foreman watches the backlog and dispatches picked cards unattended.

Frequently Asked Questions about moai-kanban-foreman

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I run an unattended kanban loop in Claude Code?

Start a session in the project, run a bare /loop, then background the session so loop tasks keep running without a terminal. Pre-approve the required permissions in project settings, since a permission prompt surfacing while unattended stalls the iteration.

How does the kanban foreman decide which backlog card to dispatch?

It dispatches only the oldest card whose state is already picked, with no live worker and no recorded blocker. Queued items are never picked by the foreman — admitting and picking work is exclusively the operator's action.

Can the foreman run multiple workers at the same time?

No. Only one write-capable worker runs at a time, and each worker operates in its own git worktree so nothing writes to the shared checkout. Multi-lane factory dispatch is a reserved seam that is not yet implemented.

What happens when a worker finishes a dispatched card?

The next iteration reads the worker's evidence file and advances the card only if the evidence shows verbatim passing check output and named gaps. A missing, unreadable, or stale evidence file leaves the card picked and blocks re-dispatch that iteration.

Why does the kanban loop stop asking questions or stall?

AskUserQuestion is removed from the tool pool while the skill is active, so anything needing a human decision becomes a blocked card in the report. Stalls usually come from unapproved permission prompts, which must be pre-approved in project settings.

Does the foreman push branches or create pull requests?

No. It performs no integration actions — no push, pull request, merge, branch deletion, or worktree disposal. The card's branch stays unpushed and its worktree remains until the operator integrates them manually.