@mmerterden/multi-agent-pipeline 8.6.0

package/pipeline/commands/multi-agent/refs/phases/phase-0-init.md

@@ -0,0 +1,481 @@
+### Phase 0: Init
+
+> **TLDR** — 8 sequential steps: load prefs → parse input (Jira/GitHub/free-text) → select project → detect remote + pick base branch → optional design input → branch name → git identity → instruction files → create worktree/local branch + agent-state.json. Every input type (Jira URL, GitHub issue, free-text) flows through the same 8 steps.
+
+#### Step −1 — Bootstrap the cross-CLI tracker (FIRST thing in every run)
+
+Before anything else — initialize the visual tracker so the user sees the pipeline's shape immediately. This is the **only** progress signal Copilot CLI users get; Claude users also get native TaskCreate tiles.
+
+```bash
+TASK_ID="${INPUT_TASK_ID:-pipeline-$(date +%Y%m%d-%H%M%S)}"
+pipeline/scripts/phase-tracker.sh init "$TASK_ID"
+for p in 0:Init 1:Analysis 2:Planning 3:Dev 4:Review 5:Test 6:Commit 7:Report; do
+  pipeline/scripts/phase-tracker.sh add "${p%%:*}" "${p#*:}"
+done
+pipeline/scripts/phase-tracker.sh update 0 in_progress
+```
+
+If `INPUT_TASK_ID` isn't known yet (free-text, project not selected), use a placeholder; rename later via `mv` once parsed in Step 1.
+
+Every subsequent phase (1-7) MUST call `phase-tracker.sh update <N> in_progress` on entry and `phase-tracker.sh update <N> completed|failed|skipped` on exit. Sub-phase milestones use `phase-tracker.sh sub <N> <subN> "<name>" <status>`. See `commands/multi-agent/refs/phases.md` "Visual Phase Tracker" for the full contract.
+
+##### TaskCreate ordering on Claude Code (strict)
+
+On Claude Code, fire all `TaskCreate` calls in strict phase-number order (0 → 7) BEFORE any `TaskUpdate`. Full contract: `refs/tracker-contract.md` § "TaskCreate ordering (strict)".
+
+---
+
+#### Step 0 — Load Preferences
+
+Read preferences: `PREFS_FILE="$HOME/.claude/multi-agent-preferences.json"` (if missing, start with `{"projects": {}, "global": {}}`).
+
+**Apply language preference IMMEDIATELY** (before any status output):
+
+```bash
+OUTPUT_LANG=$(jq -r '.global.outputLanguage // "en"' "$PREFS_FILE" 2>/dev/null || echo en)
+```
+
+From this point on, every assistant-authored conversational line (status updates, findings, phase headers, summaries, error explanations) renders in `$OUTPUT_LANG`. `AskUserQuestion` payloads stay English. External payloads stay English. See `refs/rules.md` "Language Application" for the full contract. Skipping this step is the failure mode where the user sees an English wall of text in a Turkish session.
+
+**First-run guard**: After loading prefs, check if `keychainMapping` has at least one non-null value. If ALL values are null (template defaults — setup never ran), show:
+```
+⚠ No keychain tokens mapped. Run /multi-agent setup first to discover
+  and map your tokens. Without this, the pipeline cannot authenticate
+  with Jira, Bitbucket, GitHub, or other services.
+
+  → /multi-agent setup    (interactive, ~2 min)
+```
+Then STOP Phase 0 — do not proceed with a broken token state. This prevents the user from hitting auth errors deep in Phase 1-6 and wondering why.
+
+**Preferences schema** — see `prefs.schema.json` for full definition. Key paths: `projects[{name}]` (branches, lastIdentity, jiraProjectKeys, jiraTeams, jiraComponents, jiraVersions, confluenceUrls, remoteType, jiraTeamFieldId, taskCount, lastUsed) + `global` (identities, keychainMapping, defaultJiraKey, jiraCommentDefault, confluenceDefault, recentProjects, recentBranches, recentGroups, platformIdentityRouting, serviceStatus, settings, triageCrossCheck, promptLanguage).
+
+**Key design**: Every field is an **array of all historical values** (most recent first) → "recently used" list.
+
+**Token resolution rule**: ALWAYS check `prefs.global.keychainMapping.<service_id>` first for the key name — this holds the user's actual Keychain key name (which may differ from the standard convention). Fall back to standard key name ONLY when setup has never run (mapping absent). The standard fallback exists as a safety net, not as the primary path. Service IDs: `jira`, `bitbucket_token`, `bitbucket_user`, `github`, `confluence`, `figma`, `figma_mcp`, `fortify`, `firebase`, `jenkins`.
+
+**Jira project key resolution** (first match wins):
+
+1. `prefs.projects[{project}].jiraProjectKeys[0]` — project-specific
+2. `prefs.global.defaultJiraKey` — global default
+3. Ask user → save to `prefs.global.defaultJiraKey`
+
+Used for: input parsing, branch naming, commit messages.
+
+**UX pattern**: Show `Recent: → {value}` suggestion from history, numbered alternatives, enter to accept. No history → skip suggestion line.
+
+**Save rule**: After EVERY selection, append chosen value to relevant array (dedup, most recent first, max 10). Save prefs after Phase 0 and Phase 7.
+
+**Recents update map** (which selection writes to which prefs path):
+
+| Selection event | Prefs path | Shape | Cap |
+|---|---|---|---|
+| Project picked (Step 2) | `global.recentProjects` | `[{path, label, count, lastUsed}]` | 20 |
+| Multi-repo group picked or saved (Step 2) | `global.recentGroups` | `[{label?, repos[], count, lastUsed}]` | 10 |
+| Branch picked (Step 3) | `global.recentBranches[{projectKey}]` | `[{name, lastUsed}]` (TTL `settings.branchTtlDays`, default 15d) | implicit (TTL prunes) |
+| Service ping (any external API call) | `global.serviceStatus[{service}]` | `{ok, checkedAt, reason?}` (TTL `settings.serviceStatusCacheSeconds`, default 300s) | n/a |
+| Git identity routed (Step 6a) | `projects[{name}].lastIdentity` | int (index into `global.identities`) | n/a |
+
+All updates are O(1) — read-modify-write on the in-memory `prefs` object; single atomic write at the end of Phase 0 (and again at Phase 7).
+
+#### Step 1 — Parse Input
+
+**Branch from input**: If the user provided a branch name after the issue reference (space-separated), store as `baseBranch` and skip Step 3. Otherwise Step 3 asks interactively.
+
+Classify and fetch external data:
+
+**GitHub Issue URL** (`https://github.com/org/repo/issues/N`):
+
+1. Extract org, repo, issueNumber from URL
+2. `gh issue view {N} -R {org}/{repo} --json title,body,labels,assignees`
+3. Scan body for Jira ID (`{JIRA_KEY}-XXXXX`) → store as jiraId. Multiple → use FIRST. **No Jira ID** → apply the **GitHub-issue Jira auto-create** policy below; result is either a newly created Jira (`jiraId` stored + GitHub issue body updated with the link) or an explicit "no Jira" decision (branch uses `feature/GH{issueNo}-{kebab}`). See `refs/issue-jira-triad.md` for the full policy, including autopilot behaviour and the `prefs.global.autoJiraFromGithubIssue` preference.
+4. Scan body for Figma URL (`figma.com/design/...`) → store as figmaUrl
+5. Auto-detect project: check `$HOME/{repo}` exists → skip Step 2
+
+**GitHub Issue #** (`#316` or `316`):
+
+1. Store issueNumber — repo determined after project selection (Step 2)
+2. After selection: `git remote get-url origin` → extract org/repo → fetch as above
+
+**Jira URL** (`https://{JIRA_HOST}/browse/{jiraId}`):
+
+1. Extract ID, fetch via Jira API (resolve token via keychainMapping):
+   ```bash
+   JIRA_KEY=$(jq -r '.global.keychainMapping.jira // empty' "$PREFS_FILE")
+   [ -z "$JIRA_KEY" ] && JIRA_KEY="${USER}_Jira_Access_Token"
+   JIRA_TOKEN=$(~/.claude/lib/credential-store.sh get "$JIRA_KEY" 2>/dev/null)
+   curl -s -H "Authorization: Bearer $JIRA_TOKEN" \
+     "https://{JIRA_HOST}/rest/api/2/issue/{jiraId}?fields=summary,issuetype,status"
+   ```
+2. Extract: summary, issueType (Bug/Story/Task/Feature)
+
+**Jira ID** (`PROJ-XXXXX`): Same as Jira URL but ID directly available.
+
+**Free-text**:
+
+1. Store as description. No external fetch.
+2. After project selection (Step 2), ask: `Want to create a Jira issue for this task? (y/n)`
+
+**If yes → Interactive Jira Issue Creation** (resolve `JIRA_TOKEN` via keychainMapping):
+
+Sequential prompts (standard UX pattern with Recent suggestion): Project Key → Issue Type → Summary → Target Version → Team → Component/s → Priority → Description. All selections saved to `prefs.projects[{project}]`. Create via `POST $JIRA_BASE/issue`; team uses custom field (discover via `/field` API, cache in `jiraTeamFieldId`).
+
+**If no → continue without Jira.** Branch uses `feature/{short-kebab}` or `bugfix/{short-kebab}`.
+
+**Token pre-check** (after parsing): Jira input → resolve key via `prefs.global.keychainMapping.jira`, verify token with a lightweight API call (e.g. `GET /myself`). GitHub input → verify `gh auth status`. On failure (missing key, 401, 403) → run the **Token Save Flow** from `setup.md` inline. This is the same clipboard-based flow used during setup — token never appears in terminal. If user skips and the token is critical for the input type (e.g. Jira token for Jira input), halt Phase 0.
+
+**VPN connectivity check**: Test VPN-dependent services (Jira, Bitbucket, Confluence, Fortify) with `curl --connect-timeout 3`. If unreachable, warn and offer to continue. Fallback: Jira → manual input, Bitbucket → `git push` only, Confluence → skip Phase 7, Fortify → skip scan. Cache in `agent-state.json` → `"vpnServices": {"jira": true, ...}`.
+
+#### Step 1b — URL Enrichment (catalogue + targeted deep fetches)
+
+After Step 1 fetches the Jira description (or free-text input), every URL in the text gets classified and catalogued. Targeted deep fetches (Crashlytics, Fortify) run when the matching link type is present; the rest (Swagger, Confluence, Figma, generic doc) are catalogued so Phase 1 (Analysis) can consume them via the typed fetchers documented in `refs/channels/*.md`.
+
+##### Step 1b.0 — Extract context links (always runs)
+
+Pipe the description text through `~/.claude/lib/context-link-extractor.sh` and store the result on the state:
+
+```bash
+printf '%s' "$DESCRIPTION_TEXT" \
+  | ~/.claude/lib/context-link-extractor.sh \
+  > /tmp/context-links-${TASK_ID}.json
+
+# Persist into agent-state.json under state.contextLinks
+jq --slurpfile links /tmp/context-links-${TASK_ID}.json \
+   '.contextLinks = $links[0]' \
+   "$STATE_FILE" > "$STATE_FILE.tmp" && mv "$STATE_FILE.tmp" "$STATE_FILE"
+```
+
+Output schema (one array entry per URL — full contract in `~/.claude/lib/context-link-extractor.sh`):
+
+```jsonc
+"contextLinks": [
+  { "type": "swagger",     "url": "<url>", "metadata": { "format": "json|yaml|unknown" } },
+  { "type": "confluence",  "url": "<url>", "metadata": { "host": "<host>", "pageId": "<id|null>", "spaceKey": "<key|null>" } },
+  { "type": "crashlytics", "url": "<url>", "metadata": { "projectId": "...", "platform": "ios|android", "bundle": "...", "issueId": "...", "sessionId": "<id|null>" } },
+  { "type": "fortify",     "url": "<url>", "metadata": { "host": "<host>", "projectId": "<id|null>" } },
+  { "type": "figma",       "url": "<url>", "metadata": { "kind": "design|make|board|slides", "fileKey": "...", "nodeId": "<id|null>" } },
+  { "type": "generic-doc", "url": "<url>", "metadata": { "host": "<host>", "kind": "notion|google-docs|gist|github-doc" } }
+]
+```
+
+The catalogue is the single source of truth for downstream phases — they read `state.contextLinks[]` and dispatch per `type`. The extractor is deterministic: same input → same output, no network calls, no auth.
+
+##### Step 1b.1 — Firebase Crashlytics deep fetch (runs when `type == "crashlytics"` present in `state.contextLinks[]`)
+
+URL pattern (caught by the extractor): `console.firebase.google.com/(u/[0-9]+/)?project/<projectId>/crashlytics/app/(ios|android)(:|%3A)<bundleOrPackage>/issues/<issueId>(/sessions/<sessionId>)?`
+
+- Host is fixed (`console.firebase.google.com`); no `hosts.firebase` pref needed.
+- Token resolution: `prefs.global.keychainMapping.firebase` → `~/.claude/lib/credential-store.sh get "<key>" | base64 -d` → Service Account JSON. `project_id` read from decoded JSON — verify it matches the `<projectId>` from the URL; mismatch → warn, skip enrichment.
+- Exchange the SA JSON for a short-lived GCP access token (scope `https://www.googleapis.com/auth/firebase https://www.googleapis.com/auth/cloud-platform`) using `google-auth` (Python) or an inline JWT exchange (OpenSSL sign → `https://oauth2.googleapis.com/token`). Cache in-memory for the pipeline run only — never persist.
+- Fetch crash detail: `GET https://firebasecrashlytics.googleapis.com/v1alpha/projects/<projectId>/apps/<appId>/issues/<issueId>` (issue summary + top device + OS + impacted users + top stack frame). If `sessionId` present, also fetch `/sessions/<sessionId>` for the full session timeline.
+- Store as `state.crashContext = { projectId, appId, issueId, title, subtitle, impactedUsers, topDevices[], topOS[], topStackFrame, sessionTimeline?, fetchedAt }`.
+- Phase 1 Analysis prepends `state.crashContext` to the agent prompt under a **Known Crash Context** section (do not rediscover, use as ground truth).
+- Soft-fail: any network/auth error → log warning, continue pipeline without enrichment (ticket still gets manually analysed).
+
+##### Step 1b.2 — Fortify SSC deep fetch (runs when `type == "fortify"` present in `state.contextLinks[]`)
+
+URL pattern (caught by the extractor): `https://<prefs.global.hosts.fortify>/ssc/html/(ssc/)?version/<versionId>(/.*)?(#/version/<versionId>)?(/audit|/issues|/artifacts)?(\?issue=<issueId>)?` (plus the short-link variant `/ssc/html/ssc/version/<versionId>/fix/<issueInstanceId>`).
+
+- Host comes from `prefs.global.hosts.fortify` (collected during Token Save Flow Step 3.5). URL host must match, else warn and skip (protects against pasting another company's Fortify URL by accident).
+- Token resolution: `prefs.global.keychainMapping.fortify` → `~/.claude/lib/credential-store.sh get "<key>"` → API token. Auth header: `Authorization: FortifyToken <base64(token)>` (legacy tokens) or `Bearer <token>` (scoped tokens) — try Bearer first, fall back to FortifyToken on 401.
+- Fetch finding detail (VPN required; respect `vpnServices.fortify`):
+  - Version: `GET /ssc/api/v1/projectVersions/<versionId>` → name, project name, current issue count.
+  - Issue list / single issue: if `issueInstanceId` in URL → `GET /ssc/api/v1/projectVersions/<versionId>/issues?q=issueInstanceId:"<id>"&fields=id,issueName,friority,fullFileName,lineNumber,analyzer,kingdom`. Otherwise fetch top open issue of the version.
+  - Issue details + recommendation: `GET /ssc/api/v1/issueDetails/<issueId>` → description, recommendation, code snippet (if the artifact is retained).
+- Store as `state.fortifyFinding = { host, versionId, versionName, projectName, issueId?, issueName?, severity, friority, kingdom, analyzer, file, line, description, recommendation, codeSnippet?, fetchedAt }`.
+- Phase 2 Planning injects `state.fortifyFinding` into the architectural-review prompt under a **Known Security Finding** section, and the generated task breakdown includes a task addressing the finding (naming convention: `sec(fortify-<issueId>): <issueName> at <file>:<line>`).
+- Soft-fail: 401 → re-run Token Save Flow for `fortify`; 403 → warn and skip; network timeout → respect VPN fallback (skip enrichment, mark `state.fortifyFinding = { skipped: "vpn-unreachable" }`).
+
+##### Step 1b.3 — Other link types (catalogued only at Phase 0; fetched at Phase 1)
+
+For `swagger`, `confluence`, `figma`, `generic-doc` entries in `state.contextLinks[]`, no Phase 0 fetch runs. The entries pass through to Phase 1, which dispatches the matching fetcher (Block B work: `fetch-swagger.sh`, `fetch-confluence.sh`, etc.). Until those fetchers land, the entries are surfaced in Phase 1 context as "referenced but not fetched — agent should treat the URL as an authoritative external source and read it directly when relevant."
+
+**Jira project key addendum**: Support multi-tenant Jira — `prefs.projects[{project}].jiraProjectKeys[]` is already a list. When Step 1 extracts a Jira key from input, `upsert` it at the head (dedup, cap 10). Sibling keys for the same project (e.g. one key per team or tracker board) coexist; `prefs.global.defaultJiraKey` is the fallback for ambiguous free-text input only.
+
+**Log line shape** (progress contract):
+
+```
+→ context links: total=<N>, by-type={swagger:<n>, confluence:<n>, crashlytics:<n>, fortify:<n>, figma:<n>, generic-doc:<n>}
+→ URL deep fetch: crashlytics=<hit|miss|skipped>, fortify=<hit|miss|skipped>
+```
+
+Two lines emit at the end of Step 1b. The first reports the catalogue from 1b.0 (always runs). The second reports the deep-fetch outcomes from 1b.1 / 1b.2 — `miss` = URL type not present in catalogue (normal), `skipped` = URL present but auth/VPN/mismatch skipped the fetch, `hit` = URL-derived context stored in state.
+
+#### Step 2 — Project Selection
+
+Scan `$HOME` (maxdepth 2) for project markers (`.xcodeproj`, `Package.swift`, `build.gradle`, `package.json`, `requirements.txt`, `go.mod`, `Cargo.toml`, `pom.xml`), excluding `DerivedData`, `node_modules`, `.build`, `Pods`, `.worktrees`, `build`, `.gradle`.
+
+**Skip if deterministic**: GitHub Issue URL → extract repo name → check `$HOME/{repo}` exists → auto-set.
+
+**Otherwise**: Present discovered projects as numbered list (standard UX pattern). Stack tag (`[iOS]`, `[Android]`, etc.) auto-detected from project files. Set `PROJECT_ROOT` to selected directory — all subsequent commands use `git -C $PROJECT_ROOT`. Save to `prefs.global.recentProjects` (dedup, max 10). If bare `#N` was given, now fetch GitHub issue from project's remote.
+
+**Multi-Repo Mode** (gated by `prefs.global.settings.multiRepoEnabled`):
+
+- The picker accepts space-separated numbers (`1 3 4`) for multi-select.
+- `prefs.global.recentGroups[]` (set in setup.md Step 6) surfaces at the top: pressing the group's number selects all its repos in one keystroke.
+- Multi-select activates when ≥2 repos are chosen → populate `state.projects[]` array; the legacy scalar `state.project`/`projectRoot`/`worktreePath` fields mirror the **first** entry for backward-compat (single-repo phases that still read scalars don't break).
+- After selection, if the chosen set matches an existing `recentGroups` entry, bump `count` + `lastUsed`. If it's a new combination of ≥2 repos, prompt: `Save this combo as a multi-repo group? [y/N]` — on `y`, prepend to `recentGroups` (LRU cap 10).
+- Single-repo selection (1 repo) → legacy single-repo path; `state.projects[]` is omitted, scalars are populated as before.
+
+#### Step 3 — Remote Detection + Branch Selection
+
+1. **Check preferences first**: If `prefs.projects[{project}].remoteType` exists, use cached value.
+2. Read remote: `git -C $PROJECT_ROOT remote get-url origin`
+3. Detect type: `github.com` → github (`gh` CLI), `{BITBUCKET_HOST}` → bitbucket (API + `keychainMapping.bitbucket_token`), other → generic-git. Save to `prefs.projects[{project}].remoteType`.
+4. **Skip if baseBranch already set** (from Step 1). Otherwise:
+5. Fetch + list PR-targetable branches:
+   ```bash
+   git -C $PROJECT_ROOT fetch origin
+   git -C $PROJECT_ROOT branch -r --sort=-committerdate \
+     | grep -E '(develop|release|main|master)' \
+     | grep -v -E '(feature/|bugfix/|fix/|hotfix/|chore/)'
+   ```
+6. Sort: `develop*` first, then `release/*`, then `main`/`master`. Present numbered list with standard UX pattern:
+   ```
+   Base branch:
+     Recent: → develop (enter to reuse)
+     ────────────────────
+     1. origin/develop
+     2. origin/main
+     ...
+   Select [number] or enter for suggested:
+   ```
+7. User picks → store as `baseBranch`. Save to `prefs.projects[{project}].branches` (dedup, max 10).
+
+**TTL filter for recent branches**:
+
+- `prefs.global.recentBranches[{projectKey}][]` carries `{name, lastUsed}`. Filter to those whose `lastUsed` is within `settings.branchTtlDays` (default 15).
+- Stale entries (>TTL) are pruned in-place during the read — keeps the picker uncluttered without a separate cleanup pass.
+- The filtered "Recent" list precedes the fresh `git branch -r` list; cap at 5 visible recent entries.
+
+**Fetch-fail handling** (replaces silent `git fetch origin` failure):
+
+The legacy `git -C $PROJECT_ROOT fetch origin` step (line 110 above) MUST not silently fall back to a stale cached ref. On non-zero exit, present 4 options (per `feedback_multi_agent_fetch_fail`):
+
+```
+git fetch origin failed for {project} (exit {code}, last attempt {ts}).
+Likely causes: VPN closed, host unreachable, auth expired.
+
+  [1] Connect VPN / fix network, then resume #{taskId}     (safest)
+  [2] Use cached origin/{baseBranch} ref                    (stale risk: base sha {sha}, fetched {since})
+  [3] Use local branch "{baseBranch}" as base               (only if local branch exists; commit {sha})
+  [4] Abort — no worktree, no branch, no state file
+
+Select:
+```
+
+Persist user choice in `agent-state.json.baseFetchStatus` ∈ `"fresh" | "cached-stale" | "local-branch" | "aborted"`. On any non-fresh choice, log:
+```
+⚠️ Base ref stale (fetch fail @ {ts}, choice: {cached-stale|local-branch})
+```
+Phase 6 (commit/push) MUST re-attempt `git fetch origin` before push; if successful, prompt to rebase before pushing.
+
+In multi-repo mode, the prompt fires per-repo. Choosing `[4] Abort` for any single repo aborts the entire task (atomic — no partial worktrees).
+
+#### Step 4 — Branch Naming (automatic)
+
+Branch name is deterministic — no user confirmation needed.
+
+**Type resolution** (first match wins):
+- Jira `Bug|Hotfix|Defect` → `bugfix`
+- Jira `Story|Task|Feature` → `feature`
+- GitHub label `bug` → `bugfix`
+- Free-text contains `bug`/`fix` → `bugfix`
+- Else → `feature`
+
+**Name construction**:
+- Jira → `{type}/{jiraId}` (e.g. `bugfix/ABC-12345`)
+- GitHub → `{type}/GH{issueNo}-{kebab}` (e.g. `feature/GH42-add-dark-mode`)
+- Free-text → `{type}/{kebab}` (e.g. `bugfix/login-crash-fix`)
+
+**Kebab rules** (for free-text + GitHub-issue titles):
+1. Lowercase
+2. Replace `[^a-z0-9]+` runs with single `-`
+3. Trim leading/trailing `-`
+4. Collapse adjacent `-` (no `--`)
+5. Truncate to 50 chars, then trim trailing partial word at the last `-`
+6. If empty after kebab (e.g. all-emoji title) → fall back to `task-{shortId}`
+
+**Collision handling** (automatic — no prompt):
+- Probe local + remote for existing branch:
+  ```bash
+  LOCAL_HIT=$(git -C "$root" rev-parse --verify --quiet "refs/heads/$branch")
+  REMOTE_HIT=$(git -C "$root" ls-remote --exit-code --heads origin "$branch" 2>/dev/null)
+  ```
+- No collision → use as-is
+- Collision found → append `-v2`, `-v3`, etc. until unique:
+  `bugfix/ABC-12345` exists → `bugfix/ABC-12345-v2`
+- Log: `Branch collision: {branch} exists, using {branch}-v2`
+
+**Multi-Repo Mode** — branch name is **shared across all repos in the group**. Collision check runs per-repo; if any repo collides, the suffix applies to **all** repos (keeps cross-repo uniformity).
+
+#### Step 5 — Instruction Files (optional)
+
+1. Check `$PROJECT_ROOT/.instructions/` exists → scan for `SKILL.md` files
+2. If figmaUrl exists AND instructions include figma workflow → `instructionDriven: true`
+3. Map instruction files to `"instructionFiles": { "start": "...", "validate": "...", "dev": "...", "commit": "..." }`
+4. Instruction-driven → later phases read SKILL.md; no instructions → standard phases
+
+#### Step 6 — Branch + Workspace Setup
+
+**6a. Resolve git identity** (automatic, no prompt):
+
+```bash
+ORIGIN=$(git -C "$root" config --get remote.origin.url)
+CANON=$(echo "$ORIGIN" | sed -E 's|^(git@|https?://)||; s|:|/|; s|\.git$||')
+```
+
+Resolution order:
+1. `platformIdentityRouting` match (longest-prefix wins) → use directly
+2. `prefs.projects[{project}].lastIdentity` → use if exists
+3. Single identity in `identities[]` → use it
+4. No identities → run **Token Save Flow** from `setup.md` (creates identity with first token)
+5. Multiple identities, no routing rule → ask once, save routing rule so it never asks again
+
+In **multi-repo mode**, identity is resolved **per repo** independently.
+
+Log: `Identity: {identity.name} <{identity.email}>`
+
+**6b. Create branch + worktree**:
+
+1. `git -C $PROJECT_ROOT fetch origin`
+
+**If `--local` mode** (no worktree):
+
+```bash
+if [ -n "$(git -C $PROJECT_ROOT status --porcelain)" ]; then
+  echo "Warning: Working directory has uncommitted changes. Stash or commit first."
+fi
+git -C $PROJECT_ROOT checkout -b {branch} origin/{baseBranch}
+git -C $PROJECT_ROOT config user.name "{identity.name}"
+git -C $PROJECT_ROOT config user.email "{identity.email}"
+```
+
+`worktreePath` = `$PROJECT_ROOT`, `localMode` = `true`.
+
+**If normal mode** (worktree — default): 2. Worktree path: Jira → `.worktrees/{jiraId}/`, GitHub → `.worktrees/GH{issueNo}/`, free-text → `.worktrees/task-{shortId}/` 3. `git -C $PROJECT_ROOT worktree add {path} -b {branch} origin/{baseBranch}` (if exists: enter, pull) 4. Set identity: `git -C {worktree-path} config user.name/email` 5. Create log dir + `agent-log.md` + `agent-state.json`:
+
+**Multi-Repo Worktree Setup**:
+
+When `state.projects[].length > 1`, repeat steps 2-4 **serially per repo** (worktrees are cheap; serial keeps git index sane and surfaces collisions one at a time):
+
+```bash
+for proj in "${PROJECTS[@]}"; do
+  WT_PATH="$proj/.worktrees/$BRANCH_DIR/"
+  git -C "$proj" worktree add "$WT_PATH" -b "$BRANCH" "origin/$BASE_BRANCH"
+  git -C "$WT_PATH" config user.name  "${proj_identity_name}"
+  git -C "$WT_PATH" config user.email "${proj_identity_email}"
+done
+```
+
+State file in multi-repo mode:
+- Single shared `agent-state.json` lives at `$HOME/.claude/logs/multi-agent/{first-project}/{task-id}/agent-state.json` (anchored on the first repo for back-compat with `multi-agent log`/`status` commands)
+- `state.projects[]` holds per-repo `{name, root, worktreePath, branch, baseBranch, identity, platform, baseFetchStatus, commit, pr, pushAttempts, buildStatus}` — see `agent-state.schema.json`
+- Scalar fields (`project`, `projectRoot`, `worktreePath`, `branch`, `baseBranch`, `identity`) mirror `projects[0]` so legacy phases that read scalars keep working
+- Atomicity: if any repo's worktree creation fails (collision aborted, fetch aborted, disk full), roll back already-created worktrees: `git -C $proj worktree remove --force $WT_PATH; git -C $proj branch -D $BRANCH`. Never leave a partial multi-repo state.
+
+Single-repo mode (`projects.length === 1` or scalar-only) uses the legacy single-worktree path verbatim — no behavior change for existing tasks.
+
+```json
+{
+  "taskId": "{jiraId}", "branch": "{branch}", "baseBranch": "{baseBranch}",
+  "project": "{name}", "projectRoot": "{path}", "worktreePath": "{path}",
+  "logPath": "$HOME/.claude/logs/multi-agent/{project}/{task-id}/",
+  "remoteType": "github|bitbucket|generic-git|local",
+  "offlineOnly": false,
+  "baseFetchStatus": "fresh|cached-stale|local-branch|aborted",
+  "inputType": "github-issue-url|github-issue-number|jira-url|jira-id|free-text",
+  "jiraId": "PROJ-XXXXX|null", "figmaUrl": "...|null",
+  "contextLinks": [
+    { "type": "swagger|confluence|crashlytics|fortify|figma|generic-doc",
+      "url": "<full-url>", "metadata": { } }
+  ],
+  "crashContext": null,
+  "fortifyFinding": null,
+  "localMode": false, "instructionDriven": true|false, "instructionFiles": {},
+  "identity": {"name": "...", "email": "...", "keychainKey": "..."},
+  "currentPhase": 0, "status": "in_progress", "startedAt": "{ISO}", "shortId": "#N",
+  "phases": { "0": {"status":"done","files":[]}, "1-7": {"status":"pending","files":[]} }
+}
+```
+
+**Local-only flow** — when every entry in `state.projects[]` has `provider="local"`:
+- `taskId` format: `LOCAL-{slug-of-freetext}-{yyyymmdd-HHMMSS}` (e.g. `LOCAL-purchase-flow-20260510-143200`). Slug = lowercase, non-alnum → `-`, trimmed, max 32 chars.
+- `state.offlineOnly = true` (Phases 6/7 read this flag).
+- `state.remoteType` per project = `"local"`.
+- `state.baseBranch` = current branch of the local checkout (no `origin/{base}` fetch).
+- `state.branch` = local-only feature branch on the same checkout; no upstream tracking is configured (`git checkout -b {branch}` without `-u`).
+- No `gh`/`bb` API calls anywhere in Step 8. Worktree creation still applies if the user prefers worktree mode; collision handling stays the same.
+- Multi-repo + mixed mode: any project with `provider != "local"` keeps its normal remote workflow; the `offlineOnly` flag is set only when **all** projects are local.
+
+6. Log: "Phase 0: Init complete — {project} / {branch} / {identity.name}"
+
+#### Step 7 — Task Type Detection (deterministic, sets the contract for downstream phases)
+
+Classify task _before_ Phase 1 so downstream phases branch on it. Persist to `agent-state.json.taskType`.
+
+Priority order (first match wins):
+
+1. Description/Jira summary contains Figma URL (`figma.com/design/...` or `figma.com/make/...`) → `component`
+2. `instructionDriven == true` AND instruction path contains `figma` → `component`
+3. Git diff shows new `Configuration.swift` AND `+Modifiers.swift` → `component`
+4. Jira type matches `Bug|Hotfix|Defect` → `bugfix`
+5. Branch starts with `bugfix/` or `hotfix/` → `bugfix`
+6. Branch `feature/` AND description contains `refactor`|`cleanup`|`rewrite` → `refactor`
+7. Branch `feature/` → `feature`
+8. Description contains `chore`|`docs`|`ci`|`config` (no code keyword) → `chore`
+9. Fallback → ask user (autopilot defaults to `feature`)
+
+Persist: `"taskType": "component" | "bugfix" | "feature" | "refactor" | "chore"`
+
+| Phase   | Behavior change                                                                                          |
+| ------- | -------------------------------------------------------------------------------------------------------- |
+| Phase 3 | `component` → delegate to `pipeline/skills/figma-ios/figma-to-component` (orchestrator runs 3.0–3.8 internally); else standard TDD |
+| Phase 4 | `bugfix` → test coverage; `component` → accessibility+tokens; `refactor` → behavior preservation         |
+| Phase 6 | `bugfix`/`hotfix` → `fix(...)` prefix; `feature`/`component` → `feat(...)`; `refactor` → `refactor(...)` |
+| Phase 7 | `component` → includes SubPhase breakdown                                                                |
+
+Log: `Phase 0 Step 7: taskType = {component|bugfix|feature|refactor|chore}`
+
+#### Step 8 — Clarification (opt-in, runs AFTER maturity, BEFORE Phase 1)
+
+**Gated by `prefs.global.clarifyAmbiguous.enabled`** (default: `false`). When enabled and `state.maturity.status != "blocker"`:
+
+1. Dispatch `agents/task-clarifier.md` (Haiku by default) with the task title + body + acceptance + maturity warnings already on `agent-state`.
+2. The agent returns JSON conforming to `pipeline/schemas/clarify-output.schema.json` — `clarityScore` (0-10), `questions[]`, `stopAndAsk`.
+3. If `clarityScore >= prefs.clarifyAmbiguous.minScoreToProceed` (default 6) or `stopAndAsk == false` → write `state.clarification` (score + rationale, no questions), proceed to Phase 1 silently.
+4. If `stopAndAsk == true`:
+
+   - **Interactive runs:** render the questions via `AskUserQuestion` (label + header per `refs/rules.md` Language Application matrix; `outputLanguage` for `question` + `option.description`, English for `label` + `header`). Up to `maxQuestions` questions, each with the recommended option flagged. Persist the user's answers under `state.clarification.userAnswers`.
+   - **Autopilot runs:** follow `clarifyAmbiguous.autopilotMode`:
+
+     | Mode  | Behavior |
+     |---|---|
+     | `skip`  | Discard questions, proceed to Phase 1 with no extra context. Logs `clarify.skipped` |
+     | `log`   | Append questions to `agent-log.md` for human review, proceed. Default — keeps the signal |
+     | `abort` | Pause Phase 0 (`state.status = "clarify-pending"`); user resumes via `multi-agent:resume #N`. Then Step 8 re-dispatches AskUserQuestion |
+
+5. Phase 1 Analysis reads `state.clarification.userAnswers` (when present) as additional context — fold answers into the Explore prompt so downstream phases inherit the resolution.
+
+**Cost:** ~$0.0025 per Haiku call. The pipeline's other expensive phases (Phase 4 reviewers, Phase 3 Sonnet codegen) far outweigh this — the value is avoiding the ~30 min wasted when Phase 3 builds the wrong thing because Phase 0 didn't ask.
+
+**Reference:** see `pipeline/agents/task-clarifier.md` for the full scoring rubric, question quality rules, and prior-art citations (Devin Knowledge / Cursor Plan Mode).
+
+**Why this fits Phase 0 (not a new phase):** clarification doesn't change what code gets written — it changes what gets understood before code is written. Phase 0 already collects identity / project / branch / maturity; ambiguity scoring fits naturally as the last contextual gate.
+
+#### Telemetry
+
+After each clarifier call:
+
+```bash
+pipeline/scripts/log-metric.sh "$TASK_ID" 0 clarify.call \
+  score=$SCORE questions=$Q stop_and_ask=$STOP autopilot_mode=$AP \
+  duration_ms=$D tokens_in=$TI tokens_out=$TO
+```
+
+Phase 7 cost rollup carries this as a `phase 0` line item so the user sees ambiguity-scoring cost separately from Phase 1 Analysis.
+
+<!-- progress-contract: applied -->
+
+**Progress (per `refs/progress-contract.md`):** emit one `→ <verb> <object>` line for each of: `→ parsing input`, `→ checking token <service>`, `→ scanning project <root>`, `→ creating worktree <repo>`, `→ binding identity <name>`, `→ writing state`. When `clarifyAmbiguous.enabled`, also emit `→ scoring task ambiguity` before Step 8 and `→ asking clarifying questions <N>` when `stopAndAsk` fires.
+
+**Save preferences**: Write updated prefs to `$HOME/.claude/multi-agent-preferences.json` with all Phase 0 selections.