/moai-factory-foreman

name: moai-factory-foreman
description: >
  One unattended factory 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 factory 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 gtd:*), 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: "factory, foreman, loop, backlog, dispatch, unattended"

# MoAI Extension: Progressive Disclosure
progressive_disclosure:
  enabled: true

Factory Foreman Loop Iteration

One unattended pass of the factory foreman: watch the backlog queue, dispatch the next operator-picked card to an isolated worker, collect completion evidence, report. The queue surface is `moai gtd`; the dispatch protocol and card classes live in the factory dispatch rule (`.claude/rules/moai/workflow/factory-dispatch.md`). `foreman` — an auxiliary role of the leader: the unattended watcher that dispatches the already-picked card to an isolated worker when no leader session is holding the queue.

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 queue 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 gtd add`; never run `moai gtd 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. A batch authorization (`/moai:todo --auto` — the operator's typed invocation-as-approval) is the card-pick gate's autonomous form (`.claude/rules/moai/workflow/auto-semantics.md` §9): within it, serial consumption on its own judgment, outside the keep-set (bar a `[보류` card, which is ranked last, not excluded), is authorized; queue ADMISSION stays the operator's. A lane takes its card through `moai factory next --card <id>`, never through this loop. 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. This is the foreman's own serialization, stricter than the doctrine it sits under — `one writer per tree`, owned by `.claude/rules/moai/core/agent-common-protocol.md` § Background Agent Execution. The foreman keeps one worker in flight so a failed iteration has exactly one author to read. 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 Monitor on the queue file, re-arming it at each expiry:

• `command`:

     # The queue directory, resolved the way factory.StateDirForRoot does for a
     # standard git-repository project: <moai-home>/db/<project-key>/todo,
     # keyed by the repository's canonical (primary-checkout) root.
     mh=${MOAI_HOME:-$HOME/.moai}
     root=$(git rev-parse --show-toplevel 2>/dev/null) || root=$PWD
     top=$(git worktree list --porcelain 2>/dev/null | sed -n 's/^worktree //p' | head -n 1)
     [ -n "$top" ] && root=$top
     root=$(cd "$root" && pwd -P)
     key=$(basename "$root"); key=$(printf '%s' "$key" | tr -c 'A-Za-z0-9._-' '-')
     sum=$(printf '%s' "$root" | sha256sum 2>/dev/null | cut -c1-8)