/arckit:customize cannot reach overlay plugin templates — 63% of templates invisible, and 'all' reports success on a partial copy

[tractorjuice]

Summary

/arckit:customize can only see templates in the core arckit plugin. It globs ${CLAUDE_PLUGIN_ROOT}/templates/, which resolves to the plugin the command itself ships in, so every overlay plugin's templates are invisible to it — 110 of the 175 templates in the repo, or 63%.

Worse than being unable to copy them: /arckit:customize all reports success having copied only the core set, and list presents a core-only list as if it were the complete inventory. A user asking for all templates and getting 65 of 175 has no signal that anything is missing.

Surfaced while answering #706, where a user needed to customise codebase-audit-template.md. It ships in arckit-repo, so /arckit:customize codebase-audit cannot find it and the user has to be told to copy the file by hand.

Reachable vs unreachable

Plugin	Templates	Reachable by /arckit:customize
arckit-claude (core)	65	yes
arckit-ca	12	no
arckit-fr	12	no
arckit-uae	12	no
arckit-au	10	no
arckit-uk-nhs	10	no
arckit-us	10	no
arckit-togaf-adm	9	no
arckit-uk-finance	8	no
arckit-uk-gcloud	8	no
arckit-eu	7	no
arckit-agent-architecture	6	no
arckit-at	3	no
arckit-au-energy	2	no
arckit-repo	1	no

customize.md never mentions overlays, community plugins, or other plugin roots anywhere in its 130-odd lines, so nothing warns the user or the model that the scope is partial.

Secondary: the hardcoded table has drifted both ways

customize.md carries a 46-row table mapping template names to commands. Comparing it against the 65 core templates actually on disk:

• 20 core templates are absent from the table: competitors, conformance-assessment, data-source-profile, dfd, framework-overview, gcp-research, glossary, gov-code-search, gov-landscape, gov-reuse, grants, maturity-model, presentation, tech-note, tenders, vendor-profile, wardley-climate, wardley-doctrine, wardley-gameplay, wardley-value-chain
• one row names a template that does not exist: uk-gov-tcop. The real file is tcop-review-template.md, so /arckit:customize uk-gov-tcop fails the "source template does not exist" branch while the docs say it is valid.

The list action globs rather than reading the table, so the table is supplementary rather than load-bearing. It is still a documented wrong answer.

Proposal

Two parts, and the first is worth doing on its own even if the second is deferred.

1. Stop reporting a partial answer as complete. list and all should state their scope: which plugin's templates they covered, that overlay templates are not included, and how to copy one manually. This is a small edit to customize.md and removes the silent-wrong-answer failure mode. Fix the stale table at the same time.

2. Make overlay templates reachable. Harder than it looks, so flagging the constraint rather than proposing a single design. The install layout is ~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/, and the path to an overlay template differs depending on how it was installed — verified on disk:

cache/arckit-claude/arckit-repo/6.7.5/templates/codebase-audit-template.md        # standalone
cache/arckit-claude/arckit/6.7.5/plugins/repo/templates/codebase-audit-template.md # bundled inside core

So walking up from ${CLAUDE_PLUGIN_ROOT} needs to handle two layouts and a version segment. Options:

• Glob both known layouts relative to the resolved plugin root, taking the highest version. Cheapest, but couples the command to the cache layout, which is a Claude Code implementation detail that could change.
• Accept an explicit source, e.g. /arckit:customize codebase-audit --from arckit-repo, and resolve via the same two-layout glob. Same coupling, but only on an opt-in path.
• Give each overlay its own thin customize command, so ${CLAUDE_PLUGIN_ROOT} resolves correctly per plugin. No coupling, but 14 near-duplicate commands and a worse UX (/arckit-uae:customize vs /arckit:customize).

Preference is the second: it keeps the common case unchanged, makes the capability explicit, and confines the layout assumption to one code path that fails visibly rather than silently.

3. Optional CI guard. A check that every *-template.md on disk appears in customize.md's table and vice versa would have caught both halves of the drift above. This fits the existing guard pattern (check-doc-type-registry.py, check-multi-instance-parity.py, check-guide-parity.py), and the same script could assert the table's command references resolve to real commands.

Acceptance

• /arckit:customize list and all state their scope explicitly and never present a core-only result as the full inventory
• Overlay templates are either copyable through the command or the command tells the user exactly how to copy them, with a path that works for both install layouts
• The customize.md table matches the templates on disk, uk-gov-tcop corrected to tcop-review
• Tests and lint green

Context

Found while answering #706. The manual workaround given to that user, which works today on 6.7.5:

mkdir -p .arckit/templates-custom
find ~/.claude/plugins/cache -path '*/templates/codebase-audit-template.md' \
  | sort -V | tail -1 \
  | xargs -I{} cp {} .arckit/templates-custom/codebase-audit-template.md

Note also that a project-local copy of a command loses ${CLAUDE_PLUGIN_ROOT} substitution entirely, so repo-audit's third-priority template fallback goes unresolved in that scenario. Same root cause, different surface.