spencerbeggs

Generate cross-reference graph showing relationships between design documents. Use when visualizing doc dependencies, finding related docs, or understanding documentation structure.

Validate design doc structure and frontmatter. Use when checking design docs for compliance, ensuring proper formatting, or verifying metadata before commits.

Comprehensive quality audit for CLAUDE.md context files. Use when performing thorough quality checks, preparing for releases, ensuring context efficiency, or verifying token optimization.

Style rules for LLM context files (CLAUDE.md, AGENTS.md and their .local variants). Fires automatically when these files are opened. Enforces on-demand loading patterns, proper @-reference syntax and lean context structure.

Split large CLAUDE.md into child files. Use when context files exceed word limits, are too verbose, or cover multiple distinct topics that should be separate.

Validate CLAUDE.md structure, formatting, and quality. Use when checking context files for compliance, ensuring proper structure, or verifying before commits.

Archive outdated design documentation. Use when design docs are no longer relevant, have been superseded, or document deprecated features.

Comprehensive health audit for design documentation. Use when performing thorough quality checks, preparing for releases, or ensuring documentation compliance.

Use when starting any TDD cycle, before writing any test file, editing any production file, running tests, or advancing a phase — required before any of those actions.

How to drive the vitest-agent MCP tools correctly — the non-obvious operational facts (run_tests scoping, why subset runs "fail" coverage, the consoleLeaks signal, the VITEST_AGENT_CONSOLE escape hatch, auto-recovered attribution) that otherwise cost trial-and-error.

Guide @vitest-agent/plugin configuration including thresholds, targets, output format, and plugin options. Use when setting up or modifying the plugin configuration.

Required before any production-code edit during the red phase. Forces externalization of "why I think this fix will work" with cited test_error_id and stack_frame_id evidence.

Use when starting a dogfood session for the vitest-agent plugin in this repo, when continuing one from an existing handoff at docs/superpowers/dogfood/<chain>/, or after the TDD orchestrator subagent completes a dogfood task. Repo-internal — does not apply to projects that consume vitest-agent as a dependency.

Use when reaching any TDD phase transition — spike close, red→green, green→refactor, or discard — required before exiting the phase so each cycle lands as a discrete, greppable commit in git history.

Use when working to raise code coverage, target specific uncovered lines, or close the gap against the workspace's configured coverage thresholds and aspirational targets.

Use when tests are failing, when investigating flaky or persistent failures, or when a failure signature needs systematic diagnosis through vitest-agent's test_history, test_errors, and failure_signature_get surfaces.

Comprehensive Effect v3→v4 migration reference — the single lookup for "what did this v3 API become in v4." Use when porting Effect v3 code or reaching for a v3 API name (Context.Tag, Either, Effect.async, Schedule.compose, Schema variadic unions, filter combinators, Metric.tagged, Cause guards, forkDaemon, Config accessors), and when reaching for SQL (@effect/sql is gone — the core moved into effect/unstable/sql) or a CLI (@effect/cli is dead on the v4 line — see effect-v4-cli). Per-domain rename/restructure tables verified against the installed effect beta. Consult BEFORE reaching for a v3 name; verify anything not listed against the installed package, not memory.

Use when writing tests for Effect v4 code with @effect/vitest — it.effect + Effect.gen as the default runner, asserting on typed errors via Effect.flip or Effect.result, providing test/mock layers with layer(...) for any service in R (owned or consumed; Path.layer + FileSystem.layerNoop need no platform package), property tests with it.effect.prop over a Schema, TestClock for time-dependent logic, and the mutate-the-edges discipline for proving a suite can fail. Covers the sharp edges (no it.scoped, it.prop throws on a Schema) and the FALSE GREENS that only surface at test time — a `0 tests passed` run that exits 0, TestClock starting at the epoch so clock reads return 1970, TestConsole.logLines accumulating across invocations, an eagerly-recording layerNoop stub, and Exit.isFailure failing to narrow inside assert.isTrue.

The @effected package index — what each of the kit's 18 packages contains and when to reach for it. Use when working in a repo that uses @effected/* packages and about to add a capability the kit may already ship — parsing or editing JSONC/YAML/TOML, semver math, glob matching, package.json or tsconfig.json handling, lockfile parsing, config-file loading, upward path walking, XDG directories, SQLite state/caching, monorepo/workspace introspection, git introspection, or runtime-version resolution. Also use when choosing dependencies for a new Effect v4 app or library, or when a task names an @effected package. Rows route; per-package depth lives in references/.

Use when writing core Effect v4 code — generators (Effect.gen/Effect.fn), typed error handling and recovery (catch/catchTag/catchFilter/catchReason), yieldable errors, PlatformError on FileSystem/Path IO, Cause inspection, Scope and resource cleanup, forking and fibers, runtime/entrypoints, FiberRef-as-Context.Reference, and structural equality. Teaches the idiomatic v4 spelling; for pure v3→v4 renames consult effect-v4-construct-map. Verified against effect@4.0.0-beta.94+.

Use when designing, reading, reviewing, or debugging any Effect v4 Schema — the Class-vs-Struct decision, fields and optionality, checks/refine/makeFilter, tagged unions, transformations and codecs (decodeTo, the FromString static), make-vs-new construction, brand/Opaque scalars, custom Equal/Hash, and derived tooling (toArbitrary, toJsonSchemaDocument). Also covers primitives, records, recursive schemas, custom declare types, serialization (JSON/XML/FormData), and error formatting. Verified against effect@4.0.0-beta.94+; for v3→v4 renames see effect-v4-construct-map.

Use when defining Effect v4 services or wiring Layers — the `Context.Service` class form (type params first, then the id), Layer construction (succeed/effect, scoped is gone), composition (mergeAll vs provide vs provideMerge), providing once at the boundary, and the memoization discipline that keeps a db pool or HTTP client from being built twice. Consult before reaching for any v3 name; see effect-v4-construct-map for the v3→v4 lookup.

Use when building or porting a command-line tool on Effect v4 — @effect/cli is DEAD on the v4 line (its latest peers on effect ^3.21.x), and the CLI framework now lives in core as effect/unstable/cli (Command, Flag, Argument, Primitive, Prompt), with HTTP as effect/unstable/http (HttpClient, FetchHttpClient). Covers Command.Environment and why a CLI package is integrated tier rather than pure, the exit-code contract (a usage error must fail, a no-match must not), and the process-spawning gap. Verified against effect@4.0.0-beta.94+.

The routing map for Effect v4 core — every module in one table, what it is, when to reach for it, and where to read it in the vendored source. Use FIRST when asking "what module do I reach for", "does Effect have a Sink/Pool/Trie/pattern-matcher", "what is Sink/Channel/Deferred/RcMap for", "where does X live in the source", or before designing ANY capability (the contract-inventory gate greps this map's territory). Rows route; they do not teach — patterns live in the other effect-v4-* skills, and the source is the authority on signatures and semantics.

Runs a dogfood cycle against plugin-bot — tasks the plugin-engineer agent with building a plugin capability inside the plugins/dogfood sandbox, validates and reloads it, evaluates the result (skill-creator evals for skills, fixtures/BATS for hooks), and harvests rough edges in plugin-bot's own skills and agent as improvement notes. Use after changing plugin-bot to exercise it end to end.

Enforces subagent frontmatter and system-prompt conventions when a `<name>.md` agent file is opened for authoring or review — plugin-scope ignored fields, description quality, tool-restriction shape, skills preload, and the required boundaries section.

Distilled, verification-stamped reference for the official Claude Code platform contract — plugins, skills, subagents, hooks, MCP, tools, env vars and channels. Use when authoring or auditing any Claude Code plugin component, looking up a frontmatter field, hook event schema, manifest rule, permission-rule format or tool name, or whenever a platform claim needs verifying instead of recalling from memory.

Enforces the house hook-script contract when a `hooks/**/*.sh`, `hooks/**/*.bash`, or `hooks/hooks.json` file is opened for authoring or review — envelope/exit-code/JSON discipline, subdirectory-per-event layout, lib helpers, fixtures, and BATS coverage.

Use when authoring, auditing, or registering a Claude Code plugin monitor — a monitors/monitors.json entry or the background watch script it runs. Ships the typed TypeScript poll-monitor harness (self-scheduling loop, stable-streak debounce, notify-once dedup, --once mode) plus the registration rules and notification-copy doctrine; auto-loads as the enforcer when a monitors/ file is opened.

Use when writing or reviewing language meant to shape an agent's behavior — a hook's `additionalContext` payload, a SKILL.md body or description, an agent system prompt, or an enforcer checklist. Covers choosing the imperative force, structuring with XML tags, matching the urgency tier to the moment (the EXTREMELY_IMPORTANT / IMPORTANT / reminder / acceptable-anti-pattern gradient), the persuasion-principles foundation (Cialdini + Meincke), why XML beats markdown for hook injections, and concrete templates for SessionStart, PostToolUse, and PreToolUse nudges.

Enforces manifest well-formedness when `.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json`, `.mcp.json`, or `.lsp.json` is opened for authoring or review — path-substitution rules, the hooks.json separation, and the house version policy.

Use when scaffolding a brand-new Claude Code plugin, retrofitting the house directory layout and hooks/lib helpers into an existing plugin that doesn't yet follow it, or bootstrapping hooks infrastructure (hooks.json registrations, fixtures, BATS coverage) for a plugin that has none. Ships the bootstrap checklist plus the tested hooks/lib/*.sh templates (hook-output.sh, hook-debug.sh, source-session-env.sh, gh-wrapper.sh).

Write, review, and organize the human-authored prose around a generated API reference on an rspress-plugin-api-extractor site. Use when authoring or editing a guide, concept, example, or package-overview page; deciding a site's information architecture and sidebar mount (guides spine + overview + generated api tree); setting page frontmatter (title, one-sentence description); deciding whether a code snippet earns a with-api fence versus a plain fence; writing a migration note for a breaking API change; cross-linking prose into the generated reference; or running an editorial review of a docs site. Do NOT use for the mechanics inside a with-api fence — notation, @errors,

Write and debug rspress-plugin-api-extractor configuration in an rspress.config.ts. Use when editing the ApiExtractorPlugin(...) options object — api: vs apis: single/multi shapes, versions:/multiVersion, i18n locales, the api.fromDir/apis.fromDir helpers, baseRoute/apiFolder routing, categories/DEFAULT_CATEGORIES, externalPackages/autoDetectDependencies, source links, theme (Shiki) and --api-* CSS variables, llmsPlugin, observability/logLevel, the serve() dev/preview runner, .api.json model plumbing — or when a build fails with a route collision or a Twoslash/model error. Do NOT use for RSPress mechanics outside the plugin — _meta.json/_nav.json routing, page frontmatter, built-in components, --rp-* theming (see rspress-core); for what goes inside a with-api code fence — notation, @errors, ---cut--- (see twoslash); or for the editorial call of what deserves documenting (see doc-writer).

Author and configure a general RSPress 2.x documentation site — the framework surface a docs site needs regardless of any plugin. Use when editing _meta.json (sidebar) or _nav.json (navbar); setting page frontmatter (pageType, hero/features, sidebar/outline toggles); using built-in MDX components (Badge, Tabs, PackageManagerTabs, Steps, containers, code-block line highlighting); theming with --rp-* CSS variables or the globalStyles hook; configuring RSPress locales (i18n) or multiVersion; or importing from @rspress/core/theme. Do NOT use for rspress-plugin-api-extractor's own options, --api-* variables, or API-model plumbing (see plugin-config); for the editorial craft of what prose to write (see doc-writer); or for what goes inside a with-api code fence (see twoslash).

Write and fix type-checked code examples in RSPress docs sites that use rspress-plugin-api-extractor. Use when adding or editing a code fence in a docs page, when a with-api block reports Twoslash/TypeScript errors, when choosing notation (^?, @errors, @noErrors,