create-yss-spec 1.1.3 → 2.0.0

package/template/README.md

@@ -9,26 +9,26 @@
 ## 项目结构
 
 ```text
-├── .agent/                  ← 通用 Agent 项目级 Matt skills
-├── .agents/                 ← Agent 可加载的 Engineering Skills、脚本和参考材料
-├── .claude/                 ← Claude 项目级 skills
-├── .codex/                  ← Codex 项目级 Matt + YSS skills
-├── .hermes/                 ← Hermes 项目级 skills
-├── .pi/                     ← Pi 项目级 skills
-├── .trae/                   ← Trae 项目级 skills
+├── .agents/                 ← 跨 Agent 共享 skills 的权威内容
+├── .claude/                 ← Claude skills 投影与平台专属 skills
+├── .codex/                  ← Codex skills 投影与平台专属 YSS skills
+├── .hermes/                 ← Hermes skills 投影与平台专属 skills
+├── .pi/                     ← Pi skills 投影与平台专属 skills
+├── .trae/                   ← Trae skills 投影与平台专属 skills
 ├── AGENTS.md                ← AI 指令
 ├── CONTEXT.md               ← 领域词汇表
+├── yss-project.yaml         ← 仓库身份清单
 ├── docs/
 │   ├── api/                 ← OpenAPI 3.1 契约
 │   ├── adr/                 ← 架构决策记录
-│   ├── requirements/        ← PRD / 用户故事 / 需求草案 / 垂直切片
+│   ├── requirements/        ← Spec / 用户故事 / 需求草案 / 垂直切片
 │   ├── discovery/           ← 机会探索、市场、竞品和用户材料
 │   ├── design/              ← 产品设计、原型、交互说明和状态矩阵
 │   ├── architecture/        ← 架构设计与审查模板
 │   ├── releases/            ← 发布说明
 │   ├── implementation/      ← 实施方案、上线记录和回滚方案
 │   ├── testing/             ← 测试策略和验证记录
-│   ├── agents/              ← Agent 协作规范、Issue/Triage/领域文档约定
+│   ├── agents/              ← Agent 协作规范、Ticket/Triage/领域文档约定
 │   ├── templates/           ← 通用文档模板
 │   └── process/             ← 生命周期、裁剪、Scrum 和技能治理说明
 └── scripts/                 ← 模板轻量校验脚本
@@ -38,51 +38,34 @@
 
 ## Quickstart
 
-1. 先判断当前生命周期阶段、已有资产和缺失资产；建议用 `yss-product-lifecycle` 做阶段路由。
-2. 新产品或新模块先完成机会探索；已有材料时先整理 discovery，再进入 `grill-with-docs`。
-3. 新产品或新业务域先明确业务架构，再使用 `grill-with-docs` 澄清边界。
-4. 按 `docs/templates/prd-template.md` 形成 PRD，并同步明确功能架构、模块边界和 MVP / 非目标范围。
-5. 如有 API 影响，先在 `docs/api/specs/` 生成 OpenAPI 3.1 Draft；Draft 经工程基线、系统 / 数据架构和设计审查后 Freeze。
-6. 使用 `to-issues` 或 `docs/templates/vertical-slice-issue-template.md` 拆分可独立验证的垂直切片 Issue。
-7. 进入实现前按 `docs/process/implementation-repo-integration.md` 登记外部实现仓库；已有工程用 `implementation-repo-onboarding`，跨仓库切片用 `cross-repo-implementation-routing`。
-8. 后端新服务或新模块先确认 YSS DDD 工程基线；从零创建服务时使用 `yss-ddd-scaffold-generator`。
-9. 前端 0-1 微应用使用 `yss-frontend-scaffold-generator` 对齐标准模板；业务页面实现再接 `yss-page-module-development` 和 `api-integration`。
-10. 业务行为实现默认使用 `tdd`：先写失败测试，再写最小实现；Bug 修复先建立 `diagnosing-bugs` 反馈闭环。
-11. 每个切片完成后做 `code-review` 或独立审查和 fresh verification，再发布、实施和复盘。
-12. 在 `docs/architecture/`、`docs/adr/`、`CONTEXT.md` 和 `AGENTS.md` 沉淀稳定规则。
+1. 先读取 `yss-project.yaml`，按 `repository_mode` 选择模板维护或产品研发生命周期。
+2. 必读入口为 `AGENTS.md` 与 `CONTEXT.md`；流程事实分别以生命周期映射和裁剪指南为准。
+3. `template-source` 修改流程、技能或模板后，执行 `scripts/sync-skills`、`scripts/update-skill-lock` 和 `scripts/verify-template`。
+4. `project-instance` 先做影响面分诊；进入 Spec 基线时使用 `grill-with-docs`、`to-spec`，契约冻结后再用 `to-tickets` 拆分垂直切片 Ticket。
+5. 实现仓库接入、YSS 路由、独立审查、fresh verification 和 Git checkpoint 以 `AGENTS.md` 的硬门禁为准。
 
 ## 模板初始化 CLI
 
-当前仓库已内置一个用于实例化模板的 npm CLI：`create-yss-spec`。
+`create-yss-spec` 的目标维护位置是独立 GitHub 仓库 [iloveZzz/create-yss-spec](https://github.com/iloveZzz/create-yss-spec)。本仓库不再包含 CLI 源码、测试、发布配置或开发过程记录，只保留面向模板使用者的实践指南：
 
-完整中文使用手册见：
+- [create-yss-spec 外部 CLI 实践指南](./docs/user-guide/create-yss-spec-cli-guide.md)
 
-- [docs/user-guide/create-yss-spec-cli-guide.md](./docs/user-guide/create-yss-spec-cli-guide.md)
-
-本地开发验证：
-
-```bash
-npm test
-```
-
-发包 / 使用形态：
+推荐入口：
 
 ```bash
 npm create yss-spec@latest
 ```
 
-支持的主参数能力：
-
-- 交互式初始化空目录
-- `--dry-run`
-- `--force`
-- `--git-init`
-- `--issue-tracker`
-- `--no-example-docs`
+首次使用前请先确认独立仓库和 npm 包已完成发布。
 
 ## 模板配置取舍
 
-本模板纳入 `.agent/`、`.agents/`、`.claude/`、`.codex/`、`.hermes/`、`.pi/`、`.trae/`，因为它们是跨 Agent 复用 Matt Pocock Engineering Skills 和 YSS skills 的项目级配置。
+`.agents/skills` 是共享技能的权威内容；其他 Agent root 只保存同步投影和平台专属技能。共享技能只能在权威目录修改，随后运行：
+
+```bash
+scripts/sync-skills
+scripts/update-skill-lock
+```
 
 Matt engineering skills 固定来源：
 
@@ -100,8 +83,10 @@ scripts/verify-template
 
 该脚本检查：
 
-- 项目级 Agent 目录是否包含必需 Matt engineering skills。
-- 旧流程目录、规则和运行时状态文件是否已清理。
+- `yss-project.yaml`、权威流程资产和模板是否完整。
+- 共享技能投影及 `skills-lock.json` 的完整树哈希是否一致。
+- 过时技能、路径和规范用语是否已清理。
+- 五类流程压力场景是否符合条件门禁和仓库身份路由。
 - Markdown 相对链接是否指向现有文件。
 - 示例 OpenAPI YAML 是否可解析。
 - Git diff 是否存在空白错误。
@@ -123,6 +108,7 @@ scripts/verify-template
 | [docs/process/implementation-repo-integration.md](./docs/process/implementation-repo-integration.md) | 外部前端 / 后端实现仓库接入与跨仓库切片绑定 |
 | [docs/agents/README.md](./docs/agents/README.md) | Agent 协作文档目录说明 |
 | [docs/agents/skills-maintenance.md](./docs/agents/skills-maintenance.md) | Agent skills 安装与维护 |
+| [docs/user-guide/spec-ticket-migration-guide.md](./docs/user-guide/spec-ticket-migration-guide.md) | 旧规格与任务入口迁移指南 |
 | [docs/discovery/IDEATION.md](./docs/discovery/IDEATION.md) | 机会构想方法 |
 | [docs/architecture/README.md](./docs/architecture/README.md) | 架构设计 + 审查清单 |
 | [docs/testing/README.md](./docs/testing/README.md) | 测试策略 |
@@ -131,8 +117,8 @@ scripts/verify-template
 
 | 模板 | 用途 |
 |------|------|
-| [docs/templates/prd-template.md](./docs/templates/prd-template.md) | PRD，包含 OpenAPI 影响、测试决策、AI / 人工审查点 |
-| [docs/templates/vertical-slice-issue-template.md](./docs/templates/vertical-slice-issue-template.md) | 垂直切片 Issue |
+| [docs/templates/spec-template.md](./docs/templates/spec-template.md) | Spec，包含 OpenAPI 影响、测试决策、AI / 人工审查点 |
+| [docs/templates/vertical-slice-ticket-template.md](./docs/templates/vertical-slice-ticket-template.md) | 垂直切片 Ticket |
 | [docs/templates/agent-brief-template.md](./docs/templates/agent-brief-template.md) | `triage` 产出的 Agent Brief |
 | [docs/templates/implementation-repo-registry-template.md](./docs/templates/implementation-repo-registry-template.md) | 外部实现仓库登记 |
 | [docs/templates/cross-repo-slice-template.md](./docs/templates/cross-repo-slice-template.md) | 跨仓库垂直切片记录 |

package/template/docs/adr/{adr-product-design-prototype-entrypoint.md → 0001-product-design-prototype-entrypoint.md}

@@ -1,4 +1,4 @@
-# ADR-001: 使用 product-design:index 作为产品原型主入口
+# ADR-0001: 使用 product-design:index 作为产品原型主入口
 
 ## 状态
 
@@ -16,7 +16,7 @@ YSS Harness 需要把有 UI 功能的产品原型产出收敛到一个稳定入
 
 产品原型产出统一以 `product-design:index` 为主入口。该 skill 只负责路由，实际按 Product Design plugin 规则进入 `$get-context`、`$ideate`、`$prototype`、`$image-to-code`、`$url-to-code`、`$design-qa` 或 `$share` 等 focused skill。
 
-`grill-with-docs` 保留为前置需求质询和领域边界澄清工具，不承担 HTML 原型产出。`antd` skill / `antd` CLI 作为 Ant Design v6 组件、demo、token、semantic 和 design.md 的事实来源。YSS 生命周期继续负责 `prototype-review`、用户确认、PRD 回填和 OpenAPI Draft 门禁。
+`grill-with-docs` 保留为前置需求质询和领域边界澄清工具，不承担 HTML 原型产出。`antd` skill / `antd` CLI 作为 Ant Design v6 组件、demo、token、semantic 和 design.md 的事实来源。YSS 生命周期继续负责 `prototype-review`、用户确认、Spec 回填和 OpenAPI Draft 门禁。
 
 ## 考虑的替代方案
 
@@ -43,7 +43,7 @@ YSS Harness 需要把有 UI 功能的产品原型产出收敛到一个稳定入
 
 - 如果 Agent 未读取 Product Design focused skill，可能误把 `product-design:index` 当作直接产出技能。
 - 如果跳过 `antd` CLI 查询，原型可能偏离 Ant Design v6 组件 API 或 token。
-- 如果缺少用户确认记录，下游 PRD 校准和 OpenAPI Draft 会失去体验冻结依据。
+- 如果缺少用户确认记录，下游 Spec 校准和 OpenAPI Draft 会失去体验冻结依据。
 
 ## 相关
 

package/template/docs/adr/0002-yss-project-repository-mode.md

@@ -0,0 +1,3 @@
+# ADR-0002: 使用 `yss-project.yaml` 声明仓库身份
+
+模板源仓库与模板实例仓库共享大部分目录和流程资产，仅靠目录、Git 远程或占位符推断身份会导致 Agent 选错流程。因此在根目录使用 `yss-project.yaml` 作为 CLI 与 Agent 共享的稳定契约，只声明 `schema_version` 和 `repository_mode`：模板源仓库使用 `template-source`，`create-yss-spec` 生成的仓库使用 `project-instance`。项目名称、团队规模和 Tracker 等易变信息不放入该清单，避免形成新的重复配置源。

package/template/docs/agents/README.md

@@ -1,24 +1,23 @@
 # Agent 协作说明
 
-本目录存放给团队和 AI Agent 阅读的协作规范，用来说明 Issue、Triage、领域文档和 skills 维护方式。这里不是可执行的 skills 目录。
+本目录存放给团队和 AI Agent 阅读的协作规范，用来说明 Ticket、Triage、领域文档和 skills 维护方式。这里不是可执行的 skills 目录。
 
 ## 与隐藏目录的区别
 
 | 路径 | 用途 |
 |---|---|
 | `.agents/` | Agent 可加载的 Engineering Skills、脚本、prompt 和参考材料 |
-| `.agent/` | Matt engineering skills 与通用 Agent 工作流 |
-| `.codex/skills/` | Codex 项目级 skills，包含 YSS、Matt、Issue 等能力 |
+| `.codex/skills/` | Codex 项目级 skills，包含 YSS、Matt、Ticket 等能力 |
 | `docs/agents/` | 人和 AI 都可读的协作说明、标签约定、维护规范 |
 
 ## 当前文档
 
 | 文档 | 说明 |
 |---|---|
-| `issue-tracker.md` | Issue / PRD / triage 在 GitLab Issues 与 GitHub Issues 间路由的操作约定 |
+| `issue-tracker.md` | Ticket / Spec / triage 在 GitLab Issues 与 GitHub Issues 间路由的操作约定 |
 | `triage-labels.md` | 标准五态 triage 标签与含义 |
 | `domain.md` | 领域文档读取和维护规则 |
 | `skills-maintenance.md` | Engineering Skills 的安装、升级和验证说明 |
 | `gitlab-workflow-skills.md` | GitLab、MR、CI 和自动 gitworks 的技能配置与使用规则 |
 
-当 `AGENTS.md` 或某个 skill 提到本目录时，应优先把这里当作项目协作规则读取；真正的 skill 执行入口仍在 `.agents/`、`.agent/` 或 `.codex/skills/`。
+当 `AGENTS.md` 或某个 skill 提到本目录时，应优先把这里当作项目协作规则读取；真正的 skill 执行入口仍在 `.agents/` 或 `.codex/skills/`。

package/template/docs/agents/domain.md

@@ -1,12 +1,10 @@
-# Domain Docs
+# 领域文档
 
-> 中文说明：本文规定 Agent 在做需求、Issue、架构或实现前如何读取领域上下文。领域词汇统一放在根目录 `CONTEXT.md`，架构决策放在 `docs/adr/`，避免每个任务重新解释业务概念。
+本文规定 Engineering Skills 在探索仓库、起草 Ticket、设计架构或实施代码前，如何读取和使用领域文档。
 
-Engineering skills should consume this repo's domain documentation before exploring code or drafting issues.
+## 文档布局
 
-## Layout
-
-This repo uses a single-context layout:
+本仓库采用单上下文布局：
 
 ```text
 /
@@ -15,17 +13,17 @@ This repo uses a single-context layout:
 └── docs/
 ```
 
-## Before Exploring
+## 探索前读取规则
 
-Read these files when relevant:
+根据任务影响范围读取：
 
-- `CONTEXT.md` for domain vocabulary.
-- `docs/adr/` for architectural decisions related to the area being touched.
+- `CONTEXT.md`：领域术语和统一语言。
+- `docs/adr/`：与当前任务相关的架构决策。
 
-If a file does not exist yet, proceed silently. The `domain-modeling` skill creates or updates domain docs lazily when real terms or decisions are resolved.
+如果文件尚不存在，继续执行即可，不需要将缺失本身报告为问题。`domain-modeling` skill 会在形成稳定术语或架构决策时按需创建或更新领域文档。
 
-## Usage Rules
+## 使用规则
 
-- Use glossary vocabulary in PRDs, issue titles, tests, architecture notes, and implementation summaries.
-- Do not put implementation details in `CONTEXT.md`; it is a glossary, not a spec.
-- If a proposal contradicts an ADR, call out the conflict explicitly before proceeding.
+- 在 Spec、Ticket 标题、测试、架构说明和实施总结中使用 `CONTEXT.md` 定义的术语。
+- 不在 `CONTEXT.md` 中记录实现细节；它是领域词汇表，不是需求或实现规格。
+- 如果提案与现有 ADR 冲突，必须在继续执行前明确指出冲突。

package/template/docs/agents/gitlab-workflow-skills.md

@@ -6,14 +6,14 @@
 
 当项目主远端为 GitLab 时，默认使用 GitLab 作为代码托管、Merge Request、CI/CD 和工作流协作入口。
 
-PRD、Issue 和 triage 不在本文中写死到 GitLab；它们按 `docs/agents/issue-tracker.md` 在 GitLab / GitHub 间路由。
+Spec、Ticket 和 triage 不在本文中写死到 GitLab；它们按 `docs/agents/issue-tracker.md` 在 GitLab / GitHub 间路由。
 
 已集成能力：
 
 | 能力 | 工具 / Skill | 用途 |
 |---|---|---|
 | GitLab API 与项目查询 | `gitlab-workflow` skill | 查询项目、clone 地址、创建 group / project、执行分支化 git workflow |
-| GitLab CLI | `glab` | 管理 MR、Issue、CI、Pipeline、Release、变量、Runner 等 |
+| GitLab CLI | `glab` | 管理 MR、Ticket、CI、Pipeline、Release、变量、Runner 等 |
 | 项目快捷入口 | `scripts/gitworks` | 在当前仓库内统一执行 status、workflow、MR、CI 命令 |
 | Git 推送认证 | macOS Keychain + HTTPS token | 让 `git push`、workflow push 能非交互执行 |
 
@@ -39,12 +39,12 @@ GitLab 基础配置文件：
 
 - 文件权限应为 `600`。
 - token 不得写入仓库文件。
-- token 不得出现在脚本、文档、Issue、MR 描述或提交信息中。
+- token 不得出现在脚本、文档、Ticket、MR 描述或提交信息中。
 - token 至少需要 `read_api`；若要推送代码，需要 `write_repository`；若要创建 MR、管理 CI 或项目资源，建议具备对应 API 权限。
 
 ## 3. glab 配置
 
-`glab` 用于操作 GitLab MR / CI / Issue / Release。
+`glab` 用于操作 GitLab MR / CI / Ticket / Release。
 
 自托管 GitLab 配置示例：
 
@@ -112,7 +112,7 @@ scripts/gitworks ci-status
 
 1. 读取项目状态：`scripts/gitworks status`。
 2. 需要 GitLab API / clone / push workflow 时，使用 `gitlab-workflow` skill。
-3. 需要 MR / CI / Pipeline 时，使用 `glab` 或 `scripts/gitworks`；需要 Issue / PRD / triage 时，先按 `docs/agents/issue-tracker.md` 判断 GitLab 或 GitHub。
+3. 需要 MR / CI / Pipeline 时，使用 `glab` 或 `scripts/gitworks`；需要 Ticket / Spec / triage 时，先按 `docs/agents/issue-tracker.md` 判断 GitLab 或 GitHub。
 4. 执行自动提交前，必须先检查工作区脏文件，避免把无关 `.agents/`、`.codex/`、本机配置或用户未确认文件混入提交。
 5. 不直接提交到受保护主分支；默认使用 `feature/*`、`fix/*`、`chore/*` 分支。
 6. 自动 workflow 只在用户明确授权提交/推送时执行。

package/template/docs/agents/issue-tracker.md

@@ -1,10 +1,10 @@
-# Issue Tracker: GitLab / GitHub
+# Ticket 追踪平台：GitLab / GitHub
 
-> 中文说明：本文规定项目的 PRD、垂直切片 Issue 和 triage 结果必须支持 GitLab Issues 与 GitHub Issues。Agent 不得把 issue tracker 写死为 GitHub 或 GitLab；应按用户明确选择、当前仓库主远端和可用凭据决定发布平台。
+> 本文规定项目的 Spec、功能父 Ticket、垂直切片 Ticket 和 triage 结果必须支持 GitLab Issues 与 GitHub Issues。Agent 不得把 tracker 写死为 GitHub 或 GitLab；应按用户明确选择、当前仓库主远端和可用凭据决定发布平台。
 
 ## 平台选择规则
 
-按以下优先级选择 issue tracker：
+按以下优先级选择 Ticket tracker：
 
 1. 用户明确指定平台时，使用用户指定的平台。
 2. 用户未指定时，优先使用当前仓库主远端 `origin` 对应的平台。
@@ -13,20 +13,21 @@
 
 ## 规格流程状态同步
 
-规格、生命周期和交付任务状态必须同步到当前选定 issue tracker。同步平台仍按“平台选择规则”确定：用户定 GitLab 就同步 GitLab，用户定 GitHub 就同步 GitHub；用户未指定时，以主远端对应平台为准。
+规格、生命周期和交付任务状态必须同步到当前选定 Ticket tracker。同步平台仍按“平台选择规则”确定：用户定 GitLab 就同步 GitLab，用户定 GitHub 就同步 GitHub；用户未指定时，以主远端对应平台为准。
 
 必须同步的节点：
 
-- PRD / 需求冻结 / OpenAPI Freeze / Issue change 创建完成时，创建或更新对应 Issue，并记录本地资产路径。
-- 垂直切片进入实现前，必须在对应平台存在可追踪 Issue；Issue 需要包含切片范围、阻塞关系、验收标准、测试 seam 和人工审查点。
-- 每个切片或生命周期阶段完成时，必须更新对应 Issue 的评论、标签、状态或里程碑，说明完成范围、验证命令、fresh verification 结果、剩余风险和下一步。
-- 阶段性议程、里程碑或 sprint planning 已经存在时，应把相关 PRD / change / slice Issue 归入同一议程，避免只在本地文档里记录进度。
-- 触碰安全红线时，必须在 Issue 中标记 `ready-for-human` 或写明 `TODO-HUMAN-REVIEW`，并列出需要人工确认的范围。
+- Spec 初稿形成时创建或更新功能父 Ticket，并使用 `ready-for-human` 记录本地资产路径与待审查项。
+- 需求冻结和 OpenAPI Freeze 完成后，在功能父 Ticket 汇总冻结证据，再创建垂直切片子 Ticket。
+- 垂直切片进入实现前，必须在对应平台存在可追踪 Ticket；其范围、阻塞关系、验收标准、测试 seam 和人工审查点必须完整。只有解除阻塞且可直接执行的前沿切片可标记 `ready-for-agent`。
+- 每个切片或生命周期阶段完成时，更新对应平台对象的评论、标签、状态或里程碑，说明完成范围、验证命令、fresh verification 结果、剩余风险和下一步。
+- 阶段性议程、里程碑或 sprint planning 已存在时，将同一功能的父 Ticket 和垂直切片子 Ticket 归入同一议程，避免只在本地文档记录进度。
+- 存在需要人工确认的风险时，必须在对应 Ticket 中写明范围、责任人、结论或待补齐事项。
 
 同步证据要求：
 
-1. 本地生命周期文档应记录目标平台、Issue 编号 / URL、发布时间或最近同步时间。
-2. Git checkpoint 报告应说明 Issue 同步状态：已同步、暂缓同步或平台不可用。
+1. 本地生命周期文档应记录目标平台、Ticket 编号 / URL、发布时间或最近同步时间。
+2. Git checkpoint 报告应说明 Ticket 同步状态：已同步、暂缓同步或平台不可用。
 3. 不得把“完成 / 可合并 / 可发布”只写在本地文件里；必须同步到目标平台，并附 fresh verification 证据或明确阻断项。
 4. 若同步平台不可用，本地草案必须标记“待发布平台”，恢复后优先补同步。
 
@@ -60,7 +61,7 @@ GitLab 相关配置和 MR / CI 工作流见 `docs/agents/gitlab-workflow-skills.
 
 ## Triage Surface
 
-Issue 是默认 triage surface。MR / PR 是否纳入 triage 取决于当前平台和用户请求：
+Ticket 是默认 triage surface。MR / PR 是否纳入 triage 取决于当前平台和用户请求：
 
 - GitLab 项目：可按需读取 GitLab Issues、Merge Requests 和 Pipeline 状态。
 - GitHub 项目：可按需读取 GitHub Issues、Pull Requests 和 Actions 状态。
@@ -71,9 +72,9 @@ Issue 是默认 triage surface。MR / PR 是否纳入 triage 取决于当前平
 当 skill 说 “publish to the issue tracker” 时：
 
 1. 先按“平台选择规则”确定 GitLab 或 GitHub。
-2. 在目标平台创建或更新 Issue。
+2. 在目标平台创建或更新对应 Ticket 对象。
 3. 在本地对应文档中记录平台、URL / 编号和发布时间。
-4. 若目标平台不可用，生成 `docs/requirements/issues/` 下的本地草案，并标注“待发布平台”。
+4. 若目标平台不可用，生成 `docs/requirements/tickets/` 下的本地草案，并标注“待发布平台”。
 
 当 skill 说 “fetch the relevant ticket” 时：
 

package/template/docs/agents/skills-maintenance.md

@@ -1,126 +1,61 @@
-# Skills Maintenance
-
-> 中文说明：本文说明本仓库内置 Engineering Skills 的来源、安装位置、升级步骤和验证命令。它是维护文档，不是 skill 本体；真正可被 Agent 加载的 `SKILL.md` 位于各项目 Agent roots 的 `skills/` 目录。
-
-本仓库默认使用项目内置技能快照，而不是只依赖用户全局 Codex / Hermes 技能目录。`skills-lock.json` 是来源、版本和技能清单的权威记录；`scripts/verify-template` 是落地校验入口。
-
-## Sources
-
-| Source | Ref | Path | 用途 |
-|---|---|---|---|
-| `mattpocock/skills` | `272f99b22574f50e4266791c86b9302682970e23` | `skills/engineering` | Matt Pocock Engineering Skills 主流程 |
-| `anthropics/knowledge-work-plugins` | `main` | `sales/skills/competitive-intelligence` | 竞品 / 市场事实研究 |
-
-## Installed Skills
-
-当前项目 Agent roots 必须同时具备以下技能：
-
-```text
-ask-matt
-competitive-intelligence
-grill-with-docs
-to-prd
-to-issues
-implement
-tdd
-diagnosing-bugs
-code-review
-domain-modeling
-codebase-design
-improve-codebase-architecture
-triage
-prototype
-research
-setup-matt-pocock-skills
-resolving-merge-conflicts
-```
-
-`ask-matt` 保持 Matt Pocock 上游正文不改；本项目通过 `yss-product-lifecycle` 把它的 idea -> ship 主流映射到 YSS 阶段门禁、OpenAPI Draft / Freeze、YSS routing、Git checkpoint 和 fresh verification。
+# Skills 维护说明
 
-## Project Agent Roots
+本文说明项目级 skills 的权威目录、投影方式、锁文件语义和升级验证。Agent 实际加载的入口仍是各目录中的 `SKILL.md`。
 
-| Agent | Project root |
-|---|---|
-| Agent | `.agent/skills/<skill-name>/` |
-| Agents | `.agents/skills/<skill-name>/` |
-| Claude | `.claude/skills/<skill-name>/` |
-| Codex | `.codex/skills/<skill-name>/` |
-| Hermes | `.hermes/skills/<skill-name>/` |
-| Pi | `.pi/skills/<skill-name>/` |
-| Trae | `.trae/skills/<skill-name>/` |
+## 权威内容与投影
 
-## Optional Local Workflow Tools
+- `.agents/skills` 是跨 Agent 共享技能的唯一权威内容。
+- `.claude/skills`、`.codex/skills`、`.hermes/skills`、`.pi/skills`、`.trae/skills` 中的同名共享技能是生成投影，不得分别手工修改。
+- 只属于某个平台的 skill 继续保留在对应 root，并由 `skills-lock.json` 的 `platform` 分组记录。
+- 共享技能投影可以是指向权威目录的符号链接，也可以是完整同步副本；`scripts/sync-skills --check` 会检查链接目标或完整目录哈希。
 
-除项目内置 Engineering Skills 外，维护者可按需使用本机级 GitLab 工作流工具；它们不是模板必须内置的技能目录。
+## 来源与锁定
 
-| Skill / Tool | Entry | 用途 |
+| 来源 | 固定版本 / 路径 | 用途 |
 |---|---|---|
-| `gitlab-workflow` | `$CODEX_HOME/skills/gitlab-workflow/` | GitLab API、项目查询、clone、push、分支化 workflow |
-| `glab` | `glab` | GitLab MR、CI、Pipeline、Issue、Release 等 CLI 操作 |
-| `scripts/gitworks` | `scripts/gitworks` | 当前仓库的 GitLab workflow 快捷入口 |
+| `mattpocock/skills` | `272f99b22574f50e4266791c86b9302682970e23` / `skills/engineering` | 通用工程流程 skills |
+| `anthropics/knowledge-work-plugins` | `sales/skills/competitive-intelligence` | 竞品与市场事实研究 |
+| 项目本地 | `.agents/skills` 或平台专属 root | YSS 适配与项目治理 skills |
 
-详细配置与使用规则见 `docs/agents/gitlab-workflow-skills.md`。
+`skills-lock.json` 是技能清单、来源、上游哈希、当前有效内容哈希和投影目标的权威记录：
 
-## Project-Level Harness / YSS Skills
+- `upstreamHash`：能够追溯时记录未经项目适配的上游内容哈希。
+- `effectiveHash`：当前实际生效的完整 skill 目录树哈希。
+- `targets`：权威内容应投影到的 Agent roots。
 
-本项目还维护以下项目级 Harness / YSS 集成技能：
+项目允许按 YSS 流程适配上游 skill，但必须同时保留可追溯的上游信息和适配后的有效哈希。
 
-| Skill | Path | 用途 |
-|---|---|---|
-| `implementation-repo-onboarding` | `.codex/skills/implementation-repo-onboarding/` | 接入已有前端 / 后端实现仓库，生成登记、基线发现和验证命令 |
-| `cross-repo-implementation-routing` | `.codex/skills/cross-repo-implementation-routing/` | 路由跨仓库实现任务，绑定 MR / PR 和验证证据 |
-| `yss-frontend-scaffold-generator` | `.codex/skills/yss-frontend-scaffold-generator/` | 基于标准 YSS 前端模板定义 0-1 前端工程生成流程 |
+## 维护流程
+
+1. 在临时目录读取或下载锁定来源，不直接覆盖工作区。
+2. 只在 `.agents/skills/<skill-name>/` 修改共享技能；平台专属技能只在所属 root 修改。
+3. 修改流程型 skill 时按 `writing-skills` 记录 RED 基线、压力场景、GREEN 结果和 REFACTOR 检查。
+4. 生成共享投影并更新锁文件：
+
+   ```bash
+   scripts/sync-skills
+   scripts/update-skill-lock
+   ```
 
-这些技能只定义流程、输入输出和安全边界；除非用户明确授权，不直接 clone 到 Harness 仓库、创建远端仓库、提交或推送代码。
+   新增共享 skill 时先显式登记：`scripts/update-skill-lock --add=<skill-name>`；新增平台专属 skill 使用 `scripts/update-skill-lock --add-platform=<root>:<skill-name>`。脚本不会把工作区中偶然出现的未跟踪目录自动纳入发布清单。
 
-## Upgrade Checklist
+5. 执行发布阻断校验：
 
-1. 读取 `skills-lock.json`，确认 Matt 快照 ref、`competitive-intelligence` 额外来源和技能清单。
-2. 拉取或下载对应来源到临时目录，不直接覆盖工作区。
-3. 将锁定技能同步到全部 7 个项目 Agent roots。
-4. 保留 `ask-matt` 上游正文不改；项目差异写入 `yss-product-lifecycle`、流程文档或维护说明。
-5. 检查每个技能目录都有合法 `SKILL.md` frontmatter，至少包含 `name` 和 `description`。
-6. 运行 `scripts/verify-template`。
-7. 重启需要重新加载技能的 Agent 客户端。
+   ```bash
+   scripts/verify-template
+   ```
 
-## Verification Command
+6. 需要重新加载技能的客户端在变更落地后重启或刷新项目。
+
+## 单独检查
 
 ```bash
-skills=(
-  ask-matt
-  competitive-intelligence
-  grill-with-docs
-  to-prd
-  to-issues
-  implement
-  tdd
-  diagnosing-bugs
-  code-review
-  domain-modeling
-  codebase-design
-  improve-codebase-architecture
-  triage
-  prototype
-  research
-  setup-matt-pocock-skills
-  resolving-merge-conflicts
-)
-
-roots=(
-  .agent/skills
-  .agents/skills
-  .claude/skills
-  .codex/skills
-  .hermes/skills
-  .pi/skills
-  .trae/skills
-)
-
-for root in "${roots[@]}"; do
-  for skill in "${skills[@]}"; do
-    test -f "$root/$skill/SKILL.md" || echo "missing $root/$skill/SKILL.md"
-  done
-done
-
-scripts/verify-template
+scripts/sync-skills --check
+scripts/update-skill-lock --check
 ```
+
+前者检查所有共享投影是否指向或匹配权威内容，后者检查 `skills-lock.json` 是否与当前完整目录树一致。过时技能不会保留兼容别名；旧版项目按 `docs/user-guide/spec-ticket-migration-guide.md` 一次性迁移。
+
+## 外部工作流工具
+
+维护者可按需使用本机的 `gitlab-workflow`、`glab`、`gh` 或 `scripts/gitworks`。这些工具不是共享技能投影的一部分；平台选择与发布规则见 `docs/agents/issue-tracker.md`。

package/template/docs/agents/triage-labels.md

@@ -1,15 +1,13 @@
-# Triage Labels
+# Triage 标签
 
-> 中文说明：本文定义 Agent 分诊时使用的标准五态标签。无论 skill 内部使用什么描述，落到 GitLab Issue 或 GitHub Issue 时都应映射为这里列出的标签。
+本文定义 Agent 分诊时使用的五种标准角色，以及它们在当前 Ticket tracker 中对应的标签。
 
-The engineering skills use five canonical triage roles. This file maps those roles to the label strings used in this repo's issue tracker.
+| 标准角色 | Tracker 标签 | 含义 |
+| --- | --- | --- |
+| `needs-triage` | `needs-triage` | 等待维护者评估 Ticket |
+| `needs-info` | `needs-info` | 等待报告者补充信息 |
+| `ready-for-agent` | `ready-for-agent` | 必要门禁已通过、阻塞边已清除，可由 Agent 直接实现的垂直切片 Ticket |
+| `ready-for-human` | `ready-for-human` | Spec、设计、契约草案或其他资产需要人工审查、判断或特权访问 |
+| `wontfix` | `wontfix` | 不会处理 |
 
-| Canonical role | Tracker label | Meaning |
-|---|---|---|
-| `needs-triage` | `needs-triage` | Maintainer needs to evaluate this issue |
-| `needs-info` | `needs-info` | Waiting on reporter for more information |
-| `ready-for-agent` | `ready-for-agent` | Fully specified and ready for an AFK agent |
-| `ready-for-human` | `ready-for-human` | Requires human implementation, judgment, or privileged access |
-| `wontfix` | `wontfix` | Will not be actioned |
-
-When a skill mentions a role, use the corresponding tracker label from this table.
+当 skill 提及某个标准角色时，使用表中对应的 Tracker 标签。

package/template/docs/api/templates/openapi-draft-review-checklist.md

@@ -2,7 +2,7 @@
 
 > 用于 API 影响分析 / 契约草案 / OpenAPI Draft 进入 Engineering Baseline / YSS DDD Review 之前。
 > OpenAPI Draft 在 OpenAPI Freeze 前仅用于评审和架构反审，不得作为前后端实现或生成客户端的稳定契约。
-> 评审采用 fail-closed：阻断项未关闭前，不进入架构 / 系统 / 数据架构设计。
+> 评审采用阻断项闭环：阻断项未关闭前，不进入架构 / 系统 / 数据架构设计。
 
 ## 输入资产
 
@@ -10,7 +10,7 @@
 |---|---|---|
 | API 影响记录 / 契约草案 | issue note / design note / `docs/api/specs/<feature>.yaml` |  |
 | OpenAPI Draft | `docs/api/specs/<feature>.yaml` |  |
-| PRD / 需求冻结 |  |  |
+| Spec / 需求冻结 |  |  |
 | 产品总体设计 / 功能架构 |  |  |
 | 交互说明 / 页面清单 | `docs/design/<feature>-interaction-spec.md` |  |
 | 原型 / 线框图 |  |  |
@@ -34,7 +34,7 @@
 | Draft 成熟度 | 明确当前仅为 review-only；实现、生成 client、契约测试固化均等待 OpenAPI Freeze |  |  |
 | OpenAPI 语法 | YAML、`$ref`、path 参数、lint 通过 |  |  |
 | P0 覆盖 | 每个 P0 需求有 endpoint/schema/error/test 或明确非目标 |  |  |
-| 产品总体设计完整 | Draft 已依据 PRD 和产品总体设计 / 功能架构；缺产品总体设计时返回上游补齐 |  |  |
+| 产品总体设计完整 | Draft 已依据 Spec 和产品总体设计 / 功能架构；缺产品总体设计时返回上游补齐 |  |  |
 | 交互输入完整 | 有 UI 时，Draft 已同时依据交互说明、原型/线框、状态矩阵、prototype-review、Ant Design v6 高保真 HTML 原型、AntD CLI 校验证据和用户确认记录；无 UI 时需说明页面 / 交互资产不适用原因 |  |  |
 | DDD 契约边界 | Endpoint/schema 归属的限界上下文清楚；术语与 `CONTEXT.md` 和功能架构一致；契约不直接暴露内部聚合、Repository 或持久化表结构 |  |  |
 | 页面动作覆盖 | 每个按钮 / 抽屉 / 弹窗动作有 endpoint/non-goal、`actionKey`、权限和错误码 |  |  |
@@ -43,7 +43,7 @@
 | 权限 | 无权不泄露数据；禁用动作返回 disabledReason；越权调用 403 |  |  |
 | 错误结构 | 模型级、字段级、行级错误可定位；关键 422 有 examples |  |  |
 | 乐观锁 / 幂等 | 草稿写入有 draftVersion；关键命令有幂等键 |  |  |
-| 安全红线 | 认证授权、SQL/DDL 草案、下载 URL、审计日志、敏感字段有人工审查项 |  |  |
+| 风险 / 人工确认项 | 认证授权、SQL/DDL 草案、下载 URL、审计日志、敏感字段的验证证据和责任人已记录 |  |  |
 | 契约测试 | 导入、覆盖率、检查、评审、发布、导出、权限、冲突场景可测 |  |  |
 
 ## 结论

package/template/docs/api/templates/openapi-freeze-record-template.md

@@ -16,7 +16,7 @@ owner: ai
 |------|-------------|------|------|
 | OpenAPI Draft |  |  |  |
 | OpenAPI Draft Review |  |  |  |
-| PRD / 需求冻结 |  |  |  |
+| Spec / 需求冻结 |  |  |  |
 | 产品设计 / 状态矩阵 |  |  |  |
 | 工程基线 / 系统 / 数据架构 |  |  |  |
 | Design Review |  |  |  |
@@ -38,12 +38,12 @@ owner: ai
 | 权限 / 并发 / 幂等明确 | 通过 / 阻断 / 不适用 |  |
 | YSS 统一响应包装明确 | 通过 / 阻断 |  |
 | 契约测试 seam 明确 | 通过 / 阻断 |  |
-| 安全红线已处理 | 通过 / 阻断 / 不适用 |  |
+| 风险 / 人工确认项已处理 | 通过 / 阻断 / 不适用 |  |
 
 ## 4. 冻结后变更规则
 
 - 冻结后如需改变路径、请求 / 响应 schema、错误结构、权限或分页规则，必须回到 OpenAPI Draft Review 和 Design Review。
-- 行为规格变化影响接口时，必须同步回写 `docs/api/specs/<feature>.yaml` 和 OpenAPI Draft 或 PRD 验收场景。
+- 行为规格变化影响接口时，必须同步回写 `docs/api/specs/<feature>.yaml` 和 OpenAPI Draft 或 Spec 验收场景。
 - 前后端实现必须以本记录引用的冻结版本为准。
 
 ## 5. 完成标准
@@ -51,10 +51,10 @@ owner: ai
 - [ ] OpenAPI Draft Review 无阻断项。
 - [ ] Design Review 无阻断项。
 - [ ] 前端、后端、API 契约测试均可消费冻结契约。
-- [ ] Issue change formalization 可引用本冻结记录。
+- [ ] Ticket 正式化 可引用本冻结记录。
 
 ## 6. 下一步门禁
 
 - 结论：Approved / Blocked
-- 下一步：Issue change formalization
+- 下一步：Ticket 正式化
 - 阻断项：