Promote to Main

Orchestrate the integration-to-main promotion workflow. This skill discovers everything that changed on integration since it diverged from main, runs pre-flight quality checks, performs change inventory, generates architecture diagrams, synthesizes release notes, and creates a comprehensive promotion PR.

Arguments

/autoskillit:promote-to-main [batch_branch] [base_branch] [--dry-run]

• batch_branch (optional) — source branch to promote. Defaults to integration.
• base_branch (optional) — target branch. Defaults to main.
• --dry-run — generate the full PR body without creating a PR.

When to Use

• When the develop branch is stable and ready to be promoted to main
• After feature PRs, bug fixes, and cleanup work have been collected and tested on develop
• This is the final gate before changes land on main

Critical Constraints

NEVER:

• Create files outside .autoskillit/temp/promote-to-main/
• Modify any source code — this skill is read-only analysis + PR creation
• Fail silently if gh is unavailable — output pr_url = (empty) and exit successfully
• Push or merge anything — this skill only creates the PR
• Skip pre-flight checks — a failing pre-flight must block PR creation
• Use the Bash tool for file reads — use Read, Grep, Glob for all codebase inspection
• Use gh pr create --body inline — always use --body-file

ALWAYS:

• Run ALL pre-flight checks before any analysis work
• Check gh auth status before any GitHub operations
• Output pr_url = <url> as a structured token (empty string when GitHub unavailable or dry-run)
• Output verdict = <value> as a structured token
• Carry forward ALL Closes #N, Fixes #N, and Resolves #N references from merged PR bodies
• Use gh pr create --body-file (never inline body via --body)
• pr_body_path must be an absolute path (prepend CWD)

Workflow

Phase 0: Setup

Step 0.1: Parse Arguments

Parse optional positional arguments and flags:

• batch_branch — default "develop" if absent or empty
• base_branch — default "main" if absent or empty
• dry_run — true if --dry-run present in ARGUMENTS

Validate that both branches exist locally:

git rev-parse --verify {batch_branch} 2>/dev/null
git rev-parse --verify {base_branch} 2>/dev/null

If either fails, try fetching:

git fetch origin {branch}:{branch} 2>/dev/null

If still missing, print error to stderr and exit 1.

Step 0.2: Compute Divergence Point

git merge-base {base_branch} {batch_branch}

Store as merge_base_sha.

Get commit count and timestamp:

git rev-list --count {merge_base_sha}..{batch_branch}
git show -s --format=%cI {merge_base_sha}

Store as commit_count and merge_base_date.

Step 0.3: Retrieve Token Summary from Session Logs

Determine the pipeline working directory and self-retrieve token telemetry from disk. This aggregates token usage across all constituent PR sessions that ran in this pipeline working directory.

mkdir -p .autoskillit/temp/promote-to-main
python3 - <<'EOF' > .autoskillit/temp/promote-to-main/token_summary.md 2>/dev/null || true
import json, pathlib, sys
from autoskillit.pipeline.tokens import DefaultTokenLog
from autoskillit.pipeline.telemetry_fmt import TelemetryFormatter
from autoskillit.execution.session_log import resolve_log_dir

cfg_path = pathlib.Path(".autoskillit") / "temp" / ".hook_config.json"
kitchen_id = ""
if cfg_path.exists():
    _cfg = json.loads(cfg_path.read_text())
    if isinstance(_cfg, dict):
        kitchen_id = _cfg.get("kitchen_id") or _cfg.get("pipeline_id", "")

log_root = resolve_log_dir("")
tl = DefaultTokenLog()
n = tl.load_from_log_dir(log_root, kitchen_id_filter=kitchen_id)
if n == 0:
    sys.exit(0)
steps = tl.get_report()
total = tl.compute_total()
print(TelemetryFormatter.format_token_table(steps, total))
EOF

• If .autoskillit/temp/promote-to-main/token_summary.md is non-empty, set TOKEN_SUMMARY_CONTENT to its contents and embed it in the PR body under ## Token Usage Summary.
• If empty or absent (standalone invocation, no pipeline sessions in this cwd), omit the section — graceful degradation with no error.

Phase 1: Pre-flight Checks (parallel, blocking)

Spawn three parallel Task subagents (model: sonnet) to validate promotion readiness. All three must pass before analysis proceeds. If any fails, report the failure clearly and exit 1. Do NOT create a PR when pre-flight fails.

Subagent 1A: CI and Branch Status

Check:

1. CI is green on the integration branch — run gh pr checks for any open PR from integration, or gh run list --branch {batch_branch} --workflow tests.yml --limit 1 --json conclusion
2. The integration branch is not behind base — run git rev-list --count {batch_branch}..{base_branch} to check if base has commits not in integration (if > 0, warn that a rebase may be needed)
3. No open PRs targeting integration with failing CI — gh pr list --base {batch_branch} --state open --json number,title,statusCheckRollup

Return JSON:

{
  "ci_status": "pass|fail|unknown",
  "ci_details": "description of CI state",
  "behind_base_by": 0,
  "open_prs_with_failing_ci": [],
  "pass": true
}

