xiduzo/wtf/wtf-setup

Setup

Pre-flight check and installer for the WTF workflow.

Validate the GitHub CLI. Install required extensions. Make sure .github/ISSUE_TEMPLATE/ holds all required templates.

Set up issue classification (native GitHub issue types or labels) and the lifecycle labels.

Install the PR template. Agents and humans can then create structured issues and pull requests.

Process

1. Verify gh is installed

gh --version

If gh is not found, tell the user that the GitHub CLI is required. Link them to https://cli.github.com. Stop. Do not continue until gh is installed.

2. Verify gh is authenticated

gh auth status

If gh is not authenticated, tell the user to run gh auth login. Stop. Do not continue until authentication is confirmed.

3. Check and install required extensions

gh extension list

Check the output for all three extensions below. If an extension is missing, install it:

# Sub-issue hierarchy (epic → feature → trace)
gh extension install yahsan2/gh-sub-issue
 
# Issue dependency tracking (X blocks Y)
gh extension install xiduzo/gh-issue-dependency
 
# Native stacked PRs (Trace stacks)
gh extension install github/gh-stack

If installation fails (for example network error or permissions), warn the user. Note the failure for the final status report. Without gh-sub-issue or gh-issue-dependency, relationship tracking stays unavailable until the extension is installed. Without gh-stack, Trace PRs still stack by base branch, but GitHub renders no stack map. wtf.create-pr then keeps the "stacked PR" note in the PR body (see ../references/branch-setup.md "Native stacks").

After you try installation, verify the command syntax for each newly installed extension:

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

Record three 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
• gh-stack-available: true if github/gh-stack 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. Note that issue creation will not work until the repo is connected to GitHub. Continue to the template check anyway.

4b. Verify GitHub permissions

The workflow needs the authenticated user to manage labels and create issue relationships (sub-issues, dependencies).

Both need write access to the repo. The token needs 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, tell the user to refresh auth with the right scopes:

gh auth refresh -h github.com -s repo

Stop until the user re-runs setup.

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 the user has 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 is present
• repo-write-ok: true if admin, maintain, or push is true

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

5. Check issue templates

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

ls .github/ISSUE_TEMPLATE/

Required files:

• BUG.md
• EPIC.md
• FEATURE.md
• TRACE.md

First resolve where this skill's payload is installed. npx skills add drops wtf.setup under the skills root (~/.claude/skills/wtf.setup, .claude/skills/wtf.setup, or the .agents/skills equivalent). The bundled files (references/, shared-references/, hooks/) are included inside it.

Probe in order. Keep the first that exists. Reuse $SETUP_DIR for every copy below:

for cand in \
  "$HOME/.claude/skills/wtf.setup" \
  "$HOME/.agents/skills/wtf.setup" \
  "$PWD/.claude/skills/wtf.setup" \
  "$PWD/.agents/skills/wtf.setup" \
  "$PWD/skills/wtf.setup"; do
  [ -d "$cand/references" ] && SETUP_DIR="$cand" && break
done

For each missing file, copy it from this skill's bundled references at $SETUP_DIR/references/:

mkdir -p .github/ISSUE_TEMPLATE
cp "$SETUP_DIR/references/BUG.md"     .github/ISSUE_TEMPLATE/BUG.md
cp "$SETUP_DIR/references/EPIC.md"    .github/ISSUE_TEMPLATE/EPIC.md
cp "$SETUP_DIR/references/FEATURE.md" .github/ISSUE_TEMPLATE/FEATURE.md
cp "$SETUP_DIR/references/TRACE.md"   .github/ISSUE_TEMPLATE/TRACE.md

Copy only files that are missing. Do not overwrite existing templates. After copying, list the final contents of .github/ISSUE_TEMPLATE/ to confirm.

Legacy `TASK.md`. If .github/ISSUE_TEMPLATE/TASK.md exists, it is a leftover: WTF write paths create Traces, not Tasks. Existing Task issues stay readable (legacy reads in ../references/issue-classification.md). Call AskUserQuestion (per ../references/questioning-style.md):

• question: "A legacy Task template is present. Remove it?"
• header: "Legacy template"
• options:
• Remove it (recommended) → git rm .github/ISSUE_TEMPLATE/TASK.md
• Keep it → note it in the status report

6. Check PR template

Check whether .github/pull_request_template.md exists:

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

If it is missing, copy it from the skill's bundled references (use $SETUP_DIR from step 5):

cp "$SETUP_DIR/references/pull_request_template.md" .github/pull_request_template.md

Do not overwrite the file if it already exists.

7. Choose the issue-classification mode and provision it

WTF classifies every issue as an Epic, Feature, Trace, or Bug.

There are two mechanisms. One is native GitHub issue types (an organization-only feature). That leaves labels free for your own segmentation. The other is the epic/feature/trace/bug labels (portable to any repo).

See ../references/issue-classification.md. Pick the mode once here. Record it in .wtf/config.json so every skill resolves it the same way. Lifecycle labels (implemented, designed, verified) are always created in both modes.

Step A — detect the owner type:

OWNER=$(gh repo view --json owner -q .owner.login)
OWNER_TYPE=$(gh api "users/$OWNER" --jq '.type' 2>/dev/null)   # "User" or "Organization"

Step B — pick the mode.

• If OWNER_TYPE is not Organization (a personal account, or detection failed): native issue types are unavailable. GitHub gates them to organizations. Set CLASS_MODE=labels and tell the user plainly: "This is a personal-account repo, so GitHub issue types are not available (they are org-only). WTF will classify with the `epic`/`feature`/`trace`/`bug` labels." Skip to Step D.

• If OWNER_TYPE is Organization and repo-write-ok and token-scopes-ok (from step 4b) are both true, call AskUserQuestion (per ../references/questioning-style.md):
• question: "This repo is in an org, so WTF can classify issues with native GitHub issue types (Epic/Feature/Trace/Bug) instead of labels — leaving labels free for your own segmentation like phase-2. Use native issue types?"
• header: "Classification"
• options:
• Native issue types (recommended) → CLASS_MODE=types
• Labels → CLASS_MODE=labels

If write or token permissions are missing, do not offer types. Provisioning needs org-owner rights. Set CLASS_MODE=labels and note it.

Step C — provision native types (only when CLASS_MODE=types).

Run the Provision native types block from ../references/issue-classification.md. It creates Epic and Trace (Task/Bug/Feature ship as org defaults — the Task default stays unused).

Then verify all four resolved. If any is missing (for example you are not an org owner), fall back to labels:

HAVE=$(gh api "orgs/$OWNER/issue-types" --jq '[.[].name]' 2>/dev/null)
for t in Epic Feature Trace Bug; do
  printf '%s' "$HAVE" | grep -qi "\"$t\"" || { echo "⚠️ could not provision issue type: $t — falling back to labels"; CLASS_MODE=labels; }
done

When this falls back, warn that native types need org-owner rights. WTF will use labels instead.

Step D — create labels. Always create the lifecycle labels.

Create the kind labels (epic/feature/trace/bug) only in `labels` mode. In types mode omit them on purpose so the label space stays free for your own segmentation.

--force is idempotent. It updates color/description if the label already exists. Otherwise it creates the label:

# Lifecycle labels — always, both modes:
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 Trace"     --force
gh label create verified    --color 006b75 --description "QA verified — ready for merge"          --force
 
# Kind labels — labels mode only:
if [ "$CLASS_MODE" = labels ]; then
  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 trace   --color e4e669 --description "One pass over a Feature's spine — one story, one Scenario Claim, end-to-end" --force
  gh label create bug     --color d73a4a --description "Something is broken"                                  --force
fi

If any label creation fails (for example insufficient permissions), warn the user. The affected skills fall back to creating labels on first use.

Step D (cont.) — align the issue templates with the mode.

In types mode, rewrite each copied .github/ISSUE_TEMPLATE/*.md. Make its kind come from the native type rather than a label.

Flip the labels: <kind> frontmatter line to type: <Kind>. (type is a supported template frontmatter key alongside title/labels/assignees.)

This keeps issues opened manually from the GitHub UI typed, not labelled. The label space stays free.

In labels mode leave the templates as they are. The rewrite is conservative. It only touches an exact single labels: <kind> line. Customized multi-label templates are left alone:

if [ "$CLASS_MODE" = types ]; then
  python3 - <<'PY'
import re, pathlib
kinds = {"BUG": ("bug", "Bug"), "EPIC": ("epic", "Epic"), "FEATURE": ("feature", "Feature"), "TRACE": ("trace", "Trace")}
d = pathlib.Path(".github/ISSUE_TEMPLATE")
for fname, (lbl, typ) in kinds.items():
    p = d / f"{fname}.md"
    if not p.exists():
        continue
    text = p.read_text()
    new = re.sub(rf'(?m)^labels:\s*{lbl}\s*$', f'type: {typ}', text)
    if new != text:
        p.write_text(new)
        print(f"  {fname}.md: labels: {lbl} -> type: {typ}")
PY
fi

Step E — record the mode so every skill resolves it the same way:

mkdir -p .wtf
python3 - ".wtf/config.json" "$CLASS_MODE" <<'PY'
import json, sys, pathlib
path, mode = 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 {}
data["classification"] = mode
p.write_text(json.dumps(data, indent=2) + "\n")
PY