wa-guardrails

name	wa-guardrails
description	Generate preventive Well-Architected guardrails — AWS Config rules, Service Control Policies, permission boundaries, CloudWatch alarms, and IaC policy checks (CDK Aspects, cfn-guard, OPA/Sentinel) — plus an optional governance steering doc, so a workload stays aligned with Well-Architected best practices over time instead of being assessed once. Use when the user wants to enforce best practices in CI, prevent insecure or non-compliant configurations from shipping, detect configuration drift, codify the fixes from a Well-Architected review as ongoing controls, or capture standards as an always-on steering file for their AI coding agent.
version	1.0.0

Well-Architected Guardrails

This skill generates preventive and detective controls that keep a workload Well-Architected over time. Unlike the assessment skills (which find gaps) or remediation (which fixes a specific finding once), guardrails codify best practices so non-compliant changes are blocked or flagged automatically — in CI, at deploy time, and continuously in the account.

What you'll produce: ready-to-commit control files (Config rules, SCPs, CI policy checks, alarms), each tied to the WA Question/Best Practice ID it enforces, with a note on whether the control is preventive (blocks the bad change) or detective (flags it after the fact).

Step 1: Gather context

Ask the user (skip any already provided or inferable from the codebase):

I can generate guardrails to keep your workload Well-Architected. Let me know:

• Workload name and code packages/directories (IaC, CI/CD configs)
• IaC dialect: CDK (which language), CloudFormation, Terraform, SAM, or mixed
• Source of controls: a prior /aws-well-architected-framework-review or assessment output, specific concerns, or "scan and propose"
• Enforcement points available: CI pipeline (which one), AWS Organizations/SCPs, AWS Config, account-level admin — so controls target what you can actually deploy
• Pillars to prioritize (optional; default: Security and Reliability)

If you are in a codebase, proceed directly and infer the IaC dialect and CI system from the files present.

Step 2: Discovery — what to enforce

Determine the controls to generate from one of two inputs:

Path A — From an assessment (preferred): parse the prior review for findings, their pillar, severity, evidence (file:line), and the Best Practice IDs cited. Each High/Critical finding becomes a candidate guardrail so the same gap cannot recur.

Path B — Standalone scan: analyze the IaC and identify the control-worthy configurations actually in use — storage encryption, public access, IAM scope, multi-AZ, backups, logging, TLS, tagging. Map each to the WA Best Practice it relates to.

Produce a control candidate list: for each, record the pillar, the WA Question/BP ID, the resource type it applies to, the current state (compliant / non-compliant / absent), and the enforcement point that fits (CI check, Config rule, SCP, alarm).

Step 3: Select preventive vs. detective for each control

For every candidate, choose the strongest control the user's enforcement points allow. Prefer preventive (stops the bad change before it ships) over detective (catches it afterward). Use this decision guidance:

• Can the misconfiguration be caught in IaC before deploy? → CI policy check (CDK Aspect, cfn-guard/cfn-lint, Terraform OPA/Sentinel). Strongest and cheapest.
• Must it be blocked org-wide regardless of who deploys? → SCP or permission boundary.
• Is it only observable on the live resource (e.g. drift, runtime state)? → AWS Config rule (detective; add auto-remediation only if the user confirms).
• Is it a continuous reliability/cost/performance signal? → CloudWatch metric + alarm.

If a control cannot be enforced with the available points, say so explicitly rather than emitting a control that won't run.

Step 4: Generate the controls

Generate every selected control as ready-to-commit code in the workload's existing dialect and conventions. Each control MUST:

• Cite the WA Question/BP ID it enforces (e.g. SEC 8, REL 9)
• Be labeled 🛡️ Preventive or 🔍 Detective
• Include a one-line statement of what it blocks/flags and why it matters

Cover, as applicable to the workload:

Security (SEC) — examples: s3-bucket-server-side-encryption-enabled, s3-bucket-public-read-prohibited, iam-policy-no-statements-with-admin-access (Config); SCP denying creation of unencrypted resources or disabling CloudTrail; a CDK Aspect failing synth on a security group open to 0.0.0.0/0 on non-web ports.

Reliability (REL) — rds-multi-az-support, dynamodb-pitr-enabled, db-instance-backup-enabled (Config); a cfn-guard rule requiring DeletionProtection on stateful resources; an alarm on DLQ depth.

Operational Excellence (OPS) — a CI check requiring tags (owner, cost-center, environment); a Config rule for required CloudWatch log retention; an SCP preventing manual changes outside IaC.

Cost (COST) — a CI check flagging instance types or capacity modes outside an approved list; a budget/anomaly alarm.

Performance / Sustainability (PERF/SUS) — a CI check preferring Graviton/managed services where applicable.

Provide each control's snippet in a fenced code block with the target filename, so the user can commit it directly. Match the workload's dialect — examples of the three most common forms:

Detective — AWS Config managed rule (SEC 8, encryption at rest), CloudFormation:

# guardrails/config-rules.yaml
Resources:
  S3EncryptionEnabled:                      # 🔍 Detective — flags any S3 bucket without SSE
    Type: AWS::Config::ConfigRule
    Properties:
      ConfigRuleName: s3-bucket-server-side-encryption-enabled
      Source: { Owner: AWS, SourceIdentifier: S3_BUCKET_SERVER_SIDE_ENCRYPTION_ENABLED }

