Summary
The README already contains a strong amount of CLI reference material, but a new user still has to mentally map their situation to the right command. I’d recommend adding a compact decision table near the top of the README, before the deeper command reference.
This would make Charter easier to evaluate, especially for agent/devtool users who want to know the correct first command immediately.
Suggested section
Which command do I run?
| Situation |
Command |
| I want to inspect a repo without changing anything |
charter setup --detect-only --format json |
| I want the fastest full repo onboarding path |
charter bootstrap --ci github |
| I want to install GitHub PR governance |
charter setup --ci github --yes |
| I want to initialize ADF context modules |
charter adf init |
| I want to compile task-specific agent context |
charter adf bundle --task "Fix the login flow" |
| I want to enforce metric/file-size ceilings |
charter adf evidence --auto-measure --ci |
| I want to migrate existing agent docs |
charter adf migrate --dry-run |
| I want to validate governance in CI |
charter validate --ci --format json |
| I want to check pattern drift |
charter drift --ci --format json |
| I want to audit governance coverage |
charter audit --ci --format json |
| I want to install commit trailer normalization |
charter hook install --commit-msg |
| I want to install ADF pre-commit checks |
charter hook install --pre-commit |
Why
Charter has several powerful entrypoints: setup, bootstrap, validate, drift, audit, hook install, and the ADF command family. The functionality is there, but first-time users need a “command router” before they hit the full reference.
This would help three audiences:
- Human evaluators deciding whether to adopt Charter.
- Agent workflows that need a canonical first command.
- CI/devtool users who want to wire governance quickly without reading the entire README.
Possible placement
Place this near the top of README.md, after the short product description and before the longer setup/reference sections.
Optional follow-up
A similar table could also live in packages/cli/README.md so the package docs and repo docs stay aligned.
Summary
The README already contains a strong amount of CLI reference material, but a new user still has to mentally map their situation to the right command. I’d recommend adding a compact decision table near the top of the README, before the deeper command reference.
This would make Charter easier to evaluate, especially for agent/devtool users who want to know the correct first command immediately.
Suggested section
Which command do I run?
charter setup --detect-only --format jsoncharter bootstrap --ci githubcharter setup --ci github --yescharter adf initcharter adf bundle --task "Fix the login flow"charter adf evidence --auto-measure --cicharter adf migrate --dry-runcharter validate --ci --format jsoncharter drift --ci --format jsoncharter audit --ci --format jsoncharter hook install --commit-msgcharter hook install --pre-commitWhy
Charter has several powerful entrypoints: setup, bootstrap, validate, drift, audit, hook install, and the ADF command family. The functionality is there, but first-time users need a “command router” before they hit the full reference.
This would help three audiences:
Possible placement
Place this near the top of
README.md, after the short product description and before the longer setup/reference sections.Optional follow-up
A similar table could also live in
packages/cli/README.mdso the package docs and repo docs stay aligned.