From df352af9fd581ad1537ba3c8a851b5ddecd1c5d6 Mon Sep 17 00:00:00 2001 From: rishabhraj36 Date: Sat, 18 Jul 2026 14:06:51 +0530 Subject: [PATCH 1/2] docs: fix community plugin promotion workflow --- skills/webcmd-adapter-author/SKILL.md | 2 +- .../references/adapter-template.md | 25 ++++++++----------- 2 files changed, 12 insertions(+), 15 deletions(-) diff --git a/skills/webcmd-adapter-author/SKILL.md b/skills/webcmd-adapter-author/SKILL.md index de7b5066..2ff5c745 100644 --- a/skills/webcmd-adapter-author/SKILL.md +++ b/skills/webcmd-adapter-author/SKILL.md @@ -253,7 +253,7 @@ Check these off step by step: - **The `browser:` field determines the `func` signature:** `browser:false -> (args)`, `browser:true -> (page, args)`. If this is reversed, `args` may actually be a debug flag and all external parameters can silently fall back to defaults. - Throw the correct typed error for known failures according to [`references/typed-errors.md`](./references/typed-errors.md). **Do not** silently `return []`, **do not** silently `return [{sentinel}]`, and **do not** silently clamp external parameters with `Math.max/min`. - **Persistent sessions keep stale DOM between commands.** `siteSession: 'persistent'` shares one tab per site; leftover modals/drawers from the previous command leak into the next one. State-sensitive write commands (checkout flows) should add `freshPage: true` (new tab, same lease — cookies/login/location survive). Verify session-scoped context (login, selected city/date) *before* side effects, and embed such context in URLs/IDs your command emits for sibling commands. See `references/adapter-template.md` and "Persistent Sessions and State Hygiene" in `docs/authoring.mdx`. -- For private iteration, write `~/.webcmd/clis//.js` to avoid a build. When the user says to promote a CLI, create a main-repo plugin with `webcmd plugin create --dir plugins/`, copy the real command files into it, delete scaffold sample commands, register it in root `webcmd-plugin.json`, remove the local `~/.webcmd/clis/` shadow, install the plugin, then run `webcmd validate ` and smoke commands. See `references/adapter-template.md` for details. +- For private iteration, write `~/.webcmd/clis//.js` to avoid a build. When the user says to promote a CLI, determine the plugin name (default to ``) and collect any missing author display name and GitHub handle before scaffolding. Create the main-repo plugin with `webcmd plugin create --dir plugins/ --author-name "" --author-handle ""`, copy the real command files into it, delete scaffold sample commands, remove the local `~/.webcmd/clis/` shadow, install the plugin, then run `webcmd validate ` and smoke commands. Do not hand-edit the root `webcmd-plugin.json` or generated README catalog: the community-plugin sync discovers `plugins/*/webcmd-plugin.json` and updates both after merge. See `references/adapter-template.md` for details. - Write site memory every round: no memory -> use skill -> produce memory -> next time becomes a five-minute task. - **After a site's first command passes verify, stop and ask the user for their use cases before recommending next set of commands.** See Runbook Step 13. - **Raw dumps, packet captures, and HTML samples from debugging may only be written to `~/.webcmd/sites//fixtures/` or `/tmp/`. Never leave `.dbg-*.html`, `raw-*.json`, `sample.*`, or similar temporary files in the repo root, `clis//`, or the current working directory.** diff --git a/skills/webcmd-adapter-author/references/adapter-template.md b/skills/webcmd-adapter-author/references/adapter-template.md index 4ea31466..2315d70d 100644 --- a/skills/webcmd-adapter-author/references/adapter-template.md +++ b/skills/webcmd-adapter-author/references/adapter-template.md @@ -18,28 +18,25 @@ Write the working file at: Promote a community CLI to the main repo as a plugin: +Determine the plugin name (default to ``) and collect the author's display name and GitHub handle if they are not already known. + ```bash -webcmd plugin create --dir plugins/ --description " commands for Webcmd" -cp ~/.webcmd/clis//*.js plugins// -rm plugins//hello.ts plugins//greet.ts 2>/dev/null || true +webcmd plugin create \ + --dir plugins/ \ + --description " commands for Webcmd" \ + --author-name "" \ + --author-handle "" +cp ~/.webcmd/clis//*.js plugins// +rm plugins//hello.ts plugins//greet.ts 2>/dev/null || true ``` -Then add `` to the root `webcmd-plugin.json` `plugins` map: - -```json -"": { - "path": "plugins/", - "version": "0.1.0", - "description": " commands for Webcmd", - "webcmd": ">=0.2.0" -} -``` +Do not hand-edit the root `webcmd-plugin.json` or the generated community-plugin section in `README.md`. After merge, the community-plugin sync discovers `plugins/*/webcmd-plugin.json`, validates the author metadata, and updates both generated catalogs. Before handing off, remove the private shadow and prove the plugin path works: ```bash rm -rf ~/.webcmd/clis/ -webcmd plugin install file://$PWD/plugins/ +webcmd plugin install file://$PWD/plugins/ webcmd validate webcmd --help ``` From 92ca156768f2258738ea2a23e6082c7d9ee6f5d9 Mon Sep 17 00:00:00 2001 From: rishabhraj36 Date: Sat, 18 Jul 2026 14:14:06 +0530 Subject: [PATCH 2/2] docs: align plugin usage with community sync --- skills/webcmd-usage/SKILL.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/skills/webcmd-usage/SKILL.md b/skills/webcmd-usage/SKILL.md index 70982595..0c86d81f 100644 --- a/skills/webcmd-usage/SKILL.md +++ b/skills/webcmd-usage/SKILL.md @@ -117,9 +117,9 @@ Storage paths: - Private: `~/.webcmd/clis//.js` - Public (official bundle): `clis//.js` -- Public (community PRs): `plugins//` plus root `webcmd-plugin.json` registration +- Public (community PRs): `plugins//` with its own `webcmd-plugin.json` -The main Webcmd repo is itself a plugin monorepo: promoted community CLIs belong under `plugins//` and must be registered in the root `webcmd-plugin.json`. +The main Webcmd repo is itself a plugin monorepo: promoted community CLIs belong under `plugins//`. Do not hand-edit the root `webcmd-plugin.json` or generated README catalog; after merge, the community-plugin sync discovers each plugin manifest and updates both automatically. Scaffolding and checks: