ADR-0001 — Cross-repo methodology home: a private docs repo, not a plugin

Status: Accepted — 2026-06-13 Context owner: Harol (solo operator)

Context

The Verbara ecosystem is 4 product repos (Verbara.Sdk, Verbara.Sdk.Pro, Verbara.Platform, Verbara.Platform.Web) + verbara-website, under a non-git workspace folder. Methodology artifacts that span repos have been accumulating with no versioned home: the 2026-06-13 ecosystem audit (lived only in auto-memory), the context-hygiene spec (a non-git workspace file that literally carried “this spec is unversioned”), plus a planned context-hygiene standard, shared .claude/ baseline, and verification hooks.

We ran a 4-lane investigation (Claude Code native mechanisms · industry practice · our measured fit · cost/risk + the ECC precedent) on whether to create a dedicated cross-repo methodology repo, and whether to distribute shared config as a Claude Code plugin/marketplace.

Decision

Create a private verbara-meta git repo as a docs-only home (Option K layout) for cross-repo methodology. No Claude Code plugin, no git submodules at this time. Per-repo .claude/ stays as-is (gitignored). Graduation path defined below.

Rationale (evidence)

The duplication a plugin would remove is tiny. Measured: cross-cutting constraints (AOT/Npgsql/test-naming/commit rules) appear ~once per repo and are already centralized in the global ~/.claude/CLAUDE.md. The one real duplicated block is the Option-K docs table (~33 lines across 3 repos), already owned by the docs-architecture skill. CI workflows are legitimately tailored per repo (public vs private/GHAS, C# vs JS/TS, private-feed auth), not copy-paste. Only one agent is shared by 2 repos — and it has already drifted into two forks; several other agents reference Dapper (banned by ADR-0022) and are stale.
A plugin structurally cannot carry the high-value assets. Per the official docs, a plugin’s settings.json supports only the agent/subagentStatusLine keys; plugins distribute skills/agents/hooks/MCP but not CLAUDE.md, rules, or permissions. So a plugin would not eliminate the manual sync it promises (the same gap the ECC community flags).
Scale. Genuinely solo (only Harol + dependabot[bot] commit across all repos). Internal-platform economics put the break-even at ~10–20 engineers; we are 1.
The real, concrete pain is docs homelessness — solved by one git init.
Industry & native mechanisms agree on the shape: lightweight central home now (paved-road / Minimum Viable Platform); plugins are the right eventual mechanism for shared .claude/ config but premature here; submodules to be avoided.

Consequences

Cross-repo specs, ADRs, audits, the context-hygiene standard, and runbooks get history / branches / PR / off-machine backup.
The context-hygiene spec (P1) is relocated here and is now versioned.
One more repo to keep alive — acceptable; it is docs-only with no build/release.

Graduation path (revisit triggers)

Lift specific components into a Claude Code plugin + private marketplace only when all hold: (1) a 2nd human contributor joins or repo count grows past ~4–5; (2) 3+ genuinely identical agents/skills/hooks must move in lockstep (today: one drifted agent + one skill); (3) the manual copy cost is actually felt. Reversal cost is near-zero (cp -r .claude/agents <plugin>/), so deferring forecloses nothing.

Alternatives considered

git init the workspace root — zero migration but nests the product repos (ignored); rejected for cleanliness in favor of a sibling repo.
Fold docs into a product repo (e.g. Verbara.Platform/docs) — Platform is public (internal-runbook disclosure) and mixes meta with product. Rejected.
Plugin + marketplace now — over-engineering at solo scale; can’t carry CLAUDE.md/permissions. Deferred (see Graduation).
Git submodule/subtree — CI-breakage and merge pain; universally discouraged at this scale. Rejected.
~/.claude user layer only — already exists for personal prefs but is not versioned/discoverable/shareable. Insufficient as the methodology home.