aiwg-pr

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

# 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 |

```bash
# 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)

```bash
# 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

```bash
# 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:

```bash
# 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)