Skip to content

refactor!: flatten bundle/* to repo root for plain git-clone install #9

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 29, 2026
Merged

refactor!: flatten bundle/* to repo root for plain git-clone install #9

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
e5a3772
refactor!: flatten bundle/* to repo root for plain git-clone install
brettdavies Apr 29, 2026
d49c948
fix(docs): align table pipes after bundle/ path strip (markdownlint M…
brettdavies Apr 29, 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
4 changes: 2 additions & 2 deletions .github/ISSUE_TEMPLATE/bug_report.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
14 changes: 7 additions & 7 deletions .github/ISSUE_TEMPLATE/bundle_proposal.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,15 +27,15 @@ Route check before filing:
## Proposal

<!-- One paragraph: what should the bundle do that it does not do today? Frame as a concrete change to one or more
of: bundle/SKILL.md, bundle/getting-started.md, bundle/references/<file>, bundle/templates/<file>. -->
of: SKILL.md, getting-started.md, references/<file>, templates/<file>. -->

## 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
Expand All @@ -50,7 +50,7 @@ Route check before filing:
ideal; an outline is acceptable for early-stage proposals. -->

```diff
<!-- bundle/<file> -->
<!-- <file> -->
```

## Compatibility
Expand Down
2 changes: 1 addition & 1 deletion .markdownlint-cli2.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
91 changes: 47 additions & 44 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,57 +1,60 @@
# 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

The canonical principle text lives in [`brettdavies/agentnative`](https://github.com/brettdavies/agentnative). This repo
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

Expand All @@ -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
</content>

</invoke>
Loading