Infra Plugin
The four /infra:* skills (start/design/implement/review), and the boundary with the architect pipeline
infra is the fourth plugin, added in v0.29.0. It’s a component that comes into play only when dealing with cloud infrastructure (Terraform, Kubernetes, and similar tools for assembling servers and networks as code), and unlike product/architect, it is not a pipeline. It has no manifest (a configuration file that manages execution order), is not called from /architect:pipeline, and does not appear in the state-management dashboard.
Knowledge bundle
All of infra’s answers are grounded in the 23 documents contained in the folder knowledge/okf-k8s-tf/. This is a
OKFOKF (Open Knowledge Format)A documentation format standard that structures technical knowledge into three tiers: confirmed facts, design recommendations, and questions that don't yet have answers.See in glossary
v0.2 knowledge bundle (a pre-assembled collection of technical knowledge) covering Terraform, Kubernetes, Helm, Kustomize, Argo CD, GitLab CI/CD, Docker+Cosign, Vault, External Secrets, Prometheus/Grafana, and Kyverno.
This bundle is vendored (a copy stored directly in this repository) rather than included as a submodule (a reference to another repository), because the source repository it was fetched from has been deleted — the copy in this repository is the source of record (the final, authoritative place where the correct version is kept).
Commands
| Command | Model | What it does |
|---|---|---|
/infra:start |
sonnet | Triage (the initial routing). Resolves the knowledge bundle described above, checks its freshness, determines the target environment and cloud, and routes to the appropriate mode |
/infra:design |
opus | Decides on the configuration and outputs a design document, an environment matrix (a table listing configuration differences across environments), and an ADRADR (Architecture Decision Record)A document that records why a particular design was chosen and why other options were not.See in glossary |
/infra:implement |
sonnet | Writes Terraform / Kubernetes manifests / Helm values (configuration values for the Helm packaging format) / Kustomize overlays (a mechanism that layers only the per-environment differences) / CI into the actual infrastructure repository |
/infra:review |
opus | Evaluates existing code or design documents and outputs severity-tagged findings (a record of identified issues) |
Because /infra:start pins down the bundle, freshness, environment, and cloud before handing off downstream, each mode’s skill doesn’t re-ask the same questions.
Work proceeds in the order design → user confirmation → implement, so implementation never proceeds on a design that hasn’t been agreed to.
Detailed flow of each skill
The table above is a summary. You can expand each skill below to see what it actually does.
/infra:start — Triage (the initial routing)
It pins down the following four items before handing off to downstream skills. Once these are settled, design/implement/review don’t re-ask the same questions.
- Resolving the knowledge bundle and checking its freshness. Runs
tools/update-okf-bundle.sh status --bundle=k8s-tfand checks whether any document has passed itsstale_afterdate (the threshold past which the information may be out of date) - Determining the target environment. One of
local/test/staging/production. If there are multiple, a separate section is prepared for each - Determining the target cloud. AWS / Azure / GCP. Since multi-cloud is the default assumption, it doesn’t default to a single cloud
- Determining the mode. Decides which skill to route to based on the following criteria
| What the user wants to do | Routed to |
|---|---|
| Decide on a configuration from requirements, make technology choices | /infra:design |
| Write or fix Terraform/manifests/CI | /infra:implement |
| Evaluate existing code or design documents | /infra:review |
When the routing is unclear, it asks just one question. A compound request like “design it and then implement it” is always split into the order design → user confirmation → implement, so implementation never proceeds on a design that hasn’t been agreed to.
/infra:design — Designing the configuration (opus)
The output is a design document, an environment matrix, and an ADR. No implementation code is written here.
Turn requirements into numbers
Adjectives like “highly available” or “fast” aren’t treated as requirements. Availability targets, RTO/RPO (target time to recovery and the amount of data loss that’s acceptable), performance, data retention period, budget, and regulatory or data-residency constraints are written down as numbers, or as “a provisional value and the reasoning behind it.”
Pin down the multi-cloud and environment assumptions
Fills in a cloud × environment table. A blank cell means “not deployed there,” so nothing is left blank by omission.
Decide ownership assignments
Tabulates which of Terraform/Argo CD/CI/manual operations manages each resource, and immediately checks that no resource has two or more managers (one owner per resource).
Design layer by layer (L1–L4)
Working in order from L1 (cloud-specific) to L4 (application), each layer states explicitly what stays identical across environments and what’s allowed to differ.
Write the apply flow and a change-impact matrix
Writes down who applies what and in what order, and tabulates the scope affected by a given change — for example, “what should be checked at the same time when upgrading the Kubernetes version.”
Design the environment-diff table and the promotion path
Summarizes the differences across environments on a single page, and designs the cross-environment promotion path to operate at the image-digest level (a fixed hash value computed from the contents of the container image itself — a finer-grained unit than a code version or tag).
Record decisions as ADRs and leave Open Questions
Every decision that had two or more options is recorded as an ADR. Anything that can’t yet be decided is explicitly marked “TBD,” rather than left blank.
/infra:implement — Implementation (sonnet)
Assumes an agreed-upon design document already exists. If there isn’t one, a lightweight design pass is done first, deciding only ownership assignments, the target cloud, and the target environment.
The write target is the actual infrastructure repository. This is a different location from the generated/ directory that architect’s generate-infra-code writes to — see the boundary table below this page for the difference between the two.
| Target | Example required rule |
|---|---|
| Terraform | Pin the version exactly and commit .terraform.lock.hcl. Keep state (the file recording the current state of resources) in an encrypted, access-controlled remote backend, not in Git |
| Kubernetes manifests | Use a controller (Deployment, etc.) rather than creating a bare Pod directly. Set readiness/liveness probes (health checks), and decide a PDB (Pod Disruption Budget — the maximum number of Pods that may be taken down simultaneously during maintenance, etc.) |
| Helm | Pin the repository, chart, and version. Make Terraform the sole owner of a given release |
| Kustomize | Don’t write environment branching into the base (the common foundation); confine per-environment differences entirely to overlays |
| CI (GitLab CI) | Pin shared templates to a tag or commit SHA. Don’t place long-lived cloud credentials in CI variables — use OIDC (a mechanism that issues short-lived, one-time credentials) instead |
| Docker | Pin the base image by both version and digest. Record the digest immediately after the build, and reuse that same digest through scanning, signing, and deployment |
| Secrets | Sync via Vault + External Secrets Operator (a mechanism that syncs values from external secrets management into Kubernetes); don’t place plaintext secrets in Git/values/tfvars |
The write target and who applies the change vary by environment.
| Environment | Applier | Bundle grounding |
|---|---|---|
| local | The developer themselves | Not covered by the bundle |
| test | A runbook, or kubectl apply from CI |
Implementation examples exist |
| staging | Argo CD (applied automatically via GitOps) | Implementation examples exist |
| production | Argo CD + approval | No implementation examples. Designed as staging’s configuration plus approvals, protections, and sync windows |
Every implementation reports the following without exception: the target environment, the verification commands run and their results, the owner of each resource changed, related locations affected, the impact on cross-environment consistency (parity), and any Open Questions that couldn’t be resolved.
/infra:review — Review (opus)
The output is severity-tagged findings (a record of identified issues). Each finding is written in the form “path → what → impact → how to fix → source,” and no finding is issued without a way to fix it.
Three things checked first, without exception. Anything found here is written up ahead of any other finding.
- Duplicate ownership (whether two or more mechanisms manage the same resource)
- Image digest continuity (whether the same digest is used from build through scan, sign, and deploy)
- Plaintext secret exposure (whether secrets remain in plaintext anywhere in Git/values/tfvars/CI logs/Docker layers)
After that, it runs per-domain checks covering IaC, Kubernetes, delivery, secrets, observability, and policy, and always includes a multi-cloud section and an environment parity section.
The same code is evaluated differently depending on the environment (excerpt):
| Item | local | test | staging | production |
|---|---|---|---|---|
| 1 replica, no redundancy | Acceptable | Acceptable | Needs review | Not acceptable |
Direct apply (e.g. kubectl apply) |
Acceptable | Intentional design | Not acceptable (should be GitOps) | Not acceptable |
| Plaintext secrets in Git | Not acceptable | Not acceptable | Not acceptable | Not acceptable |
Items like the last row — “not acceptable in any environment, no exceptions” — are never waved through with a “it’s just local” excuse.
Severity is rated on a five-level scale — Critical/High/Medium/Low/Info — and the basic rule is that the same issue drops one level for each step down in environment (the “not acceptable in any environment” items above are the exception).
Examples of commonly found issue patterns:
- Kyverno’s
ClusterPolicy(an old policy format slated for removal in v1.20) is still in use - Container image tags are pinned only to a major version (e.g.
docker:27), without pinning down to the patch level or digest - The digest is re-resolved from the tag after the build (a cause of drift between what was scanned and what gets deployed)
- Argo CD is rolled back manually. The correct approach is to revert in Git or apply a forward-fix (push a new commit with the fix) instead
What is enforced
- Multi-cloud is the default assumption. No answer assumes a single cloud. We divide the infrastructure into four layersLayers (L1–L4)A four-tier classification specific to infra. L1 is cloud-specific (VPC, IAM, etc. — not unified); L2 is Kubernetes abstractions (Deployment, Service, etc. — fully common); L3 is platform components (Argo CD, Vault, etc. — differ only in values); L4 is the application (fully common).See in glossary, and only L1 is written differently per cloud. L2–L4 introduce no cloud branching. If three or more differences can’t be expressed in a common form, separation is chosen over abstraction
- Four environments. The base (the common configuration that forms the foundation), chart (the Helm package), and image digest (a fixed hash value computed from the contents of the container image, which guarantees that the tested binary and the one running in production are identical) are identical across every environment — per-environment differences are confined entirely to the overlay contents. No
if env == "production"-style branching is written into the base - One owner per resource. A state where two or more of Terraform/Argo CD/CI/manual operations manage the same resource becomes the highest-priority finding in a review. Without first building the ownership map (a table listing which mechanism manages which resource), other findings can’t be prioritized
- The bundle is the source of grounding. Claims carry a citation like
[foundation/terraform.md], and anything the bundle doesn’t cover is explicitly stated as not covered
There is an asymmetry in how environments are treated. local never appears in the bundle at all, and production has no observed implementation examples. As a result, it is not presented with the same level of confidence as test/staging.
Production is designed as “staging + approvals, protections, and sync windows” and recorded as an ADR — it is never written as though it already exists.
Boundary with the architect pipeline
The infra skills intentionally overlap with three of architect’s skills. Drawing a clear boundary keeps the two mechanisms from writing to the same artifacts.
| architect | infra | Boundary |
|---|---|---|
design-infrastructure |
/infra:design |
Logical design vs. concrete design |
generate-infra-code (→ generated/) |
/infra:implement |
Scaffolding vs. code intended to be merged into the actual infrastructure repository |
review-operations |
/infra:review |
Review of design documents vs. review of Terraform, manifests, and CI |