atomic-cli-contrib

name: atomic-cli-contrib description: Conventions for editing the atomic CLI and command artifacts in this repo. Auto-fires on phrases like "add a CLI subcommand", "wire a new flag", "prompt the user", "add a doctor check", "add a doctor repair", "edit cmd/atomic/main.go", "extend claudeinstall", "add an internal package", "use huh", "add a command", "create a new verb", "add a partial", "render templates", "edit a command", "edit commands/", "create a new command", "edit an agent", "edit agents/", or "add an agent". Contributor-only — never bundled, never installed. user-invocable: false

atomic-cli-contrib

Project-local skill for working on the atomic CLI in this repo. Captures conventions that emerged from the doctor, validate, and config work, plus the prompt-layer extraction. Read this before adding subcommands, flags, prompts, or new internal packages.

This skill is contributor-scope only. It lives under .claude/skills/ and is auto-loaded for sessions in this repo. It is not bundled (see atomic/internal/bundlemirror/mirror.go — only skills/atomic-*/ at the repo root ships).

1. Interactive prompts go through internal/prompt/

• Single surface. Every interactive prompt — install flows, doctor --fix, future atomic config, anything new — calls internal/prompt.Confirm or internal/prompt.Select[T]. No direct huh.* calls outside the prompt package. No bufio.Scanner prompters.
• Why. One swap point when huh changes API. Consistent TTY detection. Consistent abort handling.
• Sentinels. Callers branch on errors.Is(err, prompt.ErrNonInteractive) (no TTY → skip path) and errors.Is(err, prompt.ErrAborted) (Ctrl+C → distinct from "No"). Never collapse abort into decline.
• Doctor adapter. The doctor's Prompter interface lives separately so the --fix loop can have its own decision shape (DecisionYes/DecisionNo/DecisionSkip/DecisionAbort). The adapter (doctor/stdin_prompter.go) translates from internal/prompt errors. Mirror the adapter pattern if you build a new prompt-consuming subsystem.

2. Testable seams via function-field structs

• Pattern. For any subsystem that calls external collaborators (filesystem, network, prompt, time), define a struct of function fields:

  type MyStep struct {
      Classify  func(scopeRoot, want string) (Result, error)
      Write     func(scopeRoot, value string) error
      Confirm   func(title, desc string, def bool) (bool, error)
      Logger    io.Writer
      AssumeYes bool
  }
  

  Default factory wires production deps. Tests inject stubs.

• Public entry points. Expose *WithStep variants alongside the bare verb: Install, InstallWithStep, Update, UpdateWithStep. CLI dispatch always uses the seam-aware form (InstallWithStep(target, ..., step)) so flags can plumb through.

• Why. Unit tests stay TTY-free, network-free, filesystem-free where possible. Seam-stubbed tests catch dispatch bugs but cannot catch path-resolution bugs (see §3 for the failsafe — the scope-root family of mistakes survives seam tests trivially).

3. End-to-end tests against real paths

Seam-stubbed tests prove dispatch logic, not path resolution. For anything that reads or writes user state (~/.claude/..., ~/.config/atomic/...), add at least one test that:

• Uses t.Setenv("HOME", t.TempDir()) or equivalent.
• Writes a fixture at the path production would actually read.
• Calls the production entry point (not the seam).
• Asserts on the real file on disk.

