@mmerterden/multi-agent-pipeline 20.30.0 → 20.34.0

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

@@ -41,10 +41,11 @@ Branch-mode runs print to chat only. PR-mode runs print to chat AND post the ver
 : "${TASK_ID:=review-$(date +%s)-$$}"
 export TASK_ID
 
-# Clean up scratch files on exit so /tmp doesn't accumulate diffs and SHAs.
 trap 'rm -f /tmp/multi-agent-review-${TASK_ID}-*' EXIT
 ```
 
+Standalone only (a `review-` id): register a tracker record per `$HOME/.claude/multi-agent-refs/review-standalone-tracker.md`.
+
 ### 1. Parse the input  -  pick a resolution path
 
 ```bash
@@ -76,77 +77,11 @@ When `provider=github` and the diff is fetched in Step 2, also persist `agent-st
 
 Reached when `kind=pick` (empty input). Skipped entirely in autopilot: autopilot with no ref goes straight to branch mode (`kind=branch; provider=local; ref=$(git rev-parse --abbrev-ref HEAD)`) so nothing prompts.
 
-**List open PRs across both providers** (a provider contributes nothing if its token/CLI is absent - never hard-fail on one provider):
-
-```bash
-# GitHub: current repo's open PRs + the user's own/requested open PRs across repos.
-gh pr list --state open --json number,title,url,headRefName,author,updatedAt 2>/dev/null   # current repo
-gh search prs --state open --review-requested=@me --json number,title,url,repository,updatedAt 2>/dev/null
-gh search prs --state open --author=@me           --json number,title,url,repository,updatedAt 2>/dev/null
-
-# Bitbucket Server: for each configured bitbucket repo (prefs recentRepos / dev-context),
-# resolve creds via credential-store (see Step 2 bitbucket block) then:
-#   GET https://$host/rest/api/1.0/projects/$KEY/repos/$slug/pull-requests?state=OPEN&role=REVIEWER
-```
-
-Merge into one deduped list, each row labeled with its provider and PR URL; sort by `updatedAt` desc. If the merged list is EMPTY -> tell the user "no open PRs found", fall back to branch mode, and continue.
-
-**Select** - follow `$HOME/.claude/multi-agent-refs/picker-contract.md` (breadcrumb narrator line before the prompt), then `AskUserQuestion` `multiSelect: true`:
-
-```
-question (outputLanguage): "Hangi PR('lar)ı review edeyim?"
-header   (English):        "Review PRs"
-options: one per open PR -> label "#<N> <short title>", description (outputLanguage): "<repo> · <provider> · <headRef>"
-```
-
-Each selected option maps back to a full `agent-state.review.input` descriptor (provider + orgRepo / bb coordinates + prNumber + raw URL), exactly as Step 1 would have parsed an explicit URL. Then **loop Steps 2-7 once per selected PR** (independent review + post each). If the user selects none, fall back to branch mode.
+List open PRs from both providers (a provider whose token or CLI is absent contributes nothing - never hard-fail on one provider), merge, dedupe and sort by `updatedAt` desc; an empty list falls back to branch mode. Ask with `AskUserQuestion` `multiSelect: true` per `$HOME/.claude/multi-agent-refs/picker-contract.md`, then **loop Steps 2-7 once per selected PR**; selecting none falls back to branch mode. Read `$HOME/.claude/multi-agent-refs/review/inputs.md` before Step 1a: the list commands, the picker fields and the descriptor mapping.
 
 ### 2. Fetch the diff  -  kind-aware
 
-**branch mode:**
-
-```bash
-git diff origin/develop...{ref}
-```
-
-**pr mode  -  github:**
-
-```bash
-gh pr diff "$pr_number" --repo "$org_repo" > /tmp/multi-agent-review-${TASK_ID}-diff.patch
-# Also capture the head commit SHA for GitHub inline-comment anchors
-# (POST .../pulls/{n}/comments requires commit_id):
-HEAD_SHA=$(gh api "/repos/$org_repo/pulls/$pr_number" --jq .head.sha)
-printf '%s\n' "$HEAD_SHA" > /tmp/multi-agent-review-${TASK_ID}-head.sha
-# Persist into agent-state  -  post-pr-review.sh reads it from there.
-tmp_state=$(mktemp)
-jq --arg sha "$HEAD_SHA" '.review.headCommitSha = $sha' "$AGENT_STATE" > "$tmp_state" \
-  && mv "$tmp_state" "$AGENT_STATE"
-```
-
-**pr mode  -  bitbucket-server:**
-
-```bash
-# Resolve credentials via prefs.global.keychainMapping (never hardcode key names).
-. "$HOME/.claude/lib/credential-store-resolver.sh" \
-  || . "$HOME/.copilot/lib/credential-store-resolver.sh"
-resolve_credential_store
-USER_KEY=$(jq -r '.global.keychainMapping.bitbucket_user' "$HOME/.claude/multi-agent-preferences.json")
-TOKEN_KEY=$(jq -r '.global.keychainMapping.bitbucket_token' "$HOME/.claude/multi-agent-preferences.json")
-BB_USER=$("$CRED_STORE" get "$USER_KEY")
-BB_TOKEN=$("$CRED_STORE" get "$TOKEN_KEY")
-
-DIFF_FILE="/tmp/multi-agent-review-${TASK_ID}-diff.patch"
-http=$(curl -sS -m 60 --config <(printf 'user = "%s:%s"\n' "$BB_USER" "$BB_TOKEN") -H "Accept: text/plain" \
-  "https://$bb_server_host/rest/api/1.0/projects/$bb_project_key/repos/$bb_repo_slug/pull-requests/$pr_number/diff?contextLines=10" \
-  -o "$DIFF_FILE" -w '%{http_code}')
-if [ "$http" != "200" ]; then
-  echo "review: Bitbucket diff fetch failed (HTTP $http)  -  error body in $DIFF_FILE" >&2
-  rm -f "$DIFF_FILE"
-  exit 1
-fi
-```
-
-The `credential-store.sh` wrapper reads the macOS Keychain (`security`).
+Branch mode: `git diff origin/develop...{ref}`. PR mode fetches through the provider: `gh pr diff` for `github`, which also persists `agent-state.review.headCommitSha`; the Bitbucket Server REST diff endpoint for `bitbucket-server`, with credentials resolved through `prefs.global.keychainMapping` (never hardcoded key names) and any non-200 response a hard failure. Read `$HOME/.claude/multi-agent-refs/review/inputs.md` "Step 2" before fetching: the exact commands per provider.
 
 Save the diff to `/tmp/multi-agent-review-${TASK_ID}-diff.patch` so reviewers can re-read it.
 
@@ -154,27 +89,7 @@ Save the diff to `/tmp/multi-agent-review-${TASK_ID}-diff.patch` so reviewers ca
 
 A module in the repo may carry its own CLAUDE guide  -  a convention/checklist file living somewhere in the module's directory tree that the host CLI never auto-loads. When a changed file's module has such a guide, the review must consult it. Discovery is deterministic, from the diff's changed paths:
 
-```bash
-# Changed file paths from the patch:
-grep -E '^\+\+\+ b/' "$DIFF_FILE" | sed 's|^+++ b/||' | sort -u > /tmp/multi-agent-review-${TASK_ID}-paths.txt
-
-# For each changed path, walk its directory chain up to the repo root and
-# collect guide files matching: CLAUDE.md, *-CLAUDE.md, AGENTS.md.
-# Root-level CLAUDE.md/AGENTS.md are excluded  -  the host CLI already loads those.
-guides=()
-while IFS= read -r p; do
-  d=$(dirname "$p")
-  while [ "$d" != "." ] && [ "$d" != "/" ]; do
-    for g in "$d"/CLAUDE.md "$d"/*-CLAUDE.md "$d"/AGENTS.md; do
-      [ -e "$g" ] && guides+=("$g")
-    done
-    d=$(dirname "$d")
-  done
-done < /tmp/multi-agent-review-${TASK_ID}-paths.txt
-# dedupe, cap at 5 (log any dropped so truncation is never silent)
-```
-
-Existence checks are resolved against the local checkout when the cwd is the target repo. In PR mode without a local checkout, probe the candidate paths via the provider API instead (`gh api /repos/{o}/{r}/contents/{path}?ref={headSha}` / Bitbucket `GET /projects/{KEY}/repos/{slug}/browse/{path}?at={headSha}`) and fetch the matching files' raw content the same way. No hit → step is a silent no-op.
+Read `$HOME/.claude/multi-agent-refs/review/module-guides.md` before Step 2b: the discovery walk (guide file names, the root-level exclusion, the cap of 5 with dropped guides logged) and the provider-API probe for PR mode without a local checkout. No hit: the step is a silent no-op.
 
 Persist `agent-state.review.moduleGuides = [<repo-relative paths>]` and inject into every reviewer prompt (Step 3):
 
@@ -186,44 +101,10 @@ Scope note: a guide governs only files under its own directory  -  a guide found
 
 The `valven-rules` registry (`ai-common-toolkit`) is applied to every review, in `review` mode. Collect what the gate needs, then run it:
 
-```bash
-VG_FILE="/tmp/multi-agent-review-${TASK_ID}-valven.json"
-VG_ARGS=(--mode review --out "$VG_FILE")
-case "$kind/$provider" in
-  branch/local)
-    VG_ARGS+=(--repo . --base origin/develop --head "$ref") ;;
-  pr/github)
-    node "$HOME/.claude/scripts/pr-timeline.mjs" --repo "$org_repo" --pr "$pr_number" \
-      --out "/tmp/multi-agent-review-${TASK_ID}-pr.json"   # gh pr view + ready time + bot-typed reviews
-    jq -r '.body // ""' "/tmp/multi-agent-review-${TASK_ID}-pr.json" > "/tmp/multi-agent-review-${TASK_ID}-body.md"
-    jq -r '.commits[] | "\(.authoredDate)\t\(.messageHeadline)"' "/tmp/multi-agent-review-${TASK_ID}-pr.json" > "/tmp/multi-agent-review-${TASK_ID}-commits.txt"
-    VG_ARGS+=(--branch "$(jq -r .headRefName "/tmp/multi-agent-review-${TASK_ID}-pr.json")"
-              --pr-body-file "/tmp/multi-agent-review-${TASK_ID}-body.md"
-              --commits-file "/tmp/multi-agent-review-${TASK_ID}-commits.txt"
-              --pr-meta-file "/tmp/multi-agent-review-${TASK_ID}-pr.json") ;;
-  pr/bitbucket-server)
-    # Same credentials as Step 2. PR: fromRef.displayId + description; commits: values[].message.
-    # Write the description to ...-body.md, one "<ISO authorTimestamp>\t<first message line>" per commit to ...-commits.txt,
-    # and the timeline to ...-meta.json (features/valven.md, "Development Behaviors"). Then:
-    VG_ARGS+=(--branch "$BB_FROM_REF" --pr-body-file "/tmp/multi-agent-review-${TASK_ID}-body.md"
-              --commits-file "/tmp/multi-agent-review-${TASK_ID}-commits.txt"
-              --pr-meta-file "/tmp/multi-agent-review-${TASK_ID}-meta.json") ;;
-esac
-```
-
-For PR input: when the cwd is a checkout of the same repo, `git fetch origin "<headRef>"` (this moves no HEAD) and add `--repo . --base "origin/<baseRef>" --head FETCH_HEAD`, so sizes and the rework ratio come from history. Otherwise add `--diff-file "$DIFF_FILE"`; the rework rule then reports `not-measured`, which is stated in the summary rather than read as a pass.
-
-```bash
-node "$HOME/.claude/scripts/valven-gate.mjs" "${VG_ARGS[@]}" >/dev/null
-VG_RC=$?   # 0 clean, 1 findings, 2 could not run
-```
+Read `$HOME/.claude/multi-agent-refs/review/valven.md` before Step 2c: the per-input gate arguments, the checkout-vs-diff-file choice, and the handling of the split, old-work, judgement (`VLV-SCOPE-02`, `VLV-PRDESC-02`, injected into every Step 3 reviewer prompt), cycle and pickup rules. Two rules hold on every input:
 
 - Exit 2: print the stderr line and continue the review with `Valven: not measured (<reason>)` in the Step 6 summary. Never print it as passed.
 - The gate's `findings[]` join the reviewer findings at Step 5 with `tag: valven`. They are measurements, so triage accepts them unless the task is exempt; an accepted `important` or `blocking` one makes the Step 7 decision NEEDS WORK.
-- When `splitRequired` is true, run `node "$HOME/.claude/scripts/valven-split.mjs" --repo . --base "origin/<baseRef>" --head <head>` (plan only, no `--apply`) where a checkout exists, and append the slice table (branch, lines, files) to the `VLV-SIZE-01` finding's `fix`.
-- When `VLV-AGE-01`, `VLV-BEHIND-01` or `VLV-TRACE-03` fires and a checkout exists, put the `valven-port.mjs` plan (same base and head, no `--apply`) in the finding's `fix` as `$HOME/.claude/multi-agent-refs/features/valven.md`, "Old work", lists it.
-- The registry's judgement rules (`rules:` block: `VLV-SCOPE-02`, `VLV-PRDESC-02`) go into every reviewer prompt in Step 3, with the PR body when one exists. Each reviewer returns a verdict per ID.
-- `VLV-CYCLE-01..03` are `suggestion` findings with a Valven score and never set NEEDS WORK alone; `VLV-PICKUP-01` is `important` for no reviewer, a `suggestion` for an old draft. Branch input reports them `not-measured`.
 
 Step 6 adds one line under the table: `Valven: <n> finding(s)  ·  <changedLines> lines / <fileCount> files  ·  split: <yes N slices|no>`, plus for a PR `Valven scores: churn · coding · pickup · review` from `scores` (`-` when absent).
 
@@ -312,6 +193,8 @@ Classify findings into:
 
 Triage also marks each finding as `accepted` (real issue), `deferred` (real but out of scope), or `rejected` (false positive). Only `accepted` findings appear in the body of the PR comment; `deferred` items go in the Triage notes section.
 
+Triage settles every reviewer `cannotVerify` row the way Phase 3 does (`phase-3-review.md` 3.2): `verified` with the file:line read, `finding` with the file:line of the accepted or deferred finding, or `out-of-scope`. Rows left unsettled are listed in the chat summary and in the Triage notes section.
+
 ### 6. Print the chat summary (always)
 
 ```
@@ -379,19 +262,13 @@ If the post fails (network, token, harness block), `post-pr-review.sh` exits non
 Per the `$HOME/.claude/multi-agent-refs/tracker-contract.md` tokens contract, after each reviewer LLM call:
 
 ```bash
-bash $HOME/.claude/scripts/phase-tracker.sh tokens 4 <input_count> <output_count>
+bash $HOME/.claude/scripts/phase-tracker.sh tokens <N> <input_count> <output_count>
 ```
 
-Standalone `/multi-agent:review` runs use phase id 3 (matches Phase 3 Review in the full pipeline) so cost aggregation stays consistent.
+`<N>`: the run's Review phase, or step 2 for a standalone review.
 
 ## Input matrix
 
-| Input | Mode | PR action |
-|---|---|---|
-| no args (interactive) | PR picker (open GitHub + Bitbucket PRs, multi-select) | inline comments + approve/needs-work, per selected PR |
-| no args (autopilot / no PRs) | branch (current) | none  -  chat only |
-| `feature/foo` | branch (named) | none  -  chat only |
-| `#N`, `repo#N`, GitHub PR URL | pr (github) | inline comments + approve/needs-work |
-| Bitbucket Server PR URL | pr (bitbucket-server) | inline comments + approve/needs-work |
+The input table at the top, by mode and PR action: `$HOME/.claude/multi-agent-refs/review/inputs.md` "Input matrix".
 
 PR-mode body language honors `prefs.global.outputLanguage`. The orchestrator entry point is `lib/post-pr-review.sh "$TASK_ID"`  -  it reads `agent-state.review` and handles diff fetch, finding render, comment posts, and review state end-to-end.

package/pipeline/commands/multi-agent/scenario-audit/SKILL.md

@@ -55,7 +55,9 @@ Read the candidate lines it returns. A term nothing matched is listed under
 
 ## Step 3 - Verdict
 
-Write `/tmp/ma-verdicts.json`: `[{id, status, citations, searched, note}]`.
+Write the verdicts to a file in a folder of this run's own
+(`VERDICTS="$(mktemp -d)/verdicts.json"`, never a fixed `/tmp` name another
+user or a second audit could share): `[{id, status, citations, searched, note}]`.
 
 | Status | When | Needs |
 |---|---|---|
@@ -66,7 +68,7 @@ Write `/tmp/ma-verdicts.json`: `[{id, status, citations, searched, note}]`.
 
 ```bash
 node "$HOME/.claude/scripts/scenario-audit.mjs" verify --csv "<scenarios.csv>" \
-  --verdicts /tmp/ma-verdicts.json --repo "<repo>" --lang "<outputLanguage>"
+  --verdicts "$VERDICTS" --repo "<repo>" --lang "<outputLanguage>"
 ```
 
 ## Step 4 - Report

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

@@ -34,51 +34,13 @@ Uses `$HOME/.claude/lib/credential-store.sh` to read/write secrets in the macOS
 
 Run `~/.claude/lib/credential-store.sh doctor` first  -  it prints the platform and whether the backend is usable.
 
-The shell driver auto-delegates `get`/`set`/`delete` to the deterministic Python helper at `$HOME/.claude/scripts/keychain.py` (Python 3 stdlib only, no external deps). The Python path writes both `-l` (label) and `-s` (service) attributes so items are findable regardless of how callers look them up. Set `KEYCHAIN_DELEGATE=0` to force the raw shell path.
+The shell driver delegates to the Python helper `$HOME/.claude/scripts/keychain.py`; what it writes and the `KEYCHAIN_DELEGATE=0` override: `$HOME/.claude/multi-agent-refs/setup/token-save-flow.md` "Inline Token Save Pattern".
 
 ### Step 0  -  Language Selection
 
-Ask BEFORE anything else, so every subsequent setup prompt and the rest of the pipeline honour the choice. The pipeline has two language axes:
+Ask BEFORE anything else: one question, `outputLanguage` (`en` / `tr`). `promptLanguage` is fixed to `"en"` and never offered to the user. Commits, branch names and agent prompts stay English; PR, Jira and wiki bodies follow `outputLanguage`. Already set in prefs: skip silently. From this point forward `question`, `label` and `description` render in `outputLanguage`; `header` stays English.
 
-| Axis | What it controls | Configurable? |
-|---|---|---|
-| `promptLanguage` | Picker chrome only: the `AskUserQuestion` `header` chip, host error UI, internal contract identifiers | **No  -  fixed to `en`.** The chip is capped at 12 chars, which most Turkish equivalents overflow. |
-| `outputLanguage` | The assistant's non-interactive explanations, status updates, error messages, and pipeline-generated reports rendered to the user | Yes  -  set here and changeable later via `/multi-agent:language <en\|tr>` |
-
-`promptLanguage` is seeded as `"en"` and never offered to the user. **External payloads always stay English** (commits, PR titles/bodies, Jira comments, wiki content, reviewer/triage prompts, agent-log.md).
-
-#### Step 0 prompt  -  `outputLanguage`
-
-The setup wizard asks one question (English UI per skill-prompt rules):
-
-```
-Which language should the assistant use for ITS OWN explanations,
-status updates, and pipeline-generated reports?
-
-  1) English
-  2) Türkçe
-
-Select (1-2):
-```
-
-**Rules:**
-
-- **Already set in prefs** → skip silently. User can change later with `/multi-agent:language <en|tr>` or `/multi-agent:language output <en|tr>`.
-- **New value** → validate against the schema enum (`en`, `tr`), write `prefs.global.outputLanguage` via atomic rename, force `prefs.global.promptLanguage = "en"`, then echo a confirmation in the just-chosen `outputLanguage`:
-  - `en`: `outputLanguage=<Y>. promptLanguage stays "en". External payloads (PR bodies, Jira comments, reviewer prompts) stay English regardless.`
-  - `tr`: `outputLanguage=<Y>. promptLanguage "en" sabit. Dış çıktılar (PR açıklamaları, Jira yorumları, review istemleri) her durumda İngilizce kalır.`
-- **Unknown input** → re-ask once, then abort setup with a hint pointing to `/multi-agent:language`.
-
-From this point forward, every prompt in Steps 1-6 below follows the canonical
-per-field matrix in `$HOME/.claude/multi-agent-refs/rules.md` ("Language Application"):
-`question`, `label` and `description` render in `outputLanguage`; `header` stays
-English. Wizard status and the post-setup summary follow `outputLanguage`. External
-payloads remain English.
-
-> `promptLanguage` governs only the button and chip chrome, never the question a
-> user reads. Rendering a whole prompt in English "per the fixed
-> `promptLanguage`" contradicts the matrix above and produces half-English
-> pickers on Turkish runs.
+Read `$HOME/.claude/multi-agent-refs/setup/language.md` before Step 0: the two language axes, the exact prompt, validation, the confirmation lines and the unknown-input rule.
 
 ### Step 0.5  -  Dependency check
 
@@ -104,22 +66,7 @@ Full procedure: `$HOME/.claude/multi-agent-refs/setup/discovery.md`. Read it for
 
 ### Step 2  -  Show Discovery Summary + Save Mapping
 
-Show results grouped by status:
-
-```
-Keychain Token Discovery (${USER}):
-
-  Jira               -> ${USER}_Jira_Access_Token
-  GitHub             -> ${USER}_Github
-  Figma              -> ${USER}_Figma_Access_Token
-  Firebase           -> ${USER}_Firebase_Access_Json
-  Confluence         -> MISSING
-  Jenkins            -> MISSING
-  ---
-  Git identities: check preferences file (see Step 3)
-
-  Mapped: 8 | Missing: 4
-```
+Show results grouped by status: one line per service with its mapped key or `MISSING`, then the mapped / missing counts. Layout: `$HOME/.claude/multi-agent-refs/setup/summaries.md` "Step 2 discovery summary".
 
 Non-standard key names are perfectly valid  -  the mapping handles resolution. No rename or migration is offered.
 
@@ -169,31 +116,11 @@ never runs update still reports. What is sent, what never is, and
 
 ### Auto-learned fields (no setup step needed)
 
-**Jira Project Key**: auto-learned from pipeline usage. User runs `/multi-agent ABC-123` → `ABC` is extracted and saved to `prefs.global.defaultJiraKey` (first ever) and `prefs.projects[{project}].jiraProjectKeys` (per-project). Multiple keys accumulate over time  -  most recent first, deduped. Phase 0 Step 1 (Parse Input) handles extraction.
-
-**Git Identity**: auto-learned from token onboarding. Each token saved in Step 3 triggers an identity prompt (see Token Save Flow Step C). No separate identity setup step.
+The Jira project key and the git identity are learned from use, never asked here. How each is captured: `$HOME/.claude/multi-agent-refs/setup/accounts.md` "Auto-learned fields".
 
 ### Step 3  -  Interactive token onboarding (for missing tokens)
 
-Git identities are NOT asked as a separate step. They are learned when tokens are added via the Token Save Flow below. Each token save triggers an identity prompt:
-
-```
-Token saved. Which git identity uses this token?
-
-  Existing identities:
-    1. Ada Lovelace <ada@example.com>
-    2. Ada Lovelace <ada@personal.com>
-    n. Create new identity
-
-  Select:
-```
-
-- First token ever → no existing identities → asks name + email → creates identity → maps token
-- Subsequent tokens → pick existing or create new → maps token to that identity's `servicePatMap`
-- Multiple accounts per platform supported (e.g. two GitHub tokens, each mapped to a different identity)
-- Identity is stored in `prefs.global.identities[]`, token-to-identity binding in `identity.servicePatMap`
-
-**Legacy compatibility**: If `prefs.global.gitIdentities` (deprecated) is present, `migrate-prefs.mjs` renames it to `identities` automatically.
+Git identities are NOT asked as a separate step. They are learned when tokens are added via the Token Save Flow: each token save triggers an identity prompt (Step C), the identity is stored in `prefs.global.identities[]` and the token binding in `identity.servicePatMap`. Multiple accounts per platform are supported. The prompt, the binding rules and the legacy `gitIdentities` migration: `$HOME/.claude/multi-agent-refs/setup/token-save-flow.md` "Identity learning (Step 3)".
 
 For each MISSING service, run the **Token Save Flow** below. When creating new tokens, use the **standard key name** from Step 1b table.
 
@@ -231,15 +158,15 @@ Full procedure: `$HOME/.claude/multi-agent-refs/setup/token-save-flow.md`. Read
 
 ### Step 3b  -  App Store Connect onboarding (iOS only, optional)
 
-Runs inside Step 3. Every part of the API key lives in the Keychain, the `.p8` included: ask for the `.p8` as a path, validate it BEFORE saving with `node "$HOME/.claude/scripts/probe-store-key.mjs" --asc ...` (exit 0 only), map `appstore_connect_private_key`, store it from the file with `credential-store.sh set appstore_connect_private_key - < <AuthKey_<keyId>.p8>`, run `node "$HOME/.claude/scripts/write-store-config.mjs"`, then offer (picker, default keep) to delete the file. `store_asc_*` and `ios_testflight_validate` then read the key from the Keychain. The five entries, the tier picker and the probes: `$HOME/.claude/multi-agent-refs/setup/app-store-connect.md`. On Skip, nothing is written.
+Runs inside Step 3, iOS target only. Every part of the API key, the `.p8` included, lives in the Keychain, and the key is validated BEFORE it is saved. Read `$HOME/.claude/multi-agent-refs/setup/app-store-connect.md` before Step 3b. On Skip, nothing is written.
 
 ### Step 3c  -  Firebase / Crashlytics onboarding (optional)
 
-Runs inside Step 3. Measure first  -  `bash "$HOME/.claude/lib/fetch-crashlytics.sh" --probe` answers `tier-1-ready` / `tier-1-no-grant` / `malformed` / `unreachable`  -  then ask by that answer, never blind. Store the JSON as issued; never base64 it. Skip writes nothing. Then offer appId discovery: `bash "$HOME/.claude/scripts/firebase-app-discovery.sh" <repo> --json` reads the pairs the repo already carries, for `firebase.accounts[].apps[]`  -  it saves a round trip per run; skipping costs nothing. The picker, both tiers, the role-request wording and the v1alpha caveat: `$HOME/.claude/multi-agent-refs/setup/firebase.md`.
+Runs inside Step 3. Measure first with `bash "$HOME/.claude/lib/fetch-crashlytics.sh" --probe`, then ask by that answer, never blind; store the JSON as issued, never base64 it. Read `$HOME/.claude/multi-agent-refs/setup/firebase.md` before Step 3c. Skip writes nothing.
 
 ### Step 3d  -  Google Play onboarding (Android only, optional)
 
-Runs inside Step 3, only when the target repo is Android. One entry, `google_play`: the service-account JSON the toolkit's `store_play_*` tools use, which lets `/multi-agent:store-ready` run Android Gate 2. Ask for the JSON's path, validate BEFORE saving with `node "$HOME/.claude/scripts/probe-store-key.mjs" --play --service-account <path>`, map `google_play`, then `credential-store.sh set google_play - < <path>` and `write-store-config.mjs`. Account prerequisites, the picker and the probe hints: `$HOME/.claude/multi-agent-refs/setup/google-play.md`. Skip writes nothing.
+Runs inside Step 3, only when the target repo is Android: one entry, `google_play`, validated BEFORE saving. Read `$HOME/.claude/multi-agent-refs/setup/google-play.md` before Step 3d. Skip writes nothing.
 
 ### Step 3.5  -  Host Prompt (embedded in Token Save Flow)
 
@@ -249,44 +176,13 @@ Full procedure: `$HOME/.claude/multi-agent-refs/setup/token-save-flow.md`. Read
 
 **Runs only when** `~/.claude/lib/account-resolver.sh` returns **more than one** account AND at least one account has Jira or Bitbucket tokens.
 
-Use case: a single user with two corporate identities (e.g. agency + client). Each account points at its own Jira host  -  `prefs.global.hosts.jira` can hold only one default, so per-account overrides win for the rest.
-
-For each non-default account, ask once:
-
-```
-Account {label} has Jira/Bitbucket tokens but no host override yet.
-Use the global default ({hosts.jira}) or set a per-account host?
-
-  1) Use global default
-  2) Set per-account host
-```
-
-If `2`, prompt for `jiraHost` / `bitbucketHost` / `confluenceHost` (each optional). Save to `prefs.global.accounts[]` as `{ \"id\": \"client-x\", \"jiraHost\": \"client-x.atlassian.net\", \"bitbucketHost\": \"bitbucket.client-x.com\" }`.
-
-`account-resolver.sh` reads this on every invocation; per-account override wins over `global.hosts.*`. Skip this step on autopilot  -  `accounts[]` stays empty until the user opts in via `/multi-agent:setup accounts`.
+For each non-default account, ask once whether to keep the global default host or set per-account hosts; read `$HOME/.claude/multi-agent-refs/setup/accounts.md` "Per-account host overrides (Step 3.6)" before Step 3.6 for the prompt, the saved `prefs.global.accounts[]` shape and the precedence. Skip this step on autopilot  -  `accounts[]` stays empty until the user opts in via `/multi-agent:setup accounts`.
 
 ---
 
 ### Step 4  -  Verify all
 
-Re-run scan from Step 1. Show final status:
-```
-All tokens present. Pipeline ready to use.
-
-Optional per-project features (configured on first use, nothing to do now):
-  • Phase 5 Report Step 2 Wiki  -  auto-generates component wiki pages + Figma
-    screenshots. Activates when (a) task is a component AND (b) a Figma token
-    is in Keychain. Four adapters supported: submodule / in-repo / github-wiki
-    / separate-repo. First run asks: use auto-detected path, use a custom
-    path, skip once, or disable for this project (persisted).
-  • channels  -  post-hoc multi-channel reporter (Jira/Confluence/Wiki/PR), works on any branch with an open PR.
-  • Default reviewers  -  auto-fetched from Bitbucket default-reviewers endpoint
-    or GitHub CODEOWNERS on first PR.
-
-Next step:
-  /multi-agent "PROJ-12345"              -> start your first task
-  /multi-agent help                      -> full usage guide
-```
+Re-run scan from Step 1 and show the final status: tokens present, the optional per-project features, the next-step commands. Layout: `$HOME/.claude/multi-agent-refs/setup/summaries.md` "Step 4 final status".
 
 If still missing, show which ones and let user skip (pipeline will re-ask for any needed token at Phase 0).
 
@@ -294,66 +190,13 @@ If still missing, show which ones and let user skip (pipeline will re-ask for an
 
 Pre-populates the Phase 0 project picker with repos the user is active in. Three independent sources merge into one flat list: local `$HOME` scan (depth 3, repo markers), Bitbucket (last 90 days, token-gated), GitHub (owner + collaborator, push in last 90 days, token-gated). Any source failing skips that source only, is reported (never swallowed), and discovery is never destructive and idempotent.
 
-```
-Step 5  -  Repo Discovery (optional)
-Scan for recent repos now to pre-populate the Phase 0 picker?
-
-  y  -  all three (local + Bitbucket + GitHub, ~10-30s)
-  l  -  local scan only (fastest, no network)
-  n  -  skip (Phase 0 will prompt for repo path manually)
-```
-
 The scan commands, merge-by-origin dedup, the multi-select picker, the `recentProjects` / `serviceStatus` prefs shapes and the skip / degrade rules live in `$HOME/.claude/multi-agent-refs/setup/repo-discovery.md`  -  read that file when the user opts in.
 
 ### Step 6  -  Remember as Multi-Repo Group (optional)
 
-After Step 5, if the user picked **2 or more** repos, offer to remember the combination as a named group. Phase 0's project picker surfaces saved groups at the top, so a multi-repo task ("update token resolver in `common` + `uicomponents`") becomes a single keypress next time.
-
-Auto-skipped if Step 5 was skipped or fewer than 2 repos were selected.
-
-**Prompt:**
-```
-Step 6  -  Remember as a multi-repo group (optional)
-You picked 2 repos: Checkout, UIComponents.
-
-Save this combo for one-tap selection in Phase 0?
-  Group name (Enter for auto): [Checkout + UIComponents]
-  Skip with 'n'.
-```
-
-**Auto-name heuristic** (suggested but editable):
-- 2 repos    → `"<repoA> + <repoB>"`
-- 3-4 repos  → `"<repoA>, <repoB>, <repoC>(+1)"`
-- 5+ repos   → `"<repoA> + <count-1> more"`
-
-Repo identifiers in the label are the human label from `recentProjects` (basename of the path, not the full path), so groups stay readable.
-
-**Save** (matches schema `global.recentGroups[]` shape  -  `repos` required, `label` / `count` / `lastUsed` optional):
-
-```json
-{
-  "global": {
-    "recentGroups": [
-      {
-        "label": "Checkout + UIComponents",
-        "repos": ["~/dev/Checkout", "~/dev/UIComponents"],
-        "count": 1,
-        "lastUsed": "2026-04-15T21:08:00Z"
-      }
-    ]
-  }
-}
-```
-
-**LRU + dedup rules:**
-- New group → unshift to front of `recentGroups`.
-- Same set of `repos` already exists (order-independent compare) → bump existing entry to front, increment its `count`, update `lastUsed`. Do NOT create a duplicate.
-- Schema cap is 10 entries; oldest LRU entries past the cap are dropped.
+After Step 5, if the user picked **2 or more** repos, offer to remember the combination as a named group in `global.recentGroups[]`, so Phase 0's project picker surfaces it at the top. Auto-skipped if Step 5 was skipped or fewer than 2 repos were selected.
 
-**Skip rules:**
-- Single-repo selection → step is a no-op (no group needed for one repo).
-- User answers `n` → not saved; the picker still works for one-time use, and a future Phase 0 selection of the same combo will re-prompt.
-- Step 5 skipped → Step 6 is also skipped (no selection to remember).
+Read `$HOME/.claude/multi-agent-refs/setup/multi-repo-group.md` before Step 6: the prompt, the auto-name heuristic, the saved shape, the LRU + dedup rules and the skip rules.
 
 ### Step 7  -  Platform Identity Routing (optional)
 
@@ -369,28 +212,7 @@ Standard key names are a convention for NEW tokens; discovery may find existing
 
 ### Inline Token Save Pattern
 
-All tokens go through `~/.claude/lib/credential-store.sh` (Python helper and label/service attributes: see "Setup" above).
-
-```bash
-# PAT / API Key / JSON contents (from clipboard)
-pbpaste | ~/.claude/lib/credential-store.sh set "<SERVICE_NAME>" -
-pbcopy < /dev/null  # clear clipboard
-
-# Non-secret value typed inline (a secret on argv is visible to ps and lands in shell history)
-~/.claude/lib/credential-store.sh set "<SERVICE_NAME>" "<VALUE>"
-
-# Key file from disk (the .p8, the Google Play JSON; or when the clipboard is unavailable)
-~/.claude/lib/credential-store.sh set "<SERVICE_NAME>" - < /path/to/file.json
-
-# Read  -  a JSON value comes back exactly as it was stored, newlines included
-~/.claude/lib/credential-store.sh get "<SERVICE_NAME>"
-```
-
-For maximum stdin hygiene (the secret never lands on argv / shell history), use the Python helper directly with the `-` sentinel:
-
-```bash
-pbpaste | ~/.claude/scripts/keychain.py set "<SERVICE_NAME>" -
-```
+All tokens go through `~/.claude/lib/credential-store.sh`: a secret from the clipboard via `pbpaste | ~/.claude/lib/credential-store.sh set "<SERVICE_NAME>" -` followed by `pbcopy < /dev/null`, a key file via `- < /path/to/file`, never a secret on argv. Every form, and the Python helper: `$HOME/.claude/multi-agent-refs/setup/token-save-flow.md` "Inline Token Save Pattern".
 
 ### Figma MCP Setup (Remote / Local question)
 
@@ -406,37 +228,15 @@ Full procedure: `$HOME/.claude/multi-agent-refs/setup/figma.md`. Read it for the
 
 ### Setup from Scratch Summary
 
-To set up multi-agent on a new machine:
-
-```
-1. Install the toolkit:
-   npx @{npm-scope}/multi-agent-pipeline install
-
-2. Start setup:
-   /multi-agent setup
-
-3. Interactive flow:
-   -> Token scan (shows what is missing)
-   -> Git Identity creation (name + email)
-   -> Inline commands for missing tokens
-   -> Final verification
-
-4. Ready:
-   /multi-agent "PROJ-12345"
-   /multi-agent "https://github.com/.../issues/42"
-   /multi-agent "bug description"
-```
+Install the toolkit (`npx @{npm-scope}/multi-agent-pipeline install`), run `/multi-agent setup`, follow the interactive flow, then start a task. Walkthrough: `$HOME/.claude/multi-agent-refs/setup/summaries.md` "Setup from scratch".
 
 All tokens are optional in the sense that every service can be answered with Skip  -  but the ASKING is not optional: the Step 3 sequential loop still walks every missing service one by one (token → author → host). Phase 0 re-asks at runtime only for tokens the user skipped here.
 
 ### Step 8  -  Enforcement hooks (optional)
 
-On Claude Code, offer to merge `$HOME/.claude/templates/claude-hooks.json`: three blocking `PreToolUse` gates (secret scan, agent-guard, read-size) plus four non-blocking hooks (`PreCompact`, `SessionEnd`, `SessionStart`, `PostToolUse`). What each does: `$HOME/.claude/multi-agent-refs/picker-contract.md`.
+On Claude Code, offer to merge `$HOME/.claude/templates/claude-hooks.json`: three blocking `PreToolUse` gates (secret scan, agent-guard, read-size) plus non-blocking hooks on `PreCompact`, `SessionEnd`, `SessionStart` and `PostToolUse`, and a `Stop` hook (`run-stop-guard.sh`) that holds a session from stopping mid-run. What each does: `$HOME/.claude/multi-agent-refs/picker-contract.md`.
 
-- Ask (picker): "Install the pipeline's hooks into `~/.claude/settings.json`?" Default Yes.
-- On Yes, deep-merge EVERY event in the template's `hooks` object (merging `PreToolUse` alone drops the capture hooks); keep existing hooks, never duplicate a matcher calling the same script.
-- Say only the three gates are hookable (no run-specific arguments); the rest are phase-enforced.
-- Say the read-size gate stays inert until `prefs.global.bulkRead.mode` is set; recommend `observe` first (why, and the Phase 3 exemption: `picker-contract.md`).
+Ask (picker) whether to install the hooks into `~/.claude/settings.json`, default Yes. On Yes, deep-merge EVERY event in the template's `hooks` object and never duplicate a matcher calling the same script. Read `$HOME/.claude/multi-agent-refs/setup/hooks-and-plugins.md` before Step 8: the merge rules and what to tell the user about the gates.
 
 Codex: offer only the syntax gate, then run `node "$HOME/.codex/scripts/host-hooks.mjs" install --host codex`. Copilot CLI: offer no hook (it discards `postToolUse` output as of 1.0.45).
 
@@ -448,9 +248,7 @@ Stack skills ship as versioned plugins in the `{owner}/multi-agent-plugins` mark
    ```bash
    bash "$HOME/.claude/scripts/plugin-refresh.sh" {owner} --add-only
    ```
-2. Ask the detector, then derive. No marker list here: a second list is a second
-   answer, and this one defaulted to `ai-ios-toolkit` when nothing matched - how
-   a Next.js site and several Node CLIs ended up with the iOS toolkit.
+2. Ask the detector, then derive (no marker list in this file):
 
    ```bash
    eval "$(bash $HOME/.claude/lib/stack-detect.sh "$PROJECT_ROOT")"   # MA_STACKS, MA_STACK_WHY
@@ -459,10 +257,7 @@ Stack skills ship as versioned plugins in the `{owner}/multi-agent-plugins` mark
    ```
 
    Report `MA_STACK_WHY` with the result. `ai-common-toolkit` and
-   `ai-analyst-toolkit` are in every answer, the empty one included: neither is
-   stack-specific. **No marker matched is an answer** - those two, not a guess.
-   A name the marketplace does not carry is dropped with `dropped[]` naming it,
-   so a toolkit that was never shipped is caught before it fails to load.
+   `ai-analyst-toolkit` are in every answer, the empty one included. How the answer is read (empty answers, `dropped[]`): `$HOME/.claude/multi-agent-refs/setup/hooks-and-plugins.md` "Step 9".
 3. Report the enabled set. To change later, run `/multi-agent:stack <ios|android|web|backend|...>` in the repo. Pipeline Phase 1 auto-detects the stack for its own routing regardless of enablement.
 
 The marketplace repo name (`multi-agent-plugins`) is generic; a different org points `{owner}` at its own fork - nothing in the pipeline is coupled to a specific account.

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

@@ -79,6 +79,7 @@ Step 3: REPO        Claude Code -> pipeline repo (genericized, personal data scr
 Step 3c: PLUGINS    pipeline shared/external -> multi-agent-plugins marketplace (rebuild knowledge/,
                      bump changed plugins' patch version, commit + push the plugins repo)
 Step 3d: DEV-TOOLKIT companion MCP server -> detect movement, run the ship gates, commit + publish
+Step 3e: OFFICE      panel page is current, installed copies match it, toolkit version recorded
 Step 4: WEBSITE     Version + phase/model counts -> {website-host} (i18n + projects.ts)
 Step 5: Commit      Commit + push all changed repos
 Step 6: Report      Summary: synced targets, platform, changed files, deploy status, multi-agent-toolkit version
@@ -131,6 +132,7 @@ Step 0 gate rules and why: `features/doctor.md`.
    - `~/.claude/CLAUDE.md`, `~/.claude/rules/`, `~/.claude/knowledge/`
    - `~/.claude/scripts/`  -  EXCEPT `pre-commit-check.sh`, `agent-guard.sh`, `agent-guard.py`, and `build-stack-plugins.mjs` (generic, synced)
    - `~/.claude/settings.json`
+   - `~/.claude/office/`  -  the office panel flows the other way: its source is the repo (`pipeline/office-src`, built by `office-build.mjs` into `pipeline/office`), and the installer copies it to each host. Never copy it from `~/.claude` into the repo; Step 3e checks it instead
    - `~/.claude/multi-agent-refs/registries/`  -  the installer copies gate registries there from `pipeline/skills/shared/external`; the repo already holds the source
    - **Any `~/.claude/commands/multi-agent/*/SKILL.md` whose frontmatter has `local-only: true`** - these are user/repo-specific alias wrappers that delegate to a private marketplace plugin's skills exposed as `multi-agent:<name>`. Syncing them would leak the private plugin/skill names into the public pipeline. Skip them at copy time; the backstop below proves none reached `pipeline/commands/`.
      ```bash
