Agent-Browser Upstream Sync Skill

Manages the process of keeping navigator's agent-browser fork in sync with the upstream vercel-labs/agent-browser repository.

Related Skills

Workflow: Use upstream-evaluation skill for the "what and why" decisions, then return here for the "how" execution.

Prerequisites

None required - the skill auto-manages everything:

1. Auto-clone: If .agent-browser/repo/ doesn't exist, the script clones the fork automatically
2. Auto-configure: Upstream remote is added if missing
3. Override: Set AGENTBROWSERLOCAL env var to use an existing local clone instead

The .agent-browser/ directory is gitignored and contains:

• repo/ — Git clone of the fork
• analysis/<sha>/ — Generated artifacts (jq-able JSON, diffs)

Workflow Overview

Phase 1: Check Status (fetch, compare)
    ↓
Phase 2: Analyze Changes (categorize commits)
    ↓
Phase 3: Evaluate Changes ← uses upstream-evaluation skill
    ↓
Phase 4: Write Integration Docs + Create Issue
    ↓
Phase 5: User Review & Confirmation
    ↓
Phase 6: Execute Merge (ONLY after user confirms)

CRITICAL: Never merge without completing phases 3-5 first.
Phase 3 MUST use the upstream-evaluation skill to apply Navigator's design frameworks.

Phase 1: Sync Fork

Steps

1. Run the analysis script (handles everything automatically)

``bash bun run .claude/skills/agent-browser-upstream/scripts/analyze-upstream.ts --format summary ``

The script will: - Clone .agent-browser/ if missing - Add upstream remote if needed - Fetch latest from both remotes - Show divergence summary

1. Or check manually

```bash cd .agent-browser/repo

# Current fork version git describe --tags origin/main 2>/dev/null || git rev-parse --short origin/main

# Latest upstream version git describe --tags upstream/main 2>/dev/null || git rev-parse --short upstream/main

# Divergence git log --oneline origin/main..upstream/main ```

Decision Point

If no commits in divergence → STOP with "Fork is up to date with upstream"

If commits exist → CONTINUE to Phase 2 (never skip to merge)

Phase 2: Analyze Changes

Steps

1. Run analysis script

``bash bun run .claude/skills/agent-browser-upstream/scripts/analyze-upstream.ts \ --repo "$REPO_PATH" \ --base origin/main \ --target upstream/main ``

1. Review commit categories

The script outputs JSON with commits categorized as: - breaking - API changes, removed exports - additive - New features, new exports - fix - Bug fixes - docs - Documentation only - chore - Build, deps, tooling

1. Identify key files changed

Focus on these files for navigator impact: - src/protocol.ts - MCP protocol definitions - src/browser.ts - Browser control API - src/index.ts - Public exports - src/cli/ - CLI commands (may inform navigator CLI)

Output

Present a summary table:

Phase 3: Evaluate Changes

REQUIRED — Even for "clean" updates with 0 breaking changes.

Run the Evaluation Command

Use /agent-browser:integrate-changes, which:

• Loads the upstream-evaluation skill
• Provides decision frameworks from DESIGN.md
• Guides through structured evaluation process
• Outputs adopt/skip/defer tables for integration docs

Why This Phase Exists

The 2025-01-20 v0.6.0 sync skipped evaluation because "0 breaking changes" was treated as a green light. This caused:

• Marketplace plugin merged without review (Vercel-branded, not navigator-appropriate)
• 8 new features not assessed for navigator integration
• No documentation created before merge

Evaluation Output

The upstream-evaluation skill produces:

• Adopt table: Features to add with Navigator naming and schema changes
• Skip table: Features to exclude with rationale
• Defer table: Features to revisit later
• Extend existing table: Changes to existing actions

1. Review evaluation output

- Ensure all new commands identified - Ensure plugins flagged - Ensure schema changes documented

1. Do NOT proceed to merge until analyst complete

Phase 4: Impact Assessment (Navigator-Specific)

Steps

1. Map upstream changes to navigator usage

Check which navigator files import from agent-browser: ``bash grep -r "@outfitter/agent-browser" packages//src --include=".ts" -l ``

1. Cross-reference with changed APIs

For each breaking change, check if navigator uses it: ``bash # Example: if upstream changed BrowserOptions grep -r "BrowserOptions" packages//src --include=".ts" ``

1. Flag breaking changes

Create a list: - [ ] Change X affects packages/server/src/browser.ts:42 - [ ] Change Y affects packages/core/src/types.ts:18

1. Identify required navigator changes

For each breaking change, document: - What changed upstream - How navigator currently uses it - What navigator code needs to change

Decision Point

If breaking changes exist → STOP and confirm with user before proceeding

Phase 5: Write Integration Docs

Steps

1. Determine version

``bash VERSION=$(git describe --tags upstream/main 2>/dev/null || echo "v$(date +%Y.%m.%d)") ``

1. Create version directory

``bash mkdir -p docs/_upstream/$VERSION ``

1. Generate changes.md

Raw changelog with all commits and diffs.

1. Generate integration.md

Use template from references/integration-template.md: - Version metadata - Breaking changes with navigator impact - Additive features with adoption plan - Required code changes - Test plan

1. Generate status.md

Tracking checklist: ```markdown ## Implementation Status

- [ ] Merge upstream into fork - [ ] Update navigator bun.lock - [ ] Apply breaking change fixes - [ ] Run navigator tests - [ ] Update navigator CHANGELOG ```

1. Update index

Add entry to docs/_upstream/README.md

1. Create GitHub issue (optional, recommended for breaking changes)

The integration doc is the issue — its frontmatter has title/labels: ``bash bun run .claude/skills/agent-browser-upstream/scripts/create-issue.ts \ docs/upstream/$VERSION/integration.md ` Or use the command: /agent-browser:issue docs/upstream/$VERSION/integration.md`

Phase 6: Execute Merge

REQUIRES USER CONFIRMATION - Do not proceed without explicit approval from Phase 5 docs review

Steps

1. Merge upstream into fork

``bash cd /path/to/navigator/.agent-browser/repo # Always use absolute path git checkout main git merge upstream/main --no-edit ``

1. Resolve conflicts if any

- Prefer upstream changes unless navigator-specific customization - Document any conflict resolutions in integration.md

1. Push to fork

``bash git push origin main ``

1. Create fork release tag

```bash # Determine tag version: <upstream-version>-nav.<patch> # e.g., v0.6.0-nav.1, v0.6.0-nav.2 VERSION="v0.6.0-nav.1" # Adjust based on upstream version

git tag -a "$VERSION" -m "Navigator fork release: synced with upstream

Upstream: vercel-labs/agent-browser <upstream-tag> Navigator tracking: <issue-url>"

git push origin "$VERSION" ```

1. Update navigator's package.json

```bash cd /path/to/navigator # Back to navigator root

# Update packages/server/package.json to reference the tag: # "@outfitter/agent-browser": "github:outfitter-dev/agent-browser#v0.6.0-nav.1" ```

1. Force refresh bun lockfile (required for GitHub deps)

``bash cd /path/to/navigator rm bun.lock bun install ``

> Why? Bun caches GitHub commit SHAs. Without removing the lockfile, > bun install may not fetch the new tag even after pushing.

1. Verify lockfile updated

``bash grep "agent-browser" bun.lock # Should show the new tag: #v0.6.0-nav.1 ``

1. Run navigator tests

``bash bun run typecheck bun test ``

1. Update integration docs

- Mark fork synced in docs/_upstream/<version>/integration.md - Add tag version to the doc

Decision Point

If tests fail → STOP and document failures, do not commit

Fork Tagging Convention

The fork uses <upstream-version>-nav.<patch> tags:

Benefits:

• Clear upstream version lineage
• Navigator can branch and test new versions before merging to main
• Pinnable in package.json: github:outfitter-dev/agent-browser#v0.6.0-nav.1

Integration Patterns

Pattern: API Signature Change

When upstream changes a function signature:

1. Find all navigator usages
2. Update to new signature
3. Add backward-compat wrapper if needed (temporary)
4. Document in integration.md

Pattern: New Feature Adoption

When upstream adds a useful feature:

1. Evaluate if navigator should expose it
2. Add to navigator's schema if needed
3. Wire through action-executor
4. Add tests
5. Document in navigator CHANGELOG

Pattern: Breaking Type Change

When upstream changes a type definition:

1. Update navigator's re-exports
2. Check all type usages compile
3. Update any Zod schemas that reference it

Quick Reference

Commands

# Run analysis (auto-clones if needed)
bun run .claude/skills/agent-browser-upstream/scripts/analyze-upstream.ts --format summary

# Generate diff artifacts (for incremental context loading)
bun run .claude/skills/agent-browser-upstream/scripts/generate-diff.ts

# Check current versions
cd .agent-browser/repo && git describe --tags origin/main upstream/main

# View pending changes
cd .agent-browser/repo && git log --oneline origin/main..upstream/main

# Diff specific file
cd .agent-browser/repo && git diff origin/main..upstream/main -- src/protocol.ts

# Read analysis artifacts incrementally
cat .agent-browser/analysis/<sha>/summary.json        # Start here
jq '.counts' .agent-browser/analysis/<sha>/summary.json
cat .agent-browser/analysis/<sha>/by-category/breaking.json

Key Files

Environment Variables

Troubleshooting

Bun Lockfile Not Updating

Symptom: After pushing new tag to fork, bun install still shows old commit SHA.

Cause: Bun caches GitHub dependencies by commit SHA. Even with a new tag, it may reuse the cached resolution.

Fix:

cd /path/to/navigator
rm bun.lock
bun install
grep "agent-browser" bun.lock  # Verify new tag/commit

Git Context Issues

Symptom: gh commands target wrong repo (e.g., upstream instead of navigator).

Cause: Working directory is .agent-browser/repo/ (the fork clone) instead of navigator root.

Fix: Always use absolute paths:

# WRONG - relative path, may be in wrong directory
cd .agent-browser/repo && git push

# RIGHT - absolute path
cd /Users/you/project/navigator/.agent-browser/repo && git push

# For navigator commands, go back to root
cd /Users/you/project/navigator && gh issue create

Tag Already Exists

Symptom: git tag fails with "tag already exists".

Fix: Increment the patch number:

# If v0.6.0-nav.1 exists, use v0.6.0-nav.2
git tag -a "v0.6.0-nav.2" -m "..."

Fork Behind After Merge

Symptom: git log origin/main..upstream/main still shows commits after merge.

Cause: Origin wasn't pushed.

Fix:

cd .agent-browser/repo
git push origin main
git log --oneline origin/main..upstream/main  # Should be empty