jagreehal

Automates real browsers from the command line using a ref-based snapshot-then-interact workflow. Use when you need to drive a live browser, navigating pages, filling and submitting forms, clicking buttons, taking screenshots, scraping or extracting data, testing or logging into web apps, mocking network requests, or verifying responsive layouts. Triggers include "open a website", "fill out this form", "take a screenshot", "scrape this page", "test this web app", "log in to a site", "automate browser actions", or any task requiring programmatic web interaction via the agent-browser CLI.

Detects question-shaped input and forces a literal answer before any action. Use when the user's message contains "?" or trigger patterns like "why did you…?", "will that work?", "have you considered…?", "shouldn't we…?", "doesn't that…?", "is that correct?", especially when the question challenges a decision, requests an assessment, or could be misread as criticism.

Builds production-ready HTTP APIs with thin handlers, consistent error envelopes, health/readiness checks, CORS, idempotency, rate limiting, and graceful shutdown. Use when designing or implementing HTTP endpoints, writing orpc route factories, defining Zod request/response schemas, mapping domain errors to status codes, or adding operational concerns (health checks, X-Request-ID, Retry-After) to a TypeScript API.

Guides completion of development work by verifying tests, presenting structured merge/PR/keep/discard options, and executing the chosen cleanup. Use when implementation is complete and tests pass, when wrapping up a feature branch, or when deciding how to land or discard work.

Traces a code execution path with file:line references and an execution diagram before any change is made, forcing real understanding of fn(args, deps) flows, Result propagation, and workflow composition. Use before fixing a bug, implementing a feature, refactoring, or starting a TDD cycle, whenever you are about to change non-trivial code.

Receives code review feedback through technical verification rather than performative agreement or blind implementation. Use when receiving review comments, before implementing reviewer suggestions, when feedback is unclear, or when a suggestion may be wrong for this codebase.

Enforces extreme brevity and high signal-to-noise ratio so every word justifies its existence. Strips filler phrases, preambles, announcements, and unnecessary elaboration. Use when writing any response, commit message, PR description, README, implementation plan, or status update, when you catch yourself opening with "I'll help you with that" or "Let me explain", or when output is drifting into paragraphs where a list or table would carry more information in fewer words.

Forces honest, calibrated confidence assessment instead of vague certainty. Expresses confidence as a percentage, shows the evidence behind it, explains every gap below 100%, and gathers more evidence before concluding when possible. Use when about to state a root cause, diagnosis, or conclusion ("the problem is", "definitely", "clearly the issue", "complete clarity"), when an answer would mislead if it looked more certain than it is, or any time you're presenting an investigation result the user will act on.

Use this skill when instrumenting AI/LLM/agent code with OpenTelemetry GenAI semantic conventions — traceGenAI() spans, token usage and cost, gen_ai.* attributes, GenAI metric views, content/evaluation events, the Vercel AI SDK bridge, or the agent identity/delegation/policy/audit governance layer. This is the canonical home for everything GenAI in autotel (the core `autotel` package is AI-free).

Review TypeScript/JavaScript code for OpenTelemetry instrumentation patterns and guide adoption of autotel. Covers Next.js, Nuxt, Nitro, TanStack Start, SvelteKit, NestJS, Express, Hono, Fastify, Elysia, Cloudflare Workers, AWS Lambda, edge runtimes, and standalone Node. Detects unstructured tracing, missing span attributes, manual exporter setup, broken context propagation, exposed PII, and ad-hoc error handling. Covers spans, metrics, logs, structured errors, the autotel processor pipeline (tail-sampling, attribute redaction, span-name normalisation, filtering, baggage), built-in enrichers (user agent, geo, request size) and custom `defineEnricher`, `defineWorkerFetch` for Cloudflare async drains, multi-vendor OTLP backends (Honeycomb, Datadog, Grafana Cloud, Sentry, Axiom, HyperDX), `composeSpanProcessors` / `composeSubscribers` / `composePostProcessors` for pipelines, AI SDK observability with gen-ai semantic conventions, and end-to-end OTLP testing.

Query OpenTelemetry telemetry (traces, metrics, logs, LLM analytics) via the autotel CLI. Use when the user asks about a production issue, slow request, error spike, expensive LLM call, or any "what is happening in my service" question. Each command returns one JSON document on stdout — parse it and answer from the data.

OpenTelemetry instrumentation for MCP (Model Context Protocol). instrumentMCPServer, instrumentMCPClient; W3C trace context via _meta; tools, resources, prompts. Security observability: annotation hints, payload-size & char-budget signals, pluggable prompt-injection classifier, spotlighting.

When to use trace vs span vs request logger vs events in Autotel. Init once at startup, package exports (autotel, autotel/event, autotel/testing). Use for setup and choosing the right API.

trace(), span(), instrument(), init(). Factory vs direct pattern, name inference. Sync init; use node-require for optional deps. Load when wrapping handlers or functions with spans.

Troubleshoot when expected OpenTelemetry spans don't reach the backend. Walks the chain top-to-bottom — code → SDK init → processor → exporter → network → backend ingest — with concrete tests at each step. Covers head sampling, ctx.waitUntil drops on Cloudflare, init-order races, runtime detection failures, propagation breaks, exporter auth errors, and silent ratelimits.

Migrate an existing observability setup to autotel. Handles raw @opentelemetry/sdk-node, Sentry tracer (`@sentry/node`), Datadog APM (`dd-trace`), New Relic agent (`newrelic`), Honeycomb Beelines, and OpenTracing / OpenCensus. Preserves trace fidelity (no gap in dashboards during cutover), maps vendor-specific span attributes to OTel semantic conventions, and runs both stacks side-by-side during the cutover window.

Use when the user asks for a rich explanation of a code change, diff, branch, or PR in a repo that uses executable-stories. Produces an explainer that is part of the living documentation — grounded in run artifacts, published next to the stories, and finished with a comprehension quiz — instead of a throwaway HTML file.

Use when teaching a technical or coding topic (onboarding, katas, LeetCode-style practice, a library, a pattern) and you want each lesson to be runnable and self-proving. Authors lessons as executable story tests so the lesson, the test, and the living documentation are one artifact. Companion to the `teach` skill: teach owns the pedagogy (mission, progression, references) and this skill owns the verification layer.

Bootstrap executable-stories into a repo from zero. Installs Vitest and/or Playwright if missing, wires the StoryReporter, drops a sample story test, and adds a test script. Use when the user wants to "set up executable-stories", "add story testing to this repo", "initialize executable-stories", "bootstrap from scratch", or runs `pnpm dlx executable-stories-init`. Mirrors the `executable-stories-init` CLI; prefer the CLI when available, otherwise follow the manual checklist.

Use when running the executable-stories CLI or formatters API: turning a RawRun into a report (Astro, Confluence, HTML, Markdown, JUnit, Cucumber, story-report-json, etc.), gating a release, comparing runs, reviewing AI-authored changes, or driving agent-loop commands (check/triage/goal).

Use when writing BDD story tests in Jest with executable-stories-jest: top-level given/when/then/and/but imports, story.init(), or doc entries.

Use when writing BDD story tests in Vitest with executable-stories-vitest: the callback-only story.init(task) API, given/when/then/and/but steps, or doc entries.

Use when incrementally adopting executable-stories in an existing Cypress test suite, converting cy.ts specs to story tests, or adding story.init() without a full rewrite. Progressive enhancement of .story.cy.ts files; requires plugin and support-file wiring.

Use when configuring the executable-stories-cypress reporter: wiring the Mocha reporter via --reporter or cypress.config.ts, or using the module API (buildRawRunFromCypressResult, generateReportsFromRawRun) for programmatic report generation.

Use when testing a localized UI built with i18next and react-i18next, when deciding how to select a control whose text is translated, or when making the i18next setup type-safe so a bad t() key fails the build instead of shipping an empty string. Pairs the locator priority of playwright-locators with the test-id judgment of playwright-testid-strategy for the localized case.

Use when testing shadcn/ui components built on base (`@base-ui/react`) with Playwright, or when a review treats "we use shadcn, so accessibility is handled" as settled. Covers what the primitives give you (real roles, keyboard, focus traps) versus what stays application code (the accessible name), the portal scoping every overlay needs, and the surfaces where a test id hides a missing name.

Use when deciding whether a `data-testid` is justified, reviewing a PR that reaches for test ids, asserting that a conditional element is present or gone, or judging whether an aria-label is a real label or a test hook in disguise. Settles the "default or fallback" question that playwright-locators raises, with the cases where a test id is genuinely the only solution and the anti-patterns that hide accessibility bugs.

Use when building a new UI component or feature with its tests, hardening an existing component for testability, or adding component/e2e coverage. Co-designs accessible markup with role-first selectors so the query that finds an element also proves a real user can reach it, then drives a two-tier test matrix (jsdom component tests + Playwright/axe journeys). Triggers on "build a component", "add tests for X", "write tests", "make this testable", "cover this component".

Use when modelling reusable UI fragments (sidebars, headers, modals, table rows, cards) in Playwright tests, when the same locators appear on multiple pages, or when one feature renders differently across themes/frameworks/A-B variants. The container-rooted component pattern that composes anywhere without ceremony.

Use when a Playwright test fails and you need fast root-cause diagnosis using trace viewer, inspector, console/network evidence, and repeatable repro commands. Focuses on shortest path from failure to permanent fix.

Use when designing the fixtures.ts file for a Playwright suite, deciding between test-scoped and worker-scoped fixtures, composing fixtures together, providing options with defaults, or wiring page objects, components, and flows into specs. The DI layer that lets specs read like user stories.

Use when diagnosing flaky Playwright tests, deciding whether a flake is a real bug, configuring retries, working with the trace viewer, or auditing a suite for reliability. The diagnostic and the playbook for permanent fixes, and the answer to "our E2E tests are flaky."

Execute Baldrick iterations on existing specs. Use when: run baldrick, execute specs, implement features, start working. Triggers on: baldrick run, run specs, implement, execute features.

Iteratively improve test coverage until target is reached. Use when: improve coverage, test coverage, coverage target, baldrick coverage. Triggers on: coverage, test coverage, coverage loop.

Iteratively reduce code entropy by fixing smells and improving quality. Use when: cleanup, code smells, entropy, refactor loop, baldrick entropy. Triggers on: entropy, cleanup, code smells, reduce entropy.

Iteratively fix all linting errors until clean. Use when: fix lint, lint errors, lint loop, baldrick lint-fix. Triggers on: lint, fix lint, lint errors, lint loop.

Generate PR documentation from completed spec and git diff. Use when: pr docs, generate docs, pull request docs, baldrick docs. Triggers on: pr docs, generate docs, document changes.

Create a feature specification for Baldrick. Use when: create a spec, new feature, write spec for, plan this feature. Triggers on: create spec, baldrick create, new spec, feature spec.

Create comprehensive spec with diagrams, flows, and thorough documentation. Use when: detailed spec, comprehensive spec, full spec, baldrick spec. Triggers on: detailed, comprehensive, full spec, thorough.

Fast spec creation with sensible defaults. No questions asked. Use when: quick spec, vibe spec, fast spec, baldrick vibe. Triggers on: vibe, quick spec, fast spec, no questions.

Use when loading secrets from AWS Secrets Manager or SSM Parameter Store with node-env-resolver-aws, setting up reference handlers for aws-sm:// or aws-ssm:// URIs, or configuring Lambda cold-start secret resolution.

Use when integrating node-env-resolver with Next.js for client/server env split, NEXT_PUBLIC_ prefix validation, App Router server/client components, or Proxy-guarded server vars.

Use when setting up application configuration with node-env-resolver, managing secrets securely, resolving env vars, or wiring config into the composition root.

Use when integrating node-env-resolver with Vite for client/server env split, VITE_ prefix validation, build-time env injection, ImportMetaEnv type generation, or Proxy-guarded server vars.

Core patterns for awaitly: typed async workflows with automatic error inference. Use when writing workflows, migrating from try/catch, or debugging Result types.

Static analysis for awaitly workflows - complexity, paths, visualization. Optimized for coding agents.

Workflow visualization patterns for awaitly. Use when wiring event capture, renderers, collectors, time-travel, and export URLs in code.

Human-in-the-loop secure install for npm/pnpm/yarn/bun deps, driven by the `sandbox` CLI (@jagreehal/sandbox-node). Runs a read-only `check` review pass (no Docker) that reports supply-chain risk WITHOUT installing, surfaces each finding with a recommended action (including a concrete older version to pin), lets the user choose, then runs the real install with the matching flags. Use when the user wants to install, add, remove, or update dependencies safely, vet a package before installing, review supply-chain risk (fresh releases, OSV advisories, known malware), or asks to "sandbox install" / "check this package".

Contain a coding agent (Claude Code, Cursor, Codex, …) so the package-manager and dependency code it runs can't touch host credentials, persistence, or the network — using the `sandbox` CLI (@jagreehal/sandbox-node). Covers the two lifecycles: ephemeral (agent on the host, every dangerous command jailed by a PreToolUse hook via `sandbox init --agent`) and persistent (agent + editor INSIDE a hardened devcontainer via `sandbox devcontainer init`). Use when the user wants to run an AI coding agent safely, stop an agent from running bare `npm install`/`npx`, isolate an untrusted repo or agent session, or asks to "sandbox my agent" / "lock down Claude in this repo".

Harden a repo's CI/cron with the read-only, no-Docker gates of the `sandbox` CLI (@jagreehal/sandbox-node) — `verify` (the sandbox boundary is committed and un-loosened), `delta` (gate only the dependency changes a PR introduces), `scan` (retroactive malware sweep over the committed lockfile), `secrets` (committed-credential tripwire), and signed `verify --sign` receipts. Use when the user wants a CI gate for supply-chain risk, a PR check for new dependencies, a scheduled malware re-scan, a committed-secret check, a "sandboxed" badge, or asks to "add sandbox to CI" / "gate dependency changes".

Audit an existing project's dependencies with screen-node and move to safe versions. Scan the declared deps, catch deps that turned malicious after install, gate a PR's dependency changes, and upgrade to vetted releases. Use when auditing a repo's dependencies, reviewing dependency changes in a PR, upgrading packages, or wiring screen into CI.

Add or install npm/pnpm/yarn/bun dependencies safely with screen-node — review findings first, then install with only the overrides you approved. Use when adding a dependency, running an install, or vetting a package before adopting it.

Use when working on the effect-analyzer package - static analysis for Effect-TS code. Covers architecture, IR types, adding analyzers, output renderers, CLI flags, diff/regression detection, interactive HTML, test matrix, coverage audit, testing with fixtures, and the fluent analyze() API. Triggers on changes to packages/effect-analyzer or questions about Effect program analysis, mermaid diagrams, or IR nodes.

Environment orchestration for Cloudflare Workers. Use when someone needs to configure, deploy, destroy, or troubleshoot staging/preview environments for Workers projects. Triggers include: wrangler-deploy.config.ts, wd commands, stage provisioning, Cloudflare resource management (D1, KV, Queues, R2, Hyperdrive), multi-worker orchestration, service bindings, CI/CD generation, secrets management, and environment lifecycle. Also use for local dev with `wd dev`, post-deploy verification, usage monitoring with guard, and comparing stage configurations. Prefer wd over raw wrangler for multi-worker projects with staging/preview environments.