Skip to content

chore(repo): restructure bundle into bundle/, add changelog generator, expand governance #3

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
brettdavies merged 2 commits into from
Apr 27, 2026
Merged

chore(repo): restructure bundle into bundle/, add changelog generator, expand governance #3

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
28476fa
chore(repo): restructure bundle into bundle/, add cliff.toml + genera…
brettdavies Apr 27, 2026
0f4bd0a
chore(repo): sync PR template — add **Renamed:** subsection under Fil…
brettdavies Apr 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 7 additions & 4 deletions .github/CODEOWNERS
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,9 @@
# Mandatory review on anything that runs on user machines at install time.
# Mandatory review on anything that runs on user machines at install time, and
# on producer ops that determine what ships.
# See: master plan risk row "Shell scripts in producer repo execute on user machines".

scripts/** @brettdavies
.github/workflows/** @brettdavies
.github/CODEOWNERS @brettdavies
bundle/scripts/** @brettdavies
scripts/** @brettdavies
.github/workflows/** @brettdavies
.github/rulesets/** @brettdavies
.github/CODEOWNERS @brettdavies
39 changes: 39 additions & 0 deletions .github/ISSUE_TEMPLATE/bug_report.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
---
name: Bug report
about: A check produces wrong results, a script fails, or a doc says one thing while the code does another.
title: "bug: <short description>"
labels: bug
---

## What happened

<!-- One or two sentences. Include the command you ran and the unexpected behavior. -->

## What you expected

<!-- One sentence — what should the bundle have done instead? -->

## How to reproduce

1. 1. 1.

```bash
# exact commands; redact paths/credentials
```

## Environment

- Bundle version (`cat bundle/VERSION` if cloned, or the tag you installed): vX.Y.Z
- Host (Claude Code / Cursor / Codex / other):
- Target tool the checker was run against (if applicable): owner/repo @ commit
- OS and shell:
- `bundle/scripts/check-compliance.sh --principle N` output (if relevant):

```text
<paste relevant scorecard rows or error output>
```

## Why this is a bundle bug, not a target-tool bug

<!-- Optional but very useful. If a check fails on a tool that you believe is correctly implementing the principle,
explain why. Cite the relevant section of bundle/SKILL.md or bundle/references/principles-deep-dive.md. -->
62 changes: 62 additions & 0 deletions .github/ISSUE_TEMPLATE/principle_proposal.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
---
name: Principle proposal
about: Propose a new principle, a substantive change to an existing principle, a new check, or a new template.
title: "proposal: <short description>"
labels: proposal
---

## Problem statement

<!-- What is the problem this proposal addresses? Be specific about which agent-native CLI failure modes it would
prevent or which user need it would serve. Cite real tools or real PRs where relevant. -->

## Proposal

<!-- One paragraph: what should the bundle do that it does not do today? Frame as a change to bundle/SKILL.md
or bundle/references/principles-deep-dive.md or both. -->

## Type of change

- [ ] New principle (P8 or later)
- [ ] Tightening an existing principle's MUST/SHOULD/MAY semantics
- [ ] Removing or relaxing an existing principle (major version bump)
- [ ] New automated check under `bundle/scripts/checks/`
- [ ] New template under `bundle/templates/`
- [ ] Other (describe)

## Prior art

<!-- Existing tools, specs, or articles that demonstrate the problem or the proposed solution. Two or three is fine. -->

- -

## Draft of the change

### `bundle/SKILL.md` diff sketch

```diff
<!-- Show approximately what would change in SKILL.md -->
```

### `bundle/references/principles-deep-dive.md` diff sketch

```diff
<!-- For new or substantively-changed principles, sketch the MUST/SHOULD/MAY language. -->
```

### Check / template additions

<!-- For new checks: which group does it belong to? What is its pass criterion? Does it produce PASS / WARN / FAIL?
For new templates: which existing reference docs would point at it? -->

## Backward compatibility

- [ ] Backward-compatible (existing tools that pass today still pass after this change)
- [ ] Tightens — some currently-passing tools would start failing or warning. List representative examples:
- [ ] Breaking — explicit major version bump justified because:

## Open questions

<!-- Anything you're unsure about. Decisions to make in the issue thread before any PR. -->

-
2 changes: 2 additions & 0 deletions .github/pull_request_template.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -90,6 +90,8 @@

**Created:**

**Renamed:**

**Deleted:**

## Key Features
Expand Down
12 changes: 10 additions & 2 deletions .github/workflows/ci.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,8 @@ on:
- dev
- "feat/**"
- "fix/**"
- "chore/**"
- "release/**"
pull_request:
branches:
- main
Expand Down Expand Up @@ -39,11 +41,17 @@ jobs:
steps:
- name: Checkout
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
- name: Run ShellCheck
- name: Run ShellCheck (bundle scripts — ship to consumers)
uses: ludeeus/action-shellcheck@00cae500b08a931fb5698e11e79bfbd38e612a38 # 2.0.0
env:
# style severity surfaces all suggestions; CI fails on error+warning by default
SHELLCHECK_OPTS: "--severity=style"
with:
scandir: ./bundle/scripts
additional_files: bundle/scripts/checks/_helpers.sh
- name: Run ShellCheck (producer scripts)
uses: ludeeus/action-shellcheck@00cae500b08a931fb5698e11e79bfbd38e612a38 # 2.0.0
env:
SHELLCHECK_OPTS: "--severity=style"
with:
scandir: ./scripts
additional_files: scripts/checks/_helpers.sh
80 changes: 44 additions & 36 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,74 +2,82 @@

Project-level agent instructions for `agentnative-skill` — the producer repo for the `agent-native-cli` skill bundle.

This repo is **not** a Rust CLI tool. It is a content + script bundle that ships at the repo root and is consumed via
`git clone` into a host's skills directory (Claude Code, Cursor, Codex, etc.). The bundle defines the standard for
agent-native CLI design and ships an automated compliance checker that consumers run against their own tools.
This repo is **not** a Rust CLI tool. It is a content + script bundle plus producer-side ops scaffolding. The bundle
defines the standard for agent-native CLI design and ships an automated compliance checker that consumers run against
their own tools.

## Layout

| Path | Purpose |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `SKILL.md` | The standard itself: 7 agent-readiness principles, when to trigger, how to use. |
| `checklists/` | Task-shaped checklists for downstream consumers (e.g., `new-tool.md`). |
| `references/` | Deep-dive references: principle specifications, framework idioms, project structure, Rust/clap patterns. |
| `scripts/check-compliance.sh` | Driver script that runs all 24 compliance checks against a target Rust CLI repo. |
| `scripts/checks/` | Individual check scripts (`check-p1-*.sh`, `check-p4-*.sh`, etc.) plus shared `_helpers.sh`. |
| `templates/` | Drop-in starting points for downstream tools (`AGENTS.md`, clap main, error types, output format). |
| `.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`. |
| `docs/plans/` | Engineering plans (`dev`-only — guarded out of `main`). |
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` | ✓ | The standard itself: 7 agent-readiness principles, when to trigger, how to use. |
| `bundle/checklists/` | ✓ | Task-shaped checklists for downstream consumers (e.g., `new-tool.md`). |
| `bundle/references/` | ✓ | Deep-dive references: principle specifications, framework idioms, project structure, Rust/clap patterns. |
| `bundle/scripts/check-compliance.sh` | ✓ | Driver script that runs all 24 compliance checks against a target Rust CLI repo. |
| `bundle/scripts/checks/` | ✓ | Individual check scripts (`check-p1-*.sh`, `check-p4-*.sh`, etc.) plus shared `_helpers.sh`. |
| `bundle/templates/` | ✓ | Drop-in starting points for downstream tools (`agents-md-template.md`, clap main, error types, output format). |
| `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` | — | Local lint configs and repo metadata. |

## Lint & Format

```bash
markdownlint-cli2 '**/*.md' '!node_modules/**'
shellcheck --severity=style scripts/check-compliance.sh scripts/checks/*.sh
shellcheck --severity=style bundle/scripts/check-compliance.sh bundle/scripts/checks/*.sh
actionlint .github/workflows/*.yml
```

The repo ships a local `.markdownlint-cli2.yaml` (canonical 120-char line length) and `.shellcheckrc` (three narrow
disables documented inline) so CI and local tooling agree.

## Branch model
## Branch + release model

`feat/* → dev (squash) → main (squash)`. `dev` and `main` are both forever; release branches are not used.
`feat/* → dev (squash) → release/<slug> from origin/main → main (squash)`. Cherry-pick the non-docs commits from `dev`
onto the `release/*` branch. `dev` and `main` are both forever branches; `release/*` branches are short-lived and
auto-deleted on merge.

Engineering docs (`docs/plans/`, `docs/solutions/`, `docs/brainstorms/`, `docs/reviews/`) live on `dev` only.
`guard-main-docs.yml` blocks them from reaching `main`.
`guard-main-docs.yml` blocks any `added` or `modified` files under those paths from reaching `main`. The release-branch
cherry-pick pattern handles this naturally: docs commits stay on `dev`, only feature commits go onto `release/*`.

See [`RELEASES.md`](./RELEASES.md) for the full workflow and version-bump procedure.

## Releases

Tags `v*` on `main`. Tag protection (deletion + force-push + update blocked) is in `.github/rulesets/protect-tags.json`;
applied post-public-flip. The site at [`anc.dev/install`](https://anc.dev/install) pins to the commit SHA of the latest
tag.
See [`RELEASES.md`](./RELEASES.md) for the full workflow, version-bump procedure, and the verified status-check context
table.

## What an agent should NEVER do

- Edit shell scripts in `scripts/checks/` casually. They run on user machines at install time. CODEOWNERS gates
`scripts/**` and `.github/workflows/**` for that reason.
- Commit anything in `docs/plans/` or similar engineering docs to a branch heading toward `main`. Use `dev`.
- Modify `SKILL.md`'s `name` or `description` frontmatter without coordinating with consumers — those fields drive skill
discovery on every host.
- Edit shell scripts in `bundle/scripts/checks/` casually. They run on user machines at install time. CODEOWNERS gates
`bundle/scripts/**` and `.github/workflows/**` for that reason.
- 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.
- 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 shell + markdown.
- Move producer-ops files into `bundle/`. The split exists deliberately so consumers don't pull repo-management
artifacts into their skills directories.

## Common pitfalls

- The bundle's `templates/agents-md-template.md` is for downstream Rust CLI tools (`cargo build`, `cargo test`, etc.).
This `AGENTS.md` describes the producer repo and is intentionally different.
- 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.
- `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`.
- The `_helpers.sh` file in `scripts/checks/` is sourced (`source _helpers.sh`), not executed. It is intentionally not
marked +x.
- The `_helpers.sh` file in `bundle/scripts/checks/` is sourced (`source _helpers.sh`), not executed. It is
intentionally not marked +x.

## References

- [`SKILL.md`](./SKILL.md) — the standard
- [`README.md`](./README.md) — what this repo is, install pointer
- [`bundle/SKILL.md`](./bundle/SKILL.md) — the standard
- [`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
78 changes: 78 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,78 @@
# Contributing to `agentnative-skill`

Thanks for your interest. This repo defines a north-star standard for agent-native CLI tools and ships an automated
compliance checker. Substantive proposals should engage with the principles directly.

## Where to start

| You want to… | Read first |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Understand the standard | [`bundle/SKILL.md`](./bundle/SKILL.md) and [`bundle/references/principles-deep-dive.md`](./bundle/references/principles-deep-dive.md) |
| File a bug in the compliance checker or a check | Open an issue with the **Bug report** template |
| Propose a new principle, check, or template | Open an issue with the **Principle proposal** template |
| Add or fix something concrete | Read [`RELEASES.md`](./RELEASES.md) for the branch model, then open a PR |
| Operate as an agent in this repo | [`AGENTS.md`](./AGENTS.md) (lint commands, hard rules, common pitfalls) |

## Branch model (TL;DR)

```text
feat/* → PR to dev (squash merge)
→ cherry-pick non-docs commits to release/<version>
→ PR release/* to main (squash merge)
→ tag v<X.Y.Z> + GitHub Release
```

`dev` is the integration branch. `main` is what consumers install. Engineering docs (`docs/plans/`, `docs/solutions/`,
`docs/brainstorms/`, `docs/reviews/`) live on `dev` only and are blocked from `main` by `guard-main-docs.yml`. Full
procedure in [`RELEASES.md`](./RELEASES.md).

## Pull requests

- **Title format**: [Conventional Commits](https://www.conventionalcommits.org/) — `type(scope): description`.
- **Body**: follow [`.github/pull_request_template.md`](.github/pull_request_template.md). The `## Changelog` section is
the source of truth for `CHANGELOG.md` entries — write for users, not implementers.
- **Scope**: keep PRs small and single-purpose where possible. A bundle change, a check tightening, and a docs refactor
should be three PRs, not one.
- **Tests**: there is no test runner in this repo, but every PR must pass `markdownlint`, `shellcheck`, and (when
targeting `main`) `guard-docs / check-forbidden-docs`. Run locally before pushing:

```bash
markdownlint-cli2 '**/*.md' '!node_modules/**'
shellcheck --severity=style bundle/scripts/check-compliance.sh bundle/scripts/checks/*.sh
actionlint .github/workflows/*.yml
```

## Bundle vs producer-ops boundary

The repository is split into:

- **`bundle/`** — what consumers install via `anc.dev/install`. SKILL.md, checklists, references, scripts, templates.
- **Everything else** — producer-side ops: governance (`AGENTS.md`, `RELEASES.md`, `CONTRIBUTING.md`, `SECURITY.md`), CI
(`.github/workflows/`), rulesets (`.github/rulesets/`), engineering plans (`docs/plans/`).

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.

## Substantive changes to the standard

The 7 principles are stable. Proposing a new principle, removing one, or materially changing existing semantics
requires:

1. An issue using the **Principle proposal** template, including the problem statement, prior art, and a draft of how
`bundle/SKILL.md` and `bundle/references/principles-deep-dive.md` would change.
2. Discussion in the issue. Maintainer signoff before any PR.
3. A PR that updates SKILL.md, the deep-dive, the relevant `bundle/scripts/checks/check-p*-*.sh` scripts, the templates,
and the `CHANGELOG.md` together. Partial coverage isn't merged.

Tightening a check's pass criteria is a `Changed` (minor or major depending on how many existing tools regress). Adding
a new check is `Added`. Removing a check is `Removed` (major). See SemVer guidance in `RELEASES.md`.

## Security

See [`SECURITY.md`](./SECURITY.md). Do not file security issues in the public tracker — use the GitHub private security
advisories channel.

## License

By contributing, you agree your contributions are licensed under the MIT license that covers this repository (see
[`LICENSE`](./LICENSE)).
Loading