---

name: ws-store-setup description: > Analyze the project's gitignored files and set up the ws store with appropriate tracking strategies. Guides initial store configuration. disable-model-invocation: true allowed-tools: Bash, Read, Glob, Grep

ws store setup

Guide the user through setting up the ws shared store for their repository. The store ensures that gitignored files (like .env, editor configs, local settings) are automatically shared across worktrees.

Step 1: Analyze .gitignore

Read the project's .gitignore file(s) to identify candidates for the store:

# Read gitignore at repo root (worktree level)
cat .gitignore 2>/dev/null

# Also check for nested gitignore files
find . -name .gitignore -not -path './.bare/*' -not -path './worktree-store/*' 2>/dev/null

Step 2: Find existing gitignored files

For each gitignored pattern, check which files actually exist in the current worktree:

# List files that exist but are gitignored
git ls-files --others --ignored --exclude-standard

Focus on files that are:

• Configuration files (.env, .env.local, .env.development)
• Editor/tool settings (.vscode/settings.json, .idea/, .claude/settings.local.json)
• Local overrides that developers typically maintain per-project

Ignore:

• Build artifacts (node_modules/, target/, dist/, __pycache__/)
• Cache directories (.cache/, .turbo/, .next/)
• OS files (.DS_Store, Thumbs.db)
• Log files (*.log)

Step 3: Determine strategy for each file

Present a table of recommended files and strategies to the user:

Strategy guidelines

| Strategy | When to use | Examples | |----------|-------------|---------| | symlink | File should be identical across all worktrees. Editing in one worktree should propagate everywhere. | .claude/settings.local.json, .vscode/settings.json, .editorconfig (local) | | copy | File may need worktree-specific values. Each worktree gets its own independent copy. | .env, .env.local, .env.development.local |

Decision rules

1. Environment files (.env*) → Almost always copy (different worktrees may run on different ports or have different feature flags)
2. Editor/IDE settings → Usually symlink (you want consistent editor behavior)
3. Claude/AI settings → Usually symlink (consistent AI tool behavior)
4. Credentials/tokens → Usually copy (may differ per environment/branch)
5. Local config overrides → Depends on the file; ask the user if unsure

Step 4: Get user confirmation

Present the proposed configuration as a clear table:

File                              Strategy    Reason
.env                              copy        Environment-specific values
.env.local                        copy        Local overrides
.claude/settings.local.json       symlink     Shared AI tool settings
.vscode/settings.json             symlink     Consistent editor config

Ask the user to:

1. Review and approve/modify the list
2. Confirm strategies for any files you're unsure about
3. Add any files they want that weren't auto-detected

Step 5: Execute tracking

After user confirmation, track each file:

# Track each file with its strategy
ws store track .env --strategy copy
ws store track .claude/settings.local.json --strategy symlink
# ... repeat for each file

# Push store files to all existing worktrees
ws store push

Step 6: Verify

Run ws store status to verify everything was set up correctly:

ws store status

Check that all files show OK status. If any show MISSING or ERROR, troubleshoot:

• MISSING: File doesn't exist in the current worktree yet — may need to create it first, then ws store pull
• MISSING(store): File exists in worktree but not in store — run ws store pull <file> to import it
• NOT_LINK: Strategy is symlink but file is a regular file — ws store push should fix this