Add AGENTS.md and copilot-instructions.md for AI agent onboarding#133
Merged
Conversation
francisfuzz
changed the title
AGENTS.md and copilot-instructions.md for AI agent onboarding
Add two complementary instruction files so AI coding agents can work effectively in this repository without re-discovering conventions: - AGENTS.md (7K chars): agent-agnostic open standard with full project structure, build/test commands, coding patterns, testing conventions, error handling, key interfaces, and non-obvious gotchas. - .github/copilot-instructions.md (2K chars): concise Copilot-specific instructions under the 4K code review limit, covering the essentials and referencing AGENTS.md for full details. Closes #132 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
francisfuzz
force-pushed
the
agent-instructions-132
branch
from
5626eef to
8178580
Compare
skarim
reviewed
Jun 17, 2026
skarim
left a comment
skarim
left a comment
Collaborator
There was a problem hiding this comment.
Thanks for putting this together! One small correction on the build command, rest looks great ✨
Co-authored-by: Sameen Karim <skarim@github.com>
Co-authored-by: Sameen Karim <skarim@github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR adds two AI agent onboarding files to the repository, closing #132. The files provide build commands, project structure, testing patterns, error handling conventions, and key interfaces so that AI coding agents don't have to rediscover this context from scratch each time.
Changes:
- Adds
AGENTS.mdat the repo root — a comprehensive agent-agnostic instruction file covering project layout, build/test/validate commands, command structure patterns, error codes, testing mock patterns, key interfaces, stack file internals, CI workflows, and non-obvious codebase gotchas. - Adds
.github/copilot-instructions.md— a shorter Copilot-specific version with essentials and a link toAGENTS.mdfor full details.
Show a summary per file
| File | Description |
|---|---|
AGENTS.md |
Comprehensive agent instruction file covering the full project architecture, conventions, and patterns |
.github/copilot-instructions.md |
Concise Copilot-specific instructions (~2K chars) with essentials and link to AGENTS.md |
Copilot's findings
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 2/2 changed files
- Comments generated: 2
- go build ./... compiles but does not produce a binary. Changed to
go build -o gh-stack . which actually outputs the executable.
- errors.As(err, &ExitError{}) panics at runtime because the value
type ExitError does not satisfy the error interface (only *ExitError
does). Updated to the correct two-line pattern matching cmd/root.go.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
skarim
approved these changes
Jun 17, 2026
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
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
Closes #132
This repo doesn't have any instruction files for AI coding agents, so every agent that shows up here has to re-discover the build commands, testing patterns, project structure, etc. from scratch each time. This PR adds two files to fix that:
AGENTS.mdat the repo root. This is the open standard that works across Copilot, Codex, Cursor, and other agents. It's got the full picture: project layout, build/test commands, how commands are structured, the mock/testing patterns, error handling with the typed exit codes, key interfaces, and some of the non-obvious stuff like the stack file locking and thedefer restore()gotcha..github/copilot-instructions.mdis a shorter version (~2K chars) that Copilot Chat, code review, and completions pick up. Kept it well under the 4K char limit for code review. It points toAGENTS.mdfor the full details.I wrote these after going through the codebase and pulling out the things that would've saved me the most time on first contact. The mock patterns especially (
git.SetOps,MockClient, the config hooks) aren't obvious without reading a few test files first.For reviewers
AGENTS.mdfeel right, or is it too much? Happy to trim if it's noisy.copilot-instructions.mdis intentionally minimal. Should it cover anything else, or is the "essentials + link to AGENTS.md" approach good?