create-yss-spec 1.1.3 → 2.0.0

package/template/docs/user-guide/create-yss-spec-cli-guide.md

@@ -1,59 +1,28 @@
-# create-yss-spec 使用手册
+# create-yss-spec 外部 CLI 实践指南
 
-本文档面向需要初始化 `yss-spec-project-template` 模板实例仓库的内部开发者、Tech Lead、项目初始化负责人。
+本文面向需要基于 YSS Spec Project Template 初始化或同步研发管理仓库的使用者。CLI 源码、测试、发布和开发记录的目标维护位置是独立项目 [iloveZzz/create-yss-spec](https://github.com/iloveZzz/create-yss-spec)；本模板仓库只记录用户使用方法和实践建议。
 
-## 适用场景
+> 以下命令以独立 GitHub 仓库和 npm 包已完成初始化与发布为前提。首次使用前，先检查独立仓库 README 和 npm 包可用性。
 
-当你需要基于当前模板源仓库快速生成一个新的研发管理仓库时，使用 `create-yss-spec`。
+## 适用范围
 
-它适合做的事：
-
-- 初始化新的 PRD / 架构 / OpenAPI / Issue 管理仓库
-- 统一生成项目级文档骨架、Agent 协作约定和模板目录结构
-- 通过参数渲染项目名称、业务领域、团队规模等元信息
-
-它不负责做的事：
-
-- 生成前端 / 后端运行时代码工程
-- 自动安装依赖
-- 自动创建远端 Git 仓库、CI 或 Issue Board
-- 直接接管没有模板元数据的历史老项目
-- 自动解决本地已修改受管文件的冲突
+`create-yss-spec` 用于生成包含 Spec、架构、OpenAPI、Ticket 和 Agent 协作基线的模板实例仓库。它不负责生成前后端运行时工程，也不会代替你创建远程 Git 仓库、CI 或 Ticket Board。
 
 ## 快速开始
 
-推荐入口：
+推荐使用 npm create 入口：
 
 ```bash
 npm create yss-spec@latest
 ```
 
-兼容入口：
+也可直接通过 npx 执行：
 
 ```bash
 npx create-yss-spec@latest
 ```
 
-运行后会按顺序询问：
-
-1. `项目名称`
-2. `业务领域`
-3. `团队规模（可留空）`
-4. `目标目录`
-
-初始化完成后，CLI 会输出结果目录和下一步建议。
-
-## 最常见用法
-
-### 交互式初始化
-
-```bash
-npm create yss-spec@latest
-```
-
-适合第一次使用或希望手动确认输入内容的场景。
-
-### 指定参数直接生成
+首次使用建议先交互式执行，并在空的目标目录中生成项目。需要脚本化时，可显式传入项目信息：
 
 ```bash
 npx create-yss-spec@latest \
@@ -65,9 +34,9 @@ npx create-yss-spec@latest \
   --git-init
 ```
 
-适合脚本化、重复初始化或在 CI / shell 脚本中调用的场景。
+## 先预演再写入
 
-### 只预览，不真正写入
+在新环境、脚本或升级流程中，先使用 `--dry-run` 检查计划：
 
 ```bash
 npx create-yss-spec@latest \
@@ -77,193 +46,42 @@ npx create-yss-spec@latest \
   --dry-run
 ```
 
-`--dry-run` 只展示计划，不会创建目录，也不会删除已有文件。
-
-### 同步已有模板实例仓库
-
-```bash
-npx create-yss-spec@latest sync
-```
+`--force` 可能清理非空目标目录，只应在已确认目标和可恢复性后使用。具体参数、版本差异和安全语义以独立 CLI 仓库当前 README 与 `--help` 输出为准。
 
-适合已经由 `create-yss-spec` 初始化过、并且根目录带有 `.yss-template.json` 的模板实例仓库。
+## 同步已有模板实例
 
-### 只预演同步，不真正写入
+对由 CLI 初始化、且根目录包含 `.yss-template.json` 的实例仓库，可先预演同步：
 
 ```bash
 npx create-yss-spec@latest sync --dry-run
 ```
 
-适合在升级前先查看版本变化、将要更新的文件、将被跳过的本地改动文件，以及模板已删除但不会自动删除的文件。
-
-## 参数说明
-
-| 参数 | 含义 | 默认行为 |
-|---|---|---|
-| `--project-name` | 项目名称 | 不传则进入交互输入 |
-| `--business-domain` | 业务领域 | 不传则进入交互输入 |
-| `--team-size` | 团队规模 | 不传则进入交互输入，可留空 |
-| `--target-dir` | 输出目录 | 不传则进入交互输入 |
-| `--issue-tracker github\|gitlab` | 默认 issue tracker 偏好 | 默认 `github` |
-| `--dry-run` | 只预览复制 / 渲染计划，不写入文件 | 默认关闭 |
-| `--force` | 目标目录非空时允许清空后重新生成 | 默认关闭 |
-| `--git-init` | 初始化完成后执行 `git init` | 默认关闭 |
-| `--include-example-docs` | 显式保留示例文档 | 默认开启 |
-| `--no-example-docs` | 不生成示例文档 | 默认关闭 |
-
-`sync` 子命令当前只支持：
-
-- 在模板实例仓库根目录执行
-- 仓库内已存在 `.yss-template.json`
-- 以当前 npm 已发布包内置模板快照作为同步源
-
-## 输出内容说明
-
-CLI 会根据模板清单把源仓库内容分成三类处理：
-
-- `render`：需要写入项目变量的文件，例如 `AGENTS.md`、`README.md`
-- `copy`：原样复制的模板资产
-- `exclude`：不会进入实例仓库的维护性文件、本地配置和本需求自身的实现资产
-
-生成结果通常包含：
-
-- `AGENTS.md`
-- `CONTEXT.md`
-- `docs/requirements/`
-- `docs/architecture/`
-- `docs/api/`
-- `docs/design/`
-- `docs/testing/`
-- 项目级 Agent skills 与流程文档
-
-如果启用了 `--git-init`，目标目录下还会生成 `.git/`。
-
-初始化完成后，CLI 还会额外生成：
-
-- `.yss-template.json`
-
-这个文件用于记录模板名称、模板版本、模板来源、最近同步时间、受管模板文件基线和关键渲染变量。后续 `sync` 能否安全工作，依赖这份模板元数据。
-
-## 默认安全策略
-
-为了避免误覆盖，CLI 采用默认安全策略：
-
-- 目标目录非空时，默认直接失败
-- 只有显式传入 `--force` 时，才允许清空目标目录后重新生成
-- 目标目录不能位于模板源仓库内部
-- `--dry-run` 没有副作用
-
-对于 `sync`，默认安全策略还包括：
-
-- 当前目录缺少 `.yss-template.json` 时，直接拒绝同步
-- 只自动更新未被本地修改的受管模板文件
-- 本地已修改的受管文件会被跳过并报告
-- 模板新版本已删除的受管文件只报告，不自动删除
-
-## 示例结果
-
-一次典型执行完成后，你会看到类似输出：
-
-```text
-初始化完成
-输出目录：/path/to/your-project
-下一步建议：
-1. cd /path/to/your-project
-2. 如需版本管理，可执行 git init
-3. 检查 AGENTS.md、README 和 docs 目录是否符合预期
-```
-
-如果已经传了 `--git-init`，第二步会提示执行 `git status` 检查初始化结果。
-
-一次典型同步完成后，你会看到类似输出：
-
-```text
-同步完成
-模板版本：0.9.0 -> 1.0.0
-自动更新：2
-新增文件：1
-跳过文件：1
-删除差异：1
-本地已修改，已跳过：
-- README.md: 检测到本地已修改的受管文件
-模板已移除但未自动删除：
-- docs/legacy-note.md
-下一步建议：
-1. 运行 git diff 或 git status 检查同步结果
-2. 人工处理被跳过文件和删除差异（如有）
-3. 确认无误后提交本次模板同步结果
-```
-
-## 常见问题
-
-### 1. 提示“目标目录非空，当前主路径不支持覆盖已有内容”
-
-说明目标目录里已经有文件。
-
-处理方式：
-
-- 改用新的空目录
-- 或确认可以清空后，显式传入 `--force`
-
-### 2. 提示“目标目录不能位于模板源仓库内部”
-
-说明你把输出目录设到了当前模板仓库内部。这样会污染模板源仓库，CLI 会直接拒绝。
-
-处理方式：
-
-- 把 `--target-dir` 改成模板仓库外部目录
-
-### 3. 我想在 shell 管道或脚本里调用
-
-可以，CLI 已支持非 TTY 输入。建议优先显式传参；如果要走标准输入，请按交互顺序提供：
+确认文件更新、本地改动跳过项和模板删除差异后，再执行：
 
 ```bash
-printf 'Acme Spec Repo\nInvestment Research\n12\n/tmp/acme-spec-repo\n' \
-  | node packages/create-yss-spec/bin/create-yss-spec.js
+npx create-yss-spec@latest sync
 ```
 
-### 4. 为什么没有自动安装依赖或创建远端仓库
-
-这是设计上的非目标范围。当前 CLI 只负责初始化研发管理模板实例仓库，组织级权限操作和后续 bootstrap 仍由人工控制。
-
-### 5. 为什么 `sync` 提示缺少模板元数据
-
-说明当前目录不是受支持的模板实例仓库，或者它是一个早期初始化的历史项目，还没有 `.yss-template.json` 基线。
-
-处理方式：
-
-- 先确认当前目录是否真的是由 `create-yss-spec` 初始化出来的项目
-- 当前版本的 `sync` 只支持带模板元数据的项目
-- 历史老项目的接管 / attach 不在本版范围内
+对早期手工创建、不含 `.yss-template.json` 的仓库，不要直接假定可被 `sync` 接管；先查看独立 CLI 项目当前支持范围。
 
-### 6. 为什么 `sync` 没有覆盖我改过的文件
+## 生成后检查
 
-这是刻意的默认安全策略。CLI 会把这类文件识别为“本地已修改的受管文件”，只报告、跳过，不自动覆盖。
+初始化或同步后，至少完成以下检查：
 
-处理方式：
+1. 运行 `git status --short` 确认实际变更范围。
+2. 检查 `AGENTS.md`、`CONTEXT.md`、`README.md` 和 `docs/` 目录是否符合项目信息。
+3. 运行 `scripts/verify-template` 检查模板结构、Markdown 链接和 OpenAPI 样例。
+4. 如果是同步，人工处理被跳过的本地修改和只报告、未自动删除的文件。
+5. 审查通过后再创建 Git checkpoint，避免把无关脏文件混入提交。
 
-- 查看输出中的跳过文件列表
-- 用 `git diff` 比较当前项目版本和模板版本的差异
-- 人工决定是否合并模板变更
+## 问题定位边界
 
-## 维护与验证
-
-如果你在维护这个 CLI，本地验证命令是：
-
-```bash
-node --test packages/create-yss-spec/tests/init-cli.test.js
-```
-
-发布前可检查打包内容：
-
-```bash
-cd packages/create-yss-spec
-npm pack --dry-run
-```
+- CLI 安装、参数解析、初始化、同步、npm 发布或 CLI 测试问题：到 [create-yss-spec 独立仓库](https://github.com/iloveZzz/create-yss-spec) 追踪。
+- 模板内容、流程文档、Agent skills 或 `scripts/verify-template` 问题：在本模板仓库追踪。
 
 ## 继续阅读
 
 - [模板使用说明](./README.md)
 - [产品全生命周期使用手册](./product-lifecycle-workflow.md)
 - [产品研发全生命周期最佳实践](./product-rd-lifecycle-best-practices.md)
-- [实现路由记录](../implementation/yss-spec-cli-init-routing.md)
-- [产品需求文档：yss-spec 模板初始化 CLI](../requirements/yss-spec-cli-init-prd.md)
+- [create-yss-spec GitHub 项目](https://github.com/iloveZzz/create-yss-spec)

package/template/docs/user-guide/excalidraw-diagram-generator-guide.md

@@ -2,7 +2,7 @@
 
 `excalidraw-diagram-generator` 是可视化说明与审查辅助 skill，用来把流程、架构、状态、依赖、数据流和切片关系生成 `.excalidraw` 文件。
 
-它不替代 `yss-product-lifecycle`、PRD、OpenAPI、ADR、Issue 或测试。它的价值是让复杂关系可以被快速看见、讨论和审查。
+它不替代 `yss-product-lifecycle`、Spec、OpenAPI、ADR、Ticket 或测试。它的价值是让复杂关系可以被快速看见、讨论和审查。
 
 ## 1. 在流程中的定位
 
@@ -12,7 +12,7 @@
 机会探索 / Discovery
   -> 用户旅程图、机会地图、竞品流程泳道图
 
-PRD / 需求澄清
+Spec / 需求澄清
   -> 业务流程图、角色职责泳道图、页面地图
 
 OpenAPI Draft / 工程基线 / 架构设计
@@ -37,7 +37,7 @@ OpenAPI Draft / 工程基线 / 架构设计
 | 架构产物 | 产出阶段 | 图的价值 | 常用图类型 | 保存位置 |
 |---|---|---|---|---|
 | 业务架构图 | 机会探索 / Discovery / 产品定义 | 让用户、价值流、角色协作和产品边界可视化 | 用户旅程、价值流、泳道图、能力地图、生态关系图 | `docs/discovery/diagrams/` 或 `docs/architecture/diagrams/` |
-| 功能架构图 | PRD baseline / 产品设计 / PRD 校准 | 让功能域、模块、优先级和依赖关系可审查 | 功能模块图、依赖图、页面地图、关系图 | `docs/design/diagrams/` 或 `docs/architecture/diagrams/` |
+| 功能架构图 | Spec baseline / 产品设计 / Spec 校准 | 让功能域、模块、优先级和依赖关系可审查 | 功能模块图、依赖图、页面地图、关系图 | `docs/design/diagrams/` 或 `docs/architecture/diagrams/` |
 | 系统总体架构图 | 工程基线 / 系统 / 数据架构设计 | 让服务边界、部署、集成、权限链路和 NFR 方案可审查 | C4/容器图、部署图、序列图、DFD、DDD 边界图 | `docs/architecture/diagrams/` |
 | 数据架构图 | 详细设计 / 持久化开发前 | 让元模型、版本、血缘、查询和存储策略在写 Repository 前被看见 | ER 图、Class/元模型图、血缘图、DFD、查询路径图 | `docs/architecture/diagrams/` |
 
@@ -56,7 +56,7 @@ OpenAPI Draft / 工程基线 / 架构设计
 不适用：
 
 - 单点文案、小样式、小 bug。
-- 已有清晰 PRD / OpenAPI / ADR，且没有理解歧义。
+- 已有清晰 Spec / OpenAPI / ADR，且没有理解歧义。
 - 只是为了让文档看起来更完整。
 
 ## 3. 与 Agents 的协作
@@ -68,7 +68,7 @@ OpenAPI Draft / 工程基线 / 架构设计
 | API Contract Agent | 画接口调用序列、数据流、错误流 |
 | Architecture Agent | 画系统架构、DDD 分层、模块依赖、ER / Class / DFD |
 | Design Review Agent | 对图做审查，找职责不清、循环依赖、契约缺口 |
-| Code Agent | 消费图辅助理解，不用图替代 PRD、OpenAPI 或 ADR |
+| Code Agent | 消费图辅助理解，不用图替代 Spec、OpenAPI 或 ADR |
 | Review Agent | 检查实现是否偏离图中的边界和流程 |
 | Knowledge / Retro Agent | 把稳定流程或架构图沉淀到 docs |
 
@@ -102,16 +102,16 @@ docs/architecture/diagrams/model-ddd-boundary.excalidraw
 推荐三步法：
 
 1. 先有文字事实。
-   来源应该是 Discovery、PRD、OpenAPI Draft、Architecture、系统 / 数据架构设计 或 Issue。
+   来源应该是 Discovery、Spec、OpenAPI Draft、Architecture、系统 / 数据架构设计 或 Ticket。
 2. 再生成图。
    根据用途选择 Flowchart、Swimlane、Relationship、Class、ER、Sequence、DFD、Architecture 或 Mind Map。
 3. 最后回写审查结论。
-   图里暴露的问题要回写到 PRD、OpenAPI、ADR、系统 / 数据架构设计 或 Issue。
+   图里暴露的问题要回写到 Spec、OpenAPI、ADR、系统 / 数据架构设计 或 Ticket。
 
 常用提示词：
 
 ```text
-使用 excalidraw-diagram-generator，基于 docs/requirements/<feature>-prd.md
+使用 excalidraw-diagram-generator，基于 docs/requirements/<feature>-spec.md
 和 docs/api/specs/<feature>.yaml，生成 <feature> 的接口调用序列图。
 保存到 docs/architecture/diagrams/<feature>-sequence.excalidraw。
 ```

package/template/docs/user-guide/grill-with-docs-best-practices.md

@@ -11,13 +11,13 @@
 好的使用方式：
 
 ```text
-请先连续追问，不要直接生成 PRD。
+请先连续追问，不要直接生成 Spec。
 ```
 
 不好的使用方式：
 
 ```text
-我有个想法，直接帮我生成完整 PRD。
+我有个想法，直接帮我生成完整 Spec。
 ```
 
 如果 AI 开始替你补全关键业务规则，要把它拉回来：
@@ -35,7 +35,7 @@
 - 是本项目特有的业务语言。
 - 定义能用一两句话说清。
 - 有同义词或容易误用的词需要规避。
-- 后续 PRD、OpenAPI、代码、测试都会复用。
+- 后续 Spec、OpenAPI、代码、测试都会复用。
 
 不写入：
 
@@ -69,9 +69,9 @@ ADR 不是会议纪要，也不是方案全文。它只记录难以回滚、非
 
 实施计划应交给：
 
-- `to-prd`
+- `to-spec`
 - `writing-plans`
-- `Issue`
+- `Ticket`
 - `yss-router`
 
 ## 2. 推荐追问维度
@@ -164,11 +164,11 @@ ADR 不是会议纪要，也不是方案全文。它只记录难以回滚、非
 追问哪些竞品能力进入 MVP，哪些作为非目标。
 ```
 
-输出应能支撑 discovery 和 PRD。
+输出应能支撑 discovery 和 Spec。
 
-### 3.2 PRD 之前
+### 3.2 Spec 之前
 
-PRD 之前使用 grill，可以降低“AI 代替产品经理做决定”的风险。
+Spec 之前使用 grill，可以降低“AI 代替产品经理做决定”的风险。
 
 推荐输出：
 
@@ -178,16 +178,16 @@ PRD 之前使用 grill，可以降低“AI 代替产品经理做决定”的风
 - OpenAPI 影响初判。
 - 待人工确认问题。
 
-### 3.3 Issue 之前
+### 3.3 Ticket 之前
 
-Issue 需要清晰 change 目标。如果目标还模糊，先 grill。
+Ticket 需要清晰 change 目标。如果目标还模糊，先 grill。
 
-进入 Issue 拆分前至少确认：
+进入 Ticket 拆分前至少确认：
 
 - change 名称表达一个目标。
 - 主要行为和非目标清楚。
 - API 影响明确。
-- 是否触碰安全红线。
+- 是否存在高风险变更、人工确认项或回滚约束。
 - 是否存在需要 ADR 的取舍。
 
 ### 3.4 YSS 实现之前
@@ -238,9 +238,9 @@ Issue 需要清晰 change 目标。如果目标还模糊，先 grill。
 | AI 替业务做决定 | 关键规则来自猜测 | 标为待确认 |
 | 术语都写进 CONTEXT.md | 词汇表膨胀失真 | 只写稳定业务语言 |
 | ADR 写成大方案 | 后续没人读 | 只记录决定和原因 |
-| grill 之后直接开发 | PRD / OpenAPI / change 丢失 | 先进入 PRD 或 Issue |
+| grill 之后直接开发 | Spec / OpenAPI / change 丢失 | 先进入 Spec 或 Ticket |
 | 只问正常路径 | 异常场景上线后暴露 | 必问失败、并发、权限、回滚 |
-| 把实现细节写入 glossary | 领域语言污染 | 实现细节放 PRD、设计或 ADR |
+| 把实现细节写入 glossary | 领域语言污染 | 实现细节放 Spec、设计或 ADR |
 
 ## 6. 检查清单
 
@@ -266,10 +266,10 @@ Issue 需要清晰 change 目标。如果目标还模糊，先 grill。
 - [ ] 已列出待确认问题。
 - [ ] `CONTEXT.md` 没有实现细节。
 - [ ] ADR 只记录必要决定。
-- [ ] 已明确下一步是 discovery、PRD、OpenAPI、Issue 还是实现路由。
+- [ ] 已明确下一步是 discovery、Spec、OpenAPI、Ticket 还是实现路由。
 
 ## 7. 一句话原则
 
 ```text
-grill-with-docs 的成果不是“问了很多问题”，而是让后续 PRD、规格和代码不再靠猜。
+grill-with-docs 的成果不是“问了很多问题”，而是让后续 Spec、规格和代码不再靠猜。
 ```

package/template/docs/user-guide/grill-with-docs-guide.md

@@ -14,10 +14,10 @@ grill-with-docs = 追问清楚 + 同步沉淀领域语言和关键决策
 
 - “模型发布”到底是按钮、流程、版本冻结，还是对外生效机制，没有说清。
 - “管理员”“实施人员”“建模人员”混用，权限边界不清。
-- AI 直接写 PRD，但关键边界来自猜测。
+- AI 直接写 Spec，但关键边界来自猜测。
 - 重要取舍只留在聊天里，后续实现和复盘找不到依据。
 
-`grill-with-docs` 的价值是先把这些问题问透，再进入 PRD、OpenAPI、Issue 或开发。
+`grill-with-docs` 的价值是先把这些问题问透，再进入 Spec、OpenAPI、Ticket 或开发。
 
 ## 2. 什么时候使用
 
@@ -25,17 +25,17 @@ grill-with-docs = 追问清楚 + 同步沉淀领域语言和关键决策
 
 | 场景 | 典型信号 | 下一步产物 |
 |---|---|---|
-| 新产品 / 新模块 | “我要新建工程”“做数据中台模型管理” | discovery、PRD、`CONTEXT.md` |
+| 新产品 / 新模块 | “我要新建工程”“做数据中台模型管理” | discovery、Spec、`CONTEXT.md` |
 | 模糊需求 | “支持模型发布”“加个审批” | 明确范围、非目标、验收标准 |
 | 领域术语混乱 | 同一个概念有多个叫法 | 更新 `CONTEXT.md` |
 | 关键取舍出现 | 版本能否回滚、发布是否可撤销 | 必要时写 ADR |
-| 进入 PRD 前 | 已有想法但边界不稳 | `to-prd` 输入 |
-| 进入 Issue 前 | change 目标还不够清晰 | proposal / design 输入 |
+| 进入 Spec 前 | 已有想法但边界不稳 | `to-spec` 输入 |
+| 进入 Ticket 前 | change 目标还不够清晰 | proposal / design 输入 |
 
 不适合使用：
 
 - 只是 typo、文案或局部样式调整。
-- 已有清晰 PRD、OpenAPI 和任务，只需要执行。
+- 已有清晰 Spec、OpenAPI 和任务，只需要执行。
 - Bug 已经可复现，应先用 `systematic-debugging`。
 - 单纯整理已有会议纪要，不需要追问或改变领域模型。
 
@@ -48,7 +48,7 @@ grill-with-docs = 追问清楚 + 同步沉淀领域语言和关键决策
 - 业务想法或问题。
 - 当前用户角色。
 - 你认为的成功结果。
-- 已有材料路径，例如 discovery、PRD、竞品分析、OpenAPI、现有页面。
+- 已有材料路径，例如 discovery、Spec、竞品分析、OpenAPI、现有页面。
 
 更好的输入：
 
@@ -67,7 +67,7 @@ grill-with-docs = 追问清楚 + 同步沉淀领域语言和关键决策
 - 已确认的用户、场景、范围和非目标。
 - 稳定术语更新到 `CONTEXT.md`。
 - 确有必要时，新增或建议 ADR。
-- 下一步建议：继续 discovery、生成 PRD、更新 OpenAPI、创建 Issue change，或进入实现路由。
+- 下一步建议：继续 discovery、生成 Spec、更新 OpenAPI、创建 Ticket，或进入实现路由。
 
 ## 4. 推荐流程
 
@@ -76,7 +76,7 @@ grill-with-docs = 追问清楚 + 同步沉淀领域语言和关键决策
 -> grill-with-docs
 -> 更新 CONTEXT.md
 -> 必要时新增 ADR
--> to-prd 或 PRD 文档
+-> to-spec 或 Spec 文档
 -> API 影响分析 / 契约草案
 -> review-only OpenAPI Draft（如需要）
 -> 工程基线 / 系统 / 数据架构设计
@@ -116,7 +116,7 @@ grill 的重点是“被问住”。遇到不确定的问题，不要让 AI 替
 2. 非目标范围
 3. 已更新术语
 4. 需要人工确认的问题
-5. 下一步建议进入 PRD、OpenAPI 还是 Issue
+5. 下一步建议进入 Spec、OpenAPI 还是 Ticket
 ```
 
 ## 5. 与 CONTEXT.md 的关系
@@ -170,9 +170,9 @@ _Avoid_: 上线、提交、保存
 
 | 阶段 | 先用 | 后接 |
 |---|---|---|
-| 机会探索后澄清 | `grill-with-docs` | discovery / PRD |
-| PRD 前 | `grill-with-docs` | `to-prd` |
-| Issue 拆分前 | `grill-with-docs` | `to-issues` |
+| 机会探索后澄清 | `grill-with-docs` | discovery / Spec |
+| Spec 前 | `grill-with-docs` | `to-spec` |
+| Ticket 拆分前 | `grill-with-docs` | `to-tickets` |
 | 正式变更技术设计前 | `grill-with-docs` 只在需求边界仍不清时使用 | `issue` / `需求澄清` |
 | 实现前 | `grill-with-docs` 只在需求不清时使用 | `writing-plans` / `yss-router` |
 | Bug | 通常不用 | `systematic-debugging` |
@@ -182,9 +182,9 @@ _Avoid_: 上线、提交、保存
 ```text
 yss-product-lifecycle
 -> grill-with-docs
--> to-prd
+-> to-spec
 -> OpenAPI
--> Issue
+-> Ticket
 ->  Matt skills / YSS skills
 ```
 
@@ -201,12 +201,12 @@ yss-product-lifecycle
 ```
 
 ```text
-使用 grill-with-docs，检查这份 PRD 还有哪些边界没问清。
+使用 grill-with-docs，检查这份 Spec 还有哪些边界没问清。
 如果发现稳定术语，更新 CONTEXT.md；如果出现重大取舍，建议是否需要 ADR。
 ```
 
 ```text
-使用 grill-with-docs，帮我把这个功能进入 Issue 拆分前的问题问完。
+使用 grill-with-docs，帮我把这个功能进入 Ticket 拆分前的问题问完。
 输出：已确认范围、未确认问题、术语变更、ADR 建议、下一步 prompt。
 ```
 
@@ -215,7 +215,7 @@ yss-product-lifecycle
 如果只记一条：
 
 ```text
-先让 AI 追问到你说清楚，再让 AI 写 PRD 或代码。
+先让 AI 追问到你说清楚，再让 AI 写 Spec 或代码。
 ```
 
 对应资产：
@@ -225,5 +225,5 @@ CONTEXT.md
 docs/adr/
 docs/discovery/
 docs/requirements/
-docs/requirements/issues/
+docs/requirements/tickets/
 ```