(MODULES-11829, MODULES-11830) Add synced CLAUDE.md.erb with Linux + Windows specifics by imaqsood · Pull Request #642 · puppetlabs/pdk-templates

imaqsood · 2026-06-09T08:06:10Z

What

Adds a synced, OS-aware CLAUDE.md template to pdk-templates so CAT-supported modules get a conventions file Claude reads before touching code. This PR now delivers two artifacts:

MODULES-11829 — the moduleroot/CLAUDE.md.erb template + the Linux specifics section.
MODULES-11830 — the expanded Windows specifics section (consolidated here; the separate stacked PR (MODULES-11830) Expand Windows specifics in moduleroot/CLAUDE.md #649 is superseded).

Jira: MODULES-11829, MODULES-11830 (epic MODULES-11828, S2 maturity for CAT modules).

How

ERB with OS-conditional content driven by the module's metadata.json, read via @configs['module_metadata']['operatingsystem_support'] with rescue fallbacks — the same convention already used in moduleroot_init/CHANGELOG.md.erb / README.md.erb.
Renders ## Linux specifics and/or ## Windows specifics based on the module's supported OS. Multi-OS modules get both; empty/unknown metadata defaults to Linux.
Linux section: package providers (apt/yum/dnf/zypper), systemd vs init, paths/SELinux, Litmus-on-Docker.
Windows section: platform basics (Chocolatey/MSI, SCM services, backslash/case-insensitive paths, ACLs), DSC resource patterns, PowerShell exec idioms, scheduled_task semantics, native-extension Ruby gotchas, and Windows Litmus/acceptance (real VMs, WinRM, reboots).
Common content: project layout, rake commands, rspec-puppet patterns, coverage, litmus/beaker, Ruby code style, Gemfile gem sourcing + version-pin env vars, type/provider DSL gotchas, task-module conventions, metadata.json conventions, CI/nightly logs, outcome-based review policy, project rules.
Pure ASCII — PDK's diff engine raises invalid byte sequence in US-ASCII on non-ASCII under a non-UTF-8 locale.

Testing

Validated locally with PDK 3.4.0:

Renders ## Linux specifics only for a Linux-only module (lvm), both sections for a Linux+Windows module (concat), and the full Windows subsections (DSC / scheduled_task / native-ext / Litmus) for a Windows-supporting module.
ERB tag balance verified; rendered output is pure ASCII with no leftover <% tags.

🤖 Generated with Claude Code

mehul-jain1

few comments.

mehul-jain1 · 2026-06-10T09:43:56Z

Question regarding Opt-out for modules with an existing CLAUDE.md

For the 5 existing modules, their hand-maintained CLAUDE.md will get overwritten the first time they run pdk update after this lands — unless CLAUDE.md: unmanaged: true is already in their .sync.yml. Since those 5 .sync.yml opt-outs aren't part of this PR, shouldn't they merge first (or atomically) to avoid losing content?

mehul-jain1

LGTM

The merge-base changed after approval.

david22swan

Overall this looks to be a solid framework, but as said in my first comment, having it enforced as a singular truth would limit its effect by preventing Claude from customising it with specific information unique to each Module.

I feel this would be better suited as a one time run in order to get the framework in place, or as a part of moduleroot_init so that it is included with newly created modules.

Honestly, as I see it this would be best as an opt in file for the moduleroot and a default file for moduleroot_init, ensuring that it is automaticall added to any new modules created and that for existing modules, you can manually choose to add it in and then update it to match what the Module needs.

Copilot

Pull request overview

Adds a new CLAUDE.md template to the PDK-managed module root so CAT-supported modules receive a synced contributor/Claude conventions file during pdk convert / pdk update.

Changes:

Introduces moduleroot/CLAUDE.md.erb with standardized guidance on project layout, common commands, testing, style, and review policy.
Implements OS-conditional rendering to include “Linux specifics” and/or “Windows specifics” sections based on metadata.json (@configs['module_metadata']['operatingsystem_support']).

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

@david22swan

Respond to review on #642: - Move CLAUDE.md.erb from moduleroot/ (force-synced on every pdk update) to moduleroot_init/ so it is a one-time default: new modules get it and own it, existing modules are never overwritten (per @david22swan). This also removes the clobber risk for the 5 modules that hand-maintain a CLAUDE.md -- no .sync.yml opt-out needed. moduleroot_init needs no config_defaults entry. - Reframe the header from "do not edit" to "starting point, tailor it to this repo" -- the file is meant to carry module-specific detail, not stay generic. - Drop `has_linux ||= !has_windows`: it mislabelled AIX/Solaris/Darwin-only modules as Linux (@Copilot). Empty/unknown metadata still defaults to Linux. - Keep RuboCop under bundler: `bundle exec rubocop -A`, not bare `rubocop -a` (@Copilot). - Note facts come from facterdb via rspec-puppet-facts/on_supported_os (@david22swan). - Mention spec_helper_acceptance.rb(+_local) for Litmus setup (@david22swan). - Note that rules needing enforcement should be backed by runtime hooks in .claude/, since prose alone can be treated as suggestions (@david22swan). Validated with PDK 3.4.0: pdk new module deploys the file (owned, customizable); pdk update leaves an existing module's copy untouched. Pure ASCII, ERB balanced. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

imaqsood · 2026-07-01T11:01:32Z

Thanks for the reviews — addressed in the two follow-up commits. Summary:

@david22swan

Not force-synced anymore. Moved CLAUDE.md.erb from moduleroot/ to moduleroot_init/, so it's a one-time default: new modules get it via pdk new module / pdk convert and own it — pdk update never overwrites it. That makes it a starting framework each module tailors with its real manifests/types/functions, which was your core point.
Reframed the header from "do not edit" → "starting point, tailor it to this repo".
Added a note that facts come from facterdb (via rspec-puppet-facts / on_supported_os).
Added spec_helper_acceptance.rb (+ _local) to the spec-helpers section.
Added a note that rules needing real enforcement should be backed by runtime hooks in .claude/, since prose alone can be treated as suggestions.

@mehul-jain1

The internal Jenkins/runbook pointers were genericized to "check the GitHub Actions nightly logs", and the MODULES-11830 stub is gone (Windows section fully expanded).
Opt-out ordering resolved: because the file now lives in moduleroot_init (never re-synced), the 5 modules that hand-maintain a CLAUDE.md are never overwritten — no .sync.yml opt-out and no merge-ordering needed.

@copilot

Dropped has_linux ||= !has_windows — it mislabelled AIX/Solaris/Darwin-only modules as Linux. Empty/unknown metadata still defaults to Linux.
RuboCop stays under bundler: bundle exec rubocop -A instead of bare rubocop -a.

Scope note: this PR now also carries the MODULES-11830 Windows-specifics expansion (the separate stacked PR is being closed and folded in here).

Validated with PDK 3.4.0: pdk new module deploys the file (owned/customizable); a subsequent pdk update leaves an existing module's copy untouched. Pure ASCII, ERB balanced, renders Linux/Windows sections per metadata.json. Re-requesting review 🙏

Copilot · 2026-07-01T11:01:41Z

@imaqsood I've opened a new pull request, #652, to work on those changes. Once the pull request is ready, I'll request review from you.

@david22swan

Respond to review on #642: - Move CLAUDE.md.erb from moduleroot/ (force-synced on every pdk update) to moduleroot_init/ so it is a one-time default: new modules get it and own it, existing modules are never overwritten (per @david22swan). This also removes the clobber risk for the 5 modules that hand-maintain a CLAUDE.md -- no .sync.yml opt-out needed. moduleroot_init needs no config_defaults entry. - Reframe the header from "do not edit" to "starting point, tailor it to this repo" -- the file is meant to carry module-specific detail, not stay generic. - Drop `has_linux ||= !has_windows`: it mislabelled AIX/Solaris/Darwin-only modules as Linux (@Copilot). Empty/unknown metadata still defaults to Linux. - Keep RuboCop under bundler: `bundle exec rubocop -A`, not bare `rubocop -a` (@Copilot). - Note facts come from facterdb via rspec-puppet-facts/on_supported_os (@david22swan). - Mention spec_helper_acceptance.rb(+_local) for Litmus setup (@david22swan). - Note that rules needing enforcement should be backed by runtime hooks in .claude/, since prose alone can be treated as suggestions (@david22swan). Validated with PDK 3.4.0: pdk new module deploys the file (owned, customizable); pdk update leaves an existing module's copy untouched. Pure ASCII, ERB balanced. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

@david22swan

Respond to review on #642: - Move CLAUDE.md.erb from moduleroot/ (force-synced on every pdk update) to moduleroot_init/ so it is a one-time default: new modules get it and own it, existing modules are never overwritten (per @david22swan). This also removes the clobber risk for the 5 modules that hand-maintain a CLAUDE.md -- no .sync.yml opt-out needed. moduleroot_init needs no config_defaults entry. - Reframe the header from "do not edit" to "starting point, tailor it to this repo" -- the file is meant to carry module-specific detail, not stay generic. - Drop `has_linux ||= !has_windows`: it mislabelled AIX/Solaris/Darwin-only modules as Linux (@Copilot). Empty/unknown metadata still defaults to Linux. - Keep RuboCop under bundler: `bundle exec rubocop -A`, not bare `rubocop -a` (@Copilot). - Note facts come from facterdb via rspec-puppet-facts/on_supported_os (@david22swan). - Mention spec_helper_acceptance.rb(+_local) for Litmus setup (@david22swan). - Note that rules needing enforcement should be backed by runtime hooks in .claude/, since prose alone can be treated as suggestions (@david22swan). Validated with PDK 3.4.0: pdk new module deploys the file (owned, customizable); pdk update leaves an existing module's copy untouched. Pure ASCII, ERB balanced. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

@david22swan

Respond to review on #642: - Move CLAUDE.md.erb from moduleroot/ (force-synced on every pdk update) to moduleroot_init/ so it is a one-time default: new modules get it and own it, existing modules are never overwritten (per @david22swan). This also removes the clobber risk for the 5 modules that hand-maintain a CLAUDE.md -- no .sync.yml opt-out needed. moduleroot_init needs no config_defaults entry. - Reframe the header from "do not edit" to "starting point, tailor it to this repo" -- the file is meant to carry module-specific detail, not stay generic. - Drop `has_linux ||= !has_windows`: it mislabelled AIX/Solaris/Darwin-only modules as Linux (@Copilot). Empty/unknown metadata still defaults to Linux. - Keep RuboCop under bundler: `bundle exec rubocop -A`, not bare `rubocop -a` (@Copilot). - Note facts come from facterdb via rspec-puppet-facts/on_supported_os (@david22swan). - Mention spec_helper_acceptance.rb(+_local) for Litmus setup (@david22swan). - Note that rules needing enforcement should be backed by runtime hooks in .claude/, since prose alone can be treated as suggestions (@david22swan). Validated with PDK 3.4.0: pdk new module deploys the file (owned, customizable); pdk update leaves an existing module's copy untouched. Pure ASCII, ERB balanced. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

@configs

…root_init Ship a module-shaped CLAUDE.md so CAT-supported modules get a conventions file Claude reads before touching code. Delivers both MODULES-11829 (the template + Linux specifics) and MODULES-11830 (Windows specifics). - Lives in moduleroot_init/ (not moduleroot/), so it is a one-time default: new modules get it via `pdk new module` / `pdk convert` and own it -- `pdk update` never overwrites it, and modules that already hand-maintain a CLAUDE.md are never clobbered. - OS-conditional via the module's metadata.json, read as @configs['module_metadata']['operatingsystem_support'] with rescue fallbacks (same convention as moduleroot_init/CHANGELOG.md.erb / README.md.erb). Renders "Linux specifics" and/or "Windows specifics"; empty/unknown metadata defaults to Linux. - Linux: package providers (apt/yum/dnf/zypper), systemd vs init, paths/SELinux, Litmus-on-Docker. Windows: Chocolatey/MSI + SCM services + ACL/paths, DSC resource patterns, PowerShell exec idioms, scheduled_task semantics, native-extension gotchas, and Windows Litmus/WinRM/reboot notes. - Common content: project layout, rake commands, rspec-puppet (facterdb via rspec-puppet-facts/on_supported_os), coverage, litmus/beaker (incl. spec_helper_acceptance.rb), Ruby style (rubocop strict, run under bundle exec), Gemfile gem sourcing + version-pin env vars, type/provider DSL gotchas, task-module conventions, metadata.json, CI/nightly logs, outcome-based review policy, and project rules paired with .claude runtime hooks. - Header frames it as a starting point to tailor per repo, not an immutable file. - Pure ASCII (PDK's diff engine raises invalid-byte-sequence on non-ASCII under a non-UTF-8 locale). Validated with PDK 3.4.0: `pdk new module` deploys the file (owned, customizable); `pdk update` leaves an existing copy untouched; renders Linux/Windows sections per metadata.json; ERB balanced, no leftover tags. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

