[matifali]

Description

Adds two rules to AGENTS.md (which CLAUDE.md links to).

Extra CLI arguments: additional_args

• Name and type: additional_args, a list(string) with one element per argument. Not extra_args, additional_arguments, extra_flags, a map, or a free-form string.
• Passing: each element is passed exactly as written and in order, so a flag can repeat (["--header", "a", "--header", "b"]). A map can't do that: Terraform silently keeps only the last value of a repeated map key, so an earlier version of this rule that used a map was changed after review.
• Validation: no element may be empty or contain a newline. A second validation rejects flags the module already passes, checking each element with any =value stripped, with a keep-in-sync comment beside both the list and the command in the script.
• Passing it to the script: base64-encode one argument per line, read it back into an array or set --, and never word-split or eval it. Use printf '%q' when writing it into another generated script.
• Existing modules: keep the old input working, add additional_args beside it, and deprecate the old one under the rule below. code-server and ttyd are noted as predating the rule; their string additional_args stays so existing templates don't break.

Deprecating inputs

Terraform 1.15 added a deprecated argument for variable blocks. Terraform 1.14 and older reject it with An argument named "deprecated" is not expected here, even in templates that never set the input. Coder bundles Terraform 1.15.5 from v2.37.0; v2.31.0 through v2.36.0 bundle 1.14.5 (from TerraformVersion in provisioner/terraform/install.go at each tag). So the rule is:

• Major version bump: set required_version = ">= 1.15" and give every deprecated input a deprecated argument, including inputs deprecated earlier by description only. Note the raised minimum as a breaking change.
• Minor or patch bump: deprecate in the description only (Deprecated: use <new_input> instead.), without raising required_version.
• The message: deprecated takes the warning text, not a boolean. deprecated = true prints the bare message true, and "" prints nothing, so the message must name the replacement. The example keeps the Deprecated: description prefix as well, so registry.coder.com shows the deprecation until coder/registry-server reads the native argument.

I checked this against Terraform 1.13.0 through 1.17.0: 1.15 and later warn only when a caller sets the deprecated input, and 1.13 and 1.14 fail to parse. The PR review checklist now covers both points.

Modules following these rules

Already merged and released:

• agent-relay-claude-code v0.4.0 (coder/registry#1205)
• agent-relay-cursor v0.7.0 (coder/registry#1206)

Open:

• coder/registry#1200 git-clone 2.1.0: deprecates extra_args by description, since this is a minor bump
• coder/registry#1201 mux 2.1.0: deprecates additional_arguments by description, since this is a minor bump

Type of Change

• New module
• New template
• Bug fix
• Feature/enhancement
• Documentation
• Other

Testing & Validation

• Tests pass (bun test) — documentation only
• Code formatted (bun fmt)
• Checked the deprecated behavior with Terraform 1.13.0, 1.14.0, 1.15.0, 1.16.0 and 1.17.0, and the list(string) validation on 1.9.8 and 1.17.0

Related Issues

None

🤖 Generated with Claude Code

https://claude.ai/code/session_01R2TMgCPW8SL8kUCB28L4dt

[35C4n0r]

This would need a follow up PR in coder/registry-server to properly handle deprecated variables.
Alternative we can add deprecation: <text> to description.

[matifali]

Keeping the major-bump rule. The description prefix is already part of it: on a minor or patch bump the Deprecated: use X instead. description is the only signal, and on a major bump the example keeps that prefix alongside deprecated = "...". So registry.coder.com shows the deprecation from the description until coder/registry-server reads the native argument, and that follow-up can land on its own schedule.

---

Generated by Claude Code

[linear-code]

REG-135