docs(plan): scope next OpenClaw milestone for ClawHub registry

2026-02-16 00:08:58 -08:00
parent 41cb82802e
commit 4c6d1d724d
2 changed files with 131 additions and 1 deletions
@@ -0,0 +1,123 @@
+# ClawHub Registry — Scoped Implementation Checklist
+
+**Date:** 2026-02-16
+
+**Parent roadmap:** `docs/plans/2026-02-15-openclaw-gap-roadmap.md`
+
+**Goal:** Close the gap item "ClawHub / community skill registry" with a safe, incremental registry flow that supports discovery and installation without weakening current skill safety controls.
+
+## Scope
+
+### In scope
+
+- Add a read-only skill registry source for discovery.
+- Add CLI registry listing/details and install-by-id flow.
+- Reuse existing skill safety scanner and install policy gates.
+- Add docs and tests for end-to-end registry flow.
+
+### Out of scope (this milestone)
+
+- Arbitrary third-party repository execution without safety checks.
+- Auto-update/auto-upgrade daemons for installed skills.
+- Full signed-package ecosystem (can be follow-up phase).
+
+## Phase Plan
+
+### Phase 1: Registry Source + Types
+
+Checklist:
+
+- [ ] Add registry types + parser module (`src/skills/registrySource.ts` or equivalent).
+- [ ] Support one source shape:
+  - [ ] local JSON file path (for deterministic tests and offline use)
+  - [ ] optional HTTPS URL source (fetch + timeout + parse)
+- [ ] Validate required fields for each skill entry:
+  - [ ] `id`, `name`, `version`, `source`, `summary`
+  - [ ] optional trust metadata (`publisher`, `homepage`, `sha256`)
+- [ ] Reject malformed registry entries with actionable errors.
+
+Acceptance:
+
+- `flynn skills` internals can load a normalized registry catalog.
+
+Tests:
+
+- [ ] Unit tests for parser/validation edge cases.
+
+---
+
+### Phase 2: CLI Discovery UX
+
+Checklist:
+
+- [ ] Add `flynn skills registry list` command (table/text + `--json`).
+- [ ] Add `flynn skills registry show <id>` command (entry detail + source fields).
+- [ ] Add filtering options:
+  - [ ] `--search <term>`
+  - [ ] `--publisher <name>`
+- [ ] Ensure output clearly marks trust metadata as declared/unverified.
+
+Acceptance:
+
+- Operators can discover candidate skills without leaving Flynn tooling.
+
+Tests:
+
+- [ ] Command tests for text + JSON output paths.
+
+---
+
+### Phase 3: Install by Registry ID
+
+Checklist:
+
+- [ ] Add `flynn skills install --registry-id <id>` resolution path.
+- [ ] Support source forms:
+  - [ ] git URL
+  - [ ] archive URL
+  - [ ] local path
+- [ ] Route resolved sources through existing installer + scanner pipeline.
+- [ ] Require explicit confirmation flag for non-local sources (for example `--confirm`).
+- [ ] Emit audit events for registry-driven installs (id + source + outcome).
+
+Acceptance:
+
+- Install-by-id works and unsafe skills still fail scanner checks.
+
+Tests:
+
+- [ ] Installer tests for registry-id resolution and scan failures.
+- [ ] CLI tests for confirmation and error paths.
+
+---
+
+### Phase 4: Docs + Runtime Visibility
+
+Checklist:
+
+- [ ] Update `README.md` skills section with registry usage.
+- [ ] Update `docs/security/SAFE_PERSONAL_AGENT.md` with registry trust model.
+- [ ] Add doctor diagnostics:
+  - [ ] registry source reachable/parsible
+  - [ ] clear warning when registry disabled/unconfigured
+
+Acceptance:
+
+- Operator docs explain safe usage and tradeoffs.
+
+Tests:
+
+- [ ] Doctor tests for registry health reporting.
+
+## Security Guardrails
+
+- [ ] Registry metadata is never treated as trusted code.
+- [ ] Skill scanner remains mandatory before skill becomes available.
+- [ ] Prompt injection and symlink/binary checks still gate registry-installed skills.
+- [ ] Secrets are never accepted from registry metadata.
+
+## Final Validation
+
+- [ ] `pnpm typecheck`
+- [ ] `pnpm test:run`
+- [ ] Update `docs/plans/state.json` to `completed` with summary + test status once all phases land.
@@ -211,6 +211,13 @@
      "updated": "2026-02-16",
      "summary": "Completed roadmap closure for the six prioritized OpenClaw gaps: per-tier credential system v2 (API + OAuth/token), Vercel AI Gateway provider, skill safety scanner, elevated mode, Matrix adapter, and deployment targets (Nix + PaaS)."
    },
+    "clawhub-registry": {
+      "file": "2026-02-16-clawhub-registry-checklist.md",
+      "status": "planned",
+      "date": "2026-02-16",
+      "updated": "2026-02-16",
+      "summary": "Scoped the next OpenClaw-gap milestone as a phased ClawHub-style registry implementation: catalog source + validation, CLI discovery, install-by-id via existing scanner pipeline, and docs/doctor visibility."
+    },
    "credential-system-v2-api-and-oauth": {
      "file": "2026-02-15-credential-system-v2-api-and-oauth-checklist.md",
      "status": "completed",
@@ -2750,7 +2757,7 @@
    "gmail_auth_cli": "flynn gmail-auth command implemented with OAuth2 flow, doctor check, config routed to Telegram",
    "native_audio_support": "completed — smart routing for native audio (Gemini/OpenAI/GitHub) vs Whisper transcription fallback",
    "remaining_phases_completion": "Phase 1: 3/3 (100%) — context levels, command registry, memory structure. Phase 2: 3/3 (100%) — component registry, confidence routing, history index. Phase 3: 2/2 (100%) — adaptive memory/compaction, truthfulness/autonomy hardening",
-    "next_up": "Pick the next OpenClaw gap milestone and create a scoped checklist (candidates: ClawHub registry, Bonjour/mDNS discovery, synthetic provider)"
+    "next_up": "Implement ClawHub registry milestone checklist (Phase 1: registry source/types and validation)"
  },
  "soul_md_and_cron_create": {
    "date": "2026-02-11",