dotfiles

WHAT: Run an adversarial interview that stress-tests a raw idea before any building - surface its load-bearing assumption, steel-man the counter-case, register kill-criteria, and end with a go/no-go verdict. WHEN: Only when explicitly invoked - "grill me on X", "interview me about X", "poke holes in this", "stress-test this idea", "is this a dead end", "red-team X", "help me decide if X is worth doing", or "break this big idea into a smaller first version." DO-NOT: Do not fire unprompted on brainstorm-y talk; do not write code or a plan doc (stop at the verdict); do not endorse the idea until a real failure mode and a concrete alternative are on the table; do not cave the moment the user pushes back.

WHAT: Build a behavioral eval that drives a small model of your choice (any pi provider) headless through the pi SDK to measure whether a pi extension / feature actually changes model behavior - does the model READ injected state, ACT on an injected directive, or pick the right memory. WHEN: You added or changed a pi extension that injects context, nudges, recalls, or steers (memory, todo, scratchpad, capture, recall, guardrails) and want evidence it works on a small model, not just on a frontier one. DO-NOT: Use for unit logic that vitest already covers (pure reducers, formatters, scorers - test those offline), for frontier-model-only behavior, or for anything that does not need a live model in the loop.

WHAT: Drive the real `pi` TUI headlessly inside a tmux pane - boot it, send turns and slash commands with `send-keys`, read the rendered screen back with `capture-pane` - to smoke-test or observe behavior that only exists in an interactive session. WHEN: You need a real `/compact`, a slash command, an overlay (`/todos`, `/scratchpad`), a keybinding, or any extension behavior that the headless SDK can't reproduce, especially against a small model. DO-NOT: Use for anything scriptable through the SDK or `pi --print` (those are faster and assert on structured events, not screen scraping) - reach here only for genuinely interactive surfaces.

Persist durable user preferences, validated approaches, project conventions, and reference pointers via the `memory` tool. Save when the user corrects your approach, expresses a preference, validates a non-obvious decision, or references an external system. Do NOT save code patterns, git history, or ephemeral task state - read the code or run `git log` instead. Applies across sessions and workspaces.

WHAT: Choose between the three notes-ish tools - `scratchpad` (turn-to-turn free-form carry-over), `todo` (a typed multi-step plan), and `memory` (durable cross-session facts) - by scope and content kind. WHEN: You are about to jot something down to remember and are unsure which tool holds it. DO-NOT: Persist ephemeral task state into `memory`, use `scratchpad` for a multi-step plan, or hand-edit any of their backing files.

WHAT: Write TypeScript under `lib/node/`, `tests/`, and `config/pi/` that passes the repo's strict `oxlint --type-aware` configuration on the first try, so the husky pre-commit hook does not reject the commit. WHEN: User asks to add or edit a `.ts` / `.spec.ts` file anywhere outside `config/pi/extensions/` (the extensions tree has a relaxed override). DO-NOT: Bypass the rules with `// oxlint-disable` instead of fixing the code.

Prompting rules for **Chenkin Noob XL (CKXL)**, a NoobAI-XL-1.1 *eps* fine-tune. Use when the user asks to generate / draw / render an anime image on a CKXL workflow (v0.2, v0.5, or near-vanilla finetune). CKXL is eps (not v-pred) and uses `artist:name` syntax with anti-furry negatives; it adds CKXL-specific quality tags (`aesthetic`, `excellent`).

Prompting rules for the OnomaAI **Illustrious-XL** SDXL anime / illustration model. Use when the user asks to generate / draw / render an anime / illustration image on an Illustrious-XL workflow (v0.1, v1.0, or a near-vanilla finetune). Illustrious takes plain Danbooru tags + natural language - no `score_N` quality tags and no `@`-prefixed artist tags. Do not use for photorealism.

Prompting rules for the Laxhar Labs **NoobAI-XL v-prediction** anime / illustration model. Use when the user asks to generate / draw / render an anime image on a NoobAI v-pred workflow. NoobAI uses `artist:name` syntax and is e621-trained (requires anti-furry negatives); the v-prediction variant has strict Euler-only, low-CFG, and zsnr constraints.

Prompting rules for the CircleStone Labs **Anima** anime / illustration model. Use when the user asks to generate / draw / render an anime / illustration / non-photoreal image on an Anima workflow. Anima uses score tags and an `@artist` prefix syntax; it is for anime / illustration, not photorealism.

Prompting rules for the Black Forest Labs **FLUX.2 [klein]** text-to-image / image-edit model. Use when the user asks to generate / draw / render / edit an image on a FLUX.2 workflow (`flux2-t2i`, `flux2-t2i-fast`, `flux2-edit`, `flux2-edit-fast`, `flux2-edit-multi`). FLUX.2 is a natural-language model with an LLM text encoder - write descriptive prose, not booru tags, and mind the CFG-vs-negative caveat below.

WHAT: Use the `ai-skill-eval` CLI to validate that an AI model (especially a small local one) actually follows a SKILL.md - run per-skill evals through a driver, grade TRIGGER detection + expectation match, and read the report. WHEN: you drafted or edited a SKILL.md, want proof a skill still works after a rewrite, or want to regression-test a whole skill set against a new model. DO-NOT: skip positive + negative evals; claim a skill is validated without quoting the report; rely on the deterministic keyword-match grade when a subjective rubric is at stake - use `--critic-cmd` instead.

When to reach for a user hook (`~/.pi/agent/hooks.json` / `<repo>/.pi/hooks.json`) over an ad-hoc bash command or a full pi extension. Use when the user asks things like "can I run X every time pi does Y", "from now on when Z happens, do W", "log every bash command", "format files after edit", "inject context into every prompt", or to wire a Claude Code hook into pi. Do not suggest a hook for one-shot tasks, to replace a built-in gate, or for behavior that needs new pi events or tool registration.

WHAT: Conventions for adding or modifying a pi extension under `config/pi/extensions/` - the .ts + .md pair and where pure helpers / unit tests live. WHEN: the user asks to add a new pi extension, extract extension logic into a shared helper, or modify an existing extension's behavior. DO-NOT: put business logic in the .ts file (extract to `lib/node/pi/`); skip the companion .md doc; forget the `extensions/README.md` row; or make behavior tier-specific (small-model vs big-model branches).

WHAT: Author a new skill folder (SKILL.md plus optional references/scripts/assets) when a recurring pattern in your work should carry into future sessions; pick project-local or global scope. WHEN: you hit the same friction twice in a session and corrected it the same way both times; the user tells you to remember a procedure ("from now on do X", "always do Y before Z", "please remember", "don't do that again"); or you fixed a mistake you would predictably repeat. Reach for this even if the user doesn't say "make a skill". DO-NOT: create a skill on a single observation; duplicate an existing skill (~70% description overlap means edit it instead); restate a convention already in AGENTS.md or CLAUDE.md; edit or delete skills you did not author this turn.

Plan multi-step work up front with the `todo` tool so it survives context compaction and stays visible every turn. Use when the user's request has two or more distinct steps, touches multiple files, mixes change + verify phases (e.g. "fix the bug and add a test", "refactor X and update docs"), or is exploratory work whose steps aren't fully known at the start. Do NOT use for single-tool-call asks, trivial one-shot questions you can answer inline, or work already scoped by an active `check` iteration-loop task.

WHAT: Decide when to run a shell command off-turn with the `bg_bash` tool instead of blocking the turn on the built-in `bash` tool, and how to poll / steer / collect it across turns. WHEN: A command is long-running (dev server, build, watch, test suite, training run, log tail) or you want the turn free while it runs. DO-NOT: Background a quick command whose output you need immediately, spawn a job you never poll, or use it for pure computation - that is `compute`.

WHAT: Decide when to stop and ask the user a structured clarifying question with the `questionnaire` tool versus inferring and proceeding, and how to shape good single / multi / free questions with mutually-exclusive options. WHEN: A decision is genuinely the user's to make and the wrong guess is costly to undo. DO-NOT: Ask what you can read from the code, ask trivia with a sensible default, or stack questions for things you should just decide.

WHAT: Decide when the heavy `research` deep-research pipeline (plan -> fanout -> synth -> two-stage review, writing a cited report under ./research/) is worth its time and token cost, versus a cheaper single fetch or subagent. WHEN: The user wants a thorough, multi-source, fact-checked written report on an open question. DO-NOT: Fire it for a single lookup, a question one `ai-fetch-web` call answers, or anything you can settle by reading the repo.

WHAT: Decide when to fire a prompt at yourself on a timer with the `schedule` tool, and which trigger to pick - recurring (cron / interval), one-shot (in / at), or activity-anchored idle (after). WHEN: A session should act without a manual nudge - a cadence ping, a future reminder, or a roleplay character that keeps a scene alive. DO-NOT: Schedule something the user could just ask for now, or persist a schedule the user did not ask to outlive the session.

WHAT: Conventions for bats tests in this repo. WHEN: User asks to add or edit a `.bats` test file anywhere under tests/. DO-NOT: Put tests under tests/bin/ instead of mirroring the source path; invent new helper names when common.bash already has one; rely on the host's real `git` / `curl` / `ssh` - stub them.

WHAT: Scaffold a new bin script in this dotfiles repo with the required sibling files: the script itself, a bash completion file, and a bats test. WHEN: User asks to add a new git subcommand, utility script, or any other executable under dotenv/bin or a platform-specific bin directory. DO-NOT: Skip the completion file or the bats test stub; invent a new argument-parsing style for flag-taking scripts; or add scripts to external/ or to private `__`-prefixed paths without confirming intent.

WHAT: Author and edit markdown in this dotfiles repo so it conforms to the project markdownlint config and oxfmt prose-wrap settings, and runs through `markdownlint-cli2 --fix` and `oxfmt` cleanly. WHEN: User asks to write, edit, restructure, or fix lint on any `.md` / `.mdc` file. Defer to the more specific `commit-message`, `doc-sync`, or skill/plan/AGENTS authoring guides when those apply. DO-NOT: Run prettier instead of oxfmt, mass-rewrap mid-edit, or add a `README.md` inside a skill folder.

WHAT: Conventions for files under plugins/ - numeric load-order prefix, `command -v` guard, disable-switch contract, no-blocking-work-at-source-time. WHEN: User asks to add a new plugin, move an integration into a plugin, or debug why a plugin isn't loading. DO-NOT: Skip the `command -v` guard; perform network/subprocess work at source time; assume the plugin loads by default.

Reach for the `ai-fetch-web` CLI for web access - search the web, fetch a URL as clean markdown, batch-fetch many URLs in parallel, convert raw HTML, list links, extract CSS-selector fields, read page metadata, or screenshot a page - whenever it is on `$PATH`. Prefer it over harness-native web tools (built-in `fetch`, MCP `fetch_web`, browser plugins). Skip it only when the user is testing raw HTTP behavior (headers, redirects, POST body shape) - that is `curl`'s job.

When to reach for the `apply_patch` tool over `edit` / `write`, plus the strict Codex patch shape (`*** Begin Patch ... *** End Patch` envelope with `@@` hunks). Use for multi-file refactors, rename + edit combos, large diffs against one file, or any task where the model would otherwise stack many `edit` calls in a row. Do not use for single-line targeted edits, binary content, hand-written patches from memory, or hunks without unique surrounding context.

Reach for the `compute` tool (sandboxed JavaScript) instead of shelling out to `python3 -c`, `node -e`, `bc`, `expr`, or `jq` whenever the task is pure calculation or data transformation - arithmetic, big-number math, base/radix conversion, date math, string/regex work, reshaping JSON, hashing (sha256), base64, or UTF-8 byte work. Skip it - and use bash - the moment the task needs files, network, environment, subprocesses, or anything asynchronous.

Default to `rg`/`grep` for discovery instead of reading whole files. Use whenever you're hunting for a symbol, function, pattern, or a specific line in a repo you don't already have fully loaded in context - especially on files over ~400 lines, unknown codebases, or when the user asks "where is X defined/used?". Do NOT use when the file is already loaded in context, when a test suite already scopes the discovery, or when the user handed you an exact path to a short file.

Use the `check` tool to run a disciplined feedback loop whenever the task is "produce an artifact and confirm it satisfies a verifiable contract" - render an SVG / chart / diagram, generate a config / regex / test / fixture / snippet that has to match a spec, write code that has to pass a test suite, produce prose a critic can rubric-judge, or "make a Y that does Z". Never claim the artifact is done without a passing verdict from `check run` this turn.

Run subagents asynchronously with `run_in_background: true` and manage them with `subagent_send` (status / wait / steer / abort). Use when you want to fan out work, hide latency behind other steps, or keep the parent responsive while a long child runs. Pairs with `subagent-delegation`, which covers when and how to delegate at all.

Delegate discovery, planning, and scoped edits to a `subagent` (agent types `explore` / `plan` / `general-purpose`) whenever the next steps would pollute the parent's context with intermediate tool output you won't reuse. Use `modelOverride` to push grunt work to cheaper / weaker models. Skip when the task fits in one tool call inline or when you need the intermediate output to inform the next decision.

WHAT: Keep REFERENCE.md and the README.md Configuration Options table in lockstep with the public shell surface of this dotfiles repo. WHEN: User adds, renames, or removes an alias, shell function, environment variable, git subcommand, hook, prompt option, plugin-exposed behavior, command on PATH, or a DOT_ / BASHRC_ startup variable. DO-NOT: Update only one of REFERENCE.md and README.md when both apply; do not touch either file for purely internal helpers, refactors, or non-user-facing changes.

WHAT: After editing shell / bats / TypeScript in this repo, run the matching gate command (`./dev/lint-shell.sh`, `./dev/test-bats-docker.sh`, or `npm test`) before claiming the change is done, and quote the pass output. WHEN: Any finished edit in dotenv/, plugins/, tests/, config/, or lib/node/. DO-NOT: Run the local `./dev/test-bats.sh` when `./dev/test-bats-docker.sh` is available; skip the gate because "it's a small change"; claim done without quoting the pass tail.

WHAT: Draft commit messages and PR descriptions for this dotfiles repo, defaulting to subject-only and adding a short body only when the why is not visible in the diff. WHEN: User asks to commit, write or rewrite a commit message, or open or describe a pull request. DO-NOT: Add test counts, lint or typecheck sign-offs, per-file walkthroughs, or marketing voice; do not write a body when the subject already conveys the change.

WHAT: Decide which dotenv phase file and which platform subdirectory a new alias, function, export, or completion belongs in. WHEN: User asks to add (or move) an alias, shell function, env var, or completion in this dotfiles repo. DO-NOT: Put platform-specific code in shared phase files with runtime `uname` checks; do not invent new phase file names (`lib/load.sh` only loads the seven canonical ones); do not put `bin/` scripts in phase files.

WHAT: When a command fails, quote the literal error line from its stderr/stdout before proposing a fix, and re-read the exact source (file + line, env var, config key) the error points at. WHEN: Any non-zero exit from a build, test, lint, install, or runtime command. DO-NOT: Skip straight to "let me try X"; do not silently retry the same command; do not guess at the cause when the error names the file, symbol, or value that is wrong.

WHAT: Keep edits narrow - change only the lines the task requires, preserve surrounding formatting, and never rewrite a file when a targeted edit suffices. WHEN: Any modification to an existing file. DO-NOT: Reformat unrelated regions, reorder imports or keys for tidiness, normalize whitespace outside the edit, or rewrite a file with a whole-file write when a small replacement would do.

WHAT: Before telling the user a code change is done, actually run a verification command (tests, lint, a smoke invocation) and paste the pass output into the reply. WHEN: Any multi-file edit, new script, rename, bug fix, or refactor where the user expects working code at the end. DO-NOT: Claim "done" / "should work" / "ready" without a fresh pass output this turn; do not substitute "I reviewed the diff" for actually running the verifier.