From 1d8b944461896c0dce5644c01e24c72bbfecd40d Mon Sep 17 00:00:00 2001 From: agentrelaybot Date: Thu, 19 Nov 2026 13:06:27 +0100 Subject: [PATCH] feat(agent-rules): stall-watching rule and the AgentWorkforce orchestration overlay Phase 3 of docs/specs/grok-bot-dynamic-prompt.md, stacked on Phase 2. Rules 2026.11.1. - sections/stall-watch.md (grok-bot, lead; base, decision D7): keep a list of delegated work; follow up on agents silent for 30 minutes, or 10 minutes after a spawn with no ack; route blockers; tell the person who owns the work without waiting to be asked; check even on runs with no new messages. One follow-up per agent per interval, one summary note per run. - overlays/agentworkforce-grok-bot.md: the reviewed AgentWorkforce grok-bot overlay (D7). Grok bots do no coding and no real decisions; all coding goes to Claude and Codex agents; they only spawn, route and relay; problems are surfaced to Khaliq. Not part of the base bundle: it takes effect only when an organization admin PUTs it, which on production needs Khaliq's OK. - No automatic heartbeat routine (D6, conservative): docs note that quiet periods need an opt-in scheduled routine. Co-Authored-By: Claude Opus 5.5 --- agent-rules/CHANGELOG.md | 12 ++++++++ agent-rules/manifest.json | 13 ++++++-- .../overlays/agentworkforce-grok-bot.md | 16 ++++++++++ agent-rules/sections/stall-watch.md | 19 ++++++++++++ docs/agent-rules.md | 30 +++++++++++++++++++ test/agent-rules.test.ts | 26 ++++++++++++++-- 6 files changed, 112 insertions(+), 4 deletions(-) create mode 100644 agent-rules/overlays/agentworkforce-grok-bot.md create mode 100644 agent-rules/sections/stall-watch.md diff --git a/agent-rules/CHANGELOG.md b/agent-rules/CHANGELOG.md index 6051902d..a994c550 100644 --- a/agent-rules/CHANGELOG.md +++ b/agent-rules/CHANGELOG.md @@ -4,6 +4,18 @@ Each version is immutable. Bump `version` in `manifest.json` (CalVer `YYYY.MM.N`) and add an entry here in the same PR as any section change; `test/agent-rules.test.ts` fails otherwise. +## 2026.11.1 + +- Adds `stall-watch` for `grok-bot` and `lead`: track delegated work, follow + up on agents that have not reported (30 minutes since the last message, 10 + minutes after a spawn with no acknowledgement), route blockers, and tell the + person who owns the work without waiting to be asked. Runs with no new + messages still do the check (docs/specs/grok-bot-dynamic-prompt.md, Phase 3). +- `overlays/agentworkforce-grok-bot.md` is the reviewed text for the + AgentWorkforce organization's `grok-bot` overlay (orchestration only; + escalate to Khaliq). It is not part of the base bundle and takes effect only + once an organization admin PUTs it (docs/agent-rules.md). + ## 2026.11.0 - First bundle (docs/specs/grok-bot-dynamic-prompt.md, Phase 2). diff --git a/agent-rules/manifest.json b/agent-rules/manifest.json index 2f731d4d..6800f8f6 100644 --- a/agent-rules/manifest.json +++ b/agent-rules/manifest.json @@ -1,5 +1,5 @@ { - "version": "2026.11.0", + "version": "2026.11.1", "bootstrap_version": 1, "sources": { "grok-inbox": "Cloud packages/web/lib/mcp-events/grok-routine.ts grokRoutinePrompt @ 84578009505b (rendered per grant)", @@ -58,7 +58,16 @@ "audiences": [ "lead" ] + }, + { + "id": "stall-watch", + "title": "Watch in-flight work", + "file": "sections/stall-watch.md", + "audiences": [ + "grok-bot", + "lead" + ] } ], - "sections_sha256": "1dd2891d795177f33da7c51b5e5d987101617441ead332a1f496f680b78db5d2" + "sections_sha256": "6c055e7c06e4e110a4935b81ec4a0dae3efdca700fff255e7a84a0d1a808fb38" } diff --git a/agent-rules/overlays/agentworkforce-grok-bot.md b/agent-rules/overlays/agentworkforce-grok-bot.md new file mode 100644 index 00000000..88054cfe --- /dev/null +++ b/agent-rules/overlays/agentworkforce-grok-bot.md @@ -0,0 +1,16 @@ +You orchestrate; you do not code or decide. Do no coding work yourself: do +not edit files, write patches, run builds or tests, or give the final word on +a code review. Send all coding work to Claude or Codex coding agents. Spawn +them with spawn_relay_agent on a target that has the repo, or hand the work to +an existing agent after reading its card. + +Make no real decisions. That means no choosing between designs, approving, +merging, deploying, labelling, or deciding scope or priority. Put the options, +and the agents' recommendations, in front of the person and let them decide. + +Your job is to spawn agents, route work to the right one, and relay results +and questions back. Never use a Cursor cloud agent for coding unless Relay +spawning is unavailable for one of the listed reasons and the person agreed. + +Surface problems to Khaliq (khaliq-gant on Agent Relay) directly, as the +stall-watching rules describe. diff --git a/agent-rules/sections/stall-watch.md b/agent-rules/sections/stall-watch.md new file mode 100644 index 00000000..98199b64 --- /dev/null +++ b/agent-rules/sections/stall-watch.md @@ -0,0 +1,19 @@ +Watch in-flight work so nothing stalls. Keep a list in this conversation of +every task you delegated: the agent, the repo, what done means, and when you +last heard from it. On every run, before you go idle: + +- Check each in-flight task. If an agent has not reported within its expected + time, follow up with send_relay_message. The default is 30 minutes since its + last message, or 10 minutes after a spawn with no acknowledgement. Use + get_relay_spawn_status, list_relay_agents and list_team_activity to see + whether it is still alive. +- If an agent is blocked, find out on what, and route the blocker to whoever + can clear it. +- Tell the person who owns this work, without waiting to be asked, when: + - an agent is gone, has failed, or is still silent after one follow-up; + - anything is blocked on a decision, a credential, an approval or an + outage. + Say what is stuck, since when, what you tried and what you need. +- Do not spam: send at most one follow-up per agent per interval, and post one + summary note per run. +- A run with no new messages still does this check. diff --git a/docs/agent-rules.md b/docs/agent-rules.md index 02ddb9b7..0d2b8d80 100644 --- a/docs/agent-rules.md +++ b/docs/agent-rules.md @@ -79,3 +79,33 @@ The `lead` audience carries layered-agents `kit/delegation.md` and `kit/orchestration.md`, copied as is. Having `kit/lead-run.sh` fetch it (`GET /api/v1/agent-rules/lead`, falling back to a pinned snapshot) is a change for the layered-agents owner; this repository only serves it. + +## Orchestration and stall-watching rules + +These rules come from Phase 3 of the spec. Decision D7 split them as +follows: + +- **Stall watching** is the base section `stall-watch`, for the `grok-bot` + and `lead` audiences, so every tenant gets it. A bot keeps a list of the + work it has delegated and follows up on agents that have not reported: after + 30 minutes since the last message, or 10 minutes after a spawn with no + acknowledgement. It routes blockers, and it tells the person who owns the + work without waiting to be asked. A run with no new messages still does the + check. A webhook routine only runs when a message arrives, so a bot that + must catch stalls in quiet periods also needs a scheduled routine. That is + opt-in and is not created automatically (decision D6). +- **Orchestration only** ("Grok bots do no coding or real decision-making; + coding goes to Claude and Codex agents; they spawn, route and relay") is + AgentWorkforce policy, not a default for every tenant. Its reviewed text, + including escalation to Khaliq, is + `agent-rules/overlays/agentworkforce-grok-bot.md`. It takes effect only once + an AgentWorkforce organization owner or admin applies it: + + ```sh + jq -Rs '{text: .}' agent-rules/overlays/agentworkforce-grok-bot.md | + curl -sS -X PUT "$SELFHOST_PUBLIC_URL/api/v1/organizations/$ORG_ID/agent-rules/grok-bot" \ + -H "Authorization: Bearer $OWNER_OR_ADMIN_TOKEN" -H 'Content-Type: application/json' --data-binary @- + ``` + + Applying it on a production deployment is a production change and needs + Khaliq's OK. diff --git a/test/agent-rules.test.ts b/test/agent-rules.test.ts index c3c10305..eca48147 100644 --- a/test/agent-rules.test.ts +++ b/test/agent-rules.test.ts @@ -35,12 +35,12 @@ test("the committed bundle is pinned: a section change needs a new sha, version test("composition filters by audience, keeps safety first, appends the overlay and versions it", () => { const bundle = loadAgentRules(); const lead = composeAgentRules(bundle, "lead", null); - assert.deepEqual(lead.sections.map(section => section.id), ["safety", "lead-delegation", "lead-orchestration"]); + assert.deepEqual(lead.sections.map(section => section.id), ["safety", "lead-delegation", "lead-orchestration", "stall-watch"]); assert.equal(lead.version, bundle.version); assert.match(lead.text, /## Orchestrate; don't implement serially/); const procedure = grokRoutinePrompt("fake-grok", { canReply: true }); const grok = composeAgentRules(bundle, "grok-bot", { version: 3, text: "Escalate to the owner." }, { grokRoutinePrompt: procedure }); - assert.deepEqual(grok.sections.map(section => section.id), ["safety", "grok-inbox", "grok-delegation", "show-ui", "organization"]); + assert.deepEqual(grok.sections.map(section => section.id), ["safety", "grok-inbox", "grok-delegation", "show-ui", "stall-watch", "organization"]); assert.equal(grok.version, `${bundle.version}+org.3`); assert.ok(grok.text.includes(procedure), "grok-inbox is the grant's copied routine procedure"); assert.ok(grok.text.indexOf("## Safety") < grok.text.indexOf("## Organization rules")); @@ -129,3 +129,25 @@ test("HTTP: members read composed rules with ETag and markdown; only admins writ assert.equal((await fetch(`${f.base}/api/v1/organizations/${other}/agent-rules/grok-bot`, { headers: headers(owner) })).status, 404); assert.equal((await (await put(owner, "")).json() as any).cleared, true); }); + +test("Phase 3: stall watching reaches Grok bots and leads; the AgentWorkforce overlay text is lint-clean and adds the orchestration rule", () => { + const bundle = loadAgentRules(); + for (const audience of ["grok-bot", "lead"] as const) { + const text = composeAgentRules(bundle, audience, null).text; + assert.match(text, /## Watch in-flight work/); + assert.match(text, /follow up with send_relay_message/); + assert.match(text, /without waiting to be asked/); + assert.match(text, /A run with no new messages still does this check\./); + } + assert.doesNotMatch(composeAgentRules(bundle, "worker", null).text, /Watch in-flight work/); + for (const file of readdirSync(resolve(directory, "overlays"))) { + const text = readFileSync(resolve(directory, "overlays", file), "utf8"); + assert.equal(rulesTextProblem(text.trim()), null, `${file} fails the overlay lint`); + } + const overlay = readFileSync(resolve(directory, "overlays", "agentworkforce-grok-bot.md"), "utf8"); + const grok = composeAgentRules(bundle, "grok-bot", { version: 1, text: overlay }); + assert.match(grok.text, /## Organization rules\n\nYou orchestrate; you do not code or decide\./); + assert.match(grok.text, /Send all coding work to Claude or Codex coding agents\./); + assert.match(grok.text, /Surface problems to Khaliq \(khaliq-gant on Agent Relay\) directly/); + assert.ok(grok.text.indexOf("## Watch in-flight work") < grok.text.indexOf("## Organization rules")); +});