docs: codify skill-naming grammar and cross-plugin reference rules - #256
Merged
Conversation
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 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YVApnNGoKxYMJKNQx1QK8C
|
Claude finished @kyle-sexton's task in 1m 47s —— View job Review: docs/naming-conventions
OverallSolid foundational work. The cross-plugin reference rule is clean and immediately enforceable, and the verb-semantics table is exactly the kind of constraint the marketplace needs. Two medium-weight consistency gaps need resolution before the downstream rename PRs run — they'll shape acceptance criteria for those PRs.
|
This was referenced Jul 17, 2026
Closed
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 1dc721f55c
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
This was referenced Jul 17, 2026
kyle-sexton
added a commit
that referenced
this pull request
Jul 17, 2026
## What Renames the `debugging` plugin's sole skill: `/debugging:diagnose` → `/debugging:debug`. One atomic rename PR per the shadowed-skill-renames contract (#256): directory (`git mv`) and frontmatter `name` move together, and all repo-wide references update in the same PR. - `plugins/debugging/skills/diagnose/` → `plugins/debugging/skills/debug/` (all bundled files) - Frontmatter `name: debug`; description unchanged — already third-person what+when, and keeps "diagnose this" as a trigger phrase - Internal `${CLAUDE_PLUGIN_ROOT}/skills/diagnose/...` paths, self-references, checklist/reference headers, and evals updated - `plugins/debugging/README.md` invocation line updated - `plugins/verification/skills/confirm/evals/evals.json` boundary notes updated - `docs/MIGRATION-PLAYBOOK.md` non-router-skill example updated - `plugins/debugging` bumped 0.3.0 → **0.4.0** (0.x breaking-by-minor precedent); new `CHANGELOG.md` with the breaking entry ## Why The skill runs the full repro → hypothesize → fix → regression-test loop; "diagnose" promised only the first half, and twinned confusingly with the unrelated `/testing:diagnose` (a read-only test-failure investigator that keeps its name). Pre-migration shadow-compromise naming is no longer needed now that plugin namespacing exists. ## Breaking change - `/debugging:diagnose` no longer resolves; invoke `/debugging:debug`. Clean break — no `renames`-map entry per the contract (marketplace `renames` map unchanged; its existing `"diagnose": "debugging"` entry is the historical plugin-level rename). - No collision with Claude Code's built-in bundled `/debug` skill: plugin skills have no bare command form, so the plugin skill is only reachable as the namespaced `/debugging:debug`. ## Deliberate skips - `plugins/testing/**` — `/testing:diagnose` is a different skill and keeps its name. - `docs/topics/plugin-organization/PLAN.md` — historical record of the earlier plugin reorganization (its D3/D13 rows describe decisions as made at the time). - `.claude-plugin/marketplace.json` — `renames` map untouched (contract constraint); the `diagnose` tag stays as a discovery keyword, mirroring the retained trigger word. - `plugin.json` `keywords` keeps `diagnose` as a discovery keyword. ## Verification - `git grep -n "debugging:diagnose"` → 0 hits - `git grep -n "skills/diagnose"` → 0 hits - `git grep -nE "(^|[^a-z:])/diagnose\b"` → 0 hits - Remaining `diagnose` hits in `plugins/debugging` are the deliberate trigger word in the skill description and the plugin keyword - Edited JSON files parse cleanly 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01YVApnNGoKxYMJKNQx1QK8C ## Related No linked issue. Contract source: #256. Sibling shadowed-skill rename PRs: #269, #270, #271. Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
kyle-sexton
added a commit
that referenced
this pull request
Jul 17, 2026
## What Renames the `work-items` plugin's `scan` skill to `scan-todos` — directory (`plugins/work-items/skills/scan` → `scan-todos` via `git mv`), frontmatter `name`, and every live repo-wide reference, atomically in one PR. One of the sequenced shadowed-skill-rename PRs (contract: `docs/topics/shadowed-skill-renames/PLAN.md`, PR #256). ## Why Under the `work-items` namespace, bare `scan` read as scanning tracker items. The skill sweeps the codebase's **source comments** for TODO/FIXME/HACK/XXX markers (and can resolve or file each) — the name now states its object. Per the fetched skills doc (https://code.claude.com/docs/en/skills), the invocation name comes from the skill directory name, so the directory and frontmatter `name` move together. ## Breaking change - `/work-items:scan` no longer exists; invoke `/work-items:scan-todos`. - No `renames`-map entry (settling-phase policy: clean break + version bump). - `work-items` plugin bumped **0.7.0 → 0.8.0** with a `Changed (breaking)` CHANGELOG entry. ## Changes - `skills/scan/` → `skills/scan-todos/` (`SKILL.md` + `evals/evals.json`); frontmatter `name: scan-todos`; description sharpened to state the object (source comments, not tracker items); usage line and eval `skill_name`/prompt updated. - Sibling-skill cross-references updated: `track`, `triage`, `work`, `decompose` descriptions; `track`'s scope note and legacy-verb router (`scan` → `/work-items:scan-todos`). - Shared docs: `reference/tracker-seam.md`, `reference/topic-docs.md`, `templates/checklist.md`, plugin `README.md`. - `plugin.json` version bump; new `[0.8.0]` CHANGELOG entry. ## Deliberate skips - Historical CHANGELOG entries (0.7.0 migration table and older) left verbatim. - `track/SKILL.md` legacy-verb list keeps the old bare verb `scan` on the left of its routing arrow (it names the retired monolith sub-action). - English-verb "scan"/"scanning" prose (plugin description, `add.md`, unrelated plugins) untouched. - `.claude-plugin/marketplace.json` untouched — it carries no skill names or per-plugin version, and no `renames` entry is added by policy. ## Verification - `git grep "work-items:scan"` → only `scan-todos` forms and the preserved historical CHANGELOG rows. - `git grep "skills/scan\b"` → no hits. - Skill-name/directory agreement: `name: scan-todos` matches `skills/scan-todos/` (invocation name derives from the directory per the official skills doc). 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01YVApnNGoKxYMJKNQx1QK8C ## Related No linked issue. Contract source: #256. Sibling shadowed-skill rename PRs: #268, #270, #271. Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Final "prune the branch-only topic contract before merge" step required by this repo's topic-docs convention: docs/topics/<slug>/ 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.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: cf789ad82c
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
…aming gaps 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 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YVApnNGoKxYMJKNQx1QK8C
Contributor
Author
|
claude-review findings addressed in 29277b1:
|
kyle-sexton
added a commit
that referenced
this pull request
Jul 17, 2026
## What Renames the `docs-hygiene` skill `declutter` -> `audit-noise` as one atomic breaking-change PR per the shadowed-skill-renames contract: `git mv` of the skill directory, frontmatter `name` + `allowed-tools` path, self-references, eval metadata, detect-script identifiers/env vars (`declutter_*` -> `audit_noise_*`, `DECLUTTER_REPO_ROOT` -> `AUDIT_NOISE_REPO_ROOT`), and every repo-wide reference (root README, docs-hygiene README/manifest, compress boundary notes, topic-docs convention doc, and the cross-plugin `code-tidying:comment-residue` routing lines). ## Why The skill is a read-only classifier and never mutates. Per the marketplace naming grammar, `audit` = read-only report, aligning it with the sibling `audit-encapsulation`. "declutter" remains a description trigger word so existing phrasing still routes to the skill. If the skill's deferred write actions (`relocate`/`generalize`) ever land, the name gets revisited. ## Breaking - `/docs-hygiene:declutter` is gone; invoke `/docs-hygiene:audit-noise`. No `renames`-map entry (per contract: clean breaks while the marketplace settles). - `docs-hygiene` 0.5.0 -> 0.6.0 (0.x breaking-by-minor precedent) with a CHANGELOG entry. - `code-tidying` 0.4.1 -> 0.4.2 for the cross-plugin reference updates (non-breaking for that plugin). ## Verification - `git grep -i declutter` clean outside deliberate keeps: historical CHANGELOG entries, the new CHANGELOG rename entries, the description trigger word, natural-English eval prompts exercising the trigger word, and generic English in `songwriting` (not this skill). - `audit-noise` detect.test.sh: 33/33 pass; `comment-residue` detect.test.sh: 27/27 pass. - shellcheck clean on all touched scripts; markdownlint-cli2 clean on all touched .md; JSON manifests/evals parse; `check-cross-plugin-source-drift.sh --check` clean. - Skill command-name behavior confirmed against https://code.claude.com/docs/en/skills (plugin `skills/` subdirectory: command name = directory name, namespaced by plugin; frontmatter `name` is the display label). No linked issue ## Related - Contract: `docs/topics/shadowed-skill-renames/PLAN.md` on #256 (this PR does not base on that branch). 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01YVApnNGoKxYMJKNQx1QK8C Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
kyle-sexton
added a commit
that referenced
this pull request
Jul 17, 2026
## What Atomic rename of the `claude-ops:troubleshoot` skill to `claude-ops:known-issues`, per the shadowed-skill-renames contract (#256): - `git mv plugins/claude-ops/skills/troubleshoot` → `skills/known-issues` (directory and frontmatter `name` move together). - Description sharpened to third-person what+when; **"troubleshoot" and "is this broken" are kept as trigger words**. - Repo-wide reference sweep: sibling skills (`changelog`, `observability` incl. read-routing and evals, `setup` incl. evals), `${CLAUDE_PLUGIN_ROOT}/skills/...` script paths, `plugin.json` description + `registry_dir` option description, plugin README, root README. "Troubleshooting registry" prose is now "known-issues registry". - `plugins/claude-ops` version bump `0.9.0` → `0.10.0` (0.x breaking-by-minor precedent) with a CHANGELOG breaking-rename entry. ## Why The skill looks up and tracks KNOWN upstream Claude Code / Anthropic product issues (GitHub bug search, service health, persistent tracked-issue registry). It never diagnoses or fixes anything locally — "troubleshoot" over-promised a diagnostic capability the skill does not have. ## Breaking `/claude-ops:troubleshoot` no longer exists; invoke `/claude-ops:known-issues`. No `renames`-map entry (clean break per contract). Registry location, `registry_dir` semantics, actions, and behavior are unchanged. ## Verification - `git grep` sweep: zero remaining `claude-ops:troubleshoot`, `/troubleshoot`, or `skills/troubleshoot` references outside historical CHANGELOG entries. Remaining "troubleshooting" occurrences are deliberate: generic keyword/tags in `plugin.json`/`marketplace.json`, the SKILL description trigger word, the external `docs.claude.com/.../troubleshooting` URL, historical CHANGELOG 0.6.0 and `docs/topics/plugin-organization/PLAN.md` records, and unrelated plugins (songwriting suno, debugging tags). - All touched JSON validated with `jq`; frontmatter `name` matches the directory (fresh-fetched https://code.claude.com/docs/en/skills). - `markdownlint-cli2` over `plugins/claude-ops/**/*.md` + `README.md`: 0 errors. - New `claude-ops:plugins` skill untouched beyond none-needed; no `vendor/` or `.work/` edits. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01YVApnNGoKxYMJKNQx1QK8C ## Related - Program contract: #280 (shadowed-skill-renames naming grammar rollout) - Conventions PR: #256 No linked issue — program-level rename executed under #280. Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
|
Claude finished @kyle-sexton's task in 1m 33s —— View job Review: docs/naming-conventions
OverallMost of the prior review round is resolved cleanly. One unresolved contradiction remains — the latest Codex finding (17:03 UTC) — which needs a one-line fix before merge. Everything else is clear. Outstanding:
|
| Finding | Source | Status |
|---|---|---|
setup / configure contradiction in Philosophy Setup section |
Claude review (medium) | Fixed — line 90 now says setup only |
| Compound verb+qualifier rule undocumented | Claude review (medium) | Fixed — hyphenated topic-qualifier rule added (line 51–53) |
| Branch-only topic contract in diff | Codex P2 | Fixed — topic slice pruned (cf789ad); durable tracker at #280 |
| Vendor-wrapper stutter vs playbook naming rule | Codex P2 | Fixed — wrapper-echo exemption added to MIGRATION-PLAYBOOK (line 122–124) |
known-issues noun not matching exceptions |
Claude review (medium) | Resolved by pruning PLAN.md; follow-up scoped to rename PRs |
Empty ## Plan section |
Claude review (low) | Resolved by pruning |
update verb narrowing uncalled-out |
Claude review (low) | Not addressed; acceptable to leave for a follow-up if the table wording causes confusion in practice |
Not flagged
- Cross-plugin reference rule (bare-reference = defect) integrates cleanly and is unambiguous.
- Built-in collision non-rule is correctly placed and clearly stated.
- The wrapper-echo/root-echo exemptions in both docs now agree.
- Vendor-CLI decomposition scope ("while it remains a single-skill router…") closes the previous gap.
- Fresh-docs mandate: references dated and linked — compliant.
- Doc-only changes; no runtime surface, no security surface.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YVApnNGoKxYMJKNQx1QK8C
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 4feec243a0
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
Claude encountered an error after 1s —— View job I'll analyze this and get back to you. |
kyle-sexton
added a commit
that referenced
this pull request
Jul 17, 2026
## What Atomic rename of the `knowledge` plugin's `youtube` skill to `youtube-digest` (one of the shadowed-skill renames charted in `docs/topics/shadowed-skill-renames/PLAN.md`, PR #256): - `git mv plugins/knowledge/skills/youtube` → `plugins/knowledge/skills/youtube-digest` (166 files, nearly all pure renames) - Frontmatter `name: youtube` → `youtube-digest`; `'/youtube'` trigger token → `'/youtube-digest'` - All internal `${CLAUDE_PLUGIN_ROOT}/skills/youtube/...` paths → `skills/youtube-digest/...` (SKILL.md, context docs, templates, evals, and the generated recovery command in `detect-recoverable-bootstrap.js`) - Slash references `/knowledge:youtube` → `/knowledge:youtube-digest` in the skill, its siblings (`course-digest` SKILL/context/evals/reference), and the knowledge README - Bare `` `/youtube watch` ``/`` `/youtube resume` `` skill references in extraction JS comments and the generated continuation prompt → `/youtube-digest ...` - Living docs: `docs/MIGRATION-PLAYBOOK.md`, `docs/knowledge-integration-design.md` skill-name mentions updated - `plugins/knowledge` bumped 0.5.6 → 0.6.0 with a breaking-rename CHANGELOG entry ## Why Sibling skills follow a source+operation grammar (`book-distill`, `course-digest`); the platform noun alone named the source but not the operation. ## Breaking `/knowledge:youtube` no longer resolves — invoke `/knowledge:youtube-digest`. Model-invocation triggers are preserved: "youtube", "watch this YouTube video", and youtube.com/youtu.be URL sharing still route to the skill. In-flight `.work/<watch-epic>/...` slices are unaffected; resume via `/knowledge:youtube-digest resume <video-slug>`. ## Deliberate skips - Platform-name prose ("YouTube video", URL-matching text) unchanged everywhere - Historical CHANGELOG entries untouched (`skills/youtube/` and `/knowledge:youtube` remain only there) - `vendor/` untouched; marketplace.json `renames` map untouched; `youtube` kept as a discovery keyword in plugin.json/marketplace tags - Hypothetical future standalone `youtube` plugin name kept as-is (README revisit condition, CATALOG-TAXONOMY graduation trigger, plugin-organization PLAN) — those name a plugin, not this skill - Internal identifiers not derived from the skill name kept: `@melodic/youtube-extraction` package, `{tmp}/youtube-*` temp dirs, "youtube-extraction deps" ## Verification - `git grep "knowledge:youtube"` → only `-digest` form outside historical CHANGELOG entries - `git grep "skills/youtube/"` → zero hits outside historical CHANGELOG entries - All edited JSON (plugin.json, both evals.json, marketplace.json) parses 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01YVApnNGoKxYMJKNQx1QK8C ## Related - Program contract: #280 (shadowed-skill-renames naming grammar rollout) - Conventions PR: #256 No linked issue — program-level rename executed under #280. --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
kyle-sexton
added a commit
that referenced
this pull request
Jul 17, 2026
## What Atomic breaking rename of the `playbooks` plugin's `thariq` skill to `skill-authoring` (`/playbooks:thariq` → `/playbooks:skill-authoring`), per the shadowed-skill-renames contract (docs/topics/shadowed-skill-renames/PLAN.md, PR #256). - `git mv plugins/playbooks/skills/thariq → skills/skill-authoring` (vendor/ moved with it) - Frontmatter `name` → `skill-authoring`; upstream metadata block (`upstream-version`, `synced`) untouched; skill-authoring trigger phrases kept - In-body self-references retargeted; attribution line ("Based on Thariq's March 17, 2026 post" + link) kept verbatim - `/playbooks:update` mechanics retargeted: pack table row + `${CLAUDE_PLUGIN_ROOT}/skills/skill-authoring/scripts/update.sh` path, pack enumeration prose, update evals - Pack `scripts/update.sh` pack-name strings renamed (log lines, tmpdir prefix, help text, suggested commit subject); upstream URLs unchanged - Playbooks README, root README, `plugin.json` description updated; `thariq` discovery tag/keyword removed from marketplace tags and plugin keywords (`skill-authoring` already present — replacing would duplicate) - `plugin.json` bumped 0.1.0 → 0.2.0; CHANGELOG breaking-rename entry added ## Why The pack's content is topic-shaped — it teaches skill authoring — so the name now denotes what it does. `boris` and `fable-5` stay persona-named because their content IS persona doctrine. No `renames`-map entry while the marketplace is settling: clean breaking change behind the version bump. ## Breaking `/playbooks:thariq` no longer exists; invoke `/playbooks:skill-authoring`. Consumers receive the rename via `/plugin marketplace update` at playbooks 0.2.0. ## Verification - `vendor/SKILL.md` and `vendor/.markdownlint-cli2.jsonc` moved at **R100** (byte-identical, `git diff --find-renames` vs origin/main) — upstream baseline integrity preserved; upstream `name: thariq-skills` frontmatter untouched - `git grep -i thariq` now hits only: attribution prose (skill body, MIGRATION-PLAYBOOK, boris reference files), historical CHANGELOG entries, the historical `thariq-skills` renames-map entry (unchanged), upstream URLs (`.../api/install-thariq`), and update.test.sh fixtures that simulate the upstream file's own frontmatter - `update.test.sh` passes (18/18, network-free); boris's own `scripts/update.sh` contains no thariq path strings (verified) - markdownlint-cli2 v0.23.0 clean on all touched markdown; all touched JSON parses - Docs verified this session per fresh-docs mandate: https://code.claude.com/docs/en/skills (plugin skill command name comes from the skill directory name, namespaced by plugin) and https://code.claude.com/docs/en/plugins-reference (`version` in plugin.json gates consumer updates; marketplace `tags` are searchability metadata) 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01YVApnNGoKxYMJKNQx1QK8C ## Related - Program contract: #280 (shadowed-skill-renames naming grammar rollout) - Conventions PR: #256 No linked issue — program-level rename executed under #280. Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
|
Claude finished @kyle-sexton's task in 2m 25s —— View job Review: docs/naming-conventions
OverallAll prior review findings (setup/configure contradictions in both PLUGIN-PHILOSOPHY and MIGRATION-PLAYBOOK, compound verb+qualifier gap, vendor-wrapper reconciliation) are cleanly resolved. One outstanding item — the Codex P2 cross-plugin reference finding — is partially valid but needs sharper scoping before merge. Open: Cross-plugin reference rule creates unacknowledged pre-existing defects — lowThe new rule in PLUGIN-PHILOSOPHY.md:
is correct as stated. But Codex's claim that
The This is pre-existing debt, not introduced by this PR — so fixing the planning skill files is out of scope here. The right move is a one-sentence acknowledgment so the rule's immediate application is unambiguous:
Resolved findings (for record)
Not flagged
|
kyle-sexton
added a commit
that referenced
this pull request
Jul 17, 2026
…ial-docs index (#257) Doctrine wave of the plugin-philosophy program (Phases 1-3 of the approved PLAN, committed on this branch at `docs/topics/plugin-philosophy/PLAN.md`): - **PLUGIN-PHILOSOPHY.md** — 13-row component stance table with per-row verified-date freshness riders and a staleness disclaimer; native-first principle with a three-part adoption gate; pointer-only convention registry (one owner doc per shared concern); userConfig full-potential criterion; exec-form hook rule (`${user_config.*}` never in shell form, v2.1.207); `version` single-home rule (plugin.json only); setup required-iff criteria with the uniform `check`/`apply` contract; runtime-prerequisite visibility rules. - **MIGRATION-PLAYBOOK.md** — points at the doctrine instead of restating it: migration gate step 7 (component-stance conformance), plugin-acceptance security review surface 7 (`settings.json` `agent` takeover, `bin/` PATH executables), setup section now defers to the philosophy doc. - **docs/OFFICIAL-DOCS.md** (new) — categorized index of every plugin-relevant official doc page, 13-row component→doc-page table, all links verified live 2026-07-17, `llms.txt` named as the authoritative self-updating master list. CLAUDE.md gains exactly one pointer row. All facts re-fetched from official docs this session per the repo fresh-docs mandate. Follow-on PRs in the approved chain: topic-docs 2.0.0 seam wave (PR B), marketplace metadata (PR C), audit close-out (PR D). The topic contract slice (`docs/topics/plugin-philosophy/`) is pruned in the final commit on this branch per the topic-docs convention; the full PLAN.md has now been graduated into this description under the **Plan** heading below. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01M1owJj9ZzkV36V3C1CyX4a ## Related No linked issue. Companion naming-convention PR: #256. ## Plan (graduated from docs/topics/plugin-philosophy/PLAN.md) # plugin-philosophy ## Brief ### TLDR Extend the plugin doctrine to the full current component surface (13 component types, official docs fetched 2026-07-17), lock a native-first principle with a maturity gate, fix the topic-docs two-tier convention's visibility seams with native mechanisms, ship a complete official-doc link index, adopt marketplace metadata maximally — then run a fanout conformance audit of all 47 plugins whose findings graduate to tracker-managed remediation waves. ### Goal Every plugin measurably conforms to an extended, freshness-guarded doctrine; no custom mechanism exists where a fitting native one does; every cross-plugin convention has exactly one registered owner doc; the remediation program lives on the work-item tracker where any session or machine can resume it. ### Locked decisions | # | Decision | |---|---| | D1 | Deliverable = doctrine revision + fleet-consistency audit, coupled in this one Brief. CI contract-gate automation deferred to follow-on (trigger: audit reveals automatable checks). | | D2 | Doc-link index is a first-class deliverable: every plugin-relevant official doc page linked (components mapped to their doc pages); no undocumented component types. | | D3 | Native-first principle: prefer built-in native mechanisms (userConfig, native component types, native lifecycle events) over custom extensibility points; custom only on genuine misfit, with the misfit documented. | | D4 | Native-adoption gate (qualifies D3): adopt a native mechanism when it (1) fills a real existing gap, (2) is stable and works cleanly — experimental/immature features wait for maturity, (3) meets repo standards. Never custom-build what a fitting native mechanism covers. | | D5 | Cross-plugin cooperation: hybrid. Native `dependencies` reserved for hard requires (plugin genuinely broken without collaborator) — none exist today; the `{name}--v{version}` git-tag release step lands with first use. Optional collaboration stays presence-gated with documented fallbacks; artifact protocol unchanged (data handoff, which dependencies don't cover). | | D6 | Component stance table: skills = primary surface (new frontmatter — `paths`, `context: fork`, `arguments`, skill-scoped `hooks`/`once` — adopted case-by-case); `commands/` prohibited (officially legacy); agents, MCP, LSP, output styles, `bin/` = adopt-on-need (`bin/` requires collision-safe prefixed names; doctrine notes plugin agents ignore `hooks`/`mcpServers`/`permissionMode`); plugin `settings.json` `agent` (main-thread takeover) prohibited by default, exception needs documented justification; monitors, themes, channels = wait (experimental/immature), re-verified against current docs before each audit; dependencies per D5. Hooks addition: exec-form (`args`) mandatory wherever `${user_config.*}` appears (v2.1.207), else the `CLAUDE_PLUGIN_OPTION_<KEY>` env mirror. | | D7 | Freshness rider on all doctrine artifacts: every stance/inventory row carries a verified-date + link to its official doc page and an explicit disclaimer that the platform changes constantly — always re-fetch current docs before acting; never trust the repo file alone. | | D8 | userConfig full-potential criterion: every personal/administrator scalar flowing through a custom channel (env-var toggle, gitignored personal file, documented hand-edit) migrates to userConfig using the full native schema — correct `type`, `default` preserving zero-config behavior, `required` only where truly blocking, `sensitive: true` for secrets, `claude plugin install --config` documented in each setup skill for headless use. Shell consumers read the native `CLAUDE_PLUGIN_OPTION_<KEY>` mirror; custom env vars retired. Ownership table otherwise unchanged. Guardrails `HOOK_<NAME>_ENABLED` toggles = flagship migration (userConfig booleans, `default: true`). | | D9 | Setup doctrine v2: setup skill required iff (a) consumer-project config surface, (b) external prerequisites (CLI, service, credential), or (c) non-trivial userConfig — criteria applied through the modular/configurable/repo-/machine-/user-agnostic lens, never blanket ceremony; zero-config zero-prereq plugins exempt. Uniform contract: skill named `setup`, `disable-model-invocation: true`, `check` (read-only inspect/verify) + `apply` (idempotent configure) actions, complete-args non-interactive path. Formatter/linter plugins gain thin check-centric setups. Native `Setup` hook event = sanctioned headless/CI init surface; SessionStart + `${CLAUDE_PLUGIN_DATA}` manifest-diff = sanctioned runtime-dependency idiom. | | D10 | Runtime-prerequisite visibility: anything with a runtime prereq (e.g. jq on PATH) degrades gracefully — never a hard crash; absence is surfaced to BOTH the agent and the user, with OTel as a candidate visibility channel; no black boxes. Extends the philosophy doc's "Prerequisites and failure behavior" section. | | D11 | Convention registry: pointer-only section in PLUGIN-PHILOSOPHY.md — one owner doc per shared concern (topic-docs binding, skill layout + evals schema, `lib/hook-utils.sh` sync, report vocabularies, artifact protocol, seam phrasing); registry names and points, never restates; audit rule = per-row conformance; a new convention lands in an owner doc before a second plugin adopts it. | | D12 | Topic-docs tiers: keep the nature-based two-tier split and the `docs/topics/` name (contents are transient topic-scoped contract docs; `docs/specs/` is already the durable vault target — renaming would conflate tiers). | | D13 | Two-tier seam fix package (all native): R1 `worktree.baseRef: "head"` in committed repo settings so worktree-isolated spawns carry task-branch state; R2 `.worktreeinclude` with targeted memory-tier patterns (stage ledgers, EXPLORE/RESEARCH — not baselines/raw scratch; one-way creation-time copy documented); R3 pointer discipline — durable surfaces (tickets, committed PLAN) never point at prunable or gitignored paths (decompose cites the PR, not the contract path; PLAN records distilled baseline values only); R4 isolated workers return results by value, the orchestrator writes both tiers in the parent checkout; R5 the work-item tracker is the cross-lane awareness/index layer (branch files stay lane-local; markdown-in-tickets as primary artifact store rejected — not diffable, drifts from code); R6 topic-docs convention doc corrected (worktree-visibility rationale, context×tier visibility matrix, mechanisms named) — a major contract version adopted by all implementers in one wave. | | D14 | Doc-link index: dedicated `docs/OFFICIAL-DOCS.md` — complete categorized map of plugin-relevant official pages with a component→doc-page table, per-row verified-dates, the D7 staleness disclaimer, and `https://code.claude.com/docs/llms.txt` named as the authoritative self-updating master list. CLAUDE.md keeps its lean canonical table plus one pointer row to the index. | | D15 | Marketplace metadata maximalism (machine-, user-, org-agnostic posture): populate every helpful-signal field — `relevance` signals wherever meaningful (audit criterion per plugin), `defaultEnabled: false` for personal/niche-category plugins, `displayName` where it genuinely clarifies, complete descriptive metadata. Consumer-facing doc section on org enablement of suggestions (`pluginSuggestionMarketplaces` + source declaration in managed settings). Hard rule: `version` lives in plugin.json only, never in marketplace entries (silent-precedence trap). | | D16 | Audit execution: doctrine docs land first; then per-plugin subagent fanout scores all 47 plugins against a doctrine-derived checklist (~15 dimensions: setup criteria, userConfig migration, exec-form hooks, metadata completeness, component stances, registry conformance, prereq degradation, pointer discipline); findings distill into a plugin×dimension conformance matrix graduating to GitHub issues — one epic + per-wave issues (setup, userConfig, metadata, hooks, convention-seam waves) via the work-items seam; raw per-plugin detail stays memory-tier; automatable checks become the deferred CI gate's backlog. | ### Constraints - Fresh-docs mandate applies at execution time: re-fetch the relevant official pages before each edit wave; this Brief's doc facts were verified 2026-07-17. - Work isolated in worktree, branch `docs/plugin-philosophy`; PRs required, squash merge, PR title per Conventional Commits. - Topic-docs convention change (D13/R6) is a major contract version; every implementer plugin adopts in the same release wave (the contract carries no compatibility machinery). - userConfig migrations preserve existing behavior via `default` values (guardrails toggles default `true`). - Every plugin change clears the migration playbook's gate + plugin-acceptance security review. ### Acceptance criteria - PLUGIN-PHILOSOPHY.md revised: component stance table (D6) with D7 freshness riders, native-first + adoption gate (D3/D4), convention registry (D11), config ownership updated (D8 criterion, exec-form rule, version-placement rule), setup criteria (D9), prerequisite-visibility rule (D10). - MIGRATION-PLAYBOOK.md updated consistently (setup contract, userConfig criterion, security review touchpoints). - `docs/OFFICIAL-DOCS.md` exists: complete categorized page map, component→doc table, verified-dates, staleness disclaimer, llms.txt master pointer; CLAUDE.md carries the pointer row and stays lean. - Topic-docs convention doc corrected per R6 with visibility matrix; R1 settings entry, R2 `.worktreeinclude`, and R3 skill pointer fixes (decompose ticket provenance, architect baseline recording) landed; the three flagged execution-time verifications resolved empirically and recorded. - marketplace.json metadata complete per D15; `claude plugin validate .` passes. - Audit epic + wave issues filed on GitHub with the conformance matrix distilled into the epic; every 47-plugin row scored; raw details in the memory slice. - Existing CI (plugin contract tests, markdownlint) green on every PR. ### Captured assumptions - Consumers run CC ≥ 2.1.207 (userConfig shell-form ban semantics, pluginConfigs scoping); older clients degrade per official behavior, not worked around. - Marketplace remains the melodic-software catalog but every decision holds machine-, user-, and org-agnostic (no solo-consumer scoping). ### Out-of-scope (deferred with triggers) - CI contract gate — trigger: audit identifies automatable checks (D16 backlog). - Bundle plugin (name + dependencies curated set) — trigger: one-command curated install need beyond the fleet-sync skill. - Monitors, themes, channels adoption — trigger: feature exits experimental/immature status at a future doc re-verification (D6 wait rows). - `music` → `creative`, deployment category, and other plugin-organization deferrals remain owned by that Brief. ### Deferred questions - Windows `sensitive` userConfig storage behavior (docs silent on Windows keychain) — empirical verification during audit, before any secret migrates. Arbiter: `/architect` (execution evidence). - Worktree-sweep treatment of ignored files; `--bg` session worktree base semantics; `worktree.baseRef` honored at project-settings scope — empirical smoke tests during D13 execution. Arbiter: `/architect`. - Per-plugin `relevance` signal quality (which signals are genuinely helpful vs noise) — decided per-plugin during the metadata wave. Arbiter: `/architect`. ## Plan Seven phases. Doctrine docs land first (D16 ordering), the topic-docs contract major version ships as one wave, marketplace metadata follows, and the fleet audit runs last against the landed doctrine. The fresh-docs mandate is embedded as the **first work item of every phase** that states platform facts — never a standalone phase, never skipped. The three flagged empirical verifications resolve at their Brief-assigned execution points: worktree-semantics smoke tests → Phase 4 (gates Phase 5 R1/R2); per-plugin `relevance` quality → Phase 6 (per-plugin, during the metadata wave); Windows `sensitive` userConfig storage → Phase 7 (before any userConfig-wave issue touching secrets is filed). ### Phase 1: PLUGIN-PHILOSOPHY.md doctrine revision [DONE] Covers D3, D4, D6, D7, D8, D9, D10, D11. Work items: 1. Fresh-fetch: `plugins`, `plugins-reference`, `skills`, `hooks`, `settings`, `plugin-dependencies` pages; re-verify the 13 component types and the D6 stance facts (skill frontmatter additions, `commands/` legacy status, `bin/` rules, agent field limitations, monitors/themes/channels maturity, v2.1.207 exec-form rule). Any drift from the Brief's 2026-07-17 facts is recorded in the memory slice and the stance table reflects current reality. The verified component-type count (N, expected 13) is written to `.work/plugin-philosophy/component-count.txt` — Phases 1 and 3 sanity checks assert against N, not a hard-coded 13. 2. Add **Native-first principle + adoption gate** section (D3/D4). 3. Add **Component stance table** (D6): 13 rows, each with stance, rationale, verified-date + official-doc link (D7 rider), and the D7 staleness disclaimer heading the table. 4. Extend **Configuration ownership and scope**: D8 userConfig full-potential criterion (native schema fields, `CLAUDE_PLUGIN_OPTION_<KEY>` mirror, retirement of custom env channels), exec-form hooks rule, version-placement rule (`version` in plugin.json only). 5. Rewrite **Setup is explicit and repeatable** to the D9 v2 criteria (required-iff conditions, uniform `setup` skill contract, `Setup` hook event and SessionStart manifest-diff idioms). 6. Extend **Prerequisites and failure behavior** with D10 (graceful degradation, dual agent+user visibility, OTel as candidate channel, no black boxes). 7. Add **Convention registry** section (D11): pointer-only table — one owner doc per shared concern (topic-docs binding, skill layout + evals schema, `lib/hook-utils.sh` sync, report vocabularies, artifact protocol, seam phrasing); registry names and points, never restates. **Sanity Check:** - `grep -c "Verified 2026" docs/PLUGIN-PHILOSOPHY.md` ≥ N (one rider per stance row; N from `component-count.txt`). - `grep -n "Convention registry\|Native-first" docs/PLUGIN-PHILOSOPHY.md` returns both sections. - Component stance table row count = N; Read confirms every verified component type named. - `npx markdownlint-cli2 --config .markdownlint-cli2.jsonc docs/PLUGIN-PHILOSOPHY.md` exit 0 (CI's pinned action is authoritative; local run uses the repo config). ### Phase 2: MIGRATION-PLAYBOOK.md consistency pass [DONE] Depends on Phase 1 (doctrine wording is SSOT; playbook points, never restates). Work items: 1. Update the per-plugin migration gate: setup-contract check (D9), userConfig criterion (D8), exec-form hook rule — each as a pointer to the philosophy doc section plus playbook-specific procedure only. 2. Extend the plugin-acceptance security review touchpoints: `sensitive` userConfig handling, `bin/` collision-safe naming, plugin `settings.json` `agent` prohibition check. 3. Remove or redirect any playbook text that now duplicates Phase 1 doctrine (no restated stance tables). **Sanity Check:** - `grep -n "PLUGIN-PHILOSOPHY" docs/MIGRATION-PLAYBOOK.md` shows pointer citations in the gate and security-review sections. - No restated stance table: no markdown table in MIGRATION-PLAYBOOK.md whose header row contains both `Component` and `Stance` columns (Read assertion — pointers naming the section are fine). - `npx markdownlint-cli2 --config .markdownlint-cli2.jsonc docs/MIGRATION-PLAYBOOK.md` exit 0. ### Phase 3: docs/OFFICIAL-DOCS.md index + CLAUDE.md pointer [DONE] Covers D14. Parallel-safe with Phase 2 (disjoint files); component list comes from the Brief/Phase 1 stance table. Work items: 1. Fresh-fetch `https://code.claude.com/docs/llms.txt`; enumerate every plugin-relevant page. 2. Create `docs/OFFICIAL-DOCS.md`: categorized page map, component→doc-page table, per-row verified-dates, D7 staleness disclaimer, llms.txt named as the authoritative self-updating master list. 3. Add one pointer row to CLAUDE.md's canonical table; CLAUDE.md stays lean (no other growth). 4. **Wave A join step (main session):** reconcile the component→doc table against Phase 1's verified component list (`component-count.txt` + stance table) before PR A — parallel work off the Brief snapshot must converge on Phase 1's fresh-fetched reality. **Sanity Check:** - `test -f docs/OFFICIAL-DOCS.md` && component table has N rows (N from `component-count.txt`). - `grep -n "llms.txt" docs/OFFICIAL-DOCS.md` and `grep -n "OFFICIAL-DOCS" CLAUDE.md` both hit. - CLAUDE.md diff = exactly one added table row: `git diff origin/main...HEAD --stat -- CLAUDE.md` shows a 1-2 line delta. - `npx markdownlint-cli2 --config .markdownlint-cli2.jsonc docs/OFFICIAL-DOCS.md` exit 0; the repo's offline link-integrity check passes on the new file (external-URL lychee lane is advisory weekly — spot-check a sample of new URLs via WebFetch instead). ### Phase 4: Worktree-semantics empirical verification (throwaway spike) [DONE] Feasibility spike (might change Phase 5's shape) — results are evidence, no kept code. Parallel-safe with Phases 1–3 (touches scratchpad + throwaway worktrees only). All tests run in a **throwaway `git init` repo in the scratchpad with a synthetic `origin`** — never in this repo (its ~30 live worktrees, runtime-written `.git/info/exclude`, and main checkout on a feature branch confound every measurement). Use `claude -p --worktree` exclusively (skips the trust dialog; interactive mode errors in a fresh repo). Unique worktree names per run (name reuse resets clean worktrees to base since v2.1.208); the spike removes its own worktrees (`-p`-created worktrees are never auto-cleaned; Windows: expect NTFS lock retries, `git worktree remove --force`). Work items: 1. Fresh-fetch the `worktrees` doc (the doc anchor for `baseRef`/`.worktreeinclude` — not the settings page) plus `settings`; record cited behavior, including the documented fallback "when `origin/HEAD` isn't resolvable, worktrees fall back to current local HEAD". 2. Smoke test A — `worktree.baseRef: "head"` at **project-settings scope**, two arms: **control** (`baseRef` unset or `"fresh"`) asserts marker ABSENT; **treatment** (`baseRef: "head"` in committed `.claude/settings.json`) asserts marker PRESENT. Verdict HONORED only if BOTH arms behave — a marker-present-only test is defeated by the documented origin/HEAD fallback (false positive). Variant A2: spawn from within an existing linked worktree (docs state `head` resolves to that worktree's HEAD — test against that expected value). Variant A3: `settings.json` present only in the worktree checkout vs only in the main checkout — pins which copy a linked-worktree session reads (undocumented; only `settings.local.json` is documented as main-checkout-resolved). 3. Smoke test B — `.worktreeinclude` one-way creation-time copy: use real nested-gitignore paths (`.work/<slug>/…` ignored via a nested `*` `.gitignore`, mirroring this repo) — not a toy root-level pattern; assert copy at creation; modify original, assert no sync-back. 4. Smoke test C — worktree-sweep treatment of ignored files (genuinely undocumented — this test is the only source of truth; capture `git status --ignored` snapshots in the raw transcript) + `--bg` session worktree base semantics. 5. The sub-agent records raw transcripts in `.work/plugin-philosophy/verifications/`, stamps every VERDICT file with `claude --version`, and **returns the VERDICT lines by value**; the **main session** fills the pending rows in this PLAN's "Empirical verification results" table (PLAN.md edits stay main-session-only) and feeds them into Phase 5's R1/R2 design. If the CC version has moved by the Phase 5 gate, re-run the cheap test-A control/treatment pair. **Sanity Check:** - `.work/plugin-philosophy/verifications/` contains ≥ 3 result files, one per smoke test, each ending in a one-line VERDICT (`HONORED` / `NOT-HONORED` / behavior description) and a `claude --version` stamp line. - Test A result file contains BOTH `control:` and `treatment:` lines with opposite marker outcomes (else verdict is invalid by construction). - This PLAN's "Empirical verification results" table row 1 is filled (no `(pending)`). ### Phase 5: Topic-docs contract 2.0.0 + seam fixes R1–R6 (one wave) [TODO] Covers D13. Contract-major change: every implementer adopts in the same wave (no compatibility machinery). Gated by Phase 4 verdicts. Work items: 1. **Pre-flight consumer check (first item):** `Grep`/`Glob` for every consumer parsing the convention surface — `.claude/topic-docs.yaml` keys, slug spec, tier paths, runtime guards, the `scripts/check-cross-plugin-source-drift.sh` registry, hooks reading `docs/topics/` or `.work/`. Document parse paths in the memory slice before editing anything. 2. R6 — rewrite `docs/conventions/topic-docs/README.md`: worktree-visibility rationale, context × tier visibility matrix, native mechanisms named (`worktree.baseRef`, `.worktreeinclude`, by-value returns, tracker index); CHANGELOG entry `2.0.0`; schema untouched unless a key changes (KEEP expected). **Reconcile the Implementers table with reality**: `toolchain` and `verification` carry `reference/topic-docs.md` but are absent from the table; `knowledge`, `claude-ops`, `docs-hygiene` are listed without delta docs — the 2.0.0 table must match the actual fleet (add/annotate rows or document why a row is delta-doc-free). The CHANGELOG 2.0.0 entry states the **mixed-fleet window** and why it is safe (no tier/key/slug-spec change — installed cache copies and in-flight branches keep 1.x text until they update; divergence is doctrinal, not layout-corrupting), and notes a post-PR-B stale-text sweep obligation for in-flight branches at their merge time. 3. R1 — committed `.claude/settings.json` with `worktree.baseRef: "head"` (shape per Phase 4 smoke test A verdict; if NOT-HONORED at project scope, execute the tagged fallback below). Rollout note in the PR B description + convention doc: a clone with an existing untracked `.claude/settings.json` hits "untracked working tree file would be overwritten" on pull — document the remedy; state the repo-wide worktree-spawn behavior change; **gitignore `.claude/worktrees/` in the same change** (mandatory — the runtime `.git/info/exclude` entry is machine-local; CI checkouts and fresh clones lack it, and partial tracking of `.claude/` otherwise turns nested worktrees into `git add -A` hazards); run the hygiene CI lanes (machine-specific-paths, gitleaks, editorconfig) locally on the new tracked file. Document the escape hatch: a personal `.claude/settings.local.json` (main-checkout-resolved, covers every worktree) silently overrides R1 machine-wide — the convention doc states this; no audit dimension may assume R1 is universally in force. **Consumer-adoption path (mandatory):** repo settings never travel with marketplace-installed plugins (isolated cache) — R1/R2 as files fix only this repo. The 2.0.0 doc ships a consumer-adoption section: the settings snippet + a `.worktreeinclude` template, scoped as "authoring-repo materialization; consumer repos self-apply" (routing it through a D9 setup-skill `apply` action is recorded as a follow-on trigger, not built now). The visibility matrix gains a caveat row: a `WorktreeCreate` hook makes `.worktreeinclude` inert (documented) — hook script owns the copy. 4. R2 — `.worktreeinclude` with targeted memory-tier patterns (stage ledgers, EXPLORE/RESEARCH; not baselines/raw scratch); one-way creation-time copy documented in the convention doc. 5. R3 — pointer-discipline fixes: `plugins/work-items/skills/decompose` cites the PR (not contract paths) in ticket provenance; `plugins/planning/skills/architect` records distilled baseline values in PLAN (raw captures stay memory-tier). Sweep both skill bodies for prunable-path citations. 6. R4/R5 — convention doc text: isolated workers return results by value with the orchestrator writing both tiers in the parent checkout (R4); the work-item tracker named as the cross-lane awareness/index layer, markdown-in-tickets rejected with rationale (R5). 7. Implementer wave: update all 8 `plugins/*/reference/topic-docs.md` delta docs against the 2.0.0 owner doc; bump each touched plugin's `plugin.json` semver + CHANGELOG; docs-hygiene declutter detector references checked (reader row). File inventory (checkbox discipline — tick as processed): | File | Action | Rationale | |---|---|---| | [ ] `docs/conventions/topic-docs/README.md` | MODIFY | R6 rewrite, visibility matrix, R4/R5 text | | [ ] `docs/conventions/topic-docs/CHANGELOG.md` | MODIFY | 2.0.0 entry | | [ ] `docs/conventions/topic-docs/topic-docs.schema.json` | KEEP (audit) | no key changes expected | | [ ] `docs/conventions/topic-docs/examples/*` | AUDIT | update only if matrix/mechanisms change examples | | [ ] `.claude/settings.json` | CREATE | R1 `worktree.baseRef` | | [ ] `.worktreeinclude` | CREATE | R2 patterns | | [ ] `plugins/discovery/reference/topic-docs.md` | MODIFY | 2.0.0 adoption | | [ ] `plugins/implementation/reference/topic-docs.md` | MODIFY | 2.0.0 adoption | | [ ] `plugins/planning/reference/topic-docs.md` | MODIFY | 2.0.0 adoption | | [ ] `plugins/review/reference/topic-docs.md` | MODIFY | 2.0.0 adoption | | [ ] `plugins/session-flow/reference/topic-docs.md` | MODIFY | 2.0.0 adoption | | [ ] `plugins/toolchain/reference/topic-docs.md` | MODIFY | 2.0.0 adoption | | [ ] `plugins/verification/reference/topic-docs.md` | MODIFY | 2.0.0 adoption | | [ ] `plugins/work-items/reference/topic-docs.md` | MODIFY | 2.0.0 adoption | | [ ] `plugins/work-items/skills/decompose/SKILL.md` | MODIFY | R3 ticket provenance | | [ ] `plugins/planning/skills/architect/SKILL.md` | MODIFY | R3 baseline recording | | [ ] 8–10 × `plugins/*/plugin.json` + `CHANGELOG.md` | MODIFY | semver bump per touched plugin | | [ ] `plugins/knowledge/…`, `plugins/claude-ops/…`, `plugins/docs-hygiene/…` | AUDIT | implementer-table rows without delta docs — verify no stale convention text | **Sanity Check:** - `bash scripts/check-cross-plugin-source-drift.sh --check` exit 0 (the flag CI runs; flagless mode is informational only). - `grep -n "2.0.0" docs/conventions/topic-docs/CHANGELOG.md` hits; `grep -rn "visibility matrix" -i docs/conventions/topic-docs/README.md` hits. - Implementers-table parity: every `plugins/*/reference/topic-docs.md` path has a matching table row and vice versa (Read assertion against the glob result). - Pre-flight consumer list exists: `.work/plugin-philosophy/consumers-topic-docs.md` non-empty. - Every plugin with a modified file has a `plugin.json` version bump: `git diff origin/main...HEAD --name-only | grep '^plugins/' | cut -d/ -f2 | sort -u` each has a matching `plugins/<name>/plugin.json` in the diff. - `bash scripts/validate-plugins.sh` exit 0 (includes `generate-catalog.mjs --check` — regenerate the catalog if any plugin.json description changed). - `npx markdownlint-cli2 --config .markdownlint-cli2.jsonc` on touched .md files exit 0. ### Phase 6: Marketplace metadata wave [TODO] Covers D15 + per-plugin `relevance` quality verification (deferred question c). Work items: 1. Fresh-fetch `plugin-marketplaces` + `discover-plugins` + `plugins-reference` (default-enablement section) + the dedicated `plugin-relevance` page; re-verify entry schema (`relevance`, `defaultEnabled`, `displayName`, description precedence, `version` silent-precedence trap). **`defaultEnabled` flip semantics for already-installed consumers are undocumented** — if the fetched pages stay silent, run a 2-minute empirical flip on one plugin before the wave (does a marketplace refresh disable an existing install?). Never touch a plugin's `name` (breaks existing installs without a `renames` map); `displayName` is safe. 2. Per-plugin pass over all 47 entries: add `relevance` only where the signal is genuinely helpful (judged per-plugin — noise rejected), `defaultEnabled: false` for personal/niche categories, `displayName` where it clarifies, complete descriptions; assert **no `version` field in any entry**. 3. Consumer-facing doc section on org enablement of suggestions (`pluginSuggestionMarketplaces` + managed-settings source declaration) — lands in the discover/consumer section of README or OFFICIAL-DOCS per where consumer docs live (decided at execution against the fetched page). 4. Record per-plugin relevance decisions (adopted vs rejected-as-noise) in `.work/plugin-philosophy/relevance-decisions.md`. 5. Regenerate the README catalog: `node scripts/generate-catalog.mjs` (CI runs `--check`; metadata edits drift the generated block otherwise). **Sanity Check:** - `claude plugin validate .` exit 0. - `node scripts/generate-catalog.mjs --check` exit 0. - `node -e` assertion: 47 entries; every entry resolves a description (entry or plugin.json); `version` absent from all entries — exit 0. - `.work/plugin-philosophy/relevance-decisions.md` has 47 rows. ### Phase 7: Fleet conformance audit fanout + tracker graduation [TODO] Covers D16. Runs against merged doctrine (Phases 1–6 landed). Work items: 1. **Search-before-create (first item):** `gh issue list --search` for an existing plugin-conformance epic / wave issues. Match found → pivot to updating the existing items (record the match + pivot in the memory slice); no match → proceed to create. Verify required labels exist (`gh label list`) and create missing ones before any `gh issue create --label` call (missing labels fail the create). 2. Derive the audit checklist (~15 dimensions) from the landed doctrine docs: setup criteria (D9), userConfig migration (D8), exec-form hooks, metadata completeness (D15), component stances (D6), registry conformance (D11), prereq degradation (D10), pointer discipline (R3), freshness riders (D7), plus dimensions the doctrine text yields. **Freeze a rubric file** with per-dimension anchored PASS/FAIL criteria + one worked example, injected verbatim into every worker prompt (uncalibrated independent scoring across batches encodes rubric drift, not conformance). **Authority rule:** plugins are scored against **landed doctrine only**; where a fresh-fetched doc disagrees with doctrine, that is a doctrine-update finding (its own wave), never plugin nonconformance. Dimensions may not assume R1 is universally in force (local-settings override exists). Checklist + rubric → memory slice. 3. Fresh-fetch the component doc pages the checklist cites (to detect doctrine-vs-platform drift per the authority rule above). 4. **Windows `sensitive` userConfig empirical verification** (deferred question a): configure a throwaway `sensitive` userConfig value on this Windows machine; locate where it persists (Credential Manager vs plaintext file); VERDICT recorded before any userConfig wave issue involving secrets is filed. Secrets excluded from that wave if storage is plaintext (tagged fallback below). 5. Fanout: **pilot batch of 3–5 plugins first**, reviewed by the main session against the rubric before full fanout; then per-plugin subagents score the remainder in **batches of 8–10**; each worker writes its own raw report to `.work/plugin-philosophy/audit/<plugin>.md` (memory-tier raw output is carved out of R4 — R4's orchestrator-writes rule governs contract/durable tiers) and returns only its scored dimension row by value; the orchestrator (main session) appends matrix rows incrementally per batch, so a compaction mid-run loses nothing. **Double-score a random 3-plugin sample** with independent workers and reconcile disagreements before graduating the matrix. 6. File the GitHub epic (conformance matrix distilled inline — **single-token score cells only**, prose lives in per-wave issues; GitHub bodies cap near 64 KB) + per-wave issues (setup, userConfig, metadata, hooks, convention-seam) via the work-items seam; issues cite the epic + PR permalinks, never contract/memory paths (R3). Automatable checks list → epic section = deferred CI gate backlog (D1 trigger). **Sanity Check:** - Search outcome recorded: `.work/plugin-philosophy/audit/tracker-search.md` states the query + hit count + create-vs-update decision. - `ls .work/plugin-philosophy/audit/*.md | wc -l` ≥ 47 (one report per plugin) + matrix file with 47 scored rows. - `gh issue list --label epic --search "plugin conformance"` (or equivalent) returns the epic; epic body contains the matrix; ≥ 5 wave issues reference the epic. - `grep -c "docs/topics/\|\.work/" <epic and wave issue bodies>` = 0 (pointer discipline). - Windows `sensitive` VERDICT file exists in `.work/plugin-philosophy/verifications/`. ### Empirical verification results | # | Question | Phase | VERDICT | |---|---|---|---| | 1 | `worktree.baseRef` at project scope; sweep of ignored files; `--bg` base | 4 | HONORED (CC 2.1.212, control+treatment): committed project `.claude/settings.json` `worktree.baseRef: "head"` honored, incl. from linked worktrees (A2: resolves to the worktree's own HEAD; A3: a linked-worktree session reads its OWN checkout's settings.json). `.worktreeinclude`: nested-gitignored files qualify, copy is one-way creation-time. Sweep: `--worktree` worktrees never auto-swept (empirical); subagent/bg sweep would remove ignored-only worktrees (INFERRED — ignored ≠ untracked). `--bg` base = origin/HEAD by default, so R1 moves it to local HEAD. Windows caveat: deep worktree base paths can trip git PATH_MAX (`'$GIT_DIR' too big`); this repo's base (~95 chars) is safe. | | 2 | Per-plugin `relevance` signal quality | 6 | (pending — per-plugin ledger) | | 3 | Windows `sensitive` userConfig storage | 7 | (pending) | ## Blast radius **HIGH.** Matches stress-test triggers: new conventions constraining all future work (doctrine + contract-major), architecture decisions across 47 plugins + 8 implementer materializations, shared committed settings (`.claude/settings.json`) affecting every session, and undocumented behavior (worktree semantics, Windows sensitive storage — mitigated by the empirical phases). Reversible via git revert (docs/metadata only, no runtime code), and existing CI (contract tests, markdownlint, drift check) gates every PR — hence HIGH, not CRITICAL. ## Stress-test summary Two fresh-context adversarial passes ran; all findings verified against the repo before adoption. **Plan-reviewer (Step 3):** 9 IMPORTANT + 5 SUGGESTION, 0 CRITICAL — all applied: implementer-roster reconciliation + parity check (Phase 5), CI-parity sanity commands (drift `--check`, catalog `--check`, markdownlint config, `node -e` over Python), pointer-vs-restate check made structural (Phase 2), Phase 4 by-value/fence contradiction resolved, component-count made variable with a Wave A join step, PR-chain PLAN lifecycle defined, Phase 7 batching + label verify-or-create, worktree-variant smoke tests, R1 rollout notes. **Devils-advocate (Step 4):** 16 assumptions attacked; 4 mandatory changes, all applied: (1) Phase 4 redesigned — isolated scratch repo with synthetic origin, control+treatment arms (defeats the documented origin/HEAD-fallback false positive), settings-scope variant A3, CC-version-stamped verdicts with re-run at the Phase 5 gate; (2) PLAN lifecycle switched to branch-local prune-per-PR (the program must not self-violate the contract it ships); (3) 2.0.0 doc gains a consumer-adoption path — repo settings provably never reach marketplace-installed consumers; (4) Phase 7 calibration — frozen anchored rubric, pilot batch, double-scored sample. Also adopted: mandatory `.claude/worktrees/` gitignore in PR B, `WorktreeCreate`-hook caveat for `.worktreeinclude`, mixed-fleet window statement in the CHANGELOG, doctrine-wins authority rule for audit scoring, `defaultEnabled`-flip empirical check, matrix cell budget (64 KB body cap), `name` immutability during the metadata wave. One finding escalated to a user gate: R6 major-vs-minor contradiction with the contract's own versioning rule (see User-approval gates). ## Execution shape Two parallel-safe waves inside an otherwise sequential PR chain; fanout inside Phase 7. | Phase | Surface | Basis | |---|---|---| | 1 | Main session | Judgment-heavy doctrine writing; SSOT wording others depend on | | 2 | Main session | Depends on Phase 1 wording; pointer discipline needs judgment | | 3 | Sub-agent worker (parallel with 1–2) | Mechanical index build from llms.txt; disjoint files (`OFFICIAL-DOCS.md`, one CLAUDE.md row) | | 4 | Sub-agent worker (parallel with 1–3) | Scripted smoke tests; touches scratch/throwaway worktrees only | | 5 | Main session (implementer sweep may fan out mechanically) | Contract-major judgment; 25-file wave needs single editorial voice | | 6 | Main session | Single file; 47 per-plugin relevance judgments | | 7 | Workflow/sub-agent fanout, orchestrated by main session | D16-locked fanout; R4 by-value returns | Wave A (parallel): Phase 1 (main) ∥ Phase 3 (sub-agent) ∥ Phase 4 (sub-agent). Zero file overlap: P1 = `docs/PLUGIN-PHILOSOPHY.md`; P3 = `docs/OFFICIAL-DOCS.md` + CLAUDE.md; P4 = `.work/` + scratch. Wave B (sequential): Phase 2 → Phase 5 → Phase 6 → Phase 7. Scope fences (Wave A): P3 agent ALLOWED `docs/OFFICIAL-DOCS.md`, `CLAUDE.md` (one row); FORBIDDEN everything else incl. PLAN.md. P4 agent ALLOWED `.work/plugin-philosophy/verifications/` and throwaway `git init` repos under the scratchpad (its own branches/worktrees live there); FORBIDDEN every file and branch of THIS repo (note: `claude -p --worktree <name>` creates branches named `worktree-<name>` — another reason the spike never runs in this repo). Sequential fallback: any fence violation or agent failure → that phase re-runs inline main-session in Wave B order. PLAN.md edits are main-session-only. Cost note: Wave A = 2 extra agents vs sequential (~saves one serial doc-build + smoke-test round); Phase 7 = ~47 scoring agents (D16-locked, run regardless of shape). ## Open questions None blocking — the three empirical questions are scheduled inside phases with tagged fallbacks. ## Handoff to implementation ### User-approval gates - **[BRIEF CONTRADICTION — user decision required]** D13 locks R6 as a **major** contract version ("2.0.0, one wave"), but the contract's own Versioning rule says major = "moves a tier, renames a key, or alters the slug spec" — R6 does none (schema KEEP; the change is visibility semantics + doctrine text). Options: (a) keep 2.0.0 and amend the Versioning rule so visibility-semantics guarantees also count as major (the doctrine repo then applies its own rule consistently); (b) downgrade to a 1.x minor, dissolving the one-wave coordination burden and most of Phase 5's mixed-fleet risk. RECOMMENDED: (a) — the Brief locked the one-wave clean break deliberately, and a visibility-guarantee change does alter what implementers may rely on; the rule amendment makes the label honest. The plan as written assumes (a). - [FALLBACK — confirm or override] Smoke test A fails (project-scope `worktree.baseRef` not honored): R1 degrades to documenting the limitation + the strongest honored scope in the convention doc, and an upstream issue is filed; R2/R6 proceed unchanged. - [FALLBACK — confirm or override] Windows `sensitive` storage is plaintext: secret-bearing userConfig migrations are excluded from the userConfig wave issue and recorded as blocked-upstream in the epic; non-secret migrations proceed. - Scope-expansion of any kind (new convention, new component adoption) mid-flight → stop and ask. ### Execution shape ([EXEC-SHAPE] tagged) - [EXEC-SHAPE] PR slicing: PR A = Phases 1–3 (doctrine + index, current branch `docs/plugin-philosophy`); PR B = Phases 4–5 (contract 2.0.0 wave; Phase 4 evidence rides the memory tier, distilled results in PLAN); PR C = Phase 6 (metadata); PR D = close-out (Phase 7's PLAN/verdict updates + prune-with-pointer). Rationale: reviewability + distinct concerns (doctrine vs contract-major vs metadata); each PR independently green on existing CI. - [EXEC-SHAPE] PLAN.md lifecycle across the PR chain — **branch-local, prune-per-PR**: the topic-docs contract says contract slices are pruned before merge, and this program (which ships that very contract's 2.0.0) must not self-violate by parking a slice on `main` for weeks. Each PR branch commits the current PLAN, pastes it into its PR description, and prunes the slice in a final commit before merge; the next PR branch (cut from post-squash `main`) re-commits the updated PLAN from the local working tree. Cross-PR continuity = the PR-description pastes + (from Phase 7) the epic. Close-out at PR D: Phase 7's verdict rows and final status tags commit there, durable outcomes graduate, final prune-with-pointer. The Windows `sensitive` VERDICT is recorded durably (PLAN verdict table → PR D description + epic), not only in gitignored `.work/`. (Alternative rejected: adding a multi-PR-program exception clause to the 2.0.0 lifecycle text — viable, but it lands only in PR B while PR A would already need it; override at approval if the exception clause is preferred.) - [EXEC-SHAPE] Wave A parallelism + fences as tabled above. - [EXEC-SHAPE] Phase 7 fanout surface: per-plugin subagents (Workflow engine if available, plain sub-agent fanout otherwise) — D16 locks the fanout itself. - [EXEC-SHAPE] Empirical verifications embedded at Brief-assigned execution points (P4/P6/P7) rather than a standalone verification phase. ### Mechanical work - Commit boundaries: one commit per phase minimum; Phase 5 = one wave commit for the contract bump + implementer adoption (clean break lands atomically); PLAN.md status-tag updates ride each phase's commit. Each PR branch is cut from **post-squash `main`**, never from the previous PR branch (stacking would replay the prior PR's squashed commits in the diff). - Verification checkpoints: run each phase's Sanity Check before its commit; existing CI (contract tests, markdownlint, drift check) green before each PR merge. - Sequential fallback: documented under Execution shape; orchestrator-writes rule (R4) applies to all fanout output. - Close-out: `/architect close-out` at PR time — PLAN.md into PR description `<details>`, durable outcomes graduate (vault_backend `docs`), contract slice pruned with pointer. --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
# Conflicts: # docs/MIGRATION-PLAYBOOK.md # docs/PLUGIN-PHILOSOPHY.md
kyle-sexton
enabled auto-merge (squash)
July 17, 2026 18:57
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 144086f978
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
Claude finished @kyle-sexton's task in 2m 30s —— View job Review: docs/naming-conventions
OverallTwo items remain unresolved — one new (the Codex P2 on the audit/mutation gap) and one carried from the 18:30 round (the cross-plugin migration-debt sentence). Both are small, in-scope additions to
|
| Finding | Source | Status |
|---|---|---|
setup/configure contradiction in Philosophy Setup section |
Claude review (medium) | Fixed in 29277b1 |
setup/configure surviving in MIGRATION-PLAYBOOK lines 265–266, 290 |
Claude review (medium) | Fixed in 4feec24 |
| Compound verb+qualifier rule undocumented | Claude review (medium) | Fixed in 29277b1 |
| Branch-only topic contract in diff | Codex P2 | Fixed in cf789ad; tracker → issue #280 |
| Vendor-wrapper stutter vs playbook naming rule | Codex P2 | Fixed in 29277b1 |
known-issues noun not matching exceptions |
Claude review (medium) | Resolved by pruning PLAN.md |
Empty ## Plan section |
Claude review (low) | Resolved by pruning |
update verb narrowing uncalled-out |
Claude review (low) | Deferred; acceptable follow-up |
Not flagged
- MIGRATION-PLAYBOOK wrapper-echo/root-echo exemptions and vendor-CLI-verbs scoping all agree with PLUGIN-PHILOSOPHY — consistent.
- The hyphenated topic-qualifier rule integrates cleanly with the verb table and the examples in the PLAN.md rename table.
- Built-in collision non-rule (namespaced plugin skills cannot collide) is unambiguous.
setup-only is now the single canonical form across all three documents.- Fresh-docs mandate: references dated 2026-07-17 and linked — compliant.
- Doc-only changes; no runtime surface, no security surface.
kyle-sexton
added a commit
that referenced
this pull request
Jul 17, 2026
## What Renames the `toolchain` plugin's `build` skill to `check` — one atomic rename PR from the shadowed-skill-renames plan (`docs/topics/shadowed-skill-renames/PLAN.md`, PR #256): - `git mv plugins/toolchain/skills/build plugins/toolchain/skills/check` (directory name is what sets the `/toolchain:check` command; frontmatter `name` moved with it) - Repo-wide reference sweep: every living reference to `/toolchain:build` updated — `verification:confirm`'s Stage-1 delegation, `implementation:implement` / `implement-dispatch` build-gate references, `testing:*` SSOT citations, `toolchain:lint` / `toolchain:setup` cross-references, reference YAMLs, READMEs, evals, `docs/conventions/ecosystem-commands`, and the plugin-organization decision record's live seam reference - `toolchain` plugin bumped 0.1.1 → 0.2.0 with a breaking-rename CHANGELOG entry - No `renames`-map entry, per the plan's constraint (clean breaking change while the marketplace settles) ## Why The skill runs build + test + lint as a deterministic pass/fail gate; per the marketplace naming grammar `check` = deterministic gate. "build" is also a null phase for several covered ecosystems (Python, Markdown), so the old name under-described what the skill does. Description keeps the "build", "does it compile", "run tests" trigger phrases so auto-invocation behavior is unchanged. ## Breaking `/toolchain:build` no longer exists — invoke `/toolchain:check`. Arguments, behavior, and the resolution ladder are unchanged. Consumers get the rename via the 0.2.0 plugin bump; there is no automatic renames-map migration. ## Verification - `git grep toolchain:build` → hits only in historical CHANGELOG entries (implementation, testing, verification, source-control, toolchain 0.1.0) and the new 0.2.0 breaking-rename note - `node scripts/validate-plugin-contracts.mjs` → pass (17 setup skills, 1377 plugin files) - `scripts/check-cross-plugin-source-drift.sh --check` → clean - `markdownlint-cli2` over touched markdown → 0 errors - Skill-name mechanics verified against https://code.claude.com/docs/en/skills (plugin skill command name = directory name, namespaced by plugin) Deliberate skips: historical CHANGELOG entries and the pre-split skill-name list in `plugins/implementation/README.md`'s migration section keep the old name as historical record; `marketplace.json` `tags`/`keywords` keep "build" (still functionally descriptive); no vendor/ or `.work/` touched. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01YVApnNGoKxYMJKNQx1QK8C ## Related No linked issue. Contract source: #256. Sibling shadowed-skill rename PRs: #268, #269, #270. --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
kyle-sexton
added a commit
that referenced
this pull request
Jul 17, 2026
## What Renames the `planning:architect` skill to `planning:plan` — one atomic breaking-change PR per the shadowed-skill-renames contract (`docs/topics/shadowed-skill-renames/PLAN.md`, PR #256): - `git mv plugins/planning/skills/architect → plugins/planning/skills/plan`; frontmatter `name: plan` matches the directory (per the plugins reference: a `skills/<dir>/SKILL.md` skill is named by its directory; the frontmatter `name` controls the invocation name — https://code.claude.com/docs/en/plugins-reference). - Repo-wide reference sweep: every `/planning:architect`, bare `/architect`, arbiter tag (`arbiter: /architect`), `architect-ready` → `plan-ready`, `architect-checklist.md` → `plan-checklist.md`, pipeline-chain prose (`interview → architect → implement`), and the marketplace/plugin keyword tag `architect` → `plan`. Cross-plugin references (implementation, testing, knowledge, claude-ops, session-flow, work-items, prototype, docs) ride in the same PR. - `plugins/planning/plugin.json` `0.12.0` → `0.13.0` (0.x breaking-by-minor precedent) + CHANGELOG entry explaining the shadow-compromise undo. - No `renames`-map entry (clean break per contract; the marketplace `renames` field is plugin-level only anyway — https://code.claude.com/docs/en/plugin-marketplaces). ## Why breaking Consumers invoking `/planning:architect` get skill-not-found and must switch to `/planning:plan`. Claude Code's built-in `/plan` (plan-mode toggle) is unaffected — plugin skills have no bare command form. ## Deliberately unchanged - Historical CHANGELOG entries (planning, prototype) keep `/planning:architect` as written — past entries are records, not live references. - The `architecture` plugin and every `/architecture:improve` reference (different thing; substring guarded with word boundaries). - English-word uses of "architect": event-storming "architect's homework" (DDD role), `extract-ssot`'s internal `architect-plan` phase name (verb), `playbooks:boris` `code-architect.md` (Boris's own agent file), `rename-references` teaching examples of stale chains, `docs/CATALOG-TAXONOMY.md` category gloss. - `'architect this'` stays as a trigger phrase in the renamed skill's description. - Bare `/architect` self-references became `/planning:plan` (not bare `/plan`) — the contract itself notes bare `/plan` names the built-in plan-mode toggle and plugin skills have no bare command form, so the namespaced form is the only unambiguous spelling. ## Verification - `git grep -n "planning:architect"` → hits only in CHANGELOG historical entries (kept intentionally). - `git grep -nw -e "/architect"` → zero hits repo-wide. - Remaining case-insensitive `architect` hits audited one-by-one — all in the deliberate-keep list above. - All touched JSON (`marketplace.json`, `plugin.json`, evals) validate with `jq empty`. - Frontmatter `name: plan` matches directory `plugins/planning/skills/plan/`. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01YVApnNGoKxYMJKNQx1QK8C ## Related - Program contract: #280 (shadowed-skill-renames naming grammar rollout) - Conventions PR: #256 No linked issue — program-level rename executed under #280. --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
kyle-sexton
added a commit
that referenced
this pull request
Jul 17, 2026
…biquitous-language (#279) Executes the domain-driven-design extraction slice of the shadowed-skill-renames contract (`docs/topics/shadowed-skill-renames/PLAN.md`, PR #256): a new `domain-driven-design` plugin (0.1.0) housing `/domain-driven-design:ubiquitous-language`, moved from `/planning:domain-modeling`. No linked issue ## Boundary rationale - **DDD stewardship, not task-shaping.** The skill maintains the consuming project's committed vocabulary record — canonical terms, rejected synonyms, what-it-IS definitions, routing among already-known bounded contexts — and explicitly refuses bounded-context discovery. "domain-modeling" over-promised (it never models a domain); the concern is a DDD practice discipline, not a planning-stage task shape, so it moves out of `planning` into a plugin scoped to DDD practices. Deferred residents (`context-mapping`, `aggregate-design`) join when they materialize; the new plugin's README records that trigger. - **`event-storming` stays standalone.** Per eventstorming.com's own positioning, EventStorming is multi-purpose (business-flow analysis, service design, software architecture — DDD is one application), so it is not folded into the DDD plugin. The moved skill's soft routing to the EventStorming capability is unchanged, and event-storming's references to the glossary steward remain soft "when available" routes. ## Dependency (fresh-docs cited) - `planning` (0.12.0 → **0.13.0**, breaking for `/planning:domain-modeling` invokers) declares `"dependencies": ["domain-driven-design"]` in `plugin.json`. Per the current official docs, a dependencies entry "can be a bare string with only the plugin name … which depends on whatever version that plugin's marketplace provides", the name "resolves within the same marketplace as the declaring plugin", and "when you install a plugin that declares dependencies, Claude Code resolves and installs them automatically" — https://code.claude.com/docs/en/plugin-dependencies (fetched this session). - The `dependencies` array is part of the plugin manifest schema ("Other plugins this plugin requires, optionally with semver version constraints") — https://code.claude.com/docs/en/plugins-reference (fetched this session). - Because `planning` declares the dependency, its `interview`/`design` inline invocations of `/domain-driven-design:ubiquitous-language` are legal cross-plugin references under the contract's rule (required-for-contract → declared dependency). `architecture` and `event-storming` keep soft "when available" references with graceful degradation, so they need no dependency. ## Change set - New `plugins/domain-driven-design/`: manifest (0.1.0), README, CHANGELOG; skill moved via `git mv` with frontmatter `name: ubiquitous-language` (description keeps the domain-modeling / glossary / ubiquitous-language / define-this-domain-term triggers); the skill's `context/` and `evals/` moved with it — it has no `${CLAUDE_PLUGIN_ROOT}` references, only skill-relative links, so nothing re-roots. - `marketplace.json`: new `domain-driven-design` entry (category `design`); planning's `domain-modeling`/`ubiquitous-language`/`glossary` tags moved to it. **No `renames`-map entries** (contract constraint). - `planning` 0.13.0: dependency declared, keywords trimmed, README/description updated, CHANGELOG marks the breaking move. - Repo-wide sweep: every live `/planning:domain-modeling` reference retargeted (planning `interview` + `design` bodies and evals, `architecture:improve`, event-storming methodology/simulation references and evals). Historical CHANGELOG entries left untouched; `git grep planning:domain-modeling` now hits only CHANGELOGs. - README catalog regenerated via `scripts/generate-catalog.mjs`; `validate-plugin-contracts.mjs`, `validate-plugins.sh`, and markdownlint pass locally. ## Rebase note PR #276 (architect→plan) also bumps `planning` and edits its CHANGELOG plus the `interview`/`design` skill bodies. This PR deliberately does **not** include any of #276's changes; whichever merges second takes a rebase (version + CHANGELOG adjacency, possible body-line context conflicts in `interview`/`design`). ## Related - PR #256 — codifies the naming grammar and carries the execution contract this PR implements. - PR #276 — `planning:architect` → `planning:plan` rename (overlapping `planning` bump; see rebase note). 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01YVApnNGoKxYMJKNQx1QK8C --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
kyle-sexton
added a commit
that referenced
this pull request
Jul 17, 2026
… (0.6.0) (#300) Extracts the all-PR babysit loop from `/source-control:pull-request` into a standalone `/source-control:babysit-prs` skill (distinct discovery intent: fleet loop vs single-PR lifecycle) and hoists the shared review discipline to plugin scope. Phase 1 of the babysit-prs migration contract (`docs/topics/babysit-prs-migration/PLAN.md` on this branch); capability convergence with the dotfiles skill (tiers, Python engine, userConfig) is the follow-up PR. Closes #260 ## Change set - **New skill `plugins/source-control/skills/babysit-prs/`** — SKILL.md (compact per-PR checklist, NEVER-merges invariant, gotchas from observed failure history), `reference/loop.md` (the former `babysit.md`, reworked), routing/refusal/anti-pattern evals. Phase-1 behavior is identical to the former `babysit` action (all open non-draft PRs, Dependabot included); the own-PRs safe-default narrowing is a Phase 2 deliverable. - **Plugin-scope seam** — `reference/review-discipline.md` is the single committed copy of the shared discipline (finding extraction + mandatory ≥3-finding subagent dispatch, per-finding D1–D7 verification gates, self-reply filter); both skills' checklists cite it. `monitor.md`'s three cross-references into the former babysit reference invert to the seam. - **Shared scripts hoisted** to plugin-root `scripts/` via `git mv`: `fetch-all-pr-comments.sh`, `babysit-readiness-gate.sh`, `test-helpers.sh` (+ tests); all citations re-rooted to `${CLAUDE_PLUGIN_ROOT}/scripts/`. `discover-prs.sh` retired (inline `gh pr list` filter is the discovery contract). - **Breaking (0.5.1 → 0.6.0, 0.x breaking-by-minor):** the `babysit` action leaves the pull-request surface; pull-request keeps only negative-routing pointers. Eval 9 moved to the new skill's eval set (ids stay stable; gap is legal per the evals schema). - Metadata: plugin description/keywords, marketplace tags, plugin README skill section, CHANGELOG 0.6.0, root README catalog regenerated. ## Trigger continuity (skill split — decompose step 5 evidence) | Retired trigger (old `pull-request` surface) | Successor | |---|---| | `'babysit PRs'` (description trigger) | `babysit-prs`: "Use when: 'babysit PRs', 'babysit my PRs', 'watch my open PRs', 'keep my PRs moving', 'advance all open PRs', or pairing with /loop" | | `/pull-request babysit` (action) | `/source-control:babysit-prs` | | `/loop /pull-request babysit` (loop pairing) | `/loop /source-control:babysit-prs` | Negative routing boundaries: `pull-request` description now carries "not for the all-PR babysit loop (use /babysit-prs)"; `babysit-prs` carries "not for the single-PR lifecycle: prep, create, monitor one PR, or merge (use /pull-request)". Routing evals: `babysit-prs` evals 1–2 (vocabulary routes to the loop skill; single-PR lifecycle stays with `pull-request`). `/skill-quality:check` on the same-path `pull-request` rewrite with `CHECK_SKILL_BASE_REF=origin/main` reports the expected check-3 finding — dropped trigger `'babysit PRs'` — which this table answers (the checker deliberately skips new paths; this table + the routing evals are the required split evidence). New-path check on `babysit-prs`: PASS, 0 errors, 0 warnings. ## Fresh-docs citations (Gate 0) - Skills — directory structure, frontmatter fields, description-driven auto-invocation, supporting files: <https://code.claude.com/docs/en/skills> (fetched this session) - Plugins reference — `skills/` location rule, `${CLAUDE_PLUGIN_ROOT}` semantics, manifest `version`/`keywords`: <https://code.claude.com/docs/en/plugins-reference> (fetched this session) ## Naming rationale `babysit-prs` carries its object in the leaf name for trigger continuity with the migrated vocabulary ("babysit PRs" is the phrase users reach with) and to disambiguate from babysitting other source-control objects; verb-object compound precedent: `scan-todos`, `youtube-digest`. ## Validation - `scripts/run-plugin-tests.sh` affected tests green (hoisted `fetch-all-pr-comments`, `babysit-readiness-gate`; re-pointed `fetch-annotations`, `fetch-failed-logs`, `parse-branch-issue`); full lane re-verified by CI - `scripts/validate-plugins.sh` exit 0 (contracts, catalog `--check`, `claude plugin validate` per plugin + `--strict`) - markdownlint + shellcheck clean; exec bits preserved via `git mv` - Non-source-repo smoke (`claude --plugin-dir … -p` from a clean consumer repo): `/source-control:babysit-prs` discovered with the new description. Known transition-window condition: the user-level dotfiles `babysit-prs` skill shares the vocabulary until the migration's cutover phase retires it - Residue sweep: `grep -ri babysit` in the pull-request skill returns only the three deliberate sibling pointers; no stale `babysit.md` or old script-path citations anywhere in the plugin ## Contract note `docs/topics/babysit-prs-migration/PLAN.md` (Brief + phased Plan) rides this branch and stays for the follow-up convergence PR; the slice is pruned at the migration's final PR per the topic-docs close-out. ## Related - #256 — skill-naming grammar + cross-plugin reference rules this split implements (decompose procedure, trigger-continuity evidence) - #257 — plugin doctrine (component stances, shared-policy-at-plugin-scope) governing the seam placement - Follow-up: PR-B (capability convergence — dotfiles babysit-prs port, tiers, Python engine, userConfig/setup) per the migration contract on this branch 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
kyle-sexton
added a commit
that referenced
this pull request
Jul 20, 2026
#734) ## Summary "What test type for a given change" knowledge lived in three sites: `testing:plan`'s file-type classification table (the actual table), `planning:plan` Step 2's test-strategy guidance, and `planning:design`'s test-seam posture thread. Per the issue's framing, `testing:plan`'s table is the source of truth — the other two should cite it, not grow a competing take. Empirical note: the triage comment named `testing:write`/`README` as also carrying the table; verified they do **not** — the classification table exists only in `testing:plan`. So no table dedup was needed, only pointers from the two planning sites. All edits are therefore in the **planning** plugin. ## Fix Added one-line pointers (pointer-not-copy — no table restated) at the two planning sites that touch test-type/level reasoning, each placed alongside the existing `/tdd:principles` reference (which covers test-design WHY; `/testing:plan` covers which type per change — complementary, not competing): - `plugins/planning/skills/plan/SKILL.md` — Step 2 test-strategy bullet - `plugins/planning/skills/plan/context/plan-template.md` — Test Strategy section - `plugins/planning/skills/design/SKILL.md` — test-seam posture thread (seam altitude → test type) `planning` bumped 0.22.1 → 0.22.2 with a CHANGELOG entry. `testing:plan` (the SSOT) is unchanged; no other plugin's files were touched. ## Verification ``` $ bash scripts/validate-plugins.sh All plugin manifests and the catalog validated. (exit 0) $ bash scripts/check-changelog-parity.sh --check-bump origin/main Every plugin whose version changed vs origin/main has a '## [<version>]' CHANGELOG.md entry. (exit 0) $ bash scripts/check-changed-skills.sh origin/main CHECK-SKILL design: PASS — 0 errors, 2 warning(s) CHECK-SKILL plan: PASS — 0 errors, 2 warning(s) 3 skill(s) checked, 0 failed. (exit 0) # warnings pre-existing, not introduced here $ typos <changed files> --config _typos.toml (no findings) $ npx markdownlint-cli2 <changed .md files> Summary: 0 error(s) ``` Closes #264 ## Related - Origin: skill-name audit + interview (PR #256); contract doc `docs/topics/shadowed-skill-renames/PLAN.md` no longer in tree (ephemeral). - `/tdd:principles` (test-design WHY) and `/testing:plan` (test-type-per-change) remain the two complementary authorities the pointers reference. Co-Authored-By: Claude <noreply@anthropic.com> --------- Co-authored-by: Claude <noreply@anthropic.com>
kyle-sexton
added a commit
that referenced
this pull request
Jul 21, 2026
## Summary
`plan`'s Step 2 re-derived design inline despite the skill's own SSOT
rule at `plugins/planning/skills/plan/SKILL.md` ("`/planning:plan`
consumes design artifacts — do not re-derive design inline when
design-significant"). Two spots leaked into `/planning:design`
territory: the **design-default axes walk** (Emit-checklist paragraph)
and **build-technique selection** (Step 2). This restates both as
*consume/audit*, not *derive*, keeping `plan` a thin consumer.
## Fix
Doc-only, one skill file plus version/changelog.
- **Design-default axes walk → audit against the plan.** Reworded from
"also walk the design-default axes during Step 2" to "walks its
design-default checklist **against the plan** — confirming the plan
reflects the design artifact's resolved threads rather than re-deriving
the axes inline." This deliberately splits the six original items by
ownership rather than blanket-routing them:
- configurability / extension points / observability / testability →
design threads owned by `/planning:design`'s "Design defaults"
(`design/SKILL.md`) — audit that the plan carries their resolutions.
- type-collaboration shape → design's Phase 3 type modeling.
- **magic-literal hygiene stays plan's own review check** (it is a
code-review/quality concern, not design) — the pre-existing "against the
consuming project's own review conventions" clause already covers it.
- Aligns with `design-handoff/SKILL.md`'s existing handoff language:
"`/planning:plan` next walks its design-default checklist **against the
plan**" — the two skills now agree that this is an audit step.
- **Build-technique selection → route design/feasibility uncertainty
upstream.** The issue named this too. It does **not** violate the SSOT
rule the way the axes walk did (spike-vs-tracer-bullet is de-risking
*sequencing*, not re-deriving types/contracts/topology), so it was
**not** gutted to "audit-only." Instead the discriminating branch is
pointed upstream: a design / viability / raw-feasibility unknown
resolves via `/planning:design` (or a throwaway
`/prototype:pressure-test` spike), and plan **consumes that outcome**;
the *kept*-slice integration sequencing (tracer bullet / walking
skeleton) remains plan's own call. `Integration-first phase ordering`
(next paragraph) still coheres — it keys off "the kept branch."
## Verification
All repo validators run against the change, real output:
- **markdownlint** (`.markdownlint-cli2.jsonc`) on both changed docs:
`Summary: 0 error(s)`.
- **`scripts/check-changelog-parity.sh --check-bump origin/main`**:
"Every plugin whose version changed vs origin/main has a '##
[<version>]' CHANGELOG.md entry."
- **`scripts/validate-plugins.sh`**: "All plugin manifests and the
catalog validated."
- **`scripts/check-skill-portability.sh origin/main`**: "No unexcused
coupling tokens in 1 skill file(s)."
- **`scripts/check-silent-skips.sh`**: "No silent prerequisite skips
found."
Duplication removed — the axes SSOT is confirmed to live in `design`,
and `plan` no longer restates it as a derivation:
```
$ grep -rn "configurability" plugins/planning/skills
design/SKILL.md:135: ...design-default gaps (configurability, extension axes, observability, testability)...
design/SKILL.md:178: Design defaults ... configurability, extension points, observability, or testability...
design-handoff/SKILL.md:39: ...`/planning:plan` next walks its design-default checklist against the plan
plan/SKILL.md:35: ...design threads owned by `/planning:design`'s "Design defaults" ... audit that the plan carries their resolutions, don't re-open them here.
```
`plan/SKILL.md:35` now points at design's ownership instead of
enumerating the axes as its own derivation step.
Closes #265
## Related
- Issue #265 (docs(planning): fix plan (ex-architect) Step-2 design-axes
leak).
- Origin: skill-name audit + interview, contract at
`docs/topics/shadowed-skill-renames/PLAN.md` (PR #256).
- No open PR touches `plugins/planning/` at dispatch, so no
serialization / `do-not-merge` needed.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
https://claude.ai/code/session_01K1V3gkrfSf75isB8MiDy3o
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
kyle-sexton
added a commit
that referenced
this pull request
Jul 21, 2026
…n to implementation/verification (#789) ## Summary `codebase-health`'s `audit` skill ran its own Phases 4-7 (fix / verify / self-review / retro), which duplicate lanes other plugins already own end-to-end — `implementation:implement` for the fix cadence and `verification:confirm` for verification. This trims the audit's scope so it stays read-only through its Phase 3 report and delegates all remediation to those two skills, referenced as soft dependencies ("when installed") per this repo's cross-plugin convention. ## Fix - **Removed inline Phases 4-7** from `skills/audit/SKILL.md`; replaced with a `## Remediation (delegated to other plugins)` section that routes fixing to `/implementation:implement` and verification to `/verification:confirm` as soft refs, matching the established `(when the <plugin> plugin is installed)` pattern used elsewhere in the fleet. - **`--fix` repurposed, not removed** — it now hands the Phase 3 findings off to those lanes rather than fixing inline, preserving the naming-doctrine flag contract already codified in the skill. Bare `audit` still reports and STOPs at Phase 3. - **No content silently dropped.** The two codebase-health-specific outputs that lived only in the old phases are preserved in the read-only surface: - The `Config Drift → Missing Enforcement → Code Quality → Doc Drift` fix order already travels with Phase 3's "Fix priority" section (cites `reference/category-playbook.md`), so the fix lane receives it with the findings. - Post-audit **config-gap observations** worth persisting via `/codebase-health:setup` (previously only in Phase 7's retrospective — an inference-time-distinct, post-audit observation) folded into Phase 3 as a new required section §5. - **Graceful-degrade guarded** — the "Adapting to your environment" section now explicitly says remediation is delegated, NOT inlined: when the plugins are absent the findings table is the manual handoff, never a cue to re-inline a fix/verify/review loop (which would re-introduce the exact duplication this change removes). - **All parallel surfaces moved in lockstep** so the skill does not drift against itself: frontmatter `description`, `argument-hint` arg-parsing block, `## Read-only default`, `## Emit checklist`, the zero-findings + fix-gate blocks, `templates/checklist.md`, `README.md`, `plugin.json` description, and `evals.json` (stale "Phases 4-7 skipped" reference fixed in eval 2; new eval 7 asserts `--fix` delegates rather than inlining). - Version bump `0.6.2 → 0.7.0` (behavior/contract change) with a matching `CHANGELOG.md` entry. ## Verification Static skill-quality gate on the modified skill (`skill-quality:check`, v0.7.0), run against the plugin's own skills root: ``` INFO: description length 562/1536 chars INFO: all 4 base-ref trigger phrase(s) preserved INFO: SKILL.md 267/500 lines INFO: markdownlint clean WARN: SKILL.md is 267 lines (soft target 200 — consider pushing detail to progressive-disclosure spokes) WARN: no Gotchas surface (inline '## Gotchas' or context/gotchas.md) — confirm the skill has no observed failure history INFO: no metadata.category in frontmatter (optional — category not machine-readable) CHECK-SKILL audit: PASS — 0 errors, 2 warning(s) ``` PASS. Both WARNs are pre-existing and advisory (line count was already over the soft target before this change; the skill never shipped a Gotchas surface) — neither is a regression from this refactor, and the trigger-phrase-preservation check confirms no `description` trigger was dropped by the rewrite. `evals.json` validates against the bundled schema (`check-jsonschema`: `ok`). Independent review: a fresh reviewer (clean context, rationale withheld) audited the diff and flagged one broken internal anchor — the `## Remediation` heading's em-dash produced an ambiguous slug. Fixed by removing the em-dash from the heading (`Remediation (delegated to other plugins)`) and updating both link references to the unambiguous `#remediation-delegated-to-other-plugins` anchor; re-ran the gate (still PASS). Closes #262 ## Related - #262 — origin: skill-name audit + interview, contract at `docs/topics/shadowed-skill-renames/PLAN.md` (PR #256). - No other open PR touches `plugins/codebase-health/` (checked at creation), so no serialization / `do-not-merge` needed. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01K1V3gkrfSf75isB8MiDy3o --------- Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Codifies the marketplace naming convention in PLUGIN-PHILOSOPHY:
audit/scanread-only (mutation only behind explicit override),check= pass/fail gate,clean/tidy/fixmutate,setup,update.-deepisolation tier.dependencies(auto-install) or "if installed" guard — bare references are defects.shadowed-skill-renamestopic contract (interview output) that drives the follow-up rename PRs.Sources fetched this session, linked in Authoritative references (verified 2026-07-17). No external content copied.
🤖 Generated with Claude Code
https://claude.ai/code/session_01YVApnNGoKxYMJKNQx1QK8C
Related
No linked issue. Companion doctrine PR: #257. Drives the follow-up shadowed-skill rename PRs: #268, #269, #270, #271.