Ocap-kernel pr

When asked to create a pull request, follow these steps:

Phase 1: Pre-flight checks

1. Run

   git status

   . If any of the following conditions apply, stop and report the errors:
   • There are unstaged changes
   • There are untracked files
   • The current branch is the default branch (

     main

     )

2. Check if this is a stacked PR:

   • Run

     git merge-base main HEAD

     to find the common ancestor with main
   • Run

     git log --oneline <merge-base>..HEAD

     to see commits since diverging from main
   • Check if any parent commits are on another feature branch (not main)
   • If so, run

     gh pr list --head <parent-branch>

     to check if that branch has an open PR
   • If a parent branch has an open PR, this is a stacked PR

3. Run

   git log main..HEAD --oneline

   to see the commit history.

4. Get the diff for the review:

   • If this is a stacked PR, run

     git diff <parent-branch>...HEAD

     to scope the diff to only this branch's changes.
   • Otherwise, run

     git diff main...HEAD

     .

Phase 2: Automated PR review (parallel subagents)

MANDATORY — DO NOT SKIP. This phase must run before any PR is created, regardless of how "simple", "mechanical", or "well-tested" the changes appear. Subtle bugs (e.g., semantic mismatches in API migrations) hide in exactly the changes that seem safe to skip. The only exception is docs-only changes as described below.

Before creating the PR, analyze the diff to decide which review subagents to launch. Not every PR needs every reviewer.

Triage: classify the change

Categorize each changed file, then pick subagents based on which categories are present. A file belongs to exactly one category — evaluate in this order (first match wins):

1. docs:

   .md

   ,

   .txt

   ,

   CHANGELOG

   ,

   LICENSE

   ,

   docs/

   ,

   .claude/

2. ci:

   .github/workflows/

   ,

   .github/actions/

   — these often contain shell scripts with non-trivial logic
3. config:

   .json

   (not

   package.json

   ),

   .yml

   ,

   .yaml

   ,

   .eslintrc*

   ,

   .prettierrc*

   ,

   tsconfig*

   ,

   Dockerfile

   ,

   .editorconfig

   ,

   .gitignore

   ,

   .gitattributes

   ,

   .nvmrc

   ,

   .yarnrc*

4. test: files matching

   *.test.ts

   ,

   *.spec.ts

   , or under

   test/

   directories
5. code: everything else (

   .ts

   ,

   .js

   ,

   .mjs

   ,

   .cjs

   ,

   package.json

   , etc.)

Then decide which subagents to launch:

• If only docs files changed: skip the entire review phase and go straight to Phase 3.
• Otherwise, select subagents based on which categories are present:
  • ci present → launch Subagent 1 (Correctness) (review shell logic, conditional expressions, job dependency chains)
  • config or test present → launch Subagent 2 (Style)
  • test present → also launch Subagent 4 (Tests)
  • code present → launch Subagent 1 (Correctness) and Subagent 2 (Style)
  • code present → also launch Subagent 4 (Tests)
  • code present and diff touches security-sensitive areas (network/HTTP, user input, auth, crypto,

    eval

    /

    Function

    , capability passing,

    harden()

    /SES) → also launch Subagent 3 (Security)

Subagent 1: Correctness & Logic

Prompt the agent to:

• Review the diff for logical errors, off-by-one mistakes, race conditions, and incorrect assumptions
• Check that error handling is adequate at system boundaries
• Verify that new code paths are reachable and dead code hasn't been introduced
• Flag any behavior changes that aren't covered by tests

Subagent 2: Style & Conventions

Prompt the agent to:

• Check adherence to the project's CLAUDE.md conventions (TypeScript types over interfaces, no

  any

  , no

  enum

  , kebab-case files,

  @metamask/superstruct

  for runtime types, options bags for 3+ args,

  harden()

  usage, etc.)
• Check test conventions (no "should",

  toStrictEqual

  for full objects,

  it.each

  for parameterized tests, concise verb-form titles)
• Flag unnecessary complexity, over-engineering, or missing

  harden()

  calls

Subagent 3: Security & Performance

Prompt the agent to:

• Look for OWASP top-10 vulnerabilities (injection, XSS, etc.)
• Check for capability leaks in the ocap model (unhardened objects, leaked references)
• Identify performance issues (unnecessary allocations in hot paths, missing early returns, O(n^2) patterns)
• Verify that lockdown/SES compatibility isn't broken (no ambient authority, no forbidden globals)

Subagent 4: Test Coverage

Prompt the agent to:

• Identify new or changed logic that lacks corresponding test coverage
• Check that edge cases and error paths are tested
• Verify tests are co-located correctly per project conventions
• Flag any test anti-patterns (global state, missing cleanup, overly broad mocks)

Phase 3: Review summary

If the review phase was skipped (docs-only), proceed directly to Phase 4.

Otherwise, after all launched subagents complete:

1. Compile findings into a Review Summary with sections for each subagent that ran.
2. Classify each finding as one of:
   • blocker - Must fix before merging
   • suggestion - Should consider fixing
   • nit - Minor, optional improvement
3. If there are blockers, present them to the user and ask whether to:
   • Fix the blockers automatically, then re-review
   • Proceed with PR creation anyway
   • Abort
4. If there are no blockers, briefly summarize the findings and proceed.

Phase 4: Create the PR

1. Run

   gh pr create

   to create a pull request. The PR body should include:
   • A brief narrative description of the PR
   • A summary of the changes (bullet points)
   • A brief description of how the code is tested (narrative, not a checklist)

   If this is a stacked PR, add

   --draft

   to create it as a draft PR.

2. Note the PR number from the created PR URL — it is needed for changelog entries. Proceed to Phase 5 before presenting results to the user.

Phase 5: Update changelogs

MANDATORY — DO NOT SKIP. Analyze the diff and determine whether any changes are consumer-facing (i.e., affect the behavior or API of a published or private package).

• If there are NO consumer-facing changes (e.g., docs-only, CI, tooling, skill definitions, dev scripts): add the

  no-changelog

  label to the PR via

  gh pr edit <number> --add-label no-changelog

  and skip the rest of this phase.
• If there ARE consumer-facing changes: update changelogs as described below.

Read the instructions in

docs/contributing/updating-changelogs.md

and follow them to the letter. In particular:

• Think from the consumer's perspective. A changelog is not a git history. For each affected package, ask: "What changed for someone who depends on this package?" Describe changes in natural language; do not simply reuse commit messages.
• Combine like changes. If multiple commits contribute to a single logical change within one package, write one changelog entry — not one per commit.
• Split disparate changes. If one commit touches unrelated concerns in a single package, write separate entries.
• Link the PR. Use the PR number from Phase 4 in each entry (e.g.

  ([#123](https://github.com/.../pull/123))

  ).

Commit the changelog updates to the current branch with the message "docs: Update changelogs" and push.

Done

Present the PR URL and any relevant information to the user. If a review was performed, include the review summary.