@mmerterden/multi-agent-pipeline 20.36.0 → 20.37.0

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

@@ -12,19 +12,9 @@ confirm: none
 
 **Input**: $ARGUMENTS
 
-Skip Phase 0-3 and review a diff only. Five input shapes, two providers:
+Skip Phase 0-3 and review a diff only: empty input (PR picker, or the current branch in autopilot), a branch, or a PR (`#N`, `repo#N`, GitHub or Bitbucket Server URL). Input matrix: `$HOME/.claude/multi-agent-refs/review/inputs.md`.
 
-| Input | Resolution | PR action? |
-|---|---|---|
-| (empty), interactive | **PR picker** - list open GitHub + Bitbucket PRs, multi-select which to review | Yes (per selected PR) |
-| (empty), autopilot / no PRs found | Current branch (`HEAD` vs `origin/develop`) | No (chat only) |
-| `feature/foo` | Named local branch | No (chat only) |
-| `#1250` | PR number on the current repo | Yes |
-| `repo#1250` | PR on a specific repo (GitHub `org/repo`) | Yes |
-| `https://github.com/.../pull/1250` | GitHub PR URL | Yes |
-| `https://bitbucket.<host>/projects/<KEY>/repos/<slug>/pull-requests/<N>/...` | Bitbucket Server PR URL | Yes |
-
-Branch-mode runs print to chat only. PR-mode runs print to chat AND post the verdict to the PR per `$HOME/.claude/multi-agent-refs/channels/pr-review-actions.md`: per-finding inline comments + an explicit approve / needs-work state. **No monolithic advisory comment** is ever posted.
+Branch mode prints to chat only. PR mode also posts per `$HOME/.claude/multi-agent-refs/channels/pr-review-actions.md`: inline comments + an approve / needs-work state.
 
 ## Gotchas
 
@@ -33,14 +23,11 @@ Branch-mode runs print to chat only. PR-mode runs print to chat AND post the ver
 
 ## Steps
 
-### 0. Session bootstrap  -  TASK_ID + tmp cleanup
+### 0. Session bootstrap
 
 ```bash
-# Standalone /multi-agent:review invocations may not inherit a pipeline TASK_ID.
-# Seed one so /tmp paths don't collide across concurrent reviews.
 : "${TASK_ID:=review-$(date +%s)-$$}"
 export TASK_ID
-
 trap 'rm -f /tmp/multi-agent-review-${TASK_ID}-*' EXIT
 ```
 
@@ -48,227 +35,65 @@ Standalone only (a `review-` id): register a tracker record per `$HOME/.claude/m
 
 ### 1. Parse the input  -  pick a resolution path
 
-```bash
-# Pseudocode  -  orchestrator implements this:
-input="$ARGUMENTS"
-case "$input" in
-  "")                              kind=pick   # interactive: go to Step 1a PR picker; autopilot/no-PRs falls back to branch (see 1a)
-                                   ;;
-  https://github.com/*/pull/*)     kind=pr; provider=github; org_repo=<extracted>; pr_number=<extracted> ;;
-  https://bitbucket.*/projects/*/repos/*/pull-requests/*)
-                                   kind=pr; provider=bitbucket-server
-                                   bb_server_host=<extracted host>
-                                   bb_project_key=<extracted KEY>
-                                   bb_repo_slug=<extracted slug>
-                                   pr_number=<extracted N>
-                                   ;;
-  *#[0-9]*)                        kind=pr; provider=github; org_repo="${input%%#*}"; pr_number="${input##*#}" ;;
-  '#'[0-9]*)                       kind=pr; provider=github; org_repo=$(gh repo view --json nameWithOwner -q .nameWithOwner); pr_number="${input#'#'}" ;;
-  [0-9]*)                          kind=pr; provider=github; org_repo=$(gh repo view --json nameWithOwner -q .nameWithOwner); pr_number="$input" ;;
-  *)                               kind=branch; provider=local; ref="$input" ;;
-esac
-```
+Empty -> `kind=pick`; `https://github.com/*/pull/*`, `repo#N`, `#N` or a bare number -> `kind=pr; provider=github`; `https://bitbucket.*/projects/*/repos/*/pull-requests/*` -> `kind=pr; provider=bitbucket-server`; anything else -> `kind=branch; provider=local`. Before parsing, read `review/inputs.md` "Step 1": the case block and field extraction.
 
