CLAUDE.md (7)

64-64: Grammar nit: add article “a”

Minor polish.

-- **`cmd/`** - Cobra CLI command definitions, each command in separate file
+- **`cmd/`** - Cobra CLI command definitions, each command in a separate file

---

441-450: Rephrase SDK guidance to align with current design

Atmos often shells out to Terraform; suggest SDKs as an option, not a blanket rule.

-- **Prefer SDKs over calling binaries** when available:
+- **Prefer SDKs over calling binaries** when it does not conflict with Atmos' current execution model:
@@
-  // CORRECT: Using SDK (cross-platform)
+  // Option: Using SDK (cross-platform)

---

3-4: Scope note to set expectations for contributors

Small addition clarifies this is assistive guidance for AI/humans; source of truth remains code and repo docs.

-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+This file provides guidance to Claude Code (claude.ai/code) and contributors working with this repository. It is assistive, not normative; the source of truth remains the codebase and official docs.

---

338-344: Coverage wording: tie to codecov.yml to avoid ambiguity

Verified that codecov.yml specifies an 80% patch coverage target, so this tweak aligns the docs with the actual config.

-- **80% minimum coverage** on new/changed lines (enforced by CodeCov)
+- **80% minimum coverage** on new/changed lines (enforced via Codecov per codecov.yml)

---

262-293: Add missing language identifiers to fenced code blocks in CLAUDE.md

It looks like there are several unlabeled ``` fences throughout CLAUDE.md, including in the snippet around lines 262–293. Please add the appropriate language (for example, shell, `mdx`, `javascript`, etc.) to each opening fence to satisfy markdownlint’s MD040 rule. You can rerun `markdownlint-cli2` locally to verify everything is labeled.

Unlabeled fences detected (partial list):

• Line 39
• Line 59
• Line 108
• Line 145
• Line 166
• Line 215
• Lines 260, 284, 291, 292
• …and others throughout the file

Next steps:

• Go through each fence and change to, e.g.,shell or ```mdx as appropriate.
• Run markdownlint-cli2 CLAUDE.md to confirm no MD040 warnings remain.

---

401-408: ✅ Schema files exist; simplify update instructions

I ran the verification script and confirmed that all four schema files are present under pkg/datafetcher/schema (no missing paths). Keeping the explicit list is accurate today, but it can drift as new schemas are added.

• Location: CLAUDE.md lines 401–408
• Verified files:
– pkg/datafetcher/schema/config/global/1.0.json
– pkg/datafetcher/schema/atmos/manifest/1.0.json
– pkg/datafetcher/schema/stacks/stack-config/1.0.json
– pkg/datafetcher/schema/vendor/package/1.0.json

Suggested optional refactor: replace the hard-coded list with a directory-based instruction and a validation step. For example:

### Schema Updates (MANDATORY)
- **Update ALL schema files** when adding Atmos configuration options:
-  - pkg/datafetcher/schema/config/global/1.0.json
-  - pkg/datafetcher/schema/atmos/manifest/1.0.json
-  - pkg/datafetcher/schema/stacks/stack-config/1.0.json
-  - pkg/datafetcher/schema/vendor/package/1.0.json
+ **Update all schema files under** `pkg/datafetcher/schema/` **when adding Atmos configuration options.**
+ Run `make validate-schemas` (or your project’s equivalent) to ensure no regressions.
- Validate schema changes don't break existing configurations

This keeps the guidance future-proof—any new schemas added to that directory are automatically covered.

---

509-512: Sync Go version notation in documentation

To keep this from aging out of date, let’s remove the hard-coded “1.24+” and point readers at the source of truth:

• In CLAUDE.md (lines 509–512), replace:

- Go 1.24+ (see go.mod for exact version)
+ Go (see go.mod for exact version and CI matrix)

This ties the documented requirement to the actual go.mod entry (go 1.24.5) and whatever versions your CI tests.

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled by default for public repositories
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

Learnt from: Listener430
PR: cloudposse/atmos#934
File: tests/fixtures/scenarios/docs-generate/README.md.gotmpl:99-118
Timestamp: 2025-01-25T03:51:57.689Z
Learning: For the cloudposse/atmos repository, changes to template contents should be handled in dedicated PRs and are typically considered out of scope for PRs focused on other objectives.

Learnt from: CR
PR: cloudposse/atmos#0
File: .cursor/rules/atmos-rules.mdc:0-0
Timestamp: 2025-07-01T02:22:25.901Z
Learning: All code must pass golangci-lint checks

Learnt from: osterman
PR: cloudposse/atmos#808
File: pkg/config/config.go:478-483
Timestamp: 2024-12-02T21:26:32.337Z
Learning: In the 'atmos' project, when reviewing Go code like `pkg/config/config.go`, avoid suggesting file size checks after downloading remote configs if such checks aren't implemented elsewhere in the codebase.

Learnt from: osterman
PR: cloudposse/atmos#740
File: cmd/cmd_utils.go:340-359
Timestamp: 2024-10-23T21:36:40.262Z
Learning: In the Go codebase for Atmos, when reviewing functions like `checkAtmosConfig` in `cmd/cmd_utils.go`, avoid suggesting refactoring to return errors instead of calling `os.Exit` if such changes would significantly increase the scope due to the need to update multiple call sites.

Learnt from: aknysh
PR: cloudposse/atmos#1363
File: internal/exec/template_utils.go:18-18
Timestamp: 2025-07-05T20:59:02.914Z
Learning: In the Atmos project, gomplate v4 is imported with a blank import (`_ "github.com/hairyhenderson/gomplate/v4"`) alongside v3 imports to resolve AWS SDK version conflicts. V3 uses older AWS SDK versions that conflict with newer AWS modules used by Atmos. A full migration to v4 requires extensive refactoring due to API changes and should be handled in a separate PR.

Learnt from: CR
PR: cloudposse/atmos#0
File: .cursor/rules/atmos-rules.mdc:0-0
Timestamp: 2025-07-01T02:22:25.901Z
Learning: Applies to **/*.go : Follow Go's documentation conventions

Learnt from: CR
PR: cloudposse/atmos#0
File: .cursor/rules/atmos-rules.mdc:0-0
Timestamp: 2025-07-01T02:22:25.901Z
Learning: Applies to cmd/*.go : Include troubleshooting hints when appropriate

Learnt from: Listener430
PR: cloudposse/atmos#844
File: cmd/helmfile.go:37-37
Timestamp: 2024-12-11T18:40:12.808Z
Learning: In the atmos project, `cliConfig` is initialized within the `cmd` package in `root.go` and can be used in other command files.

CLAUDE.md (1)

42-59: Sync CLI examples with current command surface (validate schema args, remove vendor diff).

Per prior verification, “validate schema” does not take two positionals, and “vendor diff” isn’t wired into help. Update the snippet accordingly.

 ### Key Atmos Commands
 ```bash
 # Core functionality
 atmos terraform plan <component> -s <stack>
 atmos terraform apply <component> -s <stack>
 atmos describe component <component> -s <stack>
 atmos list components
 atmos list stacks
 atmos workflow <workflow> -f <file)

 # Validation and schema
 atmos validate stacks
 atmos validate component <component> -s <stack>
-atmos validate schema <schema-type> <schema-path>
+atmos validate schema [<schema-key>]                     # optional key from atmos.yaml
+atmos validate schema --schemas-atmos-manifest <path>    # explicit schema manifest path

 # Vendoring and dependencies  
 atmos vendor pull
-atmos vendor diff

</blockquote></details>

</blockquote></details>

<details>
<summary>🧹 Nitpick comments (6)</summary><blockquote>

<details>
<summary>CLAUDE.md (6)</summary><blockquote>

`544-556`: **Avoid brittle file/line references in telemetry section.**

Hard-coding “cmd/root.go:174” will drift. Refer to the execution path or function instead.


```diff
-- **New commands automatically get telemetry** via `RootCmd.ExecuteC()` in `cmd/root.go:174`
+- **New commands automatically get telemetry** via the `RootCmd.ExecuteC()` execution path

---

447-454: Don’t publish hex codes for theme constants; point to the source of truth.

Hex values can diverge from theme.Colors. Recommend naming the constants only.

-**Use consistent Atmos theme colors** from `pkg/ui/theme/colors.go`:
-  - Success: `ColorGreen` (#00FF00)
-  - Info: `ColorCyan` (#00FFFF) 
-  - Error: `ColorRed` (#FF0000)
-  - Selected: `ColorSelectedItem` (#10ff10)
-  - Border: `ColorBorder` (#5F5FD7)
-- Use `theme.Styles` and `theme.Colors` for consistent formatting
+**Use consistent Atmos theme colors** from `pkg/ui/theme/colors.go`:
+  - Success: `theme.Colors.ColorGreen`
+  - Info: `theme.Colors.ColorCyan`
+  - Error: `theme.Colors.ColorRed`
+  - Selected: `theme.Colors.ColorSelectedItem`
+  - Border: `theme.Colors.ColorBorder`
+- Always consume `theme.Styles` and `theme.Colors`; avoid hard-coded hex values.

---

379-386: Use Viper keys mapped to multiple env vars; avoid using env names as keys.

This pattern is more idiomatic and plays well with AutomaticEnv and prefixes.

-  // WRONG: Only binding external env var
-  viper.BindEnv("GITHUB_TOKEN")
-
-  // CORRECT: Provide Atmos alternative  
-  viper.BindEnv("ATMOS_GITHUB_TOKEN", "GITHUB_TOKEN")
-  viper.BindEnv("ATMOS_PRO_TOKEN", "ATMOS_PRO_TOKEN")
+  // Prefer config keys mapped to one or more env vars (Atmos-first, then fallbacks)
+  viper.BindEnv("github.token", "ATMOS_GITHUB_TOKEN", "GITHUB_TOKEN")
+  viper.BindEnv("pro.token",    "ATMOS_PRO_TOKEN")
+  // With:
+  // viper.SetEnvPrefix("ATMOS")
+  // viper.AutomaticEnv()

---

33-33: Avoid over-specifying golangci-lint behavior in docs.

Makefile behavior varies; the “only files changed from origin/main” detail can drift.

-make lint                    # Run golangci-lint (only files changed from origin/main)
+make lint                    # Run golangci-lint

---

85-90: Document gomplate v3/v4 import nuance to avoid AWS SDK conflicts.

Based on prior learning for this repo, we keep a blank v4 import to sidestep SDK clashes; full v4 migration is separate.

 **Template System**:
 - Go text/template with custom functions
 - Gomplate integration for advanced templating
+- Note: v4 is imported alongside v3 via a blank import to avoid AWS SDK conflicts; a full v4 migration is tracked separately.
 - Context-aware functions: `atmos.Component()`, `terraform.output()`, etc.
 - Store integration for runtime secret resolution

If helpful, I can add a short “Gomplate imports” note under Development Environment.

---

147-166: Specify languages for inner code fences in the markdown example.

Improves syntax highlighting and lints cleanly even inside the markdown fence.

 ```markdown
 - Basic usage
 
-```
+```shell
 $ atmos example <component> -s <stack>
-```
+```
 
 - With output format
 
-```
+```shell
 $ atmos example <component> -s <stack> --format=yaml|json
-```
+```
 
 - Write result to file
 
-```
+```shell
 $ atmos example <component> -s <stack> --file output.yaml
-```
+```

</blockquote></details>

</blockquote></details>

<details>
<summary>📜 Review details</summary>

**Configuration used**: Path: .coderabbit.yaml

**Review profile**: CHILL

**Plan**: Pro

**💡 Knowledge Base configuration:**

- MCP integration is disabled by default for public repositories
- Jira integration is disabled by default for public repositories
- Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

<details>
<summary>📥 Commits</summary>

Reviewing files that changed from the base of the PR and between 79e33c6e95fa4254c512989a89bf32bd0e71a064 and 00415d0544588b2146b6b8942817b5bced470e4e.

</details>

<details>
<summary>📒 Files selected for processing (1)</summary>

* `CLAUDE.md` (1 hunks)

</details>

<details>
<summary>🧰 Additional context used</summary>

<details>
<summary>🧠 Learnings (7)</summary>

<details>
<summary>📚 Learning: 2025-07-01T02:22:25.901Z</summary>

Learnt from: CR
PR: cloudposse/atmos#0
File: .cursor/rules/atmos-rules.mdc:0-0
Timestamp: 2025-07-01T02:22:25.901Z
Learning: All code must pass golangci-lint checks

**Applied to files:**
- `CLAUDE.md`

</details>
<details>
<summary>📚 Learning: 2024-12-02T21:26:32.337Z</summary>

Learnt from: osterman
PR: #808
File: pkg/config/config.go:478-483
Timestamp: 2024-12-02T21:26:32.337Z
Learning: In the 'atmos' project, when reviewing Go code like pkg/config/config.go, avoid suggesting file size checks after downloading remote configs if such checks aren't implemented elsewhere in the codebase.

**Applied to files:**
- `CLAUDE.md`

</details>
<details>
<summary>📚 Learning: 2024-10-23T21:36:40.262Z</summary>

Learnt from: osterman
PR: #740
File: cmd/cmd_utils.go:340-359
Timestamp: 2024-10-23T21:36:40.262Z
Learning: In the Go codebase for Atmos, when reviewing functions like checkAtmosConfig in cmd/cmd_utils.go, avoid suggesting refactoring to return errors instead of calling os.Exit if such changes would significantly increase the scope due to the need to update multiple call sites.

**Applied to files:**
- `CLAUDE.md`

</details>
<details>
<summary>📚 Learning: 2025-07-01T02:22:25.901Z</summary>

Learnt from: CR
PR: cloudposse/atmos#0
File: .cursor/rules/atmos-rules.mdc:0-0
Timestamp: 2025-07-01T02:22:25.901Z
Learning: Applies to cmd/*.go : Include troubleshooting hints when appropriate

**Applied to files:**
- `CLAUDE.md`

</details>
<details>
<summary>📚 Learning: 2025-07-01T02:22:25.901Z</summary>

Learnt from: CR
PR: cloudposse/atmos#0
File: .cursor/rules/atmos-rules.mdc:0-0
Timestamp: 2025-07-01T02:22:25.901Z
Learning: Applies to **/*.go : Follow Go's documentation conventions

**Applied to files:**
- `CLAUDE.md`

</details>
<details>
<summary>📚 Learning: 2025-07-05T20:59:02.914Z</summary>

Learnt from: aknysh
PR: #1363
File: internal/exec/template_utils.go:18-18
Timestamp: 2025-07-05T20:59:02.914Z
Learning: In the Atmos project, gomplate v4 is imported with a blank import (_ "github.com/hairyhenderson/gomplate/v4") alongside v3 imports to resolve AWS SDK version conflicts. V3 uses older AWS SDK versions that conflict with newer AWS modules used by Atmos. A full migration to v4 requires extensive refactoring due to API changes and should be handled in a separate PR.

**Applied to files:**
- `CLAUDE.md`

</details>
<details>
<summary>📚 Learning: 2024-12-11T18:40:12.808Z</summary>

Learnt from: Listener430
PR: #844
File: cmd/helmfile.go:37-37
Timestamp: 2024-12-11T18:40:12.808Z
Learning: In the atmos project, cliConfig is initialized within the cmd package in root.go and can be used in other command files.

**Applied to files:**
- `CLAUDE.md`

</details>

</details><details>
<summary>🪛 LanguageTool</summary>

<details>
<summary>CLAUDE.md</summary>

[grammar] ~7-~7: There might be a mistake here.
Context: ...astructure using Terraform. It provides: - **Stack-based configuration management** w...

(QB_NEW_EN)

---

[grammar] ~8-~8: There might be a mistake here.
Context: ...agement** with hierarchical YAML configs - **Multi-cloud orchestration** for Terrafor...

(QB_NEW_EN)

---

[grammar] ~9-~9: There might be a mistake here.
Context: ...on** for Terraform, Helmfile, and Packer - **Component architecture** for reusable in...

(QB_NEW_EN)

---

[grammar] ~10-~10: There might be a mistake here.
Context: ...e** for reusable infrastructure patterns - **Advanced templating** with Go templates ...

(QB_NEW_EN)

---

[grammar] ~11-~11: There might be a mistake here.
Context: ...with Go templates and Gomplate functions - **Workflow orchestration** for complex dep...

(QB_NEW_EN)

---

[grammar] ~12-~12: There might be a mistake here.
Context: ...ation** for complex deployment pipelines - **Policy validation** using OPA and JSON S...

(QB_NEW_EN)

---

[grammar] ~13-~13: There might be a mistake here.
Context: ...y validation** using OPA and JSON Schema - **Vendoring system** for external componen...

(QB_NEW_EN)

---

[grammar] ~14-~14: There might be a mistake here.
Context: ...ndoring system** for external components - **Terminal UI** with rich interactive comp...

(QB_NEW_EN)

---

[grammar] ~15-~15: Please add a punctuation mark at the end of paragraph.
Context: ...- **Terminal UI** with rich interactive components  ## Essential Commands  ### Development...

(PUNCTUATION_PARAGRAPH_END)

