xwang 0.0.1

package/assets/skills/xwang/scripts/xwang-state.sh

@@ -0,0 +1,374 @@
+#!/bin/bash
+# xwang State — unified interface for xwang change state management
+# Usage: xwang-state.sh <subcommand> <change-name> [args...]
+#
+# Subcommands:
+#   init <change-name> <workflow>  — Initialize .xwang.yaml with workflow defaults
+#
+# Workflows: full, quick
+# State phases: design, build, verify, archive (open is checked but not recorded)
+
+set -euo pipefail
+
+# --- Color output helpers ---
+
+red() { echo -e "\033[31m$1\033[0m" >&2; }
+green() { echo -e "\033[32m$1\033[0m" >&2; }
+yellow() { echo -e "\033[33m$1\033[0m" >&2; }
+
+# --- Script location ---
+
+# shellcheck disable=SC2034
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+# --- Input validation ---
+
+validate_change_name() {
+  local name="$1"
+  if [ -z "$name" ]; then
+    red "ERROR: Change name cannot be empty" >&2
+    exit 1
+  fi
+  if [[ ! "$name" =~ ^[a-zA-Z0-9_-]+$ ]]; then
+    red "ERROR: Invalid change name: '$name'" >&2
+    red "Valid characters: a-z, A-Z, 0-9, -, _" >&2
+    exit 1
+  fi
+  if [[ "$name" =~ \.\. ]]; then
+    red "ERROR: Change name cannot contain '..' (path traversal not allowed)" >&2
+    exit 1
+  fi
+}
+
+validate_enum() {
+  local value="$1"
+  shift
+  local valid_values=("$@")
+
+  for valid in "${valid_values[@]}"; do
+    if [ "$value" = "$valid" ]; then
+      return 0
+    fi
+  done
+
+  red "ERROR: Invalid value: '$value'" >&2
+  red "Valid values: ${valid_values[*]}" >&2
+  exit 1
+}
+
+# --- Helper functions ---
+
+yaml_file_for() {
+  local change_name="$1"
+  echo "openspec/changes/$change_name/.xwang.yaml"
+}
+
+change_dir_for() {
+  local change_name="$1"
+  echo "openspec/changes/$change_name"
+}
+
+yaml_field() {
+  local field="$1"
+  local yaml_file="$2"
+  if [ -f "$yaml_file" ]; then
+    local value
+    value=$(grep "^${field}:" "$yaml_file" 2>/dev/null | sed "s/^${field}: *//" || true)
+    value=$(strip_inline_comment "$value")
+    strip_wrapping_quotes "$value"
+  fi
+}
+
+strip_inline_comment() {
+  local value="$1"
+  printf '%s\n' "$value" | awk -v squote="'" '
+    {
+      out = ""
+      quote = ""
+      for (i = 1; i <= length($0); i++) {
+        c = substr($0, i, 1)
+        if (quote == "") {
+          if (c == "\"" || c == squote) {
+            quote = c
+          } else if (c == "#" && (i == 1 || substr($0, i - 1, 1) ~ /[[:space:]]/)) {
+            sub(/[[:space:]]+$/, "", out)
+            print out
+            next
+          }
+        } else if (c == quote) {
+          quote = ""
+        }
+        out = out c
+      }
+      print out
+    }
+  '
+}
+
+strip_wrapping_quotes() {
+  local value="$1"
+  case "$value" in
+    \"*\")
+      printf '%s\n' "${value:1:${#value}-2}"
+      ;;
+    \'*\')
+      printf '%s\n' "${value:1:${#value}-2}"
+      ;;
+    *)
+      printf '%s\n' "$value"
+      ;;
+  esac
+}
+
+replace_yaml_field() {
+  local yaml_file="$1"
+  local field="$2"
+  local value="$3"
+  local tmp_file
+
+  tmp_file=$(mktemp)
+  chmod 600 "$tmp_file"
+  awk -v field="$field" -v value="$value" '
+    index($0, field ":") == 1 { $0 = field ": " value }
+    { buf[NR] = $0; keys[NR] = $0; sub(/:.*$/, "", keys[NR]); n = NR }
+    END {
+      for (i = 1; i <= n; i++) last[keys[i]] = i
+      for (i = 1; i <= n; i++) if (last[keys[i]] == i) print buf[i]
+    }
+  ' "$yaml_file" > "$tmp_file"
+  mv "$tmp_file" "$yaml_file"
+}
+
+validate_path_field() {
+  local value="$1"
+  local field="$2"
+  if [ -z "$value" ] || [ "$value" = "null" ]; then
+    return 0
+  fi
+  case "$value" in
+    /*|~*|[A-Za-z]:*|\\*)
+      red "ERROR: $field must be a relative path within the repo: '$value'" >&2
+      exit 1
+      ;;
+  esac
+  if [[ "$value" =~ \.\. ]]; then
+    red "ERROR: $field cannot contain '..' (path traversal not allowed): '$value'" >&2
+    exit 1
+  fi
+}
+
+# --- Subcommands ---
+
+cmd_init() {
+  local change_name="$1"
+  local workflow="$2"
+
+  validate_change_name "$change_name"
+  validate_enum "$workflow" "full" "quick" "tweak"
+
+  local change_dir yaml_file
+  change_dir=$(change_dir_for "$change_name")
+  yaml_file=$(yaml_file_for "$change_name")
+
+  # Check if .xwang.yaml already exists
+  if [ -f "$yaml_file" ]; then
+    red "ERROR: .xwang.yaml already exists at $yaml_file"
+    exit 1
+  fi
+
+  # Create change directory if it doesn't exist
+  mkdir -p "$change_dir"
+
+  # Set workflow-appropriate defaults
+  local phase design_doc plan build_mode tdd_mode isolation
+  # open 阶段只做检查，实际状态记录从 design 开始
+  phase="design"
+  design_doc="null"
+  plan="null"
+  build_mode="null"
+  tdd_mode="null"
+  isolation="null"
+
+  case "$workflow" in
+    full)
+      ;;
+    quick|tweak)
+      # Quick/Tweak workflow skips design phase, starts directly at build
+      phase="build"
+      build_mode="direct"
+      tdd_mode="direct"
+      isolation="branch"
+      ;;
+  esac
+
+  # Record current HEAD as base_ref for later diff reference
+  local base_ref="null"
+  if git rev-parse --verify HEAD >/dev/null 2>&1; then
+    base_ref=$(git rev-parse HEAD 2>/dev/null || echo "null")
+  fi
+
+  cat > "$yaml_file" <<EOF
+workflow: $workflow
+phase: $phase
+design_doc: $design_doc
+plan: $plan
+base_ref: $base_ref
+isolation: $isolation
+build_mode: $build_mode
+build_pause: null
+tdd_mode: $tdd_mode
+subagent_dispatch: null
+direct_override: false
+verify_mode: null
+verify_result: pending
+verification_report: null
+branch_status: pending
+archived: false
+created_at: $(date -u +%Y-%m-%d)
+updated_at: null
+EOF
+
+  green "Initialized: $yaml_file (workflow=$workflow)"
+}
+
+cmd_get() {
+  local change_name="$1"
+  local field="$2"
+
+  validate_change_name "$change_name"
+
+  local yaml_file
+  yaml_file=$(yaml_file_for "$change_name")
+
+  if [ ! -f "$yaml_file" ]; then
+    red "ERROR: .xwang.yaml not found at $yaml_file"
+    exit 1
+  fi
+
+  local value
+  value=$(yaml_field "$field" "$yaml_file")
+  echo "${value:-}"
+}
+
+cmd_set() {
+  local change_name="$1"
+  local field="$2"
+  local value="$3"
+
+  validate_change_name "$change_name"
+
+  local yaml_file
+  yaml_file=$(yaml_file_for "$change_name")
+
+  if [ ! -f "$yaml_file" ]; then
+    red "ERROR: .xwang.yaml not found at $yaml_file"
+    exit 1
+  fi
+
+  case "$field" in
+    workflow|phase|design_doc|plan|base_ref|isolation|build_mode|build_pause|tdd_mode|subagent_dispatch|direct_override|verify_mode|verify_result|verification_report|branch_status|archived|created_at|updated_at|build_command|verify_command)
+      # Valid field
+      ;;
+    *)
+      red "ERROR: Unknown field: '$field'" >&2
+      red "Valid fields: workflow, phase, design_doc, plan, base_ref, isolation, build_mode, build_pause, tdd_mode, subagent_dispatch, direct_override, verify_mode, verify_result, verification_report, branch_status, archived, created_at, updated_at, build_command, verify_command" >&2
+      exit 1
+      ;;
+  esac
+
+  case "$field" in
+    workflow)
+      validate_enum "$value" "full" "quick" "tweak"
+      ;;
+    phase)
+      validate_enum "$value" "design" "build" "verify" "archive"
+      ;;
+    isolation)
+      validate_enum "$value" "branch" "worktree"
+      ;;
+    build_mode)
+      validate_enum "$value" "subagent-driven-development" "executing-plans" "direct"
+      ;;
+    build_pause)
+      validate_enum "$value" "null" "plan-ready"
+      ;;
+    tdd_mode)
+      validate_enum "$value" "tdd" "direct"
+      ;;
+    subagent_dispatch)
+      validate_enum "$value" "null" "confirmed"
+      ;;
+    direct_override|archived)
+      validate_enum "$value" "true" "false"
+      ;;
+    verify_mode)
+      validate_enum "$value" "light" "full"
+      ;;
+    verify_result)
+      validate_enum "$value" "pending" "pass" "fail"
+      ;;
+    branch_status)
+      validate_enum "$value" "pending" "handled"
+      ;;
+    design_doc|plan|verification_report)
+      validate_path_field "$value" "$field"
+      ;;
+  esac
+
+  if grep -q "^${field}:" "$yaml_file"; then
+    replace_yaml_field "$yaml_file" "$field" "$value"
+  else
+    echo "${field}: ${value}" >> "$yaml_file"
+  fi
+
+  # Automatically update updated_at when other fields change
+  if [ "$field" != "updated_at" ] && [ "$field" != "created_at" ]; then
+    replace_yaml_field "$yaml_file" "updated_at" "$(date -u +%Y-%m-%d)"
+  fi
+
+  green "[SET] ${field}=${value}"
+}
+
+# --- Main ---
+
+SUBCOMMAND="${1:-}"
+shift || true
+
+case "$SUBCOMMAND" in
+  init)
+    if [ $# -lt 2 ]; then
+      red "Usage: xwang-state.sh init <change-name> <workflow>" >&2
+      red "Workflows: full, quick, tweak" >&2
+      exit 1
+    fi
+    cmd_init "$@"
+    ;;
+  get)
+    if [ $# -lt 2 ]; then
+      red "Usage: xwang-state.sh get <change-name> <field>" >&2
+      exit 1
+    fi
+    cmd_get "$@"
+    ;;
+  set)
+    if [ $# -lt 3 ]; then
+      red "Usage: xwang-state.sh set <change-name> <field> <value>" >&2
+      exit 1
+    fi
+    cmd_set "$@"
+    ;;
+  *)
+    red "Unknown subcommand: $SUBCOMMAND" >&2
+    echo "" >&2
+    echo "Usage: xwang-state.sh <subcommand> <change-name> [args...]" >&2
+    echo "" >&2
+    echo "Subcommands:" >&2
+    echo "  init <change-name> <workflow>  — Initialize .xwang.yaml with workflow defaults" >&2
+    echo "  get <change-name> <field>       — Read a field value from .xwang.yaml" >&2
+    echo "  set <change-name> <field> <val> — Update a field value in .xwang.yaml" >&2
+    echo "" >&2
+    echo "Workflows: full, quick, tweak" >&2
+    echo "State phases: design, build, verify, archive (open is checked but not recorded)" >&2
+    exit 1
+    ;;
+esac

package/assets/skills/xwang-archive/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: xwang-archive
+description: 启动 xwang 项目阶段5：归档。在 verify 完成后按 OpenSpec delta 语义合并主 spec、移动 change 到归档目录，并将 `.xwang.yaml` 标记为已归档。当用户触发 xwang 阶段5、开始归档、xwang-archive，或在 xwang-verify 完成后要求归档时使用。
+---
+
+# xwang-archive
+
+## 前置条件
+
+- 当前 change 的 `.xwang.yaml` 中 `phase` 为 `archive`
+- `verification_report` 指向已存在的验证报告文件
+- `branch_status` 为 `handled`
+
+## Quick start
+
+当用户触发 xwang 阶段5时：
+
+1. 确定 change 名称 `<name>`：优先使用用户提供的名称；若未提供，从 `openspec/changes/` 下选择 phase 为 `archive` 的 change。
+2. 读取 `.xwang.yaml` 确认当前 phase 为 `archive`，且验证报告、分支状态已记录。
+3. 向用户展示归档摘要，并**暂停等待用户确认**是否立即归档。
+4. 用户确认后，调用 `/openspec-archive-change` 按 delta 语义合并主 spec 并移动 change 到归档目录。
+5. 调用 `xwang-state.sh set <name> archived true`。
+6. 向用户汇报归档结果与新路径。
+
+## Workflows
+
+开始前先定位 xwang 脚本：
+
+```bash
+XWANG_ENV="${XWANG_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" -path '*/xwang/scripts/xwang-env.sh' -type f -print -quit 2>/dev/null)}"
+if [ -z "$XWANG_ENV" ]; then
+  echo "ERROR: xwang-env.sh not found. Ensure the xwang skill is installed." >&2
+  return 1
+fi
+. "$XWANG_ENV"
+```
+
+### Step 1：入口确认
+
+- [ ] 获取 `<name>`：用户未提供时，选择 `.xwang.yaml` 中 `phase: archive` 的 change。
+- [ ] 读取 `openspec/changes/<name>/.xwang.yaml`，确认：
+  - `phase` 为 `archive`
+  - `verification_report` 非空且文件存在
+  - `branch_status` 为 `handled`
+- [ ] 若入口条件不满足，提示用户先完成 `/xwang-verify`。
+
+### Step 2：归档前最终确认（阻塞点）
+
+- [ ] 向用户展示简短摘要：
+  - change 名称
+  - 验证报告路径和结论
+  - 分支处理状态
+  - 本次归档将执行的不可逆动作：按 OpenSpec delta 语义合并主 spec、移动 change 到 `openspec/changes/archive/` 目录、将 `.xwang.yaml` 标记为 `archived: true`
+- [ ] **必须使用当前平台可用的用户输入/确认机制暂停并等待用户选择**：
+  - **确认归档**：立即执行归档
+  - **需要调整或重新验证**：不执行归档；调用 `"$XWANG_STATE" set <name> phase verify` 回到 verify，再调用 `/xwang-verify`
+  - **暂不归档**：不执行归档，保留当前 `phase: archive` 状态，等待用户稍后再次调用 `/xwang-archive`
+- [ ] 只有用户选择「确认归档」后才继续 Step 3。
+
+### Step 3：执行归档
+
+- [ ] 调用 `/openspec-archive-change <name>`（或等价的 OpenSpec archive 命令）按 delta 语义合并主 spec 并移动 change 到归档目录。
+- [ ] 如归档命令返回非零退出码，报告错误并停止。
+- [ ] 归档成功后，确认 change 目录已移动到 `openspec/changes/archive/YYYY-MM-DD-<name>/`（或 OpenSpec 默认归档路径）。
+
+### Step 4：标记归档状态
+
+- [ ] 对归档后的 `.xwang.yaml` 调用 `"$XWANG_STATE" set <name> archived true`。
+- [ ] **归档完整性守护**：调用 `"$XWANG_GUARD" <name> archive` 校验归档后的退出条件（`archived: true`、必要文档存在且 tasks 已勾选）。
+- [ ] 如需，在 PRD 和 plan 文件前置元数据中标注 `archived-with: <name>` 和 `status: archived`。
+- [ ] 向用户汇报归档完成、新目录路径与生命周期闭环状态。
+
+## 退出条件
+
+- 归档命令执行成功
+- 归档目录存在
+- `.xwang.yaml` 中 `archived: true`
+
+## 完成
+
+xwang 流程全部完成。如需开始新工作，调用 `/xwang` 或 `/xwang-open`。
+
+## Advanced features
+
+- **预览归档**：调用 `/openspec-archive-change` 时如支持 `--dry-run`，可先预览再执行。
+- **从 archive 恢复**：如需重新验证，先 `set <name> phase verify`，再调用 `/xwang-verify`。

package/assets/skills/xwang-build/REFERENCE.md

@@ -0,0 +1,94 @@
+# xwang-build 参考
+
+## xwang 三阶段流程
+
+| 阶段 | Skill | 职责 | 主要产物 |
+|------|-------|------|----------|
+| 1 | *(待定义)* | *(待定义)* | *(待定义)* |
+| 2 | `xwang-design` | 深度设计、澄清需求、产出 PRD 与 OpenSpec change | `docs/mattpocock/<name>-prd.md`、`openspec/changes/<name>/**` |
+| 3 | `xwang-build` | 基于设计产物制定实现计划 | `docs/superpowers/plans/YYYY-MM-DD-<name>.md` |
+
+## 阶段2产物结构
+
+```
+project/
+├── docs/mattpocock/
+│   └── <name>-prd.md              # 中文 PRD
+└── openspec/changes/<name>/
+    ├── .openspec.yaml              # change 元数据
+    ├── proposal.md                 # 变更提案
+    ├── design.md                   # 设计决策
+    ├── tasks.md                    # 任务清单
+    └── specs/
+        ├── <capability-1>/
+        │   └── spec.md             # capability 详细规格
+        └── <capability-2>/
+            └── spec.md
+```
+
+## 读取顺序与用途
+
+1. **PRD** (`docs/mattpocock/<name>-prd.md`)
+   - 需求总览、目标用户、验收标准。
+   - 用于把握整体目标。
+
+2. **proposal.md**
+   - Why / What Changes / Capabilities / Impact。
+   - 用于识别需要实现哪些 capability。
+
+3. **design.md**
+   - Context / Goals & Non-Goals / Decisions / Risks。
+   - 用于理解架构决策与约束。
+
+4. **tasks.md**
+   - OpenSpec 生成的初始任务列表。
+   - 作为 writing-plans 的输入参考，但不直接照抄；需重新按 writing-plans 粒度拆分。
+
+5. **specs/\*/spec.md**
+   - 每个 capability 的 ADDED Requirements、Scenarios。
+   - 用于确保计划覆盖所有验收场景。
+
+## 与 writing-plans 的衔接
+
+- 调用 `/writing-plans` 前，需将上述文档内容汇总到当前对话上下文。
+- 明确告知 writing-plans：
+  - 计划保存路径为 `docs/superpowers/plans/YYYY-MM-DD-<name>.md`。
+  - 需要覆盖所有 `specs/` 下的 capability。
+  - 遵循项目的现有代码风格与目录结构。
+
+## 失败处理
+
+- 若 `openspec/changes/` 不存在或为空：提示用户先运行 `/xwang-design`。
+- 若指定 `<name>` 的 change 不存在：列出可用 change 名称让用户选择。
+- 若缺少 PRD 或核心 spec：仍可基于现有文档生成计划，但需向用户说明缺失内容。
+
+## 执行计划
+
+选择工作方式后进入执行阶段。
+
+### executing-plans 模式
+
+1. 使用 Skill 工具加载 Superpowers `executing-plans` 技能，ARGUMENTS 包含：`Language: 使用触发本次工作流的用户请求语言输出`。
+2. 若 `tdd_mode: tdd`，在执行第一个任务前加载 Superpowers `test-driven-development` 技能一次。
+3. 按计划执行任务，勾选 plan 中对应任务。
+4. 若任务映射到 `openspec/changes/<name>/tasks.md`，同步将对应 OpenSpec 任务从 `- [ ]` 改为 `- [x]`。
+5. 所有任务完成后，加载 Superpowers `requesting-code-review` 技能请求代码审查。
+
+### subagent-driven-development 模式
+
+1. 主窗口只负责协调，不得在当前主窗口直接运行 `subagent-driven-development` 技能。
+2. 把下一个未完成任务派发到后台 subagent，prompt 必须包含：
+   - Language 约束：`Language: 使用触发本次工作流的用户请求语言输出`
+   - TDD 硬约束（若 `tdd_mode: tdd`）："You MUST follow TDD: for each task, write a failing test first, watch it fail, then write minimal code to pass. No production code without a failing test first."
+   - 持久化勾选要求：任务完成后立即勾选 Superpowers plan 中对应任务；若映射到 OpenSpec tasks.md，同步勾选对应 OpenSpec 任务。
+3. subagent 自行加载 `subagent-driven-development` 并按其指引完成实现、检查与提交。
+
+### 异常调试
+
+执行任务期间若出现崩溃、异常行为、测试失败或构建失败，立即加载 Superpowers `systematic-debugging` 技能。完成根因调查前不得提出或实施源码修复。
+
+### 计划任务勾选要求
+
+- 不得只更新内置 Todo 或对话内 checklist。
+- 必须持久化到 `docs/superpowers/plans/YYYY-MM-DD-<name>.md`。
+- 若 plan 任务映射到 OpenSpec tasks.md，也同步更新 `openspec/changes/<name>/tasks.md`。

package/assets/skills/xwang-build/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: xwang-build
+description: 启动 xwang 项目阶段3：基于 xwang-design 生成的 PRD 与 OpenSpec 各 spec 文档，通过 subagent 制定实现计划并自动选择执行方式实施。Use when 用户触发 xwang 阶段3、开始构建、xwang-build，或在 xwang-design 完成后要求自动制定并执行实施计划。
+---
+
+# xwang-build
+
+## Quick start
+
+当用户触发 xwang 阶段3时：
+
+1. 确定 change 名称 `<name>`：优先使用用户提供的名称；若未提供，从 `openspec/changes/` 下选择最近修改的 change 目录。
+2. 读取阶段2产物：PRD、proposal、design、tasks 以及 `specs/` 下所有 `spec.md`。
+3. 通过 subagent 加载 `/writing-plans` 制定计划，避免占用主 session 上下文。
+4. 计划保存到 `docs/superpowers/plans/YYYY-MM-DD-<name>.md`，文件头包含 change、design-doc、base-ref 元数据。
+5. 计划完成后自动选择工作方式：任务数 ≥ 3 用 `subagent-driven-development`，≤ 2 用 `executing-plans`；默认 `tdd_mode: tdd`。
+6. 自动创建工作区隔离（branch 或 worktree），然后进入执行阶段。
+
+## Workflows
+
+开始前先定位 xwang 脚本：
+
+```bash
+XWANG_ENV="${XWANG_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" -path '*/xwang/scripts/xwang-env.sh' -type f -print -quit 2>/dev/null)}"
+if [ -z "$XWANG_ENV" ]; then
+  echo "ERROR: xwang-env.sh not found. Ensure the xwang skill is installed." >&2
+  return 1
+fi
+. "$XWANG_ENV"
+```
+
+
+- [ ] 确认用户要启动 xwang 阶段3（关键词：xwang-build、xwang 阶段3、开始构建、制定计划）。
+- [ ] 获取 `<name>`：用户未提供时，读取 `openspec/changes/` 目录，按修改时间选择最新的 change。
+- [ ] 验证 `openspec/changes/<name>/` 与 `docs/mattpocock/<name>-prd.md` 存在；缺失时提示用户先运行 `/xwang-design`。
+- [ ] 读取以下文档作为 plan 输入：
+  - `docs/mattpocock/<name>-prd.md`
+  - `docs/mattpocock/<name>-prd.md`
+  - `docs/mattpocock/<name>-prd.md` 
+    - `openspec/changes/<name>/proposal.md`
+  - `openspec/changes/<name>/design.md`
+  - `openspec/changes/<name>/tasks.md`
+  - `openspec/changes/<name>/specs/*/spec.md`
+
+### Step 2：制定计划（Subagent Offload）
+
+通过 subagent 创建实施计划，避免 planning skill 占用主 session 上下文。
+
+- [ ] 记录当前提交作为 `base-ref`：`git rev-parse HEAD`。
+- [ ] 派发 subagent，指令如下：
+  - 你是实施计划专家。基于以下输入创建实施计划，**全程必须使用中文输出**（包括计划条目、任务拆分、代码注释、矛盾分析、给用户的选择题和推荐理由）。不得输出英文。
+  - 立即使用 Skill 工具加载 Superpowers `writing-plans` 技能，ARGUMENTS 必须包含：`Language: 中文`。
+  - 读取 `docs/mattpocock/<name>-prd.md`（需求总览）。
+  - 读取 `openspec/changes/<name>/proposal.md`、`design.md`、`tasks.md`。
+  - 读取 `openspec/changes/<name>/specs/*/spec.md`（所有 capability 规格）。
+  - 按 `writing-plans` 技能指引创建计划，保存至 `docs/superpowers/plans/YYYY-MM-DD-<name>.md`。
+  - **计划文件头必须包含关联元数据**：
+    ```yaml
+    ---
+    change: <name>
+    design-doc: openspec/changes/<name>/design.md
+    base-ref: <git rev-parse HEAD>
+    ---
+    ```
+  - 如果计划中不同任务之间存在矛盾或不一致，必须停下来用中文向用户说明矛盾点、列出选项并给出推荐，等待用户明确选择后再继续。
+- [ ] Subagent 完成后：
+  - 若返回有效文件路径且文件存在，记录为 plan。
+  - 若 subagent 失败或返回路径无效，在主 session 内联加载 `/writing-plans` 创建计划（降级回退）。
+
+### Step 3：plan-ready 检查点
+
+- [ ] 计划写入后，向用户汇报计划路径与任务概览。
+- [ ] 默认自动继续进入 Step 4 选择工作方式并执行。
+- [ ] 若用户明确要求暂停，可记录 `plan-ready` 暂停状态；恢复时若 plan 文件存在，不重新运行 `writing-plans`，直接进入 Step 4。
+
+### Step 4：自动选择工作方式
+
+本步骤由 skill 根据 plan 自动选择工作方式，无需用户决策。
+
+- [ ] 默认设置 `tdd_mode: tdd`。
+- [ ] 读取已生成的 plan 文件，统计任务数量（例如统计 `### Task N:` 或任务勾选项数量）。
+- [ ] 自动选择执行方式：
+  - 任务数 ≥ 3 → `build_mode: subagent-driven-development`
+  - 任务数 ≤ 2 → `build_mode: executing-plans`
+- [ ] 若选择 `subagent-driven-development`，确认当前平台存在真实后台 subagent / Task / multi-agent 调度能力；若不存在，降级为 `executing-plans`。
+- [ ] 自动选择工作区隔离方式：
+  - 默认 `isolation: branch`
+  - 若当前工作树存在未提交改动 → `isolation: worktree`
+- [ ] 执行隔离：
+  - **branch**：按 `feature/YYYYMMDD/<name>` 格式创建分支，直接执行 `git checkout -b <branch>`。
+  - **worktree**：使用 Skill 工具加载 Superpowers `using-git-worktrees` 技能创建隔离工作区。若 plan 文件尚未提交，先提交计划再创建 worktree。
+- [ ] 记录最终选择：isolation、build_mode、tdd_mode，并向用户简要说明自动选择理由。
+- [ ] 进入执行阶段。详见 [REFERENCE.md#执行计划](REFERENCE.md#执行计划)。
+
+### Step 5：build 完成后进入 verify
+
+build 阶段全部任务执行完毕且代码已提交后：
+
+- [ ] 确认 `openspec/changes/<name>/tasks.md` 和 `docs/superpowers/plans/YYYY-MM-DD-<name>.md` 中所有任务已勾选。
+- [ ] 确认 `plan`、`isolation`、`build_mode`、`tdd_mode` 已正确写入 `.xwang.yaml`。
+- [ ] **默认选择保持分支不变（稍后处理），无需用户确认**：调用 `"$XWANG_STATE" set <name> branch_status handled`。
+- [ ] 如果 plan 文件路径尚未写入 `.xwang.yaml`，调用 `"$XWANG_STATE" set <name> plan docs/superpowers/plans/YYYY-MM-DD-<name>.md`。
+- [ ] **阶段出口守护（build → verify）**：调用 `"$XWANG_GUARD" <name> build --apply` 校验 build 阶段退出条件，通过后会自动将 `.xwang.yaml` 的 `phase` 推进到 `verify`。
+- [ ] **自动进入 verify 阶段**：汇报完成后，直接调用 `/xwang-verify` 继续阶段4，无需等待用户确认。
+- [ ] 向用户汇报最终状态文件路径、当前 phase 与分支处理状态。
+
+## Advanced features
+
+- **指定 change 名称**：用户可直接提供 `<name>`，例如 `/xwang-build auth-flow`。
+- **从 plan-ready 恢复**：用户再次调用 `/xwang-build` 时，若检测到未完成的 plan-ready 暂停，先确认 plan 文件存在，然后直接进入 Step 4。
+- **跳过计划直接执行**：仅在用户明确要求且已记录显式 override 时允许，否则必须完成计划制定。
+- **覆盖 TDD 模式**：默认 `tdd_mode: tdd`；用户明确要求 `direct` 模式时，可设置为 `direct`。
+- **多 capability 聚合**：`specs/` 目录下通常包含多个 capability 的 spec，确保全部读取并体现在计划中。