# Dobby CI/CD, README, CHANGELOG & Publishing — Design Spec

**Date:** 2026-03-26
**Goal:** Bring Dobby's CI/CD, README, CHANGELOG, and publishing infrastructure to the same standard as VibeLens. Package name: `dobby-orchestrator`.

---

## 1. pyproject.toml Overhaul

### Build Backend
Switch from setuptools to hatchling:

```toml
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
```

### Package Discovery
Replace setuptools package find with hatchling:

```toml
[tool.hatch.build.targets.wheel]
packages = ["dobby"]
```

### Metadata Updates
- `name = "dobby-orchestrator"`
- Add `readme = "README.md"`
- Add `license = "MIT"` (matches "Dobby is free. Dobby has no master.")
- Add `authors` field
- Add `keywords` (agent, orchestrator, meta-agent, claude, codex, distributed, automation)
- Add `classifiers` (Development Status: Beta, Python versions 3.11/3.12/3.13, Framework, Typing)

### Project URLs

```toml
[project.urls]
Homepage = "https://github.com/simonucl/dobby"
Repository = "https://github.com/simonucl/dobby"
"Bug Tracker" = "https://github.com/simonucl/dobby/issues"
Changelog = "https://github.com/simonucl/dobby/blob/main/CHANGELOG.md"
```

### Ruff Config (new)

```toml
[tool.ruff]
target-version = "py311"
line-length = 100

[tool.ruff.lint]
select = ["E", "F", "I", "UP", "B", "SIM"]

[tool.ruff.lint.isort]
known-first-party = ["dobby"]
```

### Dependencies
- Add `ruff>=0.8.0` to dev dependencies
- All existing dependencies and entry points remain unchanged

---

## 2. CI Workflow (`.github/workflows/ci.yml`)

Triggers on push to `main` and PRs to `main`.

Matrix: Python 3.11, 3.12, 3.13.

Steps:
1. Checkout (actions/checkout@v4)
2. Install uv (astral-sh/setup-uv@v4)
3. Install Python version via `uv python install`
4. Install deps via `uv sync --extra dev`
5. Lint: `uv run ruff check dobby/ tests/`
6. Test: `uv run pytest tests/ -v`

---

## 3. Publish Workflow (`.github/workflows/publish.yml`)

Triggers on push of `v*` tags.

Uses OIDC trusted publishing (no hardcoded PyPI tokens).

Steps:
1. Checkout
2. Install uv
3. Build: `uv build`
4. Publish: `pypa/gh-action-pypi-publish@release/v1`

Note: No static file verification needed (unlike VibeLens which bundles a frontend into the wheel). Dobby's dashboard is served at runtime, not bundled.

Requires: PyPI trusted publisher configured for the GitHub repo at pypi.org.

---

## 4. Release Workflow (`.github/workflows/release.yml`)

Triggers on push of `v*` tags.

Steps:
1. Checkout
2. Extract version from tag (strip `v` prefix)
3. Create GitHub Release using `softprops/action-gh-release@v2`
4. Auto-generate release notes from commits

---

## 5. README.md Refresh

### Badges (add to hero section)

```markdown
<a href="https://pypi.org/project/dobby-orchestrator/"><img src="https://img.shields.io/pypi/v/dobby-orchestrator?style=flat-square" alt="PyPI"></a>
<img src="https://img.shields.io/pypi/pyversions/dobby-orchestrator?style=flat-square" alt="Python 3.11+">
<a href="https://github.com/simonucl/dobby/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/simonucl/dobby/ci.yml?style=flat-square&label=CI" alt="CI"></a>
<a href="http://localhost:8420/dashboard"><img src="https://img.shields.io/badge/dashboard-live-brightgreen?style=flat-square" alt="Dashboard"></a>
```

### Installation Section Update
Add PyPI install option before the git clone:

```bash
# Install from PyPI
pip install dobby-orchestrator

# Or with uv
uv pip install dobby-orchestrator
```

Keep existing git clone / development install section below for contributors.

### Structure
Keep all existing content — only add badges and the PyPI install option. The README is already well-structured.

---

## 6. CHANGELOG.md Restructure

Reformat to Keep a Changelog standard with semantic version numbers:

```markdown
# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/).

## [Unreleased]

## [0.2.0] - 2026-03-23 — Overnight Autonomy & Distributed Execution

### Added
- ...

### Changed
- ...

## [0.1.0] - 2026-03-22 — Foundation

### Added
- ...
```

All existing content preserved, just restructured into proper sections with version numbers.

---

## 7. Supporting Files

### `.python-version`
Create with content `3.12`.

### `.gitignore` updates
Add missing patterns (matching VibeLens conventions):
- `*.py[cod]` (compiled Python)
- `.coverage`, `htmlcov/` (coverage reports)
- `.DS_Store` (macOS)
- `.idea/`, `.vscode/` (IDE files)

### License
If no LICENSE file exists, add MIT LICENSE file.

---

## 8. Release Process (Documentation)

The release process will be:
1. Update version in `pyproject.toml`
2. Update `CHANGELOG.md` (move Unreleased items to new version section)
3. Commit: `git commit -m "Release vX.Y.Z"`
4. Tag: `git tag vX.Y.Z`
5. Push: `git push && git push --tags`
6. CI automatically: runs tests → publishes to PyPI → creates GitHub Release

---

## Out of Scope

- Frontend bundling in wheel (Dobby serves dashboard at runtime via aiohttp)
- Docker image publishing (existing Dockerfile is sufficient for self-hosting)
- Codecov or other coverage services
- Pre-commit hooks
