setup

name	setup
description	创建一个新的 Workframe 项目，或把已有项目接入 Workframe。按用户意图与目标目录状态分流（新建 / 接入），对话采集业务上下文后落骨架、订阅 core 插件、完成落盘验收。仅用于 Workframe 框架的项目初始化，不承担 npm init / create-react-app / git init 等通用脚手架。
when_to_use	用户想用 Workframe 开一个新项目，或想把手上已有的项目接入 Workframe 时。触发词：创建 workframe 项目、接入 workframe、初始化 workframe、workframe setup。**不适用**：已接入项目内的日常工作（由 core 插件的角色与技能承担）；与 Workframe 无关的通用脚手架初始化。
allowed-tools	["Read","Write","Edit","Glob","Grep","Bash","AskUserQuestion"]
user-invocable	true

Workframe 项目初始化

定位

Workframe 的唯一入口：在任意目录发起，创建新项目或接入存量项目，完成后由 core 插件接管项目内的日常工作。

本 skill 属用户级 workframe-launcher 插件，与项目级 core 插件分层：launcher 管「怎么开局」，core 管「项目里怎么干活」。

依赖方向（硬约束）

launcher 只能单向依赖 core，且只能通过 marketplace 注册信息定位 core：

读 ~/.claude/plugins/known_marketplaces.json  → 取本市场 installLocation
  → 拼 <installLocation>/plugins/core/...

禁止用 ../ 一类相对路径向上找 core：插件安装时按插件逐个复制到缓存 （cache/<市场>/<插件>/<版本>/），launcher 的安装目录旁边不存在 core。 目录源（开发期）碰巧有兄弟目录，GitHub 源（用户侧）没有——该写法开发期能跑、发布后必坏。

定位脚本（每次执行前跑一次，一次拿到 CORE 根路径和市场源）：

python - <<'PY'
import json, pathlib
km = json.loads((pathlib.Path.home()/".claude/plugins/known_marketplaces.json").read_text(encoding="utf-8"))
for name, meta in km.items():
    loc = pathlib.Path(meta.get("installLocation", ""))
    mf = loc/".claude-plugin"/"marketplace.json"
    if not mf.exists():
        continue
    names = {p.get("name") for p in json.loads(mf.read_text(encoding="utf-8")).get("plugins", [])}
    if not ({"core", "workframe-launcher"} <= names):
        continue
    src = meta.get("source") or {}
    kind = src.get("source") or ("directory" if src.get("path") else "?")
    origin = src.get("repo") or src.get("url") or src.get("path") or "?"
    print(f"MARKET={name}\tCORE={loc/'plugins'/'core'}\tSOURCE={origin}\tKIND={kind}")
PY

命中 0 个 → 停下告知用户「未找到 workframe 市场，请先 claude plugin marketplace add <源>」。 命中 ≥2 个（用户同时有开发目录源与 GitHub 源）→ 用 AskUserQuestion 让用户选一个，不要自己挑。

SOURCE 就是 §5 步骤 2 里 claude plugin marketplace add <市场源> 要填的值——不要用 CORE 或 installLocation 顶替。三种形态：KIND=github 时 SOURCE 是 owner/repo； KIND=git 时是仓库 URL；KIND=directory 时是本地绝对路径。 installLocation 对 github / git 源是本地缓存目录（~/.claude/plugins/marketplaces/<市场名>）， 拿它当市场源写进项目 settings，等于把每台机器各不相同的缓存路径当成插件来源—— 协作者 clone 后解析不到，core 装不上（doctor 的 subscription 项会报本地目录源告警， 但那时项目已经建好了）。KIND=directory 时同样要提醒用户该项目对协作者不可自动安装（见 §5.5）。

交互纪律（本 skill 内生效，不依赖项目 rules）

launcher 常在尚未接入 Workframe 的目录运行，此时项目 rules 尚不存在，以下纪律必须由本 skill 自带：

1. 选择题一律用 AskUserQuestion 工具，不要在正文里列 A/B/C 让用户敲字。 是不是选择题看「答案空间」，不看问题措辞——「有没有 X」「要不要 Y」是二元选择题， 该出卡，哪怕它被顺嘴问出来（2026-08-11 走查教训：Q4 被当开放题混进了文字段）。 一次调用可承载多个相关问题（组件分隔渲染），别为省往返把选择题揉进正文。
2. 复杂内容先在正文完整展示（模块树、路径映射表、文件清单），AskUserQuestion 的选项只做轻量判断（「符合，按此执行」/「需调整」）——选项 preview 不承载关键信息。
3. 确认前零写盘。方案确认页是唯一闸门，用户明确确认前不创建任何目录或文件。
4. 用户已表达倾向时正面回应：同意给理由，不同意给具体替代方案，不含糊带过。
5. 说人话。来初始化项目的多半是 PM，不是工程师。技术名词（monorepo / git init / scaffold / 暂存区…）该用就用，但第一次出现时用一句日常话带出它对用户意味着什么——「已 init 但 0 次提交的 monorepo」不如「多包代码仓刚建好、还没有任何提交记录」。目标是把「发生了什么、对你意味着什么、可以怎么选」讲到初次使用的人能直接决策；具体怎么说不设模板，由你按对象发挥（2026-08-11 用户反馈：扫描汇报判定全对，但口径偏工程师）。 解释首现一次到位：同一概念第一次出现时讲透，之后直接用，不逐轮重复——多轮交互里 反复解释是内容墙的另一来源。
6. 输出密度：分档呈现，表格优先（2026-08-11 用户反馈：每步确认内容偏多，核对费劲费时）。 确认类输出把内容分两档：等用户拍板的（会写进或改动用户文件的内容、可当场驳的推断结论） 完整展示；供用户了解的（框架介绍、日后随时可查的速查内容）压到最短、给一句指路。 呈现表格优先——每行一个可核对的事实，散文只用来说「为什么」。压缩幅度与排版按现场判断， 不设模板；底线一条：决策对象不因简洁缺席。

§1 入口分流

1.1 判定目录状态

按顺序判，前面命中就不往下走：

步	判据	结论
1	有 .workframe-config.json	已接入
2	根级有 .git，或根级有项目清单（package.json / pyproject.toml / Cargo.toml / go.mod / pom.xml / *.sln …）	项目目录 —— 这条一票否决容器，monorepo 里塞多少个子包都走这条
3	是众所周知的系统容器位置：~/Desktop ~/Downloads ~/Documents ~ 本身、盘符根、/Users/<name> /home/<name>，含各语言本地化名（桌面 / 下载 / 文档 / デスクトップ …）	容器目录
4	近空（只有 .git / README 之类）	空目录
5	综合判断：内容彼此无关（几个不同主题的目录 + 散落的截图安装包）且无「这是一个整体」的标志 → 容器；内容有主题一致性、README 在描述"这个东西是什么" → 项目	按判断走
6	拿不准	按项目目录处理 —— 判错只影响推荐顺序，不删任何选项

为什么第 2 步要一票否决：早期草案用「子项里有 ≥2 个独立项目标志」判容器，这会把 monorepo 直接判成容器，而 monorepo 恰恰最需要「接入」——那不是不便，是功能没了。

目录扫描的结果只用于判断目录状态，不得直接拿去推断用户的业务或项目名（见 §2 约束）。

1.2 分流

原则：明确意图不拦路（至多一句轻确认），模糊意图才出选择卡。

先分清两个容易混的说法：

• 就地建 = 当前目录本身成为项目根
• 在此处建 = 在当前目录下面建一个子目录当项目根 ← 容器目录下的正常做法

用户表达 ↓ \ 目录状态 →	空目录	容器目录	项目目录（未接入）	已接入
明确「新建」	轻确认：就用这个空目录，还是另选位置？	在此处建子目录（Q3 首选 <容器>/<项目名>）	见 §1.3	轻确认：「这里已接入，是要在其他位置新建吧？」
明确「接入」	说明无可接入 → 顺势转就地新建	说明容器目录不适合整个接入，问是要接入它下面的某个项目，还是在此处新建	走 §3 B 路径	提示已接入；可顺带跑 doctor 体检
模糊（「初始化」「用上 workframe」）	默认就地新建，确认一句	选择卡：在此处建一个项目目录（推荐）/ 换个位置建——不出现「接入当前」	选择卡：接入当前（推荐）/ 在此处建子目录 / 另外建	提示已接入 + 问是否另建

容器目录下「接入当前」不出现的唯一理由：把桌面 / 下载夹本身变成 workframe 项目，在任何 情况下都不是用户想要的——那会在容器里散出 projects/ logs/ .claude/ CLAUDE.md 一堆东西。

兜底：用户意图永远高于自动判定。 用户明确说「就接入当前这个目录」时照做，哪怕判定为容器。

1.3 项目目录里说「新建」时先问一句

这时「新建」有两种意思，差别很大，不要替用户选：

检测到当前目录是一个已有项目。你说的「新建」是指——

1. 在它下面建一个子目录当 workframe 工作区（如 <repo>/pm/）
2. 把这个项目本身接入 workframe

选 2 时必须提示：这等同于「接入」，会顺带做存量资料分析与 CLAUDE.md 整合。跳过整合的话， 角色路由 / 状态流转 / 文档约定这些框架约定不会进你的 CLAUDE.md——落盘验收会以 error 抓出 （doctor 的 claude_md 项查四个契约段的内容，不只看文件在不在）。用户坚持只要纯骨架也可以， 但要让他知道跳过了什么。

§2 A 路径：全新创建

四个问题，全部遵循「候选 + 自填」，逐个问、不要一次性倒给用户。

步	问题	形式	要点
Q1	你在负责什么类型的产品？	选择卡，选项即格式示范	示例选项：toC 社交（海外陌生人交友） / toC 内容社区（短视频、图文） / toB SaaS（客服系统、CRM），选项写法本身示范回答颗粒度（产品形态 + 业务域）。这是业务上下文采集，喂给 CLAUDE.md 业务背景段、role_profile 推断与名称候选
Q2	项目叫什么？	基于 Q1 生成 2-3 个候选 + 自填	这是展示名（启动横幅、报告用），可以与目录名不同
Q3	放在哪个目录？	候选 + 自填	首选候选按目录状态给：空目录→当前目录本身；容器目录→<容器>/<项目名>；项目目录→<当前项目>/<项目名>。就地新建（空目录）时本问自动跳过。给候选前必须先查该路径存不存在——见下
Q4	有没有已有资料或在维护的目录要纳入分析？	选择卡（本质是「有 / 没有」二元题——选择题看答案空间不看措辞）	选项措辞自定，但须含「没有」的快捷出口与「有 → 给路径」的自填通道。有 → 走 §3 的分析能力；没有 → 标准骨架起步，日后在项目内随时用 migrate-to-modules（规范 md）/ requirement-archiving（异构原料）补充

必填字段从哪来

scaffold 有三个必填参数，上表只直接产出其中一个——别把另外两个凭空编出来：

字段	来源
project_name	Q2 直接产出
one_line_goal	必须问用户（见下 Q5），Q1 派生不出来——Q1 答的是品类（「toC 内容工具」），这里要的是这个项目做成什么（「做一个多平台自媒体内容生产与分发工具」）
business_context	由 Q1 + Q5 合成即可（两个来源都是用户亲口说的，不算编）

Q5 一句话目标：也用选择卡——基于 Q1 的回答派生 2-3 个候选目标供快速选择 （候选即格式示范，方向、颗粒度贴着用户的业务写），用户不满意随时自填。问的时候顺带 说清用途——「会写进 CLAUDE.md 业务背景段，影响模块切分与角色推断；写具体一点更好」。 写进 CLAUDE.md 的是用户选中或自填的原文，候选只是快选通道。

Q4 与 Q5 可并入同一次 AskUserQuestion 调用（组件天然分隔多个问题，不会变成文字墙； 2026-08-11 用户反馈：旧的「合并成一段文字问」正是墙的来源，已废止）。Q1 必须单独问， 它的答案决定后面所有候选。

三个字段都必须在确认页的「项目基本信息」里展示：它们会原样进 CLAUDE.md，用户在确认页 不过目，之后就没人看了。

Q3 候选必须先查路径是否被占（硬约束）

项目名默认会变成目录名，而用户起的名字很可能跟已有目录撞上——尤其是他选了那个从当前 目录推断出来的候选时（选「SmartArticle」→ 默认目录 <桌面>/SmartArticle → 正是那个代码仓）。

给出候选前，对每个候选路径判一次：

路径状态	怎么办
不存在	正常作候选
存在但近空（只有 .git / README 等）	可作候选，提一句「该目录已存在但基本是空的」
存在且有实质内容	不能作候选。摆出来问用户：是想接入这个已有项目（走 §3，会做存量分析与 CLAUDE.md 整合）／在它下面建子目录／还是换个名字？

最后一种情况别自作主张——「新建」和「接入」是两条不同的路，选错了后果是静默的： 按新建硬来虽然不会破坏文件，但会跳过整合，框架约定进不了他的 CLAUDE.md。 脚本侧有 --require-empty 兜底（退出码 3），但那是最后一道，不该指望它替你问用户。

候选从哪来（硬约束）

Q2 / Q5 的候选主体必须从 Q1 的回答派生，不是从当前目录的内容派生。 A 路径是「另外建一个 新项目」，当前目录只是你敲命令的地方，跟新项目没有关系——拿它推断业务是类别错误。

允许至多 1 个候选来自当前目录内容，但三条同时满足才行：

1. 标注推断依据——「看到你桌面上有 SmartArticle，如果是给它建的话…」，让用户知道你为什么 这么猜。不标注的话，错误推断会被误读成"系统知道什么内情"
2. 不作为推荐项（不是默认高亮那个）
3. 其余候选照常从 Q1 派生

实测教训（2026-08-10 E2E）：在桌面发起时，Q2 的三个候选全是从桌面上一个代码目录推断出的 变体，用户只能选「自填」才逃得出去——推断变成了默认值。而「桌面上有 X」推不出 「我要为 X 建项目」，这个推断即使碰巧猜对也不成立。

Q4 用户明确给出的资料路径不受此限——那是他主动交给你分析的。

role_profile 自动推断，不设问（结果在确认页展示、可调）：

• Q1 文本明显以 AI / LLM / Prompt / Agent 能力为核心 → ai-product（「智能 X」「自动化」等含混词不算）
• 文本命中「个人 PM / 一人 / 没研发 / 自己做」等 → solo-pm
• 否则 → software-team（默认）

判据是「谁在这个项目里真的干活」，不是「公司里有没有这个工种」。

B 路径能直接观测到有没有代码（见 §3 观测维度），观测到的事实优先于文本推断：项目里没有 代码时不要落进 software-team 默认档——那会把 @dev / @qa 设为主力，而这个项目里没有东西 可写、也没有东西可测。纯文档 / 需求项目按 solo-pm（pm 主力）判。

实测教训（2026-08-10）：一个零代码的产品文档项目被判成 software-team，依据是原文里的 「研发给的需求文档」「和研发对齐用飞书」。推断执行得没错，是判据本身把「有研发协作」 当成了「研发在本项目内」——而那些研发在 TAPD 和飞书那头，从不进这个仓库。 确认页已要求写明推断依据，依据里必须出现「本项目内有/无代码」这一条，让用户一眼能驳。

§3 B 路径：存量项目接入

就地分析，扫描证据后带证据确认，不设问——用户从「填表」变成「确认」。

观测维度	观测方式	影响
有没有代码	Glob 源码 / 识别脚手架	模块树切分证据 + submodule.yaml.code_paths 建议 + 接入后 code-to-doc 计划
有没有存量文档	Glob md / docx / xls 等	搬家分流计划（进确认页）
带不带团队	git shortlog -sn 贡献者数	仅 role_profile 推断，不影响目录结构；确认页可调

补充几条：

• 扫描汇报讲结论不铺过程：三个观测维度一张表结清（看到什么 / 对你意味着什么）， 判定结论先行；分析细节留给用户追问再展开。

• 项目已有 CLAUDE.md 时必须做整合——这是 B 路径最容易漏、后果最隐蔽的一步。scaffold 对已存在的 CLAUDE.md 一律跳过不覆盖，不整合的话：hooks 装上了、rules 镜像了、4 个 agent 能路由，但项目 CLAUDE.md 里没有角色体系表、没有路由规则、没有状态流转与签发权限、 没有文档与结构约定——框架一半的行为约定不生效。落盘验收会以 error 抓出（claude_md 项查四个契约段的内容，不是只看文件存在）。 规范见 <CORE>/reference/claude-md-merge-guide.md，本阶段只做到"分类原文 + 出合并稿"， 写盘在 §5。 合并稿必须在确认页正文露出——但只露含用户原文的段落（业务背景 / 项目特殊约束 / 业务目录速查等）。框架样板段（订阅声明 / 角色体系 / 路由规则 / 状态流转）每个项目一模一样， 贴出来是噪音。合并质量只体现在用户原文那几段，不给就等于让用户盲签一份即将覆盖自己文件的东西。 「全文太长会盖掉方案页」是真的，但解法是挑段落，不是改用结构摘要代替。

• 已有 .claude/agents/<custom-role>.md 时自动检测三项并提议 patch：是否误用 memory: frontmatter、body 是否引用 agent-protocols、.claude/agent-memory/<role>/ 是否存在。

• 存量文档的处理层层递进，不一次性塞给用户（2026-08-11 走查后定稿）：本阶段只做 粗扫（形态计数 + 标题级抽样：md 读 H1/H2、docx 读标题与首段、xlsx 读表头， 不逐字深读——供模块树提议用，见 material-intake §两级盘点）。每份文件的安置与 原件处置在建树后的逐模块小闸（§5 步骤 4）深读后逐模块确认、当场执行； 整理归档（原始资料 → 正式需求文档，即 requirement-archiving）的节奏在节奏闸 （§5 步骤 4.5）拍。结构闸只拍项目级的事——用户核对量小，改动也不连锁。

• 项目已有 project_name / role_profile 等配置时，确认页必须展示既有值：scaffold 对已有用户字段不覆盖，但展示名会按确认结果刷新。

• 会被修改的已存在文件必须逐个点名，不能只说「你现有 N 个文件一个不动」。 接入至少会碰两类：已存在的 CLAUDE.md（整合覆盖，落备份）、已存在的 .gitignore （末尾追加 managed block，不动用户原有规则）。 实测教训：确认页报「现有 6 个文件一个不动」时，那个 6 悄悄没算 .gitignore——数字没说谎， 但用户读到的是「什么都不碰」，而它确实被改了。统计口径排除掉的东西，必须在同一处说明白。

§4 结构闸（写盘与订阅前的唯一闸门）

在正文完整渲染，三条硬性标准见 ./reference/proposal-page.md：用 PM 自己的业务语言展示模块树、给「你以后每类东西放哪」映射表、框架术语必须带业务例子。

只拍项目级三件事：模块树（粗扫标题级证据支撑）、CLAUDE.md 合并稿（只露用户原文段落）、 会被修改的已有文件点名。每份文件的去向与处置不在这里拍——那是逐模块小闸（§5 步骤 4） 的事：一次性塞给用户既难核对，改树时又全部连锁重算。树也不是一锤定音：逐模块深读发现 更合理切分时回来提议微调（连锁已被逐模块机制隔离，微调便宜）。

本页本质是把确认从「审文件清单」升级为「审认知」——PM 确认的是「你们对我业务的分层理解对不对」。

确认用 AskUserQuestion，选项：按此执行 / 我要调整（用户用自然语句说改什么，迭代到满意）/ 取消。

§5 执行（确认后一气呵成）

先按 §依赖方向 拿到 CORE 路径，再依次执行。

1. 写参数文件并落骨架

把对话采集的值写成 JSON（必填 project_name / one_line_goal / business_context；可选 project_type / dormant_profile / role_profile / project_level_roles / project_specific_constraints / business_directories），交给脚本确定性渲染——占位符替换由脚本保证并断言零残留，不要手工替换模板：

