@wenaixi/dsh-superpower 7.0.0 → 7.1.0

package/skills/writing-skills/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: writing-skills
-description: "Superpower Skill（最高优先级）：在创建新技能、编辑或重构现有技能，以及在部署前验证技能可用性、合规性与实际生效情况时使用。"
+description: "Superpower Skill：在创建新技能、编辑或重构现有技能，以及在部署前验证技能可用性、合规性与实际生效情况时使用。"
 ---
 
 # 技能编写
@@ -9,7 +9,7 @@ description: "Superpower Skill（最高优先级）：在创建新技能、编
 
 **编写技能就是将测试驱动开发应用于流程文档。**
 
-**个人技能存放于运行时的技能目录**（Claude Code 上为 `~/.claude/skills/`）—— 其他运行时的路径请参见 [codex-tools.md](../using-superpowers/references/codex-tools.md) 或 [gemini-tools.md](../using-superpowers/references/gemini-tools.md)。Codex、Copilot CLI 与 Gemini CLI 同样识别 `~/.agents/skills/` 作为跨运行时别名。
+**个人技能存放于 DSH 的技能目录**：全局技能为 `~/.dsh/skills/`，项目级技能为 `<project>/.dsh/skills/`，亦可通过 DSH bundle 插件（`cordis.patch.yml` 注入 `ctx.skills`）分发提供。详细工具映射请参见 [dsh-tools.md](../using-superpowers/references/dsh-tools.md)。
 
 你编写测试用例（带 subagent 的压力场景）、观察其失败（基线行为）、编写技能（文档）、观察测试通过（agent 已遵守）、再进行重构（堵住漏洞）。
 
@@ -17,7 +17,7 @@ description: "Superpower Skill（最高优先级）：在创建新技能、编
 
 **必备前置知识：** 使用本技能前，你必须理解 test-driven-development。该技能定义了基本的 红-绿-重构 循环，本技能则是将 TDD 适配到文档编写上。
 
-**官方指引：** 关于 Anthropic 官方的技能编写最佳实践，请参见 anthropic-best-practices.md。本文档在以 TDD 为核心的方法之外，提供了额外的模式与指南作为补充。
+**官方指引：** 关于 DSH 平台技能的标准与工具规范，请参见 [dsh-tools.md](../using-superpowers/references/dsh-tools.md)。本文档在以 TDD 为核心的方法之外，提供了额外的模式与指南作为补充。
 
 ## 什么是技能？
 
