worktree-task

Git Worktree Task

plan ファイル / GitHub Issue / JIRA チケット / Backlog 課題 / 重量タスク受領時に自動起動。worktree + branch を作成し、A 案 (同 session 内 cd 切替) または B 案 (別 session 起動) でタスク実装。

入力受付仕様

gwt.sh <input> [--tracker jira|backlog] の <input> は以下を自動判別:

入力例	判別
docs/plans/feature.plan.md	plan ファイル (.. 含むパス禁止)
Issue 20 / Issue: 20 / Issue：20 / Issues 20	GitHub Issue (cwd の repo)
#20 / 20	GitHub Issue (cwd の repo)
イシュー 20 / イシュー：20 / チケット 20	GitHub Issue (cwd の repo、prefix 除去)
owner/repo#20 / gh:owner/repo#20 / gh:20	GitHub Issue (別 repo / 明示)
https://github.com/owner/repo/issues/20	GitHub Issue URL
https://github.com/owner/repo/pull/20	GitHub PR URL (gh pr view に dispatch)
https://github.mycompany.com/owner/repo/issues/20	GitHub Enterprise URL
PROJ-123 / Ticket PROJ-123 / チケット PROJ-123	JIRA or Backlog (環境変数で自動判別)
BLG-456 / 課題 BLG-456	JIRA or Backlog (環境変数で自動判別)
https://*.atlassian.net/browse/PROJ-123	JIRA URL (Cloud 旧)
https://*.atlassian.net/jira/software/c/projects/.../issues/PROJ-123	JIRA URL (Cloud 新レイアウト)
https://jira.example.com/browse/PROJ-123	JIRA Server URL
https://*.backlog.com|.jp|.de/view/BLG-456	Backlog URL
https://*.backlogtool.com/view/BLG-456	Backlog レガシードメイン URL

prefix キーワード (Issue / Issues / Ticket / Tickets / イシュー / チケット / 課題、大文字小文字無視) は除去後にパターン判定。区切り文字は半角空白 / 全角空白 / 半角コロン (:) / 全角コロン (：) を受付。

入力 validation:

• locale 安定化: スクリプト先頭で LC_COLLATE=C 設定 (ja_JP.UTF-8 環境で [A-Z]* glob が小文字を拾うバグ予防)
• anchored regex: [A-Z][A-Z0-9_]*-[0-9]+$ / ^[0-9]+$ 完全一致で trailing junk (PROJ-123 余計 / 20 extra / PROJ-123;rm) を弾く
• path traversal: plan ファイル経路で .. を含むパス拒否

JIRA / Backlog 自動判別

PROJ-123 形式は JIRA / Backlog どちらにも該当。解決ロジック:

1. JIRA 3 点 AND: JIRA_BASE_URL && JIRA_EMAIL && JIRA_TOKEN 全て揃って JIRA_OK=1
2. 片方のみ OK: そっちを採用
3. 両方 OK + WORKTREE_TASK_DEFAULT_TRACKER 設定: デフォルト値採用
4. 両方 OK + デフォルト未指定: exit 3 → Claude が AskUserQuestion で確認 → --tracker jira|backlog 再実行
5. JIRA 一部のみ設定 (BASE_URL or EMAIL or TOKEN 抜け): exit 4 + 不足 env 一覧を stderr 提示
6. 両方 env 未設定: exit 4 → Claude が AskUserQuestion で setup 確認 → ユーザーが .env 編集後再実行

Claude (AI) の動作仕様

gwt.sh が以下の exit code を返した場合の Claude 側対応:

exit	状態	Claude の動作
0	成功	完了報告 + 次ステップ案内
1	引数欠落 / plan ファイル不在 / --tracker 値欠落	エラー再表示 + 入力修正依頼
2	入力形式不明 / path traversal / URL からの key 抽出失敗	対応形式リスト + 再入力依頼
3	ambiguous (両方 env + default 未指定)	AskUserQuestion で確認 → --tracker <jira|backlog> flag 付きで再実行 (詳細下記)
4	ambiguous (両方 env 未設定 or JIRA 一部のみ設定)	AskUserQuestion で setup 確認 → 該当 env を .env.example を参考にユーザー設定依頼
5	--tracker / WORKTREE_TASK_DEFAULT_TRACKER 値不正	値訂正 (jira / backlog のみ)
6	worktree ディレクトリ既存	git worktree remove .worktrees/<task-name> を提案
10	必須ツール未インストール (jq / gh / curl)	${CLAUDE_PLUGIN_ROOT:-(plugin install path)}/README.md の install 手順を提示
11	gh issue view / gh pr view 失敗	gh auth status / gh auth refresh -s repo を案内
12	JIRA / Backlog API その他失敗	認証情報 / URL / network 確認、redact 済み stderr を提示
13	JIRA / Backlog 401 / 403 (認証 / 権限失敗)	API token / API key の有効期限確認、JIRA は EMAIL 一致確認
14	JIRA / Backlog 404 (issue not found)	issue key の typo 確認、project 移動の可能性
15	JIRA / Backlog 429 (rate limit)	60-300 秒待機後リトライを案内
16	JIRA / Backlog 5xx (server error)	tracker 側障害、status page 確認を案内
99	内部エラー (本来到達しない SOURCE)	バグ報告 (Issue 起票)
その他	git worktree (128) / rsync (23,24) / gh その他 (4,6) など	生 exit code を Claude に共有、ユーザーに stderr 提示

exit 3 / 4 の AskUserQuestion テンプレ (公式 schema 準拠: header ≤ 12 chars / 2-4 options)

exit 3:

• header: Tracker
• question: JIRA と Backlog どちらで取得しますか？
• options: [{label: "JIRA"}, {label: "Backlog"}]
• 選択後: gwt.sh "$INPUT" --tracker <jira|backlog> で再実行

exit 4 (両方未設定):

• header: Tracker setup
• question: JIRA と Backlog どちらをセットアップしますか？
• options: [{label: "JIRA"}, {label: "Backlog"}, {label: "両方"}]
• 選択後: ${CLAUDE_PLUGIN_ROOT}/.env.example の該当セクションを project root .env にコピー + 編集を依頼

exit 4 (JIRA 一部のみ):

• header: JIRA env
• question: 不足している JIRA env (BASE_URL / EMAIL / TOKEN) を .env に追加してください。完了したら「再実行」を選択してください。
• options: [{label: "再実行"}, {label: "キャンセル"}]

環境変数 (project root .env または shell)

JIRA_BASE_URL=https://your-company.atlassian.net
[email protected]
JIRA_TOKEN=your_atlassian_api_token
BACKLOG_SPACE_URL=https://your-space.backlog.com
BACKLOG_API_KEY=your_backlog_api_key
WORKTREE_TASK_DEFAULT_TRACKER=jira  # or "backlog"

GitHub: gh auth login で認証 (env 不要)。

.env 自動読込挙動: $PWD/.env → ~/.config/worktree-task/.env の順で最初に見つかった方のみ source (両方は同時に読まない、set -a; . file; set +a で既存 env を上書きしない)。.env は 必ず .gitignore に追加 してください。スクリプトが project root の .env を検出した時、git check-ignore で gitignore 状態を verify し、未 ignore なら stderr に WARN 出力します。

Backlog API 認証について: ?apiKey= クエリパラメータ方式を使用 (公式 2 方式のうち setup 容易な方)。OAuth 2.0 Bearer は Authorization Code Grant flow + 1 時間 token expire + refresh logic が必要なため本 skill では非対応。アクセスログ漏洩リスクは redact_secrets 関数で stderr 出力時にマスク。

取得結果の保存先

plan 以外の入力源 (gh / jira / backlog) の場合、worktree 作成後に .worktrees/<task-name>/PLAN.md へ取得本文を書き出し:

• 既存 PLAN.md 検出時は PLAN.md.bak.<UTC timestamp> に退避してから新規生成
• TITLE は見出し記号 (#) を除去 (PLAN.md 本体タイトル # {TITLE} の階層ズレ予防)
• BODY 内の三連バッククォート (```) はエスケープ (PLAN.md コードフェンスのネスト崩壊予防)
• JIRA description は ADF (Atlassian Document Format) を [.. | objects | .text? // empty] | join("\n") で plain text 抽出
• rsync は --exclude='.env' --exclude='.env.*.local' で project root の secret 複製を防止

タスク実装時は @.worktrees/<task-name>/PLAN.md を参照。

A / B 案の使い分け

判断基準 = 改修対象 (task 種別ではない):

基準	A 案 (同 session 内 cd 切替)	B 案 (別 session 起動)
対象タスク	成果物変更のみ (ファイル / git / CLAUDE.md ガイダンス)	skill / hook / MCP / settings 改修含む
方法	cd .worktrees/<name> で本 session 継続	claude -w <branch> で別 session 起動
シームレス度	90% (context 完全維持)	中 (context 失う + ターミナル切替)
公式保証	cwd 永続化 + CLAUDE.md auto-load の動的再ロードで実用化	--worktree flag 公式

A 案で動作する機能 / しない機能

動作する (A 案で OK):

• ✅ Bash の cwd 永続化 (公式仕様)
• ✅ Read / Edit / Write は cwd 配下対象
• ✅ git log / status / commit / push は cwd ベース
• ✅ CLAUDE.md / @import は cwd ベース動的再ロード

動作しない (B 案必要):

• ❌ Skill list は session 起動時 static (worktree 配下のみに追加した skill は認識されない)
• ❌ hook / MCP は session 起動時 static (settings.local.json 差分反映なし)

運用ルール (4 項目)

1. worktree は本体 main の同期 checkout 維持: skill / hook / MCP の追加変更は本体 main で実施
2. タスク実装は worktree で完結: ファイル編集 + git 操作 + commit + push 全て worktree 配下
3. skill / hook / MCP 改修必要時のみ B 案: 別 session 起動 → 改修 → main merge → 本 session 再起動 = 反映
4. 「シームレス分岐」の限定: ファイル + git + CLAUDE.md ガイダンスのシームレス、メタ設定 (skill / hook / MCP) は本体側集約

実行方法

スクリプト実行

${CLAUDE_PLUGIN_ROOT}/skills/worktree-task/scripts/gwt.sh <input> [--tracker jira|backlog]

<input> は plan ファイルパス / GitHub Issue / JIRA / Backlog のいずれか (上記「入力受付仕様」参照)。

重要: スクリプトの出力をそのまま全て表示すること。exit code 3 / 4 (ambiguous_ticket) の場合のみ AskUserQuestion で介入。

スクリプトの動作

gwt.sh が自動的に以下を実行:

1. .env auto-load (project root → ~/.config/worktree-task/.env)
2. 入力 normalize + パターン判別 (case 文 dispatch)
3. ambiguous_ticket 解決 (env 自動判別 / --tracker flag / WORKTREE_TASK_DEFAULT_TRACKER)
4. 必須ツールチェック (gh / jq / curl)
5. tracker 別本文取得 (gh issue view / JIRA REST / Backlog API)
6. task-name 生成 (plan: basename, gh: gh-<num>-<slug>, jira/backlog: <key-lower>-<slug>)
7. .worktrees/<task-name> + feature/<task-name> 作成
8. rsync で Git 管理外のファイル (node_modules, .env, venv など) を同期 ⭐
9. tracker 入力時は .worktrees/<task-name>/PLAN.md を生成 (取得本文 + メタ情報)
10. 次のステップをユーザーに案内

使用例

A 案 (同 session 内 cd 切替) - 推奨フロー (シームレス)

# plan ファイル (既存)
${CLAUDE_PLUGIN_ROOT}/skills/worktree-task/scripts/gwt.sh docs/plans/feature.plan.md

# GitHub Issue (cwd の repo)
${CLAUDE_PLUGIN_ROOT}/skills/worktree-task/scripts/gwt.sh "Issue 20"
${CLAUDE_PLUGIN_ROOT}/skills/worktree-task/scripts/gwt.sh "#20"

# GitHub Issue (別 repo)
${CLAUDE_PLUGIN_ROOT}/skills/worktree-task/scripts/gwt.sh "owner/repo#20"
${CLAUDE_PLUGIN_ROOT}/skills/worktree-task/scripts/gwt.sh "https://github.com/owner/repo/issues/20"

# JIRA (env 設定済時)
${CLAUDE_PLUGIN_ROOT}/skills/worktree-task/scripts/gwt.sh "PROJ-123"

# Backlog (env 設定済時)
${CLAUDE_PLUGIN_ROOT}/skills/worktree-task/scripts/gwt.sh "課題 BLG-456"

# 両方 env 設定 + デフォルト未指定: 明示
${CLAUDE_PLUGIN_ROOT}/skills/worktree-task/scripts/gwt.sh "PROJ-123" --tracker jira

# 後続フロー (共通):
cd .worktrees/<task-name>
# 実装
git add . && git commit -m "..." && git push -u origin feature/<task-name>
gh pr create ...
cd /path/to/repo-root

B 案 (別 session 起動) - skill / hook / MCP 改修時

# 1. worktree + branch 作成 (gwt.sh)
${CLAUDE_PLUGIN_ROOT}/skills/worktree-task/scripts/gwt.sh ...

# 2. 別ターミナルで claude -w 起動
cd .worktrees/heavy-feature && claude

# 3. 別 session で実装、本 session は別タスク並行可

並行処理パターン (B 案応用)

複数タスクを並行処理する場合:

1. メインターミナル: 軽いタスク (ドキュメント更新など)
2. 新しいターミナル: 重いタスク (実装作業) を Worktree で実行 = B 案

自動クリーンアップ

SessionEnd時に自動実行 されるクリーンアップ機能:

• gwt-cleanup.sh が全 worktree をチェック
• main ブランチにマージ済みのブランチを自動削除
• PR マージ後、次回セッション終了時に自動的にクリーンアップされる

手動クリーンアップ (必要な場合のみ)

git worktree remove .worktrees/<task-name>
git branch -d feature/<task-name>

エラーハンドリング

スクリプトがエラーを返した場合のみ、追加の説明を提供。