taskferry: Instructions file for Claude Code

taskferry

Record behavior that looks like a bug but isn't

When a change introduces behavior a future reader would reasonably file as a bug — a deliberate non-obvious default, a race the design tolerates on purpose, a "why doesn't this take effect immediately" — add it to docs/things-that-look-like-bugs.md in the same PR. That file exists so the same thing doesn't get re-diagnosed from scratch every time; it is the one piece of orientation documentation worth maintaining by hand, because nothing about it can be derived by reading the code. It lived in docs/daemon.md until the entries outgrew the daemon.

Do not reintroduce a file-by-file index of the codebase (line counts, per-file responsibility summaries). The previous docs/sourcemap.md went stale on essentially every commit that touched src/, generated repeated review findings about its own staleness, and answered questions that rg and wc -l answer correctly on demand.

Isolate your own taskferry runs when testing or developing taskferry itself

taskferry's own daemon, task state (tasks.json), file lock, and socket are resolved purely from env vars (TASKFERRY_STATE_DIR, TASKFERRY_RUNTIME_DIR, TASKFERRY_CACHE_DIR, TASKFERRY_SOCKET_PATH, falling back to XDG_STATE_HOME/XDG_RUNTIME_DIR/XDG_CACHE_HOME) — see src/paths.js. None of that resolution looks at cwd, --directory, or which git worktree you're in, so by default every worktree of this repo (and every concurrent session working in one) shares one daemon process, one tasks.json, and one lock file. This includes the "stale lock" reclaim logic in state-lock.js — it is not worktree-scoped either, it reclaims a lock in that one shared file regardless of which worktree wrote it.

Whenever a session is testing or developing taskferry itself (dispatching ferries to exercise its own dispatch/daemon/overlay code, not just using it as a tool to work on something else), export a unique TASKFERRY_STATE_DIR/TASKFERRY_RUNTIME_DIR/TASKFERRY_CACHE_DIR (e.g. under /tmp/taskferry-dev-<worktree-or-session-slug>) before dispatching, so your own dev/test daemon and task state are fully separate from the daemon and in-flight ferries any other concurrent session (or your own regular non-dev usage) is relying on. Never let a taskferry-testing session dispatch against the shared default state dir — a crash, a stale-lock reclaim, or a daemon restart triggered by your own test run can otherwise kill or corrupt another session's live ferries with no indication of what happened from that other session's point of view.