@@ -371,7 +371,7 @@ pptx/
 ```
 适用场景：参考材料篇幅过大，不适合内联
 
-通过解释器调用随包脚本（正文中用 `bash scripts/tool.sh`、`node scripts/tool.js`），绝不用裸路径：部分宿主插件打包器会剥掉可执行位，裸调 `scripts/tool.sh` 会以 `Permission denied` 失败。
+通过解释器调用随包脚本（正文中用 `bash scripts/tool.sh`、`node scripts/tool.js`），绝不用裸路径调用：部分宿主插件打包器会剥掉可执行位，裸调 `scripts/tool.sh` 会以 `Permission denied` 失败。
 
 ## 铁律（与 TDD 相同）
 
@@ -465,11 +465,11 @@ NO SKILL WITHOUT A FAILING TEST FIRST
 | 基线失效 | 正确形式 | 错误形式 |
 |---|---|---|
 | 在压力下跳过/违反规则（明知故犯） | 禁止项 + 辩解对照表 + 危险信号（见下文加固方法） | 软性指引（"尽量..."、"考虑..."） |
-| 遵守了，但输出形态错误（提示词臃肿、结论被淹没、复述需求） | 正向配方或契约：明确输出是什么——包含哪些部分、按什么顺序 | 禁止清单（"不要复述"、"切勿叙述"） |
+| 遵守了，但输出形态错误（prompt臃肿、结论被淹没、复述需求） | 正向配方或契约：明确输出是什么——包含哪些部分、按什么顺序 | 禁止清单（"不要复述"、"切勿叙述"） |
 | 对已产出内容遗漏了必需元素 | 结构化：模板中设置必填字段或槽位 | 模板附近的文字提醒 |
 | 行为应取决于某个条件 | 以可观察谓词为键的条件式（"如果 brief 存在，则引用它"） | 无条件规则 + 例外条款 |
 
-**为什么禁止项在形态塑造问题上会适得其反：** 在竞争性动机（"让提示词自包含"）的影响下，agent 会与"不要做 X"进行博弈。在针对分发提示词指引的措辞对比测试中，禁止式措辞比配方式产生了明显更多的非期望内容，甚至比无指引的对照组表现更差——请对你自己的场景做微观测试而非想当然，但切勿默认使用禁止式。配方式无可博弈：输出要么符合既定形态，要么不符合。
+**为什么禁止项在形态塑造问题上会适得其反：** 在竞争性动机（"让prompt自包含"）的影响下，agent 会与"不要做 X"进行博弈。在针对分发prompt指引的措辞对比测试中，禁止式措辞比配方式产生了明显更多的非期望内容，甚至比无指引的对照组表现更差——请对你自己的场景做微观测试而非想当然，但切勿默认使用禁止式。配方式无可博弈：输出要么符合既定形态，要么不符合。
 
 **无论选择哪种形式，都需遵守以下规则：**
 - **不要加细腻化条款。** "除非有必要否则不要做 X" 会重新打开博弈空间——在同一措辞测试中，给获胜配方追加一条细腻化条款，就使其从稳定表现退化为不稳定。真正的例外应表述为基于可观察谓词的独立条件式。

package/skills/writing-skills/testing-skills-with-subagents.md

@@ -12,7 +12,7 @@
 
 **前置要求：** 使用本技能前，必须先掌握 test-driven-development。该技能定义了 RED-GREEN-REFACTOR 基础循环，本技能则提供面向技能测试的专用格式（压力场景、合理化对照表）。
 
-**完整实战示例：** 参见 examples/CLAUDE_MD_TESTING.md，其中包含针对 CLAUDE.md 文档变体的完整测试过程。
+**完整实战示例：** 参见用 DSH 指令文件（`AGENTS.md` / `CLAUDE.md`）实际运行一遍上面的 TDD 映射，验证技能在压力场景下的发现率与合规性。
 
 ## 适用场景
 

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

@@ -1,23 +0,0 @@
-# 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/claude-code-tools.md

@@ -1,11 +0,0 @@
-# Claude Code 工具说明
-
-Claude Code 是参考宿主：技能以其词汇表表述（`Agent` 用于派发 subagent、todos 表示待办、`Skill` 表示技能）。本文说明 Claude Code 中唯一能让技能运行成本低于默认形态的场景，该场景由 human partner 决定是否启用，不影响技能的任何既有要求。
-
-## subagent 驱动开发的低成本编排
-
-控制会话是 subagent-driven-development 运行中最昂贵的席位：它读取每一次派发结果与每一份报告，且通常运行在会话最强的模型上。Claude Code 支持嵌套 subagent（默认比主对话低三层，`CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH` 可调整），因此整个循环可以整体下移一层运行。
-
-当 human partner 提出要求——或表示会话模型过于昂贵、不宜用于协调——就派发一个运行在中层模型上的编排 subagent，附上计划路径与"端到端使用 subagent-driven-development"的指令。编排者按该技能的模型选择条款派出自己的实现者与 reviewer；workspace 与 ledger 都在磁盘上，不会因多出的这一层而丢失任何内容。其最终消息必须原样携带 "Rulings I made" 清单——这份清单是决策到达 human partner 的途径，你要转达它，而不是概括它。
-
-仅对完整计划这样做。嵌套单个任务的派发毫无收益，只会多占一个席位。

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

@@ -1,108 +0,0 @@
-## 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/gemini-tools.md

@@ -1,63 +0,0 @@
-# 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., `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 `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

@@ -1,56 +0,0 @@
-# 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/muse-tools.md

@@ -1,35 +0,0 @@
-# Muse 工具映射
-
-技能以动作表述（"派发 subagent"、"创建待办"、"读取文件"）。在 Muse 上，这些动作对应下表工具。
-
-| 技能要求的动作 | Muse 等价 |
-|----------------------|----------------|
-| 读取文件 | `read_file` |
-| 读取多个文件 | `read_file`（多次调用）或 `search` |
-| 创建新文件 | `write_file` |
-| 编辑文件 | `edit_file` |
-| 运行 shell 命令 | `bash` |
-| 搜索文件内容 | `search` |
-| 按名称查找文件 | 带 `glob` 的 `search` |
-| 抓取 URL | `web_fetch` |
-| 搜索网络 | `web_search` |
-| 调用技能 | 对 `skills/<name>/SKILL.md` 使用 `read_file`，或使用原生技能工具 |
-| 派发 subagent（`Subagent (general-purpose):` 模板） | 用填充的提示词调用 `subagent_spawn` |
-| 任务跟踪（"创建待办"、"标记完成"） | `write_todos` 或 `bash` 任务文件 |
-| 向用户提问 | `request_user_input` |
-
-## 指令文件
-
-当技能提及"你的指令文件"时，在 Muse 上即项目根目录的 **`CLAUDE.md`** 或 **`AGENTS.md`**。Muse 在配置处按层级加载这些文件。
-
-## 技能调用
-
-Muse 通过 `muse skills` 提供原生技能支持。要调用 Superpowers 技能，读取其 `SKILL.md` 并遵循其中的说明。引导技能（using-superpowers）会通过插件钩子在 `SessionStart` 时自动注入——你已在遵循它，无需重新加载。
-
-## subagent 派发
-
-使用 `subagent_spawn` 将工作委派给隔离的 subagent。派发前先填充提示词模板（如 `implementer-prompt.md`、`task-reviewer-prompt.md`）。若没有可用的 subagent 工具，就在当前会话内联完成工作，而不是臆造工具调用。
-
-## 任务跟踪
-
-使用 `write_todos` 跟踪清单。技能清单中的每一项创建一个待办，随进度标记 in_progress/completed。若 `write_todos` 不可用，通过 `write_file`/`edit_file` 维护一个 Markdown 任务文件。

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

@@ -1,16 +0,0 @@
-# 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.