diff --git a/modules/ghaw/challenges/0-00-setup/COACH.md b/modules/ghaw/challenges/0-00-setup/COACH.md index 15ed0da..849fb6f 100644 --- a/modules/ghaw/challenges/0-00-setup/COACH.md +++ b/modules/ghaw/challenges/0-00-setup/COACH.md @@ -14,7 +14,7 @@ - Ask for a show-of-hands "green terminal" check after the first 10 minutes. - Pair any participant who is blocked with a working neighbor; don't let one blocker stall the group. - `gh aw` installs automatically via `postCreate.sh` in both Codespaces and local dev containers. If a participant sees "command not found", the postCreate script likely failed — have them rebuild the container. -- If `gh aw run ... --dry-run` fails with an API key error, GitHub Copilot is the default zero-config engine. Confirm the participant's account has an active Copilot subscription. For Claude/OpenAI/Gemini, point them to `github.com/settings/codespaces` to add secrets. +- If `gh aw trial ... --dry-run` fails with an API key error, GitHub Copilot is the default zero-config engine. Confirm the participant's account has an active Copilot subscription. For Claude/OpenAI/Gemini, point them to `github.com/settings/codespaces` to add secrets. --- @@ -25,7 +25,7 @@ | `gh auth status` fails | Not logged in | Run `gh auth login` again; choose HTTPS | | Codespace build times out | Network / quota | Retry once; fall back to local dev container | | `gh aw --version` not found | Container image stale or `postCreate.sh` failed | Rebuild container (`Ctrl+Shift+P → Dev Containers: Rebuild Container`); or run `curl -sL https://raw.githubusercontent.com/github/gh-aw/main/install-gh-aw.sh \| bash` manually | -| `gh aw run modules/ghaw/resources/examples/hello-world.md --dry-run` fails | AI engine key missing | Confirm Copilot subscription is active; or set `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `GEMINI_API_KEY` as Codespace secrets and rebuild | +| `gh aw trial modules/ghaw/resources/examples/hello-world.md --dry-run` fails | AI engine key missing | Confirm Copilot subscription is active; or set `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `GEMINI_API_KEY` as Codespace secrets and rebuild | | Repository not accessible | Not in the right repo | Confirm the Codespace or local clone is for `microsoft/frontier-agenticdevops-hackathon` | --- @@ -36,7 +36,7 @@ Before releasing the group to Challenge 1-01, confirm per participant: - [ ] `gh auth status` exits 0 and shows the correct username - [ ] `gh aw --version` returns a version string -- [ ] `gh aw run modules/ghaw/resources/examples/hello-world.md --dry-run` completes without errors +- [ ] `gh aw trial modules/ghaw/resources/examples/hello-world.md --dry-run` completes without errors - [ ] Repository is open and writable (or readable with a documented fallback) --- diff --git a/modules/ghaw/challenges/0-00-setup/README.md b/modules/ghaw/challenges/0-00-setup/README.md index d87d8de..96ff121 100644 --- a/modules/ghaw/challenges/0-00-setup/README.md +++ b/modules/ghaw/challenges/0-00-setup/README.md @@ -74,7 +74,7 @@ gh auth status gh aw --version # 4. Dry-run smoke test -gh aw run modules/ghaw/resources/examples/hello-world.md --dry-run +gh aw trial modules/ghaw/resources/examples/hello-world.md --dry-run ``` > All four commands must succeed before you move on. If any fail, see **Common Blockers** in the coach guide. @@ -84,7 +84,7 @@ gh aw run modules/ghaw/resources/examples/hello-world.md --dry-run | Command | Expected output | |---|---| | `gh aw --version` | Returns a version string (e.g., `gh-aw version 1.x.x`) | -| `gh aw run modules/ghaw/resources/examples/hello-world.md --dry-run` | Prints generated workflow YAML; exits 0 | +| `gh aw trial modules/ghaw/resources/examples/hello-world.md --dry-run` | Previews the workflow without executing it; exits 0 | --- diff --git a/modules/ghaw/challenges/0-00-setup/meta.yml b/modules/ghaw/challenges/0-00-setup/meta.yml index 7a79b23..421102d 100644 --- a/modules/ghaw/challenges/0-00-setup/meta.yml +++ b/modules/ghaw/challenges/0-00-setup/meta.yml @@ -17,7 +17,7 @@ success_criteria: - "`gh auth status` exits 0 and shows your username" - "`gh --version` returns gh >= 2.x" - "`gh aw --version` returns a version string" - - "`gh aw run modules/ghaw/resources/examples/hello-world.md --dry-run` completes without errors" + - "`gh aw trial modules/ghaw/resources/examples/hello-world.md --dry-run` completes without errors" - "`ls modules/ghaw/resources/examples/hello-world.md` confirms the embedded example exists" tags: - setup diff --git a/modules/ghaw/challenges/1-01-morning-briefing/COACH.md b/modules/ghaw/challenges/1-01-morning-briefing/COACH.md index 9486439..2495b8b 100644 --- a/modules/ghaw/challenges/1-01-morning-briefing/COACH.md +++ b/modules/ghaw/challenges/1-01-morning-briefing/COACH.md @@ -125,8 +125,7 @@ safe-outputs: create-issue: title-prefix: '[Morning Briefing] ' -engines: - - copilot +engine: copilot tools: github: @@ -162,7 +161,7 @@ Keep the summary concise — 5-7 sentences total. - `tools: github: toolsets: [issues, pull_requests]` — agent can query data - `safe-outputs: create-issue:` with title prefix — consistent naming - Body: clear, structured instructions with specific counts to gather and format -- `engines: [copilot]` — free, reliable default +- `engine: copilot` — free, reliable default **Production-ready reference solution:** See `coaches/sample-solutions/track-1/1-01-morning-briefing.md` diff --git a/modules/ghaw/challenges/1-02-safe-and-sound/COACH.md b/modules/ghaw/challenges/1-02-safe-and-sound/COACH.md index 5dad632..4dfdfe2 100644 --- a/modules/ghaw/challenges/1-02-safe-and-sound/COACH.md +++ b/modules/ghaw/challenges/1-02-safe-and-sound/COACH.md @@ -120,7 +120,7 @@ A coach can verify completion when the squad can show: create-issue: title-prefix: "[...]" noop: - engines: ... + engine: copilot --- ``` - Remind: "2 or 4 spaces per level, consistent throughout." @@ -146,8 +146,7 @@ safe-outputs: title-prefix: '[TODO Scan] ' noop: -engines: - - copilot +engine: copilot tools: github: diff --git a/modules/ghaw/challenges/1-03-the-watcher/COACH.md b/modules/ghaw/challenges/1-03-the-watcher/COACH.md index e9f9f27..2c8d4d3 100644 --- a/modules/ghaw/challenges/1-03-the-watcher/COACH.md +++ b/modules/ghaw/challenges/1-03-the-watcher/COACH.md @@ -123,8 +123,7 @@ safe-outputs: add-comment: noop: -engines: - - copilot +engine: copilot tools: github: diff --git a/modules/ghaw/challenges/1-04-label-maker/COACH.md b/modules/ghaw/challenges/1-04-label-maker/COACH.md index c4803d8..409eaca 100644 --- a/modules/ghaw/challenges/1-04-label-maker/COACH.md +++ b/modules/ghaw/challenges/1-04-label-maker/COACH.md @@ -77,7 +77,7 @@ A coach can verify completion when the squad can show: **Root cause:** Safe-outputs config doesn't actually specify an allowlist, or allowlist is too broad. **Coach response:** -- "Your safe-outputs should specify exact labels. For example: `safe-outputs: add-labels: labels: [bug, feature, question]`" +- "Your safe-outputs should specify exact labels. For example: `safe-outputs: add-labels: allowed: [bug, feature, question]`" - Show them: "This means the agent can ONLY apply these three labels. It can't invent others." - Verify: "Check your frontmatter — is the allowlist enforced?" @@ -123,7 +123,7 @@ permissions: safe-outputs: add-labels: - labels: + allowed: - bug - feature - question @@ -131,8 +131,7 @@ safe-outputs: - help-wanted noop: -engines: - - copilot +engine: copilot --- # Label Maker @@ -156,7 +155,7 @@ Explain your reasoning in a comment on the issue summarizing why you applied (or - `permissions: contents: read` — minimal - `safe-outputs: add-labels:` with explicit allowlist — constrained labels - `noop:` path — escape hatch for unclear cases -- `engines: [copilot]` — reliable default +- `engine: copilot` — reliable default - Body: clear heuristics with keywords and examples - Includes feedback comment so user understands the classification diff --git a/modules/ghaw/challenges/2-01-triage-bot/COACH.md b/modules/ghaw/challenges/2-01-triage-bot/COACH.md index c4dce52..75b265d 100644 --- a/modules/ghaw/challenges/2-01-triage-bot/COACH.md +++ b/modules/ghaw/challenges/2-01-triage-bot/COACH.md @@ -108,7 +108,7 @@ Agent: Use grep results as a hint; apply your judgment and post comment. **Coach response:** - "Did you set `on: issues: types: [opened]` in the frontmatter?" - Show them: `issue_comment` (for comments) vs `issues` (for issue events) -- Have them recompile: `gh aw compile triage-bot.md` +- Have them recompile: `gh aw compile triage-bot` - Then create a fresh test issue to trigger it ### Pitfall 2: Label Not Applied (But Comment Posted) @@ -187,8 +187,7 @@ safe-outputs: allowlist: [bug, feature-request, documentation, question, duplicate] add-comment: {} -engines: - - copilot +engine: copilot --- # Issue Triage Bot @@ -216,10 +215,10 @@ Keep the comment warm and welcoming—this is our first interaction with the con **Why this works:** - `on: issues: types: [opened]` — fires immediately when new issue created - `permissions: issues: read` — minimal, agent doesn't write directly -- `safe-outputs: add-labels: allowlist:` — gates to 5 safe choices +- `safe-outputs: add-labels: allowed:` — gates to 5 safe choices - `safe-outputs: add-comment:` — permission granted to post comment - Body: natural language, clear decision tree, emphasizes friendliness -- `engines: [copilot]` — free, reliable for classification +- `engine: copilot` — free, reliable for classification --- @@ -230,7 +229,7 @@ Suggest this breakdown: | Phase | Time | What to Do | |-------|------|-----------| | Read & orient | 3 min | Read the challenge, ask questions | -| Write frontmatter | 5 min | Set up `on:`, `permissions`, `safe-outputs`, `engines` | +| Write frontmatter | 5 min | Set up `on:`, `permissions`, `safe-outputs`, `engine` | | Write body | 7 min | Draft classification logic + comment template | | Compile & test | 8 min | Compile, create test issue, watch Actions tab | | Debug & refine | 5 min | Fix any label/comment issues | @@ -266,7 +265,7 @@ If a squad finishes in <20 minutes: If a squad is stuck: - [ ] Is the workflow file named `triage-bot.md` in `.github/workflows/`? -- [ ] Did they run `gh aw compile triage-bot.md`? +- [ ] Did they run `gh aw compile triage-bot`? - [ ] Does `.lock.yml` exist? (`ls .github/workflows/triage-bot.lock.yml`) - [ ] Is frontmatter valid YAML? (spaces, not tabs; proper indentation) - [ ] Is `on: issues:` spelled correctly? (not `issue:`) diff --git a/modules/ghaw/challenges/2-01-triage-bot/README.md b/modules/ghaw/challenges/2-01-triage-bot/README.md index 3402769..4f7dd46 100644 --- a/modules/ghaw/challenges/2-01-triage-bot/README.md +++ b/modules/ghaw/challenges/2-01-triage-bot/README.md @@ -49,7 +49,7 @@ Create a gh-aw workflow named `triage-bot.md` in `.github/workflows/` that: ## Success Criteria - [ ] `.github/workflows/triage-bot.md` exists with valid gh-aw frontmatter -- [ ] Frontmatter includes: `on: issues:`, `permissions`, `safe-outputs:`, `engines` +- [ ] Frontmatter includes: `on: issues:`, `permissions`, `safe-outputs:`, `engine` - [ ] Safe-outputs has an allowlist limiting labels to: `bug`, `feature-request`, `documentation`, `question`, `duplicate` - [ ] `.github/workflows/triage-bot.lock.yml` compiles without errors - [ ] You manually test by creating a test issue in your repo diff --git a/modules/ghaw/challenges/2-01-triage-bot/meta.yml b/modules/ghaw/challenges/2-01-triage-bot/meta.yml index e9327f3..7d233c7 100644 --- a/modules/ghaw/challenges/2-01-triage-bot/meta.yml +++ b/modules/ghaw/challenges/2-01-triage-bot/meta.yml @@ -13,7 +13,7 @@ prerequisite_capabilities: description: Build an event-driven workflow that categorises every new issue with an AI label and posts a friendly comment explaining the classification and next steps. success_criteria: - `.github/workflows/triage-bot.md` exists with valid gh-aw frontmatter - - Frontmatter includes: `on: issues:`, `permissions`, `safe-outputs:`, `engines` + - Frontmatter includes: `on: issues:`, `permissions`, `safe-outputs:`, `engine` - Safe-outputs has an allowlist limiting labels to: `bug`, `feature-request`, `documentation`, `question`, `duplicate` - `.github/workflows/triage-bot.lock.yml` compiles without errors - You manually test by creating a test issue in your repo diff --git a/modules/ghaw/challenges/2-02-review-buddy/COACH.md b/modules/ghaw/challenges/2-02-review-buddy/COACH.md index 145c3da..f714d99 100644 --- a/modules/ghaw/challenges/2-02-review-buddy/COACH.md +++ b/modules/ghaw/challenges/2-02-review-buddy/COACH.md @@ -192,8 +192,7 @@ permissions: safe-outputs: add-comment: {} -engines: - - copilot +engine: copilot --- # Review Buddy @@ -220,7 +219,7 @@ Tone: helpful colleague, not gatekeeper. - `checkout: false` (implicit) — doesn't need code, saves time - `safe-outputs: add-comment: {}` — can post a single comment - Body: natural language, clear observations, emphasizes warmth -- `engines: [copilot]` — free, reliable +- `engine: copilot` — free, reliable --- @@ -229,7 +228,7 @@ Tone: helpful colleague, not gatekeeper. | Phase | Time | What to Do | |-------|------|-----------| | Read & orient | 3 min | Read challenge, understand PR triggers | -| Write frontmatter | 4 min | Set up `on: pull_request:`, `permissions`, `safe-outputs`, `engines` | +| Write frontmatter | 4 min | Set up `on: pull_request:`, `permissions`, `safe-outputs`, `engine` | | Write body | 6 min | Draft observations + comment template | | Compile & test | 8 min | Compile, create test PR, watch Actions tab | | Refine tone | 6 min | Read comment, improve warmth/specificity | @@ -265,7 +264,7 @@ If finished in <20 minutes: If a squad is stuck: - [ ] Is trigger `on: pull_request: types: [opened]`? (not `on: issues:`) -- [ ] Did they compile? (`gh aw compile review-buddy.md`) +- [ ] Did they compile? (`gh aw compile review-buddy`) - [ ] Does `.lock.yml` exist? - [ ] Did they create a fresh test PR *after* compiling? - [ ] Is there a workflow run in the Actions tab? diff --git a/modules/ghaw/challenges/2-03-slash-and-burn/COACH.md b/modules/ghaw/challenges/2-03-slash-and-burn/COACH.md index 069591c..4f227cf 100644 --- a/modules/ghaw/challenges/2-03-slash-and-burn/COACH.md +++ b/modules/ghaw/challenges/2-03-slash-and-burn/COACH.md @@ -210,8 +210,7 @@ permissions: safe-outputs: add-comment: {} -engines: - - copilot +engine: copilot --- # Slash Commands: /summarize @@ -243,7 +242,7 @@ Be professional but friendly. - `checkout: false` (implicit) — doesn't need code - `safe-outputs: add-comment: {}` — can post summary - Body: natural language, clear instruction to check for `/summarize` first, then posts structured summary -- `engines: [copilot]` — free, good at summarization +- `engine: copilot` — free, good at summarization --- @@ -289,7 +288,7 @@ If a squad is stuck: - [ ] Is trigger `on: issue_comment: types: [created]`? - [ ] Is `lock-for-agent: true` present? -- [ ] Did they compile? (`gh aw compile slash-commands.md`) +- [ ] Did they compile? (`gh aw compile slash-commands`) - [ ] Did they create a test issue + several comments + then post `/summarize`? - [ ] Is there a workflow run in the Actions tab? - [ ] Does the body check for `/summarize` before posting summary? diff --git a/modules/ghaw/challenges/2-04-stale-patrol/COACH.md b/modules/ghaw/challenges/2-04-stale-patrol/COACH.md index e5f6c15..251d333 100644 --- a/modules/ghaw/challenges/2-04-stale-patrol/COACH.md +++ b/modules/ghaw/challenges/2-04-stale-patrol/COACH.md @@ -175,8 +175,7 @@ safe-outputs: add-comment: {} update-issue: {} -engines: - - copilot +engine: copilot --- # Stale Patrol @@ -204,7 +203,7 @@ Be respectful and helpful. These might be contributors' important work. - `permissions: issues: read` — can query issues - `safe-outputs: update-issue: {}` — can close (which is a form of update) - Body: clear 3-phase logic (query → warn → close), respectful tone -- `engines: [copilot]` — good at date calculations and respectful copy +- `engine: copilot` — good at date calculations and respectful copy --- @@ -213,7 +212,7 @@ Be respectful and helpful. These might be contributors' important work. | Phase | Time | What to Do | |-------|------|-----------| | Read & orient | 3 min | Read challenge, understand scheduled triggers | -| Write frontmatter | 4 min | Set up `on: schedule:`, `permissions`, `safe-outputs`, `engines` | +| Write frontmatter | 4 min | Set up `on: schedule:`, `permissions`, `safe-outputs`, `engine` | | Write body | 10 min | Draft stale issue query + warn/close logic | | Compile & test | 9 min | Compile, manually trigger with `workflow_dispatch`, verify logic | | Refine | 3 min | Adjust dates/exemptions if needed | diff --git a/modules/ghaw/challenges/2-05-welcome-wagon/COACH.md b/modules/ghaw/challenges/2-05-welcome-wagon/COACH.md index 759ccc3..148c9bf 100644 --- a/modules/ghaw/challenges/2-05-welcome-wagon/COACH.md +++ b/modules/ghaw/challenges/2-05-welcome-wagon/COACH.md @@ -182,8 +182,7 @@ permissions: safe-outputs: add-comment: {} -engines: - - copilot +engine: copilot --- # Welcome Wagon @@ -209,7 +208,7 @@ Keep the comment friendly and concise. New contributors should feel welcomed, no - `permissions: pull-requests: read` — can read PR context - `safe-outputs: add-comment: {}` — can post comment - Body: clear author_association check, warm tone, resource inclusion -- `engines: [copilot]` — good at personalization and tone +- `engine: copilot` — good at personalization and tone --- @@ -218,7 +217,7 @@ Keep the comment friendly and concise. New contributors should feel welcomed, no | Phase | Time | What to Do | |-------|------|-----------| | Read & orient | 3 min | Read challenge, understand author_association | -| Write frontmatter | 4 min | Set up `on: pull_request:`, `permissions`, `safe-outputs`, `engines` | +| Write frontmatter | 4 min | Set up `on: pull_request:`, `permissions`, `safe-outputs`, `engine` | | Write body | 8 min | Draft author_association check + welcome message with resources | | Compile & test | 10 min | Compile, create test PR (or use alternate account), verify | | Refine tone | 3 min | Make comment warmer if needed | diff --git a/modules/ghaw/challenges/2-06-mix-and-match/COACH.md b/modules/ghaw/challenges/2-06-mix-and-match/COACH.md index 576a9b6..9ba202c 100644 --- a/modules/ghaw/challenges/2-06-mix-and-match/COACH.md +++ b/modules/ghaw/challenges/2-06-mix-and-match/COACH.md @@ -50,8 +50,7 @@ safe-outputs: create-discussion: category: "General" -engines: - - copilot +engine: copilot --- ``` @@ -153,7 +152,7 @@ A correct `2-06-mix-and-match.md`: ## How to Verify It's Working -1. **Compile check:** `gh aw compile .github/workflows/2-06-mix-and-match.md` — no errors +1. **Compile check:** `gh aw compile 2-06-mix-and-match` — no errors 2. **Import check:** Inspect the compiled `.lock.yml` — the helper's content should appear merged into the agent context 3. **Manual trigger:** Run via `workflow_dispatch` from the Actions tab 4. **Discussion created:** Navigate to the repo's Discussions tab — a new post should appear in "General" within seconds of the workflow completing diff --git a/modules/ghaw/challenges/2-06-mix-and-match/README.md b/modules/ghaw/challenges/2-06-mix-and-match/README.md index 7c8a318..ab2255a 100644 --- a/modules/ghaw/challenges/2-06-mix-and-match/README.md +++ b/modules/ghaw/challenges/2-06-mix-and-match/README.md @@ -84,7 +84,7 @@ Make sure GitHub Discussions is enabled for your repository (Settings → Featur ### Step 4: Compile and validate ```bash -gh aw compile .github/workflows/2-06-mix-and-match.md +gh aw compile 2-06-mix-and-match ``` No errors? You're ready to test. Trigger manually with `workflow_dispatch` to verify the Discussion appears. diff --git a/modules/ghaw/challenges/3-01-the-relay/COACH.md b/modules/ghaw/challenges/3-01-the-relay/COACH.md index 61aeaa9..56a7a1b 100644 --- a/modules/ghaw/challenges/3-01-the-relay/COACH.md +++ b/modules/ghaw/challenges/3-01-the-relay/COACH.md @@ -196,8 +196,7 @@ tools: repo-memory: file-glob: 'metrics/**/*.json' -engines: - - copilot +engine: copilot --- # Daily Metrics Collector @@ -245,8 +244,7 @@ tools: repo-memory: file-glob: 'metrics/**/*.json' -engines: - - copilot +engine: copilot --- # Weekly Metrics Report diff --git a/modules/ghaw/challenges/3-02-context-engine/COACH.md b/modules/ghaw/challenges/3-02-context-engine/COACH.md index 6d73730..61c84ab 100644 --- a/modules/ghaw/challenges/3-02-context-engine/COACH.md +++ b/modules/ghaw/challenges/3-02-context-engine/COACH.md @@ -190,8 +190,7 @@ tools: github: toolsets: [pull_requests, contents] -engines: - - copilot +engine: copilot checkout: false --- diff --git a/modules/ghaw/challenges/3-03-engine-swap/COACH.md b/modules/ghaw/challenges/3-03-engine-swap/COACH.md index dc85ba4..d4cec91 100644 --- a/modules/ghaw/challenges/3-03-engine-swap/COACH.md +++ b/modules/ghaw/challenges/3-03-engine-swap/COACH.md @@ -31,8 +31,7 @@ A finished solution has: 1. **`issue-categorizer-copilot.md`** (~25 lines) ```markdown - engines: - - copilot + engine: copilot --- @@ -52,8 +51,7 @@ A finished solution has: 2. **`issue-categorizer-claude.md`** (~30 lines) ```markdown - engines: - - claude + engine: claude --- @@ -76,8 +74,7 @@ A finished solution has: 3. **`issue-categorizer-codex.md`** (~25 lines) ```markdown - engines: - - codex + engine: codex --- @@ -207,7 +204,7 @@ Only tests 2 of 3 engines (e.g., Copilot + Claude, skip Codex). **Root cause:** Engine name typo or API credentials missing. **Coach response:** -- "What does your `engines:` section say? Should be `copilot`, `claude`, or `codex` exactly." +- "What does your `engine:` section say? Should be `copilot`, `claude`, or `codex` exactly." - Check: do they have API access for all three engines? (Copilot is built-in; Claude and Codex may need setup) --- @@ -243,8 +240,7 @@ safe-outputs: add-labels: allowlist: [bug, feature, question, docs] -engines: - - copilot +engine: copilot checkout: false --- @@ -281,8 +277,7 @@ safe-outputs: add-labels: allowlist: [bug, feature, question, docs] -engines: - - claude +engine: claude checkout: false --- @@ -323,8 +318,7 @@ safe-outputs: add-labels: allowlist: [bug, feature, question, docs] -engines: - - codex +engine: codex checkout: false --- diff --git a/modules/ghaw/challenges/3-04-the-overseer/COACH.md b/modules/ghaw/challenges/3-04-the-overseer/COACH.md index 002549a..093aa5f 100644 --- a/modules/ghaw/challenges/3-04-the-overseer/COACH.md +++ b/modules/ghaw/challenges/3-04-the-overseer/COACH.md @@ -210,8 +210,7 @@ tools: max-effective-tokens: 5000000 -engines: - - claude +engine: claude checkout: false diff --git a/modules/ghaw/challenges/3-05-ship-it/COACH.md b/modules/ghaw/challenges/3-05-ship-it/COACH.md index e46cc82..6f2933c 100644 --- a/modules/ghaw/challenges/3-05-ship-it/COACH.md +++ b/modules/ghaw/challenges/3-05-ship-it/COACH.md @@ -221,8 +221,7 @@ tools: repo-memory: file-glob: 'observations/**/*.json' -engines: - - copilot +engine: copilot checkout: false --- @@ -273,8 +272,7 @@ tools: repo-memory: file-glob: 'observations/**/*.json' -engines: - - copilot +engine: copilot checkout: false @@ -320,8 +318,7 @@ tools: github: toolsets: [issues] -engines: - - copilot +engine: copilot checkout: false diff --git a/modules/ghaw/challenges/3-06-ground-truth/COACH.md b/modules/ghaw/challenges/3-06-ground-truth/COACH.md index d5fcc36..df19275 100644 --- a/modules/ghaw/challenges/3-06-ground-truth/COACH.md +++ b/modules/ghaw/challenges/3-06-ground-truth/COACH.md @@ -19,7 +19,7 @@ This challenge teaches one of the most important production patterns in gh-aw: * **Key insight to surface:** The AI model is not a database. It cannot look up your open issue count — it will guess. `pre-agent-steps:` separates "gather facts" (shell, deterministic, reliable) from "reason about facts" (AI, creative, unreliable without grounding). That separation is the architecture of trustworthy automation. -**For `create-pr`:** The PR gate is about trust. Even when agents produce correct output, good teams don't merge automatically. `create-pr` is the "propose, don't impose" pattern — the agent does the work, a human approves the result. +**For `create-pull-request`:** The PR gate is about trust. Even when agents produce correct output, good teams don't merge automatically. `create-pull-request` is the "propose, don't impose" pattern — the agent does the work, a human approves the result. --- @@ -64,12 +64,11 @@ pre-agent-steps: git log -1 --format="%ci" > /tmp/last-commit.txt safe-outputs: - create-pr: + create-pull-request: base-branch: main - title-template: "docs: update CONTRIBUTING.md with current project health" + title-prefix: "docs: update CONTRIBUTING.md with current project health" -engines: - - copilot +engine: copilot --- ``` @@ -80,9 +79,9 @@ engines: --- -## How `create-pr` Differs from Direct Commits +## How `create-pull-request` Differs from Direct Commits -Without `create-pr`, if an agent modifies a file, those changes are committed directly to the default branch. With `create-pr`: +Without `create-pull-request`, if an agent modifies a file, those changes are committed directly to the default branch. With `create-pull-request`: 1. The agent's file changes are staged on a new branch 2. A pull request is opened against `base-branch` @@ -90,7 +89,7 @@ Without `create-pr`, if an agent modifies a file, those changes are committed di This is the "propose, don't impose" pattern. It's not just about safety — it's about auditability. Stakeholders can see exactly what the agent changed, in the diff, before it affects anything. -**The contrast:** `safe-outputs: noop` (read-only) → `safe-outputs: create-pr` (write, but gated) → direct commit (write, ungated — not available as a safe-output by design). +**The contrast:** `safe-outputs: noop` (read-only) → `safe-outputs: create-pull-request` (write, but gated) → direct commit (write, ungated — not available as a safe-output by design). --- @@ -100,7 +99,7 @@ This is the "propose, don't impose" pattern. It's not just about safety — it's **Symptom:** Workflow runs, `pre-agent-steps:` succeeds, agent runs, but no PR appears. Permission error in logs. -**Cause:** Only `contents: write` was declared. `create-pr` needs both. +**Cause:** Only `contents: write` was declared. `create-pull-request` needs both. **Fix:** ```yaml @@ -109,7 +108,7 @@ permissions: pull-requests: write ``` -**Socratic response:** "Let's look at your permissions block. `create-pr` needs two permissions — which one is missing?" +**Socratic response:** "Let's look at your permissions block. `create-pull-request` needs two permissions — which one is missing?" --- @@ -129,7 +128,7 @@ pre-agent-steps: cat /tmp/open-issues.txt # debug: show value in logs ``` -**Socratic response:** "Run `gh aw run --dry-run` and check whether the `/tmp/` files have values. What does `cat /tmp/open-issues.txt` output in the dry-run logs?" +**Socratic response:** "Run `gh aw run 3-06-ground-truth --dry-run` and check whether the `/tmp/` files have values. What does `cat /tmp/open-issues.txt` output in the dry-run logs?" --- @@ -179,15 +178,15 @@ A correct `3-06-ground-truth.md`: - Each writes a single value to a `/tmp/` file - Body explicitly references each `/tmp/` file path and instructs the agent to use those exact values - Body asks agent to update only the `## Project Health` section of `CONTRIBUTING.md` -- `safe-outputs: create-pr: base-branch: main` with a descriptive `title-template` +- `safe-outputs: create-pull-request: base-branch: main` with a descriptive `title-prefix` - Both `contents: write` and `pull-requests: write` in `permissions:` --- ## How to Verify It's Working -1. **Compile:** `gh aw compile .github/workflows/3-06-ground-truth.md` — no errors -2. **Dry-run:** `gh aw run --dry-run` — `pre-agent-steps:` output should show real numbers in `/tmp/` files +1. **Compile:** `gh aw compile 3-06-ground-truth` — no errors +2. **Dry-run:** `gh aw run 3-06-ground-truth --dry-run` — `pre-agent-steps:` output should show real numbers in `/tmp/` files 3. **Live run:** Trigger via `workflow_dispatch` 4. **PR check:** A PR should appear with a new branch; diff shows only `## Project Health` section changed in `CONTRIBUTING.md` 5. **Number accuracy:** Open the PR, check the numbers in `CONTRIBUTING.md`. Cross-check against `gh issue list --state open | wc -l` — numbers should match (within a few seconds of drift) @@ -201,7 +200,7 @@ A correct `3-06-ground-truth.md`: | Read & orient | 3 min | Understand pre-agent-steps flow | | Write pre-agent-steps | 8 min | 3 fetch commands + write to /tmp/ | | Write agent body | 7 min | Reference /tmp/ files, describe CONTRIBUTING.md update | -| Configure create-pr | 3 min | base-branch, title-template, permissions | +| Configure create-pull-request | 3 min | base-branch, title-prefix, permissions | | Compile + dry-run | 5 min | Verify /tmp/ files populated in dry-run output | | Live test | 4 min | Trigger, verify PR opens with real numbers | @@ -222,7 +221,7 @@ A correct `3-06-ground-truth.md`: - **Separation of concerns.** `pre-agent-steps:` = deterministic. Agent body = reasoning. This is good software architecture applied to AI workflows. - **AI doesn't know your repo state.** This is not a flaw — it's by design. The agent's job is reasoning, not data fetching. `pre-agent-steps:` handles the fetch. -- **`create-pr` as a trust dial.** Squads may want to auto-merge. Push back gently: "When would you *not* want to auto-merge? Now build for that case." Most squads arrive at "keep the human in the loop for docs changes." +- **`create-pull-request` as a trust dial.** Squads may want to auto-merge. Push back gently: "When would you *not* want to auto-merge? Now build for that case." Most squads arrive at "keep the human in the loop for docs changes." --- @@ -230,5 +229,5 @@ A correct `3-06-ground-truth.md`: **Sample Solution Location:** `coaches/sample-solutions/track-3/3-06-ground-truth.md` **pre-agent-steps:** https://github.github.com/gh-aw/reference/frontmatter/#pre-agent-steps -**create-pr:** https://github.github.com/gh-aw/reference/safe-outputs/#create-pr +**create-pull-request:** https://github.github.com/gh-aw/reference/safe-outputs-pull-requests/#create-pull-request **gh CLI — gh api:** https://cli.github.com/manual/gh_api diff --git a/modules/ghaw/challenges/3-06-ground-truth/README.md b/modules/ghaw/challenges/3-06-ground-truth/README.md index c849a65..ba0e38a 100644 --- a/modules/ghaw/challenges/3-06-ground-truth/README.md +++ b/modules/ghaw/challenges/3-06-ground-truth/README.md @@ -8,7 +8,7 @@ ## What You'll Build -A workflow that runs deterministic shell commands *before* the AI model starts — using `pre-agent-steps:` — to fetch real, live repo metrics via the `gh` CLI. The agent is given those numbers and uses them to update `CONTRIBUTING.md` with a "## Project Health" section. Instead of committing directly, it opens a pull request via the `create-pr` safe-output, keeping a human in the loop. +A workflow that runs deterministic shell commands *before* the AI model starts — using `pre-agent-steps:` — to fetch real, live repo metrics via the `gh` CLI. The agent is given those numbers and uses them to update `CONTRIBUTING.md` with a "## Project Health" section. Instead of committing directly, it opens a pull request via the `create-pull-request` safe-output, keeping a human in the loop. **Why this matters:** AI models hallucinate numbers. If you ask "how many open issues does this repo have?" without giving the model real data, it will guess. `pre-agent-steps:` closes that gap: shell commands run first, write real data to files, and the agent reads those files before reasoning. The result is grounded, accurate output — not plausible fiction. @@ -21,7 +21,7 @@ By the end of this challenge, your squad will: 1. ✅ Use `pre-agent-steps:` to fetch real repo metrics via `gh` CLI 2. ✅ Pass those metrics to the agent via files 3. ✅ Have the agent update `CONTRIBUTING.md` with live data -4. ✅ Open a PR (not a direct commit) using `create-pr` +4. ✅ Open a PR (not a direct commit) using `create-pull-request` 5. ✅ Compile and dry-run successfully --- @@ -46,18 +46,18 @@ The files written to `/tmp/` are ephemeral — they exist only for the duration --- -## Background: `create-pr` +## Background: `create-pull-request` -The `create-pr` safe-output tells the gh-aw runtime to open a pull request containing any files the agent modified during its run. The agent does not commit directly; changes are staged and a PR is opened for human review. +The `create-pull-request` safe-output tells the gh-aw runtime to open a pull request containing any files the agent modified during its run. The agent does not commit directly; changes are staged and a PR is opened for human review. ```yaml safe-outputs: - create-pr: + create-pull-request: base-branch: main - title-template: "docs: update CONTRIBUTING.md with current project health" + title-prefix: "docs: update CONTRIBUTING.md with current project health" ``` -The `title-template` sets the PR title. The agent can suggest additional context in the PR body. +The `title-prefix` sets the PR title. The agent can suggest additional context in the PR body. --- @@ -89,19 +89,19 @@ Read /tmp/open-prs.txt for the number of open pull requests. Read /tmp/last-commit.txt for the date of the last commit. ``` -### Step 3: Configure `create-pr` +### Step 3: Configure `create-pull-request` -Add `create-pr` to `safe-outputs` with a `base-branch` of `main`. The agent's changes to `CONTRIBUTING.md` will land in a new branch, and a PR will be opened automatically. +Add `create-pull-request` to `safe-outputs` with a `base-branch` of `main`. The agent's changes to `CONTRIBUTING.md` will land in a new branch, and a PR will be opened automatically. ### Step 4: Set permissions -`create-pr` requires both `contents: write` (to push a branch) and `pull-requests: write` (to open the PR). Both must be declared. +`create-pull-request` requires both `contents: write` (to push a branch) and `pull-requests: write` (to open the PR). Both must be declared. ### Step 5: Compile and dry-run ```bash -gh aw compile .github/workflows/3-06-ground-truth.md -gh aw run --dry-run .github/workflows/3-06-ground-truth.md +gh aw compile 3-06-ground-truth +gh aw run 3-06-ground-truth --dry-run ``` The dry-run will execute `pre-agent-steps:` and show you the values captured — a quick sanity check before running for real. @@ -115,7 +115,7 @@ The dry-run will execute `pre-agent-steps:` and show you the values captured — - [ ] Agent body references those `/tmp/` files explicitly - [ ] `CONTRIBUTING.md` is updated with a `## Project Health` section containing real numbers - [ ] A PR is opened — not a direct commit -- [ ] PR title matches `title-template` +- [ ] PR title matches `title-prefix` - [ ] Numbers in the PR are accurate (match what `gh` CLI would return for the repo) - [ ] `permissions: contents: write` and `pull-requests: write` are both declared - [ ] Coach conversation — where has an AI confidently produced numbers or facts it made up in your work, and how would feeding it deterministic data first change what you would trust it to output? Talk it through with your coach and connect it to a real project, task, or workflow you own. @@ -144,7 +144,7 @@ The dry-run will execute `pre-agent-steps:` and show you the values captured — ## References - **pre-agent-steps:** https://github.github.com/gh-aw/reference/frontmatter/#pre-agent-steps -- **create-pr safe-output:** https://github.github.com/gh-aw/reference/safe-outputs/#create-pr +- **create-pull-request safe-output:** https://github.github.com/gh-aw/reference/safe-outputs-pull-requests/#create-pull-request - **gh CLI — gh api:** https://cli.github.com/manual/gh_api - **gh CLI — gh pr list:** https://cli.github.com/manual/gh_pr_list diff --git a/modules/ghaw/challenges/3-06-ground-truth/meta.yml b/modules/ghaw/challenges/3-06-ground-truth/meta.yml index 8a43b94..ee62861 100644 --- a/modules/ghaw/challenges/3-06-ground-truth/meta.yml +++ b/modules/ghaw/challenges/3-06-ground-truth/meta.yml @@ -10,20 +10,20 @@ prerequisite_capabilities: - GitHub Actions basics - YAML syntax - gh-aw CLI installed — see ghaw-0-00 -description: Feed your agent real data before it runs. Use pre-agent-steps: to deterministically fetch context, and create-pr to safely propose code changes. +description: Feed your agent real data before it runs. Use pre-agent-steps: to deterministically fetch context, and create-pull-request to safely propose code changes. success_criteria: - `.github/workflows/3-06-ground-truth.md` compiles without errors - `pre-agent-steps:` fetches at least 3 real metrics and writes them to `/tmp/` - Agent body references those `/tmp/` files explicitly - `CONTRIBUTING.md` is updated with a `## Project Health` section containing real numbers - A PR is opened — not a direct commit - - PR title matches `title-template` + - PR title matches `title-prefix` - Numbers in the PR are accurate (match what `gh` CLI would return for the repo) - `permissions: contents: write` and `pull-requests: write` are both declared - "Coach conversation — where has an AI confidently produced numbers or facts it made up in your work, and how would feeding it deterministic data first change what you would trust it to output? Talk it through with your coach and connect it to a real project, task, or workflow you own." tags: - pre-agent-steps - - create-pr + - create-pull-request - deterministic - context-injection app_dependency: none @@ -35,6 +35,6 @@ source_path: _challenges/3-06-ground-truth.md license: MIT references: - https://github.github.com/gh-aw/reference/frontmatter/#pre-agent-steps - - https://github.github.com/gh-aw/reference/safe-outputs/#create-pr + - https://github.github.com/gh-aw/reference/safe-outputs-pull-requests/#create-pull-request - https://cli.github.com/manual/gh_api - https://cli.github.com/manual/gh_pr_list diff --git a/modules/ghaw/challenges/4-01-issue-triage-agent/COACH.md b/modules/ghaw/challenges/4-01-issue-triage-agent/COACH.md index 1188a3c..6a35b5b 100644 --- a/modules/ghaw/challenges/4-01-issue-triage-agent/COACH.md +++ b/modules/ghaw/challenges/4-01-issue-triage-agent/COACH.md @@ -39,8 +39,7 @@ tools: github: toolsets: [issues, labels] -engines: - - copilot +engine: copilot --- # Issue Triage Agent diff --git a/modules/ghaw/challenges/4-01-issue-triage-agent/README.md b/modules/ghaw/challenges/4-01-issue-triage-agent/README.md index 2f04d2d..7a66fb9 100644 --- a/modules/ghaw/challenges/4-01-issue-triage-agent/README.md +++ b/modules/ghaw/challenges/4-01-issue-triage-agent/README.md @@ -36,12 +36,12 @@ Source: [`github/gh-aw/.github/workflows/issue-triage-agent.md`](https://github. 5. **Compile** the workflow: ```bash - gh aw compile .github/workflows/issue-triage-agent.md + gh aw compile issue-triage-agent ``` -6. **Dry-run** with a real issue number: +6. **Dry-run** the workflow: ```bash - gh aw run --dry-run .github/workflows/issue-triage-agent.md --event issue --issue 1 + gh aw run issue-triage-agent --dry-run ``` 7. Commit both `.github/workflows/issue-triage-agent.md` and the generated `.lock.yml`. diff --git a/modules/ghaw/challenges/4-02-ci-doctor/COACH.md b/modules/ghaw/challenges/4-02-ci-doctor/COACH.md index 3f2675d..ec06d6e 100644 --- a/modules/ghaw/challenges/4-02-ci-doctor/COACH.md +++ b/modules/ghaw/challenges/4-02-ci-doctor/COACH.md @@ -40,8 +40,7 @@ tools: github: toolsets: [actions] -engines: - - copilot +engine: copilot --- # CI Doctor diff --git a/modules/ghaw/challenges/4-02-ci-doctor/README.md b/modules/ghaw/challenges/4-02-ci-doctor/README.md index a40b374..9868631 100644 --- a/modules/ghaw/challenges/4-02-ci-doctor/README.md +++ b/modules/ghaw/challenges/4-02-ci-doctor/README.md @@ -8,7 +8,7 @@ CI breaks at the worst times. Normally a developer has to open the Actions tab, scroll through log noise, and manually reason about root cause. CI Doctor automates that investigation: it fires on a failed workflow run, pulls the logs, analyses them, and opens a structured diagnostic issue with the root cause and suggested fix. -In `github/gh-aw`, this workflow proposed 13 PRs with a **69% merge rate** (9 merged). That's a CI-fix pipeline running mostly on autopilot. +In `github/gh-aw`, this workflow proposed 13 PRs with roughly a **69% merge rate** (9 merged) in a point-in-time sample — numbers will have moved since. That's a CI-fix pipeline running mostly on autopilot. Source: [`githubnext/agentics/workflows/ci-doctor.md`](https://github.com/githubnext/agentics/blob/main/workflows/ci-doctor.md) @@ -37,7 +37,7 @@ Source: [`githubnext/agentics/workflows/ci-doctor.md`](https://github.com/github 5. **Compile**: ```bash - gh aw compile .github/workflows/ci-doctor.md + gh aw compile ci-doctor ``` 6. **Trigger a test failure** (break a test intentionally in a branch, push, let CI fail) and inspect the [workflow run logs](https://docs.github.com/en/actions/monitoring-and-troubleshooting-workflows/using-workflow-run-logs) as the Doctor fires. diff --git a/modules/ghaw/challenges/4-03-daily-doc-updater/COACH.md b/modules/ghaw/challenges/4-03-daily-doc-updater/COACH.md index 79bb8cb..4738814 100644 --- a/modules/ghaw/challenges/4-03-daily-doc-updater/COACH.md +++ b/modules/ghaw/challenges/4-03-daily-doc-updater/COACH.md @@ -13,7 +13,7 @@ Use these follow-ups to steer the conversation: ## What This Challenge Teaches -Scheduled automation with `create-pr` safe-output. Participants learn to think about docs as a living artefact that drifts from code, how to write prompts that detect drift (not just "review docs"), and how to produce focused, mergeable PRs rather than wholesale rewrites. +Scheduled automation with `create-pull-request` safe-output. Participants learn to think about docs as a living artefact that drifts from code, how to write prompts that detect drift (not just "review docs"), and how to produce focused, mergeable PRs rather than wholesale rewrites. Official grounding: when students are unsure whether a frontmatter field or permission is valid, anchor them in the [GitHub Actions workflow syntax](https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions) and [GITHUB_TOKEN permissions](https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication) docs before they tune the agent prompt. @@ -34,10 +34,9 @@ permissions: pull-requests: write safe-outputs: - create-pr: {} + create-pull-request: {} -engines: - - copilot +engine: copilot --- # Daily Documentation Updater diff --git a/modules/ghaw/challenges/4-03-daily-doc-updater/README.md b/modules/ghaw/challenges/4-03-daily-doc-updater/README.md index eca1e50..c3f60f6 100644 --- a/modules/ghaw/challenges/4-03-daily-doc-updater/README.md +++ b/modules/ghaw/challenges/4-03-daily-doc-updater/README.md @@ -8,7 +8,7 @@ Code evolves. Docs don't — not unless someone makes them a first-class concern. The Daily Documentation Updater runs on a cron schedule, reviews your docs directory against the actual codebase, and opens PRs for content that has drifted out of sync. -The production version in `githubnext/agentics` achieved a **96% merge rate** — 57 merged PRs out of 59 proposed. When the agent proposes a doc fix, maintainers almost always agree with it. +The production version in `githubnext/agentics` achieved roughly a **96% merge rate** (57 of 59 proposed PRs merged, as a point-in-time sample). When the agent proposes a doc fix, maintainers almost always agree with it. Source: [`githubnext/agentics/workflows/daily-doc-updater.md`](https://github.com/githubnext/agentics/blob/main/workflows/daily-doc-updater.md) @@ -37,12 +37,12 @@ Source: [`githubnext/agentics/workflows/daily-doc-updater.md`](https://github.co 5. **Compile**: ```bash - gh aw compile .github/workflows/daily-doc-updater.md + gh aw compile daily-doc-updater ``` 6. **Dry-run** to see what it would propose: ```bash - gh aw run --dry-run .github/workflows/daily-doc-updater.md + gh aw run daily-doc-updater --dry-run ``` 7. Commit both workflow and `.lock.yml`. Add a stale doc to trigger your first real PR. @@ -52,14 +52,14 @@ Source: [`githubnext/agentics/workflows/daily-doc-updater.md`](https://github.co - Change the target path in the prompt body: point at `docs/`, `README.md`, or a subdirectory specific to your project - Adjust the cron schedule — `0 9 * * 1-5` for weekdays only, or `0 9 * * 1` for Monday morning only - Tune the review depth: "only check API endpoint docs" vs "review all docs for accuracy" -- Add a PR template or label to the `create-pr` output so doc-update PRs are easy to filter +- Add a PR template or label to the `create-pull-request` output so doc-update PRs are easy to filter ## Success Criteria - [ ] `.github/workflows/daily-doc-updater.md` exists with valid gh-aw frontmatter - [ ] Trigger is `schedule: cron` (valid cron expression) - [ ] Target doc directory is configured to something real in your repo -- [ ] `safe-outputs: create-pr` is declared +- [ ] `safe-outputs: create-pull-request` is declared - [ ] `.github/workflows/daily-doc-updater.lock.yml` compiles without errors - [ ] Dry-run produces at least one proposed doc change - [ ] A manually triggered run opens a real PR with a focused, accurate diff @@ -77,7 +77,7 @@ Source: [`githubnext/agentics/workflows/daily-doc-updater.md`](https://github.co → Constrain the body: _"Review only `docs/api.md`. Open a single PR per file. Each PR should change no more than 10 lines."_ Smaller PRs get merged faster. **"How do I make sure it doesn't overwrite things it shouldn't?"** -→ `safe-outputs: create-pr` still requires a human to merge. The agent can propose; humans approve. +→ `safe-outputs: create-pull-request` still requires a human to merge. The agent can propose; humans approve. **"What cron syntax do I use?"** → GitHub Actions uses UTC. `0 9 * * *` = 9am UTC daily. Use https://crontab.guru to validate your expression. diff --git a/modules/ghaw/challenges/4-03-daily-doc-updater/meta.yml b/modules/ghaw/challenges/4-03-daily-doc-updater/meta.yml index 52f6b08..21c6264 100644 --- a/modules/ghaw/challenges/4-03-daily-doc-updater/meta.yml +++ b/modules/ghaw/challenges/4-03-daily-doc-updater/meta.yml @@ -15,7 +15,7 @@ success_criteria: - `.github/workflows/daily-doc-updater.md` exists with valid gh-aw frontmatter - Trigger is `schedule: cron` (valid cron expression) - Target doc directory is configured to something real in your repo - - `safe-outputs: create-pr` is declared + - `safe-outputs: create-pull-request` is declared - `.github/workflows/daily-doc-updater.lock.yml` compiles without errors - Dry-run produces at least one proposed doc change - A manually triggered run opens a real PR with a focused, accurate diff @@ -23,7 +23,7 @@ success_criteria: tags: - documentation - schedule - - create-pr + - create-pull-request - drift-detection - production app_dependency: none diff --git a/modules/ghaw/challenges/4-04-doc-unbloat/COACH.md b/modules/ghaw/challenges/4-04-doc-unbloat/COACH.md index 3db828a..9cd9696 100644 --- a/modules/ghaw/challenges/4-04-doc-unbloat/COACH.md +++ b/modules/ghaw/challenges/4-04-doc-unbloat/COACH.md @@ -34,10 +34,9 @@ permissions: pull-requests: write safe-outputs: - create-pr: {} + create-pull-request: {} -engines: - - copilot +engine: copilot --- # Documentation Unbloat diff --git a/modules/ghaw/challenges/4-04-doc-unbloat/README.md b/modules/ghaw/challenges/4-04-doc-unbloat/README.md index 83e00f6..fc38943 100644 --- a/modules/ghaw/challenges/4-04-doc-unbloat/README.md +++ b/modules/ghaw/challenges/4-04-doc-unbloat/README.md @@ -8,7 +8,7 @@ Every project accumulates doc debt: verbose intros, duplicate sections, outdated warnings, nested caveats-of-caveats. The Documentation Unbloat workflow finds this bloat and opens focused PRs that trim it — no rewrites, just surgical simplification. -The production version in `githubnext/agentics` achieved an **85% merge rate** — 88 merged PRs out of 103 proposed. Maintainers love it because each PR is small, targeted, and easy to review. +The production version in `githubnext/agentics` achieved roughly an **85% merge rate** (88 of 103 proposed PRs merged, as a point-in-time sample). Maintainers love it because each PR is small, targeted, and easy to review. Source: [`githubnext/agentics/workflows/unbloat-docs.md`](https://github.com/githubnext/agentics/blob/main/workflows/unbloat-docs.md) @@ -37,12 +37,12 @@ Source: [`githubnext/agentics/workflows/unbloat-docs.md`](https://github.com/git 5. **Compile**: ```bash - gh aw compile .github/workflows/unbloat-docs.md + gh aw compile unbloat-docs ``` 6. **Dry-run** against your bloated doc: ```bash - gh aw run --dry-run .github/workflows/unbloat-docs.md + gh aw run unbloat-docs --dry-run ``` 7. Review the proposed PR diff — does it match what you'd have cut manually? @@ -58,7 +58,7 @@ Source: [`githubnext/agentics/workflows/unbloat-docs.md`](https://github.com/git - [ ] `.github/workflows/unbloat-docs.md` exists with valid gh-aw frontmatter - [ ] Target document is explicitly named in the workflow body -- [ ] `safe-outputs: create-pr` is declared +- [ ] `safe-outputs: create-pull-request` is declared - [ ] Simplification criteria are specific, not vague ("make it shorter" is too vague — "remove duplicate warnings and shorten code examples to one line" is good) - [ ] `.github/workflows/unbloat-docs.lock.yml` compiles without errors - [ ] Dry-run proposes at least one real simplification @@ -80,7 +80,7 @@ Source: [`githubnext/agentics/workflows/unbloat-docs.md`](https://github.com/git → Look for: sentences starting with "Note that", "Please be aware", "It is important to". These almost always can be cut or rewritten more directly. **"The PR is huge — 50 files changed"** -→ The production workflow targets one or two files per run. Narrow your scope in the body, and use `create-pr` with a focused branch name. +→ The production workflow targets one or two files per run. Narrow your scope in the body, and use `create-pull-request` with a focused branch name. **"Should I run this on a schedule or manually?"** → Start with `workflow_dispatch` so you control when it runs. Graduate to a weekly cron once you trust the output. diff --git a/modules/ghaw/challenges/4-04-doc-unbloat/meta.yml b/modules/ghaw/challenges/4-04-doc-unbloat/meta.yml index e48897a..af7111b 100644 --- a/modules/ghaw/challenges/4-04-doc-unbloat/meta.yml +++ b/modules/ghaw/challenges/4-04-doc-unbloat/meta.yml @@ -14,7 +14,7 @@ description: Bloated docs scare contributors away. Deploy a workflow that identi success_criteria: - `.github/workflows/unbloat-docs.md` exists with valid gh-aw frontmatter - Target document is explicitly named in the workflow body - - `safe-outputs: create-pr` is declared + - `safe-outputs: create-pull-request` is declared - Simplification criteria are specific, not vague ("make it shorter" is too vague — "remove duplicate warnings and shorten code examples to one line" is good) - `.github/workflows/unbloat-docs.lock.yml` compiles without errors - Dry-run proposes at least one real simplification @@ -23,7 +23,7 @@ success_criteria: tags: - documentation - simplification - - create-pr + - create-pull-request - production app_dependency: none emu_compatible: true diff --git a/modules/ghaw/challenges/4-05-daily-testify/COACH.md b/modules/ghaw/challenges/4-05-daily-testify/COACH.md index e1ab061..31ed42a 100644 --- a/modules/ghaw/challenges/4-05-daily-testify/COACH.md +++ b/modules/ghaw/challenges/4-05-daily-testify/COACH.md @@ -36,8 +36,7 @@ permissions: safe-outputs: create-issue: {} -engines: - - copilot +engine: copilot --- # Daily Testify — Uber Expert @@ -69,7 +68,7 @@ Limit to 3 issues per run to avoid flooding. | Issues are vague ("add more tests to utils.js") | Enforce specificity: "Each issue must name the exact function and what's missing" | | Agent creates 20 issues at once | Add hard limit: "Create at most 3 issues per run" | | Expert persona feels generic | Push for specificity: what does the expert know that a junior dev doesn't? Name it explicitly | -| `create-pr` used instead of `create-issue` | Redirect: this is intentional — the Improver handles PRs; Testify only identifies | +| `create-pull-request` used instead of `create-issue` | Redirect: this is intentional — the Improver handles PRs; Testify only identifies | --- diff --git a/modules/ghaw/challenges/4-05-daily-testify/README.md b/modules/ghaw/challenges/4-05-daily-testify/README.md index 13f7f73..a35f14f 100644 --- a/modules/ghaw/challenges/4-05-daily-testify/README.md +++ b/modules/ghaw/challenges/4-05-daily-testify/README.md @@ -37,7 +37,7 @@ Source: [`github/gh-aw/.github/workflows/daily-testify-uber-super-expert.md`](ht 5. **Compile**: ```bash - gh aw compile .github/workflows/daily-testify-uber-super-expert.md + gh aw compile daily-testify-uber-super-expert ``` 6. **Trigger manually** and examine the first issue it creates — is it actionable? @@ -54,7 +54,7 @@ Source: [`github/gh-aw/.github/workflows/daily-testify-uber-super-expert.md`](ht - [ ] `.github/workflows/daily-testify-uber-super-expert.md` exists with valid frontmatter - [ ] `schedule: cron` trigger is set - [ ] Expert persona is established in the body (specific, not generic) -- [ ] `safe-outputs: create-issue` is declared — **no** `create-pr` here +- [ ] `safe-outputs: create-issue` is declared — **no** `create-pull-request` here - [ ] `.lock.yml` compiles without errors - [ ] Manually triggered run creates at least one actionable issue - [ ] Issue body is specific: names a file, a function, or a concrete gap — not "add more tests" @@ -77,7 +77,7 @@ Source: [`github/gh-aw/.github/workflows/daily-testify-uber-super-expert.md`](ht **"I don't have many tests yet"** → That's fine — the agent will tell you _where_ tests are missing, which is useful signal even before the Test Improver acts. -**"Should I use create-pr instead?"** +**"Should I use create-pull-request instead?"** → No. This is an intentional design: human review between analysis and action. The 100% merge rate comes from that review gate, not from skipping it. diff --git a/modules/ghaw/challenges/4-05-daily-testify/meta.yml b/modules/ghaw/challenges/4-05-daily-testify/meta.yml index bde2461..dc8a645 100644 --- a/modules/ghaw/challenges/4-05-daily-testify/meta.yml +++ b/modules/ghaw/challenges/4-05-daily-testify/meta.yml @@ -15,7 +15,7 @@ success_criteria: - `.github/workflows/daily-testify-uber-super-expert.md` exists with valid frontmatter - `schedule: cron` trigger is set - Expert persona is established in the body (specific, not generic) - - `safe-outputs: create-issue` is declared — **no** `create-pr` here + - `safe-outputs: create-issue` is declared — **no** `create-pull-request` here - `.lock.yml` compiles without errors - Manually triggered run creates at least one actionable issue - Issue body is specific: names a file, a function, or a concrete gap — not "add more tests" diff --git a/modules/ghaw/challenges/4-06-test-improver/COACH.md b/modules/ghaw/challenges/4-06-test-improver/COACH.md index 2707e76..4692810 100644 --- a/modules/ghaw/challenges/4-06-test-improver/COACH.md +++ b/modules/ghaw/challenges/4-06-test-improver/COACH.md @@ -35,14 +35,13 @@ permissions: issues: read safe-outputs: - create-pr: {} + create-pull-request: {} tools: github: toolsets: [issues] -engines: - - copilot +engine: copilot --- # Daily Test Improver diff --git a/modules/ghaw/challenges/4-06-test-improver/README.md b/modules/ghaw/challenges/4-06-test-improver/README.md index 1180cb1..191b445 100644 --- a/modules/ghaw/challenges/4-06-test-improver/README.md +++ b/modules/ghaw/challenges/4-06-test-improver/README.md @@ -17,7 +17,7 @@ Source: [`githubnext/agentics/workflows/daily-test-improver.md`](https://github. - Runs daily on a cron schedule - Scans the codebase for functions, methods, or paths with no corresponding test coverage - Writes new tests incrementally — one focused PR at a time -- Uses `safe-outputs: create-pr` so maintainers review before merge +- Uses `safe-outputs: create-pull-request` so maintainers review before merge ## What You'll Do @@ -37,12 +37,12 @@ Source: [`githubnext/agentics/workflows/daily-test-improver.md`](https://github. 5. **Compile**: ```bash - gh aw compile .github/workflows/daily-test-improver.md + gh aw compile daily-test-improver ``` 6. **Dry-run** to preview what tests it would write: ```bash - gh aw run --dry-run .github/workflows/daily-test-improver.md + gh aw run daily-test-improver --dry-run ``` 7. Evaluate the preview — would you merge those tests? @@ -60,7 +60,7 @@ Source: [`githubnext/agentics/workflows/daily-test-improver.md`](https://github. - [ ] `schedule: cron` trigger is set - [ ] Test framework and language are specified in the body - [ ] Coverage gap detection logic is in the body (not just "write more tests") -- [ ] `safe-outputs: create-pr` is declared +- [ ] `safe-outputs: create-pull-request` is declared - [ ] `.lock.yml` compiles without errors - [ ] Dry-run produces at least one new test file or function - [ ] Proposed test is syntactically valid for your framework diff --git a/modules/ghaw/challenges/4-06-test-improver/meta.yml b/modules/ghaw/challenges/4-06-test-improver/meta.yml index fe38398..f65bf21 100644 --- a/modules/ghaw/challenges/4-06-test-improver/meta.yml +++ b/modules/ghaw/challenges/4-06-test-improver/meta.yml @@ -17,7 +17,7 @@ success_criteria: - `schedule: cron` trigger is set - Test framework and language are specified in the body - Coverage gap detection logic is in the body (not just "write more tests") - - `safe-outputs: create-pr` is declared + - `safe-outputs: create-pull-request` is declared - `.lock.yml` compiles without errors - Dry-run produces at least one new test file or function - Proposed test is syntactically valid for your framework @@ -25,7 +25,7 @@ success_criteria: tags: - testing - coverage - - create-pr + - create-pull-request - causal-chain - production app_dependency: none diff --git a/modules/ghaw/challenges/4-07-security-compliance/COACH.md b/modules/ghaw/challenges/4-07-security-compliance/COACH.md index d564788..8e1609e 100644 --- a/modules/ghaw/challenges/4-07-security-compliance/COACH.md +++ b/modules/ghaw/challenges/4-07-security-compliance/COACH.md @@ -40,8 +40,7 @@ tools: github: toolsets: [security] -engines: - - copilot +engine: copilot --- # Security Compliance diff --git a/modules/ghaw/challenges/4-07-security-compliance/README.md b/modules/ghaw/challenges/4-07-security-compliance/README.md index 065596f..07ba42e 100644 --- a/modules/ghaw/challenges/4-07-security-compliance/README.md +++ b/modules/ghaw/challenges/4-07-security-compliance/README.md @@ -38,7 +38,7 @@ Source: [`github/gh-aw/.github/workflows/security-compliance.md`](https://github 5. **Compile**: ```bash - gh aw compile .github/workflows/security-compliance.md + gh aw compile security-compliance ``` 6. **Enable [Dependabot alerts](https://docs.github.com/en/code-security/dependabot/dependabot-alerts/about-dependabot-alerts)** on your repo (Settings > Security > Dependabot alerts) if not already enabled — give the workflow something to find. diff --git a/modules/ghaw/challenges/4-08-malicious-code-scan/COACH.md b/modules/ghaw/challenges/4-08-malicious-code-scan/COACH.md index ee90d4c..f6b5f00 100644 --- a/modules/ghaw/challenges/4-08-malicious-code-scan/COACH.md +++ b/modules/ghaw/challenges/4-08-malicious-code-scan/COACH.md @@ -40,8 +40,7 @@ tools: github: toolsets: [actions, issues] -engines: - - copilot +engine: copilot --- # Daily Malicious Code Scan diff --git a/modules/ghaw/challenges/4-08-malicious-code-scan/README.md b/modules/ghaw/challenges/4-08-malicious-code-scan/README.md index 779e60c..2c10067 100644 --- a/modules/ghaw/challenges/4-08-malicious-code-scan/README.md +++ b/modules/ghaw/challenges/4-08-malicious-code-scan/README.md @@ -37,7 +37,7 @@ Source: [`githubnext/agentics/workflows/daily-malicious-code-scan.md`](https://g 5. **Compile**: ```bash - gh aw compile .github/workflows/daily-malicious-code-scan.md + gh aw compile daily-malicious-code-scan ``` 6. **Test it** by adding a benign-but-flaggable pattern to a branch (e.g., a base64-encoded eval), then manually triggering the scan. diff --git a/modules/ghaw/resources/examples/README.md b/modules/ghaw/resources/examples/README.md index e0a4401..d217f57 100644 --- a/modules/ghaw/resources/examples/README.md +++ b/modules/ghaw/resources/examples/README.md @@ -1,6 +1,6 @@ # Examples This directory contains minimal gh-aw workflow examples for learning and smoke-testing. -Each file is a self-contained workflow you can run with `gh aw run --dry-run` to verify your environment. +Each file is a self-contained workflow you can run with `gh aw trial --dry-run` to verify your environment. - [`hello-world.md`](hello-world.md) — the simplest possible workflow: creates a "Hello from gh-aw!" issue. Use this as your first smoke test after devcontainer setup. diff --git a/modules/ghaw/setup.md b/modules/ghaw/setup.md index 7178d17..c2ce4e7 100644 --- a/modules/ghaw/setup.md +++ b/modules/ghaw/setup.md @@ -22,7 +22,7 @@ Use one of these supported environment paths before starting `ghaw-0-00`: gh auth login gh auth status gh aw --version -gh aw run modules/ghaw/resources/examples/hello-world.md --dry-run +gh aw trial modules/ghaw/resources/examples/hello-world.md --dry-run ``` If `gh aw --version` fails in a local environment, reinstall with: diff --git a/modules/ghec/challenges/ch01-issues-labels-projects/README.md b/modules/ghec/challenges/ch01-issues-labels-projects/README.md index 3ebb28b..7075994 100644 --- a/modules/ghec/challenges/ch01-issues-labels-projects/README.md +++ b/modules/ghec/challenges/ch01-issues-labels-projects/README.md @@ -35,13 +35,13 @@ Run the provisioning entrypoint (Bash or PowerShell — both supported). `wth` i # Bash wth setup ch01 --org # or directly: -bash modules/ghec/resources/provisioning/scripts/setup.sh ch01 --org +bash modules/ghec/resources/provisioning/scripts/setup.sh setup ch01 --org ``` ```powershell # PowerShell wth setup ch01 --org # or directly: -modules/ghec/resources/provisioning/scripts/setup.ps1 ch01 --org +modules/ghec/resources/provisioning/scripts/setup.ps1 setup ch01 --org ``` **What setup creates** (all artifacts namespaced `wth-ch01-*`, idempotent, prefix-guarded teardown): diff --git a/modules/ghec/challenges/ch02-pull-requests-code-review/README.md b/modules/ghec/challenges/ch02-pull-requests-code-review/README.md index e471cdc..d19fa3f 100644 --- a/modules/ghec/challenges/ch02-pull-requests-code-review/README.md +++ b/modules/ghec/challenges/ch02-pull-requests-code-review/README.md @@ -36,13 +36,13 @@ Run the provisioning entrypoint (Bash or PowerShell — both supported). `wth` i # Bash wth setup ch02 --org # or directly: -bash modules/ghec/resources/provisioning/scripts/setup.sh ch02 --org +bash modules/ghec/resources/provisioning/scripts/setup.sh setup ch02 --org ``` ```powershell # PowerShell wth setup ch02 --org # or directly: -modules/ghec/resources/provisioning/scripts/setup.ps1 ch02 --org +modules/ghec/resources/provisioning/scripts/setup.ps1 setup ch02 --org ``` **What setup creates** (all artifacts namespaced `wth-ch02-*`, idempotent, prefix-guarded teardown): diff --git a/modules/ghec/challenges/ch03-codespaces-dev-containers/README.md b/modules/ghec/challenges/ch03-codespaces-dev-containers/README.md index f037910..69bba1f 100644 --- a/modules/ghec/challenges/ch03-codespaces-dev-containers/README.md +++ b/modules/ghec/challenges/ch03-codespaces-dev-containers/README.md @@ -36,13 +36,13 @@ Run the provisioning entrypoint (Bash or PowerShell — both supported). `wth` i # Bash wth setup ch03 --org # or directly: -bash modules/ghec/resources/provisioning/scripts/setup.sh ch03 --org +bash modules/ghec/resources/provisioning/scripts/setup.sh setup ch03 --org ``` ```powershell # PowerShell wth setup ch03 --org # or directly: -modules/ghec/resources/provisioning/scripts/setup.ps1 ch03 --org +modules/ghec/resources/provisioning/scripts/setup.ps1 setup ch03 --org ``` **What setup creates** (all artifacts namespaced `wth-ch03-*`, idempotent, prefix-guarded teardown): diff --git a/modules/ghec/challenges/ch04-actions-ci-fundamentals/README.md b/modules/ghec/challenges/ch04-actions-ci-fundamentals/README.md index 9aa6016..7413bb3 100644 --- a/modules/ghec/challenges/ch04-actions-ci-fundamentals/README.md +++ b/modules/ghec/challenges/ch04-actions-ci-fundamentals/README.md @@ -37,13 +37,13 @@ Run the provisioning entrypoint (Bash or PowerShell — both supported). `wth` i # Bash wth setup ch04 --org # or directly: -bash modules/ghec/resources/provisioning/scripts/setup.sh ch04 --org +bash modules/ghec/resources/provisioning/scripts/setup.sh setup ch04 --org ``` ```powershell # PowerShell wth setup ch04 --org # or directly: -modules/ghec/resources/provisioning/scripts/setup.ps1 ch04 --org +modules/ghec/resources/provisioning/scripts/setup.ps1 setup ch04 --org ``` **What setup creates** (all artifacts namespaced `wth-ch04-*`, idempotent, prefix-guarded teardown): diff --git a/modules/ghec/challenges/ch05-advanced-pr-automation/README.md b/modules/ghec/challenges/ch05-advanced-pr-automation/README.md index 8148d90..20b54a8 100644 --- a/modules/ghec/challenges/ch05-advanced-pr-automation/README.md +++ b/modules/ghec/challenges/ch05-advanced-pr-automation/README.md @@ -36,13 +36,13 @@ Run the provisioning entrypoint (Bash or PowerShell — both supported). `wth` i # Bash wth setup ch05 --org # or directly: -bash modules/ghec/resources/provisioning/scripts/setup.sh ch05 --org +bash modules/ghec/resources/provisioning/scripts/setup.sh setup ch05 --org ``` ```powershell # PowerShell wth setup ch05 --org # or directly: -modules/ghec/resources/provisioning/scripts/setup.ps1 ch05 --org +modules/ghec/resources/provisioning/scripts/setup.ps1 setup ch05 --org ``` **What setup creates** (all artifacts namespaced `wth-ch05-*`, idempotent, prefix-guarded teardown): diff --git a/modules/ghec/challenges/ch06-enterprise-org-101/README.md b/modules/ghec/challenges/ch06-enterprise-org-101/README.md index 6783b91..324d56a 100644 --- a/modules/ghec/challenges/ch06-enterprise-org-101/README.md +++ b/modules/ghec/challenges/ch06-enterprise-org-101/README.md @@ -36,13 +36,13 @@ Run the provisioning entrypoint (Bash or PowerShell — both supported). `wth` i # Bash wth setup ch06 --org # or directly: -bash modules/ghec/resources/provisioning/scripts/setup.sh ch06 --org +bash modules/ghec/resources/provisioning/scripts/setup.sh setup ch06 --org ``` ```powershell # PowerShell wth setup ch06 --org # or directly: -modules/ghec/resources/provisioning/scripts/setup.ps1 ch06 --org +modules/ghec/resources/provisioning/scripts/setup.ps1 setup ch06 --org ``` **What setup creates** (all artifacts namespaced `wth-ch06-*`, idempotent, prefix-guarded teardown): diff --git a/modules/ghec/challenges/ch07-teams-roles-permissions/README.md b/modules/ghec/challenges/ch07-teams-roles-permissions/README.md index f59ffcf..01d1f10 100644 --- a/modules/ghec/challenges/ch07-teams-roles-permissions/README.md +++ b/modules/ghec/challenges/ch07-teams-roles-permissions/README.md @@ -36,13 +36,13 @@ Run the provisioning entrypoint (Bash or PowerShell — both supported). `wth` i # Bash wth setup ch07 --org # or directly: -bash modules/ghec/resources/provisioning/scripts/setup.sh ch07 --org +bash modules/ghec/resources/provisioning/scripts/setup.sh setup ch07 --org ``` ```powershell # PowerShell wth setup ch07 --org # or directly: -modules/ghec/resources/provisioning/scripts/setup.ps1 ch07 --org +modules/ghec/resources/provisioning/scripts/setup.ps1 setup ch07 --org ``` **What setup creates** (all artifacts namespaced `wth-ch07-*`, idempotent, prefix-guarded teardown): diff --git a/modules/ghec/challenges/ch08-rulesets-repo-properties/README.md b/modules/ghec/challenges/ch08-rulesets-repo-properties/README.md index 34cb86e..bcd122a 100644 --- a/modules/ghec/challenges/ch08-rulesets-repo-properties/README.md +++ b/modules/ghec/challenges/ch08-rulesets-repo-properties/README.md @@ -36,13 +36,13 @@ Run the provisioning entrypoint (Bash or PowerShell — both supported). `wth` i # Bash wth setup ch08 --org # or directly: -bash modules/ghec/resources/provisioning/scripts/setup.sh ch08 --org +bash modules/ghec/resources/provisioning/scripts/setup.sh setup ch08 --org ``` ```powershell # PowerShell wth setup ch08 --org # or directly: -modules/ghec/resources/provisioning/scripts/setup.ps1 ch08 --org +modules/ghec/resources/provisioning/scripts/setup.ps1 setup ch08 --org ``` **What setup creates** (all artifacts namespaced `wth-ch08-*`, idempotent, prefix-guarded teardown): diff --git a/modules/ghec/challenges/ch09-audit-log-streaming/README.md b/modules/ghec/challenges/ch09-audit-log-streaming/README.md index 251d438..c57cf89 100644 --- a/modules/ghec/challenges/ch09-audit-log-streaming/README.md +++ b/modules/ghec/challenges/ch09-audit-log-streaming/README.md @@ -36,13 +36,13 @@ Run the provisioning entrypoint (Bash or PowerShell — both supported). `wth` i # Bash wth setup ch09 --org # or directly: -bash modules/ghec/resources/provisioning/scripts/setup.sh ch09 --org +bash modules/ghec/resources/provisioning/scripts/setup.sh setup ch09 --org ``` ```powershell # PowerShell wth setup ch09 --org # or directly: -modules/ghec/resources/provisioning/scripts/setup.ps1 ch09 --org +modules/ghec/resources/provisioning/scripts/setup.ps1 setup ch09 --org ``` **What setup creates** (all artifacts namespaced `wth-ch09-*`, idempotent, prefix-guarded teardown): diff --git a/modules/ghec/challenges/ch10-billing-cost-centers/README.md b/modules/ghec/challenges/ch10-billing-cost-centers/README.md index 30faf9b..b27a268 100644 --- a/modules/ghec/challenges/ch10-billing-cost-centers/README.md +++ b/modules/ghec/challenges/ch10-billing-cost-centers/README.md @@ -36,13 +36,13 @@ Run the provisioning entrypoint (Bash or PowerShell — both supported). `wth` i # Bash wth setup ch10 --org # or directly: -bash modules/ghec/resources/provisioning/scripts/setup.sh ch10 --org +bash modules/ghec/resources/provisioning/scripts/setup.sh setup ch10 --org ``` ```powershell # PowerShell wth setup ch10 --org # or directly: -modules/ghec/resources/provisioning/scripts/setup.ps1 ch10 --org +modules/ghec/resources/provisioning/scripts/setup.ps1 setup ch10 --org ``` **What setup creates** (all artifacts namespaced `wth-ch10-*`, idempotent, prefix-guarded teardown): diff --git a/modules/ghec/challenges/ch11-secret-scanning-push-protection/README.md b/modules/ghec/challenges/ch11-secret-scanning-push-protection/README.md index 92b4d55..543b5a4 100644 --- a/modules/ghec/challenges/ch11-secret-scanning-push-protection/README.md +++ b/modules/ghec/challenges/ch11-secret-scanning-push-protection/README.md @@ -35,13 +35,13 @@ Run the provisioning entrypoint (Bash or PowerShell — both supported). `wth` i # Bash wth setup ch11 --org # or directly: -bash modules/ghec/resources/provisioning/scripts/setup.sh ch11 --org +bash modules/ghec/resources/provisioning/scripts/setup.sh setup ch11 --org ``` ```powershell # PowerShell wth setup ch11 --org # or directly: -modules/ghec/resources/provisioning/scripts/setup.ps1 ch11 --org +modules/ghec/resources/provisioning/scripts/setup.ps1 setup ch11 --org ``` **What setup creates** (all artifacts namespaced `wth-ch11-*`, idempotent, prefix-guarded teardown): diff --git a/modules/ghec/challenges/ch12-codeql-code-scanning/README.md b/modules/ghec/challenges/ch12-codeql-code-scanning/README.md index 7f74dd9..90a2912 100644 --- a/modules/ghec/challenges/ch12-codeql-code-scanning/README.md +++ b/modules/ghec/challenges/ch12-codeql-code-scanning/README.md @@ -36,13 +36,13 @@ Run the provisioning entrypoint (Bash or PowerShell — both supported). `wth` i # Bash wth setup ch12 --org # or directly: -bash modules/ghec/resources/provisioning/scripts/setup.sh ch12 --org +bash modules/ghec/resources/provisioning/scripts/setup.sh setup ch12 --org ``` ```powershell # PowerShell wth setup ch12 --org # or directly: -modules/ghec/resources/provisioning/scripts/setup.ps1 ch12 --org +modules/ghec/resources/provisioning/scripts/setup.ps1 setup ch12 --org ``` **What setup creates** (all artifacts namespaced `wth-ch12-*`, idempotent, prefix-guarded teardown): diff --git a/modules/ghec/challenges/ch13-dependabot-dependency-review/README.md b/modules/ghec/challenges/ch13-dependabot-dependency-review/README.md index ada8146..4e5427f 100644 --- a/modules/ghec/challenges/ch13-dependabot-dependency-review/README.md +++ b/modules/ghec/challenges/ch13-dependabot-dependency-review/README.md @@ -36,13 +36,13 @@ Run the provisioning entrypoint (Bash or PowerShell — both supported). `wth` i # Bash wth setup ch13 --org # or directly: -bash modules/ghec/resources/provisioning/scripts/setup.sh ch13 --org +bash modules/ghec/resources/provisioning/scripts/setup.sh setup ch13 --org ``` ```powershell # PowerShell wth setup ch13 --org # or directly: -modules/ghec/resources/provisioning/scripts/setup.ps1 ch13 --org +modules/ghec/resources/provisioning/scripts/setup.ps1 setup ch13 --org ``` **What setup creates** (all artifacts namespaced `wth-ch13-*`, idempotent, prefix-guarded teardown): diff --git a/modules/ghec/challenges/ch14-sso-saml-scim/README.md b/modules/ghec/challenges/ch14-sso-saml-scim/README.md index 6e9adf2..a00a5ff 100644 --- a/modules/ghec/challenges/ch14-sso-saml-scim/README.md +++ b/modules/ghec/challenges/ch14-sso-saml-scim/README.md @@ -38,13 +38,13 @@ Run the provisioning entrypoint (Bash or PowerShell — both supported). `wth` i # Bash wth setup ch14 --org # or directly: -bash modules/ghec/resources/provisioning/scripts/setup.sh ch14 --org +bash modules/ghec/resources/provisioning/scripts/setup.sh setup ch14 --org ``` ```powershell # PowerShell wth setup ch14 --org # or directly: -modules/ghec/resources/provisioning/scripts/setup.ps1 ch14 --org +modules/ghec/resources/provisioning/scripts/setup.ps1 setup ch14 --org ``` **What setup creates** (all artifacts namespaced `wth-ch14-*`, idempotent, prefix-guarded teardown): diff --git a/modules/ghec/challenges/ch15-security-campaigns-overview/README.md b/modules/ghec/challenges/ch15-security-campaigns-overview/README.md index a64877c..1f76bee 100644 --- a/modules/ghec/challenges/ch15-security-campaigns-overview/README.md +++ b/modules/ghec/challenges/ch15-security-campaigns-overview/README.md @@ -36,13 +36,13 @@ Run the provisioning entrypoint (Bash or PowerShell — both supported). `wth` i # Bash wth setup ch15 --org # or directly: -bash modules/ghec/resources/provisioning/scripts/setup.sh ch15 --org +bash modules/ghec/resources/provisioning/scripts/setup.sh setup ch15 --org ``` ```powershell # PowerShell wth setup ch15 --org # or directly: -modules/ghec/resources/provisioning/scripts/setup.ps1 ch15 --org +modules/ghec/resources/provisioning/scripts/setup.ps1 setup ch15 --org ``` **What setup creates** (all artifacts namespaced `wth-ch15-*`, idempotent, prefix-guarded teardown): diff --git a/modules/ghec/challenges/ch16-rest-graphql-automation/README.md b/modules/ghec/challenges/ch16-rest-graphql-automation/README.md index a2f7ee4..e36530a 100644 --- a/modules/ghec/challenges/ch16-rest-graphql-automation/README.md +++ b/modules/ghec/challenges/ch16-rest-graphql-automation/README.md @@ -36,13 +36,13 @@ Run the provisioning entrypoint (Bash or PowerShell — both supported). `wth` i # Bash wth setup ch16 --org # or directly: -bash modules/ghec/resources/provisioning/scripts/setup.sh ch16 --org +bash modules/ghec/resources/provisioning/scripts/setup.sh setup ch16 --org ``` ```powershell # PowerShell wth setup ch16 --org # or directly: -modules/ghec/resources/provisioning/scripts/setup.ps1 ch16 --org +modules/ghec/resources/provisioning/scripts/setup.ps1 setup ch16 --org ``` **What setup creates** (all artifacts namespaced `wth-ch16-*`, idempotent, prefix-guarded teardown): diff --git a/modules/ghec/challenges/ch17-webhooks-github-apps/README.md b/modules/ghec/challenges/ch17-webhooks-github-apps/README.md index c352b41..1ae8604 100644 --- a/modules/ghec/challenges/ch17-webhooks-github-apps/README.md +++ b/modules/ghec/challenges/ch17-webhooks-github-apps/README.md @@ -36,13 +36,13 @@ Run the provisioning entrypoint (Bash or PowerShell — both supported). `wth` i # Bash wth setup ch17 --org # or directly: -bash modules/ghec/resources/provisioning/scripts/setup.sh ch17 --org +bash modules/ghec/resources/provisioning/scripts/setup.sh setup ch17 --org ``` ```powershell # PowerShell wth setup ch17 --org # or directly: -modules/ghec/resources/provisioning/scripts/setup.ps1 ch17 --org +modules/ghec/resources/provisioning/scripts/setup.ps1 setup ch17 --org ``` **What setup creates** (all artifacts namespaced `wth-ch17-*`, idempotent, prefix-guarded teardown): diff --git a/modules/ghec/challenges/ch18-self-hosted-runners/README.md b/modules/ghec/challenges/ch18-self-hosted-runners/README.md index 1eb8e29..2fd9391 100644 --- a/modules/ghec/challenges/ch18-self-hosted-runners/README.md +++ b/modules/ghec/challenges/ch18-self-hosted-runners/README.md @@ -37,13 +37,13 @@ Run the provisioning entrypoint (Bash or PowerShell — both supported). `wth` i # Bash wth setup ch18 --org # or directly: -bash modules/ghec/resources/provisioning/scripts/setup.sh ch18 --org +bash modules/ghec/resources/provisioning/scripts/setup.sh setup ch18 --org ``` ```powershell # PowerShell wth setup ch18 --org # or directly: -modules/ghec/resources/provisioning/scripts/setup.ps1 ch18 --org +modules/ghec/resources/provisioning/scripts/setup.ps1 setup ch18 --org ``` **What setup creates** (all artifacts namespaced `wth-ch18-*`, idempotent, prefix-guarded teardown): diff --git a/modules/ghec/challenges/ch19-copilot-coding-agent/README.md b/modules/ghec/challenges/ch19-copilot-coding-agent/README.md index 970e9dd..3024a8b 100644 --- a/modules/ghec/challenges/ch19-copilot-coding-agent/README.md +++ b/modules/ghec/challenges/ch19-copilot-coding-agent/README.md @@ -39,13 +39,13 @@ Run the provisioning entrypoint (Bash or PowerShell — both supported). `wth` i # Bash wth setup ch19 --org # or directly: -bash modules/ghec/resources/provisioning/scripts/setup.sh ch19 --org +bash modules/ghec/resources/provisioning/scripts/setup.sh setup ch19 --org ``` ```powershell # PowerShell wth setup ch19 --org # or directly: -modules/ghec/resources/provisioning/scripts/setup.ps1 ch19 --org +modules/ghec/resources/provisioning/scripts/setup.ps1 setup ch19 --org ``` > `wth doctor ch19 --org ` runs first and **warns if the org looks EMU-managed** or if the Copilot cloud agent policy can't be confirmed. Heed it — the agent won't run on EMU repos. @@ -108,6 +108,6 @@ You are done when ALL of the following are true: - About Copilot cloud agent — https://docs.github.com/en/copilot/concepts/agents/cloud-agent/about-cloud-agent - Managing access to Copilot cloud agent — https://docs.github.com/en/copilot/concepts/agents/cloud-agent/access-management - Using Copilot to work on an issue — https://docs.github.com/en/copilot/using-github-copilot/coding-agent/using-copilot-to-work-on-an-issue -- Customizing or restricting Copilot cloud agent — https://docs.github.com/en/copilot/how-tos/agents/coding-agent +- Customizing or restricting Copilot cloud agent — https://docs.github.com/en/copilot/how-tos/use-copilot-agents/cloud-agent - Managing GitHub Copilot policies in your organization — https://docs.github.com/en/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-policies-for-copilot-in-your-organization - `gh pr` CLI manual — https://cli.github.com/manual/gh_pr diff --git a/modules/ghec/challenges/ch19-copilot-coding-agent/meta.yml b/modules/ghec/challenges/ch19-copilot-coding-agent/meta.yml index edac68b..a9a3bf9 100644 --- a/modules/ghec/challenges/ch19-copilot-coding-agent/meta.yml +++ b/modules/ghec/challenges/ch19-copilot-coding-agent/meta.yml @@ -42,5 +42,5 @@ references: - https://docs.github.com/en/copilot/concepts/agents/cloud-agent/about-cloud-agent - https://docs.github.com/en/copilot/concepts/agents/cloud-agent/access-management - https://docs.github.com/en/copilot/using-github-copilot/coding-agent/using-copilot-to-work-on-an-issue -- https://docs.github.com/en/copilot/how-tos/agents/coding-agent +- https://docs.github.com/en/copilot/how-tos/use-copilot-agents/cloud-agent - https://docs.github.com/en/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-policies-for-copilot-in-your-organization diff --git a/modules/ghec/challenges/ch20-automation-capstone/README.md b/modules/ghec/challenges/ch20-automation-capstone/README.md index 2a702cc..6a31b10 100644 --- a/modules/ghec/challenges/ch20-automation-capstone/README.md +++ b/modules/ghec/challenges/ch20-automation-capstone/README.md @@ -39,13 +39,13 @@ Run the provisioning entrypoint (Bash or PowerShell — both supported). `wth` w # Bash wth setup ch20 --org # or directly: -bash modules/ghec/resources/provisioning/scripts/setup.sh ch20 --org +bash modules/ghec/resources/provisioning/scripts/setup.sh setup ch20 --org ``` ```powershell # PowerShell wth setup ch20 --org # or directly: -modules/ghec/resources/provisioning/scripts/setup.ps1 ch20 --org +modules/ghec/resources/provisioning/scripts/setup.ps1 setup ch20 --org ``` **What setup creates** (all artifacts namespaced `wth-ch20-*`, idempotent, prefix-guarded teardown): diff --git a/modules/ghec/resources/provisioning/scripts/setup.ps1 b/modules/ghec/resources/provisioning/scripts/setup.ps1 index 42539ec..6470bd4 100755 --- a/modules/ghec/resources/provisioning/scripts/setup.ps1 +++ b/modules/ghec/resources/provisioning/scripts/setup.ps1 @@ -41,6 +41,7 @@ USAGE: COMMANDS: doctor Preflight: tooling, auth, required scopes/capabilities (no changes) provision Create all wth--* starting state (idempotent) + (alias: setup) status Report what wth--* artifacts currently exist teardown Delete ONLY wth--* artifacts (confirmation required) @@ -61,8 +62,10 @@ EXAMPLES: if (-not $Command) { Show-Usage; exit 1 } if ($Command -in @('-h', '--help', 'help')) { Show-Usage; exit 0 } +# `setup` is a friendly alias for `provision` (the verb used throughout the docs). +if ($Command -eq 'setup') { $Command = 'provision' } if ($Command -notin @('doctor', 'provision', 'status', 'teardown')) { - Stop-Wth "unknown command '$Command' (expected doctor|provision|status|teardown)" + Stop-Wth "unknown command '$Command' (expected doctor|provision|setup|status|teardown)" } if (-not $Chid) { Stop-Wth 'missing challenge id (e.g. ch01)' } diff --git a/modules/ghec/resources/provisioning/scripts/setup.sh b/modules/ghec/resources/provisioning/scripts/setup.sh index 6f36506..8f99491 100755 --- a/modules/ghec/resources/provisioning/scripts/setup.sh +++ b/modules/ghec/resources/provisioning/scripts/setup.sh @@ -48,6 +48,7 @@ USAGE: COMMANDS: doctor Preflight: tooling, auth, required scopes/capabilities (no changes) provision Create all wth--* starting state for the challenge (idempotent) + (alias: setup) status Report what wth--* artifacts currently exist teardown Delete ONLY wth--* artifacts (confirmation required) @@ -71,6 +72,8 @@ EOF # ---- arg parsing ----------------------------------------------------------- [[ $# -lt 1 ]] && { usage; exit 1; } COMMAND="$1"; shift || true +# `setup` is a friendly alias for `provision` (the verb used throughout the docs). +[[ "$COMMAND" == "setup" ]] && COMMAND="provision" while [[ $# -gt 0 ]]; do case "$1" in @@ -88,7 +91,7 @@ done case "$COMMAND" in doctor|provision|status|teardown) ;; -h|--help) usage; exit 0 ;; - *) die "unknown command '$COMMAND' (expected doctor|provision|status|teardown)" ;; + *) die "unknown command '$COMMAND' (expected doctor|provision|setup|status|teardown)" ;; esac [[ -n "$CHID" ]] || die "missing challenge id (e.g. ch01)"