Upgrade Pack Generator

Generate upgrade-pack folders for dependency families in two stages:

1. Author or refine a reusable family override.
2. Instantiate a repo-specific pack from that family plus live repo context.

The generator is monorepo-aware. During enrichment it must lock an explicit owner surface for the family:

• repo root
• one owning workspace
• repo root plus related workspaces

The generated pack is docs/research only. Do not implement package changes while generating the pack.

Core Workflow

1. Read references/workflow.md.
2. Decide the mode:

• family authoring
• repo instantiation

1. Detect repo context first:

   python3 scripts/detect_repo_context.py --repo-root /path/to/repo --json

1. Bootstrap a manifest from the anchor package:

   python3 scripts/bootstrap_manifest.py \
     --repo-root /path/to/repo \
     --anchor-package lucide-react \
     --out /tmp/upgrade-pack.yaml

1. Enrich the manifest with live repo probes and official upstream guidance:

   python3 scripts/enrich_manifest.py --manifest /tmp/upgrade-pack.yaml

1. Refine the enriched manifest further with live research when needed:

• $repo-modernizer
• $opensrc
• $technical-writing
• $hard-cut

1. Validate the manifest:

   python3 scripts/validate_upgrade_pack.py /tmp/upgrade-pack.yaml

1. Run read-only research:

   python3 scripts/research_upgrade_pack.py --manifest /tmp/upgrade-pack.yaml

1. Run the mandatory web.run confirmation pass for required official docs and

API-reference pages from research-bundle.json and record the results in web-research-findings.json.

1. Re-run read-only research so the snapshot reflects the confirmed official

pages:

    python3 scripts/research_upgrade_pack.py --manifest /tmp/upgrade-pack.yaml

1. Run read-only qualification:

    python3 scripts/qualify_upgrade_pack.py --manifest /tmp/upgrade-pack.yaml

1. Render the pack:

    python3 scripts/render_upgrade_pack.py \
      --manifest /tmp/upgrade-pack.yaml \
      --output-dir /path/to/repo/.agents/plans/upgrade/<topic>

Output Contract

Every generated repo-local pack must contain exactly:

• upgrade-pack.yaml
• research-snapshot.json
• research-bundle.json
• web-research-findings.json
• qualification-snapshot.json
• <basename>-playbook.md
• <basename>-trigger-prompt.md
• <basename>-operator-mode.md

The manifest is the canonical source. The markdown files are rendered outputs. research-snapshot.json and qualification-snapshot.json are the canonical machine-readable evidence files for the separate research and qualify stages. research-bundle.json is the raw evidence ledger that backs the research snapshot. web-research-findings.json is the machine-readable record of web.run confirmation for the required official pages.

Rendered file roles:

• <basename>-playbook.md
• authoritative human handoff doc and the only writable pack file during an

implementation run

• <basename>-operator-mode.md
• execution delta card that points back to the playbook
• <basename>-trigger-prompt.md
• thin launcher for a fresh Codex session with a compact repo summary

Do not hand-maintain operator-mode.md or trigger-prompt.md; regenerate them from the manifest.

Family Overrides

Read references/manifest-schema.md before editing any override.

Family overrides live in references/family-overrides/. Use them when a dependency family recurs across repos and benefits from package-specific:

• end-state decisions
• research lanes
• migration questions
• verification proofs
• file naming and slug conventions

Current built-in family lanes:

• lucide-react
• nextjs
• expo-eas
• convex
• turborepo
• shadcn-radix-ui

Keep overrides narrow. Put only family-specific information there. Let the base generator provide the common structure.

Package Manager And Framework Detection

Detect the target repo command family in this order:

1. package.json#packageManager
2. root lockfiles
3. repo docs and CI hints

The generator should write that decision into upgrade-pack.yaml and render package-manager-aware command variables into the pack. Do not force Bun into a pnpm/npm/Yarn repo.

Research Routing

Use the default research lanes in references/research-lanes.md.

Conditional routing:

• use $bun-dev only when Bun posture is actually relevant
• use framework/plugin lanes only when the target repo detects them
• use browser lanes only when the package family affects visible UI
• do not route through $imagegen unless raster asset generation is truly part

of the package-family surface

Scripts

• scripts/detect_repo_context.py
• inspects package manager, lockfiles, docs/CI hints, frameworks, and package

manifests

• scripts/bootstrap_manifest.py
• creates a starter upgrade-pack.yaml from generic defaults plus an optional

family override

• scripts/enrich_manifest.py
• enriches upgrade-pack.yaml with family-specific repo probes, current

package versions, and live official-doc snapshots

• scripts/validate_upgrade_pack.py
• validates the manifest contract before rendering
• scripts/research_upgrade_pack.py
• gathers upstream docs, API refs, release notes, examples, source evidence,

repo-usage mapping, package identity, target-version reasoning, source-map drift checks, provenance scores, and the web.run queue into research-snapshot.json plus research-bundle.json

• scripts/sync_source_map.py
• validates or refreshes the bundled package source-map under

references/source-maps/

• scripts/qualify_upgrade_pack.py
• runs family-native read-only qualification and writes

qualification-snapshot.json

• scripts/render_upgrade_pack.py
• renders the repo-local pack from the canonical manifest and qualification

snapshot

Examples

Bootstrap a known family override:

python3 scripts/bootstrap_manifest.py \
  --repo-root /path/to/repo \
  --anchor-package lucide-react \
  --out /tmp/lucide-upgrade-pack.yaml

Render a generic pack for a package without an override:

python3 scripts/bootstrap_manifest.py \
  --repo-root /path/to/repo \
  --anchor-package commander \
  --out /tmp/commander-upgrade-pack.yaml
python3 scripts/enrich_manifest.py \
  --manifest /tmp/commander-upgrade-pack.yaml
python3 scripts/research_upgrade_pack.py \
  --manifest /tmp/commander-upgrade-pack.yaml
python3 scripts/qualify_upgrade_pack.py \
  --manifest /tmp/commander-upgrade-pack.yaml
python3 scripts/render_upgrade_pack.py \
  --manifest /tmp/commander-upgrade-pack.yaml \
  --output-dir /path/to/repo/.agents/plans/upgrade/commander

Refresh an existing repo-local pack after refining the manifest:

python3 scripts/enrich_manifest.py \
  --manifest /path/to/repo/.agents/plans/upgrade/lucide-react/upgrade-pack.yaml
python3 scripts/validate_upgrade_pack.py \
  /path/to/repo/.agents/plans/upgrade/lucide-react/upgrade-pack.yaml
python3 scripts/research_upgrade_pack.py \
  --manifest /path/to/repo/.agents/plans/upgrade/lucide-react/upgrade-pack.yaml
python3 scripts/qualify_upgrade_pack.py \
  --manifest /path/to/repo/.agents/plans/upgrade/lucide-react/upgrade-pack.yaml
python3 scripts/render_upgrade_pack.py \
  --manifest /path/to/repo/.agents/plans/upgrade/lucide-react/upgrade-pack.yaml \
  --output-dir /path/to/repo/.agents/plans/upgrade/lucide-react