@penclipai/adapter-codex-local 2026.512.0 → 2026.514.0-canary.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@penclipai/adapter-codex-local",
-  "version": "2026.512.0",
+  "version": "2026.514.0-canary.0",
   "license": "MIT",
   "homepage": "https://github.com/penclipai/paperclip-cn",
   "bugs": {
@@ -38,7 +38,7 @@
     "skills"
   ],
   "dependencies": {
-    "@penclipai/adapter-utils": "2026.512.0",
+    "@penclipai/adapter-utils": "2026.514.0-canary.0",
     "picocolors": "^1.1.1"
   },
   "devDependencies": {

package/skills/paperclip-create-plugin/SKILL.md

@@ -1,23 +1,34 @@
 ---
 name: paperclip-create-plugin
 description: >
-  Create new Paperclip plugins with the current alpha SDK/runtime. Use when
-  scaffolding a plugin package, adding a new example plugin, or updating plugin
-  authoring docs. Covers the supported worker/UI surface, route conventions,
-  scaffold flow, and verification steps.
+  Create and develop external Paperclip plugins with the CLI-first workflow.
+  Use when scaffolding a new plugin, working on a local plugin against a running
+  Paperclip instance, or updating plugin authoring docs. Covers `penclip
+  plugin init`, the local install loop via `penclip plugin install <path>`,
+  worker/UI rebuild and reload semantics, and the required success checklist.
 ---
 
-# Create a Paperclip Plugin
+# Create and develop a Paperclip plugin
 
-Use this skill when the task is to create, scaffold, or document a Paperclip plugin.
+Use this skill when the task is to create, scaffold, or iterate on a Paperclip plugin against a local Paperclip instance.
 
-## 1. Ground rules
+## 1. Default: build the plugin OUTSIDE Paperclip core
 
-Read these first when needed:
+Plugins are their own packages. Unless the task **explicitly** asks for a bundled in-repo example, do not add plugin source under `packages/plugins/` in this repo.
+
+- Scaffold the plugin into a directory outside the Paperclip checkout (e.g. `~/dev/paperclip-plugins/<name>`).
+- Install it into the running Paperclip instance by local absolute path.
+- Edit code in the external package; let Paperclip pick up rebuilt output.
+
+Only edit Paperclip core itself when the user asks to surface a plugin as a bundled example (`server/src/routes/plugins.ts`, in-repo example lists, docs).
+
+## 2. Ground rules
+
+Reference docs when you need detail:
 
 1. `doc/plugins/PLUGIN_AUTHORING_GUIDE.md`
 2. `packages/plugins/sdk/README.md`
-3. `doc/plugins/PLUGIN_SPEC.md` only for future-looking context
+3. `doc/plugins/PLUGIN_SPEC.md` — future-looking context only
 
 Current runtime assumptions:
 
@@ -28,16 +39,25 @@ Current runtime assumptions:
 - no host-provided shared plugin UI component kit yet
 - `ctx.assets` is not supported in the current runtime
 
-## 2. Preferred workflow
+## 3. CLI-first scaffold workflow
 
-Use the scaffold package instead of hand-writing the boilerplate:
+Use `penclip plugin init`. Do not invoke the scaffold package node entrypoint by hand unless the CLI command is unavailable in the environment.
 
 ```bash
-pnpm --filter @penclipai/create-paperclip-plugin build
-node packages/plugins/create-paperclip-plugin/dist/index.js <npm-package-name> --output <target-dir>
+penclip plugin init @acme/my-plugin --output ~/dev/paperclip-plugins
 ```
 
-For a plugin that lives outside the Paperclip repo, pass `--sdk-path` and let the scaffold snapshot the local SDK/shared packages into `.paperclip-sdk/`:
+Useful flags (all optional):
+
+- `--output <dir>` — parent directory; the command creates `<dir>/<unscoped-name>/`. Defaults to the current directory.
+- `--template <default|connector|workspace|environment>` — starter template.
+- `--category <connector|workspace|automation|ui|environment>` — manifest category.
+- `--display-name <name>`, `--description <text>`, `--author <name>` — manifest metadata.
+- `--sdk-path <path>` — snapshot the local SDK from a Paperclip checkout into `.paperclip-sdk/` (useful when developing against an unreleased SDK).
+
+On success the command prints the exact next commands (`cd`, `pnpm install`, `pnpm dev`, `penclip plugin install <abs-path>`). Run them in order.
+
+If `penclip` is not on PATH in your environment, fall back to:
 
 ```bash
 pnpm --filter @penclipai/create-paperclip-plugin build
@@ -46,20 +66,40 @@ node packages/plugins/create-paperclip-plugin/dist/index.js @acme/plugin-name \
   --sdk-path /absolute/path/to/paperclip/packages/plugins/sdk
 ```
 
-Recommended target inside this repo:
+## 4. Local install + rebuild loop
+
+In the scaffolded plugin folder:
+
+```bash
+pnpm install
+pnpm dev            # esbuild --watch: rebuilds dist/manifest.js, dist/worker.js, dist/ui/
+penclip plugin install /absolute/path/to/my-plugin
+```
+
+Notes:
 
-- `packages/plugins/examples/` for example plugins
-- another `packages/plugins/<name>/` folder if it is becoming a real package
+- `penclip plugin install` auto-detects local paths (absolute, `./`, `../`, `~`, or an existing relative folder) and forwards `isLocalPath: true` to the server. Pass `--local` to force local mode if the heuristic is ambiguous.
+- Paths are resolved to absolute paths before being sent to the server.
+- The server watches built outputs (`dist/`) for local-path plugins and restarts the plugin worker on rebuild — you do not need to reinstall after every edit.
+- UI hot reload via the SDK dev server (`pnpm dev:ui`, port `4177`) is optional and template-dependent; only mention it if the template wires `devUiUrl` and you verified it works end to end.
+- `--version` only applies to npm package installs. Combining it with a local path is an error.
 
-## 3. After scaffolding
+After install, inspect with:
 
-Check and adjust:
+```bash
+penclip plugin list
+penclip plugin inspect <plugin-key>
+```
+
+## 5. After scaffolding, sanity-check the package
+
+Open and confirm:
 
-- `src/manifest.ts`
-- `src/worker.ts`
-- `src/ui/index.tsx`
-- `tests/plugin.spec.ts`
-- `package.json`
+- `src/manifest.ts` — declared capabilities and slots
+- `src/worker.ts` — worker entry
+- `src/ui/index.tsx` — UI entry (if applicable)
+- `tests/plugin.spec.ts` — placeholder test
+- `package.json` — `paperclipPlugin` block points at `dist/manifest.js`, `dist/worker.js`, `dist/ui/`
 
 Make sure the plugin:
 
@@ -68,34 +108,47 @@ Make sure the plugin:
 - does not import host UI component stubs
 - keeps UI self-contained
 - uses `routePath` only on `page` slots
-- is installed into Paperclip from an absolute local path during development
 
-## 4. If the plugin should appear in the app
+## 6. Verification (run before declaring success)
 
-For bundled example/discoverable behavior, update the relevant host wiring:
+From the plugin folder:
 
-- bundled example list in `server/src/routes/plugins.ts`
-- any docs that list in-repo examples
+```bash
+pnpm typecheck
+pnpm test
+pnpm build
+```
 
-Only do this if the user wants the plugin surfaced as a bundled example.
+If the plugin is already running under `pnpm dev`, you can keep the watcher up and run `pnpm typecheck` and `pnpm test` in a separate shell.
 
-## 5. Verification
+If you changed Paperclip SDK/host/plugin runtime code in addition to the plugin, also run the relevant Paperclip workspace checks.
 
-Always run:
+## 7. Success checklist (report this back)
 
-```bash
-pnpm --filter <plugin-package> typecheck
-pnpm --filter <plugin-package> test
-pnpm --filter <plugin-package> build
-```
+When you finish a local plugin task, report:
+
+- **Scaffold path** — absolute path of the created plugin folder.
+- **Commands run** — the exact `penclip plugin init`, `pnpm install`, `pnpm dev`, `penclip plugin install <path>` invocations (and any verification commands).
+- **Install status** — output of `penclip plugin list` / `plugin inspect` (plugin key, version, status). Note if `status` is anything other than `ready` and include `lastError`.
+- **Tests / build result** — `pnpm typecheck`, `pnpm test`, `pnpm build` pass/fail with the failing output if any.
+- **Reload limitations** — call out anything that did not hot-reload (e.g. manifest changes required a reinstall, UI dev server was not wired, etc.).
+
+If any item is missing, mark it as such — do not silently skip.
+
+## 8. When NOT to edit Paperclip core
+
+Do not add the plugin under `packages/plugins/` or update bundled-example wiring unless the user explicitly asks for a bundled example. Local-path installs are the supported development model; npm packages are the production deployment path.
+
+If the user does ask for a bundled example, also update:
 
-If you changed SDK/host/plugin runtime code too, also run broader repo checks as appropriate.
+- `server/src/routes/plugins.ts` example list
+- any docs that enumerate in-repo example plugins
 
-## 6. Documentation expectations
+## 9. Documentation expectations
 
 When authoring or updating plugin docs:
 
 - distinguish current implementation from future spec ideas
 - be explicit about the trusted-code model
 - do not promise host UI components or asset APIs
-- prefer npm-package deployment guidance over repo-local workflows for production
+- prefer local-path development + npm-package deployment guidance over repo-local workflows