visual-spec 0.1.8 → 0.1.10

package/docs/zh-CN/ai-platform-installation.md

@@ -0,0 +1,39 @@
+# 多 AI 平台安装指南
+
+推荐使用 skills.sh 的官方安装器（skills CLI）进行安装：同一套命令可面向不同 AI 平台（Trae / Claude Code / Cursor / GitHub Copilot 等）把 Skill 安装到对应的 skills 目录。
+
+## 方式一：skills.sh（推荐）
+
+安装器会自动检测本机支持的 agent，并提示选择安装位置与范围（项目级或全局）。
+
+```bash
+npx skills add visual-req/visual-spec --skill visual-spec
+```
+
+指定安装到某个 AI 平台（示例）：
+
+```bash
+# Trae（项目级）
+npx skills add visual-req/visual-spec --skill visual-spec -a trae
+
+# Claude Code（项目级）
+npx skills add visual-req/visual-spec --skill visual-spec -a claude-code
+
+# Cursor（项目级）
+npx skills add visual-req/visual-spec --skill visual-spec -a cursor
+
+# GitHub Copilot（项目级）
+npx skills add visual-req/visual-spec --skill visual-spec -a github-copilot
+```
+
+全局安装（对当前用户所有项目生效）：
+
+```bash
+npx skills add visual-req/visual-spec --skill visual-spec -g
+```
+
+查看该仓库包含的 skills：
+
+```bash
+npx skills add visual-req/visual-spec --list
+```

package/docs/zh-CN/commands.md

@@ -5,20 +5,23 @@
 | `/vspec:new` | 从原始需求生成第一版规格产物 | 原始需求文本 + 交互式问答 | `/specs/`（original、stakeholders、roles、terms、flows、scenarios、scenario_details、dependencies、functions、questions）+ 初始化 `/docs/*` 输入归档目录 |
 | `/vspec:refine` | 应用补充/澄清材料，并同步更新详情与原型 | `/docs/refine/*`（或命令参数）+ `/specs/background/original.md` + 前置条件 `/specs/details/` | 追加更新到 `/specs/background/original.md`（变更清单 + 最新口径）+ 更新受影响的 `/specs/details/` 与 `/specs/prototypes/` |
 | `/vspec:refine-q` | 将已回答的问题合并回需求并形成新口径 | `/specs/background/original.md` + `/specs/background/questions.md` | 追加到 `/specs/background/original.md`（采纳项 + 变更清单 + 最新口径） |
+| `/vspec:more-q` | 追加更多“待确认问题”到 questions 清单 | `/specs/background/original.md` + `/specs/background/questions.md` | 追加写入 `/specs/background/questions.md`（新增问题 + 回答指引） |
 | `/vspec:detail` | 展开到“可实现”的单功能详细规格 | `/specs/functions/*` + 支撑产物（background/flows/roles；models 若已存在） | `/specs/details/<function_slug>/*`（RBAC、交互、校验、日志、通知、MQ、导入导出、定时任务等） |
 | `/vspec:verify` | 快速验证：生成模型与可运行原型用于评审 | 现有 `/specs/` 产物（functions + details + roles） | `/specs/models/*.md`、`/specs/prototypes/`（按 `scheme.yaml` 选栈生成可运行原型 + `scenario.html` 评审页） |
 | `/vspec:accept` | 生成验收用例 | functions/scenarios/details/roles/models | `/specs/acceptance/<function_slug>/acceptance_cases.md`、`/specs/acceptance/index.md` |
 | `/vspec:append-test` | 生成自动化测试代码 | 验收用例 + 仓库测试技术栈 | 写入既有测试目录或 `/tests/` |
 | `/vspec:impl` | 生成后端 + 前端联调实现代码 | specs/details/models/dependencies | 写入集成实现代码（API 合同、后端、前端对接） |
 | `/vspec:upgrade` | 基于遗留材料做升级/重构分析并生成新规格 | `/docs/current/file_list.md` + `/docs/legacy/*`（可选 templates/texts/assets）+ 既有 `/specs/background/original.md`（可选） | 生成/更新 `/specs/`（沿用 `/vspec:new` 结构）+ 同步技术选型到 `/scheme.yaml` |
-| `/vspec:qc` | 对 `/specs/` 产物做质量检查 | 内置标准 + 可选 `quality_standard.md` + `/specs/` | `/specs/qc_report.md` |
+| `/vspec:qc` | 对 `/specs/` 产物做质量检查 | 内置标准 + 可选 `domain_quality_standard.md` + 可选 `quality_standard.md` + `/specs/` | `/specs/qc_report.md` |
 | `/vspec:plan` | 估算与排期 | functions/roles/flows/dependencies/details | `/specs/plan/plan_estimate.md`、`/specs/plan/plan_schedule.html` |
+| `/vspec:mrd` | 生成 MRD：市场/竞品/用户/产品设计 | `/specs/background/*` + `/specs/flows/*` + `/specs/functions/*`（如有） | `/docs/market/*.md`（market/competitors/users/product_design） |
 
 ## `/vspec:new`
 
 - 适用场景：刚拿到需求且信息不完整，需要快速形成“可评审的共同语言”
 - 关键输出：干系人、角色、术语、流程、场景、功能清单、开放问题
-- 目录初始化：创建 `/docs/` 及其子目录（legacy/current/change/refine/templates/texts/assets）用于输入归档与后续命令使用
+- 目录初始化：创建 `/docs/` 及其子目录（legacy/current/refine/templates/texts/assets）用于输入归档与后续命令使用
+- 提示：生成“开放问题/待确认问题”后，你可以把回答工作委托给 AI 先给出建议答案，你只需要逐条确认/修改即可（推荐做法：先让 AI 代答一版，再由业务确认口径）
 
 ## `/vspec:refine`
 
@@ -36,6 +39,15 @@
 - 适用场景：业务已在 `/specs/background/questions.md` 填写答案，需要合并回需求并形成新口径
 - 关键输出：采纳的 Q&A 项 + 变更清单 + 最新口径
 
+## `/vspec:more-q`
+
+- 适用场景：问题清单还不够，或需求发生变更，需要补充更多“待确认问题”
+- 关键输出：追加到 `/specs/background/questions.md` 末尾的新问题条目（延续编号、不重复），并提供“回答指引”
+- 推荐用法：
+  - 先执行 `/vspec:more-q` 生成/补充问题
+  - 业务按编号逐条填写问题的“回答/回答者/回答时间/状态”
+  - 再执行 `/vspec:refine-q` 合并答案进入 `original.md`
+
 ## `/vspec:detail`
 
 - 适用场景：在设计/实现前，需要把每个功能点展开到“可实现”的规格粒度

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

@@ -4,39 +4,22 @@
 
 ### 1. 安装
 
-先全局安装 npm 包，再把 Skill 安装到 AI 编辑器的配置目录：
+把 Skill 安装到 AI 编辑器的配置目录：
 
 - 安装与校验：`installation.md`
 
-安装/更新（npm）：
+安装/更新（skills.sh）：
 
 ```bash
-npm install -g visual-spec@latest
-```
-
-安装/更新（pnpm）：
-
-```bash
-pnpm add -g visual-spec@latest
-```
-
-安装/更新（yarn）：
-
-Yarn Classic：
-
-```bash
-yarn global add visual-spec@latest
-```
-
-Yarn Berry（v2+）：
-
-```bash
-yarn dlx -p visual-spec@latest vspec
+npx skills add visual-req/visual-spec --skill visual-spec
 ```
 
 ### 2. 推荐流程
 
 - 初始规格：`/vspec:new`
+  - 可选语言：
+    - 单语言：`/vspec:new lang=zh`（或 `lang=en`、`lang=ja`），会把 `/scheme.yaml` 的 `selected.language` 设为该值，并让后续文档产物全程按该语言输出
+    - 多语言（原型可切换）：`/vspec:new lang=zh,en`，文档默认输出 `zh`，并把 `/scheme.yaml` 的 `selected.languages` 设为可切换语言集合
   - 执行中会先生成需求口径文件（`/specs/background/original.md`），并在该步骤提出若干澄清问题
   - 你需要先在对话中回答这些问题，然后输入“继续”才能完成 `/vspec:new` 全流程（这些澄清回答不写入 `questions.md`）
   - 执行过程中还会生成开放问题清单（`/specs/background/questions.md`），用于后续合并
@@ -51,7 +34,7 @@ yarn dlx -p visual-spec@latest vspec
 
 ### 3. 关键目录
 
-- `/docs/`：输入归档（legacy/current/change/refine/templates/texts/assets）
+- `/docs/`：输入归档（legacy/current/refine/templates/texts/assets）
 - `/specs/`：生成产物（background/details/models/prototypes/acceptance 等）
 - `/scheme.yaml`：技术栈与包管理器选择（原型与实现必须遵循）
 
@@ -72,11 +55,6 @@ yarn dlx -p visual-spec@latest vspec
 - 运行：`/vspec:refine`
 - 结果：向 `/specs/background/original.md` 追加更新，并同步更新受影响的 `/specs/details/` 与 `/specs/prototypes/`
 
-#### 变更（`change`）
-
-- 把变更材料放到 `/docs/change/`（可选 `file_list.md`）
-- 结果：做影响分析并更新产物（优先 `/specs/details/<module_slug>/`），同时更新变更日志
-
 #### 升级/重构（`upgrade`）
 
 - 在 `/docs/current/file_list.md` 中列出输入材料（遗留系统在 `/docs/legacy/`，新增输入在 `/docs/current/`）

package/docs/zh-CN/installation.md

@@ -1,53 +1,18 @@
 ## 安装到支持 Skill 的 AI 编辑器
 
-本包使用脚本把内置的 Skill 目录复制到你的 AI 编辑器配置目录（Trae / Qwen / Kiro 等）。不同编辑器的配置路径可能不同，但安装逻辑一致：把 `visual-spec-skill` 安装到目标目录的 `skills/` 下。
+推荐使用 skills.sh 的官方安装器（skills CLI）安装到支持 Skill 的 AI 编辑器（Trae / Qwen / Kiro 等）。安装器会自动识别可用的 agent，并把 `visual-spec` 安装到对应的 `skills/` 目录。
 
 ### 前置条件
 
 - Node.js >= 14
 
-### 安装/更新（npm）
+### 安装/更新（推荐：skills.sh）
 
 ```bash
-npm install -g visual-spec@latest
-```
-
-### 安装/更新（pnpm）
-
-```bash
-pnpm add -g visual-spec@latest
-```
-
-### 安装/更新（yarn）
-
-Yarn Classic：
-
-```bash
-yarn global add visual-spec@latest
-```
-
-Yarn Berry（v2+）：
-
-```bash
-yarn dlx -p visual-spec@latest vspec
-```
-
-### 指定安装目录（`--target-skills-dir`）
-
-默认情况下，安装脚本会把 Skill 安装到当前目录的 `.trae/skills/visual-spec-skill`。如果你需要安装到自定义的 `skills/` 目录（例如统一放在某个编辑器配置目录），可以在安装后执行：
-
-```bash
-vspec --target-skills-dir /path/to/skills --force
-```
-
-说明：
-- `--target-skills-dir` 传入的是“skills 目录”，脚本会自动追加子目录 `visual-spec-skill/`
-- 你也可以使用 `--target-skill-dir` 传入完整目标目录（包含 `visual-spec-skill`）：
-
-```bash
-vspec --target-skill-dir /path/to/skills/visual-spec-skill --force
+npx skills add visual-req/visual-spec --skill visual-spec
 ```
 
 ### 下一步
 
 - 快速开始：`getting-started.md`
