diff --git a/skills/kova-operator/SKILL.md b/.agents/skills/kova-operator/SKILL.md similarity index 96% rename from skills/kova-operator/SKILL.md rename to .agents/skills/kova-operator/SKILL.md index af594ac..e03fa6d 100644 --- a/skills/kova-operator/SKILL.md +++ b/.agents/skills/kova-operator/SKILL.md @@ -89,11 +89,8 @@ If installing Kova from its installer, OCM can be installed or required there: curl -fsSL https://raw.githubusercontent.com/shakkernerd/Kova/main/install.sh | bash -s -- --install-ocm --require-ocm ``` -For Codex agents, install the OCM operating skill too: - -```sh -codex skills install https://github.com/shakkernerd/ocm/tree/main/skills/ocm-operator -``` +For Codex agents working from this repo, use the repo-local OCM operating skill +at `.agents/skills/ocm-operator` when direct OCM operations are needed. ## Safety Rules @@ -449,16 +446,12 @@ Artifacts: Do not paste noisy stdout unless the user asks. Use exact error lines and metrics, not vague summaries. -## Installing This Skill +## Repo-Local Skills -When Kova is hosted in GitHub, install the skill with: +This repo carries the skills under `.agents/skills/`: -```sh -codex skills install https://github.com/shakkernerd/Kova/tree/main/skills/kova-operator -``` +- `.agents/skills/kova-operator` +- `.agents/skills/ocm-operator` -If the agent also needs to operate OCM directly, install: - -```sh -codex skills install https://github.com/shakkernerd/ocm/tree/main/skills/ocm-operator -``` +Use `kova-operator` for Kova benchmark selection, execution, and reporting. Use +`ocm-operator` when direct OCM env/runtime/service/log operations are needed. diff --git a/skills/kova-operator/agents/openai.yaml b/.agents/skills/kova-operator/agents/openai.yaml similarity index 100% rename from skills/kova-operator/agents/openai.yaml rename to .agents/skills/kova-operator/agents/openai.yaml diff --git a/.agents/skills/ocm-operator/SKILL.md b/.agents/skills/ocm-operator/SKILL.md new file mode 100644 index 0000000..aa38478 --- /dev/null +++ b/.agents/skills/ocm-operator/SKILL.md @@ -0,0 +1,140 @@ +--- +name: ocm-operator +description: Use OpenClaw Manager (OCM) safely and correctly for OpenClaw environment lifecycle work, runtime installation/builds, release-shaped local builds, upgrades, migration/adoption, cloning existing user state, service supervision, gateway logs, dev worktrees, plugin testing, model/provider smoke tests, TUI/dashboard checks, cleanup, and concise reporting. Use whenever Codex is asked to use OCM, manage OpenClaw envs/runtimes/services, test OpenClaw with OCM, reproduce existing-user or new-user flows, or avoid breaking user state while working with OpenClaw. +--- + +# OCM Operator + +## Operating Model + +Use OCM as the control plane for OpenClaw. Treat an OCM environment as the +isolation boundary: it owns `OPENCLAW_HOME`, state, config, workspace, gateway +port, runtime/launcher binding, and service policy. + +Prefer OCM commands over raw OpenClaw commands whenever the task touches: + +- env creation, cloning, migration, export/import, snapshots, or cleanup +- runtime install/build/verify/update/remove +- upgrades or release testing +- background gateway services +- logs, status, TUI/dashboard, plugin checks, model checks + +Run OpenClaw inside an env with: + +```sh +ocm @ -- +``` + +Use `ocm env exec -- ` only when you need a non-OpenClaw command +inside the env, such as `env`, `node`, or shell tooling. + +## First Steps + +1. Inspect current state before changing it: + +```sh +ocm env list +ocm service status +ocm runtime list +``` + +2. Read help for the exact surface before using unfamiliar flags: + +```sh +ocm help start +ocm help env +ocm help runtime +ocm help service +ocm help logs +ocm help upgrade +``` + +3. For detailed command patterns, read +`references/command-cookbook.md`. + +4. For destructive operations, service boundaries, or real user state, read +`references/safety-and-state.md` before acting. + +5. For this machine's common paths and release-test defaults, read +`references/local-paths.md`. + +## Decision Guide + +- **Start a normal runtime-backed env**: use `ocm start --runtime ` + or `ocm start --version `. +- **Start a fresh user env**: use `ocm start --runtime ` first; + use `--onboard` only when testing interactive onboarding specifically. +- **Use source-backed OpenClaw development**: use `ocm dev --repo `. + Do not use this as proof of release packaging. +- **Test release behavior from local OpenClaw source**: use + `ocm runtime build-local --repo --force`, then test envs + against that runtime. +- **Test existing-user upgrade behavior**: clone the existing env, upgrade the + clone, and never mutate the source env directly. +- **Run OpenClaw commands in an env**: use `ocm @ -- ...`. +- **Read logs**: use `ocm logs `. +- **Manage background gateway state**: use `ocm service status/start/stop/restart`. +- **Clean up**: use `ocm env destroy --yes`; this removes env snapshots, + OCM service policy, and OCM-created dev worktrees. + +## Safety Rules + +- Treat important user envs such as `Violet` and `Shaks` as durable state. + Clone first for testing unless the user explicitly asks to mutate them. +- Remove envs with `ocm env destroy`. +- Manage OCM env gateway lifecycle with `ocm service`. +- Remember OCM injects `OPENCLAW_SERVICE_REPAIR_POLICY=external` for env-run + OpenClaw processes, so `openclaw doctor --fix` should repair normal env + state but skip OpenClaw-owned service lifecycle repair. +- Do not treat `ocm dev`, `pnpm openclaw`, or a source worktree as release + validation. For release behavior, build and use a package runtime. +- Clean up temporary envs, services, worktrees, tarballs, and retained + simulation envs. +- If a command could change real user data, run read-only inspection or clone + first, then report the exact command you plan to run if there is ambiguity. + +## Verification Standard + +Finish by exercising the relevant command path. Prefer these checks: + +```sh +ocm env list +ocm service status +ocm logs --tail 100 +ocm @ -- --version +ocm @ -- status +ocm @ -- doctor --fix +``` + +Add plugin/model/TUI checks when the task touches plugins, model auth/catalog, +onboarding, or gateway connectivity: + +```sh +ocm @ -- plugins list +ocm @ -- plugins update --all --dry-run +ocm @ -- models list +ocm @ -- tui +``` + +## Reporting + +Keep reports quiet and useful: + +- lead with pass/fail/blocker status +- include the exact command for failures +- include concise evidence for passes +- separate OCM issues from OpenClaw runtime/package issues +- say which relevant checks were skipped +- include cleanup performed + +Use this failure shape: + +```md +Failure: +- Command: `` +- Expected: +- Actual: +- Impact: +- Likely owner: OCM | OpenClaw | test setup | external dependency +- Paste to fixer: +``` diff --git a/.agents/skills/ocm-operator/agents/openai.yaml b/.agents/skills/ocm-operator/agents/openai.yaml new file mode 100644 index 0000000..48f9bdc --- /dev/null +++ b/.agents/skills/ocm-operator/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "OCM Operator" + short_description: "Use OpenClaw Manager safely and fully" + default_prompt: "Use $ocm-operator to manage OpenClaw environments, runtimes, services, upgrades, logs, and release testing through OCM without breaking user state." diff --git a/.agents/skills/ocm-operator/references/command-cookbook.md b/.agents/skills/ocm-operator/references/command-cookbook.md new file mode 100644 index 0000000..8c7eb28 --- /dev/null +++ b/.agents/skills/ocm-operator/references/command-cookbook.md @@ -0,0 +1,279 @@ +# OCM Command Cookbook + +Use these commands as patterns. Run `ocm help ` when flags may have +changed. + +## Inspect State + +```sh +ocm env list +ocm env show +ocm env status +ocm service status +ocm service status +ocm runtime list +ocm runtime show +ocm runtime verify +``` + +## Run OpenClaw Inside An Env + +```sh +ocm @ -- --version +ocm @ -- status +ocm @ -- doctor --fix +ocm @ -- plugins list +ocm @ -- models list +ocm @ -- dashboard +ocm @ -- tui +``` + +For non-OpenClaw commands inside the env: + +```sh +ocm env exec -- env +ocm env exec -- node --version +ocm env exec -- sh -lc 'pwd && env | sort' +``` + +## Create Or Start Envs + +Runtime-backed env from an installed runtime: + +```sh +ocm start --runtime +``` + +Runtime-backed env from a published version: + +```sh +ocm start --version 2026.4.24 +ocm start --channel stable +ocm start --channel beta +``` + +Foreground/no-service env: + +```sh +ocm start --runtime --no-service +``` + +Interactive onboarding path: + +```sh +ocm start --runtime --onboard +``` + +Local command launcher env: + +```sh +ocm start --command 'pnpm openclaw' --cwd /path/to/openclaw +ocm start --command 'pnpm openclaw' --cwd /path/to/openclaw --no-service +``` + +## Dev Worktree Envs + +Use for source-backed development and reproductions. Do not use this as proof +of release packaging. + +```sh +ocm dev --repo /path/to/openclaw +ocm dev --repo /path/to/openclaw --service +ocm dev --watch +ocm dev --watch --force +ocm dev --onboard +ocm dev status +ocm dev status +``` + +Rerun `ocm dev ` after pulling the source repo to refresh the worktree +binding. + +## Runtime Management + +Install a published runtime: + +```sh +ocm runtime install --channel stable +ocm runtime install --channel beta +ocm runtime install --version 2026.4.24 +``` + +Build a release-shaped runtime from local source: + +```sh +ocm runtime build-local --repo /path/to/openclaw --force +ocm runtime verify +ocm runtime show +node "$HOME/.ocm/runtimes//files/node_modules/openclaw/openclaw.mjs" --version +``` + +Update or remove runtimes: + +```sh +ocm runtime update +ocm runtime update --all +ocm runtime remove +``` + +## Upgrade Flows + +Dry-run: + +```sh +ocm upgrade --dry-run +ocm upgrade --version 2026.4.24 --dry-run +ocm upgrade --runtime --dry-run +``` + +Real upgrade: + +```sh +ocm upgrade +ocm upgrade --channel beta +ocm upgrade --version 2026.4.24 +ocm upgrade --runtime +``` + +Simulation matrix: + +```sh +ocm upgrade simulate --to 2026.4.24 --scenario all +ocm upgrade simulate --to beta --scenario all +ocm upgrade simulate --to /path/to/openclaw --scenario all +ocm upgrade simulate --to /path/to/openclaw --scenario all --keep-simulations +``` + +## Existing-User Test Flow + +Clone first: + +```sh +ocm env clone Violet +ocm start +ocm service status +ocm logs --tail 100 +``` + +Exercise: + +```sh +ocm @ -- status +ocm @ -- doctor --fix +ocm @ -- plugins list +ocm @ -- plugins update --all --dry-run +ocm @ -- tui +``` + +Upgrade the clone: + +```sh +ocm upgrade --version 2026.4.24 +ocm upgrade --runtime +``` + +## Fresh-User Test Flow + +```sh +ocm start --runtime +ocm service status +ocm @ -- --version +ocm @ -- status +ocm @ -- doctor --fix +ocm @ -- plugins list +ocm @ -- plugins update --all --dry-run +ocm @ -- models list +ocm @ -- tui +``` + +## Plugins + +```sh +ocm @ -- plugins --help +ocm @ -- plugins list +ocm @ -- plugins list --json +ocm @ -- plugins inspect --json +ocm @ -- plugins install /path/to/plugin-dir +ocm @ -- plugins install /path/to/plugin.tgz +ocm @ -- plugins install +ocm @ -- plugins update --dry-run +ocm @ -- plugins update +ocm @ -- plugins update --all --dry-run +``` + +Check both manifest data and `package.json`-derived metadata when testing +plugins that declare information in both places. + +## Services And Logs + +Use OCM service commands for supervised gateway lifecycle: + +```sh +ocm service status +ocm service status +ocm service install +ocm service start +ocm service stop +ocm service restart +ocm service uninstall +``` + +Logs are env-first: + +```sh +ocm logs +ocm logs --tail 100 +ocm logs --stream error --tail 100 +ocm logs --follow +``` + +## Migration And Portability + +Plain `~/.openclaw` into OCM: + +```sh +ocm adopt inspect ~/.openclaw +ocm adopt plan --name ~/.openclaw +ocm adopt import --name ~/.openclaw +``` + +One-step migration: + +```sh +ocm migrate ~/.openclaw +``` + +Export/import OCM envs: + +```sh +ocm env export --output ./.ocm-env.tar +ocm env import ./.ocm-env.tar --name +``` + +## Cleanup + +Preview before destroying: + +```sh +ocm env destroy +``` + +Destroy: + +```sh +ocm env destroy --yes +``` + +Protected env: + +```sh +ocm env destroy --yes --force +``` + +Check for leftovers: + +```sh +ocm env list +ocm service status +git -C /path/to/openclaw worktree list +``` diff --git a/.agents/skills/ocm-operator/references/local-paths.md b/.agents/skills/ocm-operator/references/local-paths.md new file mode 100644 index 0000000..89926af --- /dev/null +++ b/.agents/skills/ocm-operator/references/local-paths.md @@ -0,0 +1,93 @@ +# Local Paths And Defaults + +These defaults match Shakker's current OpenClaw/OCM workspace. Verify with +`pwd`, `git status --short --branch`, and `ocm env list` before relying on +them. + +## Repos + +OCM repo: + +```text +/Users/shakker/WorkSpace/ShakkerNerd/OpenSource/OpenClaw/ocm +``` + +OpenClaw release/build test repo: + +```text +/Users/shakker/WorkSpace/ShakkerNerd/OpenSource/OpenClaw/temp/test-build +``` + +OpenClaw dev/plugin test repo: + +```text +/Users/shakker/WorkSpace/ShakkerNerd/OpenSource/OpenClaw/temp/test-install +``` + +Active OpenClaw repo to avoid unless the user explicitly permits it: + +```text +/Users/shakker/WorkSpace/ShakkerNerd/OpenSource/OpenClaw/openclaw +``` + +## Long-Lived Envs + +Treat these as real user state unless the user explicitly says otherwise: + +```text +Shaks +Violet +``` + +Use `Violet` as the source for existing-user clone tests: + +```sh +ocm env clone Violet +``` + +## Common Test Names + +Use descriptive, disposable names: + +```text +Violet-local-release-test +fresh-local-release-test +fresh-local-onboard-test +plugins-dev-test +``` + +Destroy them when done: + +```sh +ocm env destroy Violet-local-release-test --yes +ocm env destroy fresh-local-release-test --yes +ocm env destroy fresh-local-onboard-test --yes +ocm env destroy plugins-dev-test --yes +``` + +## Local Release Runtime Pattern + +```sh +cd /Users/shakker/WorkSpace/ShakkerNerd/OpenSource/OpenClaw/temp/test-build +git switch main +git pull origin main +pnpm install +pnpm check +pnpm build + +cd /Users/shakker/WorkSpace/ShakkerNerd/OpenSource/OpenClaw/ocm +ocm runtime build-local test-build-1 --repo /Users/shakker/WorkSpace/ShakkerNerd/OpenSource/OpenClaw/temp/test-build --force +ocm runtime verify test-build-1 +ocm runtime show test-build-1 +node "$HOME/.ocm/runtimes/test-build-1/files/node_modules/openclaw/openclaw.mjs" --version +``` + +## Release Validation Cheatsheet + +If present, this local doc has a broader workflow checklist: + +```text +/Users/shakker/WorkSpace/ShakkerNerd/OpenSource/OpenClaw/ocm/docs/TESTING_WORKFLOW_CHEATSHEET.md +``` + +It is a local ignored doc for this checkout. diff --git a/.agents/skills/ocm-operator/references/safety-and-state.md b/.agents/skills/ocm-operator/references/safety-and-state.md new file mode 100644 index 0000000..aedf094 --- /dev/null +++ b/.agents/skills/ocm-operator/references/safety-and-state.md @@ -0,0 +1,146 @@ +# OCM Safety And State Rules + +## Isolation + +OCM envs are isolated by `OPENCLAW_HOME`. Treat the env root and its +`.openclaw` state as user data. Prefer OCM commands for changes to env state. + +Use OCM to inspect paths: + +```sh +ocm env show +ocm env exec -- env | rg 'OPENCLAW_HOME|OPENCLAW_STATE_DIR|OPENCLAW_CONFIG_PATH|OPENCLAW_SERVICE_REPAIR_POLICY|OCM_ACTIVE_ENV' +``` + +## Existing User State + +For tests involving existing users: + +1. Use a clone. +2. Run the full flow on the clone. +3. Keep the source env untouched. +4. Destroy the clone when done. + +Pattern: + +```sh +ocm env clone Violet +ocm upgrade --runtime +ocm @ -- doctor --fix +ocm env destroy --yes +``` + +## Service Boundary + +OCM owns service lifecycle for OCM-managed envs. OpenClaw doctor should not +install/start/repair OpenClaw's own service when run through OCM. + +Verify the boundary: + +```sh +ocm env exec -- env | rg 'OPENCLAW_SERVICE_REPAIR_POLICY' +ocm @ -- doctor --fix +``` + +Expected env value: + +```text +OPENCLAW_SERVICE_REPAIR_POLICY=external +``` + +Use OCM service commands: + +```sh +ocm service status +ocm service start +ocm service stop +ocm service restart +``` + +Avoid raw OpenClaw service commands for OCM-managed envs unless the user asks to +test standalone OpenClaw service behavior. + +## Destructive Commands + +Use preview modes when possible: + +```sh +ocm env destroy +ocm upgrade --dry-run +ocm upgrade simulate --to --scenario all +``` + +Use `--yes` only after confirming the target env is not a protected real user +env: + +```sh +ocm env destroy --yes +``` + +Use `--force` only when the user requested it or when destroying an intentional +temporary env that is protected by test setup. + +## Release-Shaped Testing + +Use built package runtimes for release behavior: + +```sh +ocm runtime build-local --repo /path/to/openclaw --force +ocm start --runtime +``` + +Do not use `pnpm openclaw`, `ocm dev`, or a source worktree as proof that a +published package will work. Those paths can hide packaging, bundled extension, +or runtime dependency issues. + +## Logs And Long-Running Commands + +Use env logs: + +```sh +ocm logs --tail 100 +ocm logs --stream error --tail 100 +ocm logs --follow +``` + +For stuck TUI/gateway symptoms: + +```sh +ocm service status +ocm logs --stream error --tail 200 +ps -axo pid,ppid,stat,command | rg 'openclaw|ocm|gateway|tui' +``` + +Stop follow commands before ending a task unless the user asked to keep them +running. + +## Cleanup Checklist + +Before finishing: + +```sh +ocm env list +ocm service status +``` + +Destroy temp envs: + +```sh +ocm env destroy --yes +``` + +Remove temp worktrees created by manual git commands: + +```sh +git -C /path/to/openclaw worktree list +git -C /path/to/openclaw worktree remove --force /path/to/worktree +``` + +Remove temp archives/directories: + +```sh +rm -rf /tmp/ +``` + +Do not remove shared runtimes unless they were created for the task or the user +asks for runtime cleanup. diff --git a/AGENTS.md b/AGENTS.md index a862433..defaa5e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -16,14 +16,7 @@ env cloning, runtime selection, local release builds, service status, logs, cleanup, and durable user-state boundaries. Kova remains OpenClaw-focused; the skill only improves the harness operations. -If the skill is not installed, install it from: - -```sh -codex skills install https://github.com/shakkernerd/ocm/tree/main/skills/ocm-operator -``` - -Permanent skill source: -`https://github.com/shakkernerd/ocm/tree/main/skills/ocm-operator` +The repo-local OCM skill lives at `.agents/skills/ocm-operator`. ## Core Rules diff --git a/README.md b/README.md index 5911c34..1d10a58 100644 --- a/README.md +++ b/README.md @@ -234,18 +234,12 @@ node bin/kova.mjs matrix plan --profile smoke --target runtime:stable --json node bin/kova.mjs matrix run --profile smoke --target runtime:stable --execute --json ``` -Install the Kova operator skill so agents know the benchmark workflows, -evidence rules, safety model, and report handoff format: +Kova ships repo-local agent skills: -```sh -codex skills install https://github.com/shakkernerd/Kova/tree/main/skills/kova-operator -``` +- `.agents/skills/kova-operator` +- `.agents/skills/ocm-operator` -For OCM-backed lab work, also install the OCM operator skill: - -```sh -codex skills install https://github.com/shakkernerd/ocm/tree/main/skills/ocm-operator -``` - -The skill teaches safe env cloning, local runtime builds, upgrades, service -inspection, logs, and cleanup. Kova stays focused on OpenClaw behavior. +When using Codex or another agent from this repo, tell it to use those skills. +`kova-operator` teaches benchmark workflows, evidence rules, safety model, and +report handoff format. `ocm-operator` teaches safe env cloning, local runtime +builds, upgrades, service inspection, logs, and cleanup. diff --git a/docs/AGENT_USAGE.md b/docs/AGENT_USAGE.md index 21ff5bd..fb9435c 100644 --- a/docs/AGENT_USAGE.md +++ b/docs/AGENT_USAGE.md @@ -16,17 +16,7 @@ The `ocm-operator` skill is not part of Kova's product surface. It is an agent instruction layer that helps Codex use OCM correctly while Kova remains focused on OpenClaw runtime validation. -Permanent skill source: - -```text -https://github.com/shakkernerd/ocm/tree/main/skills/ocm-operator -``` - -Install it if missing: - -```sh -codex skills install https://github.com/shakkernerd/ocm/tree/main/skills/ocm-operator -``` +The repo-local OCM skill lives at `.agents/skills/ocm-operator`. ## Standard Agent Flow diff --git a/docs/OCM_OPERATOR_INTEGRATION.md b/docs/OCM_OPERATOR_INTEGRATION.md index 06d1d1a..489bdea 100644 --- a/docs/OCM_OPERATOR_INTEGRATION.md +++ b/docs/OCM_OPERATOR_INTEGRATION.md @@ -4,17 +4,7 @@ Kova uses OCM as the OpenClaw environment and runtime control plane. Agents that have access to an `ocm-operator` skill should load it before executing real Kova scenarios. -Permanent skill source: - -```text -https://github.com/shakkernerd/ocm/tree/main/skills/ocm-operator -``` - -Install command: - -```sh -codex skills install https://github.com/shakkernerd/ocm/tree/main/skills/ocm-operator -``` +The repo-local OCM skill lives at `.agents/skills/ocm-operator`. ## Why diff --git a/scripts/build-release.mjs b/scripts/build-release.mjs index cebcf4e..097b2f2 100755 --- a/scripts/build-release.mjs +++ b/scripts/build-release.mjs @@ -21,7 +21,7 @@ const latestChecksumPath = `${latestArchivePath}.sha256`; await rm(stageRoot, { recursive: true, force: true }); await mkdir(appDir, { recursive: true }); -for (const path of ["bin", "src", "scenarios", "states", "profiles", "surfaces", "process-roles", "metrics", "support", "fixtures", "skills"]) { +for (const path of ["bin", "src", "scenarios", "states", "profiles", "surfaces", "process-roles", "metrics", "support", "fixtures", ".agents/skills/kova-operator", ".agents/skills/ocm-operator"]) { await copyRequired(path); } @@ -68,7 +68,9 @@ async function copyRequired(path) { if (!existsSync(source)) { throw new Error(`release input missing: ${path}`); } - await cp(source, join(appDir, path), { recursive: true }); + const destination = join(appDir, path); + await mkdir(dirname(destination), { recursive: true }); + await cp(source, destination, { recursive: true }); } function parseOutputDir() { diff --git a/src/setup.mjs b/src/setup.mjs index a6a860d..99022f5 100644 --- a/src/setup.mjs +++ b/src/setup.mjs @@ -440,6 +440,6 @@ function skillGuidanceCheck() { id: "ocm-operator-skill", required: false, status: "INFO", - message: "For Codex/agent runs, install or load https://github.com/shakkernerd/ocm/tree/main/skills/ocm-operator" + message: "For Codex/agent runs from this repo, use .agents/skills/kova-operator and .agents/skills/ocm-operator" }; }