From fdd9d704a4c6009c7d619ee969080823f1dd0545 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Sun, 2 Aug 2026 09:27:18 +0000 Subject: [PATCH] [instructions] Sync instruction files with release v0.84.2 Fix stale Gemini engine capability claims (max-turns and web-fetch are actually supported per gemini_engine.go/gemini_tools.go), document the undocumented 64-char create-discussion body minimum, and remove duplicated security-posture/core-rules bullets across github-agentic-workflows.md, create-agentic-workflow.md, and update-agentic-workflow.md in favor of referencing workflow-constraints.md. Co-Authored-By: Claude Sonnet 5 --- .github/aw/create-agentic-workflow.md | 3 +-- .github/aw/github-agentic-workflows.md | 21 +++++++++------------ .github/aw/safe-outputs-content.md | 2 ++ .github/aw/syntax-agentic.md | 2 +- .github/aw/syntax-engine.md | 2 +- .github/aw/update-agentic-workflow.md | 4 ++-- 6 files changed, 16 insertions(+), 18 deletions(-) diff --git a/.github/aw/create-agentic-workflow.md b/.github/aw/create-agentic-workflow.md index dd327252e96..6831a413491 100644 --- a/.github/aw/create-agentic-workflow.md +++ b/.github/aw/create-agentic-workflow.md @@ -126,10 +126,9 @@ Use [triggers.md](triggers.md), [workflow-patterns.md](workflow-patterns.md), an ### 3. Keep permissions read-only -The main agent job must stay read-only. +See [workflow-constraints.md](workflow-constraints.md) for the read-only security posture. Specific to workflow creation: - Do not grant `issues: write`, `pull-requests: write`, or `contents: write` to the agent job. -- Route GitHub writes through `safe-outputs:`. - When targeting the Copilot coding agent, recommend `permissions: { copilot-requests: write }` so Copilot can authenticate with `${{ github.token }}`. - If the user asks for direct writes, explain why the safe-output pattern is required. diff --git a/.github/aw/github-agentic-workflows.md b/.github/aw/github-agentic-workflows.md index 01f5012b62d..ee9ec079acb 100644 --- a/.github/aw/github-agentic-workflows.md +++ b/.github/aw/github-agentic-workflows.md @@ -64,16 +64,11 @@ See also: [workflow-editing.md](workflow-editing.md) ## Core Rules -- Keep the main agent job read-only. -- Use `safe-outputs:` for GitHub writes. -- Prefer `tools.github.mode: gh-proxy` and use `gh` for GitHub reads. -- For non-GitHub MCP servers, prefer `tools.cli-proxy: true` and use mounted `mcp-clis` commands. -- Use `${{ steps.sanitized.outputs.text }}` for untrusted user content. - Set `strict: true` for production workflows. -- Limit network and bash access to what the workflow actually needs. +- Limit `bash` access to what the workflow actually needs. - For visual regression workflows, explicitly name the baseline source (for example `cache-memory` key, artifact, or branch path). See [visual-regression.md](visual-regression.md). -See [workflow-constraints.md](workflow-constraints.md) for the full security posture, safer-alternatives pattern, and common risk areas. +See [workflow-constraints.md](workflow-constraints.md) for the security posture (read-only job, safe-outputs routing, gh-proxy/cli-proxy, network constraints, sanitized text), safer-alternatives pattern, and common risk areas. ## Repository-Specific Instructions @@ -107,11 +102,13 @@ Installed gh-aw agents should support scenario evaluation requests that do not c ### Non-technical persona examples -| Persona | Default trigger | Default output | Key prompt details | -|---|---|---|---| -| Program Manager | `schedule` (+ `workflow_dispatch` for previews/backfills) | `create-issue` with `close-older-issues: true` | Report window, grouping dimensions, stable dedup key, and `noop` for empty windows | -| Designer | `pull_request` with `paths:` scoped to UI, design-token, copy, and asset files | `add-comment` | Review rubric (accessibility, token consistency, asset policy); `noop` when scoped files unchanged | -| Legal / Compliance | `pull_request` with `paths:` scoped to dependency manifests or policy docs; `schedule` for recurring audits | `add-comment` for findings; `create-issue` for violations | Classify against policy tiers; dedup before escalating; `noop` when no in-scope change or violation | +Trigger and write-path are the same as the [Persona-to-Pattern Quick Matrix](#persona-to-pattern-quick-matrix) above. For ad hoc evaluation, also gather: + +| Persona | Key prompt details | +|---|---| +| Program Manager | Report window, grouping dimensions, stable dedup key, and `noop` for empty windows | +| Designer | Review rubric (accessibility, token consistency, asset policy); `noop` when scoped files unchanged | +| Legal / Compliance | Classify against policy tiers; dedup before escalating; `noop` when no in-scope change or violation | ## PR Checks with Linked References diff --git a/.github/aw/safe-outputs-content.md b/.github/aw/safe-outputs-content.md index 4c5f472d471..b8233048e40 100644 --- a/.github/aw/safe-outputs-content.md +++ b/.github/aw/safe-outputs-content.md @@ -104,6 +104,8 @@ description: Safe-output reference for issue, discussion, comment, and pull requ `close-older-discussions: true` closes up to 10 older discussions matching the same title prefix or labels as "OUTDATED" with a comment linking to the new one. Requires `title-prefix` or `labels`. + `create_discussion` output validation requires `body` minimum length: **64** characters. + - `close-discussion:` - Close discussions with comment and resolution ```yaml diff --git a/.github/aw/syntax-agentic.md b/.github/aw/syntax-agentic.md index f31aad051e3..1dd53c940fc 100644 --- a/.github/aw/syntax-agentic.md +++ b/.github/aw/syntax-agentic.md @@ -22,7 +22,7 @@ description: Agentic workflow specific frontmatter fields for GitHub Agentic Wor - **`strict:`** - Enable enhanced validation for production workflows (boolean, defaults to `true`; strongly recommended) - Prefer `strict: true`; `strict: false` is dangerous, should be extremely rare, and must be carefully security reviewed before use - **`model:`** - Top-level LLM model override applied to the agentic engine (string). Takes precedence over `engine.model` when both are set. Accepts full model IDs (e.g. `claude-3-5-sonnet-20241022`, `gpt-5.4`) and aliases (e.g. `small`, `large`). The engine-level `engine.model` is a deprecated alias — prefer this top-level field; run `gh aw fix` to migrate. -- **`max-turns:`** - AWF turn cap applied consistently across all agentic engines (integer or expression, e.g. `${{ inputs.max-turns }}`). The engine-level `engine.max-turns` is a deprecated alias kept for backward compatibility — prefer this top-level field. Not supported by the `gemini` engine. +- **`max-turns:`** - AWF turn cap applied consistently across all agentic engines (integer or expression, e.g. `${{ inputs.max-turns }}`). The engine-level `engine.max-turns` is a deprecated alias kept for backward compatibility — prefer this top-level field. - **`max-runs:`** - Deprecated legacy alias for the AWF invocation cap (`apiProxy.maxRuns`, defaults to `500` when omitted). Use `max-turns` instead; run `gh aw fix` to migrate. - **`max-ai-credits:`** - Per-run AI Credits (AIC) budget enforced by the AWF firewall (integer or `K`/`M` short-form string like `100M`; default `1000`). Set a negative value to disable enforcement and token steering. See [token-optimization.md](token-optimization.md). - **`max-turn-cache-misses:`** - Maximum consecutive AWF cache misses allowed before the API proxy blocks further requests (integer, default `5`). Maps to `apiProxy.maxCacheMisses`; precedence is frontmatter → `GH_AW_DEFAULT_MAX_TURN_CACHE_MISSES` env override → built-in default. diff --git a/.github/aw/syntax-engine.md b/.github/aw/syntax-engine.md index 1d22c6cb918..f606fd7a730 100644 --- a/.github/aw/syntax-engine.md +++ b/.github/aw/syntax-engine.md @@ -32,7 +32,7 @@ See [syntax-agentic.md](syntax-agentic.md) for the full frontmatter field index. key = "value" ``` - - **`gemini` engine**: Google Gemini CLI. Requires `GEMINI_API_KEY` secret. Does not support `max-turns`, `web-fetch`, or `web-search`. Supports AWF firewall and LLM gateway. + - **`gemini` engine**: Google Gemini CLI. Requires `GEMINI_API_KEY` secret. Does not support `web-search`. Supports AWF firewall and LLM gateway. - **`antigravity` engine** (experimental): Google Antigravity CLI in headless mode. Requires `ANTIGRAVITY_API_KEY` secret; model via `model:` (maps to `ANTIGRAVITY_MODEL`). Supports `max-turns`, tools allow-list, AWF firewall, and LLM gateway. Does not support `web-search`, `max-continuations`, or native agent files (agent content is prepended to the prompt). - **`opencode` engine** (experimental): Provider-agnostic, open-source AI coding agent (BYOK). Defaults to Copilot routing via `COPILOT_GITHUB_TOKEN` (or `${{ github.token }}` with `copilot-requests` feature). Supports 75+ models via `provider/model` format. Supports AWF firewall and LLM gateway. - **`engine.driver:`** — canonical field to run a custom inner driver script instead of the engine's built-in CLI. For the `pi` engine it launches the driver directly with Node.js (e.g. built-in `pi_agent_core_driver.cjs`, or a workspace-relative path like `.github/drivers/pi_agent_core_driver_sample_node.cjs`); the driver must emit JSONL compatible with `parse_pi_log.cjs` so step summaries and token tracking keep working. Accepts a bare basename (resolved from the setup-action directory) or a workspace-relative path; no absolute paths, no `..`, only `.js`/`.cjs`/`.mjs` (pi). diff --git a/.github/aw/update-agentic-workflow.md b/.github/aw/update-agentic-workflow.md index 4c8ad16cd4a..765b3c9263d 100644 --- a/.github/aw/update-agentic-workflow.md +++ b/.github/aw/update-agentic-workflow.md @@ -45,11 +45,11 @@ Use [workflow-editing.md](workflow-editing.md) as the source of truth. - make the smallest possible change - preserve existing style and structure unless reorganization is required - do not rewrite unrelated frontmatter sections -- keep the agent job read-only - when targeting the Copilot coding agent, recommend `permissions: { copilot-requests: write }` for Copilot authentication -- use `safe-outputs:` for writes - prefer `toolsets:` for GitHub tools +See [workflow-constraints.md](workflow-constraints.md) for the read-only security posture (keep the agent job read-only, route writes through `safe-outputs:`). + ## Common Update Categories See [workflow-editing.md](workflow-editing.md) for the full frontmatter-vs-body recompilation taxonomy and the field list that requires `gh aw compile ` plus a `.lock.yml` review.