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 AGENT_BROWSER_LOCAL 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
2. •

   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
   

2. •

   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
3. •

   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
2. •

   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
   

2. •

   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"
   

3. •

   Flag breaking changes

   Create a list:

   • • Change X affects packages/server/src/browser.ts:42
   • • Change Y affects packages/core/src/types.ts:18
4. •

   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)")
   

2. •

   Create version directory

   bash

   mkdir -p docs/_upstream/$VERSION
   

3. •

   Generate changes.md Raw changelog with all commits and diffs.

4. •

   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
5. •

   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
   

6. •

   Update index Add entry to docs/_upstream/README.md

7. •

   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
   

2. •

   Resolve conflicts if any

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

   Push to fork

   bash

   git push origin main
   

4. •

   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"
   

5. •

   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"
   

6. •

   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.

7. •

   Verify lockfile updated

   bash

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

8. •

   Run navigator tests

   bash

   bun run typecheck
   bun test
   

9. •

   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