relay

The §7 Flow Package format — directory layout, package.json shape (including the `relay` metadata block), entry point contract (default-export from flow.ts), README §7.4 ordered sections, and the semver discipline that catalog flows follow. Trigger this skill when creating or validating a flow package — examples in `examples/`, reference flows in `packages/flows/`, generator templates in `packages/generator/templates/`, the lint check in `packages/cli/src/lint.ts`, and the registry generator in `packages/cli/src/registry.ts`.

The Relay brand grammar — the mark, symbol vocabulary, color rules, voice principles, banned words, naming conventions, and verbatim copy blocks. Trigger this skill whenever you write any user-visible string — CLI command output, banner, error message, README, marketing copy, catalog page, or generator template README. This is the single source of truth for what Relay sounds like; the product spec lives in `_specs/relay-product_spec.md` and this skill distills the rules an agent needs at write time. As of sprint 19, the canonical nouns are Flow / Step / Handoff — the old nouns Race / Runner / Baton are forbidden in user-facing copy.

Conventions for the Relay pnpm-workspace monorepo — root config, per-package package.json shape, tsconfig setup, tsup bundling config, vitest test setup, ESM-only Node 22.0 + TypeScript 5.4 stack. Trigger this skill when scaffolding a new package, configuring `tsup.config.ts` or `tsconfig.json`, wiring `vitest.config.ts`, adding workspace dependencies (`workspace:^`), or troubleshooting the build pipeline. Flow packages live in `packages/flows/`. Used by the foundational sprint-0 tasks and any later task that touches build infrastructure.

TypeScript 5.4+ patterns for the Relay codebase — strict mode discipline, ESM with NodeNext resolution, discriminated unions (used heavily in Runner types and InvocationEvent), Zod schema inference, type narrowing, branded types, the ban on `any` and `as` casts, and the import-extension rules ESM enforces. Trigger this skill when writing or refactoring any `.ts` file, when designing types for a new module, when the type system is fighting you, or when an agent is tempted to reach for `any` or `// @ts-ignore`.

Comprehensive skill for building websites with Astro.build. Use when the user wants to create a website using Astro, needs to select an appropriate theme from Astro's free themes collection, requires access to Astro documentation, or wants to develop Astro components and pages. This skill handles theme selection, documentation access, project setup, and Astro-specific development patterns.

Scaffold a new Relay flow package — name the flow, pick a template (blank, linear, fan-out, discovery, or loop), elicit high-level steps, choose a model per step, and write a valid flow package to disk. Trigger when the user says "scaffold a new relay flow", "/relay-new", "generate a pipeline for ...", "new relay flow", or asks to create a Relay flow from a natural-language description (including iterative implement-and-review loops). Uses Read, Write, AskUserQuestion, and Bash. Does not build the core library and does not run flows — it only emits a directory matching the Relay Flow Package format.

How to execute a Relay sprint — read the sprint JSON in `_work/sprint-<N>.json`, dispatch each wave's tasks in parallel to the right agents, validate after each wave, and commit atomically per task. Trigger when the user says "work on sprint N", "execute sprint", "start the sprint", "next wave", or any phrase that refers to running tasks from a sprint backlog. This skill encodes the wave protocol so a session can fan out work without losing track of dependencies.

Vitest testing patterns for the Relay codebase — describe/it structure, async/await tests, the MockProvider pattern (no live Claude calls), env stubbing for the auth guard tests, child_process mocking, snapshot testing for CLI banner output, fake timers for time-dependent code, and the temp-dir fixture for filesystem tests. Trigger this skill when writing or maintaining any `tests/**/*.test.ts` file across `@ganderbite/relay-core`, `@ganderbite/relay`, `@ganderbite/relay-generator`, or any race package. Pair with the `relay-monorepo` skill for the per-package vitest config.

Zod v4 idioms for the Relay codebase — the v3 → v4 symbol table, the `z.ZodType<T>` pattern that replaces `ZodSchema<T>`, the `z.core.$ZodIssue` type used in `HandoffSchemaError`, the unchanged `instanceof z.ZodType` runtime check, and the v4-only error helpers like `z.treeifyError`. Trigger this skill whenever you write or refactor a `.ts` file that imports from `'zod'` or `'../zod.js'`, or that exposes a Zod type in a public signature (e.g. `FlowSpec.input`, a handoff schema, a step `output.schema`). Pair with the `typescript` skill.

Relay's `ANTHROPIC_API_KEY` safety contract — the §8.1 guard that prevents subscription users from silently routing tokens to a paid API account, the error hierarchy that surfaces auth/billing failures, the doctor command's blocking checks, and the env passthrough rules that contain the threat. Trigger this skill any time code touches `ANTHROPIC_API_KEY`, `CLAUDE_CODE_OAUTH_TOKEN`, the env allowlist, the doctor command, the auth inspector, the runner's authenticate phase, or any error formatting that mentions billing. The single most important non-functional requirement in the project.

The three-tier provider selection model — `--provider` flag, flow-level settings.json, global settings.json, and `NoProviderConfiguredError`. The settings schema (currently `{ provider? }`), the `relay init` command contract, path helpers `globalSettingsPath` and `flowSettingsPath`, and the `resolveProvider` function. Trigger this skill when implementing or changing provider resolution, `relay init`, settings loading, or any code that reads or writes `~/.relay/settings.json` or `<flowDir>/settings.json`.

How to use `@anthropic-ai/claude-agent-sdk` correctly inside Relay — the `query()` async iterator, options shape, message envelope translation, environment passthrough, abort signal wiring, and the auth contract that rejects subscription tokens on this path. Trigger this skill whenever code imports the SDK, when implementing the `ClaudeAgentSdkProvider`, the auth inspector for the `claude-agent-sdk` providerKind, the env allowlist, the SDK→InvocationEvent translator, or the doctor command. For subscription-safe races running on Claude Pro/Max without API billing, use the `claude-cli-provider` skill instead.

How `ClaudeCliProvider` spawns `claude -p` as a subprocess — invocation shape, stdin prompt convention, subprocess lifecycle (spawn → AbortSignal → SIGTERM → SIGKILL), stream-json envelope types, env allowlist with ANTHROPIC_API_KEY suppression, subscription auth contract, and the probe strategy. Trigger this skill when implementing or wiring ClaudeCliProvider, the subprocess runner, the stream-json translator, or any code that touches `claude -p` lifecycle. For the API-key billing path, see the `claude-agent-sdk` skill.

Plain JavaScript patterns for the narrow surface where Relay uses JS instead of TypeScript — the executable bin shims (`bin/relay.js`, `bin/relay-generator.js`, `bin/generate-registry.js`), the static catalog site's vanilla browser JS (`catalog/app.js`), and any GitHub Actions workflow snippets. Trigger this skill when editing any `.js` file in the repo. The goal is JS that behaves identically to the surrounding TypeScript at runtime — same ESM rules, same Node version target.