+- 多 AI 平台安装指南：`ai-platform-installation.md`

package/docs/zh-CN/quality_check.md

@@ -0,0 +1,32 @@
+## 需求质量检查（独立使用）
+
+本节说明如何不依赖 `/vspec:qc`，单独利用内置的质量标准文件，对“Word/Markdown/文档库”等任意格式的需求文档进行质量扫描，并生成质量问题表格。
+
+### 准备
+
+- 质量标准文件路径（任选其一，取当前环境存在者）：
+  - Skill 根目录：`/prompts/vspec_qc/quality_standard.md`
+  - 源码路径：`skills/visual-spec/prompts/vspec_qc/quality_standard.md`
+- 你的需求文档（PRD、功能说明、规格等），支持 Word/PDF/Markdown 等
+
+### 使用方式（以 DeepSeek 聊天式 AI 为例）
+
+1. 在聊天窗口上传两份文件：
+   - `quality_standard.md`（质量标准）
+   - 你的需求文档（Word/PDF/Markdown 等）
+2. 在输入框键入：
+
+   请按照质量标准对需求文档进行质量检查，并生成质量检查结果的表格。
+
+3. 若需要结构化表格，可补充表头要求，例如：
+   - 编号
+   - 问题分类/标题
+   - 是否通过（是/否/部分）
+   - 问题摘要
+   - 涉及位置（章节/段落/页码）
+   - 修复建议
+
+### 建议
+
+- 对于“上下限、时间口径、公式精度、权限与数据权限、外部依赖失败策略”等容易遗漏的部分，可在提问中强调“请重点覆盖边界/异常/幂等/回滚/审计/对账”等关键维度
+- 如果发现高频问题，可将其沉淀到你项目根目录的 `domain_quality_standard.md`，作为领域补充标准，供 `/vspec:qc` 合并使用

package/docs/zh-CN/scheme.example.yaml

@@ -7,7 +7,8 @@ selected:
   prototype_backend_stack: java17_springboot3
   prototype_database: mysql8
   package_manager: npm
-  language: zh-CN
+  language: en # 文档默认语言：en | zh | ja
+  languages: [en] # 可选：原型可切换语言集合，例如 [zh, en]
 
 prototype_options:
   calendar_view:

package/docs/zh-CN/structure.md

@@ -13,8 +13,7 @@ Skill 会按命令阶段逐步在 `/specs/` 下生成产物，并维护少量项
 │  ├─ legacy/                             # 遗留系统材料（功能、权限、交互、API 等）
 │  ├─ current/                            # 本次迭代新增/补充材料（目标、差异、流程、UI 约束等）
 │  │  └─ file_list.md                     # upgrade 入口清单（/vspec:upgrade 读取/生成）
-│  ├─ change/                             # 变更输入归档（可选）
-│  │  └─ file_list.md                     # 可选：有序输入清单
+│  ├─ dependencies/                       # 外部依赖系统文档库（已有依赖系统说明，推荐）
 │  ├─ refine/                             # 补充/澄清输入（/vspec:refine 读取）
 │  │  └─ file_list.md                     # 可选：有序输入清单
 │  ├─ templates/                          # 模板（PRD/文案/UI/表格模板，可选）
@@ -65,7 +64,7 @@ Skill 会按命令阶段逐步在 `/specs/` 下生成产物，并维护少量项
 ```
 
 说明：
-- `docs/`：归档业务输入与交付对齐材料。建议使用 `legacy/current/change/refine/templates/texts/assets` 等子目录，并在文件名中包含来源/版本信息。
+- `docs/`：归档业务输入与交付对齐材料。建议使用 `legacy/current/dependencies/refine/templates/texts/assets` 等子目录，并在文件名中包含来源/版本信息。
 - `scheme.yaml`：选择 `/vspec:verify` 与 `/vspec:impl` 使用的技术栈与选项。读取顺序为项目根目录的 `scheme.yaml` 优先，其次 `/specs/scheme.yaml`。若都不存在则生成默认 `scheme.yaml`。
 
 下一步：

package/docs/zh-CN/workflows.md

@@ -54,8 +54,32 @@
   - `/specs/plan/plan_estimate.md`
   - `/specs/plan/plan_schedule.html`
 
-## 安装（npm）
+## 独立使用质量规范（不依赖 `/vspec:qc`）
 
-- 推荐在目标项目根目录安装：`npm install <git-url>`
-- 安装后 Skill 会被复制到：`<your-project>/.trae/skills/visual-spec-skill/`
-- 需要时可手动安装：`npx vspec --force`
+内置质检标准文件位于（任选其一，取你当前环境中存在的路径）：
+- Skill 根目录下：`/prompts/vspec_qc/quality_standard.md`
+- 本仓库源码路径：`skills/visual-spec/prompts/vspec_qc/quality_standard.md`
+
+你可以把它作为“通用需求质检标准”，独立用于检查其他方式写出来的需求文档（不要求必须由 `/vspec:*` 生成）。
+
+以 DeepSeek 聊天窗口为例（其他大模型/聊天产品同理）：
+1. 上传 2 份文件：
+   - `quality_standard.md`（质检标准）
+   - 你的需求文档（例如 PRD/需求说明/功能规格）
+2. 在聊天窗口输入以下指令：
+
+   请按照质量标准对需求文档进行质量检查，并生成质量检查结果的表格。
+
+建议输出表格列（可选）：
+- 检查项编号
+- 检查项标题
+- 是否通过（是/否/部分）
+- 发现的问题摘要
+- 涉及的文档位置（章节/段落）
+- 修复建议
+
+## 安装（skills.sh）
+
+```bash
+npx skills add visual-req/visual-spec --skill visual-spec
+```

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "visual-spec",
-  "version": "0.1.8",
-  "description": "AI skill: visual-spec-skill (/vspec:* commands) for requirement analysis, prototyping, detailing, testing, and planning.",
+  "version": "0.1.10",
+  "description": "AI skill: visual-spec (/vspec:* commands) for requirement analysis, prototyping, detailing, testing, and planning.",
   "license": "MIT",
   "type": "commonjs",
   "bin": {
@@ -10,21 +10,25 @@
   "scripts": {
     "postinstall": "node scripts/postinstall.cjs",
     "install-skill": "node scripts/postinstall.cjs --force",
-    "dry-run": "node scripts/postinstall.cjs --dry-run"
+    "dry-run": "node scripts/postinstall.cjs --dry-run",
+    "build-skill": "node scripts/build_skill.cjs"
   },
   "files": [
-    "skills/visual-spec-skill/SKILL.md",
-    "skills/visual-spec-skill/SKILL-zh-CN.md",
-    "skills/visual-spec-skill/prompts/vspec_accept/",
-    "skills/visual-spec-skill/prompts/vspec_detail/",
-    "skills/visual-spec-skill/prompts/vspec_impl/",
-    "skills/visual-spec-skill/prompts/vspec_new/",
-    "skills/visual-spec-skill/prompts/vspec_plan/",
-    "skills/visual-spec-skill/prompts/vspec_qc/",
-    "skills/visual-spec-skill/prompts/vspec_refine/",
-    "skills/visual-spec-skill/prompts/vspec_test/",
-    "skills/visual-spec-skill/prompts/vspec_upgrade/",
-    "skills/visual-spec-skill/prompts/vspec_verify/",
+    "skills/visual-spec/SKILL.md",
+    "skills/visual-spec/SKILL-zh-CN.md",
+    "skills/visual-spec/SKILL-ja-JP.md",
+    "skills/visual-spec/prompts/vspec_accept/",
+    "skills/visual-spec/prompts/vspec_detail/",
+    "skills/visual-spec/prompts/vspec_impl/",
+    "skills/visual-spec/prompts/vspec_new/",
+    "skills/visual-spec/prompts/vspec_more_q/",
+    "skills/visual-spec/prompts/vspec_mrd/",
+    "skills/visual-spec/prompts/vspec_plan/",
+    "skills/visual-spec/prompts/vspec_qc/",
+    "skills/visual-spec/prompts/vspec_refine/",
+    "skills/visual-spec/prompts/vspec_test/",
+    "skills/visual-spec/prompts/vspec_upgrade/",
+    "skills/visual-spec/prompts/vspec_verify/",
     "bin/",
     "docs/",
     "scripts/",

package/scripts/build_skill.cjs

@@ -0,0 +1,56 @@
+const { spawnSync } = require("node:child_process");
+const fs = require("node:fs");
+const path = require("node:path");
+
+function getRepoRoot() {
+  return path.resolve(__dirname, "..");
+}
+
+function readPackageJson(repoRoot) {
+  const packageJsonPath = path.join(repoRoot, "package.json");
+  return JSON.parse(fs.readFileSync(packageJsonPath, "utf-8"));
+}
+
+function ensureDir(dirPath) {
+  fs.mkdirSync(dirPath, { recursive: true });
+}
+
+function main() {
+  const repoRoot = getRepoRoot();
+  const pkg = readPackageJson(repoRoot);
+
+  const skillDir = path.join(repoRoot, "skills", "visual-spec");
+  if (!fs.existsSync(skillDir)) {
+    throw new Error(`Skill dir not found: ${skillDir}`);
+  }
+
+  const distDir = path.join(repoRoot, "dist");
+  ensureDir(distDir);
+
+  const version = pkg.version || "0.0.0";
+  const outputPath = path.join(distDir, `visual-spec-${version}.skill`);
+
+  if (fs.existsSync(outputPath)) {
+    fs.rmSync(outputPath);
+  }
+
+  const result = spawnSync(
+    "zip",
+    ["-r", outputPath, ".", "-x", "*.DS_Store", "-x", "*/.DS_Store"],
+    { cwd: skillDir, stdio: "inherit" }
+  );
+
+  if (result.error) {
+    throw new Error(
+      `Failed to run 'zip'. Please ensure 'zip' is installed and available in PATH. ${result.error.message}`
+    );
+  }
+
+  if (result.status !== 0) {
+    process.exit(result.status);
+  }
+
+  process.stdout.write(`${outputPath}\n`);
+}
+
+main();

package/scripts/postinstall.cjs

@@ -76,7 +76,7 @@ async function main() {
   const { dryRun, force, target, skillDir, skillsDir } = parseArgs(process.argv.slice(2));
 
   const packageRoot = path.resolve(__dirname, "..");
-  const sourceSkillDir = path.join(packageRoot, "skills", "visual-spec-skill");
+  const sourceSkillDir = path.join(packageRoot, "skills", "visual-spec");
   const initCwd = target || process.env.INIT_CWD || process.cwd();
   const resolvedSkillsDir =
     skillsDir && path.resolve(initCwd, skillsDir);
@@ -85,8 +85,8 @@ async function main() {
   const targetSkillDir =
     resolvedSkillDir ||
     (resolvedSkillsDir
-      ? path.join(resolvedSkillsDir, "visual-spec-skill")
-      : path.join(initCwd, ".trae", "skills", "visual-spec-skill"));
+      ? path.join(resolvedSkillsDir, "visual-spec")
+      : path.join(initCwd, ".trae", "skills", "visual-spec"));
 
   if (!(await pathExists(sourceSkillDir))) {
     throw new Error(`Skill source directory not found: ${sourceSkillDir}`);

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

@@ -0,0 +1,170 @@
+---
+name: "visual-spec"
+description: "生要件を分析して visual spec と成果物を生成します。ユーザーが /vspec:new で分析を開始する時、または /vspec:verify でモデル/プロトタイプを生成する時に利用します。"
+---
+
+# Visual Spec Skill（日本語）
+
+ユーザー入力に基づいて visual spec を分析し、短い要件メモをレビュー可能な構造化成果物へ変換します。
+
+## 利用シーン
+
+以下の状況で利用します：
+- ビジネス側の要件説明が非常に簡略で、仕様化に必要な情報が欠けている
+- ユーザーが `/vspec:new` を実行して新しい要件分析フローを開始する
+
+## この Skill が定義すること
+
+- シナリオ駆動のファシリテーションで詳細を補完する
+- データモデルを設計する
+- 補完した詳細に基づき UI モック/原型を生成する
+- 業務ロジック詳細を可視化/構造化して出力する
+
+## Commands
+
+### `/vspec:new`
+
+新しい要件分析セッションを開始します。
+
+言語：
+- `/scheme.yaml` の `selected.language` を読む（`en`、`zh`、`ja`。欠落/不正なら `en`。`zh-CN` は `zh` の別名として扱う）
+- コマンド引数または入力で `lang=<...>` が明示された場合：
+  - 単一言語：`lang=en|zh|ja`
+  - 複数言語：`lang=zh,en`（先頭が文書既定言語。`selected.languages` に切替集合を保存）
+
+Flow:
+0. `/docs/` の存在を保証し、サブフォルダを作成：
+   - `/docs/legacy/`
+   - `/docs/current/`
+   - `/docs/refine/`
+   - `/docs/dependencies/`
+   - `/docs/change/` は作成しない（廃止）
+0.2 引数で `lang=...` が渡された場合、`/scheme.yaml` の `selected.language` と `selected.languages` を更新（該当フィールドのみ。その他のフィールド/フォーマットは保持）
+0.5 早期に調整できるように制約ファイルを作成（既存なら上書きしない）：
+   - `/scheme.yaml`（原型スタック選定 + catalog）
+   - `/prototype_ui_convention.md`（`/scheme.yaml` と同階層）
+1. ユーザーに原始要件の入力を依頼
+2. 入力を raw requirement として扱う
+3. `prompts/vspec_new/background.md` を読み込み、要件分析と背景補完を実行
+4. `/specs/background/original.md` に書き込み
+5. Open Questions/要確認事項の回答を促す（自己回答でも、AI の回答案→ユーザー確認でも可）
+6. 以降、`prompts/vspec_new/*` に従い `/specs/` 配下の成果物を生成
+
+### `/vspec:refine`
+
+`/docs/refine/` の追補資料（またはコマンド引数で指定されたファイル/ディレクトリ）に基づき、要件を追補して更新します。
+
+Flow:
+0. `/specs/details/` が存在し非空であることを確認（欠ける場合は停止し `/vspec:detail` を促す）
+1. refine 入力を読む（引数があれば優先、無ければ `/docs/refine/refine.md`）
+2. `prompts/vspec_refine/refine.md` を読み込み、口径と影響成果物を更新
+3. `/specs/background/original.md` に追記し、影響する `/specs/details/` と `/specs/prototypes/` を同期更新
+
+### `/vspec:refine-q`
+
+回答済みの質問に基づき要件を更新します。
+
+Flow:
+1. `/specs/background/questions.md` が無い場合は停止
+2. 回答済み項目を抽出
+3. `prompts/vspec_refine/refine_q.md` を読み込み、回答を口径へマージ
+4. `/specs/background/original.md` に追記
+5. `/specs/background/questions.md` を更新し、回答済みとして扱った項目を `<mark>...</mark>` で強調
+
+### `/vspec:more-q`
+
+追加の確認質問を生成し、`/specs/background/questions.md` に追記します（重複排除・番号継続）。
+
+Flow:
+1. `/specs/background/questions.md` が無い場合は停止（先に `/vspec:new` を促す）
+2. `prompts/vspec_more_q/more_q.md` を読み込み、追加質問を生成
+3. 新規項目のみを `questions.md` 末尾へ追記（既存は書き換えない）
+4. ユーザーが回答し、その後 `/vspec:refine-q` を実行するための指示を出す
+
+### `/vspec:detail`
+
+機能一覧に基づき要件詳細を展開します（`/specs/details/` に生成）。
+
+### `/vspec:verify`
+
+モデル（`/specs/models/`）と実行可能プロトタイプ（`/specs/prototypes/`）を生成して検証します。
+
+### `/vspec:qc`
+
+`/specs/` 配下の成果物を品質チェックし、`/specs/qc_report.md` を生成します。
+
+### `/vspec:accept`
+
+受入テストケースを `/specs/acceptance/` に生成します。
+
+### `/vspec:append-test`
+
+受入ケースと既存テストスタックをもとに、自動テストコードを生成します（テスト実行はしない）。
+
+### `/vspec:impl`
+
+仕様に基づき、統合実装コード（API 契約、backend、frontend 連携）を `/specs/` 配下に生成します。
+
+### `/vspec:upgrade`
+
+`/docs/` 配下の資料（legacy/current）に基づき、`/vspec:new` と同様の構造で `/specs/` を再生成/更新します。
+
+### `/vspec:plan`
+
+ストーリーマップで分解し、見積（SP）と排期（HTML）を生成します。
+
+### `/vspec:mrd`
+
+MRD（市場/競合/ユーザー/プロダクト設計）分析パックを生成し、`/docs/market/` に書き出します。
+
+## Prompt Files
+
+- `prompts/vspec_new/background.md`
+- `prompts/vspec_new/stakeholders.md`
+- `prompts/vspec_new/roles.md`
+- `prompts/vspec_new/terms.md`
+- `prompts/vspec_new/flows.md`
+- `prompts/vspec_new/scenarios.md`
+- `prompts/vspec_new/details_pre_post.md`
+- `prompts/vspec_new/details_constraints.md`
+- `prompts/vspec_new/details_variations.md`
+- `prompts/vspec_new/details_boundaries.md`
+- `prompts/vspec_new/details_symmetry.md`
+- `prompts/vspec_new/dependencies.md`
+- `prompts/vspec_new/functions.md`
+- `prompts/vspec_new/questions.md`
+- `prompts/vspec_more_q/more_q.md`
+- `prompts/vspec_mrd/mrd.md`
+- `prompts/vspec_refine/refine.md`
+- `prompts/vspec_refine/refine_q.md`
+- `prompts/vspec_verify/model.md`
+- `prompts/vspec_verify/prototype.md`
+- `prompts/vspec_verify/validation.md`
+- `prompts/vspec_detail/rbac.md`
+- `prompts/vspec_detail/data_permission.md`
+- `prompts/vspec_detail/page_load.md`
+- `prompts/vspec_detail/interaction.md`
+- `prompts/vspec_detail/timeline.md`
+- `prompts/vspec_detail/formula.md`
+- `prompts/vspec_detail/expression_tree.md`
+- `prompts/vspec_detail/code_rules.md`
+- `prompts/vspec_detail/judgemental_matrix.md`
+- `prompts/vspec_detail/validation_matrix.md`
+- `prompts/vspec_detail/post_submit_check.md`
+- `prompts/vspec_detail/post_submit_processing.md`
+- `prompts/vspec_detail/post_submit_navigation.md`
+- `prompts/vspec_detail/mq.md`
+- `prompts/vspec_detail/logging_matrix.md`
+- `prompts/vspec_detail/notification_matrix.md`
+- `prompts/vspec_detail/nfp.md`
+- `prompts/vspec_detail/file_import.md`
+- `prompts/vspec_detail/file_export.md`
+- `prompts/vspec_detail/cron_job.md`
+- `prompts/vspec_accept/accept.md`
+- `prompts/vspec_test/test.md`
+- `prompts/vspec_impl/implement.md`
+- `prompts/vspec_upgrade/upgrade.md`
+- `prompts/vspec_plan/estimate.md`
+- `prompts/vspec_plan/schedule.md`
+- `prompts/vspec_qc/qc.md`
+- `prompts/vspec_qc/quality_standard.md`