---

[grammar] ~64-~64: There might be a mistake here.
Context: ...a CLI command definitions, each command in separate file - **`internal/exec/`** - ...

(QB_NEW_EN)

---

[grammar] ~78-~78: There might be a mistake here.
Context: ...Concepts  **Stack Processing Pipeline**:  1. Load base configuration (`atmos.yaml`) 2...

(QB_NEW_EN)

---

[grammar] ~89-~89: Please add a punctuation mark at the end of paragraph.
Context: ... - Store integration for runtime secret resolution  **Component Lifecycle**: - Discovery v...

(PUNCTUATION_PARAGRAPH_END)

---

[grammar] ~91-~91: There might be a mistake here.
Context: ...ret resolution  **Component Lifecycle**: - Discovery via filesystem scanning - Conf...

(QB_NEW_EN)

---

[grammar] ~92-~92: There might be a mistake here.
Context: ...e**: - Discovery via filesystem scanning - Configuration merging from multiple sour...

(QB_NEW_EN)

---

[grammar] ~93-~93: There might be a mistake here.
Context: ...figuration merging from multiple sources - Variable file generation for tools (Terr...

(QB_NEW_EN)

---

[grammar] ~94-~94: There might be a mistake here.
Context: ...neration for tools (Terraform, Helmfile) - Backend configuration generation - Execu...

(QB_NEW_EN)

---

[grammar] ~95-~95: There might be a mistake here.
Context: ...file) - Backend configuration generation - Execution orchestration with progress tr...

(QB_NEW_EN)

---

[grammar] ~100-~100: There might be a mistake here.
Context: ...& Conventions  ### Configuration Loading Configuration follows strict precedence:...

(QB_NEW_EN)

---

