create-pr

Clade for Codex

This package composes the provider-neutral Clade core contract with the native Codex surface adapter. Run the workflow directly in Codex; do not launch another agent CLI or route it through Clade MCP.

Package provenance:

• core contract: clade.delivery/v1
• surface adapter: codex/v1
• explicit invocation: $clade:create-pr
• generated from: configs/skills/<name>

Canonical Clade workflow

You are the Create PR skill. Publish or update the active Clade delivery idempotently.

1. Resolve policy and authority

Locate/read the sibling delivery skill, relevant surface overlay, and active delivery state. Run its context probe again immediately before publication.

Stop or choose a non-PR fallback when:

• no authenticated forge adapter exists;
• PR publication authority is pending;
• current branch is default/shared/unknown-owned/detached;
• a fork/human-owned PR cannot be updated safely;
• trusted repository PR policy/template cannot be resolved.

GitHub uses gh; GitLab/Bitbucket use their available adapters; plain Git returns a pushed branch, request-pull, or patch/bundle. Never invoke gh in a non-GitHub repository.

2. Scope and exact candidate gate

Inspect the complete diff/commits from the resolved PR base. Map every file to one behavior/root cause. Multiple commits do not make a multi-feature branch acceptable.

• Tests, migrations, generated contracts, and docs for one behavior are one scope.
• Independent endpoints, roadmap phases, refactors, provider integrations, or “while here” fixes are separate scopes.
• Over 500 changed lines requires an explicit atomicity explanation.
• Over 1,000 defaults to split unless generated output or one inseparable foundation explains it.

For multiple scopes, preserve the source branch, then create independent or stacked delivery records in isolated worktrees. Each stacked PR targets its immediate parent and owns its own candidate/remote evidence. Never close or rewrite the recovery branch before replacements are reachable.

Require complete candidate evidence for the exact current head:

python3 "$DELIVERY_PY" show --id "<id>"
git rev-parse HEAD

If evidence is absent or names another head, run full repository checks on this head and record delivery candidate before publication. Align the base only to resolve a conflict or a stack parent that landed: main moving alone never makes a candidate stale (configs/CLAUDE.md, "Merge, then test").

3. Reuse existing PR

Query the forge for an open PR with this exact head branch before creating one.

• Existing agent-owned PR: update title/body/draft state as needed.
• Open human-owned PR: create a child repair branch/PR unless direct-update authority was explicit.
• Closed/merged predecessor: create a new PR from current base and link it.
• Fork PR: do not assume write access to its head.

PR creation is idempotent. Never open a duplicate because a previous process crashed after the forge write but before local state recording.

4. Build repository-native metadata

Honor the repository PR template, required labels/reviewers, contribution token/instructions, and forge conventions. The body records:

• problem/root cause and one scope;
• out-of-scope adjacent work;
• stack parent/children and merge order;
• exact base and head SHAs;
• exact local verification and remote-check status;
• risk and rollback;
• proposed merge strategy and why;
• whether intermediate commits are review checkpoints;
• required agent/runtime disclosure;
• the two review lines below.

Every PR body carries these two lines, spelled exactly so, because /retro parses them (pr-verification-gaps.py). A repository template governs the rest of the body, not these words:

Review depth: none | skimmed | read-in-full
Could not verify: none | <item>; <item>

• Review depth is how far someone other than the author read the diff: a human reviewer, or an independent review run such as /review-pr or a second-opinion agent, optionally named after the value. The author's own reading never counts, and a reading you did not see is never claimed, so at creation the line is almost always none. When a review lands, update the line: it states the depth at merge.
• Could not verify lists what was not checked, each item a few words naming the surface, with the reason in parentheses, items separated by ;. Write none only when every claim in the PR was checked. Reuse an earlier PR's wording for the same gap: /retro counts items by their words, so a rephrased item hides a gap that recurs.

For example:

Review depth: skimmed (by @reviewer)
Could not verify: macOS run (no Mac reachable); live hook firing (needs an interactive session)

Do not include secrets, raw auth endpoints, machine-private paths, or claims of independent human approval.

Draft only when requested, repository policy opens drafts early, or remote CI must run before ready.

5. Publish and record

--dry-run stops here. Report the resolved base, the scope verdict, the candidate-evidence status, and the PR title and body you would post — then stop without pushing and without calling gh pr create. This flag was in the argument-hint and read by nothing, so a run that asked to preview published a PR instead; of every flag in this toolkit that is the one whose absence is visible to other people.

Push with an explicit same-name refspec/upstream only under recorded push authority. Then create or update the PR through the selected forge adapter.

Record the result:

python3 "$DELIVERY_PY" publish \
  --id "<id>" --pr <number> --url "<url>" \
  --base "<resolved-base>" --head-sha "$(git rev-parse HEAD)" [--draft]

If recording fails after PR creation, re-query by head and repair the existing record; do not create another PR.

Do not wait on hosted checks: the exact-head candidate is the gate and hosted CI is the receipt. When integration is authorized, go straight to ready: with --checks receipt, the default, pending checks do not block, a failed one does, and branch protection gets auto-merge, never a bypass. When a check fails, before or after the merge, fix forward with new checkpoint commits, rerun full candidate verification for the new SHA, push, update the same PR (or open a follow-up after a merge), and record publish again so pull_request.head_sha names the pushed head (published stays true; a new candidate does not un-publish the delivery). Completion reports the URL, base/head, stack position, exact evidence, the hosted checks still running, and remaining external review.

Codex surface adapter

Codex surface adapter

• Installed Clade plugin skills are namespaced. Invoke this workflow as $clade:delivery, and use $clade:<skill-name> for companion workflows.
• Read the closest applicable agent instructions. Codex probes AGENTS.override.md before AGENTS.md at each scope and does not merge them, so where an override exists that scope's AGENTS.md is not in effect. CLAUDE.md is Clade's legacy fallback rather than a filename Codex resolves; read it only when it is trusted repository guidance.
• Codex-managed worktrees may begin at detached HEAD. A local detached commit is valid, but create/attach an owned branch or preserve a reachable Clade ref before the runtime deletes the worktree.
• Inspect git worktree list --porcelain before checkout, rewrite, or cleanup: one branch cannot be checked out by multiple worktrees.
• Use Codex native review/worktree/handoff capabilities where available. Do not launch Claude Code or a nested Codex CLI to emulate the workflow.
• Project configuration is trust-gated. Provider credentials and user connections remain user-scoped and cannot be donated by repository files.

Additional skill reference

Create or update PR

Publish one independently reviewable and reversible delivery unit. Use the shared $clade:delivery context/state controller; do not assume GitHub, origin, main, branch ownership, or autonomous PR authority.

One PR = one independently reviewable and reversible delivery unit.

Tests, migrations, generated files, and documentation for that same behavior belong together. Independent behavior becomes independent or explicitly stacked delivery records.

Delivery completion

If this workflow changes files or external state:

• Inspect the real final state before responding, including git status for a repository task.
• Never report DONE while task-owned changes are uncommitted. Use or continue $clade:delivery and create a repository-compliant checkpoint or preserve the work when committing is unavailable.
• When the user request or trusted repository policy makes publication, deployment, or live verification part of the task, do not silently downgrade the result to local-only work.
• If a required delivery transition lacks authority, credentials, a destination, or reachable external state, report BLOCKED or NEEDS_CONTEXT rather than appending a "not committed/pushed/deployed" caveat after DONE.