Add AGENTS.md for AI coding agents - #24
Merged
Merged
Conversation
Records the things about this gem that are easy to get wrong: that ~/.morph holds a live API key and must never end up in output or a fixture, that the upload includes every file not under a dot directory, that the server streams newline-delimited JSON rather than plain text, and that create_tar deliberately hands back an open rewound tempfile. Also notes that bare rake fails here because the Rakefile has no default task, that SimpleCov enforces a 90% floor so the suite can fail with every example passing, that .rubocop_todo.yml is an accepted backlog rather than something to regenerate, and that scraper.rb in the root is a leftover sample scraper rather than gem code. CLAUDE.md and .github/copilot-instructions.md are pointers, so the guidance lives in one place regardless of which tool reads it. Org-wide workflow and disclosure rules are referenced rather than restated, with the gh commands to fetch them. Assisted-by: Claude Code:claude-opus-5 Signed-off-by: Ben Fairless <ben@oaf.org.au>
The org-level guidance section told agents to fetch CONTRIBUTING.md and AGENTS.md with "gh api", which only works where the GitHub CLI happens to be present. A Copilot session, a fresh container or an outside contributor may have neither it nor an authenticated token, and the guidance is public, so it doesn't need one. Links to both files plus their raw URLs instead, so any HTTP client will do. Assisted-by: Claude Code:claude-opus-5 Signed-off-by: Ben Fairless <ben@oaf.org.au>
all_paths prunes directories whose name starts with a dot, but a dot-file isn't a directory, so it gets packed. Verified by calling all_paths against a temporary tree: a top-level .env comes back in the list, while a file inside .hidden_dir does not. The previous wording was true but easy to read as "hidden files are skipped", which is the wrong way round on the one case that has consequences. Assisted-by: Claude Code:claude-opus-5 Signed-off-by: Ben Fairless <ben@oaf.org.au>
ianheggie-oaf
approved these changes
Aug 18, 2026
ianheggie-oaf
left a comment
ianheggie-oaf
left a comment
Member
There was a problem hiding this comment.
Approved - lgtm when reading through the files
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
2 participants
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.
Description
Adds
AGENTS.mdto this repository, withCLAUDE.mdand.github/copilot-instructions.mdas one-line pointers to it. The guidance then lives in one place and applies whichever AI tool someone is using, rather than being duplicated per tool or existing only for Claude.The content is limited to repo-specific knowledge that isn't obvious from reading the code, and it doesn't restate the README or the org contributing guide. The things most likely to save someone:
~/.morphholds a live API key, so it must never be echoed or used in a fixture; the upload includes every file not under a dot directory, so.gitis skipped but a straydata.sqliteis not; the server streams newline-delimited JSON with astreamandtextper line rather than plain text; andcreate_tardeliberately returns an open, rewound tempfile.On the tooling side it records that bare
bundle exec rakefails here with "Don't know how to build task 'default'" because the Rakefile is onlyrequire "bundler/gem_tasks", that SimpleCov enforcesminimum_coverage 90so the suite can fail with every example passing, that.rubocop_todo.ymlis an accepted backlog rather than something to regenerate, and thatscraper.rbin the root is a leftover sample scraper kept for exercising the CLI by hand rather than gem code.The branch is
doc/add-agents-mdrather than the issue-numbered form in the org guide, because there's no tracking issue for this work.Motivation and Context
Part of standardising how AI coding agents are briefed across OAF repositories:
AGENTS.mdis canonical,CLAUDE.mdand.github/copilot-instructions.mdpoint at it. This repository had no agent instructions, and a couple of the items above (the API key in~/.morph, what the tar includes) are ones where an agent guessing wrong has consequences beyond a failed test.How Has This Been Tested?
Every command and file path named in AGENTS.md was checked against this repository before writing it, rather than assumed. I ran the documented commands locally on Ruby 3.2.2 and confirmed each behaves as described.
Types of Changes
Checklist:
This change is documentation, and it does not duplicate the README or the org contributing guide, so nothing else needed updating alongside it.
Note on packaging
All three gemspecs set
spec.filesfromgit ls-files, so these three files will be included in the next published gem. That seemed better than special-casing the gemspec, but flagging it so it is a decision rather than a surprise.AI disclosure
I used Claude Code (claude-opus-5) to explore the repository and draft these files, and reviewed the result myself before opening this pull request. Each commit carries an
Assisted-by: Claude Code:claude-opus-5trailer.