claude-code-artifacts

Hard-won gotchas building a .NET Aspire app with gRPC, a message bus, and an in-process agent, the kind that each cost a debugging session. Use when an Aspire service cannot reach another (service discovery, "No such host"), wiring gRPC between Aspire projects (HTTP/2, HTTPS, ALPN), adding RabbitMQ via Aspire (guest login fails, generated password, Not_Authorized), using MassTransit (v8 vs v9 licensing, IBus vs IPublishEndpoint, captive dependency), passing AppHost configuration or parameters (the `__` env-var separator, AddParameter from appsettings/user-secrets, where each setting should live, clone-and-run defaults, Worker SDK appsettings copy), building an agent with the Microsoft Agent Framework (Microsoft.Agents.AI, ChatClientAgent, function tools, an OpenAI-compatible/LiteLLM endpoint, CodeAct/Agent Harness providers, compacting a long-lived AgentSession), a Web SDK project hitting an ambiguous type like SessionOptions, the AppHost not seeing app types, exporting OpenTelemetry GenAI telemetry or fannin

See and drive a locally-running web app in a real browser to verify a change — navigate, screenshot, read console errors, and poke page state via eval. Use when verifying a visual or behavioral change to any web project (UI tweak, new component, animation, form, bug fix), comparing the rendered page against intent, or reproducing a runtime error. Also covers responsive/viewport testing with resize and verifying animations by sampling element state over time (not from a single screenshot), and the gotcha that an eval reading state right after a click returns stale values because the framework re-renders asynchronously. Project-agnostic; uses the global @playwright/cli (playwright-cli).

Performance techniques for canvas 2D render loops that draw thousands of small elements (star fields, particle systems, point clouds, scatter plots) and are CPU-bound or janky, especially on low-end devices. Use when a requestAnimationFrame canvas loop is slow, when optimizing a per-frame draw over many points, or when deciding what is actually expensive (per-element trig/projection vs canvas draw calls). Covers caching a slowly-changing projection and reprojecting at a low rate, sprite blitting (drawImage) instead of per-element beginPath/arc/fill and the per-element fillStyle color-string parse it avoids, color-bucket sprite atlases, sine/periodic lookup tables with bitwise-mask indexing, and decomposing cost before optimizing.

Building a headless or containerized worker that drives the Claude Agent SDK (@anthropic-ai/claude-agent-sdk, the TypeScript/npm SDK that wraps the Claude Code CLI, not the `claude` CLI directly). Use when a query() session hangs and never finishes, when running Claude Code unattended with no human to answer a tool-permission prompt, when streaming input into a live session for mid-run steering, when the SDK's systemPrompt / SDKUserMessage / hook shapes do not match what you wrote, or when building a one-shot vs long-lived agent worker. Covers the streaming-input session that never ends (break on the result message), permissionMode bypassPermissions, the preset-append systemPrompt, SDKUserMessage.parent_tool_use_id, query()/interrupt() teardown, PreToolUse/PostToolUse hook fields, subscription-token billing, and version drift.

Generate unit tests for an interface or service by delegating to implementation-blind sub-agents that derive black-box tests from the documented contract, with a clarifying-question and assumption-ledger loop that resolves spec ambiguity instead of guessing. Use when writing or expanding unit tests for C#/.NET interfaces, services, or DI seams (xUnit), when you want tests that do not share assumptions with the implementation, or when adding a test suite after introducing interfaces. Covers the sub-agent briefing, the question/answer loop, integration (build, run, serialize global-state tests for xUnit parallelism), and the common failure modes of LLM-written tests (tautological, vacuous, hallucinated APIs).

House standard for writing C# XML documentation comments (/// triple-slash doc comments) to Microsoft's conventions. Use when writing, reviewing, or tightening <summary>, <remarks>, <param>, <returns>, <typeparam>, or <exception> tags on C# types and members, or when doc comments feel too verbose. Covers what belongs in summary vs remarks, when to use each tag, and the project rule that summaries stay short.

Write and organize technical documentation with the Diátaxis framework: the four modes (tutorial, how-to guide, reference, explanation), the compass for classifying content, the deep/functional quality model, and the iterative improvement workflow. Use when writing or restructuring docs, READMEs, guides, API/reference pages, or architecture/explanation write-ups; when a page feels tangled or mixes teaching with lookup; when deciding what kind of page something should be; or when auditing and splitting an existing documentation set into a navigable structure.

Capture the durable learnings from a work session and route each one into the right Agent Skill instead of a dump file: augment an existing skill or create a new one, global-and-reusable vs repo-local, written to skill-authoring best practices. Use at the end of a substantive session, or when asked to "capture learnings", "store what we did in skills", "disseminate knowledge", "wrap up", or after solving something non-obvious worth reusing. Covers what is worth keeping, classifying by scope and type, finding the existing home before creating, writing concrete trigger-first skills, the global-vs-committed reference conventions, and avoiding the monolithic learnings file trap.

Building self-hosted/local text-to-speech and real-time audio playback in a .NET/C# app. Use when choosing an open-source TTS engine for self-hosting (Kokoro, Orpheus, Kyutai, Piper, XTTS, Fish, Chatterbox, CosyVoice) and weighing latency, license, and VRAM; integrating KokoroSharp (in-process ONNX TTS) including getting raw PCM without auto-play, model download, voices, and espeak-ng; doing audio output with PortAudioSharp2 (callback-only, transitive native runtimes); stopping a continuously-listening assistant from transcribing its own TTS (acoustic echo cancellation with WebRTC APM via SoundFlow.Extensions.WebRtc.Apm, mic-mute vs AEC vs an inaudible cross-device watermark, full-duplex vs two independent PortAudio streams when mic and speaker are separate clocks, anti-aliased resampling via NAudio.Core, barge-in); diagnosing a render-path buzz/choppiness or an endpointer that stalls 10+ seconds (push-resampler imaging from draining it dry, jitter-buffer underruns from bursty TTS and the pre-roll fix, why a

Reference for modeling a domain with Event Storming and tactical/strategic DDD: the sticky-note color vocabulary, the command-aggregate-event-policy flow grammar, and the conflations to avoid. Use when building or reviewing an event-storming diagram or model, choosing colors/labels for domain concepts, deciding whether something is a Policy vs an Invariant, representing aggregates/commands/events/read models/external systems/actors, mapping a DDD domain, generating such diagrams from code, or recovering a model from annotated .NET assemblies with Hindstorm. Covers what a topological (code-derived) view loses versus a workshop wall, and when a domain is a streaming/dataflow transformation pipeline (where forcing the command/aggregate grammar is over-modeling). For those, names the second-plane vocabulary: CEP / event abstraction hierarchy, soft real-time, supporting vs core subdomain, data on the inside vs outside, domain event vs measurement, and Event Modeling's Automation and Translation patterns, joined to

Build seeded, reproducible generative SVG logo/mark generators — brute-force "gallery" tools that roll many candidate marks you can lock, tweak, and export. Use when creating a generative logo lab, procedural emblem/icon generator, parametric mark explorer, constellation/orbit/spirograph mark tool, or any UI that turns parameters into SVG and needs reproducible seeds, a per-item editor, rotational symmetry, or PNG/SVG export in the browser. Covers seeded PRNG determinism (mulberry32, deriveSpec/renderSpec split, preserving RNG draw order), rotational/mirror symmetry via SVG defs+use, client-side SVG→PNG rasterization, in-page color controls that avoid OS-dialog freezes, and a Svelte-5 localStorage autosave pattern. Also rendering a generated mark outside the lab (as an <img> or data-URI, where page var()/currentColor don't resolve so colors must be baked), coloring a mark from a CSS design token via an ink override, and building a generative favicon that rolls a fresh mark each page load.

Reference guide for homelab-platform and homelab-services gotchas, known issues, and hard-won fixes. Use when troubleshooting Ansible (handler patterns, docker_container idempotency on bind-mount file changes, docker_container being additive so removing/decommissioning a service needs state: absent or docker rm, copy: vs template: for placeholder substitution, ANSIBLE_SSH_AGENT auto for 2.16+, ansible_hostname drift), Terraform (bpg/proxmox provider, kenske/technitium provider, dns-record CNAME vs A-record, output description interpolation, stale vm_ip after DHCP renewal), GitHub Actions (runner registration, offline / zombie-busy recovery, workflow_dispatch 422 from broken YAML, heredoc-in-block-scalar collisions), Infisical (OIDC trust bindings, env var pickup in Terraform), Docker (localhost in bridge containers, force-recreate after bind-mount edit, container UIDs for bind-mount permissions), DNS (.lan via systemd-resolved drop-ins, static-IP hosts need explicit A records), rsync deploy steps, or VM provi

Homelab local inference infrastructure reference. Use when working with the local-inference-infrastructure repo, the LiteLLM gateway VM, LM Studio on the inference machines, GPU node configuration, model selection, manifest-driven config generation, or Claude Code proxy setup through the homelab. Covers the specific homelab deployment, not general LiteLLM or LM Studio topics.

Query NASA/JPL HORIZONS for real spacecraft and planet position/velocity vectors over time via its public REST API. Use when you need actual trajectory or ephemeris data — where a probe (Voyager, Pioneer, New Horizons, Cassini, Parker, Juno, etc.) or a planet was at given dates, heliocentric/barycentric coordinates, an orbit or flight-path to plot, or "position of X relative to the Sun/Earth over time". Covers the ssd.jpl.nasa.gov/api/horizons.api endpoint, VECTORS + CSV params, SPICE/NAIF body ids, the ecliptic X-Y (north-pole) projection, and the coverage-bound error + clamp-and-retry gotcha.

LiteLLM proxy configuration, model routing, virtual keys, and admin UI. Use when working with LiteLLM config files, adding or removing models, troubleshooting routing errors, managing virtual keys, configuring callbacks, or diagnosing proxy issues. Covers both general LiteLLM knowledge and admin operations.

Manage Claude Code skills: create, edit, list, delete, and validate. Use when the user wants to make a new slash command, modify an existing skill, see available skills, remove a skill, or check a skill for problems. Supports both project-level (.claude/skills/) and global (~/.claude/skills/) scopes.

Interoperating between a Node/TypeScript service and a .NET MassTransit app over RabbitMQ, with no .NET runtime on the Node side. Use when a non-.NET worker must consume or publish MassTransit messages, when weighing or rejecting the masstransit-rabbitmq npm library, when RabbitMQ 4.x rejects a client (403 as guest, a frame_max negotiation reset / ECONNRESET, 541 INTERNAL_ERROR from transient_nonexcl_queues or global_qos being deprecated), or when a message published to a message-type exchange never reaches a MassTransit consumer. Covers the MassTransit JSON envelope + exchange topology to hand-roll with raw amqplib, why masstransit-rabbitmq 0.1.x is unfit for RabbitMQ 4.x, the RabbitMQ 4.x incompatibilities and their fixes, broker-log diagnosis, and the CJS-double-wrap ESM import trap.

Driving DOM and text elements as Matter.js rigid bodies for scroll- and cursor-reactive web animations (drift-apart hero text, gravity-well / suck-into-element, drag-to-throw, funnel-through-a-point). Use when building physics-based UI motion with matter-js, mapping bodies to CSS transforms, debugging why bodies will not move or run too fast on a 120Hz/144Hz monitor or too slow on iOS Low Power Mode, tuning forces / mass / collisions / restitution, or adding cursor pull, grab-to-throw, or implode-into-a-target effects. Covers frame-rate independence across high-refresh and low-power displays, the deltaTime-squared force gotcha, prefers-reduced-motion (no-op vs reduced) and accessibility, the DOM-vs-Canvas-vs-WebGL choice, sticky-element coordinate alignment, a debug overlay, and building a force-directed node-link graph over DOM bodies (constraint springs, node repulsion, centering, directional flow, a traveling pulse, an SVG edge overlay, and responsive layout hooks). Also covers touch-scroll finger forces (

Playbook for releasing a .NET NuGet library (not a CLI) to nuget.org with release-please + MinVer + OIDC Trusted Publishing, so no long-lived API key is stored. Use when setting up or debugging NuGet package publishing, GitHub Actions release workflows, the NuGet/login OIDC step, a trusted-publishing policy, release-please Release PRs, MinVer tag-driven versions, or a multi-package monorepo. Covers the hard gotchas: the "Actions can't create pull requests" toggle, first-release 1.0.0 vs Release-As, the 401 workflow-file mismatch, the NUGET_USER secret, id-token permission, and NU5104.

Create, lint, and search notes in Blake's Obsidian vault (second brain, knowledge base). Use when the user wants to create an atomic note, daily note, index note, project note, feature note, reference note, person note, recipe note, repository note, or any other Obsidian note; lint existing notes against vault standards; search the vault; explore a note's related notes (backlinks/incoming links, outgoing links, neighbors); rename, move, or delete notes (via the official Obsidian CLI, so backlinks stay intact); or propagate template/standards version updates. Operates on the vault at C:\Users\Blake\Documents\Obsidian\main.

Open a URL in a new tab after a delay or animation, without tripping popup blockers or stealing focus from the current page. Use when navigation must wait for a transition or animation to finish, when window.open after a setTimeout / requestAnimationFrame gets blocked, when a freshly opened tab steals focus mid-animation, or when you want a link to open in a background tab from JavaScript. Covers transient user activation and the Ctrl/Cmd-click background-tab technique.

Methodically investigate a subject entity (person, company, organization, politician, or facility) from open sources and build a sourced, graph-linked dossier in an Obsidian vault, then distill the patterns and concerns that matter to a decision. Use when the user wants to look into, vet, research, dig into, profile, or do due diligence on a subject ("look into X", "is X legit", "who owns or runs X", "build a profile of X", "investigate this facility / company / person"). This is a collaborative, interactive way of working WITH the user, never an autonomous pipeline. Defers to the obsidian-vault skill for note standards and references the playwright-cli skill for browser work.

Automate browser interactions, test web pages and work with Playwright tests.

Use when building voice activity detection, speech endpointing, or continuous speech-to-text pipelines in Python. Covers Silero VAD (ONNX interface, bypassing the Python wrapper), sounddevice for Windows audio capture, the IDLE/SPEAKING/TRAILING endpointing state machine with pre-roll and hangover, and faster-whisper as the STT backend.

Discover and install Claude Agent Skills (SKILL.md packages) from across the ecosystem by querying live registries. Use when the user wants to find a skill for a task, browse what skills exist for a topic, check whether someone has already built a skill, refresh the skill catalog, or get install commands for a skill. Reads the official Anthropic marketplaces plus community registries (SkillsMP REST API, GuildSkills cross-agent catalog) and ranks by trust and popularity.

Interact with the Technitium DNS server on the homelab (dns-vm.lan). Use when the user wants to see what devices are on the network (DHCP leases), list DNS zones or records, add/delete a record, query the DNS query log, view server stats or top clients/domains, flush the resolver cache, inspect allow/block lists, or do an ad-hoc resolve from the server's perspective. Wraps the Technitium HTTP API at http://dns-vm.lan:5380 with Bearer-token auth.

Generate pixel-perfect image assets (social/channel banners, avatars, OG images, brand art) by rendering them in a web page and screenshotting with a headless browser. Use when you need exact-dimension PNGs from HTML/CSS/SVG/Svelte, hi-DPI / 2x exports, a manifest-driven asset gallery with a raw export route, safe-zone overlays for platform crops, or an in-page download button. Covers Playwright element.screenshot at deviceScaleFactor, a raw-mode route plus a JSON manifest endpoint shared by the exporter and the preview UI, canvas devicePixelRatio for crisp 2x, html-to-image for in-browser downloads, and reading the exported PNG back to verify it visually.

Gotchas working in a git worktree on Windows and sharing a branch across parallel sessions. Use when a fresh worktree shows the whole tree as "modified" with no real changes (core.autocrlf / CRLF-LF warnings), when node_modules is missing in a worktree, or when two agents/sessions edit the same worktree/branch and you must commit only your own files. Covers diagnosing phantom EOL "modifications" (git diff --ignore-cr-at-eol / --numstat) and fixing them permanently with a committed .gitattributes + git add --renormalize, junctioning node_modules into the worktree, staging scoped to your files with git mv to preserve history, and matching exact tab indentation for whitespace-sensitive edits.

Use when setting up CUDA-accelerated Python libraries (ctranslate2, faster-whisper, torch) on Windows. Covers DLL loading gotchas for ctranslate2 (LoadLibraryA vs AddDllDirectory), supplying CUDA runtime libraries via pip without a system CUDA Toolkit, CUDA driver-vs-toolkit version mismatches, and PyTorch CUDA wheel Python version caps.

How to capture and enforce coding standards and conventions for AI coding agents in a repository, cross-tool and not Claude-specific. Use when setting up AGENTS.md, deciding where a convention should live, wiring a CLAUDE.md @AGENTS.md bridge, making rules portable across Cursor, Copilot, Codex, Gemini CLI, Aider, and Claude Code, or enforcing conventions via linters, analyzers, or .editorconfig. Covers the two-layer model (deterministic enforcement plus natural-language context) and the routing rule for which layer a given rule belongs in.

Playbook for versioning and releasing a .NET CLI from git tags: MinVer for tag-driven versions, release-please for automated stable Release PRs, and a rolling "edge"/nightly prerelease channel. Use when setting up or debugging release automation, version numbering, GitHub Actions release workflows, prerelease/nightly channels, or self-contained binary publishing for a dotnet CLI. Covers the non-obvious gotchas (first-release 1.0.0, Actions PR permission, tag-prefix matching, fetch-depth, GITHUB_TOKEN downstream limits).

GitHub CLI utilities for repository management, branch protection setup, CI workflows, release tagging, and deployment automation. Handles repo operations via gh API calls with proper JSON payload formatting. Use when adjusting PR scope, isolating commits to specific files, or creating a clean focused pull request from an existing branch.

Operational knowledge for the homelab dashboard (gethomepage/homepage at dashboard.lan:3000). Use when adding or rearranging service tiles, fixing broken icons, troubleshooting "Host validation failed" errors, tweaking layout/columns, wiring up widget API integrations, or understanding why a config change hasn't shown up on the page yet. Covers the specific homelab deployment in homelab-services/services/dashboard/, not general Homepage usage.

Operational knowledge for the homelab LGTM stack (Grafana, Loki, Tempo, Prometheus on observability-vm). Use when adding a Prometheus scrape target, adding or modifying a Grafana dashboard or data source, troubleshooting why a VM's logs aren't reaching Loki, fixing Alloy label issues, tweaking Tempo config, wiring up trace pipelines, scraping LiteLLM /metrics with bearer-token auth, configuring LiteLLM OTLP push to Tempo, debugging missing traces or stale Tempo search results, building dashboards via the Python generator pattern, or understanding what runs where in the metrics/logs/traces stack. Covers the specific homelab deployment in homelab-services/services/observability/ + the Alloy + Node Exporter install in homelab-platform/ansible/base-vm.yml + the LiteLLM telemetry wiring in local-inference-infrastructure, not general LGTM usage.

Infisical CLI reference for managing secrets, projects, environments, and service tokens. Use when working with the `infisical` CLI — logging in with user or machine-identity (universal-auth), linking a folder to a project via `infisical init`, reading/writing/deleting secrets across environments (dev/staging/prod) and folder paths, injecting secrets into a process with `infisical run`, exporting to dotenv/JSON/CSV, creating service tokens for CI, scanning a repo for leaked secrets, bootstrapping a self-hosted instance, or pointing the CLI at a self-hosted domain. Covers Infisical Cloud (US/EU/self-hosted) and the npm-installed `@infisical/cli` binary.

Interact with Jira Cloud via the REST API v3. Use when the user wants to create issues or stories, search with JQL, read issue details, list projects, add comments, transition issues between statuses, assign issues to a user, add issues to a sprint, list board sprints, or link issues (e.g. blocks / is blocked by) on a Jira board. Handles Basic auth with an Atlassian email + API token stored in the OS credential store, and converts plain text to Atlassian Document Format. Direct REST calls, no MCP server required.

OpenCode plugin system architecture reference. Use when building, debugging, or extending an OpenCode plugin — plugin hook types (auth, tool, config, provider), /connect provider registration, custom provider opencode.json format, no-key sentinel, auth loader pattern, graceful degradation, type: "api" prompt behavior, auth.json storage schema, plugin cache invalidation, or understanding why a provider does not appear in the /connect UI.

When and how to delegate work to subagents inside a coding harness, and — just as important — when to NOT delegate. Covers the delegation decision, model-tier selection, prompt contracts for briefing, response contracts for output, parallelism, context-pressure management, and verification via back-pressure. Invoke when planning a non-trivial multi-step task, before spawning a subagent, or when the main thread's context is starting to feel crowded.

Interact with Microsoft Outlook / Office 365 via the Microsoft Graph API. Use when the user wants to read, send, reply, forward, search, delete, or organize email; manage calendar events; look up or create contacts; or manage mail folders. Handles OAuth2 PKCE authentication for personal Microsoft accounts. Covers mail, calendar, contacts, and folder operations through direct Graph API calls — no MCP server required.

Reference and runbook for the Protostar documentation site (docs.voidprojects.ai), built from the public protostar-docs content repo and shipped by the private protostar-docs-infra repo via Azure Static Web Apps, Cloudflare DNS, OIDC, and Terraform. Use when the docs site is down or 404ing, the build-check or deploy or terraform GitHub Actions are failing, a product's docs aren't showing up, the custom domain won't validate or has no TLS, adding a new product to the docs hub, or running/debugging the Terraform (bootstrap vs site, OIDC, local state). Covers the two-repo split, the fetch-docs lift, Azure SWA custom-domain cname-delegation, and the Cloudflare grey-cloud + subscription-scope RBAC gotchas. Also covers the sibling apex root site voidprojects.ai (swa-voidprojects-site), including apex TXT-token validation and Cloudflare CNAME flattening.