Organize CLI Commands into User Journey Groups

Claude Code·Fable 5·

gtrrz-victor·2mo ago·20hr 19min·2 Checkpoints·27 file changes·+1748/-219·29.7K tokens

Answer: repo not use cobra's help-group feature at all. Zero hits for cobra.Group{}, AddGroup, or GroupID anywhere.

What repo has instead: noun-group parent commands — subcommand trees, not cobra help groups:

session — list, info, tokens, stop, attach, adopt, resume, current
checkpoint (cp/checkpoints) — list, explain, tokens, search, rewind
tokens — profile (labs/experimental)
agent — list, add, remove
auth — login, logout, status, contexts, use, token
doctor — trace, logs, bundle
plugin — install, list, remove
org / project / repo / grant — control-plane CRUD

Plus flat top-level verbs (enable, disable, status, clean, login, logout, version, dispatch, activity, recap, api, agent-help, …) all in one undifferentiated cobra list — see root.go:88-142.

So entire help render everything as one "Available Commands" blob. If want visual sections in help (e.g. "Core Workflow", "Control Plane", "Diagnostics"), that need cmd.AddGroup(&cobra.Group{ID: ..., Title: ...}) on root + GroupID on each child. Not done yet — clean opportunity.

Current help: 26 visible commands, flat alphabetical blob. Natural clusters by user journey:

1. "Get started" — repo lifecycle + local config enable, disable, configure, agent, plugin, status, doctor, clean

2. "Work with sessions" — daily driver commands session, checkpoint, recap, activity, dispatch

3. "Account" — identity login, logout, auth

4. "Control plane" — remote resource management org, project, repo, grant, api

5. Ungrouped → cobra's "Additional Commands" version, labs, agent-help, help

Rationale:

Split follows persona + frequency. New user only need group 1. Daily user live in group 2. Admin/platform person use group 4. Matches gh pattern: "Core commands" vs "Additional".
api sit in control plane because it target core/cell APIs — same audience as org/repo/grant. Arguable it belong in "Additional" as power-user escape hatch; control plane read better.
dispatch/activity/recap all reporting-flavored; small enough that separate "Insights" group not worth it. Five groups already near max useful — more groups = flat list again.
labs stay ungrouped on purpose — it is the discovery door for experimental stuff, grouping would over-promote.

Implementation notes:

AddGroup order = display order. Put "Get started" first.
Each child sets GroupID. Miss one → it fall to "Additional Commands" silently — worth a unit test asserting every visible root command has GroupID.
help need cmd.SetHelpCommandGroupID(...) if you want it grouped; leaving it in Additional fine.
Hidden commands need no group.

Want me to implement?

Intent: entire --help currently dumps 26 commands as one flat alphabetical list — user must scan everything to find anything. Grouping organizes help output by user journey: setup commands together, daily session/checkpoint work together, account and control-plane management separate. New user sees "get started" first; daily user spots their commands at a glance; admin commands stop cluttering everyone else's view.

Pure help-text presentation change — zero behavior change. Every command keeps same name, path, flags. Just cobra Group metadata so help renders sections instead of blob.

Done. Root help now render four titled sections instead of flat blob.

Changes (2 files):

cmd/entire/cli/root.go — group ID constants, inGroup() helper, cmd.AddGroup(...) with four groups (Entire Setup:, Sessions & Checkpoints:, Account:, Control Plane:), 21 AddCommand calls wrapped with inGroup(...). Constructors untouched.
cmd/entire/cli/root_test.go — TestRoot_VisibleCommandsAreGrouped: asserts every visible non-deprecated root command has expected GroupID (exact membership table), group IDs registered on root, and ungrouped allowlist (version, labs, agent-help, help, completion) stays ungrouped. New visible command without group → test fails with pointed message. Red first (undefined constants), green after implement.

Verified:

entire --help shows four sections + "Additional Commands" (output above).
entire agent-help --json and entire help <cmd> unchanged.
golangci-lint 2.11.3: 0 issues. Full unit suite: 7887 tests pass.

One env problem, not from my change: mise run lint broken on machine — stale golangci-lint v1.64.8 in ~/.local/share/mise/installs/go/1.26.4/bin/ shadows mise-managed 2.11.3, chokes on v2 config. I ran correct binary direct. Permanent fix: delete stale binary from go bin dir. Saved memory note.

Not committed — say when. mise run test:ci (integration + canary) not run yet; needed pre-commit per repo checklist.

Base directory for this skill: /Users/gtrrz-victor/.claude/skills/ship

Ship Changes

Commit current changes, push to remote, and update the PR.

Step 1: Analyze changes

Run git diff --stat and git diff to understand what changed
Run git status to see untracked files
Run git log --oneline -3 to match the repo's commit message style

Step 2: Commit

Stage only the relevant changed/untracked files by name (never git add -A or git add .)
Write a concise commit message that focuses on the "why" not the "what"
- If `` is provided, use it as the commit message
- Otherwise, draft one from the diff
Commit. If hooks fail, diagnose and fix — do NOT use --no-verify

Step 3: Push

Check if the branch tracks a remote: git rev-parse --abbrev-ref --symbolic-full-name @{u}
If not tracking, push with -u origin <branch>
If tracking, just git push
If push is rejected (remote has new commits), pull with rebase first then push

Step 4: Update PR

Find the open PR for the current branch: gh pr view --json number,body,title
If no PR exists, skip this step and inform the user
Compare the current PR body against the new changes:
- If the changes are within the existing PR scope, update the description to reflect the current state
- If the changes are additive or a follow-up, add a PR comment summarizing what was just pushed instead
When updating the PR body, preserve the overall structure but refresh the summary bullets and test plan
When adding a comment, keep it concise — bullet points of what changed and why
Before making any PR update (description edit or comment), show the user the exact text you plan to post and ask for their approval. Do NOT post until they confirm.

Rules

Never commit files that look like secrets (.env, credentials, tokens)
Never force push
Always show the user what was committed and the PR URL when done

2mo ago·44.6s

Committed 2311c8734, pushed, branch tracking set.

No PR exist for this branch. Proposed PR — post on your OK:

Title: cli: group root help output by user journey

Body:

Summary

entire --help rendered 26 visible commands as one flat alphabetical list; users scanned everything to find anything

Add cobra Groups so root help renders four titled sections: Entire Setup (enable, disable, configure, agent, plugin, status, doctor, clean), Sessions & Checkpoints (session, checkpoint, recap, activity, dispatch), Account (login, logout, auth), Control Plane (org, project, repo, grant, api)

version, labs, agent-help, help stay ungrouped under cobra's "Additional Commands" on purpose (meta/discovery commands)

Pure help-presentation change: no command names, paths, flags, or behavior change; agent-help output (text + JSON) unaffected

Test plan

New TestRoot_VisibleCommandsAreGrouped asserts exact group membership, registered group IDs, and that new visible root commands fail the test until assigned a group or allowlisted

mise run test:ci green (unit + integration + canary); golangci-lint 2.11.3 clean

🤖 Generated with Claude Code

Create it?

Base directory for this skill: /Users/gtrrz-victor/.claude/skills/review-pr-feedback

Review PR Feedback

Walk every unresolved review thread on the PR for the current branch. For each thread, decide whether it's actionable, fixable, or needs the user's input. Apply fixes, post a reply explaining what changed, and resolve the thread.

Step 1: Locate the PR

If `` is a number, use that PR.
Otherwise resolve from the current branch:
If there is no PR for the current branch, stop and tell the user.

Step 2: List every review thread (resolved status + bodies)

GitHub's REST endpoints don't expose isResolved, so use GraphQL:

Also pull issue-level comments for context:

Save the GraphQL result so you can reference thread IDs and the first comment's databaseId (used as the reply parent below).

Step 3: Triage and group threads

For each thread that is not already isResolved:

