Worktree Create
one command, five things at once

# Branch Setup — Start New Work (Worktree Version)

> Before you use this: this is a reusable template. Every [PLACEHOLDER] below is something
> you (or Claude) fill in with your own org's details the first time you set it up.
> Replace every placeholder, then save it to your commands folder.

Invoke at the very start of every new piece of Salesforce work, before touching the sandbox.
This skill creates a fresh, isolated folder (a worktree) for your new task, on a correctly-named
branch, synced from your remote, with your dev sandbox set as that folder's default org. It pauses
at every command and waits for your OK before running anything.

## Placeholders to fill in once
- [HOME_REPO]            Your main repo folder, kept on the default branch (e.g. myorg-sf)
- [DEFAULT_BRANCH]       The branch your home base stays on (main or master)
- [BASE_BRANCH]          The branch you raise PRs against — never main if you have a pipeline
- [DEV_SANDBOX_ALIAS]    Your personal dev sandbox CLI alias
- [SANDBOX_URL_PATTERN]  Your org's My Domain sandbox URL (https://myorg--<name>.sandbox.my.salesforce.com)
- [USERNAME]             Your machine username (for the memory path)
- [REPO_PARENT_DIR]      The folder your repos sit under (e.g. Documents\VSCode)
- [PM_TOOL]              Your project management tool (ClickUp, Jira, Azure DevOps)
- [BRANCH_PREFIXES]      Your team's own branch-prefix list (replace the example in Step 0b)

## How to use
Paste this into Claude at the start of every new task:

    /project:sf-branch-start

Claude asks four questions first, then proposes your branch name, worktree folder name, commit
message and PR description for you to confirm before running a single command.

## Step 0 — Collect context (ask these four, one at a time)
Q1. In one sentence, what are you about to build or fix in the dev sandbox?
Q2. Is it a NEW feature or a FIX for something broken?
Q3. Which Salesforce object(s) does it touch? (or "none")
Q4. Is there a [PM_TOOL] ticket number? (paste it, or "no ticket")
Wait for all four before moving on.

## Step 0b — Draft four artefacts (confirm before any command)
Branch name: <prefix>/<short-kebab-description>, lowercase, dashes inside, max 4 words after the slash.
Pick the prefix from your team's list. [BRANCH_PREFIXES] — replace this with your own. Example starter set:
  feat  generic new feature
  fix   bug fix to something already in production
  lwc   Lightning Web Components
  flow  Flow automation
  data  reporting and data components
  api   REST API / external integrations
Worktree folder name: the branch name with the slash replaced by a dash.
Commit message: max 70 chars, present-tense imperative.
PR title + description: title = commit message; description = What changed / Why / How to test.

## Step 0c — Seed the new worktree's memory (no "go" needed)
Each VS Code window runs its own Claude session. Seed it so the new window knows the PR details and
context without re-explaining. Memory dir:
  C:\Users\[USERNAME]\.claude\projects\c--Users-[USERNAME]-<encoded-folder-path>\memory\
Write project_pr_context.md (branch, ticket, PR title, why, how to test), copy any relevant memory
files from the current session, then write MEMORY.md indexing them.

## Step 1 — Sync the latest (no disruption)
From inside [HOME_REPO]:
    git fetch origin
Fetch never changes open files, so it is safe even mid-build in another window.

## Step 2 — Create the worktree (new folder + new branch)
From inside [HOME_REPO]:
    git worktree add -b <branch-name> ../<folder-name> origin/[DEFAULT_BRANCH]
If git says the branch is already checked out elsewhere: STOP, don't use --force, ask.

## Step 3 — Set the target org and open
    sf org list
Ask which alias is the personal dev sandbox ([DEV_SANDBOX_ALIAS]) — never UAT/staging/prod. Then:
    cd ../<folder-name>; sf config set target-org <alias>; code .
If the sandbox isn't listed, log in first:
    sf org login web --alias <alias> --instance-url [SANDBOX_URL_PATTERN]

## Safety rules — never break these
- Never git push --force, git reset --hard, or anything destructive.
- Never deploy directly to UAT or production — the pipeline does that after merge to [BASE_BRANCH].
- Never set the target org to UAT/staging/prod — always the personal dev sandbox.
- Never create a worktree inside [HOME_REPO] — they go beside it (the ../ handles this).
- A branch lives in only one worktree at a time. That's protective, not an error.
- If a command fails, STOP, translate the error to plain English, suggest one safe recovery.
- Merge conflict? STOP and escalate — don't auto-resolve.

# Branch PR — Finish Work and Raise a Pull Request (Worktree Version)

Invoke after you've finished changes in the dev sandbox and are ready to commit and raise a PR.
This skill reviews what changed, stages the right files, commits, pushes, raises a PR, then tidies
up the worktree. It pauses at every command and waits for your OK.

Run every command from inside the task's own worktree folder — not your [HOME_REPO] home base.

## How to use
From the worktree window:
    /project:sf-branch-pr

## Step 8 — Review what changed
    git status
    git diff --stat
Flag anything unexpected: profile diffs, timestamp-only XML changes, ID-only changes, files from a
component you didn't mention. For each, ask: keep or discard? Discard with:
    git checkout -- <filename>
Don't continue until the file list looks right.

## Step 9 — Stage the files
    git add .
(or stage specific files). Wait for "go".

## Step 10 — Commit with a descriptive message
Max 70 chars, present-tense imperative, specific (not "fix" or "updates").
    git commit -m "<message>"

## Step 11 — Push the branch
First push:  git push -u origin HEAD
Later:       git push
Copy the URL git prints — you'll use it in Step 12.

## Step 12 — Open a pull request
Base branch is always [BASE_BRANCH]. Never raise a PR against [DEFAULT_BRANCH].
    gh pr create --base [BASE_BRANCH] --title "<message>" --body "<description>"
PR description = What changed / Why / How to test. Paste the [PM_TOOL] ticket if there is one.

### After the PR — update [PM_TOOL] (no "go" needed)
If there's a ticket: look it up, add a comment "PR opened: <URL> — <title>", set status to In Review.
If the [PM_TOOL] connector isn't available, tell the user and continue — it's a convenience, not a blocker.

## Step 13 — Request review and wait for merge
Add a reviewer on the PR page. After merge, the pipeline deploys onward automatically.
When you can see the PR is merged, type "merged" and continue to Step 14.

## Step 14 — Tidy up the worktree (after merge only)
From your home base ([HOME_REPO]), not the worktree itself:
    git worktree remove ../<folder-name>
    git branch -d <branch-name>
If git refuses because of uncommitted changes, that's a safety feature. STOP, don't use --force,
check git status and decide with the user.

## Safety rules — never break these
- Never push --force, reset --hard, or remove a worktree with --force.
- Never deploy directly to UAT or production.
- Never run Step 14 until the PR is actually merged.
- Run git worktree remove from the home base, never from inside the folder being removed.
- Merge conflict? STOP and escalate.