dotfiles

Guidance for Worktrunk (the `wt` CLI) — git worktree management, hooks, and config. Load when editing .config/wt.toml or ~/.config/worktrunk/config.toml; adding, modifying, or debugging hooks (post-merge, post-start, pre-commit, pre-merge, post-switch, etc.); configuring commit message generation or command aliases; or troubleshooting wt behavior. Also answers general worktrunk/wt questions.

Use when a repository contains a `justfile` or `.justfile` and work should flow through `just` recipes instead of ad-hoc shell commands. Covers recipe discovery, execution, debugging, and concise recipe authoring/refactoring for repeatable project tasks.

Break a plan, spec, or PRD into independently-grabbable issues on the project issue tracker using tracer-bullet vertical slices.

Offer optional 10-15 minute deliberate learning exercises during AI-assisted coding. Use when the user asks for a learning opportunity, deliberate practice, retrieval check-in, prediction exercise, teach-back, or when substantial work created a good moment to offer learning. Do not use for ordinary implementation unless the user explicitly wants learning.

Write effective pull request description bodies that explain what changed, why it changed, reviewer focus, validation, and risk. Use when creating, reviewing, or improving PR descriptions for internal work, OSS contributions, infra changes, migrations, or WIP requests for early feedback.

Write and edit substantial human-facing prose with clear, concise technical style while preserving the user's canonical voice from `~/.config/opencode/TONE.md`. Use for documentation, README prose, PR descriptions, commit-message bodies, changelog notes, issue summaries, long-form explanations, UI/help text, error messages, and copyediting drafts for clarity, concision, structure, tone, and tradeoffs.

Audit and safely clean low-value, redundant, misleading, flaky, over-mocked, or AI-generated unit tests. Use when asked to clean useless tests, prune test suites, remove redundant tests, audit low-value tests, improve test signal, clean brittle snapshots, reduce test noise, review coverage theater, or decide whether tests should be kept, rewritten, consolidated, moved, quarantined, or deleted.

Use when creating, editing, reviewing, or troubleshooting devenv.sh developer environments, including devenv.nix, devenv.yaml, packages, languages, services, tasks, scripts, processes, tests, GitHub Actions, containers, MCP/LSP integration, or reproducible Nix-based project setup. Also use when an agent needs to discover devenv options/packages, validate environment changes with devenv test, or decide between tasks/scripts/processes/services.

Recognize, design, and refactor toward deep modules: small, stable interfaces hiding substantial cohesive implementation complexity. Use when reviewing or changing module boundaries, APIs, SDKs, React components, hooks, services, CLI commands, package structure, abstraction layers, pass-through wrappers, prop drilling, temporal decomposition, information leakage, or shallow modules.

Configure and troubleshoot Hyprland safely in this dotfiles repo. Use when adding or changing monitor, bind, input, workspace, window rule, layer rule, layout, animation, env, startup, or runtime behavior in `.config/hypr/*.conf`, and when diagnosing config errors, layer-shell stacking/input issues, or post-reload regressions for Hyprland 0.55 docs / locally recorded runtime.

Use when writing or improving README files. Not all READMEs are the same — provides templates and guidance matched to your audience and project type. Use when user asks to create README, add README section, update README, review README documentation, improve project documentation, or write README.md.

Disciplined diagnosis loop for hard bugs and performance regressions. Reproduce → minimise → hypothesise → instrument → fix → regression-test. Use when user says "diagnose this" / "debug this", reports a bug, says something is broken/throwing/failing, or describes a performance regression.

Create, review, or refactor AGENTS.md files so they stay minimal and high-signal. Use when asked to write/edit AGENTS.md, trim bloated agent context files, fix stale instructions, reduce token bloat, or audit instruction clarity. Handles minimal root guidance, monorepo scoping, and progressive-disclosure references.

Author OpenCode custom slash commands as markdown files. Use when creating, editing, or reviewing commands in ~/.config/opencode/commands/ or .opencode/commands/. Covers frontmatter (description, model, agent, subtask), prompt syntax (!`shell`, $ARGUMENTS, @file), design principles, and archetypes for strict-output, structured-report, workflow-trigger, and isolated-subtask commands.

Design and implement effective subagent patterns in OpenCode. Use when creating custom agents, orchestrating multi-agent workflows, delegating batch processing tasks, optimizing tool permissions to avoid approval spam, selecting appropriate models for agents, or implementing any multi-agent coordination pattern. Covers agent creation, orchestration, delegation strategies, tool selection, permission management, and prompt templates.

Diagnose and fix Hyprland runtime problems in this dotfiles repo. Use when behavior is wrong despite valid config, including layer-shell stacking/input issues, missing keybind effects, monitor/workspace anomalies, window-rule mismatches, startup race failures, and regressions after reload on Hyprland v0.52.0.

Author, refactor, or review Lua used as program configuration in this dotfiles repo. Use when editing or evaluating Lua config layers such as .config/nvim/, .config/wezterm/, Hypr Lua helpers, or future Lua-backed dotfiles, especially shared Lua style, module layout, config table construction, event-oriented design, optional integration guards, startup/reload safety, host API boundaries, and consistency with scoped AGENTS.md guidance.

ASCII diagram patterns for architecture, workflows, file trees, and data visualizations. Use when creating terminal-rendered diagrams, box-drawing layouts, progress bars, swimlanes, or blast radius visualizations.

Use when building, testing, and deploying JavaScript/TypeScript applications. Reach for Bun when you need to run scripts, manage dependencies, bundle code, or test applications with a single unified tool.

Run a Linear issue from intake to PR with explicit delivery gates. Use when the user asks to work a Linear ticket (id or URL), create or switch a WorkTrunk worktree or branch, implement requested changes, run local format or lint checks, and ship with commit, push, PR creation, plus optional Linear status update. Includes deterministic fallback behavior when commit or push is denied by runtime policy.

Run one-off Linux CLI tools from nixpkgs without installing them globally. Use when a task hits command-not-found or missing executable errors, or when an ephemeral tool should be run via `nix run` (or comma) instead of adding system dependencies.

Contract-first API and interface design for stable integrations. Use when creating or changing endpoints, public types, config formats, module boundaries, error models, pagination contracts, or versioned compatibility behavior.

Staged deprecation and migration planning for contract changes. Use when replacing or removing APIs, config formats, CLI flags, commands, data schemas, or defaults that existing consumers may rely on.

Threat-model-first hardening for app and API changes. Use when work touches untrusted input, auth/session logic, secrets, sensitive data paths, file upload, webhooks, or third-party integrations.

TypeScript pattern matching with ts-pattern for exhaustive branching, data selection, and runtime shape checks. Use when implementing or refactoring conditionals over discriminated unions, tuple combinations, nested object shapes, reducer/state-machine transitions, or unknown input validation with `isMatching`, `P.infer`, `P.select`, and predicate patterns. Must use when the branching logic depends on structure rather than a small number of boolean checks.

Create or update Vicinae extensions in this repo. Use when implementing new extensions, adding commands/preferences, wiring React Query + Vicinae Cache, or standardizing ActionPanel UX/shortcuts, build/lint workflows, and structure to match existing patterns under .config/vicinae/extensions.

TypeScript tsconfig.json expert. Use when: - Explaining what tsconfig options mean or do - Configuring tsconfig for a specific use case (Node.js app, bundler project, npm library, monorepo, React app, strict mode) - Diagnosing tsconfig-related errors or unexpected behavior (type errors from resolution, module format issues, decorator problems, class field issues) - Comparing tradeoffs between compiler options (e.g., esModuleInterop vs verbatimModuleSyntax, isolatedModules vs verbatimModuleSyntax) - Generating, reviewing, or auditing a tsconfig.json - Understanding how top-level fields (include, exclude, extends, references) work - Choosing between module/moduleResolution combinations - Setting up project references / composite builds - Understanding what @tsconfig/bases packages provide

Evaluate Agent Skill design quality against official specifications and best practices. Use when reviewing, auditing, or improving SKILL.md files and skill packages. Provides multi-dimensional scoring and actionable improvement suggestions.

Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.

Expert guidance for TypeScript/JSDoc documentation decisions. Use when (1) documenting public library APIs for consumers, (2) deciding what to document vs skip for different audiences, (3) writing documentation for complex types or error handling, (4) setting up automated documentation generation with TypeDoc, (5) creating migration guides for breaking changes. NOT for basic JSDoc syntax—only when making documentation strategy decisions.