-Save to `agent-state.review.input = { kind, provider, ref?, orgRepo?, bbServerHost?, bbProjectKey?, bbRepoSlug?, prNumber?, raw }`.
-
-When `provider=github` and the diff is fetched in Step 2, also persist `agent-state.review.headCommitSha`  -  GitHub inline-comment posts (`POST /repos/{o}/{r}/pulls/{n}/comments`) require `commit_id`. Bitbucket Server's anchor API does not.
+Save to `agent-state.review.input = { kind, provider, ref?, orgRepo?, bbServerHost?, bbProjectKey?, bbRepoSlug?, prNumber?, raw }`. For `github`, Step 2 also persists `agent-state.review.headCommitSha` (inline comments need `commit_id`).
 
 ### 1a. No-input PR picker  -  interactive only
 
-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 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.
+Autopilot skips it: no ref means branch mode on the current branch, no prompt. Otherwise list open PRs from both providers (an absent token or CLI contributes nothing, never a hard failure), ask `AskUserQuestion` `multiSelect: true` per `$HOME/.claude/multi-agent-refs/picker-contract.md`, and **loop Steps 2-7 once per selected PR**. An empty list or no selection falls back to branch mode. Commands and fields: `review/inputs.md` "Step 1a".
 
 ### 2. Fetch the diff  -  kind-aware
 
-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.
+Branch: `git diff origin/develop...{ref}`. GitHub: `gh pr diff`, plus `headCommitSha`. Bitbucket Server: the REST diff endpoint, credentials through `prefs.global.keychainMapping` (never hardcoded key names, never on argv), any non-200 a hard failure. Read `review/inputs.md` "Step 2" before fetching. Save to `/tmp/multi-agent-review-${TASK_ID}-diff.patch`.
 
-### 2b. Module review guides  -  path-scoped convention files
+### 2b. Module review guides
 
-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:
-
-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):
-
-> MODULE REVIEW GUIDES: before reviewing, read each of these guide files. Apply a guide's rules/checklist to every changed file under its directory. Guide violations are findings like any other  -  triage them by severity.
-
-Scope note: a guide governs only files under its own directory  -  a guide found under one module must not be applied to a sibling module's changes in the same PR.
+A changed module's own CLAUDE guide must be consulted. Read `$HOME/.claude/multi-agent-refs/review/module-guides.md` before Step 2b: discovery, the cap of 5, the PR-mode probe, and the prompt block injected into every Step 3 reviewer. No hit: silent no-op. Persist `agent-state.review.moduleGuides`. A guide governs only files under its own directory.
 
 ### 2c. Valven delivery rules  -  required on every input
 
-The `valven-rules` registry (`ai-common-toolkit`) is applied to every review, in `review` mode. Collect what the gate needs, then run it:
-
-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.
+Read `$HOME/.claude/multi-agent-refs/review/valven.md` before Step 2c: gate arguments per input, every rule family, and the judgement rules each Step 3 prompt gets. Always:
 
-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).
+- Exit 2: print the stderr line and continue with `Valven: not measured (<reason>)` in the Step 6 summary. Never print it as passed.
+- `findings[]` join at Step 5 with `tag: valven`, accepted unless the task is exempt; an accepted `important` or `blocking` one makes Step 7 NEEDS WORK. Step 6 adds its "Summary lines".
 
 ### 3. Launch parallel reviewers  -  host-CLI dependent
 
-Every host runs three reviewers; only the second slot differs, because GPT-5.4 exists on Copilot and Codex but not on Claude Code, where Opus fills it.
-
-**Resolve the fable slots first (Claude Code).** This command has no Phase 0, so
-the `prefs.global.modelFallback.fableEnabled` switch is applied here, once, before
-any dispatch:
+Resolve the fable slots first on Claude Code (this command has no Phase 0):
 
 ```bash
 REVIEW_RUNG=$(bash "$HOME/.claude/lib/model-dispatch.sh" subagent --persona reviewer --default fable)
 TRIAGE_RUNG=$(bash "$HOME/.claude/lib/model-dispatch.sh" subagent --persona triage --default fable)
 ```
 
-`fable` means the rung is on and Agent 1 runs on Fable. Anything else means it is
-off: Agent 1 is dropped, the panel is Agent 2 + Agent 3, triage runs on
-`$TRIAGE_RUNG`, and one line is printed:
-`INFO: fable rung disabled by prefs; review panel = Opus + Sonnet, triage on <rung>.`
-Never dispatch a Fable reviewer or a Fable triage on the model list below alone.
-
-**Claude Code (3 in parallel while the fable rung is on, 2 while it is off):**
-- Agent 1: `claude-fable-5-1` → security + architecture (only when `REVIEW_RUNG` is `fable`)
-- Agent 2: `claude-opus-5-5` → edge cases, alternate perspective
-- Agent 3: `claude-sonnet-5-5` → general quality
-
-**Copilot CLI (3 in parallel):**
-- Agent 1: `claude-opus-4.7` → security + architecture (Fable is not offered on Copilot CLI)
-- Agent 2: `gpt-5.4` → edge cases, alternate perspective
-- Agent 3: `claude-sonnet-4.6` → general quality
-
-**Codex CLI (3 in parallel, single vendor):**
-- Agent 1: `gpt-5.6` @ `xhigh` → security + architecture
-- Agent 2: `gpt-5.4` @ `high` → edge cases, alternate perspective
-- Agent 3: `gpt-5.6` @ `medium` → general quality
+Anything but `fable` drops Agent 1, runs triage on `$TRIAGE_RUNG`, and prints `INFO: fable rung disabled by prefs; review panel = Opus + Sonnet, triage on <rung>.` Never dispatch a Fable reviewer or a Fable triage on the model list alone. Read `$HOME/.claude/multi-agent-refs/review/panel.md` "Reviewers" before dispatch: the per-host panels. Rung switch: `$HOME/.claude/multi-agent-refs/features/model-fallback.md`.
 
-The rung switch and its resolution: `$HOME/.claude/multi-agent-refs/features/model-fallback.md`.
-
-Each reviewer receives the diff, the module review guides from Step 2b (when any were found), the Valven judgement rules from Step 2c, plus the standard reviewer system prompt (see `$HOME/.claude/multi-agent-refs/phases/phase-3-review.md` for the prompt contract). Output: structured `findings[]` per reviewer.
+Each reviewer gets the diff, the 2b guides, the 2c judgement rules and the prompt from `$HOME/.claude/multi-agent-refs/phases/phase-3-review.md`, and returns `findings[]`.
 
 ### 4. Store-compliance cross-reference
 
-When release-relevant iOS/Android files change, load the matching catalog:
-
-| Platform | Trigger files | Catalog |
-|---|---|---|
-| iOS | `**/Info.plist`, `**/PrivacyInfo.xcprivacy`, `**/*.entitlements`, `**/*App.swift`, `**/AppDelegate*.swift`, `**/SceneDelegate*.swift`, `**/project.pbxproj` | `$HOME/.claude/skills/apple-archive-compliance/SKILL.md`  -  18 rules + ITMS refs |
-| Android | `**/AndroidManifest.xml`, `**/build.gradle(.kts)`, `**/proguard-rules.pro`, `**/network_security_config.xml` | `$HOME/.claude/skills/google-play-compliance/SKILL.md`  -  21 rules + Play policy refs |
-
-Each finding gets the `ruleID` from the catalog plus the platform policy ref:
-- iOS: `(apple-archive-compliance / info-plist  -  Guideline 5.1.1)`
-- Android: `(google-play-compliance / dangerous-permissions  -  Policy  -  Permissions)`
-
-Catalog-only  -  does NOT invoke binaries. For a full scan, use `/multi-agent:test "store-ready"`.
+Release-relevant files load the catalog (`apple-archive-compliance` for iOS, `google-play-compliance` for Android); each finding gets its `ruleID` plus the policy ref. Catalog-only, no binaries; a full scan is `/multi-agent:test "store-ready"`. Triggers and paths: `review/panel.md` "Store compliance".
 
 ### 4b. Platform parity cross-check (advisory, read-only)
 
-When a counterpart repo resolves whose `stack` is the other mobile platform and
-the diff touches a screen, a service, a request model or a localization file,
-compare the change against that repo on four axes: endpoints called, parameters
-sent, business rules around the call, localization keys used.
-
-In a product, counterparts are its other repos via `product-context.mjs refs`
-and `repo_*`. Otherwise the counterpart is resolved automatically, in both directions (ios ↔ android),
-from four sources in this order, first hit wins: `--with <path|owner/repo>` (a
-one-off override, remembered like any other resolution), then a remembered
-`prefs.projects[<slug>].counterpartRoots[]`, then the primary checkout's sibling
-directories, then `state.siblings[]` from the Phase 0 dev-context picker. None of
-them is a precondition for the others. One match is used and remembered, so the
-next review of the same project asks nothing.
-
-Several candidates → interactive runs ask once; autopilot and non-interactive
-runs skip silently, because an unattended run must not block on a picker. No
-candidate → skip silently, run unaffected. Stack comes from marker files, and
-you never guess a stack from the repo name.
-
-Contract: `$HOME/.claude/multi-agent-refs/platform-parity.md`.
-
-### 5. Triage (`$TRIAGE_RUNG`: Fable while the rung is on, Opus while it is off)
-
-Classify findings into:
-- 🔴 **Blocking** → must fix
-- 🟡 **Important** → fix recommended
-- 🟢 **Suggestion** → optional
+When a counterpart repo on the other mobile platform resolves and the diff touches a screen, service, request model or localization file, compare endpoints, parameters, business rules and localization keys. Several candidates ask once interactively and skip silently unattended; none skips silently; the counterpart is never edited. Resolution order (including `--with` and `counterpartRoots`) and output: `$HOME/.claude/multi-agent-refs/platform-parity.md`.
 
-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.
+### 5. Triage (`$TRIAGE_RUNG`)
 
-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.
+Classify 🔴 Blocking / 🟡 Important / 🟢 Suggestion; mark each `accepted`, `deferred` (Triage notes) or `rejected`. Only `accepted` reach the PR. Settle every `cannotVerify` row per `phase-3-review.md` 3.2 (`verified` / `finding` / `out-of-scope`, each with its file:line); list unsettled rows.
 
 ### 6. Print the chat summary (always)
 
-```
-🔍 Review Complete  ·  PR #1250  ·  3 files +120 -45
-| Model    | Verdict   | Blocking | Important | Suggestion |
-|----------|-----------|----------|-----------|------------|
-| Fable    | approved  | 0        | 1         | 3          |
-| Opus     | approved  | 0        | 2         | 2          |
-| Sonnet   | rejected  | 1        | 2         | 5          |
-
-Consensus: ⚠ DISAGREEMENT  -  see triage
-```
-
-One row per reviewer that ran: Fable + Opus + Sonnet on Claude Code (Opus + Sonnet while the fable rung is off), Opus + GPT-5.4 + Sonnet on Copilot CLI, the three GPT rows on Codex CLI. This summary ALWAYS prints, regardless of input mode. The chat is the live conversation; on the PR side, the durable artifacts are inline comments + the review state (Step 7).
+One row per reviewer that ran, then consensus; this ALWAYS prints, in every input mode. Template: `review/panel.md` "Summary".
 
 ### 7. Post to PR  -  only when input.kind === "pr"
 
-The contract (full spec: `$HOME/.claude/multi-agent-refs/channels/pr-review-actions.md`):
-
-- **Decision**  -  purely from `accepted` finding counts:
-  - 0 accepted blocking AND 0 accepted important → **APPROVE**
-  - ≥1 accepted blocking OR ≥1 accepted important → **NEEDS WORK / REQUEST CHANGES**
-  - Suggestions never block and never post inline; they stay in chat only.
+- **Decision** from `accepted` counts: 0 accepted blocking AND 0 accepted important -> **APPROVE**; ≥1 accepted blocking OR ≥1 accepted important -> **NEEDS WORK** (`NEEDS_WORK`). Suggestions never block and never post inline.
+- **No monolith advisory comment** (never one body via `gh pr comment`); findings are inline comments at `file:line`, in `outputLanguage`.
 
