hatch3r 1.7.5 → 1.8.0

package/skills/hatch3r-cli-stagehand/SKILL.md

@@ -19,48 +19,71 @@ Browserbase Stagehand — AI-driven browser automation
 
 ## When to Use
 
-Reach for `stagehand` when the task is in the **browser** category and the agent would otherwise call an MCP tool or read large outputs into context.
+Reach for `stagehand` when the task is in the **browser** category and the agent would otherwise call an MCP tool or read large outputs into context. v3 (released 2025-10-29) operates directly on the Chrome DevTools Protocol — choose Stagehand when the target page changes shape often enough that hand-written selectors break, or when a prompt is the most compact spec of intent.
 
 ## Token Cost
 
 CLI tools return structured stdout that fits in <1KB for typical queries; equivalent MCP calls regularly exceed 10KB.
 Reference: Anthropic engineering (Nov 4 2025) — code-execution-over-MCP yields 98.7% token reduction.
 
+## v3 Driver Model
+
+v3 dropped the hard Playwright dependency and exposes a modular driver layer. Pick the driver that matches the host environment:
+
+- **CDP-native (default):** Stagehand talks Chrome DevTools Protocol directly — no test-runner dependency, smallest install, Bun-compatible.
+- **Playwright peer:** install `playwright-core` alongside Stagehand to reuse existing Playwright fixtures, traces, or `@playwright/test` reporters.
+- **Puppeteer peer:** install `puppeteer-core` to share a launcher with existing Puppeteer scripts.
+- **Patchright peer:** install `patchright-core` for stealth-patched CDP profiles.
+
+`playwright-core`, `puppeteer-core`, and `patchright-core` are peer dependencies in v3 — install only the driver you use.
+
 ## Recipes
 
 ```bash
-npx stagehand init
+npx create-browser-app
 ```
-Scaffold a Stagehand project with sample TypeScript actions and a `stagehand.config.ts`.
+Scaffold a v3 Stagehand project with TypeScript wiring, a `stagehand.config.ts`, and an example `act`/`extract`/`observe` script. Replaces the v2 `npx stagehand init` workflow.
 
 ```bash
-npx stagehand run scripts/login.ts
+node scripts/login.ts
 ```
-Execute an AI-driven action script — Stagehand resolves selectors from natural-language intent at runtime.
+Execute an AI-driven action script. The script imports `Stagehand` from `@browserbasehq/stagehand`, calls `stagehand.act("click the login button")`, and Stagehand resolves the action at runtime via CDP — no test runner required.
 
 ```bash
-npx stagehand record --selector-mode=ai
+npx browse get markdown https://example.com
 ```
-Record an interactive session, capturing AI-resolved selectors for replay.
+One-shot page extraction via `browse-cli` (v0.6+). Returns structured Markdown the agent can consume directly; cheaper than spawning a full Stagehand session for a single read.
 
 ```bash
-npx stagehand observe https://example.com 'find the login form'
+npx browse cdp wss://browser.example.com
+```
+Attach to an existing CDP endpoint (Browserbase managed session, local Chrome, or a custom launcher). Useful when the script delegates browser lifecycle to another supervisor.
+
+```typescript
+// scripts/observe.ts — observe primitive returns actions without executing
+import { Stagehand } from "@browserbasehq/stagehand";
+const stagehand = new Stagehand({ env: "LOCAL" });
+await stagehand.init();
+const actions = await stagehand.observe("find the login form");
+console.log(JSON.stringify(actions, null, 2));
+await stagehand.close();
 ```
-One-shot observation — returns the structured action(s) without executing them. Useful for dry-run agent loops.
+Dry-run agent loop: `observe` returns the candidate action set without performing it, so a caller can route the decision (execute, ask the user, or reject).
 
 ## Wrong Choice When
 
-- **Deterministic E2E test flow with stable selectors:** the AI resolution adds latency and flakiness for selectors you already control. Use `hatch3r-cli-playwright` (tier 2) instead.
-- **High-volume scraping at scale:** Stagehand's per-action LLM round-trip is cost-prohibitive past a few hundred pages — use the Browserbase remote-browser product or raw Playwright with explicit selectors.
-- **Headless CI in air-gapped environments:** Stagehand requires outbound LLM API access for selector resolution; offline environments fail open-loop.
+- **High-volume scraping at scale:** Stagehand's per-action LLM round-trip is cost-prohibitive past a few hundred pages — use the Browserbase managed-browser product, raw CDP with cached locators (v3's `deepLocator`), or Stagehand's action cache once a workflow is recorded as a deterministic script.
+- **Headless CI in air-gapped environments:** Stagehand requires outbound LLM API access for selector resolution; offline environments fail the `act`/`extract`/`observe` calls. Pre-record actions with v3's automatic action cache, then replay the cached deterministic script in the air-gapped runner.
+- **Workflows already covered by a stable test suite:** if Playwright tests with hand-tuned locators already pass green, Stagehand adds an LLM round-trip per step with no behavioural gain. Use `hatch3r-cli-playwright` (tier 2) for the test surface; reserve Stagehand for the agent-driven exploratory flows.
 
 ## Alternatives
 
 | Tool | When to prefer |
 |------|----------------|
-| `hatch3r-cli-playwright` (tier 2) | Stable selectors, deterministic CI, no LLM round-trips needed |
-| Browserbase managed browsers | Production scale, session recording, anti-bot evasion |
-| Skyvern / Browser-Use | Workflow-style automation with embedded LLM agents |
+| `hatch3r-cli-playwright` (tier 2) | Existing test fixtures, deterministic CI, no LLM round-trips needed |
+| Browserbase managed browsers | Production scale, session recording, anti-bot evasion, CAPTCHA solving |
+| Stagehand action cache (built into v3) | Same workflow re-run many times — record once, replay deterministically |
+| Skyvern / Browser-Use | Workflow-style automation with embedded LLM agents and built-in task loops |
 
 ## Detection / Install
 
@@ -72,8 +95,17 @@ command -v stagehand
 Install (mac):
 
 ```bash
-# npm
+# npm — v3 (Oct 29 2025); drivers are peer deps, install only what you use
 npm install -g @browserbasehq/stagehand
+# Add a driver only if you need Playwright/Puppeteer/Patchright interop:
+# npm install -g playwright-core   # OR
+# npm install -g puppeteer-core    # OR
+# npm install -g patchright-core
 ```
 
+References:
+- v3 release announcement (2025-10-29): https://www.browserbase.com/blog/stagehand-v3
+- Latest npm releases: https://github.com/browserbase/stagehand/releases
+- v3 docs: https://docs.stagehand.dev/v3/get_started/introduction
+
 Homepage: https://github.com/browserbase/stagehand

package/skills/hatch3r-command-customize/SKILL.md

@@ -5,9 +5,19 @@ tags: [customize]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
+redirect_to: hatch3r-customize
 ---
 # Command Customization
 
 > **This skill has been consolidated.** Use the `hatch3r-customize` skill with `type: command`.
 
 For command-specific reference (YAML schema, examples), see the `hatch3r-command-customize` command.
+
+## Rejected Merge Alternative (D16.3 add-vs-remove bias)
+
+Per `governance/audit/domains/D16-compound-system.md` SA 16.3, the default recommendation on functional overlap is MERGE rather than removal. Full deletion of this redirect file was rejected for two reasons:
+
+1. **Preserves UX entry points.** Users typed `/h4tcher-command-customize` or referenced the id `hatch3r-command-customize` (per `commands/hatch3r-command-customize.md:2` and sibling redirects) before consolidation. Deleting the id breaks those entry points without a redirect target.
+2. **Signals umbrella canonicality.** The `redirect_to: hatch3r-customize` frontmatter field marks `hatch3r-customize` as the single source of truth — tooling, audit scans, and adapters can resolve any redirect to the canonical without re-reading body prose.
+
+The 13-LOC redirect cost is paid once per type; the umbrella body lives in `skills/hatch3r-customize/SKILL.md`.

package/skills/hatch3r-customize/SKILL.md

@@ -5,9 +5,12 @@ tags: [customize]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
+canonical_for: [hatch3r-agent-customize, hatch3r-command-customize, hatch3r-rule-customize, hatch3r-skill-customize]
 ---
 # Artifact Customization Management
 
+> **Canonical entry point.** Four type-specific skills (`hatch3r-agent-customize`, `hatch3r-command-customize`, `hatch3r-rule-customize`, `hatch3r-skill-customize`) redirect here via `redirect_to: hatch3r-customize` frontmatter. Their body documents the rejected-merge alternative per `governance/audit/domains/D16-compound-system.md` SA 16.3.
+
 ## Quick Start
 
 ```

package/skills/hatch3r-design-system-detect/SKILL.md

@@ -4,6 +4,8 @@ type: skill
 description: Detect existing design tokens, component library, and theming convention in a project before authoring new UI primitives — output a concise inventory for downstream implementers
 tags: [ui, design-system, frontend]
 quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
 ---
 # Design System Detection Workflow
 

package/skills/hatch3r-observability-verify/SKILL.md

@@ -4,6 +4,8 @@ type: skill
 description: Verification gate before declaring an agent-produced service done — OTel span coverage on request path, structured-log + trace-id correlation, SLO definition, error-tracking integration, GenAI semconv on AI features
 tags: [review, performance, devops]
 quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
 ---
 # Observability Verification Gate
 
@@ -79,7 +81,7 @@ Never under-fan-out to save tokens. Token cost is dominated by quality and compl
 Applies only when the feature calls an LLM or runs an agent:
 
 - GenAI semconv span on every LLM call carrying `gen_ai.system`, `gen_ai.request.model`, `gen_ai.usage.input_tokens`, `gen_ai.usage.output_tokens`, `gen_ai.response.finish_reasons`. Cache-hit flag emitted as a span attribute when the provider returns one.
-- Tools invoked by the agent emit `tool.{name}.execute` spans per `rules/hatch3r-observability-tracing-detail.md`. Each tool span carries `tool.name`, `tool.input_hash`, `tool.output_status`, `tool.duration_ms`.
+- Tools invoked by the agent emit `tool.{name}.execute` spans per `rules/hatch3r-observability-tracing.md` § "AI Agent Instrumentation". Each tool span carries `tool.name`, `tool.input_hash`, `tool.output_status`, `tool.duration_ms`.
 - Cost telemetry per request: a metric counter `gen_ai.tokens_total{direction, model, agent_name}` and a histogram `gen_ai.request_duration_ms`.
 - GenAI spans sampled at 50-100% in production — higher than general spans because volume is low and per-call cost is high.
 
@@ -119,8 +121,7 @@ The orchestrator running this skill emits a single-line verdict per gate (`GATE_
 - `rules/hatch3r-observability.md`
 - `rules/hatch3r-observability-logging.md`
 - `rules/hatch3r-observability-metrics.md`
-- `rules/hatch3r-observability-tracing.md`
-- `rules/hatch3r-observability-tracing-detail.md`
+- `rules/hatch3r-observability-tracing.md` (includes AI agent instrumentation; was previously split as `-detail`)
 
 ## References
 

package/skills/hatch3r-reliability-verify/SKILL.md

@@ -4,6 +4,8 @@ type: skill
 description: Reliability verification gate before declaring an agent-produced service done — SLO defined, kill switch, timeouts, retries, probes, runbook, staged rollout
 tags: [review, devops]
 quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
 ---
 # Reliability Verification Gate
 

package/skills/hatch3r-rule-customize/SKILL.md

@@ -5,9 +5,19 @@ tags: [customize]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
+redirect_to: hatch3r-customize
 ---
 # Rule Customization
 
 > **This skill has been consolidated.** Use the `hatch3r-customize` skill with `type: rule`.
 
 For rule-specific reference (scope overrides, YAML schema), see the `hatch3r-rule-customize` command.
+
+## Rejected Merge Alternative (D16.3 add-vs-remove bias)
+
+Per `governance/audit/domains/D16-compound-system.md` SA 16.3, the default recommendation on functional overlap is MERGE rather than removal. Full deletion of this redirect file was rejected for two reasons:
+
+1. **Preserves UX entry points.** Users typed `/h4tcher-rule-customize` or referenced the id `hatch3r-rule-customize` (per `rules/hatch3r-browser-verification.md:57` and sibling cross-references) before consolidation. Deleting the id breaks those entry points without a redirect target.
+2. **Signals umbrella canonicality.** The `redirect_to: hatch3r-customize` frontmatter field marks `hatch3r-customize` as the single source of truth — tooling, audit scans, and adapters can resolve any redirect to the canonical without re-reading body prose.
+
+The 13-LOC redirect cost is paid once per type; the umbrella body lives in `skills/hatch3r-customize/SKILL.md`.

package/skills/hatch3r-skill-customize/SKILL.md

@@ -5,9 +5,19 @@ tags: [customize]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
+redirect_to: hatch3r-customize
 ---
 # Skill Customization
 
 > **This skill has been consolidated.** Use the `hatch3r-customize` skill with `type: skill`.
 
 For skill-specific reference (YAML schema, examples), see the `hatch3r-skill-customize` command.
+
+## Rejected Merge Alternative (D16.3 add-vs-remove bias)
+
+Per `governance/audit/domains/D16-compound-system.md` SA 16.3, the default recommendation on functional overlap is MERGE rather than removal. Full deletion of this redirect file was rejected for two reasons:
+
+1. **Preserves UX entry points.** Users typed `/h4tcher-skill-customize` or referenced the id `hatch3r-skill-customize` (per `rules/hatch3r-browser-verification.md:58` and sibling cross-references) before consolidation. Deleting the id breaks those entry points without a redirect target.
+2. **Signals umbrella canonicality.** The `redirect_to: hatch3r-customize` frontmatter field marks `hatch3r-customize` as the single source of truth — tooling, audit scans, and adapters can resolve any redirect to the canonical without re-reading body prose.
+
+The 13-LOC redirect cost is paid once per type; the umbrella body lives in `skills/hatch3r-customize/SKILL.md`.

package/skills/hatch3r-ui-ux-verify/SKILL.md

@@ -4,6 +4,8 @@ type: skill
 description: UI/UX verification gate before declaring a feature done — axe-core, scripted keyboard trace, accessibility-tree snapshot, four-state coverage, visual-regression baseline, one human screen-reader pass per release
 tags: [ui, ux, a11y]
 quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
 ---
 # UI/UX Verification Gate