# A 路径（新建）——必须带 --require-empty
python "<CORE>/scripts/project_scaffold.py" --project "<目标>" --params "<params.json>" \
    --create-missing --require-empty

# B 路径（接入已有项目）——不带 --require-empty
python "<CORE>/scripts/project_scaffold.py" --project "<目标>" --params "<params.json>"

A 路径必须带 --require-empty：它保证目标是不存在或近空的。少了这个参数，用户把项目名 起成跟已有目录同名时，会静默把一个已有代码仓当成新项目 scaffold——文件不会被破坏，但 接入流程（存量分析 + CLAUDE.md 整合）被整个跳过，框架约定进不去，而落盘验收只查「文件存在」 已经跳过的整合补不回来（目标已有 CLAUDE.md 时验收会报契约段缺失，但那时返工成本更高； 目标没有 CLAUDE.md 时四段齐全、验收看不出走错路径）。退出码 3 = 目标非空，此时改走接入 流程或换个不存在的路径，不要去掉参数硬来。

参数文件必须写在目标目录之外（系统临时目录即可，tree.json 同理）。写进目标目录时它自己 就是"实质内容"，A 路径会被 --require-empty 判为目标非空退出 3——而那条报错说的是「目标已有 内容」，照上一段的处置就会错走接入流程，把新建项目专属的存量分析与 CLAUDE.md 整合整个跳过。

非零退出即停下报错，不要跳过继续。退出码语义：3 = 目标非空（见下段处置）；1 = 模板文件缺失（插件安装不完整，stdout 会列出缺哪些）——这时重装 core 插件再重跑，别在半成品骨架上继续初始化。

1.2 建模块树（结构闸确认过模块树时）

把确认页拍定的树写成 JSON（schema 见脚本 docstring：basics[] → subs[]，各带 name / owner / positioning / code_paths），交给脚本确定性落盘：

python "<CORE>/scripts/module_init.py" --project "<目标>" --params "<tree.json>"

脚本承包骨架复制、占位符零残留断言、positioning 写入、code_paths 与反向索引、 两层索引段重建，且幂等（重跑安全）。退出码 2 = 命名 / 参数校验失败——转述 stderr、 修正后重跑，不要手工补文件。只建 basic / sub 两层：需求资产包是整理归档阶段的产物。

1.5 写入合并后的 CLAUDE.md（仅 B 路径：目标已有 CLAUDE.md 时）

scaffold 见到已存在的 CLAUDE.md 会跳过——它跳过的这一份，由你按 §3 产出的合并稿写回。 写盘前按 <CORE>/reference/claude-md-merge-guide.md §第 4 步做备份判断（两条确定性命令， 不是凭感觉）：

cd "<目标>"
git ls-files --error-unmatch CLAUDE.md   # 被跟踪吗
git status --porcelain CLAUDE.md          # 输出空才算干净

两条都过 → 免备份（git 里有原文）；任一不过 → 先写 logs/CLAUDE.md.bak-<YYYYMMDD-HHmmss>。 写完在响应里说清备份去哪了，或为什么没备份、怎么用 git 回退。

A 路径（新建项目）没有这一步——scaffold 已按模板渲染好。

2. 订阅 core —— 两条命令缺一不可

cd "<目标>"
claude plugin marketplace add "<市场源>" --scope project     # ← §依赖方向 定位脚本输出的 SOURCE
claude plugin install core@workframe --scope project

<市场源> 取定位脚本输出的 SOURCE 字段，不是 CORE 也不是 installLocation（理由见 §依赖方向 末段：后两者是本地缓存路径，写进项目 settings 会让协作者装不上）。

只跑第二条会产出协作者用不了的项目：项目 settings 里只有 enabledPlugins、没有 extraKnownMarketplaces，别人 clone 后无法解析插件来源。CLI 不可用时降级为在响应中输出这两条命令请用户手动执行，并继续后续步骤。

3. 同步 rules 镜像

python "<CORE>/scripts/sync-rules.py" --project "<目标>"

3.5 git init + 首提交（A 路径默认做，确认页可取消）

必须排在 scaffold / 订阅 / sync-rules 之后——这样 .gitignore 已就位，首提交才不会把 workframe-state/ 与 logs/ 一起提交进去。

cd "<目标>"
git rev-parse --git-dir >/dev/null 2>&1 || git init
git add -A
git commit -m "chore: 初始化 Workframe 项目骨架"

• 目标已经是 git 仓（B 路径接入常见）→ 跳过 init，也不要替用户提交，他自己的工作区可能有 未提交改动
• git commit 失败（多半是没配 user.name / user.email）→ 保留 init 不回滚，在响应里 告诉用户怎么补完，继续后面的步骤
• 用户在确认页取消了这一项 → 整步跳过

为什么默认做：没有 git，.gitignore 是废的、doctor 的可移植性检查直接跳过、 「同事 clone 接入好的项目」这条路径根本不成立。

4. 逐模块深读与安置（小闸 × N——只对有资料的模块开）

骨干已完整（树在、订阅在、git 在），现在按模块逐个处理资料——深读发生在这里，不在粗扫：

• 每轮取一个有资料的模块：深读该模块名下的文件 → 给出安置 + 原件处置方案 （处置五条边界与 A 路径外部资料档位变体见 material-intake §原件处置）→ AskUserQuestion 确认 → 当场执行该模块安置，再进下一个模块
• 粒度弹性：1-2 份文件的小模块合并进相邻一轮；单轮确认不超过约 10 份文件的决策量 ——既不一次塞，又不过度分散。无资料的模块直接跳过
• 呈现纪律：每轮方案一张表结清（文件 / 一句话结论 / 建议去向 / 原件处置），需要展开的 行在表下另起短段说「为什么」；引用收口、外部源只拷不搬这类通用纪律首轮讲清， 后续轮只报例外，不逐轮重复
• 深读中发现更合理的切分 → 按结构闸口径向用户提议树微调（改动只影响相关模块）
• 安置纪律：成品 md 搬入 / 拷入后补最小 frontmatter，移动后收口三类引用 （frontmatter related / wikilink / 相对路径资源）；成品需求类 md 的落点优先 requirements/_draft/（未立项的需求 / 方案）或 <basic>/shared/（跨 sub 事实源）， others/ 是杂项区、不作成品文档的默认落点（2026-08-11 走查：两轮归属选择不一致， 据此收紧）；异构原料进 <sub>/others/原始资料/<批次>/（跨 sub 共用进 <basic>/shared/assets/原始资料/，分组进目录不平铺）；外部源一律拷不搬 （material-intake §2.1 红线：源目录只读）
• 大批量（约 >15 份 md）走逃生口：只安置样板批证明结构可用，其余留给重启后 /core:migrate-to-modules 批量迁移（记入步骤 5 的批次）
• 在线文档链接（飞书 / Notion 等）本地无副本，装机做不了——列入「待你导出」清单，进步骤 5 批次

4.5 节奏闸（有待整理归档的批次时才出现）

安置完成后，把剩余重型活摆到桌面上让用户拍节奏。整理归档 = 把 docx / xls / 截图等 原始资料读懂后整理成正式需求文档（即 requirement-archiving 九段流水线）。 预估只给客观量：每批几份文件、含几个需要用户拍板的决策点（如原文里的未决口径）—— 不给时间预估：模型执行速度与人力经验完全两码事，时间数字只会误导（2026-08-11 用户反馈）。 用 AskUserQuestion：

1. 现在连续做完（推荐——装完即完整状态）
2. 现在做一部分（选批次；其余接力）
3. 全部留到重启后（首个会话主动接起）
4. 暂不做（只在体检 / 看板可见，随时说「继续初始化」恢复）

同一张卡（或紧接的第二问）把 git 提交策略一并拍掉，之后全程沿用不再问： 每批完成自动提交（推荐；A 路径新建项目默认此档）/ 全部完成一次提交 / 用户自己管。 用户中途挂起剩余批次时，视作当前阶段完成——主动提议把已产出内容提交（经确认执行， 不强制）；否则「全部完成一次提交」会因挂起让产物无限期滞留未提交（2026-08-11 实测现场）。

盘量超预期时主动建议档位 2（结构 + 样板批当场做）——不硬撑长会话，也不擅自缩水。

PRD 风格定制提议（条件触发）：粗扫与逐模块深读中识别到 ≥3 份章节骨架趋同的存量 需求文档时，节奏闸顺带多问一项——本项目的 PRD 框架（装机已放入 .claude/skills/prd-style/， 当前为出厂默认版）要不要按你现有 PRD 风格定制？选定制 → 作为一个批次执行（当场做或 接力均可）：读 <CORE>/skills/prd-writer/SKILL.md §风格定制与萃取照做（样例抽取 → 差异与 冲突表逐条拍 → 过目确认 → 改写项目 prd-style）。不满 3 份或用户选默认 → 不动，一句带过 「以后随时说『按我的风格写 PRD』再定制」。

4.7 整理归档段（用户选了当场做的批次）

逐批执行，SOP 从磁盘读、逐阶段照做——skill 未加载不等于拿不到，这与 §3 读 material-intake SOP 是同一模式：

批次去向	照做的 SOP	解析脚本
异构原料归档	<CORE>/skills/requirement-archiving/SKILL.md（九段 Phase 0-8，含各阶段门禁）	该 skill scripts/ 下直接 python 跑
大批量 md 迁移	<CORE>/skills/migrate-to-modules/SKILL.md	—
代码反解 current-state	<CORE>/skills/code-to-doc/SKILL.md	—

纪律：

• 九段的每个阶段门禁照过（收料冻结 / 拍板集中问 / 反向对账缺一不可），装机场景不减配
• 每批完成主动汇报 + 按拍板的提交策略提交，并给用户离场点（「继续下一批还是今天到这？」）
• 中断不怕：阶段产物步步落盘 + 台账逐行记账，任何后续会话说「继续初始化」精确续上
• 收尾跑一次 python "<CORE>/scripts/check-stale-modules.py" rebuild-index 补齐 hook 缺席期间的索引

