chore(repo): add AGENTS.md, PR template, RELEASES.md, guard-main-docs (lightweight release scaffold)#2
Merged
Conversation
… caller
Establish the lightweight release pattern (feat/* → dev → main, no
release/* cherry-pick branches) and the ops scaffolding for it.
AGENTS.md (root):
- Project-level instructions for agents working in this repo. Calls
out that this is NOT a Rust CLI (no Cargo, no clap), explains the
bundle layout, lint commands, branch model, and what an agent must
never do (touch scripts/checks/* casually, commit plans heading
toward main, re-tag, etc.).
- Distinct from templates/agents-md-template.md, which targets
downstream Rust CLI consumers of the skill.
.gitignore:
- Negate the global **/AGENTS.md ignore for this repo only. The
producer repo is the canonical home for how agents operate against
the bundle; AGENTS.md ships here on purpose.
.github/pull_request_template.md:
- Copy of ~/.config/github/pull_request_template.md (the canonical
SoT, stowed from dotfiles). GitHub does not follow symlinks for PR
template discovery, so each repo keeps its own copy.
.github/workflows/guard-main-docs.yml:
- Caller for brettdavies/.github reusable workflow that blocks
docs/plans/, docs/solutions/, docs/brainstorms/, docs/reviews/
from reaching main on any PR. This makes the "plans don't go on
main" rule mechanically enforced rather than convention-only.
RELEASES.md (root):
- Adapted from the canonical github-repo-setup template for the
lightweight pattern: feat/* → dev → main with one squash-merge
PR per release. Documents version-bump procedure, branch model,
ruleset apply (deferred post-public-flip), and the status-check
context table verified against this repo's actual contexts.
- Explicitly notes when to upgrade to the full release/* pattern.
brettdavies
added a commit
that referenced
this pull request
Apr 27, 2026
Now that PR #2 ships the .github/workflows/guard-main-docs.yml caller that invokes the brettdavies/.github reusable workflow, the protect-main ruleset can require its check as a hard gate. Add to required_status_checks: - guard-docs / check-forbidden-docs Caller job key is `guard-docs` and the reusable workflow's job is `check-forbidden-docs`, so the published context is exactly that string. Verified by reading the reusable workflow at brettdavies/.github/.github/workflows/guard-main-docs.yml@main. This is order-independent with PR #2: the ruleset is only applied post-public-flip (Task #11), by which point both PRs will have landed. The check itself runs on every PR with base=main from the moment PR #2 lands, even before the ruleset enforces it. Also update .github/rulesets/README.md's summary table to list the three required status checks instead of two.
14 tasks
brettdavies
added a commit
that referenced
this pull request
Apr 27, 2026
…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)
15 tasks
brettdavies
added a commit
that referenced
this pull request
Apr 27, 2026
…, 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)
Merged
16 tasks
brettdavies
added a commit
that referenced
this pull request
Apr 27, 2026
…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)
brettdavies
added a commit
that referenced
this pull request
Apr 28, 2026
…lease pattern, task #15 surfaced) - Step 9 verification gates: all [ ] checkboxes flipped to [x] with current-state annotations. Visibility gate marked superseded (PUBLIC since 2026-04-28). Force-push gate annotated with the protect-dev bypass-log evidence acquired during the PR #5 redo. - Step 10 hand-off note: 'still PRIVATE' line marked superseded. - Additions table: rulesets/README.md row struck through with deletion note (5d93913). RELEASES.md row updated to reflect that PR #3 rewrote it from lightweight to canonical cherry-pick pattern. - Adopted release pattern: corrected to match current on-disk RELEASES.md (release/v<X.Y.Z> cherry-pick). The earlier 'lightweight no-cherry-pick' claim was accurate at PR #2 time but stale post-PR-#3. - Outstanding tasks: surfaced bootstrap session task #15 (v0.2.0 release) as the one remaining open item, with concrete cherry-pick scope table (PR-#1 through PR-#5 + 5d93913, with the PR #5 docs/plans hunk to drop).
brettdavies
added a commit
that referenced
this pull request
Apr 29, 2026
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.
12 tasks
brettdavies
added a commit
that referenced
this pull request
Apr 29, 2026
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
added a commit
that referenced
this pull request
Apr 29, 2026
## 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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Establish the lightweight release pattern for this repo (
feat/* → dev → mainwith 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.
(Note: the lightweight pattern was later reversed in #3 in favour of the full
release/*cherry-pick pattern. Thefiles this PR adds remain valid; only
RELEASES.mdwas rewritten in #3.)Changelog
Added
AGENTS.md(root) describing the bundle layout, lint commands, branch model, and hard rules for agents working inthis producer repo.
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 fullrelease/*pattern)..github/pull_request_template.md(canonical PR template)..github/workflows/guard-main-docs.ymlcaller for thebrettdavies/.githubreusable workflow that blocksdocs/plans/,docs/solutions/,docs/brainstorms/,docs/reviews/from PRs targetingmain.Changed
.gitignoreadds!AGENTS.mdto override the global**/AGENTS.mdignore for this repo only. Other repos remainunaffected.
Type of Change
chore: Maintenance tasks (dependencies, config, etc.)Related Issues/Stories
~/dev/agentnative-site/docs/plans/2026-04-24-001-feat-skill-distribution-endpoint-plan.mdprotect-main.jsonrequires theguard-docs / check-forbidden-docscontext produced by this PR's workflow)
Testing
Test Summary:
markdownlint-cli2 '**/*.md'— 0 errors across 15 markdown files.actionlint .github/workflows/*.yml— exit 0.brettdavies/.github/.github/workflows/guard-main-docs.yml@mainconfirmed to exist and acceptworkflow_callwith no required inputs.git statusafter.gitignorenegation confirmsAGENTS.mdis no longer ignored.Files Modified
Modified:
.gitignoreCreated:
AGENTS.mdRELEASES.md.github/pull_request_template.md.github/workflows/guard-main-docs.ymlBreaking Changes
Deployment Notes
The
guard-main-docsworkflow runs on PRs tomainfrom the moment this PR lands. The ruleset that requires itsstatus check (added in #1) only takes effect post-public-flip via Task #11.
Checklist