From 3ff75efde4395edc318aa45177954acb1ede1c38 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Thu, 20 Aug 2026 20:21:51 +0000
Subject: [PATCH 01/11] Initial plan
From 7caa3848360be83fd64aab695eb98e05f0dc64fe Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Thu, 20 Aug 2026 20:28:58 +0000
Subject: [PATCH 02/11] Clarify quick start lock file and CLI add commands
Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
---
docs/src/content/docs/setup/cli.md | 8 +++
docs/src/content/docs/setup/quick-start.mdx | 61 +++++++++++++++++++++
2 files changed, 69 insertions(+)
diff --git a/docs/src/content/docs/setup/cli.md b/docs/src/content/docs/setup/cli.md
index 2c2ee507d52..ba3136a5e35 100644
--- a/docs/src/content/docs/setup/cli.md
+++ b/docs/src/content/docs/setup/cli.md
@@ -146,6 +146,14 @@ Commands are organized by workflow lifecycle: creating, building, testing, monit
### Getting Workflows
+If you are choosing between the similar setup commands, use `add-wizard` for guided interactive installation of an existing workflow, `add` for direct or scripted installation of an existing workflow, and `new` to scaffold a fresh workflow you plan to author.
+
+| Command | Best fit |
+|---------|----------|
+| [`gh aw add-wizard`](#add-wizard) | Guided, interactive setup for an existing workflow, including prompts for engine auth and secrets |
+| [`gh aw add`](#add) | Direct, non-interactive installation of an existing local, remote, or packaged workflow |
+| [`gh aw new`](#new) | Scaffold a new workflow template in this repository before writing custom instructions |
+
#### `init`
Initialize repository for agentic workflows. Configures `.gitattributes`, creates the dispatcher skill file (`.github/skills/agentic-workflows/SKILL.md`), and performs non-interactive setup. With the Copilot engine (`--engine copilot`), it also creates the Agentic Workflows custom agent (`.github/agents/agentic-workflows.md`) and enables MCP server integration by default (use `--no-mcp`/`--no-agent` to skip these Copilot-specific artifacts). Use `--no-skill` to skip dispatcher skill creation. Non-Copilot engines skip Copilot-specific artifacts; see [Initializing for non-Copilot engines](#initializing-for-non-copilot-engines).
diff --git a/docs/src/content/docs/setup/quick-start.mdx b/docs/src/content/docs/setup/quick-start.mdx
index af3b580d380..fff2bdc557d 100644
--- a/docs/src/content/docs/setup/quick-start.mdx
+++ b/docs/src/content/docs/setup/quick-start.mdx
@@ -126,6 +126,67 @@ This will take you through an interactive process to:
> [!NOTE]
> The `.lock.yml` is the compiled GitHub Actions workflow generated from your Markdown source. GitHub Actions executes this file; regenerate it with `gh aw compile` after frontmatter changes instead of editing it by hand. See [Lock File](/gh-aw/reference/workflow-structure/#lock-file-header) for the full explanation.
+For example, a short Markdown source file compiles into a longer GitHub Actions workflow:
+
+
+
+
+
+**Markdown source (`.md`)**
+
+```aw title=".github/workflows/issue-helper.md"
+---
+name: Issue Helper
+on:
+ issues:
+ types: [opened]
+permissions:
+ contents: read
+ issues: read
+engine: copilot
+---
+
+Summarize the new issue and suggest next steps.
+```
+
+
+
+
+
+**Compiled workflow (`.lock.yml`, excerpt)**
+
+```yaml title=".github/workflows/issue-helper.lock.yml"
+# This file was automatically generated by gh-aw. DO NOT EDIT.
+name: "Issue Helper"
+on:
+ issues:
+ types:
+ - opened
+
+permissions: {}
+
+jobs:
+ activation:
+ runs-on: ubuntu-slim
+ permissions:
+ contents: read
+ issues: read
+ steps:
+ - name: Generate workflow metadata
+ id: generate_aw_info
+ ...
+ agent:
+ needs: activation
+ runs-on: ubuntu-slim
+ steps:
+ - name: Run agent
+ ...
+```
+
+
+
+
@@ -163,7 +163,7 @@ on:
types:
- opened
-permissions: {} # source-level permissions move to generated jobs
+permissions: {}
jobs:
activation:
From 2029e81404f9ec34aa83703ca8bd4ef0c6b0ef3d Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Thu, 20 Aug 2026 20:37:32 +0000
Subject: [PATCH 11/11] Refine CLI chooser wording
Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
---
docs/src/content/docs/setup/cli.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/src/content/docs/setup/cli.md b/docs/src/content/docs/setup/cli.md
index aea2a476f08..51c866dbe54 100644
--- a/docs/src/content/docs/setup/cli.md
+++ b/docs/src/content/docs/setup/cli.md
@@ -144,7 +144,7 @@ For `init`, `update`, and `upgrade`, use `--create-pull-request` instead.
Commands are organized by workflow lifecycle: creating, building, testing, monitoring, and managing workflows.
-Use this chooser for the similarly named setup commands:
+Use this table to choose between the similarly named setup commands:
| Command | Best fit |
|---------|----------|