Provides a systematic 9-stage requirements analysis and implementation workflow (requirements understanding, code exploration, external resource research, clarifying questions, deep analysis, plan presentation, implementation development, code review, summary). Suitable for scenarios that require deep planning and full implementation, such as complex feature development, multi-solution comparison, and research on new technology stacks. Triggered when a user proposes complex feature development, API design, or database design that requires deep analysis and external resource research.
Language Protocol / 语言协议: Respond in the user's conversation language — an explicit user instruction (including the platform
languagesetting) takes precedence, then the language of the user's recent messages; default to English when neither indicates a language. All deliverables written to the repo (specs, plans, reports, notes) follow the conversation language at creation; incremental edits keep the artifact's existing language. Fixed-wording prompts in this skill are semantic templates — express their meaning in the conversation language, don't quote them verbatim. 语言协议：以对话语言输出——用户显式指定（含平台language设置）优先，其次跟随用户近期消息语言；均无法判定时默认英语。落盘产物以创建时对话语言为准，增量修改保持产物既有语言。本 skill 中的固定话术是语义模板，用对话语言表达其意，不逐字照搬。
通过自然的协作对话，把想法转化为经过验证的完整设计与 spec。
先理解项目现状，再逐题澄清打磨想法；理解到位后做对抗验证、给出多方案对比；用户批准设计后落盘 spec，最终交接 writing-plans 生成实施计划。
<HARD-GATE> 在设计展示给用户并获得批准之前，不得调用任何实施类 skill、不得编写任何代码、不得搭建任何脚手架、不得采取任何实施动作。此门槛适用于所有项目，无论看起来多简单。 </HARD-GATE>所有需求都要走完本流程。加一个字段、改一处文案、一个单函数工具——都一样。"简单"需求恰恰是未经检验的假设造成返工最多的地方。设计可以很短（light 档几句话即可），但必须展示并获得批准。
必须为以下每一项创建任务（Claude Code 用 TaskCreate，Codex 用 update_plan），按序完成；被跳过的项标记完成并注明原因：
.spec-dev/YYYY-MM-DD-NN-<feature>/spec/<feature>-design.md 并 git commitdigraph requirement_analysis {
"1 需求理解与分诊" [shape=box];
"2 并行探索（内部+外部）" [shape=box];
"3 澄清问题（逐题）" [shape=box];
"4 对抗验证 + 2-3 方案" [shape=box];
"用户选定方案?" [shape=diamond];
"5 展示完整设计" [shape=box];
"用户批准设计?" [shape=diamond];
"6 写 spec 并提交" [shape=box];
"7 self-review + 对抗验证" [shape=box];
"用户 review 通过?" [shape=diamond];
"8 调用 writing-plans" [shape=doublecircle];
"1 需求理解与分诊" -> "2 并行探索（内部+外部）";
"2 并行探索（内部+外部）" -> "3 澄清问题（逐题）";
"3 澄清问题（逐题）" -> "4 对抗验证 + 2-3 方案";
"4 对抗验证 + 2-3 方案" -> "用户选定方案?";
"用户选定方案?" -> "4 对抗验证 + 2-3 方案" [label="要求调整"];
"用户选定方案?" -> "5 展示完整设计" [label="选定"];
"5 展示完整设计" -> "用户批准设计?";
"用户批准设计?" -> "5 展示完整设计" [label="否，修订"];
"用户批准设计?" -> "6 写 spec 并提交" [label="是"];
"6 写 spec 并提交" -> "7 self-review + 对抗验证";
"7 self-review + 对抗验证" -> "用户 review 通过?";
"用户 review 通过?" -> "6 写 spec 并提交" [label="要求修改"];
"用户 review 通过?" -> "8 调用 writing-plans" [label="通过"];
}
终态是调用 writing-plans。 不得调用 executing-plans、acceptance-qa 或任何其他实施类 skill——本 skill 之后唯一可调用的 skill 是 writing-plans。
档位在阶段 1 判定，向用户声明并允许覆盖；它只调节探索规模与 spec 篇幅，不豁免任何 Checklist 项与 HARD-GATE。
light — 单文件/单模块、无新依赖、无方案分歧（如加字段、改文案）
探索：主线程直查或 1 个子代理；方案可收敛为 1 个（说明为何无分歧）；spec 几句话到半页
standard — 默认档。跨 2-3 模块或有方案取舍
探索：按架构层次或功能模块 3-5 个子代理；完整 2-3 方案对比
deep — 跨层架构变更、新技术栈、用户使用"彻底/全面/审计"等措辞
探索：multi-modal sweep，按模态数派发、不设上限；方案对比含更完整的风险分析
判定依据：涉及文件数与模块数（阶段 1 初判、阶段 2 修正）、是否引入新依赖、是否存在多解取舍、用户措辞强度。声明格式：「本需求判定为 {档位}（理由），如需更彻底/更轻量请告知」。
本 skill 同时兼容 Claude Code 和 Codex。核心工具映射：
| 用途 | Claude Code | Codex |
|------|-------------|-------|
| 用户澄清/确认 | AskUserQuestion（单题带选项） | 对话消息提问并等待回复 |
| 进度跟踪 | TaskCreate / TaskUpdate | update_plan |
| 并行子任务 | Agent（单响应一次性发起） | spawn_agent（继承上下文，参数见 codex-compat）+ wait_agent |
| 项目规范文件 | CLAUDE.md → AGENTS.md | AGENTS.md → CLAUDE.md |
| 网页搜索 | anysearch skill（内嵌）→ WebSearch 降级 | anysearch skill（内嵌）→ 内置 web 搜索降级（托管 web_search 工具） |
Codex 环境的完整规则见 codex-compat.md。
目标：理解意图，给流程定参。
.spec-dev/explorations/ 探索笔记时作为本阶段输入，已探索过的部分阶段 2 不重做.spec-dev/reports/YYYY-MM-DD-NN-<topic>.md 吗」（结构从轻：问题、结论、依据来源；目录随首个报告创建；同一 NN 序列全 .spec-dev/ 日期前缀产物共用），用户婉拒则只留对话、零落盘。建议式，由用户裁决。结论要落地成代码时回归正常分诊——报告通道不是实施后门.spec-dev/roadmaps/YYYY-MM-DD-NN-<project>.md（同一 NN 序列全 .spec-dev/ 日期前缀产物共用）并 git commit（登记时同步填写「原始需求」节——用户原话全文，与每子项目「上下文胶囊」——关键裁决/探索指针/已扫范围），然后只对第一个（或用户指定的）子项目走本流程。roadmap 是分解决策唯一的持久化位置——不落盘，其余子项目就只活在本次对话里，会话一结束静默蒸发.spec-dev/roadmaps/ 下某 active roadmap 的 pending 子项目与本需求对得上）→ 载入该 roadmap 的目标/分解边界/备注，并读取该子项目上下文胶囊指向的前置产物（前置子项目 spec 的「背景与目标」与验收报告结论、探索指针文件），以此为阶段 1-2 输入直接走本流程、不重新分解、不要求用户重新提供原始需求；阶段 2 探索对胶囊「已扫范围」登记过的模态不重扫、只补缺口；依赖的前置子项目未交付时先向用户指出。roadmap 目录不存在或无命中 → 本条零动作，正常走流程目标：一个波次拿齐内部代码事实与外部最佳实践。
首要任务：查找并阅读项目规范文件（优先级按环境映射表）。
编排：内部与外部探索相互独立，必须在单条消息中一次性发起全部子代理——分批发起会退化为串行等待。子代理数量不设上限，按档位与需求结构决定：
code-explorercode-explorer；阶段 1 标记了外部探索时，同波次加 1-2 个 external-resource-explorercode-explorer 彼此盲扫，模态数由项目形态决定、不设上限；外部按主题拆多个 external-resource-explorer 同波次发起外部探索工具优先级：AnySearch（通用/垂直/批量，插件内嵌）优先 → WebSearch / WebFetch 兜底；派发外部探索子代理时须在派发词中主动重申此优先级（不依赖 agent 定义文件生效，Codex 端尤其如此）；降级链与模态定义、契约校验、失败隔离规则见 exploration-patterns.md。
每个子代理必须给定：清晰的主题或模态、相关文件线索、期望输出格式、工具优先级与文档时效规则提醒（后两项定义见 exploration-patterns 派发要求）。失败的子代理先缩小范围重试 1 次，再失败由主线程接管。
目标：解决所有模糊、歧义与多解取舍。
提问纪律遵循 clarifying skill 的核心纪律（被引用模式，纪律定义以 clarifying 为准）：提问前自我披露（假设/关键信息/易犯错三段先行）、一次只问一个问题、选择题优先且推荐项放首位（Claude Code 用 AskUserQuestion）、事实自查决策交用户、按决策依赖排序、术语挑战、不编造问题——无疑点则明确记录"需求已清晰，无需澄清"后进入阶段 4。本阶段是引用方：澄清完成后直接进入阶段 4，不触发 clarifying 的共识摘要与三出口。Codex 逐题提问规范见 clarifying 内嵌的 Codex 规范节；三道门的对话呈现要求见 codex-compat.md。
可视化预览（JIT 提议）：不要在开场提议。当某个问题用看的比用说的更清楚时（真实的 mockup/布局/图示问题，而不只是"话题涉及 UI"），首次出现的那一刻单独发一条消息提议使用 visual-preview skill——该消息只含提议、不夹带其他问题。用户接受则按 visual-preview skill 执行；拒绝则继续纯文字，不再重复提议。逐题判断浏览器 vs 终端：内容本身是视觉的（线框、布局对比、架构图）用浏览器，内容是文字的（需求、取舍、概念选择）留在终端。
回补探索：澄清或方案期发现新库/新领域，允许回补一轮外部探索（同样单响应发起），回补后继续当前阶段。
目标：先证伪自己的信息，再给出可比较的方案。
零子代理：本阶段全部在主线程完成，用 sequential-thinking skill（插件内嵌，bun/tsx → scripts/think.mjs Node 端口自动降级）结构化推进；该 skill 及其运行时均不可用时降级为在回复中显式分点推演并注明工具降级原因，不得因工具缺失跳过分析。
第一步——信息对抗验证。对阶段 1-3 收集的每条承重结论（将直接决定方案取舍的事实）逐条质询：
冲突未消解前不进入方案设计。
第二步——提出 2-3 个方案。基于验证后的信息给出方案对比：
目标：把选定方案展开为完整设计，整篇获得批准。
.spec-dev/YYYY-MM-DD-NN-<feature>/（所有 spec-dev 产物统一收纳在项目根目录 .spec-dev/ 下；NN 为当日两位序号——扫描 .spec-dev/ 下当日已有的日期前缀产物（特性目录，及 reports/、roadmaps/ 下的文件名）取最大加一、01 起步，落盘前重扫一次防并发撞号：发现同号已被占则顺延并同步修正自引路径；feature 取需求主题的短语义名，跟随项目语言；存量旧命名 YYYY-MM-DD-<feature> 目录不改名（grandfather）；同一 NN 序列由全部 .spec-dev/ 日期前缀产物共用），将批准的设计写入其 spec/<feature>-design.md（用户对 spec 位置的偏好优先于此默认值）plan/ 分文件形态：index.md + tasks/ + progress.yaml）共用这一个特性目录——一个需求的全部产物收纳在一处.spec-dev/adr/NNNN-<slug>.md（全项目共用一个目录、统一编号：扫描现有最高编号递增，目录不存在时随首个 ADR 创建；落盘前重扫一次目录防撞号——并行会话可能已用掉同号，发现同号文件已存在则顺延取下一号并同步修正正文与链接中的自引编号；正文 1-3 句写清背景、决定与理由即可，值得记住的被否方案附一行），spec 决策节保留一行摘要并链接过去；三判据缺一即不建 ADR——ADR 泛滥和没有 ADR 一样没用。ADR 状态纪律：每条 ADR 标题下带状态行，封闭三态——**Status**: Accepted (YYYY-MM-DD) / **Status**: Deprecated (YYYY-MM-DD) — <一句原因，强制> / **Status**: Superseded by [ADR-NNNN](NNNN-<slug>.md) (YYYY-MM-DD)（同目录文件名相对链接，编号强制；缺状态行的历史 ADR 视同 Accepted）。判据一句话：有替代决策用 Superseded，无替代者且决策语境消失用 Deprecated。Accepted 后正文不可变（仅 status 行、错别字、坏链可改）；不做部分推翻——推翻既有 ADR 的任何部分时，新 ADR 完整重述仍有效的结论并整体取代，标题下声明 **Supersedes**: ADR-NNNN 行，且在本阶段同一提交把旧 ADR 状态行回写为 Superseded by（ADR 取代随裁决即时生效，不等实施交付）supersedes（仓库根相对路径）与正文「取代与共存」节（部分取代必须列出被取代的具体 Requirement 标题清单，每条附一句取代理由）；分面共存（同文件不同行为切面、无冲突）不登记 supersedes，记一行判定理由并各自声明 covers。节模板与标注形制见 spec-template.md。用户要求删除整个特性且无新行为承接时，产出仅含 REMOVED Requirements 的轻量 spec 作为后继（记录删除理由，交付时按完全取代回写旧 spec）。spec 的取代回写随交付生效（executing-plans 最终任务），与 ADR 的即时回写构成双轨### Requirement: 一条一个 SHALL 且可观察，#### Scenario: 用 GIVEN/WHEN/THEN——它们是后续 TDD 测试与验收的直接锚点）；修改既有功能时行为部分改用差量三节（ADDED/MODIFIED/REMOVED Requirements，见模板）spec_dev frontmatter，填写 feature 与 covers（本特性拥有的代码路径 glob；纯文档特性留空数组 []）——此阶段 status 保持 draft。该 frontmatter 是 pre-commit / CI 漂移守卫的锚点，缺失或永停 draft 意味着该特性代码不受"改了代码却没同步 spec"的拦截保护in-progress；不属于任何 roadmap 则无此步第一步——inline 自检（自己以新鲜眼光重读，发现即改，无需复审）：
第二步——对抗验证：派 1 个临时子代理（Claude Code 用 general-purpose，Codex 用 spawn_agent），提示词按 spec-reviewer-prompt.md 模板构造，对 spec 做独立审查（完整性/一致性/清晰度/范围/YAGNI）。审查回报的问题逐条处置：成立则修 spec，不成立则记录理由。
第三步——用户 review 门：
「Spec 已写入并提交至
<路径>。请 review，如需修改请告诉我，确认后我们开始编写实施计划。」
等待用户回复。若第一/二步曾修改 spec，必须让用户重新 review 修改后的版本；用户要求修改则改完重跑本阶段。用户确认后才进入阶段 8。
status: draft 翻为 active 并 commit（仅 active 参与漂移拦截——不翻转则守卫对本特性静默失效）supersedes 非空）：翻 active 的同一提交内，向每份被指向的旧 spec H1 标题下写入 Superseded-pending 标注（形制见 spec-template「取代标注形制」节；部分取代写明将被取代的 Requirement 标题）——窗口期的双 active 状态由此对全部消费方显式可判定；后续该计划若被废弃，由 executing-plans 意图级偏差收尾回收此标注出现以下想法时，停下来重新对照 Checklist：
Search for places (restaurants, cafes, etc.) via Google Places API proxy on localhost.
Interact with GitHub using the `gh` CLI. Use `gh issue`, `gh pr`, `gh run`, and `gh api` for issues, PRs, CI runs, and advanced queries.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Start voice calls via the OpenClaw voice-call plugin.
Notion API for creating and managing pages, databases, and blocks.
Gemini CLI for one-shot Q&A, summaries, and generation.
Category:developer