From b83177e52c507b76396a20ac24f7c8496044fff5 Mon Sep 17 00:00:00 2001 From: liujiazhi-arch Date: Wed, 24 Jun 2026 04:51:42 +0800 Subject: [PATCH] Lighten loop manager control-plane rules --- skills/loop-engineering/SKILL.md | 50 +++++++++++++-- .../loop-engineering/references/lane-roles.md | 64 ++++++++++--------- 2 files changed, 80 insertions(+), 34 deletions(-) diff --git a/skills/loop-engineering/SKILL.md b/skills/loop-engineering/SKILL.md index 815efbe..2b68361 100644 --- a/skills/loop-engineering/SKILL.md +++ b/skills/loop-engineering/SKILL.md @@ -163,6 +163,31 @@ multi-lane process. For substantial frontend/product-surface work, the execution contract must state the intended visible UI shape before edits: target screen, main panels/cards, empty/degraded states, backend placeholders, and the user calibration point. Prefer landing a visible skeleton tied to stable contracts before filling deep backend behavior when the user needs to judge the interface. +### Lightweight Control Plane + +Normal manager/dispatcher work should stay lightweight. The manager decides +whether the current artifact is enough to route the next phase and records only +the minimum state needed for that route. It should not spend the loop repeatedly +proving that it has not made a control-plane mistake. + +Keep hard gates heavy: planning lanes do not write production code, execution +requires explicit handoff and worktree/branch boundaries, worker lanes must not +pollute the main checkout, major code changes still need execution reports, +independent review, and arbitration/repair, and P0/P1 findings, user direction +changes, required Claude gates, and worktree boundary incidents still require +full handling. + +Heartbeat/monitor checks are light by default: check whether the expected +artifact exists, whether the lane is clearly active/idle/stuck/errored, whether +the recovery deadline has passed, and whether an obvious blocker exists. Full +heading, validator, worktree, verification, browser/DOM/screenshot, safety, and +review-readiness validation belongs to stage gates, not every heartbeat. + +Use compact records. `thread-ledger` tracks lane/thread, artifact path, status, +and next action. `state-feedback` records only events that change the next +prompt, owner, context, or action. `worklog` records human-readable summaries +and reusable lessons. Do not duplicate one routine event across all three. + Do not use long blank windows for ordinary work. Normal execution/review handoffs should use a practical first check and deadline; deadlines above 45 minutes need an explicit reason such as deep planning, whole-phase architecture review, long test/build operations, or slow external tools. For execution lanes, treat the deadline as a recovery threshold only when the lane appears idle, errored, or artifact-missing without active progress; if the execution lane is visibly active and still editing/testing, keep low-frequency artifact/status monitoring instead of interrupting or declaring failure. If the user says a lane is done, blocked, or wrong, treat that as an immediate state signal: check artifacts first, perform one recovery read if needed, update state/feedback, and route the next lane instead of waiting for the old deadline. ## Admission And New-Lane Gates @@ -193,13 +218,17 @@ Prefer a fresh lane/session when independence is part of the quality gate: Claud If choosing a new thread over a reusable lane, write the reason in the ledger. If choosing reuse, send a structured continuation handoff with the new expected artifact paths, boundaries, `check_after`, and `deadline`. -After a lane artifact lands and is validated, decide its lifecycle immediately: +After a formal lane artifact lands, validates, and is absorbed, rejected, or +deferred by its next owner, decide its lifecycle: - Review lanes are one-shot by default. Claude review, Codex independent review, adversarial critique, and second-opinion lanes should be recorded with `next_expected_use: none` and `close_or_keep: close`, then archived after the review artifact is valid and the ledger/worklog records completion. - Execution lanes, arbitration/repair lanes, planning/product/design companion lanes, manager, and dispatcher may stay open only when a named future use exists. Record `next_expected_use: ` and `close_or_keep: keep|checkpoint`. -- For active T3/T4 product loops, arbitration/repair is a standing role by default, like execution and manager. Do not archive it after a phase final report when the broader loop or milestone is still active; record `next_expected_use: continue arbitration/repair for active loop` and `close_or_keep: keep`. Archive arbitration only after the full milestone closes, a replacement lane is confirmed, the lane is corrupted/stale, or the user explicitly asks. +- Arbitration/repair may be reused only when a named next arbitration/repair use exists and the lane remains healthy. After a batch final report is absorbed, either keep it with a specific next use or archive it; do not leave it visible as passive history. - If the next phase needs independent judgment, do not keep or reuse the old review lane. Archive it and create a fresh bounded review lane. -- If no future use is named, archive the lane. Open, completed review lanes left in the UI are coordination debt. +- If no future use is named, archive the lane at the next cleanup gate. Open, completed review lanes left in the UI are coordination debt. +- Do not turn lifecycle cleanup into busywork: ordinary heartbeats may note + "artifact still pending" or "artifact landed"; full archive/keep decisions + belong to artifact validation, absorption, route change, or explicit cleanup. ## The User's Five-Step Workflow @@ -310,6 +339,12 @@ Essential constraints: - Manager/dispatcher does not own planning/execution/review/arbitration decisions. It tracks artifacts, repairs coordination, and routes handoffs. - Manager/dispatcher monitoring is artifact-driven and deadline-driven. Do not poll active lane threads every few seconds; each handoff should include `check_after`, `deadline`, and expected artifact paths when the lane may run long. - When the user asks the manager/dispatcher to keep a loop moving, do not stop with a normal final while required lane artifacts are pending and no blocker has been reached. +- Manager/dispatcher should not send a final response while a required routing + action is still pending, including artifact validation that determines the next + phase, heartbeat create/update/delete, thread title/archive/create/send, lane + handoff, recovery prompt, or state records that change the next prompt, owner, + context, or action. Optional duplicate bookkeeping must not keep the manager + busy after the route is clear. Never send an empty or placeholder final. - If the loop reaches a product, scope, or tradeoff decision that the user should own, stop and ask rather than continuing autonomously. - Reviews stay independent: Claude review and Codex review do not read each other before arbitration. - Arbitration repairs implementation defects inside the merged plan. Return to planning only for plan defects, scope-changing fixes, or user-goal mismatches. @@ -629,8 +664,13 @@ Do not turn a one-off project lesson into a skill unless it generalizes beyond t - Sending unstructured cross-lane "continue" messages. - Repeating large plan/report bodies in handoffs instead of sending artifact paths and read requirements. - Giving every lane broad project context when only planning needs it. -- Skipping `thread-ledger.md` rows for `send_message_to_thread`. -- Skipping agent worklog entries, losing lessons and repeated pitfalls. +- Treating every `send_message_to_thread` as needing a long ledger/worklog + entry. Record compact lane state, artifact path, owner, and next action; keep + longer notes only for route changes, incidents, and lessons that affect future + prompts. +- Duplicating the same event across thread-ledger, worklog, and state-feedback. + Use one compact ledger/status row plus state-feedback only when the event + changes the next prompt, owner, context, or action. - Making the manager lane the central relay for all messages instead of letting lanes hand off directly. - Treating the bootstrap thread as a main agent instead of assigning a real lane role. - Starting a new lane set for a correction to the active loop instead of messaging the existing owner lane. diff --git a/skills/loop-engineering/references/lane-roles.md b/skills/loop-engineering/references/lane-roles.md index a131c15..cfb3149 100644 --- a/skills/loop-engineering/references/lane-roles.md +++ b/skills/loop-engineering/references/lane-roles.md @@ -4,11 +4,11 @@ Use this reference when a loop needs named lanes, cross-thread handoffs, manager ## Core Principle -Artifacts are the shared memory. Chat history may help a lane think, but cross-lane coordination must flow through explicit artifacts, ledgers, worklogs, and handoffs. +Artifacts are the shared memory. Chat history may help a lane think, but cross-lane coordination must flow through explicit artifacts, compact ledgers, worklogs for human lessons, and handoffs. Treat orchestration as event/state driven. Inspired by manager-style agent frameworks and graph workflows, the manager tracks lane state, deadlines, and artifacts; it should not continuously read worker conversation just to feel current. -For multi-round or multi-lane loops, use `state-feedback-schema.md` to record how capture changes the next prompt, context, owner, or action. Feedback is not just a review comment; it is a recorded state transition. +For multi-round or multi-lane loops, use `state-feedback-schema.md` only when capture changes the next prompt, context, owner, or action. Do not duplicate the same routine event across state-feedback, ledger, and worklog. ## Role Types @@ -19,7 +19,7 @@ For multi-round or multi-lane loops, use `state-feedback-schema.md` to record ho | review / QA | independently critique execution against plan and evidence | review findings | | arbitration / editor-in-chief | adjudicate findings, repair accepted issues, close the phase | arbitration, repair report, final report | | manager | audit status, recover lost state, select next phase, maintain coordination | worklog/ledger updates | -| dispatcher | physically sends messages, creates/continues threads, monitors artifacts | ledger rows, handoffs | +| dispatcher | physically sends messages, creates/continues threads, monitors artifacts | compact ledger rows, handoffs | For non-code workflows, map roles to the task instead of forcing coding labels. Example video workflow: topic planner -> researcher -> scriptwriter -> visual planner/editor -> QA/reviewer -> publisher, with manager/dispatcher coordinating artifacts. The durable value is reusable role memory and artifact flow inside Codex, not the specific plan/execute/review labels. @@ -175,9 +175,9 @@ Rules: ## Lane Cleanup And Archiving -Lane lifecycle is part of dispatch, not optional UI housekeeping. After any lane -artifact lands and passes required heading/evidence checks, manager/dispatcher -must record one of: +Lane lifecycle is part of dispatch, but it must stay event-driven. When a formal +lane artifact lands, passes required heading/evidence checks, and is absorbed, +rejected, or deferred by the next owner, manager/dispatcher records one of: ```text next_expected_use: none @@ -197,18 +197,14 @@ Default decisions by lane: one-shot. Archive after the review artifact is valid and ledger/worklog completion is recorded. Do not keep these lanes for later phases; independence requires a fresh bounded lane next time. -- **Execution**: keep when the same loop will continue implementing related - product/contract slices and the thread is not stale, blocked, or polluted by - incompatible scope. Archive only after the broader milestone is complete or a - replacement execution lane is chosen. -- **Arbitration/repair**: keep as a standing role for active T3/T4 product loops, - especially when the same milestone will continue through more execution, - review, and repair. After a phase final report lands, record - `next_expected_use: continue arbitration/repair for active loop` and - `close_or_keep: keep` unless the broader milestone is actually closed. - Archive arbitration only when the full milestone closes, a replacement lane is - confirmed, the lane is corrupted/stale, or the user explicitly asks. Do not - archive merely because one batch's final report exists. +- **Execution**: keep only while follow-on execution in the same healthy context + is expected. After final execution/report evidence is absorbed by review, + arbitration, or next-batch planning, either record a specific next execution + use or archive/checkpoint it at a cleanup gate. +- **Arbitration/repair**: keep only while active findings disposition, repair + integration, or a named next arbitration use exists and the lane is healthy. + After final report closeout is validated, archive it at a cleanup gate unless + the ledger names a concrete next repair/arbitration task. - **Planning/product/design**: keep only when a concrete next product/strategy/UX use is named. Archive when the plan/consultation has been absorbed into a formal artifact and no follow-up is expected. @@ -219,9 +215,9 @@ Default decisions by lane: - **Manager/dispatcher**: keep for the active loop, unless the user explicitly pauses, cancels, or moves the loop elsewhere. -If a completed lane remains visible without a named future use, treat that as a -coordination defect: update the ledger/worklog, archive it, and avoid using it as -implicit state. +If a completed lane remains visible without a named future use after a cleanup +gate, treat that as a coordination defect: update the compact ledger/worklog, +archive it, and avoid using it as implicit state. ## Planning Lane @@ -506,7 +502,7 @@ Dispatcher may: - create/continue lane threads; - send standard handoffs; -- maintain ledger rows; +- maintain compact ledger rows; - perform low-frequency artifact checks; - include the latest state/feedback artifact path in handoffs when it changes the next context; - record Claude lifecycle fields (`claude_session_mode`, `reuse_reason`, `next_expected_use`, `close_or_keep`) for Claude handoffs; @@ -546,11 +542,12 @@ Ordinary execution/review deadlines above 45 minutes require a written reason in User-visible state signals override the clock. If the user says a lane finished, stalled, produced a bad artifact, or is waiting on a review, immediately check expected artifacts and ledger/worklog state; if artifacts are missing or malformed, perform one recovery read/handoff. Do not ignore the user signal because the old `deadline` has not passed. Subagent completion notifications are also state signals, not passive background -noise. When a delegated worker/subagent reports completion, immediately run the -same artifact-first validation that a heartbeat would run: check expected files, -required headings, verification summaries, and lifecycle/state feedback. Do not -wait for the next monitor window before deciding whether to update ledger/worklog, -delete or retarget stale automations, or route the next lane. +noise. When a delegated worker/subagent reports completion, run the same +artifact-first check that a heartbeat would run: check expected files first, then +perform full heading/evidence/lifecycle validation only if the artifact exists or +the route is at a stage gate. Do not wait for the next monitor window before +deciding whether to route the next lane, retarget stale automations, or record a +state change that affects the next prompt, owner, context, or action. When the route changes, update or delete stale monitors, reminders, or heartbeat automations that still point at obsolete artifacts, lanes, or deadlines. A stale monitor is a coordination bug: it can restart superseded work or make the manager wait on an artifact that no longer matters. @@ -575,6 +572,14 @@ automation record when the wakeup is important for loop progress. When the user explicitly asks manager/dispatcher to keep a loop moving: - do not end with a normal final while a required artifact is pending and no blocker has been reached; +- do not use the final channel while any required manager/control-plane routing + action is still pending: artifact checks that determine the next phase, + heartbeat create/update/delete, thread title/archive/create/send, lane handoff, + recovery prompt, or state records that change the next prompt, owner, context, + or action. Optional duplicate bookkeeping must not keep the manager busy after + the route is clear. A heartbeat final must contain the complete + `...` decision only after intended actions for that turn + are complete; empty or placeholder final messages are a coordination defect. - prefer artifact/file checks over frequent thread reads; - use the lane's `check_after` and `deadline`; if absent, set one before or in the next handoff instead of polling blindly; - if an artifact is missing beyond the wait window, first check whether the owner lane is active; if active/progressing, keep monitoring without interruption; @@ -602,7 +607,7 @@ Use role-scoped context as a starting point, not a capability limit: | execution / maker | merged plan, local files/tests for the phase, existing patterns, failing tests | | review / QA | merged plan, execution report, changed diff, relevant complete functions, test output, acceptance criteria | | arbitration / repair | both reviews, execution report, targeted live evidence, verification output | -| manager / dispatcher | ledger rows, artifact paths, lane state, deadlines, blockers | +| manager / dispatcher | compact ledger rows, artifact paths, lane state, deadlines, blockers | Rules: @@ -615,7 +620,8 @@ Rules: ## Handoff Requirements -Every cross-lane message should include: +Formal T2+ cross-lane handoffs should include the applicable fields below. Omit +fields that are irrelevant to the route instead of filling them with ceremony: ```text