The scope-root double-prepend class of bug (caller passes ~/.claude as scopeRoot, callee internally prepends .claude/ again, real production runs miss the user's actual file) passes seam-stubbed tests trivially because the test fixture is written to the buggy resolved path. A t.Setenv("HOME", ...) end-to-end test is the only thing that catches it.

4. scopeRoot is the parent of .claude/, not .claude/ itself

The outputstyle.* and settingsjson.* helpers expect scopeRoot to be the directory that contains .claude/. They internally resolve <scopeRoot>/.claude/settings.json.

• Default user scope: scopeRoot = $HOME, settings at $HOME/.claude/settings.json.
• CLI flag --target defaults to $HOME/.claude (the .claude/ dir itself). Callers must pass filepath.Dir(target) as scopeRoot. Three call sites had this wrong before the fix; check any new caller.
• hooks.Install(repoRoot, home) follows the same convention — pass home, not home + "/.claude". Mirror that precedent.

5. axiom interactions for new CLI surfaces

When adding a verb, flag, or repair:

6. New internal packages

• Path: atomic/internal/<package>/.
• Tests co-located: <package>_test.go next to <package>.go. Fixtures in <package>/testdata/ if needed.
• Public surface kept small. Don't export internal helpers that only one caller uses — keep them unexported.
• Core third-party Go deps: gopkg.in/yaml.v3 (frontmatter), github.com/tailscale/hujson (JWCC settings.json), github.com/BurntSushi/toml (config), github.com/charmbracelet/huh (prompts; transitively pulls bubbletea + lipgloss + friends). Add a new dep only when there's a concrete capability gap and the dep is well-maintained. Document the why in the commit message.

7. Doctor: adding a check

• File: atomic/internal/doctor/checks_<name>.go (production wrapper + Run<Name>With(scopeRoot) testable inner function).
• Register in doctor.go's categories slice. Pick a stable index (don't reorder existing entries — tests assert on indices).
• Severity defaults: PASS / WARN / SKIP from Result.Severity. Reserve FAIL for things that prevent atomic itself from running.
• --fix repair: add to repairPlan + applyRepair switch in fix.go. Implement default<Name>Repair in fix_impls.go. Use the existing *RepairFn global + Set*RepairFn test seam. Repair runs only after the loop's per-item Confirm returns DecisionYes.
• Spec: append a ## Change log entry to docs/spec/atomic-doctor.md when adding or changing a check. See "Spec files are append-mostly" in CLAUDE.md.

8. CLI dispatch (cmd/atomic/main.go)

• One runX function per top-level verb. Flag parsing inside runClaude / runDoctor / etc.
• Subverb dispatch (e.g. claude install vs claude list) uses a string switch on args[0]. Lowercase, hyphen-separated.
• Flags use stdlib flag.NewFlagSet(verb, flag.ContinueOnError). No cobra or urfave/cli — too much surface for the size we're at.
• Bool flags that change destructive behavior (--yes, --force): default false, name them positively, scope tightly. Don't broaden a --yes flag's effect across multiple prompts in one CL — convention is one-prompt-one-flag, not omnibus consent.
• Error to stderr, exit non-zero. Use fmt.Fprintln(os.Stderr, ...) not log.Println (no timestamps in CLI output).
• Post-install "next steps" text: keep it short, mention only actions the user must still take. Anything the install just did automatically should NOT be in next steps — that's a stale-doc trap, and stale "next steps" lines outlive the code that obsoletes them by multiple reviews.

9. Build hygiene

• make -C atomic build outputs to atomic/bin/atomic per the Makefile.
• go build ./cmd/atomic (run from inside atomic/) drops a binary at atomic/atomic. Gitignored at the repo root (/atomic/atomic, /atomic/bin/, /atomic/tmp/).
• go build from the repo root targeting ./atomic/cmd/atomic drops the binary at the repo root — won't happen in normal workflow but worth knowing.
• The bundle regenerator runs on every commit that touches a source artifact (agents/, commands/, skills/, output-styles/, rules/, CLAUDE.md). Pure atomic/ changes do NOT trigger a regen. See .githooks/pre-commit.

10. Command & agent artifact templates — templates/ is the only edit path

Both commands/ AND agents/ are fully generated from templates/ via make render. Never edit commands/<name>.md or agents/<name>.md directly — the change is overwritten on the next render. The rendered kinds and their order are defined in templaterender.renderedKinds (["commands", "agents"]).

Source of truth:

• templates/commands/<name>.md — verb-specific orchestration for that command.
• templates/agents/<name>.md — agent body. Most are self-contained; builder + surgeon pull verbatim-shared blocks via {{ template "agent-*" . }}.
• templates/shared/<name>.md — reusable partials included via {{ template "<name>" . }}. One shared pool for both kinds.

Partial taxonomy:

Adding a new command or agent: drop templates/commands/<name>.md or templates/agents/<name>.md, run make render. Never create the output file directly.

Removing a command or agent: delete BOTH the template AND the rendered output. An orphan output file without a matching template causes make render to halt with a non-zero, kind-aware error.

Partial design rules:

• Pure fragments only. No dict function, no {{ if }} conditionals, no variant flags inside partials. When two consumers diverge by one word (e.g. builder/surgeon git-state rule), generalize the wording so the partial stays verbatim-shared, or keep that bullet inline per-agent.
• Optional sub-fragments are their own micro-partials (e.g. doc-impact-why is separate from doc-impact so callers can include one without the other).
• To verify: make render && git diff --exit-code commands/ agents/ must exit 0 after any template edit.

Render workflow:

