Summary
This repository has no agent instruction files, which means every AI coding agent (Copilot, Codex, Cursor, etc.) starts from scratch each time — re-discovering build commands, testing patterns, project structure, and conventions.
Proposal
Add two complementary files:
| File |
Purpose |
Read by |
AGENTS.md |
Agent-agnostic open standard (agents.md spec) |
Copilot cloud agent, OpenAI Codex, Cursor, Amp, Jules, Gemini, and others |
.github/copilot-instructions.md |
GitHub Copilot-specific instructions (docs) |
Copilot Chat, code review, completions, cloud agent |
What to include
- Project overview: Go CLI extension for managing stacked PRs
- Build / test / vet commands:
go mod download, go build ./..., go test -race -count=1 ./..., go vet ./...
- Project structure: key packages (
cmd/, internal/git, internal/stack, internal/github, etc.)
- Testing patterns:
config.NewTestConfig(), git.SetOps(mock), MockClient, table-driven tests, testify assertions
- Error handling: typed
ExitError codes, errors.As() pattern
- Key interfaces:
git.Ops, github.ClientOps
- Coding conventions: Cobra commands, bubbletea TUI, config injection hooks
Design considerations
copilot-instructions.md should stay under ~4,000 chars (Copilot code review limit)
AGENTS.md can be more detailed
- Both should use natural language Markdown — no proprietary format
- Content should be broadly applicable (not task-specific)
References
Summary
This repository has no agent instruction files, which means every AI coding agent (Copilot, Codex, Cursor, etc.) starts from scratch each time — re-discovering build commands, testing patterns, project structure, and conventions.
Proposal
Add two complementary files:
AGENTS.md.github/copilot-instructions.mdWhat to include
go mod download,go build ./...,go test -race -count=1 ./...,go vet ./...cmd/,internal/git,internal/stack,internal/github, etc.)config.NewTestConfig(),git.SetOps(mock),MockClient, table-driven tests,testifyassertionsExitErrorcodes,errors.As()patterngit.Ops,github.ClientOpsDesign considerations
copilot-instructions.mdshould stay under ~4,000 chars (Copilot code review limit)AGENTS.mdcan be more detailedReferences