Atmos Project Layout

Use this skill for repository layout, root paths, and how atmos.yaml paths resolve.

Root Paths

base_path sets the root for most relative project paths. Keep it explicit when a repository does not use the current directory as the Atmos root.

base_path: ""

stacks:
  base_path: stacks

components:
  terraform:
    base_path: components/terraform

workflows:
  base_path: stacks/workflows

schemas:
  jsonschema:
    base_path: stacks/schemas/jsonschema
  opa:
    base_path: stacks/schemas/opa

Conventional Layout

.
  atmos.yaml
  atmos.d/
    stacks.yaml
    components.yaml
    auth.yaml
  components/
    terraform/
    helmfile/
    packer/
    ansible/
  stacks/
    catalog/
    workflows/
    orgs/
    schemas/

Use atmos.d/ for modular root config when atmos.yaml gets too large. Use stack imports for stack manifest inheritance and catalog composition; do not confuse root config imports with stack imports.

Path Rules

• Root base_path controls how project paths resolve.
• Subsystem base_path values are normally relative to the root base_path.
• Workflow --file values are relative to workflows.base_path.
• Schema paths are relative to their schema base path unless an absolute path is used.
• Stack import paths are a stack-manifest concern; load atmos-stacks for stack inheritance details.

Routing

Need	Load
Config discovery, merge order, import of root config	atmos-config
Stack discovery, stack imports, stack naming	atmos-stacks
Component type directories and component metadata	atmos-components
Terraform backend and command-specific path behavior	atmos-terraform
Workflow file discovery	atmos-workflows
Schema directories and validation paths	atmos-schemas, atmos-validation
Profiles path and activation	atmos-profiles

Guardrails

• Do not force the canonical components/terraform layout during migrations; point base_path and component paths at the user's existing repository when that is safer.
• Prefer a small root atmos.yaml plus focused atmos.d/*.yaml files for large projects.
• Verify layout assumptions with atmos describe config before generating large changes.