Lanes

Repository context. Gather first

Collect these with individual Bash calls, one command per call, never combined into a single invocation:

• Repo root, git rev-parse --show-toplevel

Treat a failure (not a repository, git unavailable) as an unknown value and carry on. Keep these as separate body Bash calls rather than pre-compute lines: the harness runs a skill's whole pre-compute block as one shell invocation, and a worktree-isolated session refuses a compound command that contains git. The dated record for that composition claim is the source-control plugin's gather-block.md, "The pre-compute block runs as one shell invocation".

Pre-computed context

claude CLI: !claude --version 2>/dev/null || echo "MISSING (required)" jq: !command -v jq >/dev/null 2>&1 && echo "present" || echo "MISSING (required)" Lane config: !bash "${CLAUDE_PLUGIN_ROOT}/skills/lanes/scripts/probe-lane-config.sh" 2>/dev/null || echo "unknown"

Variables

Arguments: $ARGUMENTS

Purpose

Running N loop lanes on a machine means a daily ritual: for each lane, cancel its loop, clear, and re-paste its canonical prompt. This skill collapses that to one command. start/restart pull the repo and refresh the plugin marketplace once, then launch each configured lane as a named background session seeded from the lane's canonical prompt file, mirroring that lane's model/effort onto the launch. status/stop read and manage those sessions through the CLI's own background-session surface.

Owns only its own lanes. stop/restart act on a session only when its name is a lane in the resolved config, a hand-started session (e.g. an interactive work window, or an unrelated PR Babysit) is never stopped by this skill.

A relaunch is the only context reset a loop lane gets

/loop re-invokes its prompt in the same session (it self-paces via ScheduleWakeup), so a lane's context carries forward across every cycle, subagent return, and operator turn, the loop never starts a fresh one. A running loop cannot reset its own context on demand: a built-in like /clear issued from a loop re-run reaches the model as plain text, not an executed command, so the model cannot /clear itself. Any "restart the loop when context passes ~N%" discipline is therefore an admonition with no in-session enforcement, the lane has no reliable way to measure its own context usage and no way to act on the threshold if it could.

The context change that does happen automatically in-session is Claude Code's auto-compaction: when the conversation nears the model's input limit, older history is summarized in place to free space. That is not a reset, the session continues on a lossy summary of what came before, not a fresh context, so a lane that runs long enough will lose earlier context to compaction well before any operator relaunch, not keep every turn until then.

restart (stop the session, relaunch from the canonical prompt) is the only fresh-session reset: the relaunched lane starts a fresh session seeded from the prompt file, carrying none of the prior conversation. That reset is operator- or launcher-initiated, not automatic. There is no per-cycle or threshold trigger that runs restart for you today. Auto-compaction can still fire between restarts, but it only summarizes; it does not clear the accumulated, increasingly degraded context. Until an automatic relaunch trigger exists, treat the periodic restart (e.g. the morning refresh) as the mechanism that keeps long-running lanes off a stale, repeatedly-compacted context, and do not let a lane prompt assume each /loop cycle begins with fresh context.

Run it

If the first token of $ARGUMENTS is consume-restarts, skip to Consume restart-requests instead. It runs a different script. Otherwise:

bash "${CLAUDE_PLUGIN_ROOT}/skills/lanes/scripts/lane-launcher.sh" --data-dir "${CLAUDE_PLUGIN_DATA}" $ARGUMENTS

Print the script's output verbatim. It is the deliverable. Preview any mutating run first with --dry-run (prints the exact claude/git commands, seeds nothing, kills nothing).

--data-dir is passed explicitly, not left to the script's own $CLAUDE_PLUGIN_DATA env-var fallback. Per plugins-reference, ${CLAUDE_PLUGIN_DATA} is exported as a real environment variable only to hook processes and MCP/LSP subprocesses. For skill content it instead resolves by inline text substitution anywhere the placeholder appears in the rendered skill body, exactly like ${CLAUDE_PLUGIN_ROOT} above. A script this skill shells out to via the Bash tool does not inherit CLAUDE_PLUGIN_DATA as an env var, so leaving --data-dir off here would silently fall through to lane-launcher.sh's own ~/.claude/plugins/data/claude-ops guess instead of the marketplace-qualified directory Claude Code actually resolves. $ARGUMENTS comes after --data-dir, so an explicit --data-dir the caller passes in $ARGUMENTS still wins (last flag wins in lane-launcher.sh's parser).

This is the dated record for the export claim; the two restatements below and in context/refresh.md point here. The page says of ${CLAUDE_PLUGIN_ROOT}, ${CLAUDE_PLUGIN_DATA} and ${CLAUDE_PROJECT_DIR} that "All three are exported as environment variables to hook processes and to MCP and LSP server subprocesses", and its component table gives skill and agent content inline placeholder substitution only. Verified 2026-09-06 against Claude Code 2.1.263 and that page as fetched that day. Recheck when the page's environment-variable section stops naming those three process kinds, or a release note names plugin environment variables.

Action Router

Parse $ARGUMENTS for the action (first token); remaining tokens are lane names (targets for restart/stop; an unknown name is rejected).

Options: --config FILE, --repo DIR, --no-pull, --no-update, --dry-run, --agents-json FILE (read the session list from a file instead of the live CLI, offline/scripted reuse), --data-dir DIR (base dir for the per-lane launch-commit marker; default $CLAUDE_PLUGIN_DATA). Exit codes: 0 ok · 3 bad argument/config · 4 prerequisite missing or repo/config unresolved.

Consume restart-requests

A lane that hits its cycle budget or the /loop seven-day expiry writes a restart_request into its telemetry state block and stops. It cannot relaunch itself. The consumer is the reader that closes that gap, meant to run unattended on an OS-owned schedule (its print-schedule action emits the registration commands; registering them is an operator action). For consume-restarts, run:

bash "${CLAUDE_PLUGIN_ROOT}/skills/lanes/scripts/restart-consumer.sh" --data-dir "${CLAUDE_PLUGIN_DATA}" $ARGUMENTS

The script strips the leading consume-restarts token itself; the next token is its sub-action. check (read-only report, the default), run (relaunch), or print-schedule (emit the registration commands), and later tokens its options. Print the output verbatim. Relaunches delegate to lane-launcher.sh restart, so each lane's prompt, model, effort, and settings come from the same config this skill already uses. The consumer's polling tick is not lane pacing: lanes stay self-paced via ScheduleWakeup, and a tick where no configured lane has a non-null restart_request is a no-op that only refreshes the consumer's own freshness telemetry. Design rationale, the relaunch predicate, operator registration with Verify/Reversal lines, and the labeled UNVERIFIED items live in context/restart-consumer.md. Read it before registering the schedule or changing the consumer.

Lane config

Lanes are defined in a JSON config, resolved first-hit-wins: --config FILE → $CLAUDE_OPS_LANES_CONFIG → <repo>/.work/lanes/lanes.json. Each lane carries a name, a prompt file path, and optional model/effort/settings (a session-only claude --settings override, e.g. opting the lane into the autonomy plugin's lane-stop gate). The full schema, resolution rules, and the prompt-storage seam live in context/config.md. Read it before authoring a config.

lanes/ is this skill's reserved concern home. The config and the lane prompt files live inside <repo>/.work/lanes/, a reserved first-level name under the memory root, not as bare files at the root itself. Lanes hardcodes the literal .work root: it does not resolve the topic-docs memory_dir setting, and a consumer that has repointed memory_dir elsewhere must pass --config or set $CLAUDE_OPS_LANES_CONFIG. That is a stated carve-out, not an oversight. The launcher is an operator script invoked outside a session (an OS schedule, a bare shell), where no skill body is loaded to resolve the setting for it, and the escape hatch is what covers the remaining case.

Compatibility with the pre-move layout. A checkout whose config is still the bare <repo>/.work/lanes.json keeps working: when the lanes/ home holds no config, the launcher reads the old path and prints a one-line deprecation warning naming the move. Only the default falls back, so --config and $CLAUDE_OPS_LANES_CONFIG keep meaning exactly what they say. A config resolved at the old path also keeps the old prompt_dir default (.work), so prompts that never moved still resolve. Move both into .work/lanes/ to clear the warning; the fallback is temporary.

Prompt storage is sanctioned, not durable. Prompt files live in prompt_dir, default .work/lanes. That is a sanctioned placement, and it is still session-local: the memory root does not travel between machines, so a fresh machine has no prompts until they are authored there or prompt_dir points at a committed directory. The launcher resolves the prompt dir in exactly one place (resolve_prompt_dir in the script), so repointing it is a one-line change.

Mid-session staleness & restart cadence

A running lane keeps the skill versions it loaded at launch: a fix merged to a plugin the lane runs does not reach that lane mid-session. This is not a missing feature to build around. It is documented Claude Code behavior (a live session keeps its launch-time plugin versions, /loop never re-reads a skill's body on later cycles, and a loop can't self-trigger /reload-plugins); the dated record with all three citations is context/refresh.md, "Empirical answer: no true mid-session hot-reload for a running loop lane". Restart is the honest refresh mechanism, the same restart that clears context bloat. Detect an unconsumed self-fix with a read-only git probe against the repo's default branch, then restart that lane at its next cycle boundary. The probe reads the launch commit lane-launcher.sh records per lane at start/restart (${CLAUDE_PLUGIN_DATA}/lanes/<repo-key>/<lane>-launch-commit; the data directory is plugin-wide, so <repo-key>, a digest of the repo's canonical path, keeps a conventional work lane in two different checkouts from sharing one marker). No manual fill-in needed. Full reasoning, the probe, and the cadence live in context/refresh.md. Read it before answering "why is my merged fix not live in the lane?" or setting a restart frequency.

Carry this line into that probe. It is the data_dir assignment context/refresh.md deliberately leaves unresolved, because only skill content (this file) substitutes the placeholder:

data_dir="${CLAUDE_PLUGIN_DATA}"

Copy it as it renders here, already substituted to an absolute path. Writing the placeholder, or a ${CLAUDE_PLUGIN_DATA:-…} env fallback, inside context/refresh.md would not work: that file is read raw, and per plugins-reference CLAUDE_PLUGIN_DATA reaches only hook and MCP/LSP subprocesses as a real environment variable, never a script the Bash tool runs (the dated record for that claim is the --data-dir note above). The probe would then read the unqualified ~/.claude/plugins/data/claude-ops guess, find no marker, and skip the staleness check silently.

Verified CLI surface

The launcher shells out only to primitives this machine's claude reports. Verified 2026-09-06 against Claude Code 2.1.263, by reading claude --help, claude agents --help, and claude plugin marketplace --help. Recheck when the CLI's major or minor version moves, or a release note names background sessions, the agents command, or plugin marketplace. The primitives: claude --bg -n <name> [--model M] [--effort E] [--settings JSON] "<prompt>" (launch a named background session, return immediately; --settings accepts inline JSON and applies session-only, per the CLI reference), claude agents --json (list active sessions: pid, cwd, kind, startedAt, sessionId, name, status), claude stop <sessionId> (stop one session; conversation kept, resumable with claude attach), and claude plugin marketplace update. There is no claude agents stop verb. Stop resolves the sessionId from agents --json and only for a configured lane name.

Gotchas

• No durable prompt home. .work/lanes is a sanctioned home, not a durable one: the memory root is session-local, so a fresh machine or session has no prompts until they are authored there, or prompt_dir is pointed at a committed directory.
• Name is the identity. Lanes are matched by session name and kind: background: every lane is launched with --bg, so an interactive window sharing a lane name is never matched or stopped. Two lanes must not share a name; a hand-started background session sharing a lane name would still be treated as that lane, so keep lane names distinct from ad-hoc background session names.
• start is idempotent-ish, restart is not. start skips a lane already running; restart always stops-and-relaunches (discarding the running lane's in-flight conversation). Use start for "bring up whatever is down".
• A missing/empty prompt file skips that lane (with an error) rather than launching an empty session. status flags [prompt MISSING].
• The launch-commit marker is per-machine and best-effort. It lives under ${CLAUDE_PLUGIN_DATA} (a per-machine dir, not synced), so a lane restarted on a different machine has no marker there yet. A write failure only warns: it never fails an already-launched (or already-stopped-and-relaunched) lane, so a missing marker means "never started here via lane-launcher.sh", not "launcher broken". A (re)start that cannot record its commit also deletes any marker the previous launch left, so "missing" always beats a stale commit the probe would otherwise trust.
• A lane name must be a single path component. It is the marker's filename, so config preflight exits 3 on a name containing / or \, or equal to . or ... Otherwise two distinct lanes could share one marker.

Per-cycle deterministic scripts

Two lane-cycle mechanics need no reasoning, so they are scripted here and a lane prompt references the script instead of re-deriving the work every cycle. Both follow lane-launcher.sh's conventions (jq CRLF wrapper, the --help header as the full contract, explicit exit codes). The header is the source of truth for each, the summary below is a pointer, not a copy.

• scripts/machine-behavior.sh. Emits the lane's MACHINE-BEHAVIOR block (gh identity, clone path, worktree inventory, installed plugin versions) as a verbatim-printable text block. Pure environment inspection: it emits only mechanically unambiguous facts and deliberately does NOT compute "deviations from standing rules". That stays a model judgment made by reading these facts against the prose rules. Plugin versions are the INSTALLED runtime versions, which per context/refresh.md can lag repo HEAD mid-session (the honest number for a running lane). --plugin <id> (repeatable) scopes the block to the plugins a lane runs.

• scripts/telemetry-upsert.sh. Maintains exactly ONE marker-identified telemetry comment on a tracking issue, editing it in place instead of posting a second. Given --issue N --marker STR --body-file PATH, it writes a machine-detectable sentinel as the comment's first line, finds that sentinel across all comments and PATCHes it, adopting or creating a comment when none carries it. The marker grammar, the <lane>@<instance> writer-identity rule, the body-file containment and size limits, the pre-write and read-back checks, and every exit code are in the script's --help header. Two rules the caller must follow: pass the body as file contents or on stdin (see "Never pass a body as an @path string" below), and lead the body with a telemetry key such as lane: rather than a GitHub @mention, because a body whose first line begins with @ is rejected.

Never pass a body as an @path string

Applies to every telemetry or comment write a lane makes. Through telemetry-upsert.sh or through the gh api upsert a lane inlines, since an installed plugin cannot invoke a sibling plugin's script.

Pass the body as file contents (--body-file PATH) or pipe it (--body-file -). Never interpolate an @path string into a body value: gh issue comment --body @path and gh api -f body=@path send the literal text @path. Reading from a file takes gh issue comment --body-file, or gh api -F/--field key=@path, per each command's own --help (gh 2.95.0); gh api has no --body-file flag at all.

The failure is invisible from the outside: the comment's timestamp still moves, so any check keying on updatedAt reads the lane as fresh while it carries no data. (This skill's sibling reader morning-brief is not that check: it parses lane: and last-cycle: out of the body, so a degraded comment makes the lane vanish from its report rather than look healthy. What a degraded body deceives is any consumer that keys on the comment's timestamp instead of reading its body.)

telemetry-upsert.sh refuses such a body before it writes anything and re-reads what landed afterward. An inlined upsert encodes three checks itself: a pre-write gate (empty, leading @, not sentinel-prefixed, or under a 16-byte payload floor measured below the sentinel line → skip the cycle, no API call), a check of the write's own exit status (a failed write leaves the previous cycle's body in place, which a read-back running regardless would accept), and a post-write read-back of what the write stored. What an inline block does NOT replicate: the 64 KiB cap, the body-file containment checks, retries, and this script's distinct non-zero exit codes, an inline branch always exits 0 and reports through stderr. It also inherits this script's own limits: a PATCH that succeeds while storing the previous body still verifies, and the read-back proves some well-formed telemetry is present, not this cycle's.

Cross-references

• context/refresh.md. Read it when a fix has merged to a plugin a lane is running on and you must decide whether to restart that lane: the git staleness probe and the restart cadence.
• /claude-ops:plugins, the authoritative, richer plugin-fleet sync (scope divergence, new-catalog installs). This skill's marketplace refresh is the light claude plugin marketplace update step of a launch, not a substitute.
• /claude-ops:morning-brief. Reads the loop-lane telemetry (per-lane last-cycle freshness). This skill starts/stops the lanes that emit it.