Filing Pull Requests

Filing Pull Requests

Related: filing issues, versioning, kernel skill `aiwg-pr` (run `aiwg show skill aiwg-pr`)

A high-quality PR is focused, verified, policy-compliant, and reaches `main` with green CI. This guide covers the AIWG-specific delivery rules — branching strategy, the no-attribution rule, the CI-green-before-done discipline, and the release-time obligations.

Pre-flight: delivery policy

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

aiwg config get --project delivery.mode
# or
cat .aiwg/aiwg.config | jq -r '.delivery.mode'
ModeBranchPRClosing
`direct`No — commit straight to `default_branch`No PR`Closes #N` in commit message
`feature-branch`Branch per issueNo PR`Closes #N` in commit on the branch
`pr-required`Branch per issueRequired`Closes #N` in PR body

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

The AIWG repo runs in `direct` mode — the May-2026 fix sweep (commits `6500e167`, `497fcca7`, `3f2b557b`, `d052aa2f`, `a50c1d76`, `ac61a2b8`) landed straight to `main` with `Closes #N` per commit.

The walkthrough

1. Find or file the issue first

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

  • Search for existing matches: `aiwg run skill steward-prep-delivery -- "<topic>"`
  • If none match, file via filing issues before drafting the PR

2. Branch (only for non-direct modes)

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

For `direct` mode, skip this step.

3. Make the change

Stay focused on the linked issue. Anti-patterns to avoid:

  • "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 — note why in the PR body.

4. Verification (REQUIRED before commit)

CheckCommandPass 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 CI-failure-then-fix cycle in `497fcca7` → `3f2b557b` was caused by skipping the local test run before push. Two pushes, one wasted CI cycle, easily prevented.

5. Commit message

Use conventional commits: `type(scope): subject`

fix(area): one-line subject

Body explains 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.

Verification:
- npx tsc --noEmit clean
- npm test — 6306 pass, 1 pre-existing flake (cli-perf cold-start)
- Manual: <smoke-test description>

Closes #N

Conventional commit types: `feat`, `fix`, `chore`, `docs`, `refactor`, `test`, `perf`, `ci`, `build`. Scope is the area (e.g., `steward`, `sdlc,release`, `cli,docs`).

6. No AI attribution

The project no-attribution rule is universal across platforms. The commit/tag/PR body 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.

7. Push

# For direct mode
git push origin main

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

8. 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 — one paragraph: what changed and why
  • Linked issues — `Closes #N` / `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.

9. CI green before done

A commit isn't done until CI is green. After push, wait for the run on `origin` (Gitea). AIWG CI takes ~2 minutes.

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.

10. 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 (see filing issues § import flow)
  • Update `CHANGELOG.md` if the change is user-visible — for releases, the `flow-release` skill handles this; for individual PRs that ship before the release, append to the unreleased section

Release-time PRs

When the PR is part of a release sequence, the `flow-release` skill handles the orchestration. The PR itself follows the same rules as any other PR, but the release flow adds extra gates:

  • Version bump (`package.json` + `CHANGELOG.md` + `docs/releases/v{version}-announcement.md`)
  • UAT for stable channel: `npm run uat` — all 9 tests must pass
  • Tag creation, push to origin, optional GitHub mirror push
  • npm dist-tag promotion

See `flow-release` for the full sequence. The `.aiwg/release.config` declares which gates apply.

Anti-patterns to avoid

  • 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.).

Quick reference

Need toRun
Check delivery mode`aiwg config get --project delivery.mode`
Verify locally before push`npx tsc --noEmit && npm test && npm run build:cli`
Run UAT (release prep)`npm run uat`
Fetch full PR guide`aiwg show skill aiwg-pr`
Drive a release`aiwg show skill flow-release`