[tom2drum]

Description

Relates to #3882. Prototype, not to be merged. It exists to prove or discard sharing agent skills, rules and developer tools across frontend repositories through a read-only git submodule, before a full migration is planned.

The shared repository is blockscout/frontend-devkit, mounted at devkit/. On this branch:

• Three skills (check-github-cli, slack-file, update-glossary) and two rules (adr, docs) are replaced by symlinks into the submodule; the doc-links tool is deleted here and run from devkit/tools/doc-links/, with this repository's exclusions in devkit.config.json.
• The submodule is kept in sync by the husky post-checkout, post-merge and post-rewrite hooks and the prepare script, and initialised for agent-made worktrees by .claude/hooks/devkit-init.sh (session start, subagent start, EnterWorktree).
• It is read-only here: a Claude Code deny rule on devkit/** and a pre-commit check that refuses a commit while the submodule has local changes.
• tsconfig, Vitest, ESLint and cspell each exclude devkit/ with one line; the Checks workflow checks out submodules in the lint job.
• tools/devkit-probes/ holds the scripts behind the results below, so they can be rerun.

Environment variables

None

Minimum API version

None

Breaking or incompatible changes

None

Additional information

Results so far. A failed check in the first group discards the approach.

Check	Result
Shared skills and rules load in an initialised checkout	Pass
First session of a fresh claude --worktree	Pass, through the session-start hook
Subagent with worktree isolation	Pass after adding a subagent-start hook; fails without it
EnterWorktree mid-session	Pass, through a post-tool hook
Detached git worktree add followed by a headless session	Pass
Pointer follows switch, merge, fast-forward, rebase (fresh clone, real hooks)	Pass, working tree clean
Fresh clone: pnpm install initialises the submodule; without install, the first agent session does	Pass
tsc, ESLint, cspell, Vitest with the submodule present	Pass, one exclude line each
doc-links run from the submodule, here and in a second repository on another TypeScript version	Pass
A shared file naming a file the consumer lacks	Reported by the consumer's doc-links run
Local override of a shared rule in a second repository	Pass
Read-only: agent edits, also through the symlink path, and shell writes	Blocked
Read-only: commit with a modified or untracked file in the submodule	Blocked by pre-commit
Change loop: branch commit tried here, pull request in the shared repository, squash merge, pointer moved onto its main branch	Pass
CI: lint job with submodules: true and a check that the pointer is on the shared repository's main branch; other jobs unchanged	Pass
Cursor: skills and a rule in an initialised checkout	Pass
Cursor-created worktree, first session	Pass after adding .cursor/worktrees.json; shared skills missing without it
Slack orchestrator's worktrees: its allow rules against the linked skill script	Pass, no change needed there
Cloud session on this branch: submodule initialised, shared skills in the first turn, shared rule on a matching read	Pass

Known costs, accepted for now:

• Checking out a commit that predates the submodule leaves devkit/ behind as an untracked directory.
• git reset --hard across a pointer change leaves the submodule modified until git submodule update, or needs --recurse-submodules. A guard that only lets the pointer change through a dedicated script is planned for the full implementation.
• git worktree remove needs --force once the submodule is initialised.

Not tested: Dependabot updates of the pointer, and a shared tool with runtime dependencies of its own.

🤖 Generated with Claude Code