From b7df7fad7e480c009a4d7b1d167d841eea1cb201 Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Fri, 31 Jul 2026 05:07:21 -0700 Subject: [PATCH 1/6] docs(rfc): define Claw application composition --- ...7-claw-setup-personalization-control-ui.md | 376 ++++++++++++++++++ rfcs/0027/implementation-plan.md | 210 ++++++++++ 2 files changed, 586 insertions(+) create mode 100644 rfcs/0027-claw-setup-personalization-control-ui.md create mode 100644 rfcs/0027/implementation-plan.md diff --git a/rfcs/0027-claw-setup-personalization-control-ui.md b/rfcs/0027-claw-setup-personalization-control-ui.md new file mode 100644 index 00000000..c04e16e8 --- /dev/null +++ b/rfcs/0027-claw-setup-personalization-control-ui.md @@ -0,0 +1,376 @@ +--- +title: Claw Application Composition and Clients +authors: + - Gio +created: 2026-07-27 +last_updated: 2026-07-31 +status: draft +issue: +rfc_pr: https://github.com/openclaw/rfcs/pull/52 +--- + +# Proposal: Claw Application Composition and Clients + +## Summary + +Complete the experimental Claw application model without introducing schema +version 2 or a second setup engine. A Claw remains a versioned definition of one +complete new agent. Its portable core carries purpose, instructions, skills, +direct MCP servers, managed workspace content, and scheduled work. Conventional +harness profiles carry native extensions and operating policy. An optional +package-root `BOOTSTRAP.md` gives the new agent a seed-once first-run interview +through the harness's existing bootstrap lifecycle. + +Schemas, API references, templates, examples, fixtures, images, HTML, and other +assets remain ordinary managed workspace files. CLI, TUI, chat, and Control UI +are clients of the same read-only plan, consent, owner, status, doctor, update, +and remove services. The Control UI may provide the richest guided experience, +but it does not own a different package parser or mutation path. + +This RFC builds on the merged, still draft-status [RFC 0016](0016-claws.md) +proposal and the draft portable profile addendum in +[RFC PR #48](https://github.com/openclaw/rfcs/pull/48). The exact +portable format, package lifecycle, and OpenClaw profile contracts live in: + +- [`0016/claw-md-v1-spec.md`](0016/claw-md-v1-spec.md) +- [`0016/claw-package-v1-spec.md`](0016/claw-package-v1-spec.md) +- [`0016/openclaw-profile-v1-spec.md` in RFC #48](https://github.com/openclaw/rfcs/pull/48) + +## Motivation + +Claws are differentiated from plugins by application scope. A plugin adds +capability to a harness. A Claw combines purpose, identity, instructions, +knowledge, tools, integrations, scheduled work, first-run setup, and lifecycle +into one operational agent application. + +The initial lifecycle proves that a complete agent can be added safely, but +three product gaps remain: + +1. **Native extensions.** OpenClaw, Claude, Codex, and Cursor plugin bundles can + contain skills, commands, hooks, subagents, MCP integrations, and other + harness behavior. Those dependencies belong in the selected harness profile, + not in portable `CLAW.md` fields that imply every harness can execute them. +2. **Application content.** Finished solutions need schemas, references, + templates, examples, fixtures, and visual assets. They should be reviewable + package content without creating a new file owner or automatically loading + every file into every turn. +3. **Onboarding and clients.** A distributable executive-assistant Claw should + interview its new user, direct credentials to canonical setup surfaces, and + finish with an applied/ready result. That should work from chat or TUI and + become polished in Control UI without requiring forms in the package schema. + +The earlier draft proposed typed setup inputs, a template language, persisted +answers, reconciliation, and schema version 2. That duplicates OpenClaw's +native `BOOTSTRAP.md` owner, adds privacy-bearing state, and commits to update +semantics before real starter Claws establish the need. The simpler native +bootstrap model meets the first-run use case while keeping later structured +setup possible as evidence-driven follow-up. + +## Goals + +- Preserve schema version 1 for launch. +- Keep `CLAW.md` portable and understandable without one harness profile. +- Put native plugin bundles and their format assertions in conventional harness + profiles. +- Delegate extension detection, scanning, installation, readiness, update, and + cleanup to canonical harness owners. +- Support finished applications with managed schemas, references, templates, + examples, fixtures, and static assets. +- Use package-root `BOOTSTRAP.md` for seed-once conversational onboarding. +- Keep credentials, OAuth, channel bindings, providers, and sensitive settings + on canonical owner surfaces; never inject them into package-authored chat. +- Provide equivalent lifecycle outcomes from CLI, TUI, chat, automation, and + Control UI. +- Preserve the one-Claw-one-new-agent and managed/referenced ownership models. +- Keep all new behavior behind the existing experimental Claws gates. + +## Non-Goals + +- A universal plugin format or a promise that every foreign plugin component + works on every harness. +- Portable commands, hooks, subagents, LSP servers, or native tool names. +- A portable capability registry, binding language, or fallback strategy. +- A general form engine, template language, answer store, personalization + ledger, or setup reconciliation system. +- Package scripts, setup hooks, arbitrary code execution, or package-defined + network calls during onboarding. +- Storing credentials or resolved secrets in package files, plans, provenance, + browser state, or bootstrap instructions. +- Automatically inferring personal data or setup questions during export. +- Loading every packaged resource into every model turn. +- Replacing plugin, MCP, SecretRef, channel, model/provider, workspace, agent, + or scheduler owners. +- Requiring Hermes, Claude, or a public npm release before OpenClaw validation. +- Removing experimental gates or graduating the schema. + +## Proposal + +### Application layers + +A Claw application has three layers: + +1. **Portable package.** `CLAW.md`, optional `BOOTSTRAP.md`, identity, managed + workspace files, skills, direct MCP servers, and scheduled work. +2. **Harness profile.** Native extensions, tool posture, memory posture, sandbox + behavior, and presentation choices at `profiles/.yml`. +3. **Local instance.** Credentials, OAuth state, channel bindings, operator + policy, runtime selection, and user-owned personalization. + +The portable package describes the complete application and its durable +behavior. A harness profile explains how one harness realizes it. Local state +finishes configuration without becoming distributable package identity. + +OpenClaw provides the richest reference profile. A Codex or Claude adapter may +configure a project rather than create an OpenClaw-style agent. Profiles do not +need identical tools or presentation, but an adapter must fail the complete plan +when it cannot realize a required component; it must not silently call a +degraded partial projection conforming. + +### Native extensions + +New harness-native plugin dependencies belong in the selected conventional +profile. The exact OpenClaw schema is defined by +[`0016/openclaw-profile-v1-spec.md` in RFC #48](https://github.com/openclaw/rfcs/pull/48). +Existing experimental schema-v1 manifests with portable `plugin` package +entries remain readable, but canonical producers do not duplicate a dependency +between portable core and a harness profile. + +The OpenClaw profile can assert `openclaw`, `claude`, `codex`, or `cursor` +artifact format. That assertion does not create a Claw parser for foreign +bundles. OpenClaw delegates detection and component mapping to its canonical +plugin owner. Preview distinguishes mapped, detect-only, unavailable, and +unsupported components. Required extension failures block the plan. + +Extension identity, exact version, artifact integrity, detected format, mapped +inventory, unavailable inventory, trust findings, redacted effects, and adapter +identity bind preview and consent. A later OpenClaw version may map the same +bundle differently; status and doctor report that compatibility drift without +silently changing plugin enablement. + +Direct `mcpServers` remain portable core. MCP servers embedded in extensions +remain extension-owned. Claws do not invent semantic deduplication between the +two representations; canonical owners preflight exact collisions and preview +attributes every effect to its declaration path. + +### Application content and assets + +Shared application schemas, references, templates, examples, fixtures, and +static assets use ordinary `workspace.files`. V1 adds no resource-role field. +Authors should use conventional directories such as: + +```text +references/ +schemas/ +templates/ +examples/ +fixtures/ +assets/ +``` + +Directory names are descriptive only. They do not load content into context, +grant execution authority, or create another owner. `CLAW.md`, `AGENTS.md`, or +an installed skill references content the agent needs. Skill-private support +content remains inside the skill's own directories so its progressive +disclosure and ownership stay intact. + +A Claw may package an HTML view or other asset and instruct the OpenClaw agent +to use `show_widget` when available. If the active client does not expose that +tool, the agent returns the complete result as ordinary Markdown or a message. +Dashboard placement is an OpenClaw-native `show_widget` option, not a portable +`dashboard` tool. No generic capability or fallback schema is added. + +### First-run onboarding + +An optional package-root `BOOTSTRAP.md` contains conversational instructions +for the new agent's first-run interview. The applying adapter discloses and +seeds it through the harness's native bootstrap owner. In OpenClaw: + +- it is written only for the new Claw workspace; +- the agent can ask about the user, working style, priorities, and preferences; +- the agent may write user-owned local files such as `USER.md`; +- host-owned controls may hand credentials and integrations off only to + canonical owner setup surfaces, never to a package-provided URL or command; +- successful native consumption may delete `BOOTSTRAP.md`; +- expected deletion is not drift; +- update never recreates or rewrites a consumed bootstrap file; +- remove deletes `BOOTSTRAP.md` only while it is still pending and its bytes + match the applied digest; +- remove never deletes user-owned interview output. + +`BOOTSTRAP.md` is package-authored prompt content, not trusted host UI. Applying +a Claw trusts its reviewed instructions to influence the new agent just as it +trusts `CLAW.md`, skills, and managed workspace instructions. A malicious prompt +can still ask a user to disclose a secret; the native bootstrap owner does not +claim to make that impossible. Preview must disclose bootstrap presence and +digest, and every first-run client must label the conversation as package- +authored and warn the operator not to paste credentials or tokens. The host +must never inject resolved secrets into that conversation, automatically follow +package-provided setup links, or let package content impersonate a canonical +credential surface. Trusted owner setup is launched only from host-owned UI or +commands. A future restricted bootstrap mode may strengthen this boundary, but +it is not implied by this RFC. + +The package cannot target root `BOOTSTRAP.md` through ordinary managed +workspace fields. This prevents the managed file reconciler from recreating a +consume-once native file. + +The interview is naturally available in chat and TUI because it is the agent's +existing bootstrap lifecycle. Control UI may open that conversation and show +bootstrap progress, but the browser does not parse instructions or store an +answer ledger. A non-interactive adapter that cannot conduct the required +bootstrap must report the prerequisite honestly rather than inventing answers. + +### Lifecycle clients + +Every client uses the same Gateway or local lifecycle services: + +```mermaid +flowchart LR + Source[Claw source] --> Inspect[Inspect] + Inspect --> Plan[Add dry-run] + Plan --> Consent[Explicit consent] + Consent --> Add[Add new agent] + Add --> Bootstrap[Native first run] + Bootstrap --> Connect[Canonical owner setup] + Connect --> Ready[Status and doctor] +``` + +The primary guided stages are: + +1. **Overview:** identity, exact version, publisher/trust context, purpose, and + expandable validated manifest. +2. **Preview:** complete agent, file, skill, extension, MCP, cron, bootstrap, + capability, blocker, and retained-boundary effects. +3. **Add:** exact plan-integrity consent and canonical mutation outcomes. +4. **Personalize:** the new agent conducts native bootstrap through chat or TUI. +5. **Connect:** canonical plugin, MCP OAuth, channel, and credential surfaces. +6. **Ready:** status and doctor distinguish applied state from operational + readiness and provide owner-specific remediation. + +Control UI can present all six stages in one polished flow. TUI and CLI may +link or transition to the same native owner operations. Surface-specific layout +is allowed; package meaning, plan integrity, consent, ownership, and lifecycle +outcomes are not. + +The Control UI appears only when the Gateway advertises experimental Claw +methods. Hiding navigation is not the security boundary. Direct routes and +Gateway methods fail closed when the experimental feature is disabled. The +browser receives bounded display projections and authorized exact effects, not +secret values or an independent mutation contract. + +### Update, remove, and export + +Update reconciles managed package content and native extension dependencies +under RFC 0016. It preserves user-owned bootstrap output and never restarts the +first-run ritual. A package that needs a new guided migration must introduce an +explicit future contract rather than repurpose bootstrap as recurring update +code. + +Remove follows managed/referenced cleanup rules. It removes unchanged managed +resources selected by the plan, releases extension dependency edges, retains +referenced resources by default, and preserves user-owned workspace content. A +still-pending, digest-identical seeded `BOOTSTRAP.md` may be removed; a consumed +or modified bootstrap file and every interview output remain user-owned. + +Export remains selection-based and excludes credentials, bindings, runtime +choices, and user-owned personal files by default. It emits supported OpenClaw +settings and native extension dependencies to `profiles/openclaw.yml`. Export +does not infer setup questions or copy a consumed local bootstrap ritual. An +author may add and review a new package-root `BOOTSTRAP.md` explicitly before +publication. + +### ClawHub boundary + +ClawHub validates the exact package, optional conventional profiles, optional +`BOOTSTRAP.md`, and safe managed sources behind its existing experimental gate. +It may expose bounded counts and safe summaries for discovery, but it does not +execute extension code, judge runtime mapping, collect onboarding answers, or +replace applying-client validation and consent. + +## Rationale + +### Why native bootstrap instead of structured setup? + +OpenClaw already has a first-run conversational owner that creates personalized +workspace state and then consumes its instruction file. Reusing it removes a +form schema, renderer, answer database, privacy surface, update reconciler, and +UI-specific setup protocol. Structured non-interactive setup can be proposed +later if real Claws demonstrate requirements native bootstrap cannot meet. + +### Why profiles instead of portable plugin fields? + +Plugin bundles are executable harness extensions. Their component models and +support levels differ. Conventional profiles let each harness use its canonical +installer and be honest about mapping without making `CLAW.md` OpenClaw-native +or reducing a Claw to an undifferentiated plugin bundle. + +### Why ordinary workspace files for assets? + +The existing file lifecycle already provides containment, digest, consent, +provenance, drift, update, export, and removal semantics. Directory conventions +and instructions supply meaning without adding schema fields that old strict v1 +consumers would reject. + +### Why multiple clients over one lifecycle? + +A Claw is useful from automation, terminal, chat, and browser. Letting each +surface parse and mutate packages would create divergent policy and ownership. +Server-driven projections preserve one contract while allowing Control UI to +provide the best visual experience. + +## Implementation Plan + +The dependency-aware cross-repository plan is in +[`0027/implementation-plan.md`](0027/implementation-plan.md). OpenClaw +[#115237](https://github.com/openclaw/openclaw/pull/115237) is reused for the +conventional-profile/native-bootstrap slice. The schema-v1 extension slice is +[#115962](https://github.com/openclaw/openclaw/pull/115962), and the current +Control UI/Gateway pair is +[#112808](https://github.com/openclaw/openclaw/pull/112808) followed by +[#112828](https://github.com/openclaw/openclaw/pull/112828). Standalone +[#1](https://github.com/giodl73-repo/claws/pull/1) provides the schema-v1 +reference CLI/OpenClaw adapter, and standalone +[#2](https://github.com/giodl73-repo/claws/pull/2) provides the bounded Codex +workspace adapter. The remaining schema-v2 answer-state and guided-template +drafts are superseded and should not land in their current form. + +## Acceptance Criteria + +1. Schema version 1 remains the only accepted portable manifest version. +2. Optional profiles are discovered only at conventional paths and are bound + into package integrity without manifest pointers. +3. OpenClaw validates profile v1 agent settings and native extensions strictly. +4. Every extension delegates to canonical plugin detection, safety, install, + readiness, update, and cleanup paths. +5. A required extension failure or unusable mapping blocks the complete plan; + unavailable components are disclosed without being presented as working. +6. Application schemas, references, templates, examples, fixtures, and assets + use ordinary managed workspace-file semantics. +7. A package-root `BOOTSTRAP.md` is seeded once through native first-run state; + consumption is not drift, update never recreates it, and remove deletes only + a pending digest-identical seed while preserving user-owned outputs. +8. Credentials and resolved secrets remain on canonical owner surfaces and out + of package content, package-authored bootstrap chat, plans, provenance, logs, + and browser state; clients label bootstrap trust and warn against pasting + secrets. +9. CLI, TUI, chat, automation, and Control UI use one package validator, + planner, consent contract, executor, and owner model. +10. OpenClaw presentation can use `show_widget` and packaged assets when the + runtime exposes the tool and returns a complete message fallback otherwise. +11. Status and doctor report extension compatibility drift, bootstrap progress, + and owner-specific readiness without adding per-turn Claw parsing. +12. ClawHub validates package/profile/bootstrap structure without claiming + runtime extension compatibility or collecting local onboarding state. +13. All new surfaces fail closed when their existing experimental Claws gate is + disabled. + +## Unresolved Questions + +- Which native foreign-bundle components should OpenClaw map at launch, and + which should remain detect-only? +- Should Control UI open the first bootstrap conversation inline or route to the + existing agent chat while preserving progress context? +- What evidence would justify a future structured, non-interactive setup + contract beyond native `BOOTSTRAP.md`? +- After the Codex adapter proof, which conformance vectors should become a + shared public standard rather than reference-engine behavior? diff --git a/rfcs/0027/implementation-plan.md b/rfcs/0027/implementation-plan.md new file mode 100644 index 00000000..44471b73 --- /dev/null +++ b/rfcs/0027/implementation-plan.md @@ -0,0 +1,210 @@ +# RFC 0027 Implementation Plan + +This sidecar translates RFC 0027 into bounded, dependency-aware repository +changes. PR boundaries are implementation guidance, not portable schema. + +## Dependencies + +- Merged RFC 0016 proposal and shipped experimental OpenClaw lifecycle; the RFC + source remains draft-status pending graduation. +- Draft RFC #48 conventional profile, bootstrap, and adapter addendum. +- Existing experimental OpenClaw and ClawHub feature gates. + +No public npm publication, stable-schema graduation, or Hermes support is a +prerequisite for this track. + +## Draft Disposition + +The previous structured-setup stack does not land in its current form. Its +first PR number is reused for the replacement first slice: + +- [`openclaw/openclaw#115237`](https://github.com/openclaw/openclaw/pull/115237): + rewritten as conventional profile discovery and native bootstrap; this is + OpenClaw PR 1 below. +- `openclaw/openclaw#115296` persisted answers and setup mutation: superseded. +- `openclaw/openclaw#115371` guided setup-template export: superseded. +- [`openclaw/openclaw#115962`](https://github.com/openclaw/openclaw/pull/115962): + rebuilt around schema v1 profile extensions and ordinary managed files; this + is OpenClaw PR 2 below. +- [`openclaw/openclaw#112808`](https://github.com/openclaw/openclaw/pull/112808): + rebuilt as the experimental read/status Control UI prerequisite. +- [`openclaw/openclaw#112828`](https://github.com/openclaw/openclaw/pull/112828): + rebuilt without form-schema or answer-state dependencies as the bounded + Gateway mutation and guided lifecycle slice. + +The superseded branches remain historical design evidence until maintainers +choose whether to close them; they are not dependencies of the new stack. + +## OpenClaw Track + +### PR 1: Conventional profile and native bootstrap + +Active PR: [`openclaw/openclaw#115237`](https://github.com/openclaw/openclaw/pull/115237). + +- Replace `metadata.openclaw.config` lookup with optional fixed + `profiles/openclaw.yml` discovery. +- Bind exact profile bytes into development and package integrity. +- Discover optional package-root `BOOTSTRAP.md`, disclose it in inspect and + dry-run, and reject ordinary managed destinations targeting root bootstrap. +- Seed it through OpenClaw's existing new-agent bootstrap owner. +- Treat expected consumption as progress, never recreate it during update, and + preserve user-owned outputs during remove. Remove only a still-pending + `BOOTSTRAP.md` whose bytes match the applied digest. +- Update export and fixtures to emit conventional profile paths and omit + consumed local bootstrap state. +- Keep all commands under `OPENCLAW_EXPERIMENTAL_CLAWS=1`. + +### PR 2: Profile extensions and application content + +Active PR: [`openclaw/openclaw#115962`](https://github.com/openclaw/openclaw/pull/115962). + +- Finalize OpenClaw profile schema version 1 with optional `extensions`. +- Support strict `openclaw`, `claude`, `codex`, and `cursor` format assertions. +- Delegate detection, safety scanning, package preflight, installation, + readiness, update, uninstall warnings, and cleanup to canonical plugin owners. +- Include exact extension effects and adapter identity in plan integrity and + provenance. +- Report mapped, detect-only, unavailable, unsupported, and compatibility-drift + states through inspect, status, and doctor. +- Preserve existing experimental portable plugin entries for reads while + exporting new native dependencies into `profiles/openclaw.yml`. +- Prove schemas, references, templates, examples, fixtures, and static assets + need no new manifest role or lifecycle beyond `workspace.files`. + +### PR 3: Gateway lifecycle API + +Active implementation is split across the read prerequisite +[`openclaw/openclaw#112808`](https://github.com/openclaw/openclaw/pull/112808) +and mutation/guided-lifecycle +[`openclaw/openclaw#112828`](https://github.com/openclaw/openclaw/pull/112828). + +- Expose bounded inspect, add-plan, add, status, doctor, update-plan, update, + remove-plan, remove, and export services over the canonical Claw owners. +- Expose authorized exact manifest/effect expansion and redacted default + projections without leaking source bytes or secret values. +- Report native bootstrap progress and canonical owner prerequisites. +- Advertise methods only while the experimental gate is enabled and fail closed + for direct disabled calls. +- Keep the API presentation-neutral so CLI, TUI, automation, and browser clients + share outcomes. + +### PR 4: Control UI experience + +Active implementation is the same dependency-ordered pair: +[`openclaw/openclaw#112808`](https://github.com/openclaw/openclaw/pull/112808) +followed by [`openclaw/openclaw#112828`](https://github.com/openclaw/openclaw/pull/112828). + +- Add experimental Claw discovery, detail, preview, consent, progress, update, + remove, and export views. +- Present overview, preview, add, personalize, connect, and ready stages using + Gateway-produced state. +- Route native bootstrap to the existing agent conversation rather than parsing + package instructions or storing answers in the browser. +- Label bootstrap as package-authored, warn against pasting secrets, and route + credentials and integrations only through host-owned canonical setup controls. +- Render extension mapping and compatibility drift, managed/referenced + ownership, retained user files, and applied-versus-ready status. +- Add responsive, keyboard, focus, reconnect, invalidated-plan, partial-outcome, + and disabled-gate tests. + +## Standalone Reference CLI Track + +The standalone `claws` repository supplies the reference lifecycle entry point: + +1. Parse and validate schema-v1 packages, conventional profiles, bootstrap, and + safe managed sources. +2. Resolve source, choose `--agent `, preview exact effects, bind + consent, and delegate host lifecycle ownership to the selected adapter. +3. Use an OpenClaw adapter that invokes `openclaw claws add` across an external + process boundary without importing or reproducing OpenClaw policy. +4. Use a bounded Codex adapter to create a new project workspace from portable + prompt/bootstrap instructions and ordinary workspace files. It ignores + foreign profiles and fails closed on required semantics it cannot represent. + +Active PRs: + +- [`giodl73-repo/claws#1`](https://github.com/giodl73-repo/claws/pull/1): + schema-v1 parser, source providers, constructor, consent flow, and OpenClaw + adapter. +- [`giodl73-repo/claws#2`](https://github.com/giodl73-repo/claws/pull/2): + portable-core Codex workspace adapter and one-package/two-host conformance + fixture. + +No package is published to npm until maintainers approve the name, repository, +release process, and initial compatibility contract. + +## ClawHub Track + +One narrow experimental PR should: + +- remove `metadata.openclaw.config` validation; +- discover and structurally validate optional conventional profiles; +- validate optional package-root `BOOTSTRAP.md` as safe bounded UTF-8 content; +- validate OpenClaw profile v1 extension structure without executing bundles or + claiming applying-version compatibility; +- retain exact artifacts as authority and expose only bounded safe summaries; +- preserve `CLAWHUB_EXPERIMENTAL_CLAWS=1` fail-closed reads and routes. + +## Awesome Claws Track + +Migrate all examples before using them as conformance proof: + +- keep `schemaVersion: 1`; +- remove profile metadata pointers; +- move native plugin dependencies into conventional profiles; +- replace structured setup/templates with reviewed package-root + `BOOTSTRAP.md` where onboarding is useful; +- keep reusable content as ordinary managed files in readable directories; +- remove invented `dashboard` tool names and use `show_widget` with complete + Markdown/message fallback where appropriate; +- validate every example from a clean OpenClaw state. + +## End-to-End Proof + +Minimum proof before asking maintainers to land the full track: + +1. Inspect a local package with no profile and inherited defaults. +2. Inspect a package with `profiles/openclaw.yml`, one native extension, + managed schemas/assets, and package-root `BOOTSTRAP.md`. +3. Add dry-run discloses every effect without mutation or secret resolution. +4. Consented add creates one new agent, installs through canonical owners, and + seeds bootstrap exactly once. +5. First chat/TUI turn labels package-authored onboarding, does not inject + secrets, and consumes bootstrap without status drift. +6. The agent uses `show_widget` when available and returns equivalent useful + Markdown when it is not. +7. Status distinguishes applied, bootstrap-pending, owner-setup-required, + extension-incompatible, and ready states. +8. Update preserves user-owned personalization, managed-file drift rules, and + unchanged extension dependency edges. +9. Remove preserves user-owned outputs and retains referenced extensions by + default while offering canonical cleanup under RFC 0016 rules. +10. ClawHub publication/search/download feeds the exact same artifact into a + clean OpenClaw add dry-run. +11. Control UI produces the same plan identity and lifecycle outcome as CLI for + the same exact source and local state. +12. One schema-v1 package produces separate host-native OpenClaw and Codex + previews; the Codex adapter proves project-oriented projection without + OpenClaw agent CRUD or silent loss of required capabilities. + +## Landing Order + +1. RFC #48 and RFC #52 design updates. +2. OpenClaw [PR #115237](https://github.com/openclaw/openclaw/pull/115237) + conventional profile/bootstrap. +3. OpenClaw [PR #115962](https://github.com/openclaw/openclaw/pull/115962) + extensions/application content. +4. Standalone [PR #1](https://github.com/giodl73-repo/claws/pull/1) + schema-v1 reference engine and OpenClaw adapter. +5. ClawHub narrow validation update. +6. Awesome Claws migration and clean-state validation. +7. OpenClaw [PR #112808](https://github.com/openclaw/openclaw/pull/112808) + read/status Control UI prerequisite. +8. OpenClaw [PR #112828](https://github.com/openclaw/openclaw/pull/112828) + Gateway mutation and guided lifecycle. +9. Standalone [PR #2](https://github.com/giodl73-repo/claws/pull/2) Codex + adapter proof and cross-harness conformance report. + +Each PR must be independently testable, signed, rebased on its real base, and +kept behind the existing experimental gate. No step merges or publishes as a +side effect of this plan. From c4391407c8483f8733d6cac11289ff1b95c6e5a7 Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Fri, 31 Jul 2026 07:58:10 -0700 Subject: [PATCH 2/6] docs(claws): complete bootstrap revector --- ...aw-application-composition-and-clients.md} | 30 ++++++---- rfcs/0027/implementation-plan.md | 56 +++++++++++++++---- 2 files changed, 63 insertions(+), 23 deletions(-) rename rfcs/{0027-claw-setup-personalization-control-ui.md => 0027-claw-application-composition-and-clients.md} (93%) diff --git a/rfcs/0027-claw-setup-personalization-control-ui.md b/rfcs/0027-claw-application-composition-and-clients.md similarity index 93% rename from rfcs/0027-claw-setup-personalization-control-ui.md rename to rfcs/0027-claw-application-composition-and-clients.md index c04e16e8..07d4eeb5 100644 --- a/rfcs/0027-claw-setup-personalization-control-ui.md +++ b/rfcs/0027-claw-application-composition-and-clients.md @@ -276,8 +276,10 @@ Export remains selection-based and excludes credentials, bindings, runtime choices, and user-owned personal files by default. It emits supported OpenClaw settings and native extension dependencies to `profiles/openclaw.yml`. Export does not infer setup questions or copy a consumed local bootstrap ritual. An -author may add and review a new package-root `BOOTSTRAP.md` explicitly before -publication. +author may explicitly supply a reviewed Markdown file as the new package-root +`BOOTSTRAP.md`. The exporter validates the finished package and binds those +bytes into normal package integrity, but it does not infer questions, template +private values, persist answers, or recreate bootstrap during update. ### ClawHub boundary @@ -324,15 +326,18 @@ The dependency-aware cross-repository plan is in [`0027/implementation-plan.md`](0027/implementation-plan.md). OpenClaw [#115237](https://github.com/openclaw/openclaw/pull/115237) is reused for the conventional-profile/native-bootstrap slice. The schema-v1 extension slice is -[#115962](https://github.com/openclaw/openclaw/pull/115962), and the current +[#115962](https://github.com/openclaw/openclaw/pull/115962), bootstrap-native +export authoring reuses +[#115371](https://github.com/openclaw/openclaw/pull/115371), and the current Control UI/Gateway pair is [#112808](https://github.com/openclaw/openclaw/pull/112808) followed by [#112828](https://github.com/openclaw/openclaw/pull/112828). Standalone [#1](https://github.com/giodl73-repo/claws/pull/1) provides the schema-v1 reference CLI/OpenClaw adapter, and standalone [#2](https://github.com/giodl73-repo/claws/pull/2) provides the bounded Codex -workspace adapter. The remaining schema-v2 answer-state and guided-template -drafts are superseded and should not land in their current form. +workspace adapter. The schema-v2 planning and answer-state drafts in #115565 +and #115296 are superseded. #115371 is rewritten rather than landed in its +guided-template form. ## Acceptance Criteria @@ -349,19 +354,22 @@ drafts are superseded and should not land in their current form. 7. A package-root `BOOTSTRAP.md` is seeded once through native first-run state; consumption is not drift, update never recreates it, and remove deletes only a pending digest-identical seed while preserving user-owned outputs. -8. Credentials and resolved secrets remain on canonical owner surfaces and out +8. Export may attach only an explicitly selected, reviewed package-root + `BOOTSTRAP.md`; it validates the finished package without inferring questions, + templating private data, or persisting answers. +9. Credentials and resolved secrets remain on canonical owner surfaces and out of package content, package-authored bootstrap chat, plans, provenance, logs, and browser state; clients label bootstrap trust and warn against pasting secrets. -9. CLI, TUI, chat, automation, and Control UI use one package validator, +10. CLI, TUI, chat, automation, and Control UI use one package validator, planner, consent contract, executor, and owner model. -10. OpenClaw presentation can use `show_widget` and packaged assets when the +11. OpenClaw presentation can use `show_widget` and packaged assets when the runtime exposes the tool and returns a complete message fallback otherwise. -11. Status and doctor report extension compatibility drift, bootstrap progress, +12. Status and doctor report extension compatibility drift, bootstrap progress, and owner-specific readiness without adding per-turn Claw parsing. -12. ClawHub validates package/profile/bootstrap structure without claiming +13. ClawHub validates package/profile/bootstrap structure without claiming runtime extension compatibility or collecting local onboarding state. -13. All new surfaces fail closed when their existing experimental Claws gate is +14. All new surfaces fail closed when their existing experimental Claws gate is disabled. ## Unresolved Questions diff --git a/rfcs/0027/implementation-plan.md b/rfcs/0027/implementation-plan.md index 44471b73..20f230e4 100644 --- a/rfcs/0027/implementation-plan.md +++ b/rfcs/0027/implementation-plan.md @@ -21,8 +21,18 @@ first PR number is reused for the replacement first slice: - [`openclaw/openclaw#115237`](https://github.com/openclaw/openclaw/pull/115237): rewritten as conventional profile discovery and native bootstrap; this is OpenClaw PR 1 below. -- `openclaw/openclaw#115296` persisted answers and setup mutation: superseded. -- `openclaw/openclaw#115371` guided setup-template export: superseded. +- [`openclaw/openclaw#115565`](https://github.com/openclaw/openclaw/pull/115565) + setup-v2 and application planning: accepted schema-v1 extension planning and + canonical plugin-owner behavior moved into #115962; setup schemas, resource + roles, metadata profile pointers, and schema version 2 are superseded. +- [`openclaw/openclaw#115296`](https://github.com/openclaw/openclaw/pull/115296) + persisted answers and setup mutation: superseded by native bootstrap; no + answer ledger, configure command, setup database, or reconciliation behavior + moves into the replacement stack. +- [`openclaw/openclaw#115371`](https://github.com/openclaw/openclaw/pull/115371) + guided setup-template export: its schema-v2 implementation is superseded, but + the PR number is reused for the bootstrap-native export-authoring follow-up + below. - [`openclaw/openclaw#115962`](https://github.com/openclaw/openclaw/pull/115962): rebuilt around schema v1 profile extensions and ordinary managed files; this is OpenClaw PR 2 below. @@ -32,8 +42,9 @@ first PR number is reused for the replacement first slice: rebuilt without form-schema or answer-state dependencies as the bounded Gateway mutation and guided lifecycle slice. -The superseded branches remain historical design evidence until maintainers -choose whether to close them; they are not dependencies of the new stack. +The superseded #115565 and #115296 branches are historical design evidence and +are not dependencies of the new stack. Their accepted extension work is +represented by #115962; closing them does not discard a live capability. ## OpenClaw Track @@ -71,7 +82,23 @@ Active PR: [`openclaw/openclaw#115962`](https://github.com/openclaw/openclaw/pul - Prove schemas, references, templates, examples, fixtures, and static assets need no new manifest role or lifecycle beyond `workspace.files`. -### PR 3: Gateway lifecycle API +### PR 3: Bootstrap-native export authoring + +Planned reuse: [`openclaw/openclaw#115371`](https://github.com/openclaw/openclaw/pull/115371). + +- Let an author explicitly select a reviewed local Markdown file to become the + exported package-root `BOOTSTRAP.md`. +- Validate bounded, nonempty UTF-8 content and reject root-bootstrap managed-file + collisions through the existing package reader. +- Re-read the complete exported package so the bootstrap bytes participate in + the same package integrity and inspection contract as hand-authored packages. +- Remove an incomplete export target on validation failure. +- Warn authors that bootstrap is package-authored prompt content and must not + contain credentials, tokens, private answers, or machine-specific paths. +- Do not infer setup questions, rewrite personal files, render templates, + persist answers, add `claws configure`, or introduce schema version 2. + +### PR 4: Gateway lifecycle API Active implementation is split across the read prerequisite [`openclaw/openclaw#112808`](https://github.com/openclaw/openclaw/pull/112808) @@ -88,7 +115,7 @@ and mutation/guided-lifecycle - Keep the API presentation-neutral so CLI, TUI, automation, and browser clients share outcomes. -### PR 4: Control UI experience +### PR 5: Control UI experience Active implementation is the same dependency-ordered pair: [`openclaw/openclaw#112808`](https://github.com/openclaw/openclaw/pull/112808) @@ -186,6 +213,9 @@ Minimum proof before asking maintainers to land the full track: 12. One schema-v1 package produces separate host-native OpenClaw and Codex previews; the Codex adapter proves project-oriented projection without OpenClaw agent CRUD or silent loss of required capabilities. +13. Bootstrap-native export attaches an explicit reviewed `BOOTSTRAP.md`, + re-inspects the finished package, and leaves no partial target after a + validation failure. ## Landing Order @@ -194,15 +224,17 @@ Minimum proof before asking maintainers to land the full track: conventional profile/bootstrap. 3. OpenClaw [PR #115962](https://github.com/openclaw/openclaw/pull/115962) extensions/application content. -4. Standalone [PR #1](https://github.com/giodl73-repo/claws/pull/1) +4. OpenClaw [PR #115371](https://github.com/openclaw/openclaw/pull/115371) + bootstrap-native export authoring. +5. Standalone [PR #1](https://github.com/giodl73-repo/claws/pull/1) schema-v1 reference engine and OpenClaw adapter. -5. ClawHub narrow validation update. -6. Awesome Claws migration and clean-state validation. -7. OpenClaw [PR #112808](https://github.com/openclaw/openclaw/pull/112808) +6. ClawHub narrow validation update. +7. Awesome Claws migration and clean-state validation. +8. OpenClaw [PR #112808](https://github.com/openclaw/openclaw/pull/112808) read/status Control UI prerequisite. -8. OpenClaw [PR #112828](https://github.com/openclaw/openclaw/pull/112828) +9. OpenClaw [PR #112828](https://github.com/openclaw/openclaw/pull/112828) Gateway mutation and guided lifecycle. -9. Standalone [PR #2](https://github.com/giodl73-repo/claws/pull/2) Codex +10. Standalone [PR #2](https://github.com/giodl73-repo/claws/pull/2) Codex adapter proof and cross-harness conformance report. Each PR must be independently testable, signed, rebased on its real base, and From b1035ed0dfb30fa53635594602413e0541336dc6 Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Fri, 31 Jul 2026 11:27:47 -0700 Subject: [PATCH 3/6] docs(claws): clarify shared plugin removal --- rfcs/0016/claw-package-v1-spec.md | 20 ++++++++++++++++++- ...law-application-composition-and-clients.md | 15 ++++++++++++++ rfcs/0027/implementation-plan.md | 11 +++++++++- 3 files changed, 44 insertions(+), 2 deletions(-) diff --git a/rfcs/0016/claw-package-v1-spec.md b/rfcs/0016/claw-package-v1-spec.md index c04dbdbc..e6ffca35 100644 --- a/rfcs/0016/claw-package-v1-spec.md +++ b/rfcs/0016/claw-package-v1-spec.md @@ -356,6 +356,11 @@ or incomplete cleanup state. Implementations must not require a historical operation ledger or stored reference-count history. Any cleanup decision uses the current enumerated dependency edges and canonical owner state. +Known ownership is not proof of runtime use. In particular, an agent may use a +globally installed plugin without creating a Claw dependency edge or another +machine-readable ownership record. The absence of another known owner must +therefore never be presented as proof that a shared plugin is unused. + Applied state and ready state are distinct. A complete add means every declared mutation was applied or safely referenced. Status must separately report unresolved environment placeholders, incomplete OAuth login, unavailable MCP @@ -445,7 +450,10 @@ The operator must be offered these referenced-resource dispositions: - **remove-if-unused**: invoke canonical removal only when the resource has no other Claw dependency edge or known non-Claw owner, was introduced by Claw add, is complete, unchanged, and unambiguous, and its canonical owner permits - removal. + removal. This bulk disposition applies only when the canonical owner can + establish that no remaining consumer uses the resource. Globally installed + plugins are excluded because Claw provenance cannot enumerate every agent + that may use them. - **remove-selected**: invoke canonical removal for specifically selected resources after showing all known affected Claws and non-Claw owners. A remaining dependency or pre-existing origin requires stronger explicit @@ -457,6 +465,13 @@ mode explicitly; it must not broaden default `retain` behavior merely because a general `--yes` flag is present. Referenced cleanup runs after managed-resource cleanup so failure cannot damage a still-live Claw agent. +Explicitly selected plugin cleanup remains available. Its plan and consent +prompt must identify the exact plugin, show every known dependency and owner, +and warn even when none are known that other manually configured agents may +still use the global plugin. The canonical plugin uninstaller and its normal +Claw-reference warnings remain authoritative. A general cleanup mode or +`--yes` alone must never select a plugin for uninstall. + If an operator explicitly uninstalls an artifact despite a Claw-reference warning, canonical uninstall semantics win. The Claw becomes degraded and status must report the missing dependency. Claw status or remove must not @@ -552,4 +567,7 @@ A conforming applying client must: - derive managed and referenced relationships from canonical owner state; - retain referenced resources by default and bind any operator-selected referenced cleanup into the exact remove plan; +- never treat missing ownership records as proof that a global plugin is + unused, and require exact operator selection plus a shared-use warning before + canonical plugin uninstall; - report partial outcomes and leave them diagnosable. diff --git a/rfcs/0027-claw-application-composition-and-clients.md b/rfcs/0027-claw-application-composition-and-clients.md index 07d4eeb5..03c0addf 100644 --- a/rfcs/0027-claw-application-composition-and-clients.md +++ b/rfcs/0027-claw-application-composition-and-clients.md @@ -272,6 +272,17 @@ referenced resources by default, and preserves user-owned workspace content. A still-pending, digest-identical seeded `BOOTSTRAP.md` may be removed; a consumed or modified bootstrap file and every interview output remain user-owned. +Native extensions backed by globally installed plugins are always referenced, +even when Claw add introduced the plugin. Normal remove releases only the +removing Claw's dependency edge and retains the plugin. Bulk +`remove-if-unused` cleanup must not select a global plugin because provenance +records known ownership, not every agent that may use shared plugin tools. +Operators may still explicitly select an exact plugin for canonical uninstall +after dry-run. That plan must show known affected owners and warn, even when +none are known, that manually configured agents may still depend on it. This +warning and exact selection are required in addition to plan-integrity consent; +a general cleanup mode or `--yes` is insufficient. + Export remains selection-based and excludes credentials, bindings, runtime choices, and user-owned personal files by default. It emits supported OpenClaw settings and native extension dependencies to `profiles/openclaw.yml`. Export @@ -371,6 +382,10 @@ guided-template form. runtime extension compatibility or collecting local onboarding state. 14. All new surfaces fail closed when their existing experimental Claws gate is disabled. +15. Remove retains referenced plugins by default, excludes global plugins from + bulk unused cleanup, and permits canonical plugin uninstall only after exact + selection, dry-run, integrity-bound consent, and a warning that unknown + manually configured agents may still use the plugin. ## Unresolved Questions diff --git a/rfcs/0027/implementation-plan.md b/rfcs/0027/implementation-plan.md index 20f230e4..f8b12a9c 100644 --- a/rfcs/0027/implementation-plan.md +++ b/rfcs/0027/implementation-plan.md @@ -73,6 +73,13 @@ Active PR: [`openclaw/openclaw#115962`](https://github.com/openclaw/openclaw/pul - Support strict `openclaw`, `claude`, `codex`, and `cursor` format assertions. - Delegate detection, safety scanning, package preflight, installation, readiness, update, uninstall warnings, and cleanup to canonical plugin owners. +- Persist extension dependency edges as referenced resources even when Claw add + introduced the global plugin. Default remove releases only the Claw edge. +- Exclude global plugins from bulk `remove-if-unused` cleanup because ownership + provenance cannot prove that arbitrary agents do not use them. Preserve exact + opt-in plugin cleanup through `remove-selected` / `--remove-referenced`, with + dry-run, plan-integrity consent, known-owner disclosure, an unknown-agent-use + warning, and canonical plugin uninstall behavior. - Include exact extension effects and adapter identity in plan integrity and provenance. - Report mapped, detect-only, unavailable, unsupported, and compatibility-drift @@ -205,7 +212,9 @@ Minimum proof before asking maintainers to land the full track: 8. Update preserves user-owned personalization, managed-file drift rules, and unchanged extension dependency edges. 9. Remove preserves user-owned outputs and retains referenced extensions by - default while offering canonical cleanup under RFC 0016 rules. + default. Bulk unused cleanup does not select global plugins; exact selected + plugin cleanup shows known owners, warns that unrecorded agent use cannot be + disproved, and delegates to canonical uninstall. 10. ClawHub publication/search/download feeds the exact same artifact into a clean OpenClaw add dry-run. 11. Control UI produces the same plan identity and lifecycle outcome as CLI for From 1afb9029ecaf17f9744413c61564188b468e8d3a Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Thu, 6 Aug 2026 06:42:56 -0700 Subject: [PATCH 4/6] docs(claws): align clients with host requirements --- ...law-application-composition-and-clients.md | 85 +++++++++++-------- rfcs/0027/implementation-plan.md | 34 +++++--- 2 files changed, 70 insertions(+), 49 deletions(-) diff --git a/rfcs/0027-claw-application-composition-and-clients.md b/rfcs/0027-claw-application-composition-and-clients.md index 03c0addf..5d07c8e4 100644 --- a/rfcs/0027-claw-application-composition-and-clients.md +++ b/rfcs/0027-claw-application-composition-and-clients.md @@ -3,7 +3,7 @@ title: Claw Application Composition and Clients authors: - Gio created: 2026-07-27 -last_updated: 2026-07-31 +last_updated: 2026-08-06 status: draft issue: rfc_pr: https://github.com/openclaw/rfcs/pull/52 @@ -17,9 +17,9 @@ Complete the experimental Claw application model without introducing schema version 2 or a second setup engine. A Claw remains a versioned definition of one complete new agent. Its portable core carries purpose, instructions, skills, direct MCP servers, managed workspace content, and scheduled work. Conventional -harness profiles carry native extensions and operating policy. An optional -package-root `BOOTSTRAP.md` gives the new agent a seed-once first-run interview -through the harness's existing bootstrap lifecycle. +harness profiles carry native extension requirements and operating policy. An +optional package-root `BOOTSTRAP.md` gives the new agent a seed-once first-run +interview through the harness's existing bootstrap lifecycle. Schemas, API references, templates, examples, fixtures, images, HTML, and other assets remain ordinary managed workspace files. CLI, TUI, chat, and Control UI @@ -70,8 +70,8 @@ setup possible as evidence-driven follow-up. - Preserve schema version 1 for launch. - Keep `CLAW.md` portable and understandable without one harness profile. -- Put native plugin bundles and their format assertions in conventional harness - profiles. +- Put native plugin requirements and their format assertions in conventional + harness profiles without transferring plugin ownership to the Claw. - Delegate extension detection, scanning, installation, readiness, update, and cleanup to canonical harness owners. - Support finished applications with managed schemas, references, templates, @@ -111,8 +111,9 @@ A Claw application has three layers: 1. **Portable package.** `CLAW.md`, optional `BOOTSTRAP.md`, identity, managed workspace files, skills, direct MCP servers, and scheduled work. -2. **Harness profile.** Native extensions, tool posture, memory posture, sandbox - behavior, and presentation choices at `profiles/.yml`. +2. **Harness profile.** Native extension requirements, tool posture, memory + posture, sandbox behavior, and presentation choices at + `profiles/.yml`. 3. **Local instance.** Credentials, OAuth state, channel bindings, operator policy, runtime selection, and user-owned personalization. @@ -126,10 +127,11 @@ need identical tools or presentation, but an adapter must fail the complete plan when it cannot realize a required component; it must not silently call a degraded partial projection conforming. -### Native extensions +### Native extension requirements -New harness-native plugin dependencies belong in the selected conventional -profile. The exact OpenClaw schema is defined by +New harness-native plugin requirements belong in the selected conventional +profile. They are requirements of the application, not members owned by the +Claw lifecycle. The exact OpenClaw schema is defined by [`0016/openclaw-profile-v1-spec.md` in RFC #48](https://github.com/openclaw/rfcs/pull/48). Existing experimental schema-v1 manifests with portable `plugin` package entries remain readable, but canonical producers do not duplicate a dependency @@ -147,6 +149,13 @@ identity bind preview and consent. A later OpenClaw version may map the same bundle differently; status and doctor report that compatibility drift without silently changing plugin enablement. +Preview classifies each requirement as satisfied, missing and installable, +conflicting, or requiring local setup. A missing installable requirement is a +distinct capability effect. Interactive clients ask whether to install it; +non-interactive clients disclose the grouped requirement action and bind it to +the exact plan-integrity acknowledgment. Approved canonical requirement actions +complete before any agent, workspace, MCP, or scheduled-work mutation. + Direct `mcpServers` remain portable core. MCP servers embedded in extensions remain extension-owned. Claws do not invent semantic deduplication between the two representations; canonical owners preflight exact collisions and preview @@ -228,7 +237,7 @@ Every client uses the same Gateway or local lifecycle services: flowchart LR Source[Claw source] --> Inspect[Inspect] Inspect --> Plan[Add dry-run] - Plan --> Consent[Explicit consent] + Plan --> Consent[Approve requirements and exact plan] Consent --> Add[Add new agent] Add --> Bootstrap[Native first run] Bootstrap --> Connect[Canonical owner setup] @@ -239,15 +248,17 @@ The primary guided stages are: 1. **Overview:** identity, exact version, publisher/trust context, purpose, and expandable validated manifest. -2. **Preview:** complete agent, file, skill, extension, MCP, cron, bootstrap, - capability, blocker, and retained-boundary effects. -3. **Add:** exact plan-integrity consent and canonical mutation outcomes. -4. **Personalize:** the new agent conducts native bootstrap through chat or TUI. -5. **Connect:** canonical plugin, MCP OAuth, channel, and credential surfaces. -6. **Ready:** status and doctor distinguish applied state from operational +2. **Preview:** complete agent, file, skill, extension-requirement, MCP, cron, + bootstrap, capability, blocker, and retained-boundary effects. +3. **Requirements:** reuse satisfied requirements and explicitly approve any + canonical installation needed before Claw-owned mutation. +4. **Add:** exact plan-integrity consent and canonical mutation outcomes. +5. **Personalize:** the new agent conducts native bootstrap through chat or TUI. +6. **Connect:** canonical plugin, MCP OAuth, channel, and credential surfaces. +7. **Ready:** status and doctor distinguish applied state from operational readiness and provide owner-specific remediation. -Control UI can present all six stages in one polished flow. TUI and CLI may +Control UI can present all seven stages in one polished flow. TUI and CLI may link or transition to the same native owner operations. Surface-specific layout is allowed; package meaning, plan integrity, consent, ownership, and lifecycle outcomes are not. @@ -260,8 +271,10 @@ secret values or an independent mutation contract. ### Update, remove, and export -Update reconciles managed package content and native extension dependencies -under RFC 0016. It preserves user-owned bootstrap output and never restarts the +Update reconciles managed package content and native extension requirements +under RFC 0016. New missing requirements receive the same explicit consent as +add; removed requirements release their dependency edge and retain the shared +artifact. Update preserves user-owned bootstrap output and never restarts the first-run ritual. A package that needs a new guided migration must introduce an explicit future contract rather than repurpose bootstrap as recurring update code. @@ -274,14 +287,12 @@ or modified bootstrap file and every interview output remain user-owned. Native extensions backed by globally installed plugins are always referenced, even when Claw add introduced the plugin. Normal remove releases only the -removing Claw's dependency edge and retains the plugin. Bulk -`remove-if-unused` cleanup must not select a global plugin because provenance -records known ownership, not every agent that may use shared plugin tools. -Operators may still explicitly select an exact plugin for canonical uninstall -after dry-run. That plan must show known affected owners and warn, even when -none are known, that manually configured agents may still depend on it. This -warning and exact selection are required in addition to plan-integrity consent; -a general cleanup mode or `--yes` is insufficient. +removing Claw's dependency edge, retains the plugin, and reminds the operator +when Claw add introduced it. A client may separately offer exact canonical +plugin uninstall after dry-run. That plan must show known affected owners and +warn, even when none are known, that manually configured agents may still +depend on it. This warning and exact selection are required in addition to +plan-integrity consent; a general cleanup mode or `--yes` is insufficient. Export remains selection-based and excludes credentials, bindings, runtime choices, and user-owned personal files by default. It emits supported OpenClaw @@ -355,10 +366,13 @@ guided-template form. 1. Schema version 1 remains the only accepted portable manifest version. 2. Optional profiles are discovered only at conventional paths and are bound into package integrity without manifest pointers. -3. OpenClaw validates profile v1 agent settings and native extensions strictly. +3. OpenClaw validates profile v1 agent settings and native extension + requirements strictly. 4. Every extension delegates to canonical plugin detection, safety, install, readiness, update, and cleanup paths. -5. A required extension failure or unusable mapping blocks the complete plan; +5. Requirements are classified as satisfied, missing-installable, conflicting, + or setup-required; missing installation needs explicit consent before + Claw-owned mutation, while a conflict or unusable mapping blocks the plan; unavailable components are disclosed without being presented as working. 6. Application schemas, references, templates, examples, fixtures, and assets use ordinary managed workspace-file semantics. @@ -382,10 +396,11 @@ guided-template form. runtime extension compatibility or collecting local onboarding state. 14. All new surfaces fail closed when their existing experimental Claws gate is disabled. -15. Remove retains referenced plugins by default, excludes global plugins from - bulk unused cleanup, and permits canonical plugin uninstall only after exact - selection, dry-run, integrity-bound consent, and a warning that unknown - manually configured agents may still use the plugin. +15. Remove releases requirement edges, retains referenced plugins by default, + reports which requirements Claw add introduced, and permits canonical + plugin uninstall only after separate exact selection, dry-run, + integrity-bound consent, and a warning that unknown manually configured + agents may still use the plugin. ## Unresolved Questions diff --git a/rfcs/0027/implementation-plan.md b/rfcs/0027/implementation-plan.md index f8b12a9c..1508f11c 100644 --- a/rfcs/0027/implementation-plan.md +++ b/rfcs/0027/implementation-plan.md @@ -65,21 +65,25 @@ Active PR: [`openclaw/openclaw#115237`](https://github.com/openclaw/openclaw/pul consumed local bootstrap state. - Keep all commands under `OPENCLAW_EXPERIMENTAL_CLAWS=1`. -### PR 2: Profile extensions and application content +### PR 2: Profile extension requirements and application content Active PR: [`openclaw/openclaw#115962`](https://github.com/openclaw/openclaw/pull/115962). -- Finalize OpenClaw profile schema version 1 with optional `extensions`. +- Finalize OpenClaw profile schema version 1 with optional `extensions`, whose + entries declare shared host requirements rather than Claw-owned members. - Support strict `openclaw`, `claude`, `codex`, and `cursor` format assertions. - Delegate detection, safety scanning, package preflight, installation, readiness, update, uninstall warnings, and cleanup to canonical plugin owners. +- Classify requirements as satisfied, missing-installable, conflicting, or + setup-required; bind approved missing installs into plan integrity and run + them before Claw-owned agent/workspace mutation. - Persist extension dependency edges as referenced resources even when Claw add - introduced the global plugin. Default remove releases only the Claw edge. -- Exclude global plugins from bulk `remove-if-unused` cleanup because ownership - provenance cannot prove that arbitrary agents do not use them. Preserve exact - opt-in plugin cleanup through `remove-selected` / `--remove-referenced`, with - dry-run, plan-integrity consent, known-owner disclosure, an unknown-agent-use - warning, and canonical plugin uninstall behavior. + introduced the global plugin. Default remove releases only the Claw edge, + retains the plugin, and reports that add introduced it. +- Preserve exact opt-in plugin cleanup through `remove-selected` / + `--remove-referenced` as a separate canonical owner action, with dry-run, + plan-integrity consent, known-owner disclosure, an unknown-agent-use warning, + and canonical plugin uninstall behavior. - Include exact extension effects and adapter identity in plan integrity and provenance. - Report mapped, detect-only, unavailable, unsupported, and compatibility-drift @@ -201,8 +205,9 @@ Minimum proof before asking maintainers to land the full track: 2. Inspect a package with `profiles/openclaw.yml`, one native extension, managed schemas/assets, and package-root `BOOTSTRAP.md`. 3. Add dry-run discloses every effect without mutation or secret resolution. -4. Consented add creates one new agent, installs through canonical owners, and - seeds bootstrap exactly once. +4. Consented add resolves satisfied requirements, installs approved missing + requirements through canonical owners before Claw-owned mutation, creates + one new agent, and seeds bootstrap exactly once. 5. First chat/TUI turn labels package-authored onboarding, does not inject secrets, and consumes bootstrap without status drift. 6. The agent uses `show_widget` when available and returns equivalent useful @@ -211,10 +216,11 @@ Minimum proof before asking maintainers to land the full track: extension-incompatible, and ready states. 8. Update preserves user-owned personalization, managed-file drift rules, and unchanged extension dependency edges. -9. Remove preserves user-owned outputs and retains referenced extensions by - default. Bulk unused cleanup does not select global plugins; exact selected - plugin cleanup shows known owners, warns that unrecorded agent use cannot be - disproved, and delegates to canonical uninstall. +9. Remove preserves user-owned outputs, releases extension dependency edges, + retains referenced extensions by default, and reports which were introduced + by add. Separately selected plugin cleanup shows known owners, warns that + unrecorded agent use cannot be disproved, and delegates to canonical + uninstall. 10. ClawHub publication/search/download feeds the exact same artifact into a clean OpenClaw add dry-run. 11. Control UI produces the same plan identity and lifecycle outcome as CLI for From 04e7a7186147bc08889b2d790ab62d4951c561c9 Mon Sep 17 00:00:00 2001 From: root Date: Sun, 9 Aug 2026 14:46:07 -0700 Subject: [PATCH 5/6] docs(claws): update composition landing status Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: db3a73db-01ff-428e-a451-b7b710cd5085 --- ...law-application-composition-and-clients.md | 27 +++-- rfcs/0027/implementation-plan.md | 104 +++++++++++------- 2 files changed, 78 insertions(+), 53 deletions(-) diff --git a/rfcs/0027-claw-application-composition-and-clients.md b/rfcs/0027-claw-application-composition-and-clients.md index 5d07c8e4..93372582 100644 --- a/rfcs/0027-claw-application-composition-and-clients.md +++ b/rfcs/0027-claw-application-composition-and-clients.md @@ -346,20 +346,19 @@ provide the best visual experience. The dependency-aware cross-repository plan is in [`0027/implementation-plan.md`](0027/implementation-plan.md). OpenClaw -[#115237](https://github.com/openclaw/openclaw/pull/115237) is reused for the -conventional-profile/native-bootstrap slice. The schema-v1 extension slice is -[#115962](https://github.com/openclaw/openclaw/pull/115962), bootstrap-native -export authoring reuses -[#115371](https://github.com/openclaw/openclaw/pull/115371), and the current -Control UI/Gateway pair is -[#112808](https://github.com/openclaw/openclaw/pull/112808) followed by -[#112828](https://github.com/openclaw/openclaw/pull/112828). Standalone -[#1](https://github.com/giodl73-repo/claws/pull/1) provides the schema-v1 -reference CLI/OpenClaw adapter, and standalone -[#2](https://github.com/giodl73-repo/claws/pull/2) provides the bounded Codex -workspace adapter. The schema-v2 planning and answer-state drafts in #115565 -and #115296 are superseded. #115371 is rewritten rather than landed in its -guided-template form. +[#115237](https://github.com/openclaw/openclaw/pull/115237), +[#115962](https://github.com/openclaw/openclaw/pull/115962), and +[#115371](https://github.com/openclaw/openclaw/pull/115371) have merged the +conventional-profile/native-bootstrap, schema-v1 extension, and reviewed +bootstrap-export slices. The read-only Control UI branch +[#112808](https://github.com/openclaw/openclaw/pull/112808) is closed and +superseded; [#112828](https://github.com/openclaw/openclaw/pull/112828) is the +single remaining reconstruction target on current `main`. Standalone +[#1](https://github.com/giodl73-repo/claws/pull/1) merged the schema-v1 reference +CLI/OpenClaw adapter, and replacement +[#3](https://github.com/giodl73-repo/claws/pull/3) merged the bounded Codex +workspace adapter after superseding #2. The schema-v2 planning and answer-state +drafts in #115565 and #115296 remain superseded. ## Acceptance Criteria diff --git a/rfcs/0027/implementation-plan.md b/rfcs/0027/implementation-plan.md index 1508f11c..13cf004f 100644 --- a/rfcs/0027/implementation-plan.md +++ b/rfcs/0027/implementation-plan.md @@ -7,7 +7,8 @@ changes. PR boundaries are implementation guidance, not portable schema. - Merged RFC 0016 proposal and shipped experimental OpenClaw lifecycle; the RFC source remains draft-status pending graduation. -- Draft RFC #48 conventional profile, bootstrap, and adapter addendum. +- RFC #48 conventional profile, bootstrap, and adapter addendum, still under + design review while its implementation layers are merged. - Existing experimental OpenClaw and ClawHub feature gates. No public npm publication, stable-schema graduation, or Hermes support is a @@ -37,10 +38,11 @@ first PR number is reused for the replacement first slice: rebuilt around schema v1 profile extensions and ordinary managed files; this is OpenClaw PR 2 below. - [`openclaw/openclaw#112808`](https://github.com/openclaw/openclaw/pull/112808): - rebuilt as the experimental read/status Control UI prerequisite. + closed and superseded as an independently landable read/status prerequisite. - [`openclaw/openclaw#112828`](https://github.com/openclaw/openclaw/pull/112828): - rebuilt without form-schema or answer-state dependencies as the bounded - Gateway mutation and guided lifecycle slice. + remains the single reconstruction target on current `main`, combining bounded + read/status projections with Gateway mutation and guided lifecycle behavior, + without form-schema or answer-state dependencies. The superseded #115565 and #115296 branches are historical design evidence and are not dependencies of the new stack. Their accepted extension work is @@ -50,7 +52,8 @@ represented by #115962; closing them does not discard a live capability. ### PR 1: Conventional profile and native bootstrap -Active PR: [`openclaw/openclaw#115237`](https://github.com/openclaw/openclaw/pull/115237). +Merged: [`openclaw/openclaw#115237`](https://github.com/openclaw/openclaw/pull/115237) +as `60fc2fe64d8ec2988a555a638dc1074d31e5760b`. - Replace `metadata.openclaw.config` lookup with optional fixed `profiles/openclaw.yml` discovery. @@ -67,7 +70,8 @@ Active PR: [`openclaw/openclaw#115237`](https://github.com/openclaw/openclaw/pul ### PR 2: Profile extension requirements and application content -Active PR: [`openclaw/openclaw#115962`](https://github.com/openclaw/openclaw/pull/115962). +Merged: [`openclaw/openclaw#115962`](https://github.com/openclaw/openclaw/pull/115962) +as `7774f9a36c12eb5f63e6ef33b3da2af065b09707`. - Finalize OpenClaw profile schema version 1 with optional `extensions`, whose entries declare shared host requirements rather than Claw-owned members. @@ -95,7 +99,8 @@ Active PR: [`openclaw/openclaw#115962`](https://github.com/openclaw/openclaw/pul ### PR 3: Bootstrap-native export authoring -Planned reuse: [`openclaw/openclaw#115371`](https://github.com/openclaw/openclaw/pull/115371). +Merged: [`openclaw/openclaw#115371`](https://github.com/openclaw/openclaw/pull/115371) +as `a3094582ffc5473df9a48be4486f3f240e14484f`. - Let an author explicitly select a reviewed local Markdown file to become the exported package-root `BOOTSTRAP.md`. @@ -111,10 +116,11 @@ Planned reuse: [`openclaw/openclaw#115371`](https://github.com/openclaw/openclaw ### PR 4: Gateway lifecycle API -Active implementation is split across the read prerequisite -[`openclaw/openclaw#112808`](https://github.com/openclaw/openclaw/pull/112808) -and mutation/guided-lifecycle -[`openclaw/openclaw#112828`](https://github.com/openclaw/openclaw/pull/112828). +Remaining implementation: +[`openclaw/openclaw#112828`](https://github.com/openclaw/openclaw/pull/112828), +reconstructed directly on current `main`. The former read prerequisite +[#112808](https://github.com/openclaw/openclaw/pull/112808) is closed and +superseded rather than a live dependency. - Expose bounded inspect, add-plan, add, status, doctor, update-plan, update, remove-plan, remove, and export services over the canonical Claw owners. @@ -128,9 +134,10 @@ and mutation/guided-lifecycle ### PR 5: Control UI experience -Active implementation is the same dependency-ordered pair: -[`openclaw/openclaw#112808`](https://github.com/openclaw/openclaw/pull/112808) -followed by [`openclaw/openclaw#112828`](https://github.com/openclaw/openclaw/pull/112828). +Remaining implementation is the same single current-main reconstruction: +[`openclaw/openclaw#112828`](https://github.com/openclaw/openclaw/pull/112828). +It includes the bounded read/status projection previously separated into +superseded #112808. - Add experimental Claw discovery, detail, preview, consent, progress, update, remove, and export views. @@ -159,21 +166,31 @@ The standalone `claws` repository supplies the reference lifecycle entry point: prompt/bootstrap instructions and ordinary workspace files. It ignores foreign profiles and fails closed on required semantics it cannot represent. -Active PRs: +Merged implementations: - [`giodl73-repo/claws#1`](https://github.com/giodl73-repo/claws/pull/1): schema-v1 parser, source providers, constructor, consent flow, and OpenClaw - adapter. -- [`giodl73-repo/claws#2`](https://github.com/giodl73-repo/claws/pull/2): + adapter, merged as `530d5edb56618814ad3526dc4af494157a389e6e`. +- [`giodl73-repo/claws#3`](https://github.com/giodl73-repo/claws/pull/3): portable-core Codex workspace adapter and one-package/two-host conformance - fixture. + fixture, merged as `250e41588a54d23ab53b49eef5e7b2eeee83ea03`. + It replaces closed, superseded #2. No package is published to npm until maintainers approve the name, repository, release process, and initial compatibility contract. ## ClawHub Track -One narrow experimental PR should: +The registry layers have merged: + +- [`openclaw/clawhub#3328`](https://github.com/openclaw/clawhub/pull/3328) + aligned conventional profiles, native bootstrap, and bounded summaries with + schema v1. +- [`openclaw/clawhub#3359`](https://github.com/openclaw/clawhub/pull/3359) + restricted publication to already-built npm-compatible `.tgz` artifacts and + preserved exact bytes and digest identity through retry and download. + +Together they: - remove `metadata.openclaw.config` validation; - discover and structurally validate optional conventional profiles; @@ -185,7 +202,15 @@ One narrow experimental PR should: ## Awesome Claws Track -Migrate all examples before using them as conformance proof: +The example migration and complete golden proof have merged: + +- [`giodl73-repo/awesome-claws#1`](https://github.com/giodl73-repo/awesome-claws/pull/1) + migrated the corpus to the schema-v1 application contract. +- [`giodl73-repo/awesome-claws#5`](https://github.com/giodl73-repo/awesome-claws/pull/5) + replaced superseded #2 and proved one exact artifact through build, + publication, download, extraction, clean add, status, doctor, and removal. + +The merged corpus: - keep `schemaVersion: 1`; - remove profile metadata pointers; @@ -232,25 +257,26 @@ Minimum proof before asking maintainers to land the full track: re-inspects the finished package, and leaves no partial target after a validation failure. -## Landing Order - -1. RFC #48 and RFC #52 design updates. -2. OpenClaw [PR #115237](https://github.com/openclaw/openclaw/pull/115237) - conventional profile/bootstrap. -3. OpenClaw [PR #115962](https://github.com/openclaw/openclaw/pull/115962) - extensions/application content. -4. OpenClaw [PR #115371](https://github.com/openclaw/openclaw/pull/115371) - bootstrap-native export authoring. -5. Standalone [PR #1](https://github.com/giodl73-repo/claws/pull/1) - schema-v1 reference engine and OpenClaw adapter. -6. ClawHub narrow validation update. -7. Awesome Claws migration and clean-state validation. -8. OpenClaw [PR #112808](https://github.com/openclaw/openclaw/pull/112808) - read/status Control UI prerequisite. -9. OpenClaw [PR #112828](https://github.com/openclaw/openclaw/pull/112828) - Gateway mutation and guided lifecycle. -10. Standalone [PR #2](https://github.com/giodl73-repo/claws/pull/2) Codex - adapter proof and cross-harness conformance report. +## Landing Status + +Merged: + +1. OpenClaw [#115237](https://github.com/openclaw/openclaw/pull/115237), + [#115962](https://github.com/openclaw/openclaw/pull/115962), and + [#115371](https://github.com/openclaw/openclaw/pull/115371). +2. Standalone Claws [#1](https://github.com/giodl73-repo/claws/pull/1) and + replacement [#3](https://github.com/giodl73-repo/claws/pull/3). +3. ClawHub [#3328](https://github.com/openclaw/clawhub/pull/3328) and + [#3359](https://github.com/openclaw/clawhub/pull/3359). +4. Awesome Claws [#1](https://github.com/giodl73-repo/awesome-claws/pull/1) + and replacement [#5](https://github.com/giodl73-repo/awesome-claws/pull/5). + +Remaining: + +1. RFC #48 and RFC #52 maintainer review. +2. OpenClaw [#112828](https://github.com/openclaw/openclaw/pull/112828), + reconstructed on current `main` as the single Gateway and Control UI + lifecycle slice. Closed #112808 is not a prerequisite. Each PR must be independently testable, signed, rebased on its real base, and kept behind the existing experimental gate. No step merges or publishes as a From 59b11e25acf4605771bced523f72083b19a8940f Mon Sep 17 00:00:00 2001 From: Gio Della-Libera <235387111+giodl73-repo@users.noreply.github.com> Date: Sun, 9 Aug 2026 18:36:31 -0700 Subject: [PATCH 6/6] docs: renumber Claw application RFC to 0031 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: db3a73db-01ff-428e-a451-b7b710cd5085 --- ...ts.md => 0031-claw-application-composition-and-clients.md} | 2 +- rfcs/{0027 => 0031}/implementation-plan.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) rename rfcs/{0027-claw-application-composition-and-clients.md => 0031-claw-application-composition-and-clients.md} (99%) rename rfcs/{0027 => 0031}/implementation-plan.md (99%) diff --git a/rfcs/0027-claw-application-composition-and-clients.md b/rfcs/0031-claw-application-composition-and-clients.md similarity index 99% rename from rfcs/0027-claw-application-composition-and-clients.md rename to rfcs/0031-claw-application-composition-and-clients.md index 93372582..6a83ca83 100644 --- a/rfcs/0027-claw-application-composition-and-clients.md +++ b/rfcs/0031-claw-application-composition-and-clients.md @@ -345,7 +345,7 @@ provide the best visual experience. ## Implementation Plan The dependency-aware cross-repository plan is in -[`0027/implementation-plan.md`](0027/implementation-plan.md). OpenClaw +[`0031/implementation-plan.md`](0031/implementation-plan.md). OpenClaw [#115237](https://github.com/openclaw/openclaw/pull/115237), [#115962](https://github.com/openclaw/openclaw/pull/115962), and [#115371](https://github.com/openclaw/openclaw/pull/115371) have merged the diff --git a/rfcs/0027/implementation-plan.md b/rfcs/0031/implementation-plan.md similarity index 99% rename from rfcs/0027/implementation-plan.md rename to rfcs/0031/implementation-plan.md index 13cf004f..44b7db20 100644 --- a/rfcs/0027/implementation-plan.md +++ b/rfcs/0031/implementation-plan.md @@ -1,6 +1,6 @@ -# RFC 0027 Implementation Plan +# RFC 0031 Implementation Plan -This sidecar translates RFC 0027 into bounded, dependency-aware repository +This sidecar translates RFC 0031 into bounded, dependency-aware repository changes. PR boundaries are implementation guidance, not portable schema. ## Dependencies