Setup

Pre-flight check and installer for the WTF workflow. Validates the GitHub CLI, installs required extensions, ensures .github/ISSUE_TEMPLATE/ contains all required templates, creates all lifecycle labels, and installs the PR template so both agents and humans can create structured issues and pull requests.

Process

1. Verify gh is installed

gh --version

If not found: tell the user that the GitHub CLI is required, link them to https://cli.github.com, and stop. Do not proceed until gh is confirmed installed.

2. Verify gh is authenticated

gh auth status

If not authenticated: tell the user to run gh auth login and stop. Do not proceed until authentication is confirmed.

3. Check and install required extensions

gh extension list

Check the output for both of the following extensions. For each that is missing, install it:

# Sub-issue hierarchy (epic → feature → task)
gh extension install yahsan2/gh-sub-issue

# Issue dependency tracking (X blocks Y)
gh extension install xiduzo/gh-issue-dependency

If installation fails (e.g. network error, permissions), warn the user that relationship tracking will be unavailable until the extension is installed. Note the failure — it will be included in the final status report.

After attempting installation, verify the command syntax for any newly installed extension:

gh sub-issue --help
gh issue-dependency --help

Record two booleans for the final report:

• gh-sub-issue-available: true if yahsan2/gh-sub-issue is installed and working
• gh-issue-dependency-available: true if xiduzo/gh-issue-dependency is installed and working

4. Detect repo context

gh repo view --json nameWithOwner -q .nameWithOwner

If this fails (not inside a git repo, or no GitHub remote), warn the user and note that issue creation will not work until the repo is connected to GitHub. Continue to the template check regardless.

4b. Verify GitHub permissions

The workflow requires the authenticated user to manage labels and create issue relationships (sub-issues, dependencies). Both need write access to the repo and a token with the repo scope (or public_repo for public repos).

Check token scopes:

gh auth status 2>&1 | grep -i "token scopes"

Required scopes (any of):

• repo — full control (private + public repos)
• public_repo — sufficient for public repos only

If neither scope is present, instruct the user to refresh auth with the right scopes:

gh auth refresh -h github.com -s repo

…and stop until re-run.

Check repo write permission:

gh api "repos/$(gh repo view --json nameWithOwner -q .nameWithOwner)" \
  --jq '.permissions | {admin, maintain, push, triage, pull}'

The user must have admin: true, maintain: true, or push: true. If only triage or pull, warn:

⚠️ You have read-only access to this repo. Label creation and issue linking will fail. Ask a maintainer for write access or fork the repo.

Record two booleans for the final report:

• token-scopes-ok: true if repo or public_repo scope present
• repo-write-ok: true if admin, maintain, or push is true

If either is false, skip label creation in step 7 and warn that sub-issue / dependency creation will fail at runtime.

5. Check issue templates

Check whether .github/ISSUE_TEMPLATE/ exists and contains all four required templates:

ls .github/ISSUE_TEMPLATE/

Required files:

• BUG.md
• EPIC.md
• FEATURE.md
• TASK.md

For each missing file, copy it from this skill's bundled references:

mkdir -p .github/ISSUE_TEMPLATE

# Copy each missing template from the skill's references folder.
# The references folder is at: skills/wtf.setup/references/
cp skills/wtf.setup/references/BUG.md .github/ISSUE_TEMPLATE/BUG.md
cp skills/wtf.setup/references/EPIC.md .github/ISSUE_TEMPLATE/EPIC.md
cp skills/wtf.setup/references/FEATURE.md .github/ISSUE_TEMPLATE/FEATURE.md
cp skills/wtf.setup/references/TASK.md .github/ISSUE_TEMPLATE/TASK.md

Only copy files that are missing — do not overwrite existing templates. After copying, list the final contents of .github/ISSUE_TEMPLATE/ to confirm.

6. Check PR template

Check whether .github/pull_request_template.md exists:

ls .github/pull_request_template.md 2>/dev/null

If missing, copy it from the skill's bundled references:

cp skills/wtf.setup/references/pull_request_template.md .github/pull_request_template.md

Do not overwrite if it already exists.

7. Create required GitHub labels

Create all lifecycle labels the workflow depends on. Using --force makes the command idempotent — it updates the description/color if the label already exists and creates it if it does not:

gh label create epic        --color 5319e7 --description "Strategic initiative spanning multiple features"      --force
gh label create feature     --color 0075ca --description "User-facing capability delivered as a vertical slice" --force
gh label create task        --color e4e669 --description "Implementable vertical slice of a Feature"            --force
gh label create bug         --color d73a4a --description "Something is broken"                                  --force
gh label create implemented --color 0e8a16 --description "Implementation complete — ready for QA"              --force
gh label create designed    --color f9d0c4 --description "Design coverage added to the Task"                   --force
gh label create verified    --color 006b75 --description "QA verified — ready for merge"                       --force

