From 04f9eaaaac4a4d7c4dfac655eba57fc8e5854d2a Mon Sep 17 00:00:00 2001 From: mm Date: Thu, 1 Oct 2026 14:11:58 -0400 Subject: [PATCH] IMP-076: Align public skill guidance with executor and evaluator roles --- README.md | 5 +-- skills/open-prose/SKILL.md | 7 ++--- skills/open-prose/agent-onboarding.md | 6 ++-- skills/open-prose/guidance/authoring.md | 34 +++++++++++++++++++-- skills/open-prose/guidance/system-prompt.md | 10 ++++++ skills/open-prose/help.md | 6 ++-- 6 files changed, 54 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 01a5d5ce..15041eab 100644 --- a/README.md +++ b/README.md @@ -14,11 +14,12 @@ ## What this is -**With OpenProse, you state what an agent must accomplish, which requirements it -must satisfy, and where it can choose its approach.** Contract authoring is +Contract authoring is expressing intent by composing requirements. Reusable contracts provide the building blocks; composition determines how their requirements apply together. +An agent performs the work, and an evaluator assesses whether the contract’s requirements are satisfied. The executor returns a result that includes the evidence needed for that assessment. Execution and evaluation repeat as needed. + This public repository supplies the **Contract Markdown and ProseScript** format, the `open-prose` skill, and reusable libraries. A `responsibility` expresses requirements for state maintained over time. A `function` performs a diff --git a/skills/open-prose/SKILL.md b/skills/open-prose/SKILL.md index 48a1af11..9e87e8d4 100644 --- a/skills/open-prose/SKILL.md +++ b/skills/open-prose/SKILL.md @@ -15,10 +15,9 @@ description: | # OpenProse Skill -Contract authoring is expressing intent by composing requirements. State what -the agent must accomplish, which conditions it must satisfy, and where it can -choose its approach. Reuse and combine contracts through the interfaces in -this skill; see [requirements and composition](guidance/authoring.md#requirements-and-composition). +Contract authoring is expressing intent by composing requirements. An agent +performs the work, and an evaluator assesses whether the contract’s requirements +are satisfied. Reuse and combine contracts through the interfaces in this skill; see [requirements and composition](guidance/authoring.md#requirements-and-composition). OpenProse has five load-bearing pieces: diff --git a/skills/open-prose/agent-onboarding.md b/skills/open-prose/agent-onboarding.md index 810dfebb..ee602992 100644 --- a/skills/open-prose/agent-onboarding.md +++ b/skills/open-prose/agent-onboarding.md @@ -2,11 +2,11 @@ > State the requirements. Reuse and combine contracts. -Contract authoring is expressing intent by composing requirements. Start with -what the agent must accomplish, which conditions it must satisfy, and the -choices it may make. See [requirements and composition](guidance/authoring.md#requirements-and-composition) +Contract authoring is expressing intent by composing requirements. See [requirements and composition](guidance/authoring.md#requirements-and-composition) for the public skill format. +An agent performs the work, and an evaluator assesses whether the contract’s requirements are satisfied. The executor returns a result that includes the evidence needed for that assessment. Execution and evaluation repeat as needed. + ## Install ``` diff --git a/skills/open-prose/guidance/authoring.md b/skills/open-prose/guidance/authoring.md index 0f964901..c99d26bb 100644 --- a/skills/open-prose/guidance/authoring.md +++ b/skills/open-prose/guidance/authoring.md @@ -16,8 +16,7 @@ Use this file when writing or reviewing OpenProse author-facing artifacts: ## Requirements and composition -State what the agent must accomplish, which requirements it must satisfy, and -where it can choose its approach. **Contract authoring is expressing intent by +**Contract authoring is expressing intent by composing requirements.** A contract states requirements and the context needed to interpret and apply them. Reusable contracts provide the building blocks; composition determines how their requirements apply together. @@ -58,6 +57,37 @@ same render with different or missing sections (the authored kinds in *inside* a render or a cross-node *subscription* across responsibilities, never a third internally-autowired graph kind. +## Execution and evaluation + +The executor performs the work required by the contract and returns a result. +The evaluator assesses whether the contract’s requirements are satisfied using +that result and the available evidence. Execution and evaluation repeat as +needed. An evaluator can also assess the current state before more execution +is necessary. These are roles: the same agent can perform both unless a +composed contract requires independent review. A decision model can perform +evaluation. + +The result includes evidence, partial work and relevant uncertainty. It can +be a document containing or referencing artifacts and records the evaluator +can access. Evidence is part of the result, not another return value. Follow +the selected kind’s existing interface: a function declares `### Returns`, +while a responsibility publishes its `### Maintains` state and receipt. +This vocabulary does not replace those interfaces or add a new file layout. + +An assessment contains the evaluator’s findings about the subject contract. +Fulfillment means satisfaction of that contract’s applicable requirements. +An evaluation can complete while identifying unmet requirements or an +unresolved subject judgment. Compose contracts to express requirements for +source evidence, independent review and authorization; they are ordinary +requirements, not additional runtime phases. + +Out names the normal result channel; error reports execution failure. A +completed evaluation that finds unmet subject requirements returns a normal +assessment. Preserve partial work and effects when execution fails. Map these +concepts to the selected runtime’s existing returns, receipts and declared +errors; they do not rename syntax, prescribe stdout/stderr or introduce a +third return channel for uncertainty. + ## Core Principles - Prefer the smallest artifact that expresses the work: a responsibility when an diff --git a/skills/open-prose/guidance/system-prompt.md b/skills/open-prose/guidance/system-prompt.md index 29df61e2..e2159efb 100644 --- a/skills/open-prose/guidance/system-prompt.md +++ b/skills/open-prose/guidance/system-prompt.md @@ -25,6 +25,16 @@ they leave choices open. See [requirements and composition](authoring.md#require Requirements do not supply missing tools or grant permissions; use the host's available primitives and authorization boundaries. +## Execution and evaluation + +Act as executor when carrying out the contract’s work and as evaluator when +assessing whether its requirements are satisfied. Follow any composed +independent-review requirement. Return a result that includes the evidence +needed for assessment; preserve missing evidence and unresolved effects. +A completed evaluation can find unmet subject requirements. Follow the +selected kind’s existing result and error interfaces; an assessment of +nonfulfillment is not by itself an evaluation failure. + ## Your Role You are not merely describing a virtual machine. You are the OpenProse VM: diff --git a/skills/open-prose/help.md b/skills/open-prose/help.md index bea67db2..332ff73d 100644 --- a/skills/open-prose/help.md +++ b/skills/open-prose/help.md @@ -6,11 +6,11 @@ Load this file when a user invokes `prose help` or asks about OpenProse. ## Welcome -With OpenProse, state what the agent must accomplish, which requirements it -must satisfy, and where it can choose its approach. Contract authoring is -expressing intent by composing requirements. Reusable contracts provide the +Contract authoring is expressing intent by composing requirements. Reusable contracts provide the building blocks; composition determines how their requirements apply together. +An agent performs the work, and an evaluator assesses whether the contract’s requirements are satisfied. The executor returns a result that includes the evidence needed for that assessment. Execution and evaluation repeat as needed. + The public skill uses Contract Markdown for requirements and interfaces, and ProseScript for required steps inside a render. A `responsibility` maintains state over time; a `function` provides a one-time call. The agent follows the