githubnext · dsyme · Sep 1, 2025 · Sep 1, 2025 · Sep 1, 2025
diff --git a/README.md b/README.md
@@ -3,24 +3,27 @@
 A sample family of reusable [GitHub Agentic Workflows](https://github.com/githubnext/gh-aw?tab=readme-ov-file).
 
 > [!WARNING]
-> GitHub Agentic Workflows are a research demonstrator, and these workflows are samples only.
+> GitHub Agentic Workflows are a research demonstrator, and these workflows are demonstrator samples only. They are not intended for production use. Use at your own risk.
 
 ## 📂 Available Workflows
 
-### Research & Planning Workflows
+### Research, Status & Planning Workflows
 - [📚 Weekly Research](docs/weekly-research.md) - Collect research updates and industry trends
 - [👥 Daily Team Status](docs/daily-team-status.md) - Assess repository activity and create status reports
 - [📋 Daily Plan](docs/daily-plan.md) - Update planning issues for team coordination
+
+### Depth Triage & Analysis Workflows
 - [🏷️ Issue Triage](docs/issue-triage.md) - Triage issues and pull requests
+- [🏥 CI Doctor](docs/ci-doctor.md) - Monitor CI workflows and investigate failures automatically
+- [🔍 Daily Accessibility Review](docs/daily-accessibility-review.md) - Review application accessibility by automatically running and using the application
 
 ### Coding & Development Workflows
-- [🏥 CI Doctor](docs/ci-doctor.md) - Monitor CI workflows and investigate failures automatically
 - [📦 Daily Dependency Updater](docs/daily-dependency-updates.md) - Update dependencies and create pull requests
 - [📖 Regular Documentation Update](docs/update-docs.md) - Update documentation automatically
-- [🔍 Daily Adhoc QA](docs/daily-qa.md) - Perform "soft", explorative quality assurance tasks
+- [🏥 PR Fix](docs/pr-fix.md) - Analyze failing CI checks and implement fixes for pull requests
+- [🔎 Daily Adhoc QA](docs/daily-qa.md) - Perform adhoc explorative quality assurance tasks
 - [🧪 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
-- [🔍 Daily Accessibility Review](docs/daily-accessibility-review.md) - Review application accessibility by automatically running and using the application
 
 ## 💻 Coding Tasks Warning
 

diff --git a/docs/daily-dependency-updates.md b/docs/daily-dependency-updates.md
@@ -16,19 +16,25 @@ This creates a pull request to add the workflow to your repository. After mergin
 gh aw run daily-dependency-updates
 ```
 
+❗IMPORTANT: GitHub Actions runs will **not** trigger on commits pushed by this workflow and will **not** tell you that CI has not been run unless you have enabled a specific custom check for this condition. **You must open/close the PR or hit "Update branch" if offered to trigger CI.Yes it's painful and yes it's just something you need to be aware of.
+
 **Checklist**
 
-* [ ] See notes on coding tasks in the [main README](../README.md). 
+* [ ] I have read the notes on coding tasks in the [main README](../README.md) and understand the implications.
+
+* [ ] I am a repository admin or have sufficient permissions, and am happy for this workflow to push new branches to the repository.
+
+* [ ] I have enabled "Allow GitHub Actions to create and approve pull requests" in the repository settings under "Actions > General"
 
-* [ ] Enable "Allow GitHub Actions to create and approve pull requests" in the repository settings under "Actions > General"
+* [ ] I have considered enabling "Always suggest updating pull request branches" in the repository settings
 
-* [ ] Recommend enabling  "Always suggest updating pull request branches" in the repository settings
+* [ ] If in a fork, I have enabled "GitHub Actions" and "GitHub Issues" in the fork repository settings
 
-* [ ] If in a fork, enable "GitHub Actions" and "GitHub Issues" in the fork project settings
+* [ ] I will review all pull requests very carefully, and carefully monitor the repository. 
 
-* [ ] When a pull request is created, you must review the changes carefully. 
+* [ ] I will operate this demonstrator for a time-limited period only (the default is 48h). 
 
-* [ ] Understand that your GitHub Actions runs will **not** trigger on pull requests created by this workflow, or indeed any Actions-created PRs. You must open/close the PR or push a new commit to trigger CI checks. This is not indicated in the GitHub UI. It's just something you need to be aware of.
+* [ ] I understand that GitHub Actions runs will **not** trigger on pull requests created by this workflow, see above.
 
 ## Configuration
 

diff --git a/docs/daily-perf-improver.md b/docs/daily-perf-improver.md
@@ -22,19 +22,25 @@ To run continuously (at most one instance running at a time and sending a trigge
 gh aw run daily-perf-improver --repeat 180
 ```
 
+❗IMPORTANT: GitHub Actions runs will **not** trigger on commits pushed by this workflow and will **not** tell you that CI has not been run unless you have enabled a specific custom check for this condition. **You must open/close the PR or hit "Update branch" if offered to trigger CI.Yes it's painful and yes it's just something you need to be aware of.
+
 **Checklist**
 
-* [ ] See notes on coding tasks in the [main README](../README.md). 
+* [ ] I have read the notes on coding tasks in the [main README](../README.md) and understand the implications.
+
+* [ ] I am a repository admin or have sufficient permissions, and am happy for this workflow to push new branches to the repository.
+
+* [ ] I have enabled "Allow GitHub Actions to create and approve pull requests" in the repository settings under "Actions > General"
 
-* [ ] Enable "Allow GitHub Actions to create and approve pull requests" in the repository settings under "Actions > General"
+* [ ] I have considered enabling "Always suggest updating pull request branches" in the repository settings
 
-* [ ] Recommend enabling  "Always suggest updating pull request branches" in the repository settings
+* [ ] If in a fork, I have enabled "GitHub Actions" and "GitHub Issues" in the fork repository settings
 
-* [ ] If in a fork, enable "GitHub Actions" and "GitHub Issues" in the fork project settings
+* [ ] I will review all pull requests very carefully, and carefully monitor the repository. 
 
-* [ ] When a pull request is created, you must review the changes carefully. 
+* [ ] I will operate this demonstrator for a time-limited period only (the default is 48h). 
 
-* [ ] Understand that your GitHub Actions runs will **not** trigger on pull requests created by this workflow, or indeed any Actions-created PRs. You must open/close the PR or push a new commit to trigger CI checks. This is not indicated in the GitHub UI. It's just something you need to be aware of.
+* [ ] I understand that GitHub Actions runs will **not** trigger on pull requests created by this workflow, see above.
 
 ## Configuration
 

diff --git a/docs/daily-test-improver.md b/docs/daily-test-improver.md
@@ -16,19 +16,25 @@ This creates a pull request to add the workflow to your repository. After mergin
 gh aw run daily-test-improver
 ```
 
+❗IMPORTANT: GitHub Actions runs will **not** trigger on commits pushed by this workflow and will **not** tell you that CI has not been run unless you have enabled a specific custom check for this condition. **You must open/close the PR or hit "Update branch" if offered to trigger CI.Yes it's painful and yes it's just something you need to be aware of.
+
 **Checklist**
 
-* [ ] See notes on coding tasks in the [main README](../README.md). 
+* [ ] I have read the notes on coding tasks in the [main README](../README.md) and understand the implications.
+
+* [ ] I am a repository admin or have sufficient permissions, and am happy for this workflow to push new branches to the repository.
+
+* [ ] I have enabled "Allow GitHub Actions to create and approve pull requests" in the repository settings under "Actions > General"
 
-* [ ] Enable "Allow GitHub Actions to create and approve pull requests" in the repository settings under "Actions > General"
+* [ ] I have considered enabling "Always suggest updating pull request branches" in the repository settings
 
-* [ ] Recommend enabling  "Always suggest updating pull request branches" in the repository settings
+* [ ] If in a fork, I have enabled "GitHub Actions" and "GitHub Issues" in the fork repository settings
 
-* [ ] If in a fork, enable "GitHub Actions" and "GitHub Issues" in the fork project settings
+* [ ] I will review all pull requests very carefully, and carefully monitor the repository. 
 
-* [ ] When a pull request is created, you must review the changes carefully. 
+* [ ] I will operate this demonstrator for a time-limited period only (the default is 48h). 
 
-* [ ] Understand that your GitHub Actions runs will **not** trigger on pull requests created by this workflow, or indeed any Actions-created PRs. You must open/close the PR or push a new commit to trigger CI checks. This is not indicated in the GitHub UI. It's just something you need to be aware of.
+* [ ] I understand that GitHub Actions runs will **not** trigger on pull requests created by this workflow, see above.
 
 ## Configuration
 

diff --git a/docs/pr-fix.md b/docs/pr-fix.md
@@ -0,0 +1,97 @@
+# 🔧 PR Fix
+
+> For an overview of all available workflows, see the [main README](../README.md).
+
+The ["@pr-fix" workflow](../workflows/pr-fix.md?plain=1) is an alias workflow "@pr-fix" that will help you fix and complete pull requests. By default it will analyze failing CI checks in pull requests, identify root causes, and implement fixes to resolve issues and get PRs back to a passing state. 
+
+You can trigger the workflow in default mode by adding a comment to a pull request with the alias:
+
+```
+@pr-fix
+```
+
+or by writing a comment:
+
+```
+@pr-fix Please add more tests.
+```
+
+## Installation
+
+```bash
+gh aw add pr-fix -r githubnext/agentics --pr
+```
+
+This creates a pull request to add the workflow to your repository. You can't start a run of this workflow directly as it is triggered in the context of a pull request with failing checks.
+
+To trigger the workflow on a specific pull request, add a comment with the alias:
+
+```
+@pr-fix
+```
+
+IMPORTANT: GitHub Actions runs will **not** trigger on commits pushed by this workflow and will **not** tell you that CI has not been run unless you have enabled a specific custom check for this condition. **You must open/close the PR or hit "Update branch" if offered to trigger CI.Yes it's painful and yes it's just something you need to be aware of.
+
+**Checklist**
+
+* [ ] I have read the notes on coding tasks in the [main README](../README.md) and understand the implications.
+
+* [ ] I am a repository admin or have sufficient permissions, and am happy for this workflow to push new branches to the repository.
+
+* [ ] I have enabled "Allow GitHub Actions to create and approve pull requests" in the repository settings under "Actions > General"
+
+* [ ] I have considered enabling "Always suggest updating pull request branches" in the repository settings
+
+* [ ] 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 carefully monitor the repository. 
+
+* [ ] I will operate this demonstrator for a time-limited period only (the default is 48h). 
+
+* [ ] I understand that GitHub Actions runs will **not** trigger on pull requests created by this workflow, see above.
+
+## Configuration
+
+This workflow requires no configuration and works out of the box. However, you can customize it as follows:
+
+1. Use local configuration to specify custom build commands, testing procedures, linting rules, and code formatting standards. Local configuration can be done in `.github/workflows/agentics/pr-fix.config.md`.
+
+2. Build tool configuration for build tools shared across all workflows installed from this pack can be done in `.github/workflows/agentics/build-tools.md`. 
+
+After editing run `gh aw compile` to update the workflow and commit all changes to the default branch.
+
+## What it reads from GitHub
+
+- Pull request details, files, and metadata
+- Workflow run logs and job outputs
+- Check run results and status information
+- Commit information and diff context
+- Repository contents and file structure
+- Existing issues related to CI failures
+
+## What it creates
+
+- Pushes fixes directly to the pull request branch
+- Adds comments to pull requests explaining the changes made
+- May create issues for complex problems requiring human intervention
+- Requires `contents: write` and `pull-requests: write` permissions
+
+## What web searches it performs
+
+- Searches for error message documentation and solutions
+- Looks up best practices for specific technologies and frameworks
+- Researches common fixes for build and test failures
+
+## Human in the loop
+
+- Review all changes pushed by the workflow before merging the PR
+- Validate that fixes actually resolve the intended issues
+- Monitor for any unintended side effects or regressions
+- Provide additional context or instructions via PR comments when needed
+- Override or revert changes if the automated fix is incorrect
+
+## Activity duration
+
+- By default this workflow will run for up to 48 hours after being triggered
+- The workflow stops automatically after this period to prevent indefinite runs
+- You can re-trigger the workflow by commenting with the alias again if needed
diff --git a/docs/update-docs.md b/docs/update-docs.md
@@ -16,20 +16,25 @@ This creates a pull request to add the workflow to your repository. After mergin
 gh aw run update-docs
 ```
 
+❗IMPORTANT: GitHub Actions runs will **not** trigger on commits pushed by this workflow and will **not** tell you that CI has not been run unless you have enabled a specific custom check for this condition. **You must open/close the PR or hit "Update branch" if offered to trigger CI.Yes it's painful and yes it's just something you need to be aware of.
+
 **Checklist**
 
-* [ ] See notes on coding tasks in the [main README](../README.md). 
+* [ ] I have read the notes on coding tasks in the [main README](../README.md) and understand the implications.
+
+* [ ] I am a repository admin or have sufficient permissions, and am happy for this workflow to push new branches to the repository.
 
-* [ ] Enable "Allow GitHub Actions to create and approve pull requests" in the repository settings under "Actions > General"
+* [ ] I have enabled "Allow GitHub Actions to create and approve pull requests" in the repository settings under "Actions > General"
 
-* [ ] Recommend enabling  "Always suggest updating pull request branches" in the repository settings
+* [ ] I have considered enabling "Always suggest updating pull request branches" in the repository settings
 
-* [ ] If in a fork, enable "GitHub Actions" and "GitHub Issues" in the fork project settings
+* [ ] If in a fork, I have enabled "GitHub Actions" and "GitHub Issues" in the fork repository settings
 
-* [ ] When a pull request is created, you must review the changes carefully. 
+* [ ] I will review all pull requests very carefully, and carefully monitor the repository. 
 
-* [ ] Understand that your GitHub Actions runs will **not** trigger on pull requests created by this workflow, or indeed any Actions-created PRs. You must open/close the PR or push a new commit to trigger CI checks. This is not indicated in the GitHub UI. It's just something you need to be aware of.
+* [ ] I will operate this demonstrator for a time-limited period only (the default is 48h). 
 
+* [ ] I understand that GitHub Actions runs will **not** trigger on pull requests created by this workflow, see above.
 
 ## Configuration
 

diff --git a/workflows/agentics/shared/gh-extra-pr-tools.md b/workflows/agentics/shared/gh-extra-pr-tools.md
@@ -0,0 +1,20 @@
+---
+tools:
+  claude:
+    allowed:
+      Bash: 
+      - "git checkout:*"
+      - "git branch:*"
+      - "git add:*"
+      - "git commit:*"
+      - "git push:*"
+      - "gh pr create:*"
+---
+
+## Creating and Updating Pull Requests
+
+To create a branch, add changes to your branch and push code to GitHub, use Bash `git branch...` `git add ...`, `git commit ...`, `git push ...` etc.
+
+When using `git commit`, ensure you set the author name and email appropriately. Do this by using a `--author` flag with `git commit`, for example `git commit --author "${{ github.workflow }} <github-actions[bot]@users.noreply.github.com>" ...`.
+
+To create a pull request with the changes, use Bash `gh pr create --repo ${{ github.repository }} ...` 
diff --git a/workflows/agentics/shared/gh-extra-read-tools.md b/workflows/agentics/shared/gh-extra-read-tools.md
@@ -0,0 +1,26 @@
+---
+tools:
+  claude:
+    allowed:
+      Bash: 
+      - "gh label list:*"
+      - "gh label view:*"
+      - "gh repo view:*"
+      - "gh issue list:*"
+      - "gh issue view:*"
+      - "gh pr list:*"
+      - "gh pr view:*"
+---
+
+## GitHub Tools
+
+You can use the GitHub MCP tools to perform various tasks in the repository. You can also use the following `gh` command line invocations:
+
+- List labels: `gh label list ...`
+- View label: `gh label view <label-name> ...`
+- View repository: `gh repo view ${{ github.repository }} ...`
+- List issues: `gh issue list --label <label-name> ...`
+- View issue: `gh issue view <issue-number> ...`
+- List pull requests: `gh pr list --label <label-name> ...`
+- View pull request: `gh pr view <pr-number> ...`
+
diff --git a/workflows/agentics/shared/gh-extra-tools.md b/workflows/agentics/shared/gh-extra-tools.md
diff --git a/workflows/daily-dependency-updates.md b/workflows/daily-dependency-updates.md
@@ -37,7 +37,10 @@ tools:
       Write:
       WebFetch:
       WebSearch:
-      Bash: ["gh pr create:*", "git commit:*", "git push:*", "git checkout:*", "git branch:*", "git add:*", "gh auth status", "gh repo view","gh issue comment:*"]
+      # Configure bash build commands here, or in .github/workflows/agentics/daily-dependency-updates.config.md or .github/workflows/agentics/build-tools.md
+      Bash:
+      # For YOLO mode, uncomment the following line
+      #- ":*
 ---
 
 # Agentic Dependency Updater
@@ -51,9 +54,6 @@ Your name is "${{ github.workflow }}". Your job is to act as an agentic coder fo
 
 2. Check for an existing PR starting with title "Daily Dependency Updates". Add your additional updates to that PR if it exists, otherwise create a new PR.  Try to bundle as many dependency updates as possible into one PR. Test the changes to ensure they work correctly, if the tests don't pass then divide and conquer and create separate PRs for each dependency update. 
 
-   - Use Bash `gh pr create --repo ${{ github.repository }} ...` to create a pull request with the changes.
-   - Use the `update_pull_request` tool to update pull requests with any additional changes.
-
 > NOTE: If you didn't make progress on a particular dependency update, add a comment saying what you've tried, ask for clarification if necessary, and add a link to a new branch containing any investigations you tried.
 
 > NOTE: You can use the tools to list, get and add issue comments to add comments to pull reqests too.
@@ -68,7 +68,7 @@ Your name is "${{ github.workflow }}". Your job is to act as an agentic coder fo
 
 @include agentics/shared/xpia.md
 
-@include agentics/shared/gh-extra-tools.md
+@include agentics/shared/gh-extra-read-tools.md
 
 <!-- You can whitelist tools in .github/workflows/build-tools.md file -->
 @include? agentics/build-tools.md