From bd3340304d49fd7fced97dab697e04ebc4e405ac Mon Sep 17 00:00:00 2001 From: tractorjuice <129532814+tractorjuice@users.noreply.github.com> Date: Fri, 7 Aug 2026 14:16:11 +0000 Subject: [PATCH] docs(contributing): document the overlay registration points that fail silently A new plugins/arckit-/ directory is not discovered automatically, and two of the hardcoded plugin lists report success while producing nothing: converter.py's PLUGIN_SOURCES (which cost arckit-uk-finance four releases of missing extension output) and the two marketplace manifests. Raised by @umag on #739, who found both by running the tooling rather than by reading this file. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01VKbHCujejpxkgvh47BndDE --- CONTRIBUTING.md | 43 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 725a2fcbc..8945871d8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -236,6 +236,49 @@ Reviewers check that the new code doesn't collide with existing codes — `scrip If the new code is the **first** of its regime, also register the regime in the `REGIMES` array and `REGIME_LABELS` object at the bottom of `doc-types.mjs`. Order convention: officially-maintained first, then community alphabetical. +## Registering a new community overlay + +A new `plugins/arckit-/` directory is **not** discovered automatically. Several scripts carry hardcoded plugin lists, and the two below fail **silently** — they report success while producing nothing for your overlay. This is not hypothetical: `arckit-uk-finance` shipped its four commands in **zero** non-Claude extensions from v5.3.0 through v5.6.0 because of the first one. + +### 1. `scripts/converter.py` — `PLUGIN_SOURCES` + +Add `"plugins/arckit-"` to the list (core `arckit-claude` stays last). Without it the converter generates **no** files for your overlay in any of the seven non-Claude extensions, and still exits 0 with a success summary — nothing looks wrong. + +Two plugins are excluded deliberately and must stay out: `arckit-fde` (Claude-only tooling) and `arckit-uk-gcloud` (proprietary — must not leak into the MIT extension repos). + +### 2. Both marketplace manifests + +There are **two**, they use different source shapes, and both need an entry: + +| Manifest | Source shape | Consumed by | +|---|---|---| +| `.claude-plugin/marketplace.json` | flat — `./plugins/arckit-nl` | this repo | +| `plugins/arckit-claude/.claude-plugin/marketplace.json` | nested — `./plugins/nl` | the published `tractorjuice/arckit-claude` marketplace | + +`tests/plugin/test_release_process.py` compares both against `EXPECTED_CLAUDE_MARKETPLACE_SOURCES`, so updating one manifest but not the other (or not the test) fails CI. Omitting all three passes silently. + +### 3. The rest of the same registration + +These belong to the same act and are best done together: + +- `scripts/sync-claude-plugin-layout.py` (`PLUGIN_LAYOUT`) and `scripts/push-extensions.sh` (`CLAUDE_PLUGIN_LAYOUT`) — both map `plugins/arckit-` to its nested publish path. Missing here, the overlay never reaches the published marketplace repo. +- `tests/extension_helpers.py`, `tests/codex/test_codex_extension.py`, `tests/paperclip/test_commands_json.py` (`PLUGIN_COMMAND_DIRS`) and `tests/plugin/test_template_consistency.py` (`PLUGIN_SOURCES`). +- `scripts/sync-shared-assets.py` (`SYNC_EXEMPT_PLUGINS`) — every governance overlay must carry the shared `templates/_partials` and `references` assets byte-identical. Only add your plugin to the exempt set if it is tooling rather than governance. + +The test lists are what makes step 1 loud instead of silent: `.github/workflows/python-tests.yml` regenerates the extensions and then runs the full suite, so an overlay present in `PLUGIN_COMMAND_DIRS` but absent from `PLUGIN_SOURCES` fails CI. Adding them matters more than it looks. + +### Verify before opening the PR + +```bash +python scripts/converter.py +find extensions -path '*-*' -type f | wc -l # expect non-zero +python scripts/sync-shared-assets.py --check +python scripts/sync-claude-plugin-layout.py --check +python -m pytest -q +``` + +See also [Adding a new doc-type code](#adding-a-new-doc-type-code-v500) above — a new overlay is almost always also a new regime. + ## Adding a bundled MCP server When a new command requires an MCP server that does not already ship with ArcKit, follow this checklist: