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.