dsh-superpower 6.3.0

package/skills/using-superpowers/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: using-superpowers
+description: "适用于任何对话开始前，建立技能查找与调用规范，要求在任何回复前优先调用相关技能，包括澄清问题"
+---
+
+<SUBAGENT-STOP>
+如果你是作为子代理被派来执行特定任务，请忽略本技能。
+</SUBAGENT-STOP>
+
+<EXTREMELY-IMPORTANT>
+如果你认为有哪怕 1% 的可能性某个技能适用于你当前要做的事，你就**必须**调用该技能。
+
+如果某项任务适用某个技能，你别无选择，必须使用它。
+
+这没有商量余地，你不能为自己找借口绕开它。
+</EXTREMELY-IMPORTANT>
+
+## 规则
+
+**在任何回复或行动之前先调用相关或被请求的技能**——包括澄清问题、探索代码库或检查文件。如果事后发现不适用于当前情况，可以不使用它。
+
+**进入规划模式之前：** 如果尚未进行头脑风暴，请先调用头脑风暴技能。
+
+然后宣告 "Using [skill] to [purpose]" 并严格按技能要求执行。如果技能包含清单，请为每一项创建一个待办。
+
+## 技能优先级
+
+当多个技能同时适用时，流程类技能优先——它们决定方法论，然后由实现类技能（如 frontend-design 等）负责落地。头脑风暴与系统化调试是 Superpowers 中最常见的流程技能，但该规则适用于所有技能。
+
+- "Let's build X" → 优先使用 superpowers:brainstorming，再使用实现类技能。
+- "Fix this bug" → 优先使用 superpowers:systematic-debugging，再使用领域技能。
+
+## 警示信号
+
+出现以下想法时请立刻停下——你正在为自己找借口：
+
+| 想法 | 现实 |
+|---------|---------|
+| "这只是个简单问题" | 问题也是任务，先检查技能。 |
+| "我需要先了解更多上下文" | 技能检查应在澄清问题之前。 |
+| "我先探索一下代码库" | 技能会告诉你如何探索，先检查技能。 |
+| "我可以快速看一下 git/文件" | 文件缺少对话上下文，先检查技能。 |
+| "我先收集一下信息" | 技能会告诉你如何收集信息。 |
+| "这不需要正式的技能" | 只要技能存在，就要用。 |
+| "我记得这个技能" | 技能会演进，请阅读当前版本。 |
+| "这不算任务" | 有行动就是任务，检查技能。 |
+| "用技能太小题大做了" | 简单的事情也会变复杂，请使用技能。 |
+| "我就先做这一件事" | 做任何事之前先检查。 |
+| "这样做感觉很高效" | 无章法的行动只会浪费时间，技能可以避免。 |
+| "我知道那是什么意思" | 知道概念不等于会用技能，请调用它。 |
+
+## 平台适配
+
+如果你的执行环境出现在此列表中，请先阅读对应的参考文件获取专项说明：
+
+- DSH (DeepSeek Harness): `references/dsh-tools.md` — **请优先阅读。** 将 Bash→pwsh/bash、Read/Write/Edit→fs、Glob/Grep→fs-search、Task/Subagent→subagent/workflow、TodoWrite→todo、AskUserQuestion→ask-user、Skill→skill 进行映射。本套件中的所有技能均假定使用 DSH 工具。
+- Codex: `references/codex-tools.md`
+- Pi: `references/pi-tools.md`
+- Antigravity: `references/antigravity-tools.md`
+- Hermes Agent: `references/hermes-tools.md`
+
+## 用户指令
+
+用户指令（CLAUDE.md、AGENTS.md、GEMINI.md 等，以及直接请求）的优先级高于技能，技能又高于默认行为。仅当人类协作方明确指示时，才可跳过技能工作流或指令。

package/skills/using-superpowers/references/antigravity-tools.md

