Component Development

Component Development

Use this skill when adding or changing an Atmos native component type or shared component behavior.

Start With The Existing Contract

Inspect comparable component types before designing:

rg -n "ComponentType|SectionName|components\\..*base_path" pkg/config pkg/schema
rg -n "component.Register|ComponentProvider|Execute\\(" pkg/component cmd internal
rg -n "process.*ComponentsIndexed|ExecuteGraph|dependencies.components" internal pkg

For stack-surface decisions, compare Terraform, Helmfile, Packer, and Ansible. Reuse shared sections when they already exist:

• metadata
• vars
• env
• settings
• hooks
• auth
• dependencies
• generate
• source
• provision

Do not invent nested settings for component-owned inputs. If an instance is components.<type>.<name>, component-specific inputs belong directly under that instance, e.g. components.kubernetes.argocd.paths, not settings.kubernetes.paths.

Required Wiring

For a new component type, update all applicable surfaces in one PR:

• Constants: pkg/config/const.go
• CLI/default config structs: pkg/schema/schema.go
• Defaults: pkg/config/default.go
• Config path resolution: pkg/config/config.go, pkg/utils/component_path_utils.go
• Component registry provider: pkg/component/<type>/
• Command package: cmd/<type>/
• Root side-effect imports: cmd/root.go
• Source provisioning base path support: pkg/provisioner/source/
• Hooks/events if lifecycle hooks are supported: pkg/hooks/
• Affected detection: internal/exec/describe_affected_*
• DAG/bulk execution if --all or --affected is supported
• Embedded CLI usage examples: cmd/markdown/atmos_<command>*_usage.md
• Runtime stack schemas: pkg/datafetcher/schema/atmos/manifest/1.0.json and pkg/datafetcher/schema/stacks/stack-config/1.0.json
• LSP hints if stack authoring changes: pkg/lsp/server/
• Docs: command docs, stack component docs, atmos.yaml config docs
• Examples under examples/ for user-visible component types

If a public website schema file exists in the checkout, update it too. Do not assume it exists; verify with find website/static -path '*schema*'.

Command Behavior

Commands should be Atmos-native, not thin binary wrappers, when the implementation owns behavior.

• Use the component registry provider rather than hard-coded command logic.
• Use flags.NewStandardParser() for command-specific flags.
• Preserve --identity and profile handling.
• For bulk operations, allow zero positional component args with --all or --affected.
• Reject ambiguous forms such as component arg plus --all.
• Use dotted hook events such as before.<type>.<operation> and after.<type>.<operation>.
• Add embedded usage examples for every public subcommand.

If a command name like kubectl or kustomize is used as a provider, be explicit whether it means CLI execution or compatible behavior. For SDK-backed providers, do not add a command override unless a binary is actually executed.

Auth

Thread Auth through stack processing and execution:

• Parse global --identity into ConfigAndStacksInfo.Identity.
• Use the same auth setup path as existing component commands when stack YAML functions or integrations need credentials.
• Keep component-level auth: in the stack schema.
• For Kubernetes-like SDK clients, create the client after Auth has prepared environment or kubeconfig integration output.
• Prefer plain ambient for local examples that should respect the surrounding environment without prompting for provider login. Use concrete provider identities for examples that actually require a cloud or service-specific authentication flow.

DAG And Affected

If the component supports --all or --affected:

• Build nodes from components.<type>.
• Skip abstract, disabled, and locked components where applicable.
• Use dependencies.components as the primary dependency source.
• Keep legacy settings.depends_on only as compatibility.
• Process in topological order.
• For --affected, run affected detection first, filter to the component type, then graph-filter selected nodes.
• Include dependencies by default so prerequisites run before selected nodes.
• Make --include-dependents explicit for downstream components.

Affected detection must include both implementation path changes and stack config changes. For new component-specific top-level sections, add affected reasons for those sections.