refactor!: flatten bundle/* to repo root for plain git-clone install by brettdavies · Pull Request #9 · brettdavies/agentnative-skill

brettdavies · 2026-04-29T19:30:01Z

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).

Fixed

Align table pipes in SKILL.md and getting-started.md after the bundle/ path strip (markdownlint MD060). MD060 isn't auto-fixable, so violations slipped past the local PostToolUse hook and surfaced in CI.

Type of Change

refactor: Code refactoring (no functional changes)
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

Unit/integration/e2e/red-team battery (40 tests) re-run against new layout. 40 pass / 0 fail.
shellcheck bin/check-update: clean.
bash -n bin/check-update: clean.
markdownlint-cli2 clean on all touched files (PostToolUse hook ran on each edit, with the MD060 follow-up commit covering the table-pipe alignment).
CI on this branch (markdownlint + shellcheck) is the gating signal — 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

Breaking changes described:

Path break: Any v0.1.0 install that referenced bundle/* paths breaks on git pull because those paths no longer exist — SKILL.md is now at the skill root, bin/check-update at <skill-root>/bin/, and so on. Hosts that auto-discover SKILL.md at the skill root (Claude Code, Codex, Cursor, OpenCode) start working with this layout where they failed under the previous one.

Migration: None required. v0.1.0 was never publicly consumed (private until 2026-04-28; only this session's testing has done git clones). v0.2.0 is the first release shipping under the new layout, and consumers see the corrected paths on first install. Anyone who happened to clone v0.1.0 during the private window can re-clone or git pull --ff-only and the new layout takes effect immediately.

Deployment Notes

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.

Checklist

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

Additional Context

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:

# 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

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. Layout change: - bundle/SKILL.md -> SKILL.md - bundle/getting-started.md -> getting-started.md - bundle/bin/check-update -> bin/check-update - bundle/references/* -> references/* - bundle/spec/* -> spec/* - bundle/templates/* -> templates/* - bundle/ removed. Script change (bin/check-update): SKILL_DIR is now one dir up from the script (was two), since there's no bundle/ layer. Env-override naming unchanged (AGENTNATIVE_SKILL_DIR). Comment header updated. Prose changes (consumer-facing markdown): 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 — all bundle/X path references rewritten to X. README + AGENTS + CONTRIBUTING reframe the consumer/producer split from a directory boundary to an audience boundary (host reads SKILL.md + bin/ + spec/ + references/ + templates/ + VERSION; ignores everything else). Producer scripts: scripts/sync-spec.sh writes to spec/ (was bundle/spec/). .markdownlint-cli2.yaml ignore for spec/CHANGELOG.md (was bundle/spec/CHANGELOG.md). BREAKING for consumers: 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). Launch ships v0.2.0 with the flat layout; consumers see the corrected layout on first install. Verification: 40-test battery (unit/integration/e2e/red-team) re-run against the new layout, 40 pass / 0 fail. shellcheck + bash -n clean. markdownlint clean on all touched files (PostToolUse hook ran on each).

…D060) CI on PR #9 caught MD060 'table-column-style' violations: the bundle/ prefix removal in PR #9 made the trimmed body cells shorter than the header pipes, breaking aligned-table style. The local PostToolUse hook runs markdownlint-cli2 --fix, but MD060 isn't auto-fixable, so the violations slipped past local lint. Fixes: - SKILL.md line 19: pad trailing cell whitespace to match header. - getting-started.md lines 61-69: shorten the 'Where' column header + separator to match the post-strip body widths.

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, #11 plus the in-cherry-pick spec re-vendor + RELEASES coordination edits). Squash-merge of release/v0.2.0 onto main becomes the v0.2.0 anchor.

…ection Two coordinated edits: 1. Re-vendor spec/ against agentnative-spec v0.3.0 via SPEC_REF=v0.3.0 scripts/sync-spec.sh. Bundle now ships principle text matching anc.dev (status: active, all v0.3.0 prose). spec/VERSION bumps 0.2.0 -> 0.3.0; spec/CHANGELOG.md and all 7 principle files updated. 2. Add 'Spec re-vendoring' section to RELEASES.md documenting how skill releases coordinate with upstream agentnative-spec — re-vendor spec/ on each release, no site-side coordination claim. Durable framing, not specific to v0.3.0. The AGENTS.md SPEC_REF v0.2.1 -> v0.3.0 bump from the original release-branch in-cherry-pick is no-op against dev (PR #9 already rebased that example to v0.3.0).

) ## 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 ```

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). PR bodies were audited by parallel subagents against .github/pull_request_template.md before this regen — empty stubs removed, missing template sections added, internal-detail bullets moved out of ## Changelog, PR #11's nested sub-bullets flattened so the generator preserves them. Squash-merge of release/v0.2.0 onto main becomes the v0.2.0 anchor.

) ## 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 ```

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.

@brettdavies

## 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 #1 - `AGENTS.md` (root) describing the bundle layout, lint commands, branch model, and hard rules for agents. by @brettdavies in #2 - `RELEASES.md` (root) documenting a release procedure for this repo (later rewritten in #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 #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 #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 #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 #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 #9 (final flat shape; intermediate `bundle/` indirection from #3 reverted before launch). - License changed from MIT-only to dual MIT or Apache-2.0 (no MIT compatibility regression). by @brettdavies in #6 - Documentation now points at `https://anc.dev/skill` instead of `https://anc.dev/install`. by @brettdavies in #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 #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 #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 #8 - Align table pipes in `SKILL.md` and `getting-started.md` (markdownlint MD060). by @brettdavies in #9 ### Documentation - `README.md` — License section rewritten to reflect dual licensing and link both LICENSE files; tree row updated. by @brettdavies in #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 #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 #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 #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 - [x] `chore`: Maintenance tasks (release engineering) - [x] `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 #8 + the SHA-pin removal across PR #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 - [x] Manual testing completed - [x] 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 #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 #1–#11. ## Files Modified **Cherry-picked from dev (squash commits):** - `8be19e6` — feat(bundle): consumer-side update-check mechanism (U1+U2) [#8] - `34b1da3` — 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 [#10] - `fb50d18` — chore(sync-spec): drop SHA-pin claims, modernize to remote-first vendoring [#11] - `e67523e` — 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 - [x] 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 - [x] 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):** 1. Tag the squash commit on `main`: ```bash git checkout main && git pull git tag -a v0.2.0 -m "v0.2.0" git push origin v0.2.0 ``` 2. Create the GitHub Release with the v0.2.0 CHANGELOG section as notes: ```bash gh release create v0.2.0 --title "v0.2.0" \ --notes "$(awk '/^## \[0\.2\.0\]/{flag=1; next} /^## \[/{flag=0} flag' CHANGELOG.md)" ``` 3. Consumers detect the new release on their next `bin/check-update` run; no site-side coordination step (the SHA-pin model is gone, per #11). ## 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 green on every cherry-picked commit) - [x] No new warnings or errors introduced - [x] Changes are backward compatible (or breaking changes documented in Breaking Changes section) ## Additional Context - Full v0.2.0 entry in [`CHANGELOG.md`](./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.

Cleanroom git-clone --depth 1 from main + 4 invocations of bin/check- update against the real raw.githubusercontent.com URL. All four checks pass: flat install layout (PR #9 claim), UPGRADE_AVAILABLE detection on stale local VERSION, UP_TO_DATE silent path on matching local VERSION, and the warm-cache TTL fast path. Settles the load-bearing v0.2.0 claims end-to-end against published artifacts. Skill side of the launch wave is verifiably launch-ready.

After tag + GitHub Release published 22:16 UTC, ran end-to-end smoke against the real raw.githubusercontent.com URL. All four scenarios green: - Fresh `git clone --depth 1` lands SKILL.md at install root (PR #9 flat-layout claim verified in production); 18 entries at root incl. bin/, spec/, references/, templates/, VERSION=0.2.0; bin/check-update mode 100755. - VERSION=0.1.0 + fresh cache: bin/check-update emits exact `UPGRADE_AVAILABLE 0.1.0 0.2.0` against live remote. - VERSION=0.2.0 + fresh cache: silent stdout, exit 0; cache file $HOME/.cache/agent-native-cli/last-update-check written with `UP_TO_DATE 0.2.0` (17 bytes). - Re-run within 60min TTL: silent stdout, exit 0, no second cache write — cache-hit fast path confirmed. Update-check plan U1 § "Verification": appended a "Production smoke" subsection with the four scenarios, exact commands, and outputs. Notes the post-flatten path (`bin/check-update`, not `bundle/bin/check-update`) for future readers. Bootstrap plan task #15: appended a one-paragraph smoke summary after the Step 3b completion note, pointing at the U1 transcript for full detail. The smoke validates the load-bearing claims of PR #4 (install/upgrade contract), PR #8 (check-update mechanism), and PR #9 (flat-layout install).

brettdavies added 2 commits April 29, 2026 14:29

brettdavies merged commit 0bf8a88 into dev Apr 29, 2026
2 checks passed

brettdavies deleted the refactor/flatten-bundle branch April 29, 2026 19:35

brettdavies mentioned this pull request Apr 29, 2026

chore(spec): re-vendor spec/ to v0.3.0 + RELEASES spec-revendor section #10

Merged

12 tasks

brettdavies mentioned this pull request Apr 29, 2026

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

Merged

12 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

refactor!: flatten bundle/* to repo root for plain git-clone install#9
brettdavies merged 2 commits into
devfrom
refactor/flatten-bundle

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

Changed

Fixed

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