Preventive — CDK Aspect (SEC 5, no open security groups), TypeScript:

// guardrails/no-open-sg.aspect.ts
import { IAspect, Annotations } from "aws-cdk-lib";
import { CfnSecurityGroupIngress } from "aws-cdk-lib/aws-ec2";
import { IConstruct } from "constructs";

// 🛡️ Preventive — fails `cdk synth` on 0.0.0.0/0 ingress to non-web ports
export class NoOpenIngress implements IAspect {
  visit(node: IConstruct): void {
    if (node instanceof CfnSecurityGroupIngress &&
        node.cidrIp === "0.0.0.0/0" && ![80, 443].includes(Number(node.fromPort))) {
      Annotations.of(node).addError(`SEC 5: security group open to 0.0.0.0/0 on port ${node.fromPort}`);
    }
  }
}

Preventive — cfn-guard rule (REL 9, stateful resources need deletion protection):

# guardrails/reliability.guard
# 🛡️ Preventive — blocks RDS instances without Multi-AZ + deletion protection
AWS::RDS::DBInstance {
  Properties { MultiAZ == true  DeletionProtection == true }
}

Step 5: Produce the guardrails plan

Output a structured deliverable:

# Well-Architected Guardrails: {Workload Name}

## Summary
- **IaC dialect**: {CDK/CloudFormation/Terraform/SAM}
- **Enforcement points used**: {CI / Config / SCP / alarms}
- **Source**: {prior review / standalone scan}
- **Controls generated**: {N} ({P} preventive, {D} detective) across {pillars}

## Controls by pillar

### {Pillar} — {WA Question/BP ID}
- **Control**: {name}  |  🛡️ Preventive / 🔍 Detective  |  Enforcement: {CI / Config / SCP / alarm}
- **Blocks/flags**: {what, and why it matters}
- **File**: `{path}`
  ```{lang}
  {ready-to-commit snippet}

• Coverage gap (if any): {what this control does NOT catch}

Rollout plan

Order	Control	Enforcement	Risk of false-positive	Notes
{Start in warn/log mode for preventive CI checks and SCPs, then promote to block once clean.}

Verification

{How to confirm each control works — e.g. attempt a known-bad change in a branch and confirm CI fails; check Config rule compliance status.}

Not covered

{Controls the available enforcement points cannot implement, and what would be needed.}

## Step 6: Offer a governance steering doc

Beyond machine-enforced controls, offer to capture the same standards as a **human- and agent-readable governance doc** — the prose counterpart to the guardrails. This is useful for the standards a control can't fully express (design conventions, review expectations) and for teams that want an always-on policy their AI coding agent will follow.

Generate it on request as a steering file the agent loads automatically (e.g. `.kiro/steering/`, `CLAUDE.md`, `.cursor/rules/`), structured as:

```markdown
# {Workload} — Well-Architected Guardrails (Governance)

## Enforced automatically
{One line per machine control, linking the rule file and its WA BP ID — so readers know what is already gated in CI/Config.}

## Conventions to follow (not auto-enforced)
- {Pillar} — {convention}, because {WA BP ID rationale}. {How a reviewer/agent checks it.}

## When proposing or reviewing changes to this workload
- {Standing instruction, e.g. "new data stores MUST set encryption + backups before merge (SEC 8 / REL 9)"}

Keep each statement tied to a WA Question/BP ID, and keep the doc short enough to live in always-on context without bloat.

Step 7: Offer follow-up

Would you like me to:

• Generate the CI workflow wiring (GitHub Actions / CodePipeline step) to run the policy checks?
• Produce a governance steering doc (CLAUDE.md / .cursor/rules/ / .kiro/steering/) capturing these standards for your AI agent?
• Add auto-remediation to a detective Config rule (with safety review)?
• Fix the existing violations these guardrails would block (remediate the current code)?
• Tighten a control from warn mode to block mode?

Calibration Guidance

• Prefer preventive controls (catch in CI/IaC) over detective — they're cheaper and stop the problem before it ships; only fall back to detective when the issue is only visible on the live resource.
• Never emit a control for an enforcement point the user doesn't have — say it's not enforceable and what's needed instead.
• Roll out preventive controls in warn/log mode first. Recommending a hard block or Deny SCP on day one risks breaking existing pipelines — flag this and stage it.
• Auto-remediation is destructive: only generate it when the user explicitly asks, and include a safety/rollback note.
• Tie every control to a WA Question/BP ID so the builder can trace the rationale — a guardrail without a "why" gets disabled the first time it's inconvenient.
• Don't over-generate: a focused set of high-value controls that the team will keep beats 50 noisy rules they'll mute.
• Respect the workload's existing dialect and conventions — emit CDK Aspects for a CDK app, cfn-guard for CloudFormation, OPA/Sentinel for Terraform; don't mix paradigms.
• The governance steering doc complements controls, it doesn't replace them — prefer a machine-enforced control whenever one exists, and use the doc for what code can't express. Keep it concise enough for always-on context.