From 6b2e467cac862f9908ed49e23b4804029ddf36f9 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Tue, 7 Jul 2026 09:54:37 +0000 Subject: [PATCH] [instructions] Sync instruction files with release v0.82.2 Accuracy: document the `evals` frontmatter field (only undocumented top-level schema key); rescope `github-token`/`bots` under `on:` in syntax-agentic.md. Duplication: collapse the cost-aware triage bullet sets in the creator and updater prompts to reference the canonical High-Volume Triage and Escalation Pattern. Cleanup: fix orphaned report-incomplete paragraph in safe-outputs-runtime.md. Co-Authored-By: Claude Opus 4.8 (1M context) --- .github/aw/create-agentic-workflow.md | 7 ++----- .github/aw/safe-outputs-runtime.md | 3 +-- .github/aw/syntax-agentic.md | 5 +++-- .github/aw/update-agentic-workflow.md | 11 +---------- 4 files changed, 7 insertions(+), 19 deletions(-) diff --git a/.github/aw/create-agentic-workflow.md b/.github/aw/create-agentic-workflow.md index 15a72102978..38baf93b74b 100644 --- a/.github/aw/create-agentic-workflow.md +++ b/.github/aw/create-agentic-workflow.md @@ -169,13 +169,10 @@ Rules: ### 8. Add cost-aware triage and context flow -- For high-volume inputs, design a cheap triage step before expensive analysis. -- Require explicit `noop` or safe-output behavior for known, duplicate, stale, or low-value cases. -- Reserve frontier-model reasoning for ambiguous/high-value cases and final synthesis. -- Prefer pull-on-demand context retrieval over prompt-stuffing large logs or API payloads. +- For high-volume inputs, apply the [High-Volume Triage and Escalation Pattern](workflow-patterns.md#high-volume-triage-and-escalation-pattern): cheap triage first, `noop`/safe output for known/duplicate/stale/low-value cases, frontier reasoning reserved for ambiguous/high-value cases, and context pulled on demand. - Use deterministic `steps:` plus compact files under `/tmp/gh-aw/` when large data must be preprocessed. -See also: [workflow-patterns.md](workflow-patterns.md), [subagents.md](subagents.md), and [token-optimization.md](token-optimization.md). +See also: [subagents.md](subagents.md) and [token-optimization.md](token-optimization.md). ### 9. Omit unnecessary defaults diff --git a/.github/aw/safe-outputs-runtime.md b/.github/aw/safe-outputs-runtime.md index 01632e178c9..01035b227f0 100644 --- a/.github/aw/safe-outputs-runtime.md +++ b/.github/aw/safe-outputs-runtime.md @@ -4,8 +4,7 @@ description: Safe-output reference for runtime defaults, custom jobs, scripts, a # Safe Outputs: Runtime and Extensibility - - The report-incomplete safe-output is automatically enabled by default and is distinct from `noop`. Use it when required tools or data are unavailable and the task cannot be meaningfully performed (e.g., MCP server crash, missing authentication, inaccessible repository). When an agent emits `report_incomplete`, gh-aw activates failure handling even when the agent process exits 0 — preventing empty outputs from being classified as successful. This ensures every unrecoverable failure is tracked. +The `report-incomplete` safe-output is enabled by default and is distinct from `noop`. Use it when required tools or data are unavailable and the task cannot be meaningfully performed (e.g., MCP server crash, missing authentication, inaccessible repository). When an agent emits `report_incomplete`, gh-aw activates failure handling even when the agent process exits 0 — preventing empty outputs from being classified as successful, so every unrecoverable failure is tracked. - `jobs:` - Custom safe-output jobs registered as MCP tools for third-party integrations diff --git a/.github/aw/syntax-agentic.md b/.github/aw/syntax-agentic.md index ab8254d34e4..a2ad53c8f2b 100644 --- a/.github/aw/syntax-agentic.md +++ b/.github/aw/syntax-agentic.md @@ -16,9 +16,9 @@ description: Agentic workflow specific frontmatter fields for GitHub Agentic Wor - Key names limited to 64 characters - Values limited to 1024 characters - Example: `metadata: { team: "platform", priority: "high" }` -- **`github-token:`** - Default GitHub token for workflow (must use `${{ secrets.* }}` syntax) +- **`github-token:`** - GitHub token override (must use `${{ secrets.* }}` syntax). Not a top-level field: set it under `on:` (trigger checks), `tools.github`, or `safe-outputs`. - **`on.roles:`** - Repository access roles that can trigger workflow (array or `"all"`). Default `[admin, maintainer, write]`; available roles: `admin`, `maintainer`, `write`, `read`, `all`. -- **`bots:`** - Bot identifiers allowed to trigger workflow regardless of role permissions (array; e.g. `[dependabot[bot], renovate[bot], github-actions[bot]]`). The bot must be active (installed) on the repository to trigger. +- **`on.bots:`** - Bot identifiers allowed to trigger workflow regardless of role permissions (array; e.g. `[dependabot[bot], renovate[bot], github-actions[bot]]`). The bot must be active (installed) on the repository to trigger. - **`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 - **`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. @@ -81,6 +81,7 @@ description: Agentic workflow specific frontmatter fields for GitHub Agentic Wor - Selected variant available as `${{ experiments. }}` and in `{{#if experiments. }}` template blocks - See [A/B Testing Experiments](experiments.md) for full design guidance +- **`evals:`** - ⚠️ Experimental. BinEval binary (YES/NO) evaluation questions run after safe-outputs and before the conclusion job. Shorthand: a list of `{ id, question, model? }` objects. Extended form: object with `questions`, plus optional `model` (default alias/ID for all questions) and `runs-on`. - **`imports:`** - Array of workflow specifications to import (array) - Format: `owner/repo/path@ref` or local paths like `shared/common.md` diff --git a/.github/aw/update-agentic-workflow.md b/.github/aw/update-agentic-workflow.md index bfbaa6cffd5..d0827dabfa1 100644 --- a/.github/aw/update-agentic-workflow.md +++ b/.github/aw/update-agentic-workflow.md @@ -58,16 +58,7 @@ See [workflow-editing.md](workflow-editing.md) for the full frontmatter-vs-body ## Cost-Oriented Update Checks -When refining existing workflows, preserve minimal edits while verifying: - -- cheap triage runs before escalation for high-volume inputs -- known/duplicate/stale/low-value cases stop with explicit `noop` or safe output -- expensive/frontier reasoning is limited to ambiguous or high-value cases and final synthesis -- large raw logs/payloads are pulled on demand instead of pushed into initial prompts -- sub-agent fan-out stays bounded and worker returns stay compact -- changes are measured with `gh aw audit` (`aic`, input/output/cache token fields) and quality regressions are treated as failures - -See also: [token-optimization.md](token-optimization.md), [subagents.md](subagents.md), and [workflow-patterns.md](workflow-patterns.md). +When refining existing workflows, keep edits minimal and confirm the design still follows the [High-Volume Triage and Escalation Pattern](workflow-patterns.md#high-volume-triage-and-escalation-pattern): cheap triage before escalation, `noop`/safe output for known/duplicate/stale cases, frontier reasoning reserved for high-value cases, and context pulled on demand. Keep sub-agent fan-out bounded (see [subagents.md](subagents.md)), then measure the change with `gh aw audit` and treat token or quality regressions as failures (see [token-optimization.md](token-optimization.md)). ## Security Rules