[grammar] ~110-~110: There might be a mistake here.
Context: ...vPrefix("ATMOS") ```  ### Error Handling - Wrap errors with context: `fmt.Errorf("p...

(QB_NEW_EN)

---

[grammar] ~111-~111: There might be a mistake here.
Context: ...or Handling - Wrap errors with context: `fmt.Errorf("processing component %s: %w", component, err)` - Use custom error types in `pkg/` package...

(QB_NEW_EN)

---

[grammar] ~116-~116: There might be a mistake here.
Context: ...y messages for CLI  ### Testing Strategy - **Unit tests**: Focus on pure functions, u...

(QB_NEW_EN)

---

[grammar] ~122-~122: There might be a mistake here.
Context: .../`  ### CLI Command Structure & Examples Atmos uses **embedded markdown files** f...

(QB_NEW_EN)

---

[grammar] ~174-~174: There might be a mistake here.
Context: ...ommand>_usage.md`  ### File Organization - One command per file in `cmd/` - Group r...

(QB_NEW_EN)

---

[grammar] ~176-~176: There might be a mistake here.
Context: ...ated functionality in `pkg/` subpackages - Tests alongside implementation files (`_...

(QB_NEW_EN)

---

[grammar] ~177-~177: There might be a mistake here.
Context: ...ngside implementation files (`_test.go`) - Shared test utilities in `tests/` direct...

(QB_NEW_EN)

---

[grammar] ~178-~178: There might be a mistake here.
Context: ...red test utilities in `tests/` directory - Mock files alongside interfaces they moc...

(QB_NEW_EN)

---

[grammar] ~202-~202: There might be a mistake here.
Context: ...ting Guidelines  ### Test File Locations - Unit tests: `pkg/**/*_test.go` - Integra...

(QB_NEW_EN)

---

[grammar] ~203-~203: There might be a mistake here.
Context: ...  ### Test File Locations - Unit tests: `pkg/**/*_test.go` - Integration tests: `tests/**/*_test.go` ...

(QB_NEW_EN)

---

[grammar] ~204-~204: There might be a mistake here.
Context: ...: `tests/**/*_test.go` with fixtures in `tests/test-cases/` - Command tests: `cmd/**/*_test.go`  ### R...

(QB_NEW_EN)

---

[grammar] ~221-~221: Please add a punctuation mark at the end of paragraph.
Context: ...definitions - `components/` - Component configurations  ## Common Development Tasks  ### Addin...

(PUNCTUATION_PARAGRAPH_END)

---

[grammar] ~225-~225: There might be a mistake here.
Context: ...opment Tasks  ### Adding New CLI Command 1. Create `cmd/new_command.go` with Cobra c...

(QB_NEW_EN)

---

[grammar] ~227-~227: There might be a mistake here.
Context: ...*Create embedded markdown examples** in `cmd/markdown/atmos_command_subcommand_usage.md` 3. **Use `//go:embed` and `utils.PrintfMarkdo...

(QB_NEW_EN)

---

[grammar] ~228-~228: There might be a mistake here.
Context: ...rintfMarkdown()`** for example rendering 4. **Register in `cmd/markdown_help.go`** exa...

(QB_NEW_EN)

---

[grammar] ~229-~229: There might be a mistake here.
Context: ...p.go`** examples map with suggestion URL 5. **Use markdown formatting** in Short/Long ...

(QB_NEW_EN)

---

[grammar] ~230-~230: There might be a mistake here.
Context: ...ptions (supports **bold**, `code`, etc.) 6. Add business logic in appropriate `pkg/`...

(QB_NEW_EN)

---

[grammar] ~231-~231: There might be a mistake here.
Context: ...**, `code`, etc.) 6. Add business logic in appropriate `pkg/` or `internal/exec/` ...

(QB_NEW_EN)

---

[grammar] ~232-~232: There might be a mistake here.
Context: ... **Create Docusaurus documentation** in `website/docs/cli/commands/<command>/<subcommand>.mdx` 8. Add tests with fixtures 9. Add integrati...

(QB_NEW_EN)

---

[grammar] ~234-~234: There might be a mistake here.
Context: ...ith fixtures 9. Add integration test in `tests/` 10. **Create pull request following template f...

(QB_NEW_EN)

---

[grammar] ~235-~235: There might be a mistake here.
Context: ...t in `tests/` 10. **Create pull request following template format**  ### Documentation Re...

(QB_NEW_EN)

---

[grammar] ~235-~235: Please add a punctuation mark at the end of paragraph.
Context: ...*Create pull request following template format**  ### Documentation Requirements (MAND...

(PUNCTUATION_PARAGRAPH_END)

---

[grammar] ~237-~237: There might be a mistake here.
Context: ...# Documentation Requirements (MANDATORY) - **All new commands/flags/parameters MUST h...

(QB_NEW_EN)

---

[grammar] ~294-~294: There might be a mistake here.
Context: ...value   ```   ```  - **File location**: `website/docs/cli/commands/<command>/<subcommand>.mdx` - **Link to core concepts** using `/core-con...

(QB_NEW_EN)

---

[grammar] ~299-~299: There might be a mistake here.
Context: ...## Pull Request Requirements (MANDATORY) - **Follow the pull request template** in `....

(QB_NEW_EN)

---

[typographical] ~315-~315: Consider using a typographic opening quote here.
Context: ...23` if PR closes an issue   ``` - **Use "no-release" label** for documentation-on...

(EN_QUOTES)

---

[typographical] ~315-~315: Consider using a typographic close quote here.
Context: ...loses an issue   ``` - **Use "no-release" label** for documentation-only changes ...

(EN_QUOTES)

---

[grammar] ~318-~318: There might be a mistake here.
Context: ...ing review  ### Adding Template Function 1. Implement in `internal/exec/template_fun...

(QB_NEW_EN)

---

[grammar] ~319-~319: There might be a mistake here.
Context: ...dding Template Function 1. Implement in `internal/exec/template_funcs.go` 2. Register in template function map 3. Add...

(QB_NEW_EN)

---

[grammar] ~320-~320: There might be a mistake here.
Context: ...go` 2. Register in template function map 3. Add comprehensive tests 4. Document in w...

(QB_NEW_EN)

---

[grammar] ~321-~321: There might be a mistake here.
Context: ... function map 3. Add comprehensive tests 4. Document in website if user-facing  ### ...

(QB_NEW_EN)

---

[grammar] ~324-~324: There might be a mistake here.
Context: ...ing  ### Bug Fixing Workflow (MANDATORY) 1. **Write a test to reproduce the bug** - cr...

(QB_NEW_EN)

---

[grammar] ~327-~327: There might be a mistake here.
Context: ...bug iteratively** - make changes and re-run test until it passes 4. **Verify fix do...

(QB_NEW_EN)

---

[grammar] ~355-~355: There might be a mistake here.
Context: ...) } ```  ### Extending Store Integration 1. Implement interface in `pkg/store/` 2. A...

(QB_NEW_EN)

---

[grammar] ~356-~356: There might be a mistake here.
Context: ...e Integration 1. Implement interface in `pkg/store/` 2. Add to store registry 3. Update configur...

(QB_NEW_EN)

---

[grammar] ~357-~357: There might be a mistake here.
Context: ...in `pkg/store/` 2. Add to store registry 3. Update configuration schema 4. Add integ...

(QB_NEW_EN)

---

[grammar] ~358-~358: There might be a mistake here.
Context: ... registry 3. Update configuration schema 4. Add integration tests with mocks  ### St...

(QB_NEW_EN)

---

[grammar] ~361-~361: There might be a mistake here.
Context: ...with mocks  ### Stack Processing Changes 1. Core logic in `pkg/stack/` and `internal...

(QB_NEW_EN)

---

[grammar] ~362-~362: There might be a mistake here.
Context: ...anges 1. Core logic in `pkg/stack/` and `internal/exec/stack_processor_utils.go` 2. Test with multiple inheritance scenarios...

(QB_NEW_EN)

---

[grammar] ~369-~369: There might be a mistake here.
Context: ...uirements  ### Test Coverage (MANDATORY) - **80% minimum coverage** on new/changed li...

(QB_NEW_EN)

---

[grammar] ~370-~370: There might be a mistake here.
Context: ... new/changed lines (enforced by CodeCov) - ALL new features MUST include comprehens...

(QB_NEW_EN)

---

[typographical] ~388-~388: In American English, use a period after an abbreviation.
Context: ...O_TOKEN")   ```  ### Structured Logging vs UI Output (MANDATORY) - **Distinguish b...

(MISSING_PERIOD_AFTER_ABBREVIATION)

---

[grammar] ~388-~388: There might be a mistake here.
Context: ...uctured Logging vs UI Output (MANDATORY) - **Distinguish between logging and UI outpu...

(QB_NEW_EN)

---

[grammar] ~404-~404: There might be a mistake here.
Context: ... username)   ```  - **UI Output Rules**:   - User prompts, status messages, progress ...

(QB_NEW_EN)

---

[grammar] ~405-~405: There might be a mistake here.
Context: ...s messages, progress indicators → stderr   - Error messages requiring user action → s...

(QB_NEW_EN)

---

[grammar] ~406-~406: There might be a mistake here.
Context: ... messages requiring user action → stderr     - Data/results for piping → stdout   - **N...

(QB_NEW_EN)

---

[grammar] ~407-~407: There might be a mistake here.
Context: ...r     - Data/results for piping → stdout   - **Never use logging for UI elements**  - *...

(QB_NEW_EN)

---

[grammar] ~410-~410: There might be a mistake here.
Context: ... for UI elements**  - **Logging Rules**:   - System events, debugging, error tracking...

(QB_NEW_EN)

---

[grammar] ~411-~411: There might be a mistake here.
Context: ...nts, debugging, error tracking → logging   - **Logging should not affect execution** - ...

(QB_NEW_EN)

---

[grammar] ~414-~414: There might be a mistake here.
Context: ...rpolation   - Follow logging hierarchy: `LogFatal > LogError > LogWarn > LogDebug > LogTrace`   - Use appropriate levels per `docs/logging...

(QB_NEW_EN)

---

[grammar] ~418-~418: There might be a mistake here.
Context: ...bled  ### Output Conventions (MANDATORY)   - **Most text UI MUST go to stderr** to enab...

(QB_NEW_EN)

---

[grammar] ~438-~438: There might be a mistake here.
Context: ...ng   ```  ### Schema Updates (MANDATORY) - **Update ALL schema files** when adding At...

(QB_NEW_EN)

---

[grammar] ~453-~453: Please add a punctuation mark at the end of paragraph.
Context: ...yles` and `theme.Colors` for consistent formatting  ### Template Integration (MANDATORY) -...

(PUNCTUATION_PARAGRAPH_END)

---

[grammar] ~455-~455: There might be a mistake here.
Context: ...ng  ### Template Integration (MANDATORY) - **All new configs MUST support Go templati...

(QB_NEW_EN)

---

[grammar] ~467-~467: There might be a mistake here.
Context: ...ous contexts  ### Code Reuse (MANDATORY) - **Search for existing methods** before imp...

(QB_NEW_EN)

---

[style] ~469-~469: The phrase ‘Look for patterns’ is used very frequently. Consider using a less frequent alternative to set your writing apart from others.
Context: ...before implementing new functionality - Look for patterns in `internal/exec/` and `pkg/` that can...

(LOOK_FOR_STYLE)

---

[grammar] ~471-~471: There might be a mistake here.
Context: ...g duplicates - Common reusable patterns:   - File operations: `pkg/utils/file_utils.g...

(QB_NEW_EN)

---

[grammar] ~472-~472: There might be a mistake here.
Context: ...reusable patterns:   - File operations: `pkg/utils/file_utils.go`   - YAML processing: `pkg/utils/yaml_utils.g...

(QB_NEW_EN)

---

[grammar] ~473-~473: There might be a mistake here.
Context: ...ils/file_utils.go`   - YAML processing: `pkg/utils/yaml_utils.go`   - Component processing: `internal/exec/com...

(QB_NEW_EN)

---

[grammar] ~474-~474: There might be a mistake here.
Context: ...aml_utils.go`   - Component processing: `internal/exec/component_utils.go`   - Stack processing: `internal/exec/stack_p...

(QB_NEW_EN)

---

[grammar] ~477-~477: There might be a mistake here.
Context: ...Cross-Platform Compatibility (MANDATORY) - **Atmos MUST work on Linux, macOS, and Win...

(QB_NEW_EN)

---

[grammar] ~491-~491: There might be a mistake here.
Context: ...` for OS-specific logic when unavoidable - Test on all supported platforms or use b...

(QB_NEW_EN)

---

[grammar] ~493-~493: Please add a punctuation mark at the end of paragraph.
Context: ...missions, path lengths, and environment variables  ### Multi-Provider Interface Pattern (...

(PUNCTUATION_PARAGRAPH_END)

---

[grammar] ~495-~495: There might be a mistake here.
Context: ...i-Provider Interface Pattern (MANDATORY) - **Create interfaces for multi-provider fun...

(QB_NEW_EN)

---

[grammar] ~544-~544: There might be a mistake here.
Context: ...telemetry** via `RootCmd.ExecuteC()` in `cmd/root.go:174` - **No additional telemetry code needed** fo...

(QB_NEW_EN)

---

[grammar] ~560-~560: There might be a mistake here.
Context: ...velopment Environment  ### Prerequisites - Go 1.24+ (see go.mod for exact version) ...

(QB_NEW_EN)

---

[grammar] ~561-~561: There might be a mistake here.
Context: ... Go 1.24+ (see go.mod for exact version) - golangci-lint for linting - Make for bui...

(QB_NEW_EN)

---

[grammar] ~562-~562: There might be a mistake here.
Context: ...act version) - golangci-lint for linting - Make for build automation  ### IDE Confi...

(QB_NEW_EN)

---

[grammar] ~565-~565: There might be a mistake here.
Context: ... build automation  ### IDE Configuration   The project includes Cursor rules in `.c...

(QB_NEW_EN)

---

[grammar] ~566-~566: There might be a mistake here.
Context: ....cursor/rules/atmos-rules.mdc` covering: - Code structure and patterns - Testing re...

(QB_NEW_EN)

---

[grammar] ~567-~567: There might be a mistake here.
Context: ... covering: - Code structure and patterns - Testing requirements   - Documentation s...

(QB_NEW_EN)

---

[grammar] ~568-~568: There might be a mistake here.
Context: ...ture and patterns - Testing requirements   - Documentation standards - Quality checks...

(QB_NEW_EN)

---

[grammar] ~569-~569: There might be a mistake here.
Context: ...requirements   - Documentation standards - Quality checks and linting  ### Build Pr...

(QB_NEW_EN)

</details>

</details>
<details>
<summary>🪛 markdownlint-cli2 (0.17.2)</summary>

<details>
<summary>CLAUDE.md</summary>

292-292: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

</details>

</details>

</details>

<details>
<summary>⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (4)</summary>

* GitHub Check: Build (windows-latest, windows)
* GitHub Check: Lint (golangci)
* GitHub Check: Analyze (go)
* GitHub Check: Summary

</details>

<details>
<summary>🔇 Additional comments (3)</summary><blockquote>

<details>
<summary>CLAUDE.md (3)</summary><blockquote>

`1-20`: **Solid addition; clear scope and actionable guidance.**

This doc sets strong expectations (coverage, schema hygiene, UI/logging split) and gives copy-pastable patterns. Nice work.

---

`21-39`: **Verified: All documented Makefile targets are present**

I’ve confirmed that each of the targets you listed in CLAUDE.md (build, build-linux, build-windows, build-macos, testacc, testacc-cover, testacc-coverage, version, get, and lint) has a corresponding rule in the Makefile. No missing targets detected.

---

`560-565`: **Go version in CLAUDE.md is accurate**  
go.mod specifies `go 1.24.5` (line 3), which satisfies the “Go 1.24+ (see go.mod for exact version)” prerequisite in CLAUDE.md. No updates needed.

</blockquote></details>

</blockquote></details>

</details>

<!-- This is an auto-generated comment by CodeRabbit for review status -->

CLAUDE.md (4)

242-244: Remove unsupported provider from list; point to registry as source of truth.

Google Secret Manager appears listed as supported, but there’s no implementation in pkg/store today. Keep this future-friendly by naming only verified providers and deferring to the registry for the authoritative list.

Apply this diff:

-### Store Functions (Runtime Secret Resolution)
-- `store.get(type, key)` - Get value from external store
-- Supports: AWS SSM, Azure Key Vault, Google Secret Manager, Redis, Artifactory
-- **See `pkg/store/registry.go`** for the authoritative list of supported store providers
+### Store Functions (Runtime Secret Resolution)
+- `store.get(type, key)` - Get value from external store
+- Supports: AWS SSM, Azure Key Vault, Redis, Artifactory
+- See `pkg/store/registry.go` for the authoritative list of providers (use the registry as the source of truth).

---

204-209: Align example filenames with actual implementations.

The file organization example includes google_secretmanager_store.go. If GCP is not implemented yet, this misleads readers.

Apply this diff:

   // pkg/store/
   store.go              // Interface definition
   aws_ssm_store.go     // AWS SSM implementation 
   azure_keyvault_store.go // Azure implementation
-  google_secretmanager_store.go // Google implementation
+  # Add new providers in separate files (see registry for current list)
+  # gcp_secretmanager_store.go // Google Secret Manager (when implemented)

---

553-556: Don’t advertise unimplemented providers in examples.

The interface examples and the “Examples in codebase” line reference Google Secret Manager as implemented.

Apply this diff:

-  type GoogleSecretManagerStore struct { /* ... */ }
+  // Add additional providers as they’re implemented (see registry for status)

-- **Examples in codebase**: `pkg/store/` (AWS SSM, Azure Key Vault, Google Secret Manager)
+- **Examples in codebase**: `pkg/store/` (for example: AWS SSM, Azure Key Vault)

Also applies to: 586-586

---

331-338: Fix extra fenced code block (markdownlint MD040).

There’s a stray “```” after the Examples block that breaks rendering.

Apply this diff:

   ## Examples
   
   ```shell
   atmos command subcommand example1
   atmos command subcommand example2 --flag=value

</blockquote></details>

</blockquote></details>

<details>
<summary>🧹 Nitpick comments (4)</summary><blockquote>

<details>
<summary>CLAUDE.md (4)</summary><blockquote>

`421-431`: **Viper BindEnv example: bind a normalized key to multiple env vars.**

Using an uppercase config key (`ATMOS_GITHUB_TOKEN`) as the Viper key is atypical and makes lookups inconsistent. Prefer binding a normalized config key to multiple env vars.

Apply this diff:

```diff
-// WRONG: Only binding external env var
-viper.BindEnv("GITHUB_TOKEN")
-
-// CORRECT: Provide Atmos alternative  
-viper.BindEnv("ATMOS_GITHUB_TOKEN", "GITHUB_TOKEN")
-viper.BindEnv("ATMOS_PRO_TOKEN", "ATMOS_PRO_TOKEN")
+// Bind a normalized configuration key to multiple env vars (Atmos-first)
+viper.BindEnv("github.token", "ATMOS_GITHUB_TOKEN", "GITHUB_TOKEN")
+viper.BindEnv("pro.token", "ATMOS_PRO_TOKEN")
+
+// Later:
+// token := viper.GetString("github.token")

---

589-591: Remove brittle line number reference.

Referencing cmd/root.go:174 will drift. Drop the line number.

Apply this diff:

-- **New commands automatically get telemetry** via `RootCmd.ExecuteC()` in `cmd/root.go:174`
+- **New commands automatically get telemetry** via `RootCmd.ExecuteC()` in `cmd/root.go`

---

327-336: Escape angle brackets in Docusaurus CLI examples.

Per house style, escape <arg> placeholders in docs to avoid MDX/HTML interpretation.

Apply this diff:

   ```shell
-  atmos command subcommand <args> [options]
+  atmos command subcommand &lt;args&gt; [options]

---

`491-499`: **Use exported theme color constants in CLAUDE.md**

Verification shows that `pkg/ui/theme/colors.go` defines all of the referenced constants:
- ColorGreen (`#00FF00`)
- ColorCyan (`#00FFFF`)
- ColorRed (`#FF0000`)
- ColorSelectedItem (`#10ff10`)
- ColorBorder (`#5F5FD7`)

To prevent drift between documentation and code, please remove the hard-coded hex values from `CLAUDE.md` and reference only the exported constants:

```diff
### Styling & Theme (MANDATORY)
- **Use consistent Atmos theme colors** from `pkg/ui/theme/colors.go`:
-  - Success: `ColorGreen` (#00FF00)
-  - Info: `ColorCyan` (#00FFFF)
-  - Error: `ColorRed` (#FF0000)
-  - Selected: `ColorSelectedItem` (#10ff10)
-  - Border: `ColorBorder` (#5F5FD7)
- Use `theme.Styles` and `theme.Colors` for consistent formatting
+ Use `theme.Styles` and the exported color constants from `pkg/ui/theme/colors.go` for consistent formatting.
+ Reference only constants such as:
+    - `theme.ColorGreen`
+    - `theme.ColorCyan`
+    - `theme.ColorRed`
+    - `theme.ColorSelectedItem`
+    - `theme.ColorBorder`

• File: CLAUDE.md (lines 491–499)
• Replace the existing block with the snippet above so hex values aren’t duplicated in docs.

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled by default for public repositories
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

Learnt from: samtholiya
PR: cloudposse/atmos#1147
File: internal/exec/validate_schema.go:42-57
Timestamp: 2025-04-11T22:06:46.999Z
Learning: The "ExecuteAtmosValidateSchemaCmd" function in internal/exec/validate_schema.go has been reviewed and confirmed to have acceptable cognitive complexity despite static analysis warnings. The function uses a clean structure with only three if statements for error handling and delegates complex operations to helper methods.

Learnt from: samtholiya
PR: cloudposse/atmos#1068
File: tests/snapshots/TestCLICommands_atmos_terraform_help.stdout.golden:59-64
Timestamp: 2025-02-18T13:13:11.497Z
Learning: For Atmos CLI help text, angle brackets in command examples and flag descriptions should be escaped using HTML entities (e.g., `<component>`) rather than converted to backticks or other markdown formatting.

Learnt from: CR
PR: cloudposse/atmos#0
File: .cursor/rules/atmos-rules.mdc:0-0
Timestamp: 2025-07-01T02:22:25.901Z
Learning: Applies to **/*.go : Wrap errors with context using `fmt.Errorf("context: %w", err)`

Learnt from: osterman
PR: cloudposse/atmos#740
File: cmd/cmd_utils.go:340-359
Timestamp: 2024-10-23T21:36:40.262Z
Learning: In the Go codebase for Atmos, when reviewing functions like `checkAtmosConfig` in `cmd/cmd_utils.go`, avoid suggesting refactoring to return errors instead of calling `os.Exit` if such changes would significantly increase the scope due to the need to update multiple call sites.

Learnt from: CR
PR: cloudposse/atmos#0
File: .cursor/rules/atmos-rules.mdc:0-0
Timestamp: 2025-07-01T02:22:25.901Z
Learning: Applies to **/*.go : Follow Go's error handling idioms

Learnt from: aknysh
PR: cloudposse/atmos#1185
File: internal/exec/yaml_func_store.go:26-26
Timestamp: 2025-04-04T02:03:23.676Z
Learning: The Atmos codebase currently uses `log.Fatal` for error handling in multiple places. The maintainers are aware this isn't an ideal pattern (should only be used in main() or init() functions) and plan to address it comprehensively in a separate PR. CodeRabbit should not flag these issues or push for immediate changes until that refactoring is complete.

Learnt from: CR
PR: cloudposse/atmos#0
File: .cursor/rules/atmos-rules.mdc:0-0
Timestamp: 2025-07-01T02:22:25.901Z
Learning: Applies to **/*.go : Consider using a custom error type for domain-specific errors

Learnt from: milldr
PR: cloudposse/atmos#1229
File: internal/exec/workflow_test.go:0-0
Timestamp: 2025-06-02T14:12:02.710Z
Learning: In the atmos codebase, workflow error handling was refactored to use `PrintErrorMarkdown` followed by returning specific error variables (like `ErrWorkflowNoSteps`, `ErrInvalidFromStep`, `ErrInvalidWorkflowStepType`, `ErrWorkflowStepFailed`) instead of `PrintErrorMarkdownAndExit`. This pattern allows proper error testing without the function terminating the process with `os.Exit`, enabling unit tests to assert on error conditions while maintaining excellent user-facing error formatting.

Learnt from: CR
PR: cloudposse/atmos#0
File: .cursor/rules/atmos-rules.mdc:0-0
Timestamp: 2025-07-01T02:22:25.901Z
Learning: Applies to **/*.go : Provide clear error messages to users

Learnt from: CR
PR: cloudposse/atmos#0
File: .cursor/rules/atmos-rules.mdc:0-0
Timestamp: 2025-07-01T02:22:25.901Z
Learning: All code must pass golangci-lint checks

Learnt from: osterman
PR: cloudposse/atmos#808
File: pkg/config/config.go:478-483
Timestamp: 2024-12-02T21:26:32.337Z
Learning: In the 'atmos' project, when reviewing Go code like `pkg/config/config.go`, avoid suggesting file size checks after downloading remote configs if such checks aren't implemented elsewhere in the codebase.

Learnt from: CR
PR: cloudposse/atmos#0
File: .cursor/rules/atmos-rules.mdc:0-0
Timestamp: 2025-07-01T02:22:25.901Z
Learning: Applies to cmd/*.go : Include troubleshooting hints when appropriate

Learnt from: aknysh
PR: cloudposse/atmos#1363
File: internal/exec/template_utils.go:18-18
Timestamp: 2025-07-05T20:59:02.914Z
Learning: In the Atmos project, gomplate v4 is imported with a blank import (`_ "github.com/hairyhenderson/gomplate/v4"`) alongside v3 imports to resolve AWS SDK version conflicts. V3 uses older AWS SDK versions that conflict with newer AWS modules used by Atmos. A full migration to v4 requires extensive refactoring due to API changes and should be handled in a separate PR.

Learnt from: CR
PR: cloudposse/atmos#0
File: .cursor/rules/atmos-rules.mdc:0-0
Timestamp: 2025-07-01T02:22:25.901Z
Learning: Applies to **/*.go : Follow Go's documentation conventions

Learnt from: Listener430
PR: cloudposse/atmos#844
File: cmd/helmfile.go:37-37
Timestamp: 2024-12-11T18:40:12.808Z
Learning: In the atmos project, `cliConfig` is initialized within the `cmd` package in `root.go` and can be used in other command files.