Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions agent-rules/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down
13 changes: 11 additions & 2 deletions agent-rules/manifest.json
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
{
"version": "2026.11.0",
"version": "2026.11.1",
"bootstrap_version": 1,
"sources": {
"grok-inbox": "Agent Relay Cloud's Grok routine prompt, copied in Phase 1 (rendered per grant)",
Expand Down Expand Up @@ -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"
}
16 changes: 16 additions & 0 deletions agent-rules/overlays/agentworkforce-grok-bot.md
Original file line number Diff line number Diff line change
@@ -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.
19 changes: 19 additions & 0 deletions agent-rules/sections/stall-watch.md
Original file line number Diff line number Diff line change
@@ -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.
30 changes: 30 additions & 0 deletions docs/agent-rules.md
Original file line number Diff line number Diff line change
Expand Up @@ -79,3 +79,33 @@ The `lead` audience carries the layered lead kit's delegation and
orchestration guidance, copied as is. Having the layered lead start-up script
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.
26 changes: 24 additions & 2 deletions test/agent-rules.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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"));
Expand Down Expand Up @@ -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"));
});
Loading