From 7e0e256370b26a632540054fd91c1d8fc4b5853d Mon Sep 17 00:00:00 2001 From: didericis Date: Sun, 10 May 2026 20:38:44 -0400 Subject: [PATCH] docs: add research note on polish priorities to close the maturity gap MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Captures the ranked list of changes that would move the project from "works for me" toward the perceived maturity of comparable tools — onboarding friction, error messages, distribution, versioning, schema validation, starter library, docs site, cross-platform CI. Includes effort estimates and an explicit "what polish is not" section so the roadmap doesn't drift into feature work. Co-Authored-By: Claude Opus 4.7 --- docs/research/polish-priorities.md | 146 +++++++++++++++++++++++++++++ 1 file changed, 146 insertions(+) create mode 100644 docs/research/polish-priorities.md diff --git a/docs/research/polish-priorities.md b/docs/research/polish-priorities.md new file mode 100644 index 0000000..cad524f --- /dev/null +++ b/docs/research/polish-priorities.md @@ -0,0 +1,146 @@ +# Closing the maturity gap: polish priorities + +Research into what would close the perceived maturity gap between +claude-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 `CLAUDE_BOTTLE_OAUTH_TOKEN`, write +`claude-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 `claude-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; claude-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 claude-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 `claude-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.