Skip to content

Onboarding is 4-5 commands, and the install instructions sit ~100 lines into the README #96

Description

@MongLong0214

The problem

Today, onboarding a repository is five separate commands, none of them discoverable from the top of the README:

git clone https://github.com/MongLong0214/commitlore ~/.commitlore
node ~/.commitlore/dist/commitlore.mjs --version
node ~/.commitlore/dist/commitlore.mjs doctor --fix
node ~/.commitlore/dist/commitlore.mjs hooks install
node ~/.commitlore/dist/commitlore.mjs index --rebuild

doctor --fix, hooks install, and index --rebuild are three separate commands a new user has to know exist, know the order of, and run every time they onboard a repository. The install instructions themselves — even after #39/#94 added a prebuilt-binary channel — sit roughly 100 lines into README.md, after the philosophy section, the trailer example, and the withdrawn-benchmark discussion.

Two projects the owner named as the standard to compare against:

  • caveman — one command (curl -fsSL .../install.sh | bash), auto-detects every agent on the machine and installs for each, ~30 seconds, the install command is in the first screen of the README.
  • ponytail — two commands, zero configuration afterwards.

The honest difference: those two are prompt rulesets with no per-repository state. CommitLore needs a git hook and an index per repository, so it cannot collapse to a single lifetime command the way they do. It can collapse to: one command to install, one command per repository.

Proposed fix

  1. commitlore init — one command replacing doctor --fix + hooks install + index --rebuild. Runs all three, reports what it did and what it could not (never silently skips a step it failed — see doctor's own fix breaks git fetch and git pull, then reports ok #63 and inject --hook-input is byte-identical on malformed input and on no-records: silent fail-open #67, the same defect class), and is safe to re-run. The three commands stay available on their own.
  2. Agent auto-detection in install.sh — after installing the binary, detect which coding agents are present (Claude Code, Codex, Gemini CLI, Cursor, Windsurf, opencode) and wire each one it can (plugin marketplace / .claude/settings.json for Claude Code, MCP registration for the rest), additively: never overwrite an existing config without saying so, never write one for an agent that is not installed.
  3. README restructure, all four languages — the install command in the first screen, before the philosophy, the trailer example, and the benchmark discussion. Everything else stays, just moves below.

Ruled out

  • Collapsing to a single lifetime command like caveman/ponytail — ruled out because the commit-msg hook and the SQLite index are per-repository state; a machine-wide install cannot set that up for a repository it has not seen yet.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions