Add comprehensive documentation to validation and helper files

- Add package-level documentation explaining organization rationale
- Document why validation functions are co-located with domain logic
- Explain parse function grouping in tools_parser.go and config_helpers.go
- Add helper file purpose and conventions documentation
- Document validation function placement following established patterns

Co-authored-by: mnkiefer <8320933+mnkiefer@users.noreply.github.com>

Author: Copilot

pkg/cli/actions_build_command.go

@@ -141,7 +141,19 @@ func getActionDirectories(actionsDir string) ([]string, error) {
 	return dirs, nil
 }
 
-// validateActionYml validates an action.yml file
+// validateActionYml validates that an action.yml file exists and contains required fields.
+//
+// This validation function is co-located with the actions build command because:
+//   - It's specific to GitHub Actions custom action structure
+//   - It's only called during the actions build process
+//   - It validates action metadata before bundling JavaScript
+//
+// The function validates:
+//   - action.yml file exists in the action directory
+//   - Required fields are present (name, description, runs)
+//   - Basic action metadata structure is valid
+//
+// This follows the principle that domain-specific validation belongs in domain files.
 func validateActionYml(actionPath string) error {
 	ymlPath := filepath.Join(actionPath, "action.yml")
 

pkg/cli/compile_campaign.go

@@ -1,3 +1,29 @@
+// Package cli provides campaign workflow compilation and validation.
+//
+// This file handles validation of campaign spec files and their referenced workflows.
+// Campaign workflows are special workflows that orchestrate multiple sub-workflows
+// across a set of target repositories.
+//
+// # Organization Rationale
+//
+// The validateCampaigns function is co-located with campaign compilation logic because:
+//   - It's domain-specific to campaign workflows
+//   - It's only called during compile operations
+//   - It's tightly coupled to the campaign compilation process
+//   - The file is small (98 lines) and focused
+//
+// This follows the principle that domain-specific validation belongs in domain files.
+// See skills/developer/SKILL.md for validation architecture patterns.
+//
+// # Validation Functions
+//
+// Campaign Validation:
+//   - validateCampaigns() - Validates campaign specs and referenced workflows
+//
+// This validation ensures that:
+//   - Campaign spec files are syntactically valid
+//   - Referenced workflow files exist in the workflows directory
+//   - Campaign configuration is complete and correct
 package cli
 
 import (

pkg/cli/compile_helpers.go

@@ -1,3 +1,36 @@
+// Package cli provides helper functions for workflow compilation.
+//
+// This file contains shared utilities used by the compile command to process workflow
+// files, manage compilation statistics, and handle campaign workflows. These helpers
+// support both single-file and batch compilation operations.
+//
+// # Organization Rationale
+//
+// These helper functions are grouped here because they:
+//   - Are used by multiple compile command variants (compile, watch, campaign)
+//   - Provide common compilation patterns and error handling
+//   - Have a clear domain focus (compilation operations)
+//   - Keep the main compile_command.go file focused on CLI interaction
+//
+// This follows the helper file conventions documented in skills/developer/SKILL.md.
+//
+// # Key Functions
+//
+// Single File Compilation:
+//   - compileSingleFile() - Compile a single markdown workflow with stats tracking
+//
+// Batch Compilation:
+//   - compileBatchWorkflows() - Compile multiple workflows in parallel
+//   - scanAllWorkflows() - Scan directories for workflow files
+//
+// Campaign Compilation:
+//   - compileAllCampaignOrchestrators() - Generate and compile campaign orchestrators
+//
+// Statistics:
+//   - CompilationStats - Track compilation success/failure/skip counts
+//
+// These functions abstract common compilation patterns, allowing the main compile
+// command to focus on CLI interaction while these helpers handle the mechanics.
 package cli
 
 import (

pkg/cli/run_command.go

@@ -616,7 +616,19 @@ func getWorkflowInputs(markdownPath string) (map[string]*workflow.InputDefinitio
 	return workflow.ParseInputDefinitions(inputsMap), nil
 }
 
-// validateWorkflowInputs validates that required inputs are provided and checks for typos
+// validateWorkflowInputs validates that required inputs are provided and checks for typos.
+//
+// This validation function is co-located with the run command implementation because:
+//   - It's specific to the workflow run operation
+//   - It's only called during workflow dispatch
+//   - It provides immediate feedback before triggering the workflow
+//
+// The function validates:
+//   - All required inputs are provided
+//   - Provided input names match defined inputs (typo detection)
+//   - Suggestions for misspelled input names
+//
+// This follows the principle that domain-specific validation belongs in domain files.
 func validateWorkflowInputs(markdownPath string, providedInputs []string) error {
 	// Extract workflow inputs
 	workflowInputs, err := getWorkflowInputs(markdownPath)
@@ -888,7 +900,19 @@ func getLatestWorkflowRunWithRetry(lockFileName string, repo string, verbose boo
 	return nil, fmt.Errorf("no workflow run found after %d attempts", maxRetries)
 }
 
-// validateRemoteWorkflow checks if a workflow exists in a remote repository and can be triggered
+// validateRemoteWorkflow checks if a workflow exists in a remote repository and can be triggered.
+//
+// This validation function is co-located with the run command implementation because:
+//   - It's specific to remote workflow execution
+//   - It's only called when running workflows in remote repositories
+//   - It provides early validation before attempting workflow dispatch
+//
+// The function validates:
+//   - The specified repository exists and is accessible
+//   - The workflow file exists in the repository
+//   - The workflow can be triggered via GitHub Actions API
+//
+// This follows the principle that domain-specific validation belongs in domain files.
 func validateRemoteWorkflow(workflowName string, repoOverride string, verbose bool) error {
 	if repoOverride == "" {
 		return fmt.Errorf("repository must be specified for remote workflow validation")

pkg/workflow/config_helpers.go

@@ -1,3 +1,38 @@
+// Package workflow provides helper functions for parsing safe output configurations.
+//
+// This file contains parsing utilities for extracting and validating configuration
+// values from safe output config maps. These helpers are used across safe output
+// processors to parse common configuration patterns.
+//
+// # Organization Rationale
+//
+// These parse functions are grouped in a helper file because they:
+//   - Share a common purpose (safe output config parsing)
+//   - Are used by multiple safe output modules (3+ callers)
+//   - Provide stable, reusable parsing patterns
+//   - Have clear domain focus (configuration extraction)
+//
+// This follows the helper file conventions documented in the developer instructions.
+// See skills/developer/SKILL.md#helper-file-conventions for details.
+//
+// # Key Functions
+//
+// Configuration Array Parsing:
+//   - ParseStringArrayFromConfig() - Generic string array extraction
+//   - parseLabelsFromConfig() - Extract labels array
+//   - parseParticipantsFromConfig() - Extract participants array
+//   - parseAllowedReposFromConfig() - Extract allowed repos array
+//   - parseAllowedLabelsFromConfig() - Extract allowed labels array
+//
+// Configuration String Parsing:
+//   - extractStringFromMap() - Generic string extraction
+//   - parseTitlePrefixFromConfig() - Extract title prefix
+//   - parseTargetRepoFromConfig() - Extract target repository
+//   - parseTargetRepoWithValidation() - Extract and validate target repo
+//
+// Configuration Integer Parsing:
+//   - parseExpiresFromConfig() - Extract expiration time
+//   - parseRelativeTimeSpec() - Parse relative time specifications
 package workflow
 
 import (

pkg/workflow/engine_helpers.go

@@ -1,3 +1,33 @@
+// Package workflow provides shared helper functions for AI engine implementations.
+//
+// This file contains utilities used across multiple AI engine files (copilot_engine.go,
+// claude_engine.go, codex_engine.go, custom_engine.go) to generate common workflow
+// steps and configurations.
+//
+// # Organization Rationale
+//
+// These helper functions are grouped here because they:
+//   - Are used by 3+ engine implementations (shared utilities)
+//   - Provide common patterns for agent installation and npm setup
+//   - Have a clear domain focus (engine workflow generation)
+//   - Are stable and change infrequently
+//
+// This follows the helper file conventions documented in skills/developer/SKILL.md.
+//
+// # Key Functions
+//
+// Agent Installation:
+//   - GenerateAgentInstallSteps() - Generate agent installation workflow steps
+//
+// NPM Installation:
+//   - GenerateNpmInstallStep() - Generate npm package installation step
+//   - GenerateEngineDependenciesInstallStep() - Generate engine dependencies install step
+//
+// Configuration:
+//   - GetClaudeSystemPrompt() - Get system prompt for Claude engine
+//
+// These functions encapsulate shared logic that would otherwise be duplicated across
+// engine files, maintaining DRY principles while keeping engine-specific code separate.
 package workflow
 
 import (

pkg/workflow/map_helpers.go

@@ -1,3 +1,29 @@
+// Package workflow provides generic map and type conversion utilities.
+//
+// This file contains low-level helper functions for working with map[string]any
+// structures and type conversions. These utilities are used throughout the workflow
+// compilation process to safely parse and manipulate configuration data.
+//
+// # Organization Rationale
+//
+// These functions are grouped in a helper file because they:
+//   - Provide generic, reusable utilities (used by 10+ files)
+//   - Have no specific domain focus (work with any map/type data)
+//   - Are small, stable functions (< 50 lines each)
+//   - Follow clear, single-purpose patterns
+//
+// This follows the helper file conventions documented in skills/developer/SKILL.md.
+//
+// # Key Functions
+//
+// Type Conversion:
+//   - parseIntValue() - Safely parse numeric types to int with truncation warnings
+//
+// Map Operations:
+//   - filterMapKeys() - Create new map excluding specified keys
+//
+// These utilities handle common type conversion and map manipulation patterns that
+// occur frequently during YAML-to-struct parsing and configuration processing.
 package workflow
 
 import "github.com/githubnext/gh-aw/pkg/logger"

pkg/workflow/repo_memory.go

@@ -1,3 +1,19 @@
+// Package workflow provides repository memory configuration and validation.
+//
+// This file handles:
+//   - Repo-memory configuration structures and defaults
+//   - Repo-memory tool configuration extraction and parsing
+//   - Generation of per-memory GitHub token secrets
+//   - Domain-specific validation for repo-memory configurations
+//
+// # Validation Functions
+//
+// This file contains domain-specific validation functions for repo-memory:
+//   - validateNoDuplicateMemoryIDs() - Ensures unique memory identifiers
+//
+// These validation functions are co-located with repo-memory logic following the
+// principle that domain-specific validation belongs in domain files. See validation.go
+// for the validation architecture documentation.
 package workflow
 
 import (

pkg/workflow/sandbox.go

@@ -1,3 +1,20 @@
+// Package workflow provides sandbox configuration and validation for agentic workflows.
+//
+// This file handles:
+//   - Sandbox type definitions (AWF, SRT)
+//   - Sandbox configuration structures and parsing
+//   - Sandbox runtime config generation
+//   - Domain-specific validation for sandbox configurations
+//
+// # Validation Functions
+//
+// This file contains domain-specific validation functions for sandbox configuration:
+//   - validateMountsSyntax() - Validates container mount syntax
+//   - validateSandboxConfig() - Validates complete sandbox configuration
+//
+// These validation functions are co-located with sandbox logic following the principle
+// that domain-specific validation belongs in domain files. See validation.go for the
+// validation architecture documentation.
 package workflow
 
 import (

pkg/workflow/tools_parser.go

@@ -1,3 +1,52 @@
+// Package workflow provides tool configuration parsing for agentic workflows.
+//
+// This file handles parsing of tool configurations from the frontmatter tools section.
+// It extracts and validates tool configurations for all supported tools, converting
+// YAML-parsed maps into strongly-typed Go structs.
+//
+// # Organization Rationale
+//
+// All tool parsing functions are grouped in this file because they:
+//   - Share a common purpose (tool configuration parsing)
+//   - Follow similar parsing patterns (map[string]any -> struct)
+//   - Are called together during workflow compilation
+//   - Provide a single source of truth for tool configuration
+//
+// This follows established patterns where domain-specific parsing is grouped by
+// functionality rather than scattered across files. See skills/developer/SKILL.md
+// for code organization principles.
+//
+// # Supported Tools
+//
+// Built-in Tools:
+//   - github: GitHub API and repository operations
+//   - bash: Shell command execution
+//   - web-fetch: HTTP content fetching
+//   - web-search: Web search capabilities
+//   - edit: File editing operations
+//   - playwright: Browser automation
+//   - serena: Serena integration
+//   - agentic-workflows: Nested workflow execution
+//   - cache-memory: In-workflow memory caching
+//   - repo-memory: Repository-backed persistent memory
+//
+// Configuration Tools:
+//   - safety-prompt: Safety prompt injection
+//   - timeout: Agent timeout configuration
+//   - startup-timeout: Agent startup timeout
+//
+// Custom Tools:
+//   - MCP servers and other custom tool configurations
+//
+// # Parse Function Pattern
+//
+// Each parse function follows the pattern:
+//   1. Accept any type to handle various YAML representations
+//   2. Type-assert to expected structure (bool, string, map, array)
+//   3. Extract and validate configuration values
+//   4. Return strongly-typed configuration struct
+//
+// This provides type safety while accommodating flexible YAML syntax.
 package workflow
 
 import (