claude-init

Automates the repo-migration runbook: take an existing bewith-dev repo and put it on the org brain. Works in an isolated worktree of the target repo so it never disturbs the developer's checkout, and it prepares a reviewable branch/PR — it does not commit to master and does not merge. The rewritten CLAUDE.md and the retired rules need a human read.

When to invoke

/claude-init [path-or-name] — defaults to the current repo. Auto-offer when a developer says "let's get repo X on the platform" / "initialize X" / "onboard X". The platform also offers it automatically — a SessionStart hook detects the first time you open an un-initialized bewith-dev repo and suggests it.

Prerequisites (per-developer, done once)

The plugin + git hooks are wired per-developer, not per-repo — see install-bewith-plugin.md. If /plugin doesn't list bewith@bewith-dev, stop and do that first; this skill only does the per-repo half.

Steps

1. Resolve + pre-flight the target repo

TARGET="$(git -C "${1:-.}" rev-parse --show-toplevel)"   # the repo to onboard
REPO="$(basename "$TARGET")"

Refuse and report if: not a git repo; not a bewith-dev repo (check the origin remote); or already onboarded (a CLAUDE.md that isn't the unfilled template and a .github/workflows/ci.yml already calling the reusable). For an already-onboarded repo, offer a re-sync (re-run idempotently to pick up template/CI changes) instead.

2. Create an isolated worktree of the target repo

Never operate on the developer's working tree — concurrent sessions may be in it.

git -C "$TARGET" fetch origin --quiet
BRANCH="chore/onboard-bewith-platform"
WORKTREE="$(mktemp -d -t bewith-onboard.XXXXXXXX)"
git -C "$TARGET" worktree add -b "$BRANCH" "$WORKTREE" origin/HEAD

If $BRANCH already exists locally or on the remote, stop — an onboarding is already in flight.

Worktree gotcha (only if you run node here): a fresh worktree has no node_modules, so any node/validator call hits ERR_MODULE_NOT_FOUND. This skill only runs bash + git, so it's not affected. If you add a node step, symlink first: ln -s "$TARGET/node_modules" "$WORKTREE/node_modules".

3. Scaffold the per-repo files

First resolve the CURRENT plugin install. Under always-latest the cache dir is SHA-versioned, so never hardcode a path — read it from Claude Code's installed-plugins manifest (the same source the CLI's resolver uses):

PLATFORM_DIR="$(jq -r '.plugins["bewith@bewith-dev"] | (map(select(.scope=="user"))[0] // .[0]).installPath' ~/.claude/plugins/installed_plugins.json 2>/dev/null)"
[ -n "$PLATFORM_DIR" ] && [ -d "$PLATFORM_DIR" ] || { echo "✗ bewith plugin not installed — see install-bewith-plugin.md"; exit 1; }

( cd "$WORKTREE" && bash "$PLATFORM_DIR/scripts/install-to-consumer.sh" )

Creates CLAUDE.md and .github/copilot-instructions.md (only if absent). It's idempotent and never commits. It does not scaffold a per-repo .claude/settings.json — the permission allowlist + status line come machine-wide from bewith platform install (Claude Code merges allow-rules across scopes), so a per-repo copy would just be a second source to sync.

One-command alternative: ( cd "$WORKTREE" && bewith project infra --fix ) does this scaffold and wires the git hooks, resolving the plugin dir for you — use it if the bewith CLI is installed. It does not add the CI caller (step 4 below) — still do that.

4. Add the CI caller

mkdir -p "$WORKTREE/.github/workflows"
cp "$PLATFORM_DIR/templates/consumer-repo/.github/workflows/ci.yml" "$WORKTREE/.github/workflows/ci.yml"

Set package-manager to the repo's PM (read its package.json / lockfile). The caller pins @ci-v1 of bewith-dev/bewith-docs (the reusable lives in bewith-docs at .github/workflows/reusable-ci.yml, tagged ci-v1). Flag to the developer that cross-repo use requires bewith-docs Actions Access = "Accessible from repositories in the organization"; if the CI / ci check errors, verify that org setting or pin a commit SHA meanwhile.

4b. Seed the GitHub Issue label vocabulary

/breakdown runs gh issue create --label effort:…,urgency:…,domain:…, and gh issue create hard-fails if any of those labels is missing — so a repo with no labels can't be broken down. Seed them once (idempotent; these are GitHub-side, not files, so this runs against the remote, not the worktree):

OWNER_REPO="$(git -C "$TARGET" remote get-url origin | sed -E 's#.*github.com[:/]##; s/\.git$//')"
bash "$PLATFORM_DIR/scripts/sync-issue-labels.sh" "$OWNER_REPO"

Report the ✓ count. If it fails on auth, the developer needs gh auth login (see the contributor quickstart) — note it and continue; labels can be re-synced later by re-running the script.

5. Fill in CLAUDE.md (repo-specific only)

Read the repo to fill the <…> placeholders: purpose, stack (from package.json/framework), repo-specific architecture rules, forbidden actions, deploy notes, domain glossary. Keep it under ~15 KB and repo-specific only — do not paraphrase generic standards (those come from the plugin).

6. Retire legacy local rules

ls -la "$WORKTREE"/.cursorrules "$WORKTREE"/.cursor "$WORKTREE"/.windsurfrules 2>/dev/null

For each rule found:

Archive to $WORKTREE/.cursor-archive/ (move, don't delete) so it's recoverable in history.
Triage each rule:
- Generic → drop it (the plugin covers it via name-shadowing). If it's a good rule the platform lacks, note it for /share-rule — don't keep it local.
- Genuinely repo-specific → rewrite into the right CLAUDE.md section (architecture §3, forbidden §5, deploy §7), concise + imperative.
Optionally leave a one-line .cursorrules pointing at CLAUDE.md so Cursor users stay on the same source.

Present the generic/repo-specific split to the developer before finalizing — this is the judgment-heavy step.

7. Verify the platform loads

Report each as ✓/✗ (don't fabricate):

git -C "$WORKTREE" config --get core.hooksPath resolves to the plugin's git-hooks/.
CLAUDE.md exists and has no remaining <…> placeholders.
.github/workflows/ci.yml references reusable-ci.yml.
Plugin reachability is a session-level check (/plugin) — note it for the developer to confirm.

8. Present the diff — do NOT merge

Show git -C "$WORKTREE" status + a summary of: files scaffolded, CLAUDE.md sections filled, rules archived, rules rewritten, rules dropped. Then ask:

"Commit this as a chore/onboard-bewith-platform branch and open a PR for review?"

On yes: commit (one onboarding commit), push the branch, gh pr create against the target repo's default branch — never --admin, never auto-merge. On no: leave the worktree for the developer to inspect, and tell them the path.

9. Clean up

git -C "$TARGET" worktree remove "$WORKTREE" --force   # only after the branch is pushed or the developer is done

Use a trap so the worktree is removed on failure paths too — but never before a pushed branch is safe.

What this skill does NOT do

It does not install the plugin or git hooks (per-developer, done once — see prerequisites).
It does not merge to master or use --admin. Onboarding a real repo is human-reviewed.
It does not delete legacy rules without archiving them first.
It does not invent CLAUDE.md content — unknown placeholders are flagged for the developer, not guessed.

When to invoke​

Prerequisites (per-developer, done once)​

Steps​

1. Resolve + pre-flight the target repo​

2. Create an isolated worktree of the target repo​

3. Scaffold the per-repo files​

4. Add the CI caller​

4b. Seed the GitHub Issue label vocabulary​

5. Fill in CLAUDE.md (repo-specific only)​

6. Retire legacy local rules​

7. Verify the platform loads​

8. Present the diff — do NOT merge​

9. Clean up​

What this skill does NOT do​

See also​