# Powerforge Library Builder

> Build, version, pack, sign, and publish multi-project .NET libraries using Invoke-ProjectBuild and project.build.json. Use for ExpectedVersionMap/X-pattern resolution, NuGet publishing, GitHub release mode/tag strategy, and release troubleshooting.

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