docs(agents): adopt the binding delivery conventions - #16
Merged
Conversation
Adds `.github/pull_request_template.md` and the Conventions entries that bind every contributor, agents included, to `microservice-app-docs/docs/Pull request and task tracking conventions.md`. The rule that was missing: every task completed is marked in the same pull request that completed it, and only against a located artifact — never from a summary, a green check, or a rendered manifest. Spec 007 sat at 0/27 while twenty-one of its tasks were already delivered and merged; that is what this prevents. Also binds the pull-request format itself, keeps the `test(scope): specify` -> `feat(scope): implement` pair intact as SDD evidence, and states plainly that an AI agent may open and update a pull request but may never approve one or author an acceptance artifact. Constitution principle 13 (Traceable Delivery), drafted in microservice-app-docs, is what makes this non-negotiable. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NLzNfeedbe2xFTjwrBPPBg
The template listed the required sections and never said what language to write them in. The omission had an immediate consequence: the pull requests that introduced these conventions had Spanish bodies while their commits and files were English. Mirrors section 3 of the conventions, added in microservice-app-docs.
Mirrors section 3 of the conventions: the body is written in English and then repeated under a Spanish heading with the same content. Titles, commits, code comments, and documentation stay English-only. Applies to AI agents too — an agent writes both halves itself.
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.
Part of a cross-repository change. The rule itself lives in
microservice-app-docs#7; this pull request adopts it here.What changes
.github/pull_request_template.md— six required sections: what changes, why, tasks, how it is verified, risk and rollback, and what it does not do. Plus two checkboxes that have to be true: that the task register was updated in this pull request, and that every ticked task was verified by locating its artifact.## Conventionsentries inAGENTS.md(symlinked asCLAUDE.md, so both are covered): branch, commit, and PR format; the SDD commit pair kept intact; the traceability rule; and the merge prohibitions.Why
Pull requests arrived in whatever shape their author chose, and work was delivered without its task register ever being updated. Spec 007 read 0/27 while twenty-one of its tasks were already delivered and merged.
The concrete rule: every completed task is marked in the same pull request that completed it, and only against a located artifact — never from a summary, a green check, or a rendered manifest. Partial delivery is annotated, not ticked.
For AI agents
Written explicitly: an agent may open, describe, and update a pull request, and may never approve one or author an acceptance artifact. Also that nobody merges with
--admin, force-pushesmain, or disables a branch protection rule to land their own work — and that outcomes are reported faithfully: name what is red, say what was skipped.Tasks
No register covers this. It is cross-cutting governance that predates the specifications, which the convention itself requires to be stated rather than left silent.
How it is verified
The template and the
AGENTS.mdentries were read back after writing.CLAUDE.mdwas confirmed to still resolve as a symlink toAGENTS.md.Risk and rollback
Documentation and a template only; no code, manifests, or infrastructure. Revert the commit.
What this PR does not do
It does not change any existing convention text beyond appending to
## Conventions, and it does not enforce the format mechanically — the template guides, it does not gate.