|
| 1 | +# 🔧 Q - Agentic Workflow Optimizer |
| 2 | + |
| 3 | +> For an overview of all available workflows, see the [main README](../README.md). |
| 4 | +
|
| 5 | +The [Q workflow](../workflows/q.md?plain=1) is a command-triggered workflow that acts as an expert system for optimizing and fixing agentic workflows. Like Q from James Bond, it provides agents with the best tools and configurations for their missions. When invoked with the `q` command, it analyzes workflow performance, identifies missing tools, detects inefficiencies, and creates pull requests with optimized configurations. |
| 6 | + |
| 7 | +You can trigger the workflow by adding a comment to any issue or pull request with the command: |
| 8 | + |
| 9 | +``` |
| 10 | +/q |
| 11 | +``` |
| 12 | + |
| 13 | +or by writing a comment with a specific request: |
| 14 | + |
| 15 | +``` |
| 16 | +/q Analyze and optimize all workflows in this repository |
| 17 | +``` |
| 18 | + |
| 19 | +## Installation |
| 20 | + |
| 21 | +```bash |
| 22 | +# Install the 'gh aw' extension |
| 23 | +gh aw extension install githubnext/agentics |
| 24 | + |
| 25 | +# Add the Q workflow to your repository |
| 26 | +gh aw add githubnext/agentics/q --pr |
| 27 | +``` |
| 28 | + |
| 29 | +This creates a pull request to add the workflow to your repository. |
| 30 | + |
| 31 | +You must also add [choose a coding agent](https://githubnext.github.io/gh-aw/reference/engines/) and add an API key secret for the agent to your repository. |
| 32 | + |
| 33 | +You can't start a run of this workflow directly as it is triggered in the context of an issue or pull request comment. |
| 34 | + |
| 35 | +To trigger the workflow on a specific issue or pull request, add a comment with the command: |
| 36 | + |
| 37 | +``` |
| 38 | +/q [your optimization request here] |
| 39 | +``` |
| 40 | + |
| 41 | +**Mandatory Checklist** |
| 42 | + |
| 43 | +* [ ] I have read the notes on coding tasks in the [main README](../README.md) and understand the implications. |
| 44 | + |
| 45 | +* [ ] I understand that this workflow will analyze workflows and create pull requests with optimizations. |
| 46 | + |
| 47 | +* [ ] I am a repository admin, maintainer, or have write permissions to trigger this workflow. |
| 48 | + |
| 49 | +* [ ] If in a fork, I have enabled "GitHub Actions" and "GitHub Issues" in the fork repository settings. |
| 50 | + |
| 51 | +## Configuration |
| 52 | + |
| 53 | +This workflow requires no configuration and works out of the box. You can customize optimization behavior and analysis scope if needed. |
| 54 | + |
| 55 | +After editing the workflow file, recompile and commit all changes to the default branch. |
| 56 | + |
| 57 | +## What it reads from GitHub |
| 58 | + |
| 59 | +- Workflow files and configurations in `workflows/` directory |
| 60 | +- Actions workflow runs, logs, and audit information |
| 61 | +- Issue or pull request context where the command was triggered |
| 62 | +- Repository structure and shared workflow configurations |
| 63 | +- Workflow execution history and performance metrics |
| 64 | + |
| 65 | +## What it creates |
| 66 | + |
| 67 | +- Pull requests with workflow optimizations (if changes are needed) |
| 68 | +- Comments with analysis findings and recommendations |
| 69 | +- Requires `contents: write`, `pull-requests: write`, and `issues: write` permissions |
| 70 | + |
| 71 | +## What web searches it performs |
| 72 | + |
| 73 | +- Searches for GitHub Actions agentic workflow best practices |
| 74 | +- Looks up tool documentation for missing or misconfigured tools |
| 75 | +- Researches performance optimization strategies |
| 76 | +- Finds solutions for identified error patterns |
| 77 | + |
| 78 | +## What bash commands it runs |
| 79 | + |
| 80 | +- File inspection commands to analyze workflow files |
| 81 | +- Directory traversal to find workflow configurations |
| 82 | +- Text processing to identify patterns and issues |
| 83 | +- Any other commands needed to analyze workflow structure |
| 84 | + |
| 85 | +## Use Cases |
| 86 | + |
| 87 | +- **Performance Optimization**: Identify and fix workflows with high token usage or excessive turns |
| 88 | +- **Missing Tools**: Detect and add missing tools that workflows attempt to use |
| 89 | +- **Permission Issues**: Fix workflows with insufficient permissions |
| 90 | +- **Pattern Extraction**: Create shared configurations for common workflow patterns |
| 91 | +- **Error Analysis**: Investigate recurring workflow failures and propose fixes |
| 92 | +- **Configuration Improvements**: Add timeouts, stop-after limits, and other best practice settings |
| 93 | + |
| 94 | +## Example Commands |
| 95 | + |
| 96 | +``` |
| 97 | +/q Analyze all workflows and suggest optimizations |
| 98 | +/q Fix the missing tools in the daily-progress workflow |
| 99 | +/q Investigate why the CI doctor workflow is failing |
| 100 | +/q Extract common patterns from coding workflows into a shared config |
| 101 | +/q Add missing permissions to workflows that have errors |
| 102 | +/q Optimize workflows with high token usage |
| 103 | +/q Review and improve workflow timeout settings |
| 104 | +``` |
| 105 | + |
| 106 | +## How It Works |
| 107 | + |
| 108 | +1. **Context Analysis**: Parses the triggering comment to understand what needs optimization |
| 109 | +2. **Data Gathering**: Downloads recent workflow logs and audit information using the agentic-workflows tool |
| 110 | +3. **Code Analysis**: Examines workflow files to identify issues and patterns |
| 111 | +4. **Research**: Uses web search to find solutions and best practices |
| 112 | +5. **Improvements**: Makes targeted changes to workflow files |
| 113 | +6. **Validation**: Validates changes using the compile tool |
| 114 | +7. **Pull Request**: Creates a PR with optimizations (or comments if no changes needed) |
| 115 | + |
| 116 | +## Human in the loop |
| 117 | + |
| 118 | +- Review the analysis and findings before accepting optimizations |
| 119 | +- Validate that suggested changes align with your workflow requirements |
| 120 | +- Test workflow changes in a development environment before merging |
| 121 | +- Provide feedback on optimization recommendations |
0 commit comments