docs: add research note on polish priorities to close the maturity gap

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 <noreply@anthropic.com>
2026-05-10 20:38:44 -04:00
parent 79604fded7
commit 7e0e256370
1 changed files with 146 additions and 0 deletions
@@ -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.