/init-workspace

description: Set up a workspace-level CLAUDE.md (Bitwarden domain context) for the folder containing all locally-cloned Bitwarden repos
allowed-tools: Read, Write, Edit, Bash(find:*), Bash(wc:*), Bash(tr:*), Bash(dirname:*), Bash(mkdir:*), Bash(diff:*), Bash(cp:*), Bash(date:*), Bash(rm:*), Glob

Walk the user through a guided Q&A to assemble a workspace-level CLAUDE.md at `<workspace-root>/.claude/CLAUDE.md`, where `<workspace-root>` is the directory the user keeps all their cloned Bitwarden repos in. Claude Code automatically loads this file in any subdirectory of that root, so it's the right home for cross-repo Bitwarden domain context (zero-knowledge invariant, P01–P06, vocabulary, operating defaults).

This represents one engineer's opinion. Modules are opt-in; the user picks which to include and is free to edit afterward.

Steps

1. **Detect workspace root.** Starting from `cwd`, walk up the directory tree. For each ancestor, count how many of its immediate subdirectories contain a `.git` entry (file or directory). If any ancestor has **2 or more** such subdirectories, propose that ancestor as the workspace root.

Use a Bash one-liner like:

   dir="$PWD"
   while [ "$dir" != "/" ]; do
     if [ "$dir" = "$HOME" ]; then break; fi
     count=$(find "$dir" -mindepth 2 -maxdepth 2 -name .git 2>/dev/null | wc -l | tr -d ' ')
     if [ "$count" -ge 2 ]; then echo "$dir"; break; fi
     dir=$(dirname "$dir")
   done

The `$HOME` guard prevents the loop from proposing `~` as the workspace root for engineers who keep multiple git repos directly under their home directory (dotfiles, config repos, personal projects) — `~/.claude/CLAUDE.md` is reserved for the user-scope file managed by `/bitwarden-init:init-user`.

• If the script prints a path, use `AskUserQuestion` to ask: "Detected workspace root: `<path>` (contains `<count>` git repos). Use this?" with options **Yes, use this**, **No, let me type a different path**, **Cancel**.
• If the script prints nothing, skip the proposal and go straight to the "type a path" branch.

When the user picks "type a different path", ask them for an absolute path via `AskUserQuestion` with options pre-filled as common candidates (e.g. `~/Source/bw`, `~/dev/bitwarden`, `~/code/bw`) — the AskUserQuestion "Other" affordance lets them type anything. Validate that the path exists. If not, re-ask.

2. **Confirm target path.** The actual file path is `<workspace-root>/.claude/CLAUDE.md`. Display this resolved path and ask `AskUserQuestion`: **Proceed writing to `<full-path>`?** with **Yes** / **Cancel**.

3. **Detect existing file.** Read the target file. If it exists, ask:

• **Merge** (add modules that aren't already present)
• **Replace** (back up and overwrite)
• **Abort**

Default: Abort. If it doesn't exist, proceed.

4. **Module selection.** Use `AskUserQuestion` with `multiSelect: true`. Options (each with the listed one-line description):

| Module file | One-line summary | | -------------------------------- | -------------------------------------------------------- | | `overview.md` | Bitwarden's mission and what this workspace file is for | | `zero-knowledge-invariant.md` | The foundational client-side encryption invariant | | `cryptography-choices.md` | AES-CBC + HMAC-SHA-256, RSA-OAEP, EK-1 | | `security-principles.md` | P01–P06 verbatim | | `core-vocabulary.md` | Vault Data, Protected Data, Secure/Trusted Channel, etc. | | `agent-planning-requirements.md` | Plans and subagents must use the vocabulary | | `operating-defaults.md` | Worktrees + plan mode for non-trivial work | | `sources-of-truth.md` | Reference links for future refinement |

5. **Render preview.** For each selected module:

• Read `${CLAUDE_PLUGIN_ROOT}/templates/workspace/<slug>.md`.
• In **Merge** mode, skip modules whose top-level `## Heading` is already present in the existing file.

Concatenate in the order shown above, separated by single blank lines. Prepend:

   # Bitwarden

   <!-- Generated by bitwarden-init v{VERSION} on {YYYY-MM-DD}.
        Workspace-level context for every Bitwarden repo cloned under this folder.
        This is a starting point assembled from opt-in modules — not a Bitwarden standard.
        Edit freely. -->

Read the current plugin version from `${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json` to substitute `{VERSION}`.

6. **Diff + confirm.**

• If the target file exists, write the rendered content to a temp file and run `diff -u <target> <temp>` via `Bash`. Display the diff.
• If the target does not yet exist, display the full rendered content.

Use `AskUserQuestion` with **Apply**, **Show diff again**, **Cancel**.

7. **Backup, then write.**

• Ensure `<workspace-root>/.claude/` exists (`mkdir -p`).
• **If the target file already exists** (Merge or Replace path from step 3): copy it to `<target>.bak-$(date -u +%Y%m%dT%H%M%SZ)`, then use `Edit` to update the target with the full rendered content. Fall back to `Write` only if `Edit`'s old-string match fails — which shouldn't happen since step 3 already Read the file.
• **If the target file is new** (step 3 found nothing to read): use `Write` to create it. `Edit` is not viable here because Edit requires a previously-Read file.
• Clean up the temp preview file.

8. **Summary.** Report:

• The target path written.
• Which modules were included.
• The backup file path (if any).
• A reminder that this file applies to **every** Bitwarden repo cloned under `<workspace-root>` — so any rule placed here will be honored across all of them on every launch.

Notes

• **Never write without an explicit Apply confirmation.** This file af