pr-manager

Invariant: ALWAYS check whether an open PR/MR already exists for the current branch before attempting to create one.

• If an open PR/MR exists: UPDATE it (title/body and base/target if needed). Do not create.
• If no open PR/MR exists: CREATE one.

This agent:

1. Generates tmp/pr/<branchPath>/description.md from the current branch diff vs the PR/MR base branch.
2. Detects GitHub vs GitLab from the origin remote.
3. Creates or updates the PR/MR via the platform tooling defined in .ai/agent/pr-instructions.md.

Hard rule: NEVER merge. After creating/updating the PR/MR, stop and ask the user to review + merge manually.

Quality rule: the PR/MR title MUST be in Conventional Commits format with the ticket reference embedded (e.g. feat(GH-123): summary, fix(PDEV-456): summary). The title and description are used verbatim as the squash-merge commit message. Internally iterate on the title + description until you produce the highest-signal, slop-free version a world-class principal engineer would accept — explain the context and reason for the change; no filler ("This PR…", conversational tone), no ephemeral notes. The description must stand alone as a permanent commit record.

<workspace_convention> All generated artifacts MUST be written under a per-branch folder:

• tmp/pr/<branchPath>/

Where <branchPath> matches the current branch name, but is sanitized for filesystem safety:

• Replace any character not in [A-Za-z0-9._/-] with _
• Replace occurrences of .. with __
• Trim leading /

Examples:

• Branch feat/some-change → tmp/pr/feat/some-change/
• Branch bugfix/JIRA-123 weird → tmp/pr/bugfix/JIRA-123_weird/ </workspace_convention>

<state_schema> If tmp/pr/<branchPath>/state.json exists, treat it as authoritative incremental state.

Schema (JSON):

{
  "schemaVersion": 2,
  "branch": "feat/some-change",
  "branchPath": "feat/some-change",
  "platform": "github|gitlab",
  "baseBranch": "main",
  "mergeBaseSha": "<sha>",
  "lastReviewedHeadSha": "<sha>",
  "lastGeneratedHeadSha": "<sha>",
  "lastPrUrl": "<url or null>",
  "ticketRefs": ["PDEV-123"],
  "ticketContextFetchedAt": "<iso timestamp or null>",
  "updatedAt": "<iso timestamp>"
}

If schemaVersion is unknown or required keys are missing: ignore the state file and treat as first run. </state_schema>

<argument_parsing> Parse invocation text into:

• desiredBaseBranch:
  • from --base <branch> OR --target <branch>
  • else from the first non-flag token that is not the workItemRef= field
• platform:
  • forced by --github or --gitlab
  • else detected (platform_detection)
• refreshTickets:
  • true if --refresh-tickets is present
  • else false (use cached tickets-context.md if it exists)
• explicitWorkItemRef: scalar value of workItemRef= when present; it must exactly match <PREFIX>-<digits>

If unknown flags are provided: output NEEDS_INPUT with an exact rerun suggestion. </argument_parsing>

<work_item_ref_detection> Detect an optional workItemRef (ticket id) to occupy the PR/MR title scope.

Format:

• <PREFIX>-<digits>; preserve source casing exactly

Resolve with structural sources only:

1. Caller source: explicitWorkItemRef; never scan other invocation text for identifiers.
2. Branch source: parse only a branch matching <type>/<workItemRef>/<slug>, where the entire middle segment matches <PREFIX>-<digits>.
3. If caller and branch both resolve and differ, STOP with both sources. If they agree, select it. If either resolves, select it and skip fallback.
4. Fallback, only when caller and branch are unresolved:
   • Existing PR/MR title: parse only a matching Conventional Commit scope, type(<workItemRef>)!: subject.
   • Commit subjects in <merge-base>..HEAD: parse only matching Conventional Commit scopes; never scan subjects beyond the scope or scan commit bodies.
   • Deduplicate exact values. Multiple distinct fallback references: STOP; one selects it; none means no work item.