release: v0.2.0 — agent-native CLI skill bundle public launch by brettdavies · Pull Request #12 · brettdavies/agentnative-skill

brettdavies · 2026-04-29T21:56:23Z

Summary

First public release of the agent-native-cli skill bundle (agentnative-skill repo). Establishes the canonical
brettdavies cherry-pick release pattern (feature → dev → release/* → main), ships the flat install layout consumers
will pull via plain git clone, and lands the consumer-side update-check mechanism that replaces the deprecated
install.json SHA-pin advisory.

Cherry-picks 10 dev PRs (#1–#4, #6–#11, #13) onto origin/main plus three direct-to-release-branch fixup commits
(9f6e276, 23e1a76 from the bootstrap window) and the curated chore(release): v0.2.0 commit. PR #5 (docs-only
public-flip follow-up) stayed on dev per the cherry-pick rule. The original in-cherry-pick spec re-vendor
(837ab9a → 1640460) was converted to a real PR (#10) so the v0.2.0 CHANGELOG carries a curated bullet for the
spec v0.2.0 → v0.3.0 bump.

PR-body template alignment was audited by parallel subagents before this regeneration — empty stubs removed, missing
template sections added, internal-detail bullets moved out of ## Changelog, PR #11's nested sub-bullets flattened.

Changelog

Added

Version-controlled GitHub repository rulesets for main, dev, and release tags (v*). Apply procedure documented in .github/rulesets/README.md. by @brettdavies in chore(repo): add version-controlled rulesets for main, dev, and release tags #1
AGENTS.md (root) describing the bundle layout, lint commands, branch model, and hard rules for agents. by @brettdavies in chore(repo): add AGENTS.md, PR template, RELEASES.md, guard-main-docs (lightweight release scaffold) #2
RELEASES.md (root) documenting a release procedure for this repo (later rewritten in chore(repo): restructure bundle into bundle/, add changelog generator, expand governance #3 to the canonical full release/* pattern).
.github/pull_request_template.md (canonical PR template).
.github/workflows/guard-main-docs.yml caller for the brettdavies/.github reusable workflow that blocks docs/plans/, docs/solutions/, docs/brainstorms/, docs/reviews/ from PRs targeting main.
cliff.toml — git-cliff configuration mirroring sibling repos. by @brettdavies in chore(repo): restructure bundle into bundle/, add changelog generator, expand governance #3
scripts/generate-changelog.sh — release-time CHANGELOG generator. Reads PR-body ## Changelog sections and prepends a curated, attributed [X.Y.Z] section. Authoritative; never hand-edit CHANGELOG.md.
CONTRIBUTING.md — how to propose changes, link to release procedure.
.github/ISSUE_TEMPLATE/bug_report.md + bundle_proposal.md (replaces principle_proposal.md with corrected routing).
Vendored spec/ tree from agentnative-spec — VERSION, CHANGELOG.md, README.md, and seven principles/p*.md files with machine-readable requirements[] frontmatter. The skill points at this canonical text instead of paraphrasing. by @brettdavies in feat(bundle)!: pivot skill to anc; vendor agentnative-spec; delete duplicate shell checker #4
getting-started.md covering three working agent loops (existing CLI / new Rust / other language), canonical anc check --output json invocations, and a "where things live" map.
scripts/sync-spec.sh for re-vendoring agentnative-spec on demand.
LICENSE-APACHE — dual-license under MIT or Apache-2.0 (consumer's choice). by @brettdavies in chore(license): dual-license under MIT or Apache-2.0 #6
bin/check-update — gstack-style consumer-side update-check. Compares the installed VERSION against the producer repo's main, emits UPGRADE_AVAILABLE <local> <remote>, with cache TTL (60 min UP_TO_DATE / 720 min UPGRADE_AVAILABLE) and 3-level snooze (24h / 48h / 7d). State directory: $HOME/.cache/agent-native-cli/. by @brettdavies in feat(bundle): consumer-side update-check mechanism (U1+U2) #8
SKILL.md ## Update check section documenting the script's invocation and the AskUserQuestion-driven upgrade flow.

Changed

BREAKING (install layout): Skill content lives at the repo root (SKILL.md, bin/, spec/, references/, templates/, VERSION). Plain git clone --depth 1 and git pull --ff-only are the load-bearing install + update commands; no sparse-checkout magic, no post-install scripts. by @brettdavies in refactor!: flatten bundle/* to repo root for plain git-clone install #9 (final flat shape; intermediate bundle/ indirection from chore(repo): restructure bundle into bundle/, add changelog generator, expand governance #3 reverted before launch).
License changed from MIT-only to dual MIT or Apache-2.0 (no MIT compatibility regression). by @brettdavies in chore(license): dual-license under MIT or Apache-2.0 #6
Documentation now points at https://anc.dev/skill instead of https://anc.dev/install. by @brettdavies in chore(docs): rename install endpoint to /skill #7
Spec content vendored under spec/ re-vendored from agentnative-spec v0.2.0 to v0.3.0. All 7 principles flip status: draft → status: active; prose tightened across P1–P7 from upstream's G11 red-team pass. No requirement IDs added/removed/renamed; no level changes. by @brettdavies in chore(spec): re-vendor spec/ to v0.3.0 + RELEASES spec-revendor section #10
scripts/sync-spec.sh no longer accepts SPEC_REF. The script always vendors the latest v* tag, queried from SPEC_REMOTE_URL (default https://github.com/brettdavies/agentnative.git) via git ls-remote --tags --sort=-version:refname and shallow-cloned for extraction. On any remote failure, falls back to the existing SPEC_ROOT-based logic (default $HOME/dev/agentnative-spec). New env var SPEC_REMOTE_URL overrides the remote; the temp clone is auto-cleaned on script exit via trap. by @brettdavies in chore(sync-spec): drop SHA-pin claims, modernize to remote-first vendoring #11

Fixed

Harden bin/check-update against malformed local VERSION (apply SemVer regex; malformed → silent exit) and against curl failure being cached as UP_TO_DATE (skip cache write on network failure so the next invocation retries). by @brettdavies in feat(bundle): consumer-side update-check mechanism (U1+U2) #8
Align table pipes in SKILL.md and getting-started.md (markdownlint MD060). by @brettdavies in refactor!: flatten bundle/* to repo root for plain git-clone install #9

Documentation

README.md — License section rewritten to reflect dual licensing and link both LICENSE files; tree row updated. by @brettdavies in chore(license): dual-license under MIT or Apache-2.0 #6
CONTRIBUTING.md — License section rewritten: contributions are dual-licensed at the consumer's option, no CLA, with an explicit pointer to the Apache §3 patent grant.
- .markdownlint-cli2.yaml excludes CHANGELOG.md from linting (matches the existing exclusion for spec/CHANGELOG.md). Aligns lint behavior with the scripts/generate-changelog.sh regen flow. by @brettdavies in chore(lint): exclude CHANGELOG.md from markdownlint #13
All public-facing markdown (RELEASES.md, AGENTS.md, README.md, spec/README.md, CONTRIBUTING.md) scrubbed of SHA-pin model vocabulary: pipeline diagram's "site re-pins to commit SHA" step, the post-merge "site re-pins via its own PR" step, the protect-tags.json / install endpoints claims that tags are pinned to install endpoints, and the spec-vendor "pinned ref" / "pinned SPEC_REF" / "current pin is recorded" vocabulary across all docs. The new model is plain git clone + bin/check-update for staleness; nothing pins to anything cross-repo. by @brettdavies in chore(sync-spec): drop SHA-pin claims, modernize to remote-first vendoring #11

Removed

bundle/scripts/check-compliance.sh and 24 bundle/scripts/checks/check-*.sh files (plus _helpers.sh). anc check --output json is the canonical replacement. by @brettdavies in feat(bundle)!: pivot skill to anc; vendor agentnative-spec; delete duplicate shell checker #4
bundle/references/principles-deep-dive.md (419-line hand-typed paraphrase of the spec; canonical text now lives at spec/principles/).
.github/ISSUE_TEMPLATE/principle_proposal.md (replaced by bundle_proposal.md with corrected routing).
.shellcheckrc (its three disables targeted the deleted bundle scripts; producer scripts pass shellcheck unmodified).

Type of Change

chore: Maintenance tasks (release engineering)
BREAKING CHANGE: Install layout changes (no v0.1.0 consumers exist; see Breaking Changes section)

Related Issues/Stories

Architecture: docs/plans/2026-04-27-001-bootstrap-agentnative-skill-plan.md — bootstrap plan (task #15: launch-eve cherry-pick + admin-bypass decision recorded 2026-04-28).
Architecture: docs/plans/2026-04-28-001-feat-update-check-mechanism-plan.md — update-check mechanism plan (drove PR feat(bundle): consumer-side update-check mechanism (U1+U2) #8 + the SHA-pin removal across PR chore(sync-spec): drop SHA-pin claims, modernize to remote-first vendoring #11 / repo docs).
Cross-repo: agentnative-cli — scripts/sync-spec.sh is the documented mirror; lockstep modernization is being driven in a parallel session.
Cross-repo: agentnative-site — installs this skill via https://anc.dev/skill; the install.json SHA-pin advisory is being removed in that repo (separate PR there) per the update-check plan's downstream coordination.

Testing

Manual testing completed
All tests passing (CI: markdownlint + shellcheck on every cherry-picked commit)

Test Summary:

markdownlint-cli2 clean across the cherry-pick chain (PostToolUse hook ran on every edit; CI re-verified each PR).
shellcheck --severity=style scripts/sync-spec.sh bin/check-update: clean.
bash -n scripts/sync-spec.sh bin/check-update: clean.
bin/check-update 40-test battery (PR feat(bundle): consumer-side update-check mechanism (U1+U2) #8): 40 pass / 0 fail (unit + integration + e2e + red-team).
scripts/sync-spec.sh remote-success path verified live: queried https://github.com/brettdavies/agentnative.git, resolved v0.3.0, shallow-cloned, vendored 7 principles + VERSION + CHANGELOG. Remote-fail-local-success path verified by setting bogus SPEC_REMOTE_URL (warning + fallback to $HOME/dev/agentnative-spec). Both-fail path verified with bogus URL + bogus SPEC_ROOT (hard error with both printed).
Vocabulary check: rg for SHA-pin / commit SHA / source.commit / install.json / re-pin / SPEC_REF / pin / pinned / pinning across shipping content (excluding docs/plans/, license boilerplate, changelogs, vendored spec/principles/): zero matches.
PR-body template alignment: parallel audit subagents reported verified=true for PRs chore(repo): add version-controlled rulesets for main, dev, and release tags #1–chore(sync-spec): drop SHA-pin claims, modernize to remote-first vendoring #11.

Files Modified

Cherry-picked from dev (squash commits):

8be19e6 — feat(bundle): consumer-side update-check mechanism (U1+U2) [feat(bundle): consumer-side update-check mechanism (U1+U2) #8]
34b1da3 — refactor!: flatten bundle/* to repo root for plain git-clone install [refactor!: flatten bundle/* to repo root for plain git-clone install #9]
4461806 — chore(spec): re-vendor spec/ to v0.3.0 + RELEASES spec-revendor section [chore(spec): re-vendor spec/ to v0.3.0 + RELEASES spec-revendor section #10]
fb50d18 — chore(sync-spec): drop SHA-pin claims, modernize to remote-first vendoring [chore(sync-spec): drop SHA-pin claims, modernize to remote-first vendoring #11]
e67523e — chore(lint): exclude CHANGELOG.md from markdownlint [chore(lint): exclude CHANGELOG.md from markdownlint #13] (added during release prep to unblock MD013 on the rich generated CHANGELOG)

Direct-to-release-branch fixup commits (bootstrap window):

9f6e276 — chore(rulesets): drop .github/rulesets/README.md
23e1a76 — docs(bundle): trim trailing platform comment on cargo install line

Curated release commit:

d66d5bd — chore(release): v0.2.0 (VERSION bump + regenerated CHANGELOG.md)

Plus PRs #1–#7 cherry-picked earlier in the bootstrap window: rulesets (#1), AGENTS/PR-template/RELEASES scaffold (#2), bundle restructure + cliff.toml (#3), spec vendoring + skill pivot (#4), dual licensing (#6), /skill endpoint rename (#7).

Breaking Changes

Breaking changes described below

Install layout (PR #4 + PR #9): the skill bundle's directory shape went from a paraphrased pre-anc layout (v0.1.0) → bundle/ subdirectory (PR #3) → flat root (PR #9). The flat root is the load-bearing final shape: git clone --depth 1 lands SKILL.md at the install root where Claude Code, Codex, Cursor, and OpenCode auto-discover it.

No real-world migration impact: v0.1.0 has zero installed consumers (the install endpoint at https://anc.dev/skill is gated by this very release). The breaking-change classification is for SemVer hygiene, not user-impacting.

Bundle surface contract (PR #4): the skill no longer ships shell-script compliance checks (bundle/scripts/check-compliance.sh + 24 check-*.sh files). anc check --output json is the canonical replacement; downstream tools that scraped the old shell scripts must migrate to anc.

Deployment Notes

Deployment steps documented below

Pre-merge admin-bypass (one-time): the protect-main ruleset requires markdownlint, shellcheck, and guard-docs / check-forbidden-docs as required status checks. The third comes from guard-main-docs.yml, which only exists on dev (it's part of this very release). For the FIRST release PR, GitHub evaluates pull_request workflows from main (the base), so the guard-docs check cannot run. Resolution: admin-bypass this single PR via the existing bypass_actors on protect-main (actor_type: RepositoryRole, actor_id: 5, bypass_mode: always). One-off; subsequent releases run cleanly. See bootstrap plan §15 (decision recorded 2026-04-28).

Post-merge sequence (per RELEASES.md):

Tag the squash commit on main:

git checkout main && git pull
git tag -a v0.2.0 -m "v0.2.0"
git push origin v0.2.0

Create the GitHub Release with the v0.2.0 CHANGELOG section as notes:

gh release create v0.2.0 --title "v0.2.0" \
  --notes "$(awk '/^## \[0\.2\.0\]/{flag=1; next} /^## \[/{flag=0} flag' CHANGELOG.md)"

Consumers detect the new release on their next bin/check-update run; no site-side coordination step (the SHA-pin model is gone, per chore(sync-spec): drop SHA-pin claims, modernize to remote-first vendoring #11).

Checklist

Code follows project conventions and style guidelines
Commit messages follow Conventional Commits
Self-review of code completed
Tests added/updated and passing (CI green on every cherry-picked commit)
No new warnings or errors introduced
Changes are backward compatible (or breaking changes documented in Breaking Changes section)

Additional Context

Full v0.2.0 entry in CHANGELOG.md (this section is a copy; CHANGELOG.md is canonical).
The PR-body audit run produced template-aligned bodies for all 11 merged PRs; CHANGELOG.md was regenerated from the audited bodies before this PR opened.

…se tags (#1) ## Summary Add three JSON files under `.github/rulesets/` capturing the GitHub repository rulesets that protect this repo's branches and release tags, plus a README documenting the apply procedure. Wire `protect-main.json` to require the `guard-docs / check-forbidden-docs` status check produced by the workflow added in #2. These cannot be applied while the repo is private on a free-tier account; the master plan flips visibility from the agentnative-site session, after which `.github/rulesets/README.md` documents the exact `gh api` invocations. ## Changelog ### Added - Version-controlled GitHub repository rulesets for `main`, `dev`, and release tags (`v*`). Apply procedure documented in `.github/rulesets/README.md`. ## Type of Change - [x] `chore`: Maintenance tasks (dependencies, config, etc.) ## Related Issues/Stories - Story: master plan Unit 1, Step 8 — `~/dev/agentnative-site/docs/plans/2026-04-24-001-feat-skill-distribution-endpoint-plan.md` - Related PRs: #2 (ships the `guard-main-docs.yml` workflow whose check is required by `protect-main.json`) ## Testing - [x] Manual testing completed - [x] All tests passing **Test Summary:** - Status-check contexts (`markdownlint`, `shellcheck`, `guard-docs / check-forbidden-docs`) confirmed against the reusable workflow source at `brettdavies/.github/.github/workflows/guard-main-docs.yml@main` and against `gh api repos/brettdavies/agentnative-skill/commits/<sha>/check-runs --jq '.check_runs[].name'`. - JSON validated against canonical templates in `~/.claude/skills/github-repo-setup/references/`. - Repo CI: markdownlint pass, shellcheck pass. ## Files Modified **Created:** - `.github/rulesets/protect-main.json` - `.github/rulesets/protect-dev.json` - `.github/rulesets/protect-tags.json` - `.github/rulesets/README.md` ## Breaking Changes - [x] No breaking changes ## Deployment Notes - [x] Deployment steps documented below: After this PR and #2 land, the agentnative-site session runs `gh repo edit brettdavies/agentnative-skill --visibility public`. Then apply the rulesets: ```bash gh api repos/brettdavies/agentnative-skill/rulesets -X POST --input .github/rulesets/protect-main.json gh api repos/brettdavies/agentnative-skill/rulesets -X POST --input .github/rulesets/protect-dev.json gh api repos/brettdavies/agentnative-skill/rulesets -X POST --input .github/rulesets/protect-tags.json ``` Run the negative tests in `.github/rulesets/README.md` to confirm enforcement. ## 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 (or breaking changes documented)

… (lightweight release scaffold) (#2) ## Summary Establish the lightweight release pattern for this repo (`feat/* → dev → main` with one squash-merge per release — no `release/*` cherry-pick branches) and ship the ops scaffolding the pattern depends on. Pairs with #1 (rulesets); either PR can land first. ## Changelog ### Added - `AGENTS.md` (root) describing the bundle layout, lint commands, branch model, and hard rules for agents working in this producer repo. - `RELEASES.md` (root) documenting the lightweight `dev → main` release procedure, version-bump checklist, and the three required status checks for the protected `main` branch. - `.github/pull_request_template.md` (canonical PR template). - `.github/workflows/guard-main-docs.yml` caller for the `brettdavies/.github` reusable workflow that blocks `docs/plans/`, `docs/solutions/`, `docs/brainstorms/`, `docs/reviews/` from PRs targeting `main`. ### Changed - `.gitignore` adds `!AGENTS.md` to override the global `**/AGENTS.md` ignore for this repo only. Other repos remain unaffected. ## Type of Change - [x] `chore`: Maintenance tasks (dependencies, config, etc.) ## Related Issues/Stories - Story: master plan Unit 1 — `~/dev/agentnative-site/docs/plans/2026-04-24-001-feat-skill-distribution-endpoint-plan.md` - Related PRs: #1 (version-controlled rulesets; `protect-main.json` requires the `guard-docs / check-forbidden-docs` context produced by this PR's workflow) ## Testing - [x] Manual testing completed - [x] All tests passing **Test Summary:** - `markdownlint-cli2 '**/*.md'` — 0 errors across 15 markdown files. - `actionlint .github/workflows/*.yml` — exit 0. - Reusable workflow at `brettdavies/.github/.github/workflows/guard-main-docs.yml@main` confirmed to exist and accept `workflow_call` with no required inputs. - `git status` after `.gitignore` negation confirms `AGENTS.md` is no longer ignored. ## Files Modified **Modified:** - `.gitignore` **Created:** - `AGENTS.md` - `RELEASES.md` - `.github/pull_request_template.md` - `.github/workflows/guard-main-docs.yml` ## Breaking Changes - [x] No breaking changes ## Deployment Notes - [x] No special deployment steps required The `guard-main-docs` workflow runs on PRs to `main` from the moment this PR lands. The ruleset that requires its status check (added in #1) only takes effect post-public-flip via Task #11. ## 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 (or breaking changes documented)

…, expand governance (#3) ## Summary Producer-side scaffolding for the v0.2.0 release. Three concurrent threads: 1. **Bundle layout split** — move skill content into `bundle/` so producer-ops files (`AGENTS.md`, `RELEASES.md`, `.github/`, `cliff.toml`, etc.) stop shipping into consumers' skill directories. Breaking change to the install layout: `anc.dev/install` must fetch `bundle/` (not the whole repo) starting at v0.2.0. 2. **Changelog generation** — add `cliff.toml` and `scripts/generate-changelog.sh` mirroring the canonical agentnative-cli pattern. CHANGELOG.md is generated from PR-body `## Changelog` sections; never hand-edited. `RELEASES.md` updated to enforce the rule. 3. **Release model + governance** — adopt full `release/*` cherry-pick pattern (was lightweight `dev → main`); plans stay on dev forever and `release/*` branches cherry-pick non-docs commits so `guard-main-docs` passes mechanically. Add `CONTRIBUTING.md` and two issue templates. Sync the canonical PR template to add a `**Renamed:**` subsection under `## Files Modified`. ## Changelog ### Changed - **Breaking (install layout):** Skill bundle moved into `bundle/` subdirectory. Installers must fetch `bundle/` rather than the entire repo. Consumer's installed skill directory shape is unchanged (`SKILL.md` at the root). - Adopted the full `release/*` cherry-pick release pattern (was lightweight `dev → main`). Plans on `dev` no longer conflict with release PRs because release branches cherry-pick only non-docs commits. - `RELEASES.md` rewritten to the canonical pattern; broken `../../.claude/...` link removed. ### Added - `cliff.toml` — git-cliff configuration mirroring sibling repos. - `scripts/generate-changelog.sh` — release-time CHANGELOG generator. Reads PR-body `## Changelog` sections and prepends a curated, attributed `[X.Y.Z]` section. Authoritative; never hand-edit `CHANGELOG.md`. - `CONTRIBUTING.md` — how to propose changes, link to release procedure. - `.github/ISSUE_TEMPLATE/bug_report.md` — bug report template. - `.github/ISSUE_TEMPLATE/principle_proposal.md` — substantive standards-change template. - `**Renamed:**` subsection in `.github/pull_request_template.md` (sync of the canonical update at `~/dotfiles/stow/github/dot-config/github/pull_request_template.md`). Sister sync PRs landing in agentnative-cli (#30 there) and agentnative-site (already on dev as commit 4437435). ## Type of Change - [x] `chore`: Maintenance tasks (dependencies, config, etc.) ## Related Issues/Stories - Story: master plan Unit 1 — `~/dev/agentnative-site/docs/plans/2026-04-24-001-feat-skill-distribution-endpoint-plan.md` - Issue: n/a - Architecture: pre-release audit identified the bundle-debris problem and the lightweight-pattern conflict with plans-on-dev. Resolved here by restructuring + adopting cherry-pick. - Related PRs: #1, #2 (already merged); agentnative-cli #30 and agentnative-site dev (sister PR-template sync) ## Testing - [ ] Unit tests added/updated - [ ] Integration tests added/updated - [x] Manual testing completed - [x] All tests passing **Test Summary:** - `markdownlint-cli2 '**/*.md'` — 0 errors across 19 markdown files. - `shellcheck --severity=style bundle/scripts/check-compliance.sh bundle/scripts/checks/*.sh` — exit 0. - `shellcheck --severity=style scripts/*.sh` — exit 0 (generate-changelog.sh). - `actionlint .github/workflows/*.yml` — exit 0. - `scripts/generate-changelog.sh --check` — exit 0 (CHANGELOG.md has versioned section). - Compliance checker still works against `~/dev/agentnative-cli/`: 17/24 PASS, 7 FAIL, exit 2 — same as pre-restructure. - All bundle cross-references (`bundle/SKILL.md` → `bundle/templates/...`, etc.) use relative paths within `bundle/`, unchanged by the move. ## Files Modified **Modified:** - `.github/CODEOWNERS` - `.github/pull_request_template.md` - `.github/workflows/ci.yml` - `AGENTS.md` - `README.md` - `RELEASES.md` **Created:** - `bundle/` (new directory containing all skill content — see Renamed below for the moves into it) - `cliff.toml` - `scripts/generate-changelog.sh` - `CONTRIBUTING.md` - `.github/ISSUE_TEMPLATE/bug_report.md` - `.github/ISSUE_TEMPLATE/principle_proposal.md` **Renamed:** - `SKILL.md` → `bundle/SKILL.md` - `checklists/new-tool.md` → `bundle/checklists/new-tool.md` - `references/*` → `bundle/references/*` (5 files) - `scripts/check-compliance.sh` → `bundle/scripts/check-compliance.sh` - `scripts/checks/*` → `bundle/scripts/checks/*` (24 files) - `templates/*` → `bundle/templates/*` (4 files) **Deleted:** ## Breaking Changes - [ ] No breaking changes - [x] Breaking changes described below: The skill-install layout changes. `anc.dev/install` must fetch `bundle/` only — not the whole repo. The consumer's installed skill directory shape (`~/.claude/skills/agent-native-cli/SKILL.md` etc.) is unchanged; only the producer- side fetch logic differs. Coordinate with the agentnative-site session before tagging v0.2.0. ## Deployment Notes - [ ] No special deployment steps required - [x] Deployment steps documented below: This PR lands on `dev` only. The actual v0.2.0 release follows the new `release/*` flow: 1. Cut `release/v0.2.0` from `origin/main`. 2. Cherry-pick non-docs commits from `dev` (this PR's squash commit + #1 + #2 from the prior round; the `docs(plan): ...` commit stays on dev). 3. Bump `VERSION` to `0.2.0`. Run `scripts/generate-changelog.sh` to populate the `[0.2.0]` section. 4. Open `release/v0.2.0 → main` PR; verify `guard-docs / check-forbidden-docs` passes. 5. After merge: tag `v0.2.0`, run `gh release create` for both `v0.1.0` (retroactive) and `v0.2.0`. 6. Updated handoff to agentnative-site session: new SHA + `bundle/` fetch instruction. ## Checklist - [x] Code follows project conventions and style guidelines - [x] Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/) - [x] Self-review of code completed - [ ] Tests added/updated and passing - [x] No new warnings or errors introduced - [x] Changes are backward compatible (or breaking changes documented)

…plicate shell checker (#4) ## Summary The bundle stops reimplementing what `anc` already does and pivots to a guide that teaches agents how to use `anc`, navigate the spec, and apply remediation patterns. Three architectural changes in one commit because they only make sense together: 1. **Vendor `agentnative-spec` as the canonical principle source.** `scripts/sync-spec.sh` mirrors agentnative-cli's vendoring script, retargeted to `bundle/spec/`. Pinned at `v0.2.0` (matches the agentnative-cli pin). The vendored tree carries machine-readable `requirements[]` frontmatter — the contract `anc` reads. 2. **Delete content that duplicates anc.** `bundle/scripts/check-compliance.sh` + 24 `check-*.sh` files were a hand-rolled shell-script reimplementation of a Rust-source-only subset of `anc`'s check matrix. `anc` supersedes them (behavioral + project + source layers, JSON scorecard, `requirement_id` citations, audit profiles). `bundle/references/principles-deep-dive.md` was a 419-line hand-typed paraphrase of the spec — replaced by the vendored `bundle/spec/principles/`. `bundle/checklists/new-tool.md` was a pre-anc 4-phase manual checklist whose Phase 4 invoked the now-deleted shell scripts — replaced by `bundle/getting-started.md`. 3. **Pivot SKILL.md and add getting-started.md.** SKILL.md drops inline principle prose, points at `bundle/spec/principles/` for canonical text, links `getting-started.md` for progressive disclosure, frames the three ecosystem artifacts (spec / `anc` / this skill). `getting-started.md` covers the agent's three loops (existing CLI / new Rust / other language), canonical `anc` invocations, and a "where things live" map. ## Changelog ### Changed - **Breaking (install layout):** Skill bundle stops shipping `bundle/scripts/` and `bundle/checklists/`. Installers and consumers should fetch only the surviving directories: `SKILL.md`, `getting-started.md`, `spec/`, `references/`, `templates/`. The consumer's installed skill-directory shape (`SKILL.md` at the root) is unchanged. - `bundle/SKILL.md` rewritten: drops inline principle prose, links `bundle/getting-started.md` and `bundle/spec/principles/` for progressive disclosure, frames the spec / `anc` / skill three-artifact ecosystem. - `RELEASES.md` SemVer guidance reframed around the bundle's actual surface (markdown + templates + vendored spec) rather than deleted shell-script exit codes; spec-bump-vs-skill-version distinction documented. - `.github/CODEOWNERS` no longer gates `bundle/scripts/**` (path deleted); only producer-ops paths require review. - `.github/workflows/ci.yml` shellcheck job now scans only `./scripts/` (the bundle has no shell scripts to lint). - `.github/ISSUE_TEMPLATE/bug_report.md` rewritten with a routing prelude that sends `anc` bugs to agentnative-cli and spec-change requests to agentnative. ### Added - `scripts/sync-spec.sh` — vendor agentnative-spec into `bundle/spec/` at a pinned `SPEC_REF`. Mirror of the agentnative-cli script. - `bundle/spec/` — vendored agentnative-spec @ v0.2.0: `VERSION`, `CHANGELOG.md`, `README.md` (resync procedure + attribution), and seven `principles/p*.md` files with `requirements[]` frontmatter. - `bundle/getting-started.md` — three working loops (existing CLI / new Rust / other language); canonical `anc check --output json` invocations; "where things live" map covering spec / references / templates / issue routing. - `.github/ISSUE_TEMPLATE/bundle_proposal.md` — replaces `principle_proposal.md`; explicitly redirects principle-level changes to the spec repo and accepts only bundle-shape proposals. ### Removed - `bundle/scripts/check-compliance.sh` and 24 `bundle/scripts/checks/check-*.sh` files (plus `_helpers.sh`). `anc check --output json` is the canonical replacement. - `bundle/references/principles-deep-dive.md` (419-line hand-typed paraphrase of the spec; canonical text now lives at `bundle/spec/principles/`). - `bundle/checklists/new-tool.md` (pre-anc manual checklist; replaced by `bundle/getting-started.md`). - `.github/ISSUE_TEMPLATE/principle_proposal.md` (replaced by `bundle_proposal.md` with corrected routing). - `.shellcheckrc` (its three disables targeted the deleted bundle scripts; producer scripts pass shellcheck unmodified). ## Type of Change - [x] `feat`: New feature (non-breaking change which adds functionality) - [x] `BREAKING CHANGE`: Breaking API change (requires major version bump) (Marked both: pivots are additive at the agent-experience level — the skill now teaches `anc` — but the install layout is a breaking change for any consumer who was fetching `bundle/scripts/` or `bundle/checklists/`.) ## Related Issues/Stories - Story: master plan Unit 1 — `~/dev/agentnative-site/docs/plans/2026-04-24-001-feat-skill-distribution-endpoint-plan.md` - Issue: pre-release adversarial audit identified two architecture mistakes — (a) the bundle was reimplementing what `anc` already does, (b) the bundle had a hand-typed duplicate of `agentnative-spec`'s principle text. Both resolved here. - Architecture: aligns this skill with the canonical brettdavies pattern — `agentnative-cli` vendors the spec via the same `sync-spec.sh` invariant; this PR makes `agentnative-skill` the third consumer of that pattern. - Related PRs: parallel sister PR pending in agentnative-spec to list `agentnative-skill` as a downstream consumer in its top-level `AGENTS.md`. ## Testing - [ ] Unit tests added/updated - [ ] Integration tests added/updated - [x] Manual testing completed - [x] All tests passing **Test Summary:** - `markdownlint-cli2 '**/*.md'` — 0 errors across 26 markdown files (vendored `bundle/spec/CHANGELOG.md` is in `ignores` per upstream-edited content). - `shellcheck --severity=style scripts/*.sh` — exit 0 (only producer scripts remain; bundle has none). - `actionlint .github/workflows/*.yml` — exit 0. - `scripts/sync-spec.sh` — verified end-to-end against `~/dev/agentnative-spec @ v0.2.0`; produces the seven expected principle files plus `VERSION` and `CHANGELOG.md`. - `scripts/generate-changelog.sh --check` — exit 0 (CHANGELOG.md has versioned section). ## Files Modified **Modified:** - `.github/CODEOWNERS` - `.github/ISSUE_TEMPLATE/bug_report.md` - `.github/workflows/ci.yml` - `.markdownlint-cli2.yaml` - `AGENTS.md` - `CONTRIBUTING.md` - `README.md` - `RELEASES.md` - `bundle/SKILL.md` **Created:** - `bundle/getting-started.md` - `bundle/spec/{VERSION,CHANGELOG.md,README.md,principles/p1-p7.md}` (10 files) - `scripts/sync-spec.sh` - `.github/ISSUE_TEMPLATE/bundle_proposal.md` **Renamed:** - `.github/ISSUE_TEMPLATE/principle_proposal.md` → `.github/ISSUE_TEMPLATE/bundle_proposal.md` (rewritten in place; retargets to bundle changes only, redirects principle changes upstream) **Deleted:** - `bundle/checklists/new-tool.md` - `bundle/references/principles-deep-dive.md` - `bundle/scripts/check-compliance.sh` - `bundle/scripts/checks/_helpers.sh` and 24 `bundle/scripts/checks/check-*.sh` files - `.shellcheckrc` ## Breaking Changes - [ ] No breaking changes - [x] Breaking changes described below: The skill-install layout changes for any consumer who previously fetched `bundle/scripts/` or `bundle/checklists/`. Those paths no longer exist. Replacement workflow: - For compliance checking, install `anc` (`brew install brettdavies/tap/agentnative` or `cargo install agentnative`) and run `anc check --output json`. The full agent loop is in `bundle/getting-started.md`. - For principle text, read `bundle/spec/principles/p<N>-*.md` (vendored at the pinned spec ref). - For onboarding flow, read `bundle/getting-started.md` instead of `bundle/checklists/new-tool.md`. Coordinate with the agentnative-site session before tagging v0.2.0 — the install endpoint at `anc.dev/install` must adapt to fetch only the surviving bundle paths. ## Deployment Notes - [ ] No special deployment steps required - [x] Deployment steps documented below: This PR lands on `dev` only. The actual v0.2.0 release follows the `release/*` flow per `RELEASES.md`: 1. Cut `release/v0.2.0` from `origin/main`. 2. Cherry-pick non-docs commits from `dev`: this PR's squash commit + `893e253` (#1) + `80099fc` (#2) + `bb5dce9` (#3). Skip the `docs(plan): ...` commits (`632b4d1`, `e8d46e4`, `774f969`). 3. Bump `VERSION` to `0.2.0`. Run `scripts/generate-changelog.sh` to populate the `[0.2.0]` section. 4. Open `release/v0.2.0 → main` PR; verify `guard-docs / check-forbidden-docs` passes. 5. After merge: tag `v0.2.0`, run `gh release create` for both `v0.1.0` (retroactive) and `v0.2.0`. 6. Updated handoff to agentnative-site session: new SHA + `bundle/` fetch instruction (only the surviving paths). ## Checklist - [x] Code follows project conventions and style guidelines - [x] Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/) - [x] Self-review of code completed - [ ] Tests added/updated and passing - [x] No new warnings or errors introduced - [ ] Changes are backward compatible (or breaking changes documented)

Cherry-pick of 0e04e53 (#5), bundle/ portion only. The docs/plans hunk was dropped on the release branch per the audience-based rule (planning surface stays on dev; this branch only ships consumer-facing changes to main). Removes `# any platform with Rust` from the cargo install snippet in both bundle/SKILL.md and bundle/getting-started.md. The brew line above already names the platforms; the cargo line stands alone without commentary.

The README was authored when rulesets couldn't be applied (private repo on free tier) and documented apply/verify procedures + bypass notes. Now that rulesets are applied (Step 11, 2026-04-28), the README is overhead: - Filenames already self-document (protect-main, protect-dev, protect-tags). - Apply procedure is one-time historical; re-apply is a basic gh api call. - Verify section was actively misleading — admin always-bypass means owner cannot solo-run the negative tests as documented. - Bypass notes are inline in each JSON's bypass_actors anyway. JSON files retained: they ARE useful (version-controlled rule definitions, single source of truth for re-apply, diff-able).

## Summary Match the licensing pattern on `agentnative-cli` so producers can adapt the skill bundle's check scripts into their own tooling without re-licensing friction. Apache-2.0 contributes the standard contributor patent grant (§3 of the license), which matters for downstream consumers who bake these scripts into Rust / Go / other tooling. ## Changelog ### Changed - License changed from MIT-only to dual MIT or Apache-2.0 (consumer's choice). The skill bundle, top-level scripts, and all repo content are now dual-licensed; no MIT compatibility regression. ### Added - `LICENSE-APACHE` — Apache 2.0 boilerplate, identical to the file in `agentnative-cli`. ### Documentation - `README.md` — License section rewritten to reflect dual licensing and link both LICENSE files; tree row updated. - `CONTRIBUTING.md` — License section rewritten: contributions are dual-licensed at the consumer's option, no CLA, with an explicit pointer to the Apache §3 patent grant. ## Type of Change - [x] `chore`: Maintenance tasks (dependencies, config, etc.) ## Related Issues/Stories - Bootstrap plan: `docs/plans/2026-04-27-001-bootstrap-agentnative-skill-plan.md` (task #15 v0.2.0 release will cherry-pick this commit). - Sibling repo licensing: `agentnative-cli` already ships dual MIT/Apache; `agentnative-spec` ships CC-BY (for spec text) + dual MIT/Apache (for code). ## Testing - [x] Manual testing completed - [x] All tests passing **Test Summary:** - markdownlint runs on every push; expected clean. - shellcheck runs on every push; no shell-script changes here. - License files are static text; no runtime test surface. ## Files Modified **Modified:** - `README.md` — License section + tree row. - `CONTRIBUTING.md` — License section. **Renamed:** - `LICENSE` → `LICENSE-MIT` (100% rename; same MIT text, history preserved via `git mv`). **Created:** - `LICENSE-APACHE` — Apache 2.0 boilerplate. ## Breaking Changes - [ ] No breaking changes - [x] Breaking changes described below: This is a license addition (now dual-licensed) — strictly a permissive expansion. Anyone who consumed v0.1.0 under MIT can continue to use it under MIT; the Apache option is added, not substituted. No re-licensing of past releases. Marked here because the file rename `LICENSE` → `LICENSE-MIT` is a path change consumers may have hardcoded; downstream tooling that grep'd for `LICENSE` should now look for either or both. ## Deployment Notes - [x] No special deployment steps required ## Additional Context Vendored content under `bundle/spec/` remains CC BY 4.0 by upstream inheritance from `agentnative-spec`; no change to that arrangement. Attribution stays in `bundle/spec/README.md`. This change applies only to `agentnative-skill`. `agentnative-spec` and `agentnative-cli` are unchanged. `agentnative-site` was not in scope of the request.

## Summary Cross-repo coordinated rename: the site is flipping the skill-distribution endpoint from `anc.dev/install` to `anc.dev/skill` (work happening in parallel in `agentnative-site`). This PR flips the three prose references in `agentnative-skill` to match. ## Changelog ### Changed - Documentation now points at `https://anc.dev/skill` instead of `https://anc.dev/install` for skill installation instructions, the cross-repo re-pin process, and the `bundle/` consumer description. ## Type of Change - [x] `chore`: Maintenance tasks (dependencies, config, etc.) - [x] `docs`: Documentation update ## Related Issues/Stories - Cross-repo: parallel rename in `agentnative-site` (route + data + tests + llms.txt + sitemap). This repo's contribution is prose-only. - Bootstrap plan: `docs/plans/2026-04-27-001-bootstrap-agentnative-skill-plan.md` task #15 (v0.2.0 release) will cherry-pick this commit. ## Testing - [x] Manual testing completed (grep verification: no remaining `anc.dev/install` URL refs in non-planning, non-historical markdown). - [x] All tests passing (CI runs markdownlint + shellcheck). **Test Summary:** - markdownlint: clean. - shellcheck: no shell changes. - Verified post-edit grep produces no hits for the old URL path in consumer-facing markdown. ## Files Modified **Modified:** - `README.md` — install instructions pointer. - `RELEASES.md` — step 5 of the cross-repo re-pin process. - `CONTRIBUTING.md` — `bundle/` description. ## Breaking Changes - [x] No breaking changes to this repo's surface. The URL change is observable to any reader who follows a link from this repo's docs to the site, but only after the site cutover lands. ## Deployment Notes - [x] No special deployment steps required from this repo. - **Coordination note:** safe to merge as soon as the site cutover lands `/skill` (with or without `/install` redirect). If merged before the site flip, README readers who click through hit a 404 transiently. ## Additional Context **Out of scope, intentionally:** - `bundle/**` — no `anc.dev` references in the bundle today; nothing to change. - `docs/plans/**` — planning surface; direct-to-dev per the audience-based branch-discipline rule. The user already has a related plan-doc untracked locally; it will land on `dev` separately. - `CHANGELOG.md` — generated artifact (per `RELEASES.md` and global `~/.claude/CLAUDE.md`); the v0.1.0 historical entry stays as written. The v0.2.0 entry (when task #15 runs `scripts/generate-changelog.sh`) will pick up this commit's `## Changelog` section above. - `RELEASES.md` line 174 references the site's `install.json` filename. Left alone — open question whether the site renames the file too or just serves it at `/skill.json` while keeping the source filename. Follow-up after site cutover lands.

## Summary `CHANGELOG.md` is a generated artifact — `scripts/generate-changelog.sh` writes single-line bullets per PR, and rich PR-body bullets routinely exceed the 120-char MD013 line-length limit. Wrapping those lines would conflict with the generator on every regen. Mirrors the existing exclusion for `spec/CHANGELOG.md` (also generated / vendored). Same rationale: content is authored elsewhere, this repo's lint rules don't apply at this layer. Surfaced when the v0.2.0 release CHANGELOG (9 cherry-picked PRs' worth of curated bullets after the parallel PR-body audit) tripped MD013 on the `release/v0.2.0` → `main` CI run. ## Changelog ### Changed - `.markdownlint-cli2.yaml` excludes `CHANGELOG.md` from linting. Aligns its treatment with `spec/CHANGELOG.md` and reflects that the file is regenerated by `scripts/generate-changelog.sh`, not hand-edited. Per-line content is governed by PR-body bullets in source PRs, not by this repo's MD013 line-length rule. ## Type of Change - [x] `chore`: Maintenance tasks (config) ## Related Issues/Stories - Related PRs: gates `release/v0.2.0` → `main` (PR #12). The v0.2.0 release CHANGELOG content is the trigger; without this lint exclusion, every release will trip MD013. ## Testing - [x] Manual testing completed - [x] All tests passing **Test Summary:** - `markdownlint-cli2 'CHANGELOG.md'` after the config change: `Linting: 0 file(s) / Summary: 0 error(s)` (file correctly excluded). - `markdownlint-cli2 '**/*.md'` (full repo): unchanged behavior on all other files. ## Files Modified **Modified:** - `.markdownlint-cli2.yaml` — added `- "CHANGELOG.md"` to ignores list with a comment explaining the rationale. ## Breaking Changes - [x] No breaking changes Lint config tweak only; no shipping content affected. ## Deployment Notes - [x] No special deployment steps required ## Checklist - [x] Code follows project conventions and style guidelines - [x] Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/) - [x] Self-review of code completed - [x] Tests added/updated and passing - [x] No new warnings or errors introduced - [x] Changes are backward compatible

## Summary Implements **U1** and **U2** of `docs/plans/2026-04-28-001-feat-update-check-mechanism-plan.md` — the gstack-style consumer-side update-check that replaces the deprecated `install.json` SHA-pin advisory. A small bash script in the skill bundle compares the consumer's local `VERSION` against the producer repo's raw GitHub `VERSION` on demand and emits `UPGRADE_AVAILABLE` when they diverge. The agent surfaces the result via `AskUserQuestion` from the SKILL.md preamble. No site round-trip, no third-party advertised SHA, no schema field that gets out of sync between releases. Required for skill `v0.2.0` so the launch-day install path doesn't silently lose the staleness-detection capability the SHA pin was a placeholder for. ## Changelog ### Added - `bundle/bin/check-update` — script that compares the consumer's local `VERSION` against the producer repo's `main` and emits `UPGRADE_AVAILABLE <local> <remote>` (or empty when up-to-date / snoozed / disabled). Adapts the gstack pattern with cache TTL (60min UP_TO_DATE / 720min UPGRADE_AVAILABLE) and a 3-level snooze (24h / 48h / 7d). State directory: `$HOME/.cache/agent-native-cli/`. - `bundle/SKILL.md` `## Update check` section — first non-frontmatter section after the intro. Documents how to invoke the script and inlines the AskUserQuestion-driven upgrade flow with three options ("Yes, upgrade now" / "Not now" / "Never ask again"). ### Changed - `bundle/SKILL.md`, `bundle/getting-started.md`, `bundle/spec/README.md` — drop "pinned ref" / "pinned upstream tag" / "pinned SPEC_VERSION" framing in favor of "vendored snapshot, refreshed each release". The bundle's behavior is unchanged; the language was misleading because the install command never actually pinned at the consumer side. ### Documentation - `bundle/spec/README.md` licensing reference catches drift from PR #6: was "MIT-licensed", now reflects the actual dual MIT/Apache-2.0 posture introduced in `18836d8`. ## Type of Change - [x] `feat`: New feature (non-breaking change which adds functionality) - [x] `docs`: Documentation update ## Related Issues/Stories - Plan: `docs/plans/2026-04-28-001-feat-update-check-mechanism-plan.md` — gstack-style update-check + drop install.json SHA pin. - Bootstrap plan task #15 (`docs/plans/2026-04-27-001-bootstrap-agentnative-skill-plan.md`): the v0.2.0 release branch will cherry-pick this PR into its scope. - Site-repo follow-up: U3 (drop SHA-pin fields from `install.json`), U4 (test updates), U5 (doc scrubs) — all owner-driven in the agentnative-site session per the plan's `Target repo:` annotations. ## Testing - [x] Manual smoke testing per plan's U1 verification suffices for v0.2.0; formal `bats` tests deferred per the plan's Scope Boundaries. - [x] All tests passing (CI runs markdownlint + shellcheck). **Test Summary:** - `bash -n bundle/bin/check-update` — passes (syntax check). - `shellcheck bundle/bin/check-update` — clean. - Happy path (`local==remote`, both `0.1.0`): empty output, exit 0. - Synthetic upgrade (`AGENTNATIVE_SKILL_REMOTE_URL=file:///tmp/fake-version` with `99.0.0`): emits `UPGRADE_AVAILABLE 0.1.0 99.0.0`, exit 0. - `git ls-files --stage bundle/bin/check-update` reports `100755` (executable bit committed). - `grep -irE 'pinned at|pinned ref|pinned upstream' bundle/` returns zero hits (excluding vendored `bundle/spec/principles/` content). - markdownlint-cli2 clean on each modified file. ## Files Modified **Created:** - `bundle/bin/check-update` — 154-line bash script, mode `100755`. **Modified:** - `bundle/SKILL.md` — `## Update check` section + drop "pinned ref" prose in two places. - `bundle/getting-started.md` — reword "What spec version is this skill pinned to?" -> "What spec version does this bundle ship?". - `bundle/spec/README.md` — drop "pinned" framing in 3 places + update licensing reference to dual MIT/Apache-2.0. ## Breaking Changes - [x] No breaking changes. Adds a new script + a SKILL.md section; existing flows continue to work. ## Deployment Notes - [x] No special deployment steps required from this repo. Consumers see the new behavior on their next `git pull` after the skill ships v0.2.0. ## Additional Context **Out of scope, intentionally** (per the plan's `Target repo:` annotations): - U3 — drop `version`/`source.commit`/`verify` fields from site `install.json` (target repo: `agentnative-site`). - U4 — site test updates (target repo: `agentnative-site`). - U5 — site doc scrubs (target repo: `agentnative-site`). - U6 — plan-doc retroactive scrubs (mixed; will fold into the v0.2.0 release-branch amend + a separate dev-side commit on the bootstrap plan).

) ## Summary PR #3 moved consumer-facing skill content into `bundle/` as an aesthetic separation between consumer and producer surfaces. That separation conflicts with the actual install model — site's `skill.json` runs plain `git clone --depth 1` into `<host>/skills/agent-native-cli/`, which lands `SKILL.md` at `<skill-root>/bundle/SKILL.md` instead of `<skill-root>/SKILL.md` where Claude Code, Codex, Cursor, and OpenCode expect to find it. Without this fix, **no host loads the skill on launch day.** Resolution: revert to the gstack-style flat layout. Plain `git clone` produces a working install; `git pull --ff-only` produces a working update; producer-ops files (`scripts/`, `docs/`, `.github/`, `cliff.toml`, `AGENTS.md`, etc.) clone alongside but are inert at runtime. Same shape gstack ships at `~/.claude/skills/gstack/`. ## Changelog ### Changed - **BREAKING (install layout):** Skill content moved out of `bundle/` to the repo root. After install, hosts find `SKILL.md` at the skill root (where Claude Code expects it), not at `<skill-root>/bundle/SKILL.md`. Plain `git clone --depth 1` and `git pull --ff-only` are now the load-bearing install + update commands; no sparse-checkout magic, no post-install scripts. - `bin/check-update`: `SKILL_DIR` is now one dir up from the script (was two), since there's no `bundle/` layer. - `scripts/sync-spec.sh` writes to `spec/` (was `bundle/spec/`). - README, AGENTS, CONTRIBUTING reframe the consumer/producer split from a directory boundary (`bundle/` vs everything else) to an audience boundary (host reads `SKILL.md` + `bin/` + `spec/` + `references/` + `templates/` + `VERSION`; ignores everything else). ## Type of Change - [x] `refactor`: Code refactoring (no functional changes) - [x] `BREAKING CHANGE`: Breaking API change (requires major version bump for v1.0+; ships in v0.x minor under SemVer 0.x convention) ## Related Issues/Stories - Fixes the install-layout incoherence surfaced during U2 smoke-test planning. - Folds into v0.2.0 cherry-pick scope. Bootstrap plan task #15 (`docs/plans/2026-04-27-001-bootstrap-agentnative-skill-plan.md`) gets a new candidate row. - Site team: `skill.json` install command stays as-is — no site-side change needed. ## Testing - [x] Unit/integration/e2e/red-team battery (40 tests) re-run against new layout. **40 pass / 0 fail.** - [x] `shellcheck bin/check-update`: clean. - [x] `bash -n bin/check-update`: clean. - [x] `markdownlint-cli2` clean on all touched files (PostToolUse hook ran on each edit). - [x] CI on this branch (markdownlint + shellcheck) is the gating signal — expect green. **Test Summary:** The 40-test battery covers: VERSION read paths (missing, whitespace-only, surrounding whitespace), disabled sentinel (set + cleared), HOME unset, snooze parser (level 1/2/3 escalation, expiry, version-reset, corrupt 1-field, non-numeric level/epoch), cache freshness (cold start, fast-path UP_TO_DATE, fast-path UPGRADE_AVAILABLE, stale TTL re-fetch, version drift mid-cache, corrupt cache), remote validation (valid SemVer, pre-release, build-metadata, HTML response, empty response, file-URL nonexistent), real-network GitHub fetch, e2e clone-layout invocation, and red-team injection / non-ASCII / read-only state / symlink-attack scenarios. ## Files Modified **Renamed (28 files):** - `bundle/SKILL.md` → `SKILL.md` - `bundle/getting-started.md` → `getting-started.md` - `bundle/bin/check-update` → `bin/check-update` - `bundle/references/*` → `references/*` (4 files) - `bundle/spec/*` → `spec/*` (CHANGELOG, README, VERSION, 7 principle files) - `bundle/templates/*` → `templates/*` (4 files) **Modified prose to drop `bundle/` path prefixes:** - `SKILL.md`, `getting-started.md`, `README.md`, `AGENTS.md`, `CONTRIBUTING.md`, `RELEASES.md`, `spec/README.md` - `.github/ISSUE_TEMPLATE/bug_report.md`, `.github/ISSUE_TEMPLATE/bundle_proposal.md` - `.markdownlint-cli2.yaml` - `scripts/sync-spec.sh` **Modified script:** - `bin/check-update` — `SKILL_DIR` resolves to `(dirname $0)/..` (one level), not two. Comment header updated. Env var name `AGENTNATIVE_SKILL_DIR` unchanged (still the install root override). All 40 battery tests still pass. ## Breaking Changes - [x] Breaking changes described: **Path break:** Any v0.1.0 install that pinned to `bundle/*` paths will break on `git pull`. **Mitigation:** v0.1.0 was never publicly consumed (private until 2026-04-28; only this session's testing has done git clones). v0.2.0 ships with the flat layout; consumers see the corrected layout on first install, no migration needed. ## Deployment Notes - [x] No special deployment steps required from this repo. - Cherry-picks into `release/v0.2.0` after merge to `dev`. Adds one row to the task #15 cherry-pick scope table. ## Additional Context **Out of scope, intentionally:** - Sparse-checkout install command (rejected during planning — breaks `git pull --ff-only` updates). - Setup script post-install (rejected — same break + adds bootstrap complexity). - Hiding producer-ops files into a `_meta/` or `.producer/` dir (deferred — additive cleanup, not launch-blocking). **The install model is now coherent end-to-end:** ```bash # install git clone --depth 1 https://github.com/brettdavies/agentnative-skill.git ~/.claude/skills/agent-native-cli # update cd ~/.claude/skills/agent-native-cli && git pull --ff-only # uninstall rm -rf ~/.claude/skills/agent-native-cli ```

…on (#10) ## Summary Re-vendor `spec/` from `agentnative-spec` v0.2.0 → v0.3.0 (status flips draft → active across all 7 principles, prose edits from upstream G11 red-team pass) and add a `## Spec re-vendoring` section to `RELEASES.md` documenting the upstream-only coordination model. Originally landed as an in-cherry-pick on `release/v0.2.0` (commit `837ab9a` → amended `1640460`). Converting to a real PR so the v0.2.0 CHANGELOG carries a curated bullet for the spec bump — direct cherry-picks have no PR body for `scripts/generate-changelog.sh` to extract from. After PR #11 (sync-spec modernization) landed on dev, this branch was rebased and the new RELEASES.md section was rewritten to drop `SPEC_REF` references that PR #11 eliminated. ## Changelog ### Changed - Spec content vendored under `spec/` re-vendored from `agentnative-spec` v0.2.0 to v0.3.0. All 7 principles flip `status: draft` → `status: active` (P1–P7 are now the shipped baseline); prose tightened across P1 (TUI parenthetical), P2 (sysexits acknowledgment), P4 (dependency-gating cleanup), P5 (`--dry-run` write-gate + retry hedge), P6 (SIGPIPE language-neutral + global-flags behavioral lead), P7 (LLM-vs-non-LLM cost generalization). No requirement IDs added/removed/renamed; no level changes. Full upstream context: agentnative `v0.3.0` CHANGELOG. ### Documentation - `RELEASES.md` gains a `## Spec re-vendoring` section between `## Why branch from main, not dev` and `## Version bump procedure`, documenting the `scripts/sync-spec.sh` re-vendor step. The script auto-resolves the latest upstream tag from the remote, so no manual version selection is needed at re-vendor time. ## Type of Change - [x] `chore`: Maintenance tasks (dependencies, config, etc.) - [x] `docs`: Documentation update ## Related Issues/Stories - Architecture: `docs/plans/2026-04-27-001-bootstrap-agentnative-skill-plan.md` task #15 (in-cherry-pick edits subsection) - Related PRs: PR #11 (`chore(sync-spec): drop SHA-pin claims, modernize to remote-first vendoring`) — already merged; this PR was rebased onto dev after #11 landed and its added section was updated to match the post-#11 vocabulary. - Replaces: in-cherry-pick commit `1640460` on `release/v0.2.0`. After this PR squash-lands on `dev`, the release branch will be replayed to swap `1640460` for this PR's squash commit (which carries the curated CHANGELOG bullet). ## Testing - [x] Manual testing completed - [x] All tests passing **Test Summary:** - `markdownlint-cli2` clean on all touched files (PostToolUse hook ran on each edit; explicit pre-push run after the post-rebase RELEASES.md fix: 0 errors). - `shellcheck` n/a (no shell changes — this PR no longer touches `scripts/sync-spec.sh`; that surface is owned by PR #11 which is already on dev). - `spec/VERSION` confirmed at `0.3.0`. - `spec/CHANGELOG.md` carries the curated v0.3.0 entry from upstream agentnative. - Post-rebase diff against `origin/dev`: 10 files, +294/-60 — only `spec/*` (vendored content) and `RELEASES.md` (new section). No conflict against PR #11's already-landed `sync-spec.sh` modernization. - Vocabulary check: `rg` for `SPEC_REF` in this PR's diff returns zero matches (was non-zero before rebase; fixed by amending the RELEASES.md section to use the auto-resolve framing). ## Files Modified **Modified:** - `RELEASES.md` — `+8 lines`: new `## Spec re-vendoring` section between existing sections. - `spec/VERSION` — `0.2.0` → `0.3.0`. - `spec/CHANGELOG.md` — re-vendored from upstream; carries the v0.3.0 entry. - `spec/principles/p1-non-interactive-by-default.md` — re-vendored. - `spec/principles/p2-structured-parseable-output.md` — re-vendored. - `spec/principles/p3-progressive-help-discovery.md` — re-vendored. - `spec/principles/p4-fail-fast-actionable-errors.md` — re-vendored. - `spec/principles/p5-safe-retries-mutation-boundaries.md` — re-vendored. - `spec/principles/p6-composable-predictable-command-structure.md` — re-vendored. - `spec/principles/p7-bounded-high-signal-responses.md` — re-vendored. ## Breaking Changes - [x] No breaking changes The principle status flip from `draft` → `active` is a state-of-spec signal, not a contract change. Requirement IDs, levels, and applicability are unchanged. ## Deployment Notes - [x] No special deployment steps required Vendored content only; consumers pick up the new spec on their next `git pull --ff-only` (driven by `bin/check-update`). ## Checklist - [x] Code follows project conventions and style guidelines - [x] Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/) - [x] Self-review of code completed - [x] Tests added/updated and passing (CI: markdownlint + shellcheck pass) - [x] No new warnings or errors introduced - [x] Changes are backward compatible

…oring (#11) ## Summary Two coordinated cleanups to `scripts/sync-spec.sh` and surrounding docs: 1. **Drop the SHA-pin model.** Eliminates all SHA-pin claims and the `SPEC_REF` override surface. After this PR merges, `rg` for any of `SHA`, `sha-pin`, `commit sha`, `source.commit`, `install.json`, `re-pin`, `SPEC_REF`, `pin`, `pinned`, `pinning` across shipping content (excluding `docs/plans/`, license boilerplate, and `CHANGELOG.md` / `spec/CHANGELOG.md`) returns **zero** matches. 2. **Remote-first vendoring with local fallback.** `sync-spec.sh` queries the upstream remote for the latest `v*` tag first; only falls back to a local `SPEC_ROOT` checkout when the remote is unreachable. Removes the manual `git fetch --tags` step from the happy path; works in fresh environments without a pre-existing local clone. ## Changelog ### Changed - `scripts/sync-spec.sh`: - **No longer accepts `SPEC_REF`.** Always vendors the latest `v*` tag. - **Resolution path:** queries `SPEC_REMOTE_URL` (default `https://github.com/brettdavies/agentnative.git`) via `git ls-remote --tags --sort=-version:refname`, picks the latest `v*`, then shallow-clones that tag into a temp directory for extraction. On any remote failure, falls back to the existing `SPEC_ROOT`-based logic (default `$HOME/dev/agentnative-spec`). - **New env var `SPEC_REMOTE_URL`** for overriding the remote. - **Temp clone is auto-cleaned** on script exit via trap. ### Removed - All SHA-pin claims from public-facing markdown (`RELEASES.md`, `AGENTS.md`, `README.md`, `spec/README.md`, `CONTRIBUTING.md`): pipeline diagram's "site re-pins to commit SHA" step, the post-merge "site re-pins via its own PR" step, the `protect-tags.json` / `install endpoints` claims that tags are pinned to install endpoints, and the spec-vendor "pinned ref" / "pinned `SPEC_REF`" / "current pin is recorded" vocabulary across all docs. ### Documentation - `AGENTS.md` `## Spec sync` section: rewritten — single-step recipe (`scripts/sync-spec.sh` then review); notes the remote-first / local-fallback behavior and the `SPEC_REMOTE_URL` / `SPEC_ROOT` overrides. Commit-message example uses `<version>` placeholder instead of a hard-coded version. - `spec/README.md` `## Resync` section: rewritten similarly; drops the manually-maintained `**Current snapshot:**` line and points readers at `spec/VERSION` (which `sync-spec.sh` writes verbatim from upstream). - `RELEASES.md` post-merge sequence ends at the GitHub Release; replaces deleted step 5 with a one-liner pointing consumers at `bin/check-update`. ## Type of Change - [x] `chore`: Maintenance tasks (dependencies, config, etc.) - [x] `docs`: Documentation update ## Related Issues/Stories - Architecture: `docs/plans/2026-04-28-001-feat-update-check-mechanism-plan.md` U6 (retroactive plan-doc + repo SHA-pin scrub) — partial. Plan files themselves are not scrubbed in this PR (they are dev-only and contain the historical record of the SHA-pin removal effort). - Related PRs: PR #10 (spec re-vendor v0.3.0) — touches different `RELEASES.md` hunks; no conflict expected at merge. - Mirror: `agentnative-cli/scripts/sync-spec.sh` is the documented mirror of this script. Lockstep update PR will land there as a separate change. ## Testing - [x] Manual testing completed - [x] All tests passing **Test Summary:** - `markdownlint-cli2` clean on all touched files (PostToolUse hook ran on each edit). - `shellcheck --severity=style scripts/sync-spec.sh`: clean. - `bash -n scripts/sync-spec.sh`: clean. - **Remote-success path** verified live: queried `https://github.com/brettdavies/agentnative.git`, resolved `v0.3.0`, shallow-cloned, vendored 7 principles + VERSION + CHANGELOG.md. Output: `vendoring v0.3.0 (5cea8bf) from remote https://github.com/brettdavies/agentnative.git`. - **Remote-fail-local-success path** verified by setting `SPEC_REMOTE_URL=https://github.com/brettdavies/does-not-exist.git`. Output: `warning: remote query failed; falling back to local /home/brett/dev/agentnative-spec` followed by successful vendor from local. - **Both-fail path** verified by setting both bogus remote and bogus `SPEC_ROOT=/tmp/no-such-dir`. Output: `error: remote unreachable and SPEC_ROOT is not a git repository: /tmp/no-such-dir` with both URL and path printed for debugging. - Final grep across shipping content for the full pin-vocabulary regex: **zero** matches. ## Follow-ups (not blocking this PR) - `agentnative-cli/scripts/sync-spec.sh` is documented as a mirror of this script (only `DEST_DIR` differs). Lockstep PR coming in that repo to apply the same modernization. - `agentnative-site` does not yet have a `sync-spec.sh` (only a plan doc). When that script lands per `docs/plans/2026-04-23-001-feat-sync-spec-plan.md`, it should adopt the same remote-first / no-SPEC_REF shape. - Plan files under `docs/plans/` retain SHA-pin language as historical record. If a future cleanup pass wants to scrub them too, that's a separate dev-only PR.

## Summary `CHANGELOG.md` is a generated artifact — `scripts/generate-changelog.sh` writes single-line bullets per PR, and rich PR-body bullets routinely exceed the 120-char MD013 line-length limit. Wrapping those lines would conflict with the generator on every regen. Mirrors the existing exclusion for `spec/CHANGELOG.md` (also generated / vendored). Same rationale: content is authored elsewhere, this repo's lint rules don't apply at this layer. Surfaced when the v0.2.0 release CHANGELOG (9 cherry-picked PRs' worth of curated bullets after the parallel PR-body audit) tripped MD013 on the `release/v0.2.0` → `main` CI run. ## Changelog ### Changed - `.markdownlint-cli2.yaml` excludes `CHANGELOG.md` from linting. Aligns its treatment with `spec/CHANGELOG.md` and reflects that the file is regenerated by `scripts/generate-changelog.sh`, not hand-edited. Per-line content is governed by PR-body bullets in source PRs, not by this repo's MD013 line-length rule. ## Type of Change - [x] `chore`: Maintenance tasks (config) ## Related Issues/Stories - Related PRs: gates `release/v0.2.0` → `main` (PR #12). The v0.2.0 release CHANGELOG content is the trigger; without this lint exclusion, every release will trip MD013. ## Testing - [x] Manual testing completed - [x] All tests passing **Test Summary:** - `markdownlint-cli2 'CHANGELOG.md'` after the config change: `Linting: 0 file(s) / Summary: 0 error(s)` (file correctly excluded). - `markdownlint-cli2 '**/*.md'` (full repo): unchanged behavior on all other files. ## Files Modified **Modified:** - `.markdownlint-cli2.yaml` — added `- "CHANGELOG.md"` to ignores list with a comment explaining the rationale. ## Breaking Changes - [x] No breaking changes Lint config tweak only; no shipping content affected. ## Deployment Notes - [x] No special deployment steps required ## Checklist - [x] Code follows project conventions and style guidelines - [x] Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/) - [x] Self-review of code completed - [x] Tests added/updated and passing - [x] No new warnings or errors introduced - [x] Changes are backward compatible

Bump VERSION to 0.2.0 and regenerate CHANGELOG via scripts/generate-changelog.sh against the cherry-picked PRs (#1, #2, #3, #4, #6, #7, #8, #9, #10, #11, #13). PR bodies were audited by parallel subagents against .github/pull_request_template.md before this regen. PR #13 added CHANGELOG.md to .markdownlint-cli2.yaml ignores so the generated long-line bullets no longer trip MD013 on the release CI run. Squash-merge of release/v0.2.0 onto main becomes the v0.2.0 anchor.

Bootstrap plan (2026-04-27-001): - Task #15 (v0.2.0 release) flipped to checked. Step 3a complete via PR #12 squash-merge to main 2026-04-29 ~16:38 PT (commit 2b10c84). Step 3b (tag + GitHub Release) still pending; commands documented in PR #12 body's Deployment Notes. - Added an "Executed scope (2026-04-29)" addendum capturing the three axes the launch-eve plan diverged on: (a) in-cherry-pick spec re-vendor was converted to a real PR (#10) so the v0.2.0 CHANGELOG carries a curated bullet for the spec bump; (b) two extra PRs added to launch-wave scope mid-execution — PR #11 (SHA-pin scrub + sync-spec.sh modernization) and PR #13 (CHANGELOG.md markdownlint exclusion); (c) the launch-eve admin-bypass concern was pessimistic — guard-docs check ran cleanly from PR head, no bypass needed. - Final cherry-pick chain table appended for the historical record. Update-check mechanism plan (2026-04-28-001) — first commit of this plan to dev: - U1 (bin/check-update script) flipped to done via PR #8. - U2 (SKILL.md preamble + bundle-doc pin-vocab drop) flipped to done via PR #8; broader pin-vocab scrub across RELEASES/AGENTS/README/ CONTRIBUTING/spec/README shipped via PR #11 (added mid-flight to launch-wave scope per U6). - U6 (retroactive scrub) flipped to done for skill scope: PR #11 handled the skill-side cleanup; bootstrap plan task #15 + central tracker (gstack file, separate edit) updated 2026-04-29. Site-side scrubs (U3-U5 + agentnative-site cross-repo-canonical-pointer.md) still pending in the user's parallel session. - U3-U5 remain unchecked — agentnative-site scope, parallel session. The central launch tracker (~/.gstack/projects/brettdavies-agentnative/brett-dev-design-show-hn- launch-inversion-20260427-144756.md) was updated in parallel to: - Mark step 3a done (PR #12 squash 2b10c84) and step 3b pending. - Drop SHA-pin re-pin claims from steps 4 + 5 + the launch-day timeline + the per-repo plan table + the dev-status block (per U6 scrub instructions). Replaced with references to bin/check-update (PR #8) and a note that source.commit is being removed from skill.json in agentnative-site U3 (parallel session). - Step 4 retains the install.json -> skill.json file-rename context from PR #44 since that's still in scope for the site cherry-pick. That tracker is not a git-repo file, so the edits land directly on disk; this commit only touches the two plan files in this repo.

brettdavies added 8 commits April 29, 2026 11:35

brettdavies mentioned this pull request Apr 29, 2026

chore(lint): exclude CHANGELOG.md from markdownlint #13

Merged

11 tasks

brettdavies added 6 commits April 29, 2026 16:59

brettdavies force-pushed the release/v0.2.0 branch from f2528e1 to d66d5bd Compare April 29, 2026 21:59

brettdavies merged commit 2b10c84 into main Apr 29, 2026
5 checks passed

brettdavies deleted the release/v0.2.0 branch April 29, 2026 22:02

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

release: v0.2.0 — agent-native CLI skill bundle public launch#12

release: v0.2.0 — agent-native CLI skill bundle public launch#12
brettdavies merged 14 commits into
mainfrom
release/v0.2.0

brettdavies commented Apr 29, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

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

Uh oh!

Summary

Changelog

Added

Changed

Fixed

Documentation

Removed

Type of Change

Related Issues/Stories

Testing

Files Modified

Breaking Changes

Deployment Notes

Checklist

Additional Context

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

brettdavies commented Apr 29, 2026 •

edited

Loading