Subagent 1B: Version Consistency

Check:

1. pyproject.toml version matches src/autoskillit/.claude-plugin/plugin.json version
2. uv lock --check passes (lockfile consistent)
3. The integration branch version is ahead of the base branch version

Return JSON:

{
  "pyproject_version": "X.Y.Z",
  "plugin_version": "X.Y.Z",
  "versions_match": true,
  "lockfile_consistent": true,
  "version_ahead_of_base": true,
  "pass": true
}

Subagent 1C: Outstanding Review Items

Check:

1. No open PRs targeting integration with CHANGES_REQUESTED reviews — gh pr list --base {batch_branch} --state open --json number,title,reviews
2. No in-progress labeled issues that might indicate incomplete work — gh issue list --label in-progress --state open --json number,title

Return JSON:

{
  "prs_with_changes_requested": [],
  "in_progress_issues": [],
  "pass": true
}

Pre-flight gate: If any subagent returns "pass": false, report all failures in a clear summary table and exit 1 without proceeding to analysis. If ci_status is unknown, treat as a warning (non-blocking) and note it in the report.

Phase 2: Change Inventory (parallel subagents)

Spawn four parallel Task subagents (model: sonnet).

Subagent 2A: Commit Categorization

Receive the output of:

git log {merge_base_sha}..{batch_branch} --format="%H %s"

Categorize each commit into exactly one category based on its subject line:

• rectify — subject contains "Rectify:" or "fix:" or "bugfix" (case-insensitive)
• feature — subject contains "Implementation Plan:", "feat:", "Add ", or introduces new capability
• infra — subject contains CI, workflow, config, build, or infrastructure changes
• test — subject only touches test files (infer from "test" in subject or tests/ paths)
• docs — subject contains "docs:", "README", or documentation-only changes

Extract PR numbers from patterns like (#123) in commit subjects.

Return JSON:

{
  "categories": {
    "rectify": [{"sha": "abc123", "title": "...", "pr_number": 495}],
    "feature": [],
    "infra": [],
    "test": [],
    "docs": []
  },
  "totals": {"rectify": 14, "feature": 13, "infra": 3, "test": 1, "docs": 1},
  "category_summary": "14 fixes, 13 features, 3 infra"
}

Subagent 2B: PR Discovery and Issue Linkage

Run:

gh pr list --base {batch_branch} --state merged --limit 200 --json number,title,author,mergedAt,body,headRefName,additions,deletions,labels,url

Filter to PRs merged after merge_base_date. If empty, fall back to commit-subject discovery:

git log {merge_base_sha}..{batch_branch} --oneline --grep="(#" --format="%s"

For each PR, extract Closes|Fixes|Resolves #N references (case-insensitive). Deduplicate across all PRs. For each linked issue number, fetch details:

gh issue view {number} --json number,title,state,url,labels 2>/dev/null

Build a traceability matrix: for each issue, identify which PR(s) close it.

Return JSON:

{
  "prs": [{"number": 1, "title": "...", "author": "...", "labels": [], "url": "...", "additions": 0, "deletions": 0}],
  "closing_refs": ["Closes #42", "Fixes #50"],
  "linked_issue_numbers": [42, 50],
  "issue_details": [{"number": 42, "title": "...", "state": "OPEN", "url": "...", "labels": ["recipe:implementation"]}],
  "traceability": [{"issue_number": 42, "issue_title": "...", "pr_numbers": [491], "recipe_route": "implementation"}]
}

Subagent 2C: File Lifecycle Tracking

Run:

git diff --name-only {base_branch}..{batch_branch}
git diff --diff-filter=A --name-only {base_branch}..{batch_branch}
git diff --diff-filter=M --name-only {base_branch}..{batch_branch}
git diff --diff-filter=D --name-only {base_branch}..{batch_branch}
git diff --diff-filter=R --name-only {base_branch}..{batch_branch}
git diff --stat {base_branch}..{batch_branch} | tail -1

Return JSON:

{
  "changed_files": ["..."],
  "new_files": ["..."],
  "modified_files": ["..."],
  "deleted_files": ["..."],
  "renamed_files": ["..."],
  "diff_stat_summary": "185 files changed, 10013 insertions(+), 1164 deletions(-)"
}

Subagent 2D: Migration and Schema Detection

Scan the diff for changes that require manual attention on merge. Check:

1. Changes to src/autoskillit/migrations/ — new migration YAML notes
2. Changes to src/autoskillit/recipe/schema.py — recipe schema modifications
3. Changes to pyproject.toml — dependency additions/removals/version bumps
4. Changes to src/autoskillit/config/defaults.yaml — config schema changes
5. Changes to src/autoskillit/hooks/hooks.json — hook registration changes
6. Changes to src/autoskillit/.claude-plugin/plugin.json — plugin metadata changes
7. Changes to .github/workflows/ — CI workflow modifications

For each detected change, provide a brief description of what changed and why it might need attention.

Return JSON:

{
  "migration_changes": ["Added migration note for v0.3.2"],
  "schema_changes": ["New RecipeStep field: optional"],
  "dependency_changes": ["Added httpx>=0.27"],
  "config_changes": ["New config key: github.staged_label"],
  "hook_changes": ["New hook: pretty_output PostToolUse"],
  "ci_changes": ["Updated tests.yml matrix"],
  "attention_required": true,
  "attention_summary": "Brief description of what needs human review"
}

Phase 3: Architecture Diagrams

Step 3.1: Select Arch-Lens Lenses

Spawn a Task subagent (model: sonnet) with the changed_files list and this lens menu:

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

Return 1-3 lens names. Apply the same selection criteria as open-pr:

Development lens guard: Only select development if at least one changed file matches: pyproject.toml, Taskfile*, conftest.py, .github/workflows/*, Makefile, setup.cfg, setup.py, tox.ini, noxfile.py, or files under ci/.

For a promotion PR, prefer lenses that show the broadest architectural impact:

• module-dependency if changes span multiple packages
• process-flow if workflow routing or state transitions changed
• c4-container if new services, tools, or integrations were added

Step 3.2: 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, immediately begin sub-step 1 for the next lens.

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

• Path: .autoskillit/temp/promote-to-main/pr_arch_lens_context_{YYYY-MM-DD_HHMMSS}.md
• Content:

# PR Context — Integration to Main Promotion

This diagram is for a promotion PR merging the integration branch into main. Focus on the areas of the codebase affected by all accumulated changes. Do not create a generic whole-project diagram.

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

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

## Deleted files:
{list of deleted_files, or "None"}

## Instructions:
- Focus exploration and the diagram on the architectural areas these files belong to
- Use star prefix on nodes representing new files/components
- Use bullet prefix on nodes representing modified files/components
- Mark deleted components with strikethrough or a X prefix
- Leave unchanged components unmarked (include only if needed for context/connectivity)
- This is a promotion PR — show the cumulative architectural impact of all changes

2. Immediately call the Skill tool to load the arch-lens skill (e.g., /autoskillit:arch-lens-module-dependency).

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

Read the output from .autoskillit/temp/arch-lens-{lens-name}/ and extract the mermaid block(s).

Validate: if the block contains at least one star marker or bullet marker for new/modified nodes, add to validated_diagrams. Otherwise discard.

Phase 4: Compose PR + Create PR

Step 4.1: Release Notes Synthesis

Spawn one Task subagent (model: sonnet) with results from Phase 2 ONLY (no domain analysis or quality assessment data). The subagent receives:

• Commit categorization from Subagent 2A
• PR and issue data from Subagent 2B
• File lifecycle from Subagent 2C
• Migration/schema detection from Subagent 2D

Return JSON:

{
  "executive_summary": "3-5 sentence narrative of what this promotion brings, focused on change themes",
  "highlights": ["top 3-5 most significant changes"],
  "release_notes_md": "### New Features\n- ...\n### Bug Fixes\n- ...\n### Infrastructure\n...\n### Breaking Changes\n...\n### Attention Required\n..."
}

Step 4.2: Write PR Body

Write to .autoskillit/temp/promote-to-main/pr_body_{YYYY-MM-DD_HHMMSS}.md (relative to the current working directory).

Sections in order:

1. ## Promotion: {batch_branch} to {base_branch} — executive summary + stats (diff_stat_summary, commit_count, PR count)
2. ### Highlights — from synthesis
3. ## Release Notes — from synthesis
4. ## Merged PRs — table (PR, Title, Author, Labels) from Subagent 2B
5. ## Linked Issues — table (Issue, Title, Status, Action) from Subagent 2B
6. ## Attention Required — from Subagent 2D (only if attention_required=true)
7. ## Architecture Impact — validated mermaid diagrams from Phase 3
8. Closing references (Closes #N lines from Subagent 2B, one per line)
9. ## Token Usage Summary — if TOKEN_SUMMARY_CONTENT non-empty
10. Footer: <sub>Generated with Claude Code via AutoSkillit</sub>

Step 4.3: Create PR

If dry_run is true: skip to Output section.

Check GitHub availability:

gh auth status 2>/dev/null

If exit code non-zero: output pr_url = and exit successfully.

Construct PR title using actual branch names: Promote {batch_branch} to {base_branch} ({len(prs)} PRs, {len(linked_issue_numbers)} issues, {category_summary})

gh pr create \
  --base {base_branch} \
  --head {batch_branch} \
  --title "{pr_title}" \
  --body-file .autoskillit/temp/promote-to-main/pr_body_{timestamp}.md

Capture the PR URL as pr_url.

Add label (optional, continue if fails):

gh pr edit {pr_url} --add-label "promotion" 2>/dev/null || true

Output

Always emit these structured output tokens as the final lines:

pr_body_path = {absolute path to .autoskillit/temp/promote-to-main/pr_body_{timestamp}.md}
pr_url = {pr_url, empty if dry-run or gh unavailable}
verdict = {created|dry_run|preflight_failed}
category_summary = {e.g., "14 fixes, 13 features, 3 infra"}