-- **No monolith advisory comment.** "Render one big body and post via `gh pr comment`" is forbidden. Findings that need to surface on the PR become inline comments anchored to `file:line`.
-
-- **Body language follows `outputLanguage`.** Per `$HOME/.claude/multi-agent-refs/rules.md` Language Application matrix, external payloads (PR comment bodies are external) render in `prefs.global.outputLanguage`. The renderer in `lib/post-pr-review.sh` honors this.
-
-Optional opt-out prompt (interactive mode only; autopilot skips and posts):
-
-```
-question (outputLanguage): "PR #{N} için review action gönderilsin mi?"
-header   (English):        "Post review"
-options (label + description in outputLanguage; semantics, not literals):
-  - option 1  -  "Post review": inline comments + Request changes when there are
-                 findings, Approve when there are none
-  - option 2  -  "Chat only": leave the PR untouched, the chat summary is enough
-default: option 1
-```
-
-Defaults:
-- Interactive mode: prompt with default option 1
-- Autopilot mode: auto-post (no prompt)
-- `--no-comment` / `--no-post` flag: skip the post entirely
-
-If the user picks option 1 (post the review):
-
-```bash
-bash $HOME/.claude/lib/post-pr-review.sh "$TASK_ID"
-```
-
-`post-pr-review.sh` reads `agent-state.review.{input, findings, iterationNumber, headCommitSha}`, decides APPROVE vs NEEDS_WORK from the rule above, posts one inline comment per accepted blocking + important finding (in `outputLanguage`), then sets the review state via the provider's API:
-
-| Provider | Inline comment | State |
-|---|---|---|
-| `github` | `gh api -X POST /repos/{o}/{r}/pulls/{n}/comments` (path + line + commit_id) | `gh pr review --approve` / `--request-changes` |
-| `bitbucket-server` | `POST /pull-requests/{n}/comments` with `anchor: { path, line, lineType:"ADDED", fileType:"TO" }` | `PUT /pull-requests/{n}/participants/{user}` body `{"status":"APPROVED"}` or `{"status":"NEEDS_WORK"}` |
-
-If a finding's `line` lies outside the diff or `headCommitSha` is missing, the comment falls back to a top-level PR comment with the same body.
-
-If the post fails (network, token, harness block), `post-pr-review.sh` exits non-zero and surfaces the failing endpoint on stderr  -  the chat summary remains the source of truth.
+Interactive asks first (default: post); autopilot posts; `--no-comment` / `--no-post` skips. Post with `bash $HOME/.claude/lib/post-pr-review.sh "$TASK_ID"`. Prompt shape, `github` / `bitbucket-server` endpoints and fallbacks: `review/panel.md` "Posting". A failed post exits non-zero; the chat summary stays the source of truth.
 
 ### 8. Token telemetry
 
-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 <N> <input_count> <output_count>
-```
-
-`<N>`: the run's Review phase, or step 2 for a standalone review.
-
-## Input matrix
-
-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.
+After each reviewer call: `bash $HOME/.claude/scripts/phase-tracker.sh tokens <N> <in> <out>` (`<N>` = the run's Review phase, or step 2 standalone; `tracker-contract.md`).

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

@@ -18,11 +18,7 @@ allowed-tools: Bash, Read, Write, AskUserQuestion, WebFetch
 
 ## Step 0 - What is actually wrong
 
-```bash
-node "$HOME/.claude/scripts/doctor.mjs"
-```
-
-Run it before the first question and again at the end. The first run turns setup from a fixed script into a targeted one: there is no point asking for a token that is already mapped and answering. The second run is the only honest way to end - "setup complete" is a claim, and the doctor's exit code is the evidence for or against it. Report both in `outputLanguage`, and if the second run still shows a BLOCK, say so plainly rather than closing on the word "complete".
+Run `node "$HOME/.claude/scripts/doctor.mjs"` before the first question (never ask for a token that is already mapped and answering) and again at the end: its exit code, not the word "complete", decides how setup ends. Report both in `outputLanguage`; a remaining BLOCK is said plainly.
 
 ## Sections
 
@@ -30,225 +26,77 @@ Run it before the first question and again at the end. The first run turns setup
 
 ## Setup (Credential Store + Git Identity Onboarding)
 
-Uses `$HOME/.claude/lib/credential-store.sh` to read/write secrets in the macOS Keychain (`security`, built in). The pipeline is macOS only (ADR-0012).
-
-Run `~/.claude/lib/credential-store.sh doctor` first  -  it prints the platform and whether the backend is usable.
-
-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: 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.
-
-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.
+Ask BEFORE anything else: one question, `outputLanguage` (`en` / `tr`); already set: skip silently. `promptLanguage` is fixed to `"en"` and never offered. From here on `question`, `label` and `description` render in `outputLanguage`; `header` stays English. Read `$HOME/.claude/multi-agent-refs/setup/language.md` before Step 0.
 
 ### Step 0.5  -  Dependency check
 
-```bash
-~/.claude/lib/credential-store.sh doctor
-command -v pdftotext >/dev/null 2>&1 || echo "pdftotext: MISSING"
-```
-
-| Output | Action |
-|--------|--------|
-| `Backend: ✓` | Continue to Step 1 |
-| Platform `unknown` or `ERR: macOS only` | Halt  -  the pipeline runs on macOS only (ADR-0012). |
-| `pdftotext: MISSING` | Advisory. Print `brew install poppler`, continue. `.docx` needs nothing. |
+Run `~/.claude/lib/credential-store.sh doctor` and `command -v pdftotext`. `Backend: ✓`: continue. Platform `unknown` or `ERR: macOS only`: **halt**. `pdftotext` missing: advise `brew install poppler`, continue.
 
 ### Credential Key Naming Rule
 
-- **New token** (first-time creation in Step 3): ALWAYS use the standard key name (`${USER}_Jira_Access_Token`, etc.). This ensures cross-machine consistency.
-- **Existing token** (discovered in Step 1): NEVER rename or migrate. Map the discovered key name as-is into `keychainMapping`. The mapping layer abstracts the actual key name  -  the pipeline never reads the credential store directly by standard name.
+- **New token** (Step 3): ALWAYS the standard key name (`${USER}_Jira_Access_Token`, etc.).
+- **Existing token** (Step 1): NEVER rename or migrate; map the discovered name as-is into `keychainMapping`.
 
 ### Step 1  -  Dynamic Credential Discovery
 
-Full procedure: `$HOME/.claude/multi-agent-refs/setup/discovery.md`. Read it for Step 1.
+Read `$HOME/.claude/multi-agent-refs/setup/discovery.md` for Step 1.
 
 ### Step 2  -  Show Discovery Summary + Save Mapping
 
-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.
-
-Save the resolved mapping to `prefs.global.keychainMapping`  -  every service ID gets an entry, the discovered key name verbatim or `null` when nothing was found:
-
-```json
-{ "jira": "${USER}_Jira_Access_Token", "github": "${USER}_Github", "confluence": null, "...": "..." }
-```
-
-Full key list and shape: `$HOME/.claude/multi-agent-refs/keychain.md`.
-
-`null` = not mapped (missing or skipped). Pipeline phases read this mapping to retrieve tokens dynamically  -  never hardcoded key names.
+Show one line per service with its key or `MISSING`, then the counts (`$HOME/.claude/multi-agent-refs/setup/summaries.md`). Save every service ID to `prefs.global.keychainMapping`, the discovered key name verbatim or `null` (key list: `$HOME/.claude/multi-agent-refs/keychain.md`). Phases read this mapping, never hardcoded key names.
 
 ### Step 2.7  -  Operational reporting
 
-Ask (in `outputLanguage`), and proceed only on an explicit yes:
-
-```
-Do you have an operational-reporting token from your admin?
-[ Paste token / Skip ]
-```
-
-On paste, store it in the credential store ONLY - never in a file, prefs value,
-git or any synced tree - under the standard per-user name, so it is revocable on
-its own:
-
-```bash
-pbpaste | ~/.claude/lib/credential-store.sh set "${USER}_Usage_Ingest_Token" -
-pbcopy < /dev/null
-```
-
-Then, **whether they pasted or skipped**, run:
+Ask whether the user has an operational-reporting token; proceed only on an explicit yes. On paste, store it in the credential store ONLY (never a file, prefs value, git or synced tree): `pbpaste | ~/.claude/lib/credential-store.sh set "${USER}_Usage_Ingest_Token" -` then `pbcopy < /dev/null`. Pasted or skipped, run `node "$HOME/.claude/scripts/usage-register.mjs" --json`; on `"needsPersonalAccount":true` ask once for a GitHub username (Skip leaves reporting off) and re-run with `--login <name>`. What is sent: `$HOME/.claude/multi-agent-refs/features/usage-reporting.md`.
 
-```bash
-node "$HOME/.claude/scripts/usage-register.mjs" --json
-```
-
-If its JSON line says `"needsPersonalAccount":true`, ask once for the person's
-GitHub username (free text; Skip leaves reporting off) and run
-`node "$HOME/.claude/scripts/usage-register.mjs" --login <name> --json`.
-
-It maps whatever token exists and switches reporting on, and requests a
-per-machine write-only one when none resolves, so a machine that runs setup and
-never runs update still reports. What is sent, what never is, and
-`usageLog.optOut`:
-`$HOME/.claude/multi-agent-refs/features/usage-reporting.md`.
-
-### Auto-learned fields (no setup step needed)
-
-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".
+The Jira project key and git identity are learned from use, never asked (`$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: 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.
-
-#### Sequential onboarding loop (strict)
-
-The Step 2 discovery summary is never the end of setup. Immediately after showing it, walk the missing services ONE BY ONE in this fixed order and run the Token Save Flow for each:
-
-1. `jira`
-2. `bitbucket_token` (then `bitbucket_user` right after, if missing)
-3. `github`
-4. `confluence`
-5. `figma`  -  Figma Personal Access Token (Tier 2, REST)
-6. `figma_mcp`  -  Figma MCP auth (Tier 1); its own prompt, never folded into the PAT prompt
-7. `fortify`
-8. `graylog`
-9. `firebase`
-10. `jenkins`
-11. App Store Connect block (Step 3b; only when the target repo is iOS)
-12. Google Play block (Step 3d; only when the target repo is Android)
-13. Free-model keys `llm-<id>` (only after `route-on --free`): `$HOME/.claude/multi-agent-refs/setup/free-models.md`
-
-Loop rules:
-
-- **One prompt per service.** Never collapse the list into a single "add missing tokens now?" yes/no, and never offer one multi-select covering all services: each service has its own source URL, key name, identity binding and host prompt, so each gets its own Token Save Flow pass.
-- **Each service pass asks, in order: token → author → host → read binding (GitHub, Bitbucket; Token Save Flow Step 3.7).** Step A/B collect the secret, Step C binds the git identity (author)  -  Bitbucket and GitHub included; every saved token gets an author  -  and Step 3.5 asks the host domain inline for hosted services (jira, confluence, bitbucket, fortify, graylog) - plus the Fortify project versions and the optional Graylog test instance. GitHub and Figma skip the host question (fixed domains); `bitbucket_user` skips author binding (username, not a PAT). Never end a service pass with the token saved but the author or a required host unasked.
-- **Skip is per-service.** A Skip answer leaves that service's `keychainMapping` at `null` and the loop continues with the next service. Skips never abort the loop.
-- **`figma` and `figma_mcp` are distinct credentials for distinct tiers  -  ask both.** Skipping the PAT does not imply skipping MCP, and vice versa. The `figma_mcp` pass opens with a Remote / Local mode question instead of a clipboard paste (see "Figma MCP Setup" below): Remote generates a `figu_` OAuth token for the current user, Local wires the PAT-based local server.
-- The loop ends only when every missing service has been asked exactly once; then continue to Step 4 (Verify all).
-
----
-
-### Token Save Flow (reusable)
-
-Full procedure: `$HOME/.claude/multi-agent-refs/setup/token-save-flow.md`. Read it for every token prompt (Steps 3, 3b, 3c and any command that saves a token).
+Identities are learned in the Token Save Flow (Step C), never asked separately.
 
-### Step 3b  -  App Store Connect onboarding (iOS only, optional)
+Walk the missing services ONE BY ONE, in this order: `jira`, `bitbucket_token` (then `bitbucket_user`), `github`, `confluence`, `figma` (PAT), `figma_mcp` (its own prompt), `fortify`, `graylog`, `firebase`, `jenkins`, App Store Connect (3b, iOS), Google Play (3d, Android), free-model keys `llm-<id>` (only after `route-on --free`: `$HOME/.claude/multi-agent-refs/setup/free-models.md`). One prompt per service, never one yes/no or multi-select for all; each pass asks token, author, host, read binding; Skip is per-service and never aborts the loop. Read `$HOME/.claude/multi-agent-refs/setup/token-save-flow.md` before the loop and for every token prompt: the loop rules, Steps 3.5 / 3.7 and identity learning.
 
-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.
+### Steps 3b-3d  -  Store and Firebase onboarding (optional)
 
-### Step 3c  -  Firebase / Crashlytics onboarding (optional)
-
-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`, 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)
-
-Full procedure: `$HOME/.claude/multi-agent-refs/setup/token-save-flow.md`. Read it for the host question inside the Token Save Flow.
+Each key is validated BEFORE it is saved and lives only in the Keychain; Skip writes nothing. Read the matching file under `$HOME/.claude/multi-agent-refs/setup/` first: `app-store-connect.md` (3b, iOS, `.p8` included), `firebase.md` (3c: probe with `fetch-crashlytics.sh --probe` before asking; store the JSON as issued), `google-play.md` (3d, Android).
 
 ### Step 3.6  -  Per-account host overrides (optional)
 
-**Runs only when** `~/.claude/lib/account-resolver.sh` returns **more than one** account AND at least one account has Jira or Bitbucket tokens.
-
-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`.
-
----
+Only when `~/.claude/lib/account-resolver.sh` returns more than one account and one has Jira or Bitbucket tokens. Read `accounts.md` "Per-account host overrides (Step 3.6)" (setup refs). Skipped on autopilot; `/multi-agent:setup accounts` opens it later.
 
 ### Step 4  -  Verify all
 
-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).
-
-### Step 5  -  Repo Discovery (optional)
-
-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.
-
-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 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.
-
-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.
+Re-run the Step 1 scan and show the final status (`summaries.md` "Step 4 final status"). Still missing: show which and let the user skip; Phase 0 re-asks.
 
-### Step 7  -  Platform Identity Routing (optional)
+### Steps 5-7  -  Repo discovery, groups, identity routing (optional)
 
-Full procedure: `$HOME/.claude/multi-agent-refs/setup/identity-routing.md`. Read it for Step 7.
+Read the file under `$HOME/.claude/multi-agent-refs/setup/` for each step the user opts into: `repo-discovery.md` (5: local, Bitbucket, GitHub; a failing source skips only itself and is reported), `multi-repo-group.md` (6: only after 2+ repos), `identity-routing.md` (7).
 
-### Cross-Platform Notes (Step 1-9)
+### Credential store, token sources, Figma MCP
 
-Every read and write goes through `~/.claude/lib/credential-store.sh`, which wraps the macOS Keychain; stay on the helper rather than calling `security` directly. The clipboard handling and what happens when no backend exists: `$HOME/.claude/multi-agent-refs/keychain.md` "Credential store mechanics".
-
-### Token -> Source Mapping
-
-Standard key names are a convention for NEW tokens; discovery may find existing keys under other names, and the mapping in preferences handles that. The key names, the token types and where to generate each one all live in one table: `$HOME/.claude/multi-agent-refs/keychain.md` "Standard key names". Git identities are stored in preferences, never in the credential store.
-
-### Inline Token Save Pattern
-
-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)
-
-Full procedure: `$HOME/.claude/multi-agent-refs/setup/figma.md`. Read it for the Figma MCP question.
+Always `~/.claude/lib/credential-store.sh` (macOS Keychain, macOS only, ADR-0012), never `security` directly; secrets from the clipboard or a file, never argv. Key names, token sources and store mechanics: `$HOME/.claude/multi-agent-refs/keychain.md`. Identities live in preferences. Figma MCP Remote / Local: `$HOME/.claude/multi-agent-refs/setup/figma.md`.
 
 ### Security Rules
 
-- Never paste tokens into terminal or chat  -  use `pbpaste` for input
+- Never paste tokens into terminal or chat - use `pbpaste` for input
 - Never hardcode tokens in source code
 - Never commit tokens to git history
 - Clear clipboard immediately: `pbcopy < /dev/null`
 - `2>/dev/null` suppresses stderr (prevents metadata leakage)
 
-### Setup from Scratch Summary
-
-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.
+From scratch: `npx @{npm-scope}/multi-agent-pipeline install`, `/multi-agent setup`, then a task (`summaries.md` "Setup from scratch").
 
 ### 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 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) 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).
+Claude Code: offer (picker, default Yes) to merge `$HOME/.claude/templates/claude-hooks.json` into `~/.claude/settings.json`; deep-merge EVERY event, never duplicate a matcher. Read `$HOME/.claude/multi-agent-refs/setup/hooks-and-plugins.md` before Step 8. Codex: only the syntax gate, via `node "$HOME/.codex/scripts/host-hooks.mjs" install --host codex`. Copilot CLI: no hook.
 
 ### Step 9  -  Default stack plugin enablement
 
-Stack skills ship as versioned plugins in the `{owner}/multi-agent-plugins` marketplace. On first setup, wire the stack so the pipeline works out of the box.
-
-1. Ensure the marketplace is known (idempotent):
-   ```bash
-   bash "$HOME/.claude/scripts/plugin-refresh.sh" {owner} --add-only
-   ```
-2. Ask the detector, then derive (no marker list in this file):
+1. `bash "$HOME/.claude/scripts/plugin-refresh.sh" {owner} --add-only` (idempotent).
+2. Ask the detector, then derive; no marker list here:
 
    ```bash
    eval "$(bash $HOME/.claude/lib/stack-detect.sh "$PROJECT_ROOT")"   # MA_STACKS, MA_STACK_WHY
@@ -256,8 +104,4 @@ Stack skills ship as versioned plugins in the `{owner}/multi-agent-plugins` mark
      console.log(m.pluginsForStacks(process.argv[1].split(" ").filter(Boolean)).plugins.join(" ")))' "$MA_STACKS"
    ```
 
-   Report `MA_STACK_WHY` with the result. `ai-common-toolkit` and
-   `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.
+3. Report `MA_STACK_WHY` and the enabled set (`hooks-and-plugins.md` "Step 9"); change later with `/multi-agent:stack <stack>`.