Convert 1GP to 2GP

When to Use This Skill

Convert a managed-released 1GP package to 2GP with sf package convert when requested by an ISV. This workflow gathers and validates both Salesforce CLI org aliases, confirms the permanent Dev Hub association, runs conversion with --code-coverage, verifies the resulting 08c, 0Ho, 05i, and 04t records, and determines whether the converted beta version passed the code-coverage check required for promotion. After a successful conversion, it asks whether the customer wants to promote the verified version and, on an explicit yes, promotes and verifies it. It does not migrate subscriber orgs or finalize the irreversible Move-to-2GP development cutover.

Critical Constraints

Preconditions:

• The latest Salesforce CLI must be installed and the customer must be in a Salesforce DX project containing sfdx-project.json. (check: SalesforceCliAndProjectAvailable)
• The customer's Partner Business Org must have Dev Hub and second-generation managed packaging enabled, and its authenticated CLI alias must resolve successfully. (check: DevHubOrgAuthenticated)
• The 1GP packaging org must be authenticated with Salesforce CLI and its alias must resolve successfully. The namespace of the 1GP package must be linked to the selected Dev Hub. (check: PackagingOrgAuthenticatedAndNamespaceLinked)
• The source package must have at least one managed-released 1GP version. Source API-version eligibility is evaluated by the conversion command and is handled only if Salesforce returns that error. (check: ManagedReleasedPackageVersionEligible)
• The customer must choose either an installation key or installation-key bypass. Never ask the customer to paste an installation key into chat or store it in skill output. (check: InstallationProtectionChoiceProvided)

Operational rules:

• CONVERSATION RULE: ask exactly one question per turn and wait for the customer's answer before asking the next question. Never combine a confirmation, a command request, and a list of additional inputs in one message. When the customer must run a command, provide only that command and ask for its sanitized result; continue after they respond. Start with collect-conversion-details and gather only the identity and package inputs sequentially: Dev Hub alias, 1GP packaging-org alias, 033 package ID, and package namespace. Do not ask about project, version mode, installation protection, wait time, definition file, seed metadata, unpackaged metadata, or apexTestAccess yet. Then run validate-salesforce-cli → validate-devhub-alias → validate-packaging-org-alias → validate-source-package → collect-conversion-options → validate-project-and-namespace → collect-conversion-settings → confirm-conversion-preflight → convert-package → verify-conversion-request → verify-code-coverage. After an explicit yes to the promotion question, continue to promote-converted-version → verify-promoted-version. OPTION QUESTIONS: after identifying the package and released source version, ask every configurable option separately, exactly one question per turn. Show that question's default in brackets and accept either a specific answer or the word default. A default response applies only to the current question; never apply a bundle of defaults or skip later questions. Ask separately for: source version, DX project, installation protection, wait time, definition file changes, seed-metadata availability, unpackaged-metadata availability, and apexTestAccess permission sets. Ask for a seed-metadata directory path only when the customer says seed metadata exists, and for an unpackaged-metadata directory path only when the customer says packaged Apex tests need unpackaged metadata. The option defaults are latest released major.minor; create a new <namespace>-conversion project in the current working directory; installation-key bypass; wait 20 minutes; no changes to the project's default definition file; no seed metadata; no unpackaged metadata; and no apexTestAccess permission sets. Before creating a project, state the exact target path. Never silently reuse an existing project from an earlier conversation or run. The permanent Dev Hub association has no default and must be confirmed separately. Do not ask the customer which API version created the source 1GP version. PROJECT DEFINITION FILE: create or validate the selected DX project before asking the remaining conversion-setting questions. Resolve and show the exact <project-directory>/config/project-scratch-def.json path and its current non-secret contents. Then ask: "Would you like to add or update anything in this definition file for conversion? [default: no changes]" Do not ask the customer to provide a definition-file path. Include --definition-file only when the customer confirms the file is required for conversion. SEED METADATA: first ask: "Do you have seed metadata to include in the conversion? [default: no]" If the answer is no or default, omit --seed-metadata and continue. If the answer is yes, ask in the next turn for the exact seed-metadata directory path, validate it, and use that path. UNPACKAGED METADATA: after the seed-metadata question, ask: "Do your packaged Apex tests need metadata that is not part of the package in order to run? For example, test-only Apex classes, custom objects or fields, or permission sets that must not ship in the package. [default: no]" If the answer is no or default, leave sfdx-project.json unchanged for unpackaged metadata and continue. If the answer is yes, ask in the next turn for the directory path relative to the DX project root, then confirm that the directory exists and contains source-format metadata. Explain the difference when the customer is unsure: seed metadata is deployed so the package metadata itself can deploy, while unpackaged metadata is deployed to the build org only so packaged Apex tests can run for code coverage, and it is never included in the converted package. There is no sf package convert flag for unpackaged metadata. Salesforce CLI reads unpackagedMetadata.path from the sfdx-project.json packageDirectories entry for this package, and only when --code-coverage is set, which this workflow always uses. That entry must have a package value that resolves through packageAliases to the converted package's 0Ho ID. On the first conversion, Salesforce CLI adds a packageAliases entry named after the 1GP package when it creates the converted package, so set package to the exact name Salesforce CLI uses for that alias; read it from the Dev Hub with sf data query --use-tooling-api --target-org <devhub-alias> --query "SELECT Name FROM SubscriberPackage WHERE Id = '<033>'". On a later conversion, use the existing packageAliases entry or the 0Ho ID. The same package requirement applies to apexTestAccess. Show the customer the exact proposed change to that packageDirectories entry, for example "package": "<package-name>", "unpackagedMetadata": { "path": "<directory>" }, and update sfdx-project.json only after they confirm. Preserve every other setting in the file. If that entry already declares package or unpackagedMetadata, show the current values and ask whether to keep or change them instead of proposing a duplicate. When the customer also provides apexTestAccess permission sets, show both changes to the entry together in one proposal. Treat the two aliases as different org roles. The Dev Hub alias owns the new converted Package2 and cannot be changed after the first conversion for this 1GP package. The packaging-org alias identifies the source 1GP DE org and is also required for supported org-shape and metadata troubleshooting. If an alias is missing, guide the customer through sf org login web --alias <alias> (add --set-default-dev-hub for the Dev Hub), then rerun the exact sf org display validation. Do not continue until the customer confirms the displayed org IDs match the intended organizations. ALIAS DISCOVERY AND AUTHENTICATION: both orgs are required for conversion. Handle one org role at a time. Ask the customer for the packaging-org alias and Dev Hub alias if not already provided; never invent or select an alias. Run sf org list --json to check what is authenticated. If an alias is missing, give the customer the exact login command and wait: sf org login web --alias <packaging-org-alias> for the packaging org, and sf org login web --alias <devhub-alias> --set-default-dev-hub for the Dev Hub. For a nonstandard login domain, append a customer-provided --instance-url <url>. After login, require sf org display --target-org <alias> --json; show the alias, username, org ID, and instance URL and ask the customer to confirm the intended org. Never ask for or expose an access token, authorization URL, session ID, or credential file. AUTHENTICATED TERMINAL: run org discovery, login, validation, package queries, conversion, and reporting in one CLI environment and operating-system user profile. The agent may run the displayed login command locally when browser OAuth is supported; otherwise the customer runs it and all remaining commands in their terminal. Never split validation and conversion across environments. Require a successful sf org display --target-org <alias> --json for each alias in the chosen environment. Immediately before conversion, require successful sf org display checks for both aliases in that same environment. When chat-local OAuth succeeded, run conversion in that chat-local environment. On the fallback path, present the conversion command with the instruction: "Run this in the same authenticated terminal where both org display checks succeeded." Do not describe an arbitrary new shell as authenticated merely because it can access the project. Success requires all of the following: the conversion request reaches Status=Success; Package2Id, Package2VersionId, and SubscriberPackageVersionId are present; the converted version report shows ConvertedFromVersionId; and HasPassedCodeCoverageCheck is true. The converted version remains beta until the customer explicitly chooses promotion. SUCCESS RESPONSE: give the customer a complete converted-package summary: source package name, namespace, 033 ID, source version and source 04t; Dev Hub alias and org ID; 08c request ID and status; Package2 name and 0Ho ID; Package2Version 05i ID; SubscriberPackageVersion 04t ID; converted version number; beta/released state; ConvertedFromVersionId; code-coverage percentage and HasPassedCodeCoverageCheck; metadata file count, total metadata size, and whether metadata was removed; build duration when available; installation URL; and any non-secret warnings. State explicitly that the converted version is still beta before promotion. If and only if HasPassedCodeCoverageCheck is true, end the success response with exactly one question: "Would you like to promote this converted package version now?" If the customer says yes, run sf package version promote with the verified 04t and Dev Hub alias, then verify the same 04t reports IsReleased=true. Promotion is irreversible, so never infer consent. If the customer says no, leave the version beta. If coverage did not pass, do not offer promotion. PROMOTION RESPONSE: after verified promotion, give the customer the complete package details again, including all conversion identifiers and source version details, the converted version number, code coverage, metadata counts and size, build duration, installation URL, and Release state: Released. State that promotion succeeded and do not ask the promotion question again. CLI COMMAND CONTRACT — run from the validated Salesforce DX project. Validate each org separately with sf org display --target-org <alias> --json. Start conversion with sf package convert --package <033> --target-dev-hub <devhub-alias> --code-coverage --wait 20 --json plus exactly one of --installation-key-bypass or --installation-key <enter-key-locally>. Append --patch-version <major.minor.patch>, --definition-file <path>, or --seed-metadata <directory> only when the customer selected those options. Unpackaged metadata is never passed as a flag; it comes from the confirmed unpackagedMetadata setting in sfdx-project.json, so run conversion from the DX project root where that relative path resolves. Never place an installation key in chat, logs, generated files, or a command the agent executes on the customer's behalf. If the convert command returns before completion, preserve its 08c ID and run sf package version create report --package-create-request-id <08c> --target-dev-hub <devhub-alias> --json; do not start a duplicate conversion. Once an 08c ID is available, use this report command immediately and then approximately every two minutes until the request reaches Success or Error. After every report, give the customer a short update containing the 08c ID, current status, and any non-secret status details returned by the CLI. Do not say that the same CLI process is still being monitored when request-report polling is available. After Status=Success, run sf package version report --package <04t> --target-dev-hub <devhub-alias> --verbose --json and require both a populated ConvertedFromVersionId and HasPassedCodeCoverageCheck=true. TROUBLESHOOTING — do not proactively ask for or confirm the source package version's API version. If conversion returns an error that the selected 1GP version was created with an unsupported API version, tell the customer to upload a new managed-released 1GP version using API 57.0 or later, then retry conversion with that newly released version. For a RecordType dependency, declare the RecordType under object settings in a scratch-org definition file and retry with --definition-file <path>. For an org-shape error, run sf org delete shape --target-org <packaging-org-alias>, then sf org create shape --target-org <packaging-org-alias>, and retry once; recurring org-shape errors go to Salesforce Partner Support. For packaged Apex test or code-coverage errors, add required permission sets through apexTestAccess and the package name in sfdx-project.json, then retry. For a StandardValueSet or picklist-value error, retrieve the named StandardValueSet from the packaging org using the official Metadata API workflow, place only StandardValueSet metadata under the seed-metadata directory, and retry with --seed-metadata <directory>. When packaged Apex tests fail because test-only metadata that is not in the package is missing, configure unpackaged metadata as described above and retry. If the CLI reports that the un-packaged metadata directory does not exist, correct unpackagedMetadata.path so it is relative to the DX project root and retry from that root. If the CLI reports that unpackagedMetadata or apexTestAccess can't be resolved because the packageDirectories entry doesn't specify the package parameter, add package to that entry and retry. If it reports that the specified package isn't a valid package ID or package alias, set package to the packageAliases entry that maps to the converted 0Ho ID, or to the 0Ho ID itself, and retry; find the 0Ho ID with sf package list --target-dev-hub <devhub-alias> --json. If unpackaged metadata is configured but tests still fail as though it were missing, update Salesforce CLI, because older versions can ignore an unresolvable setting instead of reporting it. For unsupported metadata, report the metadata types named by the CLI; the customer must remove them from the source package or wait for managed 2GP support. For "namespace is not owned by the Dev Hub," stop and ask the customer to link the package namespace in Dev Hub Setup under Namespace Registries → Link Namespace. Revalidate both aliases in the same CLI environment, then retry conversion once. For authentication, project, or installation-protection errors, return to the matching validation step. Retry conversion at most once after a documented remediation and prerequisite revalidation. For a timeout, poll the existing 08c request instead of converting again. When the CLI returns an internal Salesforce error identifier without a documented customer remediation, tell the customer that conversion failed with that identifier and that the failure could be intermittent. First confirm that no active 08c request exists, revalidate both aliases and the unchanged inputs, then retry the same conversion exactly once. If the retry returns the same identifier or message, stop and recommend a Salesforce Partner Support case. For any repeated or otherwise unclassified error, prepare a sanitized support bundle containing the CLI version, timestamp, exact redacted command, full sanitized output, 033/source-04t/08c identifiers, both org IDs and instance URLs, reproduction steps, relevant project configuration, and business impact. Never include installation keys, access tokens, session IDs, internal systems, or undocumented workarounds.

Verification Checklist

After every write operation, confirm the effect by re-reading state:

• After convert-package: call verify-conversion-request
• After verify-conversion-request: call verify-code-coverage
• After promote-converted-version: call verify-promoted-version

Read Operations reference before executing this workflow. It contains the original operation definitions, dependencies, inputs, and verification instructions.