Migrate Internal Package into Ghost

Migrate an internal package into Ghost

Move a package from another TryGhost repository into Ghost without losing its history or creating a period where neither repository owns it. Keep migration mechanics separate from Ghost's lifetime package standards.

Any contributor can run this skill. Do not require repository administration permission for the audit, import, PR preparation, CI, read-only preflight, post-merge verification or follow-up work. Administration is required only at the exceptional merge checkpoint, which is handed to one of the small set of Ghost repository administrators.

The contributor workflow is documented in docs/contributing/internal-package-migrations.md. Keep that guide aligned when this skill changes its outputs or human checkpoints.

Authority boundaries

Explain every cross-repository or administrative action before it happens.

• A request for instructions is not permission to perform the action.
• If the user says "tell me how, I do it", provide the command and wait.
• Require explicit authorization before changing repository settings, merging a PR, deprecating npm versions, or force-pushing.
• Never run the history import's --confirm operation. That command is the deliberate human administrator checkpoint because it temporarily changes a Ghost repository setting and merges the exceptional PR.
• Never ask for, display, or store credentials or OTPs.

Work in isolated checkouts

Never manipulate history in a checkout containing unrelated work. Fetch both repositories, confirm the source checkout is clean, and create a dedicated Ghost worktree from the freshly fetched origin/main.

Run history-changing commands individually or in a fail-fast shell. A failed git worktree add must not be followed by git subtree add in whichever checkout happens to be current. Before choosing a branch or path, list existing worktrees and matching local and remote branches. Use a migration-specific slug, for example codex/import-<package>-from-<source>, rather than a generic name.

If the destination branch or path already exists, stop and inspect its cleanliness, base, divergence, source split and attached worktree. Do not mutate, delete or silently reuse it. Present the evidence and ask the user whether to resume, preserve and supersede, or remove it when more than one choice is reasonable. A previous attempt can contain valid unmerged history even when its remote branch is gone.

Before importing, record and compare the destination HEAD and origin/main; they must match. Recheck the first parent immediately after the subtree commit.

Initialize a fresh Ghost worktree with pnpm bootstrap, not pnpm setup. pnpm setup is a pnpm CLI command that configures pnpm's global home and may edit shell startup files; it does not invoke Ghost's repository bootstrap. Before continuing, confirm the command installed the workspace, initialized the submodules and configured the repository-local blame ignore file as described by Ghost's root bootstrap script.

Confirm this workflow applies

Before changing either repository, record the source repository, its default branch, the package path within it, the destination path in Ghost, and whether the package has been published to npm. Then:

All packages moved by this workflow belong in Ghost's root packages/ workspace. Derive the destination as packages/<package-directory> from the source package directory and report that exact path to the user before creating the subtree. Never place an imported package under ghost/, even when Ghost Core is its only consumer. If the derived path conflicts with an existing path or the request appears to require another workspace, stop and resolve the destination explicitly before manipulating history.

1. Find every Ghost and source-repository reference to the package name and directory.
2. Inspect its npm metadata, README, documentation, release configuration and known public consumers.
3. Confirm Ghost is the real owner and can consume it via workspace:*.
4. Identify any need for independent releases or supported external use.

Publication or download counts alone do not prove that a package must remain a supported public API. If supported external consumers still need new releases, stop: this internal-only workflow is the wrong publishing model.

For the public-consumer audit, check npm metadata, first-party repositories and documentation, plus GitHub code search for package dependencies and runtime imports. Classify results as first-party consumers, independent integrations, Ghost forks, or deployed Ghost installation snapshots. Forks and installation snapshots show historical presence only. Require a recent update, current deployment, active dependency or another freshness signal before treating them as evidence of continued installation needs; even then, they do not establish an independently supported API. Record the evidence and confidence behind the ownership decision; stop and ask if current support expectations remain unclear.

Run registry-only npm view commands from a neutral temporary directory. A repository's devEngines policy can reject the host Node version before npm contacts the registry, which is unrelated to the package metadata audit. Record that failure separately if using a neutral directory does not resolve it.

Produce these work products in order

1. A green Ghost import PR with reachable source history.
2. After it merges, a green source-repository removal PR.
3. npm deprecation if the package was published and new direct use is unsupported.
4. A focused Ghost cleanup PR for stale migration-specific automation.
5. A Ghost modernization PR assessed against the current package template and comparable internal packages.

Keep the history import and modernization separate. The import establishes ownership and provenance; later commits can modernize code without obscuring the move.

1. Import the history into Ghost

Read references/history-and-merge.md completely before manipulating history.

Use an unsquashed git subtree import from the recorded source repository and package path. Do not copy the current files, pass --squash, or recreate old commits manually.

After the subtree commit, add focused integration commits that:

• make the package private with an internal placeholder version;
• set ghostPackage.goldenPath to migration and ghostPackage.reason to a concise explanation of the remaining modernization work;
• switch Ghost consumers to workspace:*;
• update the lockfile with pnpm;
• minimally adapt configuration and tests to work in Ghost;
• retain runtime behavior for the later modernization PR.

Before editing package metadata, map each source workspace:* dependency to its destination state:

• use workspace:* when the dependency already exists in Ghost;
• use catalog: when Ghost's catalog version satisfies the imported package;
• add a named migration catalog with the exact published version when changing the shared catalog would broaden the migration or alter runtime behavior;
• stop if a required dependency is unpublished or exists only in the source workspace.

Document temporary named-catalog entries for the modernization follow-up. Never inline dependency versions; Ghost's strict catalog policy still applies. Do not import additional packages implicitly. After pnpm install, inspect the lockfile's resolved override and package snapshot entries for every translated dependency. Repository-wide pnpm overrides take precedence over catalog references without changing the dependency declaration in package.json; if a global override changes an imported package's required version, add the narrowest package-scoped override that preserves the source release and record why it is needed.

If the package is legacy JavaScript or CommonJS, read references/legacy-integration.md completely before creating integration commits.

Verify that the subtree commit has two parents and that representative file history crosses into the source repository before opening the PR.

Before opening the PR, also verify the source split is reachable from the branch tip, the consumer resolves the workspace package through its production import path, package lint and tests pass through Nx, relevant consumer tests pass, the repository formatting check passes, the full build passes, and the Ghost archive contains the internal package. Record the exact commit IDs and commands in the handoff. Keep mechanical formatting in a focused integration commit so the subtree commit remains an exact history import and reviewers can distinguish format-only changes from behavioral adaptation.

Open the history-import PR with a title beginning [Don't merge]. Put a prominent warning at the top of its body that squash and rebase merges destroy the imported ancestry and that the PR must only be merged with the guarded history script below. Do not remove the prefix or warning merely because CI is green: they remain until the authorized user performs the exceptional merge.

For a pilot or first use, include a structured gap report in the handoff:

• Observed: the exact failure or ambiguity and the command/state that exposed it;
• Worked around: the safe action taken, without hiding the original gap;
• Skill change: the concrete instruction, preflight or script improvement;
• Tooling change: anything that cannot be solved within this repository;
• Confidence: high, medium or low, with unresolved evidence called out.