terraform-station-module

# Terraform Station Module Skill

Use this skill when working on Station module implementation logic.

This skill is for **module code changes**. For Terraform test authoring/execution in `tests/*.tftest.hcl`, use `terraform-station-test`.

## What this skill covers

- Adding/changing behavior in root module files (`*.tf` at repo root)
- Updating child modules:
  - `application/`
  - `group/`
  - `user_assigned_identity/`
  - `hashicorp/tfe/`
- Updating module interfaces:
  - `variables.tf`
  - `variables.applications.tf`
  - `variables.identity.tf`
  - `outputs.tf`
- Keeping Station compatible as a **called module** (consumer-facing contract)
- Updating documentation where interface/behavior changes

## Station module invariants

1. Treat Station as a module consumed by parent configurations.
2. Preserve backward compatibility unless the user explicitly requests a breaking change.
3. Keep variable schemas, validation rules, and defaults aligned with actual implementation.
4. Keep outputs aligned with resources and child module wiring.
5. Prefer extending existing patterns over introducing new structure.
6. Keep changes focused and minimal.

## Required discovery before changing code

Always inspect these first for impact analysis:

- `variables.tf`
- `variables.applications.tf`
- `variables.identity.tf`
- `outputs.tf`
- relevant feature files (for example `applications.tf`, `groups.tf`, `connectivity.tf`, `tfe.tf`)
- relevant child module `variables.tf` and `outputs.tf`

Then map your change to:

- inputs consumed
- resources/data affected
- outputs exposed
- tests likely impacted

## Implementation workflow

1. Locate feature entry points in root module files.
2. Identify whether behavior belongs in root module or child module.
3. Update variable definitions/validations if interface changed.
4. Update implementation (`resource`, `data`, `locals`, `module` calls).
5. Update outputs if exposed behavior changed.
6. Update docs/examples if user-visible behavior changed.
7. Run formatting.
8. Run relevant tests (or hand off to `terraform-station-test` flow).

## Validation and formatting rules

- Run:

```bash
terraform fmt -recursive
```

- Do **not** rely on `terraform validate` for this repository due provider alias/module limitations.

- Prefer targeted Terraform tests for affected feature areas:
  - `tests/application.tftest.hcl`
  - `tests/group.tftest.hcl`
  - `tests/tfe.tftest.hcl`
  - `tests/connectivity.tftest.hcl`
  - `tests/identity.tftest.hcl`
  - `tests/user_assigned_identities.tftest.hcl`

## Compatibility checklist for module changes

Before finishing a change, verify:

- Input object shape matches actual references in code
- Optional fields are guarded with `try(...)`, `lookup(...)`, `coalesce(...)`, or conditional logic where needed
- Validation error messages still describe the true constraint
- Resource naming/location/tag defaults still follow Station conventions
- Identity and role-assignment side effects remain correct for enabled feature blocks
- Outputs still reference valid resource/module attributes

## Common Station-specific pitfalls

- Adding new required fields to existing input objects without defaults
- Changing map keys that tests/consumers depend on
- Forgetting to propagate variable changes into child modules
- Breaking app/group/identity auto-assignment behavior
- Updating logic but not adjusting outputs/docs

## CI-aware change planning

Station uses selective test execution in CI.

When changing module files, anticipate which tests are triggered using:

- `.github/scripts/README.md`
- `.github/workflows/terraform.yaml`

If core/shared files are touched, expect full-suite runs.

## Use with testing skill

After module edits:

1. format with `terraform fmt -recursive`
2. invoke `terraform-station-test` for test updates/execution
3. ensure feature tests cover minimum + maximum scenarios when behavior changed

## Done criteria for module tasks

- Code change implemented at correct module boundary
- Variable/validation/output updates included where needed
- Formatting completed
- Relevant tests run (or explicitly delegated)
- No unrelated refactors bundled into the change