@tangle-network/agent-runtime 0.194.0 → 0.195.0

package/skills/build-with-agent-runtime/SKILL.md

@@ -1,136 +1,50 @@
 ---
 name: build-with-agent-runtime
-description: Choose and compose current runtime, eval, knowledge, and interface APIs before adding wrappers.
+description: Choose maintained runtime APIs and compose execution, evaluation, and controlled improvement.
 ---
 
-# Build with agent-runtime
+# Build with Agent Runtime
 
-Use this skill before writing product-local agent infrastructure.
-The goal is one portable agent definition, one execution path, one measurement system, and one reviewed activation path.
+Build on the maintained execution path while keeping product policy and storage in the consumer.
+Read the current [API decision table](https://github.com/tangle-network/agent-runtime/blob/main/docs/canonical-api.md) and [package exports](https://github.com/tangle-network/agent-runtime/blob/main/package.json).
+Follow the chosen entrypoint to its implementation and nearest runnable example.
+For an existing consumer, confirm the actual installed package supports the chosen contract.
 
-## Read first
+## Choose by the required outcome
 
-1. Read `docs/canonical-api.md` for the current decision table.
-2. Check exports in `src/index.ts`, `src/runtime/index.ts`, `src/improvement/index.ts`, `src/intelligence/index.ts`, and `src/knowledge/index.ts`.
-3. Read the nearest runnable example.
-4. Treat source as authoritative when docs disagree, then correct the stale doc in the same change.
-
-## Ownership
+Use the existing entrypoint for one turn, a bounded task, fixed composition, dynamic supervision, or a measured improvement.
+Avoid copying the API catalog into product code or creating a wrapper that only renames it.
 
 | Concern | Owner |
 |---|---|
-| Portable prompt, skills, tools, MCP, hooks, subagents, model hints | `AgentProfile` from `@tangle-network/agent-interface` |
-| Agent execution, supervision, budgets, streaming, candidate execution | `@tangle-network/agent-runtime` |
-| Tasks, graders, search, paired statistics, cost and latency comparison | `@tangle-network/agent-eval` |
-| Sources, retrieval, citations, freshness, memory adapters, knowledge promotion | `@tangle-network/agent-knowledge` |
-| Product records, permissions, funding, UI, and atomic storage writes | The consuming product |
-
-Do not move shared measurement into Runtime or product code.
-Do not move product storage transactions into a provider-neutral package.
-
-## Choose the entry point
-
-| Need | Use |
-|---|---|
-| One product chat turn | `handleChatTurn(...)` |
-| One normalized streamed agent turn | `streamAgentTurn(...)` and `collectAgentTurn(...)` |
-| One task or multi-turn loop | `runAgentTask(...)`, `runAgentTaskStream(...)`, or `runAgentRounds(...)` |
-| Supervisor and workers | `supervise(...)` or `superviseSurface(...)` |
-| Static roles with versioned delegation and analysis directives | `runGraph(...)` |
-| Parallel work with a shared budget | `fanout(...)` |
-| Fixed composition | `pipeline(...)`, `panel(...)`, or `verify(...)` |
-| Product benchmark | `defineLeaderboard(...)` |
-| Profile matrix | `expandProfileAxes(...)` and `runProfileMatrix(...)` from agent-eval |
-| Search one agent surface | `improve(...)` |
-| Analyze traces through a measured proposal | `proposeAgentImprovement(...)` |
-| Review and authorize an exact proposal | `reviewAgentImprovementProposal(...)` and `createAgentImprovementActivation(...)` |
-| Apply or restore an approved candidate | `executeAgentImprovementActivation(...)` with a product transaction |
-| Build a knowledge candidate | `runKnowledgeImprovementJob(...)` |
-| Apply a knowledge candidate | `createKnowledgeImprovementActivationExecutor(...)` through the same activation path |
-| Observe and pull approved changes on a live agent | `withIntelligence(...)` |
-
-## Improvement flow
-
-`improve(profile, options)` searches one surface and returns a detached winner.
-It never changes a profile, document, repository, memory store, or knowledge base.
-
-For a profile field, pass one complete agent-eval `OptimizationMethod`, explicit train, selection, and final-test partitions, judges, and the candidate execution function.
-Use `officialGepa(...)` with an explicit recipe when upstream GEPA should own search.
-Use `officialSkillOpt(...)` when Microsoft's SkillOpt should own search.
-Both require `evaluationId`; change it whenever dispatch, judges, models, or scoring behavior changes.
-Resumable runs accept `never`, `if-compatible`, or `required` and reuse state only when agent-eval derives the same run identity.
-Runtime has no local prompt, skill, memory, or profile optimizer fallback.
-Code uses Runtime's isolated worktrees and returns a sealed patch candidate.
-Knowledge uses `runKnowledgeImprovementJob(...)` and returns paired snapshots.
-
-Use `proposeAgentImprovement(...)` for a production proposal.
-It performs these steps in order:
-
-1. Analyze completed traces.
-2. Search for a candidate on development tasks.
-3. Build the frozen baseline, candidate, and held-back work.
-4. Return only baseline, candidate, held-back tasks, and policy; Runtime adds the optimizer ancestry and seals the final experiment.
-5. Reject the experiment if its candidate differs from the search winner.
-6. Run baseline and candidate on the same held-back tasks.
-7. Produce findings, confidence intervals, quality, cost, latency, and a decision.
-
-After a person or tenant policy approves the proposal, call `createAgentImprovementActivation(...)` with target identities, funding owner, authority, intent, and expiry.
-Runtime derives the expected current digests from the measured experiment.
-Call `executeAgentImprovementActivation(...)` with one product-owned transaction that compares current state, writes every target atomically, and stores the result under the activation digest.
-Pass a read-only reconciliation function so retries can distinguish committed, uncommitted, and uncertain outcomes.
-
-Never apply a change from analyst confidence alone.
-Never measure one candidate and apply another.
-Never let search code write live state.
-Never treat a lost response as a failed write without reconciling it.
-
-## Surface rules
-
-- Prompt changes `profile.prompt` only and requires a complete method.
-- Skill optimization selects one inline skill by `skills.resourceName`, requires a complete method, and requires profile resources to fail closed.
-- Curated memory changes `profile.resources.instructions`; retrieval stores and memory databases belong in the knowledge flow.
-- Tools, MCP, hooks, subagents, curated memory, rollout policy, and whole-profile changes require a complete method.
-- Code candidates must come from the Runtime worktree path so patch identity and cleanup stay intact.
-- Workflow files are code surfaces. Parameter sweeps belong in a complete agent-eval method.
-- Knowledge candidates remain detached until the shared activation path applies or restores their frozen snapshots.
-
-## Product integration
-
-The product supplies only the pieces that vary by deployment:
+| Portable prompt, skills, tools, MCP, hooks, and model hints | AgentProfile from agent-interface |
+| Execution, supervision, budgets, streaming, and candidate execution | Agent-runtime |
+| Cases, grading, search, statistics, and comparison | Agent-eval |
+| Retrieval, citations, freshness, memory stores, and knowledge promotion | Agent-knowledge |
+| Users, permissions, funding, UI, persistence, and atomic writes | The product |
 
-- How traces and current profiles are loaded.
-- How exact candidate execution is placed on compute.
-- How proposal, review, activation, and result records are persisted.
-- How a target is changed atomically.
-- Who may approve, reject, request changes, fund, apply, or restore.
-- How those records and actions appear in the UI or API.
+Keep measurement in Eval and product storage transactions in the consumer.
+Use the same agent definition and execution path in the product and its evaluation.
 
-The product must not recreate candidate hashing, paired comparison, confidence intervals, review binding, expiry, retry identity, or result validation.
+## Integrate the selected capability
 
-## Do not duplicate
+Search for the existing product adapter and current package usage before adding infrastructure.
+Supply only the policy, storage, credential, and execution-placement boundaries the consumer needs.
+Preserve explicit failures, cost and usage capture, cancellation, and recovery behavior.
 
-- Do not write a provider-specific profile wrapper; extend `AgentProfile` and its materializer.
-- Do not write a second optimizer loop; pass a complete agent-eval method to `improve(...)`.
-- Do not use Runtime's code generator to approximate GEPA, SkillOpt, or another upstream profile optimizer.
-- Do not write a second candidate catalog; persist the immutable proposal records.
-- Do not let an analyst or adapter commit, push, open a pull request, or edit a live store.
-- Do not hand-roll SSE parsing, usage totals, profile matrices, bootstrap statistics, sandbox acquisition, or worktree cleanup.
-- Do not attach completed Runtime totals to an Eval campaign. Use `loopDispatch` or `loopCampaignDispatch` so admission and receipt capture surround the paid work.
-- Do not add a product-local approval format for knowledge, code, or profile changes.
+When changing prompts, skills, code, or knowledge through measured search, read [improvement and activation](references/improvement.md) before implementing that path.
+Ordinary execution work does not need an optimizer or activation workflow.
 
-## Finish
+## Prove the integration
 
-- The same agent definition runs in product and measurement paths.
-- The held-back tasks were not visible during search.
-- Candidate identity is checked before execution and again before activation.
-- Quality, cost, latency, sample count, and uncertainty are retained.
-- Rejection and request-changes are first-class outcomes.
-- Activation is authorized, expiring, idempotent, and reconcilable.
-- No customer write, message, trigger, or billing occurs in read-only proof mode.
-- Public examples, package exports, generated API docs, type checks, tests, build, and package verification pass.
+Run a real task through the selected backend and inspect its result and execution evidence.
+Test the changed contract's denial, failure, cancellation, or recovery cases as applicable.
+An in-process test proves only its own path; it does not prove a deployed sandbox path.
+Run the repository's required checks, public-import checks when exports change, and the consumer's affected flow.
+Report retained product adapters, adopted exports, observable results, and unchecked boundaries.
 
 ## Then consider
 
-- Use `build-with-agent-knowledge` when agents should improve retrieval, memory, or a knowledge base.
-- Use `critical-audit` when the change introduces or alters a public contract.
-- Use `verify` before publishing or adopting the package in a product.
+- `build-with-agent-knowledge` when the remaining work concerns retrieval or memory integration.
+- `critical-audit` when a changed public contract needs independent review.
+- `verify` when implementation is complete and release checks remain.

package/skills/build-with-agent-runtime/references/improvement.md

@@ -0,0 +1,32 @@
+# Measured improvement and activation
+
+Read the current [improvement exports](https://github.com/tangle-network/agent-runtime/blob/main/src/improvement/index.ts), [intelligence exports](https://github.com/tangle-network/agent-runtime/blob/main/src/intelligence/index.ts), and relevant sections of the [API decision table](https://github.com/tangle-network/agent-runtime/blob/main/docs/canonical-api.md).
+For knowledge changes, also read the [knowledge exports](https://github.com/tangle-network/agent-runtime/blob/main/src/knowledge/index.ts).
+Use the selected function's current types and maintained example rather than copying a method signature from this guide.
+
+## Search without changing the live system
+
+Use the existing improvement API and a complete Eval optimization method for the chosen surface.
+Keep development, selection, and final decision cases separate.
+Record the delivered profile resources and execution identity so resumed work cannot silently reuse incompatible measurements.
+Search returns a detached candidate; it cannot edit the live product, knowledge store, or repository.
+
+Prompt, tool, resource, and profile changes remain portable profile data.
+Code candidates use Runtime's isolated worktree and patch identity path.
+Knowledge candidates use the existing snapshot and promotion contract.
+Do not rebuild candidate hashing, statistics, or search history in the consumer.
+
+## Apply only the measured candidate
+
+Use the maintained proposal, review, and activation path.
+The proposal must compare the unchanged baseline and exact candidate on tasks hidden during search.
+Keep candidate identity checked before execution and before activation.
+Retain quality, cost, latency, sample count, uncertainty, and rejected outcomes.
+
+The product supplies authority, funding, target identities, persistence, and an atomic transaction.
+That transaction compares expected current state, writes the authorized targets, and records the activation outcome under its retry identity.
+Use read-only reconciliation to distinguish committed, uncommitted, and uncertain outcomes after a lost response.
+Preserve expiry and authority checks; review evidence does not itself grant write authority.
+
+Prove rejection, successful activation, expired or mismatched activation, and retry after an uncertain write.
+A read-only experiment must not send customer messages, mutate customer data, or incur product billing side effects.

package/skills/codemode/SKILL.md

@@ -1,49 +1,37 @@
 ---
 name: codemode
-description: Batch mechanical tool work as one program so loops and intermediates stay out of context.
+description: Batch mechanical tool work in code while preserving judgment, authorization, and accounting.
 ---
 
 # Codemode
 
-Use this policy when a task needs three or more mechanical tool or command calls whose intermediate results need no judgment.
-One call per model turn spends a round trip per step and pushes every intermediate value through the context window.
-Write one program instead: the loop, the branch, and the intermediates stay in the program, and only the decision-relevant summary returns.
+Batch stretches of mechanical tool work whose intermediate results require no judgment.
+Keep decisions that could change the plan in the agent's turn.
 
-This is the pattern the ecosystem calls code mode (Cloudflare's Code Mode, Anthropic's code execution with MCP, the CodeAct paper).
-In a coding harness you already have the whole capability: a shell, a filesystem, and the tools this profile grants.
+## Batch the work
 
-## Run The Work
+Identify independent calls and the points where an observed result must change the next action.
+Use the session's permitted execution tool to hold intermediate data in variables or workspace files.
+Return the decision-relevant values, failures, and artifact locations.
+Inspect every result; a successful batch must not hide a failed item.
+Retain results needed later instead of rerunning expensive work to recover them.
 
-1. List the calls the task needs and mark which results require your judgment.
-2. Put every judgment-free stretch into one script; keep each judgment point in your own turn.
-3. Hold intermediates in variables or files inside the workspace, never in your reply.
-4. Make the script print only the decision-relevant summary: counts, failures, the final value.
-5. Prefer one script that fans out over N items to N separate tool calls with identical shape.
-6. Stop batching the moment a result changes what you would do next; read it, decide, then batch again.
+Respect each tool's concurrency, cancellation, and authorization contract.
+A batch does not expand the permission of its individual operations.
+Meter paid operations on the owning execution path and preserve their usage records.
+Keep dependent actions sequential unless their contract supports safe composition.
 
-## Boundaries That Are Not Yours To Move
+## Runtime-supervised code
 
-Code may spawn or steer only through Runtime-provided API bindings such as `api.spawn_worker`.
-Never reach coordination verbs over HTTP or create a second scheduler; that bypasses the budget pool and journal.
-An operation that costs money must run where the runtime meters it; do not wrap metered work in a script that hides the spend.
-The lint on authored code refuses imports, `process`, and network access; it is a lint, not a sandbox, so treat generated code you did not review as untrusted.
+When configuring code execution for a Runtime supervisor, read [the execution boundary](references/runtime-execution.md).
+That branch supplies a generated API over Runtime's existing coordination tools and requires an explicit runner.
+For ordinary shell or session-tool batching, no additional runtime is needed.
 
-## Router-Brained Supervisors
-
-A raw chat model has no shell, so give it the runtime's code mode: pass `codeModeSupervisorTools()` as `resolveSupervisorTools` and the supervisor's tool surface becomes `search` and `execute`.
-`search` answers a TypeScript API generated from the live coordination grant; `execute` runs the model's program through a caller-supplied runner, and every `api.spawn_worker` call crosses the kernel's pool, authorization, and journal.
-Supply a jailed runner for an untrusted model: the in-process runner is not an isolation boundary.
-The lifecycle verbs (`submit_result`, `stop`, `ask_parent`) stay model tools: the program does the mechanics, the model keeps the judgment.
-
-## Common Mistakes
-
-- Batching a step whose output should have changed your plan, then discovering it three steps later.
-- Printing a whole dataset into the reply instead of writing it to a file and printing the summary.
-- Re-running an expensive script to re-read a value the first run already produced; write results to files.
-- Moving supervision into a script because the coordination verbs are reachable over local HTTP.
+Complete the requested work and inspect the resulting artifact.
+Code reduces mechanical round trips; it does not replace judgment or prove the quality of the result.
 
 ## Then consider
 
-- `supervise` when the batched work is really delegation to workers with their own judgment.
-- `agent-graphs` when the shape of the work is a fixed topology rather than one agent's loop.
-- `loop-writer` when no shipped composition API can express the control policy you need.
+- `supervise` when the work needs workers with their own judgment.
+- `agent-graphs` when fixed roles require explicit Runtime relationships and shared accounting.
+- `loop-writer` when no maintained composition expresses the required control policy.

package/skills/codemode/references/runtime-execution.md

@@ -0,0 +1,14 @@
+# Runtime code execution boundary
+
+Read [code-mode implementation and types](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime/supervise/code-mode.ts) and its [contract tests](https://github.com/tangle-network/agent-runtime/blob/main/tests/kernel/code-mode.test.ts).
+Use `codeModeSupervisorTools(runner)` with an explicit `CodeModeRunner`; there is no default runner.
+For untrusted model output, supply a real isolated execution environment.
+The in-process runner and source lint are not security boundaries.
+
+The generated API follows the live coordination grant.
+Code can spawn or steer through Runtime-provided bindings such as `api.spawn_worker`; these retain authorization, shared budgets, and journal records.
+Direct coordination requests over HTTP or a second scheduler bypass that contract.
+
+Lifecycle decisions remain model tools: `submit_result`, `stop`, and `ask_parent` are outside the generated code API.
+Keep judgment in the model and mechanics in the program.
+Before broad use, exercise one allowed call, one denied call, a failed operation, and cancellation through the selected runner.

package/skills/generate-eval/SKILL.md

@@ -13,8 +13,9 @@ Do not use it for general coding quality or subjective output.
 - `TARGET`: a pinned package version, repository commit, or release.
 - `OUT`: the path for one candidate JSON object.
 
-Read `bench/src/generate-eval/schema.ts` and `bench/src/generate-eval/certify.ts` before authoring the candidate.
+Read the current [candidate schema](https://github.com/tangle-network/agent-runtime/blob/main/bench/src/generate-eval/schema.ts) and [execution checks](https://github.com/tangle-network/agent-runtime/blob/main/bench/src/generate-eval/certify.ts) before authoring the candidate.
 Those files define the current format and checks.
+Use a maintained target for new cases, then freeze its exact identity so later runs compare the same behavior.
 
 ## Build One Case
 

package/skills/loop-writer/SKILL.md

@@ -1,103 +1,49 @@
 ---
 name: loop-writer
-description: Write a custom control policy only when current runtime composition APIs cannot express it.
+description: Build a custom execution policy only when maintained Runtime composition cannot express it.
 ---
 
 # Loop Writer
 
-Use this only for a control policy that the shipped high-level APIs cannot express.
-Read `docs/canonical-api.md`, current exports, the implementation, and the nearest test before writing code.
-Do not copy signatures from this skill.
+Use this for a required execution policy that maintained Runtime APIs cannot express.
+Read the [current decision table](https://github.com/tangle-network/agent-runtime/blob/main/docs/canonical-api.md), [exports](https://github.com/tangle-network/agent-runtime/blob/main/package.json), selected implementation, and nearest test.
+If an existing entrypoint fits, use it and stop.
+A wrapper that only renames inputs or outputs does not justify a custom loop.
 
-## Choose The Existing Path First
+## Define the missing behavior
 
-| Need | Existing path |
-|---|---|
-| One product chat turn | `handleChatTurn(...)` |
-| One task or bounded multi-turn task | `runAgentTask(...)` or `runAgentTaskStream(...)` |
-| Two or more actors taking turns | `defineConversation(...)` and `runConversation(...)` |
-| A driver coordinating workers | `supervise(...)` or `superviseSurface(...)` |
-| Parallel or fixed composition | `fanout(...)`, `pipeline(...)`, `panel(...)`, `verify(...)`, or `loopUntil(...)` |
-| Parallel repository workers with isolated branches | `worktreeFanout(...)` |
-| Repeated work in a graded tool environment | `runAgentic(...)` |
-| Equal-budget comparison over that environment | `runBenchmark(...)` |
-| Low-level round policy with custom planning and stopping | `runAgentRounds(...)` |
+Name the consumer, required decision, and why existing composition cannot express it.
+Reuse Runtime's execution, accounting, cancellation, questions, and recovery contracts.
+The custom policy chooses work and continuation from the task and checked prior outcomes.
+It must not introduce another scheduler or measurement system.
 
-If an existing row fits, use it and stop.
-Do not create another wrapper solely to rename inputs or results.
+Keep planning separate from consequential writes.
+The caller owns credentials, persistence, and authority; executors return observed artifacts; independent checks decide whether those artifacts satisfy the task.
+A model score cannot override failed objective checks, denied actions, or service failures.
 
-## Custom Loop Contract
+## Preserve observable state
 
-A custom loop has five explicit parts:
+Represent successful delivery, exhausted resources, cancellation, unresolved questions, execution failure, and interrupted recovery where they apply.
+Keep measurement and service errors distinct from agent failure.
+Retain task and attempt identities, artifacts, spend, and the reason for continuing or stopping.
+Resume from durable facts and reconcile uncertain writes before retrying.
 
-```text
-task -> plan work -> execute attempts -> check outcomes -> continue or stop
-```
+Steering and questions use the existing typed events and delivery records.
+Keep unanswered required questions visible.
+Parallel workers receive isolated state or an explicit shared-mutation contract.
+Children remain within parent authority and the same accounting and cancellation rules.
 
-Keep ownership separate:
+## Prove the policy
 
-- The driver chooses work and termination from task plus prior outcomes.
-- Executors run attempts and return observed artifacts.
-- Objective checks determine whether an artifact is usable.
-- Trace emission records plans, attempts, tool effects, checks, spend, and decisions.
-- The caller owns policy, budgets, credentials, persistence, and side-effect authority.
+Test the custom decision on a representative real task.
+Exercise its relevant failure and recovery paths, including rejected output followed by correction, resource exhaustion, cancellation, and duplicate-side-effect prevention.
+Use existing contract tests for unchanged Runtime behavior; add checks that distinguish the new policy.
 
-The driver must not mutate product state while planning.
-An LLM score must not override failed builds, tests, missing evidence, denied permissions, or service errors.
-
-## Required States
-
-Model every terminal and resumable state explicitly:
-
-- succeeded with the accepted artifact;
-- exhausted by rounds, tokens, money, time, or concurrency;
-- cancelled by the caller;
-- blocked on a question or permission;
-- failed before an attempt;
-- failed during execution or checking;
-- interrupted with enough durable state to resume safely.
-
-Use stable run, attempt, task, and parent IDs.
-Persist the accepted artifact, every attempted artifact identity, spend, and final reason.
-Resume from durable facts, not an in-memory counter or summary alone.
-
-## Steering And Questions
-
-Steering is a typed input to a running or replacement attempt.
-Record who sent it, why, which evidence motivated it, whether delivery succeeded, and which attempt consumed it.
-
-Questions are explicit events.
-Route them to the responsible parent or user, preserve unanswered blockers, and fail closed when a required answer is unavailable.
-Do not bury a permission request in free-form worker output.
-
-## Parallel And Recursive Work
-
-Give parallel workers isolated state unless shared mutation is the point of the task.
-For repository changes, use one worktree per worker and explicit merge outcomes.
-For external writes, use idempotency keys and product-owned transactions.
-
-Recursive supervisors use the same budget, cancellation, trace, question, and completion contracts at every depth.
-Do not grant a child more authority than its parent.
-
-## Tests
-
-Cover:
-
-- success on the first and later rounds;
-- invalid output followed by a corrected attempt;
-- every budget limit;
-- abort propagation to in-flight work;
-- service and check failures remaining distinct from agent failure;
-- unresolved blocking questions;
-- interrupted run recovery without duplicate side effects;
-- deterministic replay of decisions from saved outcomes where supported.
-
-## Completion
-
-The change is complete when the public entrypoint is smaller than the policy it replaces, all states above are observable, a real task exercises the custom behavior, and package typecheck, tests, build, docs, and package verification pass.
+Complete when the required behavior works through its public entrypoint, final and resumable states remain observable, and the relevant package and consumer checks pass.
+Report the exact missing capability supplied, retained Runtime contracts, real result, and limits.
 
 ## Then consider
 
 - `critical-audit` when the loop changes a public contract or authority boundary.
-- `eval-engineering` when the loop's stopping condition needs a new evaluation case.
-- `verify` before publishing the package.
+- `eval-engineering` when the stopping condition lacks an adequate evaluation case.
+- `verify` when implementation is complete and release checks remain.

package/skills/supervise/SKILL.md

@@ -1,110 +1,58 @@
 ---
 name: supervise
-description: Author and drive recursive AgentProfiles with durable assignments, evidence, and recovery.
+description: Author and drive recursive AgentProfiles with explicit capabilities, evidence, and recovery.
 ---
 
 # Supervise
 
 Use this when Runtime coordination tools are attached.
-Author agents that can perform the work, then drive them from checked evidence.
-
-## Keep policy in its owner
-
-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.
-
-`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.
-
-## Author a descendant
-
-Write a valid `AgentProfile`, not a prose description of one.
-Use only fields the selected backend can materialize.
-
-```json
-{
-  "name": "source-skeptic-v1",
-  "description": "Challenge one candidate claim against primary evidence.",
-  "prompt": {
-    "systemPrompt": "Return a claim table with source locations, contradictions, unknowns, and a reproducible rejection check."
-  },
-  "model": {
-    "default": "<allowed-model-id>",
-    "reasoningEffort": "xhigh"
-  },
-  "tools": {
-    "agent_runtime_coordination_spawn_worker": true,
-    "agent_runtime_coordination_await_event": true
-  },
-  "resources": {
-    "failOnError": true,
-    "skills": [
-      {
-        "kind": "inline",
-        "name": "profile-authoring/SKILL.md",
-        "content": "<the complete profile-authoring skill text>"
-      }
-    ]
-  }
-}
-```
-
-The example shows placement, not required values.
-Every agent is the same `AgentProfile` shape.
-An agent becomes a recursive lead only by declaring `agent_runtime_coordination_spawn_worker: true`.
-Declare each other Runtime verb it will use, such as `await_event`, `steer_agent`, or `read_journal`.
-Runtime mounts only the declared bare verbs through its coordination surface; the provider receives a profile projection without Runtime-owned declarations.
-Metadata can describe the work, but it never grants execution authority.
-Every profile that can spawn workers carries the complete profile-authoring skill in `resources.skills`.
-Make that resource an immutable inline snapshot or a pinned reference, and set `resources.failOnError: true`.
-This is taught through the profile, not injected or enforced by Runtime: the authored profile remains the complete record of why it can delegate.
-Omit Runtime coordination tools for a 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.
-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.
+Author agents that can perform the required work, then direct them from checked evidence.
+
+## Author complete agents
+
+Put research choices, methods, revision rules, and stopping criteria in each profile's prompt.
+Runtime owns shared budgets, recursion limits, concurrency, cancellation, journals, and recovery.
+The caller configures root execution through [SuperviseOptions](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime/supervise/supervise.ts).
+Per-assignment budgets, continuity, and keys belong to the [coordination tools](https://github.com/tangle-network/agent-runtime/blob/main/src/mcp/tools/coordination.ts), not invented profile fields.
+
+An agent receives recursive authority by declaring `agent_runtime_coordination_spawn_worker: true` in its tools.
+Declare each other Runtime tool it needs explicitly.
+Metadata describes work; it does not grant authority.
+Every profile that can spawn workers carries the complete `profile-authoring/SKILL.md` resource, using an immutable snapshot and `resources.failOnError: true`.
+The authored profile must explain its own ability to delegate; Runtime does not invent that policy.
+
+When creating or changing a descendant profile, read [profile authoring](references/profile-authoring.md) for the exact contract and resource placement.
+The task names the concrete artifact and completion check; the profile names the method and granted capabilities.
+
+## Direct the work
+
+1. Split the objective into independent artifacts with checkable outcomes.
+2. Start each assignment with a stable semantic key and a deliberate budget.
+   Fill available capacity while distinct useful assignments remain.
+3. Pull settlements, findings, and questions with `await_event`.
+   A bounded wait returning does not establish failure.
+4. Inspect quiet or stalled workers with `observe_agent` before steering them.
+   Correct an observed wrong path, missing requirement, or new evidence.
+5. Check each returned artifact before using it.
+   Preserve failed attempts and change the profile or assignment when evidence supports another attempt.
+6. After recovery, reconcile the journal, roster, settlements, questions, findings, and spend before creating replacements.
+
+Use `continuity: 'resume'` to continue the most recent settled worker with that profile name.
+A resumed assignment is a new execution and cannot carry a run-once key.
+Completed keys resolve to committed results; an uncertain prior dispatch must be reconciled before replacement.
+Stop at checked success, an authorized resource limit, cancellation, or a demonstrated dead end.
+A quiet worker alone is not a reason to invent a deadline.
 
 ## 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 this agent'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.
+Preserve profile identities, assignment keys, parent-child links, continuations, costs, failures, and missing accounting.
+Worker prose cannot approve its own result.
+Use `submit_result` only when the attached check can validate this agent's artifact.
+Calling `stop` ends coordination; it does not establish completion.
 
 ## Then consider
 
-- `build-with-agent-runtime` when a product must configure the Runtime-owned limits and adapters.
+- `build-with-agent-runtime` when the product must change Runtime limits or adapters.
 - `eval-engineering` when no existing check can separate success from failure.
-- `verify` after every required artifact passes its independent check.
+- `verify` when required artifacts pass and delivery checks remain.