docs: standardize module data layout under ~/.coder-modules#869
Merged
docs: standardize module data layout under ~/.coder-modules#869
Conversation
mafredri
reviewed
Apr 23, 2026
Member
mafredri
left a comment
mafredri
left a comment
There was a problem hiding this comment.
Clean docs-only PR with a clear scope and good structure. One P2 finding from the first pass.
This is a first-pass review from Netero only. The full review panel has not yet reviewed this PR. The panel will review after this finding is addressed.
"Logs go to
module_directory/*.log, notmodule_directory/logs/*.log. Scripts similarly go tomodule_directory/*.sh, notmodule_directory/scripts/*.sh. The 'aligns with' and 'for free' claims are false." - Netero
🤖 This review was automatically generated with Coder Agents.
mafredri
reviewed
Apr 23, 2026
matifali
force-pushed
the
matifali/agents-md-module-data-layout
branch
from
16fee81 to
aa8e551
Compare
matifali
added a commit
that referenced
this pull request
Apr 23, 2026
## Summary
Move script files from the flat `${module_directory}` to a `scripts/`
subdirectory, and prefix each script's filename with
`${agent_name}-utils-` so multiple `coder-utils` instances can safely
share a `module_directory`. Mirrors the layout #870 established for
`logs/` and aligns with the Module Data Layout standard in `AGENTS.md`
(#869).
## Changes
- Compute `local.scripts_directory = "${var.module_directory}/scripts"`
and use it for every `*.sh` path.
- Script filenames are now
`${agent_name}-utils-{pre_install,install,post_install,start}.sh` so two
`coder-utils` instances don't collide on disk.
- Pre-install and install `coder_script`s `mkdir -p` the `scripts/`
sub-path before writing their `.sh`; post-install and start sync-depend
on install, so the directory already exists by the time they run.
- Update the `module_directory` description to call out the nested
`scripts/` and `logs/` paths.
- Add `test_scripts_nested_under_module_directory` asserting the new
paths (including the `${agent_name}-utils-` prefix) and the `mkdir -p`
in each script.
- README: add a "Script file locations" section documenting the new
layout.
- Bump module version to `v1.3.0`.
## Breaking Changes
Consumers reading `${module_directory}/install.sh` (and friends)
directly must look under
`${module_directory}/scripts/${agent_name}-utils-install.sh` instead. No
in-repo consumers exist today.
## Validation
- `terraform fmt -recursive` clean
- `terraform validate` clean
- `terraform test` → 16/16 pass (includes the new
`test_scripts_nested_under_module_directory`)
- `bun test main.test.ts` → 5/5 pass
- `prettier --check` clean
> 🤖 This PR was created with the help of Coder Agents, and needs a human
review. 🧑💻
DevelopmentCats
approved these changes
Apr 23, 2026
Collaborator
There was a problem hiding this comment.
Honestly @matifali this looks perfect for all the new logic, and I have no complaints ❤️
…form conventions - Remove agent_name-utils- prefix reference (dropped in PR 874) - Add templatefile() pattern with encoding rules table for .tftpl variables - Add start_script to coder-utils example (was missing) - Add scripts output pass-through pattern - Add variable/output ordering convention and sensitive = true guidance - Add .tftest.hcl command = plan vs apply guidance - Add count vs for_each rule for optional singletons
mafredri
reviewed
Apr 24, 2026
Member
mafredri
left a comment
mafredri
left a comment
There was a problem hiding this comment.
Post-merge approve. Looks good, nice job! 👍🏻
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Standardize where modules write runtime data on the workspace so troubleshooting has a single, predictable location, and point module authors at
coder-utilsfor script orchestration.All runtime data now lives under
$HOME/.coder-modules/<namespace>/<module-name>/, with standard subdirs forlogs/andscripts/. Tool-specific config and state (wherever the tool expects them) are explicitly out of scope so we don't fight the tool.Changes
AGENTS.md(picked up byCLAUDE.mdvia the existing symlink).logs/,scripts/).coder-utilsfor Script Orchestration section recommendingcoder-utilsfor any new or reworked module.Notes
Existing Coder-owned modules (e.g.
claude-code,aider,goose,amazon-q) still use the old~/.<module>-module/paths. They are intentionally out of scope for this PR and will be migrated individually so each change can be reviewed and version-bumped independently.Addresses: #782 (comment)