package-release-audit

# Package Release Audit Handle $ARGUMENTS. Goal: find newer releases for a named package, extract work kitcn can actually use, then delegate one concrete implementation slice to [$task](/Users/zbeyens/git/better-convex/.agents/skills/task/SKILL.md) so it opens the PR. ## Rules - Use evidence, not vibes. Read changelog/release sources and a diff. - Prefer deleting kitcn glue over adding more glue when upstream fixed the real problem. - Do not upgrade a package just because a newer version exists. Ship only a leverageable improvement. - Keep the PR slice coherent. One release opportunity per PR unless multiple fixes share the same seam. - If no actionable opportunity exists, stop with the evidence. Do not open a vanity PR. ## 1. Establish Package, Current, And Target Versions Extract the package name from $ARGUMENTS. If the package name is ambiguous, stop and ask for the exact npm package name. Find the currently pinned package version: ```bash rg -n '"<package-name>":' package.json packages/**/package.json example/package.json ``` Find the latest published version and package metadata: ```bash npm view <package-name> version repository homepage dist-tags --json ``` If $ARGUMENTS names a target version, use it as the upper bound. Otherwise use the latest npm version. Record: - package name - current pinned version or range - target version - every version in the current-exclusive, target-inclusive range when discoverable - exact package files that pin or constrain the package - repository owner/name inferred from npm metadata ## 2. Read Changelogs And Release Notes Prefer official sources in this order: 1. package repository changelog files 2. GitHub releases 3. package docs/blog release pages from npm metadata 4. npm package metadata only when no richer source exists Read the repository changelog through `gh`, not browser scraping, when a GitHub repo is available: ```bash gh api \ -H "Accept: application/vnd.github.raw" \ repos/<owner>/<repo>/contents/CHANGELOG.md ``` If that path is missing, discover likely changelog paths: ```bash gh api repos/<owner>/<repo>/git/trees/HEAD?recursive=1 \ --jq '.tree[].path | select(test("(^|/)(CHANGELOG|RELEASES|HISTORY|UPGRADING|MIGRATION|MIGRATIONS)\\\\.(md|mdx|txt)$"; "i"))' ``` Read GitHub releases: ```bash gh release list --repo <owner>/<repo> --limit 20 gh release view <tag-or-version> --repo <owner>/<repo> ``` Extract only the sections in range. Reconcile disagreements: - Changelog files are package-facing signal. - GitHub releases are release-manager signal. - Docs/blog pages are product-facing signal. - If they disagree, keep both facts and investigate in the diff. ## 3. Read The Upstream Diff With `gh` Use a local upstream clone for navigation, creating it only if missing: ```bash test -d ../<repo-name>/.git || gh repo clone <owner>/<repo> ../<repo-name> git -C ../<repo-name> fetch origin main --tags ``` Find refs for the current and target versions. Prefer tags if they exist: ```bash git -C ../<repo-name> tag -l "*<version>*" | sort git -C ../<repo-name> log --all --oneline -- '*package.json' '*CHANGELOG*' ``` If tags are unclear, inspect version-bump commits in the package's `package.json` or changelog and use the commit before/after each version bump. Read the compare through `gh`: ```bash gh api \ repos/<owner>/<repo>/compare/<base-ref>...<target-ref> \ --jq '.files[] | select(.filename | test("package|src|cli|server|client|auth|plugin|adapter|schema|migration|agent|mcp|codegen|docs|CHANGELOG"; "i")) | {filename,status,patch}' ``` If the compare is too large, narrow locally after proving the refs: ```bash git -C ../<repo-name> diff <base-ref>..<target-ref> -- \ . ':!**/node_modules/**' ':!**/dist/**' ':!**/build/**' ``` ## 4. Search Kitcn For Leverage Search for local package integration points and hacks: ```bash rg -n "<package-name>|<package-import>|<package-domain-term>|TODO|workaround|hack|temporary|shim|compat|adapter|plugin|peer|version" \ packages www .agents docs test tooling ``` Also search institutional notes before proposing work: ```bash rg -i --files-with-matches "<package-name>|<package-domain-term>|upgrade|compat|agent|cli|bootstrap|adapter|plugin|peer|version" docs/solutions ``` Read relevant hits, especially notes about: - package-specific wrappers, adapters, plugins, or generated code - peer dependency ranges and scaffold pins - CLI or agent workflow workarounds - non-interactive, deterministic, or machine-readable behavior - docs/skill sync for package guidance - dirty hacks that might be obsolete after the upstream release ## 5. Classify Opportunities For each release item, classify it: - `feature`: new package API, CLI command, runtime behavior, integration, or platform feature kitcn can expose. - `compatibility`: required work to keep kitcn working with the new version. - `agentic`: upstream change that improves non-interactive, deterministic, machine-readable, MCP, CLI, or automation flows. - `cleanup`: upstream change that lets kitcn delete a workaround, shim, fallback, prompt handling, wrapper, patch, or doc warning. - `docs`: upstream change that only affects user-facing docs, setup guidance, or skills. - `no-op`: interesting upstream change with no kitcn action. For every non-`no-op`, include: - changelog or release evidence - diff evidence - kitcn file(s) affected - expected implementation seam - verification command(s) - confidence Bias toward `agentic` and `cleanup`; kitcn exists to make dependencies sharper for humans and agents, not to mirror every upstream bullet. ## 6. Choose One PR Slice Pick the highest-leverage slice using this order: 1. compatibility breakage 2. delete dirty hack made obsolete upstream 3. agentic CLI/tooling unlock 4. product feature kitcn can expose cleanly 5. docs or skill-only update If the winning slice touches published package code, the delegated task must update the active changeset and run `bun --cwd packages/kitcn build`. If it touches scaffold templates, the delegated task must run `bun run fixtures:sync` and `bun run fixtures:check`. ## 7. Delegate Through `task` Load [$task](/Users/zbeyens/git/better-convex/.agents/skills/task/SKILL.md) with a prompt in this exact shape: ```md Implement this package release opportunity. Package: <package-name> Current version/range: <version> Target version: <version> Opportunity: <one-sentence selected slice> Class: <feature | compatibility | agentic | cleanup | docs> Evidence: - Changelog/release notes: <short citation or summary> - Upstream diff: <refs and files> - Kitcn evidence: <local files and docs/solutions notes> Implementation: - <specific files or seams to inspect first> - <expected code/doc/test shape> Acceptance: - <tests/checks> - <package build if packages/kitcn changes> - <fixtures commands if scaffold output changes> - open the PR after verification Do not preserve obsolete package workarounds if the upstream release removes the need for them. Hard cut the hack. ``` Then follow `task` until the PR exists or a real blocker is proven. ## Output Before delegation, keep the audit terse: ```md Package: <package-name> Current: <version> Target: <version> | Class | Opportunity | Evidence | Decision | | --- | --- | --- | --- | | cleanup | ... | ... | selected | Delegating to task: <selected slice> ``` After `task` finishes, use its final handoff format.