abildtoft/kramme:pr:create

Create Pull Request

Orchestrate the creation of a clean, well-documented PR by validating git state, setting up the branch, recreating commits as a narrative, generating a description, and pushing + creating the PR via gh.

When NOT to use this skill

• Branch already has an open PR — update it directly (or use kramme:pr:finalize / kramme:pr:generate-description to refresh the description) instead of running the full creation flow.
• Hotfix / cherry-pick that must preserve exact commit boundaries — recreate-commits will reorganize history. Push and gh pr create manually.
• Working in a stacked-PR setup where the base is another feature branch — this skill assumes the repo default branch (resolved via origin/HEAD) as the PR base.
• The current branch hasn't diverged from the base branch — Step 4 will abort, but skip running the skill in the first place.

Process Overview

/kramme:pr:create
    |
    v
Step 1  Pre-Validation .................... abort on any failure
    |
Step 2  Resolve base branch ({base-branch})
Step 3  Branch handling (on base? Linear? upstream?)
    |
Step 4  Changes detection ................. abort if nothing to ship
    |
Step 5  Capture {original-branch} / {original-commit} / {stash-created}
    |
Step 6  Invoke kramme:git:recreate-commits  --> on failure, Step 10 rollback
    |
Step 7  Invoke kramme:pr:generate-description (with title-fallback path)
    |
Step 8  Preview + confirmation
        - Abort        --> Step 10 rollback
        - Edit         --> loop until user confirms
        - Create       --> push + gh pr create
    |
Step 9  Success output

Workflow rule — do not stop mid-flow

Steps 6 and 7 each invoke a sub-skill via the Skill tool. After a sub-skill returns, continue to the next step in this skill. Do not summarize and wait for user input between sub-skills. The only stop points are: a confirmation prompt that explicitly requires input, a --auto-suppressed prompt that hits a hard blocker, or a routed-to Step 10 abort.

References

• references/pre-validation-checks.md — Step 1: repository safety checks.
• references/branch-and-platform-handling.md — Steps 2–3: base-branch detection, branch creation, Linear lookup, upstream handling.
• references/state-and-rollback.md — Steps 5 and 10: state capture, stash handling, abort/rollback.
• references/confirmation-and-creation.md — Steps 8–9: preview, confirmation, edit loop, push, gh pr create, draft mode, success output.

Step 0: Parse Arguments

Parse $ARGUMENTS for optional flags before starting:

• --auto -> set AUTO_MODE=true and remove the flag from the remaining arguments.
• --draft -> set DRAFT_MODE=true and remove the flag from the remaining arguments.

Defaults: AUTO_MODE=false, DRAFT_MODE=false. Flag order is not significant.

--auto means:

• use the recommended commit structure (Narrative)
• invoke downstream skills in non-interactive mode
• skip the final PR confirmation
• choose the recommended branch-handling path from the shared reference instructions
• stop only on hard blockers

--draft means:

• create the PR as a draft (gh pr create --draft).

Without --draft, the PR is created ready for review.

---

Step 1: Pre-Validation

Read the pre-validation checks from references/pre-validation-checks.md. Run all four checks (git repo, merge conflicts, rebase/merge in progress, remote configuration) and abort on any failure.

---

Steps 2-3: Branch Handling

Read the branch handling instructions from references/branch-and-platform-handling.md. Validate the branch is a feature branch, detect the base branch (capture as {base-branch} — used in later display strings and as the PR base), and handle edge cases (detached HEAD, on base branch, Linear issue integration, no upstream).

---

Step 4: Changes Detection

4.1 Check for Uncommitted Changes

git status --porcelain

4.2 Check for Commits Ahead of Base

git rev-list --count origin/{base-branch}..HEAD

4.3 Validation

If both checks return empty/zero:

Error: No changes detected compared to {base-branch}.

Current state:
  - Branch: {feature-branch}
  - Uncommitted changes: None
  - Commits ahead of {base-branch}: 0

Nothing to create a PR for. Make some changes first, then run /kramme:pr:create again.

Action: Abort.

If changes exist: Continue to next step.

---

Step 5: State Preservation

Read references/state-and-rollback.md and execute Step 5 (capture {original-branch}, {original-commit}, {stash-created}; stash uncommitted changes if any). Keep these values for the rest of the workflow — they are agent-tracked state, not shell variables.

---

Step 6: Invoke recreate-commits Skill

6.1 Confirm Commit Restructuring Approach

If AUTO_MODE=true, skip this question and choose Narrative (recommended).

Otherwise use AskUserQuestion:

header: "Commit style"
question: "How should commits be structured for the PR?"
options:
  - label: "Narrative (recommended)"
    description: "Reorganize into logical story: setup, core implementation, tests, polish"
  - label: "Keep original"
    description: "Keep existing commit structure, just clean up messages"
  - label: "Single squash"
    description: "Combine all changes into one well-documented commit"
multiSelect: false

6.2 Invoke the Skill

IMPORTANT: Use the Skill tool to invoke recreate-commits:

If AUTO_MODE=true:

skill: "kramme:git:recreate-commits", args: "--auto"

Otherwise:

skill: "kramme:git:recreate-commits"

This skill will:

• Analyze all changes vs {base-branch}
• Plan a logical commit sequence
• Create narrative-quality commits
• NEVER include AI attribution (no "Generated with Claude Code" or Co-Authored-By)

When it returns, continue to Step 7. See the "Workflow rule" near the top of this skill.

6.3 Handle Skill Failure

If the skill fails or encounters an error:

Error: The recreate-commits skill encountered an issue.

Original state preserved:
  - Branch: {original-branch}
  - Commit: {original-commit}

What happened:
  {skill error message}

Recovery:
  1. Your original work is safe — rollback restored the branch and any stash
  2. Check git status to confirm
  3. Try again with /kramme:pr:create

Action: Execute Step 10 (rollback via references/state-and-rollback.md), then abort.

---

Step 7: Invoke pr-description-generator Skill

7.1 Invoke the Skill

Invoke kramme:pr:generate-description via the Skill tool. Pass --auto when AUTO_MODE=true, no arguments otherwise.

The skill will:

• Analyze git diff and commit history
• Check for Linear issue references in branch name
• Generate a conventional commit-style title (<type>(<scope>): <description>)
• Generate a comprehensive description

When it returns, continue to Step 8. See the "Workflow rule" near the top of this skill.

7.2 Capture the Title and Description

Capture both the title and the full description for Step 8.

7.3 Handle Skill Failure

If the skill returns no usable output, build a fallback:

Fallback title — derive in this order, picking the first that works:

1. git log --format=%s {base-branch}..HEAD | head -1 if there is at least one commit ahead.
2. Otherwise the current branch name with / replaced by : (e.g., feature/oauth → feature: oauth).
3. Otherwise prompt the user with AskUserQuestion (header "PR title", no preset options) — required, do not continue without a title.

Fallback description:

## Summary

[Brief description of changes]

## Technical Details

[Implementation approach]

## Test Plan

- [ ] Manual testing completed
- [ ] Unit tests pass

## Breaking Changes

None

Continue to Step 8 with the fallback title and description. When AUTO_MODE=true, prefer fallback (1) or (2) over prompting.

---

Step 8: Confirmation and Creation

Read references/confirmation-and-creation.md and execute Step 8 from that file. It contains the preview format, confirmation prompt, the "Edit description first" loop, draft-mode substitutions, push command, gh pr create invocation, and failure fallbacks. Substitute {base-branch}, {original-branch}, the captured title, and the generated description when emitting commands.

---

Step 9: Success Output

Use Step 9 in references/confirmation-and-creation.md for the final success message. Preserve the draft-specific wording when DRAFT_MODE=true.

---

Step 10: Abort and Rollback Handling

Triggered by an "Abort" choice in Step 8 or a critical failure in Steps 6–8. Execute Step 10 from references/state-and-rollback.md, which performs the checkout/reset, restores any stash, and prints the rollback confirmation.

---

Important Constraints

No AI Attribution

Never add Generated with [Claude Code], Co-Authored-By: Claude, or any mention of AI assistance to commits. recreate-commits enforces this for commit messages; this skill must not undo it.

Preserve Authorship

Never modify git config or add AI as author. All commits must reflect the user's authorship.

Draft Mode (Opt-In)

Draft PRs are opt-in via the --draft flag. Default behavior is to create PRs ready for review. Pass --draft to gh pr create only when DRAFT_MODE=true.

Self-Assignment

This skill creates PRs with gh pr create --assignee @me. This is intentional — the author opening the PR is the assignee. If you need to assign someone else, edit the PR after creation.

Complete All Steps

Even for simple changes, invoke both sub-skills:

1. kramme:git:recreate-commits for clean commit history
2. kramme:pr:generate-description for a comprehensive description

This keeps PRs consistent across the workflow.