feat: add engine.bare frontmatter field to suppress automatic context loading (#25661)

Copilot · web-flow · commit 5b9e9803a4b1 · 2026-04-10T10:53:48.000-07:00
diff --git a/.changeset/patch-add-engine-bare-frontmatter-field.md b/.changeset/patch-add-engine-bare-frontmatter-field.md
diff --git a/.github/workflows/smoke-claude.lock.yml b/.github/workflows/smoke-claude.lock.yml
diff --git a/.github/workflows/smoke-claude.md b/.github/workflows/smoke-claude.md
@@ -19,6 +19,7 @@ name: Smoke Claude
 engine:
   id: claude
   max-turns: 100
+  bare: true
 strict: false
 inlined-imports: true
 imports:
diff --git a/.github/workflows/smoke-copilot.lock.yml b/.github/workflows/smoke-copilot.lock.yml
diff --git a/.github/workflows/smoke-copilot.md b/.github/workflows/smoke-copilot.md
@@ -19,6 +19,7 @@ name: Smoke Copilot
 engine:
   id: copilot
   max-continuations: 2
+  bare: true
 imports:
   - shared/github-guard-policy.md
   - shared/gh.md
diff --git a/pkg/parser/schemas/main_workflow_schema.json b/pkg/parser/schemas/main_workflow_schema.json
@@ -9253,6 +9253,11 @@
                 "type": "string"
               },
               "description": "Optional array of command-line arguments to pass to the AI engine CLI. These arguments are injected after all other args but before the prompt."
+            },
+            "bare": {
+              "type": "boolean",
+              "description": "When true, disables automatic loading of context and custom instructions by the AI engine. The engine-specific flag depends on the engine: copilot uses --no-custom-instructions (suppresses .github/AGENTS.md and user-level custom instructions), claude uses --bare (suppresses CLAUDE.md memory files), codex uses --no-system-prompt (suppresses the default system prompt), gemini sets GEMINI_SYSTEM_MD=/dev/null (overrides the built-in system prompt with an empty one). Defaults to false.",
+              "default": false
             }
           },
           "required": ["id"],
@@ -9374,6 +9379,11 @@
                 }
               },
               "additionalProperties": false
+            },
+            "bare": {
+              "type": "boolean",
+              "description": "When true, disables automatic loading of context and custom instructions by the AI engine. The engine-specific flag depends on the engine: copilot uses --no-custom-instructions, claude uses --bare, codex uses --no-system-prompt, gemini sets GEMINI_SYSTEM_MD=/dev/null. Defaults to false.",
+              "default": false
             }
           },
           "required": ["runtime"],
diff --git a/pkg/workflow/agent_validation.go b/pkg/workflow/agent_validation.go
@@ -5,7 +5,7 @@
 // This file validates agent-specific configuration and feature compatibility
 // for agentic workflows. It ensures that:
 //   - Custom agent files exist when specified
-//   - Engine features are supported (HTTP transport, max-turns, web-search)
+//   - Engine features are supported (HTTP transport, max-turns, web-search, bare mode)
 //   - Workflow triggers have appropriate security constraints
 //
 // # Validation Functions
@@ -14,6 +14,7 @@
 //   - validateMaxTurnsSupport() - Validates max-turns feature support
 //   - validateMaxContinuationsSupport() - Validates max-continuations feature support
 //   - validateWebSearchSupport() - Validates web-search feature support (warning)
+//   - validateBareModeSupport() - Validates bare mode feature support (warning)
 //   - validateWorkflowRunBranches() - Validates workflow_run has branch restrictions
 //
 // # Validation Patterns
@@ -174,6 +175,25 @@ func (c *Compiler) validateWebSearchSupport(tools map[string]any, engine CodingA
 	}
 }
 
+// validateBareModeSupport validates that bare mode is only used with engines that support this feature.
+// Emits a warning and has no effect on engines that do not support bare mode.
+func (c *Compiler) validateBareModeSupport(frontmatter map[string]any, engine CodingAgentEngine) {
+	_, engineConfig := c.ExtractEngineConfig(frontmatter)
+
+	if engineConfig == nil || !engineConfig.Bare {
+		// bare mode not requested, no validation needed
+		return
+	}
+
+	agentValidationLog.Printf("Validating bare mode support for engine: %s", engine.GetID())
+
+	if !engine.SupportsBareMode() {
+		agentValidationLog.Printf("Engine %s does not support bare mode, emitting warning", engine.GetID())
+		fmt.Fprintln(os.Stderr, console.FormatWarningMessage(fmt.Sprintf("Engine '%s' does not support bare mode (engine.bare: true). Bare mode is only supported for the 'copilot' and 'claude' engines. The setting will be ignored.", engine.GetID())))
+		c.IncrementWarningCount()
+	}
+}
+
 // validateWorkflowRunBranches validates that workflow_run triggers include branch restrictions
 // This is a security best practice to avoid running on all branches
 func (c *Compiler) validateWorkflowRunBranches(workflowData *WorkflowData, markdownPath string) error {
diff --git a/pkg/workflow/agentic_engine.go b/pkg/workflow/agentic_engine.go
@@ -38,7 +38,10 @@ type GitHubActionStep []string
 //   CapabilityProvider (feature detection - optional)
 //   ├── SupportsToolsAllowlist()
 //   ├── SupportsMaxTurns()
-//   └── SupportsWebSearch()
+//   ├── SupportsWebSearch()
+//   ├── SupportsMaxContinuations()
+//   ├── SupportsNativeAgentFile()
+//   └── SupportsBareMode()
 //
 //   WorkflowExecutor (compilation - required)
 //   ├── GetDeclaredOutputFiles()
@@ -123,6 +126,11 @@ type CapabilityProvider interface {
 	// the agent file content in prompt.txt during the activation job so that the engine just
 	// reads the standard /tmp/gh-aw/aw-prompts/prompt.txt as usual.
 	SupportsNativeAgentFile() bool
+
+	// SupportsBareMode returns true if this engine supports the bare mode feature
+	// (engine.bare: true), which suppresses automatic loading of context and custom
+	// instructions. When false, specifying bare: true emits a warning and has no effect.
+	SupportsBareMode() bool
 }
 
 // WorkflowExecutor handles workflow compilation and execution
@@ -268,6 +276,7 @@ type BaseEngine struct {
 	supportsMaxContinuations bool
 	supportsWebSearch        bool
 	supportsNativeAgentFile  bool
+	supportsBareMode         bool
 	llmGatewayPort           int
 }
 
@@ -307,6 +316,10 @@ func (e *BaseEngine) SupportsNativeAgentFile() bool {
 	return e.supportsNativeAgentFile
 }
 
+func (e *BaseEngine) SupportsBareMode() bool {
+	return e.supportsBareMode
+}
+
 func (e *BaseEngine) getLLMGatewayPort() int {
 	return e.llmGatewayPort
 }
diff --git a/pkg/workflow/claude_engine.go b/pkg/workflow/claude_engine.go
@@ -30,6 +30,7 @@ func NewClaudeEngine() *ClaudeEngine {
 			supportsMaxContinuations: false, // Claude Code does not support --max-autopilot-continues-style continuation
 			supportsWebSearch:        true,  // Claude has built-in WebSearch support
 			supportsNativeAgentFile:  false, // Claude does not support agent file natively; the compiler prepends the agent file content to prompt.txt
+			supportsBareMode:         true,  // Claude CLI supports --bare
 			llmGatewayPort:           constants.ClaudeLLMGatewayPort,
 		},
 	}
@@ -162,6 +163,13 @@ func (e *ClaudeEngine) GetExecutionSteps(workflowData *WorkflowData, logFile str
 	// This format is compatible with the log parser which expects either JSON array or JSONL
 	claudeArgs = append(claudeArgs, "--output-format", "stream-json")
 
+	// Add --bare when bare mode is enabled to suppress automatic loading of memory
+	// files (CLAUDE.md, ~/.claude/) and other context injections.
+	if workflowData.EngineConfig != nil && workflowData.EngineConfig.Bare {
+		claudeLog.Print("Bare mode enabled: adding --bare")
+		claudeArgs = append(claudeArgs, "--bare")
+	}
+
 	// Add custom args from engine configuration before the prompt
 	if workflowData.EngineConfig != nil && len(workflowData.EngineConfig.Args) > 0 {
 		claudeArgs = append(claudeArgs, workflowData.EngineConfig.Args...)
diff --git a/pkg/workflow/codex_engine.go b/pkg/workflow/codex_engine.go
@@ -255,7 +255,7 @@ touch %s
 (umask 177 && touch %s)
 INSTRUCTION="$(cat "$GH_AW_PROMPT")"
 mkdir -p "$CODEX_HOME/logs"
-%s %sexec%s%s%s%s"$INSTRUCTION" 2>&1 | tee %s`, AgentStepSummaryPath, logFile, commandName, modelParam, webSearchParam, webFetchParam, fullAutoParam, customArgsParam, logFile)
+%s 2>&1 | tee %s`, AgentStepSummaryPath, logFile, codexCommand, logFile)
 	}
 
 	// Get effective GitHub token based on precedence: custom token > default
diff --git a/pkg/workflow/compiler_orchestrator_tools.go b/pkg/workflow/compiler_orchestrator_tools.go
@@ -215,6 +215,9 @@ func (c *Compiler) processToolsAndMarkdown(result *parser.FrontmatterResult, cle
 	// Validate web-search support for the current engine (warning only)
 	c.validateWebSearchSupport(tools, agenticEngine)
 
+	// Validate bare mode support for the current engine (warning only)
+	c.validateBareModeSupport(result.Frontmatter, agenticEngine)
+
 	// Process @include directives in markdown content
 	markdownContent, includedMarkdownFiles, err := parser.ExpandIncludesWithManifest(result.Markdown, markdownDir, false)
 	if err != nil {
diff --git a/pkg/workflow/copilot_engine.go b/pkg/workflow/copilot_engine.go
@@ -42,6 +42,7 @@ func NewCopilotEngine() *CopilotEngine {
 			supportsMaxTurns:         false, // Copilot CLI does not support max-turns feature yet
 			supportsMaxContinuations: true,  // Copilot CLI supports --autopilot with --max-autopilot-continues
 			supportsWebSearch:        false, // Copilot CLI does not have built-in web-search support
+			supportsBareMode:         true,  // Copilot CLI supports --no-custom-instructions
 			llmGatewayPort:           constants.CopilotLLMGatewayPort,
 		},
 	}
diff --git a/pkg/workflow/copilot_engine_execution.go b/pkg/workflow/copilot_engine_execution.go
@@ -111,6 +111,13 @@ func (e *CopilotEngine) GetExecutionSteps(workflowData *WorkflowData, logFile st
 		copilotArgs = append(copilotArgs, "--allow-all-paths")
 	}
 
+	// Add --no-custom-instructions when bare mode is enabled to suppress automatic
+	// loading of custom instructions from .github/AGENTS.md and user-level configs.
+	if workflowData.EngineConfig != nil && workflowData.EngineConfig.Bare {
+		copilotExecLog.Print("Bare mode enabled: adding --no-custom-instructions")
+		copilotArgs = append(copilotArgs, "--no-custom-instructions")
+	}
+
 	// Add custom args from engine configuration before the prompt
 	if workflowData.EngineConfig != nil && len(workflowData.EngineConfig.Args) > 0 {
 		copilotArgs = append(copilotArgs, workflowData.EngineConfig.Args...)
diff --git a/pkg/workflow/engine.go b/pkg/workflow/engine.go
@@ -27,6 +27,7 @@ type EngineConfig struct {
 	Args             []string
 	Agent            string // Agent identifier for copilot --agent flag (copilot engine only)
 	APITarget        string // Custom API endpoint hostname (e.g., "api.acme.ghe.com" or "api.enterprise.githubcopilot.com")
+	Bare             bool   // When true, disables automatic loading of context/instructions (copilot: --no-custom-instructions, claude: --bare, codex: --no-system-prompt, gemini: GEMINI_SYSTEM_MD=/dev/null)
 	// TokenWeights provides custom model cost data for effective token computation.
 	// When set, overrides or extends the built-in model_multipliers.json values.
 	TokenWeights *types.TokenWeights
@@ -152,6 +153,14 @@ func (c *Compiler) ExtractEngineConfig(frontmatter map[string]any) (string, *Eng
 					}
 				}
 
+				// Extract optional 'bare' field (shared with non-inline path)
+				if bare, hasBare := engineObj["bare"]; hasBare {
+					if bareBool, ok := bare.(bool); ok {
+						config.Bare = bareBool
+						engineLog.Printf("Extracted bare mode (inline): %v", config.Bare)
+					}
+				}
+
 				engineLog.Printf("Extracted inline engine definition: runtimeID=%s, providerID=%s", config.ID, config.InlineProviderID)
 				return config.ID, config
 			}
@@ -288,6 +297,14 @@ func (c *Compiler) ExtractEngineConfig(frontmatter map[string]any) (string, *Eng
 				}
 			}
 
+			// Extract optional 'bare' field (disable automatic context/instruction loading)
+			if bare, hasBare := engineObj["bare"]; hasBare {
+				if bareBool, ok := bare.(bool); ok {
+					config.Bare = bareBool
+					engineLog.Printf("Extracted bare mode: %v", config.Bare)
+				}
+			}
+
 			// Extract optional 'token-weights' field (custom model cost data)
 			if tokenWeightsRaw, hasTokenWeights := engineObj["token-weights"]; hasTokenWeights {
 				if tw := parseEngineTokenWeights(tokenWeightsRaw); tw != nil {
diff --git a/pkg/workflow/engine_args_integration_test.go b/pkg/workflow/engine_args_integration_test.go
@@ -3,12 +3,15 @@
 package workflow
 
 import (
+	"fmt"
 	"os"
 	"path/filepath"
 	"strings"
 	"testing"
 
 	"github.com/github/gh-aw/pkg/testutil"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
 )
 
 func TestEngineArgsIntegration(t *testing.T) {
@@ -270,3 +273,130 @@ This is a test workflow to verify codex engine args injection.
 		t.Error("Expected --custom-flag to come before $INSTRUCTION in compiled YAML")
 	}
 }
+
+func TestEngineBareModeCopilotIntegration(t *testing.T) {
+	tmpDir := testutil.TempDir(t, "test-*")
+
+	workflowContent := `---
+on: workflow_dispatch
+engine:
+  id: copilot
+  bare: true
+---
+
+# Test Bare Mode Copilot
+`
+
+	workflowPath := filepath.Join(tmpDir, "test-workflow.md")
+	if err := os.WriteFile(workflowPath, []byte(workflowContent), 0644); err != nil {
+		t.Fatalf("Failed to write workflow file: %v", err)
+	}
+
+	compiler := NewCompiler()
+	if err := compiler.CompileWorkflow(workflowPath); err != nil {
+		t.Fatalf("Failed to compile workflow: %v", err)
+	}
+
+	content, err := os.ReadFile(filepath.Join(tmpDir, "test-workflow.lock.yml"))
+	if err != nil {
+		t.Fatalf("Failed to read lock file: %v", err)
+	}
+	result := string(content)
+
+	if !strings.Contains(result, "--no-custom-instructions") {
+		t.Errorf("Expected --no-custom-instructions in compiled output when bare=true, got:\n%s", result)
+	}
+}
+
+func TestEngineBareModeClaudeIntegration(t *testing.T) {
+	tmpDir := testutil.TempDir(t, "test-*")
+
+	workflowContent := `---
+on: workflow_dispatch
+engine:
+  id: claude
+  bare: true
+---
+
+# Test Bare Mode Claude
+`
+
+	workflowPath := filepath.Join(tmpDir, "test-workflow.md")
+	if err := os.WriteFile(workflowPath, []byte(workflowContent), 0644); err != nil {
+		t.Fatalf("Failed to write workflow file: %v", err)
+	}
+
+	compiler := NewCompiler()
+	if err := compiler.CompileWorkflow(workflowPath); err != nil {
+		t.Fatalf("Failed to compile workflow: %v", err)
+	}
+
+	content, err := os.ReadFile(filepath.Join(tmpDir, "test-workflow.lock.yml"))
+	if err != nil {
+		t.Fatalf("Failed to read lock file: %v", err)
+	}
+	result := string(content)
+
+	if !strings.Contains(result, "--bare") {
+		t.Errorf("Expected --bare in compiled output when bare=true, got:\n%s", result)
+	}
+}
+
+func TestBareMode_UnsupportedEngineWarningIntegration(t *testing.T) {
+	tests := []struct {
+		name          string
+		engineID      string
+		bannedOutput  []string
+		workflowTitle string
+	}{
+		{
+			name:          "codex emits warning, no --no-system-prompt in output",
+			engineID:      "codex",
+			bannedOutput:  []string{"--no-system-prompt"},
+			workflowTitle: "Test Bare Mode Codex",
+		},
+		{
+			name:          "gemini emits warning, no GEMINI_SYSTEM_MD=/dev/null in output",
+			engineID:      "gemini",
+			bannedOutput:  []string{"GEMINI_SYSTEM_MD=/dev/null"},
+			workflowTitle: "Test Bare Mode Gemini",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			tmpDir := testutil.TempDir(t, "test-*")
+
+			workflowContent := fmt.Sprintf(`---
+on: workflow_dispatch
+engine:
+  id: %s
+  bare: true
+---
+
+# %s
+`, tt.engineID, tt.workflowTitle)
+
+			workflowPath := filepath.Join(tmpDir, "test-workflow.md")
+			require.NoError(t, os.WriteFile(workflowPath, []byte(workflowContent), 0644),
+				"should write workflow file")
+
+			compiler := NewCompiler()
+			require.NoError(t, compiler.CompileWorkflow(workflowPath),
+				"should compile without error (bare mode unsupported is a warning, not an error)")
+
+			// A warning should have been counted
+			assert.Greater(t, compiler.GetWarningCount(), 0,
+				"should emit a warning when bare mode is specified for unsupported engine")
+
+			content, err := os.ReadFile(filepath.Join(tmpDir, "test-workflow.lock.yml"))
+			require.NoError(t, err, "should read lock file")
+			result := string(content)
+
+			for _, banned := range tt.bannedOutput {
+				assert.NotContains(t, result, banned,
+					"compiled output should not contain %q for unsupported bare mode engine", banned)
+			}
+		})
+	}
+}
diff --git a/pkg/workflow/engine_config_test.go b/pkg/workflow/engine_config_test.go
diff --git a/pkg/workflow/engine_inline_test.go b/pkg/workflow/engine_inline_test.go

Original file line number	Diff line number	Diff line change
`@@ -255,7 +255,7 @@ touch %s`
`255`	`255`	`(umask 177 && touch %s)`
`256`	`256`	`INSTRUCTION="$(cat "$GH_AW_PROMPT")"`
`257`	`257`	`mkdir -p "$CODEX_HOME/logs"`
`258`		-%s %sexec%s%s%s%s"$INSTRUCTION" 2>&1 \| tee %s`, AgentStepSummaryPath, logFile, commandName, modelParam, webSearchParam, webFetchParam, fullAutoParam, customArgsParam, logFile)
	`258`	+%s 2>&1 \| tee %s`, AgentStepSummaryPath, logFile, codexCommand, logFile)
`259`	`259`	`}`
`260`	`260`
`261`	`261`	`// Get effective GitHub token based on precedence: custom token > default`