## Command Overview

[English](../en-US/commands.md) | [中文](../zh-CN/commands.md) | [日本語](../ja-JP/commands.md)

| Command | Purpose | Primary Inputs | Primary Outputs |
| --- | --- | --- | --- |
| `/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 (JSON) | functions/scenarios/details/roles/models | `/test/验收用例/acceptance_cases.json` + `/test/testcase_reader.html` |
| `/vspec:i-test` | Generate unit/integration test cases (JSON) | functions/scenarios/details/roles/models | `/test/单元测试/unit_test_cases.json`, `/test/集成测试/integration_test_cases.json` + `/test/testcase_reader.html` |
| `/vspec:script` | Generate Playwright scripts | JSON cases under `/test/` | `/test/playwright/acceptance.spec.ts`, `/test/playwright/integration.spec.ts` |
| `/vspec:append-test` | Generate automated test code | acceptance cases (JSON) + 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 `domain_quality_standard.md` + optional project `quality_standard.md` + `/specs/` | `/specs/qc_report.json`, `/specs/qc_report.html` |
| `/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
- Language control: pass `lang=en` / `lang=zh` / `lang=ja` in the command arguments (`zh-CN` is treated as `zh`) to set the output language for this run, and update `/scheme.yaml` `selected.language` accordingly
 - Directory initialization: creates `/docs/` and its subdirectories (legacy/current/refine/templates/texts/assets) for input archiving and future command inputs

## `/vspec:refine`

- When to use: new information/refinements appear during implementation; you need to update the canonical requirement while keeping traceability, and sync details and prototype
- Inputs:
  - Default: `/docs/refine/` (prefers `/docs/refine/file_list.md`, otherwise reads files by name order)
  - Optional: command args can override with explicit files/directories (higher priority)
- Prerequisite: `/specs/details/` must exist and be non-empty; otherwise `refine` does not run (to avoid upstream changes without downstream sync)
- Key outputs:
  - Append “change list + canonical requirement + impact analysis and artifact updates” to the end of `original.md`
  - Update impacted `/specs/details/` (prefer updating existing files) and `/specs/prototypes/` (minimal reviewable diff)

## `/vspec:refine-q`

- When to use: business has answered `/specs/background/questions.md`, and you want to merge those answers into the requirement and produce a new canonical version
- Key outputs: adopted Q&A items + change list + canonical requirement

## `/vspec:detail`

- When to use: before design/implementation, you need each function to be specified at an implementable level
- Key outputs: RBAC to control level, data permissions, load/interaction/validation matrices, post-submit processing, logging/notification matrices, MQ, import/export, cron jobs

## `/vspec:verify`

- When to use: after details are available, you want to validate the data structure and page shape quickly and reduce misunderstanding risk
- Prerequisite: `/specs/details/` exists and is non-empty
- Key outputs: model files (entity splitting), runnable prototype, scenario review page
- UI spec: generates or reuses `/prototype_ui_convention.md` (same directory as `/scheme.yaml`) and uses it as the single source of truth to constrain prototype UI style and interactions
- Note: before running `/vspec:verify`, review `/specs/functions/*` and `/specs/details/` to ensure the scope is complete; otherwise models and prototypes may miss features.

## `/vspec:accept`

- When to use: align delivery and acceptance with an executable set of cases
- Key outputs: JSON acceptance cases (happy path, exceptions, boundaries, RBAC, data scope) + local reader
  - `/test/验收用例/acceptance_cases.json`
  - `/test/testcase_reader.html` (open it and select JSON files)

## `/vspec:i-test`

- When to use: derive unit/integration test cases from scenarios and implementable details, with explicit coverage for CRUD, validations, permissions, and branching
- Key outputs:
  - `/test/单元测试/unit_test_cases.json`
  - `/test/集成测试/integration_test_cases.json`
  - `/test/testcase_reader.html`

## `/vspec:script`

- When to use: generate Playwright automation skeletons from JSON test cases
- Key outputs:
  - `/test/playwright/acceptance.spec.ts`
  - `/test/playwright/integration.spec.ts`

## `/vspec:append-test`

- When to use: turn acceptance cases into runnable automated tests (E2E/API/unit)
- Key outputs: reuse the repo’s existing test frameworks and scripts; avoid introducing new dependencies
- Note: `/vspec:append-test` generates/adds test code to improve coverage; it does not run test commands (e.g. mvn test/pytest/go test).

## `/vspec:impl`

- When to use: convert spec artifacts into runnable integrated backend + frontend code
- Key outputs: API contract, backend implementation, frontend pages and API integration, RBAC/state machine enforcement

## `/vspec:upgrade`

- When to use: do an “upgrade/redesign/migration” analysis based on legacy system materials, inherit what is needed, and generate new spec artifacts
- Entry list: `/docs/current/file_list.md` (generates a template if missing) to list input files, usage, extracted key points, and whether required
- Input scope: usually from `/docs/legacy/*` and `/docs/current/*`, optionally combined with `/docs/templates/*`, `/docs/texts/*`, `/docs/assets/*`
- Key outputs: generate/update `/specs/` using the `/vspec:new` artifact structure, and label inherited/new/adjusted/deprecated items in the function list
- Stack sync: extract technical selections from “system technical spec” inputs and write them into `/scheme.yaml` for `/vspec:verify` and `/vspec:impl`

## `/vspec:plan`

- When to use: align delivery cadence, decompose via story mapping, and build a schedule
- Key outputs: story decomposition and estimation (person-days), iteration plan, and an HTML story map
