Migrate a repo onto the org brain
How to take an existing bewith-dev repo and put it on the platform: a per-repo CLAUDE.md, the shared CI gate, legacy .cursor rules retired (their genuinely-repo-specific content rewritten into CLAUDE.md), and a check that the plugin + git hooks actually load.
Per-developer vs per-repo. The plugin (agents/skills/commands/hooks) and the git hooks are wired once per developer โ see install-bewith-plugin.md. This runbook is the per-repo half: the files and cleanups a specific repo needs. Do the per-developer install first.
Automatable. The claude-init skill runs these steps in an isolated worktree and prepares a reviewable branch. It never commits to master and never merges โ you review and merge. Run the steps by hand or let the skill do them; the procedure is the same.
What the platform reaches a repo throughโ
| Channel | Wired by | Scope |
|---|---|---|
| Plugin (agents, skills, commands, plugin hooks) | /plugin install bewith@bewith-dev | per-developer, all repos |
| Git hooks (pre-commit / commit-msg / pre-push) | git config --global core.hooksPath โฆ | per-developer, all repos |
CLAUDE.md | this runbook (install-to-consumer.sh) | per-repo |
| CI (the reusable lint/typecheck/test gate) | this runbook (the ci.yml caller) | per-repo |
| Capability status line | bewith platform install (user scope) | per-developer, all repos |
| Permission allowlist (opt-in) | bewith platform permissions (user scope) | per-developer, all repos |
The permission allowlist is opt-in โ applied (with a diff + confirmation) by bewith platform permissions, not by install; once applied it is machine-wide (user scope), and Claude Code merges allow-rules across scopes, so it covers every repo without a per-repo copy. The plugin + git hooks are name-shadowed globally too โ generic standards come from the plugin, so a repo's CLAUDE.md only carries what's specific to it.
Procedureโ
1. Scaffold the per-repo filesโ
From the consumer repo's root, run the idempotent installer (it creates only what's missing โ CLAUDE.md, .github/copilot-instructions.md โ and never commits; the permission allowlist is opt-in machine-wide via bewith platform permissions, not a per-repo file):
bash ~/.claude/plugins/cache/bewith/scripts/install-to-consumer.sh
2. Fill in CLAUDE.mdโ
Replace every <โฆ> placeholder in the scaffolded CLAUDE.md: what the repo does, its stack, repo-specific architecture rules, forbidden actions, deploy notes, domain glossary. Keep it under ~15 KB. Only put what's specific to this repo โ the cross-repo standards already load via the plugin. This is also where retired .cursor content lands (step 4).
3. Add the CI callerโ
Copy the caller template to .github/workflows/ci.yml:
cp ~/.claude/plugins/cache/bewith/templates/consumer-repo/.github/workflows/ci.yml .github/workflows/ci.yml
Set package-manager to the repo's PM and drop run-tests: false only if the repo truly has no suite yet. Then make CI / ci a required check in branch protection (org-settings step). Full design + the adoption sweep: uniform-ci.md.
Dependency: the caller pins
@ci-v1of the shared reusable (bewith-dev/bewith-docs, at.github/workflows/reusable-ci.yml). Cross-repo use requires bewith-docs Actions Access = "Accessible from repositories in the organization"; if theCI / cicheck errors, verify that org setting or temporarily pin a commit SHA.
4. Retire legacy local rulesโ
Old repos carry .cursorrules, .cursor/rules/*.mdc, or ad-hoc RULES.md-style files. These predate the platform and now conflict or duplicate what the plugin ships. Retire them โ archive first, never delete blind:
- Detect. Look for
.cursorrules,.cursor/,.cursor/rules/,.windsurfrules, and ad-hoc rule docs. - Archive. Move them to
.cursor-archive/(ordocs/legacy-rules/) so the history is recoverable, then remove the live copies. Commit the archive in the same change so nothing is lost. - Triage each rule against the platform:
- Generic (a coding convention, workflow rule, gotcha that applies broadly) โ drop it. It's already covered by the plugin via name-shadowing; re-stating it locally just risks drift. If it's a good generic rule the platform is missing, propose it with
/share-ruleinstead of keeping it local. - Genuinely repo-specific (a boundary, a forbidden call, a deploy quirk, a domain invariant) โ rewrite it into
CLAUDE.mdfollowing Anthropic's CLAUDE.md guidance: concise, imperative, repo-specific only โ not a paraphrase of generic standards. Put it in the matching section (architecture rules ยง3, forbidden actions ยง5, deploy ยง7, โฆ).
- Generic (a coding convention, workflow rule, gotcha that applies broadly) โ drop it. It's already covered by the plugin via name-shadowing; re-stating it locally just risks drift. If it's a good generic rule the platform is missing, propose it with
- Point Cursor at
CLAUDE.md. A one-line.cursorrules(or.cursor/rules/) that says "see CLAUDE.md" keeps Cursor users on the same source without re-introducing drift.
5. Verify the platform loadsโ
- Plugin: in a Claude Code session in the repo,
/pluginโ Installed tab showsbewith@bewith-dev;@code-reviewerresolves;/share-ruleis in autocomplete. - Git hooks:
git config --get core.hooksPathpoints at the plugin'sgit-hooks/; a test commit on a non-conventional branch name is rejected bybranch-name-check. - CI: open the onboarding PR and confirm the
CI / cicheck appears and runs (once the reusable is tagged โ step 3). - CLAUDE.md: a fresh session in the repo loads it (it's read automatically).
6. Commit + open the onboarding PRโ
Stage the scaffolded files, the filled CLAUDE.md, the CI caller, and the .cursor archive/removal as one reviewable onboarding commit, push a chore/onboard-bewith-platform branch, and open a PR. Do not merge to master automatically โ a human reviews the rewritten CLAUDE.md and the rule retirements.
Idempotency + rollbackโ
- Re-running is safe:
install-to-consumer.shskips existing files; the CI caller copy is a no-op if present; rule archiving checks before moving. - Rollback is a branch revert โ nothing here is destructive, and the
.cursor-archive/keeps the old rules.
Per-repo notesโ
- PHP repos (
superco-consumer,superco-management) getCLAUDE.md+ git hooks but not the TS/JS CI caller โ they need a separate PHPCS/PHPStan track (seeuniform-ci.mdscope note). They are deprecation targets โ invest minimally. - Repos with no CI today (
bewith-consumer-frontend,migrations-tool, โฆ) โ the CI caller is the bigger win; prioritize step 3 there. - Frontend repos โ confirm the design-system anchor (COMPONENTS.md) is referenced in
CLAUDE.mdยง3 if the repo builds UI.
Anthropic Claude convention alignmentโ
Each repo must match Anthropic's canonical Claude Code layout, not an ad-hoc one:
CLAUDE.mdat the repo root โ read automatically every session; under ~15 KB; repo-specific only..claude/at the root for any repo-local overrides (settings.json, repo-scopedcommands/) โ generic agents/skills/commands come from the plugin, not copied here..github/copilot-instructions.mdpointing atCLAUDE.mdso Copilot users share the same source.- Legacy
.cursor*retired (step 4) โ one source of truth per rule.
Structure + naming follow the templates/consumer-repo/ scaffold. How these repo rules layer against the org platform and a developer's personal settings is governed by rule-precedence.md.
Rollout backlog (all repos)โ
Onboard in impact order. Tiers, from the live org scan:
| Tier | Repos | Onboarding |
|---|---|---|
| 1 โ active TS/JS apps (most AI dev) | backend-services, management-webapp, organization-dashboard, support-tool-frontend, bewith-consumer-frontend, design-system, facility-rentals, with-calendar | full procedure incl. the CI caller |
| 2 โ mobile (Flutter) | leaders-app, consumer-mobile | CLAUDE.md + hooks; CI is a Dart track, not the TS reusable |
| 3 โ TS/JS services + infra | sqs-consumer, migrations-tool, cognito-lambdas, loki-cloudwatch-forwarder, auth-client, Kubernetes-deployments, cdk-infra, infrastructure | full procedure where a test suite exists |
| 4 โ Python services | with-agents-platform, crm-integration, assistant-ai | CLAUDE.md + hooks; separate lint/test track |
| 5 โ deprecation targets (PHP/legacy) | superco-consumer, superco-management(-17), consumer-php-base | CLAUDE.md + git hooks only; minimal investment, no TS CI |
| Platform / meta | bewith-docs (self-hosts the platform), .github (owns the org reusables), eslint-plugin, sandbox, nestjs-docker-base* images | special-cased; cursor-rules is being retired (folds into the plugin) |
Per repo the task is the Procedure above. When execution starts, /breakdown this backlog into one GitHub issue per repo (or per tier) carrying the onboarding checklist.
See alsoโ
install-bewith-plugin.mdโ the per-developer prerequisite.rule-precedence.mdโ how platform / repo / personal rules layer.uniform-ci.mdโ the CI gate this onboarding wires.consumption-model.mdโ how consumer repos federate with the platform.claude-initโ the skill that automates this runbook.