docs: generalize agent guidelines by jdx · Pull Request #846 · jdx/hk

jdx · 2026-04-18T19:26:35Z

Summary

add AGENTS.md as a symlink to CLAUDE.md
make the shared agent guide less Claude-specific while keeping the GitHub interaction example as Claude Code
leave the existing conventional commit and PR title guidance intact

Validation

PATH="$PWD/target/debug:$PATH" git commit -m "docs: generalize agent guidelines" ran the pre-commit hook successfully
PATH="$PWD/target/debug:$PATH" git push -u origin codex/agent-guidelines ran the pre-push hook successfully
mise run lint was attempted after bun install; normal checks passed, but the slow cargo-clippy profile failed on unrelated existing Rust warnings in src/cli/migrate/mod.rs, src/git.rs, and src/settings.rs

Note

Low Risk
Documentation-only changes that rename/generalize agent guidance and add an alias file; no runtime or build logic is affected.

Overview
Renames CLAUDE.md to a more general Agent Guidelines document by removing Claude-specific wording while keeping the GitHub AI-disclosure example.

Adds AGENTS.md as a lightweight alias pointing to CLAUDE.md so other agents/tools can discover the same guidance under a neutral filename.

^{Reviewed by Cursor Bugbot for commit 2bcfff7. Bugbot is set up for automated code reviews on this repo. Configure here.}

greptile-apps · 2026-04-18T19:27:48Z

Greptile Summary

This PR adds AGENTS.md as a symlink to CLAUDE.md and generalizes the document's title/intro from Claude-specific language to agent-neutral language, making the guidelines discoverable by a broader set of AI coding tools (e.g. Codex). The conventional commit rules, architecture notes, and development commands are unchanged.

Confidence Score: 5/5

Safe to merge — docs-only change with no functional impact.

Both files are documentation only. The single inline comment is P2 style feedback about a concrete attribution example; it does not block merge.

No files require special attention.

Important Files Changed

Filename	Overview
AGENTS.md	New symlink pointing to `./CLAUDE.md`, making the guidelines discoverable by agents (e.g. Codex) that look for `AGENTS.md`.
CLAUDE.md	Title and intro generalized from "CLAUDE.md / Claude Code" to "Agent Guidelines / AI coding agents"; GitHub Interactions attribution example still references "Claude Code" (intentional per PR description but slightly inconsistent).

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[AI Coding Agent starts] --> B{Which guidelines file\ndoes it look for?}
    B -->|AGENTS.md\ne.g. Codex| C[AGENTS.md symlink]
    B -->|CLAUDE.md\ne.g. Claude Code| D[CLAUDE.md]
    C -->|resolves to| D
    D --> E[Agent Guidelines content\nConventional Commits, Architecture,\nDev Commands, GitHub Interactions]

Comments Outside Diff (1)

CLAUDE.md, line 165 (link)

Claude-specific attribution example in a generalized guide

The PR generalizes the document for all AI coding agents, but the GitHub Interactions section still uses "*This comment was generated by Claude Code.*" as its concrete example. While the e.g. framing gives agents latitude, a non-Claude agent following this guide literally could post comments attributing itself to "Claude Code." A generic placeholder would be cleaner now that the document is agent-neutral.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

_{Reviews (1): Last reviewed commit: "docs: generalize agent guidelines" | Re-trigger Greptile}

gemini-code-assist

Code Review

This pull request introduces an AGENTS.md file and updates the CLAUDE.md file to use more generic terminology, renaming the header to 'Agent Guidelines' and referring to 'AI coding agents' instead of specifically 'Claude Code'. There are no review comments to address, and I have no feedback to provide.

@jdx

### 🚀 Features - **(check)** implement --plan, --why, and --json by [@jdx](https://github.com/jdx) in [#848](#848) - **(cocogitto)** add cocogitto conventional commits config to hk builtin config by [@hituzi-no-sippo](https://github.com/hituzi-no-sippo) in [#838](#838) - **(git)** support GIT_DIR/GIT_WORK_TREE for bare-repo dotfile managers by [@jdx](https://github.com/jdx) in [#847](#847) - **(install)** use Git 2.54 config-based hooks with --global support by [@jdx](https://github.com/jdx) in [#853](#853) ### 🐛 Bug Fixes - use text progress in CI by [@jdx](https://github.com/jdx) in [#845](#845) ### 📚 Documentation - generalize agent guidelines by [@jdx](https://github.com/jdx) in [#846](#846) - add releases nav and aube lock by [@jdx](https://github.com/jdx) in [#849](#849) ### 🔍 Other Changes - bump communique to 1.0.1 by [@jdx](https://github.com/jdx) in [#850](#850) ### 📦️ Dependency Updates - update actions-rust-lang/setup-rust-toolchain digest to 2b1f5e9 by [@renovate[bot]](https://github.com/renovate[bot]) in [#832](#832) - update anthropics/claude-code-action digest to c3d45e8 by [@renovate[bot]](https://github.com/renovate[bot]) in [#833](#833) - update rust crate tokio to v1.52.1 by [@renovate[bot]](https://github.com/renovate[bot]) in [#834](#834) - update actions/upload-pages-artifact action to v5 by [@renovate[bot]](https://github.com/renovate[bot]) in [#835](#835) - update taiki-e/upload-rust-binary-action digest to f0d45ae by [@renovate[bot]](https://github.com/renovate[bot]) in [#839](#839) - update rust crate clx to v2 by [@renovate[bot]](https://github.com/renovate[bot]) in [#836](#836) - update anthropics/claude-code-action digest to 0d2971c by [@renovate[bot]](https://github.com/renovate[bot]) in [#841](#841) - update anthropics/claude-code-action digest to 38ec876 by [@renovate[bot]](https://github.com/renovate[bot]) in [#842](#842) - lock file maintenance by [@renovate[bot]](https://github.com/renovate[bot]) in [#851](#851)  --- > [!NOTE] > **Low Risk** > Low risk release bookkeeping: version bumps and doc/CLI artifact updates, plus minor dependency patch updates in `Cargo.lock`. No functional Rust source changes are included in this diff. > > **Overview** > Bumps `hk` to **v1.44.0** and publishes the corresponding release notes in `CHANGELOG.md`. > > Updates generated/packaged artifacts to match the new version (CLI docs/specs and Pkl package URLs in docs/examples), and refreshes `Cargo.lock` for the release (including patch-level updates like `rustls` and `winnow`). > > <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit a36c7a6. Bugbot is set up for automated code reviews on this repo. Configure [here](https://www.cursor.com/dashboard/bugbot).</sup>  Co-authored-by: mise-en-dev <123107610+mise-en-dev@users.noreply.github.com>

