Workflow compilation, validation, engine integration, safe-outputs, and GitHub Actions YAML generation for agentic workflow files.

The workflow package is the compilation core of gh-aw. It transforms parsed markdown frontmatter (from pkg/parser) and markdown body text into complete GitHub Actions .lock.yml files. Compilation covers the full lifecycle: frontmatter parsing into strongly-typed configuration structs, multi-pass validation (schema, permissions, security, strict mode), engine-specific step generation (Copilot, Claude, Codex, Gemini, custom), safe-output job construction, and final YAML serialization.

The package is organized around three major subsystems:

1. Compiler (compiler*.go, compiler_types.go): The Compiler struct drives the main compilation pipeline. It accepts a markdown file path (or pre-parsed WorkflowData), builds the full GitHub Actions workflow YAML, and writes the .lock.yml file only when the content has changed.

2. Engine registry (agentic_engine.go, *_engine.go): A pluggable engine architecture where each AI engine (copilot, claude, codex, gemini, crush, custom) implements a set of focused interfaces (Engine, CapabilityProvider, WorkflowExecutor, MCPConfigProvider, etc.). Engines are registered in a global EngineRegistry and looked up by name at compile time.

3. Validation (validation.go, strict_mode_*.go, *_validation.go): A layered validation system organized by domain. Each validator is a focused file under 300 lines. Validation runs both at compile time and optionally in strict mode for production deployments.

The package is intentionally large (~320 source files) because it encodes all GitHub Actions generation logic, including per-action job builders for every supported safe-output type (add comment, add labels, assign to user, close issue, update PR, etc.).

The sandbox subsystem controls which agent firewall (AWF) or sandbox runtime is used during workflow execution.

The MCP Scripts subsystem provides inline custom tool definitions (JavaScript, shell, Python, or Go) that are compiled into a local MCP server at workflow runtime.

compiler := workflow.NewCompiler(
    workflow.WithVerbose(true),
    workflow.WithEngineOverride("copilot"),
)
err := compiler.CompileWorkflow(".github/workflows/my-workflow.md")

registry := workflow.GetGlobalEngineRegistry()
engine, ok := registry.Get("copilot")
if ok {
    steps := engine.GetExecutionSteps(workflowData)
}

perms := workflow.ComputePermissionsForSafeOutputs(safeOutputsConfig)

name, err := workflow.ResolveWorkflowName("my-workflow")
lockFile, err := workflow.GetWorkflowLockFileName(name)

markdown file
    │
    ▼
pkg/parser ─── ExtractFrontmatterFromContent
    │               ProcessImportsFromFrontmatterWithSource
    │
    ▼
pkg/workflow ── FrontmatterConfig (typed structs)
    │               Compiler.CompileWorkflow()
    │                 ├─ schema validation
    │                 ├─ permissions computation
    │                 ├─ engine step generation
    │                 ├─ safe-output job generation
    │                 ├─ YAML serialization
    │                 └─ lock file write (if changed)
    │
    ▼
.github/workflows/my-workflow.lock.yml

• File-per-domain decomposition: Each validation concern and job-builder lives in its own file. The 300-line limit is enforced by convention; validation files exceeding it SHOULD be split.
• Functional compiler options: CompilerOption functions follow the standard Go functional-options pattern, keeping NewCompiler signature stable as options are added.
• Engine interface composition: Rather than one monolithic Engine interface, capabilities are split into focused interfaces (CapabilityProvider, WorkflowExecutor, etc.) and combined via CodingAgentEngine. This prevents engines from being forced to implement unused methods.
• Content-addressed lock files: Lock files are only written when the normalized YAML content changes (heredoc delimiters are normalized before comparison). This avoids unnecessary git churn.
• YAML 1.1/1.2 compatibility: The package uses goccy/go-yaml for all GitHub Actions YAML generation to ensure compatibility with GitHub Actions' YAML parser.

Internal:

• pkg/parser — frontmatter extraction and import processing
• pkg/constants — engine names, feature flags, job/step IDs
• pkg/console — terminal formatting
• pkg/logger — debug logging
• pkg/actionpins — action pin data and pin lookup helpers
• pkg/jsonutil — compact JSON marshaling for AWF configuration serialization
• pkg/semverutil — semantic version helpers
• pkg/typeutil — safe type conversions
• pkg/tty — terminal capability detection
• pkg/stringutil, pkg/fileutil, pkg/gitutil, pkg/sliceutil — utilities
• pkg/types — shared MCP types

External:

• github.com/goccy/go-yaml — YAML 1.1/1.2 compatible marshaling
• go.yaml.in/yaml/v3 — standard YAML marshaling for non-Actions YAML
• github.com/cli/go-gh/v2 — GitHub CLI API and repository integration
• github.com/santhosh-tekuri/jsonschema/v6 — JSON schema validation

Compiler instances are NOT safe for concurrent use. Create a new Compiler for each concurrent compilation. The GetGlobalEngineRegistry() singleton is initialized once at startup and is safe for concurrent reads thereafter.

Constants (MaxLockFileSize) and action pin data are read-only after initialization and are safe for concurrent access.

This specification is automatically maintained by the spec-extractor workflow.