make render                                # regenerate commands/ and agents/ from templates/
git diff --exit-code commands/ agents/     # assert no stale output

The pre-commit hook auto-runs make render and re-stages commands/ and agents/ whenever any templates/ file is staged.

11. Manual exercisers in tmp/

• tmp/ is gitignored except for the two .gitkeep files.
• Real bugs that hide behind seam-stubbed tests surface fast under a sandboxed HOME exerciser. Pattern: mkdir -p tmp/sandbox/.claude, HOME=$PWD/tmp/sandbox tmp/build/atomic ..., then assert on the file the CLI was supposed to write. Three scope-root bugs were found this way that the unit tests missed.
• Keep these scripts cheap to write and re-runnable. Don't commit them (gitignored is correct) but reference them in PR descriptions when they helped find a bug.

12. Library references

charmbracelet/huh — interactive forms / prompts

• Repo: https://github.com/charmbracelet/huh
• Pkg docs: https://pkg.go.dev/github.com/charmbracelet/huh
• Bubbletea (underlying TUI runtime): https://github.com/charmbracelet/bubbletea
• Lipgloss (styling): https://github.com/charmbracelet/lipgloss
• Showcase / patterns: https://github.com/charmbracelet/huh#examples

How we use it today (atomic/internal/prompt/prompt.go):

• huh.NewConfirm().Title(t).Description(d).Affirmative("Yes").Negative("No").Value(&result) — binary y/n. Wrapped as prompt.Confirm.
• huh.NewSelect[T]().Title(t).Description(d).Options(opts...).Value(&result) — single pick from a typed list. Wrapped as prompt.Select[T]. Constraint: T comparable (huh's restriction, not ours).
• huh.NewOption[T](label, value).Description(desc) — option constructor.
• huh.NewForm(huh.NewGroup(field, field, ...)).Run() — runs the form. We currently use one field per form; group is the structural unit for multi-field future.
• huh.ErrUserAborted — Ctrl+C sentinel. Mapped to prompt.ErrAborted in defaultRunConfirm.

Likely next uses (when atomic config lands or new prompts arrive):

• huh.NewInput().Title(t).Value(&str).Validate(fn) — free-form text input with validation. Use for "what's your name" / "what's your project slug" style fields.
• huh.NewMultiSelect[T]().Options(...).Value(&[]T) — multi-select. Reserve for fixed small choice sets only (per axiom 4 — use plain-text indexed selection for ≥4 unbounded items).
• huh.NewText().Title(t).Value(&str).Lines(N) — multi-line input. Probably overkill for atomic; flag if proposed.
• huh.NewGroup(...).WithHideFunc(func() bool { return !cond }) — conditional reveal across fields. The reason huh was chosen — once we have grouped config wizards this pays off.
• .Validate(func(s string) error { ... }) — per-field validation. Return errors.New("...") to keep the user in the field with an error message.
• huh.NewForm(...).WithTheme(huh.ThemeBase()) — strip the default rounded-border styling if it clashes with atomic minimalism. Tracked as an open question for the look-and-feel pass.

Gotchas:

• huh switches the terminal to alt-screen / raw mode. In non-TTY environments Form.Run() errors immediately; our internal/prompt package detects this before reaching huh and returns ErrNonInteractive instead.
• NewConfirm has no explicit .Default(bool) builder. Set the bound variable to the default before Form.Run() and rely on huh's PointerAccessor reading through the pointer at render time. Revisit on every huh upgrade — if a future huh version resets bound values during form init, every confirm silently becomes false. (Tracked in .claude/project/followups.md as install-output-style-F-2.)
• huh re-renders on every keystroke. Don't pass huge Description strings — keep them to one line where possible.

tailscale/hujson — JWCC (JSON with comments + commas)

• Repo: https://github.com/tailscale/hujson
• Pkg docs: https://pkg.go.dev/github.com/tailscale/hujson
• JWCC spec context: https://nigeltao.github.io/blog/2021/json-with-commas-comments.html

How we use it (atomic/internal/hooks/hooks_hujson.go, atomic/internal/outputstyle/outputstyle.go, atomic/internal/settingsjson/settingsjson.go):

• hujson.Parse(b []byte) (*hujson.Value, error) — parse JWCC bytes into an AST. The AST preserves comments, trailing commas, key order, blank lines.
• hujson.Standardize(b []byte) ([]byte, error) — JWCC → strict JSON bytes (comments stripped, trailing commas removed). Use this only when handing bytes to json.Unmarshal. Never write the standardized bytes back to the user's file — that destroys their formatting.
• Value.Pack() []byte — serialize the AST back to JWCC bytes, preserving everything the parse captured. This is the surgical-merge primitive.
• Value.Value — the underlying hujson.ValueTrimmed payload (an Object, Array, Literal, String, etc.).
• Object.Members []ObjectMember — ordered list of key/value pairs. Mutate in place to add/remove/replace fields.
• ObjectMember.Name (key) and .Value (value), both as Value (so they carry their own before/after comment metadata).

Our reusable helpers (atomic/internal/settingsjson/settingsjson.go):

• EnsureObject(v *hujson.Value) (*hujson.Object, error) — coerce a Value to an Object or fail loudly.
• FindMember(obj *hujson.Object, name string) (int, bool) — locate a top-level key by name.
• RemoveMember(obj *hujson.Object, name string) — drop a key in place.
• ParseJSONString(raw []byte) (string, error) — decode a JSON-encoded string literal (e.g. an ObjectMember.Value that holds a string).
• TopLevelKeys(v *hujson.Value) ([]string, error) — capture top-level key order; useful as the input to an iron-rule guardrail (snapshot keys before mutation, compare after, refuse to commit the rename if any original key is missing).

Likely next uses:

• Reading any new user-config file that allows comments. Today only ~/.claude/settings.json is JWCC; future config surfaces should follow.
• Mutating a nested key (e.g. permissions.allow). The same AST pattern applies — walk down via Object.Members, then mutate the target member. Don't re-marshal the whole tree.
• Inserting a new top-level key while preserving order: append to obj.Members. Inserting at a specific index: slice splice.

Gotchas:

• hujson.Parse returns a pointer to Value. Modifications mutate in place.
• Value.Pack() produces canonical JWCC, not byte-identical input. Whitespace around tokens may shift; comment text and trailing commas survive. The iron rule guards against key loss, not whitespace stability.
• json.Unmarshal does NOT accept JWCC. Always Standardize first if you need a Go struct. Pattern: hujson.Parse for validation (returns an AST), then hujson.Standardize + json.Unmarshal to extract typed values.
• Comments belong to the following token. When removing a member, its BeforeExtra comment goes with it. Removing a key with an important comment loses the comment — flag this if it ever bites.

Common mistakes to avoid

1. Passing the .claude/ dir as scopeRoot. Always one level higher. See §4.
2. Adding a new prompt with direct huh.* calls. Route through internal/prompt. See §1.
3. Marshaling a Go struct over the user's settings.json. Wipes their comments, plugin keys, custom hooks. Use the internal/settingsjson AST helpers. See atomic/internal/outputstyle/outputstyle.go:Write for the surgical merge pattern.
4. Trusting seam-stubbed tests for path-resolution coverage. They won't catch scope-root bugs. Add at least one t.Setenv("HOME", ...) end-to-end test per new state-touching subsystem. See §3.
5. Broadening --yes to silence unrelated prompts. The flag's contract is "auto-accept this specific prompt." A future PR that conflates non-interactive (no TTY) with --yes (user consent) breaks the iron rule from axiom 3.
6. Forgetting to delete stale "next steps" text when the install step starts doing the thing automatically. The CLI's own user-facing output is documentation too — keep it synchronized with the code.
7. Citing an atomic CLI flag or verb in an artifact without verifying it against the binary. Before writing atomic <verb> --some-flag into any command, agent, skill, doc, or CLAUDE.md, confirm the spelling against atomic <verb> --help from a binary built from local source (go build -o /tmp/atomic ./cmd/atomic run inside atomic/), not the globally-installed atomic (which lags your branch) and not memory. This is how atomic code … --format json shipped across six agent prompts when the real flag is --json — a wrong flag in an artifact fails silently at author time and only surfaces when a user runs the example. The binary's own --help is the source of truth; artifacts must match it. atomic validate artifacts now automates this check — it is wired into bare atomic validate and the CI step, so wrong-flag citations in committed artifacts fail CI. Run atomic validate artifacts locally after editing any artifact that cites a CLI flag.

Related

• docs/spec/atomic-doctor.md — doctor check + repair conventions.
• docs/spec/atomic-state-and-config.md — TOML config + state directory contract.
• docs/spec/atomic-validate.md — bundle parity + cross-reference linting.
• .claude/rules/authoring/axioms.md — the five design axioms this skill cross-references.
• The harness agent roster (injected each session) — when to delegate CLI work to atomic-implementer (feature vs surgical mode).