visual-spec 0.1.7 → 0.1.9

package/README.md

@@ -1,5 +1,17 @@
 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.
 
+## Installation
+
+Install the Skill into your AI editor configuration directory (Trae / Claude Code / Cursor / GitHub Copilot, etc.):
+
+```bash
+npx skills add visual-req/visual-spec --skill visual-spec-skill
+```
+
+Docs:
+- Installation: `docs/en-US/installation.md`
+- Multi-agent installation: `docs/en-US/ai-platform-installation.md`
+
 ## Overview
 
 - Requirements analysis: generate background, stakeholders, roles, terms, flows, scenarios, details, dependencies, function list, and open questions

package/docs/en-US/ai-platform-installation.md

@@ -0,0 +1,39 @@
+# Multi-Agent Installation Guide
+
+Recommended: use the official skills.sh installer (the skills CLI). It can install the same Skill to different AI platforms (Trae / Claude Code / Cursor / GitHub Copilot, etc.) by placing it into the correct skills directory.
+
+## Option 1: skills.sh (Recommended)
+
+The installer can auto-detect supported agents and prompt you for installation scope (project vs global).
+
+```bash
+npx skills add visual-req/visual-spec --skill visual-spec-skill
+```
+
+Target a specific agent (examples):
+
+```bash
+# Trae (project scope)
+npx skills add visual-req/visual-spec --skill visual-spec-skill -a trae
+
+# Claude Code (project scope)
+npx skills add visual-req/visual-spec --skill visual-spec-skill -a claude-code
+
+# Cursor (project scope)
+npx skills add visual-req/visual-spec --skill visual-spec-skill -a cursor
+
+# GitHub Copilot (project scope)
+npx skills add visual-req/visual-spec --skill visual-spec-skill -a github-copilot
+```
+
+Global install (available across all projects for the current user):
+
+```bash
+npx skills add visual-req/visual-spec --skill visual-spec-skill -g
+```
+
+List skills in this repository:
+
+```bash
+npx skills add visual-req/visual-spec --list
+```

package/docs/en-US/commands.md

@@ -5,20 +5,22 @@
 | `/vspec:new` | Generate baseline spec artifacts from raw requirements | Raw requirement text + interactive Q&A | `/specs/` (original, stakeholders, roles, terms, flows, scenarios, scenario_details, dependencies, functions, questions) + initializes `/docs/*` archive directories |
 | `/vspec:refine` | Apply refinement materials and sync impacted details and prototypes | `/docs/refine/*` (or command args) + baseline `/specs/background/original.md` + prerequisite `/specs/details/` | Appends to `/specs/background/original.md` (change list + canonical) + updates impacted `/specs/details/` and `/specs/prototypes/` |
 | `/vspec:refine-q` | Merge answered questions back into the requirement | `/specs/background/original.md` + `/specs/background/questions.md` | Appends to `/specs/background/original.md` (adopted items + change list + canonical) |
+| `/vspec:more-q` | Append more clarification questions | `/specs/background/original.md` + `/specs/background/questions.md` | Appends new items to `/specs/background/questions.md` (with answering guidance) |
 | `/vspec:detail` | Expand per-function detailed specs | `/specs/functions/*` + supporting artifacts (background/flows/roles; models if any) | `/specs/details/<function_slug>/*` (RBAC, interaction, validation, logging, notifications, MQ, import/export, cron, etc.) |
 | `/vspec:verify` | Generate models and prototype for fast validation | Existing `/specs/` artifacts (functions + details + roles) | `/specs/models/*.md`, `/specs/prototypes/` (stack-selected runnable prototype + `scenario.html` review page) |
 | `/vspec:accept` | Generate acceptance test cases | functions/scenarios/details/roles/models | `/specs/acceptance/<function_slug>/acceptance_cases.md`, `/specs/acceptance/index.md` |
 | `/vspec:append-test` | Generate automated test code | acceptance cases + repo test stack | Writes into existing test directories or `/tests/` |
 | `/vspec:impl` | Generate integrated backend + frontend implementation | specs/details/models/dependencies | Writes integrated implementation code (API contract, backend, frontend integration) |
 | `/vspec:upgrade` | Analyze and generate new specs based on legacy materials | `/docs/current/file_list.md` + `/docs/legacy/*` (optional templates/texts/assets) + existing `/specs/background/original.md` (if any) | Generate/update `/specs/` in `/vspec:new` structure + sync technical selections to `/scheme.yaml` |
-| `/vspec:qc` | Run quality checks on `/specs/` artifacts | built-in standard + optional project `quality_standard.md` + `/specs/` | `/specs/qc_report.md` |
+| `/vspec:qc` | Run quality checks on `/specs/` artifacts | built-in standard + optional `domain_quality_standard.md` + optional project `quality_standard.md` + `/specs/` | `/specs/qc_report.md` |
 | `/vspec:plan` | Estimation and scheduling | functions/roles/flows/dependencies/details | `/specs/plan/plan_estimate.md`, `/specs/plan/plan_schedule.html` |
+| `/vspec:mrd` | Generate MRD market pack | `/specs/background/*` + `/specs/flows/*` + `/specs/functions/*` (if any) | `/docs/market/*.md` (market/competitors/users/product_design) |
 
 ## `/vspec:new`
 
 - When to use: you just received the requirement and information is incomplete; you need a shared language and a first-cut spec quickly
 - Key outputs: stakeholders, roles, terms, flows, scenarios, function list, open questions
-- Directory initialization: creates `/docs/` and its subdirectories (legacy/current/change/refine/templates/texts/assets) for input archiving and future command inputs
+ - Directory initialization: creates `/docs/` and its subdirectories (legacy/current/refine/templates/texts/assets) for input archiving and future command inputs
 
 ## `/vspec:refine`
 

package/docs/en-US/getting-started.md

@@ -4,39 +4,22 @@ This package provides a `/vspec:*` command-driven Skill that turns raw requireme
 
 ### 1. Installation
 
-Install the npm package, then install the Skill into your AI editor configuration directory:
+Install the Skill into your AI editor configuration directory:
 
 - Installation and verification: `installation.md`
 
-Install / update (npm):
+Install / update (skills.sh):
 
 ```bash
-npm install -g visual-spec@latest
-```
-
-Install / update (pnpm):
-
-```bash
-pnpm add -g visual-spec@latest
-```
-
-Install / update (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-skill
 ```
 
 ### 2. Recommended Workflow
 
 - Initial spec: `/vspec:new`
+  - Optional language:
+    - Single language: `/vspec:new lang=zh-CN` (or `lang=en`, `lang=ja`) sets `/scheme.yaml` `selected.language` and generates docs in that language
+    - Multi-language (prototype switch): `/vspec:new lang=zh-CN,en` sets docs default to `zh-CN` and sets `/scheme.yaml` `selected.languages` for prototype UI language switching
   - Midway it generates the canonical requirement file (`/specs/background/original.md`) and asks clarification questions
   - Answer those questions in chat first, then type “continue” to finish `/vspec:new` (do not write these clarification answers into `questions.md`)
   - It also generates an open question list (`/specs/background/questions.md`) for later merging
@@ -51,7 +34,7 @@ yarn dlx -p visual-spec@latest vspec
 
 ### 3. Key Directories
 
-- `/docs/`: input archive (legacy/current/change/refine/templates/texts/assets)
+- `/docs/`: input archive (legacy/current/refine/templates/texts/assets)
 - `/specs/`: generated artifacts (background/details/models/prototypes/acceptance, etc.)
 - `/scheme.yaml`: stack and package manager selection (prototype and implementation must follow it)
 
@@ -72,11 +55,6 @@ Next:
 - Run: `/vspec:refine`
 - Result: appends updates to `/specs/background/original.md` and syncs impacted `/specs/details/` and `/specs/prototypes/`
 
-#### Changes (`change`)
-
-- Put change materials into `/docs/change/` (optional `file_list.md`)
-- Result: performs impact analysis, updates artifacts (prefers `/specs/details/<module_slug>/`), and updates the change log
-
 #### Upgrade/Redesign (`upgrade`)
 
 - List input materials in `/docs/current/file_list.md` (legacy system under `/docs/legacy/`, new inputs under `/docs/current/`)

package/docs/en-US/installation.md

@@ -1,37 +1,18 @@
 ## Install into Skill-Enabled AI Editors
 
-This package uses a script to copy the built-in Skill directory into your AI editor configuration directory (Trae / Qwen / Kiro, etc.). The exact config path differs by editor, but the installation logic is the same: install `visual-spec-skill` into the target `skills/` directory.
+Recommended: use the official skills.sh installer (the skills CLI) to install into a Skill-enabled AI editor (Trae / Qwen / Kiro, etc.). The installer can auto-detect available agents and place `visual-spec-skill` into the correct `skills/` directory.
 
 ### Prerequisites
 
 - Node.js >= 14
 
-### Install / Update (npm)
+### Install / Update (Recommended: skills.sh)
 
 ```bash
-npm install -g visual-spec@latest
-```
-
-### Install / Update (pnpm)
-
-```bash
-pnpm add -g visual-spec@latest
-```
-
-### Install / Update (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-skill
 ```
 
 ### Next
 
 - Getting started: `getting-started.md`
+- Multi-agent installation: `ai-platform-installation.md`

package/docs/en-US/scheme.example.yaml

@@ -7,7 +7,8 @@ selected:
   prototype_backend_stack: java17_springboot3
   prototype_database: mysql8
   package_manager: npm
-  language: zh-CN
+  language: en # default output language: en | zh-CN | ja
+  languages: [en] # optional supported languages for prototype switching, e.g. [zh-CN, en]
 
 prototype_options:
   calendar_view:

package/docs/en-US/structure.md

@@ -14,8 +14,7 @@ The Skill generates artifacts under `/specs/` (incrementally by command stage) a
 │  ├─ legacy/                             # Legacy system materials (features, permissions, interactions, APIs, etc.)
 │  ├─ current/                            # New/additional materials for this iteration (goals, deltas, flows, UI constraints, etc.)
 │  │  └─ file_list.md                     # Upgrade entry list (/vspec:upgrade reads/generates)
-│  ├─ change/                             # Change inputs archive (optional)
-│  │  └─ file_list.md                     # Optional ordered input list
+│  ├─ dependencies/                       # External systems library (existing dependency docs; optional but recommended)
 │  ├─ refine/                             # Refinement inputs (/vspec:refine reads)
 │  │  └─ file_list.md                     # Optional ordered input list
 │  ├─ templates/                          # Templates (PRD/copy/UI/table templates, optional)
@@ -66,7 +65,7 @@ The Skill generates artifacts under `/specs/` (incrementally by command stage) a
 ```
 
 Notes:
-- `docs/`: archive business inputs and delivery alignment materials. Use subdirectories like `legacy/current/change/refine/templates/texts/assets` and include source/version in filenames.
+- `docs/`: archive business inputs and delivery alignment materials. Use subdirectories like `legacy/current/dependencies/refine/templates/texts/assets` and include source/version in filenames.
 - `scheme.yaml`: selects the stack and options used by `/vspec:verify` and `/vspec:impl`. It reads `scheme.yaml` at the project root first, then `/specs/scheme.yaml`. If neither exists, it creates a default `scheme.yaml`.
 
 Next:

package/docs/en-US/workflows.md

@@ -54,8 +54,8 @@ Optional: segmented prototype generation
   - `/specs/plan/plan_estimate.md`
   - `/specs/plan/plan_schedule.html`
 
-## Installation (npm)
+## Installation (skills.sh)
 
-- Recommended at your project root: `npm install <git-url>`
-- After installation, the Skill is copied to: `<your-project>/.trae/skills/visual-spec-skill/`
-- Manual installation (if needed): `npx vspec --force`
+```bash
+npx skills add visual-req/visual-spec --skill visual-spec-skill
+```

package/docs/ja-JP/ai-platform-installation.md

@@ -0,0 +1,39 @@
+# 複数 AI プラットフォーム向けインストールガイド
+
+推奨：skills.sh の公式インストーラ（skills CLI）を利用します。同一の Skill を、Trae / Claude Code / Cursor / GitHub Copilot など複数の AI プラットフォームに対して、それぞれの `skills/` ディレクトリへインストールできます。
+
+## 方法 1：skills.sh（推奨）
+
+インストーラは利用可能な agent を自動検出し、プロジェクト単位/グローバル単位のインストールも選択できます。
+
+```bash
+npx skills add visual-req/visual-spec --skill visual-spec-skill
+```
+
+特定の agent を指定する例：
+
+```bash
+# Trae（プロジェクト単位）
+npx skills add visual-req/visual-spec --skill visual-spec-skill -a trae
+
+# Claude Code（プロジェクト単位）
+npx skills add visual-req/visual-spec --skill visual-spec-skill -a claude-code
+
+# Cursor（プロジェクト単位）
+npx skills add visual-req/visual-spec --skill visual-spec-skill -a cursor
+
+# GitHub Copilot（プロジェクト単位）
+npx skills add visual-req/visual-spec --skill visual-spec-skill -a github-copilot
+```
+
+グローバルインストール（ユーザーの全プロジェクトで利用）：
+
+```bash
+npx skills add visual-req/visual-spec --skill visual-spec-skill -g
+```
+
+このリポジトリ内の skills を一覧表示：
+
+```bash
+npx skills add visual-req/visual-spec --list
+```

package/docs/ja-JP/commands.md

@@ -0,0 +1,38 @@
+## コマンド一覧
+
+| コマンド | 目的 | 主な入力 | 主な出力 |
+| --- | --- | --- | --- |
+| `/vspec:new` | 生要件からベースライン spec を生成 | 要件テキスト + 対話 Q&A | `/specs/`（background/roles/terms/flows/scenarios/scenario_details/dependencies/functions/questions）+ `/docs/*` の初期化 |
+| `/vspec:refine` | 追補資料を反映し、詳細と原型を同期更新 | `/docs/refine/*`（または引数）+ `/specs/background/original.md` + `/specs/details/` | `original.md` に追記（変更点 + 新口径）+ 影響範囲の `/specs/details/` と `/specs/prototypes/` 更新 |
+| `/vspec:refine-q` | questions の回答を要件へ取り込み | `/specs/background/original.md` + `/specs/background/questions.md` | `original.md` に追記（採用項目 + 変更点 + 新口径） |
+| `/vspec:more-q` | 質問の追加生成（追補） | `/specs/background/original.md` + `/specs/background/questions.md` | `questions.md` へ追記（回答手順付き） |
+| `/vspec:detail` | 機能ごとの実装可能レベルの詳細 spec を生成 | `/specs/functions/*` + 関連成果物 | `/specs/details/<function_slug>/*` |
+| `/vspec:verify` | モデルと実行可能プロトタイプを生成 | 既存 `/specs/`（functions + details + roles） | `/specs/models/*.md`、`/specs/prototypes/`（原型 + `scenario.html`） |
+| `/vspec:accept` | 受入テストケースを生成 | functions/scenarios/details/roles/models | `/specs/acceptance/<function_slug>/acceptance_cases.md`、`/specs/acceptance/index.md` |
+| `/vspec:append-test` | 自動テストコードを生成 | acceptance + リポジトリのテストスタック | 既存テストディレクトリ（なければ `/tests/`）に書き込み |
+| `/vspec:impl` | バックエンド + フロントエンドの統合実装を生成 | specs/details/models/dependencies | 統合実装コード（API 契約、backend、frontend 連携） |
+| `/vspec:upgrade` | 既存資料から specs を再生成/更新 | `/docs/current/file_list.md` + `/docs/legacy/*` + 既存 `original.md`（任意） | `/specs/` 更新 + `/scheme.yaml` に選定内容同期 |
+| `/vspec:qc` | `/specs/` の品質チェック | 組み込み標準 + 任意 `domain_quality_standard.md` + 任意 `quality_standard.md` | `/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` |
+
+## `/vspec:new`
+
+- 使いどころ：情報が揃っていない段階で、レビュー可能な共通言語を素早く作る
+- 主な出力：ステークホルダー、ロール、用語、フロー、シナリオ、機能一覧、未解決質問
+- ディレクトリ初期化：`/docs/` とその配下（legacy/current/refine/templates/texts/assets）を作成
+
+## `/vspec:detail`
+
+- 使いどころ：設計・実装前に、各機能を実装可能な粒度まで落とし込む
+- 主な出力：RBAC（コントロール単位）、データ権限、ロード/操作/バリデーション、状態遷移、ログ/通知、MQ、入出力、定期実行
+
+## `/vspec:verify`
+
+- 使いどころ：詳細が揃った後、モデルと画面形状を早期に検証し認識齟齬を減らす
+- 前提：`/specs/details/` が存在し空でないこと
+
+## `/vspec:append-test`
+
+- 使いどころ：受入ケースを、実行可能な自動テストへ落とす
+- 注意：このコマンドはテストコードの生成/追記のみ（テスト実行はしない）

package/docs/ja-JP/concepts.md

@@ -0,0 +1,35 @@
+## 設計原則
+
+### 1. 成果物で合意する
+
+- 「会話」を「レビュー可能な成果物」に変換して、認識合わせのコストを下げる
+- 成果物は段階的に深くなる：要件 → specs（`/specs`）→ models → prototype → details → acceptance/tests/code
+
+### 2. シナリオ駆動で分解する
+
+- apply/approve/cancel/change/execute などのノード連鎖で、主経路とロールバック経路を網羅
+- 各機能は「実行可能な操作 + 検証可能な期待結果」にマッピングされるべき
+
+### 3. RBAC とデータ権限を先に設計する
+
+- 画面は見えても操作できない、を防ぐためコントロール単位まで RBAC を落とす
+- データ権限を独立に設計し、RBAC と合成する
+
+### 4. 実装に落ちる詳細にする
+
+- ロード/操作/送信後の挙動をチェックリストや表で表現し、実装とレビューを容易にする
+- バリデーション/ログ/通知はマトリクスで抜け漏れと追跡可能性を担保する
+
+### 5. 一貫性と観測性をデフォルトにする
+
+- 外部依存、リトライ、補償、監査ログなどを明示的に扱う
+- trace_id/request_id、監査、アラートなどを前提にする
+
+### 6. Acceptance → Automation → Integration
+
+- 受入ケースを開発と QA の共通言語にする
+- 既存のテストフレームワーク/ディレクトリ規約を優先して保守負担を下げる
+
+### 7. 変更しやすい要件
+
+- 要件ドキュメントは編集しやすく、読みやすく、問題点を見つけやすく、素早く修正できるべき

package/docs/ja-JP/getting-started.md

@@ -0,0 +1,39 @@
+## クイックスタート
+
+このパッケージは `/vspec:*` コマンド駆動の Skill を提供します。生の要件から、レビュー可能な成果物（spec、データモデル、実行可能プロトタイプ、詳細設計、受入用ケース、テスト、実装入力）へ変換します。
+
+### 1. インストール
+
+- インストール：`installation.md`
+
+```bash
+npx skills add visual-req/visual-spec --skill visual-spec-skill
+```
+
+### 2. 推奨フロー
+
+- 初期 spec：`/vspec:new`
+  - 言語（任意）：
+    - 単一言語：`/vspec:new lang=zh-CN`（または `lang=en`、`lang=ja`）。`/scheme.yaml` `selected.language` を設定し、文書成果物をその言語で統一します
+    - 多言語（プロトタイプ切替）：`/vspec:new lang=zh-CN,en`。文書の既定言語を `zh-CN` にし、`/scheme.yaml` `selected.languages` を切替用言語集合として設定します
+  - 実行中に要件口径（`/specs/background/original.md`）を生成し、確認質問を提示
+  - まずチャットで回答し、その後「continue」と入力して `/vspec:new` を完了
+- Q&A を要件へ反映：`/vspec:refine-q`（`/specs/background/questions.md` の回答済み項目を `original.md` に取り込む）
+- 品質チェック：`/vspec:qc`（`/specs/qc_report.md` を出力）
+- 詳細設計：`/vspec:detail`（RBAC/データ権限/画面のロード・操作・バリデーション等）
+- 検証（モデル + 原型）：`/vspec:verify`（`/specs/details/` が必要）
+- 受入ケース：`/vspec:accept`
+- 自動テスト生成：`/vspec:append-test`
+- 実装入力/統合コード：`/vspec:impl`
+- 既存資産からのアップグレード：`/vspec:upgrade`
+- 見積・スケジュール：`/vspec:plan`
+
+### 3. 主要ディレクトリ
+
+- `/docs/`：入力アーカイブ（legacy/current/refine/templates/texts/assets）
+- `/specs/`：生成成果物
+- `/scheme.yaml`：スタック選択（プロトタイプと実装が従う）
+
+参照：
+
+- `structure.md`

package/docs/ja-JP/installation.md

@@ -0,0 +1,18 @@
+## Skill 対応 AI エディタへのインストール
+
+推奨：skills.sh の公式インストーラ（skills CLI）を使って、Skill 対応の AI エディタ（Trae / Qwen / Kiro など）へインストールします。インストーラは利用可能な agent を自動検出し、`visual-spec-skill` を適切な `skills/` ディレクトリへ配置します。
+
+### 前提条件
+
+- Node.js >= 14
+
+### インストール / 更新（推奨：skills.sh）
+
+```bash
+npx skills add visual-req/visual-spec --skill visual-spec-skill
+```
+
+### 次へ
+
+- クイックスタート：`getting-started.md`
+- 複数 AI プラットフォーム向けインストール：`ai-platform-installation.md`

package/docs/ja-JP/scheme.example.yaml

@@ -0,0 +1,72 @@
+schema_version: 1
+
+selected:
+  prototype_frontend_stack: vue3_vite_ts_antdv
+  prototype_frontend_framework: vue
+  prototype_frontend_ui_library: ant-design-vue
+  prototype_backend_stack: java17_springboot3
+  prototype_database: mysql8
+  package_manager: npm
+  language: en # デフォルト言語：en | zh-CN | ja
+  languages: [en] # 任意：プロトタイプ言語切替用（例：[zh-CN, en]）
+
+prototype_options:
+  calendar_view:
+    enabled: auto
+    view_default: month
+    resource_dimension: auto
+
+catalog:
+  prototype_frontend_stacks:
+    - id: vue3_vite_ts_antdv
+      name: Vue 3 + Vite + TypeScript + Ant Design Vue
+      framework: vue
+      framework_version: "3"
+      build_tool: vite
+      language: typescript
+      ui_library: ant-design-vue
+      router: vue-router@4
+      state: pinia
+      http_client: axios
+      charting: echarts
+      date_library: dayjs
+      styling: less
+      lint: eslint
+      formatter: prettier
+      unit_test: vitest
+      e2e_test: playwright
+
+    - id: react18_vite_ts_antd
+      name: React 18 + Vite + TypeScript + Ant Design
+      framework: react
+      framework_version: "18"
+      build_tool: vite
+      language: typescript
+      ui_library: antd
+      router: react-router@6
+      state: redux-toolkit
+      http_client: axios
+      charting: echarts-for-react
+      date_library: dayjs
+      styling: less
+      lint: eslint
+      formatter: prettier
+      unit_test: vitest
+      e2e_test: playwright
+
+  prototype_backend_stacks:
+    - id: java17_springboot3
+      name: Java 17 + Spring Boot 3
+      language: java
+      framework: spring-boot
+      api_style: rest
+      auth: spring-security-jwt
+      orm: jpa_or_mybatis
+
+    - id: node18_nestjs10_ts
+      name: Node.js 18 + NestJS 10 + TypeScript
+      language: typescript
+      framework: nestjs
+      api_style: rest
+      auth: jwt
+      orm: prisma

package/docs/ja-JP/structure.md

@@ -0,0 +1,49 @@
+# ディレクトリ構成
+
+このドキュメントは、対象プロジェクトで使うディレクトリ構成（Skill が生成する `/specs/` ツリー等）を説明します。
+
+## 典型構成
+
+```text
+<your-project>/
+├─ docs/                                  # 入力アーカイブ（/vspec:new が作成）
+│  ├─ legacy/                             # 既存/レガシー資料
+│  ├─ current/                            # 今回の入力資料
+│  │  └─ file_list.md                     # upgrade の入力一覧（/vspec:upgrade）
+│  ├─ refine/                             # 追補資料（/vspec:refine）
+│  │  └─ file_list.md                     # 任意の入力順序リスト
+│  ├─ templates/                          # テンプレート（任意）
+│  ├─ texts/                              # 文言（任意）
+│  └─ assets/                             # 画像等（任意）
+├─ scheme.yaml                            # スタック選択（/vspec:verify, /vspec:impl）
+└─ specs/
+   ├─ background/
+   │  ├─ original.md
+   │  ├─ stakeholders.md
+   │  ├─ roles.md
+   │  ├─ terms.md
+   │  ├─ scenarios.md
+   │  ├─ scenario_details/
+   │  ├─ dependencies.md
+   │  └─ questions.md
+   ├─ flows/
+   │  └─ *.puml
+   ├─ functions/
+   │  └─ *.md
+   ├─ details/
+   │  └─ <module_slug>/
+   ├─ models/
+   │  └─ *.md
+   ├─ prototypes/
+   │  └─ ...
+   ├─ acceptance/
+   │  ├─ index.md
+   │  └─ ...
+   ├─ qc_report.md
+   └─ plan/
+      ├─ plan_estimate.md
+      └─ plan_schedule.html
+```
+
+補足：
+- `scheme.yaml` はプロジェクトルートを優先し、なければ `/specs/scheme.yaml` を参照します。

package/docs/ja-JP/ui-spec-modification-notes.md

@@ -0,0 +1,35 @@
+## 背景
+
+プロトタイプ（Web + Mobile）が拡大すると、ページ数と種類が増えます。UI 規約が統一されていないと、次の問題が起きやすくなります：
+
+- 似たページ間でレイアウトが不統一（テーブル/フォーム/詳細）
+- ステータスの色や文言が不統一
+- Web と Mobile の見た目・表現が分断される
+- 操作パターンが不統一（作成導線、Drawer/Modal の使い分けなど）
+
+これを防ぐため、プロトタイプ生成は編集可能な UI 規約ファイル `/prototype_ui_convention.md` によって制約されます。
+
+## 変更点
+
+- プロジェクトレベルの制約ファイル `/prototype_ui_convention.md` を追加（`/scheme.yaml` と同じ階層）
+- `/vspec:verify` がプロトタイプを生成/更新する際：
+  - `/prototype_ui_convention.md` がなければ、まずテンプレートを生成（既存ファイルは上書きしない）
+  - 以後の UI 生成は `/prototype_ui_convention.md` に従う
+  - より厳格な既存ルール（例：`/docs/current/ui_spec.md`）があれば `/prototype_ui_convention.md` に統合し、統合後のファイルを最終ソースにする
+
+## UI 規約の変更方法
+
+- 対象プロジェクトのルートで `/prototype_ui_convention.md` を編集
+- 実装詳細よりも規約を更新する：
+  - 色/ステータスの対応表
+  - テーブル/フォーム/詳細の共通構造
+  - Drawer/Modal の利用ルール
+  - タイポグラフィと余白（Web/Mobile）
+  - 文言とフィードバック（成功/失敗/権限/空/エラー状態）
+- 変更後に `/vspec:verify` を再実行して、生成/更新ページを規約に揃える
+
+## 非推奨
+
+- 規約をページごとの例外集にしない（全体の一貫性が崩れる）
+- プロジェクトの選定スタックにない UI ライブラリを導入しない
+- ページ単位で色/サイズを大量に固定しない（少数のトークンと構造ルールを優先）

package/docs/ja-JP/workflows.md

@@ -0,0 +1,40 @@
+## ワークフロー
+
+### 1. 要件分析（`/vspec:new`）
+
+- 生の要件を入力
+- 前提・範囲・ルール・依存関係などの確認質問に回答
+- `/specs/` にベースライン成果物（roles/terms/flows/scenarios/functions/dependencies/questions）を生成
+
+### 2. 詳細 spec（`/vspec:detail`）
+
+- `/specs/functions/*` を入力に、機能ごとの仕様を `/specs/details/<function_slug>/` に生成
+- 目標：要件を実装可能な設計入力へ変換
+
+### 3. 検証（`/vspec:verify`）
+
+- 前提：`/specs/details/` が存在し空でない
+- `/specs/models/*.md` と、`/scheme.yaml` の選択に従った実行可能プロトタイプを `/specs/prototypes/` に生成
+
+### 4. 受入ケース（`/vspec:accept`）
+
+- `/specs/acceptance/` に受入テストケースを生成
+
+### 5. 自動テスト（`/vspec:append-test`）
+
+- 受入ケースと既存テストスタックを読み、E2E/API/単体テストの最小セットを生成
+- 注意：テスト実行は行わず、コード生成/追記のみ
+
+### 6. 統合実装（`/vspec:impl`）
+
+- specs/details/models/dependencies を読み、リポジトリの規約に沿った統合コードを生成
+
+### 7. 見積・排期（`/vspec:plan`）
+
+- 機能一覧とシナリオをもとに見積・排期（HTML）を生成
+
+## インストール（skills.sh）
+
+```bash
+npx skills add visual-req/visual-spec --skill visual-spec-skill
+```

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-skill
+```
+
+指定安装到某个 AI 平台（示例）：
+
+```bash
+# Trae（项目级）
+npx skills add visual-req/visual-spec --skill visual-spec-skill -a trae
+
+# Claude Code（项目级）
+npx skills add visual-req/visual-spec --skill visual-spec-skill -a claude-code
+
+# Cursor（项目级）
+npx skills add visual-req/visual-spec --skill visual-spec-skill -a cursor
+
+# GitHub Copilot（项目级）
+npx skills add visual-req/visual-spec --skill visual-spec-skill -a github-copilot
+```
+
+全局安装（对当前用户所有项目生效）：
+
+```bash
+npx skills add visual-req/visual-spec --skill visual-spec-skill -g
+```
+
+查看该仓库包含的 skills：
+
+```bash
+npx skills add visual-req/visual-spec --list
+```