@captain_z/zsk 1.2.1 → 1.4.0

package/{templates/project-init/.zsk/schemas → schemas}/zsk-config.schema.json

@@ -1,8 +1,8 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://zsk.dev/schemas/zsk-config.schema.json",
+  "$id": "https://unpkg.com/@captain_z/zsk@1.3.0/schemas/zsk-config.schema.json",
   "title": "ZSK Project Config",
-  "description": "Project-level configuration for ZSK resource discovery, workspace paths, tools, and module index locations.",
+  "description": "Project-level configuration for ZSK resource origins, workspace paths, tools, and module index locations.",
   "type": "object",
   "additionalProperties": false,
   "required": ["project", "paths", "sources", "tools", "modules"],
@@ -49,29 +49,12 @@
       }
     },
     "sources": {
-      "description": "Project-level raw resource entry points.",
+      "description": "Project-level resource origins. May be empty after init and filled by AI or zsk config setup.",
       "type": "object",
-      "additionalProperties": false,
-      "required": ["srs", "figma_index", "api_contracts", "testing", "design_assets"],
+      "additionalProperties": {
+        "$ref": "#/$defs/sourceRef"
+      },
       "properties": {
-        "srs": {
-          "$ref": "#/$defs/sourceRef"
-        },
-        "figma_index": {
-          "$ref": "#/$defs/sourceRef"
-        },
-        "api_contracts": {
-          "$ref": "#/$defs/sourceRef"
-        },
-        "testing": {
-          "$ref": "#/$defs/sourceRef"
-        },
-        "design_assets": {
-          "$ref": "#/$defs/sourceRef"
-        },
-        "vendor_docs": {
-          "$ref": "#/$defs/sourceRef"
-        },
         "metadata": {
           "$ref": "#/$defs/metadata"
         }
@@ -143,28 +126,81 @@
       "type": "string",
       "enum": ["computer_use", "browser_use", "figma_mcp", "script", "manual", "skill"]
     },
+    "sourceType": {
+      "description": "Resource role.",
+      "type": "string",
+      "enum": ["srs", "prd", "design", "api_contract", "test_case", "design_asset", "vendor_doc", "manual"]
+    },
     "sourceRef": {
       "description": "Resource source reference.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type", "origin"],
+      "properties": {
+        "type": {
+          "$ref": "#/$defs/sourceType"
+        },
+        "origin": {
+          "$ref": "#/$defs/originRef"
+        },
+        "snapshot": {
+          "$ref": "#/$defs/pathRef"
+        },
+        "metadata": {
+          "$ref": "#/$defs/metadata"
+        }
+      }
+    },
+    "originRef": {
+      "description": "Online or local source origin.",
       "oneOf": [
         {
-          "$ref": "#/$defs/localSource"
+          "$ref": "#/$defs/urlOrigin"
+        },
+        {
+          "$ref": "#/$defs/localOrigin"
+        },
+        {
+          "$ref": "#/$defs/gitOrigin"
         },
         {
-          "$ref": "#/$defs/scriptSource"
+          "$ref": "#/$defs/figmaOrigin"
         },
         {
-          "$ref": "#/$defs/skillSource"
+          "$ref": "#/$defs/modaoOrigin"
+        },
+        {
+          "$ref": "#/$defs/openapiOrigin"
+        },
+        {
+          "$ref": "#/$defs/manualOrigin"
         }
       ]
     },
-    "localSource": {
-      "description": "Resource that already exists in the project workspace.",
+    "urlOrigin": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "url"],
+      "properties": {
+        "kind": {
+          "type": "string",
+          "const": "url"
+        },
+        "url": {
+          "type": "string",
+          "minLength": 1
+        },
+        "metadata": {
+          "$ref": "#/$defs/metadata"
+        }
+      }
+    },
+    "localOrigin": {
       "type": "object",
       "additionalProperties": false,
       "required": ["kind", "path"],
       "properties": {
         "kind": {
-          "description": "Local source kind.",
           "type": "string",
           "const": "local"
         },
@@ -176,19 +212,133 @@
         }
       }
     },
