From de1fb1a9487d1c5d411101f5b707aa4560a980b2 Mon Sep 17 00:00:00 2001 From: ayushsingh82 Date: Sat, 8 Aug 2026 08:51:52 +0530 Subject: [PATCH] docs: make CLI-promotion confirmation an explicit, hard-to-read-past gate MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The adapter-author skill gated promoting a private CLI into a repo plugin behind "when the user says to promote a CLI" — a soft clause buried inside a longer sentence. Across three separate adapter builds, a general instruction like "build a real, working adapter, this will be run by the user once done" was read as implicit authorization for the entire pipeline (private iteration + promotion + install), with no separate checkpoint asking whether to promote. Promotion writes into the shared repo and is effectively the moment an adapter goes from drafted to shipped, so it needs its own explicit ask. State the rule as a standalone, bolded gate, note that building and verifying under private iteration already satisfies "build a working adapter" on its own, and have the agent state the checkpoint out loud before promoting instead of continuing silently. Mirror the same note at the top of adapter-template.md's promotion section. Fixes #223 --- skills/webcmd-adapter-author/SKILL.md | 2 +- skills/webcmd-adapter-author/references/adapter-template.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/skills/webcmd-adapter-author/SKILL.md b/skills/webcmd-adapter-author/SKILL.md index 6e4fbbb0..7513c88c 100644 --- a/skills/webcmd-adapter-author/SKILL.md +++ b/skills/webcmd-adapter-author/SKILL.md @@ -263,7 +263,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. Building, testing, and verifying the adapter under private iteration fully satisfies a request to "build a working adapter" on its own. **Do not run `webcmd plugin create` or otherwise promote a CLI out of `~/.webcmd/clis//` until the user has explicitly confirmed they want it pushed into the repo (or a PR raised).** A general instruction to build or ship an adapter is not that confirmation — state the checkpoint out loud ("The adapter works under private iteration — want me to promote it into `plugins//` now?") and wait for a yes before promoting. Once confirmed: 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. - 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, `plugins//`, 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 20871dac..dc74115a 100644 --- a/skills/webcmd-adapter-author/references/adapter-template.md +++ b/skills/webcmd-adapter-author/references/adapter-template.md @@ -15,7 +15,7 @@ webcmd browser init / This scaffolds `~/.webcmd/clis//.js` with a `Strategy.PUBLIC` placeholder — `init` takes no flags, so set the real `strategy:` value (and the other `TODO` fields) by hand once the file exists. -Promote a community CLI to the main repo as a plugin: +Promote a community CLI to the main repo as a plugin — **only after the user has explicitly confirmed they want it pushed into the repo**; a general instruction to build a working adapter is not that confirmation (see `SKILL.md`'s Key Conventions): ```bash webcmd plugin create --dir plugins/ --description " commands for Webcmd"