# VibePod Specification Index

**Project:** VibePod  
**Domain:** vibepod.dev  
**CLI:** `vp`  
**Version:** 1.0.0  

---

## Document Index

| # | Document | Description |
|---|----------|-------------|
| 01 | [OVERVIEW.md](01-OVERVIEW.md) | Project overview, goals, architecture |
| 02 | [CLI-COMMANDS.md](02-CLI-COMMANDS.md) | Complete CLI reference |
| 03 | [PROJECT-STRUCTURE.md](03-PROJECT-STRUCTURE.md) | Python project structure, pyproject.toml |
| 04 | [CONFIGURATION.md](04-CONFIGURATION.md) | Config files, schema, management |
| 05 | [DOCKER-INTEGRATION.md](05-DOCKER-INTEGRATION.md) | Docker SDK, containers, volumes |
| 06 | [LOGGING-DATASETTE.md](06-LOGGING-DATASETTE.md) | SQLite logging, Datasette UI |
| 07 | [CICD-WORKFLOWS.md](07-CICD-WORKFLOWS.md) | GitHub Actions, releases |
| 08 | [INSTALLATION.md](08-INSTALLATION.md) | Install scripts, Homebrew |
| 09 | [README.md](09-README.md) | Repository README template |

---

## Quick Reference

### Brand Assets

| Asset | Value |
|-------|-------|
| Domain | vibepod.dev |
| GitHub Org | github.com/VibePod |
| Docker Hub | hub.docker.com/u/vibepod |
| X/Twitter | @vibepod_dev |
| Discord | (server created) |

### Repositories

| Repository | Purpose |
|------------|---------|
| `VibePod/vibepod` | Main CLI (Python/Typer) |
| `VibePod/docs` | Documentation site |
| `VibePod/skills` | Official skills |
| `nezhar/claude-container` | → `vibepod/claude` |
| `nezhar/gemini-container` | → `vibepod/gemini` |
| `nezhar/opencode-container` | → `vibepod/opencode` |
| `nezhar/devstral-container` | → `vibepod/devstral` |
| `nezhar/auggie-container` | → `vibepod/auggie` |

### Tech Stack

| Component | Technology |
|-----------|------------|
| Language | Python 3.10+ |
| CLI Framework | Typer |
| Docker | docker-py SDK |
| Config | YAML (PyYAML) |
| Output | Rich |
| Skills | AGENTS.lock |
| Logging | SQLite + Datasette |
| CI/CD | GitHub Actions |
| Package | PyPI + PyInstaller binaries |

### Docker Images

```
vibepod/claude
vibepod/gemini
vibepod/opencode
vibepod/devstral
vibepod/auggie
vibepod/datasette
```

### Core Commands

```bash
vp run <agent>       # Start agent
vp stop --all        # Stop all
vp list              # List agents
vp logs ui           # Datasette
vp skills sync       # AGENTS.lock
vp config show       # Configuration
```

### Aliases

```bash
vp c    # → vp run claude
vp g    # → vp run gemini
vp o    # → vp run opencode
vp d    # → vp run devstral
vp a    # → vp run auggie
vp ui   # → vp logs ui
```

---

## Implementation Checklist

### Phase 1: Core CLI

- [ ] Project setup (pyproject.toml, structure)
- [ ] Basic CLI with Typer
- [ ] `vp run` command
- [ ] `vp stop` command
- [ ] `vp list` command
- [ ] Docker integration
- [ ] Configuration loading
- [ ] Aliases support

### Phase 2: Skills & Logging

- [ ] AGENTS.lock integration (`vp skills`)
- [ ] SQLite logging
- [ ] Datasette container (`vp logs ui`)
- [ ] `vp logs stats` command

### Phase 3: Polish

- [ ] `vp auth` commands
- [ ] Shell completions
- [ ] Error handling
- [ ] Tests
- [ ] Documentation

### Phase 4: Release

- [ ] GitHub Actions workflows
- [ ] PyPI publishing
- [ ] Binary builds
- [ ] Install scripts
- [ ] Homebrew formula
- [ ] vibepod.dev website

---

## Development Commands

```bash
# Setup
git clone https://github.com/VibePod/vibepod
cd vibepod
pip install -e ".[dev]"

# Development
pytest                    # Run tests
ruff check src tests      # Lint
ruff format src tests     # Format
mypy src                  # Type check

# Build
python -m build           # Build package
pyinstaller ...           # Build binary

# Release
git tag v1.0.0
git push --tags           # Triggers CI release
```

---

## External Dependencies

| Package | Version | Purpose |
|---------|---------|---------|
| typer | >=0.12.0 | CLI framework |
| docker | >=7.0.0 | Docker SDK |
| pyyaml | >=6.0 | Config parsing |
| rich | >=13.0 | Terminal output |
| platformdirs | >=4.0 | Cross-platform paths |
| agentslock | >=0.1.0 | AGENTS.lock integration |
| httpx | >=0.27.0 | HTTP client |

---

## Notes for Claude Code

When building VibePod:

1. **Start with project structure** - Create pyproject.toml and directory layout first
2. **Build incrementally** - Get `vp run claude` working before adding other features
3. **Test Docker early** - Ensure Docker SDK works before building commands
4. **Use the specs** - Reference these documents for implementation details
5. **Keep it simple** - Python readability over performance

The specs are designed to be self-contained. Each document has enough detail to implement that component.

---

## Questions?

If anything is unclear in these specs, the intent is:

- **Simple over complex** - Choose the straightforward solution
- **Python conventions** - Follow standard Python patterns
- **Docker SDK** - Use docker-py, not subprocess
- **Typer patterns** - Follow Typer's recommended CLI structure
- **YAML config** - Simple, readable configuration

Good luck building VibePod! 🎵
