Skip to content

Document the issue → branch → PR contribution workflow in AGENTS.md #36

Description

@abienkowski

Is your feature request related to a problem?

AGENTS.md is the operating guide for coding agents working in this repo, and it documents structure, commands, architecture, conventions and test layout — but says nothing about how a change is supposed to land. An agent reading it has no way to know that this repo expects issue → branch → PR.

The result is predictable and has already happened in practice:

  • work started directly on an already-merged branch instead of a fresh branch off main, because merged branches linger locally and git branch --show-current looks unremarkable;
  • changes made with no issue behind them, so the rejected alternatives are never written down anywhere;
  • PRs opened without a Closes #N keyword, leaving issues to be closed by hand.

CONTRIBUTING.md covers some of this for humans, but it is thin on the points agents actually get wrong: it says "create a feature branch" without specifying the base, does not mention issues at all, does not mention Conventional Commits, and does not mention the label taxonomy. It also is not the file agents are pointed at.

Describe the solution

Add a "Contribution Workflow" section to AGENTS.md covering the six steps the repo already expects in practice:

  1. Open an issue first, using the .github/ISSUE_TEMPLATE/ structure, recording the problem with file:line evidence and the alternatives that were rejected.
  2. Label it — Type: * required, Status: Break Change for CLI/config/wire changes, Priority: P0–P3 for bugs.
  3. Branch off main, never off another feature branch, with feat/… fix/… docs/… spec/… naming, verified against git log origin/main --oneline -1.
  4. Commit with Conventional Commits — the release pipeline derives version bumps from the type, so it is not cosmetic.
  5. Open the PR with a Closes #N keyword and fill in the PR template honestly.
  6. Verify before marking ready, with pasted evidence rather than claims.

Include the gh invocations for each step, including gh pr view --json closingIssuesReferences to confirm the issue link actually landed.

Describe alternatives

  • Put it in CONTRIBUTING.md only. Rejected: that file is aimed at human contributors and is not what agents are pointed at. The failure being fixed here is an agent-facing one.
  • Leave it implicit and correct it in review. Rejected: it recurs every session, since agents start with no memory of the previous correction.
  • Duplicate the full text into both files. Rejected: two copies drift. AGENTS.md gets the operational detail; CONTRIBUTING.md stays the human-facing summary.

Which implementation(s) would this affect?

  • Go
  • Rust
  • TypeScript
  • Quint specification
  • All

Documentation only — no implementation code is touched.

Additional context

Split out of #35, which is where the gap surfaced.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type: DocumentationAdded to issues or PRs that relate to the project wiki, or documentation.

    Type

    No type

    Fields

    Priority

    None yet

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions