@raishin/vanguard-frontier-agentic 1.2.0 → 1.4.0

package/skills/finops/finops-cloud-price-advisor/SKILL.md

@@ -1,9 +1,12 @@
 ---
 name: finops-cloud-price-advisor
 description: Fetch live public prices and build cost estimates for AWS, Azure, and OCI using each cloud's public pricing API. Supports live-environment cost analysis (current resource inventory) and prototype cost planning (planned architecture spec). Currency defaults to USD; other currencies on request.
+allowed-tools: Read Grep Glob WebFetch
 metadata:
   author: "github: Raishin"
   version: "0.1.0"
+  updated: "2026-05-05"
+  category: finops
 ---
 
 # FinOps Cloud Price Advisor

package/skills/fluxcd/fluxcd-kustomization-helmrelease-review/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: fluxcd-kustomization-helmrelease-review
+description: Use this skill when reviewing FluxCD Kustomization, HelmRelease, GitRepository, HelmRepository, or OCIRepository resources. Trigger when the user asks whether a Flux configuration is safe for production, whether SOPS encryption is required, whether prune is safe on a given workload, whether commit signature verification is enabled, or whether a Flux multi-tenant setup uses least-privilege ServiceAccounts.
+allowed-tools: Read Grep Glob
+metadata:
+  author: "github: Raishin"
+  version: "0.1.0"
+  updated: "2026-05-05"
+  category: delivery
+---
+
+# FluxCD Kustomization and HelmRelease Review
+
+## Purpose
+
+Review FluxCD `Kustomization`, `HelmRelease`, `GitRepository`, `HelmRepository`, and `OCIRepository` resources for source trust guarantees, SOPS secret encryption, prune-enabled blast radius on stateful workloads, per-Kustomization ServiceAccount scoping, HelmRelease upgrade remediation safety, and health check completeness. FluxCD's default posture gives the `kustomize-controller` cluster-admin-equivalent reach — the security surface lives in per-Kustomization ServiceAccounts, commit signature verification, SOPS encryption at rest, and prune annotation guards.
+
+## Lean operating rules
+
+- Prefer user-provided sanitized resource YAML as primary evidence; official FluxCD docs are the authoritative fallback.
+- Treat unencrypted Kubernetes `Secret` manifests committed to any Git source as a CRITICAL finding — anyone with repo read access (CI, PR participants, auditors) has those secrets.
+- Treat `GitRepository.spec.ref.semver: ">=0.0.0"` or an unbound semver range in a production source as a HIGH finding — any tag push from a compromised upstream triggers a deploy.
+- Treat the absence of `spec.verify.secretRef` (commit GPG signature verification) on production `GitRepository` sources as a HIGH finding.
+- Treat `Kustomization.spec.serviceAccountName` not set as a HIGH finding — the kustomize-controller SA applies with cluster-admin-equivalent scope for all tenants.
+- Treat `spec.prune: true` on Kustomizations covering stateful workloads (StatefulSets, PVCs, CRDs) without `kustomize.toolkit.fluxcd.io/prune: disabled` annotations as a HIGH finding.
+- Treat `HelmRelease.spec.chart.spec.version: "*"` or an unbound version range as a HIGH finding — any upstream chart publish triggers an auto-upgrade.
+- Treat `HelmRelease.spec.upgrade.remediation.retries: -1` (infinite retry) as a MEDIUM finding — a broken release blocks other reconciliation loops indefinitely.
+- Keep the answer scoped: report what was reviewed, the evidence level, and the exact field path for each finding.
+
+## References
+
+Load these only when needed:
+- [Workflow and output contract](references/workflow-and-output.md)
+
+## Response minimum
+
+- Scoped target (resource kind/name/namespace) and evidence level
+- Source trust verdict (commit verification, semver pinning, SOPS encryption)
+- Kustomization ServiceAccount scope assessment
+- Prune safety verdict for any stateful workloads
+- HelmRelease version pinning and upgrade remediation assessment
+- Health check completeness verdict
+- Safe next actions and open questions

package/skills/fluxcd/fluxcd-kustomization-helmrelease-review/metadata.json

@@ -0,0 +1,22 @@
+{
+  "id": "fluxcd-kustomization-helmrelease-review",
+  "name": "FluxCD Kustomization and HelmRelease Review",
+  "type": "skill",
+  "provider": "fluxcd",
+  "harnesses": ["codex", "claude-code", "cursor", "gemini", "kiro", "other"],
+  "summary": "Review FluxCD Kustomization, HelmRelease, GitRepository, HelmRepository, and OCIRepository resources for source trust, SOPS encryption, prune blast-radius, ServiceAccount scope, and upgrade remediation safety.",
+  "source_type": "original",
+  "official_docs": [
+    "https://fluxcd.io/flux/components/kustomize/kustomizations/",
+    "https://fluxcd.io/flux/components/helm/helmreleases/",
+    "https://fluxcd.io/flux/components/source/gitrepositories/",
+    "https://fluxcd.io/flux/guides/repository-structure/",
+    "https://fluxcd.io/flux/security/secrets-management/",
+    "https://fluxcd.io/flux/installation/configuration/multitenancy/"
+  ],
+  "security_notes": "Plaintext Kubernetes Secret manifests committed to a FluxCD Git source are exposed to anyone with repo read access — including CI systems, PR participants, and auditors. GitRepository sources without commit signature verification allow any commit (including injected ones) to deploy to production.",
+  "last_verified": "2026-05-02",
+  "path": "skills/fluxcd/fluxcd-kustomization-helmrelease-review",
+  "author": "github: Raishin",
+  "version": "0.1.0"
+}

package/skills/fluxcd/fluxcd-kustomization-helmrelease-review/references/workflow-and-output.md

@@ -0,0 +1,243 @@
+# Workflow and output contract
+
+Use this reference only when performing a full FluxCD Kustomization or HelmRelease review, producing implementation guidance, triaging a GitOps drift incident, or completing a production-readiness pass.
+
+## Review domains
+
+Check these areas before giving a verdict:
+
+- `GitRepository` source trust: commit signature verification, semver pinning, SOPS decryption config
+- `Kustomization` ServiceAccount scoping, prune safety, and health check completeness
+- `HelmRelease` chart version pinning, upgrade remediation strategy, and timeout settings
+- `HelmRepository` and `OCIRepository` source authentication and trust
+- SOPS encryption status: whether Secret manifests in Git are encrypted
+- Multi-tenant ServiceAccount isolation: whether tenant Kustomizations use scoped SAs
+
+## Safe workflow
+
+1. **Frame scope**
+   - Cluster name and environment (dev / staging / production):
+   - Flux version (`flux version`):
+   - Number of Kustomizations and HelmReleases under review:
+   - Multi-tenant mode in use (yes / no):
+   - Required outcome:
+   - Explicit non-goals:
+
+2. **Collect evidence**
+   - Prefer user-provided sanitized resource YAML as primary evidence.
+   - Supplement with `flux get all -A` and `flux get sources all -A` output if available.
+   - Label each finding as `live evidence`, `user-provided evidence`, `documentation-based`, or `inference`.
+
+3. **Assess GitRepository source trust**
+   Review `spec.ref` type and value, signature verification, and interval:
+   ```yaml
+   apiVersion: source.toolkit.fluxcd.io/v1
+   kind: GitRepository
+   metadata:
+     name: fleet-infra
+     namespace: flux-system
+   spec:
+     interval: 1m
+     url: https://github.com/org/fleet-infra
+     ref:
+       # SAFE: pinned branch
+       branch: main
+       # HIGH risk: unbound semver — any tag triggers deploy
+       # semver: ">=0.0.0"
+     verify:
+       # REQUIRED for production: commit GPG signature verification
+       mode: HEAD
+       secretRef:
+         name: pgp-public-keys
+   ```
+   Absence of `spec.verify.secretRef` on a production source is a HIGH finding.
+   `spec.ref.semver: ">=0.0.0"` is a HIGH finding.
+
+4. **Verify SOPS encryption**
+   Check whether `Secret` kind manifests exist in the Git repository unencrypted:
+   ```bash
+   # Find unencrypted Secret manifests in the repo
+   grep -rl 'kind: Secret' . | xargs grep -L 'sops:'
+
+   # CORRECT: SOPS-encrypted secret — sops: field present
+   apiVersion: v1
+   kind: Secret
+   metadata:
+     name: db-credentials
+   sops:
+     kms:
+       - arn: arn:aws:kms:us-east-1:111122223333:key/...
+   data:
+     password: ENC[AES256_GCM,data:...,type:str]
+
+   # CRITICAL: plaintext secret committed to Git
+   apiVersion: v1
+   kind: Secret
+   data:
+     password: cGFzc3dvcmQ=   # base64 only — trivially decodable
+   ```
+   Any plaintext `Secret` manifest in a Git source is a CRITICAL finding.
+
+5. **Assess Kustomization ServiceAccount and prune settings**
+   ```yaml
+   apiVersion: kustomize.toolkit.fluxcd.io/v1
+   kind: Kustomization
+   metadata:
+     name: tenant-a-workloads
+     namespace: flux-system
+   spec:
+     interval: 5m
+     path: ./clusters/prod/tenant-a
+     prune: true
+     # REQUIRED: scoped SA — otherwise kustomize-controller SA (cluster-admin) is used
+     serviceAccountName: tenant-a-reconciler
+     sourceRef:
+       kind: GitRepository
+       name: fleet-infra
+     healthChecks:
+       - apiVersion: apps/v1
+         kind: Deployment
+         name: api-server
+         namespace: tenant-a
+   ```
+   Missing `serviceAccountName` is a HIGH finding. `prune: true` on a Kustomization covering
+   StatefulSets or PVCs without prune-disabled annotations is a HIGH finding.
+   Missing `healthChecks` means Flux reports Applied even when Deployments are crash-looping.
+
+6. **Protect stateful resources from prune**
+   ```yaml
+   # Add this annotation to any resource that must never be pruned
+   metadata:
+     annotations:
+       kustomize.toolkit.fluxcd.io/prune: disabled
+   ```
+   Review whether CRDs, PVCs, and namespaces containing production databases carry this annotation
+   when `spec.prune: true` is set on the parent Kustomization.
+
+7. **Assess HelmRelease version pinning and remediation**
+   ```yaml
+   apiVersion: helm.toolkit.fluxcd.io/v2
+   kind: HelmRelease
+   metadata:
+     name: nginx-ingress
+     namespace: ingress-nginx
+   spec:
+     interval: 10m
+     chart:
+       spec:
+         chart: ingress-nginx
+         # SAFE: pinned version
+         version: "4.9.1"
+         # HIGH risk: floating version — any new chart triggers auto-upgrade
+         # version: "*"
+         sourceRef:
+           kind: HelmRepository
+           name: ingress-nginx
+     upgrade:
+       remediation:
+         # SAFE: bounded retries
+         retries: 3
+         remediateLastFailure: true
+         # MEDIUM risk: infinite retries block reconciliation loops
+         # retries: -1
+     timeout: 5m
+   ```
+
+8. **Check multi-tenant isolation**
+   In a multi-tenant Flux setup, each tenant namespace should have a dedicated ServiceAccount
+   with scoped RBAC:
+   ```yaml
+   apiVersion: v1
+   kind: ServiceAccount
+   metadata:
+     name: tenant-a-reconciler
+     namespace: tenant-a
+   ---
+   apiVersion: rbac.authorization.k8s.io/v1
+   kind: RoleBinding
+   metadata:
+     name: tenant-a-reconciler
+     namespace: tenant-a
+   subjects:
+     - kind: ServiceAccount
+       name: tenant-a-reconciler
+       namespace: tenant-a
+   roleRef:
+     kind: ClusterRole
+     name: edit
+     apiGroup: rbac.authorization.k8s.io
+   ```
+   If all Kustomizations use the default `flux-system/kustomize-controller` SA, any tenant's Git
+   source compromise gives cluster-admin-equivalent write to the entire cluster.
+
+9. **Validate Flux health**
+   ```bash
+   # Check overall Flux reconciliation status
+   flux get all -A
+
+   # Check specific Kustomization
+   flux get kustomization <name> -n flux-system
+
+   # Check HelmRelease status
+   flux get helmrelease <name> -n <namespace>
+
+   # Check GitRepository source
+   flux get source git <name> -n flux-system
+
+   # Force reconciliation for testing
+   flux reconcile kustomization <name> --with-source
+
+   # Verify commit signature verification config
+   kubectl get gitrepository <name> -n flux-system -o jsonpath='{.spec.verify}'
+   ```
+
+## Output contract
+
+Return this structure:
+
+```markdown
+# FluxCD Kustomization and HelmRelease Review: <scope>
+
+## Executive verdict
+- Status: READY / READY WITH RISKS / NOT READY / NEEDS EVIDENCE
+- Biggest risk:
+- Evidence level:
+
+## Scope and assumptions
+- Cluster / namespace:
+- Flux version:
+- Resources reviewed:
+- Confirmed:
+- Unknown:
+- Out of scope:
+
+## Findings
+
+| Severity | Resource | Field | Finding | Evidence | Why it matters | Minimum safe action |
+|---|---|---|---|---|---|---|
+
+## Source trust summary
+
+| Source name | Kind | Ref type | Commit verification | SOPS enabled |
+|---|---|---|---|---|
+
+## Kustomization summary
+
+| Name | Namespace | ServiceAccount | Prune | Health checks |
+|---|---|---|---|---|
+
+## HelmRelease summary
+
+| Name | Chart version | Upgrade retries | Timeout |
+|---|---|---|---|
+
+## Recommended actions
+1. <action> — owner: <owner>, validation: <check>, rollback: <rollback>
+
+## Validation
+- Commands or checks:
+- Expected result:
+
+## Residual risk
+- <risk or explicit none>
+```

package/skills/istio/README.md

@@ -0,0 +1,28 @@
+# 🕸️ Istio Skills
+
+<p align="center">
+  <!-- 🖼️ Add an Istio logo to assets/logos/cnative/istio/ and update this path -->
+  <span style="font-size:3.5em">🕸️</span>
+</p>
+
+This folder contains Istio-focused skills curated for this marketplace.
+
+## Local marketplace portfolio
+
+This folder contains **1** local Istio skill:
+
+- `istio-ambient-mesh-review`
+
+## Portfolio posture
+
+Istio skills for evidence-backed service mesh review covering both **sidecar mode** and **ambient mode** (ztunnel + optional waypoint proxies). Ambient mode introduces a layered architecture where L4 zero-trust is enforced at ztunnel and L7 features require an explicit waypoint deployment.
+
+These skills are intentionally conservative:
+
+- prefer `kubectl get peerauthentication,authorizationpolicy,gateway,virtualservice,destinationrule,sidecar -A -o yaml` for live mesh state grounding before any review
+- treat **L7 `AuthorizationPolicy` rules in ambient mode without a waypoint** as a critical finding — the L7 fields are silently ignored when ztunnel handles the traffic alone
+- challenge `PeerAuthentication` with `mode: PERMISSIVE` or `DISABLE` in production — mTLS must be `STRICT`
+- challenge mesh-wide `PeerAuthentication` changes — the blast radius is the whole mesh
+- use official Istio documentation (istio.io) for ambient architecture, ztunnel internals, waypoint placement, HBONE protocol, and `AuthorizationPolicy` semantic differences between sidecar and ambient modes
+
+Run `npm run validate` after changing cataloged Istio skills.

package/skills/istio/istio-ambient-mesh-review/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: istio-ambient-mesh-review
+description: Use this skill for Istio service mesh review across both sidecar mode and ambient mode (ztunnel L4 + optional waypoint L7). Covers PeerAuthentication, AuthorizationPolicy, RequestAuthentication, Gateway, VirtualService, DestinationRule, Sidecar, and waypoint placement. Trigger when the user asks whether an Istio policy is correct, whether mTLS is strict, whether L7 AuthorizationPolicy will actually be enforced in ambient mode, or whether a mesh-wide PeerAuthentication change is safe.
+allowed-tools: Read Grep Glob
+metadata:
+  author: "github: Raishin"
+  version: "0.1.0"
+  updated: "2026-05-05"
+  category: security
+---
+
+# Istio Ambient Mesh Review
+
+## Purpose
+
+Review Istio configuration against zero-trust correctness and the most common ambient-mode trap: **L7 `AuthorizationPolicy` rules silently ignored when no waypoint is deployed**. Ambient mode uses ztunnel for L4 zero-trust on every node, but L7 features (HTTP method, path, JWT claim matching, request header inspection) require an explicit waypoint proxy. Without one, the L7 rules in the policy are accepted but never enforced.
+
+## Lean operating rules
+
+- Prefer live cluster evidence (`kubectl get peerauthentication,authorizationpolicy,requestauthentication,gateway,virtualservice,destinationrule,sidecar -A -o yaml` plus `istioctl analyze` and `istioctl x ztunnel-config`) when the active client exposes it; otherwise fall back to official Istio documentation (istio.io) and sanitized YAML.
+- Separate confirmed facts from inference. If mesh mode (sidecar vs ambient), waypoint deployment, and namespace labels were not queried, say so.
+- **Ambient L7 policy without a waypoint is a critical finding** — the policy looks active, the API server accepts it, but ztunnel only enforces L4. The L7 fields are silently bypassed.
+- Treat `PeerAuthentication` with `mode: PERMISSIVE` or `mode: DISABLE` in production as a critical finding — mTLS is the foundation of mesh zero-trust.
+- Treat any mesh-wide (root namespace) `PeerAuthentication` change as a critical-blast-radius finding — the entire mesh is affected at once.
+- Challenge `AuthorizationPolicy` with `action: ALLOW` and broad `from` selectors — the default action when no policy is provisioned is ALLOW, so the only thing that creates zero-trust is a deny policy or an explicit ALLOW with bounded scope.
+- Challenge `RequestAuthentication` JWKs URL changes — JWT validation depends on this.
+- Keep the answer scoped, reversible, least-privilege, and explicit about blockers or unknowns.
+
+## References
+
+Load these only when needed:
+
+- [Evidence path and tooling](references/mcp-and-evidence.md) — use when choosing live cluster evidence, confirming mesh mode and waypoint deployment, or switching to documentation mode.
+- [Workflow and output contract](references/workflow-and-output.md) — use when executing the full review, applying ambient/sidecar stress checks, or formatting the final answer.
+- [Official sources](references/official-sources.md) — use when you need the detailed Istio documentation list, ambient mode internals, and grounded insights.
+
+## Response minimum
+
+Return, at minimum:
+
+- the scoped target (mesh-wide vs namespace-scoped vs workload-scoped) and evidence level,
+- the mesh mode (sidecar, ambient, mixed) and the waypoint deployment state for the workloads involved,
+- the mTLS posture (`STRICT` / `PERMISSIVE` / `DISABLE`) on PeerAuthentication,
+- the AuthorizationPolicy enforcement layer (L4 ztunnel-enforced vs L7 waypoint-enforced) and whether L7 rules will actually run,
+- the safest next actions and rollback plan,
+- the assumptions or blockers that prevent stronger conclusions.

package/skills/istio/istio-ambient-mesh-review/metadata.json

@@ -0,0 +1,30 @@
+{
+  "id": "istio-ambient-mesh-review",
+  "name": "Istio Ambient Mesh Review",
+  "type": "skill",
+  "provider": "istio",
+  "harnesses": [
+    "codex",
+    "claude-code",
+    "cursor",
+    "gemini",
+    "kiro",
+    "other"
+  ],
+  "summary": "Review Istio service mesh configuration across both sidecar mode and ambient mode (ztunnel + waypoint), with focus on the ambient L7 policy trap, PeerAuthentication mTLS posture, AuthorizationPolicy enforcement layer, and mesh-wide blast radius.",
+  "source_type": "original",
+  "official_docs": [
+    "https://istio.io/latest/docs/",
+    "https://istio.io/latest/docs/ambient/overview/",
+    "https://istio.io/latest/docs/ambient/usage/l4-policy/",
+    "https://istio.io/latest/docs/ambient/usage/waypoint/",
+    "https://istio.io/latest/docs/overview/dataplane-modes/",
+    "https://istio.io/latest/docs/reference/config/security/peer_authentication/",
+    "https://istio.io/latest/docs/reference/config/security/authorization-policy/"
+  ],
+  "security_notes": "L7 AuthorizationPolicy rules in ambient mode are silently ignored when no waypoint is deployed — ztunnel only enforces L4. PeerAuthentication PERMISSIVE or DISABLE in production breaks mesh zero-trust. Mesh-wide root-namespace PeerAuthentication change has cluster-wide blast radius.",
+  "last_verified": "2026-05-01",
+  "path": "skills/istio/istio-ambient-mesh-review",
+  "author": "github: Raishin",
+  "version": "0.1.0"
+}

package/skills/istio/istio-ambient-mesh-review/references/mcp-and-evidence.md

@@ -0,0 +1,59 @@
+# Evidence Path and Tooling
+
+## Evidence path
+
+1. Prefer live cluster evidence when a Kubernetes MCP server, `kubectl`, and `istioctl` are available against the mesh's primary cluster.
+2. Fall back to the official Istio documentation (istio.io) for ambient/sidecar architecture, policy semantics, and CRD schema when live inspection is unavailable.
+3. Ask only for sanitized YAML for the affected resources (`PeerAuthentication`, `AuthorizationPolicy`, `RequestAuthentication`, `Gateway`, `VirtualService`, `DestinationRule`, `Sidecar`, namespace labels) when current-state proof matters.
+4. Label conclusions as `live evidence`, `documentation-based`, `sanitized user evidence`, or `inference`.
+
+## Useful live-evidence commands
+
+```shell
+# All Istio security and traffic policies across the cluster
+kubectl get peerauthentication,authorizationpolicy,requestauthentication,gateway,virtualservice,destinationrule,sidecar -A -o yaml
+
+# Confirm mesh mode (ambient vs sidecar) — namespace labels
+kubectl get namespaces --show-labels | grep -E 'istio.io/dataplane-mode|istio-injection'
+
+# Ambient: list waypoint deployments and bindings
+kubectl get gateways.gateway.networking.k8s.io -A -l istio.io/waypoint-for
+kubectl get pods -A -l gateway.networking.k8s.io/gateway-name
+
+# Inspect ztunnel state on each node
+kubectl -n istio-system get daemonset ztunnel
+istioctl x ztunnel-config workload      # what ztunnel sees as in-mesh workloads
+istioctl x ztunnel-config policies      # what L4 policies ztunnel is enforcing
+istioctl x ztunnel-config services      # service-to-workload mapping
+
+# Validate proposed changes before applying
+istioctl analyze -n <namespace>
+istioctl analyze --recursive .
+
+# For sidecar mode: which workloads have sidecars injected
+kubectl get pods -A -o jsonpath='{range .items[?(@.metadata.annotations.sidecar\.istio\.io/inject!="false")]}{.metadata.namespace}/{.metadata.name}{"\n"}{end}'
+
+# Inspect effective policy at a specific workload
+istioctl proxy-config listener <pod>.<namespace>
+istioctl proxy-config cluster <pod>.<namespace>
+istioctl authz check <pod>.<namespace>
+
+# Mesh control-plane state
+kubectl -n istio-system get deploy istiod -o yaml
+istioctl version
+istioctl proxy-status
+```
+
+## Mesh state to confirm before review
+
+- **Mesh mode per namespace** — sidecar (`istio-injection=enabled`), ambient (`istio.io/dataplane-mode=ambient`), or none. A single mesh can mix modes; conclusions differ.
+- **Waypoint deployment for ambient namespaces** — `kubectl get gateways.gateway.networking.k8s.io -n <namespace> -l istio.io/waypoint-for`. Without a waypoint, L7 AuthorizationPolicy rules in that namespace are not enforced.
+- **Istio version** (`istioctl version`) — ambient went GA in 1.24; older versions have different semantics.
+- **Whether `PeerAuthentication` exists in the mesh root namespace** (default `istio-system` or whatever `meshConfig.rootNamespace` points to). Mesh-wide policies live there.
+- **Whether multi-cluster (multi-primary or primary-remote)** is in use — `AuthorizationPolicy` evaluation crosses cluster boundaries when mesh networking is configured.
+
+## Sanitization rules
+
+- Never request kubeconfig contents, mesh root CA private keys, JWKs private keys, or workload service-account tokens.
+- Replace identifiable cluster URLs, JWT issuer URLs (when sensitive), and namespace names with placeholders unless the user provides them.
+- Do not print Istio root CA certificates beyond their public certificate body.

package/skills/istio/istio-ambient-mesh-review/references/official-sources.md

@@ -0,0 +1,32 @@
+# Official Sources
+
+Load these only when needed:
+
+- [Istio documentation home](https://istio.io/latest/docs/) — use as the entry point for any Istio question.
+- [Choosing between sidecar and ambient](https://istio.io/latest/docs/overview/dataplane-modes/) — use when deciding mesh mode or auditing a mixed-mode mesh.
+- [Ambient mode overview](https://istio.io/latest/docs/ambient/overview/) — use for the layered architecture (ztunnel L4 + optional waypoint L7), HBONE protocol, and zero-trust posture.
+- [L4 Authorization Policy in ambient](https://istio.io/latest/docs/ambient/usage/l4-policy/) — use for the L4-only fields ztunnel enforces and the default-ALLOW behavior.
+- [Waypoint configuration](https://istio.io/latest/docs/ambient/usage/waypoint/) — use for waypoint deployment, binding via `istio.io/use-waypoint`, and the L7 features that require it.
+- [PeerAuthentication API reference](https://istio.io/latest/docs/reference/config/security/peer_authentication/) — use for `STRICT` / `PERMISSIVE` / `DISABLE` semantics, mesh-wide vs namespace-scoped vs workload-scoped placement, and port-level overrides.
+- [AuthorizationPolicy API reference](https://istio.io/latest/docs/reference/config/security/authorization-policy/) — use for `ALLOW` / `DENY` / `AUDIT` / `CUSTOM` actions, evaluation order, source/destination matchers, and L4 vs L7 field semantics.
+- [RequestAuthentication API reference](https://istio.io/latest/docs/reference/config/security/request_authentication/) — use for JWT validation, `jwksUri`, `issuer`, `audiences`, `forwardOriginalToken`.
+- [Gateway API reference](https://istio.io/latest/docs/reference/config/networking/gateway/) — use for ingress/egress gateway TLS modes, port configuration, and `credentialName` SDS pattern.
+- [VirtualService API reference](https://istio.io/latest/docs/reference/config/networking/virtual-service/) — use for `match`, `rewrite`, `redirect`, `route` weighting, fault injection, retry, timeout.
+- [DestinationRule API reference](https://istio.io/latest/docs/reference/config/networking/destination-rule/) — use for client-side mTLS, load balancing, connection pool, outlier detection, subset definitions.
+- [Sidecar API reference](https://istio.io/latest/docs/reference/config/networking/sidecar/) — use for narrowing sidecar `egress.hosts` and reducing config-distribution overhead.
+- [Multi-cluster setup guides](https://istio.io/latest/docs/setup/install/multicluster/) — use when the mesh spans clusters (multi-primary, primary-remote, multi-network).
+- [istioctl reference](https://istio.io/latest/docs/reference/commands/istioctl/) — use for `istioctl analyze`, `istioctl x ztunnel-config`, `istioctl proxy-config`, `istioctl authz check`.
+- [Istio Releases](https://istio.io/latest/news/releases/) — use when version-specific features matter (ambient GA in 1.24, waypoint API stabilization, etc.).
+
+## Grounded insights worth carrying into the skill
+
+- Ambient mode is a **layered architecture**: ztunnel handles L4 zero-trust for every pod in the mesh by default, and waypoint proxies are added only for the workloads that need L7 features (HTTP method/path matching, JWT claim authorization, request header inspection, traffic management).
+- **An L7 `AuthorizationPolicy` rule on an ambient namespace with no waypoint is silently ignored.** The API server accepts the policy, but ztunnel only enforces L4 fields. This is the most-cited operational trap in ambient mode.
+- The default action when no `AuthorizationPolicy` exists is **ALLOW**. Zero-trust posture requires explicit `DENY` policies or narrow `ALLOW` policies that collectively leave nothing reachable. `DENY` is evaluated before `ALLOW`.
+- `PeerAuthentication` mTLS modes inherit from mesh → namespace → workload, with the most-specific policy winning. A mesh-wide `STRICT` policy can be locally weakened by a workload-scoped `DISABLE` policy on a specific port.
+- Ambient mode requires **no pod restart** to add a workload to the mesh — labeling the namespace `istio.io/dataplane-mode=ambient` is sufficient. This is operationally simpler than sidecar injection but means changes can propagate faster than reviewers expect.
+- The mesh root namespace (default `istio-system`, configurable via `meshConfig.rootNamespace`) is the only place where mesh-wide `PeerAuthentication` and `AuthorizationPolicy` can be authored. Anything there has cluster-wide blast radius.
+- Waypoint placement uses Gateway API resources (`gateways.gateway.networking.k8s.io`) labeled `istio.io/waypoint-for`. A namespace-level waypoint protects all workloads in the namespace; a ServiceAccount-level waypoint protects all workloads using that SA; a workload-level waypoint binds via `istio.io/use-waypoint` annotation.
+- ztunnel uses the **HBONE protocol** (HTTP/2 over mTLS, port 15008) for ztunnel-to-ztunnel communication. Network policy that blocks 15008 between nodes will break ambient mesh traffic.
+- Sidecar mode and ambient mode workloads can communicate within one mesh — Istio bridges between them transparently. Ambient pods see sidecar pod connections as mTLS-authenticated peers.
+- `istioctl analyze` runs the same checks Istiod runs at startup and is the safest pre-apply validator. CI pipelines should run it on every Istio config change.

package/skills/istio/istio-ambient-mesh-review/references/workflow-and-output.md

@@ -0,0 +1,128 @@
+# Workflow and Output Contract
+
+## Workflow
+
+### Step 1 — Identify mesh mode for the affected namespaces
+
+Istio supports three deployment modes that can coexist in one mesh. The review path differs based on mode.
+
+1. **Sidecar mode** — pods have an Envoy sidecar injected. Namespace labeled `istio-injection=enabled`. All policy is enforced at the sidecar.
+2. **Ambient mode** — no sidecars; ztunnel runs as a per-node DaemonSet for L4 zero-trust + optional waypoint proxies for L7. Namespace labeled `istio.io/dataplane-mode=ambient`.
+3. **Mixed** — some workloads in a namespace use sidecars, others use ambient. Verify per-pod with annotations.
+
+Reference: [Choosing between sidecar and ambient](https://istio.io/latest/docs/overview/dataplane-modes/) and [Ambient mode overview](https://istio.io/latest/docs/ambient/overview/).
+
+### Step 2 — Confirm waypoint deployment for ambient namespaces (the L7 trap)
+
+This is the most important ambient-specific check. Without a waypoint, L7 `AuthorizationPolicy` rules are silently ignored.
+
+1. List waypoints: `kubectl get gateways.gateway.networking.k8s.io -n <namespace> -l istio.io/waypoint-for`.
+2. Confirm the waypoint binding label on the namespace, ServiceAccount, or workload (`istio.io/use-waypoint: <waypoint-name>`).
+3. Cross-reference any `AuthorizationPolicy` that uses L7 fields (`to.operation.methods`, `to.operation.paths`, `to.operation.hosts`, `when` keys for `request.headers`, `request.auth.claims`) — if no waypoint is bound to the workload, **the L7 rules are accepted by the API server but never enforced**.
+
+The L4 fields that ztunnel enforces without a waypoint:
+
+- `from.source.principals` (SPIFFE identities — the workload's ServiceAccount mTLS identity)
+- `from.source.namespaces`
+- `to.operation.ports`
+- `when` keys: `source.principal`, `source.namespace`, `destination.port`, `connection.sni`
+
+Reference: [L4 Authorization Policy in ambient](https://istio.io/latest/docs/ambient/usage/l4-policy/) and [Waypoint configuration](https://istio.io/latest/docs/ambient/usage/waypoint/).
+
+### Step 3 — Audit `PeerAuthentication`
+
+`PeerAuthentication` controls workload-to-workload mTLS. Three modes exist with very different security properties:
+
+1. **`STRICT`** — all peer connections must use mTLS. Plaintext connections are rejected. Production target.
+2. **`PERMISSIVE`** — accepts both mTLS and plaintext. Useful only during migration.
+3. **`DISABLE`** — disables mTLS. Plaintext only.
+
+Stress-tests:
+
+- **Mesh-wide PeerAuthentication** lives in the mesh root namespace (default `istio-system`). A change here affects every workload in every namespace simultaneously. Treat as critical-blast-radius.
+- **Namespace-scoped PeerAuthentication** with `mode: PERMISSIVE` in production is a finding — there is no migration in progress; this is technical debt.
+- **Workload-scoped PeerAuthentication** with `mode: DISABLE` for a specific port (e.g., a health-check port) is sometimes legitimate but always requires justification.
+- A namespace with **no `PeerAuthentication`** inherits mesh-wide. If mesh-wide is `PERMISSIVE`, the namespace is also `PERMISSIVE`.
+
+Reference: [PeerAuthentication API](https://istio.io/latest/docs/reference/config/security/peer_authentication/).
+
+### Step 4 — Audit `AuthorizationPolicy`
+
+`AuthorizationPolicy` controls who can talk to whom. Default action when no policy exists is **ALLOW** — there is no implicit deny. Zero-trust requires explicit deny policies or explicit narrow ALLOW policies that combine to leave nothing reachable by default.
+
+Three actions: `ALLOW`, `DENY`, `CUSTOM`, `AUDIT`.
+
+1. **`DENY` policies are evaluated first**, then `ALLOW`. If multiple match, DENY wins.
+2. **Empty `rules` with `action: DENY`** denies everything — total lockdown.
+3. **`action: ALLOW` with no `from` block** allows from anywhere — only useful for narrowing by `to`.
+4. **`action: ALLOW` with `from.source.principals: ['*']`** is also "anywhere" — no practical narrowing.
+
+Stress-tests:
+
+- An `AuthorizationPolicy` with `action: ALLOW` and `from.source.namespaces: ['*']` is a documentation-only deny — it allows all and denies none.
+- L7 fields (`to.operation.methods`, `request.auth.claims`) in ambient mode without a waypoint are silently bypassed.
+- `action: AUDIT` is a logging-only mode that does not enforce — use only for migration.
+- Multi-cluster mesh: `AuthorizationPolicy` in one cluster can affect workloads called from another cluster; verify mesh networking topology.
+
+Reference: [AuthorizationPolicy API](https://istio.io/latest/docs/reference/config/security/authorization-policy/).
+
+### Step 5 — Audit `RequestAuthentication`
+
+`RequestAuthentication` defines JWT validation — `jwksUri`, `issuer`, `audiences`, `forwardOriginalToken`. Key concerns:
+
+1. **JWKs URI rotation** — if the issuer rotates signing keys, Istio caches the JWKs response. The `jwksUri` URL must remain reachable; outages here cause every JWT to fail.
+2. **`forwardOriginalToken: true`** with sensitive JWTs forwards the bearer token to backend services — they must be trusted.
+3. **`audiences: []` or missing** — accepts JWTs intended for any audience. Cross-service token replay risk.
+4. **Multiple `RequestAuthentication` for the same workload** — Istio combines them. A misconfigured second one can weaken a strict first one.
+
+Reference: [RequestAuthentication API](https://istio.io/latest/docs/reference/config/security/request_authentication/).
+
+### Step 6 — Audit `Gateway`, `VirtualService`, `DestinationRule`, `Sidecar`
+
+Traffic routing concerns:
+
+- **`Gateway` with `tls.mode: SIMPLE` and no `credentialName`** — broken or insecure TLS termination.
+- **`Gateway` with `tls.mode: PASSTHROUGH`** plus L7 routing in `VirtualService` — incompatible (passthrough cannot be inspected).
+- **`VirtualService.http.route` with `weight`-based traffic split** — verify total weights sum to 100; otherwise traffic is dropped.
+- **`DestinationRule.trafficPolicy.tls.mode: DISABLE`** on production destinations — disables Istio-side mTLS to the destination.
+- **`Sidecar` resource with `egress.hosts: ['*/*']`** — disables egress restriction.
+
+Reference: [Gateway API](https://istio.io/latest/docs/reference/config/networking/gateway/), [VirtualService API](https://istio.io/latest/docs/reference/config/networking/virtual-service/), [DestinationRule API](https://istio.io/latest/docs/reference/config/networking/destination-rule/), [Sidecar API](https://istio.io/latest/docs/reference/config/networking/sidecar/).
+
+### Step 7 — Validate with `istioctl analyze`
+
+`istioctl analyze` runs the same checks the control plane runs and surfaces structural problems. Run it on the proposed YAML before applying:
+
+```shell
+istioctl analyze -n <namespace>            # one namespace
+istioctl analyze --all-namespaces          # whole mesh
+istioctl analyze --recursive ./manifests/  # offline against files
+```
+
+Common findings:
+
+- `IST0101` — referenced resource not found (e.g., `VirtualService` references a missing host).
+- `IST0118` — port name not following Istio's protocol convention (e.g., `tcp` vs `tcp-mysql`).
+- `IST0127` — namespace not labeled for injection.
+
+## Output
+
+Return:
+
+- **target**: the resource and its scope (mesh-wide, namespace, workload),
+- **evidence level**: `live evidence` / `documentation-based` / `sanitized user evidence` / `inference`,
+- **mesh mode**: sidecar, ambient, or mixed for the affected workloads,
+- **waypoint state**: deployed and bound, missing, or not applicable (sidecar mode),
+- **L7 enforcement assessment**: whether L7 fields will actually run, with explicit "silently ignored" callouts where applicable,
+- **mTLS posture**: `STRICT` / `PERMISSIVE` / `DISABLE` per workload / namespace / mesh,
+- **risk findings** (with severity: high / medium / low),
+- **safest next actions** with sample manifest changes and `istioctl analyze` output,
+- **rollback plan**: how to revert the change without breaking mesh traffic mid-flight,
+- **assumptions and missing facts**.
+
+## Security notes
+
+- Never recommend `PeerAuthentication` `mode: PERMISSIVE` or `DISABLE` for production without a documented mTLS migration plan with a date.
+- Never recommend a mesh-wide root-namespace policy change without staged rollout (single namespace first, observe, expand).
+- Never recommend disabling waypoint enforcement for an ambient namespace if any L7 `AuthorizationPolicy` exists for that namespace.
+- Do not print Istio root CA private keys or JWKs private keys.