-    "scriptSource": {
+    "gitOrigin": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "repository"],
+      "properties": {
+        "kind": {
+          "type": "string",
+          "const": "git"
+        },
+        "repository": {
+          "type": "string",
+          "minLength": 1
+        },
+        "ref": {
+          "type": "string",
+          "minLength": 1
+        },
+        "path": {
+          "$ref": "#/$defs/pathRef"
+        },
+        "metadata": {
+          "$ref": "#/$defs/metadata"
+        }
+      }
+    },
+    "figmaOrigin": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "url"],
+      "properties": {
+        "kind": {
+          "type": "string",
+          "const": "figma"
+        },
+        "url": {
+          "type": "string",
+          "minLength": 1
+        },
+        "file_key": {
+          "type": "string",
+          "minLength": 1
+        },
+        "node_id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "metadata": {
+          "$ref": "#/$defs/metadata"
+        }
+      }
+    },
+    "modaoOrigin": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "url"],
+      "properties": {
+        "kind": {
+          "type": "string",
+          "const": "modao"
+        },
+        "url": {
+          "type": "string",
+          "minLength": 1
+        },
+        "metadata": {
+          "$ref": "#/$defs/metadata"
+        }
+      }
+    },
+    "openapiOrigin": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind"],
+      "properties": {
+        "kind": {
+          "type": "string",
+          "const": "openapi"
+        },
+        "url": {
+          "type": "string",
+          "minLength": 1
+        },
+        "path": {
+          "$ref": "#/$defs/pathRef"
+        },
+        "metadata": {
+          "$ref": "#/$defs/metadata"
+        }
+      },
+      "anyOf": [
+        {
+          "required": ["url"]
+        },
+        {
+          "required": ["path"]
+        }
+      ]
+    },
+    "manualOrigin": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "note"],
+      "properties": {
+        "kind": {
+          "type": "string",
+          "const": "manual"
+        },
+        "note": {
+          "type": "string",
+          "minLength": 1
+        },
+        "metadata": {
+          "$ref": "#/$defs/metadata"
+        }
+      }
+    },
+    "scriptSync": {
       "description": "Resource produced by a deterministic script command.",
       "type": "object",
       "additionalProperties": false,
       "required": ["kind", "command", "output"],
       "properties": {
         "kind": {
-          "description": "Script source kind.",
           "type": "string",
           "const": "script"
         },
         "command": {
-          "description": "Command that syncs this resource.",
           "type": "string",
           "minLength": 1
         },
@@ -200,19 +350,17 @@
         }
       }
     },
