Merge main branch into jsweep PR

.devcontainer/devcontainer.json

@@ -3,7 +3,14 @@
   "image": "mcr.microsoft.com/devcontainers/go:1-bookworm",
   "customizations": {
     "vscode": {
-      "extensions": ["golang.go", "GitHub.copilot-chat", "GitHub.copilot", "github.vscode-github-actions", "astro-build.astro-vscode", "DavidAnson.vscode-markdownlint"]
+      "extensions": [
+        "golang.go",
+        "GitHub.copilot-chat",
+        "GitHub.copilot",
+        "github.vscode-github-actions",
+        "astro-build.astro-vscode",
+        "DavidAnson.vscode-markdownlint"
+      ]
     },
     "codespaces": {
       "repositories": {

.github/aw/schemas/agentic-workflow.json

@@ -1,5 +1,9 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/githubnext/gh-aw/schemas/main_workflow_schema.json",
+  "title": "GitHub Agentic Workflow Schema",
+  "description": "JSON Schema for validating agentic workflow frontmatter configuration",
+  "version": "1.0.0",
   "type": "object",
   "required": ["on"],
   "properties": {
@@ -115,6 +119,7 @@
     },
     "on": {
       "description": "Workflow triggers that define when the agentic workflow should run. Supports standard GitHub Actions trigger events plus special command triggers for /commands (required)",
+      "examples": [{ "issues": { "types": ["opened"] } }, { "pull_request": { "types": ["opened", "synchronize"] } }, "workflow_dispatch", { "schedule": "daily at 9am" }, "/my-bot"],
       "oneOf": [
         {
           "type": "string",
@@ -2330,6 +2335,8 @@
             ]
           },
           "examples": [
+            [{ "prompt": "Analyze the issue and create a plan" }],
+            [{ "uses": "actions/checkout@v4" }, { "prompt": "Review the code and suggest improvements" }],
             [
               {
                 "name": "Download logs from last 24 hours",
@@ -2388,11 +2395,27 @@
     "engine": {
       "description": "AI engine configuration that specifies which AI processor interprets and executes the markdown content of the workflow. Defaults to 'copilot'.",
       "default": "copilot",
+      "examples": ["copilot", "claude", "codex", { "id": "copilot", "version": "beta" }, { "id": "claude", "model": "claude-3-5-sonnet-20241022", "max-turns": 15 }],
       "$ref": "#/$defs/engine_config"
     },
     "mcp-servers": {
       "type": "object",
       "description": "MCP server definitions",
+      "examples": [
+        {
+          "filesystem": {
+            "type": "stdio",
+            "command": "npx",
+            "args": ["-y", "@modelcontextprotocol/server-filesystem"]
+          }
+        },
+        {
+          "custom-server": {
+            "type": "http",
+            "url": "https://api.example.com/mcp"
+          }
+        }
+      ],
       "patternProperties": {
         "^[a-zA-Z0-9_-]+$": {
           "oneOf": [
@@ -2410,6 +2433,7 @@
     "tools": {
       "type": "object",
       "description": "Tools and MCP (Model Context Protocol) servers available to the AI engine for GitHub API access, browser automation, file editing, and more",
+      "examples": [{ "playwright": { "version": "v1.41.0" } }, { "github": { "mode": "remote" } }, { "github": { "mode": "local", "version": "latest" } }, { "bash": null }],
       "properties": {
         "github": {
           "description": "GitHub API tools for repository operations (issues, pull requests, content management)",
@@ -3326,6 +3350,24 @@
       "type": "object",
       "$comment": "Required if workflow creates or modifies GitHub resources. Operations requiring safe-outputs: add-comment, add-labels, add-reviewer, assign-milestone, assign-to-agent, close-discussion, close-issue, close-pull-request, create-agent-task, create-code-scanning-alert, create-discussion, create-issue, create-pull-request, create-pull-request-review-comment, hide-comment, link-sub-issue, missing-tool, noop, push-to-pull-request-branch, threat-detection, update-discussion, update-issue, update-project, update-pull-request, update-release, upload-asset. See documentation for complete details.",
       "description": "Safe output processing configuration that automatically creates GitHub issues, comments, and pull requests from AI workflow output without requiring write permissions in the main job",
+      "examples": [
+        {
+          "create-issue": {
+            "title-prefix": "[AI] ",
+            "labels": ["automation", "ai-generated"]
+          }
+        },
+        {
+          "create-pull-request": {
+            "title-prefix": "[Bot] ",
+            "labels": ["bot"]
+          }
+        },
+        {
+          "add-comment": null,
+          "create-issue": null
+        }
+      ],
       "properties": {
         "allowed-domains": {
           "type": "array",
@@ -3390,10 +3432,6 @@
                   },
                   "description": "List of additional repositories in format 'owner/repo' that issues can be created in. When specified, the agent can use a 'repo' field in the output to specify which repository to create the issue in. The target repository (current or target-repo) is always implicitly allowed."
                 },
-                "github-token": {
-                  "$ref": "#/$defs/github_token",
-                  "description": "GitHub token to use for this specific output type. Overrides global github-token if specified."
-                },
                 "expires": {
                   "oneOf": [
                     {
@@ -3547,10 +3585,6 @@
                   },
                   "description": "List of additional repositories in format 'owner/repo' that discussions can be created in. When specified, the agent can use a 'repo' field in the output to specify which repository to create the discussion in. The target repository (current or target-repo) is always implicitly allowed."
                 },
-                "github-token": {
-                  "$ref": "#/$defs/github_token",
-                  "description": "GitHub token to use for this specific output type. Overrides global github-token if specified."
-                },
                 "close-older-discussions": {
                   "type": "boolean",
                   "description": "When true, automatically close older discussions matching the same title prefix or labels as 'outdated' with a comment linking to the new discussion. Requires title-prefix or labels to be set. Maximum 10 discussions will be closed. Only runs if discussion creation succeeds.",
@@ -3641,10 +3675,6 @@
                 "target-repo": {
                   "type": "string",
                   "description": "Target repository in format 'owner/repo' for cross-repository operations. Takes precedence over trial target repo settings."
-                },
-                "github-token": {
-                  "$ref": "#/$defs/github_token",
-                  "description": "GitHub token to use for this specific output type. Overrides global github-token if specified."
                 }
               },
               "additionalProperties": false,
@@ -3702,10 +3732,6 @@
                 "target-repo": {
                   "type": "string",
                   "description": "Target repository in format 'owner/repo' for cross-repository discussion updates. Takes precedence over trial target repo settings."
-                },
-                "github-token": {
-                  "$ref": "#/$defs/github_token",
-                  "description": "GitHub token to use for this specific output type. Overrides global github-token if specified."
                 }
               },
               "additionalProperties": false
@@ -3746,10 +3772,6 @@
                 "target-repo": {
                   "type": "string",
                   "description": "Target repository in format 'owner/repo' for cross-repository operations. Takes precedence over trial target repo settings."
-                },
-                "github-token": {
-                  "$ref": "#/$defs/github_token",
-                  "description": "GitHub token to use for this specific output type. Overrides global github-token if specified."
                 }
               },
               "additionalProperties": false,
@@ -3842,10 +3864,6 @@
                   "type": "string",
                   "description": "Target repository in format 'owner/repo' for cross-repository comments. Takes precedence over trial target repo settings."
                 },
-                "github-token": {
-                  "$ref": "#/$defs/github_token",
-                  "description": "GitHub token to use for this specific output type. Overrides global github-token if specified."
-                },
                 "discussion": {
                   "type": "boolean",
                   "const": true,
@@ -4316,10 +4334,6 @@
                 "target-repo": {
                   "type": "string",
                   "description": "Target repository in format 'owner/repo' for cross-repository issue updates. Takes precedence over trial target repo settings."
-                },
-                "github-token": {
-                  "$ref": "#/$defs/github_token",
-                  "description": "GitHub token to use for this specific output type. Overrides global github-token if specified."
                 }
               },
               "additionalProperties": false