agentwheel 0.14.8 → 0.14.13

package/skills/agentwheel/references/optional-openclaw-plugin-artifacts.md

@@ -0,0 +1,76 @@
+# Optional OpenClaw plugin artifacts in OpenPack packages
+
+Use this when a package contains runtime-neutral skills/core plus OpenClaw-only plugin code. Do not force non-OpenClaw platforms to install the plugin; expose it as a selectable `plugins/<name>` artifact.
+
+## Package layout
+
+```text
+openpack.json
+agentwheel.json            # optional legacy alias
+AGENTS.md
+skills/<skill-name>/
+plugins/openclaw-agent-mesh/
+  package.json
+  openclaw.plugin.json
+  src/index.js
+  README.md
+```
+
+## Manifest pattern
+
+```json
+{
+  "schemaVersion": 2,
+  "name": "NestDevLab/agent-mesh",
+  "version": "0.9.0",
+  "provides": [
+    { "type": "instructions", "path": "AGENTS.md" },
+    { "type": "skills", "path": "skills" },
+    { "type": "plugins", "path": "plugins" }
+  ]
+}
+```
+
+If older AgentWheel installs still read `agentwheel.json`, keep it in sync with `openpack.json` until the fleet is fully migrated.
+
+## Smoke commands
+
+Validate the package:
+
+```bash
+agentwheel package validate /path/to/package
+agentwheel scan /path/to/package --driver local
+```
+
+List artifacts:
+
+```bash
+agentwheel list /path/to/package --driver local
+```
+
+Dry-run only the OpenClaw plugin artifact:
+
+```bash
+agentwheel install /path/to/package \
+  --driver local \
+  --adapter openclaw \
+  --target-root /tmp/agentwheel-openclaw-smoke \
+  --select plugins/openclaw-agent-mesh \
+  --dry-run \
+  --only-source
+```
+
+Expected plan includes a `PLUGIN` action and semantic command. For fleet-managed OpenClaw plugins the command should be copy/materialized install, **not** symlink install:
+
+```text
+openclaw plugins install .../plugins/openclaw-agent-mesh
+```
+
+If a dry-run still shows `openclaw plugins install --link ...`, the OpenClaw plugin target is using the legacy symlink flow. Patch AgentWheel's OpenClaw plugin command generation before applying fleet installs; do not compensate by adding runtime symlinks.
+
+## Pitfalls
+
+- Run `agentwheel install` with an absolute source path for local package smoke tests. A bare `.` can be interpreted as a registry dependency inside some package-resolution paths.
+- For plugin-root repositories, do not point `provides[{type:"plugins"}].path` at `"."`; AgentWheel will treat each top-level file/directory as a separate plugin artifact. Materialize the plugin under `plugins/<plugin-name>/` and set `{ "type": "plugins", "path": "plugins" }`.
+- Keep plugin package dependencies relative to the canonical repo layout, e.g. `file:../../packages/core` from `plugins/openclaw-agent-mesh/package.json`.
+- For OpenClaw-specific plugins, do not add them to every platform profile by default; select `plugins/<name>` only for OpenClaw targets.

package/skills/agentwheel/references/package-manifest-and-registry-updates.md

@@ -0,0 +1,76 @@
+# Package manifest and registry update workflow
+
+Use this when converting an AgentWheel-installable repo to OpenPack, adding optional plugin artifacts, or updating catalogue metadata.
+
+## Manifest rule
+
+- `openpack.json` / `openpack.jsonc` is the canonical package manifest.
+- `agentwheel.json` is legacy. Do not add or keep it unless a specific old AgentWheel runtime requires it.
+- After removing legacy manifest files, verify with:
+
+```bash
+agentwheel scan . --driver local
+agentwheel package validate .
+```
+
+If testing a local source from inside the package directory, pass the absolute path rather than bare `.` when dependency resolution treats `.` as a registry name:
+
+```bash
+agentwheel install /absolute/path/to/pkg \
+  --driver local \
+  --adapter openclaw \
+  --target-root /tmp/agentwheel-smoke \
+  --select plugins/<name> \
+  --dry-run \
+  --only-source
+```
+
+Expected optional OpenClaw plugin signal:
+
+```text
+PLUGIN   MANAGED  plugins/<name> ... (semantic plugin install planned) :: openclaw plugins install --link ...
+```
+
+## Optional plugin packaging
+
+For packages that provide runtime-neutral skills/rules plus platform-specific plugins:
+
+```jsonc
+{
+  "schemaVersion": 2,
+  "name": "Owner/package",
+  "version": "0.1.0",
+  "provides": [
+    { "type": "instructions", "path": "AGENTS.md" },
+    { "type": "skills", "path": "skills" },
+    { "type": "plugins", "path": "plugins" }
+  ]
+}
+```
+
+Install platform-specific plugins explicitly with `--select plugins/<plugin-name>` so non-target runtimes do not receive optional integrations.
+
+## README update checklist
+
+When changing package shape, update the README in the same PR:
+
+- State that OpenPack (`openpack.json`) is canonical.
+- Remove references to deprecated `agentwheel sync`; use `agentwheel install --dry-run` and `agentwheel install`.
+- Show runtime-neutral install flow.
+- Show optional plugin install flow with `--select plugins/<name>`.
+- Mention that generated runtime files are not committed.
+
+## Registry/catalogue update pattern
+
+AgentWheel registry source of truth is usually `index.json`.
+
+- Update `index.json` entry description/tags for the package.
+- Do not commit generated catalogue files (`catalogue-data.json`, `catalogue-vercel-index.json`) unless the repo specifically requires it for that PR.
+- If there is a workflow that regenerates catalogue data on `main` after `index.json` or `catalogue/**` changes, leave generated data to that workflow. This avoids noisy diffs from volatile GitHub stars, timestamps, and sitemap refreshes.
+- Verify JSON only:
+
+```bash
+python3 -m json.tool index.json >/tmp/index-check.json
+```
+
+Then open a small registry PR that references the package PR.