@mmerterden/multi-agent-pipeline 20.35.0 → 20.37.0

package/pipeline/commands/multi-agent/autopilot-on/SKILL.md

@@ -15,10 +15,9 @@ confirm: required
 Turns on the mode that picks work up without being asked. **No repo is included
 by default and none is ever added implicitly** - you choose, here, every time.
 
-Why a picker rather than a label alone: push rights usually reach far more repos
-than you own, many of them other people's. A label is a filter; anyone who can
-open an issue in a repo you happen to have push on could add one. The gate is
-this selection, and it is per machine.
+The gate is this selection, per machine; a label alone is only a filter.
+Reasoning and detail for every step: `$HOME/.claude/multi-agent-refs/autopilot-on/details.md`. Read it
+when Jira is a source or a step's reasoning is needed.
 
 ## Steps
 
@@ -30,8 +29,7 @@ command -v jq >/dev/null 2>&1 || echo "BLOCKED: jq is required"
 node "$HOME/.claude/scripts/doctor.mjs" >/dev/null 2>&1; [ "$?" -ge 2 ] && echo "BLOCKED: doctor reports a blocking problem - fix it first"
 ```
 
-Any BLOCKED line stops here and is reported. Arming unattended work on an install
-that `doctor` calls broken produces a queue of failures, one per item.
+Any BLOCKED line stops here and is reported.
 
 ### 2. The repo list, both halves of it
 
@@ -44,9 +42,7 @@ Two states come back and **both are shown**:
 - `eligible` - push rights and a checkout on this machine
 - `unavailable` - push rights, no local checkout, listed WITH that reason
 
-Never hide the second list. Dropping most of the rows silently looks exactly like a
-permissions problem, and the user goes hunting for a token fault that does not
-exist.
+Never hide the second list.
 
 ### 3. Pick, with the current selection already checked
 
@@ -57,34 +53,23 @@ Read `~/.claude/autopilot/config.json` if it exists, then one `AskUserQuestion`
 - `header`: "Repos" (English, UI contract)
 - `options`: one per eligible repo, currently-selected ones marked "(seçili)" / "(selected)"
 
-**This is how repos are added and removed.** Checking a new one adds it;
-unchecking an existing one removes it. There is no `add-repo` / `remove-repo`
-command, because two entry points to one list is two lists.
+**This is how repos are added and removed** (check adds, uncheck removes); there
+is no `add-repo` / `remove-repo` command.
 
 Unavailable repos are printed above the question as a plain list with their
 reason, not offered as options.
 
 ### 4. Sources and label, per selected repo
 
-One `AskUserQuestion` per newly added repo (already-configured ones keep their
-answers - re-running must not re-ask what was already settled):
+One `AskUserQuestion` per newly added repo (never re-ask a configured one):
 
 - Sources: `GitHub issues` / `Jira` / both
 - Label: default **`agent-queue`** on both sides, editable
 
-The same name works on both sides and both mechanisms already exist:
-
-| Source | Query | Extra condition |
-|---|---|---|
-| GitHub | `gh issue list --repo <r> --label <label> --assignee @me --state open` | **assigned to you** (`githubAssignee`, `"*"` for any), so a label an issue form applies is not enough |
-| Jira | `assignee = currentUser() AND labels = "<label>" AND resolution = EMPTY AND status not in (Done, Closed, Cancelled)` | **assigned to you**, so a label somebody else adds is not enough |
-
-Two Jira caveats worth saying out loud when Jira is selected: labels are one
-global namespace across the whole instance and anyone can write them, so on a
-shared instance prefer a qualified name (`agent-queue-<team>`); and the Labels
-field has to be on the edit screen for the issue types in play. An instance where
-neither holds is a `jiraJql` config change - a saved filter, a component - not a
-redesign.
+Both sources pick up only items **assigned to you** that carry the label; the
+query per source is in `details.md`, "Source queries". When Jira is selected,
+state the two Jira caveats from that section (global label namespace, Labels
+field on the edit screen).
 
 Run the query before saving it, and show the count:
 
@@ -92,21 +77,13 @@ Run the query before saving it, and show the count:
 bash "$HOME/.claude/scripts/jira-search.sh" --jql "$JQL" --max 5 | jq '.total, [.issues[].key]'
 ```
 
-A JQL that returns nothing is not an error and is usually correct on day one
-(nothing is labelled yet), but a JQL that errors is a config that will be silent
-forever - the Labels field missing from an edit screen looks exactly like an
-empty queue from the outside. Saying "0 items, query valid" and "query rejected"
-differently here is the difference between a two-minute fix and a week of
-wondering why nothing happens.
+Report "0 items, query valid" and "query rejected" differently.
 
 ### 5. Keep the Mac awake: display on, or allowed to sleep
 
-While the mode is on, the Mac is kept awake by a second launchd agent,
-`com.multi-agent.autopilot-awake`, which runs `/usr/bin/caffeinate -s -i` from
-**Start** until `autopilot-off`. Without it the machine can sleep between ticks,
-and launchd does not wake it for the next one: the queue stops with nothing to
-say so. `-s` holds system sleep off on AC power; `-i` holds idle sleep off on
-battery too.
+While the mode is on, a second launchd agent, `com.multi-agent.autopilot-awake`,
+runs `/usr/bin/caffeinate -s -i` so the Mac does not sleep between ticks (why:
+`details.md`, "Keeping the Mac awake").
 
 One `AskUserQuestion` decides the display:
 
@@ -117,8 +94,7 @@ One `AskUserQuestion` decides the display:
 Branch on the option selected: **Display may sleep** writes `awake.display:
 false`, **Keep display on** writes `awake.display: true`, both with
 `awake.enabled: true`. A config that already carries `awake` shows its current
-answer as the first option. Display sleep does not lock the keychain; system
-sleep can, which is the part `-s -i` prevents regardless of this answer.
+answer as the first option.
 
 ### 6. Write the config
 
@@ -126,10 +102,9 @@ Validate against `schemas/autopilot-config.schema.json`, then write
 `~/.claude/autopilot/config.json` (0600, in a 0700 directory) via
 `ma_ap_write` in `lib/autopilot-state.sh`. Defaults that are not asked:
 `slots: 1`, `scanIntervalSeconds: 120`, `maxAttempts: 2`,
-`costCeilingUsd: 25`. `awake` carries the answer from the previous step. Keys the schema reserves and nothing reads
-(`askOnLowMaturity`, `reportStatus`, `sendItemKeys`) are not written. A config
-written by an older version may carry `depthRouter` or one of those; the schema
-still accepts them and nothing reads them, so drop them when rewriting the file.
+`costCeilingUsd: 25`. `awake` carries the answer from the previous step. Never
+write `askOnLowMaturity`, `reportStatus`, `sendItemKeys` or `depthRouter`; drop
+them when rewriting an older file.
 
 ### 7. Build the menu bar indicator (best effort)
 
