Open PR

Read a completed plan, analyze changed files, generate architecture diagrams using the most relevant arch-lens lenses, and open a GitHub Pull Request.

Arguments

/autoskillit:open-pr {plan_paths} {feature_branch} {base_branch} [token_summary_path] [closing_issue] [conflict_report_path]

• plan_paths — Comma-separated list of absolute paths to implementation plan markdown files. Single path for non-groups runs; multiple comma-separated paths for multi-group runs.
• feature_branch — Branch containing all merged implementation changes
• base_branch — Branch to open the PR against (e.g., "main")
• token_summary_path (optional) — Absolute path to a markdown file containing a pre-formatted token usage summary table. When provided, included in the PR body. Generated by the orchestrator before invoking this skill.
• closing_issue (optional) — GitHub issue number to close (e.g., "99"). When provided, inserts Closes #closing_issue into the PR body so GitHub auto-closes the issue on merge.
• conflict_report_path (optional) — Absolute path to a single conflict resolution report from resolve-merge-conflicts. When provided and non-empty, embed a "Conflict Resolution Decisions" section in the PR body. Accepts exactly one path (not comma-separated); the implementation pipeline passes only one path per single-branch run.

When to Use

• Called by implementation when open_pr=true, after all groups/parts are merged
• Can be invoked standalone after any implementation that used a feature branch

Critical Constraints

NEVER:

• Create files outside temp/open-pr/ (except temp files used for gh pr create --body-file)
• Fail the pipeline if gh is not available or not authenticated — output pr_url= (empty) and exit successfully
• Modify any source code

ALWAYS:

• Check gh auth status before attempting GitHub operations
• ALWAYS assume the feature branch is already on the remote (the recipe pushes before invoking this skill)
• Output pr_url=<url> on the last output line (empty string if GitHub unavailable)
• Select 1–3 arch-lens lenses based on relevance — only include a lens if the changed files map to that lens's concern

Workflow

Precondition: The feature branch is already published to the remote by the push_to_remote recipe step that precedes this skill invocation. Do NOT push the branch yourself.

Step 0: Stable Branch Guard

Parse the positional arguments:

• arg[1] = plan_paths
• arg[2] = feature_branch (the branch being PRed)
• arg[3] = base_branch (PR target)

If base_branch == "stable" AND feature_branch != "main": Print to stderr: ERROR: PRs targeting 'stable' are only allowed from 'main'. Source branch '$feature_branch' is not 'main'. Stable branch policy: only integration PRs from main are permitted. Tip: Open a PR to 'integration' first, then promote via the integration pipeline. Exit with code 1.

Step 1: Parse Arguments

Parse three positional arguments: plan_paths, feature_branch, base_branch. Parse the optional fourth positional argument token_summary_path (may be absent). Parse the optional fifth positional argument closing_issue (may be absent or empty string). Parse the optional sixth positional argument conflict_report_path (may be absent or empty string). Split plan_paths by comma to get a list of plan file paths.

Step 1b: Fetch Requirements from Closing Issue

• If closing_issue is absent or empty string: skip — set requirements_section = "".
• Fetch issue body:
  bashCopy

  gh issue view {closing_issue} --json body -q .body
  

• Extract the ## Requirements section: requirements_section = everything from ## Requirements to the next ## heading or end of body, whichever comes first.
• If no ## Requirements section found: set requirements_section = "".
• This step is skipped gracefully if gh is unavailable — requirements_section remains "".

Step 2: Extract PR Title from Plan

Read all plan files. For each, extract the first # heading line and strip the # prefix.

• Single plan: Use the heading directly as {task_title} (current behavior).
• Multiple plans: Spawn a subagent (Task tool, model: sonnet) with all extracted headings. Instruct it to synthesize a single concise PR title (under 70 characters) that captures the overall scope. The title should NOT enumerate every group — it should describe the aggregate change.

PR Title Prefix (derived from run_name):

If a run_name positional argument is provided, apply a prefix to the PR title:

• run_name starts with "feature" → prepend [FEATURE] to the PR title
• run_name starts with "fix" → prepend [FIX] to the PR title
• Any other run_name → no prefix (existing behavior preserved)

This convention is set by /autoskillit:process-issues when it passes run_name="feature" for recipe:implementation issues and run_name="fix" for recipe:remediation issues. Direct recipe invocations using run_name="impl" (the default) are unaffected.

BASE_TITLE="$(head -1 {plan_path} | sed 's/^# //')"
case "$RUN_NAME" in
  feature*) TITLE="[FEATURE] $BASE_TITLE" ;;
  fix*)     TITLE="[FIX] $BASE_TITLE" ;;
  *)        TITLE="$BASE_TITLE" ;;
esac
gh pr create --title "$TITLE" ...

Step 2c: Load Conflict Resolution Report

• If conflict_report_path is absent or empty string: skip — set conflict_resolution_table = "".
• Read the file at conflict_report_path.
• Extract the ## Per-File Resolution Decisions table (all lines from the | File | header through the last table row).
• Store as conflict_resolution_table.

Skip gracefully if the path does not exist — conflict_resolution_table remains "".

Step 3: Get Changed Files

Run:

git diff --name-only {base_branch}..{feature_branch}

Collect the list of changed file paths. If the command fails or returns empty, proceed with an empty file list (the PR body will note that no diff was available).

Then classify changed files by status:

# Files added (new)
git diff --diff-filter=A --name-only {base_branch}..{feature_branch}

# Files modified
git diff --diff-filter=M --name-only {base_branch}..{feature_branch}

Store these as two separate lists: new_files (added) and modified_files. The existing changed_files list (all files) is retained for lens selection in Step 4.

Step 4: Select Arch-Lens Lenses

Spawn a subagent (Task tool, model: sonnet) with the list of changed file paths and the following lens menu:

c4-container, concurrency, data-lineage, deployment, development,
error-resilience, module-dependency, operational, process-flow,
repository-access, scenarios, security, state-lifecycle

Instruct the subagent to return 1–3 lens names. Only include a lens if at least one changed file maps to that lens's concern — if no files clearly map to a given lens, omit it. Choose as few as are genuinely relevant; more is not better.

