Auto-upgrade: daily workflow to propagate upstream changes to installed repos

Start by reading the existing gh aw add install process and the workflows/autoloop.md and workflows/sync-branches.md sources. Trace how installed workflows are compiled and identify the CLI entry point for adding upgrade and version-tracking behavior. Done means the agreed upgrade design is implemented across the CLI and upgrade-check.md workflow, with local customizations and validation handled as specified.

Problem

When autoloop's source workflows change (bug fixes, new features, breaking changes), installed copies in downstream repos become stale. There is no upgrade mechanism — the install is a one-time file copy + compile. This means fixes like #18, #20, #23, #25 don't reach repos like githubnext/tsessebe until someone manually re-copies and recompiles.

The tsessebe case demonstrates the cost: 18 duplicate PRs were created because the stale .lock.yml didn't include the reset-if-merged fix from PR #25.

Goal

A smooth, automated upgrade path that:

1. Detects upstream changes daily
2. Creates a PR in the downstream repo with the updated workflows
3. Handles breaking changes gracefully (adapts local customizations)
4. Requires minimal human intervention for non-breaking updates

Design

Component 1: upgrade-check agentic workflow (lives in autoloop repo, installed into downstream repos)

A new gh-aw agentic workflow that runs daily in the downstream repo:

on:
  schedule: daily
  workflow_dispatch:

What it does each run:

1. Detect upstream version: Fetch the latest autoloop source from githubnext/autoloop (using gh api or cloning to /tmp). Compare the upstream workflows/autoloop.md and workflows/sync-branches.md against the local .github/workflows/ copies.

2. Diff classification: Classify changes as:

   • Non-breaking: Documentation, prompt wording, new optional features, bug fixes that don't change the frontmatter schema. These can be applied automatically.
   • Breaking: Changes to frontmatter keys, step structure, tool configuration, permissions, or safe-output schema. These need agent-assisted adaptation.

3. Preserve local customizations: Before applying upstream changes, extract local overrides (e.g., schedule: every 30m instead of every 6h, custom network.allowed entries, modified safe-outputs limits). After applying upstream changes, re-apply local overrides.

4. Recompile: Run gh aw compile to regenerate .lock.yml files from the updated .md sources.

5. Validate: Run gh aw compile --validate to ensure the compiled output is valid.

6. Create PR: Open a draft PR with the changes titled [Autoloop] Upgrade workflows to <upstream-sha-short>. The PR body should include:

   • Changelog of upstream changes (commit messages since last upgrade)
   • Classification (breaking / non-breaking)
   • Any local customizations that were preserved
   • Any manual action required

Component 2: gh aw upgrade CLI command (lives in gh-aw)

A CLI counterpart for manual/interactive upgrades:

# Check for available updates
gh aw upgrade --check

# Apply upgrade, auto-fix breaking changes where possible
gh aw upgrade --fix

# Upgrade a specific workflow
gh aw upgrade autoloop --fix

--fix behavior:

• Detects the source repo from the .lock.yml header (Source: githubnext/autoloop)
• Fetches the latest upstream .md source
• Three-way merges: upstream base → upstream new → local, preserving local customizations
• Recompiles
• Reports what changed and what couldn't be auto-fixed

Component 3: Version tracking

Add a version/provenance block to the installed .md files so the upgrade tooling knows what baseline to diff against:

# Bottom of the installed .md file, or in a sidecar file
_autoloop:
  source: githubnext/autoloop
  installed_from: abc1234  # commit SHA at install time
  installed_at: 2026-04-04T05:00:00Z
  compiler_version: v0.65.6

Or a simpler approach: a .github/workflows/.autoloop-version.json:

{
  "source": "githubnext/autoloop",
  "commit": "abc1234def5678",
  "installed_at": "2026-04-04T05:00:00Z",
  "workflows": ["autoloop", "sync-branches"]
}

This gives the upgrade tooling a baseline commit to diff against, so it can show exactly what changed upstream since the last install/upgrade.

Implementation plan

Phase 1: Version tracking + gh aw upgrade CLI

1. Add version metadata to gh aw add — when installing, write .autoloop-version.json (or equivalent) recording the source commit.
2. Implement gh aw upgrade --check — compares installed commit against upstream HEAD, shows changelog.
3. Implement gh aw upgrade --fix — fetches upstream, three-way merges preserving local customizations, recompiles.

Phase 2: upgrade-check agentic workflow

1. Add workflows/upgrade-check.md to the autoloop repo.
2. Include it in the install process (add to install.md).
3. The workflow uses gh aw upgrade --fix internally, then creates a PR with the result.

Phase 3: Breaking change detection

1. Define a schema for the frontmatter DSL (what fields exist, what values are valid).
2. Classify upstream diffs against this schema to detect breaking vs non-breaking changes.
3. For breaking changes the agent can't auto-fix, create an issue instead of a PR, explaining what needs manual attention.

Open questions

• Should the upgrade workflow run as a gh-aw agentic workflow itself, or as a plain GitHub Actions workflow? An agentic workflow can reason about breaking changes and adapt, but a plain workflow is simpler and doesn't consume agent compute for routine updates.
• Should local customizations be extracted into a separate config file (e.g., .autoloop/config.yml) to make three-way merging cleaner? This would separate "upstream workflow logic" from "local overrides."
• How to handle the case where the user has made significant manual edits to the .md source beyond simple config overrides?