Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
185 changes: 185 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,191 @@ See [docs/BRANCHING_STRATEGY.md](docs/BRANCHING_STRATEGY.md) and [CLAUDE.md](CLA

---

## GitHub Template Governance

All AI agents **must** enforce template compliance when creating pull requests and issues. This section provides programmatic guidance.

### Pull Request Templates (Preventative Enforcement)

PR template enforcement is **preventative**—the workflow blocks merges that don't include required sections:

**When creating PRs via `gh pr create`:**

1. Determine the PR type from the branch prefix (`fix/`, `feat/`, `docs/`, etc.)
2. Read the corresponding template from `.github/PULL_REQUEST_TEMPLATE/pr_*.md`
3. Include required sections in the PR body:
- **Linked issues** — use `Fixes #123` or `Relates to #456`
- **Changelog** — add entries under `### Fixed`, `### Added`, `### Changed`, `### Removed`
- **Checklist** — mark items as `[x]` (completed) or `[ ]` (incomplete)
4. The workflow `validate-pr-template.yml` will validate and block merge if sections are missing

**Template locations:**

```
.github/PULL_REQUEST_TEMPLATE/
├── pr_feature.md ← feat/, design/, a11y/, ux/, i18n/, perf/, research/
├── pr_bug.md ← fix/, security/
├── pr_hotfix.md ← hotfix/
├── pr_refactor.md ← refactor/
├── pr_chore.md ← chore/, test/, ops/, config/, migrate/, qa/, uat/
├── pr_ci.md ← ci/, build/
├── pr_dep_update.md ← deps/
├── pr_docs.md ← docs/, content/, seo/
├── pr_release.md ← release/
└── config.yml ← routing rules
```

### Issue Templates (Reactive Enforcement)

Issue template enforcement is **reactive**—the workflow validates after creation and flags non-compliant issues with `status:needs-more-info`.

**When creating issues via `gh issue create`:**

1. **Determine the issue type** based on the problem:
- `bug.md` — reproducible defects, errors, crashes
- `code-refactor.md` — code cleanup, simplification (not user-facing)
- `feature.md` — new capabilities or user-visible enhancements
- `design.md` — UI/UX, token, or accessibility design
- `epic.md` — large, multi-part initiatives
- `story.md` — user-centric narratives with acceptance criteria
- `improvement.md` — enhancements to existing functionality
- `task.md` — scoped work, config updates, small delivery items
- `chore.md` — small housekeeping (label hygiene, repo tweaks)
- `testing-coverage.md` — new or refactored automated tests
- `performance.md` — speed, resource, or latency work
- `a11y.md` — accessibility compliance (WCAG 2.2 AA)
- `security.md` — vulnerabilities or hardening
- `compatibility.md` — cross-version, browser, or platform issues
- Other types: `build-ci.md`, `automation.md`, `integration-issue.md`, `release.md`, `maintenance.md`, `documentation.md`, `research.md`, `audit.md`, `code-review.md`, `ai-ops.md`, `content-modelling.md`

2. **Read the template file** from `.github/ISSUE_TEMPLATE/{NN}-{type}.md`

3. **Extract required sections** from the template:
- All issue templates require:
- `## Definition of Ready (DoR)` — pre-work checklist
- `## Definition of Done (DoD)` — completion checklist
Comment on lines +121 to +123

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 👍 / 👎.

- Template-specific sections (e.g., "Describe the bug", "Reproduction", "Expected behavior")

4. **Build the issue body** by:
- Including all template sections
- Marking appropriate checklist items as `[x]` (completed)
- Filling in content for each section
- Removing placeholder text

5. **Validate before posting:**

```javascript
function validateIssueBody(body) {
const required = [
'Definition of Ready (DoR)',
'Definition of Done (DoD)'
];
return required.every(section =>
body.includes(`## ${section}`)
);
}

if (!validateIssueBody(body)) {
throw new Error('Missing required template sections: DoR and/or DoD');
}
```

6. **Create the issue** with the validated body:

```bash
gh issue create --title "Title" --body "$body"
```

7. **The workflow `template-enforcement.yml` will validate:**
- If compliant: Issue progresses normally
- If non-compliant: Gets flagged with `status:needs-more-info` label
- AI-created issues: Specific automation feedback is added

**Template directory structure:**

```
.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 👍 / 👎.

