# VibePod Implementation Plan

## Objective

Build a practical v1 of `vp` that unifies running agent CLIs in Docker with a consistent interface, while keeping the initial scope small and reliable.

## Guiding Principles

- Ship a thin, stable core before broad feature coverage.
- Keep agent-specific behavior behind adapters.
- Prefer clear UX and predictable defaults over cleverness.
- Make all state locations explicit and inspectable.

## v1 Scope

### In Scope

- Project scaffold (`pyproject.toml`, `src/`, `tests/`, basic tooling).
- Core commands:
  - `vp run <agent>`
  - `vp stop <agent|--all>`
  - `vp list`
  - `vp logs ui`
  - `vp config show`
  - `vp config path`
  - `vp version`
- Supported agents in registry: `claude`, `gemini`, `opencode`, `devstral`, `auggie`.
- Docker lifecycle management via Docker SDK (no shelling out to docker CLI).
- Config loading/merging: defaults + global + project + env overrides.
- Container labels and naming conventions for reliable discovery.

### Out of Scope (Post-v1)

- Full `vp auth` flows.
- Full `vp skills` integration and MCP management.
- `vp logs query/export/stats`.
- Auto-update command, installers, and release automation.

## Architecture Decisions

### 1) Agent Adapter Contract

Each agent implements a small adapter interface:

- `image(config) -> str`
- `config_mounts(paths) -> list[MountSpec]`
- `env(config, runtime) -> dict[str, str]`
- `command(runtime) -> list[str]`
- `healthcheck(container) -> AdapterStatus`

This keeps `run/stop/list` generic and avoids hardcoding agent quirks.

### 2) Container Identity

Use both predictable names and labels:

- Name: `vibepod-{agent}-{shortid}`
- Labels:
  - `vibepod.managed=true`
  - `vibepod.agent=<agent>`
  - `vibepod.workspace=<absolute-path>`
  - `vibepod.version=<vp-version>`

All operational commands (`list`, `stop`, future logs) discover containers via labels.

### 3) Config Paths

- Global config dir: `~/.config/vibepod` (platformdirs-backed)
- Global file: `~/.config/vibepod/config.yaml`
- Project file: `.vibepod/config.yaml`
- Env prefix: `VP_`

Precedence: env > project > global > defaults.

## Milestones

## M0 - Repository Bootstrap

Deliverables:

- `pyproject.toml` with runtime + dev dependencies.
- Source layout under `src/vibepod`.
- Test scaffold (`pytest`, basic CLI smoke tests).
- Lint/format/type config (`ruff`, `mypy`).

Acceptance Criteria:

- `vp --help` runs locally.
- `pytest` runs with at least one passing smoke test.
- `ruff check` and `ruff format --check` pass.

## M1 - Core Domain Layer

Deliverables:

- `constants.py` for defaults and agent metadata.
- `core/config.py` with merge logic and env overrides.
- `core/agents.py` with adapter registry and validation.
- `core/docker.py` wrapper for Docker SDK interactions.

Acceptance Criteria:

- Unit tests for config merge precedence.
- Agent lookup validates known/unknown agents.
- Docker wrapper can detect daemon availability.

## M2 - Command MVP

Deliverables:

- `vp run`, `vp stop`, `vp list`, `vp version`.
- Common output helpers with Rich.
- Error-to-exit-code mapping.

Acceptance Criteria:

- `vp run claude` starts a managed container (when Docker daemon available).
- `vp list` shows running managed containers with agent + workspace.
- `vp stop claude` stops the correct container.
- `vp stop --all` stops all managed containers only.

## M3 - Logging UI + Config UX

Deliverables:

- `vp logs ui` starts/reuses Datasette container.
- `vp config show` and `vp config path`.
- Config directory first-run setup.

Acceptance Criteria:

- `vp logs ui` launches Datasette bound to configured port.
- `vp config show` displays effective merged config.
- `vp config path` prints global/project paths consistently across OS.

## M4 - Hardening + Docs

Deliverables:

- Robust error messages and troubleshooting hints.
- README aligned with actual v1 capabilities.
- Basic manual test checklist.

Acceptance Criteria:

- Clear errors for Docker unavailable, image missing, invalid agent.
- End-to-end smoke tests documented and reproducible.

## Work Breakdown (File-by-File)

1. `pyproject.toml`
2. `src/vibepod/__init__.py`
3. `src/vibepod/constants.py`
4. `src/vibepod/core/config.py`
5. `src/vibepod/core/agents.py`
6. `src/vibepod/core/docker.py`
7. `src/vibepod/utils/console.py`
8. `src/vibepod/commands/run.py`
9. `src/vibepod/commands/stop.py`
10. `src/vibepod/commands/list.py`
11. `src/vibepod/commands/logs.py`
12. `src/vibepod/commands/config.py`
13. `src/vibepod/commands/update.py` (version command only for v1)
14. `src/vibepod/cli.py`
15. `tests/test_cli.py`
16. `tests/test_config.py`
17. `tests/test_agents.py`

## Risks and Mitigations

- Docker SDK behavior differences by platform
  - Mitigation: keep a thin wrapper and centralize exception handling.
- Agent image runtime differences
  - Mitigation: adapter interface + per-agent env/mount defaults.
- Config drift as features expand
  - Mitigation: keep schema versioning and add migration hooks early.
- Logs may contain sensitive content
  - Mitigation: default body logging off; document explicitly.

## Definition of Done (v1)

- All in-scope commands implemented and documented.
- Unit tests cover config merge + command routing + agent validation.
- Manual smoke test passes on Linux/macOS with Docker Desktop/Engine.
- README reflects only implemented behavior.

## Immediate Next Step

Start M0 by scaffolding the package and wiring a minimal Typer app that exposes `vp --help` and `vp version`.
