@mmerterden/multi-agent-pipeline 20.13.0 → 20.15.0

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

@@ -72,46 +72,12 @@ Roll the high-impact + low/med-effort survivors into the Step 4 plan as band-A i
 
 Some skills/components in this project (or in the marketplace plugins it ships) were derived from an upstream source. Upstream keeps evolving  -  it fixes bugs and adds features. This step detects upstream drift so we can decide whether to pull the improvements back.
 
-The upstream mapping is **configuration, never hardcoded** (it can reference private sources, so it stays out of the shipped skill). Read it from `~/.claude/multi-agent-preferences.json` at `global.derivedSkillSources` (an array). Each entry:
-
-```jsonc
-{
-  "label": "<human name for this derivation>",
-  "localPath": "<repo-relative dir where our derived copy lives>",
-  "upstreamMarketplace": "<installed marketplace name>",   // resolved under ~/.claude/plugins/cache/<marketplace>/
-  "upstreamPlugin": "<plugin name>",
-  "upstreamSkills": ["<skill-a>", "<skill-b>"],            // the upstream skills we took
-  "derivedFromVersion": "<x.y.z>",                         // the version we last synced from
-  "upstreamVersionSource": "marketplace.json",             // which manifest is authoritative; default marketplace.json
-  "upstreamLocalClone": "<optional path>",                 // working copy of the upstream repo, preferred over the cache
-  "upstreamRepoUrl": "<optional https url>"                // used when neither a clone nor the marketplace is available
-}
-```
-
-**The plugin cache is a mirror, not the authority.** `~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/` only holds whatever the last `claude plugin marketplace update` fetched. Reading it as the current upstream version is how this step reported "up to date" while the derivation was four releases behind: the cache sat at 0.2.1 and upstream was at 0.4.1. Resolve in the order below and never let the cache alone produce an "up to date" verdict.
-
-**Which manifest carries the version** is `upstreamVersionSource`, default `marketplace.json`. That is what a marketplace consumer actually resolves, and some upstreams keep per-plugin `plugin.json` versions deliberately unused - reading those records a version nobody ships. An entry here was recorded at 0.7.0 from `plugin.json` while the upstream marketplace said 0.6.0 and its CHANGELOG stated in as many words that `plugin.json` is not used.
-
-Procedure:
-1. If `global.derivedSkillSources` is missing or empty -> **skip** this step and report "no derived-skill sources configured" (nothing to check). Never invent a source.
-2. For each entry, resolve the current upstream version, in this order, stopping at the first that answers:
-   - **`upstreamLocalClone`** if set: read `<clone>/.claude-plugin/<upstreamVersionSource>`. Also run `git -C <clone> fetch --dry-run` (or compare against `@{u}`) and say so when the clone is itself behind, so a stale working copy is not silently trusted either.
-   - **`upstreamRepoUrl`**: read the same manifest over the API (`gh api` / `WebFetch`). A private upstream can 404 for the currently active account even when the repo exists - that is an unreachable result, not a "no drift" result.
-   - **Plugin cache** under `~/.claude/plugins/cache/<upstreamMarketplace>/<upstreamPlugin>/*/`: last resort only. When the cache is the only source that answered, report the entry as **`unverified (cache only)`**, never as "up to date", and add a plan item to configure `upstreamLocalClone`.
-   - If nothing is reachable, record the entry as "upstream unreachable" and move on (do not fail the whole run).
-3. Compare the resolved upstream version to `derivedFromVersion`:
-   - equal, from an authoritative source -> "up to date" (no drift)
-   - equal, from the cache only -> "unverified (cache only)"
-   - newer -> **drift**: read the CHANGELOG entries between the two versions, and diff each `upstreamSkills` SKILL.md (+ any templates) against our `localPath` copy. Summarize what changed upstream (bug fixes, new sections, new templates, renamed inputs). Ignore changelog entries that only touch skills outside `upstreamSkills` - they are not ours to port.
-4. Emit the drift table (plan band D):
-
-```
-| Derivation | Our copy (localPath) | Derived-from | Upstream now | Drift | What changed upstream |
-|------------|----------------------|--------------|--------------|-------|-----------------------|
-| <label>    | <path>               | 0.2.1        | 0.3.0        | YES   | <changelog + diff summary> |
-```
+Rules that hold for every entry:
+- The upstream mapping is **configuration, never hardcoded**: `global.derivedSkillSources` in `~/.claude/multi-agent-preferences.json`. Missing or empty -> **skip** and report "no derived-skill sources configured". Never invent a source.
+- **The plugin cache is a mirror, not the authority.** Never let the cache alone produce an "up to date" verdict; report it as **`unverified (cache only)`**. An unreachable upstream is recorded as "upstream unreachable" and the run continues.
+- Each drifted entry becomes a band-D plan item. Do not auto-apply upstream changes  -  they go through Step 5 approval like everything else, and after porting, bump the entry's `derivedFromVersion`.
 
-5. For each drifted entry, add a band-D plan item: "port upstream <plugin> <version> changes into <localPath>", with the specific skills to update. Do not auto-apply upstream changes  -  they go through Step 5 approval like everything else, and after porting, bump the entry's `derivedFromVersion`.
+Full procedure: `$HOME/.claude/multi-agent-refs/refactor/drift.md`. Read it when `global.derivedSkillSources` has at least one entry (entry schema, source resolution order, version manifest, comparison, band-D table).
 
 ## Step 0c: DEV-TOOLKIT  -  current MCP practice for the companion toolkit
 
@@ -121,44 +87,9 @@ Full procedure  -  resolution (configuration first, never a hardcoded path; skip
 
 ## Step 0d: RUN-ERRORS  -  what the pipeline actually failed on
 
-Before speculating about improvements, read what real runs already failed on. When usage logging is enabled, every terminated run appends its errors to a local ledger:
-
-```bash
-LEDGER="$HOME/.claude/logs/multi-agent/errors-ledger.jsonl"
-[ -f "$LEDGER" ] || echo "no run-error ledger yet - skip band F"
-```
-
-Each line is one run: `{ t, id, u, c, rp, ph, v, errs[] }`. The `errs[]` entries are cause tags (`<phase>:<cause>` halt reasons, `phase-<id>-failed`, `run-failed`).
-
-1. Read the ledger (best-effort; a missing or unreadable file means skip band F, not a failure).
-2. Group by error tag. For each tag compute: occurrences, distinct users affected, distinct repos, the phase it usually strikes, first + last seen, and which pipeline versions it spans (a tag that persists across versions is unfixed; one that stopped at a version is already resolved  -  do not re-raise it).
-3. Rank by `occurrences x users-affected`. A failure that recurs across users or tasks is lived evidence, not a hypothesis  -  it outranks a speculative improvement.
-4. For each surviving tag, trace it to the phase doc / script that emits that cause and propose the concrete fix.
-
-This band mirrors the admin dashboard's "Gelişim alanları" panel, but reads the local ledger so it needs no auth and works offline. If `$ARGUMENTS` names a focus area, still read the ledger  -  a recurring run error in that area is the strongest possible signal.
-
-Then read what the transcripts themselves record, which is the half no model noticed:
-
-```bash
-node "$HOME/.claude/scripts/learn-from-transcripts.mjs" --json
-```
-
-It correlates rather than interprets  -  a failed read against the read that then worked, an identical invocation that kept failing, a search that was too narrow, a call the user refused twice, a file too big to read whole. Dry run by default; `--apply` writes them to the learnings ledger as `source: transcript-mining` and renders a marked block in `CLAUDE.local.md`. Zero candidates alongside a non-zero `toolResultsExamined` means there was nothing to find; zero of both means the read is broken.
-
-Output (plan band F):
-
-```
-| # | Error tag | Occurrences | Users | Usual phase | Versions | Root cause (file) | Fix | In plan? |
-|---|-----------|-------------|-------|-------------|----------|-------------------|-----|----------|
-| 1 | 4:reviewer-json-invalid | 12 | 3 | 4 | 14.x-15.x | reviewer prompt lets prose leak | tighten schema instruction in phase-3-review.md | Yes (P0) |
-| 2 | phase-3-failed | 5 | 2 | 3 | 15.0.x | build step misses a stack toolchain | add preflight in phase-2-dev.md | Yes (P1) |
-```
-
-Rules for this band:
+Before speculating about improvements, read what real runs already failed on. When usage logging is enabled, every terminated run appends its errors to a local ledger at `$HOME/.claude/logs/multi-agent/errors-ledger.jsonl`. A missing, unreadable or empty ledger means skip band F silently  -  it is additive signal, never a gate. If `$ARGUMENTS` names a focus area, still read the ledger  -  a recurring run error in that area is the strongest possible signal. A tag that stopped recurring after a version bump is resolved: report it, do not re-raise it. Never quote a user's identity as blame.
 
-- The ledger is evidence of the past, not a spec. A tag that stopped recurring after a version bump is resolved  -  report it as resolved, do not add a plan item.
-- Never quote a user's identity as blame. The `u` field is for counting distinct affected users, not for naming anyone in the plan.
-- If the ledger is empty or absent, skip band F silently  -  it is additive signal, never a gate.
+Full procedure: `$HOME/.claude/multi-agent-refs/refactor/run-errors.md`. Read it when the ledger exists (record shape, grouping and ranking, transcript mining, band-F table).
 
 ## Step 0e: BACKLOG  -  friction this pipeline already noticed
 

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

@@ -32,7 +32,7 @@ Read `$HOME/.claude/multi-agent-refs/analysis/review.md` and execute it:
 
 ## Why it cites Locked decisions
 
-The analysis flow already declares 36 Locked decisions and two deterministic validators. A reviewer that says "I would have written this differently" gives the author nothing to act on; one that says "Locked 33: the Confluence page is in the evidence record but not in Section 21" gives them a fix and a reason. Findings that map to no rule are still allowed, but they are marked as judgement, not dressed up as a violation.
+The analysis flow already declares 37 Locked decisions and two deterministic validators. A reviewer that says "I would have written this differently" gives the author nothing to act on; one that says "Locked 33: the Confluence page is in the evidence record but not in Section 21" gives them a fix and a reason. Findings that map to no rule are still allowed, but they are marked as judgement, not dressed up as a violation.
 
 ## What it never does
 

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

@@ -0,0 +1,79 @@
+---
+description: "Audit test scenarios from a CSV against the code: mark each PRESENT, PARTIAL, ABSENT or UNCLEAR, every PRESENT backed by a file:line that resolves at HEAD. Read-only. Use when a test set or acceptance list has to be checked against what the code does."
+description-tr: "Test senaryolarını koda karşı denetler: CSV'deki (ya da CSV'ye aktarılmış Jira test setindeki) her senaryo için kodun onu nerede karşıladığını bulur ve VAR, KISMEN, YOK ya da BELİRSİZ olarak işaretler; her VAR, HEAD'de çözülen bir dosya:satır ile desteklenir. Salt-okunur."
+allowed-tools: Bash, Read, Grep, AskUserQuestion
+argument-hint: "<scenarios.csv> [--repo <path>]"
+parameters: [{"name":"scenarios","kind":"path","required":true},{"name":"--repo","kind":"path"}]
+gui: form
+destructive: false
+confirm: none
+not-for: test, manual-test, review
+---
+
+# multi-agent scenario-audit
+
+**Input**: $ARGUMENTS
+
+Checks a list of test scenarios against a repository and says, per scenario,
+whether the code implements it. The judgement is yours; the evidence rule is
+the script's. Nothing is written and nothing leaves the machine.
+
+Script: `$HOME/.claude/scripts/scenario-audit.mjs`.
+
+## Gotchas
+
+- A verdict without a resolving `file:line` is not PRESENT. `verify` turns it into UNCLEAR and says why; do not argue with it, find the line.
+- ABSENT is a claim about a search. Record the terms you searched; an ABSENT with no terms becomes UNCLEAR.
+- Scenario text is usually business language and the code is not. Search for identifiers, localization keys, endpoint paths and error codes, not for the scenario's words.
+- The audit reads HEAD. Uncommitted work is not seen; say so when the working tree is dirty.
+
+## Step 1 - Inventory
+
+The scenarios file is a CSV with an id column and a title column (`id`/`no`/`key`,
+`title`/`scenario`/`senaryo`/`başlık`; optional `steps`/`adımlar` and
+`expected`/`beklenen`). Comma or semicolon. A Jira test set is exported to this
+shape first.
+
+```bash
+node "$HOME/.claude/scripts/scenario-audit.mjs" inventory --csv "<scenarios.csv>" > /tmp/ma-scenarios.json
+```
+
+Exit 2 names the missing column. With no `--repo`, the repository is the
+current directory; confirm it in one line before searching.
+
+## Step 2 - Search
+
+For each scenario, write the code-level terms that would implement it into
+`/tmp/ma-terms.json` (`{"<id>": ["term", ...]}`), then:
+
+```bash
+node "$HOME/.claude/scripts/scenario-audit.mjs" search --terms /tmp/ma-terms.json --repo "<repo>"
+```
+
+Read the candidate lines it returns. A term nothing matched is listed under
+`missing`; try a second term before concluding anything.
+
+## Step 3 - Verdict
+
+Write `/tmp/ma-verdicts.json`: `[{id, status, citations, searched, note}]`.
+
+| Status | When | Needs |
+|---|---|---|
+| `PRESENT` | the code does what the scenario expects | `citations`: the `file:line` that does it |
+| `PARTIAL` | part of it, e.g. the happy path without the error case | `citations`, and `note` saying what is missing |
+| `ABSENT` | nothing implements it | `searched`: the terms that found nothing relevant |
+| `UNCLEAR` | the code exists but its behaviour cannot be told from reading | `note` |
+
+```bash
+node "$HOME/.claude/scripts/scenario-audit.mjs" verify --csv "<scenarios.csv>" \
+  --verdicts /tmp/ma-verdicts.json --repo "<repo>" --lang "<outputLanguage>"
+```
+
+## Step 4 - Report
+
+Print the table `verify` produced, verbatim, and its count line. Then the
+scenarios that moved to UNCLEAR during verification, with the reason. State
+which verdicts rest on a resolved citation (mechanical) and that the reading of
+the code behind them is judgement.
+
+**Stop. No issue, no comment, no worktree.**

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

@@ -56,7 +56,10 @@ Or leave it: it exits on its own when idle.
 ## What it will not do
 
 There is no route that merges, marks ready, runs a command or starts a host.
-`POST /v1/launch` validates a launch request, writes it (0600) and returns the
-argv and environment `launch.json` declares; the client starts the process.
+`POST /v1/launch` and `POST /v1/runs/{id}/resume` return the argv and
+environment `launch.json` declares; the client starts the process.
 `POST /v1/runs/{id}/answer` accepts only an option the run's pending question
-offered.
+offered. `POST /v1/runs/{id}/kill` and `POST /v1/gc` act only on a second
+request carrying the single-use confirm token the first one returned, and a
+kill never deletes the remote branch or the logs. Autopilot can be turned off
+over HTTP, never on.

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

@@ -9,6 +9,13 @@ confirm: none
 allowed-tools: Bash, Read, Write, AskUserQuestion, WebFetch
 ---
 
+## Gotchas
+
+- A token is read and written only through `~/.claude/lib/credential-store.sh`. Never echo it, never pass it on argv, never paste it back to the user.
+- A mapping in `keychainMapping` with no value in the store is not onboarded: offer the Token Save Flow, do not ask for the secret in chat.
+- Hosts are stored without a scheme (`jira.example.com`); the callers add `https://`.
+- Publishing tokens differ by registry: npmjs takes an npm token, GitHub Packages a classic PAT with `write:packages` from the account that owns the scope.
+
 ## Step 0 - What is actually wrong
 
 ```bash
@@ -89,88 +96,7 @@ command -v pdftotext >/dev/null 2>&1 || echo "pdftotext: MISSING"
 
 ### Step 1  -  Dynamic Credential Discovery
 
-Instead of checking only hardcoded key names, discover ALL user keys and intelligently map them to services. Uses `credential-store.sh list`:
-
-**1a. Discover all keys:**
-```bash
-DISCOVERED=$(~/.claude/lib/credential-store.sh list 2>/dev/null | grep -i "^${USER}" | sort -u)
-echo "$DISCOVERED"
-```
-
-**1b. Search keywords (per service):**
-
-Standard key names  -  the ones to use when creating a NEW key  -  live in `$HOME/.claude/multi-agent-refs/keychain.md` "Standard key names"; read the name for a service from there. Existing keys under other names are perfectly valid, which is what these keywords are for.
-
-| Service ID | Search Keywords |
-|------------|-----------------|
-| `jira` | `jira` |
-| `bitbucket_token` | `bitbucket` + (`token` or `access` or `pass`) |
-| `bitbucket_user` | `bitbucket` + (`user` or `name`) |
-| `github` | `github` or `gh` (exclude `ssh`) |
-| `confluence` | `confluence` |
-| `figma` | `figma` + (`token` or `pat` or `access`) + NOT `mcp` |
-| `figma_mcp` | `figma` + `mcp` |
-| `fortify` | `fortify` |
-| `graylog` | `graylog` |
-| `graylog_test` | `graylog` + `test` |
-| `firebase` | `firebase` (any variant: `sa`, `service`, `account`, `access`, `json`) |
-| `jenkins` | `jenkins` |
-| `appstore_connect_key_id` | (`appstore` or `asc` or `app_store`) + (`key` or `keyid`) |
-| `appstore_connect_issuer_id` | (`appstore` or `asc` or `app_store`) + `issuer` |
-| `appstore_connect_private_key` | (`appstore` or `asc` or `app_store`) + (`private` or `p8`) |
-| `appstore_connect_apple_id` | (`appstore` or `asc`) + (`apple` or `account` or `user`) |
-| `appstore_connect_password_item` | (`appstore` or `asc` or `altool`) + (`password` or `app_specific`) |
-| `google_play` | (`googleplay` or `google_play` or `play_console` or `play`) + (`service` or `account` or `access` or `json` or `console`), NOT `firebase` |
-
-> Multi-agent setup onboards **both** Figma tokens because the pipeline's 3-tier Figma access chain (see `$HOME/.claude/rules/figma-pipeline.md`) uses them in priority order: Tier 1 = MCP (`figma_mcp`), Tier 2 = REST PAT (`figma`), Tier 3 = user screenshot fallback. Missing either token forces a downshift; missing both leaves Tier 3 as the only path. The Tier 2 logical key is `figma`, not `figma_pat`: `figma_pat` is the pre-v13.6 name that `migrate-prefs.mjs` consolidates away, and writing a new mapping under it means the next migration deletes it.
-
-> The five App Store Connect entries are **iOS-only and optional**  -  skipping them all reports Gate 2 of `/multi-agent:store-ready` as `SKIPPED`, never as a pass. Two hold identifiers, one an email, one a keychain ITEM NAME, and `appstore_connect_private_key` the `.p8` itself; all go through the mapping layer. `google_play` is the Android-only counterpart (Step 3d). Tiers and mechanics: Step 3b and `$HOME/.claude/multi-agent-refs/setup/app-store-connect.md`.
-
-> The `firebase` entry is **optional and any-platform**. Discovery maps a stored service-account JSON like any other credential but cannot see what decides whether Crashlytics is readable: a fresh `firebase-adminsdk-*` account authenticates perfectly and holds no Crashlytics role. Step 3c measures the tier rather than assuming it.
-
-**1c. Resolution logic (per service):**
-
-For each service in the table above, follow this order:
-
-1. **Check standard key** -> `~/.claude/lib/credential-store.sh get "<standard_key>" 2>/dev/null`
-   - Found (non-empty stdout, exit 0) -> auto-map, done
-3. **Search discovered keys** -> filter `$DISCOVERED` by the service's search keywords (case-insensitive)
-   - Exactly 1 match -> show: `"Found '${matched_key}' for ${service}  -  use this? (enter=yes / n=skip)"` -> if yes, map it
-   - Multiple matches -> show numbered list, user picks:
-     ```
-     Multiple keys found for GitHub:
-       1. ${USER}_Github
-       2. ${USER}_Github_Access_Token_Old
-       3. ${USER}_Github_Access_Token
-     Select [number] or skip:
-     ```
-   - 0 keyword matches -> go to Step 4
-4. **Suggest candidates from full keychain** -> When keyword search yields 0 results, do NOT immediately mark as MISSING. Show broad candidates from `$DISCOVERED_ALL` and ask the user:
-   ```
-   No exact match found for Jira in your keychain.
-   
-   These entries might be your Jira token  -  do any look right?
-     1. MyPersonalJiraToken
-     2. work_jira_pat
-     3. JiraPAT_2024
-     n. None of these (skip)
-   
-   Select [number] or n to skip:
-   ```
-   
-   Candidate selection:
-   - Show entries that partially match the service name, common token suffixes (`token`, `pat`, `key`, `secret`, `access`, `password`), or relaxed keyword matching (substring instead of prefix)
-   - Exclude entries already mapped to other services and system entries (Apple, com.apple.*, iCloud, etc.)
-   - Cap at 10 candidates, sorted by relevance (shortest edit distance to service keywords)
-   - If 0 candidates even after broad search -> MISSING (truly not in keychain)
-
-**Important:** Steps 3-4 search the FULL `$DISCOVERED` list (both passes from 1a), not just user-prefixed entries. This catches tokens saved under any naming convention.
-
-**1d. Check preferences for existing mapping:**
-
-Before running discovery, check `prefs.global.keychainMapping`. If a mapping already exists for a service AND the mapped key still exists in Keychain -> skip discovery for that service (show as already mapped from preferences).
-
-If a previously mapped key NO LONGER exists in Keychain -> clear the stale mapping, re-run discovery for that service.
+Full procedure: `$HOME/.claude/multi-agent-refs/setup/discovery.md`. Read it for Step 1.
 
 ### Step 2  -  Show Discovery Summary + Save Mapping
 
@@ -294,131 +220,7 @@ Loop rules:
 
 ### Token Save Flow (reusable)
 
-This flow is used in TWO contexts:
-- **Setup Step 4**  -  for missing tokens during first-time onboarding
-- **Phase 0 token pre-check**  -  when a token is missing or expired (401/403) at runtime
-
-**Trigger**: token missing (`keychainMapping` is `null`) OR token expired (API returned 401/403).
-
-**Step A  -  Ask** (options depend on whether the token is missing or expired):
-
-Missing token (first-time / unmapped):
-```
-{Service} token missing.
-  Where to get it: {source URL/instructions}
-
-  [1] Add now  -  I'll generate the token and copy it
-  [2] Skip  -  I'll set it up later
-
-  Select:
-```
-
-Expired / rejected token (401 / 403 mid-run)  -  the Expired-token decision from `$HOME/.claude/multi-agent-refs/keychain.md` Rule 1:
-```
-{Service} token expired (the service returned 401/403).
-  Where to get a fresh one: {source URL/instructions}
-
-  [1] Regenerate  -  replace {KEY_NAME} in place, then retry
-  [2] Use a different token  -  map another Keychain entry, then retry
-  [3] Skip and continue  -  drop this source (halts only if the token is required for the input)
-
-  Select:
-```
-
-Render `question` + `label` + `description` in `outputLanguage`; `header` English. Names below are option semantics, not strings to print. The picked option is a choice, never the secret: the value enters via Step B clipboard.
-
-- **Skip** (missing `[2]` / expired `[3]`) → skip semantics. During setup: `keychainMapping` stays `null`. During Phase 0 / mid-run: abort that service's contribution, warn and continue if non-critical, halt if critical (e.g. Jira token for Jira input).
-- **Add now** / **Regenerate** → proceed to Step B (clipboard save). Regenerate reuses the same `{KEY_NAME}`.
-- **Use a different token** → proceed to Step B, then re-run Step C identity binding for the new entry.
-
-**Step B  -  Clipboard save** (token NEVER appears in terminal):
-
-For PAT / API key / username:
-```
-  Copy the token to your clipboard, then press Enter.
-  (Token will be read from clipboard and saved to Keychain automatically)
-
-  Press Enter when ready...
-```
-
-Pipeline runs silently  -  value is piped via stdin (`-` sentinel) so it never lands on argv / shell history:
-```bash
-pbpaste | ~/.claude/lib/credential-store.sh set "<KEY_NAME>" -
-pbcopy < /dev/null
-```
-
-(The shell driver auto-delegates to `~/.claude/scripts/keychain.py`, which writes both `-l` (label) and `-s` (service) attributes so callers using either convention find the same entry.)
-
-For JSON file (Firebase)  -  same clipboard flow, JSON content never lands in argv or shell history:
-```
-  Open the Service Account JSON, copy its FULL contents to your clipboard,
-  then press Enter.
-  (Contents are saved to the Keychain exactly as issued)
-
-  Press Enter when ready...
-```
-
-The pipeline then runs the same `pbpaste | ... set "<KEY_NAME>" -` and `pbcopy < /dev/null` as above. A key that arrives as a file (the App Store Connect `.p8`, the Google Play JSON) skips the clipboard: `set <key> - < <file>`.
-
-**Firebase repeats per project.** Teams own several Firebase projects (legacy plus redesign, staging plus prod), each with its own key, and a crash URL from the second one used to fail the `project_id` check as if it were misconfigured. After each saved key, read `project_id` from the stored JSON (never ask) and offer another round: `Saved: <project_id>. Add another Firebase project? [y/N]`.
-
-- Every key appends `{projectId, keychainKey, label?}` to `prefs.global.firebase.accounts`; the first one also fills `keychainMapping.firebase`, so a one-project setup is unchanged.
-- Keys after the first are named `${USER}_Firebase_Access_Json_<projectId>` so they cannot collide.
-- At run time `fetch-crashlytics.sh` picks the account matching the console URL's projectId, falling back to `keychainMapping.firebase`.
-
-For GitHub (special case):
-```
-  ! gh auth login
-```
-
-**Step C  -  Identity binding** (after token saved):
-
-```
-  ✓ Saved to Keychain as <KEY_NAME>
-  ✓ Clipboard cleared
-
-  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:
-```
-
-- Existing identity selected → add `{service}: <KEY_NAME>` to that identity's `servicePatMap`
-- `n` (create new) → ask name + email → create identity → add to `prefs.global.identities[]` → map token
-- First token ever (no identities exist) → skip picker, go straight to name + email
-- `bitbucket_user` is excluded from identity binding (it's a username, not a PAT)
-
-**Step D  -  Confirm + update**:
-
-```
-  ✓ Token mapped to identity: Ada Lovelace <ada@example.com>
-```
-
-Update `prefs.global.keychainMapping.{service}` with the key name.
-Update `identity.servicePatMap.{service}` with the key name.
-Update `serviceStatus.{service} = { ok: true, checkedAt: <now> }`.
-
-**→ Next: if `{service}` is `jira` / `confluence` / `bitbucket` / `fortify` / `graylog` AND the corresponding
-`prefs.global.hosts.{service}` is unset, run Step 3.5 (Host Prompt) inline before
-the Auto-routing rule below. required  -  the pipeline cannot build API URLs without
-the host. Firebase is exempt (see Step 3.5).**
-
-**Auto-routing rule** (optional, on first token per platform):
-
-If `platformIdentityRouting` has no rule for this platform yet, auto-suggest one:
-```
-  Auto-add routing rule?
-    bitbucket.example.com/* → Ada Lovelace <ada@example.com>
-    [enter=yes / n=skip]
-```
-
-This builds `platformIdentityRouting` incrementally  -  no separate Step 7 needed for most users.
-
----
+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).
 
 ### Step 3b  -  App Store Connect onboarding (iOS only, optional)
 
@@ -434,81 +236,7 @@ Runs inside Step 3, only when the target repo is Android. One entry, `google_pla
 
 ### Step 3.5  -  Host Prompt (embedded in Token Save Flow)
 
-**Not a standalone step**  -  runs inline at the end of the Token Save Flow whenever the saved token belongs to a **hosted service** (Jira, Confluence, Bitbucket, Fortify, Graylog) AND the host is not yet in `prefs.global.hosts`. Firebase tokens skip this step  -  Crashlytics is always on Google's fixed domains and `project_id` is embedded in the service-account JSON.
-
-Right after Step D (identity mapping confirmed), ask:
-
-```
-Service host  -  needed to build API URLs for this token.
-
-  {Service} host (e.g. jira.example.com): ___
-```
-
-Save to `prefs.global.hosts.{service}`. For Fortify, also ask `Fortify project version ids (optional, comma-separated - e.g. 1234,5678)` → `prefs.global.fortify.versionIds`. A ticket naming only an instance id carries no version, so the lookup silently no-ops without these; URL-referenced findings resolve either way.
-
-For Jira, **discover the project keys instead of asking the user to recall them.** The token is already saved and the host is already known, so ask Jira which projects this person actually works in - a corporate instance has thousands of projects, and a typed key is a typo waiting to route branches and new issues at the wrong board:
-
-```bash
-printf 'Authorization: Bearer %s\n' "$TOKEN" | curl -s -H @- \
-  "https://{JIRA_HOST}/rest/api/2/search?jql=assignee%3DcurrentUser()%20OR%20reporter%3DcurrentUser()%20ORDER%20BY%20updated%20DESC&fields=project&maxResults=100" \
-  | jq -r '[.issues[].fields.project | "\(.key)\t\(.name)"] | unique | .[]'
-```
-
-Present the distinct keys, most-recently-worked first, as a picker; fall back to the free-text prompt `Default Jira project key (e.g. PROJ)` when the call fails or returns nothing (no VPN, fresh account). The picked key → `prefs.global.defaultJiraKey`. From the Jira host, derive `corpDomain` (`jira.example.com` → `example.com`) and pre-fill it so the Confluence / Bitbucket prompts only need the subdomain.
-
-`defaultJiraKey` is a single global fallback, but one Jira host usually serves several repos with DIFFERENT keys, so the pass continues with a per-repo mapping. Show the repos, and let the key come from the discovered list rather than being typed again:
-
-```
-Per-repo Jira keys (optional)  -  repos whose project key differs from {defaultJiraKey}:
-
-  [ ] 1. my-ios-app        (current: PROJA)
-  [ ] 2. my-other-app      (current:  - )
-
-  Toggle repos, then pick a project for each  -  discovered: PROJA, PROJB, PROJC. Enter to skip.
-```
-
-- The repo list comes from `prefs.projects` + `recentProjects` (when Step 5 already ran); a free-text repo path is accepted for repos not discovered yet, and a free-text key for a project the search did not surface.
-- Each answer is PREPENDED to `prefs.projects[{slug}].jiraProjectKeys` (deduped, max 10 per schema). Example: `my-ios-app` → `PROJA`, `my-other-app` → `PROJB`  -  two repos on the same Jira host, two different project keys.
-- Resolution order everywhere a Jira key is needed (placeholder replacement, branch names, new-issue creation): `prefs.projects[{slug}].jiraProjectKeys[0]` first, `global.defaultJiraKey` as fallback.
-- **Re-run / update**: `/multi-agent:setup jira-keys` re-opens only this mapping without touching tokens or hosts.
-
-Resulting shape:
-
-```json
-{
-  "global": {
-    "hosts": {
-      "jira":       "jira.example.com",
-      "confluence": "confluence.example.com",
-      "bitbucket":  "bitbucket.example.com",
-      "fortify":    "ssc.example.com",
-      "graylog":    "graylog.example.com",
-      "graylogTest": "graylog-test.example.com",
-      "corpDomain": "example.com"
-    },
-    "defaultJiraKey": "PROJ"
-  }
-}
-```
-
-Placeholders `{JIRA_HOST}`, `{CONFLUENCE_HOST}`, `{BITBUCKET_HOST}`, `{FORTIFY_HOST}`, `{GRAYLOG_HOST}`, `{GRAYLOG_TEST_HOST}`, `{CORP_DOMAIN}`, `{JIRA_KEY}` in skills/commands are resolved from this block at runtime. If a host is ever missing when a phase needs it, Phase 0 prompts the same Host Prompt inline.
-
-Graylog uses a **PAT** whose API auth is HTTP Basic with the token as username and the literal `token` as password  -  no separate username entry. It is optional by the null-mapping convention: `keychainMapping.graylog` or `hosts.graylog` left `null` degrades the log fetch to empty and never blocks a run.
-
-Graylog is asked **twice**  -  test and production are separate instances, and a tester-minted trx id does not exist in production. After the production host:
-
-```
-Graylog test host (optional  -  Enter to skip): ___
-Does the test instance use a different token? [y/N]
-```
-
-Test host → `hosts.graylogTest` (`{GRAYLOG_TEST_HOST}`); skipped means production-only search, which degrades nothing. Yes to the token question runs one more Token Save Flow pass for `graylog_test`; no (default) leaves it null and the fetcher reuses the production key. Run-time order is `--env auto`: production first, test on empty or unreachable, and the payload names which answered.
-
-**Re-run / update**: `/multi-agent:setup hosts` re-opens the prompt to edit values without touching tokens.
-
-Team-sharing note: Hosts are the only corporate metadata the pipeline needs. Tokens live in macOS Keychain (encrypted, never on disk inside the repo). Preferences file lives in `~/.claude/`  -  fully outside the repo clone. A teammate cloning the repo runs `/multi-agent:setup` once; host + token prompts run naturally together.
-
----
+Full procedure: `$HOME/.claude/multi-agent-refs/setup/token-save-flow.md`. Read it for the host question inside the Token Save Flow.
 
 ### Step 3.6  -  Per-account host overrides (optional)
 
@@ -635,64 +363,7 @@ Repo identifiers in the label are the human label from `recentProjects` (basenam
 
 ### Step 7  -  Platform Identity Routing (optional)
 
-Map repo URL **glob patterns** to a named identity from `prefs.global.identities`. Phase 0 consults this map in Step 5 to auto-pick the git author and the right `servicePatMap` for the target repo  -  preventing corporate identity leakage into personal repos and vice versa.
-
-Auto-skipped if `identities` has fewer than 2 entries (single-identity case has nothing to route).
-
-**9a. Auto-suggest from `servicePatMap` ownership**
-
-For each identity, derive a default routing rule from where its PATs work:
-- Identity owns `bitbucket` PAT → propose `<bitbucket-host>/*` glob, mapped to that identity.
-- Identity owns `github` PAT → propose `github.com/<gh-username>/*` if known (from `identities[].username`), else `github.com/*`.
-- Identity owns `confluence` / `jira` only → no URL routing applies (those aren't repo origins)  -  skip.
-
-Auto-suggestions are **proposals**, not forced. User confirms or edits each one.
-
-**9b. Confirm or edit each suggested rule**
-
-```
-Step 7  -  Platform Identity Routing (optional)
-Auto-suggested rules:
-
-  1. bitbucket.{corp-domain}/*                  -> corporate    [confirm/edit/skip]
-  2. github.com/{personal-username}/*           -> personal     [confirm/edit/skip]
-  3. github.com/{org-name}/*                    -> corporate    [confirm/edit/skip]
-
-Add another rule? [Add another / Done]
-```
-
-Each rule answer:
-- `Enter` or `c` → confirm
-- `e` → edit (prompt for new glob and/or new identity name)
-- `s` → skip this rule
-- `n` (final question) → finish
-
-**9c. Save**
-
-```json
-{
-  "global": {
-    "platformIdentityRouting": {
-      "bitbucket.{corp-domain}/*": "corporate",
-      "github.com/{personal-username}/*": "personal",
-      "github.com/{org-name}/*": "corporate"
-    }
-  }
-}
-```
-
-Glob matching semantics (Phase 0 implementation):
-- `*` matches any characters except `/`
-- `**` matches any characters including `/`
-- Most-specific match wins (longer literal prefix > shorter)
-- No match → Phase 0 falls back to the interactive identity picker
-
-**9d. Skip / degrade rules**
-
-- Zero rules saved is valid  -  Phase 0 always falls back to the identity picker.
-- A rule may point to an identity name that doesn't (yet) exist in `identities`; on Phase 0 lookup, an unknown identity name surfaces as a warning and the picker is shown.
-- Step 7 is idempotent  -  re-running merges new rules; existing rules are preserved unless the user explicitly edits them.
-- Routing is **advisory**: the user can always override the auto-picked identity in Phase 0.
+Full procedure: `$HOME/.claude/multi-agent-refs/setup/identity-routing.md`. Read it for Step 7.
 
 ### Cross-Platform Notes (Step 1-9)
 
@@ -729,31 +400,7 @@ pbpaste | ~/.claude/scripts/keychain.py set "<SERVICE_NAME>" -
 
 ### Figma MCP Setup (Remote / Local question)
 
-The `figma_mcp` pass of the Step 3 loop opens with a mode question BEFORE any token is collected:
-
-```
-Figma MCP mode?
-
-  [1] Remote  -  mcp.figma.com, OAuth token (figu_)  (recommended)
-  [2] Local   -  @anthropic-ai/figma-mcp via npx, uses the Figma PAT
-```
-
-**Remote** (`figu_` OAuth token  -  generate it FOR the current user, never just point at docs):
-- No OAuth app and no client_id/secret needed: Dynamic Client Registration against `api.figma.com/v1/oauth/mcp/register` + PKCE, the browser opens, the user clicks Allow, and the resulting access + refresh token pair is saved to the credential store under a name the user confirms. Map that entry to `keychainMapping.figma_mcp` (Token Save Flow Step D applies as usual).
-- If `prefs.global.figmaMcp.remoteGeneratorScript` is set, run that script  -  it drives the whole flow end to end (registration, browser, keychain save) for the current user. Otherwise guide the flow inline.
-- Renewal is silent afterwards via `$HOME/.claude/lib/figma-mcp-refresh.sh` (refresh token). Never echo token values.
-
-**Local** (PAT-based):
-- Validates the Figma PAT against the REST API, saves it to the credential store (reusing the `figma` mapping when present), and writes the `@anthropic-ai/figma-mcp` server block into Claude Code `settings.json` `mcpServers`:
-```bash
-# stdin sentinel keeps the value out of shell history
-pbpaste | ~/.claude/scripts/keychain.py set "${USER}_Figma_Access_Token" -
-pbcopy < /dev/null
-# then: ~/.claude/settings.json -> mcpServers -> figma
-```
-- If `prefs.global.figmaMcp.localGeneratorScript` is set, run that script instead.
-
-Choosing Remote does NOT skip the `figma` PAT pass (Tier 2 still uses the PAT); choosing Local leaves `keychainMapping.figma_mcp` null and Tier 1 unavailable until Remote is onboarded.
+Full procedure: `$HOME/.claude/multi-agent-refs/setup/figma.md`. Read it for the Figma MCP question.
 
 ### Security Rules
 

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

@@ -5,6 +5,8 @@ parameters: []
 gui: button
 destructive: false
 confirm: none
+context: fork
+agent: Explore
 ---
 
 # multi-agent status  -  Task Status Dashboard