@captain_z/zsk 1.4.0 → 1.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (18) hide show
  1. package/README.md +9 -3
  2. package/dist/commands/check.js +1 -1
  3. package/dist/commands/check.js.map +1 -1
  4. package/dist/commands/config.js +1 -1
  5. package/dist/commands/config.js.map +1 -1
  6. package/package.json +2 -2
  7. package/templates/issue/default/assets/index.md +5 -0
  8. package/templates/issue/default/debug-logs/index.md +5 -0
  9. package/templates/issue/default/issue.md +21 -20
  10. package/templates/project-init/.issues/README.md +33 -17
  11. package/templates/project-init/.raws/README.md +11 -2
  12. package/templates/project-init/.raws/api-contracts/index.md +22 -0
  13. package/templates/project-init/.raws/design-assets/index.md +25 -0
  14. package/templates/project-init/.raws/design-sources/index.md +24 -0
  15. package/templates/project-init/.raws/index.md +53 -0
  16. package/templates/project-init/.raws/requirements/index.md +23 -0
  17. package/templates/project-init/.raws/testing/index.md +22 -0
  18. package/templates/project-init/.zsk/config.yaml +17 -0
package/README.md CHANGED
@@ -33,11 +33,11 @@ npx @captain_z/zsk check
33
33
  | `add [<pattern>...]` | 装 / 刷新 / 追加。target 空 → 新装；有 manifest → 自动进刷新岔路 | 自适应 clack 向导，两级多选 |
34
34
  | `remove [<pattern>...]` \| `rm` | 从有 `zsk-manifest.json` 的目录移除；手改文件自动备份 | 多选 + 强确认 |
35
35
  | `list [--bundle=<n>] [--json]` | 浏览 bundle / skill 清单 | 非交互 |
36
- | `init` | 脚手架 `.zsk/config.yaml` + `.raws/` + `docs/` + `.issues/` 最小骨架 | 非破坏性，默认跳过已存在文件 |
36
+ | `init` | 脚手架 `.zsk/config.yaml` + `.raws/index.md` + `.raws/manifest.json` + `.raws/` 分类快照目录 + `docs/` + `.issues/` | 非破坏性，默认跳过已存在文件 |
37
37
  | `config setup` | 指导 AI/人工填写 SRS、PRD、Figma、API、测试用例等资源来源 | 非交互提示 |
38
38
  | `config check` | 校验 `.zsk/config.yaml` 与 `docs/{module}/module.yaml` | 非交互 |
39
39
  | `module init -m <id>` | 从 package 模板生成 `docs/{module}` | 非交互 |
40
- | `issue create -m <id>` | 从 package 模板生成 issue 目录 | 非交互 |
40
+ | `issue create -m <id>` | 从 package 模板生成 issue 目录、`issue.md`、`assets/index.md`、`debug-logs/index.md` | 非交互 |
41
41
  | `prep` | 根据配置记录 `.raws/manifest.json`，为 AI skills 准备上下文 | 非交互 |
42
42
  | `check` | 校验配置、测试资产映射、docs 证据边界、Documentation Feedback 记录 | 非交互 |
43
43
  | `doctor` / `lint` | 校验（Phase 4 实现） | stub |
@@ -62,7 +62,13 @@ zsk check
62
62
  .zsk/
63
63
  └── config.yaml
64
64
  .raws/
65
+ ├── index.md
65
66
  ├── manifest.json
67
+ ├── requirements/index.md
68
+ ├── api-contracts/index.md
69
+ ├── design-sources/index.md
70
+ ├── design-assets/index.md
71
+ └── testing/index.md
66
72
  docs/
67
73
  ├── SYSTEM-SPEC.md
68
74
  └── _module-index.md
@@ -74,7 +80,7 @@ Schemas 随 npm package 发布，并通过 versioned unpkg URL 提供编辑器
74
80
 
75
81
  `zsk config check` 做 schema 和路径边界校验：raw snapshot、模块文档、issue 和运行证据都必须落在 `.zsk/config.yaml` 配置的路径内。
76
82
 
77
- `zsk prep` 读取 `.zsk/config.yaml`，刷新 `{paths.raws}/manifest.json`，记录资源来源、快照存在性、大小和 hash。线上/本地资源来源由 AI 或 `zsk config setup` 填入，CLI 不在这里内置 AI runtime。
83
+ `zsk prep` 读取 `.zsk/config.yaml`，刷新 `{paths.raws}/manifest.json`，记录资源来源、快照存在性、大小和 hash。`.raws/index.md` 是人和 AI 的统一入口，`.raws` 下的分类目录只是本地快照落点，线上/本地资源来源由 AI 或 `zsk config setup` 填入，CLI 不在这里内置 AI runtime。
78
84
 
79
85
  `zsk check` 会跑确定性检查：配置是否有效、模块资源是否存在、配置 raw root 下的测试资产是否映射到模块、派生测试文档是否能追溯到事实源、截图和 debug log 是否误放在 docs root，以及阶段文档是否有 Documentation Feedback 或明确的 no-update rationale。
80
86
 
package/dist/commands/check.js CHANGED
@@ -63,7 +63,7 @@ async function readModuleConfigs(files) {
63
63
  }
64
64
  async function checkRawTestingMapped(target, rawsPath, modules, issues) {
65
65
  const testingRoot = resolve(target, rawsPath, "testing");
66
- const rawFiles = (await collectFiles(testingRoot)).filter((file) => !file.endsWith("/README.md"));
66
+ const rawFiles = (await collectFiles(testingRoot)).filter((file) => !file.endsWith("/README.md") && !file.endsWith("/index.md"));
67
67
  if (rawFiles.length === 0)
68
68
  return;
69
69
  const mapped = new Set();
package/dist/commands/check.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"check.js","sourceRoot":"","sources":["../../src/commands/check.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"check.js","sourceRoot":"","sources":["../../src/commands/check.ts"],"names":[],"mappings":"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"}
package/dist/commands/config.js CHANGED
@@ -35,7 +35,7 @@ export async function setup(opts = {}) {
35
35
  console.log([
36
36
  "",
37
37
  "Give your AI assistant the online URLs or local paths for SRS, PRD, Figma, Modao, API contracts, test cases, and design assets.",
38
- "The assistant should update .zsk/config.yaml sources with type, origin, and optional snapshot fields, then run zsk config check.",
38
+ "The assistant should update .zsk/config.yaml sources with type, origin, and optional snapshot fields under paths.raws, then run zsk config check.",
39
39
  ].join("\n"));
40
40
  }
41
41
  //# sourceMappingURL=config.js.map
package/dist/commands/config.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/commands/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,YAAY,CAAC;AAC5B,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAM3E,MAAM,CAAC,KAAK,UAAU,KAAK,CAAC,OAA2B,EAAE;IACvD,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC;IACtE,MAAM,MAAM,GAAG,MAAM,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAChD,KAAK,MAAM,OAAO,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;QACtC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,KAAK,OAAO,CAAC,IAAI,KAAK,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;IACnE,CAAC;IACD,IAAI,MAAM,CAAC,EAAE,EAAE,CAAC;QACd,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,KAAK,CAAC,2BAA2B,CAAC,CAAC,CAAC;QACnD,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,WAAW,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC;QACpD,IAAI,MAAM,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAClC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,aAAa,MAAM,CAAC,WAAW,CAAC,MAAM,mBAAmB,CAAC,CAAC,CAAC;QACjF,CAAC;QACD,OAAO;IACT,CAAC;IAED,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,CAAC,2BAA2B,CAAC,CAAC,CAAC;IACnD,OAAO,CAAC,KAAK,CAAC,kBAAkB,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;IACjD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,KAAK,CAAC,OAA2B,EAAE;IACvD,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC;IACtE,MAAM,MAAM,GAAG,MAAM,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAChD,KAAK,MAAM,OAAO,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;QACtC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,KAAK,OAAO,CAAC,IAAI,KAAK,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;IACnE,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;QACf,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,CAAC,iDAAiD,CAAC,CAAC,CAAC;QACzE,OAAO,CAAC,KAAK,CAAC,kBAAkB,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;QACjD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,KAAK,CAAC,0BAA0B,CAAC,CAAC,CAAC;IAClD,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,WAAW,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC;IACpD,OAAO,CAAC,GAAG,CACT;QACE,EAAE;QACF,iIAAiI;QACjI,kIAAkI;KACnI,CAAC,IAAI,CAAC,IAAI,CAAC,CACb,CAAC;AACJ,CAAC"}
1
+ {"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/commands/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,YAAY,CAAC;AAC5B,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAM3E,MAAM,CAAC,KAAK,UAAU,KAAK,CAAC,OAA2B,EAAE;IACvD,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC;IACtE,MAAM,MAAM,GAAG,MAAM,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAChD,KAAK,MAAM,OAAO,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;QACtC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,KAAK,OAAO,CAAC,IAAI,KAAK,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;IACnE,CAAC;IACD,IAAI,MAAM,CAAC,EAAE,EAAE,CAAC;QACd,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,KAAK,CAAC,2BAA2B,CAAC,CAAC,CAAC;QACnD,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,WAAW,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC;QACpD,IAAI,MAAM,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAClC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,aAAa,MAAM,CAAC,WAAW,CAAC,MAAM,mBAAmB,CAAC,CAAC,CAAC;QACjF,CAAC;QACD,OAAO;IACT,CAAC;IAED,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,CAAC,2BAA2B,CAAC,CAAC,CAAC;IACnD,OAAO,CAAC,KAAK,CAAC,kBAAkB,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;IACjD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,KAAK,CAAC,OAA2B,EAAE;IACvD,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC;IACtE,MAAM,MAAM,GAAG,MAAM,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAChD,KAAK,MAAM,OAAO,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;QACtC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,KAAK,OAAO,CAAC,IAAI,KAAK,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;IACnE,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;QACf,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,CAAC,iDAAiD,CAAC,CAAC,CAAC;QACzE,OAAO,CAAC,KAAK,CAAC,kBAAkB,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;QACjD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,KAAK,CAAC,0BAA0B,CAAC,CAAC,CAAC;IAClD,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,WAAW,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC;IACpD,OAAO,CAAC,GAAG,CACT;QACE,EAAE;QACF,iIAAiI;QACjI,mJAAmJ;KACpJ,CAAC,IAAI,CAAC,IAAI,CAAC,CACb,CAAC;AACJ,CAAC"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@captain_z/zsk",
3
- "version": "1.4.0",
3
+ "version": "1.4.1",
4
4
  "description": "ZNorth Standard Kit — CLI installer for zsk skill bundles (npx @captain_z/zsk add)",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -20,7 +20,7 @@
20
20
  "commander": "^12.1.0",
21
21
  "picocolors": "^1.1.1",
22
22
  "yaml": "^2.7.0",
23
- "@captain_z/zsk-skills": "1.4.0"
23
+ "@captain_z/zsk-skills": "1.4.1"
24
24
  },
25
25
  "devDependencies": {
26
26
  "@types/node": "^22.10.0",
package/templates/issue/default/assets/index.md ADDED
@@ -0,0 +1,5 @@
1
+ # Issue Assets Index
2
+
3
+ Put screenshots, recordings, HAR files, JSON payloads, exported browser state, and other reproduction artifacts for this issue here.
4
+
5
+ Reference each artifact from `../issue.md`.
package/templates/issue/default/debug-logs/index.md ADDED
@@ -0,0 +1,5 @@
1
+ # Issue Debug Logs Index
2
+
3
+ Put console output, test output, network logs, investigation logs, and command output for this issue here.
4
+
5
+ Reference each log from `../issue.md`.
package/templates/issue/default/issue.md CHANGED
@@ -1,44 +1,45 @@
1
1
  # __ISSUE_ID__-__ISSUE_SLUG__
2
2
 
3
- ## Priority
3
+ ## 问题级别
4
4
 
5
5
  __SEVERITY__
6
6
 
7
- ## Module
7
+ ## 模块
8
8
 
9
9
  `__MODULE_ID__`
10
10
 
11
- ## Environment
11
+ ## 环境
12
12
 
13
- - Date: __DATE__
14
- - Branch:
15
- - URL:
16
- - Command:
17
- - Browser:
18
- - Data source:
13
+ - 日期：__DATE__
14
+ - 分支：
15
+ - URL：
16
+ - 命令：
17
+ - 浏览器：
18
+ - 数据源：
19
+ - 工具：
19
20
 
20
- ## Reproduction Steps
21
+ ## 复现步骤
21
22
 
22
23
  1.
23
24
 
24
- ## Actual Result
25
+ ## 实际结果
25
26
 
26
27
 
27
- ## Expected Result
28
+ ## 预期结果
28
29
 
29
30
 
30
- ## Logs And Evidence
31
+ ## 日志 / 截图
31
32
 
32
- - `assets/<file>`:
33
- - `debug-logs/<file>`:
33
+ - `assets/<file>`：
34
+ - `debug-logs/<file>`：
34
35
 
35
- ## Impact
36
+ ## 影响范围
36
37
 
37
38
 
38
- ## Root Cause / Hypothesis
39
+ ## 初步定位
39
40
 
40
41
 
41
- ## Status
42
+ ## 状态
42
43
 
43
- - Status: Open
44
- - Retest:
44
+ - 状态：Open
45
+ - 复测：
package/templates/project-init/.issues/README.md CHANGED
@@ -1,25 +1,41 @@
1
- # Issue Store
1
+ # .issues — Local Verification And Bug Evidence
2
2
 
3
- This is the default issue root configured by `.zsk/config.yaml` `paths.issues`. It stores review findings, bug reports, screenshots, logs, reproduction evidence, and verification records created during project work.
3
+ This is the default issue root configured by `.zsk/config.yaml` `paths.issues`. It stores local review findings, bug reports, screenshots, logs, reproduction evidence, and verification records created during project work.
4
4
 
5
- ## Layout
5
+ ## Directory Contract
6
6
 
7
7
  ```text
8
- {paths.issues}/
9
- └── {module}/
10
- └── BUG-0001-short-slug/
11
- ├── issue.md
12
- ├── assets/
13
- └── debug-logs/
8
+ .issues/
9
+ ├── README.md
10
+ └── {area-or-module}/
11
+ ├── README.md # optional module issue index
12
+ ├── BUG-0001-short-slug/
13
+ │ ├── issue.md # required issue body
14
+ │ ├── analysis.md # optional root-cause notes
15
+ │ ├── reproduction.md # optional detailed repro script
16
+ │ ├── assets/ # screenshots, videos, HAR, exported state
17
+ │ │ └── index.md
18
+ │ └── debug-logs/ # console, test, network, investigation logs
19
+ │ └── index.md
20
+ ├── _evidence/ # shared evidence referenced by multiple issues/docs
21
+ └── _debug-logs/ # untriaged or cross-issue historical logs only
14
22
  ```
15
23
 
16
- ## Rules
24
+ Use `zsk issue create -m <module-id>` to generate issue folders from the packaged template. `zsk init` does not write `_templates/` into the project.
25
+
26
+ ## Bug Directory Rules
17
27
 
18
- - Create issue folders with `zsk issue create -m <module-id>` when possible.
19
28
  - Keep one confirmed bug per `BUG-xxxx-short-slug/` directory.
20
- - Group related bugs under the same module directory.
21
- - Put bug-specific screenshots and runtime evidence under that bug's `assets/`.
22
- - Put bug-specific console logs, test output, and investigation logs under that bug's `debug-logs/`.
23
- - Do not place runtime screenshots, debug logs, or failed verification artifacts under `docs/`.
24
- - Do not place local verification artifacts under the configured raw snapshot root.
25
- - Skills must resolve this path from `.zsk/config.yaml`; they must not hard-code `.issues`.
29
+ - Put the issue body in `issue.md`.
30
+ - Put screenshots, recordings, HAR files, JSON payloads, exported browser state, and reproduction artifacts that belong to one bug under that bug's `assets/`.
31
+ - Put console output, test output, debug logs, and investigation notes that belong to one bug under that bug's `debug-logs/`.
32
+ - Use `analysis.md` only when root-cause reasoning is long enough that it would obscure the issue body.
33
+ - If two symptoms share one root cause, keep one bug directory and list all symptoms as evidence inside it.
34
+
35
+ ## Relationship To Other Project Directories
36
+
37
+ | Directory | Purpose | May contain local screenshots/logs? |
38
+ |---|---|---|
39
+ | `.raws/` | Upstream facts, mirrored snapshots, original external test cases | No |
40
+ | `docs/{module}/` | Human-authored module proposal/spec/design/tasks/verification | No |
41
+ | `.issues/{module}/` | Local defects, verification evidence, debug logs, issue-quality records | Yes |
package/templates/project-init/.raws/README.md CHANGED
@@ -4,10 +4,19 @@ This directory is the default local snapshot root configured by `.zsk/config.yam
4
4
 
5
5
  Do not treat this directory as the source-origin configuration. SRS, PRD, Figma, Modao, API contracts, test cases, and design assets can come from online URLs, remote repositories, or local files. Their origins belong in `.zsk/config.yaml`.
6
6
 
7
+ Start from `index.md` for the human/AI resource entry point. Use `manifest.json` as the generated machine index.
8
+
7
9
  ## Expected Contents
8
10
 
9
- - `manifest.json`: maintained by `zsk prep` / `zsk sync`.
10
- - Source snapshots created only when a configured resource is synced or materialized.
11
+ - `index.md`: human/AI navigation entry point for raw resources.
12
+ - `manifest.json`: machine-readable index maintained by `zsk prep` / `zsk sync`.
13
+ - `requirements/`: SRS, PRD, acceptance notes, and other requirement snapshots.
14
+ - `api-contracts/`: OpenAPI files, backend API repository snapshots, or exported API notes.
15
+ - `design-sources/`: Figma, Modao, design handoff, and MCP capture snapshots.
16
+ - `design-assets/`: Icons, images, tokens, and other design asset snapshots.
17
+ - `testing/`: QA cases, acceptance cases, release cases, and imported test assets.
18
+
19
+ These directories are local landing zones only. The source addresses still belong in `.zsk/config.yaml` `sources`, so a resource can be online, a git repository path, a Figma/Modao URL, or a local file.
11
20
 
12
21
  ## Rules
13
22
 
package/templates/project-init/.raws/api-contracts/index.md ADDED
@@ -0,0 +1,22 @@
1
+ # API Contracts Index
2
+
3
+ Use this directory for backend API contracts needed by the current project. Organize by backend service, not by frontend page.
4
+
5
+ ## Organization
6
+
7
+ ```text
8
+ .raws/api-contracts/
9
+ ├── index.md
10
+ └── {service}/
11
+ ├── index.md
12
+ └── contracts/
13
+ └── {contract}.md
14
+ ```
15
+
16
+ ## Usage Rules
17
+
18
+ - Configure API repositories, OpenAPI URLs, or local source paths in `.zsk/config.yaml` `sources`.
19
+ - Prefer service-level folders such as `organization/`, `user/`, or `billing/`.
20
+ - Keep selected frontend-facing contracts under `{service}/contracts/`.
21
+ - If contracts are mirrored from another repo, record the original repository/ref/path in `.zsk/config.yaml`.
22
+ - Avoid copying whole backend change directories unless the frontend module truly needs that context.
package/templates/project-init/.raws/design-assets/index.md ADDED
@@ -0,0 +1,25 @@
1
+ # Design Assets Index
2
+
3
+ Use this directory for design-layer static assets: icons, images, theme tokens, CSS exports, screenshots, and other files consumed by implementation.
4
+
5
+ ## Organization
6
+
7
+ ```text
8
+ .raws/design-assets/
9
+ ├── index.md
10
+ └── {module}/
11
+ ├── index.md
12
+ ├── *.json
13
+ ├── *.css
14
+ └── {YYYY-MM-DD}-{snapshot}/
15
+ ├── description.md
16
+ ├── screenshot-main.png
17
+ └── screenshot-{state}.png
18
+ ```
19
+
20
+ ## Usage Rules
21
+
22
+ - Group assets by frontend module when possible.
23
+ - Reference assets from `docs/{module}/design.md` or module-specific design handoff docs.
24
+ - Record token/icon/component mapping decisions in module docs, not only in asset files.
25
+ - Keep runtime verification screenshots under `.issues/`, not here.
package/templates/project-init/.raws/design-sources/index.md ADDED
@@ -0,0 +1,24 @@
1
+ # Design Sources Index
2
+
3
+ Use this directory for source-level design captures: Figma, Modao, design handoff exports, MCP readouts, and page/node metadata.
4
+
5
+ ## Organization
6
+
7
+ ```text
8
+ .raws/design-sources/
9
+ ├── index.md
10
+ └── {module-or-product-area}/
11
+ ├── index.md
12
+ ├── figma.json
13
+ ├── modao.json
14
+ └── {YYYY-MM-DD}-{snapshot}/
15
+ ├── description.md
16
+ └── raw/
17
+ ```
18
+
19
+ ## Usage Rules
20
+
21
+ - Configure Figma/Modao URLs and node IDs in `.zsk/config.yaml` `sources`.
22
+ - Keep source captures separate from implementation docs.
23
+ - Use `description.md` when a snapshot needs human-readable layout, token, state, or interaction notes.
24
+ - Treat raw MCP responses as cacheable unless the project chooses to commit them.
package/templates/project-init/.raws/index.md ADDED
@@ -0,0 +1,53 @@
1
+ # .raws — Raw Resource Index
2
+
3
+ This file is the human/AI entry point for upstream facts and local snapshots. It separates source configuration from local snapshot storage.
4
+
5
+ ## Directory Contract
6
+
7
+ ```text
8
+ .raws/
9
+ ├── README.md
10
+ ├── index.md # this navigation index
11
+ ├── manifest.json # generated machine index, refreshed by zsk prep
12
+ ├── requirements/ # SRS, PRD, acceptance notes, requirement snapshots
13
+ │ └── index.md
14
+ ├── api-contracts/ # API contracts, OpenAPI files, backend repo extracts
15
+ │ └── index.md
16
+ ├── design-sources/ # Figma, Modao, MCP, design handoff captures
17
+ │ └── index.md
18
+ ├── design-assets/ # icons, images, tokens, screenshots, raw design assets
19
+ │ └── index.md
20
+ └── testing/ # QA, acceptance, release, and imported test assets
21
+ └── index.md
22
+ ```
23
+
24
+ ## Source Configuration
25
+
26
+ Real origins belong in `.zsk/config.yaml` `sources`. A source can be an online URL, git repository, Figma/Modao URL, OpenAPI location, or local file. Use `snapshot` only when the resource is materialized under `.raws/`.
27
+
28
+ `manifest.json` is generated by `zsk prep` and records configured resources, snapshot existence, size, hash, and sync method. Do not edit it by hand unless recovering from a broken sync.
29
+
30
+ ## Categories
31
+
32
+ | Category | Entry | Typical source types |
33
+ |---|---|---|
34
+ | Requirements | `requirements/index.md` | `srs`, `prd`, `manual` |
35
+ | API contracts | `api-contracts/index.md` | `api_contract`, `vendor_doc` |
36
+ | Design sources | `design-sources/index.md` | `design`, Figma, Modao, MCP |
37
+ | Design assets | `design-assets/index.md` | `design_asset`, tokens, images |
38
+ | Testing assets | `testing/index.md` | `test_case`, QA sheets, acceptance cases |
39
+
40
+ ## Boundary With Docs And Issues
41
+
42
+ | Directory | Purpose | Runtime screenshots/logs |
43
+ |---|---|---|
44
+ | `.raws/` | Upstream facts and mirrored snapshots | No |
45
+ | `docs/` | Human-authored module proposal/spec/design/tasks/verification | No |
46
+ | `.issues/` | Local bugs, verification evidence, debug logs, screenshots | Yes |
47
+
48
+ ## Rules
49
+
50
+ - Preserve upstream wording in snapshots.
51
+ - Prefer appending new snapshots over overwriting historical captures.
52
+ - Put source URLs and local origins in `.zsk/config.yaml`, not in scattered notes.
53
+ - Keep runtime evidence, failed verification artifacts, HAR files, and debug logs under `.issues/`.
package/templates/project-init/.raws/requirements/index.md ADDED
@@ -0,0 +1,23 @@
1
+ # Requirements Index
2
+
3
+ Use this directory for local snapshots of SRS, PRD, acceptance notes, product decisions, and other requirement documents.
4
+
5
+ ## Organization
6
+
7
+ ```text
8
+ .raws/requirements/
9
+ ├── index.md
10
+ ├── srs.md
11
+ ├── prd.md
12
+ └── {source-or-date}/
13
+ ├── page.md
14
+ ├── comments.json
15
+ └── attachments/
16
+ ```
17
+
18
+ ## Usage Rules
19
+
20
+ - Configure real origins in `.zsk/config.yaml` `sources`.
21
+ - Use this directory for immutable or append-only snapshots.
22
+ - Reference requirement snapshots from `docs/{module}/proposal.md` and `docs/{module}/spec.md`.
23
+ - Do not rewrite upstream text to resolve conflicts; document conflict analysis in module docs or `.issues/`.
package/templates/project-init/.raws/testing/index.md ADDED
@@ -0,0 +1,22 @@
1
+ # Testing Assets Index
2
+
3
+ Use this directory for upstream or imported test assets: QA sheets, acceptance cases, release cases, manual verification scripts, and exported test documents.
4
+
5
+ ## Organization
6
+
7
+ ```text
8
+ .raws/testing/
9
+ ├── index.md
10
+ ├── qa-cases.md
11
+ ├── acceptance-cases.md
12
+ └── {source-or-release}/
13
+ ├── cases.md
14
+ └── cases.xlsx
15
+ ```
16
+
17
+ ## Usage Rules
18
+
19
+ - Configure real test case origins in `.zsk/config.yaml` `sources`.
20
+ - Map module-level raw cases in `docs/{module}/module.yaml` `tests.raw_cases` or `sources.testing`.
21
+ - Derived cases and automated tests belong in module docs or code test files.
22
+ - `zsk check` treats non-index files here as raw test assets that should be mapped to a module.
package/templates/project-init/.zsk/config.yaml CHANGED
@@ -8,6 +8,23 @@ paths:
8
8
  docs: docs
9
9
  issues: .issues
10
10
 
11
+ # Resource origins. AI or zsk config setup should fill these with online URLs,
12
+ # git repositories, Figma/Modao links, OpenAPI locations, or local files.
13
+ # Optional snapshots should land under paths.raws, for example:
14
+ #
15
+ # sources:
16
+ # srs:
17
+ # type: srs
18
+ # origin:
19
+ # kind: url
20
+ # url: https://example.com/srs
21
+ # snapshot: .raws/requirements/srs.md
22
+ # figma_main:
23
+ # type: design
24
+ # origin:
25
+ # kind: figma
26
+ # url: https://www.figma.com/file/...
27
+ # snapshot: .raws/design-sources/figma-main.json
11
28
  sources: {}
12
29
 
13
30
  tools: