cloudposse
diff --git a/‎.claude/agents/atmos-errors.md‎
Lines changed: 100 additions & 0 deletions b/‎.claude/agents/atmos-errors.md‎
Lines changed: 100 additions & 0 deletions
diff --git a/‎.claude/agents/flag-handler.md‎
Lines changed: 45 additions & 13 deletions b/‎.claude/agents/flag-handler.md‎
Lines changed: 45 additions & 13 deletions
diff --git a/‎.golangci.yml‎
Lines changed: 15 additions & 0 deletions b/‎.golangci.yml‎
Lines changed: 15 additions & 0 deletions
diff --git a/‎.pre-commit-config.yaml‎
Lines changed: 1 addition & 1 deletion b/‎.pre-commit-config.yaml‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎CLAUDE.md‎
Lines changed: 59 additions & 0 deletions b/‎CLAUDE.md‎
Lines changed: 59 additions & 0 deletions
@@ -414,6 +414,106 @@ return errUtils.Build(errUtils.ErrComponentNotFound).
     Err()
 ```
 
+## Usage Examples for Error Messages
+
+When creating errors with complex usage examples (especially for format or syntax errors), you can embed example content using `WithExampleFile()` or `WithExample()`.
+
+### When to Include Examples
+
+Include usage examples when:
+- Error is about invalid format/syntax (e.g., `--format json` vs `--format xml`)
+- Error is about missing or malformed configuration
+- Multiple correct usage patterns exist
+- User needs to see concrete examples to understand the fix
+
+### Example Format Guidelines
+
+**IMPORTANT: Examples should be succinct commands only, NO output.**
+
+Examples should be stored in markdown files and embedded using go:embed:
+
+```markdown
+# examples/version_format.md
+
+- Display version in JSON format
+
+```bash
+$ atmos version --format json
+```
+
+- Display version in YAML format
+
+```bash
+$ atmos version --format yaml
+```
+
+- Pipe JSON output to jq
+
+```bash
+$ atmos version --format json | jq -r .version
+```
+```
+
+**Format rules:**
+- Each example starts with `- Description` (bullet point)
+- Followed by blank line
+- Command in triple backticks with `bash` language hint
+- Commands use `$` prompt
+- NO "Output:" sections
+- NO example output shown
+- Keep it succinct - just show the commands
+
+### Where to Store Examples
+
+**IMPORTANT: Use go:embed for multi-line examples.**
+
+Create markdown files and embed them:
+
+```go
+// internal/exec/version.go
+
+//go:embed examples/version_format.md
+var versionFormatExample string
+
+// Use in error:
+return errUtils.Build(errUtils.ErrVersionFormatInvalid).
+    WithExplanationf("The format '%s' is not supported for version output", format).
+    WithExample(versionFormatExample).
+    WithHint("Use --format json for JSON output").
+    WithHint("Use --format yaml for YAML output").
+    WithContext("format", format).
+    WithExitCode(2).
+    Err()
+```
+
+**File structure:**
+```
+internal/exec/
+├── version.go
+└── examples/
+    ├── version_format.md
+    └── other_examples.md
+```
+
+**Why go:embed:**
+- Clean, readable markdown files (not escaped strings)
+- Proper syntax highlighting in editors
+- Easy to edit without string concatenation hell
+- No escaped backticks or quotes
+
+**Note:** This is different from CLI command usage files which go in `cmd/markdown/atmos_*_usage.md` and are displayed via `--help`.
+
+### Inline Examples for Simple Cases
+
+For simple examples, use `WithExample()` directly:
+
+```go
+return errUtils.Build(errUtils.ErrInvalidFormat).
+    WithExample("```yaml\nworkflows:\n  deploy:\n    steps:\n      - command: terraform apply\n```").
+    WithHint("Check your workflow syntax").
+    Err()
+```
+
 ## Testing & Sentry
 
 Test with `errors.Is()` and `errUtils.GetExitCode()`. Format with `errUtils.Format(err, config)`.
 
@@ -1,14 +1,30 @@
 ---
 name: flag-handler
 description: >-
-  Use this agent for implementing new Atmos CLI commands using unified flag parsing and command registry pattern. Expert in CommandProvider interface, StandardParser, and Cobra integration.
-
-  **Invoke when:**
-  - Creating new CLI commands with flag parsing
-  - Implementing CommandProvider interface for command registry
-  - Adding flags to existing commands using StandardParser
-  - Troubleshooting flag binding or Viper integration issues
-  - Understanding compatibility flags and separated args patterns
+  Expert in Atmos flag handling patterns and command registry architecture. The pkg/flags/ infrastructure is FULLY IMPLEMENTED and robust. NEVER call viper.BindEnv() or viper.BindPFlag() directly - Forbidigo enforces this ban outside pkg/flags/.
+
+  **AUTO-INVOKE when ANY of these topics are mentioned:**
+  - flag, flags, flag parsing, flag handling, flag architecture
+  - viper.BindEnv, viper.BindPFlag, Viper binding
+  - environment variable, env var, ATMOS_* environment variables
+  - CLI flag, command flag, command-line flag, --flag, -f
+  - flag precedence, flag priority, CLI > ENV > config > defaults
+  - Creating CLI commands, modifying CLI commands, adding flags
+  - CommandProvider, command registry, flag builder
+  - StandardParser, AtmosFlagParser, flags.NewStandardParser
+  - Flag binding, flag registration, RegisterFlags, BindToViper
+  - Cobra flags, pflag, flag validation
+  - --check, --format, --stack, or any flag name discussions
+  - Flag improvements, flag refactoring, flag migration
+  - Troubleshooting flags, flag issues, flag errors
+
+  **CRITICAL: pkg/flags/ is FULLY IMPLEMENTED. This is NOT future architecture.**
+
+  **Agent enforces:**
+  - All commands MUST use flags.NewStandardParser() for flag handling
+  - NEVER call viper.BindEnv() or viper.BindPFlag() outside pkg/flags/
+  - Forbidigo linter enforces these bans
+  - See cmd/version/version.go for reference implementation
 
 tools: Read, Write, Edit, Grep, Glob, Bash, Task, TodoWrite
 model: sonnet
@@ -21,13 +37,29 @@ Expert in Atmos command registry patterns and unified flag parsing architecture.
 
 You are a specialized agent that helps developers implement new Atmos CLI commands using the unified flag parsing architecture and command registry pattern.
 
+## CRITICAL: pkg/flags/ is FULLY IMPLEMENTED
+
+**Current Architecture:**
+- ✅ `pkg/flags/` package is fully implemented with 30+ files
+- ✅ `StandardParser`, `AtmosFlagParser` are production-ready
+- ✅ Unified flag parsing is actively used by all commands
+- ✅ `viper.BindEnv()` and `viper.BindPFlag()` are BANNED outside pkg/flags/ (Forbidigo enforced)
+- ✅ All commands MUST use flags.NewStandardParser()
+
+**When consulted, you MUST:**
+1. Enforce use of `flags.NewStandardParser()` for all flag handling
+2. NEVER recommend calling `viper.BindEnv()` or `viper.BindPFlag()` directly
+3. Direct developers to `cmd/version/version.go` for reference implementation
+4. Verify Forbidigo will catch any direct Viper calls
+
 ## Your Mission
 
-Help developers create new commands that:
-1. Integrate with the command registry
-2. Implement the CommandProvider interface correctly
-3. Use StandardParser for flag parsing
-4. Follow established patterns from reference implementations
+Help developers create commands that:
+1. Integrate with the command registry using `CommandProvider` interface
+2. Use `flags.NewStandardParser()` for flag parsing with `WithEnvVars()` options
+3. Register flags in `init()` with `parser.RegisterFlags()` and `parser.BindToViper()`
+4. Parse flags in `RunE` with `parser.BindFlagsToViper()` and Viper getters
+5. Follow the exact pattern from `cmd/version/version.go`
 
 ## Workflow
 
 
@@ -131,6 +131,12 @@ linters:
           msg: Use `log.Debug()` for debug messages instead of `log.Warn()` with "DEBUG" in the message
         - pattern: log\.Error\(.*[Dd][Ee][Bb][Uu][Gg]
           msg: Use `log.Debug()` for debug messages instead of `log.Error()` with "DEBUG" in the message
+        # Flag Binding Protection: ENFORCED
+        # pkg/flags/ infrastructure is fully implemented - these patterns are now banned outside pkg/flags/.
+        - pattern: viper\.BindEnv\(
+          msg: NEVER call viper.BindEnv() directly - use pkg/flags/ unified flag parser (consult flag-handler agent)
+        - pattern: viper\.BindPFlag\(
+          msg: NEVER call viper.BindPFlag() directly - use pkg/flags/ unified flag parser (consult flag-handler agent)
       exclude-godoc-examples: false
       analyze-types: true
     funlen:
@@ -291,6 +297,15 @@ linters:
           - err113
         path: ".*"
         source: 'errors\.Join\(.*errUtils\..*fmt\.Errorf'
+      # Allow viper.BindEnv and viper.BindPFlag in pkg/flags/ and test files
+      - linters:
+          - forbidigo
+        path: ^pkg/flags/
+        text: "viper\\.BindEnv|viper\\.BindPFlag"
+      - linters:
+          - forbidigo
+        path: _test\.go$
+        text: "viper\\.BindEnv|viper\\.BindPFlag"
     paths:
       - experiments/.*
       - third_party$
 
@@ -58,7 +58,7 @@ repos:
       - id: end-of-file-fixer
         exclude: ^(vendor/|tests/test-cases/|tests/testdata/|tests/snapshots/|.*\.svg|website/src/components/Screengrabs/)
       - id: check-yaml
-        exclude: ^(vendor/)
+        exclude: ^(vendor/|tests/test-cases/|tests/testdata/|tests/snapshots/|tests/fixtures/)
         args: [--allow-multiple-documents, --unsafe]
       - id: check-added-large-files
         args: [--maxkb=500]
 
@@ -375,6 +375,65 @@ Add `defer perf.Track(atmosConfig, "pkg.FuncName")()` + blank line to all public
 ### Configuration Loading
 Precedence: CLI flags → ENV vars → config files → defaults (use Viper)
 
+### Flag Handling (MANDATORY)
+
+**CRITICAL: Unified flag parsing infrastructure is FULLY IMPLEMENTED in `pkg/flags/`.**
+
+**Current Architecture:**
+- ✅ `pkg/flags/` package is fully implemented with robust flag parsing infrastructure
+- ✅ Commands MUST use `flags.NewStandardParser()` for command-specific flags
+- ✅ **NEVER call `viper.BindEnv()` or `viper.BindPFlag()` directly** - Forbidigo enforces this
+- ✅ Flag-handler agent provides guidance on correct usage patterns.
+
+**Correct Pattern:**
+```go
+// In cmd/mycommand/mycommand.go
+var (
+    myParser *flags.StandardParser
+)
+
+func init() {
+    // Create parser with command-specific flags
+    myParser = flags.NewStandardParser(
+        flags.WithBoolFlag("check", "c", false, "Enable checking"),
+        flags.WithStringFlag("format", "f", "", "Output format"),
+        flags.WithEnvVars("check", "ATMOS_MY_CHECK"),
+        flags.WithEnvVars("format", "ATMOS_MY_FORMAT"),
+    )
+
+    // Register flags with Cobra command
+    myParser.RegisterFlags(myCmd)
+
+    // Bind to Viper for precedence handling (flags > env > config > defaults)
+    if err := myParser.BindToViper(viper.GetViper()); err != nil {
+        panic(err)
+    }
+}
+```
+
+**In RunE:**
+```go
+RunE: func(cmd *cobra.Command, args []string) error {
+    // Parse flags using Viper (respects precedence)
+    v := viper.GetViper()
+    if err := myParser.BindFlagsToViper(cmd, v); err != nil {
+        return err
+    }
+
+    // Access values via Viper
+    check := v.GetBool("check")
+    format := v.GetString("format")
+
+    return exec.MyCommand(check, format)
+}
+```
+
+**Linter Protection (Forbidigo):**
+- ❌ `viper.BindEnv()` is BANNED outside `pkg/flags/`
+- ❌ `viper.BindPFlag()` is BANNED outside `pkg/flags/`
+- ✅ Consult flag-handler agent for all flag-related work
+- ✅ See `cmd/version/version.go` for reference implementation.
+
 ### Error Handling (MANDATORY)
 - **All errors MUST be wrapped using static errors defined in `errors/errors.go`**
 - **Use `errors.Join` for combining multiple errors** - preserves all error chains