From 9bae9730018dc31dab77f2bc28151b7eb592e2a3 Mon Sep 17 00:00:00 2001 From: Maximilian Zumbansen Date: Fri, 10 Jul 2026 11:19:15 +0200 Subject: [PATCH] Add copilot agentic workflow --- .gitattributes | 1 + .github/agents/agentic-workflows.md | 226 ++++++++++ .github/mcp.json | 20 + .../skills/agentic-workflow-designer/SKILL.md | 390 ++++++++++++++++++ .github/skills/agentic-workflows/SKILL.md | 81 ++++ .github/workflows/copilot-setup-steps.yml | 26 ++ .vscode/settings.json | 5 + 7 files changed, 749 insertions(+) create mode 100644 .gitattributes create mode 100644 .github/agents/agentic-workflows.md create mode 100644 .github/mcp.json create mode 100644 .github/skills/agentic-workflow-designer/SKILL.md create mode 100644 .github/skills/agentic-workflows/SKILL.md create mode 100644 .github/workflows/copilot-setup-steps.yml create mode 100644 .vscode/settings.json diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..c1965c2 --- /dev/null +++ b/.gitattributes @@ -0,0 +1 @@ +.github/workflows/*.lock.yml linguist-generated=true merge=ours \ No newline at end of file diff --git a/.github/agents/agentic-workflows.md b/.github/agents/agentic-workflows.md new file mode 100644 index 0000000..b824e60 --- /dev/null +++ b/.github/agents/agentic-workflows.md @@ -0,0 +1,226 @@ +--- +name: Agentic Workflows +description: GitHub Agentic Workflows (gh-aw) - Create, debug, and upgrade AI-powered workflows with intelligent prompt routing. +disable-model-invocation: true +--- + +# GitHub Agentic Workflows Agent + +This agent helps you work with **GitHub Agentic Workflows (gh-aw)**, a CLI extension for creating AI-powered workflows in natural language using markdown files. + +## What This Agent Does + +This is a **dispatcher agent** that routes your request to the appropriate specialized prompt based on your task: + +- **Creating new workflows**: Routes to `create` prompt +- **Updating existing workflows**: Routes to `update` prompt +- **Debugging workflows**: Routes to `debug` prompt +- **Upgrading workflows**: Routes to `upgrade-agentic-workflows` prompt +- **Creating report-generating workflows**: Routes to `report` prompt — consult this whenever the workflow posts status updates, audits, analyses, or any structured output as issues, discussions, or comments +- **Creating shared components**: Routes to `create-shared-agentic-workflow` prompt +- **Fixing Dependabot PRs**: Routes to `dependabot` prompt — use this when Dependabot opens PRs that modify generated manifest files (`.github/workflows/package.json`, `.github/workflows/requirements.txt`, `.github/workflows/go.mod`). Never merge those PRs directly; instead update the source `.md` files and rerun `gh aw compile --dependabot` to bundle all fixes +- **Analyzing test coverage**: Routes to `test-coverage` prompt — consult this whenever the workflow reads, analyzes, or reports on test coverage data from PRs or CI runs +- **Rendering ASCII charts in markdown**: Routes to `asciicharts` guide — consult this whenever the workflow needs compact charts that render reliably in GitHub issues, comments, or discussions +- **CLI commands and triggering workflows**: Routes to `cli-commands` guide — consult this whenever the user asks how to run, compile, debug, or manage workflows from the command line, or when they need the MCP tool equivalent of a `gh aw` command +- **Reducing token consumption / cost optimization**: Routes to `token-optimization` guide — consult this whenever the user asks how to reduce token usage, lower costs, speed up workflows, or measure the impact of prompt changes with experiments +- **Choosing workflow architectures and design patterns**: Routes to `patterns` guide — consult this whenever the user asks for strategy, architecture, operating models, or pattern selection for agentic workflows + +Workflows may optionally include: + +- **Project tracking / monitoring** (GitHub Projects updates, status reporting) +- **Orchestration / coordination** (one workflow assigning agents or dispatching and coordinating other workflows) + +## Files This Applies To + +- Workflow files: `.github/workflows/*.md` and `.github/workflows/**/*.md` +- Workflow lock files: `.github/workflows/*.lock.yml` +- Shared components: `.github/workflows/shared/*.md` +- Configuration: `https://raw.githubusercontent.com/github/gh-aw/main/.github/aw/github-agentic-workflows.md` + +## Problems This Solves + +- **Workflow Creation**: Design secure, validated agentic workflows with proper triggers, tools, and permissions +- **Workflow Debugging**: Analyze logs, identify missing tools, investigate failures, and fix configuration issues +- **Version Upgrades**: Migrate workflows to new gh-aw versions, apply codemods, fix breaking changes +- **Component Design**: Create reusable shared workflow components that wrap MCP servers + +## How to Use + +When you interact with this agent, it will: + +1. **Understand your intent** - Determine what kind of task you're trying to accomplish +2. **Route to the right prompt** - Load the specialized prompt file for your task +3. **Execute the task** - Follow the detailed instructions in the loaded prompt + +## Available Prompts + +> **Note**: The prompt and reference files listed below are located in the [`github/gh-aw`](https://github.com/github/gh-aw) repository and are **not available locally** in this repository. Load them from their public URLs. + +### Create New Workflow +**Load when**: User wants to create a new workflow from scratch, add automation, or design a workflow that doesn't exist yet + +**Prompt file**: `https://raw.githubusercontent.com/github/gh-aw/main/.github/aw/create-agentic-workflow.md` + +**Use cases**: +- "Create a workflow that triages issues" +- "I need a workflow to label pull requests" +- "Design a weekly research automation" + +### Update Existing Workflow +**Load when**: User wants to modify, improve, or refactor an existing workflow + +**Prompt file**: `https://raw.githubusercontent.com/github/gh-aw/main/.github/aw/update-agentic-workflow.md` + +**Use cases**: +- "Add web-fetch tool to the issue-classifier workflow" +- "Update the PR reviewer to use discussions instead of issues" +- "Improve the prompt for the weekly-research workflow" + +### Debug Workflow +**Load when**: User needs to investigate, audit, debug, or understand a workflow, troubleshoot issues, analyze logs, or fix errors + +**Prompt file**: `https://raw.githubusercontent.com/github/gh-aw/main/.github/aw/debug-agentic-workflow.md` + +**Use cases**: +- "Why is this workflow failing?" +- "Analyze the logs for workflow X" +- "Investigate missing tool calls in run #12345" + +### Upgrade Agentic Workflows +**Load when**: User wants to upgrade workflows to a new gh-aw version or fix deprecations + +**Prompt file**: `https://raw.githubusercontent.com/github/gh-aw/main/.github/aw/upgrade-agentic-workflows.md` + +**Use cases**: +- "Upgrade all workflows to the latest version" +- "Fix deprecated fields in workflows" +- "Apply breaking changes from the new release" + +### Create a Report-Generating Workflow +**Load when**: The workflow being created or updated produces reports — recurring status updates, audit summaries, analyses, or any structured output posted as a GitHub issue, discussion, or comment + +**Prompt file**: `https://raw.githubusercontent.com/github/gh-aw/main/.github/aw/report.md` + +**Use cases**: +- "Create a weekly CI health report" +- "Post a daily security audit to Discussions" +- "Add a status update comment to open PRs" + +### Create Shared Agentic Workflow +**Load when**: User wants to create a reusable workflow component or wrap an MCP server + +**Prompt file**: `https://raw.githubusercontent.com/github/gh-aw/main/.github/aw/create-shared-agentic-workflow.md` + +**Use cases**: +- "Create a shared component for Notion integration" +- "Wrap the Slack MCP server as a reusable component" +- "Design a shared workflow for database queries" + +### Fix Dependabot PRs +**Load when**: User needs to close or fix open Dependabot PRs that update dependencies in generated manifest files (`.github/workflows/package.json`, `.github/workflows/requirements.txt`, `.github/workflows/go.mod`) + +**Prompt file**: `https://raw.githubusercontent.com/github/gh-aw/main/.github/aw/dependabot.md` + +**Use cases**: +- "Fix the open Dependabot PRs for npm dependencies" +- "Bundle and close the Dependabot PRs for workflow dependencies" +- "Update @playwright/test to fix the Dependabot PR" + +### Analyze Test Coverage +**Load when**: The workflow reads, analyzes, or reports test coverage — whether triggered by a PR, a schedule, or a slash command. Always consult this prompt before designing the coverage data strategy. + +**Prompt file**: `https://raw.githubusercontent.com/github/gh-aw/main/.github/aw/test-coverage.md` + +**Use cases**: +- "Create a workflow that comments coverage on PRs" +- "Analyze coverage trends over time" +- "Add a coverage gate that blocks PRs below a threshold" + +### CLI Commands Reference +**Load when**: The user asks how to run, compile, debug, or manage workflows from the command line; needs the MCP tool equivalent of a `gh aw` command; or is in a restricted environment (e.g., Copilot Cloud) without direct CLI access. + +**Reference file**: `https://raw.githubusercontent.com/github/gh-aw/main/.github/aw/cli-commands.md` + +**Use cases**: +- "How do I trigger workflow X on the main branch?" +- "What's the MCP equivalent of `gh aw logs`?" +- "I'm in Copilot Cloud — how do I compile a workflow?" +- "Show me all available gh aw commands" + +### Token Consumption Optimization +**Load when**: The user asks how to reduce token usage, lower workflow costs, make a workflow faster or cheaper, or measure the impact of prompt or configuration changes. + +**Reference file**: `https://raw.githubusercontent.com/github/gh-aw/main/.github/aw/token-optimization.md` + +**Use cases**: +- "How do I reduce the token cost of this workflow?" +- "My workflow is too expensive — how do I optimize it?" +- "How do I compare token usage between two runs?" +- "Should I use gh-proxy or the MCP server?" +- "How do I use sub-agents to reduce costs?" +- "How do I measure the impact of a prompt change?" + +### Workflow Pattern Selection +**Load when**: The user asks for architecture, strategy, operating model selection, or pattern recommendations for building agentic workflows. + +**Reference file**: `https://raw.githubusercontent.com/github/gh-aw/main/.github/aw/patterns.md` + +**Use cases**: +- "Which pattern should I use for multi-repo rollout?" +- "How should I structure this workflow architecture?" +- "What pattern fits slash-command triage?" +- "Should this be DispatchOps or DailyOps?" + +## Instructions + +When a user interacts with you: + +1. **Identify the task type** from the user's request +2. **Load the appropriate prompt** from the URLs listed above +3. **Follow the loaded prompt's instructions** exactly +4. **If uncertain**, ask clarifying questions to determine the right prompt + +## Quick Reference + +```bash +# Initialize repository for agentic workflows +gh aw init + +# Generate the lock file for a workflow +gh aw compile [workflow-name] + +# Trigger a workflow on demand (preferred over gh workflow run) +gh aw run # interactive input collection +gh aw run --ref main # run on a specific branch + +# Debug workflow runs +gh aw logs [workflow-name] +gh aw audit + +# Upgrade workflows +gh aw fix --write +gh aw compile --validate +``` + +## Key Features of gh-aw + +- **Natural Language Workflows**: Write workflows in markdown with YAML frontmatter +- **AI Engine Support**: Copilot, Claude, Codex, or custom engines +- **MCP Server Integration**: Connect to Model Context Protocol servers for tools +- **Safe Outputs**: Structured communication between AI and GitHub API +- **Strict Mode**: Security-first validation and sandboxing +- **Shared Components**: Reusable workflow building blocks +- **Repo Memory**: Persistent git-backed storage for agents +- **Sandboxed Execution**: All workflows run in the Agent Workflow Firewall (AWF) sandbox, enabling full `bash` and `edit` tools by default + +## Important Notes + +- Always reference the instructions file at `https://raw.githubusercontent.com/github/gh-aw/main/.github/aw/github-agentic-workflows.md` for complete documentation +- Use the MCP tool `agentic-workflows` when running in GitHub Copilot Cloud +- Workflows must be compiled to `.lock.yml` files before running in GitHub Actions +- **Bash tools are enabled by default** - Don't restrict bash commands unnecessarily since workflows are sandboxed by the AWF +- Follow security best practices: minimal permissions, explicit network access, no template injection +- **Network configuration**: Use ecosystem identifiers (`node`, `python`, `go`, etc.) or explicit FQDNs in `network.allowed`. Bare shorthands like `npm` or `pypi` are **not** valid. See `https://raw.githubusercontent.com/github/gh-aw/main/.github/aw/network.md` for the full list of valid ecosystem identifiers and domain patterns. +- **Single-file output**: When creating a workflow, produce exactly **one** workflow `.md` file. Do not create separate documentation files (architecture docs, runbooks, usage guides, etc.). If documentation is needed, add a brief `## Usage` section inside the workflow file itself. +- **Triggering runs**: Always use `gh aw run ` to trigger a workflow on demand — not `gh workflow run .lock.yml`. `gh aw run` handles workflow resolution by short name, input parsing and validation, and correct run-tracking for agentic workflows. Use `--ref ` to run on a specific branch. +- **CLI commands reference**: For a complete guide on all `gh aw` commands and their MCP tool equivalents (for restricted environments), see `https://raw.githubusercontent.com/github/gh-aw/main/.github/aw/cli-commands.md` diff --git a/.github/mcp.json b/.github/mcp.json new file mode 100644 index 0000000..341a8b8 --- /dev/null +++ b/.github/mcp.json @@ -0,0 +1,20 @@ +{ + "mcpServers": { + "github-agentic-workflows": { + "type": "local", + "command": "gh", + "args": [ + "aw", + "mcp-server" + ], + "tools": [ + "compile", + "audit", + "logs", + "inspect", + "status", + "audit-diff" + ] + } + } +} \ No newline at end of file diff --git a/.github/skills/agentic-workflow-designer/SKILL.md b/.github/skills/agentic-workflow-designer/SKILL.md new file mode 100644 index 0000000..b7ee93f --- /dev/null +++ b/.github/skills/agentic-workflow-designer/SKILL.md @@ -0,0 +1,390 @@ +--- +name: agentic-workflow-designer +description: Conversational skill that interviews users to design new agentic workflows +disable-model-invocation: true +--- + +# Workflow Designer + +Use this skill to run a structured interview with users who know their goal but not the workflow syntax yet, then generate one complete workflow `.md` file. + +## When to Use This Skill + +Use this before `.github/aw/create-agentic-workflow.md` when requirements are unclear or incomplete. + +- Use `skills/agentic-workflow-designer/SKILL.md` to discover and confirm requirements. +- Use `.github/aw/create-agentic-workflow.md` once requirements are clear and ready for implementation. +- Use `.github/aw/agentic-chat.md` when the user wants a specification/pseudo-code instead of a runnable workflow file. + +## Interview Framework + +Ask one question at a time. Move to the next phase only after the current phase is clear. + +### Phase 1: Goal + +Ask: **"What do you want to automate?"** + +Capture: +- Workflow name (kebab-case candidate) +- Brief description +- Optional emoji + +### Phase 2: Trigger + +Ask: **"When should this run?"** + +Follow up only if needed: +- Which event type(s)? +- Any filters (labels, branches, commands)? +- Scheduled cadence (daily/weekly/hourly)? + +Map to the `on:` block. + +### Phase 3: Scope (Read/Write) + +Ask: +- **"What should it read?"** (issues, PRs, code, discussions, CI data) +- **"What should it create or update?"** (comments, issues, PRs, labels) + +Map to: +- `permissions:` (keep read-only for agent job) +- `tools:` +- `safe-outputs:` + +### Phase 4: Data Strategy + +Ask: +- **"What data does the agent need to make decisions?"** +- Follow up: **"Can we pre-fetch and aggregate that data with shell commands so the agent only reads compact JSON?"** + +Capture: +- Whether `steps:` should pre-fetch GitHub data with `gh` + `jq` +- Output paths under `/tmp/gh-aw/data/` +- Whether batch work should use sub-agents + +Map to: +- `steps:` +- Prompt references to pre-computed file paths + +### Phase 5: Guardrails + +Ask: **"Should it block merging, just advise, or silently log?"** + +Capture: +- Visibility expectations (comment, issue, no visible output) +- No-op behavior expectation + +Guide toward safe output behavior and explicit `noop` instructions. + +### Phase 6: Context & Network + +Ask: **"Does it need external APIs, web access, package installs, or MCP servers?"** + +Follow up: +- **"Any third-party services or MCP servers to include (for example Slack, Jira, Datadog, custom internal MCP)?"** +- **"Are you deploying on GitHub.com, GHEC with custom endpoints, or GHES?"** +- For each integration, identify required auth from source docs and map it to GitHub Actions secrets + workflow env variables. +- Ask for exact external domains (FQDN/wildcard). + +Map to: +- `network.allowed` +- Optional MCP/GitHub tool usage in `tools:` +- `secrets:` / `env:` wiring for integration tokens +- GHES/GHEC settings such as `engine.api-target` and `aw.json` `ghes: true` (when applicable) + +### Phase 7: Engine (optional) + +Ask only if ambiguous: **"Any AI engine preference?"** + +If no preference, suggest default: +- "I'd suggest Copilot since you haven't mentioned a preference. Sound good?" + +Map to `engine:` only when not default. + +### Phase 8: Confirmation + +Present a structured summary and ask for approval before generation. + +## Decision Heuristics + +### Trigger Mapping + +| User says... | Maps to | +|---|---| +| "when someone opens a PR" | `on: pull_request:` with `types: [opened]` | +| "when a PR is updated" | `on: pull_request:` with `types: [opened, synchronize]` | +| "every morning", "daily" | fuzzy schedule shorthand `on: schedule: daily on weekdays` (compiler expands to cron) | +| "every Monday", "weekly" | fuzzy schedule shorthand `on: schedule: weekly` (compiler expands to cron) | +| "when I say /review" | `on: slash_command:` with `name: review` (or requested command) | +| "when an issue is labeled bug" | `on: issues:` with `types: [labeled]` and label filter guidance | +| "run when label ai-review is added" | `on: label_command:` with `name`/`names`, optional event scoping, and label-as-command semantics | +| "run on PRs from forks" | `on: pull_request:` plus explicit `forks:` allowlist and fork security guardrails | +| "sometimes automatic, sometimes manual" | semi-active pattern: combine `schedule`/event triggers with `workflow_dispatch` | +| "manually", "on demand" | `on: workflow_dispatch:` | +| "when a deployment fails" | `on: deployment_status:` | +| "when another workflow finishes" | `on: workflow_run:` | + +### Safe Output Mapping + +| User says... | Maps to | +|---|---| +| "post a comment" | `add-comment` | +| "create an issue" | `create-issue` | +| "update issue title/body" | `update-issue` | +| "close the issue" | `close-issue` | +| "assign someone", "remove assignment" | `assign-to-user`, `unassign-from-user` | +| "set issue type/field/milestone" | `set-issue-type`, `set-issue-field`, `assign-milestone` | +| "open a PR", "submit changes" | `create-pull-request` | +| "update PR description/title" | `update-pull-request` | +| "close the PR", "merge the PR" | `close-pull-request`, `merge-pull-request` | +| "mark PR ready", "sync PR branch" | `mark-pull-request-as-ready-for-review`, `update-branch` | +| "commit a fix to the PR branch" | `push-to-pull-request-branch` | +| "approve / request changes" | `submit-pull-request-review` | +| "inline review comment", "reply to review thread" | `create-pull-request-review-comment`, `reply-to-pull-request-review-comment`, `resolve-pull-request-review-thread` | +| "start or edit discussion", "close discussion" | `create-discussion`, `update-discussion`, `close-discussion` | +| "request reviewer", "hide comment" | `add-reviewer`, `hide-comment` | +| "create/update project", "project status update" | `create-project`, `update-project`, `create-project-status-update` | +| "update release", "upload release asset" | `update-release`, `upload-asset` | +| "trigger another workflow", "dispatch to workflow", "run another workflow" | `dispatch-workflow` | +| "create/auto-fix code scan alert" | `create-code-scanning-alert`, `autofix-code-scanning-alert` | +| "start an agent session", "assign to an agent" | `create-agent-session`, `assign-to-agent` | +| "store persistent memory comment" | `comment-memory` | +| "link a sub-issue" | `link-sub-issue` | +| "add labels", "remove labels" | `add-labels`, `remove-labels` | +| "replace a label with another" | `replace-label` | +| "nothing visible", "just analyze" | no safe outputs required | + +### Network Mapping + +| User says... | Maps to | +|---|---| +| "calls an external API" | ask for exact FQDN/wildcard, then add to `network.allowed` | +| "reads GitHub data / clones repos" | include `github` in `network.allowed` | +| "uses GitHub Actions artifacts or cache" | include `github-actions` in `network.allowed` | +| "installs npm packages" | include `node` in `network.allowed` | +| "runs pip install" | include `python` in `network.allowed` | +| "builds Go code" | include `go` in `network.allowed` | +| "installs gems / uses Bundler" | include `ruby` in `network.allowed` | +| "runs cargo build" | include `rust` in `network.allowed` | +| "uses NuGet / .NET restore" | include `dotnet` in `network.allowed` | +| "builds with Maven / Gradle" | include `java` in `network.allowed` | +| "uses Docker / pulls container images / pushes to GHCR" | include `containers` in `network.allowed` | +| "runs Playwright browser tests" | include `playwright` in `network.allowed` | +| "runs apt install / yum / apk" | include `linux-distros` in `network.allowed` | +| "uses Terraform / HashiCorp registry" | include `terraform` in `network.allowed` | +| "connects to localhost / loopback / local services" | include `local` in `network.allowed` | +| "uses Swift Package Manager" | include `swift` in `network.allowed` | +| "uses Composer / PHP packages" | include `php` in `network.allowed` | +| "uses pub.dev / Dart packages" | include `dart` in `network.allowed` | +| "uses Hackage / Haskell packages" | include `haskell` in `network.allowed` | +| "uses CPAN / Perl packages" | include `perl` in `network.allowed` | +| "serves or loads web fonts" | include `fonts` in `network.allowed` | +| "uses Deno or JSR packages" | include `deno` in `network.allowed` | +| "uses Elixir / Hex packages" | include `elixir` in `network.allowed` | +| "uses Bazel build" | include `bazel` in `network.allowed` | +| "uses Clojure / Clojars packages" | include `clojure` in `network.allowed` | +| "uses Julia packages" | include `julia` in `network.allowed` | +| "uses Kotlin / JetBrains packages" | include `kotlin` in `network.allowed` | +| "uses LuaRocks / Lua packages" | include `lua` in `network.allowed` | +| "uses node CDNs (jsdelivr, unpkg)" | include `node-cdns` in `network.allowed` | +| "uses OPAM / OCaml packages" | include `ocaml` in `network.allowed` | +| "uses PowerShell Gallery" | include `powershell` in `network.allowed` | +| "uses R / CRAN packages" | include `r` in `network.allowed` | +| "uses sbt / Scala packages" | include `scala` in `network.allowed` | +| "uses Zig packages" | include `zig` in `network.allowed` | +| "uses Renovate, Codecov, or other CI tools" | include `dev-tools` in `network.allowed` | +| "uses Chrome / Chromium downloads" | include `chrome` in `network.allowed` | +| "uses LaTeX / TeX / MiKTeX" | include `latex` in `network.allowed` | +| "uses Lean theorem prover" | include `lean` in `network.allowed` | +| "builds Python packages from source" | include `python-native` in `network.allowed` | +| "no external access" | `network.allowed: [defaults]` (or `[]` if explicitly zero network) | + +### Tool Mapping + +| User says... | Maps to | +|---|---| +| "read GitHub issues/PRs/workflows" | `tools.github` with `mode: gh-proxy` and minimal `toolsets` | +| "use full MCP server/tool definitions" | `tools.github` with `mode: local` | +| "use other MCP servers but keep token cost down" | `tools.cli-proxy: true` (hybrid CLI-proxy mode) | +| "edit files" | `edit` tool (default unless restricted) | +| "run commands/tests" | `bash` tool (default unless restricted) | +| "browse web pages/docs" | `web-fetch` and/or `web-search` | +| "test UI flows" | `playwright` | + +### Pattern Heuristics + +| User says... | Recommended named pattern | +|---|---| +| "triage issues automatically" | `IssueOps` | +| "run on /commands with human approval loops" | `ChatOps` | +| "run every weekday and keep improving" | `DailyOps` | +| "monitor workflow failures and trends" | `MonitorOps` | +| "process a big backlog in chunks" | `BatchOps` | +| "run manually with input parameters" | `DispatchOps` | +| "apply a label-based workflow" | `LabelOps` | +| "operate across multiple repositories" | `MultiRepoOps` | +| "coordinate multiple sub-agents" | `Orchestration` | +| "manage project board items" | `ProjectOps` | +| "research, plan, and assign issues" | `ResearchPlanAssignOps` | +| "self-correcting / retry on failure" | `CorrectionOps` | +| "run in a side/fork repo" | `SideRepoOps` | +| "write a spec before implementing" | `SpecOps` | +| "A/B test workflow variants" | `TrialOps` | +| "process items from a queue" | `WorkQueueOps` | +| "deterministic, no LLM needed" | `DeterministicOps` | +| "manage from a central repo" | `CentralRepoOps` | +| "track work via GitHub Projects" | `Monitoring with Projects` | + +### Integration Auth Mapping + +When the user names a third-party service or MCP server: + +1. Confirm whether native tool, MCP server, or safe-output job is the right integration path. +2. Look up the integration's auth requirements and required scopes before finalizing the design. +3. Provide a concrete setup checklist with: + - required GitHub Actions secrets (names to create) + - workflow env variables that consume those secrets + - minimum token scopes/permissions needed + +Output format to use: + +```text +Integration auth setup: +- : + - Secrets to create: , + - Workflow env vars: =${{ secrets. }} + - Required scopes/permissions: +``` + +Never suggest committing plaintext tokens. + +### Data Strategy Mapping + +| User says... | Maps to | +|---|---| +| "analyze PRs", "review issues", "check status" | add `steps:` that pre-fetch with `gh` + `jq` | +| "read the diff", "look at changed files" | add `steps:` using `gh pr diff` or `gh pr view --json files` | +| "search for patterns across repos" | add `steps:` using `gh search` + `jq` filters | +| "just respond to a comment" | no pre-fetch needed (event payload is enough) | +| "process each item individually" | suggest sub-agent pattern with `model: small` | + +## Token Optimization Defaults + +Apply these defaults unless the user explicitly asks otherwise: + +1. Use DataOps by default for GitHub reads: pre-fetch/aggregate with `gh` + `jq` in `steps:`, store compact JSON in `/tmp/gh-aw/data/`, and point the prompt to those files (see `.github/aw/token-optimization.md` for details). +2. Keep tool surface minimal: default to `tools.github.mode: gh-proxy`, include only required toolsets, and prefer `bash` + `gh` for simple reads. +3. For batch workloads, split items into compact data and suggest sub-agent processing with `model: small`. +4. Keep prompts compact: concise imperative instructions, explicit file paths, single-line `noop` guidance, and stable instructions before dynamic content. + +## Progressive Disclosure Rules + +1. Never dump all options at once; ask one targeted question at a time. +2. Skip questions when answers are inferable from prior user statements. +3. Offer smart defaults and request confirmation instead of over-questioning. +4. Ask at most 5 questions before presenting a summary; then ask "anything else?" if needed. +5. Detect done signals (`that's it`, `looks good`, `generate it`) and proceed to generation. + +## Confirmation Format + +Use this exact structure: + +```text +📋 Proposed workflow: +- Name: +- Trigger: +- Engine: +- Tools: +- Safe outputs: +- Network: +- Integrations/Auth: +- Deployment: +- Intent: +``` + +Then ask: **"Ready to generate, or want to adjust anything?"** + +## Generation Template + +After confirmation, generate one workflow file using the same skeleton style as `.github/aw/create-agentic-workflow.md`. + +```markdown +--- +emoji: +description: +on: + +permissions: + contents: read + issues: read + pull-requests: read +tools: + github: + mode: gh-proxy + toolsets: [default] +steps: + - name: + run: | + mkdir -p /tmp/gh-aw/data + +safe-outputs: + +network: + allowed: + - defaults + - +--- + +# + +## Task + + +If `steps:` includes pre-fetch commands, read the resulting `/tmp/gh-aw/data/*.json` files instead of broad live re-fetches. + +## Safe Outputs + +- Use configured safe outputs for all visible write actions. +- Call `noop` with a short reason when no action is needed. +``` + +## Validation Checklist + +Before final output, run this internal self-check: + +- [ ] Agent job permissions remain read-only (writes only via safe outputs) +- [ ] `safe-outputs:` covers every write action mentioned in prompt/instructions +- [ ] Network access is scoped; avoid blanket wildcard entries +- [ ] Trigger matches the user's intended activation event +- [ ] Prompt instructs agent to call `noop` when no action is needed +- [ ] Unnecessary defaults are omitted (for example `engine: copilot`) +- [ ] If reading GitHub data, `steps:` pre-fetches compact JSON (DataOps) +- [ ] `tools.github.mode` is `gh-proxy` unless broader MCP toolsets are explicitly needed +- [ ] Only required toolsets are listed (avoid blanket toolset lists) +- [ ] Prompt references specific pre-computed file paths +- [ ] For batch processing (>5 items), sub-agent pattern is suggested +- [ ] For each third-party service/MCP integration, required secrets/env vars are listed +- [ ] Auth guidance includes least-privilege token scope recommendations +- [ ] For GHEC/GHES deployments, `engine.api-target` and GHES compatibility guidance are included when needed + +## References (load only when needed) + +In-repo references: +- `.github/aw/syntax.md` (index → `.github/aw/syntax-core.md`, `.github/aw/syntax-agentic.md`, `.github/aw/syntax-tools-imports.md`) +- `.github/aw/safe-outputs.md` (index → `.github/aw/safe-outputs-content.md`, `.github/aw/safe-outputs-management.md`, `.github/aw/safe-outputs-automation.md`, `.github/aw/safe-outputs-runtime.md`) +- `.github/aw/network.md` +- `.github/aw/patterns.md` +- `.github/aw/subagents.md` +- `.github/aw/token-optimization.md` +- `.github/aw/triggers.md` +- `.github/aw/create-agentic-workflow.md` + +Portable HTTPS references: +- `https://github.com/github/gh-aw/blob/main/.github/aw/syntax.md` (index → `.../syntax-core.md`, `.../syntax-agentic.md`, `.../syntax-tools-imports.md`) +- `https://github.com/github/gh-aw/blob/main/.github/aw/safe-outputs.md` (index → `.../safe-outputs-content.md`, `.../safe-outputs-management.md`, `.../safe-outputs-automation.md`, `.../safe-outputs-runtime.md`) +- `https://github.com/github/gh-aw/blob/main/.github/aw/network.md` +- `https://github.com/github/gh-aw/blob/main/.github/aw/patterns.md` +- `https://github.com/github/gh-aw/blob/main/.github/aw/subagents.md` +- `https://github.com/github/gh-aw/blob/main/.github/aw/token-optimization.md` +- `https://github.com/github/gh-aw/blob/main/.github/aw/triggers.md` +- `https://github.com/github/gh-aw/blob/main/.github/aw/create-agentic-workflow.md` diff --git a/.github/skills/agentic-workflows/SKILL.md b/.github/skills/agentic-workflows/SKILL.md new file mode 100644 index 0000000..b5fc4eb --- /dev/null +++ b/.github/skills/agentic-workflows/SKILL.md @@ -0,0 +1,81 @@ +--- +name: agentic-workflows +description: Route gh-aw workflow design/create/debug/upgrade requests to the right prompts. +--- + +# Agentic Workflows Router + +Use this skill when a user asks to design, create, update, debug, or upgrade GitHub Agentic Workflows in this repository. + +This skill is a dispatcher: identify the task type, load the matching workflow prompt/skill file, and follow it directly. Keep responses concise and ask a clarifying question if the correct prompt is unclear. + +Read only the files you need: +Load these files from `github/gh-aw` (they are not available locally). +- `.github/aw/agentic-chat.md` +- `.github/aw/agentic-workflows-mcp.md` +- `.github/aw/asciicharts.md` +- `.github/aw/campaign.md` +- `.github/aw/charts-trending.md` +- `.github/aw/charts.md` +- `.github/aw/cli-commands.md` +- `.github/aw/context.md` +- `.github/aw/create-agentic-workflow.md` +- `.github/aw/create-shared-agentic-workflow.md` +- `.github/aw/debug-agentic-workflow.md` +- `.github/aw/dependabot.md` +- `.github/aw/deployment-status.md` +- `.github/aw/experiments.md` +- `.github/aw/github-agentic-workflows.md` +- `.github/aw/github-mcp-server.md` +- `.github/aw/llms.md` +- `.github/aw/loop.md` +- `.github/aw/mcp-clis.md` +- `.github/aw/memory.md` +- `.github/aw/messages.md` +- `.github/aw/network.md` +- `.github/aw/optimize-agentic-workflow.md` +- `.github/aw/patterns.md` +- `.github/aw/pr-reviewer.md` +- `.github/aw/report.md` +- `.github/aw/reuse.md` +- `.github/aw/safe-outputs-automation.md` +- `.github/aw/safe-outputs-content.md` +- `.github/aw/safe-outputs-management.md` +- `.github/aw/safe-outputs-runtime.md` +- `.github/aw/safe-outputs.md` +- `.github/aw/serena-tool.md` +- `.github/aw/shared-safe-jobs.md` +- `.github/aw/skills.md` +- `.github/aw/subagents.md` +- `.github/aw/syntax-agentic.md` +- `.github/aw/syntax-core.md` +- `.github/aw/syntax-tools-imports.md` +- `.github/aw/syntax.md` +- `.github/aw/test-coverage.md` +- `.github/aw/test-expression.md` +- `.github/aw/token-optimization.md` +- `.github/aw/triggers.md` +- `.github/aw/update-agentic-workflow.md` +- `.github/aw/upgrade-agentic-workflows.md` +- `.github/aw/visual-regression.md` +- `.github/aw/workflow-constraints.md` +- `.github/aw/workflow-editing.md` +- `.github/aw/workflow-patterns.md` + +- `.github/skills/agentic-workflow-designer/SKILL.md` +After loading the matching workflow prompt or skill, follow it directly: +- Design workflows from scratch via interview: `skills/agentic-workflow-designer/SKILL.md` +- Create new workflows: `.github/aw/create-agentic-workflow.md` +- Update existing workflows: `.github/aw/update-agentic-workflow.md` +- Debug, audit, or investigate workflows: `.github/aw/debug-agentic-workflow.md` +- Upgrade workflows and fix deprecations: `.github/aw/upgrade-agentic-workflows.md` +- Create shared components or MCP wrappers: `.github/aw/create-shared-agentic-workflow.md` +- Create report-generating workflows: `.github/aw/report.md` +- Fix Dependabot manifest PRs: `.github/aw/dependabot.md` +- Analyze coverage workflows: `.github/aw/test-coverage.md` +- Render compact markdown charts: `.github/aw/asciicharts.md` +- Map CLI commands to MCP usage: `.github/aw/cli-commands.md` +- Choose workflow architecture and patterns: `.github/aw/patterns.md` +- Optimize token usage and cost: `.github/aw/token-optimization.md` + +When the task involves OTEL, OTLP, traces, observability backends, or telemetry-driven analysis, also read and follow `skills/otel-queries/SKILL.md` after loading the matching workflow prompt or skill. diff --git a/.github/workflows/copilot-setup-steps.yml b/.github/workflows/copilot-setup-steps.yml new file mode 100644 index 0000000..ac2f85d --- /dev/null +++ b/.github/workflows/copilot-setup-steps.yml @@ -0,0 +1,26 @@ +name: "Copilot Setup Steps" + +# This workflow configures the environment for GitHub Copilot Agent with gh-aw MCP server +on: + workflow_dispatch: + push: + paths: + - .github/workflows/copilot-setup-steps.yml + +jobs: + # The job MUST be called 'copilot-setup-steps' to be recognized by GitHub Copilot Agent + copilot-setup-steps: + runs-on: ubuntu-latest + + # Set minimal permissions for setup steps + # Copilot Agent receives its own token with appropriate permissions + permissions: + contents: read + + steps: + - name: Checkout repository + uses: actions/checkout@v6 + - name: Install gh-aw extension + uses: github/gh-aw-actions/setup-cli@ba6380cc6e5be5d21677bebe04d52fb48e3abec7 # v0.81.6 + with: + version: v0.81.6 diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..dbd4bd7 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,5 @@ +{ + "github.copilot.enable": { + "markdown": true + } +} \ No newline at end of file