bot-bottle/docs/prds/prd-new-separate-agent-bottle-selection.md

# PRD prd-new: Separate agent and bottle selection

- **Status:** Draft
- **Author:** claude
- **Created:** 2026-06-25
- **Issue:** #269

## Summary

Agents and bottles are two separate concerns: agents carry a system prompt and
skills; bottles carry infrastructure configuration (egress, git-gate, env,
agent provider). Today an agent's manifest file hard-codes a single `bottle:`
reference, which prevents the same agent prompt from being reused across
projects that need different bottle configurations. This PRD decouples them: at
launch time, after choosing the agent, the operator picks an ordered list of
bottles via a multi-select picker. The selected bottles are merged in order
(later entries override earlier ones) to produce the effective bottle for the
session.

## Problem

The current `bottle: <name>` field on an agent manifest file binds the agent
permanently to one bottle. To use the same system prompt with a different bottle
(e.g. `claude-implementer` at home vs. at a client site that needs a different
egress policy), the operator must duplicate the agent file and change the
`bottle:` field. Duplicate agent files drift out of sync.

## Goals / Success Criteria

1. `bottle:` in an agent's frontmatter becomes optional. Existing manifests with
   `bottle:` continue to work unchanged (backward compat).
2. After selecting an agent (via the existing single-select picker), a new
   multi-select bottle picker appears showing all available bottles.
3. The multi-select picker pre-populates with the agent's `bottle:` value when
   present.
4. Confirming with one or more bottles selected uses those bottles, merged in
   selection order, as the effective bottle for the session.
5. Confirming with an empty selection falls back to the agent's `bottle:` field.
   If neither is set, a ManifestError is raised pointing the operator at the fix.
6. The ordered bottle list is stored in launch metadata so `./cli.py resume`
   uses the same bottles.
7. The preflight summary (`y/N` screen) shows the effective bottle name(s).
8. The multi-select picker supports incremental filtering, Space/Enter to toggle
   selection, an ordered "Selected: ..." summary line, Ctrl-D to confirm, and
   Esc/q to cancel the whole start operation.
9. Unit tests cover: multi-select widget (filter, toggle, confirm, cancel),
   the `cmd_start` bottle-picker step, and the manifest `load_for_agent`
   runtime-bottle-merge path.

## Non-goals

- Reordering the selection list from within the picker (order = insertion order;
  drag-and-drop is out of scope).
- Storing bottle selection history / MRU.
- Changes to `./cli.py edit`, `./cli.py list`, or `./cli.py info`.
- Removing the `bottle:` key from the agent schema (it stays, now optional).

## Design

### `bot_bottle/cli/tui.py` — `filter_multiselect`

```python
def filter_multiselect(
    items: list[str],
    *,
    title: str = "",
    initial: list[str] | None = None,
    tty_path: str = "/dev/tty",
) -> list[str] | None:
    """Multi-select variant of filter_select.

    Returns the ordered list of selected items, or None on cancel.
    Press Space/Enter to toggle the item under the cursor.
    Press Ctrl-D to confirm. Press Esc/q to cancel.
    """
```

Layout:

```
Select bottles
Filter: _
─────────────────────────────────────────
> [*] claude
  [ ] dev
  [ ] codex
─────────────────────────────────────────
Selected (in order): claude
─────────────────────────────────────────
[↑↓/jk] move  [Space] toggle  [Ctrl-D] done  [Esc] cancel
```

`initial` pre-populates the ordered selection. `None` means no pre-selection.
Items added are appended in insertion order; items removed leave the remaining
order unchanged.

### `bot_bottle/manifest_schema.py` — optional `bottle:`

`bottle` moves from `AGENT_KEYS_REQUIRED` to `AGENT_KEYS_OPTIONAL`.

### `bot_bottle/manifest_agent.py` — optional `bottle:`

`ManifestAgent.bottle` changes from `str` (required) to `str = ""`.
`from_dict` no longer requires the key to be present; the bottle-exists
validation is skipped when the key is absent.

### `bot_bottle/manifest_loader.py` — `scan_bottle_names`

```python
def scan_bottle_names(bottles_dir: Path) -> list[str]:
    """Scan <bottles_dir>/*.md and return sorted bottle names."""
```

### `bot_bottle/manifest.py` — `ManifestIndex` changes

**`all_bottle_names` property** — analogous to `all_agent_names`; scans
`home_md / "bottles"` in lazy mode, returns `sorted(self.bottles.keys())` in
eager mode.

**`load_for_agent(agent_name, bottle_names: tuple[str, ...] = ())`** — new
`bottle_names` parameter. When non-empty, the listed bottles are resolved and
merged in order (index 0 is the base; each subsequent bottle is applied on top
using the same field-merge rules as `extends:`). The result replaces the bottle
that `agent.bottle` would have provided. When empty, falls back to `agent.bottle`.
Raises ManifestError if neither `bottle_names` nor `agent.bottle` is set.

### `bot_bottle/manifest_extends.py` — `merge_bottles_runtime`

```python
def merge_bottles_runtime(bottles: list[ManifestBottle]) -> ManifestBottle:
    """Merge an ordered list of pre-resolved ManifestBottle objects.

    Index 0 is the base; each subsequent entry overrides the previous using
    the same rules as the file-based extends machinery:
      - env: dict merge, later wins
      - git_user: per-field overlay, later wins on non-empty
      - git (repos): union by name, later wins per-name
      - egress.routes: concatenate
      - agent_provider, supervise: later bottle's value replaces earlier
    """
```

This function operates on already-parsed `ManifestBottle` objects, so it does
not need to touch the raw-dict path.

### `bot_bottle/backend/__init__.py` — `BottleSpec` + `_validate`

`BottleSpec` gains `bottle_names: tuple[str, ...] = ()`.

`BottleBackend._validate` passes `spec.bottle_names` to `load_for_agent`:

```python
manifest = spec.manifest.load_for_agent(spec.agent_name, spec.bottle_names)
```

The preflight print updates `info(f"bottle: {agent.bottle}")` to display the
effective bottle name(s). When `spec.bottle_names` is non-empty those are
shown; when empty and `agent.bottle` is set, the agent's `bottle:` is shown.

### `bot_bottle/bottle_state.py` — persist bottle names

`BottleMetadata` gains `bottle_names: tuple[str, ...] = ()`. `read_metadata`
reads this from JSON (default `()`). `write_launch_metadata` passes
`spec.bottle_names` through.

### `bot_bottle/cli/start.py` — bottle multiselect step

After agent selection, before the name/color modal:

```python
available_bottle_names = manifest.all_bottle_names
# Peek at agent's bottle default for pre-population
initial_bottle = _peek_agent_bottle(manifest, agent_name)
initial = [initial_bottle] if initial_bottle else []

bottle_names_list = tui.filter_multiselect(
    available_bottle_names,
    title="Select bottles",
    initial=initial,
)
if bottle_names_list is None:
    return 0  # user cancelled
bottle_names = tuple(bottle_names_list)
```

`_peek_agent_bottle` reads the agent file's frontmatter without full parsing,
returning the `bottle:` value or `""` when absent.

`BottleSpec` is built with `bottle_names=bottle_names`.

### `bot_bottle/cli/resume.py` — bottle names from metadata

```python
spec = BottleSpec(
    ...
    bottle_names=tuple(metadata.bottle_names),
)
```

## Implementation chunks

1. **Schema + model** — `manifest_schema.py`, `manifest_agent.py` (optional
   `bottle:`), `manifest_loader.py` (`scan_bottle_names`), `manifest.py`
   (`all_bottle_names`, `load_for_agent` signature), `manifest_extends.py`
   (`merge_bottles_runtime`), `bottle_state.py` (`bottle_names` field),
   `resolve_common.py` (thread through).
2. **Backend** — `BottleSpec.bottle_names`, `_validate`, preflight print.
3. **TUI** — `filter_multiselect` in `tui.py` + unit tests.
4. **CLI wiring** — `start.py` bottle picker step, `resume.py` metadata load.
5. **Tests** — `test_cli_start_selector.py` bottle-picker cases,
   `test_manifest_agent.py` optional-bottle cases, new
   `test_manifest_bottle_merge.py` for `merge_bottles_runtime`.

## Open questions

None.