@mmerterden/multi-agent-pipeline 8.6.0

package/pipeline/commands/deploy.md

@@ -0,0 +1,54 @@
+---
+description: Structured deployment checklist for iOS App Store submission
+allowed-tools: Read, Bash, Glob, Grep, Agent
+---
+
+Run through the iOS deployment checklist before App Store submission.
+
+## Pre-Deployment Checklist
+
+### 1. Version & Build
+
+- [ ] `CFBundleShortVersionString` incremented
+- [ ] `CFBundleVersion` incremented
+- [ ] Version matches App Store Connect
+
+### 2. Code Quality
+
+- [ ] No `print()`, `debugPrint()`, `NSLog()` in production code
+- [ ] No debug tools (Netfox, FLEX, CocoaDebug) in Release config
+- [ ] No `#if DEBUG` blocks leaking into Release
+- [ ] No hardcoded test/staging URLs
+
+### 3. Signing & Provisioning
+
+- [ ] Correct distribution certificate
+- [ ] App Store provisioning profile (not Ad Hoc/Dev)
+- [ ] All extensions signed with same team
+- [ ] Push notification entitlement = production
+
+### 4. Privacy & Compliance
+
+- [ ] PrivacyInfo.xcprivacy present and complete
+- [ ] All Required Reason APIs declared with valid codes
+- [ ] Purpose strings meaningful (not vague)
+- [ ] ATT prompt only if tracking
+
+### 5. Assets
+
+- [ ] All app icon sizes present
+- [ ] Launch storyboard configured
+- [ ] No placeholder/test images
+
+### 6. Archive & Upload
+
+- [ ] Archive with Release configuration
+- [ ] Run App Store compliance scan: `/archive-guard <archive>` (uses `ios_app_store_audit` MCP tool)
+- [ ] Upload via Xcode Organizer or `xcrun altool`
+- [ ] Verify in App Store Connect
+
+## Steps
+
+1. Check each item by reading relevant project files.
+2. Report status for each item (PASS/FAIL/SKIP).
+3. Block deployment if any critical item fails.

package/pipeline/commands/figma-to-swiftui.md

@@ -0,0 +1,295 @@
+---
+description: "Figma URL -> SwiftUI component generation (full 8-phase pipeline with SubPhases)"
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash, Agent, WebFetch, TaskCreate, TaskUpdate
+---
+
+# Figma -> SwiftUI Component Generator
+
+Generate a production-ready SwiftUI component from a Figma design URL.
+
+**Input**: $ARGUMENTS (Figma URL, or component name if already gathered)
+
+## Phase Order
+
+```
+0-Init -> 1-Gather -> 2A-TestingIDs -> 2B-Localization -> 2C-Accessibility -> 2D-Analytics
+-> 3-TokenMapping -> 4A-Configuration -> 4B-View -> 4C-Docs -> 4D-Preview -> 4E-Modifiers
+-> 4F-Wiki -> 5A-ViewInspector -> 5B-Snapshot -> 5C-Unit -> 6-CodeConnect
+-> 7-IssueBodyUpdate -> 8-Cleanup
+```
+
+When invoked from `/multi-agent` with `instructionDriven == true` (figma instruction file detected), this skill takes over Phase 3 of the main pipeline. Progress is reported as SubPhases under the main pipeline's Phase 3:
+
+```
+* Phase 3: Dev (figma)       in progress
+  ■ SubPhase 3.0: Init            completed
+  ■ SubPhase 3.1: Gather          completed
+  * SubPhase 3.4F: Wiki           writing wiki pages...
+  □ SubPhase 3.5C: Unit Tests     pending
+  ...
+```
+
+## Phase 0: Init
+
+1. Parse Figma URL — extract fileKey and nodeId
+2. Detect component name from Figma metadata or user input
+3. Create branch: `feature/{JIRA_KEY}-{component-name}`
+4. Create task list for all phases
+
+## Phase 1: Gather
+
+1. Fetch design context from Figma (use `get_design_context` if Figma MCP available, or screenshot)
+2. Identify: variants, states, properties, design tokens
+3. Document in a gathering summary
+
+## Phase 2: Preparation (parallel sub-phases)
+
+### 2A: Testing Identifiers
+- Define `UITestingIdentifiers` enum for every interactive element
+- Pattern: `{ComponentName}_{elementName}` (e.g., `Button_title`, `Button_icon`)
+
+### 2B: Localization
+- Extract all user-facing strings
+- Create localization keys: `{componentName}.{element}` (e.g., `button.title`)
+
+### 2C: Accessibility
+- Define VoiceOver labels, hints, traits for each element
+- Minimum tap target: 44x44pt
+- Dynamic Type support plan
+
+### 2D: Analytics
+- Define analytics events per interaction
+- Pattern: `{componentName}_{action}` (e.g., `button_tapped`)
+
+## Phase 3: Token Mapping
+
+Map Figma design values to project design tokens:
+
+| Figma Value | Token |
+|-------------|-------|
+| Padding 16 | `.Spacing.spacing16` |
+| Color #E31837 | `Color.Primary.primary` |
+| Font 16/semibold | `.typographyStyle(.body1)` |
+| Corner 8 | `.CornerRadius.radius8` |
+
+**Rules**:
+- No magic numbers — all values reference design tokens
+- No raw hex colors — use semantic color tokens
+- No raw `.font()` — use typography tokens
+- Token hierarchy: Spacing > Size > Radius > BorderWidth > Color > Typography
+
+## Phase 4: Implementation (sequential sub-phases)
+
+### 4A: Configuration
+```swift
+// {Name}Configuration.swift
+struct {Name}Configuration {
+    var title: String = ""
+    var style: {Name}Style = .primary
+    var isEnabled: Bool = true
+    // ... all properties from Figma variants
+}
+```
+- Pure value type, no side effects, no view logic
+- Every Figma variant maps to a property
+- Sensible defaults for all properties
+
+### 4B: View
+```swift
+// {Name}View.swift
+struct {Name}View: View {
+    let configuration: {Name}Configuration
+
+    var body: some View {
+        // Render using configuration + design tokens
+    }
+}
+```
+- Renders Configuration only
+- Uses design tokens (no magic numbers)
+- Accessibility identifiers on every interactive element
+
+### 4C: Documentation
+```markdown
+// FIGMA.md
+## {Name} Component
+| Variant | Property | Values |
+|---------|----------|--------|
+| Style   | style    | primary, secondary, ghost |
+| Size    | size     | small, medium, large |
+```
+
+### 4D: Preview
+```swift
+#Preview("{Name} - All Variants") {
+    VStack {
+        // Every meaningful variant combination
+        // Light + Dark
+        // LTR + RTL
+    }
+}
+```
+
+### 4E: Modifiers
+```swift
+// {Name}+Modifiers.swift
+extension {Name}View {
+    func title(_ value: String) -> {Name}View {
+        var config = configuration
+        config.title = value
+        return {Name}View(configuration: config)
+    }
+}
+```
+- Fluent API chain for every configuration property
+
+### 4F: Wiki (auto-detected, auto-skipped if no wiki submodule)
+
+Generate and push wiki documentation pages to the wiki submodule.
+
+**Prerequisites check** (deterministic, no prompt):
+
+```bash
+# 1. Wiki submodule — auto-detect from .gitmodules
+WIKI_REL=$(git -C "$PROJECT_ROOT" config -f .gitmodules --get-regexp 'submodule\..*\.path' 2>/dev/null \
+  | awk '{print $2}' | grep -i 'wiki' | head -1)
+
+# Preference override
+WIKI_PATH_PREF=$(jq -r ".projects[\"$PROJECT\"].wikiPath // empty" "$PREFS_FILE")
+[ -n "$WIKI_PATH_PREF" ] && WIKI_REL_ABS="$WIKI_PATH_PREF"
+[ -n "$WIKI_REL" ] && WIKI_REL_ABS="$PROJECT_ROOT/$WIKI_REL"
+
+# User preference: disabled?
+WIKI_PREF=$(jq -r ".projects[\"$PROJECT\"].wikiPhase // empty" "$PREFS_FILE")
+[ "$WIKI_PREF" = "disabled" ] && { log "4F-Wiki disabled for $PROJECT — skipping"; exit 0; }
+
+# No wiki found
+[ -z "$WIKI_REL_ABS" ] && {
+  if autopilot; then exit 0; fi   # autopilot: silent skip
+  ask_user "No wiki submodule. (1) add submodule (2) use custom path (3) skip once (4) disable permanently"
+  # Persist user choice to prefs
+}
+
+# Figma token
+DESIGN_TOKEN_KEY=$(jq -r '.global.keychainMapping.figma // empty' "$PREFS_FILE")
+[ -z "$DESIGN_TOKEN_KEY" ] && DESIGN_TOKEN_KEY="${USER}_Figma_Access_Token"
+DESIGN_TOKEN=$(~/.claude/lib/credential-store.sh get "$DESIGN_TOKEN_KEY" 2>/dev/null)
+
+# Default branch
+WIKI_BRANCH=$(git -C "$WIKI_REL_ABS" symbolic-ref refs/remotes/origin/HEAD 2>/dev/null \
+  | sed 's|refs/remotes/origin/||')
+[ -z "$WIKI_BRANCH" ] && WIKI_BRANCH=$(git -C "$WIKI_REL_ABS" branch --show-current)
+```
+
+**Steps**:
+
+1. **Create wiki component dir**:
+   ```bash
+   mkdir -p "$WIKI_REL_ABS/{wikiCategory}/{ComponentName}/assets"
+   ```
+   `wikiCategory` mirrors the component's folder layout inside the product repo.
+
+2. **Fetch design-source screenshot** (Figma by default; other sources swap the fetch call):
+   ```bash
+   RESPONSE=$(curl -s "https://api.figma.com/v1/images/{fileKey}?ids={nodeId}&format=png&scale=2" \
+     -H "X-Figma-Token: $DESIGN_TOKEN")
+   IMAGE_URL=$(echo "$RESPONSE" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['images']['{nodeId}'])")
+   curl -s -o "$WIKI_REL_ABS/{wikiCategory}/{ComponentName}/assets/screenshot.png" "$IMAGE_URL"
+   ```
+   If `DESIGN_TOKEN` missing: leave a `TODO: add screenshot` placeholder, continue.
+
+3. **Generate main wiki page** (`{ComponentName}.md`) — sections:
+   Title · screenshot embed · Figma link · Screen/Section/Size metadata · Overview · Testing Identifiers · Localization Keys · Accessibility · Analytics Events · Sub-Components · Platform Implementations (iOS/Android/Web status) · Changelog.
+
+4. **Generate platform-specific page** (`{ComponentName}-iOS.md`) — sections:
+   Initializer · Parameters · Modifiers · Usage · Design Tokens · Testing Identifiers iOS · Code Connect · Snapshot Tests (image embeds) · Test Coverage · Changelog.
+
+5. **Commit and push**:
+   ```bash
+   cd "$WIKI_REL_ABS"
+   git add "{wikiCategory}/{ComponentName}/"
+   git -c user.name="{identity.name}" -c user.email="{identity.email}" \
+     commit -m "docs({scope}): add {ComponentName} wiki pages [{jiraId}]"
+   git fetch origin && git rebase "origin/$WIKI_BRANCH"
+   git push origin "HEAD:$WIKI_BRANCH"
+   ```
+   Retry rebase up to 3 times on reject; never force-push.
+
+## Phase 5: Testing (3-layer strategy)
+
+### 5A: ViewInspector (Structural)
+- Verify subview hierarchy
+- Verify modifiers applied correctly
+- Verify accessibility identifiers present
+
+### 5B: Snapshot Tests (Visual)
+- Light mode + Dark mode
+- LTR + RTL
+- All variant combinations
+
+### 5C: Unit Tests (Behavioral)
+- Configuration mutations
+- Modifier chain correctness
+- Default values
+
+## Phase 6: Code Connect
+
+```swift
+// {Name}.figma.swift
+import FigmaConnect
+
+@FigmaConnect("{fileKey}", "{nodeId}")
+struct {Name}CodeConnect {
+    // Map Figma variants to Configuration properties
+}
+```
+
+## Phase 7: Issue Body Update (GitHub Issue only)
+
+If a GitHub Issue tracks this component, update its body after commit + PR:
+- Fill the `### Pull Requests` section with PR URL(s), one row per submodule touched
+- Flip Implementation / Testing / Code Connect flags from Pending to Done using whatever marker the template uses (match in place, don't introduce new markers)
+- Flip the Wiki flag to Done (SubPhase 4F already pushed the wiki pages)
+- Apply with `gh issue edit {issueNo} --body "{updated body}"` — preserve every other section unchanged
+- NEVER use `Closes:` / `Fixes:` / `Resolves:` keywords — use `Ref:` or `Related:` instead
+
+Skip this phase if the task has no GitHub Issue (Jira-only or free-text runs).
+
+## Phase 8: Cleanup & Review
+
+Run the 14-item checklist:
+1. File completeness (Configuration, View, Modifiers, .figma.swift, FIGMA.md)
+2. No magic numbers (design tokens required)
+3. Configuration purity (no side effects)
+4. Modifier correctness (fluent API)
+5. Accessibility identifiers on every interactive element
+6. Analytics events tracked
+7. Testing identifier pipeline
+8. Preview quality (LTR + RTL, Light + Dark)
+9. Code Connect mapping
+10. View implementation quality
+11. FIGMA.md documentation complete
+12. Artifact cleanup
+13. Build verification (`xcodebuild`)
+14. Test verification (ViewInspector + Snapshot + Unit)
+
+## Output Files
+
+| File | Content |
+|------|---------|
+| `{Name}Configuration.swift` | Pure value type: all properties |
+| `{Name}View.swift` | SwiftUI view, renders Configuration |
+| `{Name}+Modifiers.swift` | Fluent modifier API chain |
+| `{Name}.figma.swift` | Code Connect registration |
+| `FIGMA.md` | Variant matrix, usage examples |
+| `{Name}Tests.swift` | ViewInspector structural tests |
+| `{Name}SnapshotTests.swift` | Snapshot visual tests |
+| `{Name}UnitTests.swift` | Unit behavioral tests |
+
+## Sub-Commands
+
+| Command | What It Does |
+|---------|-------------|
+| `/figma-to-swiftui <url>` | Full pipeline (this command) |
+| `/figma-to-swiftui commit <Name>` | 14-item review + commit + PR |
+| `/figma-to-swiftui review <Name>` | Interactive review (approve/request changes) |

package/pipeline/commands/multi-agent/_account-picker.md

@@ -0,0 +1,90 @@
+---
+description: "Internal — interactive account picker for multi-agent."
+---
+
+# _account-picker — Account Selection
+
+First step of every `multi-agent` flow **that touches a remote provider**.
+
+> **Skip rule (local-only flow)**: When the input is `freetext` AND the user's
+> repo selection will end up being entirely local (no github/bitbucket account
+> needed for any selected primary), this step is **skipped entirely** — no
+> question, no token lookup. Detection: `freetext` flow first fetches local
+> repos (`repo-cache.sh local "$HOME"`); if the picker resolves to local-only
+> repos, account-picker is bypassed and the state file's `accountId` is left
+> `null` with `tokens={}`. Phases 6/7 read these as "local-only" signals.
+
+> **Language**: User-facing prompt strings always render in English (`promptLanguage` is locked to `"en"`). Commit/PR/Jira payloads always English.
+
+## Steps
+
+1. **Fetch account inventory**:
+   ```bash
+   ~/.claude/lib/account-resolver.sh > /tmp/multi-agent-accounts.json
+   ```
+2. **Filter** when needed:
+   - Jira-based flow → `--providers jira`
+   - GitHub-based flow → `--providers github`
+   - Bitbucket-based flow → `--providers bitbucket`
+
+3. **Picker UI** — show via AskUserQuestion:
+   ```
+   [1/N] Select account:
+     > {label}   ({providers})
+       ...
+   ```
+   - Single account → auto-select, show info only
+   - Multiple → multiSelect=false picker
+
+4. **Persist selection to state**:
+   - `accountId`, `accountPrefix`, `tokens.{github,jira,bitbucket,confluence}`,
+     `jiraHost`, `bitbucketHost`, `isWork`
+
+## Autopilot Behavior
+
+When `MULTI_AGENT_AUTOPILOT=1`:
+- Single account → auto-select
+- Multiple → default selection priority:
+  1. account whose remote matches the cwd repo
+  2. `prefs.global.recentAccounts[0]` (most recently used)
+  3. first account with `isWork=true`
+  4. first account in the list
+- Selection logged: `auto-selected account: {label}`
+
+## Recent-accounts write
+
+After confirmation (interactive) or auto-selection (autopilot), update
+`prefs.global.recentAccounts[]` LRU-style:
+
+1. If selected `id` already in `recentAccounts`, increment its `count`,
+   refresh `lastUsed` (ISO 8601 UTC), and move it to position 0.
+2. Otherwise prepend `{id, prefix, lastUsed, count: 1}` and trim to 10 entries.
+3. Atomic write via `prefs.json.tmp` + rename.
+
+This is what makes priority rule #2 work — the picker remembers which account
+was used last and surfaces it first on the next autopilot invocation.
+
+## Error Cases
+
+- No accounts → if the input is `freetext` and at least one local repo exists,
+  fall through to local-only flow (skip this step). Otherwise prompt user to
+  run `setup` and halt.
+- Filter unmet → "No matching account for this flow ({provider} token required)" → halt.
+
+## Output (example)
+
+```json
+{
+  "accountId": "m-erden3",
+  "accountPrefix": "${USER}",
+  "tokens": {
+    "github": "${USER}_Github_Access_Token",
+    "jira": "${USER}_Jira_Access_Token",
+    "bitbucket": "${USER}_Bitbucket_Access_Token",
+    "confluence": "${USER}_Confluence_Access_Token"
+  },
+  "jiraHost": "jira.example.com",
+  "bitbucketHost": "bitbucket.example.com",
+  "isWork": true
+}
+```

package/pipeline/commands/multi-agent/_dev-context.md

@@ -0,0 +1,111 @@
+---
+description: "Internal — dev context (extra repos) picker for multi-agent."
+---
+
+# _dev-context — Extra Dev Repo Selection
+
+Selects extra repos the pipeline may touch beyond the primary repo(s) — typically submodules (e.g. SDKs vendored inside an app repo) or sibling libraries. Each candidate is enriched with a `canPush` flag so the picker can pre-select repos that the active account is allowed to edit, and surface read-only ones as advisory context the pipeline will not modify.
+
+> **Language**: Per `refs/rules.md` Language Application matrix — `AskUserQuestion.label` and `header` stay English (UI button + chip contract); `question` and `description` follow `outputLanguage`. Commit/PR/Jira/Wiki payloads: subject + branch names + code identifiers stay English; body text follows `outputLanguage`.
+
+## Steps
+
+1. **Submodule detection (with push-access enrichment)** — when the primary repo is checked out locally:
+   ```bash
+   ACCOUNT_GH_OWNER="$ACCOUNT_GH_OWNER" \
+   ACCOUNT_BB_PROJECT_KEY="$ACCOUNT_BB_PROJECT_KEY" \
+   PROJECT_PREF_KEY="$PRIMARY_REPO_NAME" \
+     ~/.claude/lib/submodule-detector.sh "$REPO_PATH"
+   ```
+   Remote fallback (when not cloned):
+   ```bash
+   ACCOUNT_GH_OWNER="$ACCOUNT_GH_OWNER" \
+   PROJECT_PREF_KEY="$PRIMARY_REPO_NAME" \
+     ~/.claude/lib/submodule-detector.sh --remote "<owner>/<repo>"
+   ```
+
+   `canPush` resolution order (first hit wins):
+   1. **prefs override** — `prefs.projects[<key>].editableRelatedRepos[]` matches `<owner>/<repo>` or bare `<name>`
+   2. **repo-cache hit** — submodule URL matches a cached repo with `viewerPermission ∈ {ADMIN, MAINTAIN, WRITE}`
+   3. **owner-match** — submodule owner equals `ACCOUNT_GH_OWNER`
+   4. else `canPush=false` (read-only)
+
+2. **Partition results**:
+   - `editable` — `canPush=true` → picker options, pre-selected
+   - `readonly` — `canPush=false` → printed as an advisory note; not selectable
+
+3. **AskUserQuestion (multiSelect=true)**:
+   ```
+   [N/N] Extra editable dev repos (multi):
+     [x] <submodule-a>  (suggestion: from .gitmodules)
+     [x] <submodule-b>  (cache hit: write access)
+     [ ] <sibling-lib>
+     [ ] (none)
+
+   Read-only siblings (pipeline will NOT modify):
+     - <vendored-sdk>   (no push access — pipeline works around)
+   ```
+
+4. **Empty submit** — user picks nothing → `extras=[]`, primary repo(s) only.
+
+## Pref override — `editableRelatedRepos`
+
+For repos that aren't on a remote provider (local-only checkout) or to explicitly grant edit rights regardless of provider state, add to `~/.claude/multi-agent-preferences.json`:
+
+```jsonc
+"projects": {
+  "<project-key>": {
+    "remoteType": "github",
+    "editableRelatedRepos": [
+      "<owner>/<repo>",   // owner/repo form
+      "<repo-name>"       // bare name also matched
+    ]
+  }
+}
+```
+
+Entries here force `canPush=true` regardless of cache state.
+
+## Output
+
+```json
+{
+  "extras": [
+    {
+      "name": "<submodule-name>",
+      "cloneUrl": "https://<host>/<owner>/<submodule>.git",
+      "provider": "github",
+      "source": "submodule",
+      "canPush": true,
+      "reason": "owner-match"
+    }
+  ],
+  "readonlySiblings": [
+    {
+      "name": "<vendored-sdk>",
+      "cloneUrl": "https://<host>/<vendor>/<sdk>.git",
+      "provider": "github",
+      "canPush": false,
+      "reason": "unknown"
+    }
+  ]
+}
+```
+
+## Rule
+
+This step **always runs**, even in direct-ID mode. Empty submit is allowed → primary repo(s) only.
+
+## Autopilot Behavior
+
+When `MULTI_AGENT_AUTOPILOT=1`:
+- Auto-select all editable submodules (`canPush=true`).
+- Read-only siblings logged to `agent-log.md` as `readonly-context: [<name>, ...]` but not selected.
+- Selection logged: `auto-selected extras: [<name>, ...]`.
+
+## Pipeline contract for read-only siblings
+
+When a read-only sibling is present (e.g. a vendored SDK checkout), Phase 3 (Dev) MUST:
+- Treat it as **read-only context** — code may be read for understanding, never edited or committed.
+- Prefer solving the task in the primary repo(s) (e.g. by wrapping/extending in consumer code) rather than patching the sibling.
+- Surface this constraint in the Phase 3 plan output so reviewers know why a workaround was chosen.

package/pipeline/commands/multi-agent/_input-parser.md

@@ -0,0 +1,43 @@
+---
+description: "Internal — input type detection for multi-agent dispatcher."
+---
+
+# _input-parser — Multi-Agent Input Type Classification
+
+The top-level `multi-agent` command classifies user arguments per the rules below.
+
+> **Language**: Schema reference only — no user-facing text. Picker UI strings always English (`promptLanguage` is locked to `"en"`). Commit/PR/Jira payloads stay English.
+
+## Type Table
+
+| # | Pattern | Type | Example |
+|---|---|---|---|
+| 1 | `^[A-Z]+-[0-9]+$` | `jira-id` | `PROJ-1` |
+| 2 | `https?://.*atlassian\.net/browse/.*` or `https?://jira\..*/browse/.*` | `jira-url` | `https://jira.example.com/browse/PROJ-1` |
+| 3 | `https?://github\.com/.*/issues/[0-9]+` | `gh-url` | `https://github.com/o/r/issues/316` |
+| 4 | `^[a-z0-9_-]+#[0-9]+$` | `gh-short` | `my-ios-app#316` |
+| 5 | `^#?[0-9]+$` | `gh-num` | `316`, `#316` |
+| 6 | `^jira$` | `picker-jira` | `jira` |
+| 7 | `^issue$` | `picker-issue` | `issue` |
+| 8 | (none of the above) | `freetext` | `"LoginView dark mode fix"` |
+
+## Flow Effect
+
+| Type | Account picker | Repo picker | Issue picker | Dev-context picker |
+|---|---|---|---|---|
+| `jira-id` / `jira-url` | ✅ (always) | ❌ | ❌ | ✅ |
+| `gh-url` | ✅ | ❌ (URL implies repo) | ❌ | ✅ |
+| `gh-short` | ✅ | ❌ (input implies repo) | ❌ | ✅ |
+| `gh-num` | ✅ | ✅ (single-select) | ❌ | ✅ |
+| `picker-jira` | ✅ | ✅ project (multi) | ✅ aggregate | ✅ |
+| `picker-issue` | ✅ | ✅ repo (multi) | ✅ aggregate | ✅ |
+| `freetext` | conditional¹ | ✅ (single-select, sources merged²) | ❌ | ✅ |
+
+¹ Account picker is **skipped** when the resolved primary repo is local-only
+  (`provider="local"`). No token lookup, no provider auth — the pipeline
+  proceeds with `accountId=null` and Phases 6/7 honor the local-only mode.
+
+² Free-text flow merges `github`+`bitbucket`+`local` repo caches into a
+  single picker list; `(local)` rows come from `repo-cache.sh local "$HOME"`.
+
+> **Rule**: Dev-context picker **always** runs (empty submit allowed → primary repo only).

package/pipeline/commands/multi-agent/_repo-picker.md

@@ -0,0 +1,76 @@
+---
+description: "Internal — multi-select repo picker for multi-agent."
+---
+
+# _repo-picker — Repo Selection (Multi-Select)
+
+Used by `picker-issue`, `picker-jira`, `gh-num`, and `freetext` flows.
+
+> **Language**: Per `refs/rules.md` Language Application matrix — `AskUserQuestion.label` and `header` stay English (UI button + chip contract); `question` and `description` follow `outputLanguage`. Commit/PR/Jira/Wiki payloads: subject + branch names + code identifiers stay English; body text follows `outputLanguage`.
+
+## Steps
+
+1. **Fetch repo list** per provider/account, then optionally merge local checkouts:
+   ```bash
+   # GitHub (only when an account was selected — see _account-picker)
+   ~/.claude/lib/repo-cache.sh github "$ACCOUNT_GH_OWNER"
+
+   # Bitbucket (work — only when an account was selected)
+   BB_TOKEN_KEY="$ACCOUNT_BB_TOKEN_KEY" \
+   BB_USER_KEY="$ACCOUNT_BB_USER_KEY" \
+   BB_HOST="$ACCOUNT_BB_HOST" \
+     ~/.claude/lib/repo-cache.sh bitbucket "$BB_PROJECT_KEY"
+
+   # Local — for freetext/no-tracker flows, scan $HOME for .git checkouts so a
+   # user with no provider account can still pick a repo and run the pipeline.
+   ~/.claude/lib/repo-cache.sh local "$HOME"
+   ```
+   Provider sources are concatenated into one picker list; each row carries a
+   `(github)` / `(bitbucket)` / `(local)` suffix so the choice is unambiguous.
+   Local rows expose `localPath` (filesystem path) and a redacted `remoteUrl`
+   (credentials stripped at cache time).
+
+2. **Show list** via AskUserQuestion (multiSelect=true):
+   ```
+   [2/N] Select repos (multi):
+     [ ] <repo-a>      (github)
+     [ ] <repo-b>      (bitbucket)
+     [ ] <repo-c>      (local)
+     ...
+   ```
+   - cwd repo, when present, defaults to `[x]`
+   - forks fall to the bottom
+   - local-only rows show `(local)` and the trimmed `$HOME`-relative path
+
+3. **Single-repo mode** — used for `gh-num`/`freetext` (multiSelect=false)
+
+4. **All-local selection** — when every selected repo has `provider="local"`,
+   downstream phases switch to local-only behavior: no remote push, no PR, no
+   Jira/Wiki/Confluence channels. Mixed selections (some local, some provider)
+   apply per-repo: the local repos stay offline, the provider repos use their
+   normal remote flow.
+
+## Output
+
+```json
+{
+  "selectedRepos": [
+    {"fullName":"<owner>/<repo-a>","name":"<repo-a>","provider":"github"},
+    {"fullName":"<owner>/<repo-b>","name":"<repo-b>","provider":"github"},
+    {"fullName":"local/<repo-c>","name":"<repo-c>","provider":"local","localPath":"<absolute-path>"}
+  ]
+}
+```
+
+## Autopilot Behavior
+
+When `MULTI_AGENT_AUTOPILOT=1`:
+- **Multi-select mode** (issue picker flow): pick **only** cwd repo if present; otherwise fall back to most-recent repo from `prefs.projects[*].lastUsed`
+- **Single-select mode** (gh-num/freetext): pick cwd repo automatically; if none, halt with error (autopilot can't prompt)
+- Selection logged: `auto-selected repos: [name1, name2]`
+
+## Error Cases
+
+- No repos for the account: prompt user for manual `owner/repo`
+- Cache fails (gh CLI missing): prompt user manually
+- Autopilot + no cwd repo: halt with "autopilot single-repo mode requires cwd to be a git repository"