/convert-to-cpm

name: convert-to-cpm
description: >
  Convert .NET projects and solutions (.sln, .slnx) to NuGet Central Package Management
  (CPM) using Directory.Packages.props. USE FOR: converting to CPM, centralizing or
  aligning NuGet package versions across multiple projects, inlining MSBuild version
  properties from Directory.Build.props into Directory.Packages.props, resolving version
  conflicts or mismatches across a solution or repository, updating or bumping or syncing
  package versions across projects. Also activate when packages are out of sync, drifting,
  or inconsistent -- even without the user mentioning CPM. Provides baseline build capture,
  version conflict resolution, build validation with binlog comparison, and a structured
  post-conversion report. DO NOT USE FOR: packages.config projects (must migrate to
  PackageReference first) or repositories that already have CPM fully enabled.
license: MIT

Convert to Central Package Management

Centralize package versions in `Directory.Packages.props` while preserving project behavior and producing reviewable before/after evidence.

Choose a mode first

Do this before running builds or changing files.

1. **Guard mode** -- If any in-scope project uses `packages.config`, stop. Explain that CPM requires `PackageReference` and recommend migrating first. Do not create or modify files. 2. **Package-maintenance mode** -- A request to update, align, bump, or sync packages authorizes those package edits, not CPM conversion. Audit the named scope, resolve the requested versions, update existing project/shared version declarations, and restore/build every affected CLI target from the directory that establishes its applicable `global.json`. Ask only when the version or alignment policy is ambiguous. Do not create or modify `Directory.Packages.props`, remove versions for CPM, or capture conversion artifacts. Complete the package work, then recommend CPM as the durable follow-up. 3. **Conversion mode** -- Use only when the user explicitly asks to adopt, enable, or convert to CPM. Follow the workflow below.

If the scope is unclear, ask once before proceeding.

Default execution plan

• **Guard**: use a minimal scoped detection pass, then answer and stop.
• **Package maintenance**: use a compact audit, edit only the requested package versions in their existing locations, validate affected targets, then recommend CPM. Do not read conversion references or enter the conversion workflow.
• **Conversion**: batch the preflight, baseline, audit/mutation, final validation, and report work to avoid redundant turns. Revisit a stage only when new CPM-specific evidence requires a targeted follow-up.

This plan is an efficiency default, not a hard cap. Never omit an in-scope project, imported `.props`/`.targets` file, detected complexity, required validation, or deliverable to save a turn. Batch complete work where practical.

Inputs

| Input | Required | Rule | |-------|----------|------| | Scope | Yes | Project, solution, or directory containing the projects to inspect or convert | | Conflict strategy | For package maintenance or conversion with conflicts | If the user already supplied a strategy such as "use the highest version," apply it without asking again and record its impact. Otherwise stop after the audit and ask before editing. |

Read references only when needed

Never preload all references.

| Condition | Read | |-----------|------| | Entering conversion baseline or producing the package diff | [baseline-comparison.md](references/baseline-comparison.md) | | A conflict, conditional reference, shared import, security concern, or `VersionOverride` is detected | [audit-complexities.md](references/audit-complexities.md) | | Placement is unclear or conditional `PackageVersion`/`VersionOverride` is required | [directory-packages-props.md](references/directory-packages-props.md) | | A package version uses an MSBuild property | [msbuild-property-handling.md](references/msbuild-property-handling.md) | | Restore or build fails after conversion | [validation-and-errors.md](references/validation-and-errors.md) | | Writing the final report | [report-template.md](references/report-template.md) |

Conversion workflow

1. Scope and preflight

• Resolve the project/solution scope. For a solution, list its projects. For a directory, search only beneath that directory and create an explicit target set that covers the full scope: use each applicable `.sln`/`.slnx`, then add each project not covered by a solution. Verify that every in-scope project is covered and avoid duplicate work for projects that occur in more than one target. Ask only when overlapping targets or repository boundaries make the intended coverage ambiguous; never ask the user to select one target when that would omit in-scope projects.
• Determine CPM management scopes separately from CLI targets. Group projects that will share one central version policy and place one `Directory.Packages.props` at each group's first common ancestor, while respecting existing nearest-file boundaries. Multiple CLI targets can share one CPM file; independent project groups can require separate files.
• Check for `packages.config`; if found, switch to Guard mode and stop.
• Check the scope and ancestors for `Directory.Packages.props`. If CPM is already fully enabled, report that and stop. If a partial file exists, preserve it and ask only when its intended scope is ambiguous.
• Choose one common artifact directory within the resolved scope, normally the targets' first common ancestor. Use explicit paths into it for every binlog, package snapshot, and the report.
• Run each target's .NET commands from its solution/project directory or another directory that establishes its applicable `global.json`, not from an unrelated parent workspace.
• Do not inspect unrelated projects or host-tool configuration when the user supplied a scope.

2. Capture the baseline

Read [baseline-comparison.md](ref