docs: add Terragrunt migration skill and fix stale PRD statuses - #2878
Open
Erik Osterman (Cloud Posse) (osterman) wants to merge 11 commits into
Open
docs: add Terragrunt migration skill and fix stale PRD statuses#2878Erik Osterman (Cloud Posse) (osterman) wants to merge 11 commits into
Erik Osterman (Cloud Posse) (osterman) wants to merge 11 commits into
Conversation
…tion research Checkpoint before syncing this branch with origin/main — these fixes were made against an older snapshot and will likely need rework once current upstream content is merged in. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
… stale PRD statuses Adds the atmos-migration skill's Terragrunt reference (classic and Stacks patterns, concept mapping, migration workflow), hands-on-validated against a real Terragrunt Stacks example run end to end on the floci/aws emulator. Corrects four PRD status headers that had gone stale relative to shipped code, fixes pre-existing EditorConfig indentation violations the commit hook surfaced in two of those files, and documents the mocks/--use-mocks feature in the website Terragrunt migration guide as the direct equivalent of mock_outputs. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Erik Osterman (Cloud Posse) (osterman)
requested a review
from a team
as a code owner
August 5, 2026 20:58
Contributor
|
Tip Atmos Pro
No affected stacks workflow was detected for this pull request. 
|
Erik Osterman (Cloud Posse) (osterman)
added
the
no-release
Dependency Review✅ No vulnerabilities or license issues found.Scanned FilesNone |
Contributor
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (9)
💤 Files with no reviewable changes (1)
🚧 Files skipped from review as they are similar to previous changes (2)
📝 WalkthroughWalkthroughAdded Terragrunt migration guidance and routing. Updated Terraform mock fallback behavior and provenance filtering. Updated related documentation, snapshots, and PRD implementation statuses. ChangesTerragrunt migration guidance
Terraform mock behavior
Provenance filtering
PRD status documentation
Estimated code review effort: 3 (Moderate) | ~20 minutes Possibly related PRs
Suggested labels: Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@agent-skills/skills/atmos-migration/references/from-terragrunt.md`:
- Around line 323-324: Update the dependency translation guidance in the “Wire
dependency blocks” step so Terragrunt mock_outputs maps to the Atmos mocks
component field and explicitly uses --use-mocks, rather than the // "default"
fallback. Reserve // "default" for real dependencies that have not deployed yet.
- Around line 97-103: Update the `generate:` stack section description to
explicitly list all five inheritance levels, including the
base-component/catalog-default level before `component` and `override`. Use the
established terminology from the generation documentation or changelog while
preserving the existing backend/provider distinction.
In `@docs/prd/custom-hooks.md`:
- Line 3: Update the status statement in the document introduction to replace
the relative “today” wording with a concrete release or absolute date, while
preserving the existing shipped and outstanding feature details.
In `@docs/prd/dag-concurrent-execution.md`:
- Around line 3-5: Reconcile the PRD’s status claims with the implementation:
update the stale `ExecuteTerraformQuery()` description to reflect
scheduler/DAG-aware routing, and revise the Phase 2 checklist around scheduler
wiring and `--max-concurrency` so completed work is marked shipped or removed.
Keep the remaining Phase 4 items explicitly open and ensure the overview and
detailed sections describe the same state.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: 7cb7c56c-6c4a-4d28-b218-c610b3d1a5ac
📒 Files selected for processing (7)
agent-skills/skills/atmos-migration/SKILL.mdagent-skills/skills/atmos-migration/references/from-terragrunt.mddocs/prd/code-generation.mddocs/prd/custom-hooks.mddocs/prd/dag-concurrent-execution.mddocs/prd/import-adapter-registry.mdwebsite/docs/migration/terragrunt.mdx
…entation CI caught two real issues in the new Terragrunt migration reference: - Two examples used the legacy doubled-double-quote YQ escaping (!terraform.state x ".field // ""default""") instead of the clean current syntax (!terraform.state x .field // "default"), which scripts/check- terraform-example-syntax.sh flags outside its designated compatibility fixtures. - The "Migration Workflow" numbered list used 3-space continuation indentation, not a multiple of the repo's 2-space EditorConfig setting. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #2878 +/- ##
=======================================
Coverage 82.76% 82.77%
=======================================
Files 1861 1861
Lines 180478 180479 +1
=======================================
+ Hits 149380 149395 +15
+ Misses 23311 23296 -15
- Partials 7787 7788 +1
Flags with carried forward coverage won't be shown. Click here to find out more.
🚀 New features to boost your workflow:
|
…unt migration guide Reconciles PRD status claims that contradicted themselves (dag-concurrent-execution.md Phase 3 is only partially shipped, not fully; custom-hooks.md's relative "today" date), completes the from-terragrunt.md 5-level merge listing, and fixes a hallucinated `settings.terraform.provider_overrides` key found via hands-on field testing. Also recommends `atmos list affected` over `atmos describe affected` for human-run migration comparisons (table output vs. a wall of YAML), notes both diff committed trees only, and updates the Change Tracking table to the current `dependencies.files`/`folders` syntax instead of the legacy inline `kind: file`/`kind: folder` form. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Actionable comments posted: 5
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@agent-skills/skills/atmos-migration/references/from-terragrunt.md`:
- Around line 325-326: Update step 3 in the dependency-block workflow to map
Terragrunt mock_outputs to the producer component’s mocks field, using
--use-mocks for read-only planning or component description. Remove the //
"default" mapping for mock_outputs, reserving YQ defaults for real dependencies
that are not yet deployed.
- Line 296: Quote each YQ default expression as a single argument in both
affected examples: update
agent-skills/skills/atmos-migration/references/from-terragrunt.md lines 296-296
to quote the .arn default expression, and lines 179-183 to quote the .vpc_id
default expression. Preserve the existing Terraform state references and
fallback values.
In `@docs/prd/dag-concurrent-execution.md`:
- Around line 841-847: Resolve the contradictory `os.Stdout` documentation by
updating the stale status near the terraform plan diff discussion to reflect
that the swap was replaced with stream injection, or revise the Phase 1 shipped
claim if that implementation is not complete. Ensure the PRD consistently
describes only the actual current behavior.
- Around line 3-5: Clarify the cross-type dependency status in the document’s
overview and the Phase 3 status sections: distinguish the shipped
`dependencies.components.kind` syntax from the still-open legacy
`settings.depends_on` support, or update the status consistently if both are
shipped. Align the references near `dependencies.components`, the Phase 3
multi-type-DAG item, and the PR `#2193` note.
In `@website/docs/migration/terragrunt.mdx`:
- Around line 857-858: Update the documented atmos list affected example and its
adjacent comment so they agree: pass --base main to explicitly compare against
main, preserving the stated comparison behavior.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: 178b6585-1d19-44de-8438-23d192668df9
📒 Files selected for processing (4)
agent-skills/skills/atmos-migration/references/from-terragrunt.mddocs/prd/custom-hooks.mddocs/prd/dag-concurrent-execution.mdwebsite/docs/migration/terragrunt.mdx
🚧 Files skipped from review as they are similar to previous changes (1)
- docs/prd/custom-hooks.md
…tion guide Step 3 of the migration workflow still mapped mock_outputs to the YQ // "default" pattern, contradicting the mocks:/--use-mocks mapping documented a few paragraphs earlier. Quotes the YQ default expressions for consistency with atmos-yaml-functions/SKILL.md and atmos-components/SKILL.md. dag-concurrent-execution.md had two more self-contradictions: the Subprocess Execution section still described the os.Stdout race that Phase 1 already fixed (terraform_plan_diff.go now captures via bytes.Buffer), and the Resolved Questions section claimed cross-type dependency syntax was "solved by PR #2193" — traced the code and found pkg/scheduler/adapters/terraform.go explicitly skips any dependency whose kind isn't "terraform", so the kind field is schema-parseable but not yet consumed by the scheduler; corrected to match the already-accurate Phase 3 status. terragrunt.mdx's list-affected example claimed to compare against main by default without passing --ref; list affected has no --base flag (unlike describe affected), so made the comparison explicit with --ref main instead. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
agent-skills/skills/atmos-migration/references/from-terragrunt.md (1)
331-334: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick winAdd the explicit base reference to
list affected.The migration workflow must document
atmos list affected --ref main. The current command omits--ref main, so the required comparison target is not explicit.Suggested fix
- `atmos list affected` (human-readable table; commit your change first — it diffs committed trees, not + `atmos list affected --ref main` (human-readable table; commit your change first — it diffs committed trees, not🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@agent-skills/skills/atmos-migration/references/from-terragrunt.md` around lines 331 - 334, Update the migration workflow step referencing `atmos list affected` to include the explicit `--ref main` option, while preserving the existing guidance about committing changes and using `atmos describe affected` for scripted or CI output.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Outside diff comments:
In `@agent-skills/skills/atmos-migration/references/from-terragrunt.md`:
- Around line 331-334: Update the migration workflow step referencing `atmos
list affected` to include the explicit `--ref main` option, while preserving the
existing guidance about committing changes and using `atmos describe affected`
for scripted or CI output.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: 50007ed0-acdf-464e-8f28-b38dda05438b
📒 Files selected for processing (3)
agent-skills/skills/atmos-migration/references/from-terragrunt.mddocs/prd/dag-concurrent-execution.mdwebsite/docs/migration/terragrunt.mdx
🚧 Files skipped from review as they are similar to previous changes (1)
- website/docs/migration/terragrunt.mdx
…lt parity A field test of --use-mocks found `describe component` silently rendering empty output whenever a component's provenance path wasn't matched due to an unnormalized lookup, a mock-output error that mislabeled the output name as a component name, and a YQ `//` default that only rescued a missing key inside a declared `mocks` map, not a component with no `mocks` section at all -- inconsistent with how `//` already rescues real state. Also cross-references the mocks:/--use-mocks feature from the docs pages and skill most likely to be read first. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (2)
internal/exec/terraform_mocks_test.go (2)
85-85: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winBuild the fixture path with
filepath.Join.At Line 85, the new test hard-codes a slash-separated relative path. Use
filepath.Joinand importpath/filepathto keep the test portable.Proposed fix.
+ "path/filepath" + - sandbox, err := testhelpers.SetupSandbox(t, "../../tests/fixtures/scenarios/terraform-component-mocks") + sandbox, err := testhelpers.SetupSandbox(t, filepath.Join("..", "..", "tests", "fixtures", "scenarios", "terraform-component-mocks"))As per coding guidelines, tests must use
filepath.Joinfor paths.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@internal/exec/terraform_mocks_test.go` at line 85, Update the test setup path in the relevant test function to use filepath.Join with each path component, and add the path/filepath import. Preserve the existing fixture location and pass the joined path to testhelpers.SetupSandbox.Source: Coding guidelines
97-99: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick winCover the
!terraform.outputfallback path.At Line 97, the regression test calls only
processTagTerraformState. Add the equivalentprocessTagTerraformOutputcase for a component withoutmocks. The changed resolver and documentation promise the same//behavior for both tags.As per coding guidelines, prefer behavior-focused tests with comprehensive coverage.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@internal/exec/terraform_mocks_test.go` around lines 97 - 99, Add a behavior-focused test alongside the existing processTagTerraformState fallback case that invokes processTagTerraformOutput for a component without mocks, using the same missing-value and // fallback scenario. Assert no error and the expected fallback value to cover the promised equivalent behavior for both tags.Source: Coding guidelines
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@errors/errors.go`:
- Line 218: Update the ErrTerraformMockOutputNotDeclared sentinel message to
remove its trailing period, preserving the existing wording so wrapped errors in
terraform mock handling produce clear punctuation.
In `@pkg/provenance/data_transform_test.go`:
- Around line 77-105: Extend TestFilterEmptySectionsKeepsComponentSections to
record provenance for the array-element path
components.terraform.app.vars[0].foo, then verify that the vars section remains
after filterEmptySections. Preserve the existing dot-nested, backend, and
metadata assertions while adding coverage for the array-element provenance
branch.
In `@pkg/provenance/tree_renderer.go`:
- Around line 28-30: Update the inline comments for defaultSeparatorWidth,
commentSpaceNeeded, and maxLineLength so each ends with a period, without
changing the constants or their values.
---
Nitpick comments:
In `@internal/exec/terraform_mocks_test.go`:
- Line 85: Update the test setup path in the relevant test function to use
filepath.Join with each path component, and add the path/filepath import.
Preserve the existing fixture location and pass the joined path to
testhelpers.SetupSandbox.
- Around line 97-99: Add a behavior-focused test alongside the existing
processTagTerraformState fallback case that invokes processTagTerraformOutput
for a component without mocks, using the same missing-value and // fallback
scenario. Assert no error and the expected fallback value to cover the promised
equivalent behavior for both tags.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: 6525373d-ff2a-445d-b545-32e9eb214373
📒 Files selected for processing (12)
agent-skills/skills/atmos-yaml-functions/SKILL.mderrors/errors.gointernal/exec/terraform_mocks.gointernal/exec/terraform_mocks_test.gopkg/provenance/data_transform.gopkg/provenance/data_transform_test.gopkg/provenance/tree_renderer.gowebsite/blog/2026-07-15-terraform-component-mocks.mdxwebsite/docs/components/terraform/stack-config.mdxwebsite/docs/functions/yaml/terraform.output.mdxwebsite/docs/functions/yaml/terraform.state.mdxwebsite/docs/migration/terragrunt.mdx
🚧 Files skipped from review as they are similar to previous changes (1)
- website/docs/migration/terragrunt.mdx
| // --use-mocks errors. | ||
| ErrTerraformComponentMocksNotDeclared = errors.New("terraform component does not declare `mocks` required by --use-mocks") | ||
| ErrTerraformMockOutputNotDeclared = errors.New("mocked terraform output is not declared for component") | ||
| ErrTerraformMockOutputNotDeclared = errors.New("mocked terraform output is not declared") |
Contributor
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Remove the trailing period from ErrTerraformMockOutputNotDeclared.
At Line 218, the sentinel ends with a period. internal/exec/terraform_mocks.go appends ": ..." when it wraps this error, so users receive mocked terraform output is not declared.: .... Remove the period from the sentinel to preserve clear error output.
Proposed fix.
- ErrTerraformMockOutputNotDeclared = errors.New("mocked terraform output is not declared.")
+ ErrTerraformMockOutputNotDeclared = errors.New("mocked terraform output is not declared")As per coding guidelines, provide clear error messages to users.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| ErrTerraformMockOutputNotDeclared = errors.New("mocked terraform output is not declared") | |
| ErrTerraformMockOutputNotDeclared = errors.New("mocked terraform output is not declared") |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@errors/errors.go` at line 218, Update the ErrTerraformMockOutputNotDeclared
sentinel message to remove its trailing period, preserving the existing wording
so wrapped errors in terraform mock handling produce clear punctuation.
Erik Osterman (Cloud Posse) (osterman)
temporarily deployed
to
screengrabs
August 6, 2026 22:59 — with 
GitHub Actions
Inactive
GitHub Actions
Inactive
… provenance fix The filterEmptySections fix (6c22503) corrected describe_component to stop silently dropping real sections (backend, metadata, env, overrides) that lack a stack-root section of the same name. CI caught the resulting golden snapshot drift on both linux and macos; regenerated via `-regenerate-snapshots` per CLAUDE.md, verified the diffs only add the previously-hidden, now-correct content. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Erik Osterman (Cloud Posse) (osterman)
temporarily deployed
to
screengrabs
August 6, 2026 23:56 — with
GitHub Actions
Inactive
GitHub Actions
Inactive
Add periods to the rendering-constant comments (godot's inline-comment scope missed these, but CLAUDE.md's comment convention still applies), and cover the array-element provenance path (vars[0].foo) alongside the already-tested dot-nested form. The trailing-period finding on ErrTerraformMockOutputNotDeclared was already resolved by an earlier commit in this PR — no change needed there. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Erik Osterman (Cloud Posse) (osterman)
temporarily deployed
to
screengrabs
August 7, 2026 00:02 — with
GitHub Actions
Inactive
GitHub Actions
Inactive
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
what
agent-skills/skills/atmos-migration/references/from-terragrunt.md: concept mapping (include,dependency/mock_outputs, source pinning,before_hook) and a migration workflow for both classic Terragrunt and Terragrunt Stacks, hands-on-validated by migrating a real Terragrunt Stacks example (Lambda + DynamoDB + IAM role) end to end against thefloci/awsemulator.agent-skills/skills/atmos-migration/SKILL.md(routing table, frontmatter, and the previously-stale "not covered by this skill" line).dag-concurrent-execution.md,custom-hooks.md,code-generation.md,import-adapter-registry.md) that had gone stale relative to already-shipped code, and fixes pre-existing EditorConfig indentation violations the commit hook surfaced in two of those files.mocks/--use-mockscomponent feature inwebsite/docs/migration/terragrunt.mdxas the direct equivalent of Terragrunt'smock_outputs, matching the doc's existing tabbed format, plus a corresponding migration checklist item.why
atmos-migrationskill previously routed Terragrunt users to an external doc with no agent-actionable guidance ("not covered by this skill"); this fills that gap with a validated, working recipe.mocks/--use-mocksfeature is a closer match to Terragrunt'smock_outputs_allowed_terraform_commandssemantics (explicit, command-scoped, fail-closed) than the YAML-function default-value pattern previously documented, and the website guide had no mention of it at all.references
Summary by CodeRabbit
New Features
--use-mocks, while preserving YQ fallback behavior.Documentation