@mmerterden/multi-agent-pipeline 8.6.0

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

@@ -0,0 +1,767 @@
+---
+description: "First-run setup wizard: keychain token discovery, Git Identity onboarding, and pipeline preparation."
+allowed-tools: Bash, Read, Write, AskUserQuestion, WebFetch
+---
+
+## Setup (Credential Store + Git Identity Onboarding)
+
+Cross-platform setup — uses `$HOME/.claude/lib/credential-store.sh` to read/write secrets in the platform-native credential store:
+
+| Platform | Backend | Built-in? |
+|----------|---------|-----------|
+| macOS    | Keychain (`security`) | Yes |
+| Windows  | Credential Manager (PowerShell `CredentialManager` module) | Module install required |
+| Linux    | libsecret (`secret-tool`) | Distro package required |
+
+Run `~/.claude/lib/credential-store.sh doctor` first — it prints platform + missing dependencies with the exact install command.
+
+On macOS and Linux 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.
+
+### 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:
+
+| Axis | What it controls | Configurable? |
+|---|---|---|
+| `promptLanguage` | Interactive pickers and prompts during a pipeline run (account, project, dev-context, branch, channels, Phase 5 test, Phase 6 confirmations) | **No — fixed to `en`.** Picker UI is always English to keep tooling consistent across CLIs. |
+| `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 (discovery summaries, Token Save Flow Steps A–D, identity binding, repo picker) renders in English (per the fixed `promptLanguage`). The setup wizard's own status text and the post-setup summary render in `outputLanguage`. External payloads remain English.
+
+### Step 0.5 — Credential Backend Check
+
+Before discovery, verify the platform's credential backend is available:
+
+```bash
+~/.claude/lib/credential-store.sh doctor
+```
+
+| Output | Action |
+|--------|--------|
+| `Backend: ✓` | Continue to Step 1 |
+| Linux: `secret-tool ✗ MISSING` | Prompt: `sudo apt install libsecret-tools` (Debian/Ubuntu) or `sudo dnf install libsecret` (Fedora). Re-run setup after install. |
+| Windows: `CredentialManager ✗ MISSING` | Prompt: `Install-Module CredentialManager -Scope CurrentUser -Force` in an elevated PowerShell. Re-run setup. |
+| Platform `unknown` | Halt — credential storage cannot proceed. |
+
+### 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.
+
+### Step 1 — Dynamic Credential Discovery
+
+Instead of checking only hardcoded key names, discover ALL user keys and intelligently map them to services. Uses cross-platform `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. Standard key names (convention):**
+
+These are the RECOMMENDED key names. When creating NEW keys, use these. But existing keys under different names are perfectly valid — the discovery step will find them.
+
+| Service ID | Standard Key Name | Search Keywords |
+|------------|------------------|-----------------|
+| `jira` | `${USER}_Jira_Access_Token` | `jira` |
+| `bitbucket_token` | `${USER}_Bitbucket_Access_Token` | `bitbucket` + (`token` or `access` or `pass`) |
+| `bitbucket_user` | `${USER}_Bitbucket_Username` | `bitbucket` + (`user` or `name`) |
+| `github` | `${USER}_Github_Access_Token` | `github` or `gh` (exclude `ssh`) |
+| `confluence` | `${USER}_Confluence_Access_Token` | `confluence` |
+| `figma` | `${USER}_Figma_Access_Token` | `figma` + NOT `mcp` |
+| `figma_mcp` | `${USER}_Figma_Mcp_Access_Token` | `figma` + `mcp` |
+| `fortify` | `${USER}_Fortify_Access_Token` | `fortify` |
+| `firebase` | `${USER}_Firebase_Access_Json` | `firebase` (any variant: `sa`, `service`, `account`, `access`, `json`) |
+| `jenkins` | `${USER}_Jenkins_Access_Token` | `jenkins` |
+
+**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.
+
+### 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
+```
+
+Non-standard key names are perfectly valid — the mapping handles resolution. No rename or migration is offered.
+
+Save the resolved mapping to preferences:
+```json
+{
+  "global": {
+    "keychainMapping": {
+      "jira": "${USER}_Jira_Access_Token",
+      "bitbucket_token": "${USER}_Bitbucket_Access_Token",
+      "bitbucket_user": "${USER}_Bitbucket_Username",
+      "github": "${USER}_Github",
+      "confluence": null,
+      "figma": "${USER}_Figma_Access_Token",
+      "figma_mcp": "${USER}_Figma_Mcp_Access_Token",
+      "fortify": null,
+      "firebase": "${USER}_Firebase_Access_Json",
+      "jenkins": null
+    }
+  }
+}
+```
+
+`null` = not mapped (missing or skipped). Pipeline phases read this mapping to retrieve tokens dynamically — never hardcoded key names.
+
+### 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.
+
+### Step 3 — Interactive token onboarding (for missing tokens)
+
+Git identities are NOT asked as a separate step. They are learned when tokens are added in Step 4 (Token Save Flow). 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.
+
+For each MISSING service, run the **Token Save Flow** below. When creating new tokens, use the **standard key name** from Step 1b table.
+
+---
+
+### 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**:
+
+```
+{Service} token {missing|expired}.
+  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:
+```
+
+- `[2]` → skip. During setup: `keychainMapping` stays `null`. During Phase 0: abort that service's pre-check, warn and continue if non-critical, halt if critical (e.g. Jira token for Jira input).
+- `[1]` → proceed to Step B.
+
+**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>" "$(cat)"
+pbcopy < /dev/null
+```
+
+(The shell driver auto-delegates to `~/.claude/scripts/keychain.py` on macOS / Linux, which writes both `-l` (label) and `-s` (service) attributes so callers using either convention find the same entry.)
+
+For JSON file (Firebase):
+```
+  Download the JSON file, then press Enter.
+  (File will be base64-encoded and saved to Keychain automatically)
+
+  Path to JSON file [~/Downloads/firebase-sa.json]: ___
+```
+
+Pipeline runs silently:
+```bash
+~/.claude/lib/credential-store.sh set "<KEY_NAME>" "$(base64 < <PATH>)"
+```
+
+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` 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 skipped here (host is always `console.firebase.google.com` /
+`firebasecrashlytics.googleapis.com`); the SA JSON itself carries `project_id`.**
+
+**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.
+
+---
+
+### 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) 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 SA 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 Jira specifically, also ask for the default project key (the token is useless without one for new-issue creation):
+
+```
+Default Jira project key (e.g. PROJ): ___
+```
+
+Save to `prefs.global.defaultJiraKey`. From Jira host, derive `corpDomain` (e.g. `jira.example.com` → `example.com`) and pre-fill it so the Confluence / Bitbucket prompts only need the subdomain.
+
+Resulting shape:
+
+```json
+{
+  "global": {
+    "hosts": {
+      "jira":       "jira.example.com",
+      "confluence": "confluence.example.com",
+      "bitbucket":  "bitbucket.example.com",
+      "fortify":    "ssc.example.com",
+      "corpDomain": "example.com"
+    },
+    "defaultJiraKey": "PROJ"
+  }
+}
+```
+
+Placeholders `{JIRA_HOST}`, `{CONFLUENCE_HOST}`, `{BITBUCKET_HOST}`, `{FORTIFY_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.
+
+**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.
+
+---
+
+### 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.
+
+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[]`:
+
+```json
+{
+  "global": {
+    "accounts": [
+      { "id": "personal", "jiraHost": "personal.atlassian.net" },
+      { "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`.
+
+**Re-run / update**: `/multi-agent:setup accounts` opens the editor for this block without re-running token discovery.
+
+---
+
+### 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 7 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
+```
+
+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. Without this, every task types the repo path by hand; with this, the picker shows a curated list of repos the user has been active in.
+
+Three sources merge into one flat list. Each source is independent — any one failing does NOT block the others.
+
+**Prompt:**
+```
+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)
+```
+
+**7a. Local scan** — `$HOME` depth-3, repo markers
+
+```bash
+find "$HOME" -maxdepth 3 -type d -name ".git" 2>/dev/null | while read gitdir; do
+  repo_dir="$(dirname "$gitdir")"
+  origin="$(git -C "$repo_dir" config --get remote.origin.url 2>/dev/null)"
+  last="$(git -C "$repo_dir" log -1 --format=%cI 2>/dev/null)"
+  printf '%s\t%s\t%s\n' "$repo_dir" "$origin" "$last"
+done
+```
+
+Auxiliary markers (recorded but not required): `*.xcworkspace`, `*.xcodeproj`, `Podfile`, `Package.swift`, `package.json`, `pom.xml`, `build.gradle`. Their presence tags the repo as iOS/macOS, Cocoapods, SPM, Node, Maven, Gradle in the picker.
+
+**7b. Bitbucket scan** — last 90 days active
+
+Runs only if `keychainMapping.bitbucket_token` is non-null AND `serviceStatus.bitbucket.ok === true` (or cache older than `settings.serviceStatusCacheSeconds`, re-ping first).
+
+Bitbucket Data Center (self-hosted) — the host comes from `prefs.global.bitbucketHost` (or prompts once if unset; NEVER hardcoded):
+```bash
+BB_HOST="$(jq -r '.global.bitbucketHost // empty' "$PREFS_FILE")"
+BB_USER="$(~/.claude/lib/credential-store.sh get "$(jq -r '.global.keychainMapping.bitbucket_user' "$PREFS_FILE")" 2>/dev/null)"
+BB_TOK="$(~/.claude/lib/credential-store.sh get "$(jq -r '.global.keychainMapping.bitbucket_token' "$PREFS_FILE")" 2>/dev/null)"
+CUTOFF_MS=$(( ( $(date +%s) - 7776000 ) * 1000 ))   # 90 days
+curl -sfS -u "$BB_USER:$BB_TOK" \
+  "https://${BB_HOST}/rest/api/1.0/repos?permission=REPO_WRITE&limit=200" \
+  | jq -r --argjson cutoff "$CUTOFF_MS" '
+      .values[] | select((.updatedDate // 0) >= $cutoff) |
+      { slug: "\(.project.key)/\(.slug)", clone: (.links.clone[] | select(.name=="http") | .href) }'
+```
+
+Bitbucket Cloud — swap to `https://api.bitbucket.org/2.0/repositories/{workspace}?role=member&sort=-updated_on`.
+
+**7c. GitHub scan** — owner + collaborator, push in last 90 days
+
+Runs only if `keychainMapping.github` is non-null AND `serviceStatus.github.ok === true`.
+
+```bash
+GH_TOK="$(~/.claude/lib/credential-store.sh get "$(jq -r '.global.keychainMapping.github' "$PREFS_FILE")" 2>/dev/null)"
+CUTOFF_ISO="$(date -u -v-90d +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u -d '90 days ago' +%Y-%m-%dT%H:%M:%SZ)"
+# gh CLI path (preferred when available)
+gh api --paginate 'user/repos?affiliation=owner,collaborator&sort=pushed&per_page=100' \
+  -q ".[] | select(.pushed_at > \"$CUTOFF_ISO\") | {full: .full_name, clone: .clone_url}"
+# Fallback without gh:
+curl -sfS -H "Authorization: Bearer $GH_TOK" \
+  'https://api.github.com/user/repos?affiliation=owner,collaborator&sort=pushed&per_page=100'
+```
+
+**7d. Merge by origin URL**
+
+Normalize clone URLs (strip `git@`, `https://`, trailing `.git`) to a canonical `host/owner/repo` key. Deduplicate:
+- Local + remote match on canonical key → single entry with `path = <local>`, `platform = <remote source>`.
+- Remote-only match → entry with `path: null` (user clones on first use from Phase 0).
+- Local-only (no remote clone URL matches) → kept as-is, `platform: "local"`.
+
+**7e. Multi-select picker**
+
+```
+Discovered 24 active repos (local + remote ≤ 90 days):
+
+  [ ]  1. Booking               ~/dev/Booking              bitbucket   iOS · SPM
+  [ ]  2. UIComponents          ~/dev/UIComponents         bitbucket   iOS · SPM
+  [ ]  3. multi-agent-pipeline  ~/multi-agent-pipeline     github      Node
+  [ ]  4. dotfiles              (not cloned)               github      —
+  [ ]  5. backend-services      ~/work/backend-services    bitbucket   Maven
+  ...
+
+  Toggle with numbers (e.g. "1 3 4"), 'all', 'none', or Enter to skip.
+  Selected repos become defaults in the Phase 0 project picker.
+```
+
+**7f. Save to preferences**
+
+```json
+{
+  "global": {
+    "recentProjects": [
+      {"path": "~/dev/Booking",            "label": "Booking",            "lastUsed": "2026-04-15T21:08:00Z"},
+      {"path": "~/dev/UIComponents",       "label": "UIComponents",       "lastUsed": "2026-04-15T21:08:00Z"},
+      {"path": "~/multi-agent-pipeline",   "label": "multi-agent-pipeline","lastUsed": "2026-04-15T21:08:00Z"}
+    ],
+    "serviceStatus": {
+      "bitbucket": {"ok": true, "checkedAt": "2026-04-15T21:08:00Z"},
+      "github":    {"ok": true, "checkedAt": "2026-04-15T21:08:00Z"}
+    }
+  }
+}
+```
+
+Entries are objects (not bare strings). The schema `recentProjects.items` is a `oneOf` — both shapes validate, but v2.1.0 writes objects so `lastUsed` + `label` are first-class.
+
+**7g. Skip / degrade rules**
+
+- Source failure (network, VPN, 401, rate-limit) skips that source silently; the others still run. Failure is recorded in `serviceStatus.{service} = { ok: false, checkedAt: <now>, reason: <short> }` so Phase 0 can also read that cache.
+- If all three sources yield zero hits, Step 5 is a no-op — the picker in Phase 0 falls back to manual path entry.
+- Discovery is **never destructive**: it never modifies git state, never writes outside `PREFS_FILE`.
+- Step 5 is idempotent. Re-running it refreshes `recentProjects` and `serviceStatus` but preserves user-curated entries unless explicitly deselected.
+
+### 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: Booking, UIComponents.
+
+Save this combo for one-tap selection in Phase 0?
+  Group name (Enter for auto): [Booking + 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": "Booking + UIComponents",
+        "repos": ["~/dev/Booking", "~/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.
+
+**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).
+
+### 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? [y/N]
+```
+
+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.
+
+### Cross-Platform Notes (Step 1-9)
+
+The credential store is platform-agnostic — every read/write goes through `~/.claude/lib/credential-store.sh`, which dispatches to the right backend (`security` on macOS, `secret-tool` on Linux, PowerShell `CredentialManager` on Windows). On macOS / Linux the shell driver delegates to `~/.claude/scripts/keychain.py` for deterministic behaviour. You almost never need the platform-native commands directly.
+
+Clipboard helpers (`pbpaste`, `pbcopy`) are macOS-specific — for Copilot CLI on Linux substitute:
+
+| macOS command | Linux equivalent | Notes |
+|---|---|---|
+| `pbpaste` | `xclip -selection clipboard -o` (X11) or `wl-paste` (Wayland) | Install with `apt install xclip` or `apt install wl-clipboard` |
+| `pbcopy < /dev/null` | `xclip -selection clipboard < /dev/null` or `wl-copy --clear` | Same intent: clear clipboard after token paste |
+
+If you need to bypass the helper (debugging, raw inspection), the underlying platform commands are documented at the top of `pipeline/lib/credential-store.sh`. Otherwise stay on the helper — it keeps secrets off argv (stdin sentinel `-`) and writes both `-l` and `-s` attributes on macOS.
+
+If no backend is available, setup falls back to a plain-text prompt + a warning that the token is **not persisted** — pipeline phases will re-ask each session.
+
+### Token -> Source Mapping
+
+Standard key names (used when creating NEW tokens). Discovery may find existing keys under different names — that's fine, the mapping in preferences handles it.
+
+| Service ID | Standard Key Name | Type | Where to Get |
+|------------|------------------|------|---------------|
+| `jira` | `${USER}_Jira_Access_Token` | PAT | Jira -> Profile -> Personal Access Tokens (VPN required) |
+| `bitbucket_token` | `${USER}_Bitbucket_Access_Token` | App Password | Bitbucket -> Personal settings -> App passwords |
+| `bitbucket_user` | `${USER}_Bitbucket_Username` | Plain text | Bitbucket profile username |
+| `github` | `${USER}_Github_Access_Token` | PAT | GitHub Settings -> Tokens (scopes: repo, read:org, project) |
+| `confluence` | `${USER}_Confluence_Access_Token` | PAT | Confluence -> Profile -> Personal Access Tokens (VPN required) |
+| `figma` | `${USER}_Figma_Access_Token` | PAT | Figma Developer Settings (max 90 days) |
+| `figma_mcp` | `${USER}_Figma_Mcp_Access_Token` | OAuth | Automatic via Claude Code Figma MCP remote auth |
+| `fortify` | `${USER}_Fortify_Access_Token` | API Token | Fortify SSC -> Token Management (VPN required) |
+| `firebase` | `${USER}_Firebase_Access_Json` | Firebase JSON (base64) | Firebase Console -> Project settings -> Service accounts -> Generate new private key. Project id is parsed from the decoded JSON — no separate entry. |
+| `jenkins` | `${USER}_Jenkins_Access_Token` | API Token | Jenkins -> User -> Configure -> API Token |
+| — | Git Identities | JSON (preferences) | Stored in `$HOME/.claude/multi-agent-preferences.json` — not Keychain |
+
+### Inline Token Save Pattern
+
+All tokens go through `~/.claude/lib/credential-store.sh`, which auto-delegates to the deterministic Python helper (`~/.claude/scripts/keychain.py`) on macOS / Linux and to the PowerShell `CredentialManager` module on Windows. The Python path writes both `-l` (label) and `-s` (service) attributes so existing manually-added entries with either convention remain findable.
+
+```bash
+# PAT / API Key (from clipboard)
+pbpaste | ~/.claude/lib/credential-store.sh set "<SERVICE_NAME>" "$(cat)"
+pbcopy < /dev/null  # clear clipboard
+
+# Plain text (direct value)
+~/.claude/lib/credential-store.sh set "<SERVICE_NAME>" "<VALUE>"
+
+# JSON file (base64 encode)
+~/.claude/lib/credential-store.sh set "<SERVICE_NAME>" "$(base64 < /path/to/file.json)"
+
+# Read
+~/.claude/lib/credential-store.sh get "<SERVICE_NAME>"
+
+# Decode JSON
+~/.claude/lib/credential-store.sh get "<SERVICE_NAME>" | base64 -d
+```
+
+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>" -
+```
+
+### Figma MCP Setup (optional)
+
+Figma MCP works in two modes:
+
+**Remote MCP** (Claude Code built-in):
+- Automatic — comes as `claude_ai_Figma` in Claude Code settings.json
+- If token renewal needed: re-auth from within Claude Code
+
+**Local MCP** (@anthropic-ai/figma-mcp package, with PAT):
+```bash
+# 1. Save PAT to keychain (stdin sentinel keeps the value out of shell history)
+pbpaste | ~/.claude/scripts/keychain.py set "${USER}_Figma_Access_Token" -
+pbcopy < /dev/null
+
+# 2. Add MCP to Claude Code settings.json
+# ~/.claude/settings.json -> mcpServers -> figma
+```
+
+### Security Rules
+
+- 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
+
+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"
+```
+
+All tokens are optional — pipeline will ask for any needed token at Phase 0. Setup only does pre-preparation.