agentleFS
modu-aimodu-ai/moai-adk/.claude/skills/moai-factory-foreman/SKILL.md

moai-factory-foreman

Skill1.3k starsChanged 2 months agoApache-2.0View on GitHub

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.

Trending

More talk lately.about the whole repository

Dec 2025: 0 mentionsJan 2026: 1 mentionFeb 2026: 0 mentionsMar 2026: 1 mentionApr 2026: 5 mentionsMay 2026: 0 mentionsJun 2026: 0 mentionsJul 2026: 1 mentionAug 2026: 0 mentionsSep 2026: 3 mentionsOct 2026: 3 mentionsNov 2026: 0 mentions
Dec 2025Jun 2026Nov 2026
Mentions a month of the modu-ai/moai-adk repository that our weekly crawl found. There is no adoption data for this file yet.

Who's talking about modu-ai/moai-adk

The biggest 5 of 16 mentions linking to the repository that our crawl found. Each line is their own headline.

See all 16

Talked about on GitHub (16 times).

On GitHub · 16

11 more on GitHub

The file

We split this skill into the rules it gives an agent

9 rules. About 0 are common, 4 are distinctive, and 5 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    The operator admits and picks work: Only backlog items whose state is already picked are dispatchable.

    line 65
  2. Distinctive:

    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 …

    line 76
  3. Distinctive:

    No integration actions: No push, no pull request, no merge, no branch deletion, no worktree disposal.

    line 90
  4. Distinctive:

    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 …

    line 103
  5. Very specific:

    Never sqlite3-open a guessed path: opening a missing file creates an empty one.

    line 160
  6. Very specific:

    Prefer the CLI: moai todo list --json, moai factory status.

    line 162
  7. Distinctive:

    Collect before dispatch: If a worker dispatched by an earlier iteration has returned, read its evidence file first (step 6).

    line 168
  8. Very specific:

    Collect on evidence: When the worker returns, read the evidence file it names.

    line 196
  9. Very specific:

    Stop the loop (ScheduleWakeup with stop: true), with a one-line reason, when the loop cannot do its job: the queue file is repeatedly …

    line 218

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Factory Foreman Loop Iteration

<!-- moai:role-rules-required -->

[HARD] Before the first action of a session running this skill, read BOTH role-gated rule files in full: .claude/rules/moai/workflow/factory-dispatch.md and .claude/rules/moai/workflow/cross-session-messaging.md. A Codex-only project deploys the same files under .moai/policies/ (for example .moai/policies/workflow/factory-dispatch.md) — read whichever layout this project carries. The always-loaded surface carries only their stubs; the dispatch protocol, the card classes, and the queue boundaries this loop consumes live in those two files.

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 todo (the moai gtd spelling serves the same queue); 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, exactly as the project reports it: the canonical
      # location the adopting moai todo verbs leave the queue in. No fallback
      # path is computed; a failure stops the watch loudly.
      d=$(moai paths --field todo-dir) || { echo "queue watch stopped: moai paths failed"; exit 1; }
      last=init
      while true; do
        cur=$(cksum "$d"/backlog.db "$d"/backlog.db-wal 2>/dev/null)
        [ -n "$cur" ] || cur=missing
        if [ "$cur" != "$last" ]; then
          [ "$last" != init ] && echo "backlog changed"
          last=$cur
        fi
        sleep 5
      done
    • timeout_ms: 1800000
    • description: backlog queue watch

    The persistent option no longer exists — every Monitor now carries a deadline, timeout_ms is a required input, and the watch above is an unbounded loop that never ends on its own. 1800000 is the longest deadline the tool documents accepting; a larger value is capped rather than honoured. At expiry the loop is killed and one notice arrives with the event count, so an iteration that still needs the watch re-arms it. A non-interactive (-p) session is reported to cap the deadline lower than an interactive one; that lower cap is not observable from the tool input schema, so treat a shorter-than-requested expiry there as expected rather than as a fault.

    The watch takes the queue directory from moai paths, the confirmed source of the project's database locations, so a linked worktree watches the primary checkout's queue, not a directory local to its own tree, and the directory stays the same after a legacy queue is adopted. When that command fails the watch stops with a visible message instead of falling back to a path of its own. The queue is the database, and a backlog.json beside it is an export or a legacy leftover — never the queue — so a watch pointed at the JSON on a migrated project polls a file that never changes and reports nothing, forever. The write-ahead log is watched alongside the database because a committed write can sit in backlog.db-wal with the database image byte-identical until a checkpoint folds it back; watching the database alone misses exactly those mutations. The checksum poll emits one line per change and costs two tiny reads 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.

    Database paths — never guess.

    • Find the database files with moai paths; never guess them.
    • Forbidden guessed paths: ~/.moai/todo.db, ~/.moai/backlog.db, ~/.moai/db/todo.db, ~/.moai/db/factory.db, ~/.moai/db/<key>/backlog.db, <root>/.moai/state/backlog.db, <root>/.moai/state/factory.db, <root>/.moai/state/factory/factory.db.
    • Never sqlite3-open a guessed path: opening a missing file creates an empty one.
    • Direct reads only on a snapshot copy of .db, .db-wal, and .db-shm together.
    • Prefer the CLI: moai todo list --json, moai factory status.
  2. Read the queue. moai gtd 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 outside a batch authorization.
  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:

    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.

  6. Collect on evidence. When the worker returns, read the evidence file it names. Advance the card — moai gtd 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.
  7. 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 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.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.