Skip to content

xiduzo/wtf / skills/wtf.setup

wtf.setup

Verified

This 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-body-helper.md

View on GitHub
# gh Body Helper

Single source of truth for **reading and writing GitHub issue / PR bodies** from any wtf skill. Use it for every body round-trip. Multi-line UTF-8 content then survives on every platform. Windows needs this most.

Raw `gh` under PowerShell corrupts bodies three ways. First: CP850 console mojibake. Second: newline collapse on variable capture. Third: inline-`--body` re-encoding.

The helper is `gh-body.py`. It is a small stdlib-only Python utility. `wtf.setup` copies it into the repo at **`.wtf/gh-body.py`**. The guard is committed and travels with the repo for every teammate. See `../wtf.setup/hooks/gh-body.py` for the source and the full rationale.

## Invocation

```bash
python3 .wtf/gh-body.py <read|create|edit> ...
```

`wtf.setup` smoke-tests this exact `python3 .wtf/gh-body.py` invocation. It reports `verified` / `wrong-name` / `no-python`. On Windows the python.org installer provides `python`/`py` rather than `python3`. If setup reports `wrong-name`, add a `python3` alias or shim. Or substitute `python`/`py -3` in these commands. The script itself is identical on all platforms. Only the launcher name differs.

## When the helper is present (the normal path)

**Create** an issue or PR. Write the filled body to a temp file with the **Write tool** first. The helper re-encodes it to UTF-8 no-BOM. Then:

```bash
# Issue:
python3 .wtf/gh-body.py create --title "<emoji> <Type>: <title>" --body-file "$BODY" --label "<label>"
# PR (add --pr and a base branch):
python3 .wtf/gh-body.py create --pr --title "<title>" --body-file "$BODY" --base "<base_branch>"
```

The helper prints `gh`'s own output (the created URL). Any extra flags — `--assignee`, `--milestone`, `--repo`, … — are forwarded verbatim to `gh`.

**Read → modify → write** (update one section of an existing body without clobbering the rest):

```bash
# 1. Fetch the current body to a UTF-8 temp file; the helper prints its path on stdout.
python3 .wtf/gh-body.py read <number>           # add --pr for a PR
# 2. Read that path with the Read tool, then replace ONLY the target section
#    with the Write or Edit tool. Never reconstruct the whole body from scratch.
# 3. Push it back:
python3 .wtf/gh-body.py edit <number> --body-file "<path-from-step-1>"   # add --pr for a PR
```

Rules:

- **Never capture a body into a shell variable** (`BODY=$(gh issue view …)`). That is the newline-collapse bug. Always go through `read` → temp file → Read tool.
- **Always read before writing**. Never assume the current body matches the original draft.
- A second write in the same run must re-`read`. Do not reuse the earlier temp file. Other sections may have changed. Example: update Test Mapping after Technical Approach.
- `read` uses `mkstemp`. Each call yields a unique path. Parallel runs never collide. You do not need to hand-roll `$(date +%s)` names.

## Comments, PR reviews, and releases

Three more body-bearing `gh` commands go through the same guard. Never post these inline with `--body "..."`. That is the failure mode the helper exists to prevent. Write the comment, body, or notes to a temp file with the Write tool first. Then:

```bash
# Add a comment to an issue (or a PR with --pr):
python3 .wtf/gh-body.py comment <number> --body-file "$COMMENT"

# Post a PR review (the verdict flag is forwarded to gh pr review):
python3 .wtf/gh-body.py review <pr_number> --request-changes --body-file "$BODY"

# Create a release from a notes file:
python3 .wtf/gh-body.py release <tag> --title "<title>" --notes-file "$NOTES"
```

## Fallback when the helper is absent

If `.wtf/gh-body.py` does not exist, the repo has not run `wtf.setup` since this guard shipped. Fall back to raw `gh` with `--body-file`. Write the body with the Write tool. Never use inline `--body`. Never capture into a variable:

```bash
gh issue create --title "…" --body-file "$BODY" --label "…"
gh issue view <n> --json body --template '{{.body}}' > "$BODY" && gh issue edit <n> --body-file "$BODY"
```

Use `--template`, not `-q .body`. The `-q` output adds one newline to the body on every round trip. This works on macOS/Linux. **On Windows it is unguarded**. Bodies with emoji or accented domain language may corrupt. In that case, tell the user to run `/wtf.setup` to install the helper. Then retry.
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: 472kUpdated Claude CodeCodexVerifiedInstall
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: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 322kUpdated Claude CodeCodexVerifiedInstall