├── 02-code-refactor.md
├── 03-feature.md
├── 04-design.md
├── 05-epic.md
├── 06-story.md
├── 07-improvement.md
├── 08-task.md
├── 09-chore.md
├── 10-testing-coverage.md
├── 11-performance.md
├── 12-a11y.md
├── 13-security.md
├── 14-compatibility.md
├── 15-build-ci.md
├── 16-automation.md
├── 17-integration-issue.md
├── 18-release.md
├── 19-maintenance.md
├── 20-documentation.md
├── 21-research.md
├── 22-audit.md
├── 23-code-review.md
├── 24-ai-ops.md
├── 25-content-modelling.md
└── config.yml
```

**Key Enforcement Rules:**

- ✅ Both DoR and DoD sections **must** be present in the body
- ✅ Sections must be visible text (not in HTML comments)
- ✅ Follow the template structure from the issue template file
- ✅ Validate before creation to avoid reactive flagging
- ✅ If flagged with `status:needs-more-info`, update the issue with proper sections

**Example: Creating a bug issue programmatically**

```bash
#!/bin/bash

# Read template
TEMPLATE=$(cat .github/ISSUE_TEMPLATE/01-bug.md)

# Extract DoR and DoD sections
DOR=$(echo "$TEMPLATE" | sed -n '/## Definition of Ready/,/## Definition of Done/p' | head -n -1)
DOD=$(echo "$TEMPLATE" | sed -n '/## Definition of Done/,$p')

# Build issue body with content
BODY="## Describe the bug
The bug description here.

## To Reproduce
1. Step one
2. Step two
3. See error

## Expected behavior
What should happen instead.

## Additional Context
Any other info.

---

$DOR

$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 👍 / 👎.

echo "ERROR: Missing required template sections"
exit 1
fi

# Create issue
gh issue create --title "Bug title" --body "$BODY"
```

---

## Contribution Guidelines & Indexes

| Area | File Reference | Notes / Usage |
Expand Down
32 changes: 32 additions & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -203,6 +203,38 @@ For issue intake, use [.github/ISSUE_TEMPLATE/config.yml](./.github/ISSUE_TEMPLA
- `code-review` for code quality discussions and review standards.
- `ai-ops` and `content-modelling` for specialist AI and content workflows.

### Issue Template Quick Reference

When creating issues programmatically, use the correct template based on issue type. **All issue templates require two mandatory sections:**

- `## Definition of Ready (DoR)` — pre-work checklist
- `## Definition of Done (DoD)` — completion checklist

Templates located in `.github/ISSUE_TEMPLATE/`:

| Issue Type | Template File | Use When |
| --- | --- | --- |
| Bug | `01-bug.md` | Reproducible defect, error, or crash |
| Code Refactor | `02-code-refactor.md` | Code cleanup or simplification (non-user-facing) |
| Feature | `03-feature.md` | New capability or user-visible enhancement |
| Design | `04-design.md` | UI/UX, token, or accessibility design work |
| Epic | `05-epic.md` | Large, multi-part initiative grouping stories |
| Story | `06-story.md` | User-centric narrative with acceptance criteria |
| Improvement | `07-improvement.md` | Enhancement to existing functionality |
| Task | `08-task.md` | Scoped work, config updates, small delivery |
| Chore | `09-chore.md` | Small housekeeping (labels, repo tweaks) |
| Testing | `10-testing-coverage.md` | New or refactored automated tests |
| Performance | `11-performance.md` | Speed, resource, or latency work |
| Accessibility | `12-a11y.md` | WCAG 2.2 AA compliance improvements |
| Security | `13-security.md` | Vulnerabilities or hardening |
| Compatibility | `14-compatibility.md` | Cross-version, browser, or platform issues |

**Template enforcement workflow:** `.github/workflows/template-enforcement.yml`

- Validates all issues have DoR and DoD sections
- Flags non-compliant issues with `status:needs-more-info` label
- See [AGENTS.md](./AGENTS.md) for programmatic issue creation guidance

### Before Every Push

1. Verify the current branch: `git branch -v`
Expand Down
Loading