docs: document issue → branch → PR workflow in AGENTS.md - #37
Open
abienkowski wants to merge 1 commit into
Open
abienkowski wants to merge 1 commit into
abienkowski wants to merge 1 commit into
Conversation
AGENTS.md described structure, commands and conventions but not how a change is meant to land, so agents had no way to know the repo expects issue → branch → PR. In practice that led to work starting on an already-merged branch, changes with no issue recording the rejected alternatives, and PRs opened without a closing keyword. CONTRIBUTING.md covers some of this for humans but omits the points that are actually got wrong: the branch base, issues, Conventional Commits and the label taxonomy. Documents the six steps with the corresponding gh invocations, including the check that confirms the issue link landed on the PR.
abienkowski
added
the
Type: Documentation
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
1 participant
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 a "Contribution Workflow" section to
AGENTS.mddescribing the issue → branch → PR process the repo already expects in practice but never wrote down in the agent-facing guide.AGENTS.mddocumented structure, commands, architecture, conventions and test layout, but nothing about how a change lands. That gap produced real mistakes: work started on an already-merged branch rather than a fresh branch offmain, changes made with no issue recording the rejected alternatives, and PRs opened without a closing keyword.CONTRIBUTING.mdstays as the human-facing summary and is deliberately not duplicated — it is thin on exactly the points agents get wrong (branch base, issues, Conventional Commits, label taxonomy), and two full copies would drift.The section covers six steps, each with its
ghinvocation, includinggh pr view --json closingIssuesReferencesto confirm the issue link actually landed.Closes #36
Split out of #35 at review request, so the workflow documentation lands independently of the Unix-socket-only change that exposed the gap.
Type of change
Implementation(s) changed
Documentation only — one file,
AGENTS.md. No implementation code touched.Testing
make test-all)make test-integration)make verify)Not applicable and not run: this change touches no build input, no source file and no CI configuration. Ticking these boxes would misrepresent what was verified.
Checklist