From 6557401df28cb9b67750be4bd48a49277cc72e47 Mon Sep 17 00:00:00 2001 From: Chris Grady <17553614+cgfixit@users.noreply.github.com> Date: Wed, 5 Aug 2026 21:37:57 +0000 Subject: [PATCH 1/2] docs(pr-template): make branch naming agent-operable; drop casual top note --- .github/PULL_REQUEST_TEMPLATE.md | 41 ++++++++++++++++++++------------ 1 file changed, 26 insertions(+), 15 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 4929bd2a..51800776 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,13 +1,23 @@ -## Note: when initiated pr draft from grok build, kimi/kimi code, or codex use preferred branch naming conventions: -> claude code: claude/{feature} -> -> codex: codex/{feature} -> -> grok build: grok/{feature} -> -> kimi or kimi code: kimi/{feature} -> -> CyClaw (directly or via mcp connector ): CyClaw/{feature}-{date} +## Branch naming (required for agent-opened PRs) + +Before opening a PR, create the head branch with the **driver-matched** prefix. +Hooks and `utils/agent_identity.py` enforce this allowlist; casual / generic names are not a substitute. + +| Driver | Branch pattern | Example | +|--------|----------------|---------| +| Claude Code | `claude/` | `claude/telegram-media-audit` | +| Codex | `codex/` | `codex/verify-dep-guard` | +| Grok Build | `grok/` | `grok/pr-template-branch-rules` | +| Kimi / Kimi Code | `kimi/` | `kimi/docs-sync` | +| CyClaw direct / MCP | `CyClaw/-` or `cyclaw/` | `CyClaw/harness-timeout-20260805` | + +Rules for agents: +1. Pick the prefix that matches **the tool that is creating the branch**, not a generic label. +2. Do **not** default to `agent/` when the driver is known (Claude → `claude/`, Grok → `grok/`, etc.). +3. `` must be short, kebab-case, and describe the change (no spaces, no leading `-`). +4. If the branch name is wrong, rename **before** push: `git branch -m /`. + +Also allowed by hooks (non-feature): `main`, `dependabot/*`, `renovate/*`, `release/*`, `hotfix/*`. ## Title **Use this format:** @@ -82,7 +92,7 @@ If this is a relatively large, complex, or core-path change, kick off the discus - Explicit before/after invariant matrix - Sandbox validation diff or key evidence - Any compensating controls or observability added -- a mature technical and eli5 version description of whats changed and whats at risk and where to monitor +- A technical summary plus a plain-language (ELI5) summary of what changed, what is at risk, and where to monitor **Examples of what good "Further comments" look like for core changes:** - "No change to graph topology or entry points. RAG-first and audit convergence remain enforced by edges only." @@ -91,8 +101,9 @@ If this is a relatively large, complex, or core-path change, kick off the discus --- -**Notes for contributors (especially solo maintainer PRs):** +**Notes for contributors (including solo maintainer / multi-agent PRs):** - Core invariant or governance changes require the strongest evidence. -- Out-of-band layers (agentic/, sync/, .claude/) can use a lighter path but still need Benefits + Risks + relevant checklist items. -- Docs-only or audit PRs can skip some technical items but must still complete Benefits / Risks. -- The goal is production-grade discipline without unnecessary ceremony. Brutal honesty on impact is expected and appreciated. +- Out-of-band layers (`agentic/`, `sync/`, harness, `.claude/`) may use a lighter checklist, but still need Benefits + Risks + the relevant items. +- Docs-only or audit PRs may skip some technical checklist rows; Benefits and Risks remain required. +- Prefer squash-and-merge. The final squashed commit message is the permanent record; keep intermediate agent WIP out of `main`. +- Be blunt about impact: if invariants, offline posture, or audit behavior are affected, say so explicitly. From 8c80d65a620e5b128238268aaef2984fc72f4104 Mon Sep 17 00:00:00 2001 From: Chris Grady <17553614+cgfixit@users.noreply.github.com> Date: Wed, 5 Aug 2026 19:21:20 -0400 Subject: [PATCH 2/2] Update PULL_REQUEST_TEMPLATE.md --- .github/PULL_REQUEST_TEMPLATE.md | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 51800776..8b9bc631 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -10,6 +10,7 @@ Hooks and `utils/agent_identity.py` enforce this allowlist; casual / generic nam | Grok Build | `grok/` | `grok/pr-template-branch-rules` | | Kimi / Kimi Code | `kimi/` | `kimi/docs-sync` | | CyClaw direct / MCP | `CyClaw/-` or `cyclaw/` | `CyClaw/harness-timeout-20260805` | +| Unknown / harness default | `agent/` | `agent/harness-browser-parity` | Rules for agents: 1. Pick the prefix that matches **the tool that is creating the branch**, not a generic label.