vintasoftware/vinta-ai-workflows/open-pr-from-context

Open PR from context

implement-plan writes per-phase PR drafts to .vinta-ai-workflows/prs-context/{feature-name}/{phase-name}.md (template) and (when a PR CLI is detected) calls this skill to publish them. When the runtime had no PR CLI at write time, the file sits as status: pending until someone runs this skill in an environment with the CLI.

The mechanical work — parse frontmatter, detect CLI, open PR, post each inline comment, rewrite frontmatter to published, append publish log — lives in `scripts/open-pr.sh`. This SKILL.md just wires the agent to it.

Dependencies

The script needs: bash 4+, git, yq (Mike Farah's), jq, and one of gh / glab. Install via the project's package manager / Homebrew / apt:

• macOS: brew install yq jq gh (or glab).
• Debian/Ubuntu: apt install yq jq + gh from cli.github.com (or glab from gitlab.com).
• Inside CI runners: ensure these are present in the image.

The script bails early with missing dependency: <name> if any are absent. Surface the install command — don't auto-install.

Steps

1. Pick the file

If the user passed a file path → use it.

Otherwise list candidates: find .vinta-ai-workflows/prs-context -type f -name '*.md', read each one's frontmatter status field, prefer status: pending. Use AskUserQuestion to confirm if more than one is pending.

2. Run the script

bash ai-tools/skills/open-pr-from-context/scripts/open-pr.sh <file>

(The script has the executable bit set, so ./ai-tools/skills/open-pr-from-context/scripts/open-pr.sh <file> also works.)

Optional flags:

• --cli gh|glab — force a specific PR CLI. Default: auto-detect (gh first, then glab).
• --dry-run / -n — print what would be posted; touch nothing remote and don't rewrite the file.

Pass through whatever the user explicitly asked for; otherwise no flags.

3. Report the result

Read the script's stdout + exit code:

• Exit 0 — PR opened (or pre-existing detected); all comments posted. File rewritten to status: published + pr_url. Surface the URL to the user; you're done.
• Exit 1 — PR opened, but one or more inline comments failed. The script's stderr lists which (file:line) failed, each one after a gh error: / glab error: line that holds the API's message (for example 422 Validation Failed). Forward both verbatim. Most common cause: a force-push between branch push and now invalidated the line position — re-run after pushing.
• Exit 2 — Hard failure (file invalid, branch not pushed, CLI missing/unauthed, missing dependency). Forward the script's error message; do not improvise (don't push the branch, don't install CLIs, don't auth on the user's behalf).

Inputs the script expects

The bundled prs-context-template.md documents the file shape. The script verifies:

• Frontmatter: branch, base (required); status, pr_url (read + written).
• # Title section: single line, non-empty.
• # Description section: markdown, non-empty.
• # Comments section: a single fenced ```yaml list (may be empty — clean phases are valid).

A file at status: published with a populated pr_url is a no-op — the script prints the URL and exits 0 without touching anything.

What this skill / script do NOT do

• Do not push the branch. implement-plan already pushed it. If the script reports branch not pushed, that's a setup bug — surface it.
• Do not edit the diff. Comment placement is informational only.
• Do not re-run tests / lint. Those happened in implement-plan before push.
• Do not draft new descriptions or comments. The file is the source of truth — edit the file (or re-run implement-plan for that phase) before re-invoking.
• Do not install or authenticate CLIs. Surfaces the gap, stops.
• Do not delete the PR-context file. implement-plan cleans up at plan end; until then the file is durable history.

Pitfalls

• Stacked phases. PR base is the previous phase's branch, not main. The file's base field has the right value; the script trusts it. Don't override.
• Force-pushed branch. Inline comments target a SHA. If the branch was force-pushed between PR open and comment posting, GitHub/GitLab may reject specific lines as "no longer in the diff". Per-comment failures are reported but don't abort the run — the surviving comments still post. Re-run after pushing if you want the failed ones.
• Empty `# Comments`. Valid; clean phases produce few or zero comments. Script no-ops the comment loop, still rewrites status to published.
• Missing `yq` / `jq`. Script bails with missing dependency: yq (or jq) before doing anything. Install the missing tool, re-run.