@@ -0,0 +1,23 @@
+# Antigravity CLI (`agy`) Tool Mapping
+
+Skills speak in actions ("dispatch a subagent", "create a todo", "read a file"). On the Antigravity CLI (`agy`) these resolve to the tools below.
+
+| Action skills request | Antigravity CLI equivalent |
+|----------------------|----------------------|
+| Dispatch a subagent (`Subagent (general-purpose):` template) | `invoke_subagent` with a built-in `TypeName` — `self` for full-capability work, `research` for read-only |
+| Task tracking ("create a todo", "mark complete") | a **task artifact** — `write_to_file` with `IsArtifact: true` and `ArtifactType: "task"` (see [Task tracking](#task-tracking)). **Not** `manage_task`, which manages background processes. |
+
+## Task tracking
+
+Antigravity has **no todo tool** (`manage_task` manages background
+processes — `list`/`kill`/`status`/`send_input` — it is *not* a checklist). When a
+skill says to create a todo list or track tasks, maintain a **task artifact**: a
+markdown checklist saved with `write_to_file` (`IsArtifact: true`,
+`ArtifactMetadata.ArtifactType: "task"`), edited with `replace_file_content` /
+`multi_replace_file_content` as you go.
+
+At the start of any multi-step task, create the task artifact listing every step of
+your plan. As you complete each step, edit the artifact to mark it done (`- [x]`).
+If the plan changes, update the checklist. Keep it current — it is your source of
+truth for what remains; once the conversation gets long, re-read it before starting
+each step.

package/skills/using-superpowers/references/codex-tools.md

@@ -0,0 +1,108 @@
+## Subagent dispatch requires multi-agent support
+
+Add to your Codex config (`~/.codex/config.toml`):
+
+```toml
+[features]
+multi_agent = true
+```
+
+This enables the multi-agent tools that skills like
+`dispatching-parallel-agents` and `subagent-driven-development` use.
+Which tools you get depends on the multi-agent version your model
+preset selects (current presets run V2; older ones run V1). Trust your
+actual tool list over any table — including this one — when they
+disagree.
+
+- **Spawning:** give children a clean context with
+  `spawn_agent {fork_turns: "none"}`; the default `"all"` copies your
+  entire transcript into the child. On Codex 0.145+, role files under
+  `~/.codex/agents/` attach to isolated forks via `agent_type`.
+  Full-history forks accept `model` and `reasoning_effort` overrides
+  (only `agent_type` is refused there) — isolated forks are the SDD
+  default for context hygiene, not because overrides require them.
+- **Fix rounds:** resume the implementer with `followup_task` — it
+  delivers your message, triggers a turn, and transparently reloads a
+  child the harness evicted. Never dispatch a fresh implementer on the
+  theory that a spawned agent cannot be messaged again; on V2 it
+  always can.
+- **Lifecycle:** V2 has no `close_agent`. Finished children are
+  evicted automatically when slots are needed; leaving them unclosed
+  costs nothing. Only V1 sessions have `close_agent` — there, close
+  reviewers when their review returns, and close each implementer
+  after its task's review passes.
+- **Model names:** never copy a model name from a skill, table, or old
+  session into `spawn_agent` without checking it against your current
+  spawn allowlist — V2 accepts only V2-capable presets and hard-errors
+  on the rest.
+
+## Waiting on children
+
+`wait_agent` is an event subscription, not a poll: a long wait wakes
+the moment a child produces mailbox activity, with the same latency as
+a short one. Short-timeout polling buys nothing and costs a tool call —
+and a context rebill — per poll. In measured sessions, roughly
+two-thirds of all wait calls were short polls that timed out.
+
+- While you still have local work, do not wait at all. A completed
+  child's final answer is pushed into your mailbox and arrives with
+  your next turn.
+- When you are genuinely idle with children outstanding, wait in
+  bounded stretches: `wait_agent` with `timeout_ms` 300000-600000
+  (5-10 minutes). After each stretch — wake or timeout — post one
+  status line, run `list_agents`, and chase any child that finished
+  without reporting. Never stack polls shorter than five minutes; the
+  event subscription wakes a bounded stretch just as fast as a short
+  one.
+- Completion mail cannot wake an idle controller (it is delivered
+  without triggering a turn); covering that idle window is
+  `wait_agent`'s only job. A stretch that times out with no activity
+  is your cue to reconcile, not to shorten the next stretch.
+
+## Model routing on spawns
+
+Every `spawn_agent` you issue — including when you are yourself a
+spawned child running a fan-out — sets `model` AND `reasoning_effort`
+explicitly, per the Model Selection rules of the skill you are
+executing. Setting `model` alone is a trap: the child's effort
+silently resets to that model's default, not to yours.
+
+Ask your human partner to add a machine-level backstop to
+`~/.codex/config.toml` so any spawn that slips through still routes to
+a deliberate tier instead of silently inheriting the session's most
+expensive model:
+
+```toml
+[agents]
+default_subagent_model = "<a mid-tier model from your spawn allowlist>"
+default_subagent_reasoning_effort = "medium"
+```
+
+## Environment Detection
+
+Skills that create worktrees or finish branches should detect their
+environment with read-only git commands before proceeding:
+
+```bash
+GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
+GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
+BRANCH=$(git branch --show-current)
+```
+
+- `GIT_DIR != GIT_COMMON` → already in a linked worktree (skip creation)
+- `BRANCH` empty → detached HEAD (cannot branch/push/PR from sandbox)
+
+See `using-git-worktrees` Step 0 and `finishing-a-development-branch`
+Step 1 for how each skill uses these signals.
+
+## Codex App Finishing
+
+When the sandbox blocks branch/push operations (detached HEAD in an
+externally managed worktree), the agent commits all work and informs
+the user to use the App's native controls:
+
+- **"Create branch"** — names the branch, then commit/push/PR via App UI
+- **"Hand off to local"** — transfers work to the user's local checkout
+
+The agent can still run tests, stage files, and output suggested branch
+names, commit messages, and PR descriptions for the user to copy.

package/skills/using-superpowers/references/dsh-tools.md

@@ -0,0 +1,47 @@
+# DSH Tools Reference for Superpowers
+
+> 面向模型的 DSH 工具速查。Superpowers 原版文案中的 Claude Code / Codex 工具名在此映射为 DSH 等价物。
+> 当 skill 指示使用某一工具时，按下表替换即可。
+
+## 核心映射
+
+| 原版提及 | DSH 等价 | 备注 |
+|---|---|---|
+| `Bash` / `bash` | `pwsh`（首选，Windows 友好）或 `bash` | 长耗时命令用 `run_in_background: true`，通过 `job_output` / `job_list` 收敛 |
+| `Read` / `Write` / `Edit` | `fs` 工具的 `read` / `write` / `edit` | `read` 前无需 `fs/observed` 校验，`write/edit` 自动触发 `fs/observed` 失效 |
+| `Glob` / `Grep` / `Grep -R` | `fs-search` 工具的 `glob` / `grep` | `glob` 发现文件，`grep` 搜内容；大仓用 `include` 过滤 |
+| `Task` / `Subagent` | `subagent` / `subagent_fork` / `workflow` | 单任务派发用 `subagent`，多阶段扇出用 `workflow`（`agent`/`pipeline`/`parallel`） |
+| `AskUserQuestion` | `ask-user` | 阻塞式提问，遵守 `userQuestions` 策略 |
+| `TodoWrite` | `todo` | 每次提供全量列表，`in_progress` 至少一项 |
+| `Skill` | `skill` | `skill(name)` 加载 `<skill_content>`，与 `ctx.skills.get()` 同源 |
+| `WebSearch` / `WebFetch` | `web` 工具 | `web_search` + `web_fetch_exa` 已封装为统一 `web` |
+| `/skill superpowers:<name>` | `skill` 工具或用户显式 `/skill` 命令 | 两种路径渲染一致的 `<skill_content>` |
+| `git worktree` | `bash` / `pwsh` 中直接执行 `git worktree` | DSH 无 worktree 专属封装，按原命令执行 |
+
+## DSH 专属能力（原版无直接对应）
+
+| DSH 能力 | 何时用 |
+|---|---|
+| `goal` / `ralph` | 长周期目标的创建、续跑、阻塞判定 |
+| `workflow` 脚本 | 需要编排数十个 subagent 的审计/迁移/批量改写 |
+| `jobs` | 托管后台任务的查询与终止 |
+| `plan-mode` | 只读规划锁定，与 `writing-plans` 的细粒度切片互补 |
+| `cordis` 动态插件 | 会话内临时扩展能力（非本移植包范畴） |
+
+## 约束与习惯
+
+- 沙箱默认 `danger-full-access`，但仍需在 skill 中标注文件路径为绝对路径或相对 `cwd` 可解析路径。
+- PowerShell 中 `ls -la` / `head` 等 Unix 别名不可用，用 `Get-ChildItem` / `Select-Object -First N`。
+- 工具 `execute` 返回结构化 JSON，面向人类的渲染放在 `output.render`（对 skill 编写者）。
+- 所有 `waterfall` 事件监听必须调用 `next()`，否则短路下游。
+
+## 最小示例
+
+```text
+用户：帮我加一个重试工具
+模型：Using superpowers:brainstorming to clarify requirements
+      -> 调用 skill(name="brainstorming")
+      -> 按 skill 流程提问、分类 Spike/Bounded/Architectural
+      -> 设计获批后调用 skill(name="writing-plans") 切片
+      -> 每切片派发 subagent(prompt="实现 task-03...") 并用 todo 跟踪
+```

package/skills/using-superpowers/references/gemini-tools.md

@@ -0,0 +1,63 @@
+# Gemini CLI Tool Mapping
+
+Skills speak in actions ("dispatch a subagent", "create a todo", "read a file"). On Gemini CLI these resolve to the tools below.
+
+| Action skills request | Gemini CLI equivalent |
+|----------------------|----------------------|
+| Read a file | `read_file` |
+| Read multiple files at once | `read_many_files` |
+| Create a new file | `write_file` |
+| Edit a file | `replace` |
+| Run a shell command | `run_shell_command` |
+| Search file contents | `grep_search` |
+| Find files by name | `glob` |
+| List files and subdirectories | `list_directory` |
+| Fetch a URL | `web_fetch` |
+| Search the web | `google_web_search` |
+| Invoke a skill | `activate_skill` |
+| Dispatch a subagent (`Subagent (general-purpose):` template) | `invoke_agent` with `agent_name: "generalist"` (invocable via `@generalist` chat syntax — see [Subagent support](#subagent-support)) |
+| Multiple parallel dispatches | Multiple `invoke_agent` calls in the same response |
+| Task tracking ("create a todo", "mark complete") | `write_todos` (statuses: pending, in_progress, completed, cancelled, blocked) |
+
+## Instructions file
+
+When a skill mentions "your instructions file", on Gemini CLI this is **`GEMINI.md`**. Gemini CLI loads `GEMINI.md` hierarchically: global at `~/.gemini/GEMINI.md`, project-level files in workspace directories and their ancestors, and sub-directory `GEMINI.md` files when a tool accesses files in those directories.
+
+## Personal skills directory
+
+User-level skills live at **`~/.gemini/skills/`**, with **`~/.agents/skills/`** as a cross-runtime alias (shared with Codex and Copilot CLI). When both directories exist at the same scope, `.agents/skills/` takes precedence. Each skill is a subdirectory containing a `SKILL.md` (with `name` and `description` frontmatter).
+
+## Subagent support
+
+Gemini CLI dispatches subagents through the `invoke_agent` tool, which takes `agent_name` and `prompt` parameters. The same dispatch is also surfaced as a chat-syntax shortcut: typing `@generalist <prompt>` is equivalent to calling `invoke_agent` with `agent_name: "generalist"`. Built-in agent names include `generalist`, `cli_help`, `codebase_investigator`, and (with browser tooling enabled) `browser_agent`.
+
+Skills dispatch with `Subagent (general-purpose):` and either reference a prompt-template file (e.g., `superpowers:subagent-driven-development`'s `./implementer-prompt.md`) or supply an inline prompt. On Gemini CLI:
+
+| Skill dispatch form | Gemini CLI equivalent |
+|---------------------|----------------------|
+| References a `*-prompt.md` template (implementer, task-reviewer, code-reviewer, etc.) | Fill the template, then `invoke_agent` with `agent_name: "generalist"` and the filled prompt |
+| References `superpowers:requesting-code-review`'s `./code-reviewer.md` | `invoke_agent` with `agent_name: "generalist"` and the filled review template |
+| Inline prompt (no template referenced) | `invoke_agent` with `agent_name: "generalist"` and your inline prompt |
+
+### Prompt filling
+
+Skills provide prompt templates with placeholders like `{WHAT_WAS_IMPLEMENTED}` or `[FULL TEXT of task]`. Fill all placeholders before passing the complete prompt to `invoke_agent`. The prompt template itself contains the agent's role, review criteria, and expected output format — the subagent will follow it.
+
+### Parallel dispatch
+
+Gemini CLI supports parallel subagent dispatch. Issue multiple `invoke_agent` calls in the same response (or multiple `@generalist` invocations in one prompt) to run independent subagent work in parallel. Keep dependent tasks sequential, but do not serialize independent subagent tasks just to preserve a simpler history.
+
+## Additional Gemini CLI tools
+
+These tools are unique to Gemini CLI:
+
+| Tool | Purpose |
+|------|---------|
+| `save_memory` (legacy) | Persist facts across sessions when `experimental.memoryV2 = false` |
+| `get_internal_docs` | Look up Gemini CLI's bundled documentation |
+| `ask_user` | Pose structured questions to the user (text / single-select / multi-select) |
+| `enter_plan_mode` / `exit_plan_mode` | Switch into and out of read-only plan mode |
+| `update_topic` | Update the current conversation's topic / strategic-intent metadata |
+| `complete_task` | Signal that a Gemini subagent has completed and return its result to the parent agent |
+| `tracker_create_task`, `tracker_update_task`, `tracker_get_task`, `tracker_list_tasks`, `tracker_add_dependency`, `tracker_visualize` | Rich task tracker with dependency and visualization support |
+| `read_mcp_resource`, `list_mcp_resources` | MCP resource access |

package/skills/using-superpowers/references/hermes-tools.md

@@ -0,0 +1,56 @@
+# Hermes Agent Tool Mapping
+
+Skills speak in actions ("dispatch a subagent", "create a todo", "read a file"). On Hermes Agent these resolve to the tools below.
+
+## Tools
+
+| Action skills request | Hermes tool |
+|---|---|
+| Read a file | `read_file` |
+| Create a new file | `write_file` |
+| Edit a file (targeted patch) | `patch` |
+| Run a shell command | `terminal` |
+| Search file contents | `search_files` |
+| Find files by name | `terminal` with `find` |
+| Fetch a URL / read a webpage | `web_extract(urls=[...])` |
+| Search the web | `web_search(query=...)` |
+| Dispatch a subagent | `delegate_task(goal=..., context=..., toolsets=[...], role="leaf")` |
+| Task tracking | `todo` tool |
+| Invoke a skill | `skill_view("skill-name")` |
+
+## Instructions file
+
+When a skill mentions "your instructions file," on Hermes Agent this is **`AGENTS.md`** in the project directory, or **`SOUL.md`** globally at `~/.hermes/SOUL.md`.
+
+## Invoking a skill
+
+Hermes Agent has a `skills` toolset with `skill_view` and `skills_list` tools.
+To invoke a superpowers skill, use:
+
+```
+skill_view("brainstorming")
+skill_view("test-driven-development")
+```
+
+If `skill_view` cannot find a superpowers skill (it may not appear in the catalog
+until the plugin fully registers it), fall back to reading the SKILL.md directly:
+
+```
+read_file(path="~/.hermes/plugins/superpowers/skills/<skill-name>/SKILL.md")
+```
+
+This fallback is the same mechanism used by other harnesses without native skill loading.
+
+## Subagent dispatch
+
+Use `delegate_task` to spawn isolated subagents for parallel or sequential workstreams:
+
+```
+delegate_task(goal="...", context="...", toolsets=[...], role="leaf")
+```
+
+If `delegate_task` is unavailable, do the work inline rather than inventing tool calls.
+
+## Task tracking
+
+Use the `todo` tool for task tracking within a session. For multi-agent task boards, use `hermes kanban` CLI if available. Treat older `TodoWrite` references as the task-tracking action.

package/skills/using-superpowers/references/pi-tools.md

@@ -0,0 +1,16 @@
+# Pi Tool Mapping
+
+Skills speak in actions ("dispatch a subagent", "create a todo", "read a file"). On Pi these resolve to the tools below.
+
+| Action skills request | Pi equivalent |
+| --- | --- |
+| Dispatch a subagent (`Subagent (general-purpose):` template) | Use an installed subagent tool such as `subagent` from `pi-subagents` if available |
+| Task tracking ("create a todo", "mark complete") | Use an installed todo/task tool if available, otherwise track tasks in the plan or `TODO.md` |
+
+## Subagents
+
+Pi core does not ship a standard subagent tool. The `pi-subagents` package is a strong optional companion and provides a `subagent` tool with single-agent, chain, parallel, async, forked-context, and resume/status workflows. If no subagent tool is available, do not fabricate `Task` calls; execute sequentially in the current session or explain that the optional subagent capability is not installed.
+
+## Task lists
+
+Pi core does not ship a standard task-list tool. If a todo/task extension is installed, use its documented tool. Otherwise use Superpowers plan files, checklists in Markdown, or a repo-local `TODO.md` for task tracking. Older Superpowers docs may refer to `TodoWrite`; treat that as the task-tracking action above.

package/skills/verification-before-completion/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: verification-before-completion
+description: "在声称完成、修复或通过前强制执行校验，用于提交或创建PR前必须运行验证命令并确认输出，始终以证据为准而非断言"
+---
+
+# 完成前的校验
+
+## 概述
+
+**核心原则：** 始终以证据为先，再作断言。
+
+**违背规则的字面，即是违背规则的精神。**
+
+## 铁律
+
+```
+未经全新的校验证据，不得声称完成
+```
+
+若在本条消息中未运行校验命令，则不得声称其已通过。
+
+## 门禁流程
+
+```
+在声称任何状态或表达满意之前：
+
+1. 识别：哪条命令能证明该断言？
+2. 执行：完整执行该命令（全新、完整）
+3. 读取：完整输出，检查退出码，统计失败数
+4. 核验：输出是否印证该断言？
+   - 若否：如实陈述实际状态并附上证据
+   - 若是：附证据再作断言
+5. 仅在此之后：方可提出断言
+
+跳过任何一步即等同于撒谎，而非校验
+```
+
+## 常见失效场景
+
+| 断言 | 所需证据 | 不充分的依据 |
+|-------|----------|----------------|
+| 测试通过 | 测试命令输出：0 失败 | 历史运行结果、“应该能过” |
+| Lint 干净 | Linter 输出：0 错误 | 局部检查、推断外延 |
+| 构建成功 | 构建命令：exit 0 | Linter 通过、日志看起来正常 |
+| 缺陷已修复 | 复现原症状的测试：通过 | 已改代码、想当然认为已修 |
+| 回归测试有效 | 红绿循环已验证 | 仅通过一次 |
+| 代理已完成 | VCS diff 显示有变更 | 代理报告“成功” |
+| 需求已满足 | 逐项核对清单 | 测试通过 |
+
+## 危险信号 - 立即停止
+
+- 使用“应该”“大概”“似乎”等不确定表述
+- 校验前就表达满意（“太好了！”“完美！”“搞定了！”等）
+- 未经校验就准备 commit / push / 提 PR
+- 轻信代理的成功报告
+- 依赖局部校验
+- 心存“就这一次”的侥幸
+- 因疲惫而想草草收工
+- **任何未运行校验就暗示成功的措辞**
+
+## 防止自我合理化
+
+| 借口 | 事实 |
+|--------|---------|
+| “现在应该能行了” | 去运行校验 |
+| “我很有把握” | 把握 ≠ 证据 |
+| “就这一次” | 没有例外 |
+| “Linter 过了” | Linter ≠ 编译器 |
+| “代理说成功了” | 需独立核验 |
+| “我太累了” | 疲惫不是理由 |
+| “局部检查就够了” | 局部证明不了任何事 |
+| “换个说法就不算违规” | 重精神而非抠字眼 |
+
+## 关键模式
+
+**测试：**
+```
+✅ [执行测试命令] [看到：34/34 通过] “所有测试通过”
+❌ “现在应该能过了” / “看起来是对的”
+```
+
+**回归测试（TDD 红绿循环）：**
+```
+✅ 编写 → 运行（通过）→ 回退修复 → 运行（必须失败）→ 恢复 → 运行（通过）
+❌ “我已写好回归测试”（未经红绿验证）
+```
+
+**构建：**
+```
+✅ [执行构建] [看到：exit 0] “构建通过”
+❌ “Linter 过了”（Linter 不检查编译）
+```
+
+**需求：**
+```
+✅ 重读方案 → 创建核对清单 → 逐项核验 → 报告缺口或完成情况
+❌ “测试通过，阶段完成”
+```
+
+**代理委派：**
+```
+✅ 代理报告成功 → 检查 VCS diff → 核验变更 → 报告实际状态
+❌ 轻信代理报告
+```
+
+## 适用时机
+
+**始终在以下动作之前：**
+- 任何形式的成功/完成断言
+- 任何满意度的表达
+- 任何关于工作状态的肯定性陈述
+- 提交、创建 PR、任务收尾
+- 进入下一项任务
+- 委派给代理
+
+**规则适用于：**
+- 准确措辞
+- 改写与同义词
+- 暗示成功
+- 任何暗示完成/正确的沟通

package/skills/writing-plans/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: writing-plans
+description: "当已具备清晰的需求规格或多步骤任务说明且尚未开始编码时使用，用于把需求拆解为结构清晰、粒度可控、可直接执行、可测试与可验证的完整实施计划"
+---
+
+# 编写计划
+
+## 概述
+
+假设执行工程师对当前代码库零背景、品味存疑，为其编写全面、可落地的实施计划。需完整记录其所需的一切信息：每个任务涉及哪些文件、代码、测试、需要查阅的文档，以及如何验证。将整体计划拆解为粒度极细的小任务。遵循 DRY、YAGNI、TDD，频繁提交。
+
+假定对方是能力扎实的开发者，但对我们的工具链与问题域几乎一无所知，且不擅长良好的测试设计。
+
+**开始时声明：** “我将使用 writing-plans 技能来创建实施计划。”
+
+**上下文：** 如在隔离的 worktree 中工作，该 worktree 应在执行时通过 `superpowers:using-git-worktrees` 技能创建。
+
+**计划保存路径：** `docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md`
+- （如用户已指定计划存放位置，则以用户偏好为准）
+
+## 范围检查
+
+若需求规格涵盖多个独立子系统，理应在头脑风暴阶段就已拆分为子项目规格。若未拆分，建议将其拆为多份独立计划——每个子系统一份。每份计划都应能独立产出可运行、可测试的软件。
+
+## 文件结构
+
+在定义任务之前，先梳理清楚将创建或修改哪些文件，以及每个文件的职责。这是锁定拆解方案的关键环节。
+
+- 设计边界清晰、接口明确的单元。每个文件只承担单一、明确的职责。
+- 人对能一次性完整装入上下文的代码推理最准确，聚焦的文件也更利于可靠地编辑。优先选择小而聚焦的文件，而非承载过多职责的大文件。
+- 会一同变更的文件应放在一起。按职责拆分，而非按技术分层。
+- 在现有代码库中遵循既有模式。若项目本身采用大文件结构，不要擅自重构；但若你正修改的文件已过于臃肿，在计划中安排一次拆分是合理的。
+
+该结构将直接决定任务如何拆解。每个任务都应产出自洽、独立有意义的变更。
+
+## 任务规模控制
+
+任务是具备完整测试闭环、值得独立评审的最小单元。划分任务边界时：将初始化、配置、脚手架与文档等步骤归入真正需要其产物的任务中；仅在评审者可能对相邻两个任务做出不同评审结论（一个通过、一个驳回）时才进行拆分。每个任务结束时都应产出可独立测试的交付物。
+
+## 细粒度任务拆解
+
+**每一步只做一件事（2-5 分钟）：**
+- “编写失败的测试”——一步
+- “运行测试并确认其失败”——一步
+- “编写刚好让测试通过的最小实现”——一步
+- “运行测试并确认其通过”——一步
+- “提交”——一步
+
+## 计划文档头部
+
+**每份计划必须以此头部开头：**
+
+```markdown
+# [功能名称] 实施计划
+
+> **面向 Agent 执行者：** 必需子技能：使用 superpowers:subagent-driven-development（推荐）或 superpowers:executing-plans 按任务逐项执行本计划。步骤使用复选框（`- [ ]`）语法进行跟踪。
+
+**目标：** [一句话描述本计划构建的内容]
+
+**架构：** [2-3 句话说明实现思路]
+
+**技术栈：** [关键技术/依赖库]
+
+**规格：** [本计划所实现的规格/设计文档路径——计划论证以规格为准，规格随计划一同流转，执行者需同时阅读两者]
+
+## 全局约束
+
+[规格中的项目级全局要求——版本基线、依赖限制、命名与文案规范、平台要求等——每项一行，数值与表述须与规格原文完全一致。所有任务的需求默认包含本节约束。]
+
+---
+```
+
+## 任务结构
+
+````markdown
+### 任务 N：[组件名称]
+
+**文件：**
+- 新建：`exact/path/to/file.py`
+- 修改：`exact/path/to/existing.py:123-145`
+- 测试：`tests/exact/path/to/test.py`
+
+**接口：**
+- 依赖输入：[本任务依赖的前置任务产出——精确签名]
+- 对外产出：[后续任务所依赖的内容——精确的函数名、参数与返回类型。任务执行者仅可见当前任务；通过本块了解相邻任务使用的名称与类型。]
+
+- [ ] **步骤 1：编写失败的测试**
+
+```python
+def test_specific_behavior():
+    result = function(input)
+    assert result == expected
+```
+
+- [ ] **步骤 2：运行测试并确认其失败**
+
+运行：`pytest tests/path/test.py::test_name -v`
+预期：FAIL，提示 "function not defined"
+
+- [ ] **步骤 3：编写最小实现**
+
+```python
+def function(input):
+    return expected
+```
+
+- [ ] **步骤 4：运行测试并确认其通过**
+
+运行：`pytest tests/path/test.py::test_name -v`
+预期：PASS
+
+- [ ] **步骤 5：提交**
+
+```bash
+git add tests/path/test.py src/path/file.py
+git commit -m "feat: add specific feature"
+```
+````
+
+## 禁止占位符
+
+每个步骤都必须包含工程师所需的实际内容。以下写法均属于**计划缺陷**——切勿出现：
+- “TBD”、“TODO”、“后续实现”、“细节待补充”
+- “添加适当的错误处理”/“添加校验”/“处理边界情况”
+- “为上述内容编写测试”（未给出实际测试代码）
+- “与任务 N 类似”（应重复贴出代码——工程师可能乱序阅读任务）
+- 只描述要做什么、未说明如何做的步骤（代码类步骤必须包含代码块）
+- 引用未在任何任务中定义的类型、函数或方法
+
+## 自检
+
+完成计划初稿后，以全新视角重新审视规格，并逐项核对计划。这份清单需由你亲自执行——无需分发给子代理。
+
+**1. 规格覆盖度：** 逐节浏览规格中的每项要求，能否为每一项找到对应的实现任务？列出所有遗漏。
+
+**2. 占位符扫描：** 在计划中搜索危险信号——即“禁止占位符”一节列出的所有模式，发现即修复。
+
+**3. 类型一致性：** 后续任务中使用的类型、方法签名与属性名是否与前置任务中的定义一致？例如任务 3 中叫 `clearLayers()` 的函数，在任务 7 中写成 `clearFullLayers()` 即为缺陷。
+
+如发现问题，直接原地修复，无需重新走一轮完整复审。若发现某项规格需求未对应任何任务，则补上该任务。
+
+## 执行交接
+
+保存计划后，提供执行方式选项：
+
+**“计划已完成并保存至 `docs/superpowers/plans/<filename>.md`。两种执行方式：**
+
+**1. 子代理驱动（推荐）**——每个任务分发全新子代理，任务间进行评审，迭代更快
+
+**2. 内联执行**——在当前会话中使用 executing-plans 批量执行，设置检查点
+
+**请选择哪种方式？”**
+
+**若选择子代理驱动：**
+- **必需子技能：** 使用 superpowers:subagent-driven-development
+- 每个任务一个全新子代理 + 两阶段评审
+
+**若选择内联执行：**
+- **必需子技能：** 使用 superpowers:executing-plans
+- 批量执行并在检查点进行评审