scion

Git-Town フォークワークフロー — 必ずお読みください

思い込みで作業しないでください。まずこのファイルをお読みください。

これは手順を定め、各段階で確認を求めるワークフローです。各ステップでは、次のすべてが必要です。

1. 事前確認 - 前提条件を確認します
2. ユーザーの確認 - 操作の前に AskUserQuestion を行います
3. 検証 - 操作が成功したことを確認します

進化するスキル：このスキルは使用を通じて改善されます。指示に誤りがある、パラメーターにずれが生じている、または回避策が必要だった場合は、先送りせず、ただちにこのファイルを修正してください。実際に再現できる問題がある場合にのみ更新してください。

⛔ ワークフローの基本方針

GIT-TOWN が正規の手段です。ブランチ操作で RAW GIT を使うことは禁止されています。

操作	✅ 使用する	❌ 決して使用しない
ブランチを作成	git town hack	git checkout -b
ブランチを更新	git town sync	git pull、git merge
PR を作成	git town propose	手動の Web UI
PR をマージ	git town ship	git merge + push
ブランチを切り替え	git town switch	git checkout

例外：コミット、ステージング、ログの表示、diff には raw git を使用できます（git-town はこれらを置き換えません）。

---

フェーズ 0：事前確認 — 必ず最初に実行

ほかの操作を行う前に、これを実行してください。

ステップ 0.1：TodoWrite を作成

TodoWrite with todos:
- "[Fork] Phase 0: Check git-town installation" | in_progress
- "[Fork] Phase 0: Check GitHub CLI installation" | pending
- "[Fork] Phase 0: Detect current repository context" | pending
- "[Fork] Phase 0: Detect existing remotes" | pending
- "[Fork] Phase 0: Detect GitHub account(s)" | pending
- "[Fork] Phase 1: GATE - Present findings and get user confirmation" | pending
- "[Fork] Phase 2: Create fork (if needed)" | pending
- "[Fork] Phase 2: Configure remotes" | pending
- "[Fork] Phase 2: Initialize git-town" | pending
- "[Fork] Phase 3: Validate setup" | pending
- "[Fork] Phase 3: Display workflow cheatsheet" | pending

ステップ 0.2：git-town のインストールを確認

/usr/bin/env bash -c 'which git-town && git-town --version'

インストールされていない場合：

AskUserQuestion with questions:
- question: "git-town is not installed. Would you like to install it now?"
  header: "Install"
  options:
    - label: "Yes, install via Homebrew (Recommended)"
      description: "Run: brew install git-town"
    - label: "No, abort workflow"
      description: "Cannot proceed without git-town"
  multiSelect: false

「Yes」の場合：brew install git-town を実行し、もう一度確認します。「No」の場合：停止してください。先に進まないでください。

ステップ 0.3：GitHub CLI のインストールを確認

/usr/bin/env bash -c 'which gh && gh --version && gh auth status'

インストールされていない、または認証されていない場合：

AskUserQuestion with questions:
- question: "GitHub CLI is required for fork operations. How to proceed?"
  header: "GitHub CLI"
  options:
    - label: "Install and authenticate (Recommended)"
      description: "Run: brew install gh && gh auth login"
    - label: "I'll handle this manually"
      description: "Provide instructions and exit"
  multiSelect: false

ステップ 0.4：リポジトリのコンテキストを検出

AskUserQuestion を行う前に、検出スクリプトを実行してください。

/usr/bin/env bash << 'DETECT_REPO_EOF'
echo "=== REPOSITORY DETECTION ==="

# Check if in git repo
if ! git rev-parse --git-dir &>/dev/null; then
    echo "ERROR: Not in a git repository"
    exit 1
fi

# Detect remotes
echo "--- Existing Remotes ---"
git remote -v

# Detect current branch
echo "--- Current Branch ---"
git branch --show-current

# Detect repo URL patterns
echo "--- Remote URLs ---"
ORIGIN_URL=$(git remote get-url origin 2>/dev/null || echo "NONE")
UPSTREAM_URL=$(git remote get-url upstream 2>/dev/null || echo "NONE")

echo "origin: $ORIGIN_URL"
echo "upstream: $UPSTREAM_URL"

# Parse GitHub owner/repo from URLs
if [[ "$ORIGIN_URL" =~ github\.com[:/]([^/]+)/([^/.]+) ]]; then
    echo "ORIGIN_OWNER=${BASH_REMATCH[1]}"
    echo "ORIGIN_REPO=${BASH_REMATCH[2]%.git}"
fi

if [[ "$UPSTREAM_URL" =~ github\.com[:/]([^/]+)/([^/.]+) ]]; then
    echo "UPSTREAM_OWNER=${BASH_REMATCH[1]}"
    echo "UPSTREAM_REPO=${BASH_REMATCH[2]%.git}"
fi

# Check git-town config
echo "--- Git-Town Config ---"
git town config 2>/dev/null || echo "git-town not configured"

DETECT_REPO_EOF

ステップ 0.5：GitHub アカウントを検出

/usr/bin/env bash << 'DETECT_ACCOUNT_EOF'
echo "=== GITHUB ACCOUNT DETECTION ==="

# Method 1: gh CLI auth status
echo "--- gh CLI Account ---"
GH_USER=$(gh api user --jq '.login' 2>/dev/null || echo "NONE")
echo "gh auth user: $GH_USER"

# Method 2: SSH config
echo "--- SSH Config Hosts ---"
grep -E "^Host github" ~/.ssh/config 2>/dev/null | head -5 || echo "No GitHub SSH hosts"

# Method 3: Git global config
echo "--- Git Global Config ---"
git config --global user.name 2>/dev/null || echo "No global user.name"
git config --global user.email 2>/dev/null || echo "No global user.email"

# Method 4: origin remote host-alias ([email protected]<account>:owner/repo names the account)
echo "--- Origin Host-Alias ---"
git remote get-url origin 2>/dev/null | sed -n 's|.*github\.com-\([A-Za-z0-9_-]*\):.*|\1|p' | grep . || echo "No host-alias on origin"

DETECT_ACCOUNT_EOF

---

フェーズ 1：確認 — 検出結果を提示

必須：検出結果をすべて提示し、ユーザーから明示的な確認を得てください。

ステップ 1.1：検出結果をまとめる

検出された状態の概要表を作成します。

項目	検出値	状態
リポジトリ	{owner}/{repo}	✅/❌
origin リモート	{url}	✅/❌
upstream リモート	{url}	✅/❌/MISSING
GitHub アカウント	{username}	✅/❌
git-town の設定	yes/no	✅/❌

ステップ 1.2：ワークフローの種類を判定

AskUserQuestion with questions:
- question: "What fork workflow do you need?"
  header: "Workflow"
  options:
    - label: "Fresh fork - Create new fork from upstream"
      description: "You want to fork someone else's repo to contribute"
    - label: "Fix existing - Reconfigure existing fork's remotes"
      description: "Origin/upstream are misconfigured, need to fix"
    - label: "Verify only - Check current setup is correct"
      description: "Just validate, don't change anything"
  multiSelect: false

ステップ 1.3：リモート URL を確認（新しいフォークの場合）

AskUserQuestion with questions:
- question: "Confirm the upstream repository (the original you're forking FROM):"
  header: "Upstream"
  options:
    - label: "{detected_upstream_owner}/{detected_upstream_repo} (Detected)"
      description: "Detected from current remotes"
    - label: "Enter different URL"
      description: "I want to fork a different repository"
  multiSelect: false

ステップ 1.4：フォーク先を確認

AskUserQuestion with questions:
- question: "Where should the fork be created?"
  header: "Fork Owner"
  options:
    - label: "{gh_auth_user} (Your account - Recommended)"
      description: "Fork to your personal GitHub account"
    - label: "Organization account"
      description: "Fork to a GitHub organization you have access to"
  multiSelect: false

ステップ 1.5：最終確認

AskUserQuestion with questions:
- question: "Ready to proceed with fork setup?"
  header: "Confirm"
  options:
    - label: "Yes, create/configure fork"
      description: "Proceed with: upstream={upstream_url}, fork_owner={fork_owner}"
    - label: "No, abort"
      description: "Cancel and make no changes"
  multiSelect: false

「No, abort」の場合：停止してください。先に進まないでください。

---

フェーズ 2：フォークを設定

ステップ 2.1：フォークを作成（必要な場合）

フォークが存在しない場合のみ：

/usr/bin/env bash -c 'gh repo fork {upstream_owner}/{upstream_repo} --clone=false --remote=false'

検証：

/usr/bin/env bash -c 'gh repo view {fork_owner}/{repo} --json url'

ステップ 2.2：リモートを設定

origin をフォークに設定（SSH を推奨）：

git remote set-url origin [email protected]:{fork_owner}/{repo}.git

upstream を追加（存在しない場合）：

git remote add upstream [email protected]:{upstream_owner}/{repo}.git

または upstream を修正（誤っている場合）：

git remote set-url upstream [email protected]:{upstream_owner}/{repo}.git

ステップ 2.3：git-town を初期化

/usr/bin/env bash << 'INIT_GITTOWN_EOF'
# Initialize git-town with fork settings
git town config setup

# Ensure sync-upstream is enabled
git config git-town.sync-upstream true

# Set dev-remote to origin (your fork)
git config git-town.dev-remote origin

INIT_GITTOWN_EOF

---

フェーズ 3：検証

ステップ 3.1：リモート設定を確認

/usr/bin/env bash << 'VALIDATE_REMOTES_EOF'
echo "=== REMOTE VALIDATION ==="

ORIGIN=$(git remote get-url origin)
UPSTREAM=$(git remote get-url upstream)

echo "origin: $ORIGIN"
echo "upstream: $UPSTREAM"

# Validate origin points to fork owner
if [[ "$ORIGIN" =~ {fork_owner} ]]; then
    echo "✅ origin correctly points to your fork"
else
    echo "❌ origin does NOT point to your fork"
    exit 1
fi

# Validate upstream points to original
if [[ "$UPSTREAM" =~ {upstream_owner} ]]; then
    echo "✅ upstream correctly points to original repo"
else
    echo "❌ upstream does NOT point to original repo"
    exit 1
fi

VALIDATE_REMOTES_EOF

ステップ 3.2：git-town の設定を確認

/usr/bin/env bash -c 'git town config'

次の出力が表示されることを確認してください。

• sync-upstream: true
• dev-remote: origin

ステップ 3.3：git-town sync をテスト

AskUserQuestion with questions:
- question: "Run a test sync to verify everything works?"
  header: "Test"
  options:
    - label: "Yes, run git town sync --dry-run"
      description: "Preview what sync would do (safe)"
    - label: "Yes, run git town sync for real"
      description: "Actually sync branches"
    - label: "Skip test"
      description: "I'll test manually later"
  multiSelect: false

テストが選択された場合：

git town sync --dry-run  # or without --dry-run

ステップ 3.4：ワークフローのチートシートを表示

最後に必ず表示してください。

## ✅ Fork Workflow Configured Successfully

### Daily Commands (USE THESE, NOT RAW GIT)

| Task                  | Command                      |
| --------------------- | ---------------------------- |
| Create feature branch | `git town hack feature-name` |
| Update all branches   | `git town sync`              |
| Create PR to upstream | `git town propose`           |
| Merge approved PR     | `git town ship`              |
| Switch branches       | `git town switch`            |

### ⚠️ FORBIDDEN (Will Break Workflow)

| ❌ Never Use           | ✅ Use Instead                     |
| ---------------------- | ---------------------------------- |
| `git checkout -b`      | `git town hack`                    |
| `git pull`             | `git town sync`                    |
| `git merge`            | `git town sync` or `git town ship` |
| `git push origin main` | `git town sync`                    |

### Quick Reference

- **Sync with upstream**: `git town sync` (automatic)
- **Create stacked branches**: `git town append child-feature`
- **Undo last git-town command**: `git town undo`
- **See branch hierarchy**: `git town branch`

---

エラー処理

フォークの作成に失敗した場合

AskUserQuestion with questions:
- question: "Fork creation failed. How to proceed?"
  header: "Error"
  options:
    - label: "Retry"
      description: "Try creating the fork again"
    - label: "Fork exists - configure existing"
      description: "Fork already exists, just configure remotes"
    - label: "Abort"
      description: "Cancel and investigate manually"
  multiSelect: false

リモートの設定に失敗した場合

エラーを表示し、手動で実行するコマンドを提示します。

# Manual fix commands:
git remote set-url origin [email protected]:{fork_owner}/{repo}.git
git remote add upstream [email protected]:{upstream_owner}/{repo}.git

---

引数

• [upstream-url] - 任意：フォーク元リポジトリの URL
• --check - 検証のみ実行し、変更は加えません
• --fix - 確認を求めず、検出した問題を自動修正します

例

# Fork a new repository
/git-town-workflow:scion https://github.com/example-org/research-repo

# Check existing fork setup
/git-town-workflow:scion --check

# Auto-fix misconfigured remotes
/git-town-workflow:scion --fix

---

トラブルシューティング

問題	原因	解決策
gh fork failed	すでにフォーク済み、またはアクセス権がありません	--check を使って既存のフォークを確認します
Permission denied	SSH キーが GitHub に追加されていません	SSH キーを追加するか、HTTPS URL を使います
Remote already exists	Origin/upstream がすでに設定されています	git remote set-url を使って更新します
Fork not detected	Origin URL が一致しません	git remote -v で不一致を確認します
Upstream sync fails	履歴が分岐しています	git town sync で調整します
"Not a fork" error	リポジトリは origin であり、フォークではありません	まず gh repo fork でフォークします

実行後の振り返り

このスキルの実行が完了したら、タスクを終了する前に振り返ります。

0. 現在の場所を確認します。 — 編集前に、この SKILL.md の正規パスを確認します（このスキルの名前で Glob を実行します）。修正対象はこのファイルと兄弟の references/ のみです。他のドキュメントは対象にしません。
1. 何が失敗しましたか？ — 原因となった指示を修正します。再発する可能性がある場合は、アンチパターンとして追加します。
2. 予想以上にうまくいったことは何ですか？ — 推奨プラクティスとして取り入れます。その理由も記録します。
3. 何が現状とずれていましたか？ — 実態に合わなくなったスクリプト、リファレンス、外部依存関係は、今すぐ修正します。
4. 記録します。 — 変更のたびに、きっかけ、修正内容、根拠を含む進化ログのエントリーを追加します。

先送りしないでください。次回の実行では、残された状態が引き継がれます。