aiwg-pr

name	aiwg-pr
description	Guide for opening high-quality pull requests — template, verification gates, delivery-policy compliance, no-attribution rule, and CI-green-before-done discipline
platforms	["codex"]

Opening AIWG Pull Requests

You are helping a user (or yourself, as an autonomous agent) open a high-quality pull request. The bar is set by the project's delivery-policy and no-attribution rules.

When this fires

Natural-language triggers:

• "I want to open a PR"
• "How do I submit a fix?"
• "Help me write up a pull request"
• "Should I commit directly or open a PR?"
• "What goes in the PR description?"
• "How do I close an issue with a PR?"

Critical pre-flight: delivery policy

Before you create a branch or open a PR, read .aiwg/aiwg.config delivery.mode. Three modes, three workflows:

Mode	Branch	PR	Closing
direct	No — commit straight to default_branch	No PR	Closes #N in commit message
feature-branch	Branch per issue	No PR	Closes #N in commit on the branch
pr-required	Branch per issue	Required	Closes #N in PR body

# Check the configured mode
aiwg config get --project delivery.mode
# or
cat .aiwg/aiwg.config | jq -r '.delivery.mode'

If mode: direct, don't open a PR. Commit directly to main with Closes #N in the message. The delivery-policy rule (kernel rule, always loaded) is authoritative.

The walkthrough

1. Find or file the issue first

Every PR closes (or refs) an issue. If you don't have one:

• Run aiwg run skill steward-prep-delivery -- "<your topic>" to check for existing issues
• If none match, file via aiwg-issue (the companion kernel skill) before drafting the PR

2. Branch (only for non-direct modes)

# feature-branch or pr-required
git checkout -b fix/{issue-number}-{slug}
# slug: short, lowercase, hyphenated derivation of the issue title

For direct mode, skip this step. Work on main.

3. Make the change

Apply the fix or feature. Stay focused on the linked issue. Anti-patterns:

• "While I'm at it" — adding unrelated changes. Split into separate PRs / commits.
• Reformatting unrelated files mid-PR. Send formatting as its own PR.
• Adding new dependencies without justification in the PR body.

4. Verification (REQUIRED before commit)

Check	Command	Pass criterion
Typecheck	npx tsc --noEmit	Clean (no output)
Tests	npm test	All pass (or only pre-existing flaky perf tests fail; document the latter)
Lint	npm exec markdownlint-cli2 (for docs)	Clean
Build	npm run build:cli	Succeeds (catches dist/ vs src/ path drift)

Don't skip these. The recent CI-failure-then-fix cycle in 497fcca7 → 3f2b557b was caused by skipping the local test run before push.

5. Commit message

Use conventional commits: type(scope): subject

Body should explain why, not just what — the diff already shows what. Reference the linked issue. For direct mode, include Closes #N so the issue auto-closes on push.

No AI attribution. Rule is universal across platforms. The commit message must not contain:

• Co-Authored-By: Claude <…> (or any AI tool)
• Generated with [Claude Code] / "Generated by Codex" / "Written by GitHub Copilot"
• 🤖 emoji or any tool branding

The AI is a tool. Tools don't sign their output.

Example commit (per the recent #1261/#1262/#1263 fix):

fix(steward,deploy): repair capability matrix loader, schema, and Claude command stubs

Three stacked bugs from the hermes-agent tester report (jmagly#108–#112,
roctinam #1264–#1268) plus filing infrastructure (#1269).

[multi-paragraph why explaining each bug...]

Verification:
- npx tsc --noEmit clean
- npm test — 6306 pass, 1 pre-existing flaky perf test
- Manual: aiwg steward capabilities --provider claude-code now works

Closes #1261
Closes #1262
Closes #1263

6. Push

# For direct mode
git push origin main

# For feature-branch / pr-required
git push origin fix/{issue-number}-{slug}

7. Open the PR (only for pr-required mode)

Use the template at .gitea/pull_request_template.md (or .github/pull_request_template.md). Required sections:

• Summary: what changed and why (one paragraph)
• Linked issues: Closes #N (or Refs #N)
• Changes: bullets of meaningful changes (not file count)
• Verification: filled-in checklist showing typecheck/test/CI status
• Risk and rollback: even if "low / git revert"
• Policy reminders: delivery mode + no-attribution + CI-green-before-done

The body should be agent-readable: clear sections, specific paths, no marketing speak.

8. CI green before done

A commit isn't done until CI is green. After push:

# Check the latest run on origin
aiwg run skill aiwg-pr -- check-ci
# (or manually inspect the tracker)

AIWG CI runs ~2 minutes. Wait for it. If it fails:

1. Diagnose the failure
2. Fix the underlying issue (no || true, no continue-on-error: true, no test deletion — see anti-laziness and dev-pipeline-safety rules)
3. Commit the fix and wait again
4. Don't declare the work done until green

Never leave main in a red state.

9. After merge (pr-required) or push (direct)

• The linked issue auto-closes via Closes #N
• If you imported a cross-tracker report, thank the original reporter in a closing comment on the source tracker (the recent jmagly→roctinam imports did this for sebuh-infsol on each of #108–#112)
• Update CHANGELOG.md if user-visible (per the release checklist in CLAUDE.md)

Anti-patterns to flag

• AI attribution lines — never. Universal rule.
• --no-verify or --no-gpg-sign — never bypass hooks. Fix the underlying issue.
• continue-on-error: true on tests — never silence the smoke detector. See dev-pipeline-safety.
• Skipping CI green wait — if CI fails, fix it before declaring done.
• Bundling unrelated changes — split into focused PRs.
• Workarounds instead of root-cause fixes — see anti-laziness Rule 9: "real fix over workaround."
• Closes #N in a PR body for direct mode — wrong; use the commit message instead.

When stuck

If the verification gates fail and you can't fix them in 3 attempts, escalate per the anti-laziness recovery protocol. Don't take destructive shortcuts (skip tests, weaken assertions, etc.).

Related

• Skills: aiwg-issue (filing issues), steward-prep-delivery (interactive walkthrough), issue-create (low-level filing), issue-auto-sync (commit↔issue linking), address-issues (issue-driven loops)
• Templates: .gitea/pull_request_template.md, .github/pull_request_template.md
• Docs: CONTRIBUTING.md (full contributor guide)
• Rules: delivery-policy (kernel), no-attribution (kernel), anti-laziness, dev-pipeline-safety, ci-green-before-done
• Origin: #1269 (templates), #1264–#1268 (tester report sweep that motivated this)