diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index d270679..58b33b1 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -34,8 +34,8 @@ Before filing: ## Environment -- Bundle version (`cat bundle/VERSION` if cloned, or the tag you installed): vX.Y.Z -- Pinned spec version (`cat bundle/spec/VERSION`): vX.Y.Z +- Bundle version (`cat VERSION` if cloned, or the tag you installed): vX.Y.Z +- Pinned spec version (`cat spec/VERSION`): vX.Y.Z - Host (Claude Code / Cursor / Codex / other): - `anc --version` (if a workflow involving anc is at issue): - OS and shell: diff --git a/.github/ISSUE_TEMPLATE/bundle_proposal.md b/.github/ISSUE_TEMPLATE/bundle_proposal.md index 6479eca..2fa2eaa 100644 --- a/.github/ISSUE_TEMPLATE/bundle_proposal.md +++ b/.github/ISSUE_TEMPLATE/bundle_proposal.md @@ -27,15 +27,15 @@ Route check before filing: ## Proposal + of: SKILL.md, getting-started.md, references/, templates/. --> ## Type of change -- [ ] New starter template under `bundle/templates/` -- [ ] New reference doc under `bundle/references/` -- [ ] Update to `bundle/SKILL.md` (entry-point structure or routing) -- [ ] Update to `bundle/getting-started.md` (new flow, new invocation) -- [ ] Idioms for a new language/framework in `bundle/references/framework-idioms-other-languages.md` +- [ ] New starter template under `templates/` +- [ ] New reference doc under `references/` +- [ ] Update to `SKILL.md` (entry-point structure or routing) +- [ ] Update to `getting-started.md` (new flow, new invocation) +- [ ] Idioms for a new language/framework in `references/framework-idioms-other-languages.md` - [ ] Other (describe) ## Prior art @@ -50,7 +50,7 @@ Route check before filing: ideal; an outline is acceptable for early-stage proposals. --> ```diff - + ``` ## Compatibility diff --git a/.markdownlint-cli2.yaml b/.markdownlint-cli2.yaml index 351dff1..3dbb9d5 100644 --- a/.markdownlint-cli2.yaml +++ b/.markdownlint-cli2.yaml @@ -82,7 +82,7 @@ ignores: - "*.min.md" # Vendored agentnative-spec content. Edited upstream; we do not enforce # this repo's lint rules on it. Resync via scripts/sync-spec.sh. - - "bundle/spec/CHANGELOG.md" + - "spec/CHANGELOG.md" # Fix automatically when --fix is used fix: true diff --git a/AGENTS.md b/AGENTS.md index cd2d83a..83ecfce 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,44 +1,47 @@ # AGENTS.md -Project-level agent instructions for `agentnative-skill` — the producer repo for the `agent-native-cli` skill bundle. +Project-level agent instructions for `agentnative-skill` — the producer repo for the `agent-native-cli` skill. This repo is **not** a Rust CLI tool and **not** a compliance checker. It is the agent-facing guide that pairs with [`anc`](https://github.com/brettdavies/agentnative-cli) (the canonical checker) and -[`agentnative-spec`](https://github.com/brettdavies/agentnative) (the canonical principle text, vendored at -`bundle/spec/`). The bundle teaches agents how to use `anc` and supplies the surrounding context — spec, idioms, -templates — that `anc` findings reference. +[`agentnative-spec`](https://github.com/brettdavies/agentnative) (the canonical principle text, vendored at `spec/`). +The skill teaches agents how to use `anc` and supplies the surrounding context — spec, idioms, templates — that `anc` +findings reference. ## Layout -The repo is split into **the bundle** (what consumers install) and **producer-side ops** (governance, CI, plans). -Consumers only see the bundle. - -| Path | Ships to consumers? | Purpose | -| ---------------------------------------------------------------------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------- | -| `bundle/SKILL.md` | ✓ | Skill metadata + entry-point pointer to `getting-started.md`. | -| `bundle/getting-started.md` | ✓ | Three working loops (existing CLI / new Rust / other language); canonical `anc check` invocations. | -| `bundle/spec/` | ✓ | Vendored copy of `agentnative-spec` at a pinned ref. Canonical principle text + machine-readable `requirements[]`. | -| `bundle/references/` | ✓ | Implementation guidance: framework idioms (Rust + others), project structure, Rust/clap patterns. | -| `bundle/templates/` | ✓ | Drop-in starter files for greenfield Rust CLIs (`clap-main.rs`, `error-types.rs`, `output-format.rs`, `agents-md-template.md`). | -| `scripts/sync-spec.sh` | — | Vendor `agentnative-spec` into `bundle/spec/` at a pinned `SPEC_REF`. Mirror of the agentnative-cli script. | -| `scripts/generate-changelog.sh` | — | Release-time CHANGELOG generator (git-cliff + PR-body extraction). | -| `AGENTS.md`, `RELEASES.md`, `CONTRIBUTING.md` | — | Producer-repo docs. Not part of the skill. | -| `.github/rulesets/` | — | Version-controlled GitHub repository rulesets (applied post-public-flip — see `.github/rulesets/README.md`). | -| `.github/workflows/` | — | CI: markdownlint, shellcheck. Plus `guard-main-docs.yml` to keep engineering docs off `main`. | -| `.github/ISSUE_TEMPLATE/` | — | Bug report + principle proposal templates. | -| `docs/plans/` | — | Engineering plans (`dev`-only — guarded out of `main`). | -| `.markdownlint-cli2.yaml`, `.shellcheckrc`, `.gitattributes`, `.gitignore`, `cliff.toml` | — | Local lint configs, git-cliff config, and repo metadata. | +The repo ships to consumers via plain `git clone`. After install, the host (Claude Code, Codex, Cursor, OpenCode) +auto-discovers `SKILL.md` at the install root and ignores everything else. Producer-side files (`scripts/`, `docs/`, +`.github/`, `cliff.toml`, etc.) clone alongside the skill content but are inert at runtime. + +| Path | Read at runtime by host? | Purpose | +| ---------------------------------------------------------------------------------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | +| `SKILL.md` | ✓ | Skill metadata + entry-point pointer to `getting-started.md`. The host's first read. | +| `getting-started.md` | ✓ | Three working loops (existing CLI / new Rust / other language); canonical `anc check` invocations. | +| `bin/check-update` | ✓ | Consumer-side update-check script. Compares local `VERSION` to GitHub `main`; emits `UPGRADE_AVAILABLE` for the SKILL.md preamble. | +| `spec/` | ✓ | Vendored copy of `agentnative-spec`. Canonical principle text + machine-readable `requirements[]`. | +| `references/` | ✓ | Implementation guidance: framework idioms (Rust + others), project structure, Rust/clap patterns. | +| `templates/` | ✓ | Drop-in starter files for greenfield Rust CLIs (`clap-main.rs`, `error-types.rs`, `output-format.rs`, `agents-md-template.md`). | +| `VERSION` | ✓ | Single-line current version. `bin/check-update` reads this for the upgrade comparison. | +| `scripts/sync-spec.sh` | — | Vendor `agentnative-spec` into `spec/` at a pinned `SPEC_REF`. Mirror of the agentnative-cli script. | +| `scripts/generate-changelog.sh` | — | Release-time CHANGELOG generator (git-cliff + PR-body extraction). | +| `AGENTS.md`, `RELEASES.md`, `CONTRIBUTING.md`, `README.md`, `SECURITY.md` | — | Producer-repo docs. | +| `.github/rulesets/` | — | Version-controlled GitHub repository rulesets. | +| `.github/workflows/` | — | CI: markdownlint, shellcheck. Plus `guard-main-docs.yml` to keep engineering docs off `main`. | +| `.github/ISSUE_TEMPLATE/` | — | Bug report + bundle-proposal templates. | +| `docs/plans/` | — | Engineering plans (`dev`-only — guarded out of `main`). | +| `.markdownlint-cli2.yaml`, `.shellcheckrc`, `.gitattributes`, `.gitignore`, `cliff.toml` | — | Local lint configs, git-cliff config, and repo metadata. | ## Lint & Format ```bash markdownlint-cli2 '**/*.md' '!node_modules/**' -shellcheck --severity=style scripts/*.sh +shellcheck --severity=style scripts/*.sh bin/* actionlint .github/workflows/*.yml ``` The repo ships a local `.markdownlint-cli2.yaml` (canonical 120-char line length) and `.shellcheckrc` so CI and local -tooling agree. The bundle has no shell scripts to lint — `anc` is the checker and lives in its own repo. +tooling agree. ## Spec sync @@ -46,12 +49,12 @@ The canonical principle text lives in [`brettdavies/agentnative`](https://github vendors it via `scripts/sync-spec.sh` at a pinned `SPEC_REF`. To bump: ```bash -SPEC_REF=v0.2.1 scripts/sync-spec.sh # pulls from $HOME/dev/agentnative-spec by default -git diff bundle/spec/ # review +SPEC_REF=v0.3.0 scripts/sync-spec.sh # pulls from $HOME/dev/agentnative-spec by default +git diff spec/ # review ``` -Then commit the result with a message like `chore: bump bundle/spec to agentnative-spec@v0.2.1`. The current pin is -recorded in [`bundle/spec/README.md`](./bundle/spec/README.md) and the version itself is in `bundle/spec/VERSION`. +Then commit the result with a message like `chore: bump spec to agentnative-spec@v0.3.0`. The current pin is recorded in +[`spec/README.md`](./spec/README.md) and the version itself is in `spec/VERSION`. ## Branch + release model @@ -68,38 +71,38 @@ table. ## What an agent should NEVER do -- Edit anything under `bundle/spec/` by hand. It is vendored from `agentnative-spec`. Any required change is a PR - against the spec repo, then a `scripts/sync-spec.sh` bump here. -- Reimplement `anc`. The bundle does not contain shell-script duplicates of `anc`'s checks. If you find yourself writing +- Edit anything under `spec/` by hand. It is vendored from `agentnative-spec`. Any required change is a PR against the + spec repo, then a `scripts/sync-spec.sh` bump here. +- Reimplement `anc`. The skill does not contain shell-script duplicates of `anc`'s checks. If you find yourself writing `rg`-based grep checks, you're rebuilding what `anc` already does — use `anc check --output json` instead. - Commit anything under `docs/plans/`, `docs/solutions/`, `docs/brainstorms/`, or `docs/reviews/` directly to a `release/*` branch — those paths are filtered by the cherry-pick pattern. Add to `dev` instead. -- Modify `bundle/SKILL.md`'s `name` or `description` frontmatter without coordinating with consumers — those fields - drive skill discovery on every host. +- Modify `SKILL.md`'s `name` or `description` frontmatter without coordinating with consumers — those fields drive skill + discovery on every host. - Re-tag a published version. Tags are immutable historical anchors that the install endpoints pin to. - Add Rust/Cargo scaffolding. There is no Rust code in this repo and there should be none — the standard is - language-prescriptive but the bundle itself is markdown. -- Move producer-ops files into `bundle/`. The split exists deliberately so consumers don't pull repo-management - artifacts into their skills directories. + language-prescriptive but the skill itself is markdown + a tiny bash update-check. ## Common pitfalls -- The bundle's `bundle/templates/agents-md-template.md` is for downstream Rust CLI tools (`cargo build`, `cargo test`, - etc.). This top-level `AGENTS.md` describes the producer repo and is intentionally different. +- The skill's `templates/agents-md-template.md` is for downstream Rust CLI tools (`cargo build`, `cargo test`, etc.). + This top-level `AGENTS.md` describes the producer repo and is intentionally different. - `markdownlint-cli2` does NOT consult a global config — every repo needs its own `.markdownlint-cli2.yaml`. If line wrapping looks wrong, the local copy has drifted from `~/.markdownlint-cli2.yaml`. -- `bundle/spec/` is a vendored copy, not a symlink or submodule. Stale orphan files can appear if the upstream spec - renames or removes a principle. `git status` after `scripts/sync-spec.sh` surfaces them; resolve by deletion. +- `spec/` is a vendored copy, not a symlink or submodule. Stale orphan files can appear if the upstream spec renames or + removes a principle. `git status` after `scripts/sync-spec.sh` surfaces them; resolve by deletion. - `CHANGELOG.md` is generated by `scripts/generate-changelog.sh` (git-cliff + PR-body extraction). Never hand-edit it — fix the input (PR body's `## Changelog` section) and re-run. ## References -- [`bundle/SKILL.md`](./bundle/SKILL.md) — skill entry point -- [`bundle/getting-started.md`](./bundle/getting-started.md) — agent's three working loops -- [`bundle/spec/README.md`](./bundle/spec/README.md) — vendored-spec resync procedure +- [`SKILL.md`](./SKILL.md) — skill entry point +- [`getting-started.md`](./getting-started.md) — agent's three working loops +- [`spec/README.md`](./spec/README.md) — vendored-spec resync procedure - [`README.md`](./README.md) — what this repo is, repo layout, install pointer - [`SECURITY.md`](./SECURITY.md) — vulnerability disclosure - [`RELEASES.md`](./RELEASES.md) — release procedure - [`CONTRIBUTING.md`](./CONTRIBUTING.md) — how to propose changes -- [`.github/rulesets/README.md`](./.github/rulesets/README.md) — branch + tag protection apply procedure + + + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4210076..d4bb60a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,14 +1,14 @@ # Contributing to `agentnative-skill` -Thanks for your interest. This repo is the agent-facing skill bundle that pairs with two siblings: +Thanks for your interest. This repo is the agent-facing skill that pairs with two siblings: - [`agentnative`](https://github.com/brettdavies/agentnative) (the spec) — canonical principle text. Vendored here at - `bundle/spec/`. + `spec/`. - [`agentnative-cli`](https://github.com/brettdavies/agentnative-cli) (`anc`) — the canonical compliance checker. -This skill bundle does **not** define principles (the spec does) and does **not** check compliance (`anc` does). It -teaches agents how to use them and supplies surrounding context (idioms, templates, getting-started). Route -contributions accordingly. +This skill does **not** define principles (the spec does) and does **not** check compliance (`anc` does). It teaches +agents how to use them and supplies surrounding context (idioms, templates, getting-started). Route contributions +accordingly. ## Where to file what @@ -16,7 +16,7 @@ contributions accordingly. | --------------------------------------------------------------- | ----------------------------------------------------------------------------------- | | Propose a new principle, change MUST/SHOULD/MAY tiers, etc. | [`brettdavies/agentnative`](https://github.com/brettdavies/agentnative) (the spec) | | Report an `anc check` bug, or propose a new checker feature | [`brettdavies/agentnative-cli`](https://github.com/brettdavies/agentnative-cli) | -| Improve a starter template, add a language idiom, fix the guide | This repo — issue + PR. Templates: **Bug report** or **Principle proposal**. | +| Improve a starter template, add a language idiom, fix the guide | This repo — issue + PR. Templates: **Bug report** or **Bundle proposal**. | | Bump the vendored spec to a newer tag | This repo — run `scripts/sync-spec.sh` and PR the diff. | | Operate as an agent in this repo | Read [`AGENTS.md`](./AGENTS.md) first (lint commands, hard rules, common pitfalls). | @@ -45,34 +45,34 @@ procedure in [`RELEASES.md`](./RELEASES.md). ```bash markdownlint-cli2 '**/*.md' '!node_modules/**' - shellcheck --severity=style scripts/*.sh + shellcheck --severity=style scripts/*.sh bin/* actionlint .github/workflows/*.yml ``` -## Bundle vs producer-ops boundary +## Repo layout -The repository is split into: +The repo ships to consumers as a flat `git clone`. After install, the host (Claude Code, Codex, Cursor, OpenCode) +auto-discovers `SKILL.md` at the install root and ignores everything else. Producer-side files (`scripts/`, `docs/`, +`.github/`, `cliff.toml`, `AGENTS.md`, `CONTRIBUTING.md`, `RELEASES.md`) clone alongside but are inert at runtime. -- **`bundle/`** — what consumers install via `anc.dev/skill`. `SKILL.md`, `getting-started.md`, vendored `spec/`, - `references/`, `templates/`. -- **Everything else** — producer-side ops: governance (`AGENTS.md`, `RELEASES.md`, `CONTRIBUTING.md`, `SECURITY.md`), - release tooling (`scripts/`, `cliff.toml`), CI (`.github/workflows/`), rulesets (`.github/rulesets/`), engineering - plans (`docs/plans/`). +**Read at runtime by the host:** `SKILL.md`, `getting-started.md`, `bin/check-update`, `spec/`, `references/`, +`templates/`, `VERSION`. -Do not move producer-ops files into `bundle/`. Do not move bundle content out of `bundle/`. The split is what keeps -consumer skill directories clean. +**Producer-side, inert at runtime:** `scripts/`, `docs/plans/`, `.github/`, `cliff.toml`, the producer-docs above. -## Touching the bundle +## Touching the skill content -- **`bundle/spec/`** is vendored. Do not edit by hand. Substantive principle changes happen in - `brettdavies/agentnative`; bring them here by re-running `scripts/sync-spec.sh` at a new `SPEC_REF`. -- **`bundle/SKILL.md`** is the host-discovered entry point. Changes to its `name` or `description` frontmatter affect - skill discovery on every host — coordinate before changing. -- **`bundle/getting-started.md`** is the agent's first read after `SKILL.md`. Keep it short and concrete; cite spec - paths and `anc` invocations rather than restating the principles. -- **`bundle/references/`** holds implementation guidance (Rust/clap patterns, framework idioms, project structure). When - `anc --fix` lands upstream, these may shrink — they exist today because the agent has to apply remediations by hand. -- **`bundle/templates/`** are starter files. They encode principles by construction. Changes here should be informed by +- **`spec/`** is vendored. Do not edit by hand. Substantive principle changes happen in `brettdavies/agentnative`; bring + them here by re-running `scripts/sync-spec.sh` at a new `SPEC_REF`. +- **`SKILL.md`** is the host-discovered entry point. Changes to its `name` or `description` frontmatter affect skill + discovery on every host — coordinate before changing. +- **`getting-started.md`** is the agent's first read after `SKILL.md`. Keep it short and concrete; cite spec paths and + `anc` invocations rather than restating the principles. +- **`bin/check-update`** is the consumer-side update-check script. It compares local `VERSION` to GitHub `main` and + emits `UPGRADE_AVAILABLE` for the SKILL.md preamble. Treat as load-bearing — agents rely on it to detect staleness. +- **`references/`** holds implementation guidance (Rust/clap patterns, framework idioms, project structure). When `anc + --fix` lands upstream, these may shrink — they exist today because the agent has to apply remediations by hand. +- **`templates/`** are starter files. They encode principles by construction. Changes here should be informed by `agentnative-cli`'s reference patterns to avoid drift; the cross-repo alignment story is documented in the spec repo's `AGENTS.md`. @@ -91,5 +91,7 @@ By contributing, you agree your contributions are dual-licensed under the same t at the consumer's option. No CLA. The Apache-2.0 side carries the standard contributor patent grant under §3 of the license. -Vendored content under `bundle/spec/` is CC BY 4.0 (upstream); contributions to that directory should happen upstream in +Vendored content under `spec/` is CC BY 4.0 (upstream); contributions to that directory should happen upstream in [`agentnative-spec`](https://github.com/brettdavies/agentnative). + + diff --git a/README.md b/README.md index b984706..7be30b5 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # agentnative-skill -The producer repo for the [`agent-native-cli`](./bundle/SKILL.md) skill bundle — an agent-facing guide to designing, -building, and auditing CLI tools for use by AI agents. +The producer repo for the [`agent-native-cli`](./SKILL.md) skill — an agent-facing guide to designing, building, and +auditing CLI tools for use by AI agents. This skill is the third artifact in a three-repo ecosystem: @@ -15,63 +15,57 @@ This skill is the third artifact in a three-repo ecosystem: ```text agentnative-skill/ -├── bundle/ ← THE SKILL — what consumers install -│ ├── SKILL.md skill metadata + entry-point pointer to getting-started.md -│ ├── getting-started.md three working loops; canonical anc invocations -│ ├── spec/ vendored from agentnative-spec at a pinned ref (do not edit) -│ ├── references/ implementation guidance: framework idioms, project structure, Rust/clap patterns -│ └── templates/ drop-in starter files (clap-main, error-types, output-format, agents-md-template) +├── SKILL.md skill entry point — host-discovered; points the agent at getting-started.md +├── getting-started.md three working loops; canonical anc invocations +├── bin/ +│ └── check-update consumer-side update-check script (gstack-style) +├── spec/ vendored from agentnative-spec at a pinned ref (do not edit) +├── references/ implementation guidance: framework idioms, project structure, Rust/clap patterns +├── templates/ drop-in starter files (clap-main, error-types, output-format, agents-md-template) +├── VERSION single-line current version (read by bin/check-update) ├── scripts/ -│ ├── sync-spec.sh vendor agentnative-spec into bundle/spec/ at a pinned ref +│ ├── sync-spec.sh vendor agentnative-spec into spec/ at a pinned ref │ └── generate-changelog.sh release-time CHANGELOG generator (git-cliff + PR-body extraction) ├── docs/plans/ engineering plans (dev-only — guarded out of main) ├── .github/ workflows, rulesets, issue templates, PR template -├── AGENTS.md project-level agent instructions FOR THIS REPO (not the bundle) +├── AGENTS.md project-level agent instructions FOR THIS REPO (producer-side) ├── CONTRIBUTING.md how to propose changes ├── RELEASES.md release procedure (cherry-pick from dev → release/* → main) ├── SECURITY.md vulnerability disclosure ├── CHANGELOG.md released versions (generated, never hand-edited) -├── VERSION single-line current version ├── cliff.toml git-cliff configuration ├── LICENSE-MIT MIT (one half of the dual license) ├── LICENSE-APACHE Apache 2.0 (the other half) └── README.md this file ``` -The skill bundle is **`bundle/`**. Everything outside `bundle/` is producer-side ops and **does not ship to consumers**. +Consumer-facing files (`SKILL.md`, `getting-started.md`, `bin/`, `spec/`, `references/`, `templates/`, `VERSION`, +`LICENSE-*`) are read by the agent at runtime. Producer-side files (`scripts/`, `docs/`, `.github/`, `AGENTS.md`, +`CONTRIBUTING.md`, `RELEASES.md`, `cliff.toml`) ship to consumers via `git clone` but are inert at runtime — the host +discovers `SKILL.md` and ignores everything else. ## Install See [anc.dev/skill](https://anc.dev/skill) for the supported hosts (Claude Code, Cursor, Codex, etc.) and the exact -install commands. - -The install fetches `bundle/` (only) at a tagged commit SHA into the host's skills directory — for example -`~/.claude/skills/agent-native-cli/`. The installed layout looks like: - -```text -~/.claude/skills/agent-native-cli/ -├── SKILL.md -├── getting-started.md -├── spec/ -├── references/ -└── templates/ -``` - -The host auto-discovers `SKILL.md` at the root of the skill directory; `SKILL.md` then points the agent at -`getting-started.md` for progressive disclosure. - -## Bundle contents - -- [`bundle/SKILL.md`](./bundle/SKILL.md) — skill metadata + entry-point pointer. -- [`bundle/getting-started.md`](./bundle/getting-started.md) — three working loops (existing CLI / new Rust / other - language); canonical `anc check` invocations; "where things live" map. -- [`bundle/spec/`](./bundle/spec/) — vendored canonical principle text from - [`agentnative-spec`](https://github.com/brettdavies/agentnative). See - [`bundle/spec/README.md`](./bundle/spec/README.md) for the pin and resync procedure. **Do not edit by hand.** -- [`bundle/references/`](./bundle/references/) — implementation guidance: framework idioms (Rust + others), project - structure, Rust/clap patterns. Used when remediating `anc` findings. -- [`bundle/templates/`](./bundle/templates/) — drop-in starting points for greenfield Rust CLIs (`clap-main.rs`, - `error-types.rs`, `output-format.rs`, `agents-md-template.md`). +install commands. The install model is plain `git clone --depth 1` into the host's skills directory — for example +`~/.claude/skills/agent-native-cli/`. The host auto-discovers `SKILL.md` at the install root; `SKILL.md` then points the +agent at `getting-started.md` for progressive disclosure. Updates are `git pull --ff-only` from inside the install dir, +prompted by `bin/check-update`. + +## Skill contents + +- [`SKILL.md`](./SKILL.md) — skill metadata + entry-point pointer. +- [`getting-started.md`](./getting-started.md) — three working loops (existing CLI / new Rust / other language); + canonical `anc check` invocations; "where things live" map. +- [`bin/check-update`](./bin/check-update) — periodic version check. Compares local `VERSION` to GitHub `main`, emits + `UPGRADE_AVAILABLE` so the agent can offer to `git pull`. +- [`spec/`](./spec/) — vendored canonical principle text from + [`agentnative-spec`](https://github.com/brettdavies/agentnative). See [`spec/README.md`](./spec/README.md) for the pin + and resync procedure. **Do not edit by hand.** +- [`references/`](./references/) — implementation guidance: framework idioms (Rust + others), project structure, + Rust/clap patterns. Used when remediating `anc` findings. +- [`templates/`](./templates/) — drop-in starting points for greenfield Rust CLIs (`clap-main.rs`, `error-types.rs`, + `output-format.rs`, `agents-md-template.md`). The principles are also published as a stable web reference at [anc.dev/p1](https://anc.dev/p1) through `/p7`. @@ -80,8 +74,8 @@ The principles are also published as a stable web reference at [anc.dev/p1](http Tagged releases follow [SemVer](https://semver.org/). The current version lives in [`VERSION`](./VERSION); release notes are in [`CHANGELOG.md`](./CHANGELOG.md). Each tag has a corresponding GitHub Release with the same notes. -The skill's own version is independent of the spec it vendors. The currently-pinned spec version is in -[`bundle/spec/VERSION`](./bundle/spec/VERSION). +The skill's own version is independent of the spec it vendors. The currently-vendored spec version is in +[`spec/VERSION`](./spec/VERSION). ## Contributing @@ -93,7 +87,7 @@ Issues and PRs welcome — see [`CONTRIBUTING.md`](./CONTRIBUTING.md). Routing: - **`anc` bugs or feature requests** → file in [`brettdavies/agentnative-cli`](https://github.com/brettdavies/agentnative-cli). The skill teaches `anc` usage but doesn't implement the checker. -- **Skill-bundle issues** (templates, references, getting-started, layout) → file here. +- **Skill issues** (templates, references, getting-started, layout) → file here. Branch + release model documented in [`RELEASES.md`](./RELEASES.md). @@ -108,9 +102,11 @@ Dual-licensed under either of: - MIT — see [`LICENSE-MIT`](./LICENSE-MIT) - Apache License, Version 2.0 — see [`LICENSE-APACHE`](./LICENSE-APACHE) -at your option. Matches the licensing on `agentnative-cli` so producers can adapt the bundle's check scripts into their -own tooling without re-licensing friction. +at your option. Matches the licensing on `agentnative-cli` so producers can adapt the skill's content into their own +tooling without re-licensing friction. -Vendored spec content under `bundle/spec/` is CC BY 4.0 (upstream from +Vendored spec content under `spec/` is CC BY 4.0 (upstream from [`brettdavies/agentnative`](https://github.com/brettdavies/agentnative)); attribution is in -[`bundle/spec/README.md`](./bundle/spec/README.md). +[`spec/README.md`](./spec/README.md). + + diff --git a/RELEASES.md b/RELEASES.md index 97d27cf..a09a556 100644 --- a/RELEASES.md +++ b/RELEASES.md @@ -137,8 +137,8 @@ flow above). There is no separate version-bump PR to `dev`. Picking the version - **Patch** — doc updates, internal cleanups, non-substantive template edits, vendoring a patch-level spec bump. - **Minor** — new templates, new reference docs, new bundle files (backward-compatible additions), vendoring a minor-level spec bump that adds requirements without tightening existing tiers. -- **Major** — breaking changes to the bundle's contract: renaming `bundle/SKILL.md` frontmatter fields, restructuring - directory layout in ways that break existing skill installations, moving content between `bundle/` and the +- **Major** — breaking changes to the bundle's contract: renaming `SKILL.md` frontmatter fields, restructuring + directory layout in ways that break existing skill installations, moving content between `` and the producer-ops root, or vendoring a major-level spec bump (renamed/removed principles or tightened MUSTs that would regress existing consumers). diff --git a/bundle/SKILL.md b/SKILL.md similarity index 90% rename from bundle/SKILL.md rename to SKILL.md index e355613..cd5340a 100644 --- a/bundle/SKILL.md +++ b/SKILL.md @@ -4,7 +4,7 @@ description: >- Guide to designing, building, and auditing CLI tools for use by AI agents. Pairs with [`anc`](https://github.com/brettdavies/agentnative-cli) (the canonical compliance checker) and [`agentnative-spec`](https://github.com/brettdavies/agentnative) (the canonical principle text, vendored at - `bundle/spec/`). Provides starter templates, language-specific implementation idioms, and a short + `spec/`). Provides starter templates, language-specific implementation idioms, and a short getting-started guide that points agents at `anc check --output json`. Use when designing a new CLI tool, reviewing one for agent-readiness, or remediating findings from `anc`. Triggers on agentic CLI, agent-native, CLI design, CLI standard, agent-first, CLI for agents, agent-friendly CLI, CLI compliance, anc. @@ -16,7 +16,7 @@ The standard for CLI tools designed to be operated by AI agents. Three artifacts | Artifact | Role | | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [`agentnative-spec`](https://github.com/brettdavies/agentnative) | Canonical text of the seven principles. Frontmatter `requirements[]` is the machine-readable contract. Vendored into [`bundle/spec/`](./spec/) — snapshot refreshed each release. | +| [`agentnative-spec`](https://github.com/brettdavies/agentnative) | Canonical text of the seven principles. Frontmatter `requirements[]` is the machine-readable contract. Vendored into [`spec/`](./spec/) — snapshot refreshed each release. | | [`anc`](https://github.com/brettdavies/agentnative-cli) | The compliance checker. Reads target source/binary, emits a JSON scorecard whose entries cite spec `requirement_id`s. The runtime authority. | | **This skill** (`agent-native-cli`) | The agent-facing guide. Tells the agent how to invoke `anc`, how to navigate the spec when remediating findings, and where the implementation patterns and starter templates live. | @@ -25,8 +25,8 @@ surrounding context (spec, idioms, templates) that `anc`'s findings reference. ## Update check -On first invocation per session, run `bundle/bin/check-update`. It compares this bundle's `VERSION` against `main` on -GitHub and prints one of: +On first invocation per session, run `bin/check-update`. It compares this bundle's `VERSION` against `main` on GitHub +and prints one of: | Output | Meaning | | ------------------------------------ | ------------------------------------------------------------------------------- | @@ -48,9 +48,9 @@ When stdout is `UPGRADE_AVAILABLE `, ask the user via `AskUserQu Three options: - **"Yes, upgrade now"** — run `git -C pull --ff-only`. Report the new HEAD and the upgrade outcome. - The bundle root is the parent of `bundle/`; `git -C ../.. pull --ff-only` from `bundle/bin/` works for the default - install layout (`~//skills/agent-native-cli/`). If `--ff-only` rejects (uncommitted edits or divergent history), - surface git's error verbatim and stop — do not auto-stash. + The bundle root is the parent of ``; `git -C ../.. pull --ff-only` from `bin/` works for the default install layout + (`~//skills/agent-native-cli/`). If `--ff-only` rejects (uncommitted edits or divergent history), surface git's + error verbatim and stop — do not auto-stash. - **"Not now"** — write `$HOME/.cache/agent-native-cli/update-snoozed` in the format ` `, where `` is `1` (24h reminder), `2` (48h), or `3` (7 days), escalating each time the user defers. Tell the user the next reminder window. @@ -67,8 +67,8 @@ language), the canonical `anc check` invocations, and a "where things live" map. ## The seven principles -Defined in [`bundle/spec/principles/`](./spec/principles/) (vendored from `agentnative-spec` — currently `v0.2.0`; see -[`bundle/spec/README.md`](./spec/README.md) for resync instructions). One file per principle, each with machine-readable +Defined in [`spec/principles/`](./spec/principles/) (vendored from `agentnative-spec` — currently `v0.2.0`; see +[`spec/README.md`](./spec/README.md) for resync instructions). One file per principle, each with machine-readable `requirements[]` frontmatter: | # | File | Subject | diff --git a/bundle/bin/check-update b/bin/check-update similarity index 91% rename from bundle/bin/check-update rename to bin/check-update index 3c6115d..fc2d01c 100755 --- a/bundle/bin/check-update +++ b/bin/check-update @@ -1,5 +1,5 @@ #!/usr/bin/env bash -# bundle/bin/check-update — periodic version check for the agent-native-cli skill. +# bin/check-update — periodic version check for the agent-native-cli skill. # # Adapted from gstack/bin/gstack-update-check (https://github.com/garrytan/gstack). # Strips telemetry, install-type detection, migrations, and config integration; @@ -12,22 +12,21 @@ # Exit code is always 0 (failures degrade silently — no agent prompt on broken installs). # # Env overrides (for testing): -# AGENTNATIVE_SKILL_DIR — override auto-detected bundle root (defaults to script's parent dir) +# AGENTNATIVE_SKILL_DIR — override auto-detected skill (install) root (defaults to script's parent dir) # AGENTNATIVE_SKILL_REMOTE_URL — override remote VERSION URL # AGENTNATIVE_SKILL_STATE_DIR — override $HOME/.cache/agent-native-cli state directory set -euo pipefail -# Script is at /bin/check-update; bundle root is one dir up, -# repo root (which holds VERSION) is two dirs up. Consumers install via -# `git clone` so the full repo layout is present on disk. -BUNDLE_DIR="${AGENTNATIVE_SKILL_DIR:-$(cd "$(dirname "$0")/.." && pwd)}" -REPO_ROOT="$(cd "$BUNDLE_DIR/.." && pwd)" +# Script is at /bin/check-update; the skill (= install) root is +# one dir up and holds VERSION. Consumers install via plain `git clone` +# so the full repo lands at the skill root. +SKILL_DIR="${AGENTNATIVE_SKILL_DIR:-$(cd "$(dirname "$0")/.." && pwd)}" STATE_DIR="${AGENTNATIVE_SKILL_STATE_DIR:-$HOME/.cache/agent-native-cli}" CACHE_FILE="$STATE_DIR/last-update-check" SNOOZE_FILE="$STATE_DIR/update-snoozed" DISABLED_FILE="$STATE_DIR/disabled" -VERSION_FILE="$REPO_ROOT/VERSION" +VERSION_FILE="$SKILL_DIR/VERSION" REMOTE_URL="${AGENTNATIVE_SKILL_REMOTE_URL:-https://raw.githubusercontent.com/brettdavies/agentnative-skill/main/VERSION}" # ─── Step 0: Bail if disabled ───────────────────────────────── diff --git a/bundle/getting-started.md b/getting-started.md similarity index 51% rename from bundle/getting-started.md rename to getting-started.md index 7922b7f..5cab6d8 100644 --- a/bundle/getting-started.md +++ b/getting-started.md @@ -3,7 +3,7 @@ This skill teaches agents how to design, build, or audit a CLI for use by other agents. The work is one of three loops; pick the one that matches your starting point. The canonical checker is [`anc`](https://github.com/brettdavies/agentnative-cli); the canonical principle text is in -[`bundle/spec/principles/`](./spec/principles/). +[`spec/principles/`](./spec/principles/). ## You have an existing CLI @@ -12,12 +12,12 @@ pick the one that matches your starting point. The canonical checker is anc check --output json . > scorecard.json # 2. For each FAIL, look up the cited requirement_id (e.g. `p1-must-no-interactive`) -# in bundle/spec/principles/p-*.md — frontmatter `requirements[]`. +# in spec/principles/p-*.md — frontmatter `requirements[]`. # 3. Apply the fix. Patterns live in: -# bundle/references/rust-clap-patterns.md (Rust/clap) -# bundle/references/framework-idioms.md (Rust idioms) -# bundle/references/framework-idioms-other-languages.md (Click, argparse, Cobra, Commander, yargs, oclif, Thor) +# references/rust-clap-patterns.md (Rust/clap) +# references/framework-idioms.md (Rust idioms) +# references/framework-idioms-other-languages.md (Click, argparse, Cobra, Commander, yargs, oclif, Thor) # Re-run `anc check` until the scorecard is clean. ``` @@ -30,13 +30,13 @@ apply (e.g. `human-tui` for tools that legitimately intercept the TTY), `--binar cargo init my-tool && cd my-tool # Starter files. Encode P1–P7 by construction. -cp /bundle/templates/clap-main.rs src/main.rs -cp /bundle/templates/error-types.rs src/error.rs -cp /bundle/templates/output-format.rs src/output.rs -cp /bundle/templates/agents-md-template.md AGENTS.md # fill placeholders +cp /templates/clap-main.rs src/main.rs +cp /templates/error-types.rs src/error.rs +cp /templates/output-format.rs src/output.rs +cp /templates/agents-md-template.md AGENTS.md # fill placeholders # Add to Cargo.toml: clap (derive, env), serde, serde_json, thiserror, -# libc (SIGPIPE), clap_complete. See bundle/references/project-structure.md. +# libc (SIGPIPE), clap_complete. See references/project-structure.md. anc check --output json # run continuously as you build ``` @@ -44,8 +44,8 @@ anc check --output json # run continuously as you build ## You're building in another language `anc`'s source-analysis layer is Rust-only; its behavioral layer (`anc check --command `) runs against any -compiled binary on `PATH`. Read `bundle/spec/principles/p1-*.md` through `p7-*.md` for the language-agnostic -requirements, and `bundle/references/framework-idioms-other-languages.md` for per-framework idioms. +compiled binary on `PATH`. Read `spec/principles/p1-*.md` through `p7-*.md` for the language-agnostic requirements, and +`references/framework-idioms-other-languages.md` for per-framework idioms. ## Installing anc @@ -58,12 +58,12 @@ Binary name: `anc`. Prebuilt releases at ` in Rust/clap? | `bundle/references/rust-clap-patterns.md` | -| How do I implement `` in Python/Go/JS? | `bundle/references/framework-idioms-other-languages.md` | -| File a spec question or proposal | | -| File an `anc` bug | | -| File a skill-bundle issue | | +| Question | Where | +| ----------------------------------------------- | -------------------------------------------------- | +| What does P3 mean? | `spec/principles/p3-progressive-help-discovery.md` | +| What spec version does this bundle ship? | `spec/VERSION` | +| How do I implement `` in Rust/clap? | `references/rust-clap-patterns.md` | +| How do I implement `` in Python/Go/JS? | `references/framework-idioms-other-languages.md` | +| File a spec question or proposal | | +| File an `anc` bug | | +| File a skill-bundle issue | | diff --git a/bundle/references/framework-idioms-other-languages.md b/references/framework-idioms-other-languages.md similarity index 100% rename from bundle/references/framework-idioms-other-languages.md rename to references/framework-idioms-other-languages.md diff --git a/bundle/references/framework-idioms.md b/references/framework-idioms.md similarity index 100% rename from bundle/references/framework-idioms.md rename to references/framework-idioms.md diff --git a/bundle/references/project-structure.md b/references/project-structure.md similarity index 100% rename from bundle/references/project-structure.md rename to references/project-structure.md diff --git a/bundle/references/rust-clap-patterns.md b/references/rust-clap-patterns.md similarity index 100% rename from bundle/references/rust-clap-patterns.md rename to references/rust-clap-patterns.md diff --git a/scripts/sync-spec.sh b/scripts/sync-spec.sh index dbb17a1..3637083 100755 --- a/scripts/sync-spec.sh +++ b/scripts/sync-spec.sh @@ -1,5 +1,5 @@ #!/usr/bin/env bash -# Vendor agentnative-spec into bundle/spec/. +# Vendor agentnative-spec into spec/. # # Extracts files at a pinned git ref via `git show :` so the user's # spec working tree is not perturbed. The vendored tree ships as part of the @@ -16,7 +16,7 @@ # SPEC_REF Git ref (tag, branch, or SHA) to vendor. Default: v0.2.0 # # Resync cadence: rerun after every new agentnative-spec tag. Stale orphan -# files in bundle/spec/principles/ (e.g., from a spec rename) are accepted; +# files in spec/principles/ (e.g., from a spec rename) are accepted; # `git status` surfaces them at commit time. # # Mirror of agentnative-cli/scripts/sync-spec.sh; only DEST_DIR differs. @@ -27,7 +27,7 @@ SPEC_ROOT="${SPEC_ROOT:-$HOME/dev/agentnative-spec}" SPEC_REF="${SPEC_REF:-v0.2.0}" REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)" -DEST_DIR="$REPO_ROOT/bundle/spec" +DEST_DIR="$REPO_ROOT/spec" DEST_PRINCIPLES="$DEST_DIR/principles" if [[ ! -d "$SPEC_ROOT/.git" ]]; then diff --git a/bundle/spec/CHANGELOG.md b/spec/CHANGELOG.md similarity index 100% rename from bundle/spec/CHANGELOG.md rename to spec/CHANGELOG.md diff --git a/bundle/spec/README.md b/spec/README.md similarity index 100% rename from bundle/spec/README.md rename to spec/README.md diff --git a/bundle/spec/VERSION b/spec/VERSION similarity index 100% rename from bundle/spec/VERSION rename to spec/VERSION diff --git a/bundle/spec/principles/p1-non-interactive-by-default.md b/spec/principles/p1-non-interactive-by-default.md similarity index 100% rename from bundle/spec/principles/p1-non-interactive-by-default.md rename to spec/principles/p1-non-interactive-by-default.md diff --git a/bundle/spec/principles/p2-structured-parseable-output.md b/spec/principles/p2-structured-parseable-output.md similarity index 100% rename from bundle/spec/principles/p2-structured-parseable-output.md rename to spec/principles/p2-structured-parseable-output.md diff --git a/bundle/spec/principles/p3-progressive-help-discovery.md b/spec/principles/p3-progressive-help-discovery.md similarity index 100% rename from bundle/spec/principles/p3-progressive-help-discovery.md rename to spec/principles/p3-progressive-help-discovery.md diff --git a/bundle/spec/principles/p4-fail-fast-actionable-errors.md b/spec/principles/p4-fail-fast-actionable-errors.md similarity index 100% rename from bundle/spec/principles/p4-fail-fast-actionable-errors.md rename to spec/principles/p4-fail-fast-actionable-errors.md diff --git a/bundle/spec/principles/p5-safe-retries-mutation-boundaries.md b/spec/principles/p5-safe-retries-mutation-boundaries.md similarity index 100% rename from bundle/spec/principles/p5-safe-retries-mutation-boundaries.md rename to spec/principles/p5-safe-retries-mutation-boundaries.md diff --git a/bundle/spec/principles/p6-composable-predictable-command-structure.md b/spec/principles/p6-composable-predictable-command-structure.md similarity index 100% rename from bundle/spec/principles/p6-composable-predictable-command-structure.md rename to spec/principles/p6-composable-predictable-command-structure.md diff --git a/bundle/spec/principles/p7-bounded-high-signal-responses.md b/spec/principles/p7-bounded-high-signal-responses.md similarity index 100% rename from bundle/spec/principles/p7-bounded-high-signal-responses.md rename to spec/principles/p7-bounded-high-signal-responses.md diff --git a/bundle/templates/agents-md-template.md b/templates/agents-md-template.md similarity index 100% rename from bundle/templates/agents-md-template.md rename to templates/agents-md-template.md diff --git a/bundle/templates/clap-main.rs b/templates/clap-main.rs similarity index 100% rename from bundle/templates/clap-main.rs rename to templates/clap-main.rs diff --git a/bundle/templates/error-types.rs b/templates/error-types.rs similarity index 100% rename from bundle/templates/error-types.rs rename to templates/error-types.rs diff --git a/bundle/templates/output-format.rs b/templates/output-format.rs similarity index 100% rename from bundle/templates/output-format.rs rename to templates/output-format.rs