From c7c5d3731c241d7a06a5965f9538220a1fe4f5b1 Mon Sep 17 00:00:00 2001 From: Drew Stone Date: Fri, 4 Sep 2026 00:32:40 -0700 Subject: [PATCH 1/5] docs(supervise): teach durable recursive profiles --- skills/supervise/SKILL.md | 101 ++++++++++++++++++++++++++++---------- 1 file changed, 75 insertions(+), 26 deletions(-) diff --git a/skills/supervise/SKILL.md b/skills/supervise/SKILL.md index 4ca2dabd..14038153 100644 --- a/skills/supervise/SKILL.md +++ b/skills/supervise/SKILL.md @@ -1,43 +1,92 @@ --- name: supervise -description: Drive worker agents with explicit profiles, corrections, budgets, and checked delivery. +description: Author and drive recursive AgentProfiles with durable assignments, evidence, and recovery. --- # Supervise -Use this policy only when the running agent has the coordination tools, including `spawn_worker` and `await_event`. -The supervisor plans and checks work; workers produce the artifacts. +Use this when Runtime coordination tools are attached. +Author agents that can perform the work, then drive them from checked evidence. -## Run The Work +## Keep policy in its owner -1. Split the job into independent deliverables with observable completion checks. -2. Call `spawn_worker` with a focused task and a complete worker profile. -3. Assign each worker only the tools, context, authority, and budget it needs. -4. Use `await_event` to collect questions, findings, progress, and settlements. -5. Answer blocking questions or steer the responsible worker with specific evidence. -6. When work fails, change the task, profile, evidence, or approach before spawning a replacement. -7. Accept only a settlement whose declared check passed and whose artifact can be inspected. -8. Stop when every required deliverable is accepted or a named limit or blocker is reached. +Put research choices, methods, revision rules, and scientific stopping conditions in each profile's prompt. +Runtime owns recursion depth, the shared budget, cancellation, concurrency, journals, retries, and recovery. -A worker profile names its role, task, relevant skills or system instructions, model constraints, tools, budget, expected artifact, and completion check. -Do not spawn empty profiles or blind retries. +`AgentProfile` has no `policy`, `budget`, `continuity`, `key`, or `deliverable` field. +Pass budget, continuity, and assignment keys to `spawn_worker`. +The caller configures the root budget and completion check in `SuperviseOptions`. +Do not claim a limit is enforced because it appears in prompt text or metadata. -## Parallel And Recursive Work +## Author a descendant -Run independent workers concurrently when their state and side effects are isolated. -Use one worktree per repository-writing worker. -Give external writes stable idempotency keys. +Write a valid `AgentProfile`, not a prose description of one. +Use only fields the selected backend can materialize. -A worker may itself supervise only when its profile includes this policy and the runtime grants coordination tools. -Child workers inherit stricter authority and budget limits than their parent. +```json +{ + "name": "source-skeptic-v1", + "description": "Challenge one candidate claim against primary evidence.", + "prompt": { + "appendSystemPrompt": "Return a claim table with source locations, contradictions, unknowns, and a reproducible rejection check." + }, + "model": { + "default": "", + "reasoningEffort": "xhigh" + }, + "metadata": { + "role": "driver" + } +} +``` -## Completion +The example shows placement, not required values. +Use `metadata.role: 'driver'` only when this child should author and supervise descendants. +Omit that role for a leaf. -Report worker IDs, assignments, accepted artifacts, failed or cancelled work, spend, unresolved questions, and the exact checks run. -The supervisor cannot turn an unchecked worker claim into completion. +The task argument names the concrete artifact and a check that can fail. +The profile names how the agent works and which capabilities it receives. +Together they must leave no acceptance criterion for the worker to invent. + +## Drive the tree + +1. Split the objective into independent checked artifacts. +2. Start each new assignment with a stable semantic `key` and a deliberate per-spawn `budget`. +3. Fill available parallel capacity while `freeSlots > 0` and distinct useful assignments remain. +4. Pull settlements and findings with `await_event`. + A bounded wait returns control; it does not prove failure. +5. Inspect a quiet or `stalled` worker with `observe_agent`. + Steer only when its recorded work shows a wrong path, missing requirement, or useful new evidence. +6. Check every settled artifact before using it. + Feed accepted results, contradictions, and negative results into the next profile or task revision. +7. After a refusal or failed check, preserve the attempt and author a materially changed profile or assignment. +8. Use `continuity: 'resume'` only to continue the most recent settled worker with the same profile name. + A resume is a new execution and cannot carry a run-once `key`. +9. After recovery, call `read_journal` and reconcile Runtime's restored roster, settlements, questions, findings, and spend before spawning. + Completed keys resolve to their committed results; do not replace them. + +Do not add a deadline because a worker is quiet. +Stop research only at checked success, a declared resource limit, cancellation, or a demonstrated dead end. + +## Accept delivery + +Inspect the artifact and its independent completion result. +Preserve exact profile identities, assignment keys, parent-child links, continuations, costs, failures, and unknown accounting. +Worker prose cannot promote its own result. + +Use `submit_result` only when the attached completion check can validate the root's own artifact. +Calling `stop` ends coordination; it does not turn missing evidence into success. + +## Exact contracts + +When a field is unclear, read the owner instead of inventing it: + +- [`AgentProfile`](https://github.com/tangle-network/agent-sdk/blob/main/packages/agent-interface/src/agent-profile.ts) and its [exact schema](https://github.com/tangle-network/agent-sdk/blob/main/packages/agent-interface/src/profile-schema.ts) own authored fields. +- [`spawn_worker` tool schema](https://github.com/tangle-network/agent-runtime/blob/main/src/mcp/tools/coordination.ts) owns per-assignment arguments. +- [`SuperviseOptions`](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime/supervise/supervise.ts) owns root execution policy. ## Then consider -- `build-with-agent-runtime` when this policy should become a reusable product integration. -- `eval-engineering` when worker acceptance needs a new executable case. -- `verify` after the accepted artifacts are assembled. +- `build-with-agent-runtime` when a product must configure the Runtime-owned limits and adapters. +- `eval-engineering` when no existing check can separate success from failure. +- `verify` after every required artifact passes its independent check. From ddaa4ecce91d9a991df6777291d2bc0b62bbf90c Mon Sep 17 00:00:00 2001 From: Drew Stone Date: Fri, 4 Sep 2026 03:11:25 -0700 Subject: [PATCH 2/5] docs(supervise): require exact execution identity --- skills/supervise/SKILL.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/skills/supervise/SKILL.md b/skills/supervise/SKILL.md index 14038153..503cd6ee 100644 --- a/skills/supervise/SKILL.md +++ b/skills/supervise/SKILL.md @@ -27,11 +27,13 @@ Use only fields the selected backend can materialize. { "name": "source-skeptic-v1", "description": "Challenge one candidate claim against primary evidence.", + "harness": "codex", "prompt": { "appendSystemPrompt": "Return a claim table with source locations, contradictions, unknowns, and a reproducible rejection check." }, "model": { - "default": "", + "provider": "openai", + "default": "gpt-5.6-sol", "reasoningEffort": "xhigh" }, "metadata": { From 3d1aaa8feaca2b0005c7cd0f2ab49924b757f5f5 Mon Sep 17 00:00:00 2001 From: Drew Stone Date: Fri, 4 Sep 2026 03:12:48 -0700 Subject: [PATCH 3/5] docs(supervise): format exact profile example --- skills/supervise/SKILL.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/skills/supervise/SKILL.md b/skills/supervise/SKILL.md index c57e613e..503cd6ee 100644 --- a/skills/supervise/SKILL.md +++ b/skills/supervise/SKILL.md @@ -32,8 +32,8 @@ Use only fields the selected backend can materialize. "appendSystemPrompt": "Return a claim table with source locations, contradictions, unknowns, and a reproducible rejection check." }, "model": { - "provider": "openai", - "default": "gpt-5.6-sol", + "provider": "openai", + "default": "gpt-5.6-sol", "reasoningEffort": "xhigh" }, "metadata": { From 1c3e1bd144508e7672db181fdb1d85692b27d70f Mon Sep 17 00:00:00 2001 From: Drew Stone Date: Fri, 4 Sep 2026 13:57:29 -0700 Subject: [PATCH 4/5] docs(supervise): make spawn authority profile-owned --- skills/supervise/SKILL.md | 22 ++++++++++++++++++---- tests/kernel/skill-tool-names.test.ts | 15 +++++++++++++++ 2 files changed, 33 insertions(+), 4 deletions(-) diff --git a/skills/supervise/SKILL.md b/skills/supervise/SKILL.md index 503cd6ee..72bb13c1 100644 --- a/skills/supervise/SKILL.md +++ b/skills/supervise/SKILL.md @@ -36,15 +36,29 @@ Use only fields the selected backend can materialize. "default": "gpt-5.6-sol", "reasoningEffort": "xhigh" }, - "metadata": { - "role": "driver" + "tools": { + "agent_runtime_coordination_spawn_worker": true + }, + "resources": { + "failOnError": true, + "skills": [ + { + "kind": "inline", + "name": "profile-authoring", + "content": "" + } + ] } } ``` The example shows placement, not required values. -Use `metadata.role: 'driver'` only when this child should author and supervise descendants. -Omit that role for a leaf. +Replace the example skill content with the exact bytes the parent received. +Declare `tools.agent_runtime_coordination_spawn_worker: true` only when this child can create descendants. +That declaration is the recursion signal; names, descriptions, prompts, and metadata never grant authority. +Every profile with spawn authority must carry the complete authoring skill in `resources.skills`. +Also declare every other coordination or work tool the child needs by its visible name. +Omit spawn authority and the authoring skill for an ordinary leaf. The task argument names the concrete artifact and a check that can fail. The profile names how the agent works and which capabilities it receives. diff --git a/tests/kernel/skill-tool-names.test.ts b/tests/kernel/skill-tool-names.test.ts index 0270d81f..aad0b7ef 100644 --- a/tests/kernel/skill-tool-names.test.ts +++ b/tests/kernel/skill-tool-names.test.ts @@ -74,3 +74,18 @@ describe('shipped skills name no harness-native tool', () => { ).toEqual([]) }) }) + +describe('supervise skill recursive authority', () => { + const supervise = readFileSync(join(skillsRoot, 'supervise', 'SKILL.md'), 'utf8') + + it('teaches the profile-owned spawn signal and complete skill propagation', () => { + expect(supervise).toContain('tools.agent_runtime_coordination_spawn_worker: true') + expect(supervise).toContain('Every profile with spawn authority must carry the complete authoring skill') + expect(supervise).toContain('"name": "profile-authoring"') + expect(supervise).toContain('"failOnError": true') + }) + + it('does not grant recursion through role metadata', () => { + expect(supervise).not.toMatch(/metadata\.role|role\s*:\s*['"]driver['"]|"role"\s*:\s*"driver"/) + }) +}) From eacc7dcdb6d5d42c1caa3cc800b8ddea053f1cd9 Mon Sep 17 00:00:00 2001 From: Drew Stone Date: Fri, 4 Sep 2026 14:17:22 -0700 Subject: [PATCH 5/5] chore(supervise): format recursive skill test --- tests/kernel/skill-tool-names.test.ts | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/tests/kernel/skill-tool-names.test.ts b/tests/kernel/skill-tool-names.test.ts index aad0b7ef..c0e0d95c 100644 --- a/tests/kernel/skill-tool-names.test.ts +++ b/tests/kernel/skill-tool-names.test.ts @@ -80,7 +80,9 @@ describe('supervise skill recursive authority', () => { it('teaches the profile-owned spawn signal and complete skill propagation', () => { expect(supervise).toContain('tools.agent_runtime_coordination_spawn_worker: true') - expect(supervise).toContain('Every profile with spawn authority must carry the complete authoring skill') + expect(supervise).toContain( + 'Every profile with spawn authority must carry the complete authoring skill', + ) expect(supervise).toContain('"name": "profile-authoring"') expect(supervise).toContain('"failOnError": true') })