cloudposse
diff --git a/‎.claude/skills/atmos-components‎
Lines changed: 0 additions & 1 deletion b/‎.claude/skills/atmos-components‎
Lines changed: 0 additions & 1 deletion
diff --git a/‎.claude/skills/atmos-core-component-development/SKILL.md‎
Lines changed: 95 additions & 0 deletions b/‎.claude/skills/atmos-core-component-development/SKILL.md‎
Lines changed: 95 additions & 0 deletions
diff --git a/‎agent-skills/skills/atmos-devcontainer/SKILL.md‎
Lines changed: 5 additions & 5 deletions b/‎agent-skills/skills/atmos-devcontainer/SKILL.md‎
Lines changed: 5 additions & 5 deletions
diff --git a/‎cmd/composition/composition.go‎
Lines changed: 97 additions & 0 deletions b/‎cmd/composition/composition.go‎
Lines changed: 97 additions & 0 deletions
diff --git a/‎cmd/composition/composition_test.go‎
Lines changed: 71 additions & 0 deletions b/‎cmd/composition/composition_test.go‎
Lines changed: 71 additions & 0 deletions
diff --git a/‎cmd/container/completions.go‎
Lines changed: 82 additions & 0 deletions b/‎cmd/container/completions.go‎
Lines changed: 82 additions & 0 deletions
@@ -0,0 +1,95 @@
+---
+name: atmos-core-component-development
+description: "Atmos CORE contributor guide for adding/modifying a component TYPE in the Go codebase (terraform/helmfile/packer/ansible/container): the component registry & provider, the CLI command group, the describe/list type whitelist, custom-component inheritance & deep-merge, schema, and tests. NOT for authoring user components in stacks (that is the atmos-components skill)."
+metadata:
+  copyright: Copyright Cloud Posse, LLC 2026
+  version: "1.0.0"
+---
+
+# Atmos Core: Component Type Development
+
+Use this skill when **developing Atmos itself** — adding or modifying a component **type** (kind) in the
+Go codebase. This is contributor/core guidance, distinct from the user-facing `atmos-components` skill
+(which documents authoring terraform/helmfile/container components in stacks).
+
+Start from `docs/developing-component-plugins.md` (the component-plugin development guide). The notes
+below capture the non-obvious wiring learned while adding the `container` component type.
+
+## The component provider (pkg/component)
+
+A component type is a `ComponentProvider` (`pkg/component/provider.go`) registered via `init()` with
+`component.Register(...)` (`pkg/component/registry.go`). Reference impls:
+
+- `pkg/component/ansible/` — typed-config built-in style.
+- `pkg/component/mock/`, `pkg/component/custom/` — the `Plugins`-map plugin style.
+- `pkg/component/container/` — provider + `cmd`/lifecycle split.
+
+Layout per the guide: `config.go` (typed `Config` + `parseConfig`), `<type>.go` (provider + `init`),
+`executor.go` (verb implementations), `<type>_test.go` (>90% coverage). Wire a blank import into
+`cmd/root.go` so `init()` runs.
+
+Reusable error sentinels live in `errors/errors.go`: `ErrComponentExecutionFailed`,
+`ErrComponentConfigInvalid`, `ErrComponentValidationFailed`, `ErrComponentTypeEmpty`.
+
+## First-class component config (NOT `vars`)
+
+Per-instance config that is **not arbitrary template data** must be first-class top-level sections
+(siblings of `metadata`/`env`/`composition`), NOT nested under `vars`. For container, the config reuses
+the workflow container-step structs (`schema.ContainerBuildStep`/`ContainerRunStep`/`ContainerMount`/
+`ContainerPort` in `pkg/schema/workflow.go`) for consistency. Decode a YAML-derived `map[string]any`
+into those structs with mapstructure using `TagName: "yaml"` so snake_case keys (`build_args`,
+`read_only`) map.
+
+## The CLI command group (cmd/<type>)
+
+Mirror `cmd/ansible/`: a base `cobra.Command` registered through the command registry
+(`cmd/internal` `CommandProvider`), persistent flags via `flags.NewStandardParser()` (NEVER
+`viper.BindEnv`/`BindPFlag`), one thin file per verb dispatching to
+`component.MustGetProvider(<type>).Execute(&component.ExecutionContext{...})`. Wire a blank import into
+`cmd/root.go`.
+
+## CRITICAL: the describe/list type whitelist
+
+A new top-level `components.<type>` is **dropped** (stack renders `{}`, "component not found") unless
+the type is added to several hardcoded lists. Grep `AnsibleSectionName` / `"ansible"` across
+`internal/exec` + `pkg/list/extract` and mirror every hit:
+
+1. `pkg/config/const.go` — `XComponentType` / `XSectionName` consts.
+2. `internal/exec/describe_stacks_component_processor.go` — the `typeEntries` list AND
+   `componentsSectionHasComponents`.
+3. `internal/exec/describe_stacks.go` — `getComponentBasePath` switch.
+4. `internal/exec/describe_component.go` — the `detectComponentType` auto-detect order (a loop over
+   `[terraform, helmfile, packer, ansible, container]`); a type missing here makes `atmos describe
+   component <name>` fail even when the lifecycle works.
+5. `pkg/list/extract/components.go` — THREE hardcoded type lists (per-stack `extractComponentType` ×2,
+   unique `extractUniqueComponentType`).
+
+Verify with `atmos describe stacks` (stack with only the new type must be non-empty) and
+`atmos describe component <name> -s <stack>`.
+
+## Inheritance & deep-merge for custom types
+
+Built-in types (terraform/helmfile/packer/ansible) get full inheritance via the processComponent
+pipeline. Other types ride the **custom-component fallback** in
+`internal/exec/stack_processor_process_stacks.go`. That fallback now resolves `metadata.inherits` and
+**generic-deep-merges all top-level keys** (`resolveCustomComponentInheritance`), so custom types honor
+catalog/abstract defaults. Gotchas:
+
+- Strip `metadata.type`/`inherits`/`component` from a base before merging, or an abstract base poisons
+  the concrete component (`sanitizeBaseForInheritance`).
+- Reject `metadata.type: abstract` for execution and filter it from listings.
+- Use the **native merge** (`pkg/merge`) — it already incorporates the slice-truncation and
+  permissive-type-mismatch fixes in `docs/fixes/2026-03-19-*` and `docs/fixes/2026-03-24-*`.
+- Component-level config *sections* (vars/settings/env/hooks/secrets/...) that need per-section
+  inheritance still require the section whitelist plumbing (see `docs/errors.md` / the merge helpers).
+
+## Schema, docs, tests
+
+- JSON schema: `pkg/datafetcher/schema/atmos/manifest/1.0.json` — add `<type>_components` +
+  `<type>_component_manifest` definitions and the `components.<type>` property.
+- Docs: `website/docs/components/components-overview.mdx` (Component Types table + directory diagram),
+  `website/docs/components/<type>.mdx`, and `website/docs/cli/commands/<type>/usage.mdx`.
+- Tests: provider unit tests with a mockgen `Runtime`/dependency, `cmd.NewTestKit` for the command,
+  inheritance + abstract + graceful-empty cases. Regenerate affected `--help` golden snapshots with
+  `-regenerate-snapshots` (never hand-edit).
+- Gate: `./custom-gcl run --new-from-rev=origin/<base> ./pkg/component/<type>/... ./internal/exec/...`.
@@ -96,11 +96,11 @@ Containers follow the naming convention: `atmos-devcontainer.{name}.{instance}`
 All Atmos devcontainers are labeled for management:
 
 ```text
-com.atmos.type=devcontainer
-com.atmos.devcontainer.name={name}
-com.atmos.devcontainer.instance={instance}
-com.atmos.workspace={workspace-path}
-com.atmos.created={timestamp}
+tools.atmos.type=devcontainer
+tools.atmos.devcontainer.name={name}
+tools.atmos.devcontainer.instance={instance}
+tools.atmos.workspace={workspace-path}
+tools.atmos.created={timestamp}
 ```
 
 ### Runtime Auto-Detection
 
@@ -0,0 +1,97 @@
+package composition
+
+import (
+	"github.com/spf13/cobra"
+	"github.com/spf13/viper"
+
+	"github.com/cloudposse/atmos/cmd/internal"
+	pkgcomposition "github.com/cloudposse/atmos/pkg/composition"
+	cfg "github.com/cloudposse/atmos/pkg/config"
+	"github.com/cloudposse/atmos/pkg/flags"
+	"github.com/cloudposse/atmos/pkg/flags/compat"
+	"github.com/cloudposse/atmos/pkg/schema"
+)
+
+var compositionParser *flags.StandardParser
+
+// compositionCmd is the base command for composition operations.
+var compositionCmd = &cobra.Command{
+	Use:   "composition",
+	Short: "Inspect compositions that group component instances into systems",
+	Long:  "Operate on compositions — named groupings of component instances (services) that form a system.",
+	RunE: func(cmd *cobra.Command, _ []string) error {
+		return cmd.Usage()
+	},
+}
+
+// The validate subcommand reports a composition's fulfilled and not-provided services.
+var validateCmd = &cobra.Command{
+	Use:   "validate <composition>",
+	Short: "Report a composition's fulfilled and not-provided services for a stack",
+	Long:  "Show which of a composition's declared services are fulfilled by components in a stack and which are not provided there.",
+	Args:  cobra.ExactArgs(1),
+	RunE: func(cmd *cobra.Command, args []string) error {
+		info := buildConfigAndStacksInfo(cmd)
+		return pkgcomposition.ExecuteValidate(cmd.Context(), &info, args[0])
+	},
+}
+
+func init() {
+	compositionParser = flags.NewStandardParser(flags.WithFlagRegistry(flags.CommonFlags()))
+	compositionParser.RegisterPersistentFlags(compositionCmd)
+	if err := compositionParser.BindToViper(viper.GetViper()); err != nil {
+		panic(err)
+	}
+
+	compositionCmd.AddCommand(validateCmd)
+	internal.Register(&CompositionCommandProvider{})
+}
+
+// CompositionCommandProvider implements the CommandProvider interface.
+type CompositionCommandProvider struct{}
+
+// GetCommand returns the composition command.
+func (c *CompositionCommandProvider) GetCommand() *cobra.Command { return compositionCmd }
+
+// GetName returns the command name.
+func (c *CompositionCommandProvider) GetName() string { return "composition" }
+
+// GetGroup returns the command group for help organization.
+func (c *CompositionCommandProvider) GetGroup() string { return "Core Stack Commands" }
+
+// GetAliases returns command aliases.
+func (c *CompositionCommandProvider) GetAliases() []internal.CommandAlias { return nil }
+
+// GetFlagsBuilder returns the flags builder for this command.
+func (c *CompositionCommandProvider) GetFlagsBuilder() flags.Builder { return nil }
+
+// GetPositionalArgsBuilder returns the positional args builder for this command.
+func (c *CompositionCommandProvider) GetPositionalArgsBuilder() *flags.PositionalArgsBuilder {
+	return nil
+}
+
+// GetCompatibilityFlags returns compatibility flags for this command.
+func (c *CompositionCommandProvider) GetCompatibilityFlags() map[string]compat.CompatibilityFlag {
+	return nil
+}
+
+// IsExperimental returns whether this command is experimental.
+func (c *CompositionCommandProvider) IsExperimental() bool { return false }
+
+// buildConfigAndStacksInfo creates a ConfigAndStacksInfo from global + stack flags.
+func buildConfigAndStacksInfo(cmd *cobra.Command) schema.ConfigAndStacksInfo {
+	globalFlags := flags.ParseGlobalFlags(cmd, viper.GetViper())
+	info := schema.ConfigAndStacksInfo{
+		AtmosBasePath:           globalFlags.BasePath,
+		AtmosConfigFilesFromArg: globalFlags.Config,
+		AtmosConfigDirsFromArg:  globalFlags.ConfigPath,
+		Identity:                cfg.NormalizeIdentityValue(globalFlags.Identity.Value()),
+		ProfilesFromArg:         globalFlags.Profile,
+	}
+	// Resolve the stack via viper so the full precedence chain is honored
+	// (flag > ATMOS_STACK env > config), not just the directly-set Cobra flag.
+	if stack := viper.GetViper().GetString("stack"); stack != "" {
+		info.Stack = stack
+	}
+	return info
+}
@@ -0,0 +1,71 @@
+package composition
+
+import (
+	"testing"
+
+	"github.com/spf13/viper"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestCompositionCommandProvider(t *testing.T) {
+	provider := &CompositionCommandProvider{}
+
+	cmd := provider.GetCommand()
+	require.NotNil(t, cmd)
+	assert.Equal(t, "composition", cmd.Use)
+	assert.Equal(t, "composition", provider.GetName())
+	assert.Equal(t, "Core Stack Commands", provider.GetGroup())
+	assert.Nil(t, provider.GetAliases())
+	assert.Nil(t, provider.GetFlagsBuilder())
+	assert.Nil(t, provider.GetPositionalArgsBuilder())
+	assert.Nil(t, provider.GetCompatibilityFlags())
+	assert.False(t, provider.IsExperimental())
+}
+
+func TestCompositionCommandStructure(t *testing.T) {
+	subcommands := compositionCmd.Commands()
+	names := make([]string, len(subcommands))
+	for i, c := range subcommands {
+		names[i] = c.Name()
+	}
+	assert.Contains(t, names, "validate")
+}
+
+func TestValidateRequiresExactlyOneArg(t *testing.T) {
+	// validate <composition> takes exactly one positional argument.
+	tests := []struct {
+		name    string
+		args    []string
+		wantErr bool
+	}{
+		{name: "no args", args: []string{}, wantErr: true},
+		{name: "exactly one arg", args: []string{"storefront"}, wantErr: false},
+		{name: "too many args", args: []string{"a", "b"}, wantErr: true},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			err := validateCmd.Args(validateCmd, tt.args)
+			if tt.wantErr {
+				require.Error(t, err)
+				return
+			}
+			require.NoError(t, err)
+		})
+	}
+}
+
+func TestBuildConfigAndStacksInfo_ResolvesStack(t *testing.T) {
+	// Stack is resolved via viper so the full precedence chain is honored.
+	v := viper.GetViper()
+	orig := v.GetString("stack")
+	t.Cleanup(func() { v.Set("stack", orig) })
+
+	v.Set("stack", "dev")
+	info := buildConfigAndStacksInfo(compositionCmd)
+	assert.Equal(t, "dev", info.Stack)
+
+	v.Set("stack", "")
+	info = buildConfigAndStacksInfo(compositionCmd)
+	assert.Empty(t, info.Stack)
+}
@@ -0,0 +1,82 @@
+package container
+
+import (
+	"github.com/spf13/cobra"
+	"github.com/spf13/viper"
+
+	e "github.com/cloudposse/atmos/internal/exec"
+	cfg "github.com/cloudposse/atmos/pkg/config"
+	"github.com/cloudposse/atmos/pkg/flags"
+	l "github.com/cloudposse/atmos/pkg/list"
+	"github.com/cloudposse/atmos/pkg/perf"
+	"github.com/cloudposse/atmos/pkg/schema"
+)
+
+// globalInfoForCompletion builds a minimal ConfigAndStacksInfo from global flags
+// so completion honors config-selection flags.
+func globalInfoForCompletion(cmd *cobra.Command) schema.ConfigAndStacksInfo {
+	globalFlags := flags.ParseGlobalFlags(cmd, viper.GetViper())
+	return schema.ConfigAndStacksInfo{
+		AtmosBasePath:           globalFlags.BasePath,
+		AtmosConfigFilesFromArg: globalFlags.Config,
+		AtmosConfigDirsFromArg:  globalFlags.ConfigPath,
+		ProfilesFromArg:         globalFlags.Profile,
+	}
+}
+
+// stackFlagCompletion provides completion values for the --stack flag.
+func stackFlagCompletion(cmd *cobra.Command, _ []string, _ string) ([]string, cobra.ShellCompDirective) {
+	defer perf.Track(nil, "container.stackFlagCompletion")()
+
+	atmosConfig, err := cfg.InitCliConfig(globalInfoForCompletion(cmd), true)
+	if err != nil {
+		return nil, cobra.ShellCompDirectiveNoFileComp
+	}
+	stacksMap, err := e.ExecuteDescribeStacks(&atmosConfig, "", nil, nil, nil, false, false, false, false, nil, nil)
+	if err != nil {
+		return nil, cobra.ShellCompDirectiveNoFileComp
+	}
+	stacks, err := l.FilterAndListStacks(stacksMap, "")
+	if err != nil {
+		return nil, cobra.ShellCompDirectiveNoFileComp
+	}
+	return stacks, cobra.ShellCompDirectiveNoFileComp
+}
+
+// componentArgCompletion provides completion values for the component argument.
+func componentArgCompletion(cmd *cobra.Command, args []string, _ string) ([]string, cobra.ShellCompDirective) {
+	defer perf.Track(nil, "container.componentArgCompletion")()
+
+	if len(args) > 0 {
+		return nil, cobra.ShellCompDirectiveNoFileComp
+	}
+	// Honor the --stack flag and restrict suggestions to container components so
+	// completion never offers non-container or wrong-stack components.
+	stack := ""
+	if stackFlag := cmd.Flag("stack"); stackFlag != nil {
+		stack = stackFlag.Value.String()
+	}
+	atmosConfig, err := cfg.InitCliConfig(globalInfoForCompletion(cmd), true)
+	if err != nil {
+		return nil, cobra.ShellCompDirectiveNoFileComp
+	}
+	stacksMap, err := e.ExecuteDescribeStacks(&atmosConfig, stack, nil, []string{cfg.ContainerComponentType}, nil, false, false, false, false, nil, nil)
+	if err != nil {
+		return nil, cobra.ShellCompDirectiveNoFileComp
+	}
+	components, err := l.FilterAndListComponents(stack, stacksMap)
+	if err != nil {
+		return nil, cobra.ShellCompDirectiveNoFileComp
+	}
+	return components, cobra.ShellCompDirectiveNoFileComp
+}
+
+// RegisterContainerCompletions registers completion functions for the container
+// command. Every subcommand takes a component argument.
+func RegisterContainerCompletions(cmd *cobra.Command) {
+	defer perf.Track(nil, "container.RegisterContainerCompletions")()
+
+	for _, subCmd := range cmd.Commands() {
+		subCmd.ValidArgsFunction = componentArgCompletion
+	}
+}