If any label creation fails (e.g. insufficient permissions), warn the user — note that the affected skills will fall back to creating labels on first use.

Closing convention: GitHub has no native setting to require PR-based closure, so this is enforced by skill behavior. Issues are only "closed as completed" when a merged PR contains Closes #<n>. Direct gh issue close calls are reserved for --reason "not planned" (won't implement) and --reason "duplicate" only. Surface this convention in the status report.

8. Install intervention-tracker hook

The tracker hook counts user corrections and nudges toward /wtf.reflect. skills.sh copies the hook script into the skill dir, but the hook must be registered in Claude Code's settings.json manually.

Step A — locate the installed hook script. Probe, in order, and keep the first that exists:

for cand in \
  "$HOME/.claude/skills/wtf.setup/hooks/track-interventions.sh" \
  "$PWD/.claude/skills/wtf.setup/hooks/track-interventions.sh" \
  "$PWD/skills/wtf.setup/hooks/track-interventions.sh"; do
  [ -f "$cand" ] && HOOK_PATH="$cand" && break
done

If none exist: warn the user that the hook script could not be found and skip hook registration.

Step B — ask scope (apply ../references/questioning-style.md):

Call AskUserQuestion (per ../references/questioning-style.md):

• question: "Install the WTF intervention-tracker hook globally or only for this repo?"
• header: "Hook scope"
• options:
  • Global (~/.claude/settings.json) → runs in every repo that has docs/steering/
  • This repo only (.claude/settings.json) → scoped to this project
  • Skip → don't install the hook

Set SETTINGS_FILE accordingly:

• Global → $HOME/.claude/settings.json
• Per-repo → .claude/settings.json
• Skip → jump to step 9.

Step C — patch settings.json idempotently. Create the file if missing (echo '{}' > "$SETTINGS_FILE"). Then merge the two hook entries using python3 (available on macOS/Linux; git-bash on Windows ships it via the installer or can be swapped for py):

HOOK_CMD="sh $HOOK_PATH"
python3 - "$SETTINGS_FILE" "$HOOK_CMD" <<'PY'
import json, sys, pathlib
path, cmd = sys.argv[1], sys.argv[2]
p = pathlib.Path(path)
data = json.loads(p.read_text()) if p.exists() and p.read_text().strip() else {}
hooks = data.setdefault("hooks", {})
for event in ("UserPromptSubmit", "Stop"):
    arr = hooks.setdefault(event, [])
    exists = any(
        any(h.get("command") == cmd for h in entry.get("hooks", []))
        for entry in arr
    )
    if not exists:
        arr.append({"matcher": "", "hooks": [{"type": "command", "command": cmd}]})
p.write_text(json.dumps(data, indent=2))
PY

Re-running is safe — existing entries are detected by exact command string and not duplicated.

Windows note: if the user is on Windows without python3, skip the patch and print the JSON snippet for manual paste. Detect via command -v python3 >/dev/null || echo 'manual'.

Record hook-installed: true|false|skipped for the status report.

9. Report status

Print a clear status summary covering every check:

WTF Setup — Status Report
─────────────────────────
gh CLI installed          ✅
gh authenticated          ✅
gh-sub-issue extension    ✅  (or ⚠️ not installed — relationship links unavailable)
gh-issue-dependency ext   ✅  (or ⚠️ not installed — dependency links unavailable)
Repo context              ✅  owner/repo  (or ⚠️ not detected)
Token scopes              ✅  repo  (or ⚠️ missing — run `gh auth refresh -s repo`)
Repo write permission     ✅  push/maintain/admin  (or ⚠️ read-only — labels & links will fail)
Issue templates
  BUG.md                  ✅  (or ✅ installed from references)
  EPIC.md                 ✅  (or ✅ installed from references)
  FEATURE.md              ✅  (or ✅ installed from references)
  TASK.md                 ✅  (or ✅ installed from references)
PR template               ✅  (or ✅ installed from references)
GitHub labels             ✅  epic, feature, task, bug, implemented, designed, verified
Intervention hook         ✅  installed (global)  (or  ✅ installed (repo)  /  ⚪ skipped  /  ⚠️ manual paste required)
─────────────────────────
Ready to use WTF. Start with `wtf.write-epic` to plan your first initiative.

If any item failed (gh not installed, not authenticated), replace the closing line with a clear "Fix the issues above before proceeding." and do not suggest next steps.

10. Offer to set up steering docs

If setup completed without fatal errors, call AskUserQuestion (per ../references/questioning-style.md):

• question: "Setup complete. The steering docs (VISION.md, TECH.md, DESIGN.md, QA.md) capture your project's principles and standards — every skill reads them automatically. Would you like to create them now?"
• header: "Steering docs"
• options:
  • Yes — set them up now → run wtf.steer-vision (it will offer to chain to TECH, DESIGN, and QA at the end)
  • Not now → skip; skills will prompt you to create them on first use