scion

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

/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

/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:

/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)

/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:

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

Validate:

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

Step 2.2: Configure Remotes

Set origin to fork (SSH preferred):

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

Add upstream (if missing):

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

Or fix upstream (if wrong):

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

Step 2.3: Initialize 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

---

Phase 3: Validation

Step 3.1: Verify Remote Configuration

/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

Step 3.2: Verify git-town Configuration

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

Expected output should show:

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

Step 3.3: Test 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

If test selected:

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

Step 3.4: Display Workflow Cheatsheet

Always display at end:

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

---

Error Handling

If Fork Creation Fails

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

If Remote Configuration Fails

Display the error and provide manual commands:

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

---

Arguments

• [upstream-url] - Optional: URL of repository to fork
• --check - Only run validation, don't make changes
• --fix - Auto-fix detected issues without prompting

Examples

# Fork a new repository
/git-town-workflow:scion https://github.com/EonLabs-Spartan/alpha-forge

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

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

---

Troubleshooting

Issue	Cause	Solution
gh fork failed	Already forked or no access	Use --check to verify existing fork
Permission denied	SSH key not added to GitHub	Add SSH key or use HTTPS URL
Remote already exists	Origin/upstream already set	Use git remote set-url to update
Fork not detected	Origin URL doesn't match	Check git remote -v for mismatch
Upstream sync fails	Diverged histories	git town sync to reconcile
"Not a fork" error	Repo is origin, not a fork	Fork first via gh repo fork

Post-Execution Reflection

After this skill completes, reflect before closing the task:

0. Locate yourself. — Find this SKILL.md's canonical path (Glob for this skill's name) before editing. All corrections target THIS file and its sibling references/ — never other documentation.
1. What failed? — Fix the instruction that caused it. If it could recur, add it as an anti-pattern.
2. What worked better than expected? — Promote it to recommended practice. Document why.
3. What drifted? — Any script, reference, or external dependency that no longer matches reality gets fixed now.
4. Log it. — Every change gets an evolution-log entry with trigger, fix, and evidence.

Do NOT defer. The next invocation inherits whatever you leave behind.