From 1dc721f55c9c3168acd213706725bb73a740b912 Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Fri, 17 Jul 2026 12:11:07 -0400 Subject: [PATCH 1/4] docs: codify skill-naming grammar and cross-plugin reference rules MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Imperative-verb grammar with fixed verb meanings (audit/scan read-only, check gate, clean/tidy/fix mutate, setup, update), noun-router and vendor-wrapper exceptions, and the audit-mutation override rule — a documented deviation from the official gerund preference, chosen for sentence-composability and collection consistency. Cross-plugin references must be declared dependencies or "if installed"-guarded. Includes the shadowed-skill-renames contract that drives the rename PRs. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01YVApnNGoKxYMJKNQx1QK8C --- docs/PLUGIN-PHILOSOPHY.md | 44 +++++++++++ docs/topics/shadowed-skill-renames/PLAN.md | 87 ++++++++++++++++++++++ 2 files changed, 131 insertions(+) create mode 100644 docs/topics/shadowed-skill-renames/PLAN.md diff --git a/docs/PLUGIN-PHILOSOPHY.md b/docs/PLUGIN-PHILOSOPHY.md index 9f89b67d4..4a66d85a7 100644 --- a/docs/PLUGIN-PHILOSOPHY.md +++ b/docs/PLUGIN-PHILOSOPHY.md @@ -20,11 +20,44 @@ Keep plugins horizontally decoupled: or an optional namespaced skill invocation. - Every plugin remains useful alone. If an optional collaborator is absent, use a documented fallback or report the missing optional capability clearly. +- A reference to another plugin is either declared or guarded. A collaborator the plugin's contract + requires is listed in the manifest `dependencies` array, and Claude Code installs it automatically; + an optional collaborator is invoked behind an "if installed" guard with the documented fallback + above. A bare unguarded cross-plugin reference is a defect. This follows Claude Code's distinction between project-specific standalone configuration and plugins intended for reusable, versioned distribution. Namespaced skill invocations are part of that isolation, not an implementation detail. +## Naming + +A skill name is an imperative verb phrase; the plugin namespace supplies the object +(`/machine-health:audit`, `/source-control:commit`). Names compose into instruction sentences — +"/discovery:explore the module, then /planning:interview me" — and one grammar keeps every name in +the marketplace predictable. This is a deliberate, documented deviation from the official authoring +guidance's gerund preference; that guidance sanctions imperative alternatives and treats +collection-wide consistency as a requirement, which this section provides. + +Verb meanings are fixed: + +| Verb | Contract | +|---|---| +| `audit`, `scan` | Read-only findings report. Mutation only behind an explicit user override such as an autofix argument, never on bare invocation; safety qualifiers may narrow what an override touches. | +| `check` | Deterministic pass/fail gate. | +| `clean`, `tidy`, `fix` | Mutates the target. | +| `setup` | Configures the plugin for a consumer, per the setup section below. | +| `update` | Refreshes vendored upstream material. | + +Nouns are reserved for knowledge routers (`principles`, `methodology`) and lifecycle-object routers +(`worktree`, `pull-request`). Two further documented exceptions: a single-skill vendor-CLI wrapper +repeats its tool name (`firecrawl:firecrawl`), and a `-deep` suffix marks the heavier +isolated-execution tier of a sibling skill (`explore`/`explore-deep`). + +The frontmatter `name` always matches the skill directory name, in the character set the Agent +Skills specification allows. Never degrade a name to dodge a built-in command: plugin skills are +namespaced and cannot collide with other levels. When a name matches a built-in, the bare token +still belongs to the built-in; the namespaced form is the plugin skill's only command. + ## Configuration ownership and scope Choose one authoritative owner for each value: @@ -127,3 +160,14 @@ Verified 2026-07-14: scopes. - `melodic-software/standards` engineering philosophy and cross-platform review criteria — repository design and verification policy. + +Verified 2026-07-17: + +- [Plugin dependencies](https://code.claude.com/docs/en/plugin-dependencies) — the `dependencies` + array, automatic installation, and version constraints. +- [Skills](https://code.claude.com/docs/en/skills) — command-name derivation and the plugin skill + namespace. +- [Skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) + — naming-convention guidance this document deviates from deliberately. +- [Agent Skills specification](https://agentskills.io/specification) — `name` field constraints and + directory matching. diff --git a/docs/topics/shadowed-skill-renames/PLAN.md b/docs/topics/shadowed-skill-renames/PLAN.md new file mode 100644 index 000000000..29897105a --- /dev/null +++ b/docs/topics/shadowed-skill-renames/PLAN.md @@ -0,0 +1,87 @@ +# Shadowed skill renames + +## Brief + +**TLDR:** Undo the pre-migration shadow-compromise skill names (namespacing removed the constraint), fix audit-surfaced semantic misfits, extract a `domain-driven-design` plugin, and codify the naming grammar + cross-plugin reference rules in `docs/PLUGIN-PHILOSOPHY.md` — as a sequenced set of breaking-change PRs with no renames-map entries. + +### Goal + +Every skill and plugin name in the marketplace denotes what it actually does, follows one codified grammar, and the conventions that produced this state are written down so future names are predictable. + +### Locked decisions + +**Naming grammar (codify in PLUGIN-PHILOSOPHY, PR 1):** + +- Imperative verbs; namespace supplies the object. Documented deviation from the official gerund preference (cite the page, copy nothing) — rationale: sentence-composability ("/explore X, then /research, then /interview me") and collection-consistency (itself official guidance). +- Verb meanings: `audit`/`scan` = read-only report; `check` = deterministic pass/fail gate; `clean`/`tidy`/`fix` = mutates; `setup` = plugin config; `update` = vendor refresh. +- `audit` mutation: read-only by default; mutation only behind an explicit user override (flag/argument), safety qualifiers permitted. Bare invocation never mutates. +- Sanctioned exceptions: nouns for knowledge routers (`principles`, `methodology`) and lifecycle-object routers (`worktree`, `pull-request`); vendor-wrapper stutter (`firecrawl:firecrawl`); `-deep` suffix = heavier isolated execution tier. +- Cross-plugin references: required-for-contract → declared plugin dependency (native auto-install; link the official doc); optional enhancement → "if installed" soft reference with graceful degradation; bare unguarded references forbidden. + +**Skill renames** (dir + frontmatter `name` move together; description sharpened third-person what+when): + +| From | To | +|---|---| +| `planning:architect` | `planning:plan` | +| `debugging:diagnose` | `debugging:debug` | +| `docs-hygiene:declutter` | `docs-hygiene:audit-noise` | +| `work-items:scan` | `work-items:scan-todos` | +| `toolchain:build` | `toolchain:check` | +| `machine-health:check` | `machine-health:audit` | +| `claude-ops:troubleshoot` | `claude-ops:known-issues` | +| `knowledge:youtube` | `knowledge:youtube-digest` | +| `playbooks:thariq` | `playbooks:skill-authoring` (vendor/, upstream metadata, and `/playbooks:update` mechanics move intact) | +| `session-flow:orchestration-brief` | `session-flow:orchestrate` (finish mid-flight rename) | + +**Plugin changes:** + +- New `domain-driven-design` plugin housing `ubiquitous-language` (from `planning:domain-modeling`). `planning` declares a hard dependency on it (auto-install). `ubiquitous-language` soft-routes discovery to `event-storming`. +- `event-storming` stays standalone — multi-purpose per eventstorming.com (business health, startup viability, service design, software architecture; DDD is one application). +- Plugin renames as hard breaks: `markdown-formatter` → `markdown-format`, `bash-lint` → `bash-format`. +- Keep: `testing:e2e` (cover non-UI smoke in description), `verification:confirm`, `discovery:research-deep`/`explore-deep`, `review:quality-gate` (add /code-review boundary note), plugin names `codebase-health`, `tdd`. + +**Execution (approved package):** + +1. PR 1 — codify conventions in PLUGIN-PHILOSOPHY; no renames. +2. One PR per affected plugin for skill renames; each PR carries ALL repo-wide reference updates for that rename atomically (cross-plugin doc references included); minor version bump per plugin (0.x breaking-by-minor precedent); `/docs-hygiene:rename-references` sweep before merge. +3. PR — domain-driven-design extraction + planning dependency + planning bump. +4. PR — plugin renames (markdown-format, bash-format): marketplace.json entry rename, hard break. +5. PR — finish orchestration-brief → orchestrate. +6. Tier D deferred items filed on the work-item tracker, not executed here. + +### Constraints + +- NO `renames`-map entries while the marketplace is settling — every rename is a clean breaking change with a version bump. +- Never hand-copy external documentation into convention docs; state the rule, link the source. +- Skill `name` must match its directory (agentskills.io spec); 1–64 chars, lowercase alnum + hyphens. +- Plugin skills have no bare command form — `/planning:plan` is the full command; built-in `/plan` (plan-mode toggle) is unaffected. +- Repo process: PRs required, squash merge, Conventional Commits titles, branch `/`; fresh-docs mandate applies to every manifest/schema edit. + +### Acceptance criteria + +- PLUGIN-PHILOSOPHY contains grammar, audit-mutation rule, cross-plugin reference rule, and sanctioned exceptions, citing official sources without copying them. +- All renamed skills load under their new names; no file in the repo references a dead skill/plugin name (rename-references sweep clean). +- `claude plugin install planning` auto-installs `domain-driven-design`. +- marketplace.json `renames` map unchanged (no new entries). +- Every touched plugin has a version bump and CHANGELOG note marking the breaking rename. + +### Captured assumptions + +- planning→domain-driven-design dependency declared as bare name (marketplace-latest), no version constraint / release tags — monorepo marketplace keeps them consistent. Revisit if plugins gain independent release cadence. +- `domain-driven-design` plugin starts at 0.1.0. +- Private-marketplace consumers tolerate hard plugin renames by reinstalling (dev-phase posture). + +### Out-of-scope + +- Tier D restructurings (filed as tracker items): songwriting split (keep `object-writing`; extract `metaphor`, `cliche`, `point-of-view`), `discovery:explore` blindspot split, `source-control:pull-request` babysit split, `firecrawl` update-pipeline extraction, `codebase-health:audit` fix-phase delegation to implementation/verification lanes, `toolchain:setup` step-6 relocation, `testing:plan` as test-type SSOT, `planning:plan` Step-2 design-axes leak, `review:quality-gate` /code-review boundary note. +- Gerund migration (rejected), plugin renames for `codebase-health`/`tdd` (kept). + +### Deferred questions + +- [arbiter: implementation] Exact sharpened description wording per renamed skill (third-person, what+when, key triggers preserved — e.g. "troubleshoot" stays a trigger word for `known-issues`). +- [arbiter: USER-RESERVED] Reserved-word exposure: if any skill ever ships to the API Skills surface, `claude-*` plugin names need re-checking against platform-side validation (trigger recorded; no action now). +- [arbiter: USER-RESERVED] Songwriting split details (which content moves to `metaphor`/`cliche`/`point-of-view`) — own interview when picked up. + +## Plan + +(To be filled by /planning:plan — or proceed directly; the PR sequence above is execution-ready.) From cf789ad82c620817e68ffa37905423210f5d7b01 Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Fri, 17 Jul 2026 12:46:21 -0400 Subject: [PATCH 2/4] docs: prune branch-only shadowed-skill-renames topic contract Final "prune the branch-only topic contract before merge" step required by this repo's topic-docs convention: docs/topics// is a Contract tier committed on the task branch only and pruned before merge, so the merged diff carries no docs/topics/** path. The shadowed-skill-renames contract has served its purpose driving the rename PRs; removing it here keeps the merge clean. --- docs/topics/shadowed-skill-renames/PLAN.md | 87 ---------------------- 1 file changed, 87 deletions(-) delete mode 100644 docs/topics/shadowed-skill-renames/PLAN.md diff --git a/docs/topics/shadowed-skill-renames/PLAN.md b/docs/topics/shadowed-skill-renames/PLAN.md deleted file mode 100644 index 29897105a..000000000 --- a/docs/topics/shadowed-skill-renames/PLAN.md +++ /dev/null @@ -1,87 +0,0 @@ -# Shadowed skill renames - -## Brief - -**TLDR:** Undo the pre-migration shadow-compromise skill names (namespacing removed the constraint), fix audit-surfaced semantic misfits, extract a `domain-driven-design` plugin, and codify the naming grammar + cross-plugin reference rules in `docs/PLUGIN-PHILOSOPHY.md` — as a sequenced set of breaking-change PRs with no renames-map entries. - -### Goal - -Every skill and plugin name in the marketplace denotes what it actually does, follows one codified grammar, and the conventions that produced this state are written down so future names are predictable. - -### Locked decisions - -**Naming grammar (codify in PLUGIN-PHILOSOPHY, PR 1):** - -- Imperative verbs; namespace supplies the object. Documented deviation from the official gerund preference (cite the page, copy nothing) — rationale: sentence-composability ("/explore X, then /research, then /interview me") and collection-consistency (itself official guidance). -- Verb meanings: `audit`/`scan` = read-only report; `check` = deterministic pass/fail gate; `clean`/`tidy`/`fix` = mutates; `setup` = plugin config; `update` = vendor refresh. -- `audit` mutation: read-only by default; mutation only behind an explicit user override (flag/argument), safety qualifiers permitted. Bare invocation never mutates. -- Sanctioned exceptions: nouns for knowledge routers (`principles`, `methodology`) and lifecycle-object routers (`worktree`, `pull-request`); vendor-wrapper stutter (`firecrawl:firecrawl`); `-deep` suffix = heavier isolated execution tier. -- Cross-plugin references: required-for-contract → declared plugin dependency (native auto-install; link the official doc); optional enhancement → "if installed" soft reference with graceful degradation; bare unguarded references forbidden. - -**Skill renames** (dir + frontmatter `name` move together; description sharpened third-person what+when): - -| From | To | -|---|---| -| `planning:architect` | `planning:plan` | -| `debugging:diagnose` | `debugging:debug` | -| `docs-hygiene:declutter` | `docs-hygiene:audit-noise` | -| `work-items:scan` | `work-items:scan-todos` | -| `toolchain:build` | `toolchain:check` | -| `machine-health:check` | `machine-health:audit` | -| `claude-ops:troubleshoot` | `claude-ops:known-issues` | -| `knowledge:youtube` | `knowledge:youtube-digest` | -| `playbooks:thariq` | `playbooks:skill-authoring` (vendor/, upstream metadata, and `/playbooks:update` mechanics move intact) | -| `session-flow:orchestration-brief` | `session-flow:orchestrate` (finish mid-flight rename) | - -**Plugin changes:** - -- New `domain-driven-design` plugin housing `ubiquitous-language` (from `planning:domain-modeling`). `planning` declares a hard dependency on it (auto-install). `ubiquitous-language` soft-routes discovery to `event-storming`. -- `event-storming` stays standalone — multi-purpose per eventstorming.com (business health, startup viability, service design, software architecture; DDD is one application). -- Plugin renames as hard breaks: `markdown-formatter` → `markdown-format`, `bash-lint` → `bash-format`. -- Keep: `testing:e2e` (cover non-UI smoke in description), `verification:confirm`, `discovery:research-deep`/`explore-deep`, `review:quality-gate` (add /code-review boundary note), plugin names `codebase-health`, `tdd`. - -**Execution (approved package):** - -1. PR 1 — codify conventions in PLUGIN-PHILOSOPHY; no renames. -2. One PR per affected plugin for skill renames; each PR carries ALL repo-wide reference updates for that rename atomically (cross-plugin doc references included); minor version bump per plugin (0.x breaking-by-minor precedent); `/docs-hygiene:rename-references` sweep before merge. -3. PR — domain-driven-design extraction + planning dependency + planning bump. -4. PR — plugin renames (markdown-format, bash-format): marketplace.json entry rename, hard break. -5. PR — finish orchestration-brief → orchestrate. -6. Tier D deferred items filed on the work-item tracker, not executed here. - -### Constraints - -- NO `renames`-map entries while the marketplace is settling — every rename is a clean breaking change with a version bump. -- Never hand-copy external documentation into convention docs; state the rule, link the source. -- Skill `name` must match its directory (agentskills.io spec); 1–64 chars, lowercase alnum + hyphens. -- Plugin skills have no bare command form — `/planning:plan` is the full command; built-in `/plan` (plan-mode toggle) is unaffected. -- Repo process: PRs required, squash merge, Conventional Commits titles, branch `/`; fresh-docs mandate applies to every manifest/schema edit. - -### Acceptance criteria - -- PLUGIN-PHILOSOPHY contains grammar, audit-mutation rule, cross-plugin reference rule, and sanctioned exceptions, citing official sources without copying them. -- All renamed skills load under their new names; no file in the repo references a dead skill/plugin name (rename-references sweep clean). -- `claude plugin install planning` auto-installs `domain-driven-design`. -- marketplace.json `renames` map unchanged (no new entries). -- Every touched plugin has a version bump and CHANGELOG note marking the breaking rename. - -### Captured assumptions - -- planning→domain-driven-design dependency declared as bare name (marketplace-latest), no version constraint / release tags — monorepo marketplace keeps them consistent. Revisit if plugins gain independent release cadence. -- `domain-driven-design` plugin starts at 0.1.0. -- Private-marketplace consumers tolerate hard plugin renames by reinstalling (dev-phase posture). - -### Out-of-scope - -- Tier D restructurings (filed as tracker items): songwriting split (keep `object-writing`; extract `metaphor`, `cliche`, `point-of-view`), `discovery:explore` blindspot split, `source-control:pull-request` babysit split, `firecrawl` update-pipeline extraction, `codebase-health:audit` fix-phase delegation to implementation/verification lanes, `toolchain:setup` step-6 relocation, `testing:plan` as test-type SSOT, `planning:plan` Step-2 design-axes leak, `review:quality-gate` /code-review boundary note. -- Gerund migration (rejected), plugin renames for `codebase-health`/`tdd` (kept). - -### Deferred questions - -- [arbiter: implementation] Exact sharpened description wording per renamed skill (third-person, what+when, key triggers preserved — e.g. "troubleshoot" stays a trigger word for `known-issues`). -- [arbiter: USER-RESERVED] Reserved-word exposure: if any skill ever ships to the API Skills surface, `claude-*` plugin names need re-checking against platform-side validation (trigger recorded; no action now). -- [arbiter: USER-RESERVED] Songwriting split details (which content moves to `metaphor`/`cliche`/`point-of-view`) — own interview when picked up. - -## Plan - -(To be filled by /planning:plan — or proceed directly; the PR sequence above is execution-ready.) From 29277b1ae9d5dcb893209b5139827d3afbad5526 Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Fri, 17 Jul 2026 12:58:39 -0400 Subject: [PATCH 3/4] =?UTF-8?q?docs:=20address=20review=20=E2=80=94=20prun?= =?UTF-8?q?e=20topic=20slice,=20reconcile=20playbook,=20close=20naming=20g?= =?UTF-8?q?aps?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Topic contract promoted to tracker issue #280 per the topic-docs branch-only convention; setup locked as the single configure verb; compound verb-qualifier rule documented; playbook stutter rule reconciled via a wrapper-echo exemption scoped to single-skill vendor-CLI routers. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01YVApnNGoKxYMJKNQx1QK8C --- docs/MIGRATION-PLAYBOOK.md | 17 ++++++++++------- docs/PLUGIN-PHILOSOPHY.md | 6 +++++- 2 files changed, 15 insertions(+), 8 deletions(-) diff --git a/docs/MIGRATION-PLAYBOOK.md b/docs/MIGRATION-PLAYBOOK.md index 0bf9a6182..a13a3e420 100644 --- a/docs/MIGRATION-PLAYBOOK.md +++ b/docs/MIGRATION-PLAYBOOK.md @@ -117,10 +117,12 @@ Applying that precedence, the grammar of an invocation is `/:` is failing at its job — the namespace is not naming the domain, or the skill is not naming its action. Fix it by, in preference order: rename the skill to its real action verb; rename the plugin to its domain noun; decompose, when the single skill actually hides distinct discovery - intents (per the Organization section's split rule above). The one exemption is + intents (per the Organization section's split rule above). Two exemptions: **root-echo** — the domain's core action shares the domain's root word - (`implementation:implement`, `code-tidying:tidy`, `work-items:work`); that is honest naming, not - a true doubling, and is accepted. + (`implementation:implement`, `code-tidying:tidy`, `work-items:work`) — and + **wrapper-echo** — a single-skill vendor-CLI wrapper whose one router skill repeats the tool + name (`firecrawl:firecrawl`, `playwright:playwright`), per the philosophy's Naming section. + Both are honest naming, not true doubling, and are accepted. - **Skill families order base-concept-first.** Sibling skills sharing a base concept put the base first (`design`, `design-handoff`, `implement`, `implement-dispatch`) so prefix typeahead and sorted listings group the family. A standalone skill keeps natural English order (`batch-simplify`, `quality-gate`). @@ -132,10 +134,11 @@ Applying that precedence, the grammar of an invocation is `/:` (a dispatch variant of `research`) are siblings on this axis; the `-deep` suffix names that isolation tier, not a depth knob on the same execution path — a true effort knob on one execution path still takes an argument. -- **A vendor-CLI plugin names its skills after the vendor's own CLI verbs.** A tool-scoped plugin - wrapping a CLI mirrors that CLI's verb vocabulary — `/playwright:test` mirrors - `npx playwright test`; a firecrawl decomposition would use `scrape` / `crawl` / `map` per - `firecrawl-cli` — the consumer already knows the vendor's verbs. +- **A vendor-CLI plugin that decomposes names its skills after the vendor's own CLI verbs.** When a + tool-scoped plugin splits into multiple skills, it mirrors that CLI's verb vocabulary — + `/playwright:test` would mirror `npx playwright test`; a firecrawl decomposition would use + `scrape` / `crawl` / `map` per `firecrawl-cli` — the consumer already knows the vendor's verbs. + While it remains a single-skill router, the wrapper-echo exemption above applies instead. - **Generic skill names are safe under namespacing** (`help`, `list`, `configure`) — the overloaded-term caution governs plugin *identity*, not a namespaced skill leaf. - **Tool-scope shows up as brand-in-name, not a structural split.** A branded name signals a tool-scoped diff --git a/docs/PLUGIN-PHILOSOPHY.md b/docs/PLUGIN-PHILOSOPHY.md index 4a66d85a7..2af41a008 100644 --- a/docs/PLUGIN-PHILOSOPHY.md +++ b/docs/PLUGIN-PHILOSOPHY.md @@ -48,6 +48,10 @@ Verb meanings are fixed: | `setup` | Configures the plugin for a consumer, per the setup section below. | | `update` | Refreshes vendored upstream material. | +When a bare verb would collide with or under-specify against a sibling in the same namespace, a +topic qualifier follows the verb with a hyphen (`audit-noise` beside `audit-encapsulation`, +`scan-todos` under `work-items`); the verb keeps its fixed meaning from the table. + Nouns are reserved for knowledge routers (`principles`, `methodology`) and lifecycle-object routers (`worktree`, `pull-request`). Two further documented exceptions: a single-skill vendor-CLI wrapper repeats its tool name (`firecrawl:firecrawl`), and a `-deep` suffix marks the heavier @@ -83,7 +87,7 @@ merely to create a second configuration channel. ## Setup is explicit and repeatable -A configurable plugin provides an explicit `setup` or `configure` skill with +A configurable plugin provides an explicit `setup` skill with `disable-model-invocation: true`. Setup must be: - idempotent and safe to rerun; From 4feec243a0fb2829544647578c3badc53d3d83cb Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Fri, 17 Jul 2026 13:45:25 -0400 Subject: [PATCH 4/4] docs: align playbook setup verb with the naming section Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01YVApnNGoKxYMJKNQx1QK8C --- docs/MIGRATION-PLAYBOOK.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/MIGRATION-PLAYBOOK.md b/docs/MIGRATION-PLAYBOOK.md index a13a3e420..fd2c2f307 100644 --- a/docs/MIGRATION-PLAYBOOK.md +++ b/docs/MIGRATION-PLAYBOOK.md @@ -139,7 +139,7 @@ Applying that precedence, the grammar of an invocation is `/:` `/playwright:test` would mirror `npx playwright test`; a firecrawl decomposition would use `scrape` / `crawl` / `map` per `firecrawl-cli` — the consumer already knows the vendor's verbs. While it remains a single-skill router, the wrapper-echo exemption above applies instead. -- **Generic skill names are safe under namespacing** (`help`, `list`, `configure`) — the overloaded-term +- **Generic skill names are safe under namespacing** (`help`, `list`, `update`) — the overloaded-term caution governs plugin *identity*, not a namespaced skill leaf. - **Tool-scope shows up as brand-in-name, not a structural split.** A branded name signals a tool-scoped plugin; a plain domain-noun signals a tool-agnostic one. No marketplace separates plugins by tool-scope @@ -262,8 +262,9 @@ value, infers-and-records, or asks — never guesses silently. ## Setup action — every configurable plugin ships one -Every plugin that carries any `userConfig` or tracked-config seam ships a re-runnable `setup` / -`configure` action (a skill) that interviews the consumer and writes the tracked config. It is +Every plugin that carries any `userConfig` or tracked-config seam ships a re-runnable `setup` +skill (the canonical verb per the philosophy's Naming section) that interviews the consumer and +writes the tracked config. It is idempotent — safe to re-run to reconfigure. The Thariq `config.json` first-run pattern is **rejected** for plugins: it is not an official mechanism, and it writes into `${CLAUDE_PLUGIN_ROOT}`, which is replaced on every update (the plugins-reference caching note), so its state does not survive. Setup @@ -287,8 +288,8 @@ a skill ships them only when they earn their keep. that could silently regress — how it triggers, how it routes an ambiguous request, when it refuses, or the shape of what it emits. A skill is an explicit **skip** when it is pure-reference (answers from a knowledge corpus with no decision contract — `playbooks:fable-5`, `tdd`, …) or lives in a **hook** plugin -(deterministic, silent-always-on, guarded by `.test.sh`, no model-invoked skill). A `setup` / -`configure` skill *is* warrantable — it makes interview and write-config decisions (the +(deterministic, silent-always-on, guarded by `.test.sh`, no model-invoked skill). A `setup` +skill *is* warrantable — it makes interview and write-config decisions (the `codebase-health/setup` eval is the model). Gray-zone skills (thin mechanical wrappers, reference-ish routers) are **author-confirm**: re-check the warrant against the live `SKILL.md` at authoring time and record an explicit skip verdict if it dissolves — a satisfied "looks covered" is not a warrant.