diff --git a/biome.json b/biome.json
index a85ba22..c0924b2 100644
--- a/biome.json
+++ b/biome.json
@@ -1,7 +1,13 @@
 {
   "$schema": "https://biomejs.dev/schemas/2.4.15/schema.json",
   "files": {
-    "includes": ["**", "!**/dist", "!**/node_modules", "!packages/workflow/workflow"]
+    "includes": [
+      "**",
+      "!**/dist",
+      "!**/node_modules",
+      "!packages/workflow/workflow",
+      "!xiaoju/scripts/bundle.ts"
+    ]
   },
   "assist": { "actions": { "source": { "organizeImports": "on" } } },
   "formatter": {
diff --git a/packages/cli-workflow/src/skill.ts b/packages/cli-workflow/src/skill.ts
index 06ea030..471066f 100644
--- a/packages/cli-workflow/src/skill.ts
+++ b/packages/cli-workflow/src/skill.ts
@@ -301,6 +301,26 @@ function createLazyAdapter(): AdapterFn {
 }
 \`\`\`
 
+### Agent CLI paths: use optionalEnv with defaults
+
+When binding agent adapters (cursor-agent, hermes, etc.), **always use \`optionalEnv\` with a sensible default** — never \`requireEnv\`. The worker process may start without the expected env vars, causing a silent crash.
+
+Discover the correct CLI path yourself (e.g. \`which cursor-agent\`, \`which hermes\`) and use it as the fallback:
+
+\`\`\`typescript
+// ❌ WRONG — worker crash if env var missing, thread silently fails with 0 steps
+const adapter = createCursorAgent({
+  command: requireEnv("WORKFLOW_CURSOR_COMMAND", "set it"),
+  ...
+});
+
+// ✅ CORRECT — env override with discovered default
+const adapter = createCursorAgent({
+  command: optionalEnv("WORKFLOW_CURSOR_COMMAND") ?? "cursor-agent",
+  ...
+});
+\`\`\`
+
 ### Bundle import restrictions
 
 The bundle validator only allows these import specifiers:
diff --git a/packages/workflow-template-develop/bundle-entry.ts b/packages/workflow-template-develop/bundle-entry.ts
index fd79fd6..c7e0612 100644
--- a/packages/workflow-template-develop/bundle-entry.ts
+++ b/packages/workflow-template-develop/bundle-entry.ts
@@ -7,11 +7,11 @@
 import { createCursorAgent } from "@uncaged/workflow-agent-cursor";
 import { createHermesAgent } from "@uncaged/workflow-agent-hermes";
 import { createWorkflow } from "@uncaged/workflow-runtime";
-import { optionalEnv, requireEnv } from "@uncaged/workflow-util";
+import { optionalEnv } from "@uncaged/workflow-util";
 import { buildDevelopDescriptor, developWorkflowDefinition } from "./src/index.js";
 
 const cursorAdapter = createCursorAgent({
-  command: requireEnv("WORKFLOW_CURSOR_COMMAND", "set WORKFLOW_CURSOR_COMMAND (e.g. cursor-agent)"),
+  command: optionalEnv("WORKFLOW_CURSOR_COMMAND") ?? "cursor-agent",
   model: optionalEnv("WORKFLOW_CURSOR_MODEL"),
   timeout: optionalEnv("WORKFLOW_CURSOR_TIMEOUT")
     ? Number(optionalEnv("WORKFLOW_CURSOR_TIMEOUT"))
@@ -20,7 +20,7 @@ const cursorAdapter = createCursorAgent({
 });
 
 const hermesAdapter = createHermesAgent({
-  command: requireEnv("WORKFLOW_HERMES_COMMAND", "set WORKFLOW_HERMES_COMMAND (absolute path to hermes CLI)"),
+  command: optionalEnv("WORKFLOW_HERMES_COMMAND") ?? "hermes",
   model: optionalEnv("WORKFLOW_HERMES_MODEL"),
   timeout: optionalEnv("WORKFLOW_HERMES_TIMEOUT")
     ? Number(optionalEnv("WORKFLOW_HERMES_TIMEOUT"))