Skip to content

refactor(migration-to-aws): tf-best-practices owns AWS authoring posture; gcp-to-aws consumes it as a black box#145

Merged
icarthick merged 1 commit into
awslabs:mainfrom
icarthick:feat/tf-best-practices-authoring-posture
Jul 15, 2026
Merged

refactor(migration-to-aws): tf-best-practices owns AWS authoring posture; gcp-to-aws consumes it as a black box#145
icarthick merged 1 commit into
awslabs:mainfrom
icarthick:feat/tf-best-practices-authoring-posture

Conversation

@icarthick

Copy link
Copy Markdown
Collaborator

Summary

Makes the tf-best-practices skill the single source of truth for "what good AWS Terraform looks like," and has gcp-to-aws consume it as a black box — invoking it by name and passing context, with no knowledge of its internal files, part structure, or rule list. This lets the posture evolve independently of any one caller and prepares it for reuse by future callers (heroku-to-aws).

Builds on #142 (which introduced the tf-best-practices policy gate).

What moved

tf-best-practices — the "what":

  • SKILL.md gains a routing contract: callers enter by name and state their context (authoring/pre-generation vs post-writing validation); the skill routes to its own reference files. Scope broadened to three tiers: gate-enforced / authoring-only / compliance-conditional.
  • security-posture-rules.md becomes the single source of AWS authoring truth — source-cloud-agnostic framing, a Caller-context signals contract (compliance, aws_config), the migrated authoring-only rules (deletion_protection, master-password-via-Secrets-Manager, S3 hardening, Fargate/EKS/ECR, subnet/NAT, monitoring), and a compliance-conditional section (the rule lives in the skill; the compliance trigger is a caller-supplied signal).

gcp-to-aws — the "wiring":

  • Step 3.0 (new): before writing terraform, invoke tf-best-practices by name for the authoring context and pass caller context (compliance from preferences, aws_config values); follow the returned posture.
  • Step 3.1 + domain table: keep only GCP-source glue (authorized_networks warning, success_metrics alarms, resource wiring); posture removed.
  • Step 5 self-check + Step 6: reference the skill as a black box — invoke by name for validation, no internal paths, no rule enumeration, no Part 1/Part 2 structure.

Black-box boundary

gcp-to-aws no longer references any tf-best-practices internal file, its part structure, or its rule list — it only invokes by name and passes context. The skill can reorganize files, rename parts, or add rules without touching the caller.

Verification

Verified end-to-end with a live gcp-to-aws run (not just build-green):

  • The skill was invoked at both touchpoints inside Generate (authoring + validation); nested skill-invocation returned control cleanly.
  • Step 3.0 posture landed in the generated .tf: storage_encrypted=true, publicly_accessible=false, deletion_protection=true, the Secrets-Manager master-password recipe, scoped SG + least-privilege IAM.
  • Compliance-conditionals correctly suppressed for empty compliance.
  • Step 6 returned POLICY_OK (0 violations, no fix-and-retry).
  • mise build green.

Not covered (follow-up)

The compliance-conditional branch was verified only in the suppressed direction (empty compliance). Emitting flow logs / rotation / KMS for a declared pci/hipaa stack uses the same delegation mechanism but was not exercised in this run.

…authoring posture; gcp-to-aws consumes it as a black box

Moves "what good AWS Terraform looks like" out of gcp-to-aws's generate phase and
into the tf-best-practices skill, so the posture evolves independently of any one
caller and both current/future callers (gcp-to-aws now, heroku-to-aws later) share
one source of truth.

tf-best-practices (the "what"):
- SKILL.md gains a routing contract: callers enter by NAME and state their context
  (authoring/pre-generation vs post-writing validation); the skill routes to its own
  reference files. Scope broadened to three tiers (gate-enforced / authoring-only /
  compliance-conditional).
- security-posture-rules.md becomes the single source of AWS authoring truth:
  source-cloud-agnostic framing, a Caller-context signals contract (compliance,
  aws_config), the migrated authoring-only rules (deletion_protection, master-
  password-via-Secrets-Manager, S3 hardening, Fargate/EKS/ECR, subnet/NAT, monitoring),
  and a compliance-conditional section (rule lives in the skill; the compliance
  trigger is a caller-supplied signal).

gcp-to-aws (the "wiring"):
- Step 3.0 (new): before writing terraform, INVOKE tf-best-practices by name for the
  authoring context and pass caller context (compliance from preferences, aws_config
  values). Follow the posture it returns.
- Step 3.1 + domain table: keep only GCP-source glue (authorized_networks warning,
  success_metrics alarms, resource wiring); posture removed.
- Step 5 self-check + Step 6: reference the skill as a black box — invoke by name for
  validation, no internal file paths, no rule enumeration, no Part 1/Part 2 structure.

Black-box boundary: gcp-to-aws no longer references any tf-best-practices internal
file, its part structure, or its rule list — only invokes by name and passes context.

Verified end-to-end: a live gcp-to-aws run invoked the skill at both touchpoints; the
Step 3.0 posture landed in the generated .tf (storage_encrypted/publicly_accessible=
false/deletion_protection, Secrets-Manager master-password recipe, scoped SG + IAM),
compliance-conditionals correctly suppressed for empty compliance, and Step 6 returned
POLICY_OK. mise build green.
@icarthick
icarthick requested a review from a team as a code owner July 15, 2026 22:28
@icarthick
icarthick merged commit 2eb090a into awslabs:main Jul 15, 2026
8 checks passed
@icarthick
icarthick deleted the feat/tf-best-practices-authoring-posture branch July 16, 2026 02:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant