bot-bottle/docs/research/polish-priorities.md

Closing the maturity gap: polish priorities

Research into what would close the perceived maturity gap between bot-bottle and a "polished" comparable like claudebox. Motivated by adopter feedback citing first-run friction, manifest authoring, and distribution as the dominant obstacles to recommending the tool to others.

Summary

"Polish" in tool-of-this-shape means a specific set of properties, most of which aren't features. Ranked roughly by leverage on the perceived maturity gap:

1. First-run friction reduction — no manifest authoring required
2. Error messages that tell the user what to do next
3. Single-command distribution (brew, curl | sh, go install)
4. Tagged releases and a real CHANGELOG
5. JSON schema for the manifest with editor integration
6. A starter library of bottles/agents for common shapes
7. A docs site, not just the README
8. Cross-platform CI

Realistic effort: 4–6 weeks of focused part-time work for one person. The single highest-impact item is collapsing first-run setup from "five steps including authoring JSON" to "one command produces a working agent" — that one change closes most of the perceived maturity gap on its own. Everything else compounds, but it compounds on top of working onboarding.

Dimensions in detail

Onboarding friction

A first-time user today goes through five steps: install Docker, install uv, set BOT_BOTTLE_CLAUDE_OAUTH_TOKEN, write bot-bottle.json, run ./cli.py start. One of those is "author a JSON manifest." Polished tools in this category let users skip that step on day one. The fix is an init subcommand that drops a working bot-bottle.json with a default coder bottle/agent into the user's home directory and prints the next command to run.

Error messages

Missing Docker, missing OAuth token, manifest typo, image build failure — each should print a one-line fix rather than a stack trace. claudebox handles this well; bot-bottle currently exits on die() calls that vary in helpfulness. A focused pass over every die() site, ensuring each message says what failed and what to do, is cheap and compounds across every user interaction.

Distribution

brew install bot-bottle or curl | sh, not "clone the repo, install Python deps, chmod cli.py." The single highest-leverage polish item, and the one that interacts with the language choice covered in bash-vs-python-vs-go.md. Staying on Python means a brew formula and a published pip package; switching to Go means a single static binary via goreleaser. Either path is real work; the Python path is shorter (~3 days) and the Go path produces a better long-term distribution story (~1–2 weeks plus a rewrite).

Versioning

Tagged releases with semver and a maintained CHANGELOG. Migration notes when the manifest schema changes. The mechanical cost is small; the signal value is large.

Schema

A JSON schema for bot-bottle.json published with a $schema URL gives VSCode and Cursor users autocomplete and inline validation. ~½ day to author the schema, plus a few hours to publish it where editors can fetch it.

Starter library

A contrib/ directory with five working bottle/agent pairs covering common shapes — generic coder, sysadmin, data analyst, research bot, deploy helper. Lowers the "I have a use case but no template" threshold without requiring users to learn the manifest format from scratch.

Documentation site

A small site (mdBook, Docusaurus, or similar) with conceptual overview, recipes, troubleshooting, and FAQ. Search. The README is a landing page; the docs are the manual. Most published tools at the maturity level being compared against have both.

Cross-platform CI

Tests run against macOS arm64, macOS amd64, and Linux amd64 in CI. Catches regressions in the test matrix surfaced in bash-vs-python-vs-go.md before users do.

Estimated ordering

Working from highest leverage downward, with rough effort estimates for one person:

1. Quickstart with init subcommand and default manifest — 1 week
2. Error message audit + JSON schema — 3 days
3. Tagged release v0.1.0 + CHANGELOG — 1 day
4. Brew formula (Python path) or Go rewrite for single-binary distribution — 3 days to 2 weeks
5. Starter library + recipes — 1 week
6. Docs site — 1 week
7. Cross-platform CI — 3 days

Total: 4–6 weeks of focused part-time work. With realistic side-project pacing, 3–4 months elapsed.

What "polish" is not

Common conflations to avoid burning effort on:

• More features. The existing feature set is the right one; the gap is reliability and onboarding, not capability. Adding features before the existing ones feel finished moves perceived maturity in the wrong direction.
• Marketing surface. "Trusted by" logos and adoption pages are not the polish HN responds to. A docs site with real recipes is worth ten landing-page redesigns.
• Aesthetic work. The project already has a logo. Aesthetic polish is well below functional polish in priority.
• A web UI. Sometimes mentioned as a polish item; it isn't, at this stage. A web UI for browsing bottles is a feature; the current CLI works. Build the UI when distribution and onboarding are solved, not before.

Recommendation

Treat the ordered list above as the polish roadmap and resist deviating to feature work until at least items 1–4 ship. Item 1 (the init subcommand and default manifest) is the single most valuable change and should be done first regardless of what else gets cut. Item 4 (single-command distribution) is the second most valuable and the one that signals "this is a real tool" to a non-author reader more than any other change.

The decision on item 4 — brew formula vs Go rewrite — should be deferred until items 1–3 ship and the project has real adoption data on whether Python distribution is causing bug reports. Until then, the cheaper Python-path version is the right choice.