powerforge-module-builder

# PowerForge Module Builder Use this skill for module build pipeline work, not website work. ## Golden Path (Do This In Order) 1. Confirm repo/branch hygiene before changes. - Prefer a feature branch or git worktree. - Keep unrelated paths clean. 2. Preflight configuration. - Locate `Build/Build-Module.ps1` and module root (`Module/`). - Check `New-ConfigurationBuild` and install settings first. 3. Produce JSON plan/config before invasive changes. - Use `Invoke-ModuleBuild -JsonOnly -JsonPath ...` when possible. 4. Run the real module build. - Prefer repo script `Build/Build-Module.ps1`. 5. Validate outcomes from summary + logs. - Check merge summary, missing commands, required modules, and import step. 6. Apply install compatibility policy intentionally. - Default is warn-only for legacy flat installs. - Use explicit behavior when migrating old flat installs. 7. Keep fail-fast ordering. - Validate/import before signing when changing pipeline order. 8. Verify both engines. - Validate PowerShell 5.1 path (`WindowsPowerShell`) and PowerShell 7+ path. 9. Validate tests/build. - Run focused tests first, then broader tests. 10. Document config and migration behavior. - Update docs/schema/help when adding parameters. 11. Respect generated docs boundaries. - `Module/Docs` and `Module/en-US/*-help.xml` are generated. - Author source docs in code comments and about-topic sources (`Help/About/about_*`), not directly in generated files. ## High-Value Commands ```powershell # Generate pipeline JSON only (no execution) Invoke-ModuleBuild -ModuleName 'MyModule' -Path . -JsonOnly -JsonPath .\powerforge.json -Settings { ... } # Run standard module build entrypoint .\Build\Build-Module.ps1 # Focused tests for pipeline changes dotnet test .\PowerForge.Tests\PowerForge.Tests.csproj -c Release # Scaffold about-topic source file New-ModuleAboutTopic -TopicName 'Troubleshooting' -OutputPath '.\Help\About' ``` ## Decision Rules - For mixed legacy flat + versioned installs, prefer explicit config: - `VersionedInstallLegacyFlatHandling`: `Warn`, `Delete`, or `Convert`. - `VersionedInstallPreserveVersions`: versions that must not be removed. - Do not silently change install policy defaults in behavior-changing PRs. - If missing commands are environment-specific (for example RSAT), classify clearly and avoid noisy false positives. ## Reference Files (Read As Needed) - `references/checklist.md` for fast preflight + troubleshooting sequence. - `Module/Docs/Invoke-ModuleBuild.md` for command surface. - `Module/Docs/New-ConfigurationBuild.md` for build/install parameters. - `Docs/PSPublishModule.ProjectBuild.md` when module build and repo release flow intersect. - `Docs/PSPublishModule.ModuleDocumentation.md` for generated-doc workflow and about topics. - `Docs/PSPublishModule.DotNetPublish.Quickstart.md` when module work intersects DotNet publish engine usage.