@@ -141,15 +116,10 @@ if command -v swiftc >/dev/null 2>&1; then
 fi
 ```
 
-Built from source on demand, never shipped as a binary: the package contains only
-text today, and a compiled artifact in it would need signing and notarization to
-be distributable. No `swiftc` means no indicator and nothing else changes - say
-so in one line rather than failing. `autopilot-status` works either way.
-
-The compiled binary is the one thing an update does not replace, so the runner
-rebuilds it on the first tick after `autopilot-menubar.swift` becomes newer than
-`bin/menubar`. A machine that is already on picks up a new indicator without
-running this command again.
+Built from source on demand, never shipped as a binary. No `swiftc` means no
+indicator and nothing else changes - say so in one line rather than failing.
+`autopilot-status` works either way. The runner rebuilds it when the source is
+newer.
 
 ### 8. Confirm the schedule, naming the file
 
@@ -163,62 +133,26 @@ node "$HOME/.claude/scripts/autopilot-arming.mjs" probe
 `PROBE_READY=false` removes **Start** from the question below: each
 `PROBE_PROBLEM=` line names the logical key (or GitHub) and the fix, and is shown
 as it is. "Configure only" stays available. `PROBE_WARNING=` lines are shown and
-do not block: a login keychain that locks on sleep or after a timeout is readable
-now and locked for the tick after the Mac slept, which every tick checks again
-and refuses with the same message. `features/autopilot-operations.md` has the
-probe's rules.
+do not block (why: `details.md`, "Probe warnings").
 
 Render `templates/multi-agent-autopilot.plist.template` by substituting its seven
-placeholders, then show the resolved **path** and interval and `AskUserQuestion`:
-
-```bash
-. "$HOME/.claude/lib/autopilot-state.sh"
-TPL=$(ma_ap_asset templates/multi-agent-autopilot.plist.template) || {
-  echo "BLOCKED: the plist template is not installed on this host - re-run the installer"; exit 1; }
-DEST="$HOME/Library/LaunchAgents/com.multi-agent.autopilot.plist"
-INTERVAL=$(bash "$HOME/.claude/scripts/autopilot-status.sh" --json | jq -r '.scanIntervalSeconds // 120')
-sed -e "s|{{NODE}}|$(command -v node)|g" \
-    -e "s|{{TICK}}|$HOME/.claude/scripts/autopilot-runner.mjs|g" \
-    -e "s|{{LABEL}}|com.multi-agent.autopilot|g" \
-    -e "s|{{ROOT}}|$HOME/.claude/autopilot|g" \
-    -e "s|{{INTERVAL}}|$INTERVAL|g" \
-    -e "s|{{HOME}}|$HOME|g" \
-    -e "s|{{CLAUDE}}|$(command -v claude || true)|g" \
-    "$TPL" > "$DEST"
-```
-
-`ma_ap_asset` rather than a literal `$HOME/.claude/templates/...`: only
-`install/claude.mjs` used to lay that tree down, so on a Copilot-only or
-Codex-only machine the mode would have written a launchd job from a template
-the host does not have. The state root stays shared on purpose - two CLIs on one
-machine must see one queue, not two.
-
-`command -v node` rather than the bare word: launchd does not read a login
-shell, so its `PATH` is the short one in the plist's own `EnvironmentVariables`,
-and a Homebrew or nvm node that is not on that path would make every tick fail
-with a message nobody is watching for. `claude` is captured the same way, and
-the plist's `PATH` carries `~/.local/bin` as well, which is where the native
-installer puts it; the runner tries the captured path first, then that `PATH`.
+placeholders with the block in `details.md`, "Rendering the plist" (template via
+`ma_ap_asset`, never a literal templates path), then show the resolved **path** and interval and `AskUserQuestion`:
 
 - `question`: install the schedule at `~/Library/LaunchAgents/com.multi-agent.autopilot.plist`, and the awake agent at `~/Library/LaunchAgents/com.multi-agent.autopilot-awake.plist`, and start picking work up?
 - options: `{ label: "Start" }` / `{ label: "Configure only", description: "Save the repo selection, do not schedule anything yet" }`
 
-"Configure only" is a real answer and the safe default to offer first: the queue
-can be watched with `autopilot-status` for a while before anything runs.
+"Configure only" is a real answer and the safe default to offer first.
 
-On **Start**, load the schedule and the awake agent with the same script the
-office panel's `POST /v1/autopilot/on` calls, naming every repo selected in step 3:
+On **Start**, load the schedule and the awake agent, naming every repo selected
+in step 3:
 
 ```bash
 node "$HOME/.claude/scripts/autopilot-control.mjs" on --repo <owner/name> [--repo <owner/name>...]
 ```
 
-It keeps exactly those repos in `config.json`, probes their credentials again
-(`autopilot-arming.mjs probeCredentials`), renders
-`templates/multi-agent-autopilot.plist.template` with its seven placeholders
-(NODE, TICK, LABEL, ROOT, INTERVAL, HOME, CLAUDE), loads it with `launchctl
-bootstrap` (falling back to `load`) and installs the awake agent with the
-`awake.display` answer saved above. `scheduled: false` with probe problems means
+It re-probes credentials, renders and loads the plist and installs the awake
+agent (detail: `details.md`). `scheduled: false` with probe problems means
 nothing was loaded; say so with the problems. Exit 1 with `launchd refused`
 means launchd refused the job: say so, with its path, and say the Mac may sleep
 between ticks until it is fixed. "Configure only" is `--configure-only`, which
@@ -226,21 +160,16 @@ saves the selection and installs neither.
 
 ### 9. Report what is now true
 
-Say all five, because each one is something a user has asked about after the
-fact: which repos and which labels; that it survives a restart with no command to
-run (launchd loads at **login** - not boot, and that is correct, because the login
-keychain is what unlocks the tokens, so a run before login could not reach Jira or
-GitHub anyway); that the machine is kept awake for as long as the mode is on (system sleep on AC, idle sleep on battery too) and whether the display is kept on; the slot count
+Say all five: which repos and which labels; that it survives a restart with no
+command to run (launchd loads at **login**, not boot); that the machine is kept awake while the mode is on and whether the display is kept on; the slot count
 and the ceiling this machine would allow (`ma_ap_slot_ceiling`); and that
 `/multi-agent:autopilot-off` is the only way to stop it.
 
 ## What this does not do
 
-- **No cap on PRs.** As many items as carry the label become as many PRs. The
-  bounds are `costCeilingUsd` over a rolling 24 hours and what the machine can
-  hold - never a daily count.
+- **No cap on PRs.** Every labelled item becomes a PR; the bounds are
+  `costCeilingUsd` over a rolling 24 hours and machine capacity, never a daily count.
 - **Does not merge.** The runner stops at an open PR; the merge decision stays
   yours.
-- **Does not touch an attended run.** Both are worktrees and per-repo concurrency
-  is 1, so the queue skips a repo you are working in rather than competing for
-  `.git/index.lock`.
+- **Does not touch an attended run.** Per-repo concurrency is 1: the queue skips
+  a repo you are working in.

package/pipeline/commands/multi-agent/channels/SKILL.md

@@ -9,12 +9,9 @@ confirm: none
 allowed-tools: Read, Write, Edit, Bash, Grep, WebFetch, AskUserQuestion
 ---
 
-# /multi-agent channels  -  Multi-Channel Reporter
+# /multi-agent channels - Multi-Channel Reporter
 
-> **TLDR**  -  Single entry point for posting task reports to external channels. Jira, Confluence, Wiki (component-only), PR description. Multi-select channels × content. Phase 5 of the pipeline delegates to this command; users can also invoke it post-hoc by Jira ID / PR URL / branch.
-
-**Claude Code invocation:** `/multi-agent:channels <target>`
-**Copilot CLI invocation:** `multi-agent-channels <target>` (top-level command, dash-separated per Copilot no-namespace convention)
+Single entry point for posting a task report to Jira, Confluence, Wiki (component-only), the PR description and Board status (GitHub Projects v2). Phase 5 delegates here; users also invoke it post-hoc by Jira ID / PR URL / branch. Claude Code: `/multi-agent:channels <target>`; Copilot CLI: `multi-agent-channels <target>`.
 
 ## Gotchas
 
@@ -23,190 +20,64 @@ allowed-tools: Read, Write, Edit, Bash, Grep, WebFetch, AskUserQuestion
 - A Bitbucket PR update must carry the reviewer list back, or the PUT removes every reviewer.
 - With several repos, the PR description goes to every PR but Jira and Confluence get one post each.
 
-## Input
-
-A Jira id or URL, a GitHub or Bitbucket PR URL, a GitHub `#N`, or nothing (cwd + current branch), plus the flags below. Example invocations: `$HOME/.claude/multi-agent-refs/channels/reference.md` "Input forms".
-
 ## Flow
 
-`resolve target → fetch context → menu (or flags) → generator → humanizer → approval → dispatch → summary`. Channels: Jira comment, Confluence page, Wiki pages, PR description, Board status (GitHub Projects v2).
-
-### Step 1  -  Target resolution
-
-1. Parse argument → classify as: Jira-id, Jira-url, PR-url (GitHub or Bitbucket), GitHub-issue-number, empty (cwd+branch).
-2. Resolve linked entities:
-   - Jira ID → linked PR via dev-status API (`/rest/dev-status/latest/issue/detail`)
-   - PR URL → Jira ID extracted from branch name / title / body using `{JIRA_KEY}-XXXXX` pattern
-   - GitHub `#N` → resolved against the repo in cwd
-   - Empty → read git branch, extract Jira ID, find linked PR
-3. Detect remote type: `github` (gh CLI) or `bitbucket` (REST).
-4. Store in runtime state: `{jiraId, targets: [{prUrl, prNumber, remoteType, repoPath, baseBranch, headBranch, repoName, isPrimary}]}`.
-
-**Multi-repo:** when `agent-state.json` `projects[].length > 1`, Step 1 builds **one target per project**. How each target is resolved and which one is primary: `$HOME/.claude/multi-agent-refs/channels/multi-repo.md` "Target resolution (Step 1)", read before Step 1 then. Single-repo tasks have exactly one target.
-
-### Step 2  -  Context source detection
-
-Automatic: pipeline log, PR diff, or a manual message, best available first. Read `$HOME/.claude/multi-agent-refs/channels/menu.md` before Step 2: the source table (when each source is available, which content options it feeds) and the Step 3 menu rules.
-
-If both pipeline log and PR diff exist, the menu offers both. If only one, the unavailable options are greyed out with a one-line reason.
-
-### Step 3  -  Multi-select menu (normal mode)
-
-Rendered in English (`promptLanguage` is locked to `en`). Previous selections (`prefs.global.reportChannels`, `prefs.global.reportContent`) are pre-ticked.
-
-#### Step 3a  -  Work Summary preview (summary-first flow)
-
-**Runs only when** `agent-state.json` exists for the task AND a Work Summary can be generated. It prints the summary BEFORE the channel picker and auto-ticks the workSummary content row in 3b; an explicit `prefs.global.reportContent.workSummary` still wins. Otherwise 3a is skipped silently.
-
-**Autopilot interaction (Step 4):** `state.autopilot === true` still pauses at channels (documented exception to zero-interaction contract), preview in-line. Under `MULTI_AGENT_UNATTENDED=1` it posts nothing: `$HOME/.claude/multi-agent-refs/features/unattended-security.md`.
-
-#### Step 3b  -  Channel + content picker
-
-Two pickers: **Channels** (PR description, Jira comment, Confluence page, Wiki, Board) and **Content**. An unavailable option is greyed with a one-line reason, never hidden. Selections are saved to `prefs.global.reportChannels` and `prefs.global.reportContent` as the next run's defaults.
-
-`channels/menu.md` (read at Step 2) carries the preview snippet, the auto-tick rules, every greyed-out rule with its reason string, and the first-run defaults.
-
-### Step 4  -  Mode short-circuit
-
-Non-interactive in three cases  -  menu skipped entirely, flag values or prefs used directly:
-
-| Mode | Behavior |
-|---|---|
-| `--channels X,Y` + `--content A,B` flags | Exact flag values, no menu. |
-| `autopilot` (Phase 5 delegate) | Reads `prefs.global.reportChannels` + `prefs.global.reportContent`  -  per Phase 5 autopilot-pause contract, Phase 5 STILL pauses before calling channels but pre-fills menu from prefs. Post-hoc `/channels` in autopilot mode uses prefs directly. |
-| `--dry-run` | Runs menu, generates output, prints to stdout, DOES NOT post. |
-
-### Step 5  -  Generator
-
-For each selected **content** source, produce one section body. Each section runs through the `humanizer` skill separately (Jira / Confluence / PR tones differ).
-
-**The Jira body is not the PR body.** Jira is read by the person who filed the
-ticket and by whoever tests it, so its comment carries the four sections
-`channels/jira.md` fixes - `summary` (`Geliştirme Özeti`), `test_scenarios`
-(`Test Senaryoları`), `impact` (`Etki Analizi`) and `context_refs`
-(`Bağlantılar`), plus `test_run` when selected - and nothing else. Technical sections go to the PR and to
-Confluence, where the reader is a code reviewer. When `jira` is a selected channel, drop
-the technical sections from its body rather than converting them: the PR link on
-line 1 is how a Jira reader reaches the detail.
+`resolve target -> fetch context -> menu (or flags) -> generator -> humanizer -> approval -> dispatch -> summary`. Before Step 1, read `$HOME/.claude/multi-agent-refs/channels/reference.md`: input forms, flags, the Step 1 resolution detail, the Step 4 mode table, error handling and the Phase 5 delegation contract.
 
