# Directory Structure

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

This document describes the directory structure used in a target project:
- The `/specs/` artifact tree generated by the Skill (requirements/design deliverables)


## Target Project Layout

The Skill generates artifacts under `/specs/` (incrementally by command stage) and maintains a small set of project-level configs and input archive directories. A typical layout:

```text
<your-project>/
├─ docs/                                  # Input archive (/vspec:new creates it)
│  ├─ 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)
│  ├─ 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)
│  ├─ texts/                              # Copywriting (prompts, error messages, agreements, message templates, optional)
│  └─ assets/                             # Static assets (designs, screenshots, prototypes, images, optional)
├─ scheme.yaml                            # Prototype stack selection (/vspec:verify uses; created with defaults if missing)
└─ specs/
   ├─ background/                         # Background analysis and shared materials
   │  ├─ original.md                      # Raw requirement (or equivalent input)
   │  ├─ stakeholders.md                  # Stakeholders
   │  ├─ roles.md                         # Roles and responsibilities
   │  ├─ terms.md                         # Glossary
   │  ├─ scenarios.md                     # Scenario list
   │  ├─ scenario_details/                # Scenario details per node: pre_post.md/constraints.md/variations.md/boundaries.md/symmetry.md
   │  ├─ dependencies.md                  # External dependencies
   │  └─ questions.md                     # Open questions (must be resolved or explicitly skipped before verify)
   ├─ flows/                              # Flow diagrams (PlantUML)
   │  └─ *.puml
   ├─ functions/                           # Function list (split by module)
   │  └─ *.md
   ├─ details/                             # Per-function detailed design (/vspec:detail output)
   │  └─ <module_slug>/
   │     ├─ rbac/                          # RBAC
   │     ├─ data_permission/               # Data permissions
   │     ├─ page_load/
   │     ├─ interaction/
   │     ├─ validation_matrix/
   │     ├─ logging_matrix/
   │     ├─ notification_matrix/
   │     ├─ mq/
   │     ├─ nfp/                           # Non-functional requirements (performance, security, compatibility, resilience, stability)
   │     ├─ file_import/
   │     ├─ file_export/
   │     └─ cron_job/
   ├─ models/                              # Data models (/vspec:verify output)
   │  ├─ *.md
   │  └─ README.md
   ├─ prototypes/                          # Runnable prototype + review pages (/vspec:verify output)
   │  └─ ...
   ├─ qc_report.md                         # Quality report (/vspec:qc output)
   ├─ plan/                                # Planning outputs (/vspec:plan output)
   │  ├─ plan_estimate.md                  # Estimation
   │  └─ plan_schedule.html                # Schedule page
   └─ change_log.md                        # Change log (optional)
```

Test cases (JSON) and Playwright scripts are generated under:

```text
/test/
  ├─ 验收用例/                              # /vspec:accept output (JSON)
  │  └─ acceptance_cases.json
  ├─ 单元测试/                              # /vspec:i-test output (JSON)
  │  └─ unit_test_cases.json
  ├─ 集成测试/                              # /vspec:i-test output (JSON)
  │  └─ integration_test_cases.json
  ├─ playwright/                           # /vspec:script output
  │  ├─ acceptance.spec.ts
  │  └─ integration.spec.ts
  └─ testcase_reader.html                  # JSON reader (single-file HTML)
```

Notes:
- `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:

- Read `commands.md` for each `/vspec:*` command’s inputs, outputs, and usage scenarios
