From 2bed3c6ed45699d8fe3d6ad55a4f25b4d2d440ad Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 20 Dec 2025 20:19:37 +0000 Subject: [PATCH 1/4] Initial plan From 75e8e62028f82f54253a1ccb5e21e383de1d00fa Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 20 Dec 2025 20:22:45 +0000 Subject: [PATCH 2/4] Create AGENT.md with agentic workflows documentation Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> --- AGENT.md | 85 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 85 insertions(+) create mode 100644 AGENT.md diff --git a/AGENT.md b/AGENT.md new file mode 100644 index 0000000..21bb880 --- /dev/null +++ b/AGENT.md @@ -0,0 +1,85 @@ +# Agent Documentation + +## Overview + +This repository contains **GitHub Agentic Workflows**, which are AI-powered automation workflows that use agents to perform tasks in your repository. These workflows allow you to use AI agents (like GitHub Copilot) to automate tasks such as issue triage, code analysis, and more. + +## What are Agentic Workflows? + +Agentic workflows are a markdown-based format that combines natural language instructions with YAML frontmatter to define automated workflows. These workflows are compiled into GitHub Actions and can be triggered by various events (issues, pull requests, schedules, etc.). + +For complete documentation on GitHub Agentic Workflows, please refer to: +- **[GitHub Agentic Workflows Documentation](.github/aw/github-agentic-workflows.md)** - Comprehensive guide to creating and managing agentic workflows + +## Available Custom Agents + +This repository includes the following custom agents in `.github/agents/`: + +### 1. **create-agentic-workflow** +- **Purpose**: Design and create new agentic workflows with interactive guidance +- **Use case**: When you need to create a new workflow for automating tasks +- **Features**: + - Interactive workflow design + - Helps determine appropriate triggers (issues, pull requests, schedule, etc.) + - Configures tools and MCP servers + - Applies security best practices + - Generates valid `.md` workflow files + +### 2. **debug-agentic-workflow** +- **Purpose**: Debug and refine existing agentic workflows +- **Use case**: When a workflow is failing or needs improvement +- **Features**: + - Analyzes workflow run logs + - Audits execution to identify issues + - Provides improvement recommendations + - Helps fix missing tool calls or configuration issues + +## Important: Compiling Workflows + +**⚠️ CRITICAL**: After creating or modifying any agentic workflow file (`.md` files in `.github/workflows/`), you **MUST** compile it to generate the GitHub Actions YAML file. + +### Compilation Command + +Run this command after **every** workflow change: + +```bash +# Compile all workflows in .github/workflows/ +gh aw compile + +# Compile a specific workflow by name (without .md extension) +gh aw compile +``` + +### Why Compilation is Required + +- Agentic workflows are written in markdown (`.md` files) +- They must be compiled to GitHub Actions YAML (`.lock.yml` files) to execute +- The compilation process: + - Resolves dependencies and imports + - Processes tool configurations + - Generates proper GitHub Actions syntax + - Validates the workflow structure + +### Fix All Errors + +After running `gh aw compile`, **fix all errors** before proceeding. Common errors include: +- Invalid YAML frontmatter +- Missing required fields +- Incorrect permissions +- Invalid tool configurations +- Security violations + +Run `gh aw compile` again after fixing errors to ensure the workflow compiles successfully. + +## Getting Started + +1. **Create a new workflow**: Use the `create-agentic-workflow` custom agent +2. **Compile the workflow**: Run `gh aw compile` to generate the `.lock.yml` file +3. **Test the workflow**: Trigger it through the appropriate event (issue, PR, schedule, etc.) +4. **Debug if needed**: Use the `debug-agentic-workflow` custom agent to troubleshoot + +## Additional Resources + +- [Main README](README.md) - Repository setup and token configuration +- [GitHub Agentic Workflows Documentation](https://githubnext.github.io/gh-aw/) - Official online documentation +- [CLI Documentation](https://githubnext.github.io/gh-aw/setup/cli/) - Command-line interface reference From 7252db9548069365d40906dc038ce4f77bbe4186 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 20 Dec 2025 20:34:46 +0000 Subject: [PATCH 3/4] Rename to AGENTS.md and emphasize using MCP tools for compilation Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> --- AGENT.md => AGENTS.md | 26 +++++++++++++++++++++----- 1 file changed, 21 insertions(+), 5 deletions(-) rename AGENT.md => AGENTS.md (76%) diff --git a/AGENT.md b/AGENTS.md similarity index 76% rename from AGENT.md rename to AGENTS.md index 21bb880..c6ae13c 100644 --- a/AGENT.md +++ b/AGENTS.md @@ -38,9 +38,25 @@ This repository includes the following custom agents in `.github/agents/`: **⚠️ CRITICAL**: After creating or modifying any agentic workflow file (`.md` files in `.github/workflows/`), you **MUST** compile it to generate the GitHub Actions YAML file. -### Compilation Command +### Using the GitHub Agentic Workflows MCP Tools -Run this command after **every** workflow change: +**AGENTS MUST use the GitHub Agentic Workflows MCP tools to compile workflows.** The `agentic-workflows` MCP server provides tools specifically designed for workflow management: + +- **`compile`** - Compile markdown workflows to YAML (`.lock.yml` files) +- **`status`** - Show status of workflow files in the repository +- **`logs`** - Download and analyze workflow run logs +- **`audit`** - Investigate workflow run failures and generate reports + +To enable these tools in a workflow, add: + +```yaml +tools: + agentic-workflows: +``` + +### Manual Compilation (Alternative) + +If the MCP tools are not available, you can use the CLI command: ```bash # Compile all workflows in .github/workflows/ @@ -62,19 +78,19 @@ gh aw compile ### Fix All Errors -After running `gh aw compile`, **fix all errors** before proceeding. Common errors include: +After compiling (using MCP tools or CLI), **fix all errors** before proceeding. Common errors include: - Invalid YAML frontmatter - Missing required fields - Incorrect permissions - Invalid tool configurations - Security violations -Run `gh aw compile` again after fixing errors to ensure the workflow compiles successfully. +Recompile after fixing errors to ensure the workflow compiles successfully. ## Getting Started 1. **Create a new workflow**: Use the `create-agentic-workflow` custom agent -2. **Compile the workflow**: Run `gh aw compile` to generate the `.lock.yml` file +2. **Compile the workflow**: Use the `agentic-workflows` MCP tool's `compile` command (or `gh aw compile` CLI) to generate the `.lock.yml` file 3. **Test the workflow**: Trigger it through the appropriate event (issue, PR, schedule, etc.) 4. **Debug if needed**: Use the `debug-agentic-workflow` custom agent to troubleshoot From 5020b1ebf0760a8de42f72446487d357a6c252f6 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 20 Dec 2025 20:48:44 +0000 Subject: [PATCH 4/4] Remove gh CLI references - agents must use MCP tools only Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> --- AGENTS.md | 17 ++--------------- 1 file changed, 2 insertions(+), 15 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index c6ae13c..c647f83 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -54,18 +54,6 @@ tools: agentic-workflows: ``` -### Manual Compilation (Alternative) - -If the MCP tools are not available, you can use the CLI command: - -```bash -# Compile all workflows in .github/workflows/ -gh aw compile - -# Compile a specific workflow by name (without .md extension) -gh aw compile -``` - ### Why Compilation is Required - Agentic workflows are written in markdown (`.md` files) @@ -78,7 +66,7 @@ gh aw compile ### Fix All Errors -After compiling (using MCP tools or CLI), **fix all errors** before proceeding. Common errors include: +After compiling using MCP tools, **fix all errors** before proceeding. Common errors include: - Invalid YAML frontmatter - Missing required fields - Incorrect permissions @@ -90,7 +78,7 @@ Recompile after fixing errors to ensure the workflow compiles successfully. ## Getting Started 1. **Create a new workflow**: Use the `create-agentic-workflow` custom agent -2. **Compile the workflow**: Use the `agentic-workflows` MCP tool's `compile` command (or `gh aw compile` CLI) to generate the `.lock.yml` file +2. **Compile the workflow**: Use the `agentic-workflows` MCP tool's `compile` command to generate the `.lock.yml` file 3. **Test the workflow**: Trigger it through the appropriate event (issue, PR, schedule, etc.) 4. **Debug if needed**: Use the `debug-agentic-workflow` custom agent to troubleshoot @@ -98,4 +86,3 @@ Recompile after fixing errors to ensure the workflow compiles successfully. - [Main README](README.md) - Repository setup and token configuration - [GitHub Agentic Workflows Documentation](https://githubnext.github.io/gh-aw/) - Official online documentation -- [CLI Documentation](https://githubnext.github.io/gh-aw/setup/cli/) - Command-line interface reference