@tw93/waza 3.25.0

package/scripts/statusline.sh

@@ -0,0 +1,321 @@
+#!/bin/bash
+# Claude Code statusline: Context % | 5h: % (reset) | 7d: % (reset)
+# Set WAZA_STATUSLINE_DEBUG=1 to surface stderr (jq parse errors, missing tools).
+[ "${WAZA_STATUSLINE_DEBUG:-}" = "1" ] || exec 2>/dev/null
+
+CACHE_DIR="$HOME/.cache/waza-statusline"
+CACHE_FILE="$CACHE_DIR/last.json"
+HIGHWATER_FILE="$CACHE_DIR/highwater.json"
+HIGHWATER_LOCK_DIR="$CACHE_DIR/highwater.lock"
+CACHE_MAX_AGE=21600  # 6 hours: one full rate_limit window
+HIGHWATER_LOCK_MAX_AGE=10
+HIGHWATER_RESET_SKEW_MAX=7200  # tolerate session jitter, reject crossed windows
+
+input=$(cat)
+
+tab=$(printf '\t')
+
+jq_full='[
+  ((.context_window.current_usage.input_tokens // 0)
+   + (.context_window.current_usage.cache_creation_input_tokens // 0)
+   + (.context_window.current_usage.cache_read_input_tokens // 0) | tostring),
+  (.context_window.context_window_size // 0 | tostring),
+  (.rate_limits.five_hour.used_percentage // null | if . then (. | round | tostring) else "null" end),
+  (.rate_limits.five_hour.resets_at // "" | tostring),
+  (.rate_limits.seven_day.used_percentage // null | if . then (. | round | tostring) else "null" end),
+  (.rate_limits.seven_day.resets_at // "" | tostring)
+] | @tsv'
+
+jq_rl='[
+  (.rate_limits.five_hour.used_percentage // null | if . then (. | round | tostring) else "null" end),
+  (.rate_limits.five_hour.resets_at // "" | tostring),
+  (.rate_limits.seven_day.used_percentage // null | if . then (. | round | tostring) else "null" end),
+  (.rate_limits.seven_day.resets_at // "" | tostring)
+] | @tsv'
+
+cache_file_mtime() {
+  local path="$1"
+  local ts=""
+  ts=$(stat -c %Y "$path" 2>/dev/null || true)
+  if [ -z "$ts" ]; then
+    ts=$(stat -f %m "$path" 2>/dev/null || true)
+  fi
+  printf '%s\n' "${ts:-0}"
+}
+
+is_uint() {
+  case "$1" in
+    ''|null) return 1 ;;
+    *[!0-9]*) return 1 ;;
+    *) return 0 ;;
+  esac
+}
+
+acquire_highwater_lock() {
+  mkdir -p "$CACHE_DIR" 2>/dev/null || return 1
+  local attempts=0 lock_mtime now
+  while [ "$attempts" -lt 5 ]; do
+    attempts=$((attempts + 1))
+    if mkdir "$HIGHWATER_LOCK_DIR" 2>/dev/null; then
+      return 0
+    fi
+    lock_mtime=$(cache_file_mtime "$HIGHWATER_LOCK_DIR")
+    now=$(date +%s)
+    if [ $((now - lock_mtime)) -gt "$HIGHWATER_LOCK_MAX_AGE" ]; then
+      rmdir "$HIGHWATER_LOCK_DIR" 2>/dev/null || true
+      continue
+    fi
+    sleep 0.05
+  done
+  return 1
+}
+
+release_highwater_lock() {
+  rmdir "$HIGHWATER_LOCK_DIR" 2>/dev/null || true
+}
+
+read_highwater() {
+  hw_5h_pct=""
+  hw_5h_reset=""
+  hw_7d_pct=""
+  hw_7d_reset=""
+  [ -f "$HIGHWATER_FILE" ] || return
+  hw_5h_pct=$(jq -r 'if .five_hour.used_percentage == null then "" else (.five_hour.used_percentage | round | tostring) end' "$HIGHWATER_FILE" 2>/dev/null)
+  hw_5h_reset=$(jq -r 'if .five_hour.resets_at == null then "" else (.five_hour.resets_at | tostring) end' "$HIGHWATER_FILE" 2>/dev/null)
+  hw_7d_pct=$(jq -r 'if .seven_day.used_percentage == null then "" else (.seven_day.used_percentage | round | tostring) end' "$HIGHWATER_FILE" 2>/dev/null)
+  hw_7d_reset=$(jq -r 'if .seven_day.resets_at == null then "" else (.seven_day.resets_at | tostring) end' "$HIGHWATER_FILE" 2>/dev/null)
+}
+
+# apply_hw: compares live vs high-water marks for a single counter (5h or 7d).
+# Mutates four caller-scope globals by name (no return, by design):
+#   applied_pct, applied_reset       — values to render in the statusline now
+#   applied_hw_pct, applied_hw_reset — values to persist back to highwater.json
+# Caller must read these immediately after the call; the next invocation
+# clobbers them. Side effect is intentional: bash can't return composite values
+# cleanly, and threading four out-params through every call site was worse.
+apply_hw() {
+  local live_pct="$1" live_reset="$2" hw_pct="$3" hw_reset="$4"
+  local now reset_diff live_ok=0 hw_ok=0
+  now=$(date +%s)
+
+  if is_uint "$hw_reset" && [ "$hw_reset" -le "$now" ]; then
+    hw_pct=""
+    hw_reset=""
+  fi
+  if is_uint "$live_reset" && [ "$live_reset" -le "$now" ]; then
+    live_pct=""
+    live_reset=""
+  fi
+  if is_uint "$live_reset" && is_uint "$hw_reset"; then
+    reset_diff=$((live_reset - hw_reset))
+    [ "$reset_diff" -lt 0 ] && reset_diff=$((-reset_diff))
+    if [ "$reset_diff" -gt "$HIGHWATER_RESET_SKEW_MAX" ]; then
+      hw_pct=""
+      hw_reset=""
+    fi
+  fi
+
+  is_uint "$live_pct" && live_ok=1
+  is_uint "$hw_pct" && hw_ok=1
+
+  applied_pct=""
+  applied_reset=""
+  applied_hw_pct=""
+  applied_hw_reset=""
+  if [ "$live_ok" = "0" ] && [ "$hw_ok" = "0" ]; then
+    return
+  fi
+  if [ "$live_ok" = "0" ]; then
+    applied_pct="$hw_pct"
+    applied_reset="$hw_reset"
+    applied_hw_pct="$hw_pct"
+    applied_hw_reset="$hw_reset"
+    return
+  fi
+  if [ "$hw_ok" = "0" ] || [ "$live_pct" -gt "$hw_pct" ] 2>/dev/null; then
+    applied_pct="$live_pct"
+    applied_reset="$live_reset"
+    applied_hw_pct="$live_pct"
+    applied_hw_reset="$live_reset"
+    return
+  fi
+
+  applied_pct="$hw_pct"
+  applied_reset="${live_reset:-$hw_reset}"
+  applied_hw_pct="$hw_pct"
+  applied_hw_reset="$hw_reset"
+}
+
+write_highwater() {
+  is_uint "$new_hw_5h_pct" || is_uint "$new_hw_7d_pct" || return
+  mkdir -p "$CACHE_DIR" 2>/dev/null || return
+  local r5="${new_hw_5h_reset:-0}" r7="${new_hw_7d_reset:-0}"
+  is_uint "$r5" || r5=0
+  is_uint "$r7" || r7=0
+  if ! {
+    {
+      printf '{\n'
+      if is_uint "$new_hw_5h_pct"; then
+        printf '  "five_hour": {"used_percentage": %s, "resets_at": %s}' "$new_hw_5h_pct" "$r5"
+        is_uint "$new_hw_7d_pct" && printf ','
+        printf '\n'
+      fi
+      if is_uint "$new_hw_7d_pct"; then
+        printf '  "seven_day": {"used_percentage": %s, "resets_at": %s}\n' "$new_hw_7d_pct" "$r7"
+      fi
+      printf '}\n'
+    } > "${HIGHWATER_FILE}.tmp" 2>/dev/null \
+      && mv "${HIGHWATER_FILE}.tmp" "$HIGHWATER_FILE" 2>/dev/null
+  }; then
+    :
+  fi
+}
+
+apply_highwater_all() {
+  read_highwater
+
+  apply_hw "$five_pct" "$five_reset" "$hw_5h_pct" "$hw_5h_reset"
+  five_pct="$applied_pct"
+  five_reset="$applied_reset"
+  new_hw_5h_pct="$applied_hw_pct"
+  new_hw_5h_reset="$applied_hw_reset"
+
+  apply_hw "$seven_pct" "$seven_reset" "$hw_7d_pct" "$hw_7d_reset"
+  seven_pct="$applied_pct"
+  seven_reset="$applied_reset"
+  new_hw_7d_pct="$applied_hw_pct"
+  new_hw_7d_reset="$applied_hw_reset"
+}
+
+# Single jq pass for live input
+parsed=""
+[ -n "$input" ] && parsed=$(printf '%s' "$input" | jq -r "$jq_full" 2>/dev/null)
+
+IFS="$tab" read -r used_tokens window_size live_five_pct live_five_reset live_seven_pct live_seven_reset <<EOF
+$parsed
+EOF
+
+five_pct="${live_five_pct:-}"
+five_reset="${live_five_reset:-}"
+seven_pct="${live_seven_pct:-}"
+seven_reset="${live_seven_reset:-}"
+
+# If rate_limits missing from live input, read from cache
+if [ "$five_pct" = "null" ] || [ -z "$five_pct" ]; then
+  if [ -f "$CACHE_FILE" ]; then
+    cache_mtime=$(cache_file_mtime "$CACHE_FILE")
+    cache_age=$(( $(date +%s) - cache_mtime ))
+    if [ "$cache_age" -lt "$CACHE_MAX_AGE" ]; then
+      cached=$(jq -r "$jq_rl" "$CACHE_FILE" 2>/dev/null)
+      IFS="$tab" read -r five_pct five_reset seven_pct seven_reset <<EOF
+$cached
+EOF
+    fi
+  fi
+fi
+
+# Persist live rate_limits only when present (atomic write)
+if [ "${live_five_pct:-}" != "null" ] && [ -n "${live_five_pct:-}" ] && [ -n "$input" ]; then
+  mkdir -p "$CACHE_DIR"
+  if ! {
+    printf '%s' "$input" | jq '{rate_limits: .rate_limits}' \
+      > "${CACHE_FILE}.tmp" 2>/dev/null \
+      && mv "${CACHE_FILE}.tmp" "$CACHE_FILE" 2>/dev/null
+  }; then
+    :
+  fi
+fi
+
+new_hw_5h_pct=""
+new_hw_5h_reset=""
+new_hw_7d_pct=""
+new_hw_7d_reset=""
+if acquire_highwater_lock; then
+  apply_highwater_all
+  write_highwater
+  release_highwater_lock
+else
+  apply_highwater_all
+fi
+
+# --- Colors ---
+RESET="\033[0m"
+DIM="\033[2m"
+GREEN="\033[32m"
+YELLOW="\033[33m"
+RED="\033[31m"
+BLUE="\033[94m"
+MAGENTA="\033[95m"
+
+# Format seconds remaining as "4h23m" or "1d21h"
+format_reset() {
+  local ts="$1"
+  [ -z "$ts" ] && return
+  local epoch now diff
+  epoch=$(printf '%s' "$ts" | tr -dc '0-9')
+  [ -z "$epoch" ] && return
+  now=$(date +%s)
+  diff=$((epoch - now))
+  [ "$diff" -le 0 ] && return
+  local mins=$(( diff / 60 ))
+  local hours=$(( mins / 60 ))
+  local days=$(( hours / 24 ))
+  if [ "$days" -ge 1 ]; then
+    printf "%dd%dh" "$days" $(( hours % 24 ))
+  elif [ "$hours" -ge 1 ]; then
+    printf "%dh%dm" "$hours" $(( mins % 60 ))
+  else
+    printf "%dm" "$mins"
+  fi
+}
+
+# Context %
+ctx_pct=0
+if [ "$window_size" -gt 0 ] 2>/dev/null; then
+  ctx_pct=$(awk -v u="${used_tokens:-0}" -v t="$window_size" 'BEGIN { printf "%d", (u/t)*100 }')
+fi
+if [ "$ctx_pct" -ge 85 ] 2>/dev/null; then
+  ctx_color="$RED"
+elif [ "$ctx_pct" -ge 70 ] 2>/dev/null; then
+  ctx_color="$YELLOW"
+else
+  ctx_color="$GREEN"
+fi
+context_part="${DIM}Context${RESET} ${ctx_color}${ctx_pct}%${RESET}"
+
+# Usage color
+usage_color() {
+  local pct="$1"
+  if [ "$pct" -ge 90 ] 2>/dev/null; then printf "%s" "$RED"
+  elif [ "$pct" -ge 70 ] 2>/dev/null; then printf "%s" "$MAGENTA"
+  else printf "%s" "$BLUE"
+  fi
+}
+
+# 5h part
+if [ "$five_pct" != "null" ] && [ -n "$five_pct" ]; then
+  color=$(usage_color "$five_pct")
+  reset_str=$(format_reset "$five_reset")
+  if [ -n "$reset_str" ]; then
+    five_part="${DIM}5h:${RESET} ${color}${five_pct}%${RESET} ${DIM}(${reset_str})${RESET}"
+  else
+    five_part="${DIM}5h:${RESET} ${color}${five_pct}%${RESET}"
+  fi
+else
+  five_part="${DIM}5h: --${RESET}"
+fi
+
+# 7d part
+if [ "$seven_pct" != "null" ] && [ -n "$seven_pct" ]; then
+  color=$(usage_color "$seven_pct")
+  reset_str=$(format_reset "$seven_reset")
+  if [ -n "$reset_str" ]; then
+    seven_part="${DIM}7d:${RESET} ${color}${seven_pct}%${RESET} ${DIM}(${reset_str})${RESET}"
+  else
+    seven_part="${DIM}7d:${RESET} ${color}${seven_pct}%${RESET}"
+  fi
+else
+  seven_part="${DIM}7d: --${RESET}"
+fi
+
+printf "%b | %b | %b\n" "$context_part" "$five_part" "$seven_part"

package/scripts/validate_package.py

@@ -0,0 +1,66 @@
+#!/usr/bin/env python3
+"""Post-package integrity check for the Claude Desktop dispatcher ZIP.
+
+Invoked by scripts/package-skill.sh after the ZIP is unpacked into a temp
+directory. Verifies the generated root SKILL.md exists, carries the ninja
+marker, inlines every skill section, and has no broken nested SKILL.md path
+references.
+
+Lives in scripts/ (build-time only); never shipped to end users, so it stays
+a real file rather than a heredoc.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+
+EXPECTED_SKILLS = ["think", "design", "check", "hunt", "write", "learn", "read", "health"]
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("stage", type=Path, help="Extracted ZIP root")
+    args = parser.parse_args()
+
+    root_skill = args.stage / "SKILL.md"
+    if not root_skill.exists():
+        print("POST-PACKAGE ERROR: SKILL.md missing from extracted ZIP", file=sys.stderr)
+        return 1
+
+    text = root_skill.read_text()
+
+    if "Prefix your first line with 🥷 inline" not in text:
+        print(
+            "POST-PACKAGE ERROR: root SKILL.md missing ninja prefix instruction",
+            file=sys.stderr,
+        )
+        return 1
+
+    for skill in EXPECTED_SKILLS:
+        if f"# SKILL: {skill}" not in text:
+            print(
+                f"POST-PACKAGE ERROR: SKILL section '{skill}' not inlined in root SKILL.md",
+                file=sys.stderr,
+            )
+            return 1
+
+    # The packager rewrites `skills/<name>/SKILL.md` references to the inlined
+    # section name. Any stragglers indicate a regex bug in the rewriter.
+    for skill in ("check", "think"):
+        if f"skills/{skill}/SKILL.md" in text:
+            print(
+                "POST-PACKAGE ERROR: root SKILL.md still contains nested "
+                f"SKILL.md path references (e.g. skills/{skill}/SKILL.md)",
+                file=sys.stderr,
+            )
+            return 1
+
+    print("ok: post-package validation passed")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/verify_skills.py

@@ -0,0 +1,100 @@
+#!/usr/bin/env python3
+"""Validate Waza skill metadata, references, marketplace, and resolver invariants.
+
+Driver only. Validation logic lives in two sibling modules so both can be
+imported and unit-tested without invoking argparse:
+  - `skill_frontmatter.py`  -- parse_frontmatter, parse_when_to_use_keywords, fail
+  - `skill_checks.py`       -- all check_* functions
+
+Run as: python3 scripts/verify_skills.py [--root PATH] [--skills-only]
+
+Default --root is the repository root inferred from this file's location.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+# Allow `from skill_frontmatter import ...` style imports when invoked as a
+# standalone script. Tests and codegen import directly via sys.path tricks.
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from skill_frontmatter import fail  # noqa: E402
+from skill_checks import (  # noqa: E402
+    check_attribution_leak,
+    check_description_conformance,
+    check_durable_context_and_paths,
+    check_english_coaching_guard,
+    check_marketplace,
+    check_markdown_links,
+    check_no_root_skill,
+    check_readme_install_command,
+    check_references,
+    check_resolver,
+    check_rules_files_present,
+    check_skill_files,
+    check_table_pipes,
+    check_trigger_overlap,
+    collect_all_md,
+)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--root",
+        type=Path,
+        default=Path(__file__).resolve().parent.parent,
+        help="Repository root (default: parent of scripts/)",
+    )
+    parser.add_argument(
+        "--skills-only",
+        action="store_true",
+        help=(
+            "Verify only per-skill frontmatter under <root>/skills/. Skips "
+            "marketplace.json, RESOLVER.md, README, and root-level checks. "
+            "Use when validating an installed copy that does not ship the "
+            "build-only files."
+        ),
+    )
+    args = parser.parse_args()
+    root = args.root.resolve()
+
+    skill_files, skill_descriptions, skill_keywords = check_skill_files(root)
+    skill_names = set(skill_descriptions)
+    check_description_conformance(skill_descriptions)
+    if (root / "rules" / "durable-context.md").exists():
+        check_durable_context_and_paths(root, skill_files)
+
+    if args.skills_only:
+        # Installed copies (e.g. ~/.claude/skills/) don't ship VERSION,
+        # marketplace.json, RESOLVER.md, or the repo README. Stop here.
+        print(f"ok: skills-only verification passed for {len(skill_files)} skills")
+        return 0
+
+    version_file = root / "VERSION"
+    if not version_file.exists():
+        fail("MISSING VERSION FILE: expected top-level VERSION with one line like '3.24.0'")
+    expected_version = version_file.read_text().strip()
+    if not expected_version:
+        fail("EMPTY VERSION FILE: VERSION must contain one line like '3.24.0'")
+
+    check_marketplace(root, expected_version, skill_names, skill_descriptions)
+    check_references(root, skill_files)
+    resolver_path = check_resolver(root, skill_names)
+    all_md = collect_all_md(root, skill_names, resolver_path)
+    check_markdown_links(root, all_md)
+    check_table_pipes(root, all_md)
+    check_no_root_skill(root)
+    check_trigger_overlap(skill_keywords)
+    check_rules_files_present(root)
+    check_readme_install_command(root)
+    check_english_coaching_guard(root)
+    check_attribution_leak(root)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/RESOLVER.md

@@ -0,0 +1,91 @@
+# Waza Skill Resolver
+
+## Shared Output Marker
+
+所有技能都沿用同一个输出约定：首行内联带上 `🥷`，不要单独起段。这个约定写在各自的 `SKILL.md` 里，`verify-skills.sh` 也会校验它。
+
+触发词到技能的路由表。Claude Code 通过每个 SKILL.md 的 `description` 自动匹配，这份文档是给人看的集中索引，也是 `verify-skills.sh` 的校验依据。改 SKILL.md 的适用范围时，同步改这里。
+
+> **Read the skill file before acting.** 两个技能都可能匹配时，两个都读。它们设计成可串联（例：`/think` → 实现 → `/check`）。
+
+## 按工作流阶段分路
+
+### Pre-build（动手前）
+
+| 触发 | 技能 |
+|------|------|
+| 新功能 / 架构决策 / "怎么设计" / "应该用什么方案" / "判断一下" / "有没有必要" / "值不值得" / 商业化/产品 pivot / 需要可执行计划或 handoff | `skills/think/SKILL.md` |
+| UI / 组件 / 页面 / 视觉界面 / 前端 / 截图里说"丑"、"不清晰"、"很怪" / 真实截图视觉 polish | `skills/design/SKILL.md` |
+
+### Post-build（交付前）
+
+| 触发 | 技能 |
+|------|------|
+| 实现完成 / 合并前 / "review 一下" / "看看这段代码" / release gate / 生成产物检查 / safety sink 审查 / `code-review` | `skills/check/SKILL.md` |
+| release / publish / push / release reaction / 发布 / 提交 / 关闭 issue / 发布前检查 / 发布表情 / registry/appcast/asset 检查 | `skills/check/SKILL.md` (Ship / Release Follow-through) |
+| review issue / review PR / triage / 批量处理 / "看看有没有 issue" / close issue | `skills/check/SKILL.md` (Triage Mode) |
+| 项目体检 / project audit / 项目评分 / 给项目打分 / 深入分析项目代码 / 评估项目质量 / 代码质量评分 / scorecard / linus 风格 review / rate this codebase / score this project | `skills/check/SKILL.md` (Project Audit Mode) |
+
+### Diagnostic（出问题了）
+
+| 触发 | 技能 |
+|------|------|
+| 报错 / 崩溃 / 测试失败 / 行为异常 / "为什么不工作" / 以前是好的 / 回归 / 截图回归 / 反复修不好 / stale cache / 队列或生成物边界 | `skills/hunt/SKILL.md` |
+| Claude/Codex 忽略指令 / hook 失灵 / MCP 异常 / Codex 配置 / AGENTS.md / config.toml / agent instructions / 配置审计 / health 消耗 token / AI coding 腐化 / 代码变烂 / 维护性 / hotspot ownership / 上下文混乱 / 验证缺失 / 验证命令失真 | `skills/health/SKILL.md` |
+
+### Content（内容进出）
+
+| 触发 | 技能 |
+|------|------|
+| 消息含 http(s) URL / 任何网页链接 / PDF 路径 / "看一下这个", "读一下这个" | `skills/read/SKILL.md` |
+| 写作 / 改稿 / 润色 / 去 AI 味（中英文） / 推特推文 / 社交媒体文案 / launch copy / release notes 文案 | `skills/write/SKILL.md` |
+| 文档审阅 / 白皮书 / release notes prose 审核 / "审稿" / "check this document" | `skills/write/SKILL.md` (Document Review Mode) |
+| 深度研究一个陌生领域 / 六阶段研究到成稿 / 一批材料沉淀成文章 | `skills/learn/SKILL.md` |
+
+## Disambiguation（歧义消解）
+
+多个技能都可能匹配时按以下规则：
+
+1. **最具体优先**：`/design` 比 `/think` 更具体（仅限 UI 决策）。用户说"帮我设计登录页"时优先 `/design`。
+2. **URL 按内容类型二次分流**：消息含 URL → 先走 `/read` 取回 Markdown → 如果用户要总结或分析，继续完成总结或分析；如果是长文研究性素材再接 `/learn`。
+3. **改错 vs review**：代码已经交付或走到 PR → `/check`；代码跑不通或行为错了 → `/hunt`。两者都可能匹配"帮我看看"，按"有没有具体错误现象"判断。
+4. **配置/维护性异常 vs 代码错误**：Claude/Codex 本身不听话、hook 不触发、MCP 掉链子、AGENTS/CLAUDE/config.toml 漂移、`/health` 消耗 token、AI coding 腐化、上下文混乱、验证缺失或验证命令失真 → `/health`；用户写的代码抛异常 → `/hunt`。
+5. **发布动作 vs 发布文案**：要写 release notes / changelog → `/write`；要提交、打 tag、publish、push、上传 release asset、补 GitHub release reactions、回复/关闭 issue → `/check`。
+6. **截图审美 vs 截图回归**：截图里说"丑/不好看/不清晰"且是审美校准 → `/design`；截图证明以前好的现在坏了、渲染错、状态错、生成物错 → `/hunt`。
+7. **长文产出 vs 润色**：从零到成稿 → `/learn`；已有稿子要改 → `/write`。
+8. **判断 vs 调试**："判断一下" + 报错/异常/不工作 → `/hunt`（诊断问题）；"判断一下" + 有没有必要/该不该保留/值不值得 → `/think` Evaluation Mode（价值判断）。
+9. **继续优化 vs 调试**："继续优化" / "优化代码" 不含报错或异常现象 → `/check`（代码质量改善）；有具体报错或回归 → `/hunt`。
+10. **兜底**：两个都模糊时读两个 SKILL.md 的 "Not for" 段，用排除法；还是模糊就问用户。
+
+## Chaining（常见串联）
+
+技能之间的转换需要用户手动触发，不会自动串联。每个技能完成后会停下来，等你决定下一步。
+
+- `/think` 出方案 → **用户说"实现"** → 实施 → **用户说"/check"** → `/check` 把关
+- `/think` 出可执行计划 → **用户说"Implement the plan / 可以干 / 直接改"** → 按计划实施，不重新争论方向
+- `/hunt` 修复 issue → **用户说"发布 / push / 关闭 issue"** → `/check` 做发布前检查和收尾
+- `/read` 取回多篇 URL → **用户说"/learn"** → `/learn` 综合成文
+- `/learn` 出初稿 → **用户说"/write"** → `/write` 去 AI 味
+- `/hunt` 定位根因 → **用户说"修"** → 修完 → **用户说"/check"** → `/check` 确认没副作用
+- `/health` 发现 skill 配置问题 → **用户说"修"** → 修完 → **用户说"/health"** → 再跑一次 `/health`
+
+## Latent vs Deterministic
+
+Waza 的技能都是 fat skill（Markdown 判断），底层的确定性约束走 `scripts/verify-skills.sh` 和 `rules/*.md`。新加能力时先问：
+
+- 需要判断 / 适应场景 / 追问用户？→ skill
+- 同入同出 / 只是校验和列举？→ script 或 rule
+
+不要把 lint 检查写成 skill，也不要把"怎么研究一个陌生领域"塞进脚本。详见根目录 `AGENTS.md` 的决策表。
+
+## Project Context
+
+通用程序员能力沉淀在 Waza。遇到具体项目时，先从公开项目上下文提炼约束，再执行对应技能：
+
+- `code-review` / `/check` -> 从 diff、README、manifest、CI、release notes 中提炼验证命令、生成物、风险、safety sinks 和发布规则。
+- `github-ops` -> 复用 `skills/check/SKILL.md` 的 Triage Mode，并从 issue/PR 现场确认 repo、发布状态和回复语言。
+- `release` -> 从项目公开发布文档、脚本和 CI 中确认前置条件、产物和验证命令。
+
+本地 durable memory / preview 可以作为可选私有上下文来理解用户偏好、旧决策和可迁移模式；它不属于公开项目约束，且必须用当前代码、日志、测试、文档或远端状态重新验证。
+
+不要把证书路径、私钥文件名、token、个人机器路径或未公开的机器配置写进 Waza。