@captain_z/zsk 1.3.0 → 1.4.1

package/templates/project-init/.raws/requirements/index.md

@@ -0,0 +1,23 @@
+# Requirements Index
+
+Use this directory for local snapshots of SRS, PRD, acceptance notes, product decisions, and other requirement documents.
+
+## Organization
+
+```text
+.raws/requirements/
+├── index.md
+├── srs.md
+├── prd.md
+└── {source-or-date}/
+    ├── page.md
+    ├── comments.json
+    └── attachments/
+```
+
+## Usage Rules
+
+- Configure real origins in `.zsk/config.yaml` `sources`.
+- Use this directory for immutable or append-only snapshots.
+- Reference requirement snapshots from `docs/{module}/proposal.md` and `docs/{module}/spec.md`.
+- Do not rewrite upstream text to resolve conflicts; document conflict analysis in module docs or `.issues/`.

package/templates/project-init/.raws/testing/index.md

@@ -0,0 +1,22 @@
+# Testing Assets Index
+
+Use this directory for upstream or imported test assets: QA sheets, acceptance cases, release cases, manual verification scripts, and exported test documents.
+
+## Organization
+
+```text
+.raws/testing/
+├── index.md
+├── qa-cases.md
+├── acceptance-cases.md
+└── {source-or-release}/
+    ├── cases.md
+    └── cases.xlsx
+```
+
+## Usage Rules
+
+- Configure real test case origins in `.zsk/config.yaml` `sources`.
+- Map module-level raw cases in `docs/{module}/module.yaml` `tests.raw_cases` or `sources.testing`.
+- Derived cases and automated tests belong in module docs or code test files.
+- `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

@@ -0,0 +1,39 @@
+# 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
+
+# Resource origins. AI or zsk config setup should fill these with online URLs,
+# git repositories, Figma/Modao links, OpenAPI locations, or local files.
+# Optional snapshots should land under paths.raws, for example:
+#
+# sources:
+#   srs:
+#     type: srs
+#     origin:
+#       kind: url
+#       url: https://example.com/srs
+#     snapshot: .raws/requirements/srs.md
+#   figma_main:
+#     type: design
+#     origin:
+#       kind: figma
+#       url: https://www.figma.com/file/...
+#     snapshot: .raws/design-sources/figma-main.json
+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/.issues/_templates/issue.md

@@ -1,44 +0,0 @@
-# BUG-0000-short-description
-
-## Priority
-
-P1
-
-## Module
-
-`<module-id>`
-
-## Environment
-
-- Date: YYYY-MM-DD
-- Branch:
-- URL:
-- Command:
-- Browser:
-- Data source:
-
-## Reproduction Steps
-
-1. 
-
-## Actual Result
-
-
-## Expected Result
-
-
-## Logs And Evidence
-
-- `assets/<file>`:
-- `debug-logs/<file>`:
-
-## Impact
-
-
-## Root Cause / Hypothesis
-
-
-## Status
-
-- Status: Open
-- Retest:

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}/`.

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

@@ -1,16 +0,0 @@
-# Design Assets
-
-Store Figma, MCP, and design-source snapshots here.
-
-Recommended layout:
-
-```text
-.raws/design-assets/
-└── {module}/
-    └── {snapshot}/
-        ├── description.md
-        ├── screenshot-*.png
-        └── raw/
-```
-
-Treat each sync as a snapshot. Prefer adding a new snapshot over overwriting historical evidence.

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

@@ -1,10 +0,0 @@
-# Testing Sources
-
-Store original test assets here:
-
-- QA test cases
-- acceptance spreadsheets or exports
-- release test packs
-- manually supplied validation scenarios
-
-These are raw source facts. Derived scenario matrices and automated test mappings belong under `docs/{module}/`.

package/templates/project-init/CLAUDE.md

@@ -1,45 +0,0 @@
-# CLAUDE.md — <项目名>
-
-> Claude Code 进入本项目时自动读取的会话指令。其他 harness（Codex `AGENTS.md` / Gemini `GEMINI.md`）镜像核心语义。
-
-## 项目身份
-
-- **名称**：<项目名>
-- **类型**：<microfrontend / monolith / library / cli>
-- **技术栈**：见 [`project-config.md`](./project-config.md)（frontmatter `stack.*`）
-
-## 本项目使用 zsk skill set
-
-通过 `@captain_z/zsk add` 安装（`~/.claude/skills/` 或 `./.claude/skills/`）。运行时自动发现；手动触发写 "用 `zsk:<name>`"。
-
-**常用 skill 组合**（见 `npx @captain_z/zsk list`）：
-
-- 启动任一变更：`zsk:feature` / `zsk:bugfix` / `zsk:refactor`
-- 7 阶段：`zsk:proposal` → `zsk:spec` → `zsk:design` → `zsk:coding` → `zsk:reviewing` → `zsk:verify` → `zsk:archive`
-- 任务：`zsk:task` / `zsk:task-structure` / `zsk:task-tracking`（含 §6 每任务交互契约）/ `zsk:task-evidence` / `zsk:dor-dod`
-- 前端扩展：`zsk:spec-frontend` / `zsk:design-frontend` / `zsk:review-frontend` / `zsk:feature-tasks-frontend`
-
-## 项目事实源
-
-| 文件 / 目录 | 作用 |
-| --- | --- |
-| [`project-config.md`](./project-config.md) | 机械配置（`{{config.*}}` 占位符的解析源） |
-| [`.raws/`](./.raws/) | 原始事实源（SRS / FIGMA-INDEX / api-contracts / design-assets） |
-| `docs/system/` | 系统级决策（ADR / architecture / glossary / nfr-baseline） |
-| `SYSTEM-SPEC.md`（可选） | 团队共享的项目硬约束，覆写 zsk skill 默认 |
-
-## 规约优先级（冲突时上位胜出）
-
-1. 用户会话显式指令
-2. 本 `CLAUDE.md` 的项目指令
-3. `SYSTEM-SPEC.md`（若存在）
-4. `project-config.md`
-5. `docs/system/*`（ADR / architecture / NFR baseline）
-6. zsk skills（已安装）
-7. 平台级 skill（`~/.claude/skills/*` 非 zsk 的）
-8. 工具默认行为
-
-## 交互契约（LLM 执行任务时）
-
-见 `zsk:task-tracking` §6：**每单任务执行完 → 更新状态 + 填证据 → 短汇报 → 等人类确认 → 再推下一个**，不自动连跑。
-例外：纯读取任务 / 用户显式授权"连跑 N 个" / CI 自动化任务。

package/templates/project-init/docs/_module-template/module.yaml

@@ -1,32 +0,0 @@
-# yaml-language-server: $schema=../../.zsk/schemas/module.schema.json
-
-module:
-  id: example-module
-  name: Example Module
-
-sources:
-  srs:
-    path: .raws/SRS.md
-    sections: []
-  api_contracts: []
-  testing: []
-  design_assets: []
-
-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/example-module
-  issues: .issues/example-module

package/templates/project-init/docs/system/README.md

@@ -1,12 +0,0 @@
-# System Docs
-
-Use this directory for project-wide architecture, ADRs, glossary, and non-functional requirements.
-
-Recommended files:
-
-- `architecture.md`
-- `glossary.md`
-- `nfr-baseline.md`
-- `adrs/ADR-0001-title.md`
-
-Keep project-wide rules in `SYSTEM-SPEC.md`; keep module-specific behavior under `docs/{module}/`.