changes done as per suggested

david22swan

LGTM

Are we waiting on the CoPilot pr or is that to be ignored?

imaqsood requested a review from a team as a code owner June 9, 2026 08:06

imaqsood force-pushed the MODULES-11829-moduleroot-claude-md branch from d6daa55 to b4cb1f0 Compare June 9, 2026 08:09

imaqsood mentioned this pull request Jun 9, 2026

(MODULES-11832) Add synced PR template with outcome-based review policy #643

Merged

mehul-jain1 reviewed Jun 10, 2026

View reviewed changes

Comment thread moduleroot/CLAUDE.md.erb Outdated

Comment thread moduleroot/CLAUDE.md.erb Outdated

Comment thread moduleroot_init/CLAUDE.md.erb

Comment thread moduleroot_init/CLAUDE.md.erb

david22swan closed this Jun 11, 2026

david22swan deleted the MODULES-11829-moduleroot-claude-md branch June 11, 2026 15:15

david22swan restored the MODULES-11829-moduleroot-claude-md branch June 12, 2026 09:50

david22swan reopened this Jun 12, 2026

mehul-jain1 self-requested a review June 22, 2026 09:43

mehul-jain1 previously approved these changes Jun 22, 2026

View reviewed changes

imaqsood force-pushed the MODULES-11829-moduleroot-claude-md branch 2 times, most recently from c697470 to 72fef79 Compare June 24, 2026 14:17

imaqsood requested review from LukasAud, actowery, bronachfalls, david22swan, gavindidrichsen, gregohardy and pmcmaw June 25, 2026 16:46

imaqsood mentioned this pull request Jun 28, 2026

(MODULES-11830) Expand Windows specifics in moduleroot/CLAUDE.md #649

Closed

3 tasks

david22swan previously requested changes Jun 29, 2026

View reviewed changes

Comment thread moduleroot/CLAUDE.md.erb Outdated

Comment thread moduleroot_init/CLAUDE.md.erb

Comment thread moduleroot_init/CLAUDE.md.erb

Comment thread moduleroot_init/CLAUDE.md.erb

david22swan requested a review from Copilot June 29, 2026 14:39

Copilot started reviewing on behalf of david22swan June 29, 2026 14:40 View session

Copilot AI reviewed Jun 29, 2026

View reviewed changes

Comment thread moduleroot/CLAUDE.md.erb Outdated

Comment thread moduleroot/CLAUDE.md.erb Outdated

imaqsood changed the title ~~(MODULES-11829) Add synced moduleroot/CLAUDE.md.erb~~ (MODULES-11829, MODULES-11830) Add synced CLAUDE.md.erb with Linux + Windows specifics Jul 1, 2026

imaqsood requested a review from david22swan July 1, 2026 11:01

imaqsood requested a review from mehul-jain1 July 1, 2026 11:01

Copilot AI mentioned this pull request Jul 1, 2026

(MODULES-11829, MODULES-11830) Add initial CLAUDE.md.erb template (moduleroot_init) with Linux + Windows specifics #652

Draft

5 tasks

imaqsood force-pushed the MODULES-11829-moduleroot-claude-md branch from 3772d7b to 6795912 Compare July 1, 2026 11:06

imaqsood force-pushed the MODULES-11829-moduleroot-claude-md branch from 6795912 to aea7507 Compare July 1, 2026 11:08

imaqsood force-pushed the MODULES-11829-moduleroot-claude-md branch from aea7507 to 35aeb59 Compare July 3, 2026 13:10

imaqsood force-pushed the MODULES-11829-moduleroot-claude-md branch from 35aeb59 to abaa7b2 Compare July 3, 2026 13:37

david22swan approved these changes Jul 14, 2026

View reviewed changes

Uh oh!

Conversation

imaqsood commented Jun 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

How

Testing

Uh oh!

mehul-jain1 left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mehul-jain1 commented Jun 10, 2026

Uh oh!

mehul-jain1 left a comment

Choose a reason for hiding this comment

Uh oh!

david22swan left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

imaqsood commented Jul 1, 2026

Uh oh!

Copilot AI commented Jul 1, 2026

Uh oh!

david22swan left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

imaqsood commented Jun 9, 2026 •

edited

Loading

mehul-jain1 left a comment •

edited

Loading