# 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. Use when this capability is needed.

- Skill: `tomevault-io/powerforge-library-builder` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/powerforge-library-builder`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/powerforge-library-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-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.
   - 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.
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.

## 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.

---
> 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 -->