feat!: convert to copier-managed skeleton

.agents/references/primitive/creation.md

@@ -0,0 +1,40 @@
+# Primitive Module Creation and Cleanup
+
+Use this reference when converting the skeleton into a primitive module or reviewing a conversion.
+
+## Creation Flow
+
+1. Confirm the provider and one target resource type. Review the provider documentation and a similar primitive for that provider.
+2. For AWS, consult the official service API reference when practical. Translate documented ranges, enums, formats, and cross-field constraints into variable validation and descriptions. If no suitable public API reference is found after a reasonable search, proceed using provider documentation rather than retrying indefinitely.
+3. Implement `versions.tf`, `variables.tf`, `main.tf`, and `outputs.tf` using the primitive standards.
+4. Build `examples/complete/` with its Terraform files, an accurate README, resource naming, and any deployable prerequisite resources.
+5. Before writing cloud-backed tests, run the available example validation flow: formatting and linting, init, validate, plan, apply, and destroy. Resolve failures before continuing when credentials and environment access permit.
+6. Add Terratest coverage, then run the Go quality checks in the testing reference before cloud-backed test execution.
+7. Build root `README.md` from `TEMPLATED_README.md`, replace the module-specific title and overview, add usage, retain the development boilerplate, and populate terraform-docs.
+8. Run the cleanup and completion checks below.
+
+## Root and Example Documentation
+
+- Do not write root `README.md` from scratch. Start from `TEMPLATED_README.md` and preserve Module Development, Pre-Requisites, Pre-Commit Hooks, Local Validation, Review and Merge Process, and Automatic Updates.
+- Do not remove `TEMPLATED_README.md` until all of its required sections have been incorporated into the root README.
+- The generated terraform-docs block in the root README must not be empty. Generate it when available; otherwise supply accurate inputs and outputs tables.
+- The handwritten usage block in `examples/complete/README.md` must match `examples/complete/main.tf`, including resources, policies, dependencies, variables, inputs, and outputs. Update it whenever the example changes.
+
+## Skeleton Cleanup
+
+Before completion:
+
+- Delete `examples/with_cake/` when it is part of the skeleton.
+- Update the Go module path and every test import from `launch-terraform-template` to the new module repository.
+- Replace template comments in `tests/testimpl/`, including empty template settings comments.
+- Search all Markdown and Go files for `TODO:` and template references. Remove or replace every placeholder, including the hooks documentation placeholder.
+- Search for stale resource names, package names, copied snippets, imports, and generated provider files that should not be committed.
+- Run `go mod tidy` after renaming imports or adding SDK dependencies.
+
+## Completion Checklist
+
+- Root variables have explicit types, descriptions, required validation, and coherent optional objects.
+- Root outputs exist in the provider schema, have descriptions, and match the intended composition interface.
+- The complete example passes every root variable through, exposes test-consumed outputs, and uses the secure configuration.
+- Root and example documentation are synchronized and complete.
+- No skeleton resources, TODOs, template names, or stale imports remain.

.agents/references/primitive/release-history.md

@@ -0,0 +1,67 @@
+# Primitive Module Guidance Release History
+
+This file preserves the learnings from the previous monolithic primitive module guide.
+
+## 2.1
+
+- Skeleton updates now add the `.agents/`, `.claude/`, and `.cursor/` guidance trees. Reviewers of automatic update PRs should expect this additive template change.
+
+## 2.0
+
+- Split the legacy GitHub agent guide into an agent-agnostic skill and focused reference files. The legacy file is a compatibility stub; operational standards, creation and cleanup guidance, test guidance, and historical rationale now live separately.
+
+## 1.13
+
+- AWS primitive modules should consult official AWS API references where practical and translate documented ranges, enums, formats, and cross-field constraints into Terraform validations and variable descriptions.
+
+## 1.12
+
+- Root `README.md` should be built from `TEMPLATED_README.md`; preserve skeleton boilerplate and only replace module-specific sections.
+
+## 1.11
+
+- Optional object variables need cross-field validation for paired fields, conditional requirements, and contradictory sentinel values.
+
+## 1.10
+
+- Add mechanical checks for loose test assertions and README/example drift. When `main.tf` changes, revisit the example README and tests.
+
+## 1.9
+
+- Regula/OPA references were removed from the skeleton. Use the current unified Terraform check workflow and current Makefile targets.
+
+## 1.8
+
+- Avoid Terraform reserved variable names. Verify output attributes against provider schema. Keep example outputs aligned with tests. Use account-scoped unique names where cloud resources require uniqueness.
+
+## 1.7
+
+- Treat specific-value assertions, differentiated functional/readonly tests, security verification, README accuracy, and template cleanup as high-severity requirements.
+
+## 1.6
+
+- Remove skeleton placeholders, generate terraform-docs output, require output descriptions, validate bounded inputs, and keep examples complete.
+
+## 1.5
+
+- Examples should use security-first defaults and cleanup should search broadly for skeleton/template references.
+
+## 1.4
+
+- Legacy GitHub agent files required frontmatter first to be recognized.
+
+## 1.3
+
+- Agent guidance moved into `.github/agents/` in the older layout and gained a skeleton cleanup checklist.
+
+## 1.2
+
+- Resource naming module usage was corrected: use `for_each = var.resource_names_map`, `class_env`, required `cloud_resource_type` and `maximum_length`, and output format references such as `module.resource_names["key"].format`.
+
+## 1.1
+
+- Terratest should verify real resource state through provider APIs, not only Terraform outputs.
+
+## 1.0
+
+- Initial primitive module guidance.

.agents/references/primitive/standards.md

@@ -0,0 +1,101 @@
+# Primitive Module Standards
+
+Primitive modules wrap one cloud resource type and keep the interface reusable. They are comprehensive production wrappers, not minimal examples or opinionated architectures.
+
+## Architecture
+
+- Include one primary cloud resource type.
+- Do not add business logic or multi-resource architecture behavior.
+- Use a descriptive Terraform resource name based on the resource type; do not use `this`.
+- Expose every non-deprecated, non-computed argument that a typical production deployment would configure. Optional attributes normally default to `null` so Terraform omits them unless chosen.
+- Export useful resource attributes individually. Do not output the complete resource object.
+- Keep secure defaults in the example, especially encryption and private access patterns where the provider supports them.
+
+## Required Structure
+
+```text
+examples/complete/
+  main.tf
+  variables.tf
+  outputs.tf
+  versions.tf
+  README.md
+tests/
+  post_deploy_functional/
+  post_deploy_functional_readonly/
+  testimpl/
+main.tf
+variables.tf
+outputs.tf
+versions.tf
+README.md
+TEMPLATED_README.md
+Makefile
+go.mod
+go.sum
+```
+
+## Provider Notes
+
+- Azure resources commonly use explicit `location`, `resource_group_name`, and nested configuration blocks.
+- AWS resources commonly use `data.aws_region.current`, tags for grouping, and separate resources for versioning, policies, encryption, or logging when the provider models them separately.
+- GCP resources commonly distinguish project, location, labels, and IAM binding patterns.
+
+## Variables
+
+- Give every variable an explicit type and useful description.
+- Use `snake_case`, provider argument names where practical, and concise group headings for related inputs.
+- Do not use Terraform-reserved names such as `source`, `target`, `version`, `count`, `for`, or `provider`.
+- Required infrastructure inputs have no default. Optional flags should default to `false` or the safer option. Tags or labels should default to an empty map.
+- Use `object()` with `optional()` attributes for structured optional configuration.
+- Add validation for provider-enforced numeric bounds, enums, formats, mutually exclusive inputs, and cross-field requirements.
+- Nullable validation expressions must avoid evaluating null values, for example with a conditional expression. Use `try()` for nested optional object attributes.
+- Optional object descriptions must explain conditional field requirements and prohibited combinations.
+
+For every optional object, validate all of the following where applicable:
+
+- Individual enum, range, and format constraints.
+- Fields that must be provided together.
+- Fields required when another field is set or active.
+- Fields prohibited by an off or disabled sentinel value.
+
+## Resources and Outputs
+
+- Map variables directly to resource arguments. Use dynamic blocks for optional nested blocks when the provider supports them.
+- Avoid lifecycle blocks and data sources unless they are necessary for the resource contract.
+- AWS often models configuration as separate resources rather than nested blocks; follow the provider schema.
+- Place tags or labels at the end of resource blocks where the local provider convention supports it.
+- Every output needs a short description and must reference an attribute verified in the provider schema.
+- Use generic output names such as `id`, `name`, `arn`, `url`, or `fqdn`, without resource-type prefixes.
+- When `id` is the same value as another output, say so in the `id` description.
+- Do not mark outputs sensitive by default; callers handle sensitivity in their own interface.
+
+## Version Constraints
+
+- Set a Terraform version and provider constraints that avoid untested major upgrades.
+- Pin providers to an appropriate compatible minor range, following the current skeleton and provider-specific precedent.
+- Keep provider configuration out of the root module; examples own provider configuration.
+
+## AWS API Reference Check
+
+For AWS primitive modules, consult the official AWS service API reference when practical. Derive validation ranges, enum values, formats, and cross-field constraints from the API reference and provider schema. If no suitable public API reference is found after a reasonable search, skip the step and do not retry indefinitely.
+
+## Example Requirements
+
+- The example must pass through every root module variable.
+- Mutually exclusive root variables should both be represented with coherent defaults.
+- The example should demonstrate the secure pattern for the resource type.
+- `examples/complete/README.md` usage must exactly match `examples/complete/main.tf`.
+- Example outputs must expose every value used by tests.
+- Use the Launch resource naming module correctly: `for_each = var.resource_names_map`, `class_env`, numeric `instance_env` and `instance_resource`, and each entry's `name` and `max_length` for `cloud_resource_type` and `maximum_length`.
+- Read naming outputs by map key, for example `module.resource_names["<key>"].standard`. Account-scoped names need a random suffix when concurrent or sequential tests could collide.
+- Use the provider's regional convention for the naming module. AWS and GCP patterns may need hyphens removed from region names.
+
+## Common Anti-Patterns
+
+- Wrapping more than one primary resource type.
+- Using `assert.NotEmpty` where a specific expected value is known.
+- Copying functional tests into readonly tests unchanged.
+- Leaving an empty terraform-docs block.
+- Writing root `README.md` from scratch and dropping skeleton boilerplate.
+- Leaving `TEMPLATED_README.md` content unincorporated.

.agents/references/primitive/testing.md

@@ -0,0 +1,62 @@
+# Primitive Module Testing
+
+Primitive tests must prove the Terraform interface and the cloud resource behavior.
+
+## Test Shape
+
+- `post_deploy_functional` performs write or behavior-changing operations where the resource type supports them.
+- `post_deploy_functional_readonly` performs read-only verification only.
+- The two test packages must call different implementation functions.
+- Shared setup and provider clients belong in `tests/testimpl/`.
+- Use `t.Parallel()` where the test framework and provisioned resources support concurrent execution.
+- Functional tests deploy and clean up the complete example. Readonly tests assume deployed infrastructure.
+
+## Assertions
+
+- Assert specific expected values from Terraform inputs, computed naming outputs, provider API responses, or known example configuration.
+- Avoid `assert.NotEmpty` and `require.NotEmpty` when the value is knowable.
+- Use `require` for attributes that must exist before deeper assertions.
+- Verify security settings through the cloud provider API when the module configures encryption, policies, public access controls, identity, or networking.
+- For a required security API attribute, use `require.True(t, ok, ...)` before assertions rather than an `if ok` branch that silently skips a missing setting.
+- The limited valid uses of `NotEmpty` are checking a collection before indexing it or verifying a required environment variable. Configuration and API-returned values should have known expected values.
+
+## Readonly Tests
+
+Readonly tests must not create, update, invoke mutating operations, publish messages, write objects, or alter state.
+
+## Readonly Test Runner
+
+The readonly package (`tests/post_deploy_functional_readonly`) must:
+
+- Call `lib.RunNonDestructiveTest`, not `lib.RunSetupTestTeardown`. The setup/teardown runner turns a readonly suite into a full apply, test, and destroy flow.
+- Pass a `tests/testimpl` function whose name begins with `TestComposable`, such as `TestComposableCompleteReadOnly`. `lcaf-component-terratest` fails the test at runtime when the name does not meet this requirement.
+
+CI excludes the readonly binary from its test command, so both requirements must be correct by construction.
+
+## Functional Tests
+
+Functional tests should exercise the resource behavior, not just Terraform outputs. Examples include writing and reading data, invoking a function, publishing a message, checking access policies, or using the relevant provider SDK operation.
+
+## Go Quality
+
+- Keep provider SDK helpers small and purpose-focused.
+- Run `go mod tidy` after adding SDK dependencies.
+- Before cloud-backed test runs, run the available Go linter, `go get -u ./...`, `go mod tidy`, and `go build ./...`; resolve failures before running the wider test flow.
+- Build or run targeted Go tests before cloud-backed runs when possible.
+- Keep example outputs and Go expected values synchronized.
+
+## Provider State Verification
+
+- Verify both Terraform outputs and real cloud state. Prefer Terratest provider helpers, then use the provider SDK where no helper covers the resource.
+- Read cloud credentials and region or project context from the environment. Fail clearly when required configuration is missing.
+- Compare API values to Terraform outputs or known example values, including security configuration such as encryption, TLS, access policy, private networking, or identity settings.
+
+## Test Review Checklist
+
+- No configuration assertion uses `assert.NotEmpty` or `require.NotEmpty` when a specific value is available.
+- Functional and readonly entrypoints call different `tests/testimpl/` functions and are not copies of each other.
+- The readonly entrypoint uses `lib.RunNonDestructiveTest` and a `TestComposable*` implementation function.
+- Functional coverage includes a safe write or behavior operation when the resource supports one.
+- Readonly coverage performs no writes, invocation, publishing, resource creation, updates, or state changes.
+- Security-critical provider attributes are required and compared to expected values.
+- Test-consumed Terraform outputs exist in `examples/complete/outputs.tf`.

.agents/references/reference-architecture/release-history.md

@@ -0,0 +1,51 @@
+# Reference Architecture Guidance Release History
+
+This file preserves the learnings from the previous monolithic reference architecture guide.
+
+## 3.1
+
+- Skeleton updates now add the `.agents/`, `.claude/`, and `.cursor/` guidance trees. Reviewers of automatic update PRs should expect this additive template change.
+
+## 2.0
+
+- Readonly tests must use non-destructive helpers. Add a skeleton transformation verification gate. Include Lambda source directories when examples need deployable source. Avoid duplicate CloudWatch log groups with `terraform-aws-modules/lambda/aws`. Use registry module source formats. Keep output prefixes consistent. Prefer `create_*` feature flags. Strengthen the ban on loose non-empty assertions.
+
+## 1.9
+
+- Complete examples must not redundantly compose `resource_names`. Do not commit `providers.tf` in examples. Use `RunNonDestructiveTest` for readonly tests. Check community module compatibility before choosing versions. Remove stale skeleton names from go.mod, imports, and test functions. Avoid duplicate IAM permissions.
+
+## 1.8
+
+- Strengthen specific-value assertions, differentiate functional and readonly tests, mandate KMS/encryption verification where configured, and require README tables to match actual code.
+
+## 1.7
+
+- Keep cloud-provider guidance balanced. Add Azure networking and security patterns alongside AWS examples.
+
+## 1.6
+
+- Provider SDK verification examples were added for AWS services and read-only versus destructive test flows.
+
+## 1.5
+
+- SDK verification is mandatory for meaningful tests. IAM should use least privilege and avoid duplicated policy attachments. Community module versions need compatibility checks.
+
+## 1.4
+
+- Legacy GitHub agent files required frontmatter first to be recognized.
+
+## 1.3
+
+- Agent guidance moved into `.github/agents/` in the older layout and gained a skeleton cleanup checklist.
+
+## 1.2
+
+- Resource naming module usage was corrected: use `for_each = var.resource_names_map`, `class_env`, required `cloud_resource_type` and `maximum_length`, output format references, and no obsolete `resource_names_strategy` variable.
+
+## 1.1
+
+- Terratest should verify real resource state through provider APIs, and reference architecture tests should cover optional features enabled by examples.
+
+## 1.0
+
+- Initial reference architecture guidance.