xiduzo/wtf / skills/wtf.setup
wtf.setup
VerifiedThis skill should be used when a user wants to set up WTF in a repository or check that the environment is ready for it — for example "set up wtf", "is wtf ready", "install wtf templates", or "a new dev joined, set them up". Verifies the GitHub CLI and its auth, installs the required gh extensions and the issue and PR templates, configures issue classification, planning, feature scope, and delivery mode, and registers the hooks. Run once per repo when onboarding, or when a contributor joins the project.
shared-references/gh-setup.md
View on GitHub# GitHub CLI Setup
Run this check at the start of any wtf skill that creates or links GitHub issues. Every calling skill has an identical step 0:
```
### 0. GitHub CLI setup
Run `../references/gh-setup.md`. Stop if `gh` is not installed or not authenticated.
```
## When to skip
Skip this entire step if **any** of the following is true:
- The calling orchestrator already ran gh-setup this session (e.g. `wtf.epic-to-features` → `wtf.write-feature`, `wtf.implement-trace` → `wtf.verify-trace`). The orchestrator passes the confirmation when it does not ask again.
- A prior wtf skill in the same session ran gh-setup and succeeded.
- The skill re-invokes itself in a loop (e.g. "Write next Trace" → restart from step 2).
## Which sections apply to which skills
- **Sections 1–2 (install + auth):** all skills — hard stop if either fails.
- **Sections 3–4 (extensions):** only skills that create or traverse native sub-issue/dependency links (`wtf.write-epic`, `wtf.write-feature`, `wtf.write-trace`, `wtf.loop`, `wtf.refine`, `wtf.epic-to-features`, `wtf.feature-to-traces`). Other skills (`wtf.verify-trace`, `wtf.create-pr`, `wtf.report-bug`, `wtf.design-trace`, `wtf.design-feature`, `wtf.pr-review`, `wtf.changelog`, `wtf.spike`, `wtf.retro`, `wtf.health`, `wtf.hotfix`) may skip these — they do not rely on the extensions. `wtf.create-pr` runs section 3 for `gh-stack` only, when the PR base is a `trace/*` branch.
- **Section 5 (repo detect):** run if the skill needs the `<owner>/<repo>` pair (wiki sync, repo-scoped queries).
## 1. Verify `gh` is installed
```bash
gh --version
```
If not found: tell the user `gh` CLI is required and link them to https://cli.github.com. Stop. Do not continue.
## 2. Verify `gh` is authenticated
```bash
gh auth status
```
If not authenticated: tell the user to run `gh auth login` and stop. Do not continue until authentication is confirmed.
## 3. Check and install required extensions
```bash
gh extension list
```
Check the output for all three extensions below. For each that is missing, install it:
```bash
# 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 `gh-stack` fails to install, Trace PRs still stack by base branch. `wtf.create-pr` then keeps the "stacked PR" note in the PR body. See `./branch-setup.md` "Native stacks".
If `gh-sub-issue` or `gh-issue-dependency` fails to install (e.g. network error, permissions), warn the user that relationship tracking is unavailable until the extension is installed. **Do not fall back to writing `Depends on #X` or `Blocks #Y` into issue bodies** — body-text relationship references are not used in this workflow.
After this step, record three booleans for use in the rest of the session:
- `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
All callers use the first two flags when they decide whether to create native links. `wtf.create-pr` and `wtf.loop` use `gh-stack-available` when they decide whether to link a native stack.
## 4. Confirm command syntax (first install only)
After you install an extension for the first time, verify the available commands:
```bash
gh sub-issue --help
gh issue-dependency --help
gh stack --help
```
Skip this step on later sessions if the extensions already work. Use the output to confirm the exact flag names. The appendix below shows the call shapes WTF uses. If the `--help` output shows different flags, use those instead.
## 5. Detect repo context
```bash
gh repo view --json nameWithOwner -q .nameWithOwner
```
Store the result as `<owner>/<repo>` for all later extension calls in this session.
## Appendix — Sub-issue, dependency, and stack cookbook
Canonical call shapes for the two extensions installed above. Skills cite this section rather than re-document the patterns.
All commands assume `gh-sub-issue-available` / `gh-issue-dependency-available` is true. When false, do not write `Depends on #X` / `Blocks #Y` into issue bodies. Warn the user that relationship tracking is unavailable.
### Hierarchy — `gh sub-issue`
```bash
# List child sub-issues of a parent (default relation: children):
gh sub-issue list <parent_number>
# Find the parent of a sub-issue:
gh sub-issue list <child_number> --relation parent --json number --jq '.[0].number'
# List siblings:
gh sub-issue list <issue_number> --relation siblings
# Filter by state, JSON-shaped output:
gh sub-issue list <parent_number> --state closed --json number,title,state
# Link an existing issue as a child:
gh sub-issue add <parent_number> <child_number>
```
Typical wtf usage:
| Caller | Call | Purpose |
|---|---|---|
| `wtf.write-feature` | `gh sub-issue add <epic> <feature>` | Link new Feature under Epic |
| `wtf.write-trace` | `gh sub-issue add <feature> <trace>` | Link new Trace under Feature |
| `wtf.feature-to-traces` | `gh sub-issue list <feature> --relation parent` | Find parent Epic |
| `wtf.epic-to-features` | `gh sub-issue list <epic>` | List existing Features |
| `wtf.verify-trace` Full Feature | `gh sub-issue list <feature>` | Authoritative Trace list (plus legacy Tasks) |
| `wtf.loop` | `gh sub-issue list <epic>` then per-Feature | Walk the full DAG |
| `wtf.changelog` | `gh sub-issue list <epic>` then per-Feature | Walk closed work |
### Dependencies — `gh issue-dependency`
```bash
# Mark <issue> as blocked by one or more issues:
gh issue-dependency add <issue_number> --blocked-by <blocker1>,<blocker2>
# Mark <issue> as blocking one or more issues:
gh issue-dependency add <issue_number> --blocks <blocked1>,<blocked2>
# List dependency edges in both directions:
gh issue-dependency list <issue_number>
# Cross-repository dependency:
gh issue-dependency add <issue_number> --blocked-by owner/other-repo#<n>
```
Typical wtf usage:
| Caller | Call | Purpose |
|---|---|---|
| `wtf.write-epic` | `gh issue-dependency add <epic> --blocked-by <n>` | Record Epic-level dependency |
| `wtf.write-feature` | `gh issue-dependency add <feature> --blocked-by <n>` | Record sibling-feature dep |
| `wtf.write-trace` | `gh issue-dependency add <trace> --blocked-by <n>` | Cross-feature trace dep |
| `wtf.loop` step 1 | `gh issue-dependency list <n>` per node | Build DAG for topo sort |
For the full traversal pattern (Trace → Feature → Epic walk), see `./spec-hierarchy.md`. Do not reimplement that walk per skill.
### Stacks — `gh stack`
WTF links stacks on GitHub without local tracking. Do not use `gh stack init`, `add`, or `submit` for Trace branches. The Trace branches already exist, and `wtf.create-pr` opens their PRs.
```bash
# Link open PRs into one stack on GitHub, bottom to top. Creates the stack or
# updates it. PRs already in the stack stay in it.
gh stack link <bottom-pr> <next-pr> ... <top-pr>
# Append to an existing stack by its number (shown in the GitHub stack UI):
gh stack link <stack-number> <new-pr>
# Remove the stack grouping on GitHub. The PRs stay open. GitHub keeps PRs
# that are queued for merge or have auto-merge on in the stack.
gh stack unstack <stack-number>
# Merge every layer up to a PR in one atomic operation (interactive wizard):
gh stack merge <pr-number>
```
Pass PR numbers to `gh stack link`, not branch names. A branch name with no open PR makes the command push the branch and open a PR on its own.
Typical wtf usage:
| Caller | Call | Purpose |
|---|---|---|
| `wtf.create-pr` step 8 | `gh stack link <bottom-pr> ... <this-pr>` | Add the new Trace PR to its stack |
| `wtf.loop` step d | same, inlined | Same, non-interactive |
| `wtf.loop` step d | `gh pr merge <n> --merge --delete-branch` | Merge one layer, bottom-up. Never squash a Trace PR. |
| Human | `gh stack merge <pr-number>` | Merge several layers at once. Pick the merge-commit method, not squash. |
Gotchas:
- `gh pr edit --base` on a stacked PR fails with `part of a stack`. Unstack, change the base, link again.
- `gh stack view` shows local tracking only. A linked stack has none. Check the stack map on the PR page instead.
- `gh stack submit` does nothing when every PR already exists. Use `gh stack link`.
- `gh stack modify` is an interactive TUI. Do not use it from a skill.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |