chore: install agent contract and chore workflows by norrietaylor · Pull Request #189 · gominimal/minimal

norrietaylor · 2026-05-07T03:27:07Z

This is a hand-off from gominimal/min-aw, not a self-merging change. Review the diff at your own pace; mark ready-for-review and merge when satisfied. The min-aw operator job ended at draft creation; they will not enable auto-merge on this PR. See docs/rollout/07-target-repo-rollout.md for the full hand-off contract and decisions/0001-not-gating.md for the no-mutation-of-branch-protection rule.

TL;DR

Markdown only. No source code, no CI mutation, no branch-protection mutation. Safe to merge as-is.
What runs after merge. A weekly sync workflow pulls chore workflows from gominimal/min-aw@v0.2.4. Chores file issues / open draft PRs against this repo on a fuzzy schedule. Caps: max 1 issue per chore per run; max 1 PR per chore per run; auto-merge opt-in per chore (only trivial-dep-bump enables it, and only for patch-level Cargo.lock changes).
You can opt out anytime. Disable a specific chore by deleting its .github/workflows/<chore>.lock.yml after sync, OR halt all chores by removing the sync workflow itself. No retaliatory state on the source-of-truth side.

What this PR installs (markdown-only)

AGENTS.md — agent context document for human + AI tooling
.github/copilot-instructions.md — Copilot instructions referencing gh-aw-fragments
.github/labels.yml — agent label set (agent:*, kind:*, priority:*)
.github/agents/ — agent definition directory
.github/ISSUE_TEMPLATE/ — issue templates (bug, feature, chore, feedback)
.github/workflows/sync-from-source-of-truth.yml — weekly sync workflow that pulls compiled .lock.yml files from min-aw

Source-of-truth pin: gominimal/min-aw@v0.2.4. The pin is either a release tag (vX.Y.Z) or a full 40-char commit SHA — both link via /tree/ so the link works regardless of which form was passed to quick-setup.sh.

What runs after merge

The sync workflow lands compiled chore .lock.yml files on a weekly schedule. Each chore is governed by its own caps and triggers; full details in workflows/ on min-aw. For minimal (LANGUAGE=Rust) per ADR 0003, the applicable chores include:

docs-patrol — files an issue when documentation drifts from the source code (1 issue/run, fuzzy weekly Monday).
worker-fix — picks up open agent:* issues and drafts a fix PR (1 PR/run, fuzzy daily). Bot-authored PRs auto-trigger CodeRabbit review.
worker-iterate — addresses CodeRabbit (and human) inline review-comment feedback on gominimal-aw-bot[bot]-authored [worker: ... PRs. Triggered per CodeRabbit review submission; pushes commits to the PR branch and replies inline. Caps: 3 comments/run, 5 runs/PR. (#83)
not-gating-audit — weekly audit that branch protection on main requires only your CI (no gh-aw checks added). Files an issue if drift is detected.
Rust-coupled chores (dependency-review, api-surface-drift, test-coverage-detector, trivial-dep-bump) — install only if LANGUAGE=rust today; per-language overlays for Go/Node/Nickel land in #69 phase 1.

What this does NOT do

Does not modify branch protection. Per ADR 0001, no gh-aw check is ever added to required_status_checks. Your CI remains the only gate. The not-gating-audit chore actively defends this; it files an issue if any gh-aw check appears in branch protection.
Does not modify your CI. No edits to existing workflow files; only adds the sync workflow.
Does not push commits to main. All chore output flows through the gh-aw safe-output gate (PRs and issues, never direct pushes).

Review checklist

Diff touches only AGENTS.md + .github/ markdown/yaml files; no source code touched
Token substitution looks correct (REPO_NAME=minimal, LANGUAGE=Rust)
AGENTS.md matches the active agent set for this repo
.github/workflows/sync-from-source-of-truth.yml pins to a release tag (not main)
No direct push to main was made (this is a PR)
Branch protection on main is unchanged (verify via gh api repos/gominimal/minimal/branches/main/protection)

Hand-off

This PR is opened as draft. The min-aw operator will not toggle ready-for-review or enable auto-merge. When you are satisfied:

Click "Ready for review."
Optionally request review from CODEOWNERS or your team.
Merge when CI is green and you are satisfied.

To push back or roll back, see the rollback procedure in docs/rollout/07-target-repo-rollout.md. Or comment on this PR — feedback shapes the next sync.

Summary by CodeRabbit

Release Notes

Documentation
- Added GitHub issue templates for standardized bug reporting, feature requests, chores, and feedback
- Added agent workflows documentation and guidelines
Chores
- Introduced standardized GitHub labels for issue triage and workflow organization
- Added automated workflows for repository synchronization and maintenance tasks

Installed by scripts/quick-setup.sh from gominimal/min-aw@v0.2.4.

coderabbitai · 2026-05-07T03:27:15Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: dd2b7e93-d4cc-4df2-8b7e-ca0906d8e46a

📥 Commits

Reviewing files that changed from the base of the PR and between fa6f5c3 and 9896f9c.

📒 Files selected for processing (3)

.github/ISSUE_TEMPLATE/chore.md
.github/labels.yml
.github/workflows/sync-from-source-of-truth.yml

✅ Files skipped from review due to trivial changes (2)

.github/ISSUE_TEMPLATE/chore.md
.github/labels.yml

🚧 Files skipped from review as they are similar to previous changes (1)

.github/workflows/sync-from-source-of-truth.yml

📝 Walkthrough

Walkthrough

This PR establishes a comprehensive agentic workflow infrastructure by adding GitHub issue templates (bug, feature, chore, feedback), defining labels and agent conventions, creating worker workflows that execute remote agents, configuring Copilot instructions, and documenting the agent contract via AGENTS.md.

Changes

Agentic Workflow Foundation

Layer / File(s)	Summary
Configuration & Conventions `.github/labels.yml`, `.github/copilot-instructions.md`, `.github/agents/README.md`	Defines agent and triage labels; documents Copilot expectations for fragment imports and agent behavior; provides guidance on adding new agent definitions.
Issue Templates `.github/ISSUE_TEMPLATE/bug.md`, `.github/ISSUE_TEMPLATE/chore.md`, `.github/ISSUE_TEMPLATE/feature.md`, `.github/ISSUE_TEMPLATE/feedback.md`	Adds four issue templates with YAML front-matter (labels, assignees, title) and structured markdown sections for users to report bugs, propose features, file chores, and submit feedback.
Workflow Infrastructure `.github/workflows/sync-from-source-of-truth.yml`, `.github/workflows/worker-fix.yml`, `.github/workflows/worker-iterate.yml`	Sync workflow updates default `source_ref` to `v0.2.5`; worker-fix and worker-iterate workflows implement preflight checks, GitHub App token minting, source ref validation (full SHA matching), remote worker fetching, and conditional execution via `gh aw run`.
Agent Contract Documentation `AGENTS.md`	Defines the minimal agent contract, enumerates active chore workflows and their triggers/labels, specifies per-language applicability, documents universal chore constraints (not-gating, no direct `main` push), label taxonomy, and prompt fragment compilation workflow.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related issues

gominimal/inbox#70: The changes directly implement pieces of the Agentic Workflows system by adding agent labels, worker/chore workflows, and documentation of the agent contract.

Possibly related PRs

gominimal/min-aw#91: Both add and modify the worker-iterate workflow (caller wrapper, workflow config, docs).
gominimal/min-aw#1: Both introduce the same repository scaffold including ISSUE_TEMPLATE files, AGENTS.md, GitHub workflows, labels, and agent fragment documentation.
gominimal/inbox#109: Both modify .github/workflows/sync-from-source-of-truth.yml to bump workflow_dispatch.inputs.source_ref.default from v0.2.4 to v0.2.5.

Poem

🐰 A warren of workflows now takes its form,
With agents and labels in neat uniform,
Templates for chores, bugs, and feedback galore,
The minimal sync opens automation's door!
Hop skip and jump to agentic delight! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: installing agent contract documentation and chore workflows infrastructure.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch chore/install-agent-contract

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.github/ISSUE_TEMPLATE/chore.md:
- Around line 29-37: Update the "Agent Label (if applicable)" list to include
the two missing labels by adding `agent:api-drift` and `agent:not-gating-audit`
alongside the existing `agent:doc-drift`, `agent:coverage`, and
`agent:dep-drift` entries; ensure the list under that header (and any mention
that points readers to `AGENTS.md`) remains consistent with the AGENTS.md
taxonomy so the template and docs match.

In @.github/labels.yml:
- Around line 6-25: The file is missing two required agent labels; add entries
for name: "agent:api-drift" and name: "agent:not-gating-audit" mirroring the
existing label format (include a hex color and a short description each) so they
appear alongside the other agent:* labels (e.g., like "agent:doc-drift" and
"agent:coverage"); ensure the descriptions state they are opened/updated by the
api-drift agent and the not-gating-audit agent respectively and follow the same
YAML structure as the other label entries.

In @.github/workflows/sync-from-source-of-truth.yml:
- Around line 86-90: The workflow's SOURCE_REF validation rejects the current
default 'v0.2.4', so either make the default a distinct placeholder token (e.g.,
set SOURCE_REF to "__SOURCE_REF__" in the template and have quick-setup.sh
replace that with "v0.2.4") or delete/disable the validation block that checks
for the unsubstituted "v0.2.4"; locate the variable SOURCE_REF and the
validation if-block that compares it to "v0.2.4" and implement one of these two
fixes, updating quick-setup.sh substitution logic if you choose the placeholder
approach.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 166e28fc-96a6-409e-a618-ff57d1ea7e40

📥 Commits

Reviewing files that changed from the base of the PR and between 3949779 and fa6f5c3.

📒 Files selected for processing (12)

.github/ISSUE_TEMPLATE/bug.md
.github/ISSUE_TEMPLATE/chore.md
.github/ISSUE_TEMPLATE/feature.md
.github/ISSUE_TEMPLATE/feedback.md
.github/agents/.gitkeep
.github/agents/README.md
.github/copilot-instructions.md
.github/labels.yml
.github/workflows/sync-from-source-of-truth.yml
.github/workflows/worker-fix.yml
.github/workflows/worker-iterate.yml
AGENTS.md

Pulls in the three CodeRabbit-flagged template fixes: 1. sync-from-source-of-truth.yml: drops the unsubstituted-token guard that had become a self-rejecting tautology after sed substituted {{SOURCE_REF}} -> v0.2.4 globally. The regex check already rejects the unsubstituted form. Source_ref default bumped v0.2.4 -> v0.2.5. 2. labels.yml: adds agent:api-drift and agent:not-gating-audit (were referenced in chore.md / agent-taxonomy comment but never defined). 3. chore.md: adds the same two labels to the agent-label enumeration. Source-of-truth pin: gominimal/min-aw@v0.2.5 (https://github.com/gominimal/min-aw/releases/tag/v0.2.5) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

coderabbitai · 2026-05-07T17:42:09Z

Caution

Failed to replace (edit) comment. This is likely due to insufficient permissions or the comment being deleted.

Error details

{}

chore: install agent contract and chore workflows

fa6f5c3

Installed by scripts/quick-setup.sh from gominimal/min-aw@v0.2.4.

coderabbitai Bot reviewed May 7, 2026

View reviewed changes

Comment thread .github/ISSUE_TEMPLATE/chore.md Resolved

Comment thread .github/labels.yml Resolved

Comment thread .github/workflows/sync-from-source-of-truth.yml Resolved

norrietaylor marked this pull request as ready for review May 7, 2026 04:49

twitchyliquid64 approved these changes May 7, 2026

View reviewed changes

norrietaylor merged commit 6f9be0a into main May 7, 2026
15 checks passed

norrietaylor deleted the chore/install-agent-contract branch May 7, 2026 20:58

norrietaylor mentioned this pull request May 7, 2026

chore(sync): patch in git-author config + bump pin v0.2.5 -> v0.3.1 #197

Closed

coderabbitai Bot mentioned this pull request May 14, 2026

chore: strip pre-gh-aw-add install artifacts ahead of re-bootstrap #209

Merged

Navigation Menu

Repository navigation

chore: install agent contract and chore workflows - #189

chore: install agent contract and chore workflows#189
norrietaylor merged 2 commits into
mainfrom
chore/install-agent-contract

norrietaylor commented May 7, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented May 7, 2026 •

edited

Loading

Walkthrough

Changes

Estimated code review effort

Possibly related issues

Possibly related PRs

Poem

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

coderabbitai Bot commented May 7, 2026

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

norrietaylor commented May 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

TL;DR

What this PR installs (markdown-only)

What runs after merge

What this does NOT do

Review checklist

Hand-off

Summary by CodeRabbit

Release Notes

Uh oh!

coderabbitai Bot commented May 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Possibly related issues

Possibly related PRs

Poem

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

coderabbitai Bot commented May 7, 2026

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

norrietaylor commented May 7, 2026 •

edited

Loading

coderabbitai Bot commented May 7, 2026 •

edited

Loading