scion

What this skill does

<!-- ⛔⛔⛔ MANDATORY: READ THIS ENTIRE FILE BEFORE ANY ACTION ⛔⛔⛔ -->

# Git-Town Fork Workflow — STOP AND READ

**DO NOT ACT ON ASSUMPTIONS. Read this file first.**

This is a **prescriptive, gated workflow**. Every step requires:

1. **Preflight check** - Verify preconditions
2. **User confirmation** - AskUserQuestion before action
3. **Validation** - Verify action succeeded

> **Self-Evolving Skill**: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

## ⛔ WORKFLOW PHILOSOPHY

**GIT-TOWN IS CANONICAL. RAW GIT IS FORBIDDEN FOR BRANCH OPERATIONS.**

| Operation     | ✅ Use             | ❌ Never Use            |
| ------------- | ------------------ | ----------------------- |
| Create branch | `git town hack`    | `git checkout -b`       |
| Update branch | `git town sync`    | `git pull`, `git merge` |
| Create PR     | `git town propose` | Manual web UI           |
| Merge PR      | `git town ship`    | `git merge` + push      |
| Switch branch | `git town switch`  | `git checkout`          |

**Exception**: Raw git for commits, staging, log viewing, diff (git-town doesn't replace these).

---

## Phase 0: Preflight — MANDATORY FIRST

**Execute this BEFORE any other action.**

### Step 0.1: Create 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
```

### Step 0.2: Check git-town Installation

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

**If NOT installed:**

```
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
```

If "Yes": Run `brew install git-town`, then re-check.
If "No": **STOP. Do not proceed.**

### Step 0.3: Check GitHub CLI Installation

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

**If NOT installed or NOT authenticated:**

```
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
```

### Step 0.4: Detect Repository Context

**Run detection script BEFORE any AskUserQuestion:**

```bash
/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
```

### Step 0.5: Detect GitHub Account(s)

```bash
/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: mise env (if available)
echo "--- mise env ---"
mise env 2>/dev/null | grep -i github || echo "No GitHub vars in mise"

DETECT_ACCOUNT_EOF
```

---

## Phase 1: GATE — Present Findings

**MANDATORY: Present ALL detection results and get explicit user confirmation.**

### Step 1.1: Synthesize Findings

Create a summary table of detected state:

| Aspect              | Detected Value | Status        |
| ------------------- | -------------- | ------------- |
| Repository          | {owner}/{repo} | ✅/❌         |
| Origin remote       | {url}          | ✅/❌         |
| Upstream remote     | {url}          | ✅/❌/MISSING |
| GitHub account      | {username}     | ✅/❌         |
| git-town configured | yes/no         | ✅/❌         |

### Step 1.2: Determine Workflow Type

```
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
```

### Step 1.3: Confirm Remote URLs (if Fresh 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
```

### Step 1.4: Confirm Fork Destination

```
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
```

### Step 1.5: Final Confirmation Gate

```
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
```

**If "No, abort": STOP. Do not proceed.**

---

## Phase 2: Execute Fork Setup

### Step 2.1: Create Fork (if needed)

**Only if fork doesn't exist:**

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

**Validate:**

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

### Step 2.2: Configure Remotes

**Set origin to fork (SSH preferred):**

```bash
git remote s