From 813e1c6fa4d9c170b1e8f748347cb3bb6e3c97e4 Mon Sep 17 00:00:00 2001
From: NanoClaw User <nanoclaw@local>
Date: Wed, 25 Mar 2026 22:05:29 +0000
Subject: [PATCH] fix: improve task scripts agent instructions
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Reword Task Scripts opening in main template to guide agents toward
schedule_task instead of inline bash loops. Add missing Task Scripts
section to global template — non-main groups have unrestricted access
to schedule_task with script parameter, so omitting instructions just
leads to worse patterns.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 groups/global/CLAUDE.md | 39 +++++++++++++++++++++++++++++++++++++++
 groups/main/CLAUDE.md   |  2 +-
 2 files changed, 40 insertions(+), 1 deletion(-)

diff --git a/groups/global/CLAUDE.md b/groups/global/CLAUDE.md
index c814e39..7018c04 100644
--- a/groups/global/CLAUDE.md
+++ b/groups/global/CLAUDE.md
@@ -74,3 +74,42 @@ No `##` headings. No `[links](url)`. No `**double stars**`.
 ### Discord channels (folder starts with `discord_`)
 
 Standard Markdown works: `**bold**`, `*italic*`, `[links](url)`, `# headings`.
+
+---
+
+## Task Scripts
+
+To check or monitor something on a recurring basis, use `schedule_task` — not a bash loop. This way the check survives container restarts and doesn't block other messages. If the user only needs to know when a condition changes, add a `script` to avoid unnecessary wake-ups — the script runs first, and you only wake up when there's something to act on.
+
+### How it works
+
+1. You provide a bash `script` alongside the `prompt` when scheduling
+2. When the task fires, the script runs first (30-second timeout)
+3. Script prints JSON to stdout: `{ "wakeAgent": true/false, "data": {...} }`
+4. If `wakeAgent: false` — nothing happens, task waits for next run
+5. If `wakeAgent: true` — you wake up and receive the script's data + prompt
+
+### Always test your script first
+
+Before scheduling, run the script in your sandbox to verify it works:
+
+```bash
+bash -c 'node --input-type=module -e "
+  const r = await fetch(\"https://api.github.com/repos/owner/repo/pulls?state=open\");
+  const prs = await r.json();
+  console.log(JSON.stringify({ wakeAgent: prs.length > 0, data: prs.slice(0, 5) }));
+"'
+```
+
+### When NOT to use scripts
+
+If a task requires your judgment every time (daily briefings, reminders, reports), skip the script — just use a regular prompt.
+
+### Frequent task guidance
+
+If a user wants tasks running more than ~2x daily and a script can't reduce agent wake-ups:
+
+- Explain that each wake-up uses API credits and risks rate limits
+- Suggest restructuring with a script that checks the condition first
+- If the user needs an LLM to evaluate data, suggest using an API key with direct Anthropic API calls inside the script
+- Help the user find the minimum viable frequency
diff --git a/groups/main/CLAUDE.md b/groups/main/CLAUDE.md
index 6080427..5e693fa 100644
--- a/groups/main/CLAUDE.md
+++ b/groups/main/CLAUDE.md
@@ -267,7 +267,7 @@ The task will run in that group's context with access to their files and memory.
 
 ## Task Scripts
 
-When scheduling tasks that check a condition before acting (new PRs, website changes, API status), use the `script` parameter. The script runs first — if there's nothing to do, you don't wake up.
+To check or monitor something on a recurring basis, use `schedule_task` — not a bash loop. This way the check survives container restarts and doesn't block other messages. If the user only needs to know when a condition changes, add a `script` to avoid unnecessary wake-ups — the script runs first, and you only wake up when there's something to act on.
 
 ### How it works