vybekiit 0.7.25 → 0.7.27

package/dist/global-skills/aws-cdk/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: aws-cdk
-description: Authors, deploys, and troubleshoots AWS infrastructure using CDK with TypeScript or Python. Covers best practices, stack architecture, and construct patterns. Always use when writing CDK constructs, bootstrapping environments, running cdk deploy/synth/diff, fixing CDK or CloudFormation errors, planning stack structure, importing existing resources, resolving drift, or refactoring stacks without resource replacement.
+description: Authors, deploys, and troubleshoots AWS infrastructure using CDK with TypeScript or Python. Covers best practices, stack architecture, and construct patterns. Applies when writing CDK constructs, bootstrapping environments, running cdk deploy/synth/diff, fixing CDK or CloudFormation errors, planning stack structure, importing existing resources, resolving drift, or refactoring stacks without resource replacement.
 metadata:
-  version: "1"
+  version: "2"
 ---
 
 # AWS CDK
@@ -19,7 +19,9 @@ Domain expertise for CDK construct authoring, deployment workflows, compliance,
 
 **Construct ID changes cause replacement**: Renaming/moving a construct changes its logical ID → CloudFormation replaces the resource (data loss for stateful resources). Always `cdk diff` before deploy. See [refactor-and-prevent-replacement](references/refactor-and-prevent-replacement.md).
 
-**UPDATE_ROLLBACK_FAILED**: Stack is stuck. Fix with `cdk rollback $STACK` or `cdk rollback $STACK --orphan <LogicalId>`. See [troubleshooting-deployment](references/troubleshooting-deployment.md).
+**UPDATE_ROLLBACK_FAILED**: Stack is stuck. Fix with `cdk rollback $STACK` or `cdk rollback $STACK --orphan <LogicalId>`. Express mode stacks are the exception — they cannot be rolled back at all. See [troubleshooting-deployment](references/troubleshooting-deployment.md).
+
+**Hotswap and express mode are development-only**: `--hotswap` / `--hotswap-fallback` bypass CloudFormation and create drift on purpose; `--express` reports success before resources stabilize and disables automatic rollback. You MUST NOT use either in production. A failed `--express` deployment cannot be rolled back — recover by rolling forward with another `--express` deploy. See [fast-deployments](references/fast-deployments.md).
 
 **Non-empty S3 buckets persist after destroy**: You MUST set both `removalPolicy: DESTROY` and `autoDeleteObjects: true`. Versioned buckets are worse — delete markers persist even after apparent deletion.
 
@@ -30,12 +32,21 @@ Domain expertise for CDK construct authoring, deployment workflows, compliance,
 | Bootstrap | `cdk bootstrap aws://$ACCOUNT/$REGION` | [bootstrap-and-project-setup](references/bootstrap-and-project-setup.md) |
 | New TS project | `cdk init app --language typescript` — use `tsx`, `eslint-plugin-awscdk` | [bootstrap-and-project-setup](references/bootstrap-and-project-setup.md) |
 | New Python project | `cdk init app --language python` — pin deps, use virtualenv | [bootstrap-and-project-setup](references/bootstrap-and-project-setup.md) |
-| Deploy | `cdk synth --strict` → `cdk diff` → `cdk deploy` | Always diff before deploy to prod |
+| Deploy | `cdk synth --strict` → `cdk diff` → `cdk deploy` | Always diff before deploy to production |
+| Fast dev iteration | `cdk deploy --hotswap-fallback`, `cdk watch`, or `cdk deploy --express` — dev only, never production | [fast-deployments](references/fast-deployments.md) |
 | cdk-nag | `Aspects.of(app).add(new AwsSolutionsChecks())` | [compliance-and-drift](references/compliance-and-drift.md) |
 | Drift | `cdk drift $STACK` (use `--fail` in CI) | [compliance-and-drift](references/compliance-and-drift.md) |
 | Import resource | `cdk import` (interactive or `--resource-mapping` for CI), `cdk deploy --import-existing-resources` | [import-and-migrate](references/import-and-migrate.md) |
 | Refactor safely | `cdk refactor --unstable=refactor` — no property changes in same deploy | [refactor-and-prevent-replacement](references/refactor-and-prevent-replacement.md) |
 
+## Fast Deployments — Hotswap vs Express (dev only)
+
+Both trade safety for speed and you MUST NOT use either in production.
+
+**Choosing between them:** Use `--hotswap` / `--hotswap-fallback` for the fastest loop when you work mostly with hotswappable resources and drift does not matter. Use `--express` when drift is unacceptable, or your resources are not hotswappable.
+
+Recovery workflows (hotswap drift via `--revert-drift`, rolling a failed `--express` deploy forward), the hotswappable-resource rules, and IAM/monitoring enforcement of the prod prohibition are all in the full guide: [fast-deployments](references/fast-deployments.md).
+
 ## Troubleshooting
 
 | Error | Cause → Fix |
