engsys 1.0.0

package/stacks/domain/mobile-growth/skills/google-play-growth/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: google-play-growth
+description: "Understand Google Play growth and Google Ads app acquisition. Use when evaluating Android app growth strategy, Google Ads App campaigns, Google Play store listing optimization, store listing experiments, custom store listings, web-to-app flows, Android app-growth cost planning such as CPI, CPA, tCPA, tROAS, and the measurement realities around Google Ads, GAID, Firebase, and modern attribution."
+---
+
+# Google Play Growth
+
+Use this skill when reasoning about Android app growth across **Google Ads App
+Campaigns** and **Google Play Console** growth surfaces.
+
+## When to Use This Skill
+
+- The user asks about Android app acquisition or Google Play growth.
+- You need to explain Google Ads App Campaigns or bidding strategies.
+- You need to reason about store listing experiments, custom store listings, or
+  Google Play conversion improvements.
+- You need Android CPI / CPA / tCPA / tROAS guidance.
+- You need to refresh official docs for Google Ads or Play Console growth tools.
+
+## What Exists in the Google Play Growth Stack
+
+As of 2025-2026, the practical Google ecosystem for app growth is:
+
+- **Google Ads App Campaigns for installs**.
+- **Google Ads App Campaigns for engagement / re-engagement**.
+- **Pre-registration campaigns** for Android launches.
+- **Google Play search, browse, charts, editorial, and related-app discovery**.
+- **Store Listing Experiments** for native A/B testing.
+- **Custom Store Listings** for keyword, audience, or regional variants.
+- **Promotional content and in-app event merchandising** inside Google Play.
+- **Firebase + Google Ads measurement** for post-install signals and value.
+- **Web-to-App Connect** and deep links to reduce mobile web friction.
+
+## How Google Ads App Campaigns Work
+
+### Asset-Based Automation
+
+- App Campaigns are not traditional keyword-managed search campaigns.
+- You provide **text, images, videos, and app metadata**.
+- Google automatically mixes assets and serves them across:
+  - Search,
+  - Google Play,
+  - YouTube,
+  - Display,
+  - Discover,
+  - other eligible Google inventory.
+
+This means your job is to set the **right objective**, provide the **right
+assets**, and judge success by **business outcome**, not by trying to manually
+micromanage every placement.
+
+### Campaign Types
+
+- **Install campaigns**: drive new installs.
+- **Action-optimized install campaigns**: still acquire new users, but bias
+  toward users likely to complete an in-app action.
+- **Engagement campaigns**: re-engage existing users to complete valuable
+  actions.
+- **Pre-registration campaigns**: build launch demand for Android apps before
+  release.
+
+### Bidding Modes That Matter
+
+- **tCPI**: target cost per install.
+- **tCPA**: target cost per action.
+- **tROAS**: target return on ad spend; useful when you have revenue/value
+  tracking.
+- **Maximize Conversions / Conversion Value**: useful when you have enough data
+  and want the system to optimize around volume or value.
+
+### Practical Budget Rules of Thumb
+
+Use these as operating heuristics, not as hard platform laws unless Google says
+otherwise in current documentation.
+
+- Install campaigns need enough daily budget to generate meaningful conversion
+  volume.
+- Action-based campaigns need even more room because the optimized event is
+  deeper and rarer.
+- If the campaign is underfunded relative to the target bid, the algorithm may
+  never leave learning cleanly.
+
+## How Google Play Optimization Works
+
+### Metadata
+
+- **Title**: highest-weight metadata field.
+- **Short description**: crucial both for ranking and for above-the-fold
+  conversion.
+- **Long description**: lower weight than title and short description, but still
+  matters for semantic relevance.
+- **Category and tags**: influence where the app is eligible to appear.
+
+### Conversion Assets
+
+- **Icon**: your most repeated brand signal.
+- **Feature graphic**: critical for conversion on Play surfaces.
+- **Screenshots**: major conversion lever.
+- **Preview video**: especially useful when the product benefits from visual
+  explanation.
+
+### Native Growth Tools
+
+- **Store Listing Experiments**: A/B test listing assets in Play Console.
+- **Custom Store Listings**: tailor listings to different geographies, queries,
+  or acquisition contexts.
+- **Promotional content / events**: keep the listing active and relevant.
+- **Acquisition reporting**: inspect store visitors, acquisitions, conversion
+  rate, and source mix.
+
+## Cost Model and Planning Concepts
+
+### Core Buying Logic
+
+- Google Ads is an **auction**.
+- App Campaigns rely on machine learning, not manual keyword-by-keyword control.
+- Your actual economics are shaped by:
+  - bid target,
+  - budget,
+  - asset quality,
+  - optimization event quality,
+  - category competition,
+  - region,
+  - downstream monetization.
+
+### Practical Metrics
+
+- **CPI**: install cost; useful, but not enough by itself.
+- **CPA**: action cost; better when the app monetizes post-install.
+- **tCPA**: your target action cost.
+- **ROAS / tROAS**: required once revenue quality matters.
+- **CVR**: store-listing or post-click conversion rate.
+- **Retention and payer quality**: what stops cheap installs from fooling you.
+
+### Directional Cost Expectations
+
+- Android installs are usually cheaper than iOS installs.
+- Install-only campaigns can look efficient while bringing in poor users.
+- Higher-value bidding targets usually cost more per acquisition but can improve
+  payback and gross profit quality.
+
+Use [references/benchmark-notes.md](references/benchmark-notes.md) for safe
+benchmark framing.
+
+## Measurement and Attribution Reality
+
+- Android remains more measurable than iOS, but you should still plan for more
+  modeled and privacy-constrained reporting over time.
+- Use **Firebase** and first-party event design well; poor event design ruins
+  App Campaign optimization.
+- Use **Web-to-App Connect** and correctly configured deep links when the user
+  journey starts on web.
+- Treat Google Ads attribution as useful, not infallible.
+- Validate big spend decisions with cohort performance and, when possible,
+  lift-style testing rather than trusting platform-reported success blindly.
+
+## Operational Advice
+
+- Start with the business goal, not the ad format.
+- If monetization depends on a deeper in-app event, optimize toward that event
+  as soon as data volume supports it.
+- Separate Android from iOS planning; they do not behave the same economically.
+- Keep creative volume high enough for the system to actually learn.
+- Treat Play listing optimization and paid growth as one loop, not two teams
+  pretending not to affect each other.
+- Use Store Listing Experiments continuously; do not guess at conversion assets.
+- Reassess bids and budgets after the learning phase, not every day during it.
+
+## Common Mistakes
+
+- Optimizing for installs when the real goal is purchases or subscriptions.
+- Underfunding campaigns and then blaming the channel.
+- Uploading too few assets for the algorithm to test.
+- Treating Play Console conversion rate as a design vanity metric instead of a
+  ranking input.
+- Mixing brand demand and non-brand demand without understanding the difference.
+- Taking Google recommendations at face value without checking incremental value
+  or payback.
+- Ignoring web-to-app deep links and then wondering why mobile web converts
+  poorly.
+
+## Refresh Workflow
+
+When this skill may be stale:
+
+1. Read [references/official-links.md](references/official-links.md).
+2. Re-check Google Ads help pages for App Campaign setup, bidding, and app deep
+   link behavior.
+3. Re-check Play Console docs for experiments, custom store listings, and
+   acquisition reporting.
+4. Re-check Firebase guidance if event or value measurement is in scope.
+5. Use third-party benchmarks only as directional priors.
+
+## References
+
+- [Official links](references/official-links.md)
+- [Benchmark notes](references/benchmark-notes.md)

package/stacks/domain/mobile-growth/skills/google-play-growth/references/benchmark-notes.md

@@ -0,0 +1,47 @@
+# Google Play Growth Benchmark Notes
+
+Google does not publish universally applicable CPI, CPA, or ROAS benchmarks for
+your category. Use benchmark sources to sanity-check plans, not to pretend you
+have certainty.
+
+## Practical Benchmark Heuristics
+
+- Android installs are usually cheaper than iOS installs.
+- Install-only campaigns often produce cheaper traffic than action-optimized
+  campaigns, but that traffic can be materially worse.
+- Competitive categories, high-income geographies, and purchase-heavy apps cost
+  more.
+- Search-led intent usually performs better than broad, entertainment-style
+  reach placements.
+
+## Common Directional Ranges Seen in 2025-2026 Reporting
+
+- Global Android CPI is often reported in the low-single-dollar range.
+- iOS CPI is often reported at a multiple of Android CPI.
+- Search CPCs across Google properties rose year over year in many 2025-2026
+  benchmark reports.
+- Smart bidding usually outperforms manual control once enough conversion data
+  exists.
+
+Use those as priors only.
+
+## Recommended Third-Party Refresh Sources
+
+- Business of Apps: https://www.businessofapps.com/
+- Adjust benchmark resources: https://www.adjust.com/resources/
+- AppsFlyer performance / benchmark resources: https://www.appsflyer.com/resources/
+- App Radar Google Play optimization guides: https://appradar.com/academy/google-play-optimization
+- WordStream Google Ads benchmarks: https://www.wordstream.com/blog
+
+## How to Use Benchmarks Safely
+
+- Build **base / upside / downside** models for Android separately from iOS.
+- Benchmark against your own:
+  - store conversion rate,
+  - D1 / D7 / D30 retention,
+  - payer conversion,
+  - trial-to-paid rate,
+  - ARPU / LTV,
+  - CAC payback.
+- If a benchmark makes your model look amazing, pressure-test harder rather than
+  celebrating earlier.

package/stacks/domain/mobile-growth/skills/google-play-growth/references/official-links.md

@@ -0,0 +1,45 @@
+# Google Play Growth Official Links
+
+Use these first when refreshing the skill.
+
+## Google Ads App Campaigns
+
+- App campaigns overview: https://support.google.com/google-ads/answer/6247380?hl=en
+- Create App campaigns: https://support.google.com/google-ads/answer/6167162?hl=en
+- App campaign asset guidance: https://support.google.com/google-ads/answer/6167158?hl=en
+- App campaign bidding strategy guidance: https://support.google.com/google-ads/answer/12073727?hl=en
+- App engagement campaigns: https://support.google.com/google-ads/answer/14104492?hl=en
+- App pre-registration campaigns: https://support.google.com/google-ads/answer/9441180?hl=en
+- Pre-registration campaign details: https://support.google.com/google-ads/answer/9441344?hl=en
+
+## Web-to-App and Deep Links
+
+- Web-to-App Connect / app deep links: https://support.google.com/google-ads/answer/10024200?hl=en
+- App deep link requirements: https://support.google.com/google-ads/answer/16413616?hl=en
+
+## Google Play Console Growth Surfaces
+
+- Acquisition reporting: https://play.google.com/console/about/acquisitionreporting/
+- Acquisition report help: https://support.google.com/googleplay/android-developer/answer/9859173?hl=en
+- Store Listing Experiments: https://play.google.com/console/about/store-listing-experiments/
+
+## APIs and Developer Docs
+
+- Google Ads API App campaigns overview: https://developers.google.com/google-ads/api/docs/app-campaigns/overview
+- Google Ads API create App campaign: https://developers.google.com/google-ads/api/docs/app-campaigns/create-campaign
+- Firebase docs: https://firebase.google.com/docs
+- Firebase iOS on-device ads measurement tutorial: https://firebase.google.com/docs/tutorials/ads-ios-on-device-measurement/step-3
+
+## Product and Ecosystem Updates
+
+- Google Ads & Commerce blog: https://blog.google/products/ads-commerce/
+- Android Developers blog / Google Play growth updates: https://developer.android.com/blog
+- Think with Google / business strategy: https://business.google.com/think/
+
+## Notes
+
+- Prefer Google support and developer docs over growth blogs when checking
+  feature availability or policy behavior.
+- Re-check bidding docs before using old tCPI / tCPA rules of thumb.
+- Re-check privacy and measurement docs before assuming anything about future
+  Android identifier policy.

package/stacks/iac/bicep/claude.fragment.md

@@ -0,0 +1,14 @@
+## IaC stack
+
+- **Active IaC tool: Bicep.** Infrastructure changes go through Bicep; Aaron loads the
+  `iac-bicep` skill pack.
+- **Workflow gate:** `bicep build` (syntax) → `az deployment group validate` →
+  `what-if` (review) → deploy. `bicep build` alone is not the gate — validate + what-if
+  are. Fix failures locally; don't let CI discover them.
+- Run the `azure-deployment-preflight` skill before deploying for stale-deployment
+  cleanup, globally-unique naming, and SKU/tier checks.
+- Read-only CLI (`bicep build`, `validate`, `what-if`, `azd provision --preview`) is
+  allowed; `deployment create` / `azd up` are gated.
+
+<!-- naturalize: confirm the infrastructure/ layout, resource group(s), and per-env
+.bicepparam files. -->

package/stacks/iac/bicep/settings.fragment.json

@@ -0,0 +1,20 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(bicep build:*)",
+      "Bash(az bicep build:*)",
+      "Bash(bicep --version:*)",
+      "Bash(az deployment group validate:*)",
+      "Bash(az deployment group what-if:*)",
+      "Bash(az deployment sub what-if:*)",
+      "Bash(az deployment group list:*)",
+      "Bash(azd provision --preview:*)"
+    ],
+    "deny": [
+      "Bash(az deployment group create:*)",
+      "Bash(az deployment sub create:*)",
+      "Bash(azd up:*)"
+    ]
+  },
+  "mcpServers": {}
+}

package/stacks/iac/bicep/skills/iac-bicep/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: iac-bicep
+description: Bicep / ARM discipline for any project where Bicep is the active IaC tool — modules/environments/main.bicep layout, parameter files (.bicepparam), the az validate → what-if flow, deployment scopes, and the hard-won Azure Bicep gotchas (globally-unique names, ACR SKU, PgBouncer Burstable limit, alert module location, KQL interpolation, metric names). Activate when working on *.bicep / *.bicepparam files, az deployment / azd provision, ARM deployment failures, or diagnosing Bicep validation and drift.
+---
+
+# Bicep / ARM Discipline
+
+The operational discipline for Bicep as the active IaC tool (Azure). Pairs with the
+`cloud-architecture-azure` pack (service-level detail) and the
+`azure-deployment-preflight` skill (the pre-deploy gate). Project file layout and
+resource-group/subscription facts come from `CLAUDE.md`.
+
+## Core stance
+
+- **Infrastructure is software.** If it only works once, it doesn't work. "Just deploy it
+  again" is not a strategy — understand *why* it failed.
+- **`bicep build` only checks syntax.** It does NOT catch invalid property combinations,
+  metric names, KQL scope, secret-ref mismatches, or naming collisions. The real gate is
+  `az deployment group validate` + `what-if` (see `azure-deployment-preflight`).
+- **Batch your fixes.** Each push triggers a long CI run — read the whole failing module,
+  fix every issue, push once. One run per problem cluster, not one per error message.
+
+## Project layout
+
+A conventional, recreatable structure (confirm exact paths in `CLAUDE.md`):
+
+```
+infrastructure/
+  main.bicep                 # orchestration: wires modules together, declares params
+  modules/                   # reusable modules, one concern each (db, acr, alerts, …)
+    <concern>.bicep
+  environments/
+    dev.bicepparam           # per-env parameter files (preferred over .parameters.json)
+    staging.bicepparam
+    prod.bicepparam
+  scripts/                   # helper scripts (e.g. seed-keyvault.sh)
+```
+
+- **`main.bicep`** is the orchestrator: declare `param`s, set defaults, instantiate
+  modules with explicit dependencies, expose `output`s.
+- **Modules** group related resources with a narrow, typed interface (`param` +
+  `@description`). Don't wrap a single resource unless it earns reuse.
+- **`.bicepparam`** files (typed, support expressions and `getSecret()`) are preferred
+  over JSON parameter files. Keep one per environment; never hard-code per-env values in
+  `main.bicep`.
+
+## Deployment scopes
+
+The `targetScope` declaration picks the deploy/validate command:
+
+| `targetScope` | command family |
+| --- | --- |
+| `resourceGroup` (default) | `az deployment group ...` |
+| `subscription` | `az deployment sub ... --location <loc>` |
+| `managementGroup` | `az deployment mg ... --management-group-id <id> --location <loc>` |
+| `tenant` | `az deployment tenant ... --location <loc>` |
+
+## The validate → what-if flow (run before every deploy)
+
+```bash
+cd infrastructure
+bicep build main.bicep --stdout            # 1. syntax only
+
+az deployment group validate \             # 2. real deploy-time validation
+  --resource-group <rg> \
+  --template-file main.bicep \
+  --parameters environments/<env>.bicepparam \
+  --parameters postgresAdminPassword="dummy" --parameters postgresAdminUsername="dummy"
+
+az deployment group what-if \              # 3. the preview (creates/modifies/DELETES)
+  --resource-group <rg> \
+  --template-file main.bicep \
+  --parameters environments/<env>.bicepparam \
+  --validation-level Provider              # fall back to ProviderNoRbac on RBAC errors
+```
+
+**If it fails locally, fix it locally.** Don't push and let CI discover it. Review the
+what-if for **deletes/replacements of stateful resources** (PostgreSQL, Key Vault,
+storage). See `azure-deployment-preflight` for stale-deployment cleanup and the full gate.
+
+## Secrets
+
+- No secrets in templates or param files. Reference **Key Vault** from `.bicepparam` via
+  `getSecret()` and from app resources as secret references.
+- Prefer **managed identities** for resource-to-resource auth over connection strings.
+
+## Hard-won Bicep gotchas (don't rediscover the expensive way)
+
+- **Globally-unique names** (Key Vault, storage, ACR, Redis, Front Door) collide or are
+  soft-deleted from prior attempts. Parameterize the name (`param keyVaultName` etc.) and
+  override in `*.bicepparam` with a short unique suffix — don't hard-code the bare default.
+  If a helper script (Key Vault seeder) defaults the name internally, **pass the override
+  explicitly** and ensure every workflow step uses the same resolved name.
+- **ACR SKU:** `Basic` may be unavailable on some subscriptions; `Standard` works but
+  `retentionPolicy` requires `Premium` — remove it from dev/staging. If a failed deploy
+  left a broken ACR, create it manually and let Bicep treat it as no-change.
+- **PgBouncer not on Burstable:** Burstable (`Standard_B*`) PostgreSQL can't run PgBouncer
+  (needs GeneralPurpose+). Guard with `= if (currentSku.tier != 'Burstable') { ... }`.
+- **Alert module location:** `metricAlerts` → `location: 'global'`; `scheduledQueryRules`
+  → real region (NOT `global`), and they must scope to the **Log Analytics workspace ID**,
+  not the App Insights ID (the `AppRequests` table lives in the workspace).
+- **KQL in verbatim strings doesn't interpolate:** `${vars}` inside `'''...'''` are NOT
+  substituted — build the query with string-concatenation variables.
+- **Metric names:** PostgreSQL Flexible Server uses `active_connections`, not
+  `connection_percent` (that's Azure SQL).
+
+## Drift & troubleshooting
+
+- ARM tracks deployments by name; a **failed sub-deployment blocks re-deploy**
+  (`DeploymentActive`) even while `Failed` — clean it up (see preflight Step 4).
+- Bicep/ARM is declarative-incremental by default (Complete mode deletes anything not in
+  the template — use with care). What-if before every deploy surfaces out-of-band drift.
+- No click-ops in production; manual changes create snowflakes that the next deploy fights.

package/stacks/iac/cdk/claude.fragment.md

@@ -0,0 +1,14 @@
+## IaC stack
+
+- **Active IaC tool: AWS CDK.** Infrastructure changes go through CDK (synthesizes
+  CloudFormation); Aaron loads the `iac-cdk` skill pack.
+- **Workflow gate:** `cdk synth` → `cdk diff` (review resource + IAM changes) →
+  `cdk deploy`. Never deploy without reading the diff; review security/replacement
+  deltas deliberately.
+- Run the `aws-deployment-preflight` skill before deploying for stale-stack cleanup
+  (`ROLLBACK_COMPLETE`), globally-unique naming (S3/ECR), and quota checks.
+- Read-only CLI (`cdk synth`, `cdk diff`, `cdk list`) is allowed; `cdk deploy` /
+  `cdk destroy` are gated.
+
+<!-- naturalize: confirm the CDK app entry (bin/), stack separation, target account +
+region, and whether the account is bootstrapped. -->

package/stacks/iac/cdk/settings.fragment.json

@@ -0,0 +1,23 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(cdk synth:*)",
+      "Bash(cdk diff:*)",
+      "Bash(cdk list:*)",
+      "Bash(cdk ls:*)",
+      "Bash(cdk doctor:*)",
+      "Bash(cdk context:*)",
+      "Bash(npx cdk synth:*)",
+      "Bash(npx cdk diff:*)",
+      "Bash(npx cdk list:*)"
+    ],
+    "deny": [
+      "Bash(cdk deploy:*)",
+      "Bash(cdk destroy:*)",
+      "Bash(cdk bootstrap:*)",
+      "Bash(npx cdk deploy:*)",
+      "Bash(npx cdk destroy:*)"
+    ]
+  },
+  "mcpServers": {}
+}

package/stacks/iac/cdk/skills/iac-cdk/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: iac-cdk
+description: AWS CDK discipline for any project where CDK is the active IaC tool — app/stack structure, constructs (L1/L2/L3), synth/diff/deploy flow, stack separation, context and environment config, asset bundling, and bootstrapping. Activate when working on CDK code (bin/ + lib/ TypeScript or app.py), cdk synth/diff/deploy, construct design, or diagnosing CDK/CloudFormation deploy failures.
+---
+
+# AWS CDK Discipline
+
+The operational discipline for AWS CDK as the active IaC tool. CDK synthesizes
+CloudFormation, so it inherits CloudFormation's behavior. Pairs with the
+`cloud-architecture-aws` pack (service-level detail) and the `aws-deployment-preflight`
+skill (the pre-deploy gate). Project file layout and account/region facts come from
+`CLAUDE.md`.
+
+## Core stance
+
+- **Infrastructure is software** — and CDK makes that literal: it's real TypeScript/
+  Python. Apply the same discipline (types, tests, no copy-paste, narrow interfaces) you'd
+  apply to app code. Resist the temptation to be "clever" in synth-time logic.
+- **CDK is a CloudFormation generator.** What deploys is the synthesized template. When in
+  doubt, read `cdk synth` output — the abstraction is convenient, not magic.
+- **`cdk diff` is the contract.** Never `deploy` without reading the diff. It shows
+  resource changes *and* IAM/security changes (the `--require-approval` gate) — review
+  security deltas deliberately, never rubber-stamp.
+
+## App & stack structure
+
+```
+bin/<app>.ts        # the App: instantiates stacks, sets env (account/region)
+lib/
+  <x>-stack.ts       # one stack per deployment unit / lifecycle boundary
+  constructs/        # reusable L3 constructs (your own abstractions)
+cdk.json             # app entry + context
+```
+
+- **Separate stacks by lifecycle and blast radius** — e.g. network / data / compute /
+  edge / security. A stateful stack (databases, buckets) should be independently
+  deployable from churny app stacks so a compute redeploy can't threaten data.
+- Stacks have a **500-resource CloudFormation limit** — split before you hit it. Nested
+  stacks help but complicate diffs; prefer multiple top-level stacks with cross-stack
+  references via `Stack` props (passing constructs) over brittle string exports/imports.
+- **Set `env` explicitly** (account + region) on stacks — environment-agnostic stacks
+  silently use ambient credentials and can deploy to the wrong account.
+
+## Constructs (L1 / L2 / L3)
+
+- **L1 (`Cfn*`)** — raw CloudFormation, 1:1 with resources. Escape hatch for properties
+  L2 doesn't expose yet (`addPropertyOverride`). Verbose, no defaults.
+- **L2** — curated constructs with sane defaults, IAM grants (`grantRead`, etc.), and
+  helper methods. **The default choice** — prefer them; they encode best practice.
+- **L3 (patterns / your own)** — opinionated multi-resource compositions. Write your own
+  for genuinely-repeated patterns; don't over-abstract a one-off.
+- Use the **`grant*` methods** for IAM rather than hand-writing policies — least-privilege
+  by construction, and they wire the right principal.
+
+## The synth → diff → deploy flow
+
+```bash
+cdk synth                 # generate the template; fails on construct/TS errors first
+cdk diff                  # the what-if: resource + IAM changes vs the deployed stack
+cdk deploy <stack>        # apply (CI: behind approval for prod)
+```
+
+- **Bootstrap once per account+region:** `cdk bootstrap` creates the CDKToolkit stack
+  (asset bucket, ECR repo, deploy roles). A missing bootstrap is a common first-deploy
+  failure.
+- **Review the diff for replacements** — a property change that forces a replacement on a
+  stateful resource (RDS, DynamoDB, S3) is a data-loss event. Use `RemovalPolicy.RETAIN`
+  on precious resources; know that RETAIN-ed resources then block stack deletion until
+  cleared manually (see preflight).
+- Deploy stacks in dependency order (CDK handles this within one `deploy '*'`, but explicit
+  ordering in CI is clearer).
+
+## Context & configuration
+
+- **`cdk.json` context** + `cdk.context.json` (cached lookups like AZs, AMIs, VPCs).
+  Cached context can go stale — `cdk context --clear` to refresh. Commit `cdk.context.json`
+  so synth is deterministic across machines/CI.
+- Pass per-environment config via **stack props / construct parameters**, not via
+  scattered `tryGetContext` reads. Keep env selection explicit (e.g. `-c env=prod` →
+  typed config object), not implicit.
+- Pin the CDK library + construct-library versions; CDK moves fast and minor versions
+  change synthesized output.
+
+## Assets & bundling
+
+- Lambda/container assets are bundled and uploaded to the bootstrap bucket/ECR on deploy.
+  Keep bundles small (esbuild for Node, layers/`--platform` for native deps) — bundle size
+  drives cold start (see `cloud-architecture-aws`). Docker is required for some bundling
+  modes.
+
+## Troubleshooting
+
+- **`ROLLBACK_COMPLETE`** stack can't be updated — delete and recreate (`cdk destroy` then
+  deploy). Read the **first** failed CloudFormation event, not the rollback cascade.
+- **Drift:** out-of-band console changes diverge from the template; `cdk diff` won't show
+  console drift directly — use CloudFormation drift detection. No click-ops in prod.
+- **Cross-stack deadlock:** a hard export that another stack imports can't be changed/
+  deleted until the consumer stops importing it — refactor cross-stack refs deliberately.
+
+## Preflight
+
+Before deploying, run the `aws-deployment-preflight` skill — it covers
+`cdk synth`/`cdk diff` validation, stale/failed-stack cleanup (`ROLLBACK_COMPLETE`),
+globally-unique naming (S3/ECR), and service-quota checks that the diff alone won't surface.

package/stacks/iac/terraform/claude.fragment.md

@@ -0,0 +1,13 @@
+## IaC stack
+
+- **Active IaC tool: Terraform.** Infrastructure changes go through Terraform; Aaron
+  loads the `iac-terraform` and `terraform-conventions` skill packs.
+- **Workflow gate:** `terraform fmt` → `validate` → `plan` (review) → `apply`. Never
+  `apply` without reading the `plan`; plan on PR, apply on merge (approval for prod).
+- Run the active cloud's `*-deployment-preflight` skill before applying for the
+  cloud-specific checks (naming, quotas, stale state) `plan` won't surface.
+- Read-only CLI (`fmt`, `validate`, `plan`, `state list`, `show`) is allowed; `apply`
+  and `destroy` are gated.
+
+<!-- naturalize: confirm the IaC directory, backend config location, and per-environment
+state layout. -->

package/stacks/iac/terraform/settings.fragment.json

@@ -0,0 +1,25 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(terraform fmt:*)",
+      "Bash(terraform validate:*)",
+      "Bash(terraform plan:*)",
+      "Bash(terraform show:*)",
+      "Bash(terraform state list:*)",
+      "Bash(terraform output:*)",
+      "Bash(terraform version:*)",
+      "Bash(terraform providers:*)",
+      "Bash(tflint:*)",
+      "Bash(tfsec:*)",
+      "Bash(checkov:*)"
+    ],
+    "deny": [
+      "Bash(terraform apply:*)",
+      "Bash(terraform destroy:*)",
+      "Bash(terraform state rm:*)",
+      "Bash(terraform state mv:*)",
+      "Bash(terraform import:*)"
+    ]
+  },
+  "mcpServers": {}
+}