Skip to content

Add AGENTS.md and .github/copilot-instructions.md for AI agent onboarding #132

Description

@francisfuzz

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions