feat: add Stagehand code-mode guidance

[shrey150]

Why

This third stack layer distributes the canonical instructions an agent needs to use code_execute well. It stays separate from the execution engine so reviewers can evaluate prompt content, generated-code integrity, package loading, and distribution without re-reviewing browser lifecycle code.

Stack

1. feat: scaffold Stagehand code-mode MCP host #2597 — private package, MCP stdio host, lifecycle, repository build/test wiring
2. feat: add Stagehand code execution tool #2619 — code_execute, Stagehand executor, local/Browserbase configuration, schemas, and runtime tests
3. This PR — SKILL.md, REFERENCE.md, generated exports, package assets, and guidance loading checks
4. #2626 — Vercel AI SDK MCP example and smoke flows
5. #2627 — Mastra MCP example and smoke flows
6. #2628 — CrewAI MCP example and smoke flows
7. #2629 — LangChain Deep Agents MCP example and smoke flows

What changed

• adds the concise code-mode SKILL.md used as the tool-facing agent guide
• adds the longer REFERENCE.md for Stagehand, page, context, event, and schema lookup
• generates bundle-safe JavaScript constants from both Markdown assets
• exports the raw Markdown files and generated constants from the private package
• appends the exact generated skill to the code_execute MCP description
• fails build and typecheck when committed generated content is stale
• tests generated TypeScript parsing and round-trip fidelity for backslashes, quotes, carriage returns, tabs, and Unicode separators
• tests package-export resolution for both raw Markdown assets

Loading paths

Consumers can use either representation without reading repository source files:

Consumer need	Package surface
Install a skill file into an agent project	@browserbasehq/stagehand-integrations/codemode/SKILL.md
Install the long-form lookup reference	@browserbasehq/stagehand-integrations/codemode/REFERENCE.md
Embed guidance in a JavaScript bundle	STAGEHAND_CODEMODE_SKILL and STAGEHAND_CODEMODE_REFERENCE
Discover guidance through MCP	code_execute tool description

Intentionally not included

• no consumer-specific project-directory or framework adapter; that stays in feat(evals): run v4_code through shared MCP #2614
• no executor or transport behavior changes beyond adding guidance to the tool description
• no published package surface; the package remains private while names are validated

E2E Test Matrix

Command / flow	Observed output	Confidence / sufficiency
pnpm --filter @browserbasehq/stagehand-integrations typecheck && pnpm --filter @browserbasehq/stagehand-integrations test	Generated-content check, typecheck, and build passed; 9 test files and 68 tests passed.	Covers byte parity, stale output, special-character parse/round-trip, package-export resolution, tool-description wiring, and all lower-layer regressions.
Pack private package and inspect extracted artifact	{"status":"PASS","rawSkill":true,"rawReference":true,"bundledGuidance":true,"runtimeFilesystemDependency":false}	Proves both Markdown assets and bundled guidance ship in the package without runtime file reads.
Compiled stdio MCP guidance plus local-browser call	Exactly code_execute was discovered, its description ended with the generated skill, and a real navigation returned the expected title and URL.	Proves the built child exposes the canonical guidance and still executes against a real local browser.
pnpm exec turbo run fmt:check lint typecheck --concurrency=1	9/9 repository tasks passed.	Supports repository-wide formatting, lint, and type compatibility while avoiding an unrelated generated-protocol formatting race in the parallel local command.

Changeset

None. This changes a private workspace package and does not publish a release.

[changeset-bot]

⚠️ No Changeset found

Latest commit: d5b288a

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[cubic-dev-ai]

All reported issues were addressed across 9 files

Architecture diagram

sequenceDiagram
    participant Agent as AI Agent
    participant MCP as MCP Server
    participant Executor as Code Executor
    participant GenScript as generate-codemode-content.mjs
    participant Markdown as codemode/*.md
    participant Bundle as generated-content.ts
    participant Package as @browserbasehq/stagehand-integrations
    participant Consumer as Downstream Package
    participant Test as Test Suite

    Note over Agent,Test: Build-time guidance generation
    GenScript->>Markdown: Read SKILL.md & REFERENCE.md
    GenScript->>GenScript: Escape special characters (\, quotes, tabs)
    GenScript->>Bundle: Write STAGEHAND_CODEMODE_SKILL & STAGEHAND_CODEMODE_REFERENCE
    alt --check flag
        GenScript->>Bundle: Compare generated content
        alt Content stale
            GenScript-->>Build: Throw error (block build)
        else Content current
            GenScript-->>Build: Pass
        end
    end

    Note over Agent,Test: Package exports
    Package->>Consumer: Export raw ./codemode/SKILL.md
    Package->>Consumer: Export raw ./codemode/REFERENCE.md
    Package->>Consumer: Export STAGEHAND_CODEMODE_SKILL
    Package->>Consumer: Export STAGEHAND_CODEMODE_REFERENCE

    Note over Agent,Test: Runtime MCP tool description
    Agent->>MCP: Discover available tools
    MCP->>Executor: Load tool definitions
    Executor->>Bundle: Import STAGEHAND_CODEMODE_SKILL
    Executor->>Executor: Append skill to code_execute description
    MCP-->>Agent: Return tool list (with code_execute + guidance)
    Agent->>MCP: Call code_execute({ code: "..." })
    MCP->>Executor: Execute async function body
    Executor-->>MCP: Return result
    MCP-->>Agent: Return execution result

    Note over Agent,Test: Test validation
    Test->>Bundle: Import STAGEHAND_CODEMODE_SKILL
    Test->>Markdown: Read raw SKILL.md
    Test->>Test: Compare byte parity
    Test->>Package: Resolve @browserbasehq/stagehand-integrations/codemode/SKILL.md
    Test->>Test: Verify package export resolution
    Test->>Executor: Check CODE_EXECUTE_DESCRIPTION ends with skill
    Test->>GenScript: Run with --check on fixture
    alt Content matches
        Test-->>Test: Pass
    else Content stale
        Test-->>Test: Expect error
    end

Loading

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>