5. 断点标记——不是最后才写，是每步紧跟着记

setup-state.json 是为中断准备的，所以它必须在中断发生之前就记下进度。 scaffold 成功时会自己落 scaffold: ok（代码保证，不靠你记得）；从第 2 步起，每完成一步 立刻记一笔，用 core 的 mark_setup_step()：

python -c "import sys; sys.path.insert(0, r'<CORE>/scripts'); \
from project_scaffold import mark_setup_step; from pathlib import Path; \
mark_setup_step(Path(r'<目标>'), 'subscribe')"

失败时把原因一起记下（第三、四个参数）：

python -c "import sys; sys.path.insert(0, r'<CORE>/scripts'); \
from project_scaffold import mark_setup_step; from pathlib import Path; \
mark_setup_step(Path(r'<目标>'), 'subscribe', 'failed', 'claude CLI 不在 PATH')"

四步各自的落笔人——第三列是套进上面那个 python -c 外壳的调用，紧跟在该步做完之后执行：

step	什么时候记	怎么记
scaffold	步骤 1	脚本自动落，不用你记
subscribe	步骤 2 两条订阅命令都跑完	mark_setup_step(Path(r'<目标>'), 'subscribe')
sync_rules	步骤 3 sync-rules.py 退出 0 之后	mark_setup_step(Path(r'<目标>'), 'sync_rules')
acceptance	步骤 5.5 验收跑完	doctor 自己落笔（含失败原因），不用你记

acceptance 之所以不由你记：它的语义是「落盘验收做完了」，只能在验收之后写，而验收查的就是 这份文件——让你来记就成了自指，第一次跑必然缺它、必然报一条机制自造的 error。

条件步做了就记：B 路径 claude_md_merge；做了 git 的 git_init；建了树的 module_tree； 安置了资料的 placement（全部模块安置完才记 ok）；整理归档段做完的 transform。

有剩余批次时必须记 pending_work——用户在节奏闸拍了接力 / 暂不的批次、未定处置的 资料、待导出的在线文档，不记下来就再没人提起（收尾报告在 gitignore 的 logs/ 下， 重启后是空白屏）。这是「第二幕」接力链的起点：

python -c "import sys, json; sys.path.insert(0, r'<CORE>/scripts'); \
from project_scaffold import mark_pending_work; from pathlib import Path; \
mark_pending_work(Path(r'<目标>'), json.loads(r'''<batches JSON>'''), '<一句话安排>')"

batches 每项含 name / files（项目根相对）/ target_skill / pace——pace 用用户拍的节奏： relay（重启后做→首会话强接力）/ paused（暂不做→零打扰，仅体检可见）/ undecided（没做处置决策→软提醒 3 会话 + 文件搬走自清除）。 只填资料批次，不填 CLAUDE.md / .gitignore 这类项目约定文件。 当场全部做完则不写此键——doctor 的 init_completeness 直接报「完整落地」。

5.5 落盘验收（批次落定之后跑——时序是关键）

python "<CORE>/scripts/workframe_doctor.py" --project "<目标>" --group install

验收放在 pending_work 落定之后，「初始化完整度」读到的才是真实终态——放在安置前会 误报「完整落地」（2026-08-11 实测教训）。

11 项覆盖：骨架完整性（硬/软两档 + 占位符残留）、CLAUDE.md 四契约段、项目 PRD 框架 （prd-style 在位性，缺失仅 info）、config 三字段、订阅接线两项、rules 镜像 4 份、 .gitignore 必需条目、初始化断点、初始化完整度（pending_work 批次状态，纯 info）、 可移植性、环境与 hook 活性。

向用户报项数时以实际输出为准，不要照抄本行。本行到 2026-08-10 一直写「8 项」且漏了 claude_md——新增该检查时没同步这里，而它恰是 B 路径最该被验的一项。清单与代码有两处 事实源就会漂，check_doctor_install_group_contract 已对账两边。

此刻还没重启，所以依赖 hook 的项会显示 i「待首个会话后复查」——这是正常的，不要当失败。 重启后由 core 侧自动跑同一组做运行时验收，那时它们才有真结果。

来源形态是本地目录路径时必须提示用户：该项目对协作者不可自动安装（对方机器上没有这个路径），开源/团队协作场景应改用 git 源。

退出码 1（有 error）时当场对话修复（重试 / 给手工命令），修完才放行——不要把待办写进文件让用户日后自己发现。仅有 ! warn 时可继续，但要把每条 warn 念给用户听。

失败要当场记，而不是等流程末尾统一写——真断在中途时，末尾那次写入根本不会发生。 早期设计正是把它放在全流程最后一次性写：为中断设计的机制反过来要求流程别中断， 自我否定（2026-08-10 走查发现）。

顺带一个时序问题也随之解决：doctor 的 setup_state 项读的就是这份文件。按增量写法， 第 5.5 步落盘验收时此前各步已在文件里，它才验得到「装到哪一步」；旧写法下验收跑在写入之前， 那一项永远只能报「无 setup-state.json」。

§6 收尾

1. 写 <目标>/logs/creation-report.md：基本信息、对话摘要、最终结构、订阅与验收状态、后续建议。报告落 logs/ 不落项目根，避免污染业务目录。
2. 在响应正文里直接输出关键结论，不依赖用户去打开报告文件：

按有无剩余批次分两种话术——不给用户「装完了」的错觉是硬要求：

全部落地（无 pending_work）：

✅ 项目「<name>」已初始化并**完整落地**：模块树 <N> 个模块、<M> 份资料已归位<、K 份原料已归档>。

⚠️ 请现在用 Claude Code 打开 <target>（新开一个会话）：
1. core 的 hook 链路与 rules 需要新会话才激活
2. **屏幕会是空白的，这是正常的**——hook 的输出进的是 Claude 的上下文，不显示在终端。
   随便说句话（比如「装好了吗」），它会把首个会话的安装验收结果告诉你
3. 想自己确认：说「看板」让它读 `projects/board.yaml` 汇报，或跑
   `python "<CORE>/scripts/workframe_doctor.py" --group install`

有剩余批次（记了 pending_work）：

✅ 第一幕完成：模块树已建好、<已安置摘要>。

⏭️ 初始化还有**第二幕**（你拍的节奏）：<批次 × 节奏清单，含「待你导出」项>

⚠️ 请重启 Claude Code 打开 <target> 继续：屏幕是空白的（正常），**随便说句话**——
   我会按你拍的节奏接着带你走完第二幕。进度随时可查：说「看板」，或体检里的「初始化完整度」。

两种话术后都补一句（告知档，一行带过）：「本项目的 PRD 规范在 .claude/skills/prd-style/， 写 PRD 按它执行——想按自己习惯改，直接改这份文件」；本次做过风格定制的项目改说 「PRD 规范已按你的风格定制，在 .claude/skills/prd-style/」。

不要写「看启动横幅是否出现 [<name>]」——那句话在终端里看不见（2026-08-10 走查实证： 用户重启后面对空白屏，以为 hook 没跑，实际全部正常）。hook stdout 只进模型上下文。

首次会话由 core 侧自动做运行时验收：session-start-prep hook 在 session_counter == 1 时 内联跑同一组检查，结果直接打进启动上下文——纯代码确定性，不依赖模型自觉，本 skill 不再介入。

质量自检

• 目录状态按 §1.1 六步判过（根级 .git / 项目清单一票否决容器；拿不准按项目处理）
• 容器目录下没给出「就地建」「接入当前」，Q3 首选是 <容器>/<项目名>
• Q1/Q2 候选主体来自 Q1 的回答；来自当前目录的至多 1 个且标了推断依据、不是推荐项
• Q3 候选路径逐个查过存不存在；已存在有内容的没直接拿来当候选
• A 路径的 scaffold 命令带了 --require-empty（B 路径不带）
• 选择题都走了 AskUserQuestion，没在正文列 A/B/C 让用户敲字
• 确认页在正文完整展示过，且用户明确确认后才开始写盘
• core 路径经 known_marketplaces 定位，全程无 ../ 向上引用
• 订阅跑了两条命令，落盘验收确认两项声明齐全
• scaffold / sync-rules / doctor 任一非零退出都已停下处理，没有跳过继续
• 报告落 logs/，且关键结论已在响应正文输出
• 没在任何生成文件里硬编码本机用户名或桌面路径
• 结构闸只拍项目级三件事（树 / 合并稿 / 文件点名），粗扫未逐字深读全文
• 确认类输出分了档：拍板项完整展示、告知项精简指路；同一概念未逐轮重复解释
• 逐模块小闸：有资料的模块才开、单轮 ≤ 约 10 份决策量、确认后当场执行该模块安置
• 模块树经 module_init.py 落盘（不手搓树）；安置执行了引用收口；外部源只拷未动；大批量走了逃生口
• 节奏闸预估只给份数与待拍板决策点数、没给时间；git 提交策略一次拍板全程沿用
• 整理归档段逐阶段照 SOP（门禁不减配），每批完成有汇报与离场点
• 剩余批次已记 pending_work（pace 按用户拍板）；全部落地则未写此键
• 落盘验收跑在批次落定之后（「初始化完整度」读到真实终态）
• 收尾话术按有无第二幕分形态，没给「装完了」的错觉

与其他 skill 的衔接

场景	交给谁
存量资料盘点 / 分流 / 结构推荐	core material-intake（launcher 读其 SOP 照做）
basic / sub 建树	core module_init.py（§5 步骤 1.2 直接调）
规范 md 批量搬家	core migrate-to-modules（装机整理归档段读 SOP 照做，或按节奏接力到重启后）
异构原料整理归档	core requirement-archiving（同上，九段门禁装机不减配）
代码反解为现状文档	core code-to-doc（同上）
需求资产包（整理归档产物）	core module-init（requirement 模式，项目内执行）

注意事项

• 生成内容不追求一次完美，鼓励用户后续迭代完善。
• 整理归档节奏由用户在节奏闸拍板，不替用户决定；推迟的批次必须记 pending_work， 否则「第二幕」再没人提起——装完 ≠ 完整落地，完整落地 = pending_work 清零。