@@ -226,9 +228,19 @@ When invoked with the `release` argument:
 8. WEBSITE       Version + features -> {website-host} (maintainer identity, build verified Ready)
 9. COPILOT       Copilot CLI instructions + skills sync
 9b. CODEX        Codex CLI router skill + refs + agent TOML (node install.js --codex)
+9c. OFFICE       Step 3e: the installed panel matches the release
 10. Report       Summary: version, touched repos, deploy status
 ```
 
+### Step 3e: OFFICE (every sync, and step 9c of a release)
+
+The office panel ships with the pipeline, so a sync carries it by checking it, not by copying it:
+
+1. `node ~/multi-agent-pipeline/pipeline/scripts/office-build.mjs --check`: the committed page is what `pipeline/office-src` builds to, and `office/toolkit.json` carries the toolkit version in `docs/facts.json`. Either stale fails the sync until it is rebuilt and committed; a release that regenerates facts rebuilds the office right after.
+2. After the install steps, compare `pipeline/office/index.html` with the installed copies (`~/.claude/office/`, and the Copilot and Codex trees when installed), byte for byte, plus the asset list. A difference means the install is behind: run `node install.js --installed` and compare again.
+3. Report the toolkit version the installed `office/toolkit.json` carries: it is what the office Tools window starts, and it moves forward with every release.
+4. An office server that is already running picks the update up by itself: the open page shows a reload banner, and `/multi-agent:office-on` replaces a server whose code changed. Nothing to restart by hand.
+
 ---
 
 ## Sub-Command Sync (Claude Code <-> Copilot CLI Skills)