From b05fcad7a7d64c2ea03b95a4ca85b5f5f9c12b84 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Sat, 16 May 2026 11:02:04 +0100 Subject: [PATCH] docs: add Crabbox human handoff preflight --- .agents/skills/crabbox/SKILL.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/.agents/skills/crabbox/SKILL.md b/.agents/skills/crabbox/SKILL.md index 099b49161d34..cb272f75e2b7 100644 --- a/.agents/skills/crabbox/SKILL.md +++ b/.agents/skills/crabbox/SKILL.md @@ -378,6 +378,30 @@ browser/app inside the visible session, bridges the lease into the authenticated WebVNC portal, and opens the portal. Keep browsers windowed for human QA; use `--fullscreen` only for capture/video workflows. +Human handoff preflight: + +- Do not assume a visible desktop or launched browser means the repo CLI/app is + installed, built, or on the interactive terminal's `PATH`. +- Before handing WebVNC to a human tester, prove the expected command from the + same kept lease and from a neutral directory such as `~`. +- If the handoff needs repo-local code, sync/build/link it explicitly on that + lease. Source-tree CLIs often need build output before a symlink works. +- Prefer a real `command -v && --version` + check over a repo-root-only `pnpm ...` command. + +Generic handoff repair pattern: + +```sh +../crabbox/bin/crabbox run --id --full-resync --shell -- \ + "set -euo pipefail + pnpm install --frozen-lockfile + pnpm build + sudo ln -sf \"\$PWD/\" /usr/local/bin/ + cd ~ + command -v + --version" +``` + ## If Crabbox Fails Keep the fallback narrow. First decide whether the failure is Crabbox itself,