scion

Git-Town Fork 工作流 — 停下并阅读

不要凭假设行事。请先阅读此文件。

这是一个规定性、设有门禁的工作流。每个步骤都要求：

1. 预检 - 验证前置条件
2. 用户确认 - 执行操作前使用 AskUserQuestion 询问
3. 验证 - 确认操作成功

自我进化的技能：此技能会在使用过程中不断改进。如果说明有误、参数发生偏移，或需要变通方案，请立即修复此文件，不要拖延。只针对真实且可复现的问题进行更新。

⛔ 工作流原则

GIT-TOWN 是唯一规范。禁止使用原始 GIT 执行分支操作。

操作	✅ 使用	❌ 绝不使用
创建分支	git town hack	git checkout -b
更新分支	git town sync	git pull、git merge
创建 PR	git town propose	手动使用网页界面
合并 PR	git town ship	git merge + push
切换分支	git town switch	git checkout

例外：提交、暂存、查看日志和差异时可使用原始 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}	✅/❌/缺失
GitHub 账户	{username}	✅/❌
git-town 已配置	是/否	✅/❌

步骤 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（如果是新 Fork）

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：确认 Fork 目标

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：执行 Fork 设置

步骤 2.1：创建 Fork（如有需要）

仅当 Fork 尚不存在时：

/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 设置为 Fork（优先使用 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 同步

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`

---

错误处理

如果创建 Fork 失败

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] - 可选：要 Fork 的仓库 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 失败	已经创建过 fork 或没有访问权限	使用 --check 验证是否已有 fork
权限被拒绝	尚未将 SSH 密钥添加到 GitHub	添加 SSH 密钥或使用 HTTPS URL
远程仓库已存在	已设置 origin/upstream	使用 git remote set-url 更新
未检测到 Fork	Origin URL 不匹配	检查 git remote -v 是否存在不匹配
上游同步失败	历史记录已分叉	使用 git town sync 进行协调
“不是 Fork”错误	仓库是 origin，而不是 Fork	先通过 gh repo fork 创建 Fork

执行后的反思

此技能完成后，请在结束任务前进行反思：

0. 确认位置。 — 在编辑前找到此 SKILL.md 的规范路径（使用 Glob 搜索此技能名称）。所有修正都针对此文件及其同级的 references/ — 绝不要修改其他文档。
1. 什么失败了？ — 修复导致问题的指令。如果问题可能再次发生，将其作为反模式添加。
2. 哪些做得比预期更好？ — 将其提升为推荐实践，并记录原因。
3. 哪些内容偏离了？ — 如果脚本、参考资料或外部依赖不再符合实际情况，请立即修正。
4. 记录下来。 — 每项更改都要在演进日志中记录触发原因、修复内容和证据。

不要推迟。下一次调用会继承你留下的一切。