From fd4e78c81c918d6aaa45670e9e016f53a4e44985 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 6 Feb 2026 16:54:56 +0000 Subject: [PATCH 1/4] Initial plan From e077573c159228fd32102ce79e9444ad0be1c283 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 6 Feb 2026 17:01:24 +0000 Subject: [PATCH 2/4] Add CLI automation discovery section to create workflow agent - Add prominent CLI tool discovery guidance to create-agentic-workflow.md - Document gh aw project new --with-project-setup command with examples - Show anti-pattern vs recommended approach for project setup - Update projects.md with Quick Setup section at the top - Emphasize using CLI commands before manual configuration Co-authored-by: mnkiefer <8320933+mnkiefer@users.noreply.github.com> --- .github/aw/create-agentic-workflow.md | 94 +++++++++++++++++++++++++++ .github/aw/projects.md | 23 ++++++- 2 files changed, 116 insertions(+), 1 deletion(-) diff --git a/.github/aw/create-agentic-workflow.md b/.github/aw/create-agentic-workflow.md index c615af23fbb..06a2ebd7a81 100644 --- a/.github/aw/create-agentic-workflow.md +++ b/.github/aw/create-agentic-workflow.md @@ -226,6 +226,7 @@ These resources contain workflow patterns, best practices, safe outputs, and per - **Advanced static analysis** → See `.github/aw/serena-tool.md` for guidance on when and how to use Serena language server (only for advanced coding tasks when user explicitly requests it) - **Orchestration patterns** → See `.github/aw/orchestration.md` for guidance on coordinating multi-step work and tracking progress across runs (use when the workflow is acting as a coordinator) - **GitHub Projects (v2)** → See `.github/aw/projects.md` for GitHub Projects (v2) integration patterns and safe-outputs setup (use when the workflow updates project boards or posts project status updates) + - **⚡ CLI Tool Discovery** → Before configuring complex manual setup, check if `gh aw` provides a CLI command for the task (see CLI Automation Discovery section below) - ⚠️ For GitHub write operations (creating issues, adding comments, etc.), always use `safe-outputs` instead of GitHub tools @@ -321,6 +322,99 @@ These resources contain workflow patterns, best practices, safe outputs, and per **DO NOT use `post-steps:` for these scenarios.** `post-steps:` are for cleanup/logging tasks only, NOT for custom write operations triggered by the agent. + **CLI Automation Discovery:** + + ⚡ **IMPORTANT**: Before recommending complex manual setup instructions, **always check if `gh aw` provides a CLI command** that automates the task. + + **Principle**: Minimize user configuration burden by discovering and recommending built-in CLI automation. + + **Available CLI Commands:** + + - **`gh aw project new`** - Create GitHub Projects V2 with optional automated setup: + ```bash + gh aw project new "Project Title" --owner myorg --with-project-setup + ``` + - **When to recommend**: User wants to create a project board for tracking workflow + - **Key feature**: `--with-project-setup` automatically creates: + - Standard views (Progress Board, Task Tracker, Roadmap) + - Custom fields (Tracker Id, Worker Workflow, Target Repo, Priority, Size, dates) + - Enhanced Status field with "Review Required" option + - **Token requirements**: Requires `GH_AW_PROJECT_GITHUB_TOKEN` with Projects permissions (not the default `GITHUB_TOKEN`) + - **Link to repo**: Use `--link owner/repo` to associate project with repository + + - **`gh aw init`** - Initialize repository for agentic workflows + - **`gh aw new `** - Scaffold a new workflow with examples + - **`gh aw add `** - Add workflows from other repositories + - **`gh aw secrets`** - Manage repository secrets and tokens + + **When creating workflows that involve GitHub Projects:** + + 1. **First**: Recommend using `gh aw project new --with-project-setup` to create the project board + 2. **Then**: Configure the workflow with the project URL in frontmatter + 3. **Result**: User runs one CLI command instead of manually creating views and fields + + **Example Workflow Creation Flow (Projects):** + + ```markdown + ## Setup Steps + + 1. Create your project board: + ```bash + gh aw project new "Dependabot Tracker" \ + --owner myorg \ + --link myorg/myrepo \ + --with-project-setup + ``` + This creates a project with standard views and custom fields. + + 2. Generate a PAT with Projects permissions and store it: + ```bash + gh aw secrets set GH_AW_PROJECT_GITHUB_TOKEN + ``` + + 3. Copy the project URL from the output above and paste it into the workflow frontmatter + + 4. Compile and run your workflow + ``` + + **Anti-Pattern (what NOT to do):** + ```markdown + ## Configuration Required ❌ + + Users must: + 1. Create Projects v2 board: https://github.com/orgs//projects/ + 2. Manually create views: Progress Board, Task Tracker, Roadmap + 3. Manually create fields: Tracker Id, Worker Workflow, Priority, Size, etc. + 4. Generate PAT with Projects permissions → GH_AW_PROJECT_GITHUB_TOKEN secret + 5. Update placeholder project URLs in frontmatter + 6. Recompile: gh aw compile workflow-name + ``` + + **Better Approach (recommended):** + ```markdown + ## Quick Setup ✅ + + Run this command to create a fully configured project board: + ```bash + gh aw project new "Dependabot Tracker" --owner myorg --link myorg/myrepo --with-project-setup + ``` + + Then store your Projects PAT: + ```bash + gh aw secrets set GH_AW_PROJECT_GITHUB_TOKEN + ``` + + Copy the project URL from the output and paste it into the workflow frontmatter, then compile. + ``` + + **Discovery Process:** + + When a user asks to create a workflow: + 1. **Identify automation needs** - Does the workflow need project boards, secrets management, etc? + 2. **Check for CLI tools** - Does `gh aw` provide a command for this setup? + 3. **Recommend CLI first** - Guide users to CLI commands before manual configuration + 4. **Provide workflow config** - Show the frontmatter that integrates with the CLI-created resources + **Security Education for Common Patterns:** When creating workflows with certain patterns, always educate users about security risks: diff --git a/.github/aw/projects.md b/.github/aw/projects.md index 869dde12003..d75b5d0038e 100644 --- a/.github/aw/projects.md +++ b/.github/aw/projects.md @@ -6,6 +6,26 @@ description: GitHub Projects (v2) integration patterns for agentic workflows When designing workflows that manage GitHub Projects, use these patterns and best practices. +## Quick Setup with CLI + +⚡ **Recommended**: Use `gh aw project new` to create a fully configured project board: + +```bash +gh aw project new "Project Title" --owner myorg --link myorg/myrepo --with-project-setup +``` + +**What this creates:** +- Project board in GitHub Projects V2 +- Standard views: Progress Board, Task Tracker, Roadmap +- Custom fields: Tracker Id, Worker Workflow, Target Repo, Priority, Size, Start Date, End Date +- Enhanced Status field with "Review Required" option + +**Requirements:** +- Token: Set `GH_AW_PROJECT_GITHUB_TOKEN` with Projects permissions (Classic PAT: `project` scope; Fine-grained PAT: Organization → Projects: Read & Write) +- The default `GITHUB_TOKEN` cannot create projects + +**Then**: Copy the project URL from the output and use it in your workflow frontmatter. + ## When to Use Projects Integration Use GitHub Projects safe-outputs when designing workflows that: @@ -17,9 +37,10 @@ Use GitHub Projects safe-outputs when designing workflows that: ## Core Projects Patterns +- **Create projects with automation** - Use `gh aw project new --with-project-setup` for quick setup with standard views and fields (recommended) - **Track items and fields** with `update-project` (add issue/PR items, create/update fields, optionally create views) - **Post periodic run summaries** with `create-project-status-update` (status, dates, and a concise markdown summary) -- **Create new projects** with `create-project` (optional; prefer manual creation unless automation is explicitly desired) +- **Create new projects programmatically** with `create-project` safe-output (advanced; prefer CLI for initial setup) ## Prerequisites and Authentication From c5f4b7e1b00b7c62a4a60d7b38ceb2d70513280c Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 6 Feb 2026 17:45:05 +0000 Subject: [PATCH 3/4] Make CLI Automation Discovery section more concise Reduced from ~93 lines to ~8 lines based on feedback that it was too verbose. The section now provides just the key principle and brief examples, referring users to `gh aw --help` for details instead of duplicating help text. Co-authored-by: mnkiefer <8320933+mnkiefer@users.noreply.github.com> --- .github/aw/create-agentic-workflow.md | 94 ++------------------------- 1 file changed, 5 insertions(+), 89 deletions(-) diff --git a/.github/aw/create-agentic-workflow.md b/.github/aw/create-agentic-workflow.md index 06a2ebd7a81..5eb4d6dfad5 100644 --- a/.github/aw/create-agentic-workflow.md +++ b/.github/aw/create-agentic-workflow.md @@ -324,96 +324,12 @@ These resources contain workflow patterns, best practices, safe outputs, and per **CLI Automation Discovery:** - ⚡ **IMPORTANT**: Before recommending complex manual setup instructions, **always check if `gh aw` provides a CLI command** that automates the task. + ⚡ **IMPORTANT**: Before recommending manual setup, check if `gh aw` provides a CLI command (use `gh aw --help` to explore). Examples: + - `gh aw project new --with-project-setup` - Creates project boards with views and fields + - `gh aw secrets` - Manages repository secrets + - `gh aw init` / `gh aw new` / `gh aw add` - Repository and workflow setup - **Principle**: Minimize user configuration burden by discovering and recommending built-in CLI automation. - - **Available CLI Commands:** - - - **`gh aw project new`** - Create GitHub Projects V2 with optional automated setup: - ```bash - gh aw project new "Project Title" --owner myorg --with-project-setup - ``` - - **When to recommend**: User wants to create a project board for tracking workflow - - **Key feature**: `--with-project-setup` automatically creates: - - Standard views (Progress Board, Task Tracker, Roadmap) - - Custom fields (Tracker Id, Worker Workflow, Target Repo, Priority, Size, dates) - - Enhanced Status field with "Review Required" option - - **Token requirements**: Requires `GH_AW_PROJECT_GITHUB_TOKEN` with Projects permissions (not the default `GITHUB_TOKEN`) - - **Link to repo**: Use `--link owner/repo` to associate project with repository - - - **`gh aw init`** - Initialize repository for agentic workflows - - **`gh aw new `** - Scaffold a new workflow with examples - - **`gh aw add `** - Add workflows from other repositories - - **`gh aw secrets`** - Manage repository secrets and tokens - - **When creating workflows that involve GitHub Projects:** - - 1. **First**: Recommend using `gh aw project new --with-project-setup` to create the project board - 2. **Then**: Configure the workflow with the project URL in frontmatter - 3. **Result**: User runs one CLI command instead of manually creating views and fields - - **Example Workflow Creation Flow (Projects):** - - ```markdown - ## Setup Steps - - 1. Create your project board: - ```bash - gh aw project new "Dependabot Tracker" \ - --owner myorg \ - --link myorg/myrepo \ - --with-project-setup - ``` - This creates a project with standard views and custom fields. - - 2. Generate a PAT with Projects permissions and store it: - ```bash - gh aw secrets set GH_AW_PROJECT_GITHUB_TOKEN - ``` - - 3. Copy the project URL from the output above and paste it into the workflow frontmatter - - 4. Compile and run your workflow - ``` - - **Anti-Pattern (what NOT to do):** - ```markdown - ## Configuration Required ❌ - - Users must: - 1. Create Projects v2 board: https://github.com/orgs//projects/ - 2. Manually create views: Progress Board, Task Tracker, Roadmap - 3. Manually create fields: Tracker Id, Worker Workflow, Priority, Size, etc. - 4. Generate PAT with Projects permissions → GH_AW_PROJECT_GITHUB_TOKEN secret - 5. Update placeholder project URLs in frontmatter - 6. Recompile: gh aw compile workflow-name - ``` - - **Better Approach (recommended):** - ```markdown - ## Quick Setup ✅ - - Run this command to create a fully configured project board: - ```bash - gh aw project new "Dependabot Tracker" --owner myorg --link myorg/myrepo --with-project-setup - ``` - - Then store your Projects PAT: - ```bash - gh aw secrets set GH_AW_PROJECT_GITHUB_TOKEN - ``` - - Copy the project URL from the output and paste it into the workflow frontmatter, then compile. - ``` - - **Discovery Process:** - - When a user asks to create a workflow: - 1. **Identify automation needs** - Does the workflow need project boards, secrets management, etc? - 2. **Check for CLI tools** - Does `gh aw` provide a command for this setup? - 3. **Recommend CLI first** - Guide users to CLI commands before manual configuration - 4. **Provide workflow config** - Show the frontmatter that integrates with the CLI-created resources + **For GitHub Projects workflows**: Recommend `gh aw project new "Title" --owner org --with-project-setup` instead of manual board/field creation **Security Education for Common Patterns:** From f9900a4f6f50a3b19b57ece3d14056797b9d6e3a Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 6 Feb 2026 18:08:00 +0000 Subject: [PATCH 4/4] Remove redundant Quick Setup with CLI section from projects.md The CLI command reference is already present in Core Projects Patterns section, making the separate Quick Setup section redundant. Co-authored-by: mnkiefer <8320933+mnkiefer@users.noreply.github.com> --- .github/aw/projects.md | 20 -------------------- 1 file changed, 20 deletions(-) diff --git a/.github/aw/projects.md b/.github/aw/projects.md index d75b5d0038e..3af9d9e535a 100644 --- a/.github/aw/projects.md +++ b/.github/aw/projects.md @@ -6,26 +6,6 @@ description: GitHub Projects (v2) integration patterns for agentic workflows When designing workflows that manage GitHub Projects, use these patterns and best practices. -## Quick Setup with CLI - -⚡ **Recommended**: Use `gh aw project new` to create a fully configured project board: - -```bash -gh aw project new "Project Title" --owner myorg --link myorg/myrepo --with-project-setup -``` - -**What this creates:** -- Project board in GitHub Projects V2 -- Standard views: Progress Board, Task Tracker, Roadmap -- Custom fields: Tracker Id, Worker Workflow, Target Repo, Priority, Size, Start Date, End Date -- Enhanced Status field with "Review Required" option - -**Requirements:** -- Token: Set `GH_AW_PROJECT_GITHUB_TOKEN` with Projects permissions (Classic PAT: `project` scope; Fine-grained PAT: Organization → Projects: Read & Write) -- The default `GITHUB_TOKEN` cannot create projects - -**Then**: Copy the project URL from the output and use it in your workflow frontmatter. - ## When to Use Projects Integration Use GitHub Projects safe-outputs when designing workflows that: