Inject agentic-workflows MCP usage guide as a compiler-level builtin prompt

actions/setup/md/agentic_workflows_guide.md

@@ -0,0 +1,30 @@
+<agentic-workflows-guide>
+## Using the agentic-workflows MCP Server
+
+**⚠️ CRITICAL**: The `status`, `logs`, `audit`, and `compile` operations are MCP server tools,
+NOT shell commands. Do NOT run `gh aw` directly — it is not authenticated in this context.
+Do not attempt to download or build the `gh aw` extension. If the MCP server fails, give up.
+Call all operations as MCP tools with JSON parameters.
+
+- Run the `status` tool to verify configuration and list all workflows
+- Use the `logs` tool to download run logs (saves to `/tmp/gh-aw/aw-mcp/logs/`)
+- Use the `audit` tool with a run ID or URL to investigate specific runs
+
+### Tool Parameters
+
+#### `status` — Verify MCP server configuration and list workflows
+
+#### `logs` — Download workflow run logs
+- `workflow_name`: filter to a specific workflow (leave empty for all)
+- `count`: number of runs (default: 100)
+- `start_date`: filter runs after this date (YYYY-MM-DD or relative like `-1d`, `-7d`, `-30d`)
+- `end_date`: filter runs before this date
+- `engine`: filter by AI engine (`copilot`, `claude`, `codex`)
+- `branch`: filter by branch name
+- `firewall` / `no_firewall`: filter by firewall status
+- `after_run_id` / `before_run_id`: paginate by run database ID
+- Logs are saved to `/tmp/gh-aw/aw-mcp/logs/`
+
+#### `audit` — Inspect a specific run
+- `run_id_or_url`: numeric run ID, run URL, job URL, or job URL with step anchor
+</agentic-workflows-guide>

pkg/workflow/prompt_constants.go

@@ -18,6 +18,7 @@ const (
 	safeOutputsCreatePRFile        = "safe_outputs_create_pull_request.md"
 	safeOutputsPushToBranchFile    = "safe_outputs_push_to_pr_branch.md"
 	safeOutputsAutoCreateIssueFile = "safe_outputs_auto_create_issue.md"
+	agenticWorkflowsGuideFile      = "agentic_workflows_guide.md"
 )
 
 // GitHub context prompt is kept embedded because it contains GitHub Actions expressions

pkg/workflow/prompts.go

@@ -29,6 +29,21 @@ func hasPlaywrightTool(parsedTools *Tools) bool {
 	return hasPlaywright
 }
 
+// ============================================================================
+// Tool Prompts - Agentic Workflows
+// ============================================================================
+
+// hasAgenticWorkflowsTool checks if the agentic workflows tool is enabled in the tools configuration
+func hasAgenticWorkflowsTool(parsedTools *Tools) bool {
+	if parsedTools == nil {
+		log.Print("Checking for agentic-workflows tool: no parsed tools provided")
+		return false
+	}
+	hasAgenticWorkflows := parsedTools.AgenticWorkflows != nil
+	log.Printf("Agentic-workflows tool enabled: %v", hasAgenticWorkflows)
+	return hasAgenticWorkflows
+}
+
 // ============================================================================
 // PR Context Prompts
 // ============================================================================

pkg/workflow/prompts_test.go

@@ -750,3 +750,101 @@ This is a test workflow without contents read permission.
 
 	t.Logf("Successfully verified PR context instructions are NOT included without contents permission")
 }
+
+// ============================================================================
+// Agentic Workflows Guide Prompt Tests
+// ============================================================================
+
+func TestAgenticWorkflowsGuideIncludedWhenEnabled(t *testing.T) {
+	tmpDir, err := os.MkdirTemp("", "gh-aw-agentic-guide-test-*")
+	if err != nil {
+		t.Fatalf("Failed to create temp dir: %v", err)
+	}
+	defer os.RemoveAll(tmpDir)
+
+	testFile := filepath.Join(tmpDir, "test-workflow.md")
+	testContent := `---
+on: schedule daily
+engine: claude
+tools:
+  agentic-workflows:
+permissions:
+  actions: read
+---
+
+# Test Workflow with Agentic Workflows
+
+This workflow uses the agentic-workflows MCP server.
+`
+
+	if err := os.WriteFile(testFile, []byte(testContent), 0644); err != nil {
+		t.Fatalf("Failed to create test workflow: %v", err)
+	}
+
+	compiler := NewCompiler()
+	if err := compiler.CompileWorkflow(testFile); err != nil {
+		t.Fatalf("Failed to compile workflow: %v", err)
+	}
+
+	lockFile := stringutil.MarkdownToLockFile(testFile)
+	lockContent, err := os.ReadFile(lockFile)
+	if err != nil {
+		t.Fatalf("Failed to read generated lock file: %v", err)
+	}
+
+	lockStr := string(lockContent)
+
+	if !strings.Contains(lockStr, "- name: Create prompt with built-in context") {
+		t.Error("Expected 'Create prompt with built-in context' step in generated workflow")
+	}
+
+	if !strings.Contains(lockStr, "cat \"/opt/gh-aw/prompts/agentic_workflows_guide.md\"") {
+		t.Error("Expected cat command for agentic_workflows_guide.md in generated workflow")
+	}
+
+	t.Logf("Successfully verified agentic-workflows guide is included when agentic-workflows tool is enabled")
+}
+
+func TestAgenticWorkflowsGuideNotIncludedWhenDisabled(t *testing.T) {
+	tmpDir, err := os.MkdirTemp("", "gh-aw-no-agentic-guide-test-*")
+	if err != nil {
+		t.Fatalf("Failed to create temp dir: %v", err)
+	}
+	defer os.RemoveAll(tmpDir)
+
+	testFile := filepath.Join(tmpDir, "test-workflow.md")
+	testContent := `---
+on: push
+engine: codex
+tools:
+  github:
+---
+
+# Test Workflow without Agentic Workflows
+
+This workflow does not use the agentic-workflows MCP server.
+`
+
+	if err := os.WriteFile(testFile, []byte(testContent), 0644); err != nil {
+		t.Fatalf("Failed to create test workflow: %v", err)
+	}
+
+	compiler := NewCompiler()
+	if err := compiler.CompileWorkflow(testFile); err != nil {
+		t.Fatalf("Failed to compile workflow: %v", err)
+	}
+
+	lockFile := stringutil.MarkdownToLockFile(testFile)
+	lockContent, err := os.ReadFile(lockFile)
+	if err != nil {
+		t.Fatalf("Failed to read generated lock file: %v", err)
+	}
+
+	lockStr := string(lockContent)
+
+	if strings.Contains(lockStr, "agentic_workflows_guide.md") {
+		t.Error("Did not expect 'agentic_workflows_guide.md' reference in workflow without agentic-workflows tool")
+	}
+
+	t.Logf("Successfully verified agentic-workflows guide is NOT included when agentic-workflows tool is disabled")
+}

pkg/workflow/testdata/wasm_golden/TestWasmGolden_CompileFixtures/smoke-copilot.golden

@@ -125,6 +125,7 @@ jobs:
           cat "/opt/gh-aw/prompts/temp_folder_prompt.md"
           cat "/opt/gh-aw/prompts/markdown.md"
           cat "/opt/gh-aw/prompts/playwright_prompt.md"
+          cat "/opt/gh-aw/prompts/agentic_workflows_guide.md"
           cat << 'GH_AW_PROMPT_EOF'
           <github-context>
           The following GitHub context information is available for this workflow: