Skip to content

feat(architecture): add map-deployment, IaC topology per environment with a diff #4649

Closed

Description

@kyle-sexton

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.
  • --diff between 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

  1. kyle-sexton commented on Sep 29, 2026

    @kyle-sexton
    MemberAuthor

    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

    • High: collect-deployment.sh:302-308 classified any tracked YAML that contains {{ as Helm. Real repositories were refused, including this repository, whose GitHub Actions workflows use ${{ }}.
    • A layered Compose base plus per-environment override files (collect-deployment.sh:330-348) was read as separate, unmerged environments.
    • --diff missed most differences: it ignored parameter presence (a key in one environment only) and did not compare Kubernetes parameters.
    • ARM templates, *.tfvars, *.tf.json and module-only Terraform were not recognized, so a repository using them was half-read silently. That breaks the last acceptance criterion.

    What #5392 changes

    • T12: Helm is detected by structure (a 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.json and *.tf are declined by name.
    • T13: --diff names are validated like --env. The diff reports parameter presence, Kubernetes parameters, ports and valueFrom, labels secret-shaped differences secret-differs without printing values, and lists the kinds it compared when it finds none.
    • Fixtures added to collect-deployment.test.sh: structural Helm detection, layered Compose refusal, each declined tool shape, --diff name 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.

  2. kyle-sexton commented on Sep 30, 2026

    @kyle-sexton
    MemberAuthor

    Owner decision (2026-09-29): Option 1. The IaC tool scope is ratified: Docker Compose and Kubernetes manifests are read first; Terraform, Helm, ARM, *.tfvars and *.tf.json are 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.sh on main, so this issue closes as completed.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area: securitySecurity-relevant: vulnerability, hardening, or disclosure follow-up.

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions