starting-work
Sync local main, then create a properly named branch (or worktree) to start new work. Use when starting new work, asked to "start a new branch", "create a branch for X", "sync main and branch off", or "set up a worktree for this feature" — before any commits happen. Validates the branch name against git-kit's [type]/[description] convention and offers a worktree as an alternative to a plain branch checkout.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-15
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- starting-work
- description
- Sync local main, then create a properly named branch (or worktree) to start new work. Use when starting new work, asked to "start a new branch", "create a branch for X", "sync main and branch off", or "set up a worktree for this feature" — before any commits happen. Validates the branch name against git-kit's [type]/[description] convention and offers a worktree as an alternative to a plain branch checkout.
- allowed-tools
- Bash(git fetch:*), Bash(git checkout:*), Bash(git pull:*), Bash(git status:*), Bash(git branch --show-current:*), Bash(git symbolic-ref refs/remotes/origin/HEAD:*), Bash(git worktree add:*), Bash(git worktree lock:*), Bash(bash ${CLAUDE_PLUGIN_ROOT}/scripts/git-write-marker.sh:*), Read, Glob, Write, AskUserQuestion
- argument-hint
- (optional) branch type and description, e.g. "feature add-user-auth"
02 资源文件 2
- 参考文档references/worktree-decision.md1.4 KB
- 脚本scripts/smoke_test.py7.8 KB
03 SKILL.md 正文
Starting Work
Get from "I'm about to start something new" to a properly named, up-to-date branch (or worktree) in one gated flow — instead of manually remembering to sync main, checking the naming convention, and deciding whether a worktree makes sense, separately, every time.
When to Use
Before writing any code for a new piece of work: syncing local main and creating the branch (or
worktree) it'll happen on. Triggers: "start a new branch", "create a branch for X", "sync main and
branch off", "set up a worktree for this feature".
When NOT to Use
- Rebasing an already-existing feature branch onto a newer main — that's
/git-sync-branch, not this skill.starting-workonly runs before a branch exists. - Renaming an existing branch based on what it now contains — that's
/git-update-branch-name. - Anything after the first commit — once work has started, this skill has nothing left to do.
Instructions
- Note the starting point and sync:
git branch --show-current(for the report).git fetch origin --prune. Resolve the actual default branch —git symbolic-ref refs/remotes/origin/HEAD(falling back tomainif that fails, e.g. nooriginremote configured) — the same resolutionfinishing-workuses, so the two halves of the branch lifecycle agree on what "main" means in a repo that defaults to something else. Note: because the resolved branch name is dynamic,allowed-toolsgrantsBash(git checkout:*)broadly rather than pinned to a literal branch name — this also covers step 4'sgit checkout -b, so no separate grant is needed there. This skill never runs the file-restore form (git checkout -- <path>); only branch checkout and-bare ever invoked. If not already on the resolved default branch, ask viaAskUserQuestion— "Base the new branch off<resolved-branch>, or off the current branch (<name>)?" — default the resolved branch. If basing off it:git checkout <resolved-branch>, thengit pull --ff-only. If that fails (diverged local branch, or it's already checked out in another worktree), tell the user exactly why and stop rather than force anything. If basing off the current branch, skip the checkout/pull — seereferences/worktree-decision.mdfor why this branch-off-a-branch case is legitimate (e.g. stacking related work). Verifygit status --porcelainis clean before proceeding; if not, tell the user to commit or stash first (point at thecommitskill) and stop here. - Resolve the branch name: use
$ARGUMENTSif it supplies a type and description; otherwise ask viaAskUserQuestionfor both, one at a time. Validate:- Type: a single lowercase word, no slashes or spaces.
- Description: kebab-case — lowercase letters, digits, and hyphens only; no leading/trailing/double
hyphen.
Don't hardcode or restate the accepted type list here —
commit's own "Branch Naming Convention" section is the single source of truth for that. If the user is unsure what type to use, point them there instead of guessing or duplicating the list. If either value fails validation, tell the user why and ask again viaAskUserQuestion— never pass an invalid type or description forward to step 4, the same "stop and explain" discipline step 1 already applies to a diverged main.
- Ask worktree or plain branch: read
use_worktree(defaulttrue) the same waycommitreads its own settings —.claude/git-kit.local.jsonif it exists and sets the field, else the git-tracked${CLAUDE_PLUGIN_ROOT}/git-kit.settings.jsondefault. This field doesn't need the trust-boundary checkcommit'scommit_confirm_before_commit/commit_auto_stagerequire — it never skips the question below or triggers any automation on its own, it only changes which option is pre-highlighted, so honor it from either file, tracked or not. Then always ask viaAskUserQuestion— "Create a plain branch, or a separate worktree for this?" — options "Plain branch" and "Worktree", with whicheveruse_worktreefavors listed first and suffixed(Recommended): "Worktree (Recommended)" whentrue(the default, chosen with multiple agents — e.g. Codex CLI alongside Claude Code — potentially working in this same repo, where a separate working directory per piece of work avoids one agent's uncommitted state colliding with another's), "Plain branch (Recommended)" whenfalse. The setting never replaces this ask — a human always makes the actual choice. Seereferences/worktree-decision.mdfor the tradeoffs to mention if the user wants guidance rather than a snap decision. - Create: immediately before either branch-creating command below, run
bash "${CLAUDE_PLUGIN_ROOT}/scripts/git-write-marker.sh" git-branch-create starting-work— this writes the marker git-kit's branch-creation guard requires; it must be written right before the command runs, not earlier, since the hook only accepts a marker up to 60 seconds old.- Plain branch:
git checkout -b <type>/<description>. - Worktree: compute a default path at
.claude/worktrees/<description>(this skill only ever runs under Claude Code; the equivalent path for a Codex CLI session would be.codex/worktrees/<description>— both are gitignored). This isstarting-work's own default for a session-lifecycle-managed worktree — distinct fromgit-worktrees' sibling-directory convention (../project-feature), which stays the right default for manual, ad-hoc worktree management outside this automated flow; see that skill's own note on the two use cases. Confirm the computed path with its ownAskUserQuestion— "Create the worktree at<path>?" — options "Use this path" / "Enter a different path". Don't rely on step 3's worktree-vs-branch question to also cover the path (its own options only ever say "Plain branch" / "Worktree" — never fold the computed path into that option's description text as a substitute for asking here). If the user supplies an override, constrain it: letters, digits, hyphens, underscores, forward slashes, and periods only (no shell metacharacters), it must not contain a..path segment, and it must resolve to a location either (a) inside this repo under.claude/worktrees/or.codex/worktrees/, or (b) alongside/below the repo's parent directory (the old sibling convention, still supported as an explicit override) — not step 2's kebab-case rule, which is stricter than a filesystem path needs to be. If the override doesn't meet this, tell the user why and ask again rather than passing it through. Thengit worktree add -b <type>/<description> <path>, followed immediately bygit worktree lock <path> --reason "claude session"so the worktree can't be removed bygit worktree remove(without--force) until it's explicitly unlocked —git-cleanupknows to unlock a session-locked worktree before removing it once its branch is safe to delete. Then copy over local, gitignored configgit worktree adddoesn't carry (it only shares tracked history, not untracked files):Globthe main worktree root for.claude/*.local.json(top-level only, not recursive) and copy each match found into the same relative path in the new worktree, only if the destination doesn't already exist there (never clobber). This covers.claude/settings.local.jsonplus every other per-plugin.claude/<name>.local.jsonoverride this repo's local-config precedent (.claude/rules/ask-before-config-decisions.md) produces — e.g.git-kit.local.json,analysis-kit.local.json,plugin-auditor.local.json,codex-windows-guardrails.local.json— generically, rather than a hardcoded list that needs a follow-up fix every time a new plugin adopts the same precedent. AlsoGlobthe main worktree for**/CLAUDE.local.mdand copy each match found into the same relative path in the new worktree, same no-clobber rule — but first drop any match under a vendored/third-party tree (node_modules/,.venv/), this repo's own.temp/directory, or another worktree's own directory (.claude/worktrees/*/,.codex/worktrees/*/) — this last exclusion matters because this same skill's own default worktree path lives under one of those trees, so without it aCLAUDE.local.mdbelonging to a different, unrelated worktree could be swept in and copied into the new one. Since a bare**/CLAUDE.local.mdpattern would otherwise sweep all of these, andGlobitself has no exclude syntax, filter the match list before copying rather than trying to encode the exclusion into the pattern.
- Plain branch:
- Report: the branch (or worktree path) just created, current location, and — for a worktree —
that
cd-ing into the worktree path is needed before working there, and that it's now locked to this session: when the work here is done,finishing-work//git-cleanuphandles unlocking and removal — don'tgit worktree remove --forceit directly, since that bypasses the lock as a safety signal that this worktree is still in active use. Mentiongit-worktreeshas further operations (compare, merge, cleanup) if multiple worktrees end up in play.
Worktree Topic Scope
A worktree this skill creates is scoped to one topic. If a session's already-bound worktree was created
for a different piece of work, don't start unrelated work in it — run this skill again for the new topic,
which creates its own worktree. Symmetrically, don't keep working across worktrees for unrelated topics in
the same session: finish the current topic (finishing-work / /git-cleanup) before starting the next
one, rather than leaving multiple topics open at once.
This is a convention for how these worktrees get used, not a mechanical lock — nothing enforces "topic" the way a file lock enforces exclusive access, since there's no way to check whether two pieces of work are actually the same topic from git state alone.
Why it matters: a worktree that accumulates unrelated work becomes hard for git-cleanup to reason
about — it can't tell whether all the work in it is done, just the piece currently top of mind, so a
mixed-topic worktree is more likely to get force-deleted along with unrelated in-progress changes by
mistake. One worktree per topic keeps git-cleanup's merged/unmerged/dirty analysis meaningful: "this
worktree's branch merged" reliably means "this worktree is done."
The session-level half — don't leave one topic's worktree open while starting a second, unrelated one —
matters because the Stop exit-guard (git-guard-dirty-worktree-exit.sh) only checks the worktree the
session's current working directory is actually in when the turn ends, not every worktree the session has
ever locked. Moving into a second worktree before finishing the first leaves the first one's dirty/unmerged
state unchecked at Stop time, even though it's still locked and still at risk.
Testing & Validation
Verify this skill activates on:
- "start a new branch for the auth refactor"
- "create a branch for X" / "sync main and branch off"
- "set up a worktree for this feature"
Verify it does NOT activate on:
- "sync my current branch with main" →
/git-sync-branch - "rename this branch to match what it does now" →
/git-update-branch-name - "I just merged, clean this up" →
finishing-work
Verify use_worktree behavior:
use_worktree: true(the default) — confirm step 3'sAskUserQuestionstill fires every time, with "Worktree (Recommended)" listed firstuse_worktree: false— confirm the same question fires, with "Plain branch (Recommended)" listed first instead- Either value — confirm the setting never skips the question outright; the user's actual answer at step 3 always decides, regardless of which option was pre-highlighted
Verify the worktree-path confirmation:
- Worktree chosen at step 3, default path accepted at step 4's own
AskUserQuestion— confirmgit worktree addruns with the computed default path - Worktree chosen at step 3, path overridden at step 4 — confirm the override goes through the existing
character-class/
..-segment/location validation before being passed togit worktree add - Confirm the computed path is never mentioned inside step 3's own option description text as a substitute for step 4's own question — step 3 asks whether, step 4 asks where
Verify the local-config copy behavior (issue #113):
- Main worktree root has
.claude/settings.local.jsonplus one or more other.claude/<name>.local.jsonfiles (e.g..claude/git-kit.local.json) — confirm every one of them is copied into the new worktree, not justsettings.local.json - A destination
.claude/<name>.local.jsonalready exists in the new worktree — confirm it's never clobbered .claude/*.local.jsonglob stays top-level only — confirm a.local.jsonfile nested deeper than.claude/(not a realistic case today, but the pattern shouldn't accidentally reach one) is not swept
Verify the CLAUDE.local.md exclusion behavior:
- An unrelated, already-existing worktree (e.g.
.claude/worktrees/other-topic/) has its ownCLAUDE.local.md— confirm creating a new worktree never copies that file in; the sweep must drop.claude/worktrees/*/and.codex/worktrees/*/matches the same way it already dropsnode_modules//.venv//.temp/ - A
CLAUDE.local.mdgenuinely at or below the main worktree root (not inside another worktree) is still copied normally
Verified live, 2026-08-28: ran find .claude -maxdepth 1 -name "*.local.json" against this repo's
real main checkout — matched exactly .claude/settings.local.json and
.claude/codex-windows-guardrails.local.json (the same file issue #113's own reproduction steps cite),
confirming a .claude/*.local.json glob reaches every real per-plugin local override this repo
currently has, not just settings.local.json. No fresh skill-tester eval re-run for this edit — the
fix is a mechanical glob-pattern generalization of already-eval-covered copy logic
(evals/starting-work/evals.json), verified directly against real repo files rather than re-run
end-to-end.
Quality gates:
- [ ] Step 1 never fast-forwards a diverged local
mainsilently — always stops and tells the user - [ ] Step 2 never hardcodes the branch-type list — always points at
commit's own convention section - [ ] Step 2 never passes an invalid type/description forward — always re-asks on validation failure
- [ ] Step 3's worktree-vs-branch question always uses
AskUserQuestion, never assumed —use_worktreeonly changes which option is recommended, it never skips the question - [ ] Step 4 never passes an unconstrained worktree-path override to
git worktree add— always validates the character class and rejects any..path segment - [ ] Step 4 always fires its own
AskUserQuestionfor the worktree path beforegit worktree addruns — a path mentioned only inside step 3's option description never satisfies this - [ ] Step 4's default worktree path is always
.claude/worktrees/<description>(or.codex/worktrees/for a Codex CLI session) — never the old sibling-directory convention, unless the user explicitly overrides to one - [ ] Every worktree Step 4 creates is locked (
git worktree lock) immediately aftergit worktree add— never left unlocked - [ ] Step 4's local-config copy always globs
.claude/*.local.json(every per-plugin override), never just.claude/settings.local.jsonalone - [ ] Step 4's
CLAUDE.local.mdsweep always drops matches under another worktree's own directory (.claude/worktrees/*/,.codex/worktrees/*/), never justnode_modules//.venv//.temp/ - [ ] Step 5's report always mentions the worktree is session-locked and points at
finishing-work//git-cleanupfor removal — never suggestsgit worktree remove --forcedirectly - [ ] Step 4 always writes the
git-branch-createmarker immediately beforegit checkout -b/git worktree add -b, never earlier in the run - [ ] A dirty working tree at step 1 always stops the flow with a pointer to
commit, never proceeds
Reference Guide
| Resource | Purpose |
|---|---|
references/worktree-decision.md |
Worktree-vs-plain-branch tradeoffs, and the branch-off-a-branch escape hatch for stacking work on top of an open PR |
04 同仓库更多 Skills
demo
Fixture skill used by scripts.marketplace_ci sync tests.
export-demo
Fixture skill used by scripts.marketplace_ci export tests.
work-to-development
Validate an accepted Linear Issue's readiness for implementation (criteria, dependencies, duplicate/existing artifacts) and request governed branch/worktree creation through git-kit:starting-work — recording work-started Git/GitHub evidence and a deliberate Linear Started transition only after Git identity is read back and verified. Use when asked to start work on a Linear issue, begin development for an accepted issue, or prepare an accepted issue for implementation. Never creates a branch directly — always delegates to git-kit.
work-linking
Create and maintain stable cross-system links and authority labels between Notion and Linear records, and detect/repair drift between them. Use when asked to link a Notion record to a Linear record, check for drift between Notion and Linear, or repair a broken/stale link. Repairs only the bounded non-authoritative copy or link — never chooses by newest timestamp, and never creates a reverse-write loop against either system's own authority.
status-and-learning
Produce a dated, explicitly non-live Linear-to-Notion progress summary, or capture an outcome/learning after work completes. Use when asked to summarize progress to Notion, report portfolio status, or capture what was learned from a completed piece of work — not to disposition open follow-up items (see open-item-management for that). Never runs automatically or continuously — every summary is a deliberate, approved snapshot, not a live sync.
repository-gates
Discover, delegate, record, and invalidate this repository's actual Git/GitHub lifecycle gates (pre-commit, pre-push, PR required checks, Codex delta review, review requirements, merge rights) and the repository-policy provider profile that maps governed operations to git-kit. Use when asked what gates apply to this repository, to discover repository policy before starting Wave 2 work, or to check whether prior gate evidence is still valid after new commits. Discovery and delegation only — never executes a gate's own internal logic, and never invents a gate the repository doesn't actually define (in particular, never assumes a "Review Changes" gate exists).