worktree-handoff
/worktree-handoff
Tworzy worktree dla zadania i zapisuje kontekst przekazania w pliku planu, który trafia do commita na gałęzi.
- Autor
- hanamizuki ↗
- Repozytorium
- solopreneur ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 13.10.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 1
- Skrypty
- 0
- Komentarze HTML
- 2
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 13.10.2026, bez odwołań do wycofanych modeli i API.
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
- SKILL.md zawiera komentarze HTML (2). Nie widać ich w podglądzie Markdown, a model je czyta.
Co robi i kiedy
Tworzy worktree dla zadania i zapisuje kontekst przekazania w pliku planu, który trafia do commita na gałęzi.
Wyzwalacze z opisu
Oryginalny opis (EN)
Create a git worktree for a task and record handoff context into a plan file that is committed to the branch. Discovers existing plan files in the user's configured todos or plans directory, appends a dated Handoff Context section, and commits everything before printing the next-session pickup message. Use when the user says "open worktree", "worktree handoff", "create a worktree", "start a new branch for this", or wants to hand off a task to a fresh session with full context preserved.
Jak działa
- Codex host guard
- Flow
- Example
Podgląd SKILL.md
---
name: worktree-handoff
description: |
Create a git worktree for a task and record handoff context into a plan file
that is committed to the branch. Discovers existing plan files in the user's
configured todos or plans directory, appends a dated Handoff Context section,
and commits everything before printing the next-session pickup message.
Use when the user says "open worktree", "worktree handoff", "create a worktree",
"start a new branch for this", or wants to hand off a task to a fresh session
with full context preserved.
---
# Worktree Handoff
## Codex host guard
Before any other action, check whether `CODEX_THREAD_ID` is set. If it is, stop
before creating a worktree or branch, copying configuration, changing a plan,
or committing. This release supports Worktree Handoff only on Claude Code;
tell the user the Codex worktree seam is not shipped yet and to run the
workflow there instead.
Create an isolated workspace for a new or in-progress task, and record the complete
task context into a plan file that gets committed to the branch. The next session reads
the plan file to pick up without re-explanation.
## Flow
### Step 1: Resolve Mode and Paths
Source the cascade config helpers, then determine the operating mode:
```bash
# --- solopreneur config helpers (sourced from shared/config.sh) ---
# One real shell file, so no harness rewrites the helpers on the way to the
# shell. Claude Code replaces the ${CLAUDE_SKILL_DIR} token below when it loads
# this body; Codex does not. It is SINGLE-quoted on purpose — it is a load-time
# token, not an environment variable, and letting the shell expand the name
# would source whatever an inherited value happened to point at. Unreplaced, it
# is not a directory, so substitute the absolute path of the directory holding
# THIS SKILL.md — every harness states that path to the model.
SOLO_SKILL_DIR='${CLAUDE_SKILL_DIR}'
[ -d "$SOLO_SKILL_DIR" ] || SOLO_SKILL_DIR="<absolute path of the directory holding this SKILL.md>"
SOLO_CONFIG_SH="$SOLO_SKILL_DIR/../../shared/config.sh"
# Three candidates, one contract. Inside the plugin the helpers sit at ../../shared/;
# authoring against this repo reaches them under src/solopreneur/shared/; and a
# skill republished on its own — any flattened skills directory — carries them
# at scripts/config.sh instead, because shared/ is a sibling of skills/ and does
# not travel with a per-skill copy. Try each in order, then STOP. Sourcing a
# file that is not there does not halt the shell: every helper stays undefined,
# every config read returns empty, and the 2026-08-11 A2 run showed where that
# leads — the model "rescued" it with a repo-relative path, which resolves only
# when the repo under review happens to be this plugin's own source repo.
# Canonical authoring keeps non-skill source under src/.
[ -f "$SOLO_CONFIG_SH" ] || SOLO_CONFIG_SH="$SOLO_SKILL_DIR/../../../src/solopreneur/shared/config.sh"
[ -f "$SOLO_CONFIG_SH" ] || SOLO_CONFIG_SH="$SOLO_SKILL_DIR/scripts/config.sh"
[ -f "$SOLO_CONFIG_SH" ] || { echo "HALT: solopreneur config helpers not found under $SOLO_SKILL_DIR — stop here, do not improvise a path"; exit 1; }
source "$SOLO_CONFIG_SH"
# --- end solopreneur config helpers ---
TODOS_CONFIG=$(read_solopreneur_config todos)
PLANS_CONFIG=$(read_solopreneur_config plans)
BACKLOG=$(echo "${TODOS_CONFIG:-{}}" | jq -r '.backlog // empty')
DOING=$(echo "${TODOS_CONFIG:-{}}" | jq -r '.doing // empty')
PLANS_DIR=$(echo "${PLANS_CONFIG:-{}}" | jq -r '.dir // empty')
PLANS_DIR="${PLANS_DIR:-docs/solopreneur/plans}" # default
MODE=$([ -n "$BACKLOG" ] && [ -n "$DOING" ] && echo "state-machine" || echo "flat")
```
**Mode decision:**
- **State-machine mode**: `$BACKLOG` and `$DOING` are both non-empty
- **Flat mode**: otherwise — uses `$PLANS_DIR`
### Step 2: Decide Worktree Name and Branch
Name based on task type and description:
| Task Type | Branch Prefix | Example |
|-----------|--------------|---------|
| Bug fix | `fix/` | `fix/sleep-calculation` |
| New feature | `feature/` | `feature/health-connect-edit` |
| Refactor | `refactor/` | `refactor/sleep-sessionizer` |
| Research | `research/` | `research/healthkit-sources` |
Worktree directory name = branch name slug (strip prefix, use `-` separators).
### Step 3: Create Worktree
**Always place worktrees under `.worktrees/`:**
```bash
git worktree add .worktrees/<slug> -b <branch-name>
```
**Prohibited:** operating on main, placing worktrees outside `.worktrees/`.
### Step 4: Copy Environment Config Files (gitignored secrets/config)
Worktrees are separate directories — gitignored files don't carry over automatically.
Check `.gitignore` for config/secret patterns, find matching files in the main repo,
copy them to the same relative paths in the worktree. Never copy build artifacts.
```bash
# The main repo is the first worktree. `--porcelain` puts the path on its own
# `worktree <path>` line, so a path containing spaces survives — and no `$N`
# lands in a skill body (see ../../shared/config.sh for why that matters).
MAIN_REPO="$(git worktree list --porcelain | sed -n 's/^worktree //p' | head -1)"
WORKTREE=".worktrees/<slug>"
# Find gitignored config files that exist in the main repo
# Common patterns: .env, *.xcconfig, local.properties, secrets.json
# Copy any that are relevant to this project to the worktree's corresponding paths
```
### Step 5: Discover Candidate Plan Files + Context-Aware Picker
**Collect all plan files:**
```bash
# State-machine mode: collect from backlog + doing
if [ "$MODE" = "state-machine" ]; then
ALL_FILES=$(find "$BACKLOG" "$DOING" -maxdepth 1 -name "*.md" 2>/dev/null)
else
mkdir -p "$PLANS_DIR"
ALL_FILES=$(find "$PLANS_DIR" -maxdepth 1 -name "*.md" 2>/dev/null)
fi
```
**Context matching — before prompting the user:**
Extract 3–5 key terms from the current conversation (task name, feature area, keywords
from the user's description). Then score each plan file:
1. Search file **names** (basename) for the key terms
2. Search file **content** (title headings, `Plan-Branch:` lines, first 20 lines) for the key terms
```bash
# ILLUSTRATIVE ONLY — substitute actual key terms extracted from the current
# conversation before running. Do NOT execute this block with these hardcoded terms.
TERMS="<term1>\|<term2>\|<term3>" # replace with actual key terms
CANDIDATES=""
while IFS= read -r f; do
[ -z "$f" ] && continue
score=$(head -20 "$f" | grep -i -c "$TERMS" 2>/dev/null); score=${score:-0}
name_score=$(basename "$f" | grep -i -c "$TERMS" 2>/dev/null); name_score=${name_score:-0}
total=$((score + name_score * 2))
[ "$total" -gt 0 ] && CANDIDATES="$CANDIDATES\n$total $f"
done <<< "$ALL_FILES"
CANDIDATES=$(printf '%b' "$CANDIDATES" | sort -rn)
MATCH_COUNT=$([ -n "$CANDIDATES" ] && printf '%b' "$CANDIDATES" | grep -c . || echo 0)
```
**Match count** = number of files with a score greater than zero (i.e., at least one key term found in the filename or first 20 lines of content).
**Decision based on match count:**
- **0 matches** — if `$ALL_FILES` is non-empty, briefly tell the user: "No matching plans found for this task — creating a new plan file. (Reply with a filename to use an existing plan instead.)" Then proceed to Step 6 to create a new file.
- **1 match** — use it automatically, no prompt. Print: `→ Matched plan: <filename>` so the user knows what was selected.
- **2+ matches** — show only the matching candidates (not all files) with index numbers, then ask:
> "Found N matching plans. Which one does this worktree belong to? Enter a number to reuse it, or 'new' to create a fresh plan file."
In state-machine mode, note the source directory in parentheses (Backlog / Doing) next to each filename.
**If no plan files exist at all**, skip all of the above and proceed directly to creating a new file.
**Recording the source:** When a file is selected, set `PLAN_SOURCE=backlog` or
`PLAN_SOURCE=doing` based on which directory it came from. Step 6 checks
`$PLAN_SOURCE` to decide whether to run `git mv` (only when `PLAN_SOURCE=backlog`).
### Step 6: Prepare the Plan File
#### If user picked 'new' (or no plans exist)
Create a new file:
- State-machine mode: `<doing>/<YYYY-MM-DD>-<branch-slug>.md`
- Flat mode: `<plans-dir>/<YYYY-MM-DD>-<branch-slug>.md`
Where `<branch-slug>` = branch name with `/` replaced by `-`
(e.g., `fix/sleep-calculation` → `fix-sleep-calculation`).
Date from `$(date +%Y-%m-%d)`.
New file content:
```markdown
<!--
Plan-Branch: <branch-name>
-->
## Handoff Context (<YYYY-MM-DD>, branch: <branch-name>)
### Problem Background
<why is this being done — user reports, screenshots, logs>
### Root Cause
<known technical issues, with file paths + line numbers>
### Items to Fix / Implement
- [ ] <item with expected approach>
### Key Files
| path | description |
|------|-------------|
### Current Progress
Not started.
```
Fill in the five sections based on context from the current conversation.
#### If user picked an existing file
1. **Move from backlog to doing (state-machine mode only):**
If the selected file is in `$BACKLOG`, move it:
```bash
git mv "$BACKLOG/<filename>" "$DOING/<filename>"
PLAN_FILE="$DOING/<filename>"
```
In flat mode, skip this step — the file stays in place.
2. **Ensure the `Plan-Branch:` marker block exists at the top of the file.**
If the file already starts with an HTML comment block containing at least one
`Plan-Branch:` line, check whether `Plan-Branch: <branch-name>` is already
present. If it is absent, append the line inside the existing comment block:
```bash
python3 -c "
import sys
branch, path = sys.argv[1], sys.argv[2]
with open(path) as f: content = f.read()
idx = content.find('\n-->')
if idx != -1:
content = content[:idx+1] + 'Plan-Branch: ' + branch + '\n' + content[idx+1:]
with open(path, 'w') as f: f.write(content)
" "<branch-name>" "$PLAN_FILE"
```
If no comment block exists at the top (legacy file), prepend one:
```markdown
<!--
Plan-Branch: <branch-name>
-->
```
3. **Append the handoff section at the end of the file:**
```markdown
## Handoff Context (<YYYY-MM-DD>, branch: <branch-name>)
### Problem Background
<why is this being done — user reports, screenshots, logs>
### Root Cause
<known technical issues, with file paths + line numbers>
### Items to Fix / Implement
- [ ] <item with expected approach>
### Key Files
| path | description |
|------|-------------|
### Current Progress
<not started / steps done so far>
```
Fill in the five sections based on context from the current conversation.
Be specific: include file names, line numbers, error messages, actual numbers.
Include root cause analysis already done so the next session doesn't debug from
scratch. If the conversation had screenshots or user-reported bug details,
include everything.
### Step 7: Commit and Push
```bash
git add <plan-file-path>
# Also stage the git mv result if the file moved from backlog to doing
git commit -m "docs(handoff): context for <branch-name>"
git push -u origin <branch-name>
```
Single commit. Push immediately so the doc is visible to the next session and to
PR reviewers.
### Step 8: Output the Next-Session Pickup Message
Print this so the user can paste it into a new session:
```text
cd /absolute/path/to/repo/.worktrees/<slug>
Plan file: <relative/path/to/plan.md>
Read the plan file for the full context — branch <branch-name> is tracked under
the `Plan-Branch:` marker, and the latest `## Handoff Context` section captures
the current state.
Branch: <branch-name>, <one-line task description>.
```
Use an absolute path in the `cd` command (from `git worktree list`). The plan file
path should be relative to the repo root.
## Example
User says: "Open a worktree to fix the sleep calculation — the issue is duplicate
sources from HealthKit"
```bash
git worktree add .worktrees/fix-sleep-calculation -b fix/sleep-calculation
```
Plan file discovery: user picks existing `2026-04-10-sleep-tracking.md` from
backlog (state-machine mode). File is `git mv`'d to doing, `Plan-Branch:
fix/sleep-calculation` is added to the marker block, and the Handoff Context
section is appended with the HealthKit duplicate-source root cause detail.
Commit: `docs(handoff): context for fix/sleep-calculation`
Output for user:
```text
cd /path/to/project/.worktrees/fix-sleep-calculation
Plan file: docs/solopreneur/plans/doing/2026-04-10-sleep-tracking.md
Read the plan file for the full context — branch fix/sleep-calculation is tracked
under the `Plan-Branch:` marker, and the latest `## Handoff Context` section
captures the current state.
Branch: fix/sleep-calculation, deduplicate HealthKit multi-source sleep samples
so displayed sleep time matches Apple Health's value.
```
Wersje
W bazie nie ma innych skilli o nazwie worktree-handoff.
Identyczna treść występuje jeszcze w 1 innych folderach na GitHubie. Tu pokazujemy jedną, najlepiej ocenioną kopię.
Migawka bazy z 13.11.2026 · wersja paczki 55e9681c3a50 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100worktree-new
Tworzy worktree zadania poleceniem aidrian i uruchamia bootstrap projektu. - 100worktree
Tworzy worktree gita dla nowej gałęzi funkcji i przygotowuje w nim pliki oraz zależności. - 100ce-worktree
Przygotowuje izolowane worktrees gita: tworzy nową gałąź do świeżej pracy albo podpina worktree do istniejącej gałęzi, PR lub commita. - 100worktree
Tworzy worktree z origin/trunk w katalogu ~/worktrees.nosync i kopiuje node_modules, żeby zacząć pracę na gałęzi. - 100worktree-open
Tworzy lub ponownie otwiera worktree gita do pracy równoległej, gdy chcesz pracować na boku bez przełączania gałęzi. - 100worktree
Uruchamia, sprawdza i czyści worktree git dla sesji, pilnując zasady jedna sesja, jeden worktree i jedna gałąź.