Repository navigation
Description
Part of #4639. Not blocked by map-dependencies. Consumes map-containers output for
the container-to-host mapping when that exists.
Problem
No skill produces the C4 deployment view: which containers run on which infrastructure, in which
environment. Where a project has infrastructure as code, this topology is fully declared and
machine-readable, but people still redraw it by hand. plugins/architecture/skills/ on main has no
map-deployment.
Evidence
Verified this pass (main a6ba321): the skill does not exist, and no existing issue covers IaC
topology or environment diffs. Nothing else was reproduced; the rest of this issue is carried from the
item's design.
Proposed approach
/architecture:map-deployment [environment] [--diff <env-a> <env-b>]
It reads committed IaC only (Pulumi, Terraform, Bicep/ARM, CloudFormation, Kubernetes manifests, Helm,
Compose) and extracts:
- infrastructure nodes
- the mapping of containers to compute
- network topology (VNets, subnets, private endpoints, ingress)
- per-environment parameters
The high-value feature is --diff: "what is different about production" is the question people
actually ask, usually during an incident. Prioritize the diff over diagram polish.
Design questions to settle before building:
- which IaC tool to support first
- the dialect key
- whether a live-state comparison mode is built at all. If it is, it is a separate opt-in mode with its
own label, because "what IaC declares" and "what is deployed" are different claims.
Files:
- new
plugins/architecture/skills/map-deployment/{SKILL.md,scripts,evals} - the shared redaction helper in
plugins/architecture/lib/ plugin.json,CHANGELOG.md,README.md
Acceptance criteria
- With no cloud credentials present, a multi-environment IaC fixture produces a per-environment
topology. -
--diffbetween two environments reports the real declared differences. - A fixture containing secret-shaped values produces no secret material in the output.
- The artifact states which environment and which IaC source produced it.
- A repository with two IaC tools either has both read or gets an explicit decline. It is never
half-read silently.
Constraints and gotchas
- By default: no cloud API calls, no credentials and no live state.
- Redaction is shared with map-context and map-containers. IaC files are dense with connection targets
and sometimes hold values that should not be there at all. - Out of scope: cost, scaling and capacity, and runtime health.
- Follow
.claude/rules/skill-bodies-state-current-rules.md, keep the description under 1024
codepoints, and bump the version and add a CHANGELOG entry.
Context
Source: local handoff item 20260907-094205-map-deployment-skill-proposal.md (retired into this issue).
Parent epic: #4639. Related: the map-containers and map-context issues (shared redaction
and the container mapping).
Activity
docs(architecture): tidy family skill hints, dead flags and tracker r…
fix(architecture): detect Helm structurally, refuse layered Compose a…
fix(architecture): report parameter presence, Kubernetes parameters a…
fix(architecture): label secret diffs secret-differs and diff Kuberne…
fix(architecture): record the C4 dialect syntax each map skill emits …
kyle-sexton commentedon Sep 29, 2026
Reopened. This issue was closed as completed by #5158, but the 2026-09-29 audit of the Cursor run found the delivery partial and defective.
What the audit found
collect-deployment.sh:302-308classified any tracked YAML that contains{{as Helm. Real repositories were refused, including this repository, whose GitHub Actions workflows use${{ }}.collect-deployment.sh:330-348) was read as separate, unmerged environments.--diffmissed most differences: it ignored parameter presence (a key in one environment only) and did not compare Kubernetes parameters.*.tfvars,*.tf.jsonand module-only Terraform were not recognized, so a repository using them was half-read silently. That breaks the last acceptance criterion.What #5392 changes
Chart.yaml), not by a double-brace marker. Layered Compose is refused with a named reason and is never read as environments. ARM,*.tfvars,*.tf.jsonand*.tfare declined by name.--diffnames are validated like--env. The diff reports parameter presence, Kubernetes parameters, ports andvalueFrom, labels secret-shaped differencessecret-differswithout printing values, and lists the kinds it compared when it finds none.collect-deployment.test.sh: structural Helm detection, layered Compose refusal, each declined tool shape,--diffname validation, Kubernetes namespace diffs with added and removed parameters and secret redaction, and Compose parameter presence. The suite passes on the branch.Each acceptance criterion now has a fixture, so #5392 carries
Closes #4649. This issue closes when that PR merges.The IaC tool scope
Which IaC tools to read first was the question behind
status: needs-decision. The agent chose Compose and Kubernetes first, with the others declined by name, and never surfaced that choice. The epic's dialect decision comment on #4639 does not cover it. The audit recommends ratifying it, so it is recorded here as the standing scope. The owner can override it; that label stays on this issue.The remaining readers (Terraform, Pulumi, Bicep, ARM, CloudFormation, Helm, Kustomize), merged layered Compose, compute-node placement, Service and Ingress links, and node diffs are tracked in #5400.
fix(architecture): remediate the map-* family audit findings (#5392)
kyle-sexton commentedon Sep 30, 2026
Owner decision (2026-09-29): Option 1. The IaC tool scope is ratified: Docker Compose and Kubernetes manifests are read first; Terraform, Helm, ARM,
*.tfvarsand*.tf.jsonare declined by name, never half-read.Basis given to the owner: #5392 (merged 2026-09-29T21:01:27Z) builds and tests those two readers, and a scan of the owner's 17 local checkouts found no deployment IaC for any tool, so no consumer sets a different order today.
The remaining readers (Terraform, Pulumi, Bicep, ARM, CloudFormation, Helm, Kustomize), merged layered Compose, compute-node placement and node diffs stay tracked in #5400. Every acceptance criterion has a fixture in
collect-deployment.test.shon main, so this issue closes as completed.