docs: initialize v0.8 to v1.0 migration guide skeleton

CHANGELOG.md

@@ -7,6 +7,14 @@
 
 ## Unreleased
 
+### Added
+
+- Initialize v0.8 → v1.0 migration guide skeleton at
+  `docs/migration-v0.8-to-v1.0.md`. Includes an AI-assisted migration
+  prompt (referential style for IDE/CLI agents) and a format spec for
+  per-break entries that Phase 2 PRs will populate. Phase 1 of
+  [#120](https://github.com/psake/PowerShellBuild/issues/120).
+
 ## [0.8.1] 2026-06-03
 
 ### Fixed
@@ -24,13 +32,13 @@
 
 ### Added
 
 - [**#92**](https://github.com/psake/PowerShellBuild/pull/92) Add Authenticode
   code-signing support for PowerShell modules with three new public functions:
   - `Get-PSBuildCertificate` - Resolves code-signing X509Certificate2 objects
     from certificate store, PFX files, Base64-encoded environment variables,
     or pre-resolved certificate objects
   - `Invoke-PSBuildModuleSigning` - Signs PowerShell module files (*.psd1,
     *.psm1, *.ps1) with Authenticode signatures supporting configurable
     timestamp servers and hash algorithms
   - `New-PSBuildFileCatalog` - Creates Windows catalog (.cat) files for
     tamper detection
@@ -59,7 +67,7 @@
 - The `$PSBPreference` variable now supports the following PlatyPS
   `New-MarkdownHelp` and `Update-MarkdownHelp` boolean options:
   - `$PSBPreference.Docs.AlphabeticParamsOrder`
   - `$PSBPreference.Docs.ExcludeDontShow`
   - `$PSBPreference.Docs.UseFullTypeName`
 - The `$PSBPreference` variable now supports the following Pester test
   configuration options:

docs/migration-v0.8-to-v1.0.md

@@ -0,0 +1,143 @@
+# Migrating from PowerShellBuild v0.8 to v1.0
+
+> 🚧 **Pre-release.** v1.0.0 has not shipped yet, and no breaking changes
+> have been documented here. This guide is being prepared alongside the
+> v1.0.0 work; entries are added by each breaking-change PR as it lands.
+> Track progress in
+> [#120 — PowerShellBuild v1.0.0 roadmap](https://github.com/psake/PowerShellBuild/issues/120).
+> If you are on 0.8.x today, there is nothing to migrate yet.
+
+This guide helps you upgrade a consumer `build.ps1` (or equivalent) from
+PowerShellBuild **0.8.x** to **1.0.0**.
+
+It only covers **breaking changes**. For new features and bug fixes that
+do not require user action, see [`CHANGELOG.md`](../CHANGELOG.md).
+
+## Quick Start
+
+> **Status:** no breaking changes have landed yet. This list will be
+> populated by Phase 2 PRs as the migration to Microsoft.PowerShell.PlatyPS
+> 1.x and psake 5.x progresses.
+>
+> Once entries exist, this section will summarize each break in one line
+> with a link into the body below — so you can scan what's likely to
+> affect you before reading the details.
+
+## AI-assisted migration
+
+If you use an IDE or CLI agent (Claude Code, GitHub Copilot in VS Code,
+Copilot CLI, Cursor, Aider, etc.), you can ask it to migrate your build
+file for you. From inside the repository you are migrating, paste this
+prompt:
+
+```text
+You are migrating a PowerShellBuild consumer's build configuration from
+0.8.x to 1.0.0.
+
+Inputs:
+- This migration guide: docs/migration-v0.8-to-v1.0.md in the
+  psake/PowerShellBuild repository on GitHub. Fetch and read it if you
+  have web or repo access; otherwise ask me to paste it.
+- My build file (default: ./build.ps1 for psake, or ./.build.ps1 for
+  Invoke-Build; ask if it lives elsewhere or has a different name).
+- Any psake or Invoke-Build files my build file references.
+
+Task:
+1. Read the migration guide's "Migration entries" section.
+2. For each entry, check whether it applies to my file(s).
+3. Apply applicable entries' migration steps. Preserve all customizations
+   not directly affected by the migration.
+4. If you are uncertain how to apply an entry, leave the original code
+   in place and add a `# MIGRATION-REVIEW: <reason>` comment on the
+   relevant line.
+5. After editing, run my test suite if one is configured. If you don't
+   know how, ask.
+6. Output: a summary of the changes you applied and any review flags
+   you raised.
+
+PowerShellBuild conventions worth knowing:
+- The module is imported with `Import-Module PowerShellBuild`.
+- Configuration goes through `$PSBPreference`, a hashtable populated in
+  build.ps1 before tasks are invoked.
+- Invoke-Build users dot-source the alias after import:
+  `. PowerShellBuild.IB.Tasks`.
+- psake users invoke via `-FromModule PowerShellBuild`.
+```
+
+**Notes on the workflow:**
+
+- The agent reads the migration guide and your build file directly. You
+  do not need to paste either into the prompt.
+- If you are using a web chatbot (Claude.ai, ChatGPT, etc.) without
+  file-system access, paste the relevant entries from this guide and
+  your build file into the conversation alongside the prompt.
+- Always review the agent's output before committing. The
+  `# MIGRATION-REVIEW:` markers (if any) flag lines that need a human
+  decision.
+
+## Migration entries
+
+_No breaking changes documented yet._ Each breaking-change PR adds its
+entry here as it lands; see [Adding an entry](#adding-an-entry-for-pr-contributors)
+below for the format.
+
+<!--
+TEMPLATE / EXAMPLE ENTRY — for PR contributors only; not rendered to
+readers. Copy this structure for a real entry. It uses a FICTIONAL change
+to demonstrate the format; the first real entry's PR can remove this
+comment block.
+
+### `Invoke-PSBuildPlaceholder` renamed its `-LegacyOption` parameter
+
+The function `Invoke-PSBuildPlaceholder` renamed its `-LegacyOption`
+parameter to `-StandardOption`. The behavior is otherwise unchanged.
+
+**Before (0.8.x):**
+
+    Invoke-PSBuildPlaceholder -LegacyOption 'value'
+
+**After (1.0.0):**
+
+    Invoke-PSBuildPlaceholder -StandardOption 'value'
+
+You will see a parameter-binding error referencing `LegacyOption` if you
+do not migrate.
+
+Tracked in PR #999.
+-->
+
+## Adding an entry (for PR contributors)
+
+Every breaking-change PR that lands in v1.0.0 must add an entry here for
+each distinct user-visible break.
+
+Format conventions (loose — match what's useful for the specific break,
+modeled on [`psake/psake docs/migration-v4-to-v5.md`](https://github.com/psake/psake/blob/main/docs/migration-v4-to-v5.md)):
+
+- `###` heading describing the change in user terms (not internal
+  terms — e.g. "`Build-PSBuildMarkdown` now requires a module page
+  path", not "PlatyPS 1.x signature change")
+- A short prose paragraph: what changed and why
+- A `**Before (0.8.x):**` / `**After (1.0.0):**` PowerShell code-block
+  pair, when the migration is a concrete code change
+- A sentence on detection when not obvious from the code (the error
+  message a user will see, or a `grep` pattern to find affected code)
+- A closing reference to the PR and any related issues
+
+Also:
+
+- Add a one-line summary to the **Quick Start** section above, linking
+  to your new entry's heading.
+- Reference this guide from your PR description (the entry it adds).
+
+A commented-out template entry lives in the **Migration entries** section
+above (visible only in the raw Markdown) — copy it as a starting point.
+The first real entry's PR can remove that comment block.
+
+## Related
+
+- Tracking issue: [#120 — PowerShellBuild v1.0.0 roadmap](https://github.com/psake/PowerShellBuild/issues/120)
+- Changelog (non-breaking changes and complete release history):
+  [`CHANGELOG.md`](../CHANGELOG.md)
+- Sibling convention reference:
+  [`psake/psake docs/migration-v4-to-v5.md`](https://github.com/psake/psake/blob/main/docs/migration-v4-to-v5.md)