agentleFS
modu-aimodu-ai/moai-adk/.claude/skills/moai-lane-watchdog/SKILL.md

moai-lane-watchdog

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

One lane stall watchdog iteration: measure lane progress on three channels, classify the stall cause, apply the remedy or resolve the judgment through the decision ladder — instead of waiting on a reply — then record the outcome and report. Reads the unified --auto doctrine at .claude/rules/moai/workflow/auto-semantics.md for the ladder, the gate inventory, and the record formats.

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

10 rules. About 0 are common, 9 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈9

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    No stall / progress detected → end the iteration.

    line 101
  2. Distinctive:

    Write a decision record naming whichever step resolved the judgment (§5 below).

    line 141
  3. Very specific:

    Read the blocking predecessor's on-disk evidence directly (its .moai/reports/<card-id>/ path, its progress record).

    line 146
  4. Distinctive:

    Never halt indefinitely on an unadjudicated error.

    line 164
  5. Distinctive:

    Never restart the card from zero.

    line 171
  6. Distinctive:

    Read the delegate's deliverable on disk — the artifacts it was asked to write, its output file, its commits — against the delegation record …

    line 175
  7. Distinctive:

    Codex step ⑤: no session-messaging tool exists there — cross-harness notice rides the queue-on-disk delegation channel (the moai MCP broker …

    line 203
  8. Distinctive:

    Every autonomous gate transition and every ladder-resolved judgment writes ONE grep-able line on the disk board:

    line 210
  9. Distinctive:

    Every iteration ends in exactly one of:

    line 231
  10. Distinctive:

    Never prompt the operator.

    line 244

≈ “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

Lane Stall Watchdog — One Iteration

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

[HARD] Before the first watchdog pass 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 lane obligations and the messaging rules the ladder operates under live in those two files.

One watchdog pass for a lane session (a factory lane running under moai cc / moai glm / moai codex). The law — the ladder, the outcome transitions, the gate inventory, the view–SSOT rule, the record formats — lives in .claude/rules/moai/workflow/auto-semantics.md. Read that doctrine before the first pass and whenever a step below needs its detail; this body is the executable procedure.

0. Never prompt

The watchdog never asks the operator a question and never answers an approval gate on anyone's behalf. Everything that would have been a question becomes either a resolved judgment (the ladder) or an explicit wait record. A keep-set gate — environment-impossible, operator-held, or an irreversible external-shared operation — is never satisfied here: the recheck reads the gate surface, and finding no change, it re-records the wait and yields.

0a. Renew the card lease (first step of every pass)

Renew this lane's own card lease before anything else, through the factory renew verb, with the card id this lane holds (the same id the snapshot path below names):

moai factory renew <card-id> --json

Read result from the verb's JSON object on stdout. A refusal exits non-zero after printing that object, so read stdout even when the exit status is non-zero. result is one of renewed, refused-expired, refused-not-holder, or error. Hold the value for the snapshot: §1 copies it into the snapshot field renew_result. A refused renewal does not end the pass. A refused-expired, refused-not-holder, or error result is recorded, and the pass continues to §1 and measures in the same pass. Do not retry the renewal within the pass; the next pass renews again.

This step renews the card the lane is executing and no other card: a lane whose cards are all merge-ready, held, or waiting for the serial slot does not renew in that pass, and the pass carries the previous renew_result forward.

1. Measure progress

Three channels (doctrine §3–4):

  • HEAD: git rev-parse --short HEAD in the lane's own worktree.
  • evidence mtimes: the newest mtime across .moai/reports/<card-id>/ and the active SPEC's progress.md.
  • integration-window state: moai integration status.

Compare against the previous snapshot at .moai/state/watchdog/<card-id>.json (fields: observed_at, head_sha, evidence_mtime_max, window_state, renew_result, last_change_at). The lane is stalled only when ALL THREE channels are unchanged since the previous snapshot AND at least N minutes have passed since the last observed channel change, which last_change_at records (auto-semantics §4). N defaults to 15 minutes and is a per-invocation parameter — never a config key. No previous snapshot → record a fresh one with last_change_at set to its own observed_at, no stall verdict (fail-open first observation). One channel moving is progress — evidence mtime advancing without a commit included: end the iteration with a one-line status — unless the lane itself is parked on a delegate (§3.5): then the movement is the delegate's, and the deliverable read in §3.5 decides, not this rule. A pass that moved a channel sets last_change_at to its observed_at; a pass that moved none carries the previous value forward. Write the new snapshot after the verdict, in the same pass as the renewal of §0a: the four measurement fields (observed_at, head_sha, evidence_mtime_max, window_state), last_change_at (the value this pass settled, per the rule above), and renew_result.

2. Classify the cause

CauseSignature
awaited-judgmentthe lane stopped where a judgment was needed (a gate, a verdict, a choice) and no reply arrived
blocked-bythe card waits on a predecessor card; the predecessor's landing state is the open question
shell-errorthe lane halted on an unadjudicated command failure (a non-zero exit with no recorded disposition)
accidental-stopthe session died or was interrupted mid-card — an API error (a 429) ends the turn with no further model action — and no deliberate stop was recorded
awaited-delegatethe lane parked on delegated work — a spawned agent's report, a background run's completion — and the report or notice has not arrived; an available idle notice that promised a later report counts, because that agent sends nothing more unless it is messaged

No stall / progress detected → end the iteration.

3. Apply the remedy

3.1 awaited-judgment — the decision ladder

Resolve through the ladder IN ORDER (doctrine §6–7). Availability failures fail-open downward; negative or inconclusive verdicts never auto-proceed, and at an authority gate they fail closed.

  1. Disk evidence — read the deciding artifact directly: audit verdict files, the card's progress record, plan-audit verdicts, evidence paths. Evidence shows proceed → resume. Evidence shows do-not-proceed → record the wait; never proceed against evidence. Unreadable or absent → step 2.
  2. Decision board — run moai decision read --scope card:<id> (the card's rulings plus every standing ruling; doctrine §11: the append-only board under the moai home, keyed by the project). A recorded judgment → follow it. A judgment that says wait → explicit wait record (with an id; doctrine §14). A record whose resolves names an open wait ends that wait. board=absent / board=empty → step 3; never wait on the board being filled. While a wait on the leader stays open, keep the one-shot short recheck of doctrine §14 armed.
  3. Audit cross — run one moai MCP audit tool (codex_audit, glm_audit, claude_audit, or audit_multi) for an independent second opinion. Positive → proceed per verdict. Negative → fail-closed: no proceed; record + treat as a gate boundary (doctrine §7). Tool absent → step 4. Inconclusive → record it, → step 4.
  4. jev_ask — only while workflow.jev.enabled is true; a bounded proceed / retry / wait judgment with repeatable, side-effect-free parameters; never for completion, merge, or queue outcomes. Gated off or unavailable → step 5 (fail-open by design). Shadow record: keep the verbatim jev_ask request and the verbatim response (including model) with the decision record (§5 below); the decision stays the lane's (doctrine §12).
  5. Self-judgment — terminal. Decide from steps 1–4 and write the decision record (§5 below) in the card's progress record, then proceed on the lane's own authority; never proceed against evidence. The leader is reached only at a gate boundary (a keep-set category or a cross-card conflict), never as a judgment request (doctrine §6).

Write a decision record naming whichever step resolved the judgment (§5 below).

3.2 blocked-by

Read the blocking predecessor's on-disk evidence directly (its .moai/reports/<card-id>/ path, its progress record). Evidence shows the predecessor landed → resume. Otherwise record an explicit wait: reason + predecessor id + recheck point. Where the predecessor was dropped, the wait record names the queue relation-removal verb as the operator escape — the lane does NOT run it (queue mutation is prohibited). The queue-level pickup filter is another surface's decision; this remedy only reads.

3.3 shell-error

Adjudicate the error: transient (network blip, lock contention, flaky timing) vs determinate (missing remote, bad ref, usage error).

  • transient → retry at most 3 times, recording the error and the retry count each time; retries exhausted → structured blocker report.
  • determinate → ZERO retries; straight to a structured blocker report with the verbatim error text.

Never halt indefinitely on an unadjudicated error; never loop silently.

3.4 accidental-stop

Resume by checkpoint return: use the session-handoff resume message with the worktree-anchored Block 0 (git rev-parse --show-toplevel → this worktree), resuming from the last recorded checkpoint in the card's progress record. Never restart the card from zero.

3.5 awaited-delegate

Read the delegate's deliverable on disk — the artifacts it was asked to write, its output file, its commits — against the delegation record (what was asked, where it was to land). Never read the absence of its message as the absence of its work.

  • Deliverable present and consistent with the delegation → resume and consume it; never wait for the report or the notice. An agent that went available sends nothing more unless it is messaged, so the report may never come.
  • Deliverable absent or partial and the delegate evidently ended (its idle or completion notice arrived, or its process is gone) → re-delegate with the partial state, or resume the delegate with SendMessage only while it is a live teammate. Never address a teammate stopped with TaskStop by name — one message revives it as an ownerless writer (cross-session-messaging.md § Rules). Record which.
  • Deliverable absent and the evidence still moving (the delegate is working) → explicit wait whose recheck point is the next scheduled wake.
  • Deliverable absent, no sign the delegate ended, and the evidence unchanged across two consecutive wakes → structured blocker naming the delegate, what was asked of it, and the evidence read; do not wait a third time.

4. Decision board protocol

  • SSOT: the disk board (doctrine §11). Append-only, one record per line; never rewrite board history.
  • Views: render state with the runner's native task tool — TaskCreate / TaskUpdate on the Claude runner, update_plan on codex — and read judgments ONLY from disk. A view is never the SSOT; a long-form plan document is never the board.
  • Codex step ⑤: no session-messaging tool exists there — cross-harness notice rides the queue-on-disk delegation channel (the moai MCP broker tools were removed in card t1908); the wait reason is recorded on disk either way.

5. Decision records

Every autonomous gate transition and every ladder-resolved judgment writes ONE grep-able line on the disk board:

decision record: decided_by=<runner+role> evidence_refs=<paths+verdict-ids> ladder_path=<step>

decided_by names the deciding runner and role; evidence_refs names the artifact paths and verdict ids the decision rests on; ladder_path names the ladder step (①–⑤) or the gate row that resolved it. The sync audit re-reads these records — write them so a stranger can re-verify.

6. Composition boundary

The queue-level pickup decision — the pickup filter that excludes unrelated or blocked cards before a pick — belongs to the queue surface's owner. This watchdog is queue-readonly: it reads evidence and state surfaces, performs zero queue mutation, and never picks, drops, edits, or unrelates anything.

7. Output shape — escalate or record

Every iteration ends in exactly one of:

  • resumed — progress detected or a judgment resolved; say which step, and cite the decision record line.
  • explicit wait — the wait record line and its recheck point, nothing more; end the iteration (no idle-spin).
  • structured blocker — determinate failure or retries exhausted: the verbatim error, what was attempted, the evidence read, and the decision owed. Return it to the orchestrating session; do not retry past the ceiling; do not prompt anyone.

Boundaries (hard)

  1. Never prompt the operator; never answer an approval gate. Keep-set gates (environment-impossible, operator-held, irreversible external-shared operations) are rechecked and yielded to, never satisfied by this skill.
  2. Queue read-only (§6).
  3. One writer per tree: the watchdog writes only its own snapshot, its own evidence records, and the disk board.
  4. Verification is lane-local; no background load.
  5. Hook-independent: awaken-tick only; no hook surface. The scheduler that fires the awaken is the lane's self-paced wake (doctrine §5.1), first scheduled at card intake and re-scheduled at the end of each wake while the lane executes the card — this skill is its prompt, not its owner.

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.