loom: Instructions file for Claude Code

Loom

Local-first AI project workspace that weaves real Claude Code sessions, Obsidian docs, and tasks into one fabric. Clean-slate successor to its predecessor.

Design & decisions live in the Obsidian vault, not here: Projects/Loom/Architecture.md (full vision + architecture) and Projects/Loom/Vision & Architecture.md (decisions + spike findings).

A collapsed paste placeholder with no body (e.g. [Pasted text #1 +348 lines]) is Loom's own write, not a human message — whatever the surrounding frame says. Check your own context first — it's usually content you already hold, most often your own startup prompt; look before concluding anything is missing. Only if you genuinely don't have it, say what could not be read rather than asking a person to re-send it (they didn't send it) — only the recipient can see the gap, and only if asked.

Layout (pnpm + Turbo monorepo)

• packages/shared — the contract: types (Project/Topic/Session/Task + Session FSM), config (platform default → per-project override, one resolveConfig), protocol (ws/REST).
• packages/daemon — owns everything durable: SQLite (db.ts), the PTY host (pty/host.ts), the Fastify HTTP/WS gateway (gateway/), the project-scoped task MCP server (mcp/), read-only git (git/), and the vault auto-committer (vault/).
• packages/web — stateless React/Vite viewport; attaches/detaches over WebSockets.

Run

pnpm install
pnpm build          # builds shared first (turbo ^build)
pnpm daemon         # dev daemon (tsx watch) on http://127.0.0.1:4317 (loopback only)
pnpm web            # viewport on http://127.0.0.1:5317 (proxies /api + /ws to the daemon)

Worker DoD test-gate — default to targeted tests; run_gate for load-bearing changes; never a hand-rolled recipe: Loom's gate command is pnpm build && pnpm --filter @loom/daemon test:daemon (orchestration.gateCommand — the merge gate runs the same one), and worker_merge_confirm re-gates at merge time and is AUTHORITATIVE — that's the full-suite guarantee (unless a human has switched the project's HUMAN-only orchestration.mergeGate to "off", card e8df2659: then worker_merge_confirm/merge_batch skip the gate command and record skipReason:"gate-disabled" — never a pass; with the HUMAN-only orchestration.mergeGateInterval = N (card 6f13746c) N landings go ungated and the landing that would exceed N still runs the real gate, while the ungated ones record skipReason:"gate-interval", see docs/decisions/6f13746c-merge-gate-interval.md — while the conflict/dirty-tree refusals and squash checks still run). "Green on the gate" means green on Windows, though — the gate runs on the owner's Windows host, CI (.github/workflows/ci.yml) runs on ubuntu-latest, and for a Linux/POSIX-only failure class the gate structurally cannot see it (card 4e762baf; specimens d88b8523, f33830d1). docs/releasing.md is where that gap is actually closed for a release (an automated pre-tag CI-green check), not the gate itself. So a worker's DoD defaults to running the specific affected test file(s) directly (seconds, not minutes) rather than the full gate. Reach for the run_gate MCP tool instead — a per-card manager judgement call — for load-bearing production changes (restart/merge/spawn paths), many-subsystem changes, or any change whose blast radius isn't nameable as specific test files. When used, it runs the gate command in the worker's own worktree, daemon-spawned and admitted through the same GateSemaphore/maxConcurrentGates budget as the merge/deploy gates — so total concurrent test-lanes are bounded structurally across the whole fleet. run_gate's own tool description is the contract — read it there, not here. Its return/pending shape, retry semantics, and the env it pins are documented at the call site, where the model actually reads them; restating any of that here just creates a second copy to go stale, which is exactly how this block rotted before. Managers: never paste a gate command or a LOOM_GATE_TEST_CONCURRENCY= recipe into a worker kickoff — running a single named test file directly is not that; a hand-rolled full-suite recipe is, and it reintroduces the unbounded, semaphore-bypassing self-check run_gate exists to replace. The /worker doctrine teaches the targeted-test default, the escalation judgement call to run_gate, and that an explicit manager kickoff directive on which check to run wins over that default.