-`impact` is not a technical section in disguise. It answers four questions -
-what was wrong, what was changed, which areas must be tested, what else is
-affected - in the same plain register as the summary, and it is the part a test
-lead reads before deciding how wide to test.
+### Step 1 - Target resolution
 
-Read `$HOME/.claude/multi-agent-refs/channels/generator.md` before generating any section: the content-option table (which section each option produces, from which source), the aggregated output template, store-compliance auto-augmentation from cached `archiveguard-*.json` / `play-compliance-*.json` reports, and the work-summary (`render-work-summary.sh`) and cost-summary (`render-cost-summary.sh`) generators with their precision rules.
+Classify the argument (Jira id / url, GitHub or Bitbucket PR URL, `#N`, empty = cwd + branch), resolve the linked Jira / PR, detect `github` or `bitbucket`, store `{jiraId, targets[]}`. Multi-repo (`projects[].length > 1`): one target per project, per `$HOME/.claude/multi-agent-refs/channels/multi-repo.md`. A Phase 5 call passes a state bundle and skips Step 1.
 
-**The content options are sources, not the body's shape.** Which sections a PR
-body carries and in what order is fixed by `channels/pr.md` (`summary` →
-`technical` → `architecture` → `impact` → `test_scenarios` → `test_run` → `visuals` → `risk`
-→ `dependencies` → `build` → `related`); the content options choose what gets
-gathered to fill them. A content option left unselected means a section has no
-source, not that the section may be reordered or renamed.
+### Step 2 - Context source detection
 
-**Target length rule:** full body fits one screen on a typical laptop (< 80 lines). Auto-diff summary capped at 5 lines per section. No framework-theory paragraphs, no numbered "why this approach" lists.
+Pipeline log, PR diff, or a manual message, best first. Read `$HOME/.claude/multi-agent-refs/channels/menu.md` before Step 2: the source table and the Step 3 menu rules.
 
-### Step 6  -  Body preview + approval gate (interactive modes)
+### Step 3 - Multi-select menu
 
-Plan-mode-style gate: the user sees exactly what will be posted BEFORE any external write. Runs after the generator + humanizer, before Step 7 dispatch, in every interactive invocation  -  menu mode AND `--channels`/`--content` flag mode alike (flags pick the targets, they do not waive the content approval).
+Step 3a prints the Work Summary first (summary-first flow) when `agent-state.json` exists, and auto-ticks that content row; an explicit pref wins. Step 3b: **Channels** (PR description, Jira comment, Confluence page, Wiki, Board) and **Content**; an unavailable option is greyed with a reason, never hidden. Selections pre-tick from and save to `prefs.global.reportChannels` / `prefs.global.reportContent`. Autopilot still pauses here; unattended posts nothing (`$HOME/.claude/multi-agent-refs/features/unattended-security.md`).
 
-Skipped in exactly two cases:
+### Step 4 - Mode short-circuit
 
-| Case | Why |
-|---|---|
-| Autopilot (`state.autopilot === true` or `MULTI_AGENT_AUTOPILOT=1`), attended | Explicit consent for side-effect creation: posts directly with prefs/flag selections |
-| `--dry-run` | Prints without posting |
+`--channels` + `--content` flags, autopilot (prefs), and `--dry-run` skip or shortcut the menu (table in `reference.md`).
 
-**Preview render** (one block per selected channel, final body after humanizer  -  shown in readable Markdown, channel-specific markup conversion happens after approval).
+### Step 5 - Generator
 
-PR description and GitHub issue comment are posted as Markdown verbatim; Jira comment and Confluence page are converted after approval. Read `$HOME/.claude/multi-agent-refs/channels/preview.md` before rendering the preview: the per-channel conversion table, the preview block layout and the secondary-artifact intents that ride along at its bottom.
+One section body per selected content source, each run through the `humanizer` skill per channel. Read `$HOME/.claude/multi-agent-refs/channels/generator.md` before generating: the content options, the template, store compliance, work and cost summaries, and the Jira-versus-PR rule.
 
-**Then a single AskUserQuestion** (`picker-contract.md`; `question`/`label`/`description` in `outputLanguage`, `header` English):
+- **The Jira body is not the PR body.** Jira gets only `Geliştirme Özeti`, `Test Senaryoları`, `Etki Analizi` and `Bağlantılar` (plus the test run when selected); technical sections are dropped from it, never converted, and go to the PR and Confluence.
+- PR section order is fixed by `channels/pr.md`; content options are sources, not the shape.
+- Target length: under 80 lines; auto-diff capped at 5 lines per section.
 
-| Option | Behavior |
-|---|---|
-| `Approve & post` | Step 7 dispatches every previewed body verbatim |
-| `Edit` | Free-text "which channel, what should change" → apply → re-render the FULL preview → re-ask (loop, no cap) |
-| `Skip channels` | multiSelect which channels to drop this run → re-render remaining → re-ask |
-| `Cancel` | Abort dispatch entirely  -  nothing posted anywhere. Internal capture (agent-log, knowledge) is unaffected |
+### Step 6  -  Body preview + approval gate
 
-**Hard rule:** what is posted is byte-identical to the approved preview (markup conversion excepted). Any body regeneration after approval invalidates the approval and re-runs the gate. Persisting channel prefs (Step 8) still happens on `Cancel`  -  selection memory and content approval are independent.
+Every interactive run, menu mode and flag mode alike, shows the final bodies before any external write. Skipped in exactly two cases: autopilot (`state.autopilot === true` or `MULTI_AGENT_AUTOPILOT=1`, attended) and `--dry-run` (prints without posting). Read `$HOME/.claude/multi-agent-refs/channels/preview.md` before rendering: conversion table, block layout, option table.
 
-### Step 7  -  Channel dispatch
+One `AskUserQuestion` (`picker-contract.md`; `question` / `label` / `description` in `outputLanguage`, `header` English): `Approve & post` / `Edit` (loop) / `Skip channels` / `Cancel` (nothing posted).
 
-For each selected **channel**, call the corresponding adapter. Adapters run **in parallel**  -  one failure does not block others. Dispatch NEVER starts before the Step 6 gate resolves (`Approve & post`), except in the two documented skip cases (autopilot, `--dry-run`).
+**Hard rule:** what is posted is byte-identical to the approved preview (markup conversion excepted). Any regeneration after approval invalidates the approval and re-runs the gate.
 
-**Multi-repo dispatch** (`state.projects[].length > 1`): which channel posts once and which per repo, and the `channels-multi-repo.sh` calls: `$HOME/.claude/multi-agent-refs/channels/multi-repo.md`.
+### Step 7 - Channel dispatch
 
-#### Adapter: PR description
-Aggregated Markdown from Step 5 → PR description. GitHub uses `gh pr edit --body-file`; Bitbucket uses a **reviewer-preserving (required)** `PUT /pull-requests/{id}` payload (must re-send `reviewers`, `fromRef`, `toRef`, `draft`, `version`  -  omitting any one resets that field server-side). Default is **replace**; `--append` opt-in. Multi-repo cross-links handled by `channels-multi-repo.sh render-pr`.
+Adapters run in parallel; one failure does not block the others. Dispatch NEVER starts before the Step 6 gate resolves, except autopilot and `--dry-run`. Multi-repo: `channels/multi-repo.md`.
 
-Full contract: [`$HOME/.claude/multi-agent-refs/channels/pr.md`]($HOME/.claude/multi-agent-refs/channels/pr.md)  -  Bitbucket payload assembly snippet, version-mismatch retry, `--ready` promotion, multi-repo cross-link block.
+- **PR description**: GitHub `gh pr edit --body-file`; Bitbucket a reviewer-preserving `PUT` that re-sends `reviewers`, `fromRef`, `toRef`, `draft`, `version`. Replace by default, `--append` opt-in. Contract: `$HOME/.claude/multi-agent-refs/channels/pr.md`.
+- **Jira comment**: PR URL on line 1, then the four sections. Post with `bash "$HOME/.claude/lib/jira-publish.sh" --issue "$JIRA_ID" --body-file "$F" --target comment` (escapes the body, token never on argv). Contract: `$HOME/.claude/multi-agent-refs/channels/jira.md`. Issue family (`state.jiraFamily`): `jira-family-write.sh plan`, preview, `apply`, per `$HOME/.claude/multi-agent-refs/features/jira-family.md`.
+- **Confluence page**: `$HOME/.claude/multi-agent-refs/channels/confluence.md`.
+- **Board**: `$HOME/.claude/multi-agent-refs/channels/board.md`.
+- **Wiki**: only when `taskType === "component"` and `wiki.enabled`, otherwise the Case B menu from `$HOME/.claude/multi-agent-refs/wiki-capture.md`; once wiki pages are written, the Wiki-to-Jira comment needs `prefs.global.wikiToJiraComment`. Contract: `$HOME/.claude/multi-agent-refs/channels/wiki.md`.
 
-#### Adapter: Jira comment
-Sections: `summary` + `test_scenarios` + `impact` + `context_refs` only - the technical ones go to the PR and Confluence (`channels/jira.md` fixes the order). The PR URL goes on line 1, above the first heading. The wiki-markup conversion table lives in that same ref and only there.
+### Step 8 - Summary
 
-Then post it - do not assemble the request:
-
-```bash
-bash "$HOME/.claude/lib/jira-publish.sh" --issue "$JIRA_ID" --body-file "$F" --target comment
-```
-
-The publisher escapes every body (emoticon sequences, see Gotchas) and resolves the token from `keychainMapping.jira` without putting it on argv.
-
-Full contract: [`$HOME/.claude/multi-agent-refs/channels/jira.md`]($HOME/.claude/multi-agent-refs/channels/jira.md)  -  full conversion table, multi-repo PR-list prepend, Wiki→Jira triad interaction.
-
-**Issue family** (`state.jiraFamily` set): instead, `bash $HOME/.claude/lib/jira-family-write.sh plan --state "$STATE_FILE" --dev-body "$F"`, the Step 6 preview as one multi-select under `plan.confirm`, then `apply --state "$STATE_FILE"`: `$HOME/.claude/multi-agent-refs/features/jira-family.md`.
-
-#### Adapter: Confluence page
-Token from `keychainMapping.confluence`; missing/expired triggers the inline Save Flow from `setup.md`. Parent page from `prefs.projects[<project>].confluenceUrls` recents or a pasted URL, then storage-format conversion and POST; URL saved back to recents.
-
-Full contract: [`$HOME/.claude/multi-agent-refs/channels/confluence.md`]($HOME/.claude/multi-agent-refs/channels/confluence.md)  -  URL parsing rules, full storage-XML conversion table, update-vs-create branch.
-
-#### Adapter: Board (GitHub Projects v2 status move)
-
-Precondition, token, item lookup, mutation and idempotency: `$HOME/.claude/multi-agent-refs/channels/board.md`.
-
-#### Adapter: Wiki
-**Precondition gate:** `state.taskType === "component"` AND `figmaConfig.wiki.enabled === true`. If not met, shows the Case B menu from `$HOME/.claude/multi-agent-refs/wiki-capture.md` (setup / skip / disable / manual-note).
-
-**If preconditions met (Case A):** scope multi-select, then dispatch to the plugin skill `ai-ios-toolkit:figma-component-wiki` (or `ai-android-toolkit:figma-component-wiki`). When wiki pages are written AND `state.jiraId` is set AND `prefs.global.wikiToJiraComment === true`, the Wiki-to-Jira comment auto-link posts an additional Jira comment, independent of the main Jira channel's comment.
-
-Full contract: [`$HOME/.claude/multi-agent-refs/channels/wiki.md`]($HOME/.claude/multi-agent-refs/channels/wiki.md)  -  all four `figma-config.wiki.mode` adapters (submodule / in-repo / github-wiki / separate-repo), full Case A scope menu, screenshot quadrant gate.
-
-### Step 8  -  Summary
-
-After all adapters complete (or fail non-blocking), print one line per channel: status symbol (`✓` / `✗` / `-`), key metric, URL where applicable. Format example: `$HOME/.claude/multi-agent-refs/channels/reference.md` "Step 8 summary format".
-
-Persist selections to `prefs.global.reportChannels` + `prefs.global.reportContent` for next run default.
-
-## Flags
-
-`--channels`, `--content`, `--flow-run`, `--message`, `--message-file`, `--append`, `--dry-run`, `--lang`, `--ready`. What each one does: `$HOME/.claude/multi-agent-refs/channels/reference.md` "Flags", read before Step 1 whenever a flag is present.
+One line per channel (status, metric, URL), format in `reference.md`; persist the selections to prefs.
 
 ## Required rules
 
-- **Bitbucket reviewer preservation**  -  every PR PUT MUST carry current `reviewers`, `fromRef`, `toRef`, `draft`. Omitting any resets that field server-side.
-- **Default is replace, not append** for PR description. `--append` opt-in.
-- **Real newlines + no HTML entities** in ALL bodies (Jira, Confluence, PR): heredoc + `jq --rawfile` + `curl --data-binary @file`. Never embed `\n` literally  -  Jira/Bitbucket save verbatim.
-- **Humanizer per-channel**  -  each channel body runs humanizer independently. Tones differ (Jira informal, Confluence formal, PR technical).
-- **No markers**  -  channels does a full replace each run; no `<!-- channels:start -->` bookmarks.
-- **Every body item references a symbol/file/line** from diff or pipeline log. No generic "tested the feature" sentences.
-- **Adapter failures are non-blocking**  -  one channel failing does not abort others. Final summary shows per-adapter status.
-- **Approval before post**  -  interactive runs never write to an external channel without the Step 6 preview + approval. Autopilot and `--dry-run` are the only bypasses.
-
-## Error handling
-
-Read `$HOME/.claude/multi-agent-refs/channels/reference.md` before Step 1: the condition-by-condition behaviour table (no target, PR missing or merged, bot author, oversized diff, forced unavailable content, Bitbucket version mismatch, missing token, Wiki preconditions). Cross-CLI parity notes and worked examples live in the same file.
-
-## Phase 5 delegation contract
-
-Phase 5 invokes this command internally instead of running its own inline Jira/Confluence/Wiki logic. Responsibilities split:
-
-| Who | What |
-|---|---|
-| Phase 5 | Progress tracker (sub-steps 1-3), agent-log finalization (step 4), knowledge+memory capture (step 5), telemetry emission |
-| `channels` | All external delivery: PR description update, Jira comment, Confluence page, Wiki pages |
-
-Phase 5 passes a runtime state bundle: `{jiraId, prUrl, remoteType, taskType, figmaConfig, agentState, pipelineLogPath, flowRuns}`. `channels` reads these directly, skips target-resolution Step 1.
-
-**Autopilot contract:** Phase 5 ALWAYS pauses at the channels menu (breaks generic autopilot zero-interaction). 30-min timeout → session ends cleanly, task resumable via `/multi-agent:resume`. See `$HOME/.claude/multi-agent-refs/phases/modes.md` for full contract. The Step 6 body preview + approval gate follows the same split: interactive runs approve the composed bodies before dispatch; autopilot posts directly after the menu resolves.
+- **Bitbucket reviewer preservation**: every PR PUT carries current `reviewers`, `fromRef`, `toRef`, `draft`.
+- **Replace, not append**, for the PR description unless `--append`.
+- **Real newlines, no HTML entities** in every body: heredoc + `jq --rawfile` + `curl --data-binary @file`; never a literal `\n`.
+- **Humanizer per channel**; tones differ.
+- **No markers**: a full replace each run, no `<!-- channels:start -->` bookmarks.
+- **Every body item cites a symbol / file / line** from the diff or log.
+- **Adapter failures are non-blocking**.
+- **Approval before post**: autopilot and `--dry-run` are the only bypasses.
+- **Phase 5 autopilot** always pauses at the menu; a 30-min timeout ends the session cleanly, resumable via `/multi-agent:resume`.