-    "skillSource": {
+    "skillSync": {
       "description": "Resource produced by an AI skill or tool-assisted workflow.",
       "type": "object",
       "additionalProperties": false,
       "required": ["kind", "skill", "output"],
       "properties": {
         "kind": {
-          "description": "Skill source kind.",
           "type": "string",
           "const": "skill"
         },
         "skill": {
-          "description": "Skill used to obtain the resource.",
           "type": "string",
           "minLength": 1
         },
@@ -228,10 +376,10 @@
       "description": "Optional sync entry for a resource provider.",
       "oneOf": [
         {
-          "$ref": "#/$defs/scriptSource"
+          "$ref": "#/$defs/scriptSync"
         },
         {
-          "$ref": "#/$defs/skillSource"
+          "$ref": "#/$defs/skillSync"
         }
       ]
     },

package/templates/{project-init/.issues/_templates → issue/default}/issue.md

@@ -1,16 +1,16 @@
-# BUG-0000-short-description
+# __ISSUE_ID__-__ISSUE_SLUG__
 
 ## Priority
 
-P1
+__SEVERITY__
 
 ## Module
 
-`<module-id>`
+`__MODULE_ID__`
 
 ## Environment
 
-- Date: YYYY-MM-DD
+- Date: __DATE__
 - Branch:
 - URL:
 - Command:
@@ -19,7 +19,7 @@ P1
 
 ## Reproduction Steps
 
-1. 
+1.
 
 ## Actual Result
 

package/templates/module/frontend-module/design.md

@@ -0,0 +1,6 @@
+# __MODULE_NAME__ Design
+
+## Documentation Feedback
+
+- No-update rationale:
+  - Created from the ZSK module template; no design decisions have been documented yet.

package/templates/module/frontend-module/module.yaml

@@ -0,0 +1,26 @@
+# yaml-language-server: $schema=https://unpkg.com/@captain_z/zsk@1.3.0/schemas/module.schema.json
+
+module:
+  id: __MODULE_ID__
+  name: __MODULE_NAME__
+
+sources: {}
+
+runtime:
+  url: http://localhost:3000
+  tools:
+    - computer_use
+    - browser_use
+
+tests:
+  raw_cases: []
+  derived_cases: []
+  automated:
+    unit: []
+    integration: []
+    e2e: []
+  tdd_required: true
+
+outputs:
+  docs: __DOCS_OUTPUT__
+  issues: __ISSUES_OUTPUT__

package/templates/module/frontend-module/spec.md

@@ -0,0 +1,6 @@
+# __MODULE_NAME__ Spec
+
+## Documentation Feedback
+
+- No-update rationale:
+  - Created from the ZSK module template; no accepted module behavior has been documented yet.

package/templates/module/frontend-module/tasks.md

@@ -0,0 +1,6 @@
+# __MODULE_NAME__ Tasks
+
+## Documentation Feedback
+
+- No-update rationale:
+  - Created from the ZSK module template; no implementation work has started yet.

package/templates/module/frontend-module/verification.md

@@ -0,0 +1,6 @@
+# __MODULE_NAME__ Verification
+
+## Documentation Feedback
+
+- No-update rationale:
+  - Created from the ZSK module template; no verification has been performed yet.

package/templates/project-init/.issues/README.md

@@ -1,14 +1,11 @@
-# Issues
+# Issue Store
 
-`.issues/` stores local review findings, bug reports, screenshots, logs, reproduction evidence, and verification records created during project work.
+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.
 
 ## Layout
 
 ```text
-.issues/
-├── README.md
-├── _templates/
-│   └── issue.md
+{paths.issues}/
 └── {module}/
     └── BUG-0001-short-slug/
         ├── issue.md
@@ -18,9 +15,11 @@
 
 ## Rules
 
+- Create issue folders with `zsk issue create -m <module-id>` when possible.
 - Keep one confirmed bug per `BUG-xxxx-short-slug/` directory.
 - Group related bugs under the same module directory.
 - Put bug-specific screenshots and runtime evidence under that bug's `assets/`.
 - Put bug-specific console logs, test output, and investigation logs under that bug's `debug-logs/`.
 - Do not place runtime screenshots, debug logs, or failed verification artifacts under `docs/`.
-- Do not place local verification artifacts under `.raws/`.
+- Do not place local verification artifacts under the configured raw snapshot root.
+- Skills must resolve this path from `.zsk/config.yaml`; they must not hard-code `.issues`.

package/templates/project-init/.raws/README.md

@@ -1,40 +1,17 @@
-# .raws/ — 项目原始事实源
+# Raw Snapshots
 
-本目录是项目的**原始事实源层**，存放由人类或外部系统维护、不由 LLM 自由改写的原始文档。
+This directory is the default local snapshot root configured by `.zsk/config.yaml` `paths.raws`.
 
-## 推荐内容
+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`.
 
-| 文件 / 子目录 | 用途 | zsk 配置入口 |
-| --- | --- | --- |
-| `SRS.md` | 原始需求文档（Software Requirements Spec） | `zsk.config.yaml#sources.srs.path` |
-| `FIGMA-INDEX.md` | 模块 → Figma URL / node-id 索引 | `zsk.config.yaml#sources.figma_index.path` |
-| `api-contracts/` | 后端 API 契约（OpenAPI / GraphQL schema） | `zsk.config.yaml#sources.api_contracts.path` |
-| `design-assets/{module}/{snapshot}/` | Figma 快照（由 `zsk:ue-mcp` 产出） | `zsk.config.yaml#sources.design_assets.path` |
-| `testing/` | 原始测试用例、验收用例、提测测试包 | `docs/{module}/module.yaml` 的 `tests.raw_cases` |
-| `manifest.json` | 资源同步清单，由 `zsk prep` / `zsk sync` 维护 | N/A |
+## Expected Contents
 
-## 消费路径
+- `manifest.json`: maintained by `zsk prep` / `zsk sync`.
+- Source snapshots created only when a configured resource is synced or materialized.
 
-skill 通过 `zsk.config.yaml` 和 `docs/{module}/module.yaml` 找到本目录文件：
+## Rules
 
-```
-zsk.config.yaml:
-  sources:
-    srs:
-      path: .raws/SRS.md
-    testing:
-      path: .raws/testing
-```
-
-## Git 状态建议
-
-- `SRS.md` / `FIGMA-INDEX.md`：**入库**（团队共享）
-- `design-assets/{module}/{snapshot}/raw/`：可选 `.gitignore`（体积大或含敏感信息）
-- 含敏感数据的文件：在本目录加 `.gitignore` 排除
-
-## 原则
-
-- **源文件不被 LLM 随意改写**：变更走人工/流程
-- **变更即新 snapshot**：Figma 更新→新 snapshot 目录，不覆盖历史
-- **编号锚稳定**：SRS 中的 `FR-001` / `US-001` / `AC-001` 一旦发布不改（仅废弃，合并/拆分留追踪）
-- **测试用例是一等资产**：原始测试用例保存在 `.raws/testing/`，派生测试矩阵和自动化映射写入 `docs/{module}/`
+- Preserve upstream wording. Do not rewrite snapshots to resolve conflicts.
+- Prefer new snapshots over overwriting historical design/API captures.
+- Keep runtime screenshots, debug logs, HAR files, and failed verification evidence out of this directory.
+- Skills must resolve this path from `.zsk/config.yaml`; they must not hard-code `.raws`.

package/templates/project-init/.zsk/config.yaml

@@ -0,0 +1,22 @@
+# yaml-language-server: $schema=https://unpkg.com/@captain_z/zsk@1.3.0/schemas/zsk-config.schema.json
+
+project:
+  name: "<project-name>"
+
+paths:
+  raws: .raws
+  docs: docs
+  issues: .issues
+
+sources: {}
+
+tools:
+  runtime_ui:
+    - computer_use
+    - browser_use
+  design:
+    - figma_mcp
+
+modules:
+  index: docs/_module-index.md
+  root: docs

package/templates/project-init/{SYSTEM-SPEC.md → docs/SYSTEM-SPEC.md}

@@ -1,36 +1,34 @@
 # System Spec
 
-This file defines project-level behavior rules for humans and AI agents. Keep stable constraints here, and keep machine-readable paths in `zsk.config.yaml`.
+This file defines project-level behavior rules for humans and AI agents. Keep stable constraints here, and keep machine-readable paths and source origins in `.zsk/config.yaml`.
 
 ## Source Priority
 
 When sources conflict, use this priority order until the project overrides it:
 
-1. `SYSTEM-SPEC.md`
-2. `zsk.config.yaml`
-3. `.raws/SRS.md`
-4. `.raws/api-contracts/`
-5. `.raws/testing/`
-6. `.raws/design-assets/`
-7. `docs/{module}/spec.md`
-8. `docs/{module}/design.md`
+1. `docs/SYSTEM-SPEC.md`
+2. `.zsk/config.yaml`
+3. Project sources listed in `.zsk/config.yaml`
+4. Module sources listed in `docs/{module}/module.yaml`
+5. `docs/{module}/spec.md`
+6. `docs/{module}/design.md`
 
-If two upstream raw sources conflict, do not silently choose one. Record the conflict in `.issues/{module}/BUG-xxxx-short-slug/issue.md`, then ask for confirmation before changing accepted specs or designs.
+If two upstream sources conflict, do not silently choose one. Record the conflict under the configured issue root, then ask for confirmation before changing accepted specs or designs.
 
-## Directory Policy
+## Store Policy
 
-- `.raws/` stores upstream facts and source snapshots only.
-- `docs/` stores digested module knowledge, decisions, tasks, and verification.
-- `.issues/` stores defects, local verification evidence, screenshots, logs, and retest records.
-- Runtime screenshots, debug logs, HAR files, and failed verification artifacts must not be stored under `docs/`.
+- `paths.raws` stores local snapshots of upstream facts only.
+- `paths.docs` stores digested module knowledge, decisions, tasks, and verification.
+- `paths.issues` stores defects, local verification evidence, screenshots, logs, and retest records.
+- Runtime screenshots, debug logs, HAR files, and failed verification artifacts must not be stored under the docs root.
 
 ## Testing Policy
 
 Test cases are first-class project assets.
 
-- Original QA, acceptance, release, and manually supplied test cases belong under `.raws/testing/`.
-- Module-derived test cases belong under `docs/{module}/`.
-- AI coding must be TDD-driven from `.raws/testing` and module-derived test cases.
+- Original QA, acceptance, release, and manually supplied test cases belong in configured project sources and may be snapshotted under `paths.raws`.
+- Module-derived test cases belong under each module's configured docs output.
+- AI coding must be TDD-driven from raw and module-derived test cases.
 - A task is not done until the relevant test case is covered by automated tests or recorded as runtime/manual verification evidence.
 
 ## Documentation Feedback Policy

package/templates/project-init/.raws/FIGMA-INDEX.md

@@ -1,38 +0,0 @@
----
-title: Figma Index
-project: <fill-me>
-last_updated: <YYYY-MM-DD>
----
-
-# Figma Index — <项目名>
-
-> **角色**：模块 → Figma URL / node-id 的权威索引。zsk skill 通过 `{{config.paths.figma_index}}` 引用。
-> **配合 skill**：`zsk:ue-mcp`（结构化快照）、`zsk:figma-to-code`（7 步工作流）。
-> **更新时机**：模块首次接入 Figma 设计时登记；设计大改时追加新 snapshot 行。
-
-## 1. 模块索引
-
-| 模块 ID | Figma URL | Node ID | 页面 / Frame | 最后确认 | 快照路径 |
-| --- | --- | --- | --- | --- | --- |
-| <module-a> | https://www.figma.com/file/... | <int:int> | <Page / Frame> | <YYYY-MM-DD> | `.raws/design-assets/module-a/<snapshot>/` |
-
-## 2. 工作流
-
-1. 模块接入 Figma 时：登记本表一行
-2. 走 `zsk:ue-mcp` skill：
-   - 创建 `.raws/design-assets/{module}/{YYYY-MM-DD}-{描述}/` 目录
-   - 落盘 `description.md`（结构化 YAML frontmatter + 人读章节）
-   - 落盘 `screenshot-*.png`（每状态一张）
-   - 可选：`raw/mcp-response.json`（`.gitignore`）
-3. 走 `zsk:figma-to-code`：按 7 步从快照产出生产级代码
-
-## 3. 变更纪律
-
-- **新 snapshot**：设计大改 → 新目录，**不覆盖历史**（历史用于回溯）
-- **本表改写**：指向新 snapshot 目录，旧行转入"归档"小节（保留追溯）
-- **node-id 废弃**：Figma 重绘导致 node-id 失效 → 旧行标 `[deprecated]`，新 node-id 新行
-
-## 归档（历史 snapshot）
-
-| 模块 ID | 旧 snapshot | 归档原因 | 归档日期 |
-| --- | --- | --- | --- |

package/templates/project-init/.raws/SRS.md

@@ -1,73 +0,0 @@
----
-title: Software Requirements Specification
-project: <fill-me>
-status: draft
-version: 0.1.0
-last_updated: <YYYY-MM-DD>
----
-
-# SRS — <项目名>
-
-> **角色**：原始需求事实源。zsk skill 通过 `{{config.paths.srs}}` 引用本文件。
-> **变更流程**：走人工评审（见 `zsk:proposal` → `zsk:spec`），不由 LLM 自由改写。
-> **编号纪律**：FR / NFR / AC 只增不改，废弃用 `[deprecated]` 标记。
-
-## 1. 范围与目标
-
-### 1.1 背景
-<为什么要做此产品/模块>
-
-### 1.2 SMART 目标
-<用 zsk:proposal skill 的 G-{n} 格式>
-
-### 1.3 超出范围（Out of Scope）
-<显式列出不做什么，避免范围蔓延>
-
-## 2. 用户角色与核心场景
-
-| 角色 | 核心场景 | 优先级 |
-| --- | --- | --- |
-| <角色 A> | <场景描述> | P0 |
-
-## 3. 功能需求（FR）
-
-> 编号规则见 `zsk:spec`。每条 FR 必须可被下游 Design / Task / Verify 用编号引用。
-
-- **FR-001**: <描述：做什么，不写怎么做>
-- **FR-002**: <...>
-
-## 4. 非功能需求（NFR）
-
-> 7 大类：performance / a11y / security / i18n / compat / observability / reliability
-> 项目级基线见 `project-config.md` 的 `quality.*`；模块级偏离单独声明。
-
-- **NFR-001**: <描述 + 阈值 + 验证手法>
-
-## 5. 验收条件（AC）
-
-> Gherkin（Given/When/Then）或 BDD 可执行化。每条 AC 覆盖至少 1 个 FR。
-
-- **AC-001**: Given <前置>, When <操作>, Then <期望结果> · 覆盖 `FR-001`
-
-## 6. 用户故事（US）
-
-> INVEST 原则。每个 US 关联若干 FR/AC。
-
-- **US-001**: 作为 <角色>，我想 <目标>，以便 <价值> · 覆盖 `FR-001` / `AC-001`
-
-## 7. 约束（Constraints）
-
-<业务/合规/技术约束。技术约束尽量走 `project-config.md` 与 ADR，不在此重抄>
-
-## 8. 术语表（Glossary）
-
-> 可独立维护于 `docs/system/glossary.md`（zsk:glossary skill）。
-
-| 术语 | 定义 |
-| --- | --- |
-| <Term A> | <定义> |
-
-## 9. 开放问题
-
-- [ ] <待澄清问题 1>
-- [ ] <待澄清问题 2>

package/templates/project-init/.raws/api-contracts/README.md

@@ -1,13 +0,0 @@
-# API Contracts
-
-Store upstream API contracts here, grouped by service or provider.
-
-Recommended layout:
-
-```text
-.raws/api-contracts/
-└── {service}/
-    └── contracts/
-```
-
-Do not edit generated or upstream-owned contracts to match frontend assumptions. If a contract conflicts with SRS, test cases, or design assets, record an issue and resolve the decision in `docs/{module}/`.