Browser-based graphical shell and control plane for a Linux server you own — real terminal, file manager, live metrics and BYOK AI in one mobile-first workspace. Next.js 16 · React 19 · node-pty · Tailwind v4 · shadcn/ui. Public alpha, self-hosted.
TypeScript browser-shellcontrol-planefile-managerhomelabmobile-firstnextjsptyreactself-hostedserver-managementshadcn-uisysadmintailwindcssterminaltypescriptvpsweb-desktopweb-terminal
feat(plugins): add structured OpenAI skill contracts
Rahmanf037e4c912f0
diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.jsonnew file mode 100644index 00000000..84d1f579--- /dev/null+++ b/.codex-plugin/plugin.json@@ -0,0 +1,28 @@+{+ "name": "mso",+ "version": "0.2.16",+ "description": "Operate MSO projects, workflows, VPS resources, integrations, deployments, and MCP capabilities through reusable safety-first skills.",+ "author": {+ "name": "MSO"+ },+ "homepage": "https://github.com/rahmanef63/mso",+ "skills": "./claude-skills/",+ "interface": {+ "displayName": "MSO",+ "shortDescription": "Operate projects, VPS, workflows, and MCP safely",+ "longDescription": "MSO provides reusable operator workflows for project work, deployments, service debugging, integrations, MCP feature engineering, managed apps, and VPS operations. Skills preserve MSO trust, scope, concurrency, evidence, and bounded-tool policies while the live MSO MCP app remains a separately authorized connection.",+ "developerName": "MSO",+ "category": "Developer Tools",+ "capabilities": [+ "Interactive",+ "Read",+ "Write"+ ],+ "websiteURL": "https://github.com/rahmanef63/mso",+ "defaultPrompt": [+ "Inspect this project and continue the safest verified workflow.",+ "Debug this service using bounded MSO tools and evidence.",+ "Implement and verify this MCP capability without weakening existing MSO safeguards."+ ]+ }+}diff --git a/claude-skills/integrations/agents/openai.yaml b/claude-skills/integrations/agents/openai.yamlnew file mode 100644index 00000000..58a15515--- /dev/null+++ b/claude-skills/integrations/agents/openai.yaml@@ -0,0 +1,4 @@+interface:+ display_name: "MSO Integrations"+ short_description: "Manage provider connections and credentials"+ default_prompt: "Use $integrations to inspect or configure MSO integrations safely."diff --git a/claude-skills/integrations/contract.yaml b/claude-skills/integrations/contract.yamlnew file mode 100644index 00000000..f418d071--- /dev/null+++ b/claude-skills/integrations/contract.yaml@@ -0,0 +1,28 @@+version: 1+routing:+ use_when:+ - "manage provider connections and credentials"+ do_not_use_when:+ - "A narrower official MSO skill exactly matches the requested task."+ fallback: false+context:+ target: integrations+ mode: mixed+ actor: operator+lifecycle:+ discover:+ - connections_list+ validate:+ - identity-policy+ - secret-boundary+ verify:+ - connections_list+state:+ source_of_truth: live+ refresh: before-write+safety:+ risk: high+ confirmation: contextual+ concurrency: contextual+presentation:+ authority: hybriddiff --git a/claude-skills/mso-apps/agents/openai.yaml b/claude-skills/mso-apps/agents/openai.yamlnew file mode 100644index 00000000..6957a180--- /dev/null+++ b/claude-skills/mso-apps/agents/openai.yaml@@ -0,0 +1,4 @@+interface:+ display_name: "MSO Apps"+ short_description: "Operate managed apps on the VPS"+ default_prompt: "Use $mso-apps to inspect, start, stop, or troubleshoot managed MSO apps."diff --git a/claude-skills/mso-apps/contract.yaml b/claude-skills/mso-apps/contract.yamlnew file mode 100644index 00000000..eb6bb3d2--- /dev/null+++ b/claude-skills/mso-apps/contract.yaml@@ -0,0 +1,27 @@+version: 1+routing:+ use_when:+ - "operate managed apps on the VPS"+ do_not_use_when:+ - "A narrower official MSO skill exactly matches the requested task."+ fallback: false+context:+ target: managed-app+ mode: mixed+ actor: operator+lifecycle:+ discover:+ - apps_list+ validate:+ - managed-app-policy+ verify:+ - apps_status+state:+ source_of_truth: live+ refresh: before-write+safety:+ risk: medium+ confirmation: contextual+ concurrency: contextual+presentation:+ authority: hybriddiff --git a/claude-skills/mso-camoufox/agents/openai.yaml b/claude-skills/mso-camoufox/agents/openai.yamlnew file mode 100644index 00000000..82f059e2--- /dev/null+++ b/claude-skills/mso-camoufox/agents/openai.yaml@@ -0,0 +1,4 @@+interface:+ display_name: "MSO Camoufox"+ short_description: "Operate the managed browser session"+ default_prompt: "Use $mso-camoufox to inspect or operate the managed Camoufox browser."diff --git a/claude-skills/mso-camoufox/contract.yaml b/claude-skills/mso-camoufox/contract.yamlnew file mode 100644index 00000000..ef2c4148--- /dev/null+++ b/claude-skills/mso-camoufox/contract.yaml@@ -0,0 +1,28 @@+version: 1+routing:+ use_when:+ - "operate the managed browser session"+ do_not_use_when:+ - "A narrower official MSO skill exactly matches the requested task."+ fallback: false+context:+ target: browser-session+ mode: execute+ actor: operator+lifecycle:+ discover:+ - browser_status+ validate:+ - browser-session-policy+ - credential-boundary+ verify:+ - browser_status+state:+ source_of_truth: live+ refresh: before-write+safety:+ risk: high+ confirmation: contextual+ concurrency: contextual+presentation:+ authority: hybriddiff --git a/claude-skills/mso-deploy/agents/openai.yaml b/claude-skills/mso-deploy/agents/openai.yamlnew file mode 100644index 00000000..2ae3249d--- /dev/null+++ b/claude-skills/mso-deploy/agents/openai.yaml@@ -0,0 +1,4 @@+interface:+ display_name: "MSO Deploy"+ short_description: "Verify and deploy MSO itself"+ default_prompt: "Use $mso-deploy to build, deploy, or verify the MSO production service."diff --git a/claude-skills/mso-deploy/contract.yaml b/claude-skills/mso-deploy/contract.yamlnew file mode 100644index 00000000..e163309d--- /dev/null+++ b/claude-skills/mso-deploy/contract.yaml@@ -0,0 +1,30 @@+version: 1+routing:+ use_when:+ - "verify and deploy MSO itself"+ do_not_use_when:+ - "A narrower official MSO skill exactly matches the requested task."+ fallback: false+context:+ target: mso-production+ mode: execute+ actor: operator+lifecycle:+ discover:+ - project_get+ validate:+ - targeted-tests+ - build+ - release-gates+ verify:+ - health+ - runtime+state:+ source_of_truth: live+ refresh: before-write+safety:+ risk: high+ confirmation: contextual+ concurrency: revision+presentation:+ authority: hybriddiff --git a/claude-skills/mso-image-editor/agents/openai.yaml b/claude-skills/mso-image-editor/agents/openai.yamlnew file mode 100644index 00000000..d014f32d--- /dev/null+++ b/claude-skills/mso-image-editor/agents/openai.yaml@@ -0,0 +1,4 @@+interface:+ display_name: "MSO Image Editor"+ short_description: "Edit project images with the local pipeline"+ default_prompt: "Use $mso-image-editor to run the trusted MSO image-editing workflow."diff --git a/claude-skills/mso-image-editor/contract.yaml b/claude-skills/mso-image-editor/contract.yamlnew file mode 100644index 00000000..6b4114fd--- /dev/null+++ b/claude-skills/mso-image-editor/contract.yaml@@ -0,0 +1,28 @@+version: 1+routing:+ use_when:+ - "edit project images with the local pipeline"+ do_not_use_when:+ - "A narrower official MSO skill exactly matches the requested task."+ fallback: false+context:+ target: image-artifact+ mode: execute+ actor: operator+lifecycle:+ discover:+ - fs_read+ validate:+ - image-input+ - output-path+ verify:+ - artifact+state:+ source_of_truth: live+ refresh: before-write+safety:+ risk: medium+ confirmation: contextual+ concurrency: hash+presentation:+ authority: hybriddiff --git a/claude-skills/mso-list/agents/openai.yaml b/claude-skills/mso-list/agents/openai.yamlnew file mode 100644index 00000000..e9353341--- /dev/null+++ b/claude-skills/mso-list/agents/openai.yaml@@ -0,0 +1,4 @@+interface:+ display_name: "MSO Capability Guide"+ short_description: "Inspect MSO capabilities and routes"+ default_prompt: "Use $mso-list to discover MSO capabilities, routes, and supported surfaces."diff --git a/claude-skills/mso-list/contract.yaml b/claude-skills/mso-list/contract.yamlnew file mode 100644index 00000000..c3ee3724--- /dev/null+++ b/claude-skills/mso-list/contract.yaml@@ -0,0 +1,25 @@+version: 1+routing:+ use_when:+ - "inspect MSO capabilities and routes"+ do_not_use_when:+ - "A narrower official MSO skill exactly matches the requested task."+ fallback: true+context:+ target: capability-catalog+ mode: read+ actor: operator+lifecycle:+ discover:+ - skills_search+ validate:+ - catalog-freshness+state:+ source_of_truth: live+ refresh: contextual+safety:+ risk: low+ confirmation: none+ concurrency: none+presentation:+ authority: hybriddiff --git a/claude-skills/mso-mcp-feature-engineering/agents/openai.yaml b/claude-skills/mso-mcp-feature-engineering/agents/openai.yamlnew file mode 100644index 00000000..63fb9045--- /dev/null+++ b/claude-skills/mso-mcp-feature-engineering/agents/openai.yaml@@ -0,0 +1,4 @@+interface:+ display_name: "MSO MCP Engineering"+ short_description: "Build and verify MCP capabilities"+ default_prompt: "Use $mso-mcp-feature-engineering to add or repair MSO MCP tools, skills, scopes, or app surfaces."diff --git a/claude-skills/mso-mcp-feature-engineering/contract.yaml b/claude-skills/mso-mcp-feature-engineering/contract.yamlnew file mode 100644index 00000000..64d14dff--- /dev/null+++ b/claude-skills/mso-mcp-feature-engineering/contract.yaml@@ -0,0 +1,31 @@+version: 1+routing:+ use_when:+ - "build and verify MCP capabilities"+ do_not_use_when:+ - "A narrower official MSO skill exactly matches the requested task."+ fallback: false+context:+ target: mcp-server+ mode: mixed+ actor: operator+lifecycle:+ discover:+ - workflow_start+ validate:+ - mcp-contract+ - scope-policy+ - mcp-catalog+ - targeted-tests+ verify:+ - mcp-catalog+ - runtime+state:+ source_of_truth: live+ refresh: before-write+safety:+ risk: medium+ confirmation: contextual+ concurrency: revision+presentation:+ authority: hybriddiff --git a/claude-skills/mso-project-deploy/agents/openai.yaml b/claude-skills/mso-project-deploy/agents/openai.yamlnew file mode 100644index 00000000..b0095728--- /dev/null+++ b/claude-skills/mso-project-deploy/agents/openai.yaml@@ -0,0 +1,4 @@+interface:+ display_name: "MSO Project Deploy"+ short_description: "Deploy one project through bounded providers"+ default_prompt: "Use $mso-project-deploy to publish or repair a project deployment through MSO integrations."diff --git a/claude-skills/mso-project-deploy/contract.yaml b/claude-skills/mso-project-deploy/contract.yamlnew file mode 100644index 00000000..b80e6063--- /dev/null+++ b/claude-skills/mso-project-deploy/contract.yaml@@ -0,0 +1,31 @@+version: 1+routing:+ use_when:+ - "deploy one project through bounded providers"+ do_not_use_when:+ - "A narrower official MSO skill exactly matches the requested task."+ fallback: false+context:+ target: project-production+ mode: execute+ actor: operator+lifecycle:+ discover:+ - project_get+ - connections_list+ validate:+ - provider-policy+ - project-identity+ - build+ verify:+ - deployment+ - health+state:+ source_of_truth: live+ refresh: before-write+safety:+ risk: high+ confirmation: contextual+ concurrency: contextual+presentation:+ authority: hybriddiff --git a/claude-skills/mso-repo-work/agents/openai.yaml b/claude-skills/mso-repo-work/agents/openai.yamlnew file mode 100644index 00000000..b742596f--- /dev/null+++ b/claude-skills/mso-repo-work/agents/openai.yaml@@ -0,0 +1,4 @@+interface:+ display_name: "MSO Repo Work"+ short_description: "Make safe repository changes"+ default_prompt: "Use $mso-repo-work for multi-file repository implementation, tests, and Git verification."diff --git a/claude-skills/mso-repo-work/contract.yaml b/claude-skills/mso-repo-work/contract.yamlnew file mode 100644index 00000000..e33f7db8--- /dev/null+++ b/claude-skills/mso-repo-work/contract.yaml@@ -0,0 +1,30 @@+version: 1+routing:+ use_when:+ - "make safe repository changes"+ do_not_use_when:+ - "A narrower official MSO skill exactly matches the requested task."+ fallback: false+context:+ target: repository+ mode: mixed+ actor: operator+lifecycle:+ discover:+ - workflow_start+ - project_get+ validate:+ - diff-boundary+ - targeted-tests+ verify:+ - project_diff+ - tests+state:+ source_of_truth: live+ refresh: before-write+safety:+ risk: medium+ confirmation: contextual+ concurrency: revision+presentation:+ authority: hybriddiff --git a/claude-skills/mso-service-debug/agents/openai.yaml b/claude-skills/mso-service-debug/agents/openai.yamlnew file mode 100644index 00000000..4e7db265--- /dev/null+++ b/claude-skills/mso-service-debug/agents/openai.yaml@@ -0,0 +1,4 @@+interface:+ display_name: "MSO Service Debug"+ short_description: "Diagnose service failures safely"+ default_prompt: "Use $mso-service-debug to diagnose a managed service or runtime regression."diff --git a/claude-skills/mso-service-debug/contract.yaml b/claude-skills/mso-service-debug/contract.yamlnew file mode 100644index 00000000..5d9183da--- /dev/null+++ b/claude-skills/mso-service-debug/contract.yaml@@ -0,0 +1,29 @@+version: 1+routing:+ use_when:+ - "diagnose service failures safely"+ do_not_use_when:+ - "A narrower official MSO skill exactly matches the requested task."+ fallback: false+context:+ target: service-runtime+ mode: execute+ actor: operator+lifecycle:+ discover:+ - apps_list+ - apps_logs+ validate:+ - runtime-evidence+ verify:+ - apps_status+ - health+state:+ source_of_truth: live+ refresh: before-write+safety:+ risk: medium+ confirmation: contextual+ concurrency: contextual+presentation:+ authority: hybriddiff --git a/claude-skills/mso-skill-authoring/SKILL.md b/claude-skills/mso-skill-authoring/SKILL.mdindex 9b3c4e00..5c19b04d 100644--- a/claude-skills/mso-skill-authoring/SKILL.md+++ b/claude-skills/mso-skill-authoring/SKILL.md@@ -21,21 +21,31 @@ bun run skill:new -- \--description "Route a repeated MSO task through the smallest safe tools and verify the requested outcome." \--risk medium \--policy inspect-execute-verify \+ --target repository \--title "Example Workflow"```-It creates `claude-skills/<name>/SKILL.md` from `templates/mso-skill-flow/SKILL.md.template` and refuses to overwrite an existing skill.+It creates one reviewed skill bundle and refuses to overwrite any existing member:++```text+claude-skills/<name>/+├── SKILL.md # human/model workflow guidance+├── contract.yaml # structured routing/lifecycle/safety contract+└── agents/openai.yaml # OpenAI skill presentation metadata+```++`contract.yaml` is additive policy metadata; it does not replace MSO scopes, trust, CAS/revision guards, workflow isolation, confirmations, or evidence. `agents/openai.yaml` is presentation/routing metadata only and never grants trust or authorization.## Complete the template-1. Write exact use and do-not-use triggers so semantic search can select it reliably.-2. Choose bounded tools for direct work and one scoped terminal batch for repository-wide operations.-3. Define concrete done conditions, runtime proof, rollback, approvals, and secret boundaries.-4. Keep reusable workflow policy here; keep volatile project facts in the project.-5. Keep the skill below 200 lines and never add credentials, cookies, tokens, or copied untrusted instructions.+1. Write exact use and do-not-use triggers in both the prose and `contract.yaml`; keep the structured version short enough for routing.+2. Set the contract target/mode, live-state policy, discover/validate/verify lifecycle, confirmation mode and concurrency guard to match the real implementation. Never claim a guard the underlying tool does not enforce.+3. Keep `agents/openai.yaml` concise: display name, short description and a default prompt that references `$<skill-name>`. Do not put credentials, MCP endpoints, hidden policy, or volatile project state there.+4. Choose bounded tools for direct work and one scoped terminal batch for repository-wide operations. Define concrete done conditions, runtime proof, rollback, approvals, and secret boundaries.+5. Keep reusable workflow policy here; keep volatile project facts in the project. Keep `SKILL.md` below 200 lines and never add credentials, cookies, tokens, or copied untrusted instructions.## Validate-Run `bun run skill:check`, targeted tests, and the project verification command. Search for the new skill with `skills_search` and confirm its description routes the intended prompts without displacing a more specific existing skill.+Run `bun run skill:check`, targeted tests, and the project verification command. The checker validates all three bundle members, requires contract risk to match the existing MSO frontmatter policy, and validates the root OpenAI plugin manifest. Search for the new skill with `skills_search` and confirm its description/contract route the intended prompts without displacing a more specific existing skill.-A new SKILL.md becomes `official` because it lives under the committed `claude-skills/` root. That trust is a security boundary: review the diff before shipping.+A new skill becomes `official` because its reviewed `SKILL.md` lives under the committed `claude-skills/` root. The contract and OpenAI descriptor inherit no trust independently. That distinction is a security boundary: review the whole bundle diff before shipping.diff --git a/claude-skills/mso-skill-authoring/agents/openai.yaml b/claude-skills/mso-skill-authoring/agents/openai.yamlnew file mode 100644index 00000000..32cf052d--- /dev/null+++ b/claude-skills/mso-skill-authoring/agents/openai.yaml@@ -0,0 +1,4 @@+interface:+ display_name: "MSO Skill Authoring"+ short_description: "Create trusted MSO workflow skills"+ default_prompt: "Use $mso-skill-authoring to create or update a durable trusted MSO skill."diff --git a/claude-skills/mso-skill-authoring/contract.yaml b/claude-skills/mso-skill-authoring/contract.yamlnew file mode 100644index 00000000..2badc69a--- /dev/null+++ b/claude-skills/mso-skill-authoring/contract.yaml@@ -0,0 +1,29 @@+version: 1+routing:+ use_when:+ - "create trusted MSO workflow skills"+ do_not_use_when:+ - "A narrower official MSO skill exactly matches the requested task."+ fallback: false+context:+ target: skill+ mode: write+ actor: operator+lifecycle:+ discover:+ - skills_search+ validate:+ - skill-contract-v1+ - openai-skill-interface-v1+ - skill-check+ verify:+ - skills_search+state:+ source_of_truth: live+ refresh: before-write+safety:+ risk: low+ confirmation: contextual+ concurrency: revision+presentation:+ authority: hybriddiff --git a/claude-skills/mso/agents/openai.yaml b/claude-skills/mso/agents/openai.yamlnew file mode 100644index 00000000..ec63c6a5--- /dev/null+++ b/claude-skills/mso/agents/openai.yaml@@ -0,0 +1,4 @@+interface:+ display_name: "MSO"+ short_description: "Operate MSO and the VPS safely"+ default_prompt: "Use $mso for general MSO/VPS operations when no narrower official skill is a better match."diff --git a/claude-skills/mso/contract.yaml b/claude-skills/mso/contract.yamlnew file mode 100644index 00000000..587aaad3--- /dev/null+++ b/claude-skills/mso/contract.yaml@@ -0,0 +1,29 @@+version: 1+routing:+ use_when:+ - "operate MSO and the VPS safely"+ do_not_use_when:+ - "A narrower official MSO skill exactly matches the requested task; prefer the specialist skill."+ fallback: true+context:+ target: host+ mode: mixed+ actor: operator+lifecycle:+ discover:+ - workflow_start+ validate:+ - bounded-first+ - scope-policy+ - progressive-verification+ verify:+ - workflow_finish+state:+ source_of_truth: live+ refresh: before-write+safety:+ risk: high+ confirmation: contextual+ concurrency: contextual+presentation:+ authority: hybriddiff --git a/claude-skills/provider-automation/agents/openai.yaml b/claude-skills/provider-automation/agents/openai.yamlnew file mode 100644index 00000000..38e8a6f0--- /dev/null+++ b/claude-skills/provider-automation/agents/openai.yaml@@ -0,0 +1,4 @@+interface:+ display_name: "MSO Provider Automation"+ short_description: "Automate supported infrastructure providers"+ default_prompt: "Use $provider-automation to run bounded provider automation through configured MSO connections."diff --git a/claude-skills/provider-automation/contract.yaml b/claude-skills/provider-automation/contract.yamlnew file mode 100644index 00000000..7aef0d8c--- /dev/null+++ b/claude-skills/provider-automation/contract.yaml@@ -0,0 +1,28 @@+version: 1+routing:+ use_when:+ - "automate supported infrastructure providers"+ do_not_use_when:+ - "A narrower official MSO skill exactly matches the requested task."+ fallback: false+context:+ target: provider-integration+ mode: execute+ actor: operator+lifecycle:+ discover:+ - connections_list+ validate:+ - provider-policy+ - identity-policy+ verify:+ - provider-status+state:+ source_of_truth: live+ refresh: before-write+safety:+ risk: high+ confirmation: contextual+ concurrency: contextual+presentation:+ authority: hybriddiff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.mdindex 494e6ea2..8461f5de 100644--- a/docs/CHANGELOG.md+++ b/docs/CHANGELOG.md@@ -8,6 +8,7 @@ this is the *what*, and it is what Settings → About shows as “What's new”.**Added**+- `plugins` add structured OpenAI skill contracts- `workflows` stabilize semantic action references- `workflows` add semantic session flows- `workflows` visualize agent sessionsdiff --git a/docs/CHATGPT-PLUGIN.md b/docs/CHATGPT-PLUGIN.mdindex cb435bc7..948ae8dc 100644--- a/docs/CHATGPT-PLUGIN.md+++ b/docs/CHATGPT-PLUGIN.md@@ -50,6 +50,8 @@ Every advertised MSO tool has:The ChatGPT projection compacts verbose descriptions/schema descriptions without changing names, required arguments, enum/range constraints, scopes, or safety semantics.+Selected lifecycle-sensitive tools also declare an additive `mso/actionContract` on the **full** MCP descriptor. The contract names the semantic target, discover/validate/verify path, source-of-truth policy, confirmation mode and concurrency guard. It is documentation/orchestration metadata only: OAuth scope, tool implementation checks, CAS/revision guards, provider policy and explicit confirmations remain authoritative. The compact ChatGPT action snapshot intentionally omits this extra per-tool metadata because the complete 112-action profile already sits close to MSO's strict 96 KiB scanner budget; ChatGPT receives the same structured workflow policy through the published skill resources instead, without dropping any action.+## Exact ChatGPT model tool profileThe exact current ChatGPT profile is generated under **ChatGPT model profile** in [`generated/MCP-CATALOG.md`](./generated/MCP-CATALOG.md). It automatically projects every MSO-owned generic model/operator tool registered in `lib/mcp/tools.ts`; only the two compatibility bridges marked app-only remain outside model tool calling. Project-owned MCP names still never enter the global catalog. OAuth `read < write < exec` remains enforced independently.@@ -70,10 +72,28 @@ After the Fresh 3 rescan exposed `Output schema recommended` on non-UI actions,### Native MCP skill snapshot-Fresh 3 also advertises the bounded `io.modelcontextprotocol/skills` extension. `skills/list`, `skills/get`, and `resources/read` publish a submission-time snapshot of exactly five general official MSO skills: `mso`, `mso-repo-work`, `mso-service-debug`, `mso-deploy`, and `mso-mcp-feature-engineering`. The manifest is generated from `claude-skills/`, includes complete resources plus `sha256:` digests, refuses symlinks/path normalization conflicts/oversize files, and never publishes operator, project, verified-third-party, or untrusted skill roots. The ordinary `skills_search/list/read` actions remain the live runtime catalog for the rest.+Fresh 3 also advertises the bounded `io.modelcontextprotocol/skills` extension. `skills/list`, `skills/get`, and `resources/read` publish a submission-time snapshot of exactly five general official MSO skills: `mso`, `mso-repo-work`, `mso-service-debug`, `mso-deploy`, and `mso-mcp-feature-engineering`. Each published skill is now a reviewed bundle containing `SKILL.md`, `contract.yaml`, and `agents/openai.yaml` (plus any skill-specific resources). `contract.yaml` carries structured routing/lifecycle/safety metadata; `agents/openai.yaml` carries concise OpenAI display/default-prompt metadata. Publication fails closed when either structured file is missing or invalid. The manifest still includes complete resources plus `sha256:` digests, refuses symlinks/path normalization conflicts/oversize files, and never publishes operator, project, verified-third-party, or untrusted skill roots. The ordinary `skills_search/list/read` actions remain the live runtime catalog for the rest.For the complete non-ChatGPT MSO catalog, scopes, limits, A2A, providers, Tool Forge and other generic capabilities, see [`MCP.md`](./MCP.md).+## OpenAI/Codex plugin package++The repository root also carries `.codex-plugin/plugin.json` as a **skill-only** OpenAI/Codex package. It points directly at `./claude-skills/`, so the same reviewed skill bundles are reusable without maintaining a second copy. The package deliberately does **not** declare `mcpServers`: the live web-capable MSO MCP connection remains the separately authorized custom app at `/mcp`, preserving its OAuth scopes, server-side credentials, dynamic project MCP seams and browser/mobile availability instead of coupling those capabilities to a local plugin executor. Installing/importing the skill package never grants MCP access by itself.++Do not invent a root `.app.json` id. If an existing OpenAI app registration is intentionally packaged later, add its exact registered app id and keep that connection lifecycle separate from the skill package.++The OpenAI-facing repository shape is therefore:++```text+MSO repo+├── .codex-plugin/plugin.json # OpenAI/Codex skill package+├── claude-skills/<skill>/+│ ├── SKILL.md+│ ├── contract.yaml+│ └── agents/openai.yaml+└── /mcp + /oauth/* # live custom MCP app, separately authorized+```+## Dynamic project capabilities without global project toolsMSO is generic and must not publish another project's MCP tool names.diff --git a/docs/PROGRESS.md b/docs/PROGRESS.mdindex b63f8a67..cb83fa8c 100644--- a/docs/PROGRESS.md+++ b/docs/PROGRESS.md@@ -1,3 +1,10 @@+## 2026-09-17 — OpenAI plugin skill contracts + local validator registry++- Implemented additive structured `contract.yaml` + `agents/openai.yaml` bundles for all 13 official skills, a portable root `.codex-plugin/plugin.json`, local artifact validators, compact contract-aware skill discovery, and full-MCP `mso/actionContract` lifecycle metadata on selected stateful tools.+- WHY: make routing, target, source-of-truth, validation, confirmation, concurrency, and OpenAI presentation machine-readable without replacing MSO's stronger trust/provenance, bounded scopes, CAS/revision guards, workflow isolation, evidence receipts, dynamic project MCP boundaries, explicit confirmations, or shell escape hatch.+- Kept all 112 ChatGPT actions and the 97,350-byte compact action profile; per-tool action contracts stay on the full MCP descriptor while OpenAI receives the structured workflow policy through skill resources, preserving the scanner budget without hiding capabilities.+- Re-reviewed the refreshed Shopify reference implementation: adopted its offline/local schema-validation and per-skill OpenAI descriptor ideas, but did not copy external prompt/code telemetry. The live OAuth `/mcp` app remains a separate connection from the skill-only Codex/OpenAI plugin package.+## 2026-09-15 — Shell-native server status + CI security fixesThe global floating `Live server · owner` badge is gone. MSO now contributes one `systemStatus` feature into AppShell and each shell places that shared status in native chrome: macOS menu bar, Windows taskbar, iOS/Android top status area, and the Dashboard header. Auth/session logic remains single-source in the consumer feature; generic AppShell owns only the slot placement.diff --git a/lib/capabilities/tool.ts b/lib/capabilities/tool.tsindex 3b37b886..fb9ff951 100644--- a/lib/capabilities/tool.ts+++ b/lib/capabilities/tool.ts@@ -37,6 +37,24 @@ export function isCapabilityDirectResult(value: unknown): value is CapabilityDirreturn Boolean(value && typeof value === "object" && (value as CapabilityDirectResult).__mcpDirect === true);}+export type CapabilityActionContract = {+ /** Contract version; omitted on declarations and normalized to 1 for transport metadata. */+ version?: 1;+ phase?: "discover" | "read" | "validate" | "execute" | "mutate" | "verify";+ /** Semantic target/surface such as project-mcp, filesystem-text, workflow, or artifact-ingress. */+ target?: string;+ sourceOfTruth?: "live" | "local" | "snapshot" | "provider";+ /** Named capabilities or checks that should precede this action. */+ discover?: string[];+ /** Validator/policy identifiers. They are metadata, not arbitrary commands. */+ validators?: string[];+ /** Named read/status capabilities expected after mutation/execution. */+ verify?: string[];+ confirmation?: "none" | "contextual" | "explicit";+ concurrency?: "none" | "hash" | "revision" | "compare" | "provider" | "contextual";+ presentation?: "structured" | "tool-owned" | "ui-owned" | "hybrid";+};+export interface CapabilityRunContext {actor?: string;principal?: string;@@ -68,6 +86,8 @@ export interface CapabilityTool {annotations?: { readOnlyHint?: boolean; destructiveHint?: boolean; openWorldHint?: boolean; idempotentHint?: boolean };securitySchemes?: Array<{ type: "oauth2"; scopes: string[] } | { type: "noauth" }>;meta?: Record<string, unknown>;+ /** Optional compact lifecycle contract surfaced to clients as mso/actionContract metadata. */+ actionContract?: CapabilityActionContract;run: (args: Record<string, unknown>, context: CapabilityRunContext) => Promise<unknown>;audit?: {action: AuditAction;diff --git a/lib/mcp/dispatch.test.ts b/lib/mcp/dispatch.test.tsindex e03bea48..05359e8b 100644--- a/lib/mcp/dispatch.test.ts+++ b/lib/mcp/dispatch.test.ts@@ -62,7 +62,11 @@ describe("protocol", () => {const r = await dispatch({ id: 1, method: "tools/list" }, "write");const tools = (r.result as { tools: Array<{ name: string; _meta?: Record<string, unknown> }> }).tools;const upload = tools.find((tool) => tool.name === "fs_upload_file");- expect(upload?._meta).toEqual({ "openai/fileParams": ["file"], securitySchemes: [{ type: "oauth2", scopes: ["write"] }] });+ expect(upload?._meta).toMatchObject({+ "openai/fileParams": ["file"],+ securitySchemes: [{ type: "oauth2", scopes: ["write"] }],+ "mso/actionContract": { version: 1, phase: "mutate", target: "artifact-ingress" },+ });});it("answers ping and initialized", async () => {diff --git a/lib/mcp/skills-extension.test.ts b/lib/mcp/skills-extension.test.tsindex f6894e8e..c1fc908d 100644--- a/lib/mcp/skills-extension.test.ts+++ b/lib/mcp/skills-extension.test.ts@@ -18,6 +18,8 @@ describe("MCP Skills extension", () => {expect(skill.frontmatter.description).toEqual(expect.any(String));expect(skill.resources.length).toBeGreaterThan(0);expect(skill.resources[0].uri).toBe(skill.uri);+ expect(skill.resources.some((resource) => resource.uri.endsWith("/contract.yaml"))).toBe(true);+ expect(skill.resources.some((resource) => resource.uri.endsWith("/agents/openai.yaml"))).toBe(true);for (const resource of skill.resources) expect(resource.digest).toMatch(/^sha256:[a-f0-9]{64}$/);}});diff --git a/lib/mcp/skills-extension.ts b/lib/mcp/skills-extension.tsindex 7df1f333..7a4936f1 100644--- a/lib/mcp/skills-extension.ts+++ b/lib/mcp/skills-extension.ts@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";import { promises as fs } from "node:fs";import path from "node:path";import { parse as parseYaml } from "yaml";+import { validateSkillArtifact } from "@/lib/skills/skill-artifact-validators";import { readBoundedRegularBuffer } from "@/lib/host/bounded-read";export const MCP_SKILLS_EXTENSION = "io.modelcontextprotocol/skills";@@ -117,6 +118,14 @@ async function loadSkill(name: string): Promise<LoadedSkill> {const files = await collectFiles(root, name);const skillMd = files[0];const frontmatter = parseFrontmatter(skillMd.data.toString("utf8"), name);+ const contractFile = files.find((file) => file.relative === "contract.yaml");+ if (!contractFile) throw new Error(`published skill ${name} is missing contract.yaml`);+ const contractValidation = validateSkillArtifact("skill-contract-v1", parseYaml(contractFile.data.toString("utf8")));+ if (!contractValidation.ok) throw new Error(`published skill ${name} has invalid contract.yaml: ${contractValidation.errors.join("; ")}`);+ const openAiFile = files.find((file) => file.relative === "agents/openai.yaml");+ if (!openAiFile) throw new Error(`published skill ${name} is missing agents/openai.yaml`);+ const openAiValidation = validateSkillArtifact("openai-skill-interface-v1", parseYaml(openAiFile.data.toString("utf8")));+ if (!openAiValidation.ok) throw new Error(`published skill ${name} has invalid agents/openai.yaml: ${openAiValidation.errors.join("; ")}`);return { name, files, entry: { uri: skillMd.uri, frontmatter, resources: files.map(({ uri, digest }) => ({ uri, digest })) } };}diff --git a/lib/mcp/tool-contract.test.ts b/lib/mcp/tool-contract.test.tsindex be8058c7..60dbd758 100644--- a/lib/mcp/tool-contract.test.ts+++ b/lib/mcp/tool-contract.test.ts@@ -30,4 +30,14 @@ describe("MCP advertised tool contract", () => {expect(toolDescriptor(fileList!, "chatgpt").outputSchema).toEqual({ type: "object", properties: { result: {} }, required: ["result"], additionalProperties: false });});+ it("publishes additive action contracts on full MCP descriptors without bloating the compact ChatGPT scanner", () => {+ const write = TOOLS.find((tool) => tool.name === "fs_write");+ expect(write).toBeDefined();+ const full = toolDescriptor(write!, "full");+ expect(full._meta["mso/actionContract"]).toMatchObject({+ version: 1, phase: "mutate", target: "filesystem-text", concurrency: "hash",+ });+ expect(toolDescriptor(write!, "chatgpt")._meta).not.toHaveProperty("mso/actionContract");+ });+});diff --git a/lib/mcp/tool-contract.ts b/lib/mcp/tool-contract.tsindex 6f59df23..4b1cbcc0 100644--- a/lib/mcp/tool-contract.ts+++ b/lib/mcp/tool-contract.ts@@ -91,6 +91,11 @@ export function toolSecuritySchemes(tool: McpTool): McpSecurityScheme[] {return tool.securitySchemes ?? [{ type: "oauth2", scopes: [tool.scope] }];}+export function actionContractForTool(tool: McpTool): Record<string, unknown> | undefined {+ if (!tool.actionContract) return undefined;+ return { version: 1, ...tool.actionContract };+}+export function toolAllowedForProfile(_name: string, _profile: McpToolProfile = "full"): boolean {return true;}@@ -118,7 +123,11 @@ function compactSchema(value: unknown): unknown {export function toolDescriptor(tool: McpTool, profile: McpToolProfile = "full") {const securitySchemes = toolSecuritySchemes(tool);- const meta = { ...(tool.meta ?? {}), securitySchemes };+ // ChatGPT already receives the structured contract through published skill resources.+ // Keep action-level contracts on the full MCP descriptor so the compact ChatGPT+ // scanner stays below its deliberately strict byte budget without hiding any tools.+ const actionContract = profile === "full" ? actionContractForTool(tool) : undefined;+ const meta = { ...(tool.meta ?? {}), securitySchemes, ...(actionContract ? { "mso/actionContract": actionContract } : {}) };const compact = profile === "chatgpt";const outputSchema = outputSchemaForProfile(tool, profile);return {diff --git a/lib/mcp/tools-discovery.ts b/lib/mcp/tools-discovery.tsindex 84f4f34c..277b400f 100644--- a/lib/mcp/tools-discovery.ts+++ b/lib/mcp/tools-discovery.ts@@ -1,5 +1,6 @@import { listProjects, projectCapabilities, publicProjectMcpServers, readProjectMcpServers, resolveProjectHint, PROJECT_LIMITS } from "@/lib/host/projects-api";import { catalogSkillsDetailed, resolveSkill, readSkillFile, skillIsExecutableByDefault, SKILL_SCAN_LIMITS } from "@/lib/skills/catalog";+import { compactSkillContract } from "@/lib/skills/skill-contract";import { type McpTool, str, opt, S, READ_ONLY } from "./tool-kit";// GLOBAL discovery: every project container the owner configured, and every skill@@ -124,6 +125,7 @@ export const DISCOVERY_TOOLS: McpTool[] = [instructionsReadable: skillIsExecutableByDefault(skill),...(skill.project ? { project: skill.project } : {}),...(skill.provenance ? { provenance: skill.provenance } : {}),+ ...(skill.contract ? { contract: compactSkillContract(skill.contract) } : {}),})),};},@@ -155,6 +157,7 @@ export const DISCOVERY_TOOLS: McpTool[] = [const meta = {id: skill.id, name: skill.name, description: skill.description, source: skill.source, trust: skill.trust,...(skill.project ? { project: skill.project } : {}),+ ...(skill.contract ? { contract: skill.contract } : {}),};if (!skillIsExecutableByDefault(skill)) {return {diff --git a/lib/mcp/tools-flows.ts b/lib/mcp/tools-flows.tsindex d6ec88e9..46532977 100644--- a/lib/mcp/tools-flows.ts+++ b/lib/mcp/tools-flows.ts@@ -26,12 +26,14 @@ export const FLOW_TOOLS: McpTool[] = [description: "Discover project API/MCP flows, schemas and ordered steps. Inspect before flow_run.",chatgptDescription: "Discover project flows and inputs before flow_run.",annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },+ actionContract: { phase: "discover", target: "project-flow", sourceOfTruth: "live", validators: ["project-selection", "flow-definition"], confirmation: "none", concurrency: "revision", presentation: "structured" },inputSchema: S({ project, flow }, ["project"]),run: async a => { const { project: p, flows, revision } = await flowCatalog(str(a, "project"), typeof a.flow === "string" ? a.flow : undefined); return { project: p.id, revision, flows }; } },{ name: "flow_run", title: "Run Automation Flow", scope: "exec",description: "Run an inspected project flow with exact input/idempotency key. Returns a durable receipt; failed writes are not auto-retried.",chatgptDescription: "Run an inspected flow; use flow_status for its receipt.",- annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true }, audit: { action: "exec.run", targetArg: "flow" },+ annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },+ actionContract: { phase: "execute", target: "project-flow", sourceOfTruth: "live", discover: ["flow_catalog"], validators: ["flow-input-schema", "idempotency-key"], verify: ["flow_status"], confirmation: "contextual", concurrency: "compare", presentation: "structured" }, audit: { action: "exec.run", targetArg: "flow" },limit: { key: "flow.run", max: 20, windowMs: 60_000 },inputSchema: S({ project, flow, input: { type: "object", additionalProperties: true }, idempotency_key: { type: "string", minLength: 1, maxLength: 128 } }, ["project", "flow", "input", "idempotency_key"]),run: async (a, context) => {@@ -48,7 +50,8 @@ export const FLOW_TOOLS: McpTool[] = [{ name: "flow_manage", limit: { key: "flow.manage", max: 20, windowMs: 60_000 }, title: "Save Project Automation", scope: "write",description: "Create/update/delete a project flow with flow_catalog revision. Built-ins are immutable; credentials are forbidden.",chatgptDescription: "Save/delete a project flow by revision; no credentials.",- annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: false }, audit: { action: "fs.write", targetArg: "project" },+ annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: false },+ actionContract: { phase: "mutate", target: "project-flow", sourceOfTruth: "live", discover: ["flow_catalog"], validators: ["flow-definition", "revision"], verify: ["flow_catalog"], confirmation: "contextual", concurrency: "revision", presentation: "structured" }, audit: { action: "fs.write", targetArg: "project" },inputSchema: S({ project, flow, action: { type: "string", enum: ["upsert", "delete"] }, revision: { type: "string" }, definition: { type: "object", additionalProperties: true } }, ["project", "flow", "action", "revision"]),run: async a => {const id = str(a, "flow");diff --git a/lib/mcp/tools-forge.ts b/lib/mcp/tools-forge.tsindex acaec636..7e9f123c 100644--- a/lib/mcp/tools-forge.ts+++ b/lib/mcp/tools-forge.ts@@ -112,6 +112,7 @@ export const FORGE_TOOLS: McpTool[] = ["Use only after reviewing tool_forge_candidates/evaluation evidence.",scope: "exec",annotations: { destructiveHint: true, openWorldHint: false },+ actionContract: { phase: "mutate", target: "tool-forge-candidate", sourceOfTruth: "live", discover: ["tool_forge_candidates"], validators: ["fresh-evaluation", "target-drift", "tool-drift", "image-drift"], verify: ["tool_forge_candidates"], confirmation: "explicit", concurrency: "compare", presentation: "structured" },limit: { key: "tool.forge.promote", max: 6, windowMs: 60_000 },audit: { action: "tool.forge.promote" as const, targetArg: "candidate_id" },inputSchema: S({diff --git a/lib/mcp/tools-mutate.ts b/lib/mcp/tools-mutate.tsindex 21d56f9b..788c6fa0 100644--- a/lib/mcp/tools-mutate.ts+++ b/lib/mcp/tools-mutate.ts@@ -19,6 +19,7 @@ export const MUTATE_TOOLS: McpTool[] = ["Bounded to OS_FS_WRITE_ROOTS (home + ~/projects by default).",scope: "write",annotations: { idempotentHint: true },+ actionContract: { phase: "mutate", target: "filesystem-text", sourceOfTruth: "live", discover: ["fs_read"], validators: ["path-policy", "sha256-cas"], verify: ["fs_read"], confirmation: "contextual", concurrency: "hash", presentation: "structured" },inputSchema: S({...PATH_P,content: { type: "string" },@@ -37,6 +38,7 @@ export const MUTATE_TOOLS: McpTool[] = [description: "Import one ChatGPT conversation/generated PNG, WebP, JPEG, JSON or ZIP file through openai/fileParams. MSO validates OAuth-bound temporary URL provenance, type, size and content before writing inside OS_FS_WRITE_ROOTS. Verified ChatGPT callbacks may use rotating Azure file hosts; generic MCP clients require exact allowlisting. Same bytes are idempotent; different existing bytes fail by default. conflict=rename is deterministic; conflict=replace requires expected_sha256.",scope: "write",annotations: { destructiveHint: true, openWorldHint: true, idempotentHint: true },+ actionContract: { phase: "mutate", target: "artifact-ingress", sourceOfTruth: "provider", validators: ["openai-file-provenance", "content-type", "content-size", "content-structure", "destination-policy"], verify: ["fs_read"], confirmation: "contextual", concurrency: "hash", presentation: "structured" },meta: { "openai/fileParams": ["file"] },inputSchema: S({file: {diff --git a/lib/mcp/tools-project-mcp.ts b/lib/mcp/tools-project-mcp.tsindex 54db95f3..bf6c7367 100644--- a/lib/mcp/tools-project-mcp.ts+++ b/lib/mcp/tools-project-mcp.ts@@ -12,6 +12,7 @@ export const PROJECT_MCP_TOOLS: McpTool[] = [chatgptDescription: "Discover a declared project MCP through its private connection. Dynamic tools stay project-scoped.",scope: "exec",annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true, idempotentHint: false },+ actionContract: { phase: "discover", target: "project-mcp", sourceOfTruth: "provider", discover: ["project_capabilities"], validators: ["project-selection", "private-connection"], confirmation: "none", concurrency: "provider", presentation: "structured" },audit: { action: "exec.run" as const, targetArg: "server" },limit: { key: "projects.mcp.read", max: 30, windowMs: 60_000 },inputSchema: S({@@ -35,6 +36,7 @@ export const PROJECT_MCP_TOOLS: McpTool[] = [scope: "exec",outputSchema: { type: "object", properties: { result: { type: "object" } }, required: ["result"], additionalProperties: false },annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true, idempotentHint: false },+ actionContract: { phase: "execute", target: "project-mcp", sourceOfTruth: "provider", discover: ["project_capabilities", "project_mcp_tools"], validators: ["dynamic-input-schema", "project-scope", "private-connection"], confirmation: "contextual", concurrency: "provider", presentation: "tool-owned" },limit: { key: "projects.mcp.call", max: 30, windowMs: 60_000 },audit: { action: "exec.run" as const, targetArg: "server" },result: { maxTextBytes: 64 * 1024, overflowHint: "Project MCP result was compacted; request a narrower project tool call." },diff --git a/lib/mcp/tools-project-runtime.ts b/lib/mcp/tools-project-runtime.tsindex 45edf13e..a3ee50f2 100644--- a/lib/mcp/tools-project-runtime.ts+++ b/lib/mcp/tools-project-runtime.ts@@ -11,6 +11,7 @@ export const PROJECT_RUNTIME_TOOLS: McpTool[] = [title: "Get Convex Database Status",description: "Get Convex status for one validated project through the project's installed official Convex MCP server. Supports cloud/local/self-hosted project configuration. MSO pins --project-dir to the selected project and refuses cross-project deployment selectors.",scope: "exec", annotations: { destructiveHint: false, openWorldHint: true, idempotentHint: true },+ actionContract: { phase: "discover", target: "project-database", sourceOfTruth: "provider", validators: ["project-selection", "deployment-scope"], confirmation: "none", concurrency: "provider", presentation: "structured" },limit: { key: "projects.mcp.read", max: 30, windowMs: 60_000 }, audit: { action: "exec.run" as const, targetArg: "project" },inputSchema: S({ project: { type: "string" }, deployment: { type: "string", description: "Optional dev, prod, local, staging-like name, or dev/<name>." } }, ["project"]),run: async (a) => {@@ -25,6 +26,7 @@ export const PROJECT_RUNTIME_TOOLS: McpTool[] = [title: "List Convex Database Tools",description: "List the supported official Convex MCP schemas for one selected project/deployment. Use this before project_database_call so dynamic Convex schemas stay out of MSO's global ChatGPT catalog.",scope: "exec", annotations: { destructiveHint: false, openWorldHint: true, idempotentHint: true },+ actionContract: { phase: "discover", target: "project-database", sourceOfTruth: "provider", discover: ["project_database_status"], validators: ["project-selection", "deployment-scope"], confirmation: "none", concurrency: "provider", presentation: "structured" },limit: { key: "projects.mcp.read", max: 30, windowMs: 60_000 }, audit: { action: "exec.run" as const, targetArg: "project" },inputSchema: S({ project: { type: "string" }, deployment: { type: "string" } }, ["project"]),run: async (a) => {@@ -37,6 +39,7 @@ export const PROJECT_RUNTIME_TOOLS: McpTool[] = [title: "Call Convex Database Tool",description: "Call one supported official Convex MCP tool for the selected project. Dynamic arguments must match project_database_tools. MSO removes projectDir overrides and refuses cross-project deployment selectors; Convex production PII/write restrictions remain fail-closed because MSO never enables dangerous production flags automatically.",scope: "exec", annotations: { destructiveHint: true, openWorldHint: true, idempotentHint: false },+ actionContract: { phase: "execute", target: "project-database", sourceOfTruth: "provider", discover: ["project_database_status", "project_database_tools"], validators: ["dynamic-input-schema", "project-selection", "deployment-scope", "provider-production-policy"], confirmation: "contextual", concurrency: "provider", presentation: "tool-owned" },limit: { key: "projects.mcp.call", max: 30, windowMs: 60_000 }, audit: { action: "exec.run" as const, targetArg: "tool" },result: { maxTextBytes: 96 * 1024, overflowHint: "Convex result was compacted; use a narrower query or table/function target." },inputSchema: S({diff --git a/lib/mcp/tools-project-state.ts b/lib/mcp/tools-project-state.tsindex 54014360..4e56298b 100644--- a/lib/mcp/tools-project-state.ts+++ b/lib/mcp/tools-project-state.ts@@ -108,6 +108,7 @@ export const PROJECT_STATE_TOOLS: McpTool[] = [title: "Set Project Knowledge",description: `Replace .mso/KNOWLEDGE.md for one project (max ${PROJECT_KNOWLEDGE_MAX_BYTES} UTF-8 bytes). Read project_knowledge_get first and pass expected_sha256 to avoid overwriting concurrent changes. Empty content clears the knowledge text but keeps the canonical file.`,scope: "write", annotations: { destructiveHint: true, idempotentHint: true },+ actionContract: { phase: "mutate", target: "project-knowledge", sourceOfTruth: "live", discover: ["project_knowledge_get"], validators: ["content-limit", "sha256-cas"], verify: ["project_knowledge_get"], confirmation: "contextual", concurrency: "hash", presentation: "structured" },limit: { key: "project.knowledge", max: 30, windowMs: 60_000 }, audit: { action: "fs.write" as const, targetArg: "project" },inputSchema: S({project: { type: "string" }, content: { type: "string", maxLength: PROJECT_KNOWLEDGE_MAX_BYTES },diff --git a/lib/mcp/tools-workflow-lifecycle.ts b/lib/mcp/tools-workflow-lifecycle.tsindex 7ee660e3..87207a54 100644--- a/lib/mcp/tools-workflow-lifecycle.ts+++ b/lib/mcp/tools-workflow-lifecycle.ts@@ -38,6 +38,7 @@ export const WORKFLOW_LIFECYCLE_TOOLS: McpTool[] = [description: "Cancel one exact active workflow without saving a learned recipe.",scope: "write",annotations: { idempotentHint: false },+ actionContract: { phase: "mutate", target: "workflow", sourceOfTruth: "live", validators: ["workflow-ownership"], confirmation: "contextual", concurrency: "contextual", presentation: "structured" },limit: { key: "workflow.memory", max: 30, windowMs: 60_000 },audit: { action: "workflow.cancel" as const, targetArg: "workflow_id" },inputSchema: S({@@ -58,6 +59,7 @@ export const WORKFLOW_LIFECYCLE_TOOLS: McpTool[] = [description: "Finish one verified workflow. MSO saves redacted evidence, memory, recipe quality and safe automation-learning metadata.",scope: "write",annotations: { idempotentHint: false },+ actionContract: { phase: "verify", target: "workflow", sourceOfTruth: "live", validators: ["evidence-receipt", "risk-policy"], confirmation: "none", concurrency: "contextual", presentation: "structured" },limit: { key: "workflow.memory", max: 30, windowMs: 60_000 },audit: { action: "workflow.finish" as const, targetArg: "workflow_id" },inputSchema: S({diff --git a/lib/mcp/tools-workflow-start.ts b/lib/mcp/tools-workflow-start.tsindex 5b8f9b20..4e0ff97d 100644--- a/lib/mcp/tools-workflow-start.ts+++ b/lib/mcp/tools-workflow-start.ts@@ -103,7 +103,7 @@ export const WORKFLOW_START_TOOL: McpTool =hits: search.hits.slice(0, 5).map((hit) => ({kind: hit.kind, id: hit.id, name: hit.name, score: hit.score,description: hit.description.slice(0, 600), source: hit.source, trust: hit.trust, scope: hit.scope, project: hit.project,- successRate: hit.successRate, attempts: hit.attempts, missingTools: hit.missingTools,+ successRate: hit.successRate, attempts: hit.attempts, missingTools: hit.missingTools, contract: hit.contract,})),recommendedRecipe: search.recommendedRecipe ? {...search.recommendedRecipe,diff --git a/lib/skills/catalog-scan.ts b/lib/skills/catalog-scan.tsindex ba2dbd6d..0cb8be8e 100644--- a/lib/skills/catalog-scan.ts+++ b/lib/skills/catalog-scan.ts@@ -8,6 +8,7 @@ import path from "path";import { readBoundedRegularFile } from "@/lib/host/bounded-read";import { SKILL_FILE, SKILL_SCAN_LIMITS, type ProjectRef, type SkillInfo, type SkillSource, type SkillTrust } from "./catalog-types";import { projectSkillTrust } from "./project-skills";+import { readSkillContract } from "./skill-contract";export type RootSpec = {path: string;@@ -129,6 +130,7 @@ export async function scanRoot(trust = verified.trust;provenance = verified.provenance;}+ const contract = trust === "untrusted" ? undefined : await readSkillContract(dir).catch(() => undefined);found.push({priority: spec.priority,skill: {@@ -140,6 +142,7 @@ export async function scanRoot(trust,...(spec.project ? { project: spec.project } : {}),...(provenance ? { provenance } : {}),+ ...(contract ? { contract } : {}),},});}diff --git a/lib/skills/catalog-types.ts b/lib/skills/catalog-types.tsindex 4e0a6a34..264fb8dc 100644--- a/lib/skills/catalog-types.ts+++ b/lib/skills/catalog-types.ts@@ -1,3 +1,4 @@+import type { SkillContract } from "./skill-contract-types";// The catalog's shared vocabulary. Split from catalog.ts so per-project discovery// can depend on the types without an import cycle back through the scanner.@@ -51,6 +52,8 @@ export type SkillInfo = {version?: string;sha256?: string;};+ /** Optional structured execution/routing contract. Parsed only for trusted skills. */+ contract?: SkillContract;};/** A resumable position in a skill scan. Positional in readdir order, like the projectdiff --git a/lib/skills/search.ts b/lib/skills/search.tsindex 5504cea3..77c403fb 100644--- a/lib/skills/search.ts+++ b/lib/skills/search.ts@@ -1,6 +1,7 @@import { catalogSkillsDetailed, readSkillFile, type ProjectRef, type SkillInfo, type SkillScanReport } from "./catalog";import { listLearnedRecipes, type LearnedRecipe, type RecipeAccess } from "@/lib/workflow";import { embedSkillText, hybridSemanticScore, prepareSemanticQuery, SKILL_EMBEDDING_VERSION } from "./semantic";+import { compactSkillContract } from "./skill-contract";export type SkillSearchToolDoc = {name: string;@@ -25,6 +26,7 @@ export type SkillSearchHit = {attempts?: number;steps?: Array<{ tool: string; target?: string; args?: Record<string, string | number | boolean>; durationMs?: number }>;missingTools?: string[];+ contract?: ReturnType<typeof compactSkillContract>;};export type SkillSearchOptions = {@@ -99,7 +101,8 @@ export async function searchSkillMemory(query: string, options: SkillSearchOptiofor (const skill of skills) {if (!options.includeUntrusted && skill.trust === "untrusted") continue;const content = skill.trust === "untrusted" ? "" : (await readSkillFile(skill.path))?.slice(0, 18_000) ?? "";- const text = `${skill.id}\n${skill.name}\n${skill.project?.name ?? ""}\n${skill.description}\n${content}`;+ const contractText = skill.contract ? JSON.stringify(compactSkillContract(skill.contract)) : "";+ const text = `${skill.id}\n${skill.name}\n${skill.project?.name ?? ""}\n${skill.description}\n${contractText}\n${content}`;hits.push({kind: "skill",id: skill.id,@@ -109,6 +112,7 @@ export async function searchSkillMemory(query: string, options: SkillSearchOptiodescription: skill.description,source: skill.source,trust: skill.trust,+ ...(skill.contract ? { contract: compactSkillContract(skill.contract) } : {}),});}diff --git a/lib/skills/skill-artifact-validators.ts b/lib/skills/skill-artifact-validators.tsnew file mode 100644index 00000000..5d4f4065--- /dev/null+++ b/lib/skills/skill-artifact-validators.ts@@ -0,0 +1,38 @@+import { parseSkillContract } from "./skill-contract";++export type SkillArtifactKind = "skill-contract-v1" | "openai-skill-interface-v1";+export type SkillArtifactValidation = { ok: true; value: unknown } | { ok: false; errors: string[] };++type Validator = (value: unknown) => unknown;+const object = (value: unknown): value is Record<string, unknown> => Boolean(value && typeof value === "object" && !Array.isArray(value));++function validateOpenAiSkillInterface(value: unknown) {+ if (!object(value)) throw new Error("OpenAI skill descriptor must be an object");+ if (!object(value.interface)) throw new Error("OpenAI skill descriptor requires interface");+ const required = ["display_name", "short_description", "default_prompt"] as const;+ for (const key of required) {+ const field = value.interface[key];+ if (typeof field !== "string" || !field.trim()) throw new Error(`interface.${key} must be a non-empty string`);+ }+ if (value.interface.brand_color !== undefined && (typeof value.interface.brand_color !== "string" || !/^#[0-9a-fA-F]{6}$/.test(value.interface.brand_color))) {+ throw new Error("interface.brand_color must be a six-digit hex color when provided");+ }+ return value;+}++const REGISTRY: Record<SkillArtifactKind, Validator> = {+ "skill-contract-v1": parseSkillContract,+ "openai-skill-interface-v1": validateOpenAiSkillInterface,+};++export function skillArtifactValidatorIds(): SkillArtifactKind[] {+ return Object.keys(REGISTRY) as SkillArtifactKind[];+}++export function validateSkillArtifact(kind: SkillArtifactKind, value: unknown): SkillArtifactValidation {+ try {+ return { ok: true, value: REGISTRY[kind](value) };+ } catch (error) {+ return { ok: false, errors: [error instanceof Error ? error.message : String(error)] };+ }+}diff --git a/lib/skills/skill-contract-types.ts b/lib/skills/skill-contract-types.tsnew file mode 100644index 00000000..3998e732--- /dev/null+++ b/lib/skills/skill-contract-types.ts@@ -0,0 +1,40 @@+export type SkillContractMode = "read" | "write" | "execute" | "mixed";+export type SkillContractSourceOfTruth = "live" | "local" | "snapshot" | "mixed";+export type SkillContractRefresh = "always" | "before-write" | "contextual";+export type SkillContractConfirmation = "none" | "contextual" | "explicit";+export type SkillContractConcurrency = "none" | "hash" | "revision" | "compare" | "contextual";+export type SkillContractPresentationAuthority = "tool" | "model" | "hybrid";++export type SkillContract = {+ version: 1;+ routing: {+ use_when: string[];+ do_not_use_when: string[];+ fallback?: boolean;+ prefer_over?: string[];+ handoff_to?: string[];+ };+ context: {+ target: string;+ mode: SkillContractMode;+ actor?: string;+ };+ lifecycle?: {+ discover?: string[];+ validate?: string[];+ verify?: string[];+ };+ state?: {+ source_of_truth: SkillContractSourceOfTruth;+ refresh: SkillContractRefresh;+ };+ safety?: {+ risk: "low" | "medium" | "high";+ confirmation: SkillContractConfirmation;+ concurrency: SkillContractConcurrency;+ };+ presentation?: {+ authority: SkillContractPresentationAuthority;+ renderer?: string;+ };+};diff --git a/lib/skills/skill-contract.test.ts b/lib/skills/skill-contract.test.tsnew file mode 100644index 00000000..00199ff4--- /dev/null+++ b/lib/skills/skill-contract.test.ts@@ -0,0 +1,31 @@+import { describe, expect, it, vi } from "vitest";+vi.mock("server-only", () => ({}));+const { parseSkillContract, compactSkillContract } = await import("./skill-contract");+const { validateSkillArtifact, skillArtifactValidatorIds } = await import("./skill-artifact-validators");++const contract = {+ version: 1,+ routing: { use_when: ["write guarded text"], do_not_use_when: ["binary data"], fallback: false },+ context: { target: "filesystem-text", mode: "write", actor: "operator" },+ lifecycle: { discover: ["fs_read"], validate: ["sha256-cas"], verify: ["fs_read"] },+ state: { source_of_truth: "live", refresh: "before-write" },+ safety: { risk: "medium", confirmation: "contextual", concurrency: "hash" },+ presentation: { authority: "hybrid" },+};++describe("structured skill artifacts", () => {+ it("parses and compacts the portable contract without weakening its safety fields", () => {+ const parsed = parseSkillContract(contract);+ expect(parsed.safety).toEqual({ risk: "medium", confirmation: "contextual", concurrency: "hash" });+ expect(compactSkillContract(parsed)).toMatchObject({ target: "filesystem-text", mode: "write", risk: "medium", concurrency: "hash" });+ });++ it("fails closed on invalid contract enums and validates OpenAI skill descriptors locally", () => {+ expect(() => parseSkillContract({ ...contract, safety: { ...contract.safety, concurrency: "provider" } })).toThrow(/concurrency/);+ expect(skillArtifactValidatorIds()).toEqual(["skill-contract-v1", "openai-skill-interface-v1"]);+ expect(validateSkillArtifact("openai-skill-interface-v1", {+ interface: { display_name: "MSO", short_description: "Operate MSO", default_prompt: "Use $mso." },+ })).toMatchObject({ ok: true });+ expect(validateSkillArtifact("openai-skill-interface-v1", { interface: { display_name: "MSO" } })).toMatchObject({ ok: false });+ });+});diff --git a/lib/skills/skill-contract.ts b/lib/skills/skill-contract.tsnew file mode 100644index 00000000..45cfb6d6--- /dev/null+++ b/lib/skills/skill-contract.ts@@ -0,0 +1,119 @@+import path from "node:path";+import { parse as parseYaml } from "yaml";+import { readBoundedRegularFile } from "@/lib/host/bounded-read";+import type {+ SkillContract, SkillContractMode, SkillContractSourceOfTruth, SkillContractRefresh,+ SkillContractConfirmation, SkillContractConcurrency, SkillContractPresentationAuthority,+} from "./skill-contract-types";++const CONTRACT_FILE = "contract.yaml";+const CONTRACT_MAX_BYTES = 32 * 1024;+const MODES = new Set(["read", "write", "execute", "mixed"]);+const SOURCES = new Set(["live", "local", "snapshot", "mixed"]);+const REFRESH = new Set(["always", "before-write", "contextual"]);+const RISKS = new Set(["low", "medium", "high"]);+const CONFIRMATIONS = new Set(["none", "contextual", "explicit"]);+const CONCURRENCY = new Set(["none", "hash", "revision", "compare", "contextual"]);+const AUTHORITIES = new Set(["tool", "model", "hybrid"]);++const object = (value: unknown): value is Record<string, unknown> => Boolean(value && typeof value === "object" && !Array.isArray(value));+const strings = (value: unknown, field: string, required = false): string[] | undefined => {+ if (value === undefined && !required) return undefined;+ if (!Array.isArray(value) || value.some((item) => typeof item !== "string" || !item.trim())) throw new Error(`${field} must be a non-empty string array`);+ return value.map((item) => item.trim());+};+const oneOf = (value: unknown, allowed: Set<string>, field: string): string => {+ if (typeof value !== "string" || !allowed.has(value)) throw new Error(`${field} must be one of: ${[...allowed].join(", ")}`);+ return value;+};+const optionalString = (value: unknown, field: string): string | undefined => {+ if (value === undefined) return undefined;+ if (typeof value !== "string" || !value.trim()) throw new Error(`${field} must be a non-empty string`);+ return value.trim();+};++/** Parse the portable, execution-neutral contract that accompanies trusted skills. */+export function parseSkillContract(value: unknown): SkillContract {+ if (!object(value)) throw new Error("skill contract must be an object");+ if (value.version !== 1) throw new Error("skill contract version must be 1");+ if (!object(value.routing)) throw new Error("skill contract routing is required");+ if (!object(value.context)) throw new Error("skill contract context is required");++ const routing = {+ use_when: strings(value.routing.use_when, "routing.use_when", true)!,+ do_not_use_when: strings(value.routing.do_not_use_when, "routing.do_not_use_when", true)!,+ ...(value.routing.fallback === undefined ? {} : typeof value.routing.fallback === "boolean" ? { fallback: value.routing.fallback } : (() => { throw new Error("routing.fallback must be boolean"); })()),+ ...(strings(value.routing.prefer_over, "routing.prefer_over") ? { prefer_over: strings(value.routing.prefer_over, "routing.prefer_over")! } : {}),+ ...(strings(value.routing.handoff_to, "routing.handoff_to") ? { handoff_to: strings(value.routing.handoff_to, "routing.handoff_to")! } : {}),+ };+ const context = {+ target: optionalString(value.context.target, "context.target") ?? (() => { throw new Error("context.target is required"); })(),+ mode: oneOf(value.context.mode, MODES, "context.mode") as SkillContractMode,+ ...(optionalString(value.context.actor, "context.actor") ? { actor: optionalString(value.context.actor, "context.actor")! } : {}),+ };++ let lifecycle: SkillContract["lifecycle"];+ if (value.lifecycle !== undefined) {+ if (!object(value.lifecycle)) throw new Error("lifecycle must be an object");+ lifecycle = {+ ...(strings(value.lifecycle.discover, "lifecycle.discover") ? { discover: strings(value.lifecycle.discover, "lifecycle.discover")! } : {}),+ ...(strings(value.lifecycle.validate, "lifecycle.validate") ? { validate: strings(value.lifecycle.validate, "lifecycle.validate")! } : {}),+ ...(strings(value.lifecycle.verify, "lifecycle.verify") ? { verify: strings(value.lifecycle.verify, "lifecycle.verify")! } : {}),+ };+ }++ let state: SkillContract["state"];+ if (value.state !== undefined) {+ if (!object(value.state)) throw new Error("state must be an object");+ state = {+ source_of_truth: oneOf(value.state.source_of_truth, SOURCES, "state.source_of_truth") as SkillContractSourceOfTruth,+ refresh: oneOf(value.state.refresh, REFRESH, "state.refresh") as SkillContractRefresh,+ };+ }++ let safety: SkillContract["safety"];+ if (value.safety !== undefined) {+ if (!object(value.safety)) throw new Error("safety must be an object");+ safety = {+ risk: oneOf(value.safety.risk, RISKS, "safety.risk") as "low" | "medium" | "high",+ confirmation: oneOf(value.safety.confirmation, CONFIRMATIONS, "safety.confirmation") as SkillContractConfirmation,+ concurrency: oneOf(value.safety.concurrency, CONCURRENCY, "safety.concurrency") as SkillContractConcurrency,+ };+ }++ let presentation: SkillContract["presentation"];+ if (value.presentation !== undefined) {+ if (!object(value.presentation)) throw new Error("presentation must be an object");+ presentation = {+ authority: oneOf(value.presentation.authority, AUTHORITIES, "presentation.authority") as SkillContractPresentationAuthority,+ ...(optionalString(value.presentation.renderer, "presentation.renderer") ? { renderer: optionalString(value.presentation.renderer, "presentation.renderer")! } : {}),+ };+ }++ return { version: 1, routing, context, ...(lifecycle ? { lifecycle } : {}), ...(state ? { state } : {}), ...(safety ? { safety } : {}), ...(presentation ? { presentation } : {}) };+}++export async function readSkillContract(skillDir: string): Promise<SkillContract | undefined> {+ const raw = await readBoundedRegularFile(path.join(skillDir, CONTRACT_FILE), CONTRACT_MAX_BYTES);+ if (!raw) return undefined;+ return parseSkillContract(parseYaml(raw));+}++export function compactSkillContract(contract: SkillContract) {+ return {+ target: contract.context.target,+ mode: contract.context.mode,+ useWhen: contract.routing.use_when.slice(0, 4),+ doNotUse: contract.routing.do_not_use_when.slice(0, 4),+ handoffTo: contract.routing.handoff_to?.slice(0, 4) ?? [],+ fallback: contract.routing.fallback === true,+ risk: contract.safety?.risk,+ confirmation: contract.safety?.confirmation,+ concurrency: contract.safety?.concurrency,+ sourceOfTruth: contract.state?.source_of_truth,+ refresh: contract.state?.refresh,+ discover: contract.lifecycle?.discover ?? [],+ validate: contract.lifecycle?.validate ?? [],+ verify: contract.lifecycle?.verify ?? [],+ };+}diff --git a/lib/skills/skill-flow-scripts.test.ts b/lib/skills/skill-flow-scripts.test.tsindex 817b8a6e..2e058380 100644--- a/lib/skills/skill-flow-scripts.test.ts+++ b/lib/skills/skill-flow-scripts.test.ts@@ -9,9 +9,12 @@ const run = promisify(execFile);const temp = await fs.mkdtemp(path.join(os.tmpdir(), "mso-skill-flow-"));const createScript = path.join(process.cwd(), "scripts", "create-skill-flow.mjs");const checkScript = path.join(process.cwd(), "scripts", "check-skill-flows.mjs");-const skillFile = path.join(temp, "mso-generated-test", "SKILL.md");+const skillDir = path.join(temp, "mso-generated-test");+const skillFile = path.join(skillDir, "SKILL.md");+const contractFile = path.join(skillDir, "contract.yaml");+const openAiFile = path.join(skillDir, "agents", "openai.yaml");-const command = (script: string, args: string[]) => run(process.execPath, [script, ...args], { cwd: process.cwd() });+const command = (script: string, args: string[]) => run("bun", [script, ...args], { cwd: process.cwd() });afterAll(async () => { await fs.rm(temp, { recursive: true, force: true }); });@@ -26,8 +29,12 @@ describe("workflow skill factory", () => {];await expect(command(createScript, args)).resolves.toMatchObject({ stdout: expect.stringContaining("created") });const source = await fs.readFile(skillFile, "utf8");+ const contract = await fs.readFile(contractFile, "utf8");+ const openAi = await fs.readFile(openAiFile, "utf8");expect(source).toContain("{{USE_WHEN}}");expect(source).toContain("{{EXPECTED_STATE}}");+ expect(contract).toContain("{{USE_WHEN}}");+ expect(openAi).toContain("Use $mso-generated-test");await expect(command(createScript, args)).rejects.toMatchObject({stderr: expect.stringContaining("already exists"),});@@ -35,10 +42,12 @@ describe("workflow skill factory", () => {it("fails closed until the generated workflow is made specific", async () => {await expect(command(checkScript, ["--root", temp])).rejects.toMatchObject({- stderr: expect.stringContaining("unresolved template placeholder"),+ stderr: expect.stringContaining("unresolved"),});const source = await fs.readFile(skillFile, "utf8");+ const contract = await fs.readFile(contractFile, "utf8");await fs.writeFile(skillFile, source.replace(/{{(?:USE_WHEN|DO_NOT_USE|REQUIRED_CONTEXT|EXPECTED_STATE|TARGETED_CHECKS|RUNTIME_PROOF|VISUAL_PROOF|DIFF_BOUNDARY)}}/g, "Explicit reviewed workflow guidance."));+ await fs.writeFile(contractFile, contract.replace(/{{(?:USE_WHEN|DO_NOT_USE)}}/g, "Explicit reviewed workflow guidance."));await expect(command(checkScript, ["--root", temp])).resolves.toMatchObject({stdout: expect.stringContaining("1 official skills valid"),});diff --git a/package.json b/package.jsonindex 1be4ffd6..71477efd 100644--- a/package.json+++ b/package.json@@ -14,7 +14,7 @@"typecheck": "tsc --noEmit","test": "vitest run","coverage": "vitest run --coverage",- "check": "node scripts/check-cycles.mjs && node scripts/check-architecture.mjs && node scripts/check-docs.mjs && node scripts/gen-comparison.mjs --check && node scripts/check-contrast.mjs && node scripts/check-skill-flows.mjs && bun run check:instance-literals",+ "check": "node scripts/check-cycles.mjs && node scripts/check-architecture.mjs && node scripts/check-docs.mjs && node scripts/gen-comparison.mjs --check && node scripts/check-contrast.mjs && bun scripts/check-skill-flows.mjs && bun run check:instance-literals","audit": "node scripts/audit.mjs","verify": "bun run typecheck && bun run lint && bun run coverage && bun run check && bun run audit","security:ultimate": "bash scripts/security-ultimate.sh",@@ -25,7 +25,7 @@"smoke": "vitest run --config scripts/e2e/vitest.config.mts","icons:app": "node scripts/gen-app-icons.mjs && python3 scripts/gen-remaining-platform-icons.py","skill:new": "node scripts/create-skill-flow.mjs",- "skill:check": "node scripts/check-skill-flows.mjs",+ "skill:check": "bun scripts/check-skill-flows.mjs","comparison": "node scripts/gen-comparison.mjs","bench:cognitive": "bun scripts/bench-cognitive-runtime.mjs","bench:memory": "bun scripts/bench-memory-retrieval.mjs",diff --git a/scripts/check-skill-flows.mjs b/scripts/check-skill-flows.mjsindex eef57663..06b7cc41 100755--- a/scripts/check-skill-flows.mjs+++ b/scripts/check-skill-flows.mjs@@ -1,6 +1,8 @@-#!/usr/bin/env node+#!/usr/bin/env bunimport { promises as fs } from "fs";import path from "path";+import { parse as parseYaml } from "yaml";+import { validateSkillArtifact } from "../lib/skills/skill-artifact-validators.ts";const args = process.argv.slice(2).filter((arg) => arg !== "--");const argValue = (flag, fallback) => {@@ -9,7 +11,10 @@ const argValue = (flag, fallback) => {};const repo = process.cwd();const skillsRoot = path.resolve(repo, argValue("--root", "claude-skills"));-const templatePath = path.resolve(repo, argValue("--template", "templates/mso-skill-flow/SKILL.md.template"));+const templateRoot = path.resolve(repo, argValue("--template-root", "templates/mso-skill-flow"));+const skillTemplatePath = path.join(templateRoot, "SKILL.md.template");+const contractTemplatePath = path.join(templateRoot, "contract.yaml.template");+const openAiTemplatePath = path.join(templateRoot, "agents/openai.yaml.template");const slug = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;const errors = [];const unquote = (value) => {@@ -20,22 +25,29 @@ const unquote = (value) => {return trimmed.replace(/^['"]|['"]$/g, "");};-const template = await fs.readFile(templatePath, "utf8").catch(() => "");-const templateTokens = [+const skillTemplate = await fs.readFile(skillTemplatePath, "utf8").catch(() => "");+const contractTemplate = await fs.readFile(contractTemplatePath, "utf8").catch(() => "");+const openAiTemplate = await fs.readFile(openAiTemplatePath, "utf8").catch(() => "");+const skillTemplateTokens = ["{{NAME}}", "{{DESCRIPTION_YAML}}", "{{RISK}}", "{{POLICY}}", "{{TITLE}}","{{USE_WHEN}}", "{{DO_NOT_USE}}", "{{REQUIRED_CONTEXT}}", "{{EXPECTED_STATE}}","{{TARGETED_CHECKS}}", "{{RUNTIME_PROOF}}", "{{VISUAL_PROOF}}", "{{DIFF_BOUNDARY}}",];-for (const token of templateTokens)- if (!template.includes(token)) errors.push(`template is missing ${token}`);+for (const token of skillTemplateTokens)+ if (!skillTemplate.includes(token)) errors.push(`SKILL template is missing ${token}`);+for (const token of ["{{USE_WHEN}}", "{{DO_NOT_USE}}", "{{TARGET}}", "{{RISK}}"])+ if (!contractTemplate.includes(token)) errors.push(`contract template is missing ${token}`);+for (const token of ["{{NAME}}", "{{TITLE}}", "{{OPENAI_SHORT_DESCRIPTION}}"])+ if (!openAiTemplate.includes(token)) errors.push(`OpenAI template is missing ${token}`);for (const heading of ["## Trigger and boundaries", "## Fast route", "## Tool routing", "## Execution flow", "## Verification contract", "## Failure and rollback", "## Recipe memory"])- if (!template.includes(heading)) errors.push(`template is missing heading: ${heading}`);+ if (!skillTemplate.includes(heading)) errors.push(`template is missing heading: ${heading}`);const entries = (await fs.readdir(skillsRoot, { withFileTypes: true }).catch(() => [])).filter((entry) => entry.isDirectory()).sort((a, b) => a.name.localeCompare(b.name));let checked = 0;for (const entry of entries) {- const file = path.join(skillsRoot, entry.name, "SKILL.md");+ const dir = path.join(skillsRoot, entry.name);+ const file = path.join(dir, "SKILL.md");const source = await fs.readFile(file, "utf8").catch(() => "");if (!source) continue;checked += 1;@@ -54,8 +66,52 @@ for (const entry of entries) {if (!["low", "medium", "high"].includes(risk ?? "")) errors.push(`${entry.name}: metadata.mso.risk must be low, medium, or high`);if (!slug.test(policy ?? "")) errors.push(`${entry.name}: metadata.mso.policy must be kebab-case`);if (!body.includes(`# /${entry.name}`)) errors.push(`${entry.name}: H1 must begin with # /${entry.name}`);- if (/{{[A-Z_]+}}/.test(source)) errors.push(`${entry.name}: unresolved template placeholder`);+ if (/{{[A-Z_]+}}/.test(source)) errors.push(`${entry.name}: unresolved SKILL template placeholder`);if (source.split("\n").length > 200) errors.push(`${entry.name}: exceeds the 200-line skill limit`);++ const contractPath = path.join(dir, "contract.yaml");+ const contractSource = await fs.readFile(contractPath, "utf8").catch(() => "");+ if (!contractSource) errors.push(`${entry.name}: missing contract.yaml`);+ else {+ if (/{{[A-Z_]+}}/.test(contractSource)) errors.push(`${entry.name}: unresolved contract template placeholder`);+ try {+ const raw = parseYaml(contractSource);+ const validated = validateSkillArtifact("skill-contract-v1", raw);+ if (!validated.ok) errors.push(...validated.errors.map((error) => `${entry.name}: contract ${error}`));+ else if (raw?.safety?.risk !== risk) errors.push(`${entry.name}: contract safety.risk must match metadata.mso.risk`);+ } catch (error) {+ errors.push(`${entry.name}: contract YAML parse failed: ${error instanceof Error ? error.message : String(error)}`);+ }+ }++ const openAiPath = path.join(dir, "agents/openai.yaml");+ const openAiSource = await fs.readFile(openAiPath, "utf8").catch(() => "");+ if (!openAiSource) errors.push(`${entry.name}: missing agents/openai.yaml`);+ else {+ if (/{{[A-Z_]+}}/.test(openAiSource)) errors.push(`${entry.name}: unresolved OpenAI descriptor placeholder`);+ try {+ const raw = parseYaml(openAiSource);+ const validated = validateSkillArtifact("openai-skill-interface-v1", raw);+ if (!validated.ok) errors.push(...validated.errors.map((error) => `${entry.name}: OpenAI descriptor ${error}`));+ const prompt = raw?.interface?.default_prompt;+ if (typeof prompt === "string" && !prompt.includes(`$${entry.name}`)) errors.push(`${entry.name}: OpenAI default_prompt must reference $${entry.name}`);+ } catch (error) {+ errors.push(`${entry.name}: OpenAI descriptor YAML parse failed: ${error instanceof Error ? error.message : String(error)}`);+ }+ }+}++const pluginPath = path.join(repo, ".codex-plugin/plugin.json");+try {+ const plugin = JSON.parse(await fs.readFile(pluginPath, "utf8"));+ const pkg = JSON.parse(await fs.readFile(path.join(repo, "package.json"), "utf8"));+ if (plugin.name !== "mso") errors.push(".codex-plugin/plugin.json name must be mso");+ if (plugin.version !== pkg.version) errors.push(".codex-plugin/plugin.json version must match package.json");+ if (plugin.skills !== "./claude-skills/") errors.push(".codex-plugin/plugin.json skills must point at ./claude-skills/");+ if (plugin.mcpServers !== undefined) errors.push(".codex-plugin/plugin.json must not declare mcpServers; the web-capable MSO custom MCP app remains a separate OAuth connection");+ if (!Array.isArray(plugin.interface?.capabilities)) errors.push(".codex-plugin/plugin.json interface.capabilities must be an array");+} catch (error) {+ errors.push(`OpenAI plugin manifest invalid: ${error instanceof Error ? error.message : String(error)}`);}if (!checked) errors.push(`no SKILL.md files found under ${skillsRoot}`);@@ -63,4 +119,4 @@ if (errors.length) {console.error(errors.map((error) => `skill-flows: ${error}`).join("\n"));process.exit(1);}-console.log(`skill-flows: ${checked} official skills valid; template ready`);+console.log(`skill-flows: ${checked} official skills valid; contracts + OpenAI descriptors + plugin manifest ready`);diff --git a/scripts/create-skill-flow.mjs b/scripts/create-skill-flow.mjsindex 5e645cee..42d66885 100755--- a/scripts/create-skill-flow.mjs+++ b/scripts/create-skill-flow.mjs@@ -13,10 +13,12 @@ const usage = () => console.log(`Usage:bun run skill:new -- --name <slug> --description <text> [options]Options:- --title <heading> Human title; defaults from the slug- --risk low|medium|high Default: medium- --policy <slug> Default: inspect-execute-verify- --root <directory> Default: claude-skills+ --title <heading> Human title; defaults from the slug+ --risk low|medium|high Default: medium+ --policy <slug> Default: inspect-execute-verify+ --target <slug> Structured contract target; defaults to skill name+ --openai-short <text> OpenAI short description; defaults from --description+ --root <directory> Default: claude-skills`);if (has("--help") || has("-h")) { usage(); process.exit(0); }@@ -26,31 +28,39 @@ const risk = value("--risk")?.trim() ?? "medium";const policy = value("--policy")?.trim() ?? "inspect-execute-verify";const root = value("--root")?.trim() ?? "claude-skills";const title = value("--title")?.trim() ?? name?.split("-").map((part) => part[0]?.toUpperCase() + part.slice(1)).join(" ");+const targetName = value("--target")?.trim() ?? name;+const openAiShort = value("--openai-short")?.trim() ?? description?.slice(0, 100);if (!name || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name)) fail("--name must be a lowercase kebab-case slug");-if (!description || description.length < 20 || description.length > 280 || /[\r\n]/.test(description))- fail("--description must be one line and 20–280 characters");+if (!description || description.length < 20 || description.length > 280 || /[\r\n]/.test(description)) fail("--description must be one line and 20–280 characters");if (!["low", "medium", "high"].includes(risk)) fail("--risk must be low, medium, or high");if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(policy)) fail("--policy must be a lowercase kebab-case slug");+if (!targetName || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(targetName)) fail("--target must be a lowercase kebab-case slug");if (!title || /[\r\n]/.test(title)) fail("--title must be one line");+if (!openAiShort || openAiShort.length > 120 || /[\r\n]/.test(openAiShort)) fail("--openai-short must be one line and at most 120 characters");const repo = process.cwd();-const templatePath = path.join(repo, "templates/mso-skill-flow/SKILL.md.template");+const templateRoot = path.join(repo, "templates/mso-skill-flow");const targetDir = path.resolve(repo, root, name);-const target = path.join(targetDir, "SKILL.md");-const template = await fs.readFile(templatePath, "utf8").catch(() => fail(`missing template: ${templatePath}`));-const content = template- .replaceAll("{{NAME}}", name)- .replaceAll("{{DESCRIPTION_YAML}}", JSON.stringify(description))- .replaceAll("{{RISK}}", risk)- .replaceAll("{{POLICY}}", policy)- .replaceAll("{{TITLE}}", title);--await fs.mkdir(targetDir, { recursive: true });-await fs.writeFile(target, content, { encoding: "utf8", flag: "wx" }).catch((error) => {- if (error?.code === "EEXIST") fail(`${target} already exists; edit it intentionally instead of regenerating`);- throw error;-});-console.log(`skill:new: created ${path.relative(repo, target)}`);-console.log("next: replace every {{GUIDANCE_PLACEHOLDER}}; skill:check intentionally fails until the workflow is specific");+const outputs = [+ { template: path.join(templateRoot, "SKILL.md.template"), target: path.join(targetDir, "SKILL.md") },+ { template: path.join(templateRoot, "contract.yaml.template"), target: path.join(targetDir, "contract.yaml") },+ { template: path.join(templateRoot, "agents/openai.yaml.template"), target: path.join(targetDir, "agents/openai.yaml") },+];+for (const row of outputs) {+ const exists = await fs.stat(row.target).then(() => true).catch(() => false);+ if (exists) fail(`${row.target} already exists; edit it intentionally instead of regenerating`);+}+const replacements = new Map([+ ["{{NAME}}", name], ["{{DESCRIPTION_YAML}}", JSON.stringify(description)], ["{{RISK}}", risk], ["{{POLICY}}", policy],+ ["{{TITLE}}", title], ["{{TARGET}}", targetName], ["{{OPENAI_SHORT_DESCRIPTION}}", openAiShort],+]);+await fs.mkdir(path.join(targetDir, "agents"), { recursive: true });+for (const row of outputs) {+ let content = await fs.readFile(row.template, "utf8").catch(() => fail(`missing template: ${row.template}`));+ for (const [from, to] of replacements) content = content.replaceAll(from, to);+ await fs.writeFile(row.target, content, { encoding: "utf8", flag: "wx" });+ console.log(`skill:new: created ${path.relative(repo, row.target)}`);+}+console.log("next: replace every remaining {{...}} guidance placeholder in SKILL.md/contract.yaml; skill:check intentionally fails until the workflow is specific");console.log("then run `bun run skill:check`, targeted tests, and project verification");diff --git a/templates/mso-skill-flow/agents/openai.yaml.template b/templates/mso-skill-flow/agents/openai.yaml.templatenew file mode 100644index 00000000..527a177b--- /dev/null+++ b/templates/mso-skill-flow/agents/openai.yaml.template@@ -0,0 +1,4 @@+interface:+ display_name: "{{TITLE}}"+ short_description: "{{OPENAI_SHORT_DESCRIPTION}}"+ default_prompt: "Use ${{NAME}} for this workflow."diff --git a/templates/mso-skill-flow/contract.yaml.template b/templates/mso-skill-flow/contract.yaml.templatenew file mode 100644index 00000000..11995c17--- /dev/null+++ b/templates/mso-skill-flow/contract.yaml.template@@ -0,0 +1,27 @@+version: 1+routing:+ use_when:+ - "{{USE_WHEN}}"+ do_not_use_when:+ - "{{DO_NOT_USE}}"+ fallback: false+context:+ target: {{TARGET}}+ mode: mixed+ actor: operator+lifecycle:+ discover:+ - workflow_start+ validate:+ - targeted-checks+ verify:+ - workflow_finish+state:+ source_of_truth: live+ refresh: before-write+safety:+ risk: {{RISK}}+ confirmation: contextual+ concurrency: contextual+presentation:+ authority: hybrid