Upstream

Take changes from a fork and contribute them back to the upstream open-source project following upstream expectations:

• Follow upstream contribution norms (issue-first rules, templates, CLA/DCO hints).
• Determine the correct target/base branch (e.g., develop vs main, release branches).
• Produce humanized, casual PR/issue text with minimal markdown.
• Fully automate submission via gh while verifying the final body stored on GitHub.

Agent Workflow

Step 1: Verify prerequisites

Before calling prep, check:

1. git remote -v — confirm there is a remote named upstream pointing to the original repo. If only origin exists and it looks like the fork, note it.
2. git status — confirm the branch is committed and pushed to origin.
3. If the branch hasn't been pushed yet, push it first: git push origin <branch>.

Branch naming: If the work is on main or a branch that doesn't follow the upstream project's contribution conventions (e.g., upstream expects fix/, feat/, username/ prefixes), create a properly named branch first. Use the worktrunk skill to create and manage the new branch, then cherry-pick or rebase the commits onto it before proceeding.

Step 2: Run prep

Before running prep, decide which flags to use:

Use --base to skip interactive prompts when the target branch is known (e.g., from running gh api repos/<upstream>/... --jq .default_branch):

python3 <skill-dir>/scripts/upstream.py prep --base main --no-issue

<skill-dir> is the directory containing this SKILL.md file. Resolve it at runtime as the absolute path to the skill directory (e.g., use $SKILL_DIR if set by the agent framework, or locate the directory containing scripts/upstream.py).

• --base <branch> skips the interactive branch selection prompt.
• --no-issue skips issue-first gating when you know a standalone PR is appropriate.

Step 3: Edit draft-pr.md

After prep generates draft-pr.md, you must edit it before submitting. The template contains placeholder tokens (<problem>, <what changed>, etc.) that need real content. The file also contains a commented-out git log block to help you understand what the commits do. Replace the placeholder lines with a short, honest description of:

• What problem the change addresses
• What was changed at a high level

Keep it brief and human. Don't add headings or bullets unless truly necessary.

Step 4: Run submit pr

python3 <skill-dir>/scripts/upstream.py submit pr --title "fix(scope): short description"

Always pass --title explicitly. The script will automatically:

• Detect cross-fork scenarios (origin ≠ upstream remote) and add the owner:branch head prefix and --repo flag.
• Verify the posted body and repair garbling if needed.

Step 5: Confirm

Report the PR URL to the user.

NEVER Do

• NEVER open a PR without reading CONTRIBUTING.md — many upstream repos require an issue first and will close PRs immediately without one
• NEVER use gh pr create --body "..." inline — shell quoting corrupts markdown; always use --body-file (the script handles this automatically)
• NEVER target a release/hotfix branch as the PR base without explicit maintainer instruction
• NEVER push commits directly to the upstream remote — always PR from your fork's branch to upstream
• NEVER skip the --title flag on submit pr — gh will prompt interactively and block agent execution

Disclosure Name Configuration

• Default: upstream-skill
• Configurable via --skillname or environment variable SKILLNAME.

User-Facing Artifacts (Repo Root)

• draft-pr.md — generated by prep; must be edited before submitting
• draft-issue.md — generated when issue-first is required
• .draft-pr.rendered.md, .draft-issue.rendered.md — ephemeral; used for safe gh --body-file submission
• draft-pr.github.md, draft-issue.github.md — written only on unrecoverable body garbling

Cross-Fork PR Handling

When the repo has both an origin remote (your fork) and an upstream remote (the original project), submit pr automatically:

1. Resolves the upstream repo slug from the upstream remote.
2. Prefixes the head branch with your fork owner: fork-owner:branch-name.
3. Passes --repo upstream-owner/upstream-repo to gh pr create.

This means you do not need to manually run gh pr create --repo ... — the script handles it.

Disclosures (AI Drafting)

Each issue/PR begins with a short disclosure:

Note: I used an AI agent ({skillname}) to help draft this, but I ({username}) reviewed the write-up and the code. If the tone/format isn't a good fit here, please let me know and I'll adjust the skill.

Subcommand Reference

prep [--base <branch>] [--no-issue]

Discovers upstream process, resolves target branch, and generates draft-pr.md (and optionally draft-issue.md).

• --base <branch> — override target branch; skips interactive selection entirely
• --no-issue — suppress issue-first gating; don't generate draft-issue.md

submit issue [--title <title>]

Creates or updates an issue from draft-issue.md.

submit pr [--title <title>] [--head <branch>] [--draft]

Creates or updates a PR from draft-pr.md. Always pass --title.

status

Shows recorded URLs, branches, and draft file state.

fix (issue|pr)

Re-verifies and repairs a posted body without re-running prep.

clean

Removes all draft and rendered files.

Gating and Discovery

Base Branch Discovery

Signal order (highest to lowest confidence):

1. --base CLI flag (skips all discovery)
2. CONTRIBUTING.md explicit branch reference
3. Mode of recently merged PRs' base branches
4. Default branch

Issue-First Discovery

• Reads CONTRIBUTING.md for "file an issue before PR" language
• Reads PR template for issue linkage mentions
• If unclear, asks interactively (bypassed with --no-issue)

Draft Style Contract

• Remove excessive headings (plain prose preferred)
• Collapse long bullet lists into short sentences
• Avoid code fences unless the content requires it
• Keep the narrative casual, first-person, and minimal

Submission Safety and Verification

• Always uses --body-file (never inline --body) to avoid shell quoting
• Appends hidden integrity marker: <!-- upstream-skill:sha256=<hash> -->
• After submission, fetches canonical body from GitHub and compares
• Two-stage repair: re-apply → safe rewrite → fail with saved body

Ask Tool Integration

• ASK_BACKEND=stdio (default): interactive CLI prompts
• ASK_BACKEND=jsonrpc: host-native ask dialogs

Dependencies

• python3
• git
• gh (GitHub CLI) authenticated (gh auth login)

Installation

Verify scripts/upstream.py exists in the skill directory. If it does not, inform the user that the implementation file is missing and halt.

Run from the repo root:

python3 <skill-dir>/scripts/upstream.py <subcommand>

Example Workflows

A) Simple PR to upstream (known branch, no issue required)

python3 upstream.py prep --base main --no-issue
# edit draft-pr.md — fill in the placeholder text
python3 upstream.py submit pr --title "fix(scope): description"

B) Issue-first repo

python3 upstream.py prep --base main
python3 upstream.py submit issue --title "bug: short description"
python3 upstream.py submit pr --title "fix: short description"

C) Ambiguous branch (interactive)

python3 upstream.py prep   # will ask which branch to target
# edit draft-pr.md
python3 upstream.py submit pr --title "feat: ..."

Implementation

The reference implementation is included as scripts/upstream.py.