Skip to content

docs: add GitHub template governance guidance for AI agents - #1080

Closed
ashleyshaw wants to merge 1 commit into
developfrom
docs/github-template-governance-ai-guidance
Closed

ashleyshaw wants to merge 1 commit into
developfrom
docs/github-template-governance-ai-guidance

Conversation

@ashleyshaw

Copy link
Copy Markdown
Member

Documentation Pull Request

This repository enforces changelog, release, and label automation for all PRs and issues.
See the organisation-wide Automation Governance & Release Strategy for required rules.

Linked issues

Relates to #1078

What changed

  • AGENTS.md: Added "GitHub Template Governance" section with comprehensive guidance for AI agents
  • CLAUDE.md: Added "Issue Template Quick Reference" section with quick lookup table

Audience & placement

  • Audience: contributors (AI agents and developers)
  • Location: AGENTS.md (organisation-wide) and CLAUDE.md (repo-local)

Changelog

Added

  • GitHub Template Governance documentation (AGENTS.md) — Comprehensive section guiding AI agents on creating compliant PRs and issues programmatically, with 25 issue types, validation functions, and code examples. Addresses issue Add GitHub template governance guidance for AI agents #1078.
  • Issue Template Quick Reference (CLAUDE.md) — Quick lookup table mapping issue types to templates with emphasis on mandatory Definition of Ready (DoR) and Definition of Done (DoD) sections.

Checklist (Global DoD / PR)

  • All AC met and demonstrated
  • Tests added/updated (N/A for documentation)
  • Accessibility checklist completed (Markdown follows hierarchy)
  • Docs/readme/changelog updated
  • Security checklist completed (no secrets introduced)
  • Code/design reviews approved
  • CI green; linked issues; release notes prepared

🤖 Created via proper GitHub workflow: Issue → Branch → PR → Merge

@coderabbitai

coderabbitai Bot commented Jul 22, 2026 •

Copy link
Copy Markdown
Contributor

Warning

Review limit reached

@ashleyshaw, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 35 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details
⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro

Run ID: 1f15999b-2b1d-40d8-bd91-295f9b983c7b

📥 Commits

Reviewing files that changed from the base of the PR and between 86f3914 and 6ad8dbc.

📒 Files selected for processing (2)
  • AGENTS.md
  • CLAUDE.md
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch docs/github-template-governance-ai-guidance

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

Added comprehensive guidance to help AI agents create compliant pull requests
and issues:

- AGENTS.md: New 'GitHub Template Governance' section with:
  * Pull request template guidance (preventative enforcement)
  * Issue template guidance (reactive with pre-flight validation)
  * 25 issue types mapped to template files
  * Programmatic creation patterns with code examples
  * JavaScript validation function
  * Complete bash example

- CLAUDE.md: New 'Issue Template Quick Reference' section with:
  * Quick lookup table mapping issue types to templates
  * Mandatory sections emphasized (Definition of Ready & Done)
  * Cross-reference to AGENTS.md for detailed guidance

This enables AI agents to create template-compliant issues programmatically,
avoiding post-creation flagging with status:needs-more-info.

Addresses #1078

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
@github-actions

Copy link
Copy Markdown
Contributor

🔍 Reviewer Summary for PR #1080

CI Status: ✅ success
Files changed: 2
Risk Distribution: 0 critical, 0 high, 0 medium, 2 low

Recommendations

  • Ready to proceed pending human review

@ashleyshaw
ashleyshaw force-pushed the docs/github-template-governance-ai-guidance branch from 7a3cfca to 6ad8dbc Compare July 22, 2026 11:06
@ashleyshaw
ashleyshaw enabled auto-merge (squash) July 22, 2026 11:06
@ashleyshaw ashleyshaw closed this Jul 22, 2026
auto-merge was automatically disabled July 22, 2026 11:07

Pull request was closed

@ashleyshaw
ashleyshaw deleted the docs/github-template-governance-ai-guidance branch July 22, 2026 11:07

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 7a3cfcae23

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread AGENTS.md

```
.github/ISSUE_TEMPLATE/
├── 01-bug.md

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Use the repository's actual issue-template filenames

For programmatic bug, refactor, task, chore, testing, performance, accessibility, security, compatibility, build, and automation issues, this inventory points agents at either a nonexistent file or the wrong issue type. The current tree starts with 01-task.md, 02-bug.md, and 09-code-refactor.md, while testing through compatibility are numbered 12–16; consequently the bug example's cat .github/ISSUE_TEMPLATE/01-bug.md fails and the duplicated CLAUDE.md table is also unusable. Replace both maps with the canonical filenames from the template directory.

AGENTS.md reference: AGENTS.md:L118-L124

Useful? React with 👍 / 👎.

Comment thread AGENTS.md
Comment on lines +121 to +123
- All issue templates require:
- `## Definition of Ready (DoR)` — pre-work checklist
- `## Definition of Done (DoD)` — completion checklist

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Account for templates that lack the mandatory sections

When an agent creates a testing-coverage, performance, research, audit, AI-ops, or content-modelling issue, the official template contains neither or both of these asserted headings, so extracting the template and running the supplied JavaScript validator prevents creation. Either add DoR and DoD to .github/ISSUE_TEMPLATE/12-testing-coverage.md, 13-performance.md, 21-research.md, 22-audit.md, 24-ai-ops.md, and 25-content-modelling.md, or document that automation must synthesise the missing sections rather than claiming every template already provides them.

AGENTS.md reference: AGENTS.md:L120-L124

Useful? React with 👍 / 👎.

Comment thread AGENTS.md
$DOD"

# Validate
if ! echo "$BODY" | grep -q "Definition of Ready\|Definition of Done"; then

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Require both headings in the shell validation

If extraction or future template changes leave only one required section in BODY, this grep still succeeds because \| is alternation, and the script proceeds to gh issue create; .github/workflows/template-enforcement.yml tests DoR and DoD independently and will then flag the issue. Validate each heading separately so this advertised pre-posting check enforces the stated requirement that both are present.

AGENTS.md reference: AGENTS.md:L193-L199

Useful? React with 👍 / 👎.

@github-actions github-actions Bot added migrate:status:needs-review Awaiting code review migrate:type:documentation Documentation migrate:priority:normal Default priority migrate:area:documentation Docs & guides migrate:lang:md Markdown content/docs migrate:type:chore Chore / small hygiene change migrate:meta:needs-changelog Requires a changelog entry before merge labels Jul 22, 2026
@github-actions

Copy link
Copy Markdown
Contributor

Metadata governance

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

Labels

migrate:area:documentation Docs & guides migrate:lang:md Markdown content/docs migrate:meta:needs-changelog Requires a changelog entry before merge migrate:priority:normal Default priority migrate:status:needs-review Awaiting code review migrate:type:chore Chore / small hygiene change migrate:type:documentation Documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant