Add maintainer workflow for automated gh-aw upgrades

README.md

@@ -27,6 +27,9 @@ A sample family of reusable [GitHub Agentic Workflows](https://githubnext.github
 - [🧪 Daily Test Coverage Improver](docs/daily-test-improver.md) - Improve test coverage by adding meaningful tests to under-tested areas
 - [⚡ Daily Performance Improver](docs/daily-perf-improver.md) - Analyze and improve code performance through benchmarking and optimization
 
+### Maintenance Workflows
+- [🔧 Maintainer](docs/maintainer.md) - Upgrade workflows to the latest version of gh-aw
+
 > [!WARNING] The workflows that help with coding tasks should be installed with caution and used only experimentally, then disabled. While the tasks are executed within GitHub Actions and have no access to secrets, they still operate in an environment where outward network requests are allowed. This means untrusted inputs such as issue descriptions, comments, and code could potentially be exploited to direct the models to access external content that in turn could be malicious. Pull requests and other outputs must be reviewed very carefully before merging.
 
 ## 💬 Share Feedback

docs/maintainer.md

@@ -0,0 +1,86 @@
+# 🔧 Maintainer Workflow
+
+> For an overview of all available workflows, see the [main README](../README.md).
+
+The [maintainer workflow](../workflows/maintainer.md?plain=1) helps keep your agentic workflows up to date by automatically upgrading them to the latest version of gh-aw. It fetches the latest changes from the gh-aw repository, attempts to recompile all workflows, and either creates a pull request with the updates or an issue if compilation errors occur.
+
+## Installation
+
+```bash
+# Install the 'gh aw' extension
+gh extension install githubnext/gh-aw
+
+# Add the Maintainer workflow to your repository
+gh aw add githubnext/agentics/maintainer --pr
+```
+
+This creates a pull request to add the workflow to your repository. After merging the PR and syncing to main, you can start a run of this workflow immediately by running:
+
+```bash
+gh aw run maintainer
+```
+
+**Mandatory Checklist**
+
+* [ ] I am a repository admin or have sufficient permissions, and am happy for the safe-outputs portion of this workflow to create pull requests or issues in the repository.
+
+* [ ] I have enabled "Allow GitHub Actions to create and approve pull requests" in the repository settings under "Actions > General"
+
+* [ ] If in a fork, I have enabled "GitHub Actions" and "GitHub Issues" in the fork repository settings
+
+* [ ] I will review all pull requests very carefully and monitor the repository.
+
+## What it does
+
+1. **Fetches latest gh-aw changes**: Retrieves the CHANGELOG.md or release notes from the `githubnext/gh-aw` repository to understand new features, breaking changes, and migration instructions.
+
+2. **Installs latest gh-aw**: Upgrades the gh-aw CLI extension to the latest version using the GitHub token.
+
+3. **Attempts recompilation**: Tries to recompile all workflows in the `workflows/` directory with the new gh-aw version.
+
+4. **Fixes compilation errors**: If errors occur, analyzes them using the changelog and documentation, then attempts to fix the workflow files.
+
+5. **Creates outputs**:
+   - **Success**: Creates a pull request with upgraded workflows and any necessary fixes
+   - **Failure**: Creates an issue documenting the compilation errors and attempted fixes
+
+## Configuration
+
+This workflow requires no configuration and works out of the box. It will process all workflow markdown files in the `workflows/` directory.
+
+## What it reads from GitHub
+
+- Repository contents and workflow files
+- CHANGELOG.md from the `githubnext/gh-aw` repository
+- Release information and documentation from gh-aw
+
+## What it creates
+
+- Creates pull requests with upgraded workflows (if successful)
+- Creates issues documenting upgrade failures (if compilation errors persist)
+- Makes file changes to workflow files to fix compatibility issues
+- May generate `.lock.yml` files during compilation
+- Uses `permissions: read-all` with `safe-outputs` mechanism for controlled write operations (PRs and issues)
+
+## Human in the loop
+
+- Review pull requests created by this workflow to understand what changed
+- Test the upgraded workflows before merging
+- Investigate issues created by the workflow if compilation fails
+- Manually fix complex migration issues that the workflow couldn't handle
+- Disable or uninstall the workflow if not needed regularly
+
+## When to run
+
+- Run this workflow when you know a new version of gh-aw has been released
+- Run it periodically (e.g., monthly) to stay up to date
+- Run it before making other workflow changes to ensure compatibility
+- Trigger manually via workflow_dispatch when needed
+
+## Troubleshooting
+
+If the workflow creates an issue instead of a PR:
+1. Review the issue to understand what compilation errors occurred
+2. Check the gh-aw changelog for migration instructions
+3. Manually update the affected workflows based on the guidance
+4. Re-run the maintainer workflow to verify the fixes work

workflows/maintainer.md

@@ -0,0 +1,76 @@
+---
+on:
+  workflow_dispatch:
+
+permissions: read-all
+
+network: defaults
+
+safe-outputs:
+  create-pull-request:
+    draft: false
+  create-issue:
+    title-prefix: "${{ github.workflow }}"
+
+tools:
+  github:
+    toolset: [all]
+    edit: true
+  web-fetch:
+  bash: [ ":*" ]
+
+timeout_minutes: 30
+
+---
+
+# Agentic Workflow Maintainer
+
+Your name is "${{ github.workflow }}". Your job is to upgrade the workflows in the GitHub repository `${{ github.repository }}` to the latest version of gh-aw.
+
+## Steps to follow:
+
+1. **Fetch the latest gh-aw changes**: 
+   - Use the GitHub tools to fetch the CHANGELOG.md or release notes from the `githubnext/gh-aw` repository
+   - Review and understand the interesting changes, breaking changes, and new features in the latest version
+   - Pay special attention to any migration guides or upgrade instructions
+
+2. **Install the latest gh-aw CLI extension**:
+   - Run `gh extension install githubnext/gh-aw || gh extension upgrade githubnext/gh-aw` to install or upgrade to the latest version
+   - Verify the installation by running `gh aw version` to check the current version
+
+3. **Check the current workflows**:
+   - List all workflow markdown files in the `workflows/` directory
+   - Understand which workflows need to be compiled
+
+4. **Attempt to recompile the workflows**:
+   - Clean up any existing `.lock.yml` files: `find workflows -name "*.lock.yml" -type f -delete`
+   - Run `gh aw compile --validate` on each workflow file in the `workflows/` directory
+   - Note any compilation errors or warnings
+
+5. **Fix compilation errors if they occur**:
+   - If there are compilation errors, analyze them carefully
+   - Review the gh-aw changelog and new documentation you fetched earlier
+   - Identify what changes are needed in the workflow files to make them compatible with the new version
+   - Make the necessary changes to the workflow markdown files to fix the errors
+   - Re-run `gh aw compile --validate` to verify the fixes work
+   - Iterate until all workflows compile successfully or you've exhausted reasonable fix attempts
+
+6. **Create appropriate outputs**:
+   - **If all workflows compile successfully**: Create a pull request with the title "Upgrade workflows to latest gh-aw version" containing:
+     - All updated workflow files
+     - Any generated `.lock.yml` files
+     - A detailed description of what changed, referencing the gh-aw changelog
+     - A summary of any manual fixes that were needed
+
+   - **If there are compilation errors you cannot fix**: Create an issue with the title "Failed to upgrade workflows to latest gh-aw version" containing:
+     - The specific compilation errors you encountered
+     - What you tried to fix them
+     - Links to relevant sections of the gh-aw changelog or documentation
+     - The version of gh-aw you were trying to upgrade to
+
+## Important notes:
+- Always check the gh-aw changelog first to understand breaking changes
+- Test each fix by running `gh aw compile --validate` before moving to the next error
+- Include context and reasoning in your PR or issue descriptions
+- If you create a PR, make sure it includes all necessary changes for the workflows to compile
+