From 470f391ae67860c621d72b6d7bcb9e30b6e947ec Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Thu, 22 Jan 2026 00:21:36 +0000
Subject: [PATCH 1/3] Initial plan


From a635f994859321b3515a48b26adc50bb1dc7ec38 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Thu, 22 Jan 2026 00:29:34 +0000
Subject: [PATCH 2/3] Add comprehensive upgrade guide for agentic workflows

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
---
 .../src/content/docs/agent-factory-status.mdx |   3 +-
 docs/src/content/docs/guides/upgrading.md     | 595 ++++++++++++++++++
 2 files changed, 597 insertions(+), 1 deletion(-)
 create mode 100644 docs/src/content/docs/guides/upgrading.md

diff --git a/docs/src/content/docs/agent-factory-status.mdx b/docs/src/content/docs/agent-factory-status.mdx
index 7b73fd33212..26fe992a271 100644
--- a/docs/src/content/docs/agent-factory-status.mdx
+++ b/docs/src/content/docs/agent-factory-status.mdx
@@ -112,7 +112,6 @@ These are experimental agentic workflows used by the GitHub Next team to learn,
 | [Safe Output Health Monitor](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/safe-output-health.md) | claude | [![Safe Output Health Monitor](https://github.com/githubnext/gh-aw/actions/workflows/safe-output-health.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/safe-output-health.lock.yml) | - | - |
 | [Schema Consistency Checker](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/schema-consistency-checker.md) | claude | [![Schema Consistency Checker](https://github.com/githubnext/gh-aw/actions/workflows/schema-consistency-checker.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/schema-consistency-checker.lock.yml) | - | - |
 | [Scout](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/scout.md) | claude | [![Scout](https://github.com/githubnext/gh-aw/actions/workflows/scout.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/scout.lock.yml) | - | `/scout` |
-| [Security Alert Burndown](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/security-alert-burndown.campaign.md) | copilot | [![Security Alert Burndown](https://github.com/githubnext/gh-aw/actions/workflows/security-alert-burndown.campaign.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/security-alert-burndown.campaign.lock.yml) | - | - |
 | [Security Compliance Campaign](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/security-compliance.md) | copilot | [![Security Compliance Campaign](https://github.com/githubnext/gh-aw/actions/workflows/security-compliance.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/security-compliance.lock.yml) | - | - |
 | [Security Fix PR](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/security-fix-pr.md) | copilot | [![Security Fix PR](https://github.com/githubnext/gh-aw/actions/workflows/security-fix-pr.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/security-fix-pr.lock.yml) | - | - |
 | [Security Review Agent 🔒](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/security-review.md) | copilot | [![Security Review Agent 🔒](https://github.com/githubnext/gh-aw/actions/workflows/security-review.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/security-review.lock.yml) | - | `/security` |
@@ -122,12 +121,14 @@ These are experimental agentic workflows used by the GitHub Next team to learn,
 | [Smoke Claude](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/smoke-claude.md) | claude | [![Smoke Claude](https://github.com/githubnext/gh-aw/actions/workflows/smoke-claude.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/smoke-claude.lock.yml) | - | - |
 | [Smoke Codex](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/smoke-codex.md) | codex | [![Smoke Codex](https://github.com/githubnext/gh-aw/actions/workflows/smoke-codex.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/smoke-codex.lock.yml) | - | - |
 | [Smoke Copilot](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/smoke-copilot.md) | copilot | [![Smoke Copilot](https://github.com/githubnext/gh-aw/actions/workflows/smoke-copilot.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/smoke-copilot.lock.yml) | - | - |
+| [Smoke OpenCode](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/smoke-opencode.md) | copilot | [![Smoke OpenCode](https://github.com/githubnext/gh-aw/actions/workflows/smoke-opencode.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/smoke-opencode.lock.yml) | - | - |
 | [Stale Repository Identifier](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/stale-repo-identifier.md) | copilot | [![Stale Repository Identifier](https://github.com/githubnext/gh-aw/actions/workflows/stale-repo-identifier.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/stale-repo-identifier.lock.yml) | - | - |
 | [Static Analysis Report](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/static-analysis-report.md) | claude | [![Static Analysis Report](https://github.com/githubnext/gh-aw/actions/workflows/static-analysis-report.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/static-analysis-report.lock.yml) | - | - |
 | [Step Name Alignment](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/step-name-alignment.md) | claude | [![Step Name Alignment](https://github.com/githubnext/gh-aw/actions/workflows/step-name-alignment.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/step-name-alignment.lock.yml) | `daily` | - |
 | [Sub-Issue Closer](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/sub-issue-closer.md) | copilot | [![Sub-Issue Closer](https://github.com/githubnext/gh-aw/actions/workflows/sub-issue-closer.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/sub-issue-closer.lock.yml) | - | - |
 | [Super Linter Report](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/super-linter.md) | copilot | [![Super Linter Report](https://github.com/githubnext/gh-aw/actions/workflows/super-linter.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/super-linter.lock.yml) | `0 14 * * 1-5` | - |
 | [Terminal Stylist](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/terminal-stylist.md) | copilot | [![Terminal Stylist](https://github.com/githubnext/gh-aw/actions/workflows/terminal-stylist.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/terminal-stylist.lock.yml) | - | - |
+| [Test Create PR Error Handling](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/test-create-pr-error-handling.md) | claude | [![Test Create PR Error Handling](https://github.com/githubnext/gh-aw/actions/workflows/test-create-pr-error-handling.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/test-create-pr-error-handling.lock.yml) | - | - |
 | [The Daily Repository Chronicle](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/daily-repo-chronicle.md) | copilot | [![The Daily Repository Chronicle](https://github.com/githubnext/gh-aw/actions/workflows/daily-repo-chronicle.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/daily-repo-chronicle.lock.yml) | `0 16 * * 1-5` | - |
 | [The Great Escapi](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/firewall-escape.md) | copilot | [![The Great Escapi](https://github.com/githubnext/gh-aw/actions/workflows/firewall-escape.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/firewall-escape.lock.yml) | - | - |
 | [Tidy](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/tidy.md) | copilot | [![Tidy](https://github.com/githubnext/gh-aw/actions/workflows/tidy.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/tidy.lock.yml) | `0 7 * * *` | - |
diff --git a/docs/src/content/docs/guides/upgrading.md b/docs/src/content/docs/guides/upgrading.md
new file mode 100644
index 00000000000..47e210fd5fa
--- /dev/null
+++ b/docs/src/content/docs/guides/upgrading.md
@@ -0,0 +1,595 @@
+---
+title: Upgrading Agentic Workflows
+description: Step-by-step guide to upgrade your repository to the latest version of agentic workflows, including updating extensions, applying codemods, and validating changes.
+sidebar:
+  order: 100
+---
+
+This guide walks you through upgrading your agentic workflows to the latest version, ensuring you have access to the newest features, improvements, and security fixes.
+
+## Overview
+
+The upgrade process updates two key areas:
+
+1. **Agent and prompt files** — GitHub Copilot instructions, dispatcher agent, and workflow creation prompts
+2. **Workflow syntax** — Automatically migrates deprecated fields and applies the latest configuration patterns
+
+> [!TIP]
+> Quick Upgrade
+>
+> For most users, upgrading is a single command:
+> ```bash wrap
+> gh aw upgrade
+> ```
+> This updates agent files and applies codemods to all workflows.
+
+## Prerequisites
+
+Before upgrading, ensure you have:
+
+- ✅ **GitHub CLI** (`gh`) v2.0.0 or higher — Check with `gh --version`
+- ✅ **Latest gh-aw extension** — Upgrade with `gh extension upgrade gh-aw`
+- ✅ **Git repository** with agentic workflows initialized (`.github/workflows/*.md` files exist)
+- ✅ **Write access** to the repository to commit changes
+- ✅ **Clean working directory** — Commit or stash any uncommitted changes
+
+**Verify your setup:**
+
+```bash wrap
+gh --version                      # Should show 2.0.0+
+gh extension list | grep gh-aw    # Should show gh-aw extension
+git status                        # Should show "working tree clean"
+```
+
+## Step 1: Upgrade the Extension
+
+Before upgrading workflows, ensure you have the latest version of the `gh-aw` extension:
+
+```bash wrap
+gh extension upgrade gh-aw
+```
+
+This downloads and installs the latest release with new features, bug fixes, and updated codemods.
+
+> [!NOTE]
+> Check Current Version
+>
+> Run `gh aw version` to see your current version.
+> Compare against the [latest release](https://github.com/githubnext/gh-aw/releases) to confirm you're up to date.
+
+### Alternative: Clean Reinstall
+
+If you encounter issues with the upgrade, try a clean reinstall:
+
+```bash wrap
+gh extension remove gh-aw
+gh extension install githubnext/gh-aw
+gh aw version    # Verify installation
+```
+
+## Step 2: Backup Your Workflows
+
+Before making changes, create a backup of your workflows to easily revert if needed:
+
+```bash wrap
+# Create a backup branch
+git checkout -b backup-before-upgrade
+
+# Or create a backup directory
+cp -r .github/workflows .github/workflows.backup
+```
+
+Alternatively, ensure your latest changes are committed and pushed to a remote branch:
+
+```bash wrap
+git add .
+git commit -m "Pre-upgrade snapshot"
+git push origin main
+```
+
+> [!TIP]
+> Git History
+>
+> Since workflows are tracked in Git, you can always view or revert changes using:
+> ```bash wrap
+> git diff HEAD~1 .github/workflows/    # See what changed
+> git checkout HEAD~1 -- .github/workflows/my-workflow.md  # Revert single file
+> ```
+
+## Step 3: Run the Upgrade Command
+
+Run the upgrade command from your repository root:
+
+```bash wrap
+gh aw upgrade
+```
+
+This command performs two main operations:
+
+### 3.1 Updates Agent and Prompt Files
+
+The upgrade updates these files to the latest templates (similar to running `gh aw init`):
+
+- `.github/aw/github-agentic-workflows.md` — GitHub Copilot custom instructions
+- `.github/agents/agentic-workflows.agent.md` — Dispatcher agent for routing tasks
+- `.github/aw/create-agentic-workflow.md` — Prompt for creating new workflows
+- `.github/aw/update-agentic-workflow.md` — Prompt for updating existing workflows
+- `.github/aw/create-shared-agentic-workflow.md` — Prompt for shared workflows
+- `.github/aw/debug-agentic-workflow.md` — Prompt for debugging workflows
+- `.github/aw/upgrade-agentic-workflows.md` — Prompt for upgrade guidance
+
+### 3.2 Applies Codemods to All Workflows
+
+The upgrade automatically applies codemods to fix deprecated fields in all workflow files (`.github/workflows/*.md`):
+
+| Codemod | What It Fixes | Example |
+|---------|---------------|---------|
+| **timeout-minutes-migration** | Replaces `timeout_minutes` with `timeout-minutes` | `timeout_minutes: 30` → `timeout-minutes: 30` |
+| **network-firewall-migration** | Removes deprecated `network.firewall` field | Deletes `firewall: mandatory` |
+| **sandbox-agent-false-removal** | Removes `sandbox.agent: false` (firewall now mandatory) | Deletes `agent: false` |
+| **safe-inputs-mode-removal** | Removes deprecated `safe-inputs.mode` field | Deletes `mode: auto` |
+| **schedule-at-to-around-migration** | Converts `daily at TIME` to `daily around TIME` | `daily at 10:00` → `daily around 10:00` |
+| **delete-schema-file** | Deletes deprecated schema file | Removes `.github/aw/schemas/agentic-workflow.json` |
+| **delete-old-agents** | Deletes old `.agent.md` files moved to `.github/aw/` | Removes outdated agent files |
+
+**Example output:**
+
+```text
+Updating agent and prompt files...
+✓ Updated agent and prompt files
+Applying codemods to all workflows...
+Processing workflow: daily-team-status
+  ✓ Applied schedule-at-to-around-migration
+  ✓ Applied timeout-minutes-migration
+Processing workflow: issue-triage
+  ✓ Applied safe-inputs-mode-removal
+All workflows processed.
+
+✓ Upgrade complete
+```
+
+### Command Options
+
+```bash wrap
+# Standard upgrade (updates agent files + applies codemods)
+gh aw upgrade
+
+# Verbose output (shows detailed progress)
+gh aw upgrade -v
+
+# Update agent files only (skip codemods)
+gh aw upgrade --no-fix
+
+# Upgrade workflows in custom directory
+gh aw upgrade --dir custom/workflows
+```
+
+> [!WARNING]
+> Custom Workflow Directory
+>
+> If you're using a custom workflow directory (not `.github/workflows`), always specify it with `--dir`:
+> ```bash wrap
+> gh aw upgrade --dir path/to/workflows
+> ```
+
+## Step 4: Review the Changes
+
+After upgrading, carefully review all changes before committing:
+
+### Check Modified Files
+
+```bash wrap
+# View all modified files
+git status
+
+# See what changed in each file
+git diff .github/workflows/
+git diff .github/aw/
+git diff .github/agents/
+```
+
+### Review Codemod Changes
+
+Focus on workflow files (`.md`) to verify codemods applied correctly:
+
+```bash wrap
+# Review specific workflow changes
+git diff .github/workflows/my-workflow.md
+
+# Check all workflow changes
+git diff .github/workflows/*.md
+```
+
+**What to verify:**
+
+- ✅ Deprecated fields are removed or updated
+- ✅ Formatting and comments are preserved
+- ✅ No unintended changes to workflow logic
+- ✅ YAML frontmatter syntax remains valid
+
+### Common Changes to Expect
+
+**Before upgrade:**
+```yaml wrap
+---
+on:
+  schedule: daily at 09:00
+timeout_minutes: 45
+network:
+  firewall: mandatory
+safe-inputs:
+  mode: auto
+---
+```
+
+**After upgrade:**
+```yaml wrap
+---
+on:
+  schedule: daily around 09:00
+timeout-minutes: 45
+network: defaults
+safe-inputs:
+  allowed-commands: ["gh", "git"]
+---
+```
+
+> [!TIP]
+> Detailed Comparison
+>
+> Use `git diff --word-diff` to see changes highlighted at the word level:
+> ```bash wrap
+> git diff --word-diff .github/workflows/my-workflow.md
+> ```
+
+## Step 5: Compile and Validate
+
+Compile your workflows to ensure they're valid and generate updated `.lock.yml` files:
+
+```bash wrap
+# Compile all workflows
+gh aw compile
+
+# Compile with validation
+gh aw compile --validate
+
+# Compile specific workflow
+gh aw compile my-workflow
+```
+
+**Expected output:**
+
+```text
+✓ Compiled daily-team-status
+✓ Compiled issue-triage
+✓ Compiled security-scanner
+All workflows compiled successfully.
+```
+
+### Troubleshooting Compilation Errors
+
+If compilation fails, the error message will indicate the issue:
+
+```bash wrap
+# See detailed validation errors
+gh aw compile my-workflow --validate
+```
+
+**Common issues and fixes:**
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `Invalid frontmatter YAML` | Syntax error in YAML | Check YAML indentation and structure |
+| `Unknown field: X` | Deprecated field not migrated | Run `gh aw fix my-workflow --write` |
+| `Missing required field: Y` | Required configuration missing | Add missing field to frontmatter |
+| `Invalid schedule syntax` | Incorrect schedule format | Use [schedule syntax](/gh-aw/reference/schedule-syntax/) |
+
+> [!NOTE]
+> Automatic Fixes
+>
+> If you still have deprecated fields after upgrading, manually apply codemods:
+> ```bash wrap
+> gh aw fix my-workflow --write    # Fix specific workflow
+> gh aw fix --write                # Fix all workflows
+> ```
+
+## Step 6: Test Your Workflows
+
+Before pushing changes, test your workflows to ensure they work correctly:
+
+### Local Validation
+
+```bash wrap
+# Check workflow status
+gh aw status
+
+# Validate specific workflow
+gh aw compile my-workflow --validate
+```
+
+### Test Workflow Execution
+
+Trigger a workflow manually to verify it runs successfully:
+
+```bash wrap
+# Trigger workflow (requires workflow_dispatch)
+gh aw run my-workflow
+
+# Trigger and push changes in one command
+gh aw run my-workflow --push
+```
+
+**Wait for completion:**
+
+```bash wrap
+# Monitor workflow status
+gh aw status
+
+# View execution logs
+gh aw logs my-workflow
+```
+
+### Verify MCP Configuration (if using MCP servers)
+
+If your workflows use MCP servers, verify the configuration:
+
+```bash wrap
+# List workflows with MCP servers
+gh aw mcp list
+
+# Inspect specific workflow's MCP configuration
+gh aw mcp inspect my-workflow
+```
+
+> [!TIP]
+> Test in Draft PR
+>
+> Create a draft pull request to test workflows in CI before merging:
+> ```bash wrap
+> git checkout -b upgrade-workflows
+> git add .
+> git commit -m "Upgrade workflows to latest version"
+> git push origin upgrade-workflows
+> gh pr create --draft --title "Upgrade workflows" --body "Testing upgraded workflows"
+> ```
+
+## Step 7: Commit and Push Changes
+
+Once you've reviewed and tested the changes, commit them to your repository:
+
+```bash wrap
+# Stage all changes
+git add .github/workflows/ .github/aw/ .github/agents/
+
+# Create a descriptive commit message
+git commit -m "Upgrade agentic workflows to latest version
+
+- Updated agent and prompt files
+- Applied codemods to migrate deprecated fields
+- Recompiled all workflows"
+
+# Push to remote repository
+git push origin main
+```
+
+### Recommended Commit Structure
+
+For better traceability, consider separate commits for different types of changes:
+
+```bash wrap
+# Commit 1: Agent file updates
+git add .github/aw/ .github/agents/
+git commit -m "Update agent and prompt files to latest templates"
+
+# Commit 2: Workflow migrations
+git add .github/workflows/*.md
+git commit -m "Apply codemods to migrate deprecated workflow fields"
+
+# Commit 3: Recompiled lock files
+git add .github/workflows/*.lock.yml
+git commit -m "Recompile workflows after upgrade"
+
+# Push all commits
+git push origin main
+```
+
+> [!CAUTION]
+> Lock Files Must Be Committed
+>
+> Always commit both `.md` and `.lock.yml` files together. The `.lock.yml` files are the actual workflows GitHub Actions runs.
+> Never add `.lock.yml` to `.gitignore`.
+
+## Troubleshooting Common Issues
+
+### Extension Upgrade Fails
+
+**Symptom:** `gh extension upgrade gh-aw` fails with permission or network errors.
+
+**Solutions:**
+
+```bash wrap
+# Try clean reinstall
+gh extension remove gh-aw
+gh extension install githubnext/gh-aw
+
+# Or use standalone installer
+curl -sL https://raw.githubusercontent.com/githubnext/gh-aw/main/install-gh-aw.sh | bash
+```
+
+### Codemods Not Applied
+
+**Symptom:** Deprecated fields still present after running `gh aw upgrade`.
+
+**Solution:**
+
+```bash wrap
+# List available codemods
+gh aw fix --list-codemods
+
+# Manually apply codemods with verbose output
+gh aw fix --write -v
+
+# Check specific workflow
+gh aw fix my-workflow --write -v
+```
+
+### Compilation Errors After Upgrade
+
+**Symptom:** `gh aw compile` fails with validation errors.
+
+**Solution:**
+
+```bash wrap
+# See detailed error messages
+gh aw compile my-workflow --validate
+
+# Check for syntax errors
+cat .github/workflows/my-workflow.md
+
+# Verify YAML structure
+head -20 .github/workflows/my-workflow.md
+```
+
+### Workflows Not Running After Upgrade
+
+**Symptom:** Workflows don't trigger or execute after upgrading.
+
+**Solutions:**
+
+1. **Verify compilation:** Ensure `.lock.yml` files are up-to-date and committed
+   ```bash wrap
+   gh aw compile
+   git status  # Check if .lock.yml files are modified
+   ```
+
+2. **Check workflow status:** Ensure workflows are enabled
+   ```bash wrap
+   gh aw status
+   ```
+
+3. **Verify secrets:** Confirm AI engine tokens are still valid
+   ```bash wrap
+   gh aw secrets bootstrap --engine copilot
+   ```
+
+4. **Review workflow logs:** Check for execution errors
+   ```bash wrap
+   gh aw logs my-workflow
+   ```
+
+### Breaking Changes or Unexpected Behavior
+
+**Symptom:** Workflows behave differently after upgrade.
+
+**Solution:**
+
+```bash wrap
+# Revert to backup
+git checkout backup-before-upgrade
+
+# Or revert specific files
+git checkout HEAD~1 -- .github/workflows/my-workflow.md
+
+# Recompile after reverting
+gh aw compile
+```
+
+Then review [release notes](https://github.com/githubnext/gh-aw/releases) for breaking changes and migration guidance.
+
+## Advanced Topics
+
+### Upgrading Across Multiple Versions
+
+If you're upgrading from an older version (e.g., v0.0.x to v0.2.x), review the [changelog](https://github.com/githubnext/gh-aw/blob/main/CHANGELOG.md) for all intermediate versions to understand cumulative changes.
+
+### Custom Workflow Directory
+
+For repositories using custom workflow directories:
+
+```bash wrap
+# Upgrade custom directory
+gh aw upgrade --dir custom/workflows
+
+# Compile custom directory
+gh aw compile --dir custom/workflows
+```
+
+### Selective Codemod Application
+
+To apply specific codemods only:
+
+```bash wrap
+# Check what would be changed (dry-run)
+gh aw fix my-workflow
+
+# Apply specific workflow
+gh aw fix my-workflow --write
+
+# Skip codemods during upgrade
+gh aw upgrade --no-fix
+
+# Then manually fix specific workflows
+gh aw fix workflow-1 workflow-2 --write
+```
+
+### Upgrading in CI/CD Pipelines
+
+Automate upgrades in your CI/CD pipeline:
+
+```yaml wrap
+name: Upgrade Agentic Workflows
+on:
+  schedule:
+    - cron: '0 0 * * MON'  # Weekly on Monday
+  workflow_dispatch:
+
+jobs:
+  upgrade:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Install gh-aw
+        run: gh extension install githubnext/gh-aw
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      
+      - name: Upgrade workflows
+        run: gh aw upgrade
+      
+      - name: Compile workflows
+        run: gh aw compile
+      
+      - name: Create Pull Request
+        uses: peter-evans/create-pull-request@v6
+        with:
+          commit-message: 'Automated upgrade of agentic workflows'
+          title: 'Upgrade agentic workflows'
+          branch: automated-upgrade
+          labels: automation, upgrade
+```
+
+> [!WARNING]
+> Review Automated Upgrades
+>
+> Always review automated upgrade PRs before merging to catch any unexpected changes or breaking updates.
+
+## Best Practices
+
+- ✅ **Upgrade regularly** — Stay current with latest features and security fixes
+- ✅ **Review changes** — Always inspect diffs before committing
+- ✅ **Test workflows** — Trigger manual runs to verify functionality
+- ✅ **Read release notes** — Understand what changed in each version
+- ✅ **Keep backups** — Use Git branches or tags for easy rollback
+- ✅ **Update extension** — Upgrade `gh aw` before upgrading workflows
+
+## What's Next?
+
+After upgrading your workflows:
+
+- **Learn about new features** — Check the [changelog](https://github.com/githubnext/gh-aw/blob/main/CHANGELOG.md) for what's new
+- **Explore advanced configuration** — See the [frontmatter reference](/gh-aw/reference/frontmatter-full/)
+- **Optimize workflow performance** — Review [best practices](/gh-aw/guides/deterministic-agentic-patterns/)
+- **Add new workflows** — Browse the [agentics collection](https://github.com/githubnext/agentics)
+
+Need help? Check the [troubleshooting guide](/gh-aw/troubleshooting/common-issues/) or [open an issue](https://github.com/githubnext/gh-aw/issues/new).

From 0bb30d6656991281d277073cd7e28b43e3979076 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Thu, 22 Jan 2026 01:12:42 +0000
Subject: [PATCH 3/3] Update upgrade guide to reflect automatic workflow
 compilation

- Document that upgrade command now compiles workflows automatically
- Update overview to mention 3 key areas (added compilation)
- Clarify that compilation step is now part of upgrade command
- Update all command examples to reflect compilation is included
- Add new Step 6 for reviewing generated lock files
- Renumber subsequent steps (Step 7: Test, Step 8: Commit)
- Remove redundant compile step from CI/CD example
- Add notes about --no-fix skipping both codemods and compilation
- Update troubleshooting sections to reflect automatic compilation

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
---
 docs/src/content/docs/guides/upgrading.md | 94 ++++++++++++++++-------
 1 file changed, 66 insertions(+), 28 deletions(-)

diff --git a/docs/src/content/docs/guides/upgrading.md b/docs/src/content/docs/guides/upgrading.md
index 47e210fd5fa..7b4a6e08b29 100644
--- a/docs/src/content/docs/guides/upgrading.md
+++ b/docs/src/content/docs/guides/upgrading.md
@@ -1,6 +1,6 @@
 ---
 title: Upgrading Agentic Workflows
-description: Step-by-step guide to upgrade your repository to the latest version of agentic workflows, including updating extensions, applying codemods, and validating changes.
+description: Step-by-step guide to upgrade your repository to the latest version of agentic workflows, including updating extensions, applying codemods, compiling workflows, and validating changes.
 sidebar:
   order: 100
 ---
@@ -9,10 +9,11 @@ This guide walks you through upgrading your agentic workflows to the latest vers
 
 ## Overview
 
-The upgrade process updates two key areas:
+The upgrade process updates three key areas:
 
 1. **Agent and prompt files** — GitHub Copilot instructions, dispatcher agent, and workflow creation prompts
 2. **Workflow syntax** — Automatically migrates deprecated fields and applies the latest configuration patterns
+3. **Workflow compilation** — Automatically compiles all workflows to generate up-to-date `.lock.yml` files
 
 > [!TIP]
 > Quick Upgrade
@@ -21,7 +22,7 @@ The upgrade process updates two key areas:
 > ```bash wrap
 > gh aw upgrade
 > ```
-> This updates agent files and applies codemods to all workflows.
+> This updates agent files, applies codemods, and compiles all workflows.
 
 ## Prerequisites
 
@@ -104,7 +105,7 @@ Run the upgrade command from your repository root:
 gh aw upgrade
 ```
 
-This command performs two main operations:
+This command performs three main operations:
 
 ### 3.1 Updates Agent and Prompt Files
 
@@ -132,6 +133,10 @@ The upgrade automatically applies codemods to fix deprecated fields in all workf
 | **delete-schema-file** | Deletes deprecated schema file | Removes `.github/aw/schemas/agentic-workflow.json` |
 | **delete-old-agents** | Deletes old `.agent.md` files moved to `.github/aw/` | Removes outdated agent files |
 
+### 3.3 Compiles All Workflows
+
+The upgrade automatically compiles all workflows to generate or update `.lock.yml` files, ensuring they're ready to run in GitHub Actions.
+
 **Example output:**
 
 ```text
@@ -144,6 +149,8 @@ Processing workflow: daily-team-status
 Processing workflow: issue-triage
   ✓ Applied safe-inputs-mode-removal
 All workflows processed.
+Compiling all workflows...
+✓ Compiled 3 workflow(s)
 
 ✓ Upgrade complete
 ```
@@ -151,13 +158,13 @@ All workflows processed.
 ### Command Options
 
 ```bash wrap
-# Standard upgrade (updates agent files + applies codemods)
+# Standard upgrade (updates agent files + applies codemods + compiles workflows)
 gh aw upgrade
 
 # Verbose output (shows detailed progress)
 gh aw upgrade -v
 
-# Update agent files only (skip codemods)
+# Update agent files only (skip codemods and compilation)
 gh aw upgrade --no-fix
 
 # Upgrade workflows in custom directory
@@ -242,22 +249,22 @@ safe-inputs:
 > git diff --word-diff .github/workflows/my-workflow.md
 > ```
 
-## Step 5: Compile and Validate
+## Step 5: Verify Compilation
 
-Compile your workflows to ensure they're valid and generate updated `.lock.yml` files:
+The `gh aw upgrade` command automatically compiles all workflows, so you typically don't need to run `gh aw compile` separately. However, if you want to verify compilation or recompile specific workflows:
 
 ```bash wrap
-# Compile all workflows
+# Verify all workflows compiled successfully (optional)
 gh aw compile
 
-# Compile with validation
+# Compile with additional validation
 gh aw compile --validate
 
-# Compile specific workflow
+# Recompile specific workflow
 gh aw compile my-workflow
 ```
 
-**Expected output:**
+**Expected output (if running compile again):**
 
 ```text
 ✓ Compiled daily-team-status
@@ -268,10 +275,10 @@ All workflows compiled successfully.
 
 ### Troubleshooting Compilation Errors
 
-If compilation fails, the error message will indicate the issue:
+If the upgrade command shows compilation warnings or you want more detailed validation:
 
 ```bash wrap
-# See detailed validation errors
+# See detailed validation errors for a specific workflow
 gh aw compile my-workflow --validate
 ```
 
@@ -293,7 +300,31 @@ gh aw compile my-workflow --validate
 > gh aw fix --write                # Fix all workflows
 > ```
 
-## Step 6: Test Your Workflows
+## Step 6: Review Generated Lock Files
+
+After the upgrade compiles your workflows, review the generated or updated `.lock.yml` files:
+
+```bash wrap
+# Check that lock files were generated/updated
+git status | grep .lock.yml
+
+# Review changes to lock files
+git diff .github/workflows/*.lock.yml
+```
+
+**What to verify:**
+
+- ✅ Each `.md` workflow has a corresponding `.lock.yml` file
+- ✅ Lock files are tracked in Git (not in `.gitignore`)
+- ✅ Lock files contain GitHub Actions YAML syntax
+- ✅ No obvious errors in the generated workflow structure
+
+> [!CAUTION]
+> Never Edit Lock Files Directly
+>
+> `.lock.yml` files are auto-generated. Always edit the `.md` file and recompile with `gh aw compile`.
+
+## Step 7: Test Your Workflows
 
 Before pushing changes, test your workflows to ensure they work correctly:
 
@@ -353,7 +384,7 @@ gh aw mcp inspect my-workflow
 > gh pr create --draft --title "Upgrade workflows" --body "Testing upgraded workflows"
 > ```
 
-## Step 7: Commit and Push Changes
+## Step 8: Commit and Push Changes
 
 Once you've reviewed and tested the changes, commit them to your repository:
 
@@ -433,23 +464,31 @@ gh aw fix --write -v
 gh aw fix my-workflow --write -v
 ```
 
-### Compilation Errors After Upgrade
+### Compilation Errors During Upgrade
 
-**Symptom:** `gh aw compile` fails with validation errors.
+**Symptom:** The upgrade command shows compilation warnings or errors.
 
 **Solution:**
 
 ```bash wrap
-# See detailed error messages
+# Review detailed error messages
 gh aw compile my-workflow --validate
 
-# Check for syntax errors
+# Check for syntax errors in the source file
 cat .github/workflows/my-workflow.md
 
 # Verify YAML structure
 head -20 .github/workflows/my-workflow.md
+
+# Fix the workflow and recompile
+gh aw compile my-workflow
 ```
 
+> [!NOTE]
+> Non-Critical Compilation Errors
+>
+> The upgrade command treats compilation errors as warnings and continues. Review any warnings and fix issues in the source `.md` files before committing.
+
 ### Workflows Not Running After Upgrade
 
 **Symptom:** Workflows don't trigger or execute after upgrading.
@@ -458,8 +497,9 @@ head -20 .github/workflows/my-workflow.md
 
 1. **Verify compilation:** Ensure `.lock.yml` files are up-to-date and committed
    ```bash wrap
-   gh aw compile
-   git status  # Check if .lock.yml files are modified
+   git status  # Check if .lock.yml files were updated
+   git add .github/workflows/*.lock.yml
+   git commit -m "Update compiled workflow lock files"
    ```
 
 2. **Check workflow status:** Ensure workflows are enabled
@@ -507,10 +547,10 @@ If you're upgrading from an older version (e.g., v0.0.x to v0.2.x), review the [
 For repositories using custom workflow directories:
 
 ```bash wrap
-# Upgrade custom directory
+# Upgrade custom directory (includes compilation)
 gh aw upgrade --dir custom/workflows
 
-# Compile custom directory
+# Verify or recompile specific workflows if needed
 gh aw compile --dir custom/workflows
 ```
 
@@ -528,8 +568,9 @@ gh aw fix my-workflow --write
 # Skip codemods during upgrade
 gh aw upgrade --no-fix
 
-# Then manually fix specific workflows
+# Then manually fix and compile specific workflows
 gh aw fix workflow-1 workflow-2 --write
+gh aw compile workflow-1 workflow-2
 ```
 
 ### Upgrading in CI/CD Pipelines
@@ -557,9 +598,6 @@ jobs:
       - name: Upgrade workflows
         run: gh aw upgrade
       
-      - name: Compile workflows
-        run: gh aw compile
-      
       - name: Create Pull Request
         uses: peter-evans/create-pull-request@v6
         with: