---
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**: see `picker-contract.md` + `rules.md` Language Application matrix.

## 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)**. Print the breadcrumb narrator line first (per `$HOME/.claude/multi-agent-refs/picker-contract.md` Step narration): `<localized: "Step N/N: extra dev repos">`.
   ```
   [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.

## Frontend repos  -  `frontendRepos`

Frontend repos are rarely submodules of the app repo, so submodule detection never finds them. `prefs.projects[<key>].frontendRepos[]` is the primary source for them and is merged into the candidate list alongside the detected submodules. Only `/multi-agent:analysis` used to read this key, which meant the pipeline's own dev-context picker could not offer a frontend repo at all.

## 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.