powerforge-library-builder

# PowerForge Library Builder Use this skill for repository/package pipelines (`Invoke-ProjectBuild`), including NuGet + GitHub release workflows. Prefer one entrypoint script: `Build/Build-Project.ps1`. ## Golden Path (Do This In Order) 1. Confirm repository scope and branch hygiene. - Prefer feature branch/worktree. 2. Validate `project.build.json`. - Discovery filters (`IncludeProjects`, `ExcludeProjects`, expected map include mode). - Version expectations and version sources. 3. Generate plan before publishing. - Use `PlanOnly` or cmdlet `-Plan` first. 4. Execute build/pack/sign path. - Ensure staging/output paths are deterministic. - Treat `CleanStaging` as artifact cleanup only; release compilation freshness is enforced by PowerForge. - Require primary managed package assemblies to match the fresh release build before signing or publishing; do not treat native runtime assets or metadata-only packages as managed assembly payloads. - Keep `Build-Project.ps1` minimal (param pass-through + `Invoke-ProjectBuild` call). - Do not keep legacy wrapper scripts (`Build-AllPackages.ps1`, `Publish-*.ps1`, `Update-Version.ps1`) unless explicitly required. 5. Publish NuGet with explicit fail-fast and duplicate policy. 6. Publish GitHub release with explicit tag policy. - Choose `Single` or `PerProject` intentionally. - Set `GitHubPrimaryProject` for single-mode version source. 7. Handle tag conflicts intentionally. - Prefer configurable conflict policy instead of ad-hoc retries. 8. Verify final release state. - Confirm release/tag and attached asset set match plan. - Inspect the published package content when the release adds or changes public APIs; version visibility and a valid signature alone do not prove the payload is current. - If an immutable feed already contains a stale package, publish a corrected higher version and keep consumers off the bad version. 9. Update docs/schema/help for any new config fields. 10. Keep engine boundaries explicit. - Use `Invoke-ProjectBuild` for package/release pipelines. - Use DotNet publish engine (`Invoke-DotNetPublish`, `New-ConfigurationDotNet*`) for service/app publish packaging. ## High-Value Commands ```powershell # Plan-only Invoke-ProjectBuild -ConfigFilePath .\Build\project.build.json -Plan # Full run Invoke-ProjectBuild -ConfigFilePath .\Build\project.build.json # Validate core tests after engine changes dotnet test .\PowerForge.Tests\PowerForge.Tests.csproj -c Release ``` ## Decision Rules - Standard script surface for repos: - Keep `Build/Build-Project.ps1` and `Build/project.build.json`. - Remove obsolete wrapper scripts once migration is complete. - Keep `Build-Project.ps1` simple: - avoid custom coercion/helper blocks when normal nullable bool parameters and splatting are enough. - If projects have mixed versions in `Single` release mode: - set `GitHubPrimaryProject` or use date/timestamp tags by template. - Prefer template-based tags over hardcoded tags: - tokens include `{Project}`, `{Version}`, `{PrimaryProject}`, `{PrimaryVersion}`, `{Repo}`, `{Date}`, `{UtcDate}`, `{DateTime}`, `{UtcDateTime}`, `{Timestamp}`, `{UtcTimestamp}`. - Use explicit conflict policy for existing tags: - `Reuse`, `Fail`, or `AppendUtcTimestamp`. - In plan/what-if mode, avoid hard failures that require produced artefacts on disk. - Never use `CleanStaging` as evidence that project `bin`/`obj` outputs were rebuilt. - Do not publish when PowerForge reports a package payload provenance mismatch. ## Reference Files (Read As Needed) - `references/checklist.md` for quick release-mode and tag-policy decisions. - `Docs/PSPublishModule.ProjectBuild.md` for JSON behavior. - `Docs/PSPublishModule.DotNetPublish.Quickstart.md` when release work also needs app/service publish flows. - `schemas/project.build.schema.json` for allowed fields and enums. - `Module/Docs/Invoke-ProjectBuild.md` for cmdlet behavior.