feat: Add experimental feature transparency and controls

.claude/agents/flag-handler.md

@@ -17,6 +17,8 @@ description: >-
   - --check, --format, --stack, or any flag name discussions
   - Flag improvements, flag refactoring, flag migration
   - Troubleshooting flags, flag issues, flag errors
+  - experimental, IsExperimental, experimental commands, ATMOS_EXPERIMENTAL
+  - settings.experimental, experimental feature handling
 
   **CRITICAL: pkg/flags/ is FULLY IMPLEMENTED. This is NOT future architecture.**
 
@@ -563,6 +565,60 @@ type global.Flags struct {
 }
 ```
 
+## Experimental Feature Handling
+
+Commands can be marked as experimental by implementing `IsExperimental() bool`:
+
+```go
+// IsExperimental returns whether this command is experimental.
+func (t *MyCommandProvider) IsExperimental() bool {
+    return true
+}
+```
+
+For subcommands, use the `experimental` annotation:
+
+```go
+mySubCmd := &cobra.Command{
+    Use: "affected",
+    Annotations: map[string]string{
+        "experimental": "true",
+    },
+}
+```
+
+### Experimental Configuration
+
+Users configure experimental feature handling via `settings.experimental` in `atmos.yaml`:
+
+```yaml
+settings:
+  # Control experimental feature handling
+  # Values: "silence", "disable", "warn" (default), "error"
+  experimental: warn
+```
+
+| Mode | Behavior |
+|------|----------|
+| `silence` | Run without any notification |
+| `warn` | Show notification, then continue (default) |
+| `error` | Show notification and exit with error |
+| `disable` | Block experimental commands entirely |
+
+Environment variable: `ATMOS_EXPERIMENTAL`
+
+### How It Works
+
+1. Commands declare experimental status via `IsExperimental() bool` method
+2. Root command's `PersistentPreRunE` checks if any command in the tree is experimental
+3. Based on `settings.experimental` value, it either:
+   - `silence`: Does nothing
+   - `warn`: Shows notification via `ui.Experimental()`, continues
+   - `error`: Shows notification, exits with error
+   - `disable`: Exits with error (no notification)
+
+See [/experimental](https://atmos.tools/experimental) for full documentation.
+
 Embed in options struct:
 
 ```go
@@ -684,11 +740,7 @@ When implementing complex commands, coordinate with other agents:
 
 ## Resources
 
-**Primary PRDs:**
-- `docs/prd/flag-handling/unified-flag-parsing.md` - Unified flag parsing architecture
-- `docs/prd/flag-handling/strongly-typed-builder-pattern.md` - Builder pattern implementation
-- `docs/prd/flag-handling/global-flags-pattern.md` - Global flags design
-- `docs/prd/command-registry-pattern.md` - Command registry architecture
+**PRDs:** `docs/prd/flag-handling/` (unified-flag-parsing.md, strongly-typed-builder-pattern.md, global-flags-pattern.md), `docs/prd/command-registry-pattern.md`
 
 **Additional PRDs:**
 - `docs/prd/flag-handling/README.md` - Overview of flag handling architecture
@@ -707,52 +759,10 @@ When implementing complex commands, coordinate with other agents:
 
 ## Key Principle
 
-**Everything goes through the command registry.** There is no direct flag parsing - all commands MUST implement CommandProvider and register with `internal.Register()`.
+**Everything goes through the command registry.** All commands MUST implement CommandProvider and register with `internal.Register()`.
 
 ## Self-Maintenance
 
-This agent actively monitors and updates itself when dependencies change.
-
-**Dependencies to monitor:**
-- `docs/prd/flag-handling/unified-flag-parsing.md` - Core flag parsing architecture
-- `docs/prd/flag-handling/strongly-typed-builder-pattern.md` - Builder pattern implementation
-- `docs/prd/flag-handling/global-flags-pattern.md` - Global flags design
-- `docs/prd/command-registry-pattern.md` - Command registry architecture
-- `CLAUDE.md` - Core development patterns
-- `cmd/internal/command.go` - CommandProvider interface definition
-- `pkg/flags/builder.go` - Builder interface definition
-
-**Update triggers:**
-1. **PRD updated** - When flag-handling PRDs or command-registry PRD modified
-2. **Interface changes** - When CommandProvider or Builder interfaces evolve
-3. **Pattern maturity** - When new flag patterns emerge in implementations
-4. **Invocation unclear** - When agent isn't triggered appropriately
-
-**Update process:**
-1. Detect change: `git log -1 --format="%ai" docs/prd/flag-handling/*.md`
-2. Read updated documentation
-3. Draft proposed changes to agent
-4. **Present changes to user for confirmation**
-5. Upon approval, apply updates
-6. Test with sample command implementation
-7. Commit with descriptive message referencing PRD version
-
-**Self-check before each invocation:**
-- Read latest version of unified-flag-parsing.md
-- Verify CommandProvider interface hasn't changed
-- Check for new flag patterns in recent command implementations
-
-## Relevant PRDs
-
-This agent implements patterns from:
-
-- `docs/prd/flag-handling/unified-flag-parsing.md` - Unified flag parsing architecture
-- `docs/prd/flag-handling/strongly-typed-builder-pattern.md` - Builder pattern
-- `docs/prd/flag-handling/global-flags-pattern.md` - Global flags design
-- `docs/prd/command-registry-pattern.md` - Command registry
-
-**Before implementing:**
-1. Check PRD modification date: `git log -1 --format="%ai" docs/prd/flag-handling/unified-flag-parsing.md`
-2. Compare with last sync date
-3. If newer, read full PRD before proceeding
-4. Update this agent if patterns have changed
+**Monitor:** `docs/prd/flag-handling/*.md`, `docs/prd/command-registry-pattern.md`, `cmd/internal/command.go`, `pkg/flags/builder.go`
+
+**Before each invocation:** Check PRD dates with `git log -1 --format="%ai" docs/prd/flag-handling/unified-flag-parsing.md`. If newer than last sync, read full PRD and update agent if patterns changed.

.github/settings.yml

@@ -37,3 +37,6 @@ labels:
   - name: go
     color: '#00add8'
     description: Pull requests that update Go code
+  - name: experimental
+    color: '#ff9800'
+    description: Feature is experimental and still being refined

cmd/about/about.go

@@ -68,3 +68,8 @@ func (a *AboutCommandProvider) GetCompatibilityFlags() map[string]compat.Compati
 func (a *AboutCommandProvider) GetAliases() []internal.CommandAlias {
 	return nil
 }
+
+// IsExperimental returns whether this command is experimental.
+func (a *AboutCommandProvider) IsExperimental() bool {
+	return false
+}

cmd/devcontainer/devcontainer.go

@@ -77,3 +77,9 @@ func (d *DevcontainerCommandProvider) GetCompatibilityFlags() map[string]compat.
 func (d *DevcontainerCommandProvider) GetAliases() []internal.CommandAlias {
 	return nil
 }
+
+// IsExperimental returns whether this command is experimental.
+// Devcontainer support is currently experimental.
+func (d *DevcontainerCommandProvider) IsExperimental() bool {
+	return true
+}

cmd/env/env.go

@@ -283,3 +283,8 @@ func (e *EnvCommandProvider) GetCompatibilityFlags() map[string]compat.Compatibi
 func (e *EnvCommandProvider) GetAliases() []internal.CommandAlias {
 	return nil
 }
+
+// IsExperimental returns whether this command is experimental.
+func (e *EnvCommandProvider) IsExperimental() bool {
+	return false
+}

cmd/help_template.go

@@ -52,6 +52,17 @@ const (
 	valueZero = "0"
 )
 