@@ -52,8 +63,11 @@ Domain expertise for CDK construct authoring, deployment workflows, compliance,
 | **NoStacksMatched** | CDK uses logical ID (2nd constructor arg), not CFN name. `cdk list` to find IDs. [Details](references/troubleshooting-synth.md) |
 | **Cannot find module** (synth time) | Run `npx tsc --noEmit`, check `cdk.json` app path matches `tsconfig.json` `outDir`, delete stale `.js` files. Python: activate venv. [Details](references/troubleshooting-synth.md) |
 | **V1 import paths / duplicate aws-cdk-lib** | V1 `@aws-cdk/*` imports, wrong `Construct` import, duplicate lib copies in monorepos. [Details](references/v1-to-v2-migration.md) |
-| **Lambda Cannot find module** (runtime) | Wrong handler value, missing SDK v3 migration, Python deps not bundled. [Details](references/troubleshooting-deployment.md) |
+| **Lambda Cannot find module** (runtime) | Wrong handler value, missing AWS SDK v3 migration, Python deps not bundled. [Details](references/troubleshooting-deployment.md) |
 | **API Gateway multi-stage conflicts** | Set `deploy: false` on `RestApi`, create `Deployment` and `Stage` explicitly. [Details](references/troubleshooting-deployment.md) |
+| **Change didn't deploy under `--hotswap`** | Changes to non-hotswappable resources are silently ignored and only logged — the command still reports success. Read the output; use `--hotswap-fallback` to force a CloudFormation deployment instead. [Details](references/fast-deployments.md) |
+| **Failed `--express` deploy / can't roll back** | Express mode cannot use the Rollback Stack API, and a standard deploy MUST NOT be used to recover it. Roll forward: fix the cause, then `cdk deploy $STACK --express`. [Details](references/fast-deployments.md) |
+| **Unexpected drift on a dev stack** | Hotswap and `cdk watch` create drift by design. Until reverted, the live resources — not CloudFormation's records — are authoritative. Reconcile with `cdk deploy $STACK --revert-drift`, which uses Drift Aware Changesets to bring live resources in line with the template (updates reality to match desired state; does NOT rewrite CF records to match drifted resources). [Details](references/fast-deployments.md) |
 
 ## Construct Patterns
 

package/dist/global-skills/aws-cdk/references/fast-deployments.md

@@ -0,0 +1,191 @@
+# Fast Deployments: Hotswap and Express Mode
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Choosing a Deployment Mode](#choosing-a-deployment-mode)
+- [Hotswap](#hotswap)
+  - [`--hotswap` vs `--hotswap-fallback`](#--hotswap-vs---hotswap-fallback)
+  - [Hotswappable Resource Types](#hotswappable-resource-types)
+  - [cdk watch Defaults to Hotswap](#cdk-watch-defaults-to-hotswap)
+  - [Hotswap Drift and Recovery](#hotswap-drift-and-recovery)
+- [Express Mode](#express-mode)
+  - [Supported Commands](#supported-commands)
+  - [Rollback Behavior](#rollback-behavior)
+  - [Recovering a Failed Express Deployment](#recovering-a-failed-express-deployment)
+- [Production Prohibition](#production-prohibition)
+- [Security Considerations](#security-considerations)
+
+---
+
+## Overview
+
+A standard `cdk deploy` with no extra flags runs a full CloudFormation deployment and waits for every resource to stabilize. Two options trade safety for speed:
+
+- **Hotswap** (`--hotswap`, `--hotswap-fallback`) — bypasses CloudFormation entirely and updates supported resources directly through AWS SDK or Cloud Control API calls.
+- **Express mode** (`--express`) — still a CloudFormation deployment, but it does not wait for resources to stabilize.
+
+Hotswap and express mode are **independent mechanisms**. When a `--hotswap-fallback` deployment falls back to CloudFormation, it performs a *standard* CloudFormation deployment, NOT an express-mode one.
+
+You MUST NOT use either mode for production deployments. See [Production Prohibition](#production-prohibition).
+
+---
+
+## Choosing a Deployment Mode
+
+| Situation | Mode |
+|---|---|
+| Any production deployment | Standard `cdk deploy` (no speed flags) |
+| Iterating on mostly hotswappable resources, want the fastest possible deploy, drift does not matter | `cdk deploy --hotswap` |
+| Same, but the deployment MUST still succeed when it touches a non-hotswappable resource | `cdk deploy --hotswap-fallback` |
+| You want to avoid CloudFormation drift, or the resources are not hotswappable | `cdk deploy --express` |
+
+Express mode is the right dev-loop choice when drift is unacceptable, because it remains a real CloudFormation deployment. Hotswap is faster but deliberately desynchronizes CloudFormation from reality.
+
+---
+
+## Hotswap
+
+Hotswap updates resources directly via AWS SDK or Cloud Control API calls instead of submitting a CloudFormation change set. This is why it is fast, and also why it **creates drift on purpose**: the live state of the resource no longer matches the state CloudFormation believes it is in.
+
+Hotswap is for development use cases ONLY.
+
+The first hotswap deployment diffs your local changes against the last successful CloudFormation deployment. For back-to-back hotswap deployments, the template synthesized by the *previous hotswap deployment* is used as the basis for the current deployment's diff.
+
+### `--hotswap` vs `--hotswap-fallback`
+
+These two flags behave very differently when a deployment touches a resource that cannot be hotswapped. You MUST pick deliberately.
+
+**`cdk deploy --hotswap`** — deploys only the changes to hotswappable resources. When a deployment involves both hotswappable and non-hotswappable resources, the changes to non-hotswappable resources are **silently ignored** and merely logged in the command output.
+
+```bash
+cdk deploy $STACK_NAME --hotswap
+```
+
+You MUST read the command output when using `--hotswap`. A change to a non-hotswappable resource will not be deployed even though the command reports success. If a code change appears to have no effect, check the output for ignored non-hotswappable changes before debugging further.
+
+**`cdk deploy --hotswap-fallback`** — if the deployment involves only hotswappable changes, a hotswap deployment is performed. If it involves any non-hotswappable change, hotswap is not attempted at all and a standard CloudFormation deployment is performed instead.
+
+```bash
+cdk deploy $STACK_NAME --hotswap-fallback
+```
+
+The decision is all-or-nothing: either every changed resource is hotswappable and a hotswap deployment happens, or at least one is not and the whole deployment goes through CloudFormation. `--hotswap-fallback` SHOULD be preferred over `--hotswap` when you cannot afford a silently dropped change.
+
+### Hotswappable Resource Types
+
+Hotswap supports a specific set of resource types and change kinds that varies by CDK CLI version, so you MUST NOT answer from an enumerated list — including one recalled from training data.
+
+The authoritative list lives in the `--hotswap` option of the [`cdk deploy` CLI reference](https://docs.aws.amazon.com/cdk/v2/guide/ref-cli-cmd-deploy.html#ref-cli-cmd-deploy-options-hotswap), in the section listing the supported hotswap changes. Read it before concluding a change is or is not hotswappable. For types not yet documented there, check the [aws-cdk-cli release notes](https://github.com/aws/aws-cdk-cli/releases). That page also documents which CloudFormation intrinsic functions resolve during a hotswap deployment, which constrains what a hotswappable resource's properties can reference. That set also changes across CDK CLI releases, so read it from the CLI reference or the release notes rather than assuming it.
+
+Any change outside the current list is non-hotswappable and is subject to the `--hotswap` / `--hotswap-fallback` behavior above. The empirical check is the deployment itself: `--hotswap` logs every change it skipped as non-hotswappable, and `--hotswap-fallback` falls through to CloudFormation when it finds one.
+
+### cdk watch Defaults to Hotswap
+
+`cdk watch` (equivalently `cdk deploy --watch`) continuously observes CDK project files and automatically deploys the specified stacks when it detects a change.
+
+```bash
+cdk watch $STACK_NAME
+```
+
+By default `cdk watch` deploys using `--hotswap`. It therefore inherits both hotswap consequences: it creates drift, and it silently ignores changes to non-hotswappable resources. You MUST NOT run `cdk watch` against a production stack.
+
+### Hotswap Drift and Recovery
+
+Because hotswap writes directly to resources, CloudFormation's record of the stack becomes stale: the stored template still describes the pre-hotswap state, while the live resources hold the hotswapped state.
+
+**Until you revert the drift, you MUST NOT treat CloudFormation's recorded state as authoritative.** After a hotswap deployment the live resources — not CloudFormation's records — are the source of truth for what is actually deployed. Anything that reads the stored template instead of the live resources (a drift-unaware audit, another engineer's `cdk diff`, compliance tooling that trusts CloudFormation) will report the stale pre-hotswap configuration, not what is running.
+
+To reconcile CloudFormation's records with the live resources, deploy with the revert-drift flag:
+
+```bash
+cdk deploy $STACK_NAME --revert-drift
+```
+
+This performs a CloudFormation deployment using **Drift Aware Changesets**. A Drift Aware Changeset treats the *template being deployed* as the source of truth and, resource by resource, checks whether the live resource is already in the state the template specifies:
+
+- If a resource is already in the expected state, it is left alone.
+- If a resource is not in the expected state, it is updated so the live resource matches the template.
+
+Note the direction of reconciliation: `--revert-drift` makes the **live resources** conform to the **template** (your desired state). It does NOT rewrite CloudFormation's records to match whatever the resources currently happen to be — the template is authoritative, not the drifted live state. This is the best way to recover from hotswap drift, because the template you deploy after a run of hotswap deployments describes the state you actually want your resources in, and the drift-aware changeset skips the resources hotswap already brought to that state instead of needlessly re-updating them.
+
+---
+
+## Express Mode
+
+Express mode is a CloudFormation deployment option for faster deployments, enabled in CDK with `--express`. It is primarily for development use cases.
+
+```bash
+cdk deploy $STACK_NAME --express
+```
+
+Express mode is faster than a standard CloudFormation deployment because it **skips waiting for resources to stabilize**. It returns as soon as the create, update, or delete API call for each resource returns, reporting whether that call succeeded or failed, without waiting for the resource to reach a stable state. Consequently, resources MAY NOT be fully operational when the deployment reports completion.
+
+Express mode still respects the resource dependencies declared in your template. When one resource references another, CloudFormation confirms the referenced resource's configuration is applied before starting the dependent resource. If a dependent resource fails because a referenced resource was not ready, CloudFormation retries the operation.
+
+Express mode propagates automatically to nested stacks when an operation on the parent stack uses it.
+
+Unlike hotswap, express mode does not bypass CloudFormation, so it does not create drift.
+
+### Supported Commands
+
+Express mode is available as an option on:
+
+- `cdk deploy --express`
+- `cdk bootstrap --express`
+- `cdk destroy --express`
+
+### Rollback Behavior
+
+Express mode does NOT perform rollback automatically. When an operation fails, CloudFormation does not attempt to roll the change back and reports the stack as failed.
+
+Automatic rollback can be enabled explicitly:
+
+```bash
+cdk deploy $STACK_NAME --express --rollback
+```
+
+This is NOT the preferred way to deploy with express mode.
+
+Note the narrow scope of `--rollback`: when a deployment fails *during* `cdk deploy --express --rollback`, that stack will be rolled back. Express mode does not perform rollback in any other instance.
+
+### Recovering a Failed Express Deployment
+
+This is the highest-risk difference between express mode and a standard CloudFormation deployment, and standard recovery guidance does NOT apply.
+
+- Express mode deployments MUST NOT be expected to use the CloudFormation Rollback Stack API — they cannot.
+- Standard CloudFormation deployments MUST NOT be used to recover a failed express mode deployment.
+- Running `cdk deploy --express` or `cdk deploy --express --rollback` against an already-failed stack will not attempt to use the Rollback Stack API to recover it, unlike `cdk deploy` without express mode. The changes are applied to the failed stack without first attempting a rollback.
+
+You MUST recover by rolling **forward** with another express mode deployment that resolves the failure — either revert the resource to its last successful state in code, or make some other change that fixes the underlying cause — then:
+
+```bash
+cdk deploy $STACK_NAME --express
+```
+
+---
+
+## Production Prohibition
+
+You MUST NOT use hotswap in production deployments. Hotswap deployments create drift on purpose; the actual state of your resources may not match the state CloudFormation thinks they are in.
+
+You MUST NOT use express mode in production deployments, because:
+
+- An operation may quietly fail after express mode has already reported success, since it does not wait for resources to stabilize.
+- Express mode disables automatic rollback by default, so stacks can end up in states that are difficult to recover from.
+
+For production, deploy with a standard `cdk deploy` and no speed flags.
+
+---
+
+## Security Considerations
+
+Both modes carry security consequences beyond the operational ones above.
+
+**Hotswap drift can desynchronize security-critical configuration.** Hotswap writes directly to resources, so security groups, IAM policies, encryption settings, and resource policies can end up in states that diverge from what CloudFormation records. Any control that reads the CloudFormation template rather than live resource state will report the intended configuration, not the deployed one. You MUST NOT treat CloudFormation state as authoritative for an audit of a stack that has been hotswapped; reconcile first with `cdk deploy $STACK_NAME --revert-drift`.
+
+**A failed express deployment can leave resources partially configured.** Because express mode does not wait for stabilization and does not roll back by default, a deployment that fails midway can leave a resource created but without its intended encryption, access controls, or policy attachments. You MUST NOT assume a failed `--express` deployment left nothing behind; inspect the stack's resources before reusing the environment.
+
+**Enforce the production prohibition with IAM rather than developer discipline.** Hotswap performs its API calls with your current AWS credentials — it deliberately does not assume the bootstrap stack's deploy roles, because those roles do not have permission to update resources directly outside CloudFormation. A production account can therefore block hotswap outright: grant direct resource-mutation permissions only to the CloudFormation deployment role, and use an SCP or IAM permissions boundary to deny those mutations to developer principals. Hotswap then fails on the API call instead of silently drifting production. Because hotswap mutates resources directly under the developer's own identity, developers performing hotswap deployments SHOULD authenticate with short-lived credentials from IAM Identity Center (AWS SSO) rather than long-lived IAM user access keys, so that a compromised credential has a bounded lifetime and a smaller blast radius.
+
+**Detect hotswap through drift.** Hotswap introduces CloudFormation drift by design, so drift detection is the signal that matches it most directly: run `cdk drift $STACK --fail` on production stacks in CI.

package/dist/global-skills/aws-cdk/references/troubleshooting-deployment.md

@@ -177,6 +177,22 @@ cdk deploy -e $PRODUCER_STACK   # then producer, removing the export
 
 A stack enters `UPDATE_ROLLBACK_FAILED` when CloudFormation cannot roll back a failed update. The stack is wedged and MUST be recovered before any further operations.
 
+### First: was the failed deployment an express mode deployment?
+
+If the failed operation was run with `--express`, the rollback-based recovery below does NOT apply. Express mode deployments cannot use the CloudFormation Rollback Stack API, and a standard CloudFormation deployment MUST NOT be used to recover a failed express mode deployment.
+
+Recover by rolling **forward** instead — make another express mode deployment that resolves the failure, either by reverting the resource to its last successful state in code or by making another change that fixes the cause:
+
+```bash
+cdk deploy $STACK --express
+```
+
+**Security note:** A failed express deployment may have left resources partially configured — potentially without intended encryption, access controls, or policy attachments. Inspect the stack's resources (`aws cloudformation list-stack-resources`) before reusing the environment.
+
+**Audit note:** Check CloudTrail logs for the failed deployment's API calls to determine which resources were created or modified and in what state they were left. This is the most reliable way to reconstruct exactly which create/update/delete operations succeeded or failed, since express mode reports the stack as failed without recording per-resource stabilization.
+
+Running `cdk deploy --express` or `cdk deploy --express --rollback` against an already-failed stack applies the changes without first attempting a rollback, unlike `cdk deploy` without express mode. See [fast-deployments](fast-deployments.md).
+
 ### Root causes
 
 - Resource deleted out-of-band (e.g., manually deleted in the console).

package/dist/global-skills/aws-cloudformation/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: aws-cloudformation
-description: Authors, validates, and troubleshoots AWS CloudFormation templates. Covers template authoring with secure defaults, pre-deployment validation (cfn-lint, cfn-guard, change sets), CloudFormation Express mode for faster deployments, and root-cause diagnosis of failed stacks using CloudFormation events and CloudTrail correlation.
+description: Authors, validates, and troubleshoots AWS CloudFormation templates. Covers template authoring with secure defaults, local validation with either cfn-lint or cloudformation-validate, cfn-guard security and compliance checks as a recommended default, account-aware CloudFormation service pre-deployment validation, CloudFormation Express mode for faster deployments, and root-cause diagnosis of failed stacks using CloudFormation events and CloudTrail correlation. Also covers author-time template intelligence with the CloudFormation Language Server and published cloudformation-validate libraries.
 metadata:
-  version: "2"
+  version: "3"
 ---
 # CloudFormation
 
@@ -42,6 +42,13 @@ fetch or write customer data through `retrieve_skill`.
 tool) is recommended for sandboxed execution and audit logging, but not required
 — every step also works with the AWS CLI.
 
+### Configure author-time template intelligence
+
+Use the [CloudFormation Language Server guide](references/cloudformation-language-server.md) for completion,
+diagnostics, hover documentation, navigation, refactoring, and code actions in editors and AI clients. Follow the
+AWS Toolkit or standalone installation documentation for the selected client rather than relying on runtime,
+build, package, or release-asset details copied into this skill.
+
 ### Understand, explain, or document a template
 
 To answer exploratory questions about an existing template or stack — "what does
@@ -97,25 +104,14 @@ PII into Metadata.
 **Attribution marker.** On any template you create or modify, ensure a top-level
 `Metadata.AWSToolsMetrics.AWSAgentToolkit` marker whose value is
 `aws-cloudformation@<version>`, taking `<version>` from this skill's frontmatter
-`version` field (for example `aws-cloudformation@2`). The marker is idempotent:
+`version` field (for example `aws-cloudformation@3`). The marker is idempotent:
 do not duplicate it, and preserve any other keys already under `AWSToolsMetrics`
 (for example another tool's `IaC_Generator`). Add it regardless of which context
 convention the template uses.
 
 ### Validate a template before deployment
 
-Run three validation layers in order — each catches different classes of errors:
-
-1. **Syntax and schema** — [validate-cloudformation-template SOP](references/validate-cloudformation-template.script.md) (cfn-lint)
-2. **Security and compliance** — [check-cloudformation-template-compliance SOP](references/check-cloudformation-template-compliance.script.md) (cfn-guard)
-3. **Pre-deployment** — [cloudformation-pre-deploy-validation SOP](references/cloudformation-pre-deploy-validation.script.md) (`describe-events` API)
-
-**Critical:** Pre-deployment validation is enabled by default on Create Stack,
-Update Stack, and change set creation. A `FAIL`-mode finding halts the operation
-before any resource is provisioned. Retrieve results via `aws cloudformation
-describe-events` (see
-[SOP](references/cloudformation-pre-deploy-validation.script.md) for scoping
-options). Do NOT use `describe-stack-events`.
+Use the [CloudFormation validation workflow guide](references/validation-tool-selection.md) to choose and sequence local validation, cfn-guard security and compliance checks, and account-aware CloudFormation service pre-deployment validation. The guide covers tool selection, skip and approval conditions, in-process validation, audit logging, and result retrieval.
 
 ### Deploy faster with Express mode
 
@@ -135,24 +131,18 @@ Key points:
 
 ### Troubleshoot a failed deployment
 
-When a stack is in a failed state (`CREATE_FAILED`, `ROLLBACK_COMPLETE`, `UPDATE_ROLLBACK_FAILED`, etc.), follow the [troubleshoot-deployment SOP](references/troubleshoot-deployment.script.md).
-
-Key points:
-
-- Use `aws cloudformation describe-events --stack-name <name> --filters FailedEvents=true --region <region>` to get only failure events. Do NOT use `describe-stack-events` — that API does not support the `--filters` parameter. Do NOT use `--query` JMESPath filters as a substitute — use the `--filters` parameter directly.
-- Examine EVERY failed event's `ResourceStatusReason`. If a failure has a specific error message (e.g., "not authorized to perform", "already exists"), it is a real failure. If a failure says "Resource creation cancelled" with no specific error, it is a cascade caused by rollback — it does not tell you what would have gone wrong.
-- When multiple resources have their own specific errors, they are parallel failures from a shared root cause (e.g., an IAM role missing permissions for multiple services). Enumerate ALL the specific permission gaps, not just the first one, so the developer can fix everything in one pass.
-- Cancelled resources may have their own issues that only surface on the next deployment attempt. Warn the developer that additional failures may appear after fixing the visible ones.
-- Classify the fix as **template-level** (change the template) or **environment-level** (fix IAM, quotas, resource state) — do not propose template changes for environment issues
+When a stack enters a failed state, use the [troubleshoot failed stack SOP](references/troubleshoot-failed-stack.script.md) to classify all actionable failures, rollback cascades, and template-level versus environment-level fixes. Use the broader [troubleshoot deployment SOP](references/troubleshoot-deployment.script.md) when deeper CloudTrail correlation or recovery guidance is needed.
 
 ## Decision Guide
 
 | User intent | Action |
 |-------------|--------|
+| Configure author-time template intelligence in an editor or AI client | CloudFormation Language Server guide |
 | Write or modify a template | Author task + best-practices checklist |
-| Check a template before deploying | Validation pipeline (3 layers) |
+| Check a template before deploying | CloudFormation validation workflow guide |
+| Run validation in code or in process | Use a published cloudformation-validate library for the application language |
 | Deploy faster during development | Deploy-with-express-mode SOP |
-| Stack failed or is stuck | Troubleshoot-deployment SOP |
+| Stack failed or is stuck | Troubleshoot-failed-stack SOP |
 | Unsure about a resource property | Resource property lookup SOP |
 | Explain or understand what a template does (and why) | Retrieve-template-context SOP |
 | Document design decisions in a template | Persist-template-context SOP |

package/dist/global-skills/aws-cloudformation/references/check-cloudformation-template-compliance.script.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-Deterministic procedure for validating a CloudFormation template against security and compliance rules using cfn-guard. Works via the `cfn-guard` CLI or the Python `guardpycfn` binding.
+Deterministic procedure for validating a CloudFormation template against security and compliance rules using cfn-guard. Works via the `cfn-guard` CLI or the Python `guardpycfn` library.
 
 ## Parameters
 
@@ -30,7 +30,7 @@ Check which compliance mechanism is available.
   1. `cfn-guard` CLI available on the user's system (verify with `which cfn-guard` or `cfn-guard --version`)
   2. Python `guardpycfn` library (verify by attempting `import guardpycfn` in a throwaway Python command)
 - If cfn-guard is not installed, You MUST ask the user: "I can install `cfn-guard` (see https://docs.aws.amazon.com/cfn-guard/latest/ug/setting-up.html for install options). Do you want me to install it, or would you prefer to install it manually?"
-- You MUST NOT execute compliance checks or run any install command without the user's explicit approval because this changes the user's environment
+- You SHOULD run the compliance check by default when a supported mechanism is available; You MUST NOT run an install command without the user's explicit approval because installation changes the user's environment
 - If no mechanism is available and the user declines installation, You MUST ask whether to abort or proceed anyway (knowing the SOP cannot complete)
 - You MUST respect the user's decision to proceed, install, or abort
 
@@ -44,7 +44,7 @@ Obtain the CloudFormation template from the user.
 - You MUST read the template content from the provided source (file path, direct input, or URL)
 - You MUST confirm the template is non-empty and parseable as YAML or JSON before proceeding
 - If the template cannot be read or parsed, You MUST inform the user with the specific error and stop
-- You SHOULD recommend running the `validate-cloudformation-template` SOP first if the user has not already done so, because compliance checks assume a syntactically valid template
+- You SHOULD recommend running the project-selected local validation SOP first if the user has not already done so: either the [cfn-lint SOP](validate-with-cfn-lint.script.md) or the [cloudformation-validate SOP](validate-with-cloudformation-validate.script.md), never both by default, because compliance checks assume a syntactically valid template
 
 ### 3. Acquire Rules File (if needed)
 
@@ -97,6 +97,10 @@ Guide the user after compliance results.
 - After fixes are applied, You SHOULD recommend re-running this SOP to confirm all violations are resolved
 - Once compliance passes, You SHOULD recommend the `cloudformation-pre-deploy-validation` SOP for final pre-deployment readiness
 
+## Security Considerations
+
+Follow the [shared security guidance](security-considerations.md) when handling templates, outputs, secrets, tools, and installation artifacts.
+
 ## Examples
 
 ### Example Input

package/dist/global-skills/aws-cloudformation/references/cloudformation-language-server.md

@@ -0,0 +1,177 @@
+# CloudFormation Language Server
+
+## Contents
+
+- [Purpose](#purpose)
+- [Choose the installation path](#choose-the-installation-path)
+- [Configure the server](#configure-the-server)
+- [Kiro CLI configuration](#kiro-cli-configuration)
+- [Generic LSP clients](#generic-lsp-clients)
+- [Validation workflow](#validation-workflow)
+- [Security Considerations](#security-considerations)
+- [Troubleshooting](#troubleshooting)
+- [Authoritative references](#authoritative-references)
+
+## Purpose
+
+Use the CloudFormation Language Server for author-time template intelligence in JSON and YAML templates. It provides completion,
+diagnostics, hover documentation, navigation, refactoring, and code actions through the Language Server Protocol (LSP).
+
+The language server improves the edit loop but is not a final deployment gate. After editing, run one local validation
+tool: `cfn-lint` or `cloudformation-validate` through its `cfn-validate` CLI, not both by default. Then run the cfn-guard security and compliance check unless the
+user explicitly skips it or confirms that an equivalent project check already passed.
+
+## Choose the installation path
+
+### Visual Studio Code or JetBrains
+
+Follow the AWS Toolkit documentation for the editor. Use the Toolkit's documented CloudFormation integration
+rather than separately configuring a standalone server unless the Toolkit instructions require it.
+
+### Other editors and AI clients
+
+A client that supports a custom stdio LSP server can use the standalone distribution. Before installation, read the
+[standalone installation guide](https://github.com/aws-cloudformation/cloudformation-languageserver/blob/main/INSTALLATION.md)
+and the selected [release notes](https://github.com/aws-cloudformation/cloudformation-languageserver/releases/latest).
+Choose the supported download and prerequisites documented for the user's platform at that time.
+
+You MUST NOT copy runtime versions, build labels, asset filenames, or asset-name patterns into this guide because release
+packaging changes independently of the skill. You MUST also avoid inferring an installation method from a package
+manifest or third-party registry; use the official installation guide. Ask the user before downloading, extracting, or
+installing anything because those actions change the local environment.
+
+A client without LSP support cannot gain code intelligence merely by launching the server. Use local validation for
+deterministic checks in that environment.
+
+## Configure the server
+
+Use the server command, entry point, arguments, and prerequisites from the installation guide. Configure stdio
+transport and use absolute paths where the client requires them. Do not guess a runtime executable or bundle filename
+from an older release.
+
+Route only intended CloudFormation JSON and YAML files to the server. Avoid attaching it indiscriminately to every JSON
+or YAML document when the client supports project or file-pattern scoping.
+
+Preserve the nested `aws` initialization data even if the client calls the outer field `init_options`,
+`initializationOptions`, or `initialization_options`:
+
+```json
+{
+  "initializationOptions": {
+    "aws": {
+      "clientInfo": {
+        "extension": {
+          "name": "<client-name>",
+          "version": "<client-version>"
+        }
+      },
+      "telemetryEnabled": true
+    }
+  }
+}
+```
+
+Keep telemetry enabled in generated configuration. Before generating configuration, tell the user that the server
+collects anonymous usage and performance metrics, not CloudFormation template contents or values, and link the
+[telemetry documentation](https://github.com/aws-cloudformation/cloudformation-languageserver/blob/main/src/telemetry/README.md).
+If the user explicitly asks to disable it, honor that preference. Resolve client identity and version from the installed
+client instead of hardcoding them.
+
+## Kiro CLI configuration
+
+Initialize code intelligence in the project root:
+
+```text
+/code init
+```
+
+Then add the server to `.kiro/settings/lsp.json`. Replace the command and argument placeholders with the exact stdio
+invocation from the standalone installation guide:
+
+```json
+{
+  "languages": {
+    "cfn-lsp": {
+      "name": "cloudformation-languageserver",
+      "command": "<server-command>",
+      "args": ["<server-arguments>"],
+      "file_extensions": ["json", "yaml", "yml", "cfn", "template"],
+      "project_patterns": [],
+      "exclude_patterns": [],
+      "multi_workspace": false,
+      "initialization_options": {
+        "aws": {
+          "clientInfo": {
+            "extension": {
+              "name": "kiro-cli",
+              "version": "<installed-client-version>"
+            }
+          },
+          "telemetryEnabled": true
+        }
+      }
+    }
+  }
+}
+```
+
+If the documented invocation needs multiple arguments, represent each as a separate `args` entry. Adjust file extensions
+and project patterns to the repository rather than treating the example as a universal selector.
+
+Restart Kiro CLI after changing the file, or force code-intelligence reinitialization:
+
+```text
+/code init -f
+/code status
+```
+
+`/code status` should show `cfn-lsp` as initialized. Use code-intelligence tools for symbol navigation, hover,
+completion, diagnostics, and code actions rather than simulating those features with text search.
+
+## Generic LSP clients
+
+For another LSP-capable editor, translate the standalone stdio command and the initialization options above into
+the client's configuration format. Follow the editor's documentation for root detection, workspace folders, file
+selectors, and argument arrays. The standalone installation guide contains the maintained client examples.
+
+## Validation workflow
+
+1. Confirm the LSP process is initialized and attached to the intended template.
+2. Read all published diagnostics.
+3. Use hover, completion, and code actions to understand and fix the template; inspect each proposed edit before
+   applying it.
+4. Save the file and wait for diagnostics to refresh.
+5. Run exactly one local validation procedure against the saved file: the
+   [cfn-lint SOP](validate-with-cfn-lint.script.md) or the
+   [cloudformation-validate SOP](validate-with-cloudformation-validate.script.md). LSP diagnostics may reflect an editor
+   buffer while deployment tooling reads the file on disk.
+6. Run the
+   [cfn-guard security and compliance SOP](check-cloudformation-template-compliance.script.md) by default. Skip it only
+   when the user explicitly requests that or confirms an equivalent project security and compliance check already
+   passed.
+7. Use [CloudFormation service pre-deployment validation](cloudformation-pre-deploy-validation.script.md) when
+   account-aware checks are needed before deployment.
+
+Do not claim that an empty editor diagnostics panel proves the saved template is valid, compliant, or deployable.
+
+## Security Considerations
+
+Follow the [shared security guidance](security-considerations.md) when handling templates, outputs, secrets, tools, and installation artifacts.
+
+## Troubleshooting
+
+| Symptom | Check |
+|---------|-------|
+| Server does not initialize | Re-read the selected release's prerequisites and confirm the installed artifact matches the platform |
+| Client reports an immediate process exit | Compare the configured command and argument array with the installation guide |
+| No diagnostics or completion | Confirm the file selector routes this file to the server and the document is recognized as CloudFormation |
+| Kiro CLI cannot see the server | Run `/code status`, inspect `.kiro/settings/lsp.json`, then restart or run `/code init -f` |
+
+## Authoritative references
+
+- [CloudFormation Language Server](https://github.com/aws-cloudformation/cloudformation-languageserver)
+- [Standalone installation guide](https://github.com/aws-cloudformation/cloudformation-languageserver/blob/main/INSTALLATION.md)
+- [CloudFormation Language Server releases](https://github.com/aws-cloudformation/cloudformation-languageserver/releases/latest)
+- [CloudFormation Language Server telemetry](https://github.com/aws-cloudformation/cloudformation-languageserver/blob/main/src/telemetry/README.md)
+- [AWS Toolkit for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=AmazonWebServices.aws-toolkit-vscode)
+- [AWS Toolkit for JetBrains](https://plugins.jetbrains.com/plugin/11349-aws-toolkit)

package/dist/global-skills/aws-cloudformation/references/cloudformation-pre-deploy-validation.script.md

@@ -70,8 +70,8 @@ Catch issues locally before consuming CloudFormation API quota.
 
 **Constraints:**
 
-- You SHOULD recommend running the `validate-cloudformation-template` SOP first to catch cfn-lint syntax and schema errors locally
-- You SHOULD recommend running the `check-cloudformation-template-compliance` SOP to catch security violations locally
+- You SHOULD recommend running the project-selected local validation SOP first: either the [cloudformation-validate SOP](validate-with-cloudformation-validate.script.md) or the [cfn-lint SOP](validate-with-cfn-lint.script.md), never both by default
+- You SHOULD recommend running the `check-cloudformation-template-compliance` SOP by default to catch security violations locally
 - If the user has already run these checks or explicitly skips them, You MUST proceed to the next step
 
 ### 3. Upload Template (if needed)
@@ -198,6 +198,12 @@ When the user is deploying with the AWS CDK rather than raw CloudFormation, pre-
 - You SHOULD inform the user that both `cdk deploy` and `cdk validate` surface pre-deployment validation results in a unified report with construct-level tracing, mapping each result back to the originating CDK construct
 - You SHOULD prefer `cdk validate` when the user wants to validate without deploying
 - You MUST treat the structured CDK validation report the same way as `describe-events` results: enumerate every `FAIL` result before recommending a deploy, and surface `WARN` results for the user to evaluate
+- You MUST distinguish CDK's local `CloudFormationValidatePlugin` integration from CloudFormation service pre-deployment validation
+- See [validate-with-cloudformation-validate.script.md](validate-with-cloudformation-validate.script.md) for library APIs, custom rules, and CDK integration guidance
+
+## Security Considerations
+
+Follow the [shared security guidance](security-considerations.md) when handling templates, outputs, secrets, tools, and installation artifacts.
 
 ## Examples