chore(ops): repo setup audit fixes + single anc binary + RELEASES.md by brettdavies · Pull Request #11 · brettdavies/agentnative-cli

brettdavies · 2026-04-15T20:49:34Z

Summary

Closes the github-repo-setup and rust-tool-release skill audit findings that were quick wins, plus resolves todo 003
(single anc binary + agentnative symlink). Sets up the repo for v0.1.0 release infrastructure work (Plan 002)
without doing the publish itself.

Changelog

Changed

The installed binary is now anc. The crate is still agentnative. Homebrew users will get both anc and an
agentnative symlink (formula lands in Plan 002).

Documentation

Add RELEASES.md documenting the dev/main/release/* workflow and the Rust release pipeline (crates.io, GitHub
Releases, Homebrew dispatch).
README install section now lists all five distribution channels (Homebrew, cargo install, cargo binstall, GitHub
Releases, from source) and all five shell completions with canonical auto-loaded paths.

Type of Change

feat: New feature (single anc binary)
chore: Repo setup audit fixes
docs: RELEASES.md, README install section, completions docs

Related Issues/Stories

Todo: .context/compound-engineering/todos/003-ready-p2-ship-single-anc-binary-with-symlink.md (resolved, deleted)
Skill audits: github-repo-setup (6 findings) + rust-tool-release (12 findings); all quick-win findings
addressed; remaining work is Plan 002 (release infrastructure)

Testing

Unit tests added/updated
Integration tests added/updated
Manual testing completed
All tests passing

Test Summary:

Unit tests: 233 passing (single binary; previously ran twice as 233 × 2 due to dual [[bin]] entries)
Integration tests: 12 passing, 3 ignored (fixture tests)
cargo fmt --check clean
cargo clippy --all-targets -- -D warnings clean
cargo package --list no longer leaks .context/, .markdownlint-cli2.yaml, scripts/hooks/
Pre-push hook (fmt + clippy + test + windows compat) green on every push

Files Modified

Created:

RELEASES.md: canonical release workflow doc
.github/workflows/guard-release-branch.yml: caller for the reusable workflow
completions/anc.{bash,elvish,fish,powershell,zsh}: pre-generated completions
scripts/generate-changelog.sh, scripts/generate-completions.sh: copied from skill templates

Modified:

Cargo.toml: single [[bin]] anc, removed default-run, expanded exclude (added .context/,
.markdownlint-cli2.yaml, scripts/), added Windows binstall override
.github/workflows/release.yml: bin: anc (crate stays agentnative)
.github/rulesets/protect-main.json: added guard-release / check-release-branch-name to required status checks
src/cli.rs, src/main.rs: name = "anc" for clap usage line + completion generator
src/project.rs: user-facing depth/file-limit warnings reference anc check src/
tests/integration.rs: Command::cargo_bin("anc"), version assertion
README.md: install section, completions section, CLI reference, contributing
AGENTS.md, CLAUDE.md: anc for CLI invocations

Renamed:

.github/PULL_REQUEST_TEMPLATE.md → .github/pull_request_template.md (lowercase per convention)
completions/agentnative.<shell> → completions/anc.<shell> (matches new binary name)

Key Features

Single anc binary: eliminates the duplicate-build-target warning and halves test runtime (no more 233 × 2)
All 5 shell completions generated and committed, named anc.<shell>, README documents canonical auto-loaded
install paths (~/.local/share/bash-completion/completions/anc, "${fpath[1]}/_anc", etc.)
Package hygiene: cargo package --list is clean; no dev files leak into the published crate
Release infrastructure docs: RELEASES.md covers the full dev/main/release/* + tag/publish flow with annotated
tags (avoids the tag.gpgsign=true silent-fail trap)
Repo setup parity: guard-release-branch workflow + ruleset entry mean release/* is enforced at the workflow
level, not just by convention

Benefits

Credibility for v0.1.0: dual licensing, all install channels, complete completions story, accurate docs
Maintainability: convergence on RELEASES.md filename across brettdavies repos (bird, xurl-rs, agentnative-site
also updated this session)
Agent-readiness for the repo itself: single binary, no warnings, package contents auditable

Breaking Changes

Breaking changes described below:

The installed executable is now anc, not agentnative. This only affects users who installed the crate before today,
and there are none, since v0.1.0 hasn't shipped yet. Homebrew users will additionally get an agentnative symlink
(formula creation is in Plan 002).

Clap's help/version output always shows Usage: anc regardless of how the binary is invoked. Acceptable per the
naming rationale (`anc` is the canonical CLI name; agentnative is the project/crate name).

Deployment Notes

No special deployment steps required

This PR doesn't trigger a release. v0.1.0 publish happens in Plan 002 via a release/v0.1.0 branch from main.

Checklist

Code follows project conventions and style guidelines
Commit messages follow Conventional Commits
Self-review of code completed
Tests added/updated and passing
No new warnings or errors introduced
Changes are backward compatible (or breaking changes documented)

Additional Context

Three companion repos got related fixes this session (separate PRs/branches, not in this one):

brettdavies/xurl-rs: fixed bash completion install path bug, renamed RELEASING.md → RELEASES.md, all 5 shells
documented
brettdavies/bird: same RELEASES.md rename, 5-shell docs
brettdavies/agent-skills: rust-tool-release skill updated to require canonical completion paths and annotated
tags

Solutions doc shipped to brettdavies/solutions-docs:
best-practices/shell-completion-install-paths-in-cli-readmes-20260415.md.

…name, ruleset update - Add guard-release-branch.yml caller workflow (enforces release/* head for PRs to main) - Rename PULL_REQUEST_TEMPLATE.md to pull_request_template.md (match convention) - Add guard-release / check-release-branch-name to protect-main ruleset - Remove premature crates.io homepage URL from repo settings Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- Add .context/, .markdownlint-cli2.yaml, scripts/ to Cargo.toml exclude (prevents leaking dev-only files into crate) - Add Windows binstall override for .zip format - Generate and commit shell completions for all 5 shells (bash, elvish, fish, powershell, zsh) - Copy generate-changelog.sh and generate-completions.sh from skill templates Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Remove the dual [[bin]] setup in Cargo.toml. The crate is still `agentnative`, but the installed executable is now just `anc` — matching the ripgrep/fd convention (crate name != binary name). Homebrew users will get both `anc` and an `agentnative -> anc` symlink once the formula lands. Eliminates "file found in multiple build targets" warning and halves test runtime (previously ran the full suite twice, once per binary). ## Code changes - `Cargo.toml` — remove second `[[bin]]` and `default-run` - `src/cli.rs` — `#[command(name = "anc", ...)]` for clap Usage line - `src/main.rs` — completion generator writes `anc` as the binary name - `src/project.rs` — user-facing depth/file-limit warnings say `anc check src/` - `tests/integration.rs` — `Command::cargo_bin("anc")`, version assertion ## Completions - Regenerate all 5 shells as `completions/anc.<shell>` - Remove the old `completions/agentnative.<shell>` files ## Docs - `README.md` — binary usage updated throughout, adds Homebrew + GitHub Releases install channels, lists all 5 shell completion paths using canonical auto-loaded locations (bash: XDG, zsh: `${fpath[1]}`) - `AGENTS.md`, `CLAUDE.md` — reference `anc` instead of `agentnative` for CLI invocations; project name stays `agentnative` ## Release - `.github/workflows/release.yml` — `bin: anc` (crate stays `agentnative`) - Binstall pkg-url kept as `agentnative-{target}.tar.gz` — reusable release workflow uses `${CRATE}` for archive naming ## Tradeoff Clap help always shows `Usage: anc`. Users invoking via the `agentnative` Homebrew symlink will still see `Usage: anc`. Acceptable — `anc` is the canonical CLI name per the naming rationale. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Aligns with the github-repo-setup canonical template (used by agentnative-site). Contents: - dev/main/release/* branch flow with full daily/release-branch examples - Tag/publish pipeline (check-version, audit, build, crates.io, draft release, Homebrew dispatch, finalize) - CHANGELOG.md handling, crates.io Trusted Publishing, required secrets, branch protection, status-check context pitfall Uses annotated tags (\`git tag -a -m\`) per solutions-docs/best-practices/git-tag-fails-with-tag-gpgsign-use-annotated-tags-2026-04-13.md — bare \`git tag <name>\` silently fails when tag.gpgsign=true. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…#13) ## Summary Resolves the seven recommended fixes from the post-merge `/ce-review` of PR #12 (commit `4afef67`). All actionable findings closed; main.rs trimmed back under the 200-line trigger. ## Changelog ### Added - `value_hint = ValueHint::CommandName` on `--command` so zsh, fish, and elvish completions suggest PATH commands instead of file paths. Bash is patched post-generation in `scripts/generate-completions.sh`. - `after_help` text on `Cli` documenting the implicit default subcommand and the bare-invocation contract directly in `anc --help` output. - Mutual exclusion: `--command` and `--source` now error at parse time instead of silently producing an empty result. ### Changed - `anc -q` / `anc --quiet` (top-level flag without subcommand) now prints help and exits 2 instead of panicking via `unreachable!()` (pre-existing bug). - `anc help` and `anc help check` now work — clap's auto-generated `help` subcommand was missing from our known-subcommand set and got misclassified as a path. - `anc --command <NAME>` where NAME collides with a subcommand name (e.g. `anc --command check`) now resolves NAME as a binary on PATH instead of producing a confusing clap error. - `anc --command rg` and `anc --output json --source` (no positional argument) now work — the pre-parser detects subcommand-scoped flags and injects `check` accordingly. - `anc -- .` (POSIX double-dash separator) now runs check against `.` instead of producing undefined behavior. ### Documentation - README and AGENTS.md exit-code tables clarify that exit 2 is overloaded (failures, errors, and usage errors all share it). Suggest parsing stderr (`Usage:` text) to distinguish. ## Type of Change - [x] `fix`: Bug fix (non-breaking change which fixes an issue) ## Related Issues/Stories - Original feature: PR #12 (Plan 003 merge, commit `4afef67`) - Review run artifact: `.context/compound-engineering/ce-review/20260415-173344-efaaf5ff/` - Plan: `docs/plans/2026-04-02-003-feat-cli-default-subcommand-and-command-flag-plan.md` ## Findings Resolved | # | Severity | Title | Resolution | |---|----------|-------|------------| | 1 | P2 | clap `help` subcommand missing from known set | Append `\"help\"` to `known` after `get_subcommands()` | | 2 | P2 | `--command <NAME>` value collides with subcommand | Pair value-taking flags with their values via clap introspection | | 3 | P2 | Flag-value tokens silently fragile | Same fix as #2; also tracks subcommand-scoped flags to inject `check` when no positional follows | | 4 | P2 | `anc -q` panics via `unreachable!()` (pre-existing) | `None` arm now renders help to stderr and exits 2 | | 5 | P2 | `--command` + `--source` silent empty result | `conflicts_with = \"source\"` on `command` arg | | 6 | P2 | Bare `anc` exit 2 conflates user-error vs check-failure | Documented in README/AGENTS exit-code tables | | 7 | P2 | Default-subcommand magic not in `--help` | `after_help` block on `Cli` documents it | | 8 | P2 | `anc -- .` POSIX double-dash undefined | New branch in inject_default_subcommand | | 10 | P2 | main.rs over 200-line refactor trigger | Extract `inject_default_subcommand` + tests to new `src/argv.rs` module (538 → 203 lines) | | 14 | P3 | Bash `--command` completion uses `compgen -f` | `ValueHint::CommandName` fixes zsh/fish/elvish; bash post-patched in gen script | | 22 | P3 | `anc .` succeeds where it previously errored | Documented in PR Changelog above | Findings not addressed (intentional): #11/#12/#17/#18 (subsumed by #10 refactor), #15/#16/#19/#20/#21/#23/#24 (low-priority test/style nits or pre-public-schema concerns). ## Testing - [x] Unit tests added/updated (244 → 253, +9 covering all 5 fixed edge cases) - [x] Integration tests added/updated (26 → 34, +8 covering same) - [x] All tests passing - [x] Pre-push hook clean (fmt + clippy `-Dwarnings` + test + Windows compat) - [x] Manual probes: every previously-broken invocation now does the right thing, bare `anc` still exits 2 (fork-bomb guard intact), explicit subcommands still work **Test Summary:** - Unit tests: 253 passing (was 244) - Integration tests: 34 passing, 3 ignored (was 26 / 3) - Coverage: every fix has both a unit test (where applicable) and an integration test ## Files Modified **Modified:** - `src/cli.rs` — `after_help` text, `value_hint` on `--command`, `conflicts_with = \"source\"` - `src/main.rs` — `None` arm prints help instead of panicking; refactor extracts injection to `argv` module - `tests/integration.rs` — 8 new tests covering the fixed edge cases - `scripts/generate-completions.sh` — post-process bash to substitute `compgen -c` for `--command` (clap_complete bash backend ignores `ValueHint::CommandName`) - `completions/anc.{bash,zsh,fish}` — regenerated to expose new behavior - `README.md`, `AGENTS.md` — exit-code clarification **Created:** - `src/argv.rs` — new module hosting `inject_default_subcommand` and 19 unit tests ## Breaking Changes - [x] No breaking changes Every previous valid invocation continues to produce identical output. Previously-broken invocations (`anc help`, `anc -q`, `anc --command check`, `anc --command rg`, `anc --output json --source`, `anc -- .`) now behave correctly. ## Deployment Notes - [x] No special deployment steps required Ships with Plan 003 in the v0.1.0 `release/*` batch when Plan 002 (release infra) runs. No standalone release branch. ## Checklist - [x] Code follows project conventions and style guidelines - [x] Commit messages follow Conventional Commits - [x] Self-review of code completed - [x] Tests added/updated and passing - [x] No new warnings or errors introduced - [x] Changes are backward compatible

…11) ## Summary Closes the github-repo-setup and rust-tool-release skill audit findings that were quick wins, plus resolves todo 003 (single `anc` binary + `agentnative` symlink). Sets up the repo for v0.1.0 release infrastructure work (Plan 002) without doing the publish itself. ## Changelog ### Changed - The installed binary is now `anc`. The crate is still `agentnative`. Homebrew users will get both `anc` and an `agentnative` symlink (formula lands in Plan 002). ### Documentation - Add `RELEASES.md` documenting the dev/main/release/* workflow and the Rust release pipeline (crates.io, GitHub Releases, Homebrew dispatch). - README install section now lists all five distribution channels (Homebrew, cargo install, cargo binstall, GitHub Releases, from source) and all five shell completions with canonical auto-loaded paths. ## Type of Change - [x] `feat`: New feature (single `anc` binary) - [x] `chore`: Repo setup audit fixes - [x] `docs`: RELEASES.md, README install section, completions docs ## Related Issues/Stories - Todo: `.context/compound-engineering/todos/003-ready-p2-ship-single-anc-binary-with-symlink.md` (resolved, deleted) - Skill audits: `github-repo-setup` (6 findings) + `rust-tool-release` (12 findings) — all quick-win findings addressed; remaining work is Plan 002 (release infrastructure) ## Testing - [x] Unit tests added/updated - [x] Integration tests added/updated - [x] Manual testing completed - [x] All tests passing **Test Summary:** - Unit tests: 233 passing (single binary; previously ran twice as 233 × 2 due to dual `[[bin]]` entries) - Integration tests: 12 passing, 3 ignored (fixture tests) - `cargo fmt --check` clean - `cargo clippy --all-targets -- -D warnings` clean - `cargo package --list` no longer leaks `.context/`, `.markdownlint-cli2.yaml`, `scripts/hooks/` - Pre-push hook (fmt + clippy + test + windows compat) green on every push ## Files Modified **Created:** - `RELEASES.md` — canonical release workflow doc - `.github/workflows/guard-release-branch.yml` — caller for the reusable workflow - `completions/anc.{bash,elvish,fish,powershell,zsh}` — pre-generated completions - `scripts/generate-changelog.sh`, `scripts/generate-completions.sh` — copied from skill templates **Modified:** - `Cargo.toml` — single `[[bin]] anc`, removed `default-run`, expanded `exclude` (added `.context/`, `.markdownlint-cli2.yaml`, `scripts/`), added Windows binstall override - `.github/workflows/release.yml` — `bin: anc` (crate stays `agentnative`) - `.github/rulesets/protect-main.json` — added `guard-release / check-release-branch-name` to required status checks - `src/cli.rs`, `src/main.rs` — `name = "anc"` for clap usage line + completion generator - `src/project.rs` — user-facing depth/file-limit warnings reference `anc check src/` - `tests/integration.rs` — `Command::cargo_bin("anc")`, version assertion - `README.md` — install section, completions section, CLI reference, contributing - `AGENTS.md`, `CLAUDE.md` — `anc` for CLI invocations **Renamed:** - `.github/PULL_REQUEST_TEMPLATE.md` → `.github/pull_request_template.md` (lowercase per convention) - `completions/agentnative.<shell>` → `completions/anc.<shell>` (matches new binary name) ## Key Features - **Single `anc` binary** — eliminates the duplicate-build-target warning and halves test runtime (no more `233 × 2`) - **All 5 shell completions** generated and committed, named `anc.<shell>`, README documents canonical auto-loaded install paths (`~/.local/share/bash-completion/completions/anc`, `"${fpath[1]}/_anc"`, etc.) - **Package hygiene** — `cargo package --list` is clean; no dev files leak into the published crate - **Release infrastructure docs** — `RELEASES.md` covers the full dev/main/release/* + tag/publish flow with annotated tags (avoids the `tag.gpgsign=true` silent-fail trap) - **Repo setup parity** — guard-release-branch workflow + ruleset entry mean release/* is enforced at the workflow level, not just by convention ## Benefits - **Credibility for v0.1.0**: dual licensing, all install channels, complete completions story, accurate docs - **Maintainability**: convergence on `RELEASES.md` filename across brettdavies repos (bird, xurl-rs, agentnative-site also updated this session) - **Agent-readiness for the repo itself**: single binary, no warnings, package contents auditable ## Breaking Changes - [x] Breaking changes described below: The installed executable is now `anc`, not `agentnative`. This only affects users who installed the crate before today — and there are none, since v0.1.0 hasn't shipped yet. Homebrew users will additionally get an `agentnative` symlink (formula creation is in Plan 002). Clap's help/version output always shows `Usage: anc` regardless of how the binary is invoked. Acceptable per the naming rationale (\`anc\` is the canonical CLI name; `agentnative` is the project/crate name). ## Deployment Notes - [x] No special deployment steps required This PR doesn't trigger a release. v0.1.0 publish happens in Plan 002 via a `release/v0.1.0` branch from main. ## Checklist - [x] Code follows project conventions and style guidelines - [x] Commit messages follow Conventional Commits - [x] Self-review of code completed - [x] Tests added/updated and passing - [x] No new warnings or errors introduced - [x] Changes are backward compatible (or breaking changes documented) ## Additional Context Three companion repos got related fixes this session (separate PRs/branches, not in this one): - `brettdavies/xurl-rs` — fixed bash completion install path bug, renamed `RELEASING.md` → `RELEASES.md`, all 5 shells documented - `brettdavies/bird` — same `RELEASES.md` rename, 5-shell docs - `brettdavies/agent-skills` — `rust-tool-release` skill updated to require canonical completion paths and annotated tags Solutions doc shipped to `brettdavies/solutions-docs`: `best-practices/shell-completion-install-paths-in-cli-readmes-20260415.md`. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

## Summary Lockstep update with `brettdavies/agentnative-skill` PR #11. Both repos now share an identical `sync-spec.sh` shape; only `DEST_DIR` differs (`src/principles/spec/` here vs `spec/` in the skill repo). Two coordinated changes to `scripts/sync-spec.sh`: 1. **Drop `SPEC_REF` override entirely.** The script always vendors the latest `v*` tag; no opt-in version selection. Removes the `SPEC_REF` env var, the `SPEC_REF` default that constantly went stale (last value `v0.3.0`), and all the doc references that pointed at manual bumps. 2. **Resolve from remote first, fall back to local.** New flow: 1. `git ls-remote --tags --sort=-version:refname` against `SPEC_REMOTE_URL` (default `https://github.com/brettdavies/agentnative.git`) to discover the latest tag without a checkout. 2. Fall back to `git -C \"$SPEC_REPO\" tag --sort=-version:refname` only when the remote query fails or returns no tags. Prior order was the opposite — local-first, with remote as override. 3. Document offline use via `--from-local <path>` for full reproducibility (no network needed if the user has a checkout already). ## Changelog ### Changed - Vendoring now always tracks the latest published spec tag — `SPEC_REF` env override removed. Run `bash scripts/sync-spec.sh` to refresh; no environment configuration required. ### Documentation - `AGENTS.md` and `src/principles/spec/README.md` updated to reflect the simpler vendor flow. ## Type of Change - [x] `chore`: Maintenance tasks (dependencies, config, etc.) ## Related Issues/Stories - Lockstep with: `brettdavies/agentnative-skill` PR #11 ## Testing - [x] Manual testing completed - [x] All checks passing **Test Summary:** Pre-push hook passed (fmt, clippy `-Dwarnings`, test, cargo-deny, Windows compatibility). ## Files Modified **Modified:** - `scripts/sync-spec.sh` — remote-first resolution, SPEC_REF removed - `AGENTS.md` — vendor-flow doc updates - `src/principles/spec/README.md` — vendor-flow doc updates ## Breaking Changes - [x] No breaking changes (consumer-facing — anyone who relied on `SPEC_REF` for a non-latest tag must now use `--from-local <path-to-checkout-at-desired-tag>`). ## Deployment Notes - [x] No special deployment steps required. ## Checklist - [x] Code follows project conventions and style guidelines - [x] Commit messages follow Conventional Commits - [x] Self-review of code completed - [x] No new warnings or errors introduced - [x] Changes are backward compatible

brettdavies and others added 4 commits April 15, 2026 14:19

brettdavies merged commit 45b5234 into dev Apr 15, 2026
6 checks passed

brettdavies deleted the chore/repo-setup-fixes branch April 15, 2026 20:52

brettdavies mentioned this pull request Apr 15, 2026

fix(cli): close 7 review findings on default subcommand + --command #13

Merged

14 tasks

brettdavies mentioned this pull request Apr 29, 2026

chore(sync-spec): modernize — remote-first, drop SPEC_REF #33

Merged

10 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

chore(ops): repo setup audit fixes + single anc binary + RELEASES.md - #11

chore(ops): repo setup audit fixes + single anc binary + RELEASES.md#11
brettdavies merged 4 commits into
devfrom
chore/repo-setup-fixes

brettdavies commented Apr 15, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

brettdavies commented Apr 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changelog

Changed

Documentation

Type of Change

Related Issues/Stories

Testing

Files Modified

Key Features

Benefits

Breaking Changes

Deployment Notes

Checklist

Additional Context

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

brettdavies commented Apr 15, 2026 •

edited

Loading