Repository context
The current repository is both the CONSUMER, whose convention home declares where artifacts land,
and the DEFAULT SUBJECT, whose tracked IaC declares the topology.
Collect with an individual Bash call, one command per call: the project root,
git rev-parse --show-toplevel. Treat a failure (not a repository, git unavailable) as an unknown
value and carry on; ${CLAUDE_PROJECT_DIR} is the resolver's --root either way.
Purpose
Answer "where does this run, and what is different about that environment" from committed
infrastructure as code. Every node traces to a named file. The scripts collect and render. Do not
draw a node the script did not emit, and do not describe a live cloud. This is the C4 deployment
view; each environment is its own deployment environment in the diagram.
Resolve home and dialect
Read ${CLAUDE_PLUGIN_ROOT}/reference/config.md first. This skill writes into architecture_dir.
It does not read landscape_dialect and adds no dialect key: the diagram dialect is
diagram_dialect.system from the authoring-formats topic doc. likec4 writes deployment.md with
one fenced likec4 block, c4-plantuml with one fenced plantuml block. Mermaid is not offered.
Run bash "${CLAUDE_PLUGIN_ROOT}/lib/resolve-convention-home.sh" --root "${CLAUDE_PROJECT_DIR}" and
follow the exit code; never parse the root instruction file yourself. Exit 0: read
<home>/architecture/README.md for architecture_dir. Exit 1, 2, or 3: no declared home.
Per key, in order: --out <dir> wins for this run alone, then a declared architecture_dir, then
one question. architecture_dir has NO default. An undeclared and unconfirmed home, including
every non-interactive run, STOPS and points at /architecture:setup. Do not invent a directory.
Resolve diagram_dialect.system by restating this ladder, then running the resolver rather than
parsing the topic doc yourself. The ladder is a resolution order, not a task list:
1. Anchor at the repository root: `${CLAUDE_PROJECT_DIR}` when set, otherwise
`git rev-parse --show-toplevel`. Never a CWD-relative read.
2. Resolve the convention home `<home>` with the bundled resolver above. Never hand-parse the root
file.
3. The printed home is repo-relative: join it to the root, then pass
`<root>/<home>/authoring-formats/README.md` to the resolver.
4. Layer order is one layer deep: an explicit `--dialect` argument, then the team convention doc.
There is no personal override.
5. `diagram_dialect.system` has NO default. Allowed values are `likec4` and `c4-plantuml`. When it
is unset, emit no C4 deployment view. The record is still written.
6. Degrade soft, and say so. No pointer, no doc, no key, or an unrecognized value (mermaid
included) each resolve to emitting nothing. The resolver names the cause on stderr. Do not
hard-fail and do not ask the operator to create the surface mid-task.
7. Report provenance: the key, the value, and the layer (`argument`,
`team convention doc <path>`, or `unset (no C4 view emitted)`).
bash "${CLAUDE_PLUGIN_ROOT}/lib/resolve-diagram-dialect.sh" --kind system \
--formats "<root>/<home>/authoring-formats/README.md"
Omit --formats when no convention home resolved. Stdout is likec4, c4-plantuml, or none.
An explicit --dialect likec4|c4-plantuml on the invocation wins and the resolver is not required.
This skill never writes the consumer's root instruction file or its topic doc.
Build the record
"${CLAUDE_SKILL_DIR}/scripts/collect-deployment.sh" \
--repo "<subject-repo>" --out "<architecture_dir>/deployment.json" \
--generated-on "<YYYY-MM-DD|unknown>" \
--containers "<architecture_dir>/containers.json"
Pass --generated-on from git -C <root> log -1 --format=%cs, or unknown when that fails.
Omit --containers when containers.json is not already in the architecture directory; when
present it must be schema_version 1, and an unreadable catalog refuses the run. Pass --live only
when the invocation asked for live state. The script does not call a cloud API.
Shipped readers, every one that is present:
- Docker Compose (
compose.yaml, docker-compose.yml, and compose.<env>.yaml). The
environment is the filename suffix of compose.<env>.yaml, otherwise the parent directory name
(deploy/<env>/compose.yaml), and default for a file at the repository root. A base file and
its compose.override.yaml, or the files a tracked .env COMPOSE_FILE lists, merge in Compose
merge order into one environment named for the directory: scalars (image, replicas) are
overridden, ports and networks append without duplicates, environment merges by key. Any
other file beside them (a variant with no listed order, an override with no base, a second base)
or a !reset or !override tag is refused by name as compose-not-mergeable:<file>, never
guessed. Environment-per-directory layouts are unaffected. Each service is a compute node, and
its placement names it in compute.
- Kubernetes manifests whose
kind is Deployment, StatefulSet, DaemonSet, Service, or Ingress.
Each container of a workload, a sidecar included, is its own placement, and every container of a
workload runs on that workload's one compute node. The environment is the namespace, otherwise
the parent directory. A Service selects the containers of each workload in its namespace whose
pod template labels hold the whole selector; an Ingress routes to the containers behind each
Service its backends name. Each is a relationships entry from the Service or Ingress node to a
container. A selector that matches no pod template labels draws nothing.
- Terraform (
.tf, .tf.json, .tfvars, .tfvars.json), read as text: no terraform
binary, state, or credentials. A root is a directory of configuration that no local module source
names. Its environments are the <env> of an envs/<env>/ or environments/<env>/ path, else
one per <env>.tfvars at or above it, else the directory name (default at the repository
root). terraform.tfvars and *.auto.tfvars apply to every environment of their root and are
not environments themselves. Containers come from aws_ecs_task_definition
container_definitions (jsonencode([...]) or heredoc JSON), azurerm_container_app,
google_cloud_run_v2_service, and kubernetes_deployment, kubernetes_stateful_set, and
kubernetes_daemonset (with or without _v1). Compute nodes are aws_ecs_cluster,
aws_eks_cluster, azurerm_container_app_environment, azurerm_kubernetes_cluster,
google_container_cluster, and each Kubernetes workload. An ECS container runs on the cluster
its aws_ecs_service names, with the service's desired_count. A container app runs on the
environment its container_app_environment_id names. A Cloud Run container sits directly in the
environment. A module-only root follows local module sources, each resource addressed
module.<name>.<type>.<name>. A remote module source, or a local one with no tracked
configuration, refuses the record as terraform-module-unread:<file>:module.<name>, and the
source itself is never printed. A file that does not parse is terraform-unreadable:<file>. A
tfvars file with no configuration at or above it is terraform-orphan-tfvars:<file>.
- Bicep (
.bicep, .bicepparam) and ARM templates (JSON whose $schema names
deploymentTemplate, any scope), read as text: no bicep or az binary, no registry restore.
A root is a template that no module names, or one a parameters file names. Its environments are
one per .bicepparam whose using names it (main.prod.bicepparam is prod) and one per JSON
parameters file ($schema names deploymentParameters): <name>.parameters.<env>.json beside
<name>.bicep or <name>.json, or parameters.<env>.json beside the directory's only template.
With none, the environment is the directory name (default at the repository root). Containers
come from Microsoft.App/containerApps (template.containers, scale.minReplicas,
ingress.targetPort), Microsoft.ContainerInstance/containerGroups (each group is the compute
node of its containers), and Microsoft.Web/sites whose linuxFxVersion or windowsFxVersion
is DOCKER|<image> (appSettings are its parameters). Compute nodes are
Microsoft.App/managedEnvironments and connectedEnvironments, Microsoft.Web/serverfarms,
and Microsoft.ContainerService/managedClusters. A container app runs on the environment its
managedEnvironmentId or environmentId names, a site on its serverFarmId: a Bicep
<symbol>.id, or an ARM resourceId('<type>', <name>) whose name matches a declared resource.
A local module (Bicep or ARM) is followed, each resource addressed module.<name>.<symbol>. A
registry or template-spec module, or a local one that is not a tracked template, refuses the
record as bicep-module-unread:<file>:module.<name>, and the source is never printed. A file
that does not parse is bicep-unreadable:<file> or arm-unreadable:<file>. A .bicepparam
with using none, extends, or an untracked using target is bicep-param-unread:<file>. A
JSON parameters file with no template to pair is arm-parameters-unpaired:<file>. A nested
Microsoft.Resources/deployments resource is <bicep|arm>-deployment-unread:<file>:<symbol>.
- CloudFormation (YAML or JSON), read as text: no
aws binary, stack, or credentials. A
template names AWSTemplateFormatVersion, or holds a top-level Resources section with AWS::
types (Resources at the left margin in YAML). The short tags (!Ref, !Sub, !GetAtt,
!Join, !If) read the same as Ref and Fn::* in JSON. Containers come from
AWS::ECS::TaskDefinition ContainerDefinitions (Name, Image, PortMappings,
Environment, Secrets), and compute nodes from AWS::ECS::Cluster. An AWS::ECS::Service
names the task definition and cluster it runs (!Ref or !GetAtt) and gives DesiredCount.
Environments come from parameter files, one per environment, in either JSON shape (the
ParameterKey/ParameterValue array, or {"Parameters": {}}): <stem>.<env>.json or
<stem>.parameters.<env>.json beside <stem>.<ext>, else, when the repository holds exactly
one template, <env>.json or parameters.<env>.json anywhere. With no parameter
file the environment is the directory name (default at the repository root). A Ref to a
template parameter and a Sub over parameters resolve, from the parameter file and then the
parameter Default. A Transform (SAM, a macro) refuses as
cloudformation-transform-unread:<file>, a nested AWS::CloudFormation::Stack as
cloudformation-stack-unread:<file>:<id> (its TemplateURL is never printed), a parameter file
that pairs with no template as cloudformation-parameters-unpaired:<file>, and a file that does
not parse as cloudformation-unreadable:<file>.
- Pulumi YAML: a
Pulumi.yaml whose runtime is yaml and that holds its own program (no
main, no runtime options). Its environments are the Pulumi.<stack>.yaml files beside it, else
the directory name. The mapped resources are aws:ecs:Cluster, aws:ecs:TaskDefinition (with
containerDefinitions as fn::toJSON), and aws:ecs:Service, in the short or the
aws:ecs/<type>:<Type> form. ${pulumi.stack} and ${pulumi.project} resolve. ${key}
resolves from the stack file's config (<project>:<key> or <key>), then the project's
config default. ${resource.attr} links a service to its cluster and task definition. A file
that does not parse is pulumi-unreadable:<file>.
- Both YAML readers refuse anchors, aliases, the
<< merge key, duplicate keys, a tab in the
indentation, and more than one document. Their containerDefinitions given as anything but a
non-empty list (absent, empty, a JSON string, a function) places one container whose image is
unresolved:containerDefinitions.
- A task definition that two or more ECS services run, in the Terraform, CloudFormation or Pulumi
YAML reader, is placed once per service: each service puts every container on its own cluster
with its own desired count, named
<container>@<service>. The service part is the resource's
address in the file (the Terraform label, the CloudFormation logical ID, the Pulumi resource
name), not its name property, so the placement keeps one name in every environment and is
diffed like any other container. A task definition one service runs keeps the plain container
name. A containers.json name matches its @<service> placements.
A Pulumi project of any other runtime (nodejs, python, go, dotnet, ...), Helm (a
Chart.yaml, a Terraform helm_release, or a kubernetes:helm.sh/ resource in a Pulumi YAML
program), and Kustomize are recognized and named, never read. If any of them is present, the
record is refused, including when a shipped reader also matches, because a diagram of only the
shipped tool would be a partial read. Shipped readers beside each other (Terraform, Bicep,
CloudFormation, or Pulumi YAML beside Compose) are all read. A repository whose only IaC is a
declined tool is refused as adapter-not-shipped, not drawn empty. The declined Pulumi projects are
the tool pulumi with the runtime in the evidence (Pulumi.yaml (runtime nodejs)); the shipped
reader is the tool pulumi-yaml. Files under CI directories such as .github/ are not IaC and are
skipped.
A resource the Terraform, Bicep, ARM, CloudFormation, or Pulumi YAML reader parses and has no
mapping for is listed in the record's unmapped array (tool, resource type, file) and in the
## Unmapped resources table of deployment.md, never dropped without a trace. When no container
is placed and unmapped is not empty (a Terraform root of only aws_lambda_function and
aws_s3_bucket), the record is refused as no-mapped-container and keeps the list, rather than
drawn as an empty environment. A repository that also places containers is drawn with the list
beside it. The Compose reader adds nothing to the list. The Kubernetes reader lists a CronJob and
a Job (tool kubernetes, the kind, the file) and places none of their containers or parameters,
so a repository of only those is refused as no-mapped-container. They add no environment, and
their kind: must come before spec: for their env entries to stay out of the record. A double-brace expression in
a Compose or Kubernetes value (a Go template in a healthcheck) reads normally; one in a name,
image, namespace, replicas, or kind field refuses the file as unreadable.
Every value the collector writes and the renderer prints passes through
${CLAUDE_PLUGIN_ROOT}/lib/redact-connection.awk. A parameter whose key names a credential, or
whose value carries one (a connection-string password or key, a SAS signature, a GitHub token, a
cloud access key, a private key, URL userinfo, or an HTTP Basic or Bearer credential), is recorded
with an empty value and "redacted":"yes". So is a value resolved from a Terraform variable, a
Bicep, ARM or CloudFormation parameter, or a Pulumi config key whose name names a credential,
whatever the name of the env var it lands in and with or without a native secret marker. Any other
emitted field that carries one prints as [redacted]. A secret must not appear in the record, the
diagram, the diff, or stdout. A diff of two secret values says that the parameter differs and
prints neither value.
A diff compares two environments of one tool over these kinds, for every shipped reader: a
container present in one environment only, image, replicas, ports, a parameter present in one
environment only, a plain parameter value, a secret parameter that differs, a network (a Compose
network or a Kubernetes Service) or an Ingress present in one environment only, and a network
exposure or port or an Ingress host that differs. A compute node (a cluster, service plan or node
pool) of the Terraform, Bicep, ARM, CloudFormation and Pulumi readers is compared too: present in
one environment only (compute-added, compute-removed), or, for Bicep, CloudFormation and
Pulumi, at one address with a different resource type (compute). It is matched by resource
address, not name, since a name usually differs per environment, so a changed name alone is not a
difference. An ARM resource has no stable address, so it is matched by type and its order among
nodes of that type. A Terraform Kubernetes workload and an Azure container group are compute nodes
too. A Kubernetes
container port (containerPort) is the placement's ports. A Kubernetes valueFrom reference
counts as a secret parameter whose presence is compared; envFrom is not read. The report's diff
section lists these kinds, and an empty diff reads No differences of these kinds: ... so a clean
diff is never mistaken for a full comparison.
When <architecture_dir>/containers.json exists, container names that the IaC does not place are
listed. When it does not exist, the artifact says container names came from the IaC.
Render
"${CLAUDE_SKILL_DIR}/scripts/render-deployment.sh" \
--record "<architecture_dir>/deployment.json" --out "<architecture_dir>" \
--dialect "<likec4|c4-plantuml|none>" --env "<environment>" --diff "<env-a>" "<env-b>"
Pass the resolved dialect. With none the script still writes deployment.md with the tools,
environments, diff, and container tables, and draws no diagram block. Omit --env to draw every
collected environment, one deployment environment each inside the one fenced block. Omit --diff
when the invocation did not ask for a comparison. The unmapped resources, when there are any, and
then the diff table follow the tools. An unknown --env or --diff name writes a refusal that
lists the environments and exits 3. In a non-interactive run, stop there.
The script prints one summary line. Keep it:
deployment: status=<drawn|refused> reason=<reason|none> tools=<list> environments=<n> placements=<n> diffs=<n> dialect=<likec4|c4-plantuml|none> unmapped=<n>
Exit 1 means the record is unreadable or not schema_version 1 in the one-object-per-line layout;
nothing was written. Do not reformat the record by hand.
Close with the report
End every run with this block, in this order:
- Artifacts: each path written, or
none written when the run stopped before a home existed.
- Status:
drawn or refused, and the reason when it is a refusal.
- Tools: which IaC tools were shipped readers and which were recognized and declined.
- Not drawn: the summary's
unmapped= count and each resource type listed under
## Unmapped resources with its file, or that none were listed.
- Environment: the one drawn, or each environment, and the file that declared it.
- Diff: the summary's
diffs= count, or that --diff was not requested.
- Dialect:
diagram_dialect.system, the value, and the layer (argument,
team convention doc <path>, or unset (no C4 view emitted)).
- Containers:
map-containers output was used, or it was absent and names came from the IaC.
- Secrets: redacted. No secret value was written.
- Live: not requested, or requested and refused. No cloud API was called.
Interactive view
After the report, offer an interactive view of deployment.json in one sentence. The markdown and
the record stay authoritative. Build it only with
${CLAUDE_PLUGIN_ROOT}/scripts/build-view.mjs deployment, never hand-written; the shared medium
resolver decides the destination, with this plugin's medium option ${user_config.medium}, or ""
when that reads empty or unsubstituted (never put a ${user_config.*} string in a shell command), and
its report line is printed. Procedure:
${CLAUDE_PLUGIN_ROOT}/reference/rendered-view.md.
What this skill does NOT do
- Call a cloud API, use credentials, or compare live state to the declaration.
- Run
terraform, read Terraform state, or fetch a remote module.
- Run
bicep or az, restore a registry module, or evaluate an ARM function.
- Run
aws or pulumi, expand a CloudFormation Transform, or evaluate Fn::If, Fn::FindInMap,
Fn::Join, or a Pulumi fn::* function.
- Cost, scaling, capacity, or runtime health.
- Apply Helm templates or Kustomize. Those tools are a refusal, not a guessed render.
- Add a dialect key, read
landscape_dialect, or emit mermaid. The dialect is the existing
diagram_dialect.system.
- Invent a home, a network, or a node the script did not emit.
Next
- The topology settles a decision worth keeping:
/architecture:record-decision.
- The topology needs a deployment change decided:
/planning:design system.
- The question is which systems the repository sits among:
/architecture:map-landscape.
Gotchas
- C4 scopes a deployment diagram to one environment. This skill writes one fenced block with
every environment inside it as its own deployment environment;
--env narrows the block to
one. The diff is a table, not a picture. Pointer: when checking a deployment view's scope or
elements, fetch C4 deployment diagram § Scope and § Primary and supporting elements
live. As of: 2026-11-10. Recheck trigger: that page changes the scope or the primary elements.
- C4-PlantUML deployment syntax: read against the README, never run. The renderer writes the
macros. The
C4_Deployment include name is our inference from the README's container
example. No PlantUML run has parsed this output. Rel is drawn from a container to a network
node its placement names, and from a Kubernetes Service or Ingress node to a container in the
record's relationships. Pointer: when checking the macros or the include the renderer
writes, fetch C4-PlantUML README § Deployment diagram and
§ Including the C4-PlantUML library live. As of: 2026-11-10. Recheck trigger: that README changes the deployment macros or the
include path, or a host with Java can run PlantUML over a rendered block.
- LikeC4 deployment syntax: parsed by the CLI. The record is a probe:
likec4@1.59.4 validate exits 0 on the golden blocks in ${CLAUDE_PLUGIN_ROOT}/lib/likec4-golden/
(deployment-compose.c4, deployment-kubernetes.c4, deployment-ecs-shared.c4), which
collect-deployment.test.sh diffs against. Pointer: when checking the syntax the collector
writes, fetch LikeC4 deployment model § Deployment nodes,
§ Deployed instances, § Deployment relationships
and deployment views § View definition live. As of: 2026-11-10. Recheck trigger: any of those sections changes that syntax, or a
newer likec4 release ships: set LIKEC4_VALIDATE=1 when running the test to re-run the CLI.
- Labels cannot leave the block. Quotes, backticks, backslashes, and line breaks are stripped
from labels,
@ prints as (at), and every identifier is prefixed and numbered, so a hostile
name cannot close the fence, end the diagram, or collide with a keyword.
- Compose without a
networks entry joins the default network. A service that declares none
is recorded on default; a service that names a network is recorded on that network.
- A required secret is not a topology fact. The value is dropped. The diff can say the
parameter differs. It cannot show the value.
- CloudFormation and Pulumi values are resolved, never evaluated. A parameter or config value
resolves only through the sources listed above. Every other function (
Fn::If, Fn::FindInMap,
Fn::Join, GetAtt, a pseudo parameter such as AWS::Region, fn::join, a Pulumi variable) is
recorded as unresolved:<text>. A resource Condition, Mappings, and Fn::ForEach are not
applied, so a conditional resource is drawn in every environment. Only the ECS types above are
mapped: an EKS cluster, a Lambda, or an aws:eks or kubernetes: Pulumi resource is not drawn,
and its type is listed under ## Unmapped resources. A service whose task definition is not
declared in the same template is placed as one container whose image is
unresolved:taskDefinition. YAML parameter files and CloudFormation git-sync deployment files
are not read.
- CloudFormation and Pulumi secrets. A parameter with
NoEcho: true, any value holding a
{{resolve:...}} dynamic reference, every container Secrets entry, a Pulumi config key with
secret: true, a secure: stack value, a fn::secret wrapper, and a parameter or config key
whose name names a credential are redacted wherever they land, including in a name, image or
port. A secret that differs between two environments is reported as differing, and neither value
is printed.
- CloudFormation template shape. Claim: the YAML short form
!Ref name equals
Ref: name, and JSON writes { "Ref": "name" }. Basis:
https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/intrinsic-function-reference-ref.html.
Claim: Fn::Sub, Fn::GetAtt, and the other functions take the same !Name short form and
Fn::Name long form; Ref to a parameter returns its value. Basis: the same reference index,
https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference.html.
Claim: AWS::ECS::Service takes Cluster, DesiredCount, ServiceName, and TaskDefinition.
Basis: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-ecs-service.html.
As of: 2026-09-30. Recheck when any of those pages changes a form or property name.
- CloudFormation parameters and secrets. The redaction and resolution rules above read
NoEcho, Default and the {{resolve:...}} forms. Pointer: when checking what those mean or
how a dynamic reference is written, fetch
Parameters § Properties
and
Dynamic references
live. As of: 2026-11-10. Recheck trigger: either section changes the parameter properties or
the dynamic-reference syntax. Claim: a parameter file is either the ParameterKey/ParameterValue
array or a template configuration file with a top-level Parameters object. Basis:
https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cfn-using-cli-parameters.html. No
document names a per-environment file convention, so the pairing rules above are this skill's own.
As of: 2026-09-30. Recheck when those pages change the syntax or add a parameter file shape.
- Pulumi YAML program and stack shape. The reader maps the project file's
runtime, the
program's resources, variables and outputs, config items, ${...} interpolation and the
fn::toJSON, fn::secret and fn::join forms. Pointer: when checking those forms, fetch
project file § Attributes, § Runtime options,
and the YAML language reference's § Config, § Interpolation,
§ Built-in variables, § fn::toJSON,
§ fn::secret and § fn::join live. As of: 2026-11-10. Recheck trigger: any of those sections changes a key or a form. Claim:
Pulumi.<stack>.yaml holds a config map keyed [<namespace>:]<key>, the project name is the default
namespace, and an encrypted value is secure: <ciphertext>. Basis:
https://www.pulumi.com/docs/concepts/config/ and
https://www.pulumi.com/docs/iac/concepts/secrets/. Claim: aws:ecs:Service takes cluster,
taskDefinition, desiredCount, and name, and aws:ecs:TaskDefinition takes containerDefinitions
as fn::toJSON over a list of name, image, portMappings (containerPort). Basis:
https://www.pulumi.com/registry/packages/aws/api-docs/ecs/service/ and
https://www.pulumi.com/registry/packages/aws/api-docs/ecs/taskdefinition/. As of: 2026-09-30.
Recheck when any of those pages changes a key, the secure: form, or the runtime forms.
- Bicep and ARM values are resolved, never evaluated. A parameter resolves from a module
params argument, then the environment's parameters file, then its default, and ${name} inside
a Bicep string the same way. An ARM value resolves only when it is exactly
[parameters('<name>')]; [[ opens a literal. A parameter marked @secure(), typed
securestring or secureobject, given a Key Vault reference, or named for a credential is
redacted wherever it lands, as is a secretRef or secureValue env entry. Every var, function, and conditional is recorded
as unresolved:<expression>. A for or copy loop is placed once, an if or condition is
ignored, a resourceId with scope arguments matches nothing, and Microsoft.App/jobs is not
mapped. A child resource nested in its parent (a Bicep resource inside a body, an ARM
resources array inside a resource) is listed under its full type, such as
Microsoft.Storage/storageAccounts/blobServices. A Microsoft.Web/sites/slots nested in its site,
or naming it as its Bicep parent, whose fx version reads DOCKER| is the exception: it places
the container <site>/<slot>, its full resource name, on the site's serverFarmId, with its own
appSettings. Any other slot, including a top-level ARM one, is listed. A container app or container
group whose containers are an expression, an empty list, or absent places one container named for
the resource, its image unresolved:<expression> or unresolved:containers. Every other resource
type, and a site whose fx version does not read DOCKER| (listed as Microsoft.Web/sites), is
listed under ## Unmapped resources.
- Bicep module and parameter file forms. The reader tells a local module path from a registry
or template-spec source, and pairs a
.bicepparam file with its template through its using
line. Pointer: when checking which module paths are local or how a parameters file names
its template, fetch Bicep modules § Path to a module
(§ Local file, § File in registry, § File in template spec)
and parameter files § Define parameters file and § Extendable parameters file
live. As of: 2026-11-10. Recheck trigger: either page changes a path form or the using statement.
- ARM expressions are bracketed strings. The reader resolves only
[parameters('<name>')]
and reads [[ as a literal. Pointer: when checking the expression and escape rules, fetch
template expressions § Escape characters
live. As of: 2026-11-10. Recheck trigger: that section changes the escape rule.
- A nested child resource carries one type segment. The reader lists a child nested in its
parent under the parent's full type plus the child's segment (
Microsoft.Web/sites/slots).
Pointer: when checking how a nested child writes its type, fetch
Bicep child resource name and type § Within parent resource and
ARM child resource name and type § Within parent resource
live. As of: 2026-11-10. Recheck trigger: either section changes the single-segment rule or the nesting depth.
- A slot with its own image is placed on its site's plan. A
DOCKER| slot places as
<site>/<slot> on the site's App Service plan, naming it by its full resource name, whether it is
nested in the site or names it with a Bicep parent. Pointer: when deciding how a child's full
name is written, or where a slot runs, fetch
Bicep child resource name and type § Full resource name outside parent,
ARM child resource name and type § Outside parent resource and
App Service plans § Considerations for running and scaling an app
live. As of: 2026-11-10. Recheck trigger: a read of any of those sections diverges from the placement above.
- Terraform values are resolved, never evaluated.
var.X resolves from a module call argument,
then the root's tfvars files, then the variable default, and ${var.X} inside a string the
same way. A variable declared sensitive = true, or named for a credential, is redacted wherever
it lands. Everything else, such as locals, functions other than jsonencode, conditionals,
for-expressions, file(), and templatefile(), is recorded as unresolved:<expression>. count
and for_each are not expanded (the resource is placed once), a dynamic block is not read, and
an env list built by an expression records no parameters. A container app, Cloud Run service, or
Kubernetes workload whose containers are a dynamic block or an expression places one container
named for the resource, its image unresolved:dynamic container (containers for Cloud Run) or
unresolved:container; a dynamic block beside plain ones adds a second, <name>.dynamic. An
ECS task definition with no container_definitions places one container, its image
unresolved:container_definitions. A resource with an empty body (resource "aws_s3_bucket" "b" {})
is placed or listed as unmapped like any other. A .tf.json block type or label written as an
array of objects ("resource": [{...}]) reads like the object form.
- Only
./ and ../ sources are local. The reader treats only those module sources as
local. Pointer: when checking how a local module path is written, fetch
module block § Local paths
live. As of: 2026-11-10. Recheck trigger: that section changes how a local path is written.
- Auto-loaded tfvars rank below the environment's file. The reader ranks the environment's
<env>.tfvars above the auto-loaded tfvars files, and a variable default lowest. Pointer:
when checking Terraform's precedence, fetch
input variables § Assign values to variables
live. As of: 2026-11-10. Recheck trigger: that section changes the precedence list.
- A
.tf.json block may be an array of objects at any level. Claim: each label level of a
block (a resource's type and name) and its body may be a JSON object or a JSON array of objects,
so "resource": [{"aws_s3_bucket": {"b": {}}}] declares the same resource as the object form.
Basis: https://raw.githubusercontent.com/hashicorp/hcl/main/json/spec.md (Blocks). As of:
2026-09-30. Recheck when that spec changes where an array may stand in for an object.
- One task definition, several services. Each service that runs a shared task definition places
the task definition's containers on its own cluster with its own desired count, named
<container>@<service>. The @ separates the two parts, and a label prints it as (at), like
any other. Pointer: when deciding whether the cluster and the count belong to the service, or
whether @ can appear in a container or service name, fetch
task definitions,
services,
name
and serviceName
live. As of: 2026-10-04. Recheck trigger: a read of any of those sections diverges from
the <container>@<service> placement above.
- Helm reached through IaC is still Helm. Claim: the Terraform Helm provider declares a release
as
resource "helm_release", and the Pulumi Kubernetes provider as the type
kubernetes:helm.sh/v3:Release. Basis:
https://raw.githubusercontent.com/hashicorp/terraform-provider-helm/main/docs/resources/release.md
and https://www.pulumi.com/registry/packages/kubernetes/api-docs/helm/v3/release/. As of:
2026-09-30. Recheck when either page renames the type. Either one declines Helm, which refuses the
whole record as partial-read, because the chart's workloads are not read. kubernetes_manifest
and the kubernetes_* types the Terraform reader does not map appear under ## Unmapped resources, since the Kubernetes tool itself is a shipped reader.
--live is a refusal. Committed files are not silently substituted for a live comparison.
- A reformatted record is refused. Render exits 1 and writes nothing.
- Tracked files only.
git ls-files is the source list. A tracked symlink is skipped, so it
cannot pull in an untracked file.
1---2name: map-deployment3description: "C4 deployment view of committed infrastructure: which containers sit on which declared nodes, per environment, and what differs between two environments. Use when 'map deployment', 'deployment diagram', 'what is different in production', 'IaC topology', or 'where does this container run'. Skip when the question is a live cloud inventory, cost, or runtime health."4argument-hint: "[environment] [--diff <env-a> <env-b>] [--dialect likec4|c4-plantuml] [--out <dir>]"5user-invocable: true6disable-model-invocation: false7shell: bash8metadata:9 source: https://skillmd.com/skills/melodic-software/map-deployment10 workflow-stage: explore11 summary: Chart IaC deployment topology per environment, with a diff12---1314## Repository context1516The current repository is both the CONSUMER, whose convention home declares where artifacts land,17and the DEFAULT SUBJECT, whose tracked IaC declares the topology.1819Collect with an **individual** Bash call, one command per call: the project root,20`git rev-parse --show-toplevel`. Treat a failure (not a repository, git unavailable) as an unknown21value and carry on; `${CLAUDE_PROJECT_DIR}` is the resolver's `--root` either way.2223## Purpose2425Answer "where does this run, and what is different about that environment" from committed26infrastructure as code. Every node traces to a named file. The scripts collect and render. Do not27draw a node the script did not emit, and do not describe a live cloud. This is the C4 deployment28view; each environment is its own deployment environment in the diagram.2930## Resolve home and dialect3132Read `${CLAUDE_PLUGIN_ROOT}/reference/config.md` first. This skill writes into `architecture_dir`.33It does not read `landscape_dialect` and adds no dialect key: the diagram dialect is34`diagram_dialect.system` from the authoring-formats topic doc. `likec4` writes `deployment.md` with35one fenced `likec4` block, `c4-plantuml` with one fenced `plantuml` block. Mermaid is not offered.3637Run `bash "${CLAUDE_PLUGIN_ROOT}/lib/resolve-convention-home.sh" --root "${CLAUDE_PROJECT_DIR}"` and38follow the exit code; never parse the root instruction file yourself. Exit 0: read39`<home>/architecture/README.md` for `architecture_dir`. Exit 1, 2, or 3: no declared home.4041Per key, in order: `--out <dir>` wins for this run alone, then a declared `architecture_dir`, then42one question. `architecture_dir` has NO default. An undeclared and unconfirmed home, including43every non-interactive run, STOPS and points at `/architecture:setup`. Do not invent a directory.4445Resolve `diagram_dialect.system` by restating this ladder, then running the resolver rather than46parsing the topic doc yourself. The ladder is a resolution order, not a task list:4748```markdown491. Anchor at the repository root: `${CLAUDE_PROJECT_DIR}` when set, otherwise50 `git rev-parse --show-toplevel`. Never a CWD-relative read.512. Resolve the convention home `<home>` with the bundled resolver above. Never hand-parse the root52 file.533. The printed home is repo-relative: join it to the root, then pass54 `<root>/<home>/authoring-formats/README.md` to the resolver.554. Layer order is one layer deep: an explicit `--dialect` argument, then the team convention doc.56 There is no personal override.575. `diagram_dialect.system` has NO default. Allowed values are `likec4` and `c4-plantuml`. When it58 is unset, emit no C4 deployment view. The record is still written.596. Degrade soft, and say so. No pointer, no doc, no key, or an unrecognized value (mermaid60 included) each resolve to emitting nothing. The resolver names the cause on stderr. Do not61 hard-fail and do not ask the operator to create the surface mid-task.627. Report provenance: the key, the value, and the layer (`argument`,63 `team convention doc <path>`, or `unset (no C4 view emitted)`).64```6566```bash67bash "${CLAUDE_PLUGIN_ROOT}/lib/resolve-diagram-dialect.sh" --kind system \68 --formats "<root>/<home>/authoring-formats/README.md"69```7071Omit `--formats` when no convention home resolved. Stdout is `likec4`, `c4-plantuml`, or `none`.72An explicit `--dialect likec4|c4-plantuml` on the invocation wins and the resolver is not required.7374This skill never writes the consumer's root instruction file or its topic doc.7576## Build the record7778```bash79"${CLAUDE_SKILL_DIR}/scripts/collect-deployment.sh" \80 --repo "<subject-repo>" --out "<architecture_dir>/deployment.json" \81 --generated-on "<YYYY-MM-DD|unknown>" \82 --containers "<architecture_dir>/containers.json"83```8485Pass `--generated-on` from `git -C <root> log -1 --format=%cs`, or `unknown` when that fails.86Omit `--containers` when `containers.json` is not already in the architecture directory; when87present it must be schema_version 1, and an unreadable catalog refuses the run. Pass `--live` only88when the invocation asked for live state. The script does not call a cloud API.8990Shipped readers, every one that is present:9192- **Docker Compose** (`compose.yaml`, `docker-compose.yml`, and `compose.<env>.yaml`). The93 environment is the filename suffix of `compose.<env>.yaml`, otherwise the parent directory name94 (`deploy/<env>/compose.yaml`), and `default` for a file at the repository root. A base file and95 its `compose.override.yaml`, or the files a tracked `.env` `COMPOSE_FILE` lists, merge in Compose96 merge order into one environment named for the directory: scalars (`image`, `replicas`) are97 overridden, `ports` and `networks` append without duplicates, `environment` merges by key. Any98 other file beside them (a variant with no listed order, an override with no base, a second base)99 or a `!reset` or `!override` tag is refused by name as `compose-not-mergeable:<file>`, never100 guessed. Environment-per-directory layouts are unaffected. Each service is a compute node, and101 its placement names it in `compute`.102- **Kubernetes** manifests whose `kind` is Deployment, StatefulSet, DaemonSet, Service, or Ingress.103 Each container of a workload, a sidecar included, is its own placement, and every container of a104 workload runs on that workload's one compute node. The environment is the namespace, otherwise105 the parent directory. A Service selects the containers of each workload in its namespace whose106 pod template labels hold the whole selector; an Ingress routes to the containers behind each107 Service its backends name. Each is a `relationships` entry from the Service or Ingress node to a108 container. A selector that matches no pod template labels draws nothing.109- **Terraform** (`.tf`, `.tf.json`, `.tfvars`, `.tfvars.json`), read as text: no `terraform`110 binary, state, or credentials. A root is a directory of configuration that no local module source111 names. Its environments are the `<env>` of an `envs/<env>/` or `environments/<env>/` path, else112 one per `<env>.tfvars` at or above it, else the directory name (`default` at the repository113 root). `terraform.tfvars` and `*.auto.tfvars` apply to every environment of their root and are114 not environments themselves. Containers come from `aws_ecs_task_definition`115 `container_definitions` (`jsonencode([...])` or heredoc JSON), `azurerm_container_app`,116 `google_cloud_run_v2_service`, and `kubernetes_deployment`, `kubernetes_stateful_set`, and117 `kubernetes_daemonset` (with or without `_v1`). Compute nodes are `aws_ecs_cluster`,118 `aws_eks_cluster`, `azurerm_container_app_environment`, `azurerm_kubernetes_cluster`,119 `google_container_cluster`, and each Kubernetes workload. An ECS container runs on the cluster120 its `aws_ecs_service` names, with the service's `desired_count`. A container app runs on the121 environment its `container_app_environment_id` names. A Cloud Run container sits directly in the122 environment. A module-only root follows local module sources, each resource addressed123 `module.<name>.<type>.<name>`. A remote module source, or a local one with no tracked124 configuration, refuses the record as `terraform-module-unread:<file>:module.<name>`, and the125 source itself is never printed. A file that does not parse is `terraform-unreadable:<file>`. A126 tfvars file with no configuration at or above it is `terraform-orphan-tfvars:<file>`.127- **Bicep** (`.bicep`, `.bicepparam`) and **ARM** templates (JSON whose `$schema` names128 `deploymentTemplate`, any scope), read as text: no `bicep` or `az` binary, no registry restore.129 A root is a template that no module names, or one a parameters file names. Its environments are130 one per `.bicepparam` whose `using` names it (`main.prod.bicepparam` is `prod`) and one per JSON131 parameters file (`$schema` names `deploymentParameters`): `<name>.parameters.<env>.json` beside132 `<name>.bicep` or `<name>.json`, or `parameters.<env>.json` beside the directory's only template.133 With none, the environment is the directory name (`default` at the repository root). Containers134 come from `Microsoft.App/containerApps` (`template.containers`, `scale.minReplicas`,135 `ingress.targetPort`), `Microsoft.ContainerInstance/containerGroups` (each group is the compute136 node of its containers), and `Microsoft.Web/sites` whose `linuxFxVersion` or `windowsFxVersion`137 is `DOCKER|<image>` (`appSettings` are its parameters). Compute nodes are138 `Microsoft.App/managedEnvironments` and `connectedEnvironments`, `Microsoft.Web/serverfarms`,139 and `Microsoft.ContainerService/managedClusters`. A container app runs on the environment its140 `managedEnvironmentId` or `environmentId` names, a site on its `serverFarmId`: a Bicep141 `<symbol>.id`, or an ARM `resourceId('<type>', <name>)` whose name matches a declared resource.142 A local module (Bicep or ARM) is followed, each resource addressed `module.<name>.<symbol>`. A143 registry or template-spec module, or a local one that is not a tracked template, refuses the144 record as `bicep-module-unread:<file>:module.<name>`, and the source is never printed. A file145 that does not parse is `bicep-unreadable:<file>` or `arm-unreadable:<file>`. A `.bicepparam`146 with `using none`, `extends`, or an untracked `using` target is `bicep-param-unread:<file>`. A147 JSON parameters file with no template to pair is `arm-parameters-unpaired:<file>`. A nested148 `Microsoft.Resources/deployments` resource is `<bicep|arm>-deployment-unread:<file>:<symbol>`.149- **CloudFormation** (YAML or JSON), read as text: no `aws` binary, stack, or credentials. A150 template names `AWSTemplateFormatVersion`, or holds a top-level `Resources` section with `AWS::`151 types (`Resources` at the left margin in YAML). The short tags (`!Ref`, `!Sub`, `!GetAtt`,152 `!Join`, `!If`) read the same as `Ref` and `Fn::*` in JSON. Containers come from153 `AWS::ECS::TaskDefinition` `ContainerDefinitions` (`Name`, `Image`, `PortMappings`,154 `Environment`, `Secrets`), and compute nodes from `AWS::ECS::Cluster`. An `AWS::ECS::Service`155 names the task definition and cluster it runs (`!Ref` or `!GetAtt`) and gives `DesiredCount`.156 Environments come from parameter files, one per environment, in either JSON shape (the157 `ParameterKey`/`ParameterValue` array, or `{"Parameters": {}}`): `<stem>.<env>.json` or158 `<stem>.parameters.<env>.json` beside `<stem>.<ext>`, else, when the repository holds exactly159 one template, `<env>.json` or `parameters.<env>.json` anywhere. With no parameter160 file the environment is the directory name (`default` at the repository root). A `Ref` to a161 template parameter and a `Sub` over parameters resolve, from the parameter file and then the162 parameter `Default`. A `Transform` (SAM, a macro) refuses as163 `cloudformation-transform-unread:<file>`, a nested `AWS::CloudFormation::Stack` as164 `cloudformation-stack-unread:<file>:<id>` (its `TemplateURL` is never printed), a parameter file165 that pairs with no template as `cloudformation-parameters-unpaired:<file>`, and a file that does166 not parse as `cloudformation-unreadable:<file>`.167- **Pulumi YAML**: a `Pulumi.yaml` whose `runtime` is `yaml` and that holds its own program (no168 `main`, no runtime options). Its environments are the `Pulumi.<stack>.yaml` files beside it, else169 the directory name. The mapped resources are `aws:ecs:Cluster`, `aws:ecs:TaskDefinition` (with170 `containerDefinitions` as `fn::toJSON`), and `aws:ecs:Service`, in the short or the171 `aws:ecs/<type>:<Type>` form. `${pulumi.stack}` and `${pulumi.project}` resolve. `${key}`172 resolves from the stack file's `config` (`<project>:<key>` or `<key>`), then the project's173 `config` default. `${resource.attr}` links a service to its cluster and task definition. A file174 that does not parse is `pulumi-unreadable:<file>`.175- Both YAML readers refuse anchors, aliases, the `<<` merge key, duplicate keys, a tab in the176 indentation, and more than one document. Their `containerDefinitions` given as anything but a177 non-empty list (absent, empty, a JSON string, a function) places one container whose image is178 `unresolved:containerDefinitions`.179- A task definition that two or more ECS services run, in the Terraform, CloudFormation or Pulumi180 YAML reader, is placed once per service: each service puts every container on its own cluster181 with its own desired count, named `<container>@<service>`. The service part is the resource's182 address in the file (the Terraform label, the CloudFormation logical ID, the Pulumi resource183 name), not its `name` property, so the placement keeps one name in every environment and is184 diffed like any other container. A task definition one service runs keeps the plain container185 name. A `containers.json` name matches its `@<service>` placements.186187A Pulumi project of any other runtime (`nodejs`, `python`, `go`, `dotnet`, ...), Helm (a188`Chart.yaml`, a Terraform `helm_release`, or a `kubernetes:helm.sh/` resource in a Pulumi YAML189program), and Kustomize are recognized and named, never read. If any of them is present, the190record is refused, including when a shipped reader also matches, because a diagram of only the191shipped tool would be a partial read. Shipped readers beside each other (Terraform, Bicep,192CloudFormation, or Pulumi YAML beside Compose) are all read. A repository whose only IaC is a193declined tool is refused as `adapter-not-shipped`, not drawn empty. The declined Pulumi projects are194the tool `pulumi` with the runtime in the evidence (`Pulumi.yaml (runtime nodejs)`); the shipped195reader is the tool `pulumi-yaml`. Files under CI directories such as `.github/` are not IaC and are196skipped.197198A resource the Terraform, Bicep, ARM, CloudFormation, or Pulumi YAML reader parses and has no199mapping for is listed in the record's `unmapped` array (tool, resource type, file) and in the200`## Unmapped resources` table of `deployment.md`, never dropped without a trace. When no container201is placed and `unmapped` is not empty (a Terraform root of only `aws_lambda_function` and202`aws_s3_bucket`), the record is refused as `no-mapped-container` and keeps the list, rather than203drawn as an empty environment. A repository that also places containers is drawn with the list204beside it. The Compose reader adds nothing to the list. The Kubernetes reader lists a `CronJob` and205a `Job` (tool `kubernetes`, the kind, the file) and places none of their containers or parameters,206so a repository of only those is refused as `no-mapped-container`. They add no environment, and207their `kind:` must come before `spec:` for their `env` entries to stay out of the record. A double-brace expression in208a Compose or Kubernetes value (a Go template in a healthcheck) reads normally; one in a name,209image, namespace, replicas, or kind field refuses the file as unreadable.210211Every value the collector writes and the renderer prints passes through212`${CLAUDE_PLUGIN_ROOT}/lib/redact-connection.awk`. A parameter whose key names a credential, or213whose value carries one (a connection-string password or key, a SAS signature, a GitHub token, a214cloud access key, a private key, URL userinfo, or an HTTP Basic or Bearer credential), is recorded215with an empty value and `"redacted":"yes"`. So is a value resolved from a Terraform variable, a216Bicep, ARM or CloudFormation parameter, or a Pulumi config key whose name names a credential,217whatever the name of the env var it lands in and with or without a native secret marker. Any other218emitted field that carries one prints as `[redacted]`. A secret must not appear in the record, the219diagram, the diff, or stdout. A diff of two secret values says that the parameter differs and220prints neither value.221222A diff compares two environments of one tool over these kinds, for every shipped reader: a223container present in one environment only, image, replicas, ports, a parameter present in one224environment only, a plain parameter value, a secret parameter that differs, a network (a Compose225network or a Kubernetes Service) or an Ingress present in one environment only, and a network226exposure or port or an Ingress host that differs. A compute node (a cluster, service plan or node227pool) of the Terraform, Bicep, ARM, CloudFormation and Pulumi readers is compared too: present in228one environment only (`compute-added`, `compute-removed`), or, for Bicep, CloudFormation and229Pulumi, at one address with a different resource type (`compute`). It is matched by resource230address, not name, since a name usually differs per environment, so a changed name alone is not a231difference. An ARM resource has no stable address, so it is matched by type and its order among232nodes of that type. A Terraform Kubernetes workload and an Azure container group are compute nodes233too. A Kubernetes234container port (`containerPort`) is the placement's ports. A Kubernetes `valueFrom` reference235counts as a secret parameter whose presence is compared; `envFrom` is not read. The report's diff236section lists these kinds, and an empty diff reads `No differences of these kinds: ...` so a clean237diff is never mistaken for a full comparison.238239When `<architecture_dir>/containers.json` exists, container names that the IaC does not place are240listed. When it does not exist, the artifact says container names came from the IaC.241242## Render243244```bash245"${CLAUDE_SKILL_DIR}/scripts/render-deployment.sh" \246 --record "<architecture_dir>/deployment.json" --out "<architecture_dir>" \247 --dialect "<likec4|c4-plantuml|none>" --env "<environment>" --diff "<env-a>" "<env-b>"248```249250Pass the resolved dialect. With `none` the script still writes `deployment.md` with the tools,251environments, diff, and container tables, and draws no diagram block. Omit `--env` to draw every252collected environment, one deployment environment each inside the one fenced block. Omit `--diff`253when the invocation did not ask for a comparison. The unmapped resources, when there are any, and254then the diff table follow the tools. An unknown `--env` or `--diff` name writes a refusal that255lists the environments and exits 3. In a non-interactive run, stop there.256257The script prints one summary line. Keep it:258259`deployment: status=<drawn|refused> reason=<reason|none> tools=<list> environments=<n> placements=<n> diffs=<n> dialect=<likec4|c4-plantuml|none> unmapped=<n>`260261Exit 1 means the record is unreadable or not schema_version 1 in the one-object-per-line layout;262nothing was written. Do not reformat the record by hand.263264## Close with the report265266End every run with this block, in this order:267268- **Artifacts**: each path written, or `none written` when the run stopped before a home existed.269- **Status**: `drawn` or `refused`, and the reason when it is a refusal.270- **Tools**: which IaC tools were shipped readers and which were recognized and declined.271- **Not drawn**: the summary's `unmapped=` count and each resource type listed under272 `## Unmapped resources` with its file, or that none were listed.273- **Environment**: the one drawn, or each environment, and the file that declared it.274- **Diff**: the summary's `diffs=` count, or that `--diff` was not requested.275- **Dialect**: `diagram_dialect.system`, the value, and the layer (`argument`,276 `team convention doc <path>`, or `unset (no C4 view emitted)`).277- **Containers**: `map-containers` output was used, or it was absent and names came from the IaC.278- **Secrets**: redacted. No secret value was written.279- **Live**: not requested, or requested and refused. No cloud API was called.280281## Interactive view282283After the report, offer an interactive view of `deployment.json` in one sentence. The markdown and284the record stay authoritative. Build it only with285`${CLAUDE_PLUGIN_ROOT}/scripts/build-view.mjs deployment`, never hand-written; the shared medium286resolver decides the destination, with this plugin's `medium` option `${user_config.medium}`, or `""`287when that reads empty or unsubstituted (never put a `${user_config.*}` string in a shell command), and288its report line is printed. Procedure:289[`${CLAUDE_PLUGIN_ROOT}/reference/rendered-view.md`](${CLAUDE_PLUGIN_ROOT}/reference/rendered-view.md).290291## What this skill does NOT do292293- Call a cloud API, use credentials, or compare live state to the declaration.294- Run `terraform`, read Terraform state, or fetch a remote module.295- Run `bicep` or `az`, restore a registry module, or evaluate an ARM function.296- Run `aws` or `pulumi`, expand a CloudFormation `Transform`, or evaluate `Fn::If`, `Fn::FindInMap`,297 `Fn::Join`, or a Pulumi `fn::*` function.298- Cost, scaling, capacity, or runtime health.299- Apply Helm templates or Kustomize. Those tools are a refusal, not a guessed render.300- Add a dialect key, read `landscape_dialect`, or emit mermaid. The dialect is the existing301 `diagram_dialect.system`.302- Invent a home, a network, or a node the script did not emit.303304## Next305306- The topology settles a decision worth keeping: `/architecture:record-decision`.307- The topology needs a deployment change decided: `/planning:design system`.308- The question is which systems the repository sits among: `/architecture:map-landscape`.309310## Gotchas311312- **C4 scopes a deployment diagram to one environment.** This skill writes one fenced block with313 every environment inside it as its own deployment environment; `--env` narrows the block to314 one. The diff is a table, not a picture. Pointer: when checking a deployment view's scope or315 elements, fetch [C4 deployment diagram § Scope](https://c4model.com/diagrams/deployment#scope) and [§ Primary and supporting elements](https://c4model.com/diagrams/deployment#primary-and-supporting-elements)316 live. As of: 2026-11-10. Recheck trigger: that page changes the scope or the primary elements.317- **C4-PlantUML deployment syntax: read against the README, never run.** The renderer writes the318 macros. The `C4_Deployment` include name is our inference from the README's container319 example. No PlantUML run has parsed this output. `Rel` is drawn from a container to a network320 node its placement names, and from a Kubernetes Service or Ingress node to a container in the321 record's `relationships`. Pointer: when checking the macros or the include the renderer322 writes, fetch [C4-PlantUML README § Deployment diagram](https://github.com/plantuml-stdlib/C4-PlantUML/blob/master/README.md#deployment-diagram) and323 [§ Including the C4-PlantUML library](https://github.com/plantuml-stdlib/C4-PlantUML/blob/master/README.md#including-the-c4-plantuml-library) live. As of: 2026-11-10. Recheck trigger: that README changes the deployment macros or the324 include path, or a host with Java can run PlantUML over a rendered block.325- **LikeC4 deployment syntax: parsed by the CLI.** The record is a probe: `likec4@1.59.4326 validate` exits 0 on the golden blocks in `${CLAUDE_PLUGIN_ROOT}/lib/likec4-golden/`327 (`deployment-compose.c4`, `deployment-kubernetes.c4`, `deployment-ecs-shared.c4`), which328 `collect-deployment.test.sh` diffs against. Pointer: when checking the syntax the collector329 writes, fetch [LikeC4 deployment model § Deployment nodes](https://likec4.dev/dsl/deployment/model/#deployment-nodes),330 [§ Deployed instances](https://likec4.dev/dsl/deployment/model/#deployed-instances), [§ Deployment relationships](https://likec4.dev/dsl/deployment/model/#deployment-relationships)331 and [deployment views § View definition](https://likec4.dev/dsl/deployment/views/#view-definition) live. As of: 2026-11-10. Recheck trigger: any of those sections changes that syntax, or a332 newer `likec4` release ships: set `LIKEC4_VALIDATE=1` when running the test to re-run the CLI.333- **Labels cannot leave the block.** Quotes, backticks, backslashes, and line breaks are stripped334 from labels, `@` prints as `(at)`, and every identifier is prefixed and numbered, so a hostile335 name cannot close the fence, end the diagram, or collide with a keyword.336- **Compose without a `networks` entry joins the default network.** A service that declares none337 is recorded on `default`; a service that names a network is recorded on that network.338- **A required secret is not a topology fact.** The value is dropped. The diff can say the339 parameter differs. It cannot show the value.340- **CloudFormation and Pulumi values are resolved, never evaluated.** A parameter or config value341 resolves only through the sources listed above. Every other function (`Fn::If`, `Fn::FindInMap`,342 `Fn::Join`, `GetAtt`, a pseudo parameter such as `AWS::Region`, `fn::join`, a Pulumi variable) is343 recorded as `unresolved:<text>`. A resource `Condition`, `Mappings`, and `Fn::ForEach` are not344 applied, so a conditional resource is drawn in every environment. Only the ECS types above are345 mapped: an EKS cluster, a Lambda, or an `aws:eks` or `kubernetes:` Pulumi resource is not drawn,346 and its type is listed under `## Unmapped resources`. A service whose task definition is not347 declared in the same template is placed as one container whose image is348 `unresolved:taskDefinition`. YAML parameter files and CloudFormation git-sync deployment files349 are not read.350- **CloudFormation and Pulumi secrets.** A parameter with `NoEcho: true`, any value holding a351 `{{resolve:...}}` dynamic reference, every container `Secrets` entry, a Pulumi `config` key with352 `secret: true`, a `secure:` stack value, a `fn::secret` wrapper, and a parameter or config key353 whose name names a credential are redacted wherever they land, including in a name, image or354 port. A secret that differs between two environments is reported as differing, and neither value355 is printed.356- **CloudFormation template shape.** Claim: the YAML short form `!Ref name` equals357 `Ref: name`, and JSON writes `{ "Ref": "name" }`. Basis:358 <https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/intrinsic-function-reference-ref.html>.359 Claim: `Fn::Sub`, `Fn::GetAtt`, and the other functions take the same `!Name` short form and360 `Fn::Name` long form; `Ref` to a parameter returns its value. Basis: the same reference index,361 <https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference.html>.362 Claim: `AWS::ECS::Service` takes `Cluster`, `DesiredCount`, `ServiceName`, and `TaskDefinition`.363 Basis: <https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-ecs-service.html>.364 As of: 2026-09-30. Recheck when any of those pages changes a form or property name.365- **CloudFormation parameters and secrets.** The redaction and resolution rules above read366 `NoEcho`, `Default` and the `{{resolve:...}}` forms. Pointer: when checking what those mean or367 how a dynamic reference is written, fetch368 [Parameters § Properties](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/parameters-section-structure.html#parameters-section-structure-properties)369 and370 [Dynamic references](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/dynamic-references.html#dynamic-references)371 live. As of: 2026-11-10. Recheck trigger: either section changes the parameter properties or372 the dynamic-reference syntax. Claim: a parameter file is either the `ParameterKey`/`ParameterValue`373 array or a template configuration file with a top-level `Parameters` object. Basis:374 <https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cfn-using-cli-parameters.html>. No375 document names a per-environment file convention, so the pairing rules above are this skill's own.376 As of: 2026-09-30. Recheck when those pages change the syntax or add a parameter file shape.377- **Pulumi YAML program and stack shape.** The reader maps the project file's `runtime`, the378 program's `resources`, `variables` and `outputs`, `config` items, `${...}` interpolation and the379 `fn::toJSON`, `fn::secret` and `fn::join` forms. Pointer: when checking those forms, fetch380 [project file § Attributes](https://www.pulumi.com/docs/concepts/projects/project-file/#attributes), [§ Runtime options](https://www.pulumi.com/docs/concepts/projects/project-file/#runtime-options),381 and the YAML language reference's [§ Config](https://www.pulumi.com/docs/iac/languages-sdks/yaml/yaml-language-reference/#config), [§ Interpolation](https://www.pulumi.com/docs/iac/languages-sdks/yaml/yaml-language-reference/#interpolation),382 [§ Built-in variables](https://www.pulumi.com/docs/iac/languages-sdks/yaml/yaml-language-reference/#built-in-variables), [§ fn::toJSON](https://www.pulumi.com/docs/iac/languages-sdks/yaml/yaml-language-reference/#fntojson),383 [§ fn::secret](https://www.pulumi.com/docs/iac/languages-sdks/yaml/yaml-language-reference/#fnsecret) and [§ fn::join](https://www.pulumi.com/docs/iac/languages-sdks/yaml/yaml-language-reference/#fnjoin) live. As of: 2026-11-10. Recheck trigger: any of those sections changes a key or a form. Claim:384 `Pulumi.<stack>.yaml` holds a `config` map keyed `[<namespace>:]<key>`, the project name is the default385 namespace, and an encrypted value is `secure: <ciphertext>`. Basis:386 <https://www.pulumi.com/docs/concepts/config/> and387 <https://www.pulumi.com/docs/iac/concepts/secrets/>. Claim: `aws:ecs:Service` takes `cluster`,388 `taskDefinition`, `desiredCount`, and `name`, and `aws:ecs:TaskDefinition` takes `containerDefinitions`389 as `fn::toJSON` over a list of `name`, `image`, `portMappings` (`containerPort`). Basis:390 <https://www.pulumi.com/registry/packages/aws/api-docs/ecs/service/> and391 <https://www.pulumi.com/registry/packages/aws/api-docs/ecs/taskdefinition/>. As of: 2026-09-30.392 Recheck when any of those pages changes a key, the `secure:` form, or the `runtime` forms.393- **Bicep and ARM values are resolved, never evaluated.** A parameter resolves from a module394 `params` argument, then the environment's parameters file, then its default, and `${name}` inside395 a Bicep string the same way. An ARM value resolves only when it is exactly396 `[parameters('<name>')]`; `[[` opens a literal. A parameter marked `@secure()`, typed397 `securestring` or `secureobject`, given a Key Vault `reference`, or named for a credential is398 redacted wherever it lands, as is a `secretRef` or `secureValue` env entry. Every var, function, and conditional is recorded399 as `unresolved:<expression>`. A `for` or `copy` loop is placed once, an `if` or `condition` is400 ignored, a `resourceId` with scope arguments matches nothing, and `Microsoft.App/jobs` is not401 mapped. A child resource nested in its parent (a Bicep `resource` inside a body, an ARM402 `resources` array inside a resource) is listed under its full type, such as403 `Microsoft.Storage/storageAccounts/blobServices`. A `Microsoft.Web/sites/slots` nested in its site,404 or naming it as its Bicep `parent`, whose fx version reads `DOCKER|` is the exception: it places405 the container `<site>/<slot>`, its full resource name, on the site's `serverFarmId`, with its own406 `appSettings`. Any other slot, including a top-level ARM one, is listed. A container app or container407 group whose containers are an expression, an empty list, or absent places one container named for408 the resource, its image `unresolved:<expression>` or `unresolved:containers`. Every other resource409 type, and a site whose fx version does not read `DOCKER|` (listed as `Microsoft.Web/sites`), is410 listed under `## Unmapped resources`.411- **Bicep module and parameter file forms.** The reader tells a local module path from a registry412 or template-spec source, and pairs a `.bicepparam` file with its template through its `using`413 line. Pointer: when checking which module paths are local or how a parameters file names414 its template, fetch [Bicep modules § Path to a module](https://learn.microsoft.com/azure/azure-resource-manager/bicep/modules#path-to-a-module)415 ([§ Local file](https://learn.microsoft.com/azure/azure-resource-manager/bicep/modules#local-file), [§ File in registry](https://learn.microsoft.com/azure/azure-resource-manager/bicep/modules#file-in-registry), [§ File in template spec](https://learn.microsoft.com/azure/azure-resource-manager/bicep/modules#file-in-template-spec))416 and [parameter files § Define parameters file](https://learn.microsoft.com/azure/azure-resource-manager/bicep/parameter-files#define-parameters-file) and [§ Extendable parameters file](https://learn.microsoft.com/azure/azure-resource-manager/bicep/parameter-files#extendable-parameters-file)417 live. As of: 2026-11-10. Recheck trigger: either page changes a path form or the `using` statement.418- **ARM expressions are bracketed strings.** The reader resolves only `[parameters('<name>')]`419 and reads `[[` as a literal. Pointer: when checking the expression and escape rules, fetch420 [template expressions § Escape characters](https://learn.microsoft.com/azure/azure-resource-manager/templates/template-expressions#escape-characters)421 live. As of: 2026-11-10. Recheck trigger: that section changes the escape rule.422- **A nested child resource carries one type segment.** The reader lists a child nested in its423 parent under the parent's full type plus the child's segment (`Microsoft.Web/sites/slots`).424 Pointer: when checking how a nested child writes its type, fetch425 [Bicep child resource name and type § Within parent resource](https://learn.microsoft.com/azure/azure-resource-manager/bicep/child-resource-name-type#within-parent-resource) and426 [ARM child resource name and type § Within parent resource](https://learn.microsoft.com/azure/azure-resource-manager/templates/child-resource-name-type#within-parent-resource)427 live. As of: 2026-11-10. Recheck trigger: either section changes the single-segment rule or the nesting depth.428- **A slot with its own image is placed on its site's plan.** A `DOCKER|` slot places as429 `<site>/<slot>` on the site's App Service plan, naming it by its full resource name, whether it is430 nested in the site or names it with a Bicep `parent`. **Pointer**: when deciding how a child's full431 name is written, or where a slot runs, fetch432 [Bicep child resource name and type § Full resource name outside parent](https://learn.microsoft.com/azure/azure-resource-manager/bicep/child-resource-name-type#full-resource-name-outside-parent),433 [ARM child resource name and type § Outside parent resource](https://learn.microsoft.com/azure/azure-resource-manager/templates/child-resource-name-type#outside-parent-resource) and434 [App Service plans § Considerations for running and scaling an app](https://learn.microsoft.com/azure/app-service/overview-hosting-plans#considerations-for-running-and-scaling-an-app)435 live. **As of**: 2026-11-10. **Recheck trigger**: a read of any of those sections diverges from the placement above.436- **Terraform values are resolved, never evaluated.** `var.X` resolves from a module call argument,437 then the root's tfvars files, then the variable `default`, and `${var.X}` inside a string the438 same way. A variable declared `sensitive = true`, or named for a credential, is redacted wherever439 it lands. Everything else, such as locals, functions other than `jsonencode`, conditionals,440 for-expressions, `file()`, and `templatefile()`, is recorded as `unresolved:<expression>`. `count`441 and `for_each` are not expanded (the resource is placed once), a `dynamic` block is not read, and442 an env list built by an expression records no parameters. A container app, Cloud Run service, or443 Kubernetes workload whose containers are a `dynamic` block or an expression places one container444 named for the resource, its image `unresolved:dynamic container` (`containers` for Cloud Run) or445 `unresolved:container`; a `dynamic` block beside plain ones adds a second, `<name>.dynamic`. An446 ECS task definition with no `container_definitions` places one container, its image447 `unresolved:container_definitions`. A resource with an empty body (`resource "aws_s3_bucket" "b" {}`)448 is placed or listed as unmapped like any other. A `.tf.json` block type or label written as an449 array of objects (`"resource": [{...}]`) reads like the object form.450- **Only `./` and `../` sources are local.** The reader treats only those module sources as451 local. Pointer: when checking how a local module path is written, fetch452 [module block § Local paths](https://developer.hashicorp.com/terraform/language/block/module#local-paths)453 live. As of: 2026-11-10. Recheck trigger: that section changes how a local path is written.454- **Auto-loaded tfvars rank below the environment's file.** The reader ranks the environment's455 `<env>.tfvars` above the auto-loaded tfvars files, and a variable `default` lowest. Pointer:456 when checking Terraform's precedence, fetch457 [input variables § Assign values to variables](https://developer.hashicorp.com/terraform/language/values/variables#assign-values-to-variables)458 live. As of: 2026-11-10. Recheck trigger: that section changes the precedence list.459- **A `.tf.json` block may be an array of objects at any level.** Claim: each label level of a460 block (a resource's type and name) and its body may be a JSON object or a JSON array of objects,461 so `"resource": [{"aws_s3_bucket": {"b": {}}}]` declares the same resource as the object form.462 Basis: <https://raw.githubusercontent.com/hashicorp/hcl/main/json/spec.md> (Blocks). As of:463 2026-09-30. Recheck when that spec changes where an array may stand in for an object.464- **One task definition, several services.** Each service that runs a shared task definition places465 the task definition's containers on its own cluster with its own desired count, named466 `<container>@<service>`. The `@` separates the two parts, and a label prints it as `(at)`, like467 any other. **Pointer**: when deciding whether the cluster and the count belong to the service, or468 whether `@` can appear in a container or service name, fetch469 [task definitions](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definitions.html),470 [services](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs_services.html),471 [`name`](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ContainerDefinition.html#ECS-Type-ContainerDefinition-name)472 and [`serviceName`](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_CreateService.html#ECS-CreateService-request-serviceName)473 live. **As of**: 2026-10-04. **Recheck trigger**: a read of any of those sections diverges from474 the `<container>@<service>` placement above.475- **Helm reached through IaC is still Helm.** Claim: the Terraform Helm provider declares a release476 as `resource "helm_release"`, and the Pulumi Kubernetes provider as the type477 `kubernetes:helm.sh/v3:Release`. Basis:478 <https://raw.githubusercontent.com/hashicorp/terraform-provider-helm/main/docs/resources/release.md>479 and <https://www.pulumi.com/registry/packages/kubernetes/api-docs/helm/v3/release/>. As of:480 2026-09-30. Recheck when either page renames the type. Either one declines Helm, which refuses the481 whole record as `partial-read`, because the chart's workloads are not read. `kubernetes_manifest`482 and the `kubernetes_*` types the Terraform reader does not map appear under `## Unmapped483 resources`, since the Kubernetes tool itself is a shipped reader.484- **`--live` is a refusal.** Committed files are not silently substituted for a live comparison.485- **A reformatted record is refused.** Render exits 1 and writes nothing.486- **Tracked files only.** `git ls-files` is the source list. A tracked symlink is skipped, so it487 cannot pull in an untracked file.