stage-11-agentics/lattice/delegator-example

Example Delegator Flow (Stage 11 / c11)

This is an example skill, not a generic one. It documents how Stage 11 drives a single Lattice ticket end-to-end inside the c11 terminal multiplexer. It uses c11-specific commands (c11 new-split, c11 new-surface, c11 set-metadata, etc.) to compose panes, surfaces, and sidebar telemetry around the work. If you are running a different harness, treat the orchestrator/delegator/phase architecture and the worktree+Lattice discipline as the transferable lesson; the surface mechanics will need a rewrite.

Stage 11 publishes this as a worked example so other teams can see what a fully developed agent-native delegation pattern looks like before designing their own.

Prerequisites

1. Install the `lattice` CLI if it is not already on your PATH (lattice --help should resolve). Pick whichever installer fits your environment:

• uv tool install lattice-tracker (recommended)
• pipx install lattice-tracker
• pip install lattice-tracker

1. Initialize Lattice in the target repo if it has not been initialized yet:

``bash lattice init --project-code PROJ ` (Replace PROJ with a short project code, e.g. APP, API, WEB.) This creates the project's .lattice/` directory.

1. Load the companion `lattice` skill (in this same skills/ directory) for the core CLI reference. This skill builds on top of it.
2. You are running inside c11 (CMUX_SHELL_INTEGRATION=1). If you are not on c11, do not try to follow the surface/pane commands literally — read the pattern, then adapt. The Stage 11 c11 project lives at <https://github.com/Stage-11-Agentics/c11>.

Lattice Delegate Pattern

A pattern for driving a single Lattice ticket through its full lifecycle with dedicated panes, an isolated git worktree, and sub-agents per phase. The delegator is the single point of contact for the human; the ticket is the shared comms bus; the worktree is the blast-radius boundary.

Roles

• Orchestrator — the chat that sets up the delegation and then runs an active polling loop. Creates the worktree, splits a pane, seeds the delegator surface, posts a framing Lattice comment. After setup, the orchestrator schedules periodic wake-ups (ScheduleWakeup) and surfaces meaningful ticket transitions to the operator — silent watching is a documented failure mode (see Active orchestrator watch below). The work itself happens in the delegator pane; the orchestrator's job is to make sure the operator hears about it.
• Delegator — a new Claude Code session spawned in a sibling pane. Walks the ticket's lifecycle, spawning one sibling surface per phase inside its own pane. The delegator is the primary human interface — when the human scrubs the delegation, they read the delegator pane; when the human has a question or needs to intervene, they talk to the delegator; when the work escalates, the delegator is the one who surfaces the escalation.
• Phase sub-agents — spawned by the delegator. One per phase: Plan, Impl, Translator (only if user-facing strings change and the repo is localized), Review, Validate. Each lives as a tab in the delegator's pane so the operator can scrub any of them in one vertical slice.
• The ticket — the shared comms bus. Every agent posts lattice comment at meaningful milestones. The orchestrator reads the trail via lattice show <id> or lattice watch --task <id>.

Core principles

These shape every decision downstream. If a section below seems to conflict with one of these, the principle wins.

The delegator is the human interface

The human watches and interacts with exactly one pane: the delegator's. Everything else is internal machinery. This has real consequences:

• Sub-agents never message the human directly. They write to the ticket, set their surface status, and stop. If they have a question or recommendation, it's a Lattice comment addressed to the delegator — not chat text addressed to the human.
• Only the delegator escalates. Needs-human flags, operator decisions, pauses for clarification — all of these flow through the delegator. A Plan or Review sibling that discovers an ambiguity flags it to the delegator (via the ticket), and the delegator decides whether to resolve, spawn another sub-agent, or escalate to the human.
• The delegator summarizes. When the human checks in, they read the delegator pane and get a coherent picture of where the ticket is and what's next. The delegator owns that picture — it's not assembled from scraping 9 sibling tabs.
• The delegator is also the last-mile communicator. When the PR is ready, when a decision is needed, when something has gone sideways — the delegator's most recent message is what the human sees.

Sub-agents are internal. The delegator is the membrane between the human and the work.

Prefer cohesive tickets over spree tickets

When a review surfaces additional work, the default is to absorb it into the current ticket's PR as additional commits, not to spawn a follow-up ticket. A single fatter ticket with a cleanup commit is almost always better than a ticket + a followup ticket. Reasons: less coordination overhead, one review cycle, one merge, one audit trail, one reader has to load the context once.

Create a follow-up ticket only when:

• The item is explicitly out of scope per the plan's Do NOT ship list.
• The item would block current-ticket merge (e.g., unrelated CI/infra fix).
• The item needs its own planning cycle (not a trivial absorb).

The delegator is free to file follow-up tickets when the above applies, but it should feel like an exception, not a default.

Review sub-agents are read-only; reviewers fix minor, escalate major

See the Review phase below — this is important enough to call out as a principle. Review sub-agents (the ones that only read code and emit findings) never mutate the codebase, never create Lattice tasks, and never commit. But the Review phase itself is not purely read-only — see the contract below for how minor findings get absorbed and major ones escalate.

Worktrees are the blast-radius boundary — for code, not for Lattice

Every delegation runs in its own git worktree. The delegator and every sub-agent do their code work inside it: edits, builds, commits, branch pushes. The orchestrator's repo's working tree stays untouched. Parallel delegations don't collide. Build artifacts don't cross-contaminate. The diff on the worktree is, by definition, the delegation's entire code output.

Lattice writes are the exception — see the next principle. Lattice is the coordination surface; it must be visible to every reader (dashboard, board, orchestrator, sibling delegations, the operator scanning their normal workflow), not buried inside one worktree's .lattice/ that nobody else looks at.

Lattice writes target the parent repo, not the worktree

Lattice state — task status, comments, attachments, completions — must be written to the parent repo's .lattice/, not the worktree's. The worktree's .lattice/ is a hydrated snapshot that exists so lattice show <TICKET> resolves during phase work; it is read-only for the delegation. All write operations target $REPO_ROOT.

# Code work lives in the worktree:
cd $WT_DIR
git diff
git commit -am "..."
git push
 
# Lattice writes live in the parent repo. Use a subshell so cwd doesn't drift:
(cd $REPO_ROOT && lattice status $TICKET review --actor $ACTOR)
(cd $REPO_ROOT && lattice comment $TICKET "..." --actor $ACTOR)
(cd $REPO_ROOT && lattice attach $TICKET <pr-url> --type reference --title "PR" --actor $ACTOR)
(cd $REPO_ROOT && lattice complete $TICKET --review "..." --actor $ACTOR)

Why: the dashboard, the board UI, the orchestrator's polling, sibling delegations, and any other agents reading the project's Lattice state all read from $REPO_ROOT/.lattice/. A status change written only to $WT_DIR/.lattice/ is invisible to all of them — including the operator looking at their normal Lattice surfaces. The worktree may have its .lattice/ deltas merged eventually (when the branch lands), but "eventually" is not "right now," and needs-human flags / blocked / review transitions need to be visible right now.

Failure mode this prevents: delegator runs an audit, completes work, flags the ticket needs-human in the worktree, then sits silent. The flag lands only in the worktree's .lattice/; the Lattice dashboard, board, and orchestrator never see it. Operator has no way to know their input is needed. (Observed 2026-05-03 on C11-1; led to this principle.)

Reading is fine from either location. lattice show in the worktree shows the worktree's view (which may be slightly behind the parent if the parent is being mutated by something else). When the orchestrator polls, it reads from $REPO_ROOT because that's where writes land — see Active orchestrator watch below.

Verify the prior phase's claims before acting on them

Every phase inherits the prior phase's claimed work. Before executing what the prior phase said it did, ground in the actual artifacts: read the diff, grep the source, list the commits. Plan claims a localization sweep — Impl checks the codebase pattern before wrapping every string. Impl reports completion — Translator greps the diff for String(localized:) calls before translating. Review reads synthesis-action.md — but verifies cited file:line refs against the actual diff before applying. The pattern generalizes: a downstream phase trusts no upstream claim without grounding. Catching a Plan-vs-codebase or Plan-vs-Impl gap at the next phase is cheap; catching it post-merge is not.

Lattice status is the durable record — bump it as you go, not at the end

Surface metadata (c11 set-metadata --key status) is local and ephemeral — it tells the operator what the pane is doing right now. The Lattice ticket status is a different thing: it's what the operator, the orchestrator, sibling delegators, and every future reader use to know where the work is. Bump the ticket status at every phase transition, immediately, before you spawn the next sub-agent. Never batch status updates for the end. Never assume opening a PR implies review.

Concrete invariant: before the Plan sub-agent starts, status must be in_planning. Before Impl, planned. Before Review, review is already correct (Impl ends by transitioning there). Before opening the PR, verify lattice show <ticket> reports the expected status — if it doesn't, you missed a transition; fix it before pushing further.

The orchestrator polls on these transitions to sequence dependent work (e.g., "spawn C11-4 when C11-7 hits review"). If you skip a transition, downstream delegations stall silently and the operator has to babysit. Status discipline is the contract that makes parallel delegations work.

Failure mode this prevents: delegator drives 14 commits + opens PR, but ticket status never moves past planned. Operator looking at the board has no idea the work is real, dependent tickets don't fire, audit trail breaks. (Observed 2026-04-25 on CMUX-37; the orchestrator had to backfill status by hand.)

Two-line sidebar convention

Every surface in the delegation — orchestrator, delegator, every phase sub-agent — uses a two-line read in the c11 sidebar:

• Tab title (first line): <TICKET> <ROLE> or <TICKET> <ROLE> :: <PHASE>. e.g. <TICKET> Orchestrator, <TICKET> Delegator, <TICKET> Delegator :: Plan.
• Description (second line): the ticket's purpose — a one-line restatement of what the ticket is for (the title field from lattice show). The same purpose string across every surface in the delegation, so scrubbing the sidebar tells you what the work is about, not just who's doing what role.