+// Command annotation constants.
+const (
+	annotationExperimental = "experimental"
+	annotationValueTrue    = "true"
+)
+
+// isExperimentalCommand checks if a command has the experimental annotation.
+func isExperimentalCommand(cmd *cobra.Command) bool {
+	return cmd.Annotations != nil && cmd.Annotations[annotationExperimental] == annotationValueTrue
+}
+
 // colorConfig holds the color detection and environment variable configuration.
 type colorConfig struct {
 	forceColor         bool
@@ -358,6 +369,13 @@ func printLogoAndVersion(w io.Writer, styles *helpStyles) {
 func printDescription(w io.Writer, cmd *cobra.Command, styles *helpStyles) {
 	defer perf.Track(nil, "cmd.printDescription")()
 
+	// Print experimental badge if command is experimental.
+	if isExperimentalCommand(cmd) {
+		badge := ui.FormatExperimentalBadge()
+		fmt.Fprintln(w, badge)
+		fmt.Fprintln(w)
+	}
+
 	var desc string
 	switch {
 	case cmd.Long != "":
@@ -496,82 +514,86 @@ func isConfigAlias(cmd *cobra.Command) bool {
 }
 
 // calculateCommandWidth calculates the display width of a command name including type suffix.
-func calculateCommandWidth(cmd *cobra.Command) int {
+// If parentExperimental is true, experimental badges won't be shown on subcommands.
+func calculateCommandWidth(cmd *cobra.Command, parentExperimental bool) int {
 	width := len(cmd.Name())
 	if cmd.HasAvailableSubCommands() {
 		width += len(" [command]")
 	}
+	// Account for experimental badge if present and parent is not already experimental.
+	if isExperimentalCommand(cmd) && !parentExperimental {
+		width += len(" [EXPERIMENTAL]")
+	}
 	return width
 }
 
 // calculateMaxCommandWidth finds the maximum command name width for alignment.
 // Config aliases are excluded from this calculation since they're shown in a separate section.
-func calculateMaxCommandWidth(commands []*cobra.Command) int {
+// If parentExperimental is true, experimental badges won't be included in width calculations.
+func calculateMaxCommandWidth(commands []*cobra.Command, parentExperimental bool) int {
 	maxWidth := 0
 	for _, c := range commands {
 		if !isCommandAvailable(c) || isConfigAlias(c) {
 			continue
 		}
-		width := calculateCommandWidth(c)
+		width := calculateCommandWidth(c, parentExperimental)
 		if width > maxWidth {
 			maxWidth = width
 		}
 	}
 	return maxWidth
 }
 
+// getExperimentalBadge returns the styled and plain badge strings if command is experimental.
+// Returns empty strings if parent is already experimental or command is not experimental.
+func getExperimentalBadge(cmd *cobra.Command, parentExperimental bool) (styled, plain string) {
+	if isExperimentalCommand(cmd) && !parentExperimental {
+		return " " + ui.FormatExperimentalBadge(), " [EXPERIMENTAL]"
+	}
+	return "", ""
+}
+
 // formatCommandLine formats a single command line with proper padding and styling.
-func formatCommandLine(ctx *helpRenderContext, cmd *cobra.Command, maxWidth int, mdRenderer *markdown.Renderer) {
+func formatCommandLine(ctx *helpRenderContext, cmd *cobra.Command, maxWidth int, mdRenderer *markdown.Renderer, parentExperimental bool) {
 	cmdName := cmd.Name()
-	cmdTypePlain := ""
-	cmdTypeStyled := ""
+	cmdTypePlain, cmdTypeStyled := "", ""
 	if cmd.HasAvailableSubCommands() {
 		cmdTypePlain = " [command]"
 		cmdTypeStyled = " " + ctx.styles.flagName.Render("[command]")
 	}
 
-	padding := maxWidth - len(cmdName) - len(cmdTypePlain)
+	experimentalBadge, experimentalBadgePlain := getExperimentalBadge(cmd, parentExperimental)
+	padding := maxWidth - len(cmdName) - len(cmdTypePlain) - len(experimentalBadgePlain)
 
-	// Calculate where the description starts (left pad + command name + padding + spacing)
+	// Calculate description column position and width.
 	descColStart := commandListLeftPad + maxWidth + commandDescriptionSpacing
-
-	// Get terminal width and calculate available width for description
-	termWidth := getTerminalWidth()
-	descWidth := termWidth - descColStart
+	descWidth := getTerminalWidth() - descColStart
 	if descWidth < minDescriptionWidth {
 		descWidth = minDescriptionWidth
 	}
 
+	// Write command name and badges.
 	fmt.Fprint(ctx.writer, strings.Repeat(spaceChar, commandListLeftPad))
 	fmt.Fprint(ctx.writer, ctx.styles.commandName.Render(cmdName))
 	fmt.Fprint(ctx.writer, cmdTypeStyled)
-	fmt.Fprint(ctx.writer, strings.Repeat(spaceChar, padding))
-	fmt.Fprint(ctx.writer, strings.Repeat(spaceChar, commandDescriptionSpacing))
+	fmt.Fprint(ctx.writer, experimentalBadge)
+	fmt.Fprint(ctx.writer, strings.Repeat(spaceChar, padding+commandDescriptionSpacing))
 
-	// Wrap plain text first, then render markdown without additional wrapping.
-	// This matches the approach used by flag description rendering.
+	// Render description with word wrap and markdown.
 	wrapped := wordwrap.String(cmd.Short, descWidth)
-
 	if mdRenderer != nil {
-		rendered, err := mdRenderer.RenderWithoutWordWrap(wrapped)
-		if err == nil {
+		if rendered, err := mdRenderer.RenderWithoutWordWrap(wrapped); err == nil {
 			wrapped = strings.TrimSpace(rendered)
 		}
 	}
 
+	// Write description lines.
 	lines := strings.Split(wrapped, "\n")
-
-	// Print first line (already positioned)
 	if len(lines) > 0 {
 		fmt.Fprintf(ctx.writer, "%s\n", ctx.styles.commandDesc.Render(lines[0]))
 	}
-
-	// Print continuation lines with proper indentation
-	if len(lines) > 1 {
-		indentStr := strings.Repeat(spaceChar, descColStart)
-		for i := 1; i < len(lines); i++ {
-			fmt.Fprintf(ctx.writer, "%s%s\n", indentStr, ctx.styles.commandDesc.Render(lines[i]))
-		}
+	for i := 1; i < len(lines); i++ {
+		fmt.Fprintf(ctx.writer, "%s%s\n", strings.Repeat(spaceChar, descColStart), ctx.styles.commandDesc.Render(lines[i]))
 	}
 }
 
@@ -586,7 +608,11 @@ func printAvailableCommands(ctx *helpRenderContext, cmd *cobra.Command) {
 	fmt.Fprintln(ctx.writer, ctx.styles.heading.Render("AVAILABLE COMMANDS"))
 	fmt.Fprintln(ctx.writer)
 
-	maxCmdWidth := calculateMaxCommandWidth(cmd.Commands())
+	// Check if the parent command is experimental.
+	// If so, subcommands don't need to repeat the badge since it's shown at the top.
+	parentExperimental := isExperimentalCommand(cmd)
+
+	maxCmdWidth := calculateMaxCommandWidth(cmd.Commands(), parentExperimental)
 
 	// Create markdown renderer for command descriptions (same approach as flag rendering).
 	var mdRenderer *markdown.Renderer
@@ -598,7 +624,7 @@ func printAvailableCommands(ctx *helpRenderContext, cmd *cobra.Command) {
 		if !isCommandAvailable(c) || isConfigAlias(c) {
 			continue
 		}
-		formatCommandLine(ctx, c, maxCmdWidth, mdRenderer)
+		formatCommandLine(ctx, c, maxCmdWidth, mdRenderer, parentExperimental)
 	}
 	fmt.Fprintln(ctx.writer)
 }