swift-ai-sdk-upstream

name	swift-ai-sdk-upstream
description	Use for Swift AI SDK upstream parity management: refresh or inspect Vercel AI SDK baselines, scan upstream package coverage, classify drift, plan provider/core/docs audits, land parity fixes with tests, and maintain generated local artifacts under .upstream/ plus durable evidence in upstream/*.

Swift AI SDK Upstream Parity

This skill is the operating protocol for keeping Swift AI SDK aligned with the Vercel AI SDK. It is not only a "refresh upstream" helper; it manages intake, coverage mapping, drift triage, audits, fixes, tests, and evidence.

Authority Model

• Tracked process source: this skill directory.
• Durable parity evidence: upstream/UPSTREAM.md, upstream/PROGRESS.md, and upstream/providers/*.md.
• Generated working artifacts: .upstream/**. These are local scratch artifacts and must stay gitignored.
• Upstream reference checkout: external/vercel-ai-sdk. Treat it as read-only during audits.

Use generated .upstream/** files to decide what to inspect next. Do not cite a generated artifact as final proof unless it is backed by source paths, tests, and durable evidence.

When This Skill Applies

Use this skill when the user asks to:

• update or refresh upstream Vercel AI SDK;
• understand current upstream drift;
• audit provider/core/docs parity;
• add or repair provider behavior;
• update upstream/* evidence;
• generate or read upstream package coverage/status reports.

Required First Steps

1. Read upstream/UPSTREAM.md for the pinned baseline.
2. Run or inspect the local component scan:

   node .agents/skills/swift-ai-sdk-upstream/scripts/scan-upstream.js --out .upstream/current
   

3. Open .upstream/current/component-catalog.md for the current coverage map.
4. Pick exactly one audit scope before editing:
   • core:<package>
   • provider:<package>
   • docs:<section>
   • intake:<baseline>

Scope Rules

• Prefer provider-first vertical slices.
• Touch core only when a provider or public API contract requires it.
• Match observable behavior contracts: request shape, response parsing, streaming order, errors, tools, provider options, usage, defaults, and tests.
• Do not chase line-by-line TypeScript diffs for their own sake.
• Do not use parity/*; this repo tracks parity through upstream/*.
• Do not store generated reports, work queues, or scan snapshots in git.

Refresh Protocol

Only refresh when the user asks for a refresh or the task requires a newer baseline.

Latest main:

rm -rf external/vercel-ai-sdk
git clone --depth 1 https://github.com/vercel/ai external/vercel-ai-sdk
git -C external/vercel-ai-sdk rev-parse HEAD

Pinned tag or branch:

rm -rf external/vercel-ai-sdk
git clone --branch <tag-or-branch> --depth 1 https://github.com/vercel/ai external/vercel-ai-sdk
git -C external/vercel-ai-sdk rev-parse HEAD

Specific commit:

rm -rf external/vercel-ai-sdk
git clone --depth 1 https://github.com/vercel/ai external/vercel-ai-sdk
git -C external/vercel-ai-sdk fetch --depth 1 origin <sha>
git -C external/vercel-ai-sdk checkout <sha>
git -C external/vercel-ai-sdk rev-parse HEAD

After a refresh, update upstream/UPSTREAM.md, regenerate .upstream/current, and add a short upstream/PROGRESS.md note only when the baseline or shipped parity state meaningfully changed.

Audit Workflows

Provider Audit

1. Read the upstream provider implementation, tests, and fixtures under external/vercel-ai-sdk/packages/<provider>/.
2. Read the matching Swift implementation and tests.
3. Use references/audit-slices.md as the checklist.
4. Add or tighten Swift regressions near the changed boundary.
5. Fix the minimal owner-level Swift code required for parity.
6. Run targeted tests, then AGENT=1 swift test unless the user explicitly narrows verification.
7. Update upstream/providers/<provider>.md with:
   • audited commit;
   • verified contracts;
   • Swift and upstream evidence paths;
   • gaps or intentional deviations.

Core Audit

Use only for packages/ai, packages/provider, packages/provider-utils, or core contracts required by a provider.

1. Define the exact upstream contract.
2. Read upstream implementation and nearest tests.
3. Read Swift owner code and tests.
4. Add or tighten tests under the matching Swift test target.
5. Fix the owner-level contract.
6. Record evidence in upstream/PROGRESS.md; if provider-driven, also update the relevant provider page.

Docs Audit

Use only when the task is docs work or a behavior change needs docs.

1. Copy from external/vercel-ai-sdk/content/**.
2. Adapt for Swift and Starlight in apps/docs/src/content/docs/**.
3. Update navigation in apps/docs/astro.config.mjs when needed.
4. Run pnpm run docs:check and pnpm run docs:build.

Status Vocabulary

Use the statuses from references/component-taxonomy.md:

• unknown
• mapped
• partial
• verified
• stale
• drift
• n/a

Do not mark a component verified without an audited commit and concrete Swift test/source evidence.

Bundled References

• references/component-taxonomy.md: areas, priorities, status meanings, and package classification.
• references/audit-slices.md: provider/core/docs audit checklist.
• references/artifacts.md: generated artifact contract for .upstream/**.
• templates/component-status.md: durable component/provider status template.
• templates/work-item.md: generated work queue item template.

Fast Commands

node .agents/skills/swift-ai-sdk-upstream/scripts/scan-upstream.js --out .upstream/current
rg -n "<symbol>" external/vercel-ai-sdk/packages -S
rg -n "<symbol>" Sources Tests -S
AGENT=1 swift test
node tools/test-runner.js --config tools/test-runner.default.config.json

Done Criteria

• The selected scope has a named owner.
• The audited upstream commit is explicit.
• Swift behavior matches the intended upstream contract or a deviation is documented.
• Tests cover the contract.
• Generated .upstream/** artifacts were used only as local working state.
• Durable evidence in upstream/* was updated when parity state changed.