Development lens guard: The development lens must ONLY be selected if at least one changed file matches a build/test configuration pattern: pyproject.toml, Taskfile*, conftest.py, .github/workflows/*, Makefile, setup.cfg, setup.py, tox.ini, noxfile.py, or files under a ci/ directory. If no changed file matches these patterns, do NOT select the development lens regardless of other criteria.

Selection criteria:

• module-dependency → changes span multiple packages or add new dependencies
• process-flow → changes affect workflow routing, state transitions, or control flow
• development → changes affect build config or quality gates (pyproject.toml, Taskfile*, conftest.py, CI configs) — NOT selected for ordinary test file changes
• operational → changes affect CLI, config, or observability
• c4-container → changes add new services, tools, or integrations
• security → changes affect trust boundaries or validation layers
• repository-access → changes affect data access or repository patterns
• state-lifecycle → changes affect field contracts or resume safety

Step 5: Generate Arch-Lens Diagrams

For each selected lens, follow this exact sequence:

CRITICAL: Do NOT output any prose status text between lens iterations. After completing all sub-steps for one lens (including mermaid extraction and validation), immediately begin sub-step 1 (Write the PR context file) for the next lens. Progress announcements like "Diagram generated. Now calling X:" create end_turn windows that cause stochastic session termination.

1. Write the PR context to a file using the Write tool:

• Path: temp/open-pr/pr_arch_lens_context_{YYYY-MM-DD_HHMMSS}.md
• Content: The following PR context block, with placeholders filled in:

# PR Context — Changed Files

This diagram is for a Pull Request. Focus the diagram on the areas of the codebase affected by these changes. Do not create a generic whole-project diagram.

## New files (use ★ prefix on these nodes):
{list of new_files from Step 3, or "None"}

## Modified files (use ● prefix on these nodes):
{list of modified_files from Step 3, or "None"}

## Instructions:
- Focus exploration and the diagram on the architectural areas these files belong to
- Use `★` prefix on nodes representing new files/components
- Use `●` prefix on nodes representing modified files/components
- Leave unchanged components unmarked (include them only if needed for context/connectivity)
- The diagram should help PR reviewers understand the architectural impact of these specific changes

2. Immediately call the Skill tool to load the arch-lens skill (e.g., /autoskillit:arch-lens-module-dependency). The loaded skill will read the PR context file written in step 1 above.

3. Follow the loaded skill's instructions to explore the codebase and generate the diagram.

The arch-lens skills write their output to temp/arch-lens-{lens-name}/ (relative to the current working directory). After each skill runs, read the generated markdown file and extract the mermaid code block(s).

After extracting the mermaid block, inspect its content for ★ or ● characters:

• If the block contains at least one ★ or ● → add it to validated_diagrams.
• If the block contains neither → discard this diagram; do not add it to the list.

This ensures the PR body only includes diagrams where at least one component was visibly modified or created by the PR.

Step 6: Compose PR Body

After generating all diagrams, check validated_diagrams:

• If validated_diagrams is non-empty → include the ## Architecture Impact section as described below, embedding only the validated mermaid blocks.
• If validated_diagrams is empty → omit the ## Architecture Impact section entirely. Do not include a placeholder or note in the PR body.

Write the PR body to temp/open-pr/pr_body_{timestamp}.md. (relative to the current working directory)

Read ## Summary from each plan file.

Single plan (one path):

## Summary

{First paragraph of the plan's ## Summary section, or first 5 lines after the heading}

{If extracted: include the requirements section from the closing issue}
## Requirements

{requirements_section from closing issue}

{If conflict_resolution_table is non-empty:}
## Conflict Resolution Decisions

The following files had merge conflicts that were automatically resolved.

{conflict_resolution_table}

{## Architecture Impact — conditional: include only if validated_diagrams is non-empty}
## Architecture Impact

{For each validated lens diagram: embed the mermaid block with a heading for the lens name}

### {Lens Name} Diagram

` ` `mermaid
{diagram content}
` ` `

{If closing_issue is provided and non-empty:}
Closes #{closing_issue}

## Implementation Plan

Plan file: `{plan_path}`

{If token_summary_path was provided and the file exists, include this section:}
## Token Usage Summary

{Read the file at token_summary_path and include its contents verbatim.}

🤖 Generated with [Claude Code](https://claude.com/claude-code) via AutoSkillit

Multiple plans (comma-separated paths):

## Summary

{Synthesized overall summary — 2-3 sentences covering the aggregate change.
 Use a sonnet subagent to produce this from all individual summaries.}

<details>
<summary>Individual Group Plans</summary>

### Group 1: {heading from plan 1}
{Summary from plan 1}

### Group 2: {heading from plan 2}
{Summary from plan 2}

</details>

{If extracted: include the requirements section from the closing issue}
## Requirements

{requirements_section from closing issue}

{If conflict_resolution_table is non-empty:}
## Conflict Resolution Decisions

The following files had merge conflicts that were automatically resolved.

{conflict_resolution_table}

{## Architecture Impact — conditional: include only if validated_diagrams is non-empty}
## Architecture Impact

{Same as single plan — validated lens diagrams are based on full diff, not plan count}

### {Lens Name} Diagram

` ` `mermaid
{diagram content}
` ` `

{If closing_issue is provided and non-empty:}
Closes #{closing_issue}

## Implementation Plan

Plan files:
- `{plan_path_1}`
- `{plan_path_2}`

{If token_summary_path was provided and the file exists, include this section:}
## Token Usage Summary

{Read the file at token_summary_path and include its contents verbatim.}

🤖 Generated with [Claude Code](https://claude.com/claude-code) via AutoSkillit

Step 7: Check GitHub Availability

Run gh auth status 2>/dev/null. If exit code is non-zero:

• Log "GitHub CLI not available or not authenticated — skipping PR creation"
• Output: pr_url=
• Exit successfully

Step 8: Create Pull Request

gh pr create \
  --base {base_branch} \
  --head {feature_branch} \
  --title "{task_title}" \
  --body-file temp/open-pr/pr_body_{timestamp}.md

Capture the PR URL from stdout.

Output: pr_url={url}

Output

• Always: pr_url=<url> (empty string when GitHub unavailable)
• PR body written to: temp/open-pr/pr_body_{timestamp}.md