jmagly/aiwg-pr

Opening AIWG Pull Requests

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

Routing Boundary

Use this skill only when the user is doing AIWG-specific delivery: AIWG repository work, an AIWG release/change PR, or any task that explicitly asks for AIWG delivery policy. Do not use aiwg-pr for ordinary repository pull request work. Generic requests like "open a PR for this repo", "create a pull request", or "review this PR" should use the host repository's normal git/Gitea/GitHub PR tools and templates unless the user names AIWG delivery.

Compatibility: aiwg-pr remains the stable kernel skill name. aiwg-delivery-pr is the explicit alias for agents that need a less ambiguous discoverable capability name.

When this fires

Natural-language triggers:

• "Open an AIWG PR"
• "Prepare the AIWG delivery PR"
• "Should this AIWG change commit directly or open a PR?"
• "What goes in the AIWG PR description?"
• "How do I close an AIWG 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)