This MR contains the following updates: | Package | Update | Change | |---|---|---| | [hk](https://github.com/jdx/hk) | minor | `1.43.0` → `1.45.0` | MR created with the help of [el-capitano/tools/renovate-bot](https://gitlab.com/el-capitano/tools/renovate-bot). **Proposed changes to behavior should be submitted there as MRs.** --- ### Release Notes <details> <summary>jdx/hk (hk)</summary> ### [`v1.45.0`](https://github.com/jdx/hk/blob/HEAD/CHANGELOG.md#1450---2026-05-04) [Compare Source](jdx/hk@v1.44.3...v1.45.0) ##### 🚀 Features - **(builtins)** add `buildifier` format and lint built-ins by [@plx](https://github.com/plx) in [#896](jdx/hk#896) ##### 🐛 Bug Fixes - **(step)** only auto-batch when rendered command exceeds ARG\_MAX by [@jdx](https://github.com/jdx) in [#901](jdx/hk#901) ##### 📚 Documentation - thank Namespace for GitHub Actions runner support by [@jdx](https://github.com/jdx) in [#895](jdx/hk#895) ##### 🔍 Other Changes - **(ci)** use !cancelled() instead of always() for final job by [@jdx](https://github.com/jdx) in [#906](jdx/hk#906) - **(docs)** remove shrill.en.dev analytics script by [@jdx](https://github.com/jdx) in [#903](jdx/hk#903) - remove rust-cache from release jobs by [@jdx](https://github.com/jdx) in [#893](jdx/hk#893) - invert CLAUDE.md/AGENTS.md so AGENTS.md is canonical by [@jdx](https://github.com/jdx) in [#905](jdx/hk#905) - set dev profile debug to 1 by [@jdx](https://github.com/jdx) in [#907](jdx/hk#907) ##### 📦️ Dependency Updates - update anthropics/claude-code-action digest to [`fefa07e`](jdx/hk@fefa07e) by [@renovate\[bot\]](https://github.com/renovate\[bot]) in [#897](jdx/hk#897) - update jdx/mise-action digest to [`1648a78`](jdx/hk@1648a78) by [@renovate\[bot\]](https://github.com/renovate\[bot]) in [#898](jdx/hk#898) - update apple-actions/import-codesign-certs action to v7 by [@renovate\[bot\]](https://github.com/renovate\[bot]) in [#900](jdx/hk#900) - update autofix-ci/action action to v1.3.4 by [@renovate\[bot\]](https://github.com/renovate\[bot]) in [#899](jdx/hk#899) - lock file maintenance by [@renovate\[bot\]](https://github.com/renovate\[bot]) in [#908](jdx/hk#908) ##### New Contributors - [@plx](https://github.com/plx) made their first contribution in [#896](jdx/hk#896) ### [`v1.44.3`](https://github.com/jdx/hk/blob/HEAD/CHANGELOG.md#1443---2026-04-30) [Compare Source](jdx/hk@v1.44.2...v1.44.3) ##### 🐛 Bug Fixes - **(hook)** do not stage fixes when fail\_on\_fix=true by [@jdx](https://github.com/jdx) in [#892](jdx/hk#892) - use site domain for plausible data-domain by [@jdx](https://github.com/jdx) in [#886](jdx/hk#886) - make text-mode progress output usable in CI by [@jdx](https://github.com/jdx) in [#890](jdx/hk#890) ##### 📚 Documentation - prefix GitHub star count with ★ glyph by [@jdx](https://github.com/jdx) in [#883](jdx/hk#883) ##### 🔍 Other Changes - **(release)** dedupe sponsor section in release notes by [@jdx](https://github.com/jdx) in [#881](jdx/hk#881) - switch analytics from gtm/goatcounter to plausible by [@jdx](https://github.com/jdx) in [#885](jdx/hk#885) - migrate to namespace.so runners by [@jdx](https://github.com/jdx) in [#891](jdx/hk#891) ### [`v1.44.2`](https://github.com/jdx/hk/blob/HEAD/CHANGELOG.md#1442---2026-04-26) [Compare Source](jdx/hk@v1.44.1...v1.44.2) ##### 🐛 Bug Fixes - **(builtins)** silence pklr deprecation warnings on Builtins.pkl load by [@jdx](https://github.com/jdx) in [#880](jdx/hk#880) - **(ci)** serialize docs lint step by [@jdx](https://github.com/jdx) in [#874](jdx/hk#874) - **(config)** include main pkl path in cache fresh files by [@jdx](https://github.com/jdx) in [#879](jdx/hk#879) - **(docs)** stack banner message and link on mobile by [@jdx](https://github.com/jdx) in [#865](jdx/hk#865) - **(docs)** pin banner close button to top-right corner on mobile by [@jdx](https://github.com/jdx) in [#867](jdx/hk#867) ##### 📚 Documentation - **(site)** show release version and github stars by [@jdx](https://github.com/jdx) in [#872](jdx/hk#872) ##### 🔍 Other Changes - add pr-closer workflow by [@jdx](https://github.com/jdx) in [#876](jdx/hk#876) ##### 📦️ Dependency Updates - bump communique 1.0.3 → 1.0.4 by [@jdx](https://github.com/jdx) in [#868](jdx/hk#868) - update anthropics/claude-code-action digest to [`2da6cfa`](jdx/hk@2da6cfa) by [@renovate\[bot\]](https://github.com/renovate\[bot]) in [#869](jdx/hk#869) - update anthropics/claude-code-action digest to [`567fe95`](jdx/hk@567fe95) by [@renovate\[bot\]](https://github.com/renovate\[bot]) in [#870](jdx/hk#870) - bump communique to 1.1.2 by [@jdx](https://github.com/jdx) in [#875](jdx/hk#875) ### [`v1.44.1`](https://github.com/jdx/hk/blob/HEAD/CHANGELOG.md#1441---2026-04-24) [Compare Source](jdx/hk@v1.44.0...v1.44.1) ##### 🐛 Bug Fixes - **(git)** skip untracked scan when HK\_STASH\_UNTRACKED=false by [@jdx](https://github.com/jdx) in [#861](jdx/hk#861) - **(run)** add post-commit and pre-rebase subcommands by [@jdx](https://github.com/jdx) in [#858](jdx/hk#858) ##### 📚 Documentation - **(install)** recommend global hooks as primary setup path by [@jdx](https://github.com/jdx) in [#855](jdx/hk#855) - add cross-site announcement banner by [@jdx](https://github.com/jdx) in [#857](jdx/hk#857) - respect banner expires field by [@jdx](https://github.com/jdx) in [#862](jdx/hk#862) ##### 🔍 Other Changes - vendor bats test helpers instead of git submodules by [@jdx](https://github.com/jdx) in [#859](jdx/hk#859) ##### 📦️ Dependency Updates - bump communique to 1.0.3 by [@jdx](https://github.com/jdx) in [#863](jdx/hk#863) - update anthropics/claude-code-action digest to [`e58dfa5`](jdx/hk@e58dfa5) by [@renovate\[bot\]](https://github.com/renovate\[bot]) in [#864](jdx/hk#864) ### [`v1.44.0`](https://github.com/jdx/hk/blob/HEAD/CHANGELOG.md#1440---2026-04-23) [Compare Source](jdx/hk@v1.43.0...v1.44.0) ##### 🚀 Features - **(check)** implement --plan, --why, and --json by [@jdx](https://github.com/jdx) in [#848](jdx/hk#848) - **(cocogitto)** add cocogitto conventional commits config to hk builtin config by [@hituzi-no-sippo](https://github.com/hituzi-no-sippo) in [#838](jdx/hk#838) - **(git)** support GIT\_DIR/GIT\_WORK\_TREE for bare-repo dotfile managers by [@jdx](https://github.com/jdx) in [#847](jdx/hk#847) - **(install)** use Git 2.54 config-based hooks with --global support by [@jdx](https://github.com/jdx) in [#853](jdx/hk#853) ##### 🐛 Bug Fixes - use text progress in CI by [@jdx](https://github.com/jdx) in [#845](jdx/hk#845) ##### 📚 Documentation - generalize agent guidelines by [@jdx](https://github.com/jdx) in [#846](jdx/hk#846) - add releases nav and aube lock by [@jdx](https://github.com/jdx) in [#849](jdx/hk#849) ##### 🔍 Other Changes - **(release)** append en.dev sponsor blurb to release notes by [@jdx](https://github.com/jdx) in [#854](jdx/hk#854) - bump communique to 1.0.1 by [@jdx](https://github.com/jdx) in [#850](jdx/hk#850) ##### 📦️ Dependency Updates - update actions-rust-lang/setup-rust-toolchain digest to [`2b1f5e9`](jdx/hk@2b1f5e9) by [@renovate\[bot\]](https://github.com/renovate\[bot]) in [#832](jdx/hk#832) - update anthropics/claude-code-action digest to [`c3d45e8`](jdx/hk@c3d45e8) by [@renovate\[bot\]](https://github.com/renovate\[bot]) in [#833](jdx/hk#833) - update rust crate tokio to v1.52.1 by [@renovate\[bot\]](https://github.com/renovate\[bot]) in [#834](jdx/hk#834) - update actions/upload-pages-artifact action to v5 by [@renovate\[bot\]](https://github.com/renovate\[bot]) in [#835](jdx/hk#835) - update taiki-e/upload-rust-binary-action digest to [`f0d45ae`](jdx/hk@f0d45ae) by [@renovate\[bot\]](https://github.com/renovate\[bot]) in [#839](jdx/hk#839) - update rust crate clx to v2 by [@renovate\[bot\]](https://github.com/renovate\[bot]) in [#836](jdx/hk#836) - update anthropics/claude-code-action digest to [`0d2971c`](jdx/hk@0d2971c) by [@renovate\[bot\]](https://github.com/renovate\[bot]) in [#841](jdx/hk#841) - update anthropics/claude-code-action digest to [`38ec876`](jdx/hk@38ec876) by [@renovate\[bot\]](https://github.com/renovate\[bot]) in [#842](jdx/hk#842) - lock file maintenance by [@renovate\[bot\]](https://github.com/renovate\[bot]) in [#851](jdx/hk#851) </details> --- ### Configuration 📅 **Schedule**: (UTC) - Branch creation - At any time (no schedule defined) - Automerge - At any time (no schedule defined) 🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied. ♻ **Rebasing**: Whenever MR becomes conflicted, or you tick the rebase/retry checkbox. 🔕 **Ignore**: Close this MR and you won't be reminded about this update again. --- - [ ] If you want to rebase/retry this MR, check this box --- This MR has been generated by [Mend Renovate](https://github.com/renovatebot/renovate).

docs: generalize agent guidelines

2bcfff7

jdx marked this pull request as ready for review April 18, 2026 19:29

jdx merged commit c6e316d into main Apr 18, 2026
21 checks passed

jdx deleted the codex/agent-guidelines branch April 18, 2026 19:29

jdx mentioned this pull request Apr 18, 2026

chore: release v1.44.0 #837

Merged

gemini-code-assist Bot reviewed Apr 18, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs: generalize agent guidelines#846

docs: generalize agent guidelines#846
jdx merged 1 commit intomainfrom
codex/agent-guidelines

jdx commented Apr 18, 2026 •

edited by cursor Bot

Loading

Uh oh!

greptile-apps Bot commented Apr 18, 2026 •

edited

Loading

Comments Outside Diff (1)

Uh oh!

Uh oh!

gemini-code-assist Bot left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

jdx commented Apr 18, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Validation

Uh oh!

greptile-apps Bot commented Apr 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Greptile Summary

Confidence Score: 5/5

Important Files Changed

Flowchart

Comments Outside Diff (1)

Uh oh!

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

jdx commented Apr 18, 2026 •

edited by cursor Bot

Loading

greptile-apps Bot commented Apr 18, 2026 •

edited

Loading