Read the body fully — bot comments (Cursor Bugbot, Copilot, etc.) are often long and the actionable bit is buried after metadata.
Classify as one of:
- Easy fix — uncontroversial, narrow scope (e.g. "use f.Reader instead of f.Contents", "add validation", "fix typo"). Just do it.
- Already fixed — earlier commits on the branch already addressed the concern. Don't re-fix; reply explaining where it landed.
- Outdated/no longer applies — code shape changed. Reply briefly noting the current state and resolve.
- Needs decision — design tradeoff, scope question, or "won't fix" candidate. Hold for the user.
For threads marked isOutdated: still address them; outdated ≠ irrelevant, GitHub just collapsed them because the underlying line moved.

Skip resolved threads silently — those have already been handled.

Step 4: Ask the user about the hard ones

Before applying any fixes that involve a tradeoff or non-trivial scope, batch the open questions into a single AskUserQuestion call. Group easy-fix threads as one question ("OK to apply these N small fixes and resolve?" with options for "do all", "do some", "skip"). Keep questions short and include enough context that the user doesn't have to scroll back.

If a thread reports a security or correctness concern that needs a real investigation (e.g. "race condition under concurrent X"), surface that explicitly rather than treating it as easy.

Step 5: Apply fixes

Make the code changes, then run before pushing:

Fix any linter/test fallout from the changes. Don't push if anything is red.

If a nolint directive becomes "unused" after a config change, decide between adding the type to the linter allowlist (preferred for stable cases) or removing the directive — never both.

Step 6: Commit and push

Stage only the files you changed (never git add -A). Use one commit per logical group; e.g. one for the "easy fixes" batch, one per substantial change. Commit messages focus on why, not what. Reference PR threads by topic, not by GitHub numeric ID — those don't render anywhere useful.

Push:

Step 7: Reply on each thread + resolve

Use the first comment's databaseId as the parent, not the thread ID:

Reply guidelines:

Cite the commit hash that addressed the concern: Fixed in abc1234.
Summarize what changed in one sentence — the reviewer doesn't need a detailed explanation, just enough to verify.
For "won't fix" replies, give the rationale once, briefly. Don't argue.

Step 8: Final sweep

After resolving everything you can, re-run the GraphQL query to confirm:

Report to the user:

Number of threads addressed (with one-line summary each)
Number deferred and why
Final commit hash + PR URL

Rules

Never resolve a thread without posting a reply first. The reply is the audit trail.
Don't --force push.
Don't bypass the build/lint/test gate to land "review fixes" — broken main is worse than slow review cycles.
If a reviewer's concern is wrong, explain why in the reply and resolve. Don't leave open threads festering.
If you genuinely can't tell what a thread is asking for, ask the user — don't guess and resolve.

2mo ago·3m

Both done.

Copilot feedback — 1 unresolved thread, now 0:

Comment in root_test.go claimed everything in ungrouped allowlist renders under "Additional Commands"; completion never renders (hidden via HiddenDefaultCmd). Comment fixed, replied with commit hash, thread resolved.

Conflicts — merged origin/main into branch. Main added the experimental package: build-gated "Experimental commands:" help group, moving tokens/import/review/investigate/blame/why/search/experts/runner behind experimental.Register. Conflict was only the AddCommand block in root.go; resolved as union — experimental commands keep their gate, everything else keeps journey groups. Also updated TestRoot_VisibleCommandsAreGrouped to skip experimental.GroupID commands (visibility is build-dependent).

Help now renders: Entire Setup → Sessions & Checkpoints → Account → Control Plane → Experimental commands (dev/nightly builds only) → Additional Commands. Two features compose clean.

Verified: full mise run test:ci green (unit + 117 integration + 8 canary), golangci-lint 2.11.3 zero issues, help output eyeballed.

PR now MERGEABLE (state BLOCKED = draft awaiting checks/review). Merge commit 61b3c54e1 pushed: https://github.com/entireio/cli/pull/1745