Delegate

Issue Delegation

Fetch open GitHub issues, assign each to the right specialist agent, and orchestrate execution. Handles parallel worktree isolation when safe and serial chaining when necessary.

Run checkpoints

The phases below (Fetch → Classify → Plan → Execute → Report) hand state forward. Rather than trust that state to prose in the orchestrating context alone, each phase writes a typed, schema-validated checkpoint and validates its predecessor's before proceeding. The checkpoint is the single source of truth for load-bearing fields — issue numbers, branch names, worktree paths — a resume point after interruption, and the audit trail the Report phase reads.

• One JSON document per run, at .claude/worktrees/.delegate/<runId>.json. <runId> is the run identifier — delegate-<timestamp> for multi-issue runs, or delegate-single-<N>-<timestamp> for the single-issue fast path. (It names the run, not a team: the session has a single implicit team and there is no team object to name.) Create the directory first: mkdir -p .claude/worktrees/.delegate. It is gitignored throwaway run state.

• Schema: .claude/skills/delegate/checkpoint.schema.json — one section per phase (scope, issues, classification, plan, execution, report), each documented inline. Start the file with { "version": 1, "runId": "<runId>" }, then append each phase's section as you complete it.

• Validator: .claude/skills/delegate/checkpoint.mjs — dependency-free (Node built-ins only, runs in any consumer repo). At every phase boundary, after writing the current phase's section, run:

  node .claude/skills/delegate/checkpoint.mjs --file .claude/worktrees/.delegate/<runId>.json --phase <fetch|classify|plan|execute|report>
  

  It checks the document shape and cross-references (every classified/assigned/executed issue traces back to a fetched issue; a parallel assignment has a worktree and a serial one does not; an executed branch matches the branch the plan assigned — this is what catches a hallucinated branch). Exit 0 = proceed. Exit 1 = STOP the run and report the error verbatim — never improvise past a failed checkpoint. This deterministic gate is the point of the mechanism; do not replace it with an eyeball "looks right".

The per-phase instructions below each end with a Checkpoint step naming the section to write and the phase to validate.

Run memory

The checkpoint above is per-run throwaway state. Run memory is the opposite: one small, curated, durable doc per repo that carries lessons between runs — repo quirks, setup steps that flake, which issues are entangled, which agent a fuzzy area really belongs to. Without it, everything learned in run N evaporates before run N+1; the two tempting fixes — an append-only log, or stuffing prior notes into prompts — both bloat unbounded until they poison context instead of helping it. So this doc is curated and hard-capped, never append-only.

• One doc per repo, at .claude/worktrees/.delegate/memory.md. It sits alongside the checkpoints and inherits the same gitignore. Same trade-off as the checkpoint dir: it persists locally but is per-clone (not committed), so memory does not follow the repo to another machine — that is acceptable, just don't treat it as authoritative shared state.

• Hard cap: 4096 bytes. The cap is the point — it forces the doc to stay a compact working set. When curation would push it over, prune the stalest entries; never raise the cap to dodge pruning.

• Format — an H1 title, a one-line preamble, then entries. Each entry is an H2 whose heading is the fact, plus three required fields so pruning is judged, not FIFO:

  # Delegate run memory — <repo>
  
  > Curated, capped (see delegate.memoryMaxBytes). Prune stale entries; never blind-append.
  
  ## Setup step `npm run seed` flakes on a cold checkout
  - **Why:** Agents burn a cycle when it fails; re-running once clears it — tell them up front.
  - **Since:** #42 — the summarize agent hit it twice before we noticed.
  - **Area:** summarize
  
  ## Issues touching `shared/` must serialize behind the config refactor
  - **Why:** Parallel edits there collide on the same export map.
  - **Since:** #55, PR #61 — learned when two worktrees conflicted.
  - **Area:** shared
  

  • Why — why the fact is forward-useful (what it saves a future run).
  • Since — the issue/PR that taught it (must contain a #N). This is the staleness anchor: when that area is later reworked, re-judge or drop the entry rather than trusting it forever.
  • Area — the module/area tag, so the Execute phase can hand each agent only the entries relevant to its issue.

• Validator / cap gate: .claude/skills/delegate/memory.mjs — dependency-free (Node built-ins only). It enforces the byte cap and the entry format:

  node .claude/skills/delegate/memory.mjs --file .claude/worktrees/.delegate/memory.md --max-bytes 4096
  

  A missing file is valid (a repo with no delegate history yet). Exit 0 = within cap and every entry well-formed. Exit 1 = over cap or a malformed entry — STOP and curate; do not improvise past it, and do not finish the run with the doc over cap. This is the deterministic gate, same as the checkpoint's — don't replace it with an eyeball "looks small enough".

The read policy lives in Phases 2–4 (Classify and Plan load the doc; each spawned agent gets only its area's entries), and the write policy in Phase 5 (Report curates — prune + rewrite — then runs the gate above).

Batch mode

/delegate pauses for human confirmation whenever the plan is non-trivial (the Phase 3 gate: >2 agents, an ambiguous assignment, or parallel execution). That gate is correct for interactive use, but it blocks delegate from running as a building block for the autonomous backlog runner (the autopilot skill), which must work through a supplied issue list without a human accepting each plan. Batch mode removes that interactive pause by treating explicit scope as the confirmation.

• Opt-in, per run. Batch mode is ON when delegate.batchMode is true; for this run it is false. Default false — the interactive confirmation gate behaves exactly as it always has.
• Activation requires explicit scope. Batch mode applies only when the invoker (a human or the autopilot orchestrator) supplied the issue set explicitly — an issue list / #N, milestone:<name>, a known label, a keyword, or the all-open / todo-column default scopes (a config-chosen default set is an explicit opt-in; a todo-column fallback resolves to all-open, itself an explicit-scope signal). That explicit scope is what stands in for the human accepting the plan. If delegate.batchMode is true but the resolved scope carries no such signal, fall back to interactive confirmation — never auto-proceed on an unscoped run.
• It changes decision points, not machinery. Classification, the parallel-only-when-areas-disjoint rules, worktree isolation for parallel groups, serial dependency chains, per-issue PR creation, and board updates are all unchanged. Batch mode changes exactly two decisions:
  1. The Phase 3 confirmation gate is skipped — instead of pausing, log the plan that would have been shown for approval (the same table) so the run stays auditable after the fact, then proceed. The plan checkpoint still records confirmed: true, tagged confirmedVia: "batch-scope" to mark that confirmation came from explicit scope under batch mode, not from a human.
  2. Ambiguous classification falls back to the safest choice — serial execution in the main checkout (a serial group, worktree null) — instead of pausing to ask.
• It composes with the other opt-ins and never weakens them.
  • With delegate.autoMerge (the autopilot orchestrator, #100, sets both), delegate plans and spawns with no pause and each PR arms itself on green — the fully unattended path.
  • delegate.approveBeforePush still wins. Batch mode removes only the Phase-3 planning confirmation; it does not disable the pre-push push approval gate. A batch run with delegate.approveBeforePush: true still stops each agent at its pre-push gate exactly as in interactive mode. The two gates are independent: batch mode silences the plan pause, approveBeforePush still holds each push.
• Process the supplied list one group at a time, in the same reasonably-chunked units delegate already produces — batch mode neither widens scope nor merges groups.

Phase 1: Fetch Issues

Argument handling — the fetch path depends on whether $ARGUMENTS is provided:

• No $ARGUMENTS (default) → delegate the project's configured default scope, which for this project is all-open:
  • current-milestone → delegate every open issue in the current milestone, and only that milestone. Resolve the current milestone first (see below), then fetch its issues. This path must never silently widen to all open issues.
  • all-open → fetch every open issue in the repo: gh issue list --state open --json number,title,labels,body,milestone --limit 50. This is the bulk path for repos that don't plan with milestones; in interactive mode the Phase 3 confirmation gate guards it — always present the full plan before spawning anything. (In batch mode, all-open is an explicit-scope signal: the plan is logged, not paused on — see Batch mode.)
  • todo-column → delegate exactly the open issues in the project board's "Todo" Status column. Resolve the board and its Status = "Todo" option first (see Resolving the Todo column below), then fetch those issues. No project board, or no "Todo" option on the Status field → fall back to all-open (a failed board lookup — API error, missing token scope — is not a missing board: it stops the run; see Resolving the Todo column) — that fallback is the documented contract of choosing delegate.defaultScope: todo-column, but it must be explicit, never silent: lead the Phase 3 plan with Board or Todo column not found → falling back to all-open (N issues); in interactive mode the confirmation gate still guards the widened set, and in batch mode that line is logged, not paused on. A Todo column that exists but is empty is NOT a fallback — that is "nothing to delegate": report that the Todo column is clear and stop (the zero-matching-issues rule below). Never widen past the Todo set for any other reason. (Contrast with current-milestone, which stops rather than widens — there the user never consented to more than the milestone; here the fallback is what the configured scope value itself opted into.)
• #N or a bare number → fetch that single issue: gh issue view N --json number,title,labels,body,milestone
• milestone:<title-or-number> → delegate that milestone explicitly: resolve a number directly, or match the title against gh api "repos/$OWNER/$REPO/milestones?state=open", then fetch its open issues exactly as in the current-milestone path.
• A known label (bug, enhancement, documentation, question) → filter: gh issue list --state open --label "$ARGUMENTS" --json number,title,labels,body,milestone
• Any other text → fetch all open issues and filter client-side by keyword match against title and body: gh issue list --state open --json number,title,labels,body,milestone --limit 50

Zero matching issues (any path) → report that there is nothing to delegate and stop.

Determining the current milestone (no-args path)

The current milestone is the open milestone with the earliest due date among those that have a due date. Milestones with no due date are backlogs (e.g. an "Icebox") and are explicitly not the current milestone.

OWNER=$(gh repo view --json owner -q .owner.login)
REPO=$(gh repo view --json name -q .name)

# Current milestone = earliest-due OPEN milestone that actually has a due date.
# CAUTION: GitHub's `sort=due_on&direction=asc` sorts NULL due dates FIRST, so a
# naive `.[0]` would wrongly pick an undated backlog. Filter out nulls in jq.
CURRENT=$(gh api "repos/$OWNER/$REPO/milestones?state=open" \
  --jq '[.[] | select(.due_on != null)] | sort_by(.due_on) | .[0]')

MILESTONE_NUMBER=$(echo "$CURRENT" | jq -r '.number // empty')
MILESTONE_TITLE=$(echo "$CURRENT"  | jq -r '.title  // empty')

Then fetch only that milestone's open issues — filter by milestone number (titles may contain em-dashes that are fragile to quote):

gh issue list --state open --milestone "$MILESTONE_NUMBER" \
  --json number,title,labels,body,milestone --limit 50

Guardrails — never widen scope beyond the current milestone:

• No open milestone has a due date (or there are zero open milestones) → MILESTONE_NUMBER is empty. Stop. Report that no current milestone could be determined, and do not fall back to all open issues. Suggest the user pass an explicit issue number, label, or keyword.
• Current milestone has zero open issues → report that it is already clear and stop.
• Always state the selected milestone (title + number) in the Phase 3 plan so the user can confirm the scope before any agent is spawned.

Resolving the Todo column (todo-column path)

Delegate exactly the board's Status = "Todo" open issues. Three lookups, in order — a successful-but-empty result at step 1 or 2 triggers the explicit all-open fallback described above; an empty result at step 3 is a clear column, which stops the run instead.

Failed lookup ≠ empty lookup. An empty capture means "no match" only when the query itself succeeded. A failed lookup at any step — a non-zero gh exit (check $? immediately after the capture) or an errors key in the GraphQL response (rate limit, 5xx, a token without Projects v2 read scope — the default Actions GITHUB_TOKEN cannot see Projects v2 at all) — must stop the run and report the error, never take the fallback. Only a confirmed no-match may widen scope; a transient failure must never widen it. This matters most in batch mode, where the fallback line is logged rather than gated — an unattended run that read an API error as "no board" would delegate the entire backlog.

1. Discover PROJECT_ID — the same title-match query Board Setup uses (an account may own several projects, so never assume the first result):

   OWNER=$(gh repo view --json owner -q .owner.login)
   REPO=$(gh repo view --json name -q .name)
   
   PROJECT_ID=$(gh api graphql -f query='
     query($owner: String!) {
       user(login: $owner) {
         projectsV2(first: 20) {
           nodes { id number title }
         }
       }
     }
   ' -f owner="$OWNER" --jq 'first(.data.user.projectsV2.nodes[] | select(.title | test("wafflestack"; "i")) | .id) // empty')
   

   For an organization-owned repo, replace user(login: $owner) with organization(login: $owner) — the same caveat github-project-board documents. It is not optional here: against an org owner the user query resolves to a null account node and the --jq filter errors (a failed lookup, not an empty one), so without the org variant a todo-column run on an org repo can never find its board.

   PROJECT_ID empty and the query succeeded → no board: fall back to all-open, stated explicitly per above. Empty because the lookup failed → stop and report (the failed-lookup rule above).

2. Find the Status field and its "Todo" option — the Board Setup fields query. Extract the field ID and all the status option IDs in one pass while $STATUS_FIELD is in hand: Board Setup reuses them for kanban sync instead of re-querying, so capturing only the Todo option here would leave the board mutations without their In Progress / In Review IDs (an absent "In Review" option simply leaves IN_REVIEW_OPTION_ID empty, exactly as Board Setup allows):

   STATUS_FIELD=$(gh api graphql -f query='
     query($projectId: ID!) {
       node(id: $projectId) {
         ... on ProjectV2 {
           fields(first: 50) {
             nodes {
               ... on ProjectV2SingleSelectField {
                 id name
                 options { id name }
               }
             }
           }
         }
       }
     }
   ' -f projectId="$PROJECT_ID" --jq 'first(.data.node.fields.nodes[] | select(.name == "Status")) // empty')
   
   STATUS_FIELD_ID=$(echo "$STATUS_FIELD" | jq -r '.id // empty')
   TODO_OPTION_ID=$(echo "$STATUS_FIELD" | jq -r 'first(.options[]? | select(.name == "Todo") | .id) // empty')
   IN_PROGRESS_OPTION_ID=$(echo "$STATUS_FIELD" | jq -r 'first(.options[]? | select(.name == "In Progress") | .id) // empty')
   IN_REVIEW_OPTION_ID=$(echo "$STATUS_FIELD" | jq -r 'first(.options[]? | select(.name == "In Review") | .id) // empty')
   

   TODO_OPTION_ID empty and the query succeeded → no "Todo" option on the Status field (or no Status field at all): fall back to all-open, stated explicitly per above. A failed fields query → stop and report (the failed-lookup rule above).

3. List the issue numbers currently in the Todo column — the github-project-management skill's items-with-status catalog query, filtered client-side to items whose content is an open Issue in this repo and whose Status fieldValues value is "Todo". The repo filter is load-bearing: a user-level project (matched by a fuzzy title regex above) can track several repos' issues, and a foreign repo's Todo issue whose number collides with an open issue here must not leak into the set:

   TODO_ITEMS=$(gh api graphql -f query='
     query($projectId: ID!) {
       node(id: $projectId) {
         ... on ProjectV2 {
           items(first: 100) {
             pageInfo { hasNextPage endCursor }
             nodes {
               content { ... on Issue { number state repository { nameWithOwner } } }
               fieldValues(first: 20) {
                 nodes {
                   ... on ProjectV2ItemFieldSingleSelectValue {
                     field { ... on ProjectV2SingleSelectField { name } }
                     name
                   }
                 }
               }
             }
           }
         }
       }
     }
   ' -f projectId="$PROJECT_ID")
   
   HAS_NEXT_PAGE=$(echo "$TODO_ITEMS" | jq -r '.data.node.items.pageInfo.hasNextPage')
   
   TODO_NUMBERS=$(echo "$TODO_ITEMS" | jq -r --arg repo "$OWNER/$REPO" '[.data.node.items.nodes[] | select(.content.state == "OPEN") | select(.content.repository.nameWithOwner == $repo) | select(any(.fieldValues.nodes[]?; .field.name == "Status" and .name == "Todo")) | .content.number | tostring] | join(" ")')
   

   The items(first: 100) bound is detectable, not hypothetical — HAS_NEXT_PAGE is the signal. true means the board holds more than 100 items and TODO_NUMBERS is a truncated set: re-run the query with an after: cursor argument set to the returned endCursor and merge each page's numbers until hasNextPage comes back false — or stop and report the truncation. Never trust a truncated TODO_NUMBERS; this path's contract is exactly the Todo set.

   TODO_NUMBERS empty → the Todo column exists but is empty. This is NOT a fallback — report that the Todo column is clear and stop (the zero-matching-issues rule).

Then fetch full issue JSON in bulk and intersect client-side — keep only the issues whose number appears in TODO_NUMBERS (same pattern as the keyword path). Unlike the all-open and keyword paths — where --limit 50 defines the set — the bound here must only be a superset of the board's Todo issues, so raise it comfortably above the 100-item board page (--limit 50 would silently clip a Todo issue that is not among the first 50 open issues):

gh issue list --state open --json number,title,labels,body,milestone --limit 500

That intersection is the delegated set. Count invariant: the intersection must hold exactly as many issues as TODO_NUMBERS — a mismatch means a Todo issue fell outside the fetched window (or the board tracks an issue that is missing here); stop and report the discrepancy rather than silently under-delegate.

Checkpoint — write scope (the resolved mode, a human description, and milestone for milestone modes) and issues (one entry per fetched issue: number, title, labels, optionally body/milestone), then validate. mode is todo-column only when the Todo set was actually delegated; a run that fell back records mode: "all-open" with the provenance in description (e.g. defaultScope todo-column: no Todo column on board — fell back to all-open (12 issues)) — the checkpoint records what actually ran, the description carries why. Validate:

node .claude/skills/delegate/checkpoint.mjs --file .claude/worktrees/.delegate/<runId>.json --phase fetch

Phase 2: Classify

Load run memory first. Read .claude/worktrees/.delegate/memory.md (skip silently if it does not exist yet) — it is small by design, so load the whole doc as compact context. Let its entries inform classification: a prior run may have recorded that a fuzzy area really belongs to a particular agent, or that two issues are entangled. Do not let memory override a clear content match; use it to break ties and flag known quirks.

For each issue, determine the best specialist agent using content-based matching. Scan the issue title and body for keywords and source paths, then apply the first matching row:

Signal (keywords / paths)	Agent
installer, CLI, render, doctor, eject, template, installer/**	harness-architect
stack, skill, agent definition, config key, stacks/**, schema/**	harness-architect
docs, AGENTS.md, architecture/status docs	docs-agent (machine) / docs-human (human)

Label fallback — if no keyword match:

Label	Agent
bug	harness-architect
enhancement	harness-architect
documentation	docs-agent
question	harness-architect

After classification, determine the area each issue touches — which module or subdirectory, and whether it includes root files (toolkit.yaml, package.json, installer/cli.mjs, schema/FORMAT.md, README.md) or installer/lib/ (render pipeline — every CLI command and test imports it). This drives parallelization.

Ambiguous classification in batch mode — when delegate.batchMode is on and an issue's agent or area cannot be pinned down confidently, do not defer it to a human. Resolve it to the safest option: settle on your best-guess agent, and flag the issue touchesShared: true so Phase 3 places it in a serial group in the main checkout (worktree null) rather than parallelizing on an uncertain area. Note the fallback in the plan you log in Phase 3. In interactive mode an ambiguous classification instead surfaces at the Phase 3 confirmation gate as usual.

Checkpoint — write classification (one entry per issue: number, agent, area, and touchesRoot/touchesShared where known), then validate. The validator enforces that every fetched issue is classified exactly once and none references an unknown issue:

node .claude/skills/delegate/checkpoint.mjs --file .claude/worktrees/.delegate/<runId>.json --phase classify

Phase 3: Plan & Confirm

Build an assignment plan table and determine parallel grouping. Consult the run memory loaded in Phase 2 while grouping: an entry recording an entanglement ("issues touching shared/ must serialize behind the config refactor") or a recurring conflict is grounds to serialize where the static rules alone would allow parallel. Memory augments the rules below; it never relaxes a serialization the rules require.

Parallelization rules — two issues can run in parallel when ALL of these hold:

• They touch different areas (no module/subdirectory overlap)
• Neither touches root files (toolkit.yaml, package.json, installer/cli.mjs, schema/FORMAT.md, README.md) or installer/lib/ (render pipeline — every CLI command and test imports it)
• No dependency language in the issue body ("depends on #N", "blocked by #N", "after #N")

Worktree isolation makes it safe for two agents of the same type to run at once — issues sharing an agent type may still parallelize as long as their areas are disjoint (each spawn is a separate instance with its own worktree and a unique name).

Serialization rules (override parallel):

• installer/lib/ (render pipeline — every CLI command and test imports it) is a bottleneck — any two issues touching it must serialize
• stack content depends on installer template semantics — installer/lib changes merge before dependent stacks/** changes.
• Security issues serialize last
• Documentation issues serialize last (need final code state)

Present the plan to the user. On the no-args path, lead with the resolved scope — the milestone (title, number, open-issue count), all open issues (N), board Todo column (N issues), or the todo-column fallback line (Board or Todo column not found → falling back to all-open (N issues)) — so the user confirms exactly what is being delegated:

## Delegation Plan

**Milestone:** v1.1.0 — Post Release (#5) — 12 open issues

| # | Issue | Agent | Module(s) | Group |
|---|-------|-------|-----------|-------|
| 3 | Fix UI hang when... | plugin-architect | summarize | A |
| 5 | Fix folder picker... | lead-engineer | shared | B (serial) |

**Parallel:** Group A runs simultaneously with worktree isolation
**Serial:** Group B runs after A completes (touches the shared module)

Proceed?

Confirmation gate:

• Batch mode (delegate.batchMode is true) with explicit scope → do not pause. Explicit scope stands in for the human accepting the plan, so skip the interactive gate: log the plan table above (the same assignment/grouping decisions you would have shown for approval) so the run is auditable after the fact, then proceed straight to execution. Any assignment that would be ambiguous was already resolved to the safest choice — serial execution in the main checkout — back in Phase 2, so it never reaches a pause here. This does not touch delegate.approveBeforePush: if that pre-push gate is on, each agent still stops before git push (see Batch mode).
• Always confirm when: >2 agents would spawn, any assignment is ambiguous, or parallel execution is planned
• Skip confirmation for a single obvious assignment (e.g., /delegate #5 with a clear match)

Wait for the user to approve, modify, or cancel before proceeding. In batch mode there is no wait — the logged plan is the audit record and execution proceeds immediately.

Checkpoint — once the plan is settled (approved, the batch-mode logged plan, or the single-obvious-assignment fast path), write plan: confirmed (true), confirmedVia (how confirmation was obtained — interactive when a human approved the gate, batch-scope when batch mode + explicit scope stood in for it, or single-obvious for the fast path), and groups, each group carrying id, mode (parallel/serial), and assignments. Each assignment records number, agent, branch (the exact git-workflow branch name), and worktree — the absolute path <repo>/.claude/worktrees/issue-<N> for parallel groups, or null for serial groups and the single-issue fast path. This plan is the source of truth Phase 4 reads branch and worktree from. Validate:

node .claude/skills/delegate/checkpoint.mjs --file .claude/worktrees/.delegate/<runId>.json --phase plan

The validator enforces that every issue is assigned exactly once, branch names are well-formed, worktree presence matches group mode (parallel ⇒ has a path, serial ⇒ null), and — when set — confirmedVia requires confirmed: true (a recorded confirmation source can't sit atop an unconfirmed plan).

Identity preflight (deterministic gate)

The plan is settled and nothing has happened yet: no board writes, no worktrees, no agents. This is the last moment at which a misconfigured git identity is free to fix. Verify it now, with a script — not by eye.

Validator: .claude/skills/delegate/identity.mjs — dependency-free, same idiom as checkpoint.mjs. Run it with the agent slugs taken from the plan checkpoint's assignments (the single source of truth — never re-derive them):

node .claude/skills/delegate/identity.mjs \
  --git-cmd 'git -c commit.gpgsign=false -c tag.gpgSign=false -c user.name="Wafflebot" -c [email protected]' \
  --agents-dir '.claude/agents' \
  --agents '<comma-separated agent slugs from the plan checkpoint assignments>' \
  <<'WAFFLE_AGENT_IDENTITIES'
{}
WAFFLE_AGENT_IDENTITIES

The --git-cmd value is single-quoted. git.cmd declares an allowlist pattern: in both the orchestration and github-workflow stacks (#254), so a value carrying ', `, $, ;, &, |, <, >, \ or a newline fails the render — the tokenizer's no-single-quote assumption is enforced at render time, not merely assumed, and this shell literal cannot be broken by a rendered value. The quote guards on the identity keys composed inside it — git.botName, git.botEmail, git.signingKey — still apply on top. The gate parses the command, it does not sanitize it; the render guard is what makes that parse safe.

What it proves, per tier. There is no runtime probe for "a human is driving", and none is needed: the tier boundary is which rendered command a commit routes through, and that is fully static.

• Human tier — every git invocation outside the skill's rendered identity-bearing commands (push, diff, log, and a bare git.cmd). Human runs stay on the human identity because nothing rendered ever overrides it, not because the gate detected a human.
• Main-agent tier — the orchestrator's own commits route through the resolved git.cmd. The gate proves that command is coherent.
• Sub-agent tier — each spawned agent's commits route through {agent-git-cmd} (see Per-agent commit identity). The gate proves that derivation is feasible and coherent for every planned agent, before any agent exists.

The preflight validates configuration, not runtime process identity: it proves the right identity will apply to each tier's commits, not who is at the keyboard.

Reading the result:

• ERROR: (exit 1) — STOP the run and report the validator output verbatim. Do not enter Board Setup; do not spawn anything. This holds in batch mode too: for an unattended run the safe move on an incoherent identity is not proceeding under the ambient one — that silent default is exactly what this gate exists to kill. Never improvise an identity. Errors include half an identity, an empty or valueless user.name / user.email (present but with no usable value), an unresolved placeholder, a non-boolean commit.gpgsign, an unparseable override map, and — the #158 bug class itself — an identity-bearing git.cmd that leaves commit.gpgsign unpinned, whose posture would otherwise fall back to the human's ambient signing config.
• WARN: (exit 0) — proceed, but surface it. Interactively, show the WARN lines with the verdict. In batch mode, append them to the logged plan so the run stays auditable. Warnings are expressed intent that cannot take effect — a per-agent identity map that is inert without the opt-in, a per-agent signingKey under a non-signing recipe, a key whose shape contradicts the pinned gpg.format.
• NOTE: (exit 0) — informational, nothing to do. A git.cmd bare of identity reports no bot identity configured and passes: that is a legitimate documented state, not a misconfiguration, and the gate must never nag the no-opt-in path. When such a base still pins a signing posture, the NOTE and the verdict both name it — an identity-bare command is not necessarily an inert one.

The gate is stateless — it writes nothing to the checkpoint. Like {agent-git-cmd}, its verdict is a pure function of the resolved config and the plan's agent list, so on resume you simply re-run it; it cannot go stale. Identity warnings worth keeping end up in the Phase 5 report.notes free text.

Board Setup

Before execution begins, discover the project board metadata for kanban sync. This is best-effort — if the project or status options are not found, log a warning and skip all board updates. A todo-column run already discovered PROJECT_ID, STATUS_FIELD_ID, IN_PROGRESS_OPTION_ID, and IN_REVIEW_OPTION_ID while resolving the Todo column in Phase 1 — reuse those values instead of re-running steps 2–3's queries.

1. Get repo owner/name:

   OWNER=$(gh repo view --json owner -q .owner.login)
   REPO=$(gh repo view --json name -q .name)
   

2. Discover PROJECT_ID — select the board by title match against the project name (an account may own several projects, so never assume the first result):

   PROJECT_ID=$(gh api graphql -f query='
     query($owner: String!) {
       user(login: $owner) {
         projectsV2(first: 20) {
           nodes { id number title }
         }
       }
     }
   ' -f owner="$OWNER" --jq 'first(.data.user.projectsV2.nodes[] | select(.title | test("wafflestack"; "i")) | .id) // empty')
   

3. Get STATUS_FIELD_ID and status option IDs (IN_PROGRESS_OPTION_ID, IN_REVIEW_OPTION_ID) from the project fields:

   gh api graphql -f query='
     query($projectId: ID!) {
       node(id: $projectId) {
         ... on ProjectV2 {
           fields(first: 50) {
             nodes {
               ... on ProjectV2SingleSelectField {
                 id name
                 options { id name }
               }
             }
           }
         }
       }
     }
   ' -f projectId="$PROJECT_ID"
   

   Look for the "Status" field and extract IN_PROGRESS_OPTION_ID. If the board also has an "In Review" option, capture IN_REVIEW_OPTION_ID; otherwise leave it unset (many boards are just Todo / In Progress / Done).

4. If PROJECT_ID is empty or any of the above fail → set BOARD_SYNC_ENABLED=false, log a warning, and skip all board updates in subsequent phases. When the board is missing entirely (or lacks the standard Status options), note that the github-project-board skill can provision or standardize it — but don't run it inline; board provisioning is a deliberate, user-approved step, not something to trigger mid-delegation.

See the github-project-management skill for the full GraphQL query catalog, and the github-project-board skill to create or standardize the board itself.

Checkpoint (optional) — record the resolved board metadata in the checkpoint's board section (enabled, plus projectId, statusFieldId, inProgressOptionId, inReviewOptionId when found) so the Report phase and any resume know whether board sync is live. This section is optional and has no dedicated validation phase; write it if the board was discovered.

Phase 4: Execute

Task Setup (multi-issue only)

When delegating 2 or more issues, create a task per issue so agents can report progress. Skip this bookkeeping for single-issue delegation.

There is no team to create: the session has a single implicit team, and the Agent tool's team_name parameter is deprecated and ignored. Coordination comes from named agents — an agent's name: is its address for SendMessage(to:) and TaskStop(task_id:).

If a spawn is rejected because the roster is flat (an agent cannot name its own spawns — only the main conversation loop can), omit name: and address the agent by the agentId the spawn returns. SendMessage and TaskStop both accept it in place of a name.

TaskCreate takes subject and description (both required) — no team_name, and no addBlockedBy at create time:

# For each issue:
task_N = TaskCreate(
  subject: "Issue #{number}: {title}",
  description: "{agent-type} implements issue #{number} on branch {branch}; opens a PR"
)

For serial dependencies (e.g., shared/ bottleneck), chain the tasks afterwards with TaskUpdate — addBlockedBy is a TaskUpdate parameter, and its key is taskId, not id:

TaskUpdate(taskId: task_B.id, addBlockedBy: [task_A.id])

Branch naming

Each agent gets a branch named per git-workflow conventions:

• Bug fix: fix/issue-{N}-{short-desc}
• Enhancement: feat/issue-{N}-{short-desc}
• Refactor: refactor/issue-{N}-{short-desc}
• Chore/docs: chore/issue-{N}-{short-desc}

Worktree provisioning (parallel groups only)

Delegate provisions its own worktrees — deliberately. The Agent tool's isolation: "worktree" parameter does work today. It was previously ignored whenever team_name was also passed (anthropics/claude-code#33045); team_name is now deprecated and ignored outright, so that bug's precondition is gone. Isolation is nonetheless not what delegate wants, for three reasons — each tested against the live harness, by spawning a real isolation: "worktree" agent and reading back its pwd, branch, HEAD, and post-run git worktree list (2026-07-13), never inferred from the tool description:

1. The path is the harness's, not ours. It lands the agent in .claude/worktrees/agent-<agentId>, and that id does not exist until spawn time (observed: .claude/worktrees/agent-afbd147fc9066e7a4). Delegate's plan checkpoint records each parallel issue's absolute worktree path before any agent is spawned, and the validator rejects a parallel assignment with no path.
2. The branch is the harness's, not ours. It creates worktree-agent-<agentId> (observed), not the git-workflow-conventional feat/issue-{N}-{short-desc}. The checkpoint validator fails an executed branch that does not match the planned one — a harness-named branch trips delegate's own hallucinated-branch gate.
3. The base is the harness's, not ours. Agent exposes no base parameter, so delegate cannot say what a worktree branches from. Observed: a spawn made from a feature branch's tip (0af9cc4) came up on main (6384311) — not the spawning checkout's HEAD. Delegate needs every worktree in a group cut from the same freshly-fetched origin/main, which it guarantees by fetching first (below); the harness gives it no way to ask for that. (What this probe did not distinguish: local main vs origin/main — they were identical when it ran. Do not promote that into a claim about local main lagging without testing it.)

Lifetime is not a fourth reason — recorded here so it is not re-inferred as one. The harness auto-cleans an isolated worktree only if the agent left it unchanged (the Agent tool's own wording — "auto-cleaned if unchanged" — and confirmed by probe: an unchanged agent's worktree was gone afterwards, while one that committed was retained, branch and all). Delegate's agents always commit, so the harness would not clean up after them regardless. Delegate does still retain a worktree while its PR is open, and retains a gate-rejected branch's worktree so its local commits can be salvaged — but that is delegate's own removal policy (see Worktree cleanup), not a conflict with the harness.

Delegate owns worktree naming and basing because its checkpoint contract depends on both being deterministic and known in advance. Use the manual pattern below for parallel groups.

For each issue in a parallel group, before spawning its agent:

# Run from the main checkout
WORKTREE_PATH=".claude/worktrees/issue-{N}"
git fetch origin main
git worktree add "$WORKTREE_PATH" -b feat/issue-{N}-{short-desc} origin/main

Notes:

• Pick the branch prefix (feat/, fix/, etc.) per the Branch naming table.
• If the branch already exists from a prior aborted run, use git worktree add "$WORKTREE_PATH" feat/issue-{N}-{short-desc} (no -b).
• Use origin/main as the base, not local main, so all worktrees start from the same fetched tip.
• Keep .claude/worktrees/ gitignored.

Retain the absolute path of each worktree (resolve with realpath "$WORKTREE_PATH") to inject into the agent's prompt. This path — and the branch — must match what the plan checkpoint recorded for this issue; read them from the checkpoint rather than re-deriving them, so a single source of truth drives both provisioning and the agent prompt.

For serial groups (including the single-issue fast path), no worktree is needed — the agent runs in the main checkout and switches branches there.

Set In Progress

Before spawning each agent, update the issue's status on the project board:

1. Get the issue node ID:

   ISSUE_NODE_ID=$(gh api graphql -f query='
     query($owner: String!, $repo: String!, $number: Int!) {
       repository(owner: $owner, name: $repo) {
         issue(number: $number) { id }
       }
     }
   ' -f owner="$OWNER" -f repo="$REPO" -F number=$ISSUE_NUMBER --jq '.data.repository.issue.id')
   

2. Add the issue to the project board (idempotent — returns existing item if already present):

   ITEM_ID=$(gh api graphql -f query='
     mutation($projectId: ID!, $contentId: ID!) {
       addProjectV2ItemById(input: {projectId: $projectId, contentId: $contentId}) {
         item { id }
       }
     }
   ' -f projectId="$PROJECT_ID" -f contentId="$ISSUE_NODE_ID" --jq '.data.addProjectV2ItemById.item.id')
   

3. Set status to "In Progress":

   gh api graphql -f query='
     mutation($projectId: ID!, $itemId: ID!, $fieldId: ID!, $optionId: String!) {
       updateProjectV2ItemFieldValue(input: {
         projectId: $projectId
         itemId: $itemId
         fieldId: $fieldId
         value: {singleSelectOptionId: $optionId}
       }) {
         projectV2Item { id }
       }
     }
   ' -f projectId="$PROJECT_ID" -f itemId="$ITEM_ID" -f fieldId="$STATUS_FIELD_ID" -f optionId="$IN_PROGRESS_OPTION_ID"
   

4. Retain ITEM_ID for each issue (needed for status update in the Report phase).

Errors in any step → log a warning and continue. Board updates must never block agent execution.

Spawning agents

Parallel groups — each agent gets a pre-provisioned worktree. Do NOT pass isolation: "worktree" — delegate provisions worktrees itself so the path, branch, and base commit are deterministic and match the checkpoint (see Worktree provisioning above). Inject the worktree path into the prompt; the agent will cd into it as its first action.

Agent(
  subagent_type: "{agent-type}",
  name: "issue-3-{agent-type}",
  run_in_background: true,
  prompt: <agent prompt with WORKTREE_PATH baked in>,
  description: "Issue #3: Fix UI hang"
)

Spawn all agents of the group in the same response (multiple Agent tool calls in one message) so they run truly concurrently.

Single-issue fast path — skip the task bookkeeping entirely, and spawn without a name: (nothing needs to address it). Run in the main checkout, no worktree needed:

Agent(
  subagent_type: "{agent-type}",
  prompt: <agent prompt>,
  description: "Issue #3: Fix UI hang"
)

Serial groups — spawn agents one at a time in the main checkout. Wait for each to complete before spawning the next.

Silent specialists — a specialist agent only has the tools its definition grants. Agents without SendMessage/TaskUpdate finish silently: never wait on a report-back from them. After each agent completes, verify its work directly (branch pushed? PR opened? gh pr list --head {branch-name}) and do the task/board bookkeeping yourself.

Per-agent commit identity

Every spawned agent commits under its own git author, so two agents in the same run produce distinct attribution instead of a byte-identical trailer. The Identity preflight at the end of Phase 3 already proved this derivation feasible for every planned agent; what follows is the derivation it validated. You compute that author at spawn time, per agent, and bake it into the prompt as {agent-git-cmd}. Do not write it into the plan checkpoint — the checkpoint schema is closed (additionalProperties: false), and this value is a pure function of the two inputs below, so re-derivation at spawn time cannot drift.

The base command — this project's resolved git.cmd, and the source of the base name and email:

git -c commit.gpgsign=false -c tag.gpgSign=false -c user.name="Wafflebot" -c [email protected]

The consumer overrides — this project's resolved git.agentIdentities ({} means no overrides; every agent uses the derived default):

{}

Derive {agent-git-cmd} for an agent with slug <agent-slug>:

1. If the base command is bare of identity — it sets neither user.name nor user.email (a plain git, or one that pins only a signing posture) — this project has not opted into a bot identity. Then {agent-git-cmd} is the base command verbatim — no virtualization, and git.agentIdentities is inert. The toolkit never clobbers a human's git config; git.cmd is the single opt-in switch and there is no second one. Stop here. A base that sets one half of the identity — a user.name with no user.email, or the reverse — is not this no-opt-in state but a misconfiguration: the missing half falls back to the ambient config, and the identity preflight fails the run on it (half an identity).
2. Otherwise derive the agent's defaults:

   • Display name — read identity.displayName from the rendered agent definition at .claude/agents/<agent-slug>.md. If the file or the field is absent (general-purpose, for instance, is a harness built-in with no definition file), title-case the slug: lead-engineer → Lead Engineer.

   • Email — take the user.email= value out of the base command and insert +<agent-slug> immediately before the @: [email protected] → [email protected]. Unless the base cannot subaddress — then use it verbatim, no + inserted. It cannot subaddress when either:

     • its domain is users.noreply.github.com (or any *.noreply.github.com) — that domain routes only the <id>+<username>@ shape, so a second + segment resolves to nothing at all; or
     • its local part already contains a + (12345+wafflebot@…, bot+ci@…) — the tag is already spent; appending another does not yield "the base, tagged".

     This matters when a project overrides the subaddressable default git.botEmail ([email protected]) with a noreply base: in that case every agent shares one email and attribution rides on the display name alone; give an agent its own address with an explicit git.agentIdentities[<agent-slug>].botEmail entry (rule 3), which is applied verbatim.

3. Apply git.agentIdentities[<agent-slug>] over those defaults, per field: botName replaces the display name; botEmail replaces the email verbatim (an explicit override is exact — do not plus-address on top of it); signingKey, when present, additionally appends -c user.signingkey=<key> to the command.
4. {agent-git-cmd} = the base command with the user.name= value swapped for the (always double-quoted) display name and the user.email= value swapped for the virtualized email. Swap the values in place; do not rebuild the command from scratch — everything else the project put in git.cmd (a -c commit.gpgsign=false, say) must survive.

The signing resolution rule: the recipe owns the posture, keys own key selection. git.cmd decides whether and how commits are signed — for the bot and for every agent derived from it (rule 4 preserves its flags verbatim). A per-agent signingKey (rule 3) appends -c user.signingkey=<key> after those flags, and git's last-wins -c semantics make it the effective key when the base recipe signs. Under the canonical -c commit.gpgsign=false recipe a per-agent key is deliberately inert — one map leaf must not silently overturn a project-wide "do not sign". When the base does sign, a per-agent key inherits the base's pinned gpg.format — it selects a key for that signer, so its shape must match: a GPG-shaped key id under gpg.format=ssh (or a key path under openpgp) fails every commit by that one agent at its first signature. The identity gate WARNs on a shape mismatch (a heuristic — the signer is the authority); fix the key or the base recipe, never with per-agent posture flags. If a spawned agent's commit hangs or fails on a signing prompt, that is a config problem: stop and surface it to the human. Never add -c commit.gpgsign=false (or any other posture flag) to a commit yourself.

Four caveats, so nothing is over-claimed:

• Attribution is per agent type, not per spawn. Two parallel instances of the same agent share one identity — issue-3-lead-engineer and issue-7-lead-engineer both commit as Lead Engineer. Two different agents are distinct, which is the guarantee.
• A plus-addressed email is a distinct address to GitHub. Commits authored under bot+<slug>@domain do not link to the bot's GitHub account (no profile) unless that exact alias is registered there. Plus-addressing buys per-agent attribution and mail filtering, not account linkage. For the avatar, that unlinked state is the point: GitHub falls back to the address's Gravatar when it belongs to no account (and to the gray Octocat when it has none). The toolkit owner registers one Gravatar per agent address with wafflestack avatars sync, so consumers on the default [email protected] get per-agent avatars for free — the generated .waffle/AVATARS.md lists each agent's avatar file, its exact commit email, and the pipeline. Do not add these aliases to the bot's GitHub account: that relinks every agent to one profile and one avatar.
• A noreply base gets no per-agent email at all. Per rule 2, *@users.noreply.github.com (and any base whose local part already carries a +) is used verbatim rather than mangled into an address that routes nowhere. Agents still commit under distinct names; distinct addresses need explicit git.agentIdentities entries.
• Sub-agent commits are unverified by design. Under the canonical commit.gpgsign=false recipe they are unsigned and GitHub shows no badge (a neutral state — signing with a key GitHub cannot check would instead show the yellow "Unverified"). Where the bot email subaddresses (the bot+<slug>@… shape), making them "Verified" means registering each alias on the bot's GitHub account, which relinks every agent to one profile and one avatar: there, per-agent avatars and verified sub-agent commits are mutually exclusive, and this toolkit recommends the avatars. The default [email protected] subaddresses, so a default project is in that avatars-vs-verified trade-off and this toolkit takes the avatars. On a noreply base — an opt-in override, and the previous caveat's case — the trade-off does not arise: rule 2 gives every agent the bot's email verbatim, so there is no alias to register and no per-agent avatar to lose, and under a signing recipe those commits are Verified already. A repo with required signatures branch protection cannot use plus-addressed sub-agent authors at all.

Co-authored-by: Dustin Keeton <[email protected]> is unchanged by any of this: with per-agent authors, the author records which agent did the work, while the trailer defaults to crediting the repo owner (Dustin Keeton <[email protected]>) — so the work that reaches the default branch counts toward the owner's contribution graph.

Agent prompt template

Each spawned agent receives this prompt. Its load-bearing fields — {number}, {branch-name}, and {worktree_path} — come from this issue's entry in the plan checkpoint (the single source of truth), not from re-derivation; {agent-git-cmd} is computed at spawn time per "Per-agent commit identity" above. For parallel groups, fill in {worktree_path} with the checkpoint's worktree value (the absolute path provisioned for this issue). For serial groups / single-issue fast path, omit the "Working directory" section — the agent works in the main checkout and creates its branch there per the git-workflow skill.

Inject only this issue's relevant memory. From the run-memory doc loaded in Phase 2, select the entries whose Area matches this issue's classified area (plus any that name this issue number in their Since), and paste just those into the "Repo notes from prior runs" section below. Do not dump the whole doc into every agent — an agent gets only what pertains to its issue. If no entry matches, omit the section entirely.

You are assigned to GitHub issue #{number}: {title}

## Working directory

YOUR WORKTREE: {worktree_path}

FIRST COMMANDS — run before anything else, each as its OWN Bash call (a chained `cd … && git status` matches no single-program allowlist entry):

    git -C {worktree_path} status

    cd {worktree_path}

Every subsequent shell command in your session MUST run from this directory. Bash sessions persist `cwd`, so the single standalone `cd` above is enough — but never run `cd` to a different directory afterward, and never operate on the parent checkout. If your harness resets `cwd` between calls, address the worktree explicitly instead of re-chaining: `git -C {worktree_path}` for git commands, absolute paths under {worktree_path} for everything else.

The worktree is already on branch `{branch-name}` based on `origin/main`. Do NOT run `git checkout main` or `git pull` — that would corrupt sibling agents' worktrees. Just start committing.

## Issue body

{full issue body from GitHub}

## Repo notes from prior runs

{only the memory entries whose Area matches this issue — omit this whole section if none}

## Instructions

1. Read the relevant source files identified in the issue.
2. Implement the fix/feature following the project's conventions.
3. Run the pre-flight checklist:
   - npm run validate
   - npm run typecheck
   - npm test
   - npm run build
   - `npm run validate` passes after any stack/manifest edit
- If `stacks/**` changed: re-run `node installer/cli.mjs render --allow-unreleased` and commit the updated render + lock (the doctor CI gate fails on drift) — never hand-edit rendered `.claude/` output. The flag is required (#373): `render` refuses from a toolkit that is not at a release tag, and a feature branch never is. It suppresses the refusal, not the truth.
4. Commit your work following the git-workflow skill — commit with `{agent-git-cmd} commit` (that is where your own agent identity, if this project configures one, is applied) and end every commit message with `Co-authored-by: Dustin Keeton <[email protected]>`. Commit everything **locally**; do not push yet.
5. Push and open the PR — but first check the approval gate. The gate is ON when `delegate.approveBeforePush` is `true`; for this run it is **`false`**.
   - **Gate off (`false`, the default):** push and open the PR yourself, exactly as usual —
     - Push: git push -u origin {branch-name}
     - Create a PR: gh pr create --title "{type}: {short description}" --body "..." targeting main.
   - **Gate on (`true`):** do NOT run `git push` or `gh pr create`. Stop at the local commit and hand an approval summary to the orchestrator — branch `{branch-name}`, target issue #{number}, diffstat (`git diff --stat origin/main...HEAD`), and commit list (`git log --oneline origin/main..HEAD`):
     - If you have SendMessage, send that summary to `team-lead` and WAIT for an explicit approval reply. On approval, push and open the PR as above. On rejection, leave the worktree exactly as-is (committed, unpushed) and report the rejection — never push.
     - If you lack messaging tools, STOP after committing without pushing, and make the approval summary your final message. The orchestrator inspects your worktree, collects approval, and completes or withholds the push itself.
6. Arm auto-merge — opt-in, and only when a PR was actually opened. Auto-merge is ON when `delegate.autoMerge` is `true`; for this run it is **`false`**.
   - **Off (`false`, the default):** do nothing — leave the PR for a human to merge. Skip this step; nothing else changes.
   - **On (`true`):** immediately after `gh pr create` succeeds, arm the PR to merge itself once the base branch's required checks pass:
     - gh pr merge --auto --merge <pr-number>
     - Merge commits, not squash — squash is disabled on this repo. `--auto` only arms when the repo has **"Allow auto-merge"** enabled *and* a required status check is configured for the base branch (otherwise there is nothing for it to wait on). If it cannot arm, report the PR as **open but auto-merge could not be enabled** — do **NOT** fall back to an immediate merge or `--admin` merge, and never bypass branch protection.
     - On a **successful** arm, label the PR as a durable paper trail that automation (not a human) queued the merge: `gh pr edit <pr-number> --add-label "waffle-auto-merged"` — only when `--auto` actually armed (the label means "armed," not "attempted"); the label must already exist in the repo.
   - If the approval gate (step 5) was on and your push was **rejected**, there is no PR — skip this step.
   - State in your report whether auto-merge armed on the PR.
7. If you have the tools, mark your task as completed — TaskUpdate(taskId: "<task_id>", status: "completed") — and report back: SendMessage(to: "team-lead", message: <summary with PR URL and whether auto-merge armed, or the approval summary when the gate is on>, summary: "issue #{N}: PR opened"). If you lack these tools, just ensure the PR exists (gate off) or the local commit is in place (gate on); the orchestrator verifies your work directly.

Branch name: {branch-name}

Approval gate (opt-in — only when delegate.approveBeforePush is enabled)

This step runs only when delegate.approveBeforePush is true. When it is false (the default), agents push and open their own PRs autonomously — skip this section entirely; nothing about the run changes.

When the gate is on, each agent commits locally and STOPS before git push (see the agent prompt template). No branch may leave the machine until the human has approved it. For each agent that has reached its pre-push stop:

1. Assemble the summary. Take it from the agent's report if it sent one, or reconstruct it straight from the branch/worktree — either is authoritative:

   # <dir> = the agent's worktree (parallel groups) or the main checkout (serial / single-issue).
   git -C <dir> log  --oneline origin/main..<branch>   # commit list
   git -C <dir> diff --stat    origin/main...<branch>  # diffstat
   

2. Collect the decision. Present each summary — branch, target issue, diffstat, commit list — to the human with AskUserQuestion, offering Approve, Approve all remaining, and Reject. Ask one question per agent, or a single multi-select over all pending agents. Never assume approval on a timeout or a silent agent.

3. On approval → the branch is pushed and the PR opened: reply to a waiting (messaging-capable) agent with the approval so it pushes (it then arms auto-merge itself per step 6 of its prompt), or, for a silent agent, push and open the PR yourself from its worktree/branch — and when you open it yourself, arm auto-merge too if delegate.autoMerge is on, following the same guardrails (arm with gh pr merge --auto --merge; on a successful arm, label it as a paper trail with gh pr edit <pr#> --add-label "waffle-auto-merged"; on failure leave it open-but-not-armed, never --admin). Record approval: "approved" and approvedBy (who approved) in this issue's execution entry.

4. On rejection → do NOT push. Leave the worktree and its local branch intact for inspection (never git worktree remove a rejected branch). In this issue's execution entry record status: "skipped", pr: null, approval: "rejected", and approvedBy (who rejected), and surface it in the Report.

Post-agent verification

After each agent completes, verify the build still passes in the main working directory:

npm run typecheck

npm test

Run each as its own Bash call — one command per call, which is why each gets its own fence above. A single Bash call whose text joins commands matches no single-program tool-allowlist entry and is silently denied, and that is true of a newline-separated pair (cmd1\ncmd2) exactly as it is of cmd1 && cmd2: this repo's own dispatch prompts warn against both, and the hygiene workflow's denial classifier counts a newline as a compound separator. Two commands in one fence read as one call, so they get two fences.

If verification fails after a parallel agent's worktree merge, stop and report the conflict.

Checkpoint — after all agents finish, write execution: one entry per planned issue with number, agent, branch (verified from gh pr list --head <branch> / the pushed branch — not re-typed from memory), status (done/failed/skipped), pr (URL or #number, or null), and optional boardMoved. When the approval gate was on (delegate.approveBeforePush), also record approval (approved/rejected) and approvedBy per entry — a rejected push is status: "skipped" with pr: null (the validator enforces this, so a rejection can never masquerade as a merged PR). When auto-merge was enabled for the run (delegate.autoMerge), also record autoMergeArmed (true/false) per entry — whether gh pr merge --auto actually armed on that PR. Verify it, don't assume it: gh pr view <pr> --json autoMergeRequest -q '.autoMergeRequest != null' returns true only when the PR is really armed; a PR left open-but-not-armed (no required check, or auto-merge disabled on the repo) records false. The validator enforces that only a PR-bearing entry can be autoMergeArmed: true. Validate:

node .claude/skills/delegate/checkpoint.mjs --file .claude/worktrees/.delegate/<runId>.json --phase execute

The validator cross-checks every execution branch against the branch the plan assigned — a mismatch (hallucinated or stale branch) stops the run here rather than surfacing as a broken Report.

Phase 5: Report

After all agents complete, present a summary. Build the table from the checkpoint's execution and issues sections — that is the audit trail, so the report can never disagree with what actually ran:

## Delegation Report

| # | Issue | Agent | Status | PR |
|---|-------|-------|--------|----|
| 3 | Fix UI hang... | plugin-architect | done | #6 |
| 5 | Fix folder picker... | lead-engineer | done | #7 |

Build: passing

Approval gate — when it was active for the run (any execution entry carries an approval field), add an Approved by column so the report records who approved or rejected each push. A rejected issue shows status: skipped with no PR; call it out explicitly and note that its worktree/branch was left local and intact for inspection (it is not cleaned up).

Auto-merge — when it was enabled for the run (delegate.autoMerge; any execution entry carries an autoMergeArmed field), add an Auto-merge column reading armed or not armed per PR. Call out every PR that came back not armed explicitly — it is open but will not merge itself (auto-merge disabled on the repo, or no required check on the base branch), so a human still has to merge it. An armed PR merges itself once its required checks pass; the post-merge board-to-Done move for those is the orchestrator's job (see Board status after work), not a human's.

Curate run memory

Now distil this run's durable, forward-useful lessons into the run-memory doc at .claude/worktrees/.delegate/memory.md — the source of truth the next run's Classify/Plan phases read (see Run memory above). This is a curation, not an append:

1. Read the existing doc (create it with the H1 + preamble header if this is the repo's first run) and take its current entries as the baseline. Draw candidate lessons from what this run actually surfaced — the checkpoint is the audit trail: setup steps that flaked, a misclassification that had to be corrected, issues that turned out entangled, a repo quirk an agent reported.

2. Only record what will help a future run. Skip one-off details and anything already obvious from the code. Every entry needs its three fields — Why, Since (cite the issue/PR from this run, with a #N), and Area.

3. Prune as you go — judged, not FIFO. Drop or rewrite entries whose Since anchor was superseded by this run (e.g. the quirk it noted was just fixed), and merge duplicates. The doc must stay curated: replacing a stale entry is preferred over adding a new one beside it.

4. Enforce the cap. After rewriting, run the deterministic gate — the run may not complete while it fails:

   node .claude/skills/delegate/memory.mjs --file .claude/worktrees/.delegate/memory.md --max-bytes 4096
   

   Exit 1 (over cap, or a malformed entry) → prune further and re-validate. Do not raise delegate.memoryMaxBytes to escape curation, and do not finish the run with the doc over cap or an entry missing a field. Exit 0 → memory is curated and within budget; proceed.

If nothing durable was learned this run, that is a valid outcome — leave the doc unchanged (or make only prunes) and still run the gate to confirm it is within cap.

Checkpoint — write report (build: passing/failing/unknown, plus optional notes for failures, skips, rejected pushes, worktree-cleanup caveats, or memory-curation notes), then validate the completed run:

node .claude/skills/delegate/checkpoint.mjs --file .claude/worktrees/.delegate/<runId>.json --phase report

Board status after work

For each issue where the agent succeeded AND created a PR, update the board status:

• If the board has an "In Review" option (IN_REVIEW_OPTION_ID captured in Board Setup), set the item to it with the mutation below.
• Otherwise leave the item as "In Progress" — a human moves it to "Done" when merging the PR.

# Only if IN_REVIEW_OPTION_ID was captured in Board Setup:
gh api graphql -f query='
  mutation($projectId: ID!, $itemId: ID!, $fieldId: ID!, $optionId: String!) {
    updateProjectV2ItemFieldValue(input: {
      projectId: $projectId
      itemId: $itemId
      fieldId: $fieldId
      value: {singleSelectOptionId: $optionId}
    }) {
      projectV2Item { id }
    }
  }
' -f projectId="$PROJECT_ID" -f itemId="$ITEM_ID" -f fieldId="$STATUS_FIELD_ID" -f optionId="$IN_REVIEW_OPTION_ID"

Skip if: agent failed, no PR was created, or board setup was disabled (warning in Board Setup phase).

Failed agents leave the issue as "In Progress" — this is intentional, as stalled "In Progress" items are visible on the board as work that needs attention.

Auto-merge armed PRs (delegate.autoMerge) merge themselves once their required checks pass — no human is at the merge to move the board. So for an armed PR the post-merge move to Done is the orchestrator's housekeeping, not a human's: after arming, once the PR has actually merged (poll gh pr view <pr> --json state -q .state for MERGED, or pick it up on the next post-merge sweep), set its board item to "Done" and close any straggler issue. Until it merges it stays "In Review" (or "In Progress"), same as any other open PR. Do not move it to Done at arming time — arming only queues the merge; it is not merged yet.

Include any failures or skipped issues with reasons.

After the PRs merge, verify the issues actually closed — GitHub's closing keywords apply per reference (Closes #1, #2 only closes #1), and epics never auto-close from their sub-issues. Close stragglers explicitly.

Worktree cleanup (parallel groups only)

Once each agent's PR is merged, remove its worktree:

git worktree remove .claude/worktrees/issue-{N}

Do not remove worktrees while their PRs are still open — the user may want to push follow-up commits from there. A branch rejected at the approval gate has no PR and was never pushed: leave its worktree in place too, so the user can inspect or salvage the local commits. If git worktree remove complains about a dirty tree, leave it for the user to inspect and report it in the delegation summary.

Agent teardown (multi-issue only)

After reporting, stand every agent this run spawned down. Teardown is shutdown-then-stop: shutdown_request is the polite first step and an agent that honours it terminates cleanly, but it is not reliable on its own — a requested agent can go idle and stay alive. TaskStop is what actually terminates it, and it is safe to call on an agent that has already exited. Never treat a sent shutdown_request as proof the agent is gone.

# For each agent:
SendMessage(to: "issue-{N}-{agent-type}", message: {type: "shutdown_request", reason: "Delegation complete"})
TaskStop(task_id: "issue-{N}-{agent-type}")

There is no team to delete — the session has a single implicit team, so nothing was created and nothing is torn down but the agents themselves.

Error Handling

• Checkpoint validation failure — checkpoint.mjs exited non-zero. Stop at that phase boundary. Report the validator's error verbatim; do not enter the next phase or improvise the missing/mismatched state. Fix the checkpoint (or re-run the phase that wrote it) and re-validate before continuing. The checkpoint also survives an interruption: on resume, re-validate the last-written phase to find where the run left off.
• Identity preflight failure — identity.mjs exited non-zero. Stop before Board Setup, report the validator output verbatim, and never improvise an identity or fall back to the ambient one. This holds in batch mode as well as interactively. Fix the identity configuration (git.cmd, git.agentIdentities), re-render, and re-run the preflight before continuing.
• Build failure — stop the chain, report to the user, do not create a PR for the failing agent's work
• Agent cannot complete — add a comment to the GitHub issue via gh issue comment {N} --body "..." explaining what was attempted and what blocked completion, then move on to the next issue
• Worktree conflict — fall back to serial execution in the main working directory, report the conflict
• All agents failed — present a summary of all failures and suggest manual intervention
• Board sync failure — log warning and continue; board updates are informational, never blocking