claude-code-plugins

Repository context

The current repository is both the CONSUMER, whose convention home declares where artifacts land,
and the DEFAULT SUBJECT, the repository 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. One diagram is one deployment environment.

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 it does not add a 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 writes it 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 means read
<home>/architecture/README.md for architecture_dir. Exit 1, 2, and 3 mean there is 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,
   then the documented default. There is no personal overlay.
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 it is
present it must be schema_version 1. 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, both when both are present:

• Docker Compose (compose.yaml, docker-compose.yml, and compose.<env>.yaml). The environment
  is the filename suffix, or the parent directory when the file sits under deploy/<env>/.
• Kubernetes manifests whose kind is Deployment, StatefulSet, DaemonSet, Service, or Ingress.
  Each container of a workload, a sidecar included, is its own placement.
  The environment is the namespace, otherwise the parent directory.

Terraform, Pulumi, Bicep, CloudFormation, Helm, and Kustomize are recognized. If any of them is
present, the record is refused, including when Compose or Kubernetes is also present. A diagram of
only the shipped tool would be a partial read. A repository whose only IaC is an unshipped tool is
refused as adapter-not-shipped, not drawn empty.

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". 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 does not print either value.

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 diff table is the first section after the tools. An
unknown --env 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>

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

What this skill does NOT do

• Call a cloud API, use credentials, or compare live state to the declaration.
• 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 question is which systems the repository sits among: /architecture:map-landscape.

Gotchas

• A deployment diagram is one environment. Scope is one or more software systems within a
  single deployment environment. Deployment nodes are where instances run, and they nest.
  Infrastructure nodes such as networks and ingress are supporting elements. Verified 2026-09-28
  against https://c4model.com/diagrams/deployment. Recheck when that page changes the scope or
  the primary elements. This skill draws one diagram per environment so a diff does not become a
  single mixed picture.
• C4-PlantUML shape. The block uses !include <C4/C4_Deployment>,
  Deployment_Node(alias, label, ?type, ?descr) with a { } body for nesting,
  Container(alias, label, ?techn, ?descr), and Rel(from, to, label). Verified 2026-09-28
  against https://github.com/plantuml-stdlib/C4-PlantUML/blob/master/README.md. Recheck when
  that README changes those signatures or the include path. Rel is drawn only from a container
  to a network node its placement names; the record has no other edges.
• LikeC4 shape. Deployment node kinds are declared as deploymentNode <kind> in
  specification, nodes nest in deployment { environment ... }, a model element is placed with
  instanceOf, and a deployment view <name> { include <env>.** } draws one environment. Verified
  2026-09-28 against https://likec4.dev/dsl/deployment/model/ and
  https://likec4.dev/dsl/deployment/views/. Recheck when either page changes that syntax.
• 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.
• Two tools are not half-read. Seeing Terraform beside Compose refuses the whole record.
• --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.