wtf.setup

用途

wtf.setup 是 WTF 工作流的预检与安装器。当用户希望在一个新仓库中设置 WTF、验证环境是否就绪、检查 GitHub CLI 是否已安装并完成认证时使用。

主要能力

环境预检

验证 gh 是否已安装（gh --version）。若未找到，提示用户 GitHub CLI 为必需项，链接 https://cli.github.com，并停止，直到安装完成。
验证 gh 是否已完成认证（gh auth status）。若未认证，提示用户运行 gh auth login，并停止，直到认证确认。
检查并安装所需扩展：

# 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

安装后验证命令语法（gh sub-issue --help、gh issue-dependency --help），并记录两个布尔值：gh-sub-issue-available、gh-issue-dependency-available。可选扩展 github/gh-stack（用于 Trace 堆叠的原生 stacked PR）不会未经请求安装，仅提及一次。

仓库上下文与权限

检测仓库上下文（gh repo view --json nameWithOwner -q .nameWithOwner）。若非 git 仓库或无 GitHub 远程，会警告用户。
验证 GitHub 权限：需要写权限，令牌需要 repo 或 public_repo scope。检查令牌 scope 与仓库写权限（admin、maintain 或 push 为 true）。若仅 triage 或 pull，会警告只读访问将导致标签创建和议题链接失败。记录 token-scopes-ok、repo-write-ok 两个布尔值；若任一为 false，跳过标签创建并警告。

模板检查与安装

检查 .github/ISSUE_TEMPLATE/ 是否存在并包含四个必需模板：BUG.md、EPIC.md、FEATURE.md、TRACE.md。
解析技能载荷安装位置，按顺序探测目录并复用 $SETUP_DIR：

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

仅复制缺失文件，不覆盖已有模板：

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

旧版 TASK.md：若存在，WTF 不再创建 Tasks，写入路径创建 Traces。通过 AskUserQuestion 询问是否移除（推荐移除 → git rm .github/ISSUE_TEMPLATE/TASK.md；保留 → 在状态报告中注明）。
检查 PR 模板 .github/pull_request_template.md，若缺失则从 $SETUP_DIR/references/ 复制，已有文件不覆盖。

议题分类模式

WTF 将每个议题分类为 Epic、Feature、Trace 或 Bug。两种机制：原生 GitHub 议题类型（仅组织可用）或 epic/feature/trace/bug 标签（可移植到任何仓库）。

检测所有者类型（OWNER_TYPE：User 或 Organization）。
若为个人账户：原生议题类型不可用，设置 CLASS_MODE=labels 并说明。
若为组织且具备写权限与令牌 scope：询问使用原生议题类型还是标签。
原生类型模式下，运行 Provision native types 块，创建 Epic 和 Trace，并验证四种类型是否解析成功；若失败则回退到标签。
创建标签（--force 幂等）：

# 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 标签（epic、feature、trace、bug）。

原生类型模式下，将模板的 labels: <kind> frontmatter 改写为 type: <Kind>。
将模式记录到 .wtf/config.json：

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

提交 .wtf/config.json 以便团队统一分类。

关闭约定

GitHub 无原生设置强制基于 PR 的关闭，此行为由技能强制执行。议题仅在合并的 PR 包含 Closes #<n> 时被“关闭为已完成”。直接 gh issue close 仅保留给 --reason "not planned" 和 --reason "duplicate"。

自动删除头分支

Trace PR 会堆叠。检查 deleteBranchOnMerge，若为 false，询问用户是否启用（推荐启用）：

gh api -X PATCH "repos/$(gh repo view --json nameWithOwner -q .nameWithOwner)" \
  -F delete_branch_on_merge=true

若因权限失败，提示用户自行在 Settings → General → Automatically delete head branches 设置。

规划模式

两种模式，两者运行相同的质量门：guided（逐步询问，团队仍在塑造规格时推荐）或 flow（推导内容并一次性呈现综合评审）。通过 AskUserQuestion 选择，并记录到 .wtf/config.json：

python3 - ".wtf/config.json" "$PLAN_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["planning"] = mode
p.write_text(json.dumps(data, indent=2) + "\n")
PY

功能范围

WTF Features 携带 1..n 个用户故事。选择 single-story（每个 Feature 恰好一个用户故事）或 grouped（一个 Feature 携带多个共享一个 Spine 的相关故事）。记录到 feature_scope。

交付模式

设置 Trace PR 合并位置：staged（每个 Trace 合并到其功能分支，功能 PR 在 Trace Plan 用尽时合并到 main）或 trunk（每个 Trace PR 直接合并到 main）。记录到 .wtf/config.json。

使用方式

用户在新仓库中希望设置 WTF、验证环境就绪时调用此技能。技能按上述流程逐步执行：预检、安装扩展、检测仓库、验证权限、检查模板、配置分类模式、启用分支清理、选择规划/范围/交付模式，并写入 .wtf/config.json。

适用场景

在新的代码仓库中首次配置 WTF 工作流。
验证本地环境是否已准备好使用 WTF（gh 安装与认证、扩展、权限）。
为团队统一议题分类方式、规划模式、功能范围与交付模式。
补齐缺失的议题模板与 PR 模板。

限制

需要 GitHub CLI 已安装并完成认证，否则技能停止。
原生 GitHub 议题类型为组织专属功能，个人账户仓库不可用。
标签创建与议题关系创建需要仓库写权限；仅 triage 或 pull 权限会失败。
原生类型配置需要组织所有者权限，否则回退到标签。
扩展安装可能因网络或权限失败，关系追踪在安装成功前不可用。
自动删除头分支的 API 调用可能因权限失败，需用户手动设置。