# Powerforge Module Builder

> Build, validate, install, and publish PowerShell modules with PSPublishModule/PowerForge. Use when working with Invoke-ModuleBuild, Build/Build-Module.ps1, New-ConfigurationBuild, merge/approved modules, versioned install behavior, legacy flat-module migration, and module packaging/signing troubleshooting. Use when this capability is needed.

- Skill: `tomevault-io/powerforge-module-builder` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/powerforge-module-builder`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/powerforge-module-builder/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/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.

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/evotecit) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-11 -->