From 68591f6eff5345216964e153d41a753c4ccbcc78 Mon Sep 17 00:00:00 2001
From: ayushsingh82 <ayushsinghmi711@gmail.com>
Date: Fri, 21 Aug 2026 17:57:57 +0530
Subject: [PATCH] skills: force-load adapter-author when creating a command

webcmd-usage force-loaded webcmd-browser for raw browser work but had
no equivalent for authoring. Agents that discovered browser init on
their own then skipped the durable authoring surfaces: they hand-wrote
notes next to the adapter instead of using site-memory commands, and
invented a sibling *_verify command instead of running webcmd verify /
webcmd browser verify.

- webcmd-usage now requires loading webcmd-adapter-author before
  creating, revising, or privately overriding a command, mirroring the
  existing browser-work requirement.
- Added Do-Not lines in both skills against hand-written notes and
  sibling verify commands.
- webcmd-adapter-author now documents that CLI flags map onto args by
  the declared name (e.g. args['note-id']), not a camelCase alias.

Fixes #386
---
 skill-src/webcmd-adapter-author/SKILL.src.md | 7 +++++++
 skill-src/webcmd-usage/SKILL.src.md          | 8 ++++++++
 skills/webcmd-adapter-author/SKILL.md        | 2 ++
 skills/webcmd-usage/SKILL.md                 | 4 ++++
 src/skills.test.ts                           | 4 ++++
 5 files changed, 25 insertions(+)

diff --git a/skill-src/webcmd-adapter-author/SKILL.src.md b/skill-src/webcmd-adapter-author/SKILL.src.md
index e6dc1df3..fe857854 100644
--- a/skill-src/webcmd-adapter-author/SKILL.src.md
+++ b/skill-src/webcmd-adapter-author/SKILL.src.md
@@ -257,6 +257,8 @@ Check these off step by step:
 - Adapters import only `@agentrhq/webcmd/registry` and `@agentrhq/webcmd/errors`; do not add third-party dependencies.
 - Browser-run’s Playwright-style `page` and adapter `func(page,args)` are different contracts. Preserve evidence and behavior, not syntax. Implement adapters with the existing `IPage`, pipeline, Node-fetch, or interceptor APIs.
 - The `columns` array and `func` return object keys must match exactly, including order.
+- CLI flags map onto `args` by the declared `name`. `{ name: 'note-id' }` is `args['note-id']`, not `args.noteId`. A `type: 'boolean'` flag is `true` when passed. Do not grep the framework for camelCase aliases.
+- Verification is `webcmd browser verify` / `webcmd verify`. Do not add a second command whose name ends in verify.
 - **Intermediate parsing object keys must not overlap any `columns` entry.** Otherwise silent-column-drop audits can misread the adapter. Use dedicated internal names and destructure with aliases when pushing rows.
 - **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`.
@@ -284,4 +286,9 @@ Author-only. Stripped by litprompt, so it costs the running agent nothing.
 Append one dated line whenever a correction lands, or whenever an approach
 is tried and rejected. Record what was tried and why it failed, not just
 what won.
+
+- 2026-08-21: Agents skipped this skill, wrote notes next to the adapter, and
+  invented a sibling verify command. Usage now force-loads this skill for
+  create/revise/override. Args keys match declared `name`, not Commander camelCase (#386).
 -->
+
diff --git a/skill-src/webcmd-usage/SKILL.src.md b/skill-src/webcmd-usage/SKILL.src.md
index d30ba0ac..d721e36f 100644
--- a/skill-src/webcmd-usage/SKILL.src.md
+++ b/skill-src/webcmd-usage/SKILL.src.md
@@ -41,6 +41,8 @@ Do not install Node.js or silently fall back to `npx`.
 
 **REQUIRED SUB-SKILL:** Before raw browser work, load `webcmd-browser`.
 
+**REQUIRED SUB-SKILL:** Before creating, revising, or privately overriding a command, load `webcmd-adapter-author`.
+
 ## Install
 
 ```bash
@@ -282,6 +284,8 @@ Do not invoke these removed commands:
 - Do not assume every adapter needs a browser; check `strategy`.
 - Do not silently fall back from a failing adapter to hand-rolled `fetch`; use `--trace retain-on-failure` first.
 - Do not treat a raw 403 or challenge from a direct fetch as a browser gate; run `webcmd web fetch --url <url>` first.
+- Do not store authoring notes in a hand-written file next to the adapter; use the site-memory commands (`webcmd site note`, `webcmd site endpoint`, `webcmd site field-map`).
+- Do not invent a sibling verify command; use `webcmd verify` or `webcmd browser verify`.
 
 <!-- @
 ## Learnings log
@@ -291,6 +295,10 @@ Append one dated line whenever a correction lands, or whenever an approach
 is tried and rejected. Record what was tried and why it failed, not just
 what won.
 
+- 2026-08-21: Usage force-loaded `webcmd-browser` for raw browser work but not
+  `webcmd-adapter-author` for create/revise/override. Agents then skipped
+  site-memory and invented a sibling verify command (#386).
+
 - 2026-08-20: A prior generic-client 403 is not authority to escalate to the
   browser; browser use remains gated on Webcmd returning `FETCH_BLOCKED` or
   `FETCH_REQUIRES_BROWSER`.
diff --git a/skills/webcmd-adapter-author/SKILL.md b/skills/webcmd-adapter-author/SKILL.md
index 21aa5220..0fac5556 100644
--- a/skills/webcmd-adapter-author/SKILL.md
+++ b/skills/webcmd-adapter-author/SKILL.md
@@ -257,6 +257,8 @@ Check these off step by step:
 - Adapters import only `@agentrhq/webcmd/registry` and `@agentrhq/webcmd/errors`; do not add third-party dependencies.
 - Browser-run’s Playwright-style `page` and adapter `func(page,args)` are different contracts. Preserve evidence and behavior, not syntax. Implement adapters with the existing `IPage`, pipeline, Node-fetch, or interceptor APIs.
 - The `columns` array and `func` return object keys must match exactly, including order.
+- CLI flags map onto `args` by the declared `name`. `{ name: 'note-id' }` is `args['note-id']`, not `args.noteId`. A `type: 'boolean'` flag is `true` when passed. Do not grep the framework for camelCase aliases.
+- Verification is `webcmd browser verify` / `webcmd verify`. Do not add a second command whose name ends in verify.
 - **Intermediate parsing object keys must not overlap any `columns` entry.** Otherwise silent-column-drop audits can misread the adapter. Use dedicated internal names and destructure with aliases when pushing rows.
 - **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`.
diff --git a/skills/webcmd-usage/SKILL.md b/skills/webcmd-usage/SKILL.md
index 326d0dad..fb03cdfb 100644
--- a/skills/webcmd-usage/SKILL.md
+++ b/skills/webcmd-usage/SKILL.md
@@ -41,6 +41,8 @@ Do not install Node.js or silently fall back to `npx`.
 
 **REQUIRED SUB-SKILL:** Before raw browser work, load `webcmd-browser`.
 
+**REQUIRED SUB-SKILL:** Before creating, revising, or privately overriding a command, load `webcmd-adapter-author`.
+
 ## Install
 
 ```bash
@@ -282,3 +284,5 @@ Do not invoke these removed commands:
 - Do not assume every adapter needs a browser; check `strategy`.
 - Do not silently fall back from a failing adapter to hand-rolled `fetch`; use `--trace retain-on-failure` first.
 - Do not treat a raw 403 or challenge from a direct fetch as a browser gate; run `webcmd web fetch --url <url>` first.
+- Do not store authoring notes in a hand-written file next to the adapter; use the site-memory commands (`webcmd site note`, `webcmd site endpoint`, `webcmd site field-map`).
+- Do not invent a sibling verify command; use `webcmd verify` or `webcmd browser verify`.
diff --git a/src/skills.test.ts b/src/skills.test.ts
index b4f04d7e..cfc972be 100644
--- a/src/skills.test.ts
+++ b/src/skills.test.ts
@@ -198,6 +198,10 @@ describe('webcmd skills content', () => {
       'utf8',
     );
     expect(usage).toMatch(/existing adapter command first[\s\S]{0,220}load `webcmd-browser`[\s\S]{0,120}root `--session <session-id>`/i);
+    expect(usage).toContain('Before creating, revising, or privately overriding a command, load `webcmd-adapter-author`');
+    expect(usage).toContain('Do not invent a sibling verify command');
+    expect(author).toContain("args['note-id']");
+    expect(author).toContain('Do not add a second command whose name ends in verify');
     expect(browser).toMatch(/`tabs`, `bind --page`, `snapshot`, and `run`/i);
     expect(browser).toContain('webcmd --session <session-id> browser tabs');
     expect(browser).toContain('webcmd --session <session-id> browser bind --page');