visual-spec 0.1.10 → 0.1.12

package/README.md

@@ -1,6 +1,6 @@
 This repo provides a requirements analysis and delivery assistant Skill. It offers a `/vspec:*` command-driven workflow that turns raw requirements into reviewable artifacts: specs, data models, runnable prototypes, detailed design, acceptance cases, tests, and integrated implementation inputs.
 
-Version: 0.1.10 (2026-04-12)
+Version: 0.1.12 (2026-04-12)
 
 ## Installation
 

package/docs/en-US/workflows.md

@@ -5,8 +5,38 @@
 - Provide the raw requirement input
 - Answer open questions (key assumptions, scope, rules, dependencies)
 - Get baseline artifacts under `/specs/`: roles, terms, flows, scenarios, function list, dependencies, questions
+- Answer questions (HTML, recommended):
+  - `/vspec:new` generates an interactive Q&A page: `/specs/background/question_and_answer.html`
+  - Open the HTML, then pick:
+    - `/specs/background/original.md`
+    - `/specs/background/questions.md`
+  - Answer questions in the form UI and save back (if the browser supports File System Access API, it can overwrite; otherwise download and replace manually)
 
-### 2. Detailed Specs (`/vspec:detail`)
+### 2. More Questions (`/vspec:more-q`)
+
+- Use when the question list is not enough or the requirement changed and you need more clarifications
+- Input: `/specs/background/questions.md` (if missing, run `/vspec:new` first)
+- Output: append new items to `/specs/background/questions.md` (new questions + how-to-answer)
+- Answer questions (HTML, recommended):
+  - `/vspec:more-q` updates/generates the same Q&A page: `/specs/background/question_and_answer.html`
+  - Open the HTML, answer the newly appended questions, save back, then run `/vspec:refine-q`
+
+### 3. Merge Answers (`/vspec:refine-q`)
+
+- Use when the business has filled answers in `/specs/background/questions.md` and you want to merge them back into the canonical requirement
+- Input: answered items in `/specs/background/questions.md` + `original.md`
+- Output: append updates to `/specs/background/original.md` (adopted items + change log + latest wording)
+
+### 4. Apply Refinements (`/vspec:refine`)
+
+- Use when new information arrives during implementation and you need to update the canonical requirement and sync downstream artifacts
+- Inputs:
+  - Default: `/docs/refine/*` (prefer `file_list.md`)
+  - Optional: files/directories passed as command arguments
+- Prerequisite: `/specs/details/` must exist and be non-empty
+- Outputs: append updates to `original.md` and update impacted `/specs/details/` and `/specs/prototypes/`
+
+### 5. Detailed Specs (`/vspec:detail`)
 
 - Using `/specs/functions/*` as input, generate per-function specs under `/specs/details/<function_slug>/`
 - Goal: turn “requirements” into implementable design inputs:
@@ -14,8 +44,16 @@
   - load/interaction/validation matrices
   - post-submit checks/processing/navigation
   - logging/notification matrices, MQ specs, import/export, cron jobs
+- Extra output: `/specs/details/index.html` (left directory tree + right markdown-rendered reader; PlantUML rendered as diagrams)
+
+### 6. Word Summary Doc (`/vspec:doc`)
 
-### 3. Solution Verification (`/vspec:verify`)
+- Use when you need a deliverable Word doc for review/circulation/archiving based on current artifacts
+- Input: existing `/specs/**` artifacts (original/functions/details/models/flows, when available)
+- Output: `/docs/current/requirement_detail.docx` (Word-openable `.docx`, single-file HTML)
+- Note: this Word file is a read-only summary; make changes in the corresponding markdown files and rerun `/vspec:doc` to regenerate
+
+### 7. Solution Verification (`/vspec:verify`)
 
 - Prerequisite: `/specs/details/` exists and is non-empty
 - Based on `/specs/` (functions + details + roles), generate:
@@ -31,29 +69,45 @@ Optional: segmented prototype generation
   - `/vspec:proto-execute`: execution flow pages (including mobile `/m/*`)
   - `/vspec:proto-crud`: config/master-data CRUD admin pages
 
-### 4. Acceptance Cases (`/vspec:accept`)
+### 8. Acceptance Cases (`/vspec:accept`)
 
 - Generate acceptance cases into `/specs/acceptance/`
 - Goal: define acceptance criteria and coverage (happy path, exceptions, boundaries, RBAC, data permissions)
 
-### 5. Automated Tests (`/vspec:append-test`)
+### 9. Automated Tests (`/vspec:append-test`)
 
 - Read acceptance cases and the repo’s existing test stack
 - Generate a minimal runnable set of E2E/API/unit tests
 - Note: this step only generates/adds test code to improve coverage; it does not run test commands (e.g. mvn test).
 
-### 6. Integrated Implementation (`/vspec:impl`)
+### 10. Integrated Implementation (`/vspec:impl`)
 
 - Read specs, details, models, and dependencies
 - Generate integrated backend + frontend code following repo conventions (API contract → backend implementation → frontend integration)
 
-### 7. Planning (`/vspec:plan`)
+### 11. Quality Check (`/vspec:qc`)
+
+- Run a quality check on artifacts under `/specs/`
+- Output: `/specs/qc_report.md`
+
+### 12. Planning (`/vspec:plan`)
 
 - Split functions and scenarios into user stories, estimate effort, and build iteration schedules
 - Outputs:
   - `/specs/plan/plan_estimate.md`
   - `/specs/plan/plan_schedule.html`
 
+### 13. Upgrade / Retrofit (`/vspec:upgrade`)
+
+- Use when you need to retrofit/upgrade based on materials under `/docs/` (legacy/current)
+- Entry list: `/docs/current/file_list.md` (generated if missing)
+- Output: generate/update `/specs/` following the `/vspec:new` structure and sync tech selections to `/scheme.yaml`
+
+### 14. MRD Pack (`/vspec:mrd`)
+
+- Generate market/competitor/user/product-design pack
+- Output directory: `/docs/market/` (market/competitors/users/product_design)
+
 ## Installation (skills.sh)
 
 ```bash

package/docs/ja-JP/workflows.md

@@ -5,34 +5,85 @@
 - 生の要件を入力
 - 前提・範囲・ルール・依存関係などの確認質問に回答
 - `/specs/` にベースライン成果物（roles/terms/flows/scenarios/functions/dependencies/questions）を生成
+- 質問への回答（HTML、推奨）：
+  - `/vspec:new` は対話式 Q&A ページを生成：`/specs/background/question_and_answer.html`
+  - HTML を開き、以下を選択：
+    - `/specs/background/original.md`
+    - `/specs/background/questions.md`
+  - フォームで回答し保存して md に反映（ブラウザが File System Access API に対応していれば直接上書き、未対応ならダウンロードして手動で置換）
+
+### 2. 追加質問（`/vspec:more-q`）
+
+- 質問が不足している、または要件が変わって追加確認が必要な場合に使う
+- 入力：`/specs/background/questions.md`（無い場合は先に `/vspec:new`）
+- 出力：`/specs/background/questions.md` に追記（追加質問 + 回答手順）
+- 質問への回答（HTML、推奨）：
+  - `/vspec:more-q` は同じ Q&A ページを更新/生成：`/specs/background/question_and_answer.html`
+  - HTML を開き、追加された質問に回答して保存し、最後に `/vspec:refine-q` を実行
+
+### 3. 回答の取り込み（`/vspec:refine-q`）
+
+- `questions.md` に記入した回答を要件口径へ取り込む
+- 入力：回答済みの `/specs/background/questions.md` + `original.md`
+- 出力：`/specs/background/original.md` へ追記（採用項目 + 変更点 + 最新口径）
+
+### 4. 追補の適用（`/vspec:refine`）
+
+- 実装中の追加情報/明確化を反映し、口径と下流成果物を同期する
+- 入力：
+  - 既定：`/docs/refine/*`（`file_list.md` があれば優先）
+  - 任意：コマンド引数で指定したファイル/ディレクトリ
+- 前提：`/specs/details/` が存在し空でない
+- 出力：`original.md` へ追記 + 影響する `/specs/details/` と `/specs/prototypes/` を更新
 
-### 2. 詳細 spec（`/vspec:detail`）
+### 5. 詳細 spec（`/vspec:detail`）
 
 - `/specs/functions/*` を入力に、機能ごとの仕様を `/specs/details/<function_slug>/` に生成
 - 目標：要件を実装可能な設計入力へ変換
+- 追加出力：`/specs/details/index.html`（左にディレクトリツリー、右に Markdown レンダリング。PlantUML は図としてレンダリング）
+
+### 6. Word 要約ドキュメント（`/vspec:doc`）
+
+- 既存成果物を集約してレビュー/回覧/保管用の Word 文書を生成する
+- 入力：既存の `/specs/**`（original/functions/details/models/flows など。存在するものを読む）
+- 出力：`/docs/current/requirement_detail.docx`（Word で開ける `.docx`、単一 HTML）
+- 注意：この Word は要約用（直接編集しない）。修正は対応する markdown を更新し、`/vspec:doc` を再実行して再生成する
 
-### 3. 検証（`/vspec:verify`）
+### 7. 検証（`/vspec:verify`）
 
 - 前提：`/specs/details/` が存在し空でない
 - `/specs/models/*.md` と、`/scheme.yaml` の選択に従った実行可能プロトタイプを `/specs/prototypes/` に生成
 
-### 4. 受入ケース（`/vspec:accept`）
+### 8. 受入ケース（`/vspec:accept`）
 
 - `/specs/acceptance/` に受入テストケースを生成
 
-### 5. 自動テスト（`/vspec:append-test`）
+### 9. 自動テスト（`/vspec:append-test`）
 
 - 受入ケースと既存テストスタックを読み、E2E/API/単体テストの最小セットを生成
 - 注意：テスト実行は行わず、コード生成/追記のみ
 
-### 6. 統合実装（`/vspec:impl`）
+### 10. 統合実装（`/vspec:impl`）
 
 - specs/details/models/dependencies を読み、リポジトリの規約に沿った統合コードを生成
 
-### 7. 見積・排期（`/vspec:plan`）
+### 11. 品質チェック（`/vspec:qc`）
+
+- `/specs/` 配下の成果物を品質チェックし、`/specs/qc_report.md` を生成
+
+### 12. 見積・排期（`/vspec:plan`）
 
 - 機能一覧とシナリオをもとに見積・排期（HTML）を生成
 
+### 13. アップグレード/改修（`/vspec:upgrade`）
+
+- `/docs/` 配下の資料（legacy/current）に基づき、`/vspec:new` と同様の構造で `/specs/` を再生成/更新
+- 入口：`/docs/current/file_list.md`（無ければテンプレを生成）
+
+### 14. MRD（`/vspec:mrd`）
+
+- 市場/競合/ユーザー/プロダクト設計の分析パックを生成し、`/docs/market/` に書き出す
+
 ## インストール（skills.sh）
 
 ```bash

package/docs/zh-CN/commands.md

@@ -20,6 +20,7 @@
 
 - 适用场景：刚拿到需求且信息不完整，需要快速形成“可评审的共同语言”
 - 关键输出：干系人、角色、术语、流程、场景、功能清单、开放问题
+- 原始材料归档：如果你有原始材料文件（PRD/需求文档/流程说明/字段口径/模板/协议/截图/样例数据等），统一放在 `/docs/current/`（便于后续 refine/upgrade/verify/impl 等命令按约定读取与引用）
 - 目录初始化：创建 `/docs/` 及其子目录（legacy/current/refine/templates/texts/assets）用于输入归档与后续命令使用
 - 提示：生成“开放问题/待确认问题”后，你可以把回答工作委托给 AI 先给出建议答案，你只需要逐条确认/修改即可（推荐做法：先让 AI 代答一版，再由业务确认口径）
 

package/docs/zh-CN/complicated.md

@@ -0,0 +1,60 @@
+# 复杂输入材料（Word/Excel 等）的归档与使用
+
+当你的需求不是“一段文字”，而是多份原始材料（Word/Excel/PDF/流程图/截图/样例数据/协议等）时，建议把这些材料统一归档到 `/docs/`，并通过约定目录与清单文件让 Skill 能够稳定引用与复用。
+
+## 1. `/docs/current/`：本次需求/迭代的原始材料
+
+把“本次要分析的输入材料”放到 `/docs/current/`，并尽量保持结构清晰、可追溯、可复用。
+
+推荐做法：
+- 用子目录按来源/主题组织（可选）：`/docs/current/prd/`、`/docs/current/rules/`、`/docs/current/ui/`、`/docs/current/data/`、`/docs/current/api/`
+- 文件名建议包含：来源、主题、版本或日期，例如：
+  - `prd_v3_2026-04-12.docx`
+  - `field_mapping_v1.xlsx`
+  - `process_overview_v2.pdf`
+  - `ui_screenshots_2026-04-12/`（多张截图可用目录）
+- 如果你有“材料入口清单”，放在：`/docs/current/file_list.md`
+  - `/vspec:upgrade` 会读取/生成该文件，并按清单顺序读取输入
+  - 即使 `/vspec:upgrade` 会扫描 `/docs/legacy/`，你仍然应该在 `file_list.md` 中把“你认为最重要/最权威”的材料排在前面
+
+常见材料放置建议：
+- Word/Doc/PRD：放 `prd/` 或根目录，强调“口径优先级”
+- Excel（字段口径、枚举、映射表、权限矩阵、接口清单）：放 `rules/` 或 `data/`
+- PDF（历史说明/流程/合规材料）：放 `prd/` 或 `rules/`
+- 截图/原型/设计稿：放 `ui/` 或 `assets/`
+- 样例数据（CSV/JSON）：放 `data/`
+
+## 2. `/docs/legacy/`：升级/重构场景的遗留系统材料
+
+当你做的是“升级/重构/迁移”，遗留系统材料应该放在 `/docs/legacy/`（包含子目录）。例如：
+- 旧系统功能说明、页面截图、交互说明
+- 旧 RBAC/权限模型、数据权限口径
+- 旧接口文档、事件/MQ 定义、对账规则
+- 旧表结构/字段定义、枚举表、状态机
+
+`/vspec:upgrade` 的用法要点：
+- 会递归扫描 `/docs/legacy/` 及其子目录，把其中的文档当作原始输入资料
+- 若发现 `/docs/current/file_list.md` 未覆盖的 legacy 文件，会先把它们追加进 `file_list.md`，再读取并参与抽取
+- 你仍然可以通过 `/docs/current/file_list.md` 来“控制阅读顺序”和“强调哪些文件更权威”，避免被大量 legacy 资料淹没
+
+## 3. `/docs/dependencies/`：外部依赖系统文档库
+
+当你的需求依赖外部系统（例如 SSO/CRM/ERP/支付/消息/地图/库存等），建议把这些依赖系统的“稳定资料”沉淀到 `/docs/dependencies/`，作为长期复用的知识库。
+
+推荐放入：
+- 对方系统的接口说明、字段字典、错误码、鉴权方式
+- 回调/事件/MQ 消息定义、签名校验、幂等规则
+- 业务对账规则、结算口径、对接注意事项
+- 版本更新记录与差异说明（如有）
+
+与 `/docs/current/` 的区别：
+- `/docs/current/`：本次迭代的输入（更可能频繁变动）
+- `/docs/dependencies/`：依赖系统的“相对稳定资料”（用于多次迭代复用）
+
+## 4. 推荐操作顺序（有多份材料时）
+
+1. 把材料放入 `/docs/current/`（需要升级/重构则同时整理 `/docs/legacy/`）
+2. 如材料较多：先整理 `/docs/current/file_list.md`（按“权威性/优先级”排序）
+3. 运行 `/vspec:new`（生成 `/specs/background/original.md` 与问题清单）
+4. 需要继承 legacy/当前材料并生成新 specs：运行 `/vspec:upgrade`
+5. 需要汇总成 Word：运行 `/vspec:doc` 输出到 `/docs/current/requirement_detail.docx`

package/docs/zh-CN/getting-started.md

@@ -45,6 +45,7 @@ npx skills add visual-req/visual-spec --skill visual-spec
 下一步：
 
 - 阅读 `structure.md`，确认输入放在哪里、输出会生成到哪里
+- 如果你的需求输入包含多份原始材料（Word/Excel/PDF/截图等），阅读 `complicated.md`，了解如何放置到 `/docs/current/`、以及 upgrade/legacy/dependencies 的用法
 
 ### 4. 常见场景
 

package/docs/zh-CN/structure.md

@@ -11,7 +11,7 @@ Skill 会按命令阶段逐步在 `/specs/` 下生成产物，并维护少量项
 <your-project>/
 ├─ docs/                                  # 输入归档（/vspec:new 会创建）
 │  ├─ legacy/                             # 遗留系统材料（功能、权限、交互、API 等）
-│  ├─ current/                            # 本次迭代新增/补充材料（目标、差异、流程、UI 约束等）
+│  ├─ current/                            # 本次迭代新增/补充材料（也包括 /vspec:new 引用的原始材料文件：PRD/需求文档/流程说明/字段口径/模板/协议/截图/样例数据等）
 │  │  └─ file_list.md                     # upgrade 入口清单（/vspec:upgrade 读取/生成）
 │  ├─ dependencies/                       # 外部依赖系统文档库（已有依赖系统说明，推荐）
 │  ├─ refine/                             # 补充/澄清输入（/vspec:refine 读取）

package/docs/zh-CN/workflows.md

@@ -5,8 +5,38 @@
 - 输入原始需求
 - 回答开放问题（关键假设、范围、规则、依赖）
 - 在 `/specs/` 下得到第一版产物：角色、术语、流程、场景、功能清单、依赖、问题清单
+- 提问回答（HTML 方式，推荐）：
+  - `/vspec:new` 会生成交互式问答页：`/specs/background/question_and_answer.html`
+  - 打开该 HTML 后，分别选择：
+    - `/specs/background/original.md`
+    - `/specs/background/questions.md`
+  - 在页面里用表单回答问题并保存回写（浏览器支持写入时可直接覆盖写回；否则下载后手动替换）
 
-### 2. 详细规格（`/vspec:detail`）
+### 2. 补充问题（`/vspec:more-q`）
+
+- 适用场景：问题清单还不够，或需求发生变更，需要补充更多“待确认问题”
+- 输入：`/specs/background/questions.md`（不存在则先 `/vspec:new`）
+- 输出：追加写入 `/specs/background/questions.md`（新增问题 + 回答指引）
+- 提问回答（HTML 方式，推荐）：
+  - `/vspec:more-q` 会更新/生成交互式问答页：`/specs/background/question_and_answer.html`
+  - 打开该 HTML，用表单继续回答新增问题，保存回写后再执行 `/vspec:refine-q`
+
+### 3. 合并问答（`/vspec:refine-q`）
+
+- 适用场景：业务已在 `/specs/background/questions.md` 填写答案，需要合并回需求并形成新口径
+- 输入：`/specs/background/questions.md`（已回答项）+ `original.md`
+- 输出：追加更新到 `/specs/background/original.md`（采纳项 + 变更清单 + 最新口径）
+
+### 4. 应用补充材料（`/vspec:refine`）
+
+- 适用场景：实现中出现新信息/澄清，需要更新需求口径并同步更新详情与原型，且保留可追溯性
+- 输入：
+  - 默认：`/docs/refine/*`（优先 `file_list.md`）
+  - 可选：命令参数指定文件/目录
+- 前置条件：`/specs/details/` 必须存在且非空
+- 输出：追加更新到 `original.md` + 更新受影响的 `/specs/details/` 与 `/specs/prototypes/`
+
+### 5. 详细规格（`/vspec:detail`）
 
 - 以 `/specs/functions/*` 为输入，在 `/specs/details/<function_slug>/` 下生成单功能规格
 - 目标：把“需求”转成可实现的设计输入：
@@ -14,8 +44,16 @@
   - 加载/交互/校验矩阵
   - 提交后检查/处理/跳转
   - 日志/通知矩阵、MQ、导入导出、定时任务
+- 额外输出：`/specs/details/index.html`（左侧目录树 + 右侧 Markdown 渲染阅读；PlantUML 渲染为图）
+
+### 6. Word 汇总文档（`/vspec:doc`）
 
-### 3. 方案验证（`/vspec:verify`）
+- 适用场景：把当前已有的规格产物汇总成可交付的 Word 文档，用于评审/流转/归档
+- 输入：现有 `/specs/**` 产物（original/functions/details/models/flows 等，存在则读取）
+- 输出：`/docs/current/requirement_detail.docx`（Word 可打开的 `.docx`，HTML 单文件）
+- 提示：该 Word 只是汇总，不建议直接修改；修改应回到对应的 markdown 文件，修改后重新 `/vspec:doc` 生成新版本
+
+### 7. 方案验证（`/vspec:verify`）
 
 - 前置条件：`/specs/details/` 存在且非空
 - 基于 `/specs/`（functions + details + roles）生成：
@@ -31,29 +69,45 @@
   - `/vspec:proto-execute`：执行流页面（包含移动端 `/m/*`）
   - `/vspec:proto-crud`：配置/主数据 CRUD 管理页
 
-### 4. 验收用例（`/vspec:accept`）
+### 8. 验收用例（`/vspec:accept`）
 
 - 在 `/specs/acceptance/` 下生成验收用例
 - 目标：定义验收口径与覆盖范围（主流程、异常、边界、RBAC、数据权限）
 
-### 5. 自动化测试（`/vspec:append-test`）
+### 9. 自动化测试（`/vspec:append-test`）
 
 - 读取验收用例与仓库现有测试技术栈
 - 生成最小可运行的一组 E2E/API/单测
 - Note：该步骤只生成/补齐测试代码以提升覆盖率，不负责执行测试命令（例如 mvn test）。
 
-### 6. 集成实现（`/vspec:impl`）
+### 10. 集成实现（`/vspec:impl`）
 
 - 读取 specs、details、models、dependencies
 - 按仓库约定生成后端 + 前端联调代码（API 合同 → 后端实现 → 前端对接）
 
-### 7. 估算与排期（`/vspec:plan`）
+### 11. 质量检查（`/vspec:qc`）
+
+- 对 `/specs/` 下产物做质量检查
+- 输出：`/specs/qc_report.md`
+
+### 12. 估算与排期（`/vspec:plan`）
 
 - 把功能与场景拆成用户故事，估算工作量，并生成迭代排期
 - 输出：
   - `/specs/plan/plan_estimate.md`
   - `/specs/plan/plan_schedule.html`
 
+### 13. 升级/改造（`/vspec:upgrade`）
+
+- 适用场景：基于遗留系统材料做“升级/重构/迁移”分析，继承必要部分并生成新规格
+- 入口清单：`/docs/current/file_list.md`（缺失时生成模板）
+- 输出：生成/更新 `/specs/`（沿用 `/vspec:new` 结构）+ 同步技术选型到 `/scheme.yaml`
+
+### 14. MRD 分析包（`/vspec:mrd`）
+
+- 输出市场/竞品/用户/产品设计分析包
+- 输出目录：`/docs/market/`（market/competitors/users/product_design）
+
 ## 独立使用质量规范（不依赖 `/vspec:qc`）
 
 内置质检标准文件位于（任选其一，取你当前环境中存在的路径）：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "visual-spec",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "description": "AI skill: visual-spec (/vspec:* commands) for requirement analysis, prototyping, detailing, testing, and planning.",
   "license": "MIT",
   "type": "commonjs",
@@ -23,6 +23,7 @@
     "skills/visual-spec/prompts/vspec_new/",
     "skills/visual-spec/prompts/vspec_more_q/",
     "skills/visual-spec/prompts/vspec_mrd/",
+    "skills/visual-spec/prompts/vspec_doc/",
     "skills/visual-spec/prompts/vspec_plan/",
     "skills/visual-spec/prompts/vspec_qc/",
     "skills/visual-spec/prompts/vspec_refine/",

package/skills/visual-spec/SKILL-ja-JP.md

@@ -47,8 +47,9 @@ Flow:
 2. 入力を raw requirement として扱う
 3. `prompts/vspec_new/background.md` を読み込み、要件分析と背景補完を実行
 4. `/specs/background/original.md` に書き込み
-5. Open Questions/要確認事項の回答を促す（自己回答でも、AI の回答案→ユーザー確認でも可）
-6. 以降、`prompts/vspec_new/*` に従い `/specs/` 配下の成果物を生成
+5. `/specs/background/question_and_answer.html` を生成（`prompts/vspec_new/question_and_answer.html` をそのままコピー）。このページで `original.md` / `questions.md` の質問に回答し、md に書き戻せるようにする。
+6. Open Questions/要確認事項の回答を促す（`/specs/background/question_and_answer.html` を開き、`/specs/background/original.md` を選択して回答・保存）。この時点で必ず停止して待機し、回答が揃うまで次のステップへ進まない（「続けて/继续/continue」等で回答完了を明示してもらう）。
+6. ユーザーの回答後（または「続けて/继续/continue」等で回答完了を明示した後）、`prompts/vspec_new/*` に従い `/specs/` 配下の成果物を生成
 
 ### `/vspec:refine`
 
@@ -83,7 +84,11 @@ Flow:
 
 ### `/vspec:detail`
 
-機能一覧に基づき要件詳細を展開します（`/specs/details/` に生成）。
+機能一覧に基づき要件詳細を展開します（`/specs/details/` に生成）。各ステップの種別（端=Web/Mobile/Web+Mobile/Backend/Job）を判定し、対応するロジック詳細を必ず生成します（ロジックを省略しない）。あわせて、Markdown/PlantUML をレンダリングできる閲覧用 `index.html` を `/specs/details/index.html` に生成します。
+
+### `/vspec:doc`
+
+要件成果物（`/specs/**`）を集約し、Word で直接開ける単一ファイルの Word 文書（HTML 形式の `.docx`）を `/docs/current/requirement_detail.docx` に生成します。
 
 ### `/vspec:verify`
 
@@ -107,7 +112,7 @@ Flow:
 
 ### `/vspec:upgrade`
 
-`/docs/` 配下の資料（legacy/current）に基づき、`/vspec:new` と同様の構造で `/specs/` を再生成/更新します。
+`/docs/` 配下の資料（legacy/current）に基づき、`/vspec:new` と同様の構造で `/specs/` を再生成/更新します。あわせて、`/docs/legacy/` 配下（サブディレクトリ含む）を再帰的にスキャンし、原資料として取り込みます。
 
 ### `/vspec:plan`
 
@@ -137,6 +142,7 @@ MRD（市場/競合/ユーザー/プロダクト設計）分析パックを生
 - `prompts/vspec_mrd/mrd.md`
 - `prompts/vspec_refine/refine.md`
 - `prompts/vspec_refine/refine_q.md`
+- `prompts/vspec_doc/doc.md`
 - `prompts/vspec_verify/model.md`
 - `prompts/vspec_verify/prototype.md`
 - `prompts/vspec_verify/validation.md`
@@ -144,6 +150,8 @@ MRD（市場/競合/ユーザー/プロダクト設計）分析パックを生
 - `prompts/vspec_detail/data_permission.md`
 - `prompts/vspec_detail/page_load.md`
 - `prompts/vspec_detail/interaction.md`
+- `prompts/vspec_detail/index.md`
+- `prompts/vspec_detail/index.html`
 - `prompts/vspec_detail/timeline.md`
 - `prompts/vspec_detail/formula.md`
 - `prompts/vspec_detail/expression_tree.md`
@@ -154,6 +162,8 @@ MRD（市場/競合/ユーザー/プロダクト設計）分析パックを生
 - `prompts/vspec_detail/post_submit_processing.md`
 - `prompts/vspec_detail/post_submit_navigation.md`
 - `prompts/vspec_detail/mq.md`
+- `prompts/vspec_detail/service_logic.md`
+- `prompts/vspec_detail/job_logic.md`
 - `prompts/vspec_detail/logging_matrix.md`
 - `prompts/vspec_detail/notification_matrix.md`
 - `prompts/vspec_detail/nfp.md`

package/skills/visual-spec/SKILL-zh-CN.md

@@ -42,7 +42,8 @@ description: "将原始需求分析为可评审的视觉规格，并生成相关
 3. 加载提示词文件 `prompts/vspec_new/background.md`。
 4. 使用该提示词分析需求并扩展业务背景。
 5. 将原始需求与背景分析写入 `/specs/background/original.md`。
-6. 提示用户回答“待确认问题/Open Questions/要確認事項”章节中的问题（按所选语言对应章节标题）。
+5.5 同时生成交互式问答页面：`/specs/background/question_and_answer.html`（从 `prompts/vspec_new/question_and_answer.html` 复制，单文件 HTML，内联 CSS/JS），用于回答 `original.md` 与 `questions.md` 并回写。
+6. 提示用户回答“待确认问题/Open Questions/要確認事項”章节中的问题（按所选语言对应章节标题），并要求通过 `/specs/background/question_and_answer.html` 完成（在页面中选择 `/specs/background/original.md`，填写并保存回写）。然后必须暂停并等待用户回复“继续/continue/続けて”。不得继续加载后续提示词或生成后续产物（不得越过问答直接进入 stakeholders/roles/terms 等阶段）。用户明确回复后再进入下一步。
 7. 用户回复后，加载 `prompts/vspec_new/stakeholders.md` 分析干系人。
 8. 将干系人结果写入 `/specs/background/stakeholder.md`（markdown 表格）。
 9. 加载 `prompts/vspec_new/roles.md` 分析系统用户角色（直接用户）及其工作任务。
@@ -118,6 +119,10 @@ description: "将原始需求分析为可评审的视觉规格，并生成相关
 2. 尽可能读取可用的上下文产物：`/specs/background/*`、`/specs/flows/*.puml`、`/specs/background/scenario_details/`、`/specs/background/roles.md`，以及已有的 `/specs/models/*.md`（若存在）。
 3. 对每个功能（页面或非页面任务），先判断哪些详情产物真正涉及，再只生成涉及的部分；对不涉及的部分不得生成空文档。
    - 覆盖性要求（必须）：对遍历到的每个功能点，必须至少产出 `rbac.md` 与 `data_permission.md`（按规则写入对应路径）；若因信息不足无法产出，必须输出可见错误并停止，而不是静默跳过。
+   - Step 类型要求（必须）：你必须从功能行的“说明”中解析 step 的类型（端=Web/Mobile/Web+Mobile/Backend/Job），并生成对应的逻辑细节文档；不得跳过逻辑部分：
+     - 对 `端=Web` / `端=Mobile` / `端=Web+Mobile`：必须生成 `page_load.md` 与 `interaction.md`（页面加载 + 交互逻辑是必需的）。
+     - 对 `端=Backend`：必须生成 `service_logic.md`（服务端逻辑：输入输出、规则、状态、接口/事件、错误与幂等/一致性）。
+     - 对 `端=Job`：必须生成 `job_logic.md`（作业逻辑：触发/频率、数据范围、重试/补偿、可观测性、失败处理）。
    - 始终生成基础文档：
      - `rbac.md`：RBAC 权限下沉到页面区域与控件级。
      - `data_permission.md`：数据权限规则与范围。
@@ -149,6 +154,32 @@ description: "将原始需求分析为可评审的视觉规格，并生成相关
 4. 仅写入生成的（涉及的）详情文档：
    - 单功能：`/specs/details/<module_slug>/<logic_type>/<function_slug>.(md|html)`
    - 模块级：`/specs/details/<module_slug>/<logic_type>/<module_slug>.(md|html)`
+5. 加载 `prompts/vspec_detail/index.md` 生成单页阅读入口：`/specs/details/index.html`
+   - 左侧：按 `/specs/details/` 目录结构生成目录树
+   - 右侧：以 Markdown 渲染方式阅读详情内容
+   - 遇到 PlantUML 必须渲染成图（不得展示源码文本）
+
+### `/vspec:doc`
+
+用于生成“需求详细文档”的 Word 文件（Word 可打开的单文件 `.doc`，HTML 格式），并写入到 `/docs/current/` 目录下。
+
+语言：
+- 读取 `/scheme.yaml` 的 `selected.language`（支持 `en`、`zh`、`ja`；若缺失/非法则按 `en` 处理；`zh-CN` 视为 `zh` 的别名）。
+- 生成的 Word 文档必须统一使用所选语言（标题、章节名、字段名、表头与说明文字）。
+
+流程：
+1. 确保 `/docs/current/` 存在。
+2. 尽可能读取已有产物作为输入：
+   - 需求口径：`/specs/background/original.md`
+   - 功能清单：`/specs/functions/*`
+   - 需求详情：`/specs/details/**`
+   - 角色与权限：`/specs/background/roles.md`、`/specs/details/**/rbac.md`
+   - 数据权限：`/specs/details/**/data_permission.md`
+   - 场景与流程：`/specs/background/scenarios.md`、`/specs/background/scenario_details/**`、`/specs/flows/*.puml`
+   - 外部依赖：`/specs/background/dependencies.md`
+   - 数据模型：`/specs/models/*.md`
+3. 加载 `prompts/vspec_doc/doc.md`，生成 Word 可打开的单文件 HTML 文档。
+4. 将输出写入：`/docs/current/requirement_detail.docx`。
 
 ### `/vspec:verify`
 
@@ -242,7 +273,7 @@ Note：Pro 版支持更广泛的质量检测能力（例如更完整的原型/
 
 流程：
 1. 确保 `/docs/current/file_list.md` 入口文件存在；若缺失则按模板生成。
-2. 读取 `/docs/current/file_list.md`，再按顺序读取 `/docs/` 下列出的输入（通常 `/docs/legacy/*`、`/docs/current/*`，可选 `/docs/templates/*`、`/docs/texts/*`、`/docs/assets/*`）并抽取结构化信息（功能、依赖、UI 风格、角色/权限、技术规格）。
+2. 读取 `/docs/current/file_list.md`，再按顺序读取 `/docs/` 下列出的输入（通常 `/docs/legacy/*`、`/docs/current/*`，可选 `/docs/templates/*`、`/docs/texts/*`、`/docs/assets/*`）并抽取结构化信息（功能、依赖、UI 风格、角色/权限、技术规格）。另外，必须递归扫描 `/docs/legacy/` 及其子目录下的文档，作为原始输入资料（即使尚未被 `file_list.md` 显式列出）；当发现 `file_list.md` 未覆盖的 legacy 文件时，先把它们追加写入 `/docs/current/file_list.md`，再读取并参与抽取。
 3. 若 `/specs/background/original.md` 已存在，则将其视为当前需求口径并作为 diff 基线（继承/新增/变更/废弃）。
 4. 加载 `prompts/vspec_upgrade/upgrade.md`，按 `/vspec:new` 产物约定生成/更新 `/specs/`。
 5. 将抽取到的技术规格同步到 `/scheme.yaml`，供 `/vspec:verify` 与 `/vspec:impl` 使用。
@@ -294,6 +325,7 @@ Note：Pro 版支持更广泛的质量检测能力（例如更完整的原型/
 - `prompts/vspec_new/questions.md`：生成 `/specs/background/questions.md` 的提示词。
 - `prompts/vspec_refine/refine.md`：`/vspec:refine` 使用的提示词。
 - `prompts/vspec_refine/refine_q.md`：`/vspec:refine-q` 使用的提示词。
+- `prompts/vspec_doc/doc.md`：`/vspec:doc` 使用的提示词，用于生成 Word 可打开的 `.docx`（HTML）需求详细文档到 `/docs/current/`。
 - `prompts/vspec_verify/model.md`：生成 `/specs/models/*.md` 的提示词。
 - `prompts/vspec_verify/prototype.md`：生成按选栈的可运行原型工程（`/specs/prototypes/`）的提示词（必须遵循 `scheme.yaml`）。
 - `prompts/vspec_verify/validation.md`：生成 `scenario.html` 场景评审页的提示词。
@@ -301,6 +333,8 @@ Note：Pro 版支持更广泛的质量检测能力（例如更完整的原型/
 - `prompts/vspec_detail/data_permission.md`：生成数据权限详情的提示词。
 - `prompts/vspec_detail/page_load.md`：生成页面加载逻辑的提示词。
 - `prompts/vspec_detail/interaction.md`：生成页面交互逻辑的提示词。
+- `prompts/vspec_detail/index.md`：生成 `/specs/details/index.html` 单页阅读入口（Markdown/PlantUML 渲染）的提示词。
+- `prompts/vspec_detail/index.html`：`/specs/details/index.html` 的固定 HTML 模板（用于稳定生成：目录树 + Markdown 渲染）。
 - `prompts/vspec_detail/timeline.md`：生成时间轴 HTML 的提示词。
 - `prompts/vspec_detail/formula.md`：生成公式说明的提示词。
 - `prompts/vspec_detail/expression_tree.md`：生成表达式树 HTML 的提示词。
@@ -311,6 +345,8 @@ Note：Pro 版支持更广泛的质量检测能力（例如更完整的原型/
 - `prompts/vspec_detail/post_submit_processing.md`：生成提交后处理的提示词。
 - `prompts/vspec_detail/post_submit_navigation.md`：生成提交后跳转规则的提示词。
 - `prompts/vspec_detail/mq.md`：生成 MQ 设计的提示词。
+- `prompts/vspec_detail/service_logic.md`：生成 `端=Backend` 功能点的服务端逻辑细节（service logic）的提示词。
+- `prompts/vspec_detail/job_logic.md`：生成 `端=Job` 功能点的作业逻辑细节（job logic）的提示词。
 - `prompts/vspec_detail/logging_matrix.md`：生成日志矩阵的提示词。
 - `prompts/vspec_detail/notification_matrix.md`：生成通知矩阵的提示词。
 - `prompts/vspec_detail/nfp.md`：生成非功能需求的提示词。