create-yss-spec 2.1.9 → 2.1.11

package/template/.cursor/skills/yss-web-controller/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: yss-web-controller
+description: Use when generating or refactoring YSS Web Adapter Controllers, request DTOs, response VOs, validation, result wrappers, or Web Convertors from frozen contracts and stable Application interfaces.
+---
+
+# yss-web-controller
+
+这是一个 Web 适配层生成型 skill。优先复用脚本 `scripts/generate_controller.mjs` 和模板，不手写重复 CRUD。
+
+## 何时使用
+
+- 用户要批量生成 Controller。
+- 用户要根据 metadata 或已有 Domain Gateway 生成 `AddCmd / UpdateCmd / PageQuery / VO / Controller / WebConvertor`。
+- 用户要求统一 Web Adapter 风格、返回值和接口路径。
+
+## 不适用
+
+- 用户只是要新增一个手写复杂接口，不一定要用脚本。
+- 用户还没有稳定的领域模型或 metadata，先补 `yss-domain` 并准备完整的 metadata 输入。
+
+## 优先流程
+
+1. 先确认冻结 OpenAPI/no-impact record、Application Service 接口、metadata、基础包、模块名、领域 segment、domain/web 落盘目录。
+2. 涉及 DTO / VO / CMD / Query POJO 样板代码时，加载并遵守 `lombok`。
+3. 涉及 Domain / Application Result 到 VO / DTO 或 CMD / Query 到输入模型的转换时，加载并遵守 `mapstruct`。
+4. 运行 `node scripts/generate_controller.mjs`。
+5. 生成后检查路径、命名、返回值包装、Application Service 引用、`@Valid`、Lombok 注解和 MapStruct WebConvertor 是否对齐项目。
+6. 对复杂接口做少量手工修正，不在 skill 中承诺自动覆盖全部业务逻辑。
+
+## 推荐命令
+
+```bash
+node scripts/generate_controller.mjs \
+  --metadata-file /path/metadata.json \
+  --base-package com.yss.demo \
+  --module-name demo \
+  --domain-segment example \
+  --domain-project-dir /path/demo-domain \
+  --web-project-dir /path/demo-adapter/demo-web \
+  --application-service-package com.yss.demo.application.service \
+  --validation-namespace javax \
+  --force
+```
+
+## 输出预期
+
+- `client/dto/cmd/*AddCmd.java`
+- `client/dto/cmd/*UpdateCmd.java`
+- `client/dto/query/*PageQuery.java`
+- `client/vo/*VO.java`
+- `rest/*Controller.java`
+- `rest/convertor/*WebConvertor.java`
+
+## 约束
+
+- 生成代码默认依赖既有 Application Service。只有批准合同明确标记的纯查询 CQRS 工作单元才允许直接读 Gateway；写操作禁止绕过 Application。
+- 返回结构保持项目既有 `SingleResult`、`PageResult`、`MultiResult` 体系。
+- DTO / VO / CMD / Query 默认用 Lombok 处理 getter/setter、constructor、builder 和日志样板；不要在 Controller 内部类或非约定包临时定义主要 DTO / VO。
+- `WebConvertor` 默认使用 MapStruct；禁止在 Controller / Application 中大段手写字段赋值、使用 `BeanUtils.copyProperties` 或反射式通用拷贝，除非有受控例外和测试证据。
+- 先跑脚本，再按项目规范做少量手调。
+- `javax` / `jakarta` validation namespace 必须来自工程基线，不得按记忆选择。
+- 若用户只是要改单个 Controller，先看现有代码，不要盲覆盖整个目录。
+
+## 按需读取
+
+- 分层开发规范：`references/web-adapter-layer-guide.md`
+- 生成脚本：`scripts/generate_controller.mjs`
+- Controller 模板：`assets/templates/Controller.java.template`
+- Convertor 模板：`assets/templates/WebConvertor.java.template`
+- POJO 样板代码：`lombok`
+- 对象转换：`mapstruct`
+
+## 阶段 7 合同
+
+- 只消费已批准合同和冻结 OpenAPI/no-impact record；不得用 Controller 或半成品 backend 反向定义产品契约。
+- DTO/VO/WebConvertor 机械骨架可用 `controlled-generation`；权限、错误映射、校验语义和接口行为必须使用 `behavior-tdd`。
+- 写入必须位于合同 `allowed_write_paths`，并提供 Controller、DTO/VO、WebConvertor、契约/API 测试和实际验证结果。
+- 按统一 `YSS Skill Execution Result` 返回偏离与新增影响；出现新 API/schema、权限或响应包装变化时暂停并回到 Router/生命周期。

package/template/.cursor/skills/yss-web-controller/agents/openai.yaml

@@ -0,0 +1,5 @@
+version: 1
+interface:
+  display_name: "YSS Web Controller"
+  short_description: "Web Controller、DTO、VO 与响应封装规范"
+  default_prompt: "Use $yss-web-controller to generate or refactor a YSS REST controller, request DTO, and response VO."

package/template/.cursor/skills/yss-web-controller/assets/templates/Controller.java.template

@@ -0,0 +1,73 @@
+package ${base_package}.rest;
+
+${application_service_import}
+${dto_imports}
+${domain_import}
+${web_convertor_import}
+import com.yss.cloud.dto.result.PageResult;
+import com.yss.cloud.dto.result.SingleResult;
+import lombok.RequiredArgsConstructor;
+import org.springframework.web.bind.annotation.*;
+import io.swagger.annotations.Api;
+import io.swagger.annotations.ApiOperation;
+import ${validation_namespace}.validation.Valid;
+
+/**
+ * ${domain_desc} 管理
+ *
+ * @author ${author}
+ */
+@RestController
+@RequestMapping("/api/${module_name}/${domain_url_path}")
+@RequiredArgsConstructor
+@Api(tags = "${domain_desc}管理")
+public class ${domain_class}Controller {
+
+    ${application_service_field}
+    private static final ${web_convertor_class} CONVERTOR = ${web_convertor_class}.INSTANCE;
+
+    /**
+     * 分页查询 ${domain_desc}
+     */
+    @PostMapping("/page")
+    @ApiOperation("分页查询")
+    public PageResult<${vo_class}> page(@Valid @RequestBody ${query_class} query) {
+        return CONVERTOR.toVOPage(${query_call});
+    }
+
+    /**
+     * 根据ID查询 ${domain_desc}
+     */
+    @GetMapping("/{id}")
+    @ApiOperation("详情查询")
+    public SingleResult<${vo_class}> detail(@PathVariable Long id) {
+        return SingleResult.of(CONVERTOR.toVO(${detail_call}));
+    }
+
+    /**
+     * 新增 ${domain_desc}
+     */
+    @PostMapping
+    @ApiOperation("新增")
+    public SingleResult<Long> add(@Valid @RequestBody ${add_cmd_class} cmd) {
+        return SingleResult.of(${add_call});
+    }
+
+    /**
+     * 更新 ${domain_desc}
+     */
+    @PutMapping
+    @ApiOperation("更新")
+    public SingleResult<Boolean> update(@Valid @RequestBody ${update_cmd_class} cmd) {
+        return SingleResult.of(${update_call});
+    }
+
+    /**
+     * 删除 ${domain_desc}
+     */
+    @DeleteMapping("/{id}")
+    @ApiOperation("删除")
+    public SingleResult<Boolean> delete(@PathVariable Long id) {
+        return SingleResult.of(${delete_call});
+    }
+}

package/template/.cursor/skills/yss-web-controller/assets/templates/WebConvertor.java.template

@@ -0,0 +1,23 @@
+package ${base_package}.rest.convertor;
+
+import com.yss.cloud.dto.result.PageResult;
+import ${base_package}.client.dto.cmd.${domain_class}AddCmd;
+import ${base_package}.client.dto.cmd.${domain_class}UpdateCmd;
+import ${base_package}.client.vo.${domain_class}VO;
+import ${base_package}.domain.${domain_pkg_name}.model.${domain_class};
+import org.mapstruct.Mapper;
+import org.mapstruct.factory.Mappers;
+
+@Mapper
+public interface ${web_convertor_class} {
+
+    ${web_convertor_class} INSTANCE = Mappers.getMapper(${web_convertor_class}.class);
+
+    ${domain_class} toDomain(${domain_class}AddCmd source);
+
+    ${domain_class} toDomain(${domain_class}UpdateCmd source);
+
+    ${domain_class}VO toVO(${domain_class} source);
+
+    PageResult<${domain_class}VO> toVOPage(PageResult<${domain_class}> source);
+}

package/template/.cursor/skills/yss-web-controller/assets/templates/domain/dto/cmd/AddCmd.java.template

@@ -0,0 +1,23 @@
+package ${base_package}.client.dto.cmd;
+
+import com.yss.cloud.dto.CommandDTO;
+import lombok.Data;
+import lombok.EqualsAndHashCode;
+import ${validation_namespace}.validation.constraints.NotBlank;
+import ${validation_namespace}.validation.constraints.NotNull;
+import java.util.Date;
+import java.math.BigDecimal;
+import java.time.LocalDateTime;
+import java.time.LocalDate;
+
+/**
+ * ${domain_desc} 新增命令
+ *
+ * @author ${author}
+ */
+@Data
+@EqualsAndHashCode(callSuper = true)
+public class ${domain_class}AddCmd extends CommandDTO {
+
+${field_declarations}
+}

package/template/.cursor/skills/yss-web-controller/assets/templates/domain/dto/cmd/UpdateCmd.java.template

@@ -0,0 +1,23 @@
+package ${base_package}.client.dto.cmd;
+
+import com.yss.cloud.dto.CommandDTO;
+import lombok.Data;
+import lombok.EqualsAndHashCode;
+import ${validation_namespace}.validation.constraints.NotBlank;
+import ${validation_namespace}.validation.constraints.NotNull;
+import java.util.Date;
+import java.math.BigDecimal;
+import java.time.LocalDateTime;
+import java.time.LocalDate;
+
+/**
+ * ${domain_desc} 更新命令
+ *
+ * @author ${author}
+ */
+@Data
+@EqualsAndHashCode(callSuper = true)
+public class ${domain_class}UpdateCmd extends CommandDTO {
+
+${field_declarations}
+}

package/template/.cursor/skills/yss-web-controller/assets/templates/domain/dto/query/PageQuery.java.template

@@ -0,0 +1,21 @@
+package ${base_package}.client.dto.query;
+
+import com.yss.cloud.dto.page.PageQuery;
+import lombok.Data;
+import lombok.EqualsAndHashCode;
+import java.util.Date;
+import java.math.BigDecimal;
+import java.time.LocalDateTime;
+import java.time.LocalDate;
+
+/**
+ * ${domain_desc} 分页查询
+ *
+ * @author ${author}
+ */
+@Data
+@EqualsAndHashCode(callSuper = true)
+public class ${domain_class}PageQuery extends PageQuery {
+
+${field_declarations}
+}

package/template/.cursor/skills/yss-web-controller/assets/templates/domain/vo/VO.java.template

@@ -0,0 +1,20 @@
+package ${base_package}.client.vo;
+
+import lombok.Data;
+import java.io.Serializable;
+import java.util.Date;
+import java.math.BigDecimal;
+import java.time.LocalDateTime;
+import java.time.LocalDate;
+
+/**
+ * ${domain_desc} VO
+ *
+ * @author ${author}
+ */
+@Data
+public class ${domain_class}VO implements Serializable {
+    private static final long serialVersionUID = 1L;
+
+${field_declarations}
+}

package/template/{.claude/skills/yss-backend-scaffold-web/SKILL.md → .cursor/skills/yss-web-controller/references/web-adapter-layer-guide.md}

@@ -1,10 +1,3 @@
----
-name: "yss-backend-scaffold-web"
-description: "YSS 管理服务的 Web Adapter 开发框架和技术指南。在实现 REST API 控制器、请求处理和响应格式化时需要用到。"
----
-
-# Web Adapter Layer Development Guide
-
 本技能为开发 YSS 服务的**Web 适配器层**（REST API）提供指导和框架。
 Web 适配器负责通过 HTTP 公开业务功能、处理输入验证和格式化响应。
 

package/template/.cursor/skills/yss-web-controller/scripts/generate_controller.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const TYPE_MAPPING = { bigint: "Long", int: "Integer", integer: "Integer", smallint: "Integer", tinyint: "Integer", number: "Long", numeric: "BigDecimal", decimal: "BigDecimal", float: "Float", double: "Double", real: "Float", varchar: "String", varchar2: "String", nvarchar2: "String", char: "String", nchar: "String", text: "String", clob: "String", nclob: "String", date: "LocalDateTime", datetime: "LocalDateTime", timestamp: "LocalDateTime", "timestamp with time zone": "LocalDateTime", boolean: "Boolean", bool: "Boolean", bit: "Boolean", json: "String", jsonb: "String", uuid: "String" };
+const required = ["metadata-file", "base-package", "module-name", "domain-segment"];
+const valued = new Set([...required, "output-dir", "domain-project-dir", "web-project-dir", "domain-output-dir", "web-output-dir", "author", "application-service-package", "validation-namespace"]);
+
+function usage() {
+  return "Usage: node generate_controller.mjs --metadata-file FILE --base-package PACKAGE --module-name NAME --domain-segment SEGMENT [--output-dir DIR] [--domain-project-dir DIR] [--web-project-dir DIR] [--domain-output-dir DIR] [--web-output-dir DIR] [--author NAME] [--force] [--application-service-package PACKAGE] [--validation-namespace javax|jakarta]";
+}
+export function parseArgs(argv) {
+  const args = { "output-dir": "./output", author: "System", "validation-namespace": "javax", force: false };
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (token === "--help" || token === "-h") return { help: true };
+    if (token === "--force") { args.force = true; continue; }
+    if (!token.startsWith("--") || !valued.has(token.slice(2))) throw new Error(`unrecognized argument: ${token}`);
+    const value = argv[++index];
+    if (!value || value.startsWith("--")) throw new Error(`argument ${token} requires a value`);
+    args[token.slice(2)] = value;
+  }
+  for (const key of required) if (!args[key]) throw new Error(`the following arguments are required: --${key}`);
+  if (!new Set(["javax", "jakarta"]).has(args["validation-namespace"])) throw new Error("--validation-namespace must be javax or jakarta");
+  return args;
+}
+const pascal = (value) => value.toLowerCase().split("_").map((part) => part ? part[0].toUpperCase() + part.slice(1) : "").join("");
+const lowerCamel = (value) => { const output = pascal(value); return output ? output[0].toLowerCase() + output.slice(1) : ""; };
+const kebab = (value) => value.toLowerCase().replaceAll("_", "-");
+const packagePath = (value) => value.replaceAll(".", path.sep);
+const ensureSubdir = (root, name) => path.basename(path.normalize(root)) === name ? root : path.join(root, name);
+const javaType = (sqlType = "") => TYPE_MAPPING[sqlType.toLowerCase().split("(")[0]] || "String";
+
+function fields(columns, { skipPk = false, command = false, skipAudit = true } = {}) {
+  const audit = new Set(["create_time", "update_time", "create_by", "update_by", "deleted", "version"]);
+  return columns.filter((column) => !(skipPk && column.primary) && !(skipAudit && audit.has(String(column.name).toLowerCase()))).map((column) => {
+    const type = javaType(column.sql_type);
+    const name = lowerCamel(column.name);
+    const comment = column.comment || "";
+    const documentation = comment ? `    /**\n     * ${comment}\n     */\n` : "";
+    const validation = command && !column.nullable ? `    @${type === "String" ? "NotBlank" : "NotNull"}(message = \"${comment || name}不能为空\")\n` : "";
+    return `${documentation}${validation}    private ${type} ${name};`;
+  }).join("\n\n");
+}
+function render(template, context) { return template.replace(/\$(?:\{([A-Za-z_][A-Za-z0-9_]*)\}|([A-Za-z_][A-Za-z0-9_]*))/g, (_, braced, plain) => { const key = braced || plain; if (!(key in context)) throw new Error(`missing template field: ${key}`); return context[key]; }); }
+async function exists(target) { try { await access(target); return true; } catch { return false; } }
+
+export async function generate(args, logger = console) {
+  if (!await exists(args["metadata-file"])) throw new Error(`Metadata file not found: ${args["metadata-file"]}`);
+  let metadata;
+  try { metadata = JSON.parse(await readFile(args["metadata-file"], "utf8")); } catch (error) { throw new Error(`Error reading metadata file: ${error.message}`); }
+  const tables = metadata.tables || [];
+  if (!tables.length) { logger.warn("Warning: No tables found in metadata."); return []; }
+  const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+  const templatesDir = path.resolve(scriptDir, "../assets/templates");
+  const template = async (name) => { const target = path.join(templatesDir, name); if (!await exists(target)) throw new Error(`Template not found: ${target}`); return readFile(target, "utf8"); };
+  const templates = Object.fromEntries(await Promise.all(["Controller.java.template", "WebConvertor.java.template", "domain/vo/VO.java.template", "domain/dto/cmd/AddCmd.java.template", "domain/dto/cmd/UpdateCmd.java.template", "domain/dto/query/PageQuery.java.template"].map(async (name) => [name, await template(name)])));
+  const basePath = packagePath(args["base-package"]);
+  const domainBase = args["domain-output-dir"] || (args["domain-project-dir"] ? path.join(args["domain-project-dir"], "src", "main", "java", basePath) : path.join(args["output-dir"], basePath));
+  const webBase = args["web-output-dir"] || (args["web-project-dir"] ? path.join(args["web-project-dir"], "src", "main", "java", basePath) : path.join(args["output-dir"], basePath));
+  const domainRoot = ensureSubdir(domainBase, "client");
+  const webRoot = ensureSubdir(webBase, "rest");
+  const written = [];
+  const write = async (target, contents) => { await mkdir(path.dirname(target), { recursive: true }); if (!await exists(target) || args.force) { await writeFile(target, contents, "utf8"); logger.log(`Generated: ${target}`); written.push(target); } else logger.log(`Skipped (exists): ${target}`); };
+  for (const table of tables) {
+    const domainClass = pascal(table.table_name); const domainVar = lowerCamel(table.table_name); const domainDesc = String(table.table_comment || domainClass).trim().replaceAll("\n", " ");
+    const applicationPackage = args["application-service-package"] || `${args["base-package"]}.application.service`;
+    const context = { base_package: args["base-package"], module_name: args["module-name"], domain_class: domainClass, domain_var: domainVar, domain_desc: domainDesc, domain_url_path: kebab(table.table_name), domain_pkg_name: args["domain-segment"], author: args.author, dto_imports: [`import ${args["base-package"]}.client.dto.cmd.${domainClass}AddCmd;`, `import ${args["base-package"]}.client.dto.cmd.${domainClass}UpdateCmd;`, `import ${args["base-package"]}.client.dto.query.${domainClass}PageQuery;`, `import ${args["base-package"]}.client.vo.${domainClass}VO;`].join("\n"), application_service_import: `import ${applicationPackage}.${domainClass}Service;`, domain_import: `import ${args["base-package"]}.domain.${args["domain-segment"]}.model.${domainClass};`, web_convertor_import: `import ${args["base-package"]}.rest.convertor.${domainClass}WebConvertor;`, web_convertor_class: `${domainClass}WebConvertor`, application_service_field: `private final ${domainClass}Service ${domainVar}Service;`, query_call: `${domainVar}Service.page(query)`, detail_call: `${domainVar}Service.detail(id)`, add_call: `${domainVar}Service.add(cmd)`, update_call: `${domainVar}Service.update(cmd)`, delete_call: `${domainVar}Service.delete(id)`, vo_class: `${domainClass}VO`, add_cmd_class: `${domainClass}AddCmd`, update_cmd_class: `${domainClass}UpdateCmd`, query_class: `${domainClass}PageQuery`, validation_namespace: args["validation-namespace"] };
+    await write(path.join(webRoot, `${domainClass}Controller.java`), render(templates["Controller.java.template"], context));
+    await write(path.join(webRoot, "convertor", `${domainClass}WebConvertor.java`), render(templates["WebConvertor.java.template"], context));
+    for (const [templateName, target, declaration] of [["domain/vo/VO.java.template", path.join(domainRoot, "vo", `${domainClass}VO.java`), fields(table.columns || [], { skipAudit: false })], ["domain/dto/cmd/AddCmd.java.template", path.join(domainRoot, "dto/cmd", `${domainClass}AddCmd.java`), fields(table.columns || [], { skipPk: true, command: true })], ["domain/dto/cmd/UpdateCmd.java.template", path.join(domainRoot, "dto/cmd", `${domainClass}UpdateCmd.java`), fields(table.columns || [], { command: true })], ["domain/dto/query/PageQuery.java.template", path.join(domainRoot, "dto/query", `${domainClass}PageQuery.java`), fields(table.columns || [])]]) await write(target, render(templates[templateName], { ...context, field_declarations: declaration }));
+  }
+  return written;
+}
+async function main() { try { const args = parseArgs(process.argv.slice(2)); if (args.help) { console.log(usage()); return; } await generate(args); } catch (error) { console.error(`Error: ${error.message}`); process.exitCode = 1; } }
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main();

package/template/.cursor/skills/yss-web-controller/scripts/generate_controller.test.mjs

@@ -0,0 +1,19 @@
+import assert from "node:assert/strict";
+import { mkdtemp, readFile, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { generate, parseArgs } from "./generate_controller.mjs";
+
+test("generates application-service controller with requested validation profile", async () => {
+  const root = await mkdtemp(path.join(tmpdir(), "yss-controller-"));
+  const metadata = path.join(root, "metadata.json");
+  await writeFile(metadata, JSON.stringify({ tables: [{ table_name: "quality_rule", table_comment: "质量规则", columns: [{ name: "id", sql_type: "bigint", primary: true, nullable: false }, { name: "rule_name", sql_type: "varchar(64)", nullable: false }] }] }));
+  await generate(parseArgs(["--metadata-file", metadata, "--base-package", "com.yss.demo", "--module-name", "demo", "--domain-segment", "quality", "--output-dir", path.join(root, "out"), "--application-service-package", "com.yss.demo.application.service", "--validation-namespace", "jakarta"]), { log() {}, warn() {} });
+  const controller = await readFile(path.join(root, "out", "com", "yss", "demo", "rest", "QualityRuleController.java"), "utf8");
+  assert.match(controller, /import com\.yss\.demo\.application\.service\.QualityRuleService;/);
+  assert.match(controller, /import jakarta\.validation\.Valid;/);
+  assert.doesNotMatch(controller, /Gateway/);
+});
+
+test("rejects missing required CLI arguments", () => assert.throws(() => parseArgs(["--module-name", "demo"]), /required/));

package/template/.hermes/skills/ask-matt/SKILL.md

@@ -8,9 +8,15 @@ disable-model-invocation: true
 
 You don't remember every skill, so ask.
 
+## YSS default (read this first)
+
+In this template, **`yss-product-lifecycle` is the default orchestrator**. Native work-units own Spec, tickets, implementation authorization, and gates.
+
+This skill is a **Matt compatibility map**. Use `/grill-with-docs`, `/to-spec`, `/to-tickets`, and `/implement` only when the user **explicitly** names them. Do not treat the idea→ship list below as the YSS default. `/implement` does not grant git commit/push. Spec drafts from `/to-spec` stay `ready-for-human` until a human approves the Spec baseline.
+
 A **flow** is a path through the skills. Most paths run along one **main flow**, and two **on-ramps** merge onto it. Everything else is standalone, or a vocabulary layer that runs underneath.
 
-## The main flow: idea → ship
+## Matt compatibility flow: idea → ship
 
 The route most work travels. You have an idea and want it built.
 
@@ -23,7 +29,7 @@ The route most work travels. You have an idea and want it built.
    - **Yes** → **`/to-spec`** (turn the thread into a spec), then **`/to-tickets`** to split it into tracer-bullet tickets, each declaring its **blocking edges**. On a local tracker that's one file per ticket under `docs/.scratch/<feature>/issues/`, worked blockers-first by hand; on a real tracker the edges become native blocking links, so any ticket whose blockers are done can be grabbed — kick off **`/implement`** per ticket, **`/clear`ing context between each one**. Each ticket is self-contained, so the last one's context is disposable.
    - **No** → **`/implement`** right here, in the same context window.
 
-   Either way, **`/implement`** builds each issue by driving **`/tdd`** internally — one red-green slice at a time — then closes out by running **`/code-review`**, a two-axis review (Standards + Spec) of the diff, before committing. Reach for **`/tdd`** on its own when you just want to build a concrete behaviour test-first without a full spec, and **`/code-review`** on its own whenever you want to review a branch or PR against a fixed point.
+   Either way, **`/implement`** builds each issue by driving **`/tdd`** internally — one red-green slice at a time — then closes out by running **`/code-review`** (Standards + Spec, plus UI fidelity when UI is in scope). Do not commit or push from `/implement`. Reach for **`/tdd`** on its own when you just want to build a concrete behaviour test-first without a full spec, and **`/code-review`** on its own whenever you want to review a branch or PR against a fixed point.
 
 ### Context hygiene
 

package/template/.hermes/skills/code-review/SKILL.md

@@ -3,12 +3,13 @@ name: code-review
 description: Use when the user wants to review a branch, PR, committed candidate, uncommitted work-in-progress changes, or changes since a fixed point.
 ---
 
-Two-axis review of a pinned candidate against a fixed point:
+Review of a pinned candidate against a fixed point on two core axes, plus UI fidelity when UI is in scope:
 
 - **Standards** — does the code conform to this repo's documented coding standards?
 - **Spec** — does the code faithfully implement the originating issue / spec?
+- **UI fidelity** (only when the change has UI impact) — does the candidate match the confirmed prototype and `yss-design-system` / `yss-ui`? Type-check or claiming "already aligned" is not a pass. Invoke those skills' verification notes; do not collapse this axis into Standards or Spec.
 
-Both axes run as **parallel sub-agents** so they don't pollute each other's context, then this skill aggregates their findings.
+Standards and Spec run as **parallel sub-agents** so they don't pollute each other's context, then this skill aggregates their findings. When UI is in scope, add a separate UI fidelity pass after those two reports (do not merge it into either axis).
 
 If `docs/agents/issue-tracker.md` is missing, tell the user to run `/setup-matt-pocock-skills`; do not invoke another user-invoked skill yourself.
 
@@ -99,17 +100,18 @@ If the spec is missing, skip the Spec sub-agent and note this in the final repor
 
 ### 5. Aggregate
 
-Present the two reports under `## Standards` and `## Spec` headings, verbatim or lightly cleaned. Do **not** merge or rerank findings — the two axes are deliberately separate (see _Why two axes_).
+Present the reports under `## Standards` and `## Spec` headings, verbatim or lightly cleaned. If UI is in scope, add `## UI fidelity` from the separate pass. Do **not** merge or rerank findings — the axes are deliberately separate (see _Why separate axes_).
 
 For Worktree mode, recapture the candidate digest after both reports return. If it differs from `candidate_digest`, mark both reports as reviewing a **stale candidate** and return `blocked`; the caller may start a new review against a new capture, but this invocation must not aggregate findings from different bytes. Recheck the same digest again at the completion/checkpoint boundary.
 
 State the reviewed `review_mode`, fixed point, candidate digest and coverage before the two reports. End with a one-line summary: total findings per axis, and the worst issue _within each axis_ (if any). Don't pick a single winner across axes — that's the reranking the separation exists to prevent.
 
-## Why two axes
+## Why separate axes
 
 A change can pass one axis and fail the other:
 
 - Code that follows every standard but implements the wrong thing → **Standards pass, Spec fail.**
 - Code that does exactly what the issue asked but breaks the project's conventions → **Spec pass, Standards fail.**
+- Code that implements the spec but diverges from the confirmed prototype or design system → **Spec pass, UI fidelity fail.**
 
 Reporting them separately stops one axis from masking the other.

package/template/.hermes/skills/diagnosing-bugs/SKILL.md

@@ -127,7 +127,7 @@ If a correct seam exists:
 4. Watch it pass.
 5. Re-run the Phase 1 feedback loop against the original (un-minimised) scenario.
 
-## Phase 6 — Cleanup + post-mortem
+## Phase 6 — Cleanup
 
 Required before declaring done:
 
@@ -135,6 +135,4 @@ Required before declaring done:
 - [ ] Regression test passes (or absence of seam is documented)
 - [ ] All `[DEBUG-...]` instrumentation removed (`grep` the prefix)
 - [ ] Throwaway prototypes deleted (or moved to a clearly-marked debug location)
-- [ ] The hypothesis that turned out correct is stated in the commit / PR message — so the next debugger learns
-
-**Then ask: what would have prevented this bug?** If the answer involves architectural change (no good test seam, tangled callers, hidden coupling) hand off to the `/improve-codebase-architecture` skill with the specifics. Make the recommendation **after** the fix is in, not before — you have more information now than when you started.
+- [ ] The hypothesis that turned out correct is stated in the commit / PR message, so the next debugger learns

package/template/.hermes/skills/domain-modeling/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: domain-modeling
-description: Build and sharpen a project's domain model. Use when the user wants to pin down domain terminology or a ubiquitous language, record an architectural decision, or when another skill needs to maintain the domain model.
+description: Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a CONTEXT.md, or recording or editing an ADR.
 ---
 
 # Domain Modeling

package/template/.hermes/skills/grilling/SKILL.md

@@ -7,11 +7,17 @@ Interview the user relentlessly until you reach a shared understanding. Map this
 
 Work the tree in **rounds**. The **frontier** is every decision whose prerequisites are already settled — the questions you can ask _now_ without guessing at answers you haven't heard yet. Ask the whole frontier in one round: number each question and give your recommended answer. Then wait for the user's answers before the next round.
 
-Each question should be formatted like so:
+Format a round like so:
 
 ```
 ❓ **Q1** - **<question title>**: <question body, might be multiple paragraphs, including multiple choices>
 
+➡️ <your recommended answer>
+
+---
+
+❓ **Q2** - **<question title>**: <question body, might be multiple paragraphs, including multiple choices>
+
 ➡️ <your recommended answer>
 ```
 

package/template/.hermes/skills/high-fidelity-html-prototype/SKILL.md

@@ -102,5 +102,5 @@ High-fidelity HTML prototype
 - <yes/no; list blocking gaps>
 
 ### 下一步
-- <Spec calibration / return to high-fidelity prototype / return to product-design-prototype>
+- <Spec calibration / return to high-fidelity prototype / return to yss-prototype-stage>
 ```

package/template/.hermes/skills/implement/SKILL.md

@@ -12,4 +12,4 @@ Run typechecking regularly, single test files regularly, and the full test suite
 
 Once done, use /code-review to review the work.
 
-Commit your work to the current branch.
+Do not commit or push. Implementation authorization does not include git commit/push. Natural language such as "do it and commit" is not structured Git authorization. Stop after review unless a structured Git authorization is already present.

package/template/.hermes/skills/to-spec/SKILL.md

@@ -16,7 +16,7 @@ If the issue tracker or triage label vocabulary is missing, tell the user to run
 
 Check with the user that these seams match their expectations.
 
-3. Write the spec using the template below, then publish it to the project issue tracker. Apply the `ready-for-agent` triage label - no need for additional triage.
+3. Write the spec using the template below, then publish it to the project issue tracker. Apply the `ready-for-human` triage label. Spec drafts need a human baseline approval before they are `approved`, and before implementation tickets may become `ready-for-agent`. Do not label the Spec itself `ready-for-agent`.
 
 <spec-template>
 

package/template/.hermes/skills/triage/SKILL.md

@@ -40,7 +40,7 @@ For a PR, the same states read against the attached code: `ready-for-agent` mean
 
 Every triaged issue should carry exactly one category role and one state role. If state roles conflict, flag it and ask the maintainer before doing anything else.
 
-These are canonical role names — the actual label strings used in the issue tracker may differ. The mapping should have been provided to you - run `/setup-matt-pocock-skills` if not.
+These are canonical role names. The actual label strings used in the issue tracker may differ. The mapping should have been provided to you. If not, tell the user to run `/setup-matt-pocock-skills`.
 
 State transitions: an unlabeled issue normally goes to `needs-triage` first; from there it moves to `needs-info`, `ready-for-agent`, `ready-for-human`, or `wontfix`. `needs-info` returns to `needs-triage` once the reporter replies. The maintainer can override at any time — flag transitions that look unusual and ask before proceeding.
 
@@ -73,7 +73,7 @@ Show counts and a one-line summary per item. Let the maintainer pick.
 
 3. **Verify the claim.** Before any grilling, check that the claim holds up. For a bug, reproduce it from the reporter's steps. For a PR, confirm the diff does what it claims — check it out, run the relevant tests or commands. Report what happened: confirmed (with code path), failed, or insufficient detail (a strong `needs-info` signal). A confirmed verification makes a much stronger agent brief.
 
-4. **Grill (if needed).** If the request needs fleshing out, run the `/grilling` and `/domain-modeling` skills together — grill it into shape a round of questions at a time, sharpening domain terms and updating `CONTEXT.md`/ADRs inline as decisions land.
+4. **Grill (if needed).** If the request needs fleshing out, call the Skill tool twice, for "grilling" and "domain-modeling", and grill it into shape a round of questions at a time, sharpening domain terms and updating `CONTEXT.md`/ADRs inline as decisions land.
 
 5. **Apply the outcome:**
    - `ready-for-agent` — post an agent brief comment ([AGENT-BRIEF.md](AGENT-BRIEF.md)).

package/template/.hermes/skills/wait-what/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: wait-what
-description: Stop. That last message did not land — re-pitch it.
+description: "Stop. That last message did not land: re-pitch it."
 disable-model-invocation: true
 ---
 
-Wait — I don't understand where you've got to here. Re-pitch that: give me a little bit of context, talk in ASD-STE100 Simplified Technical English, and use the ubiquitous language from `CONTEXT.md`.
+Wait, I don't understand where you've got to here. Re-pitch that: give me a little bit of context, talk in ASD-STE100 Simplified Technical English, and use the ubiquitous language from `CONTEXT.md` (follow `CONTEXT-MAP.md` to the right one if the repo has more than one).

package/template/.hermes/skills/wayfinder/SKILL.md

@@ -22,7 +22,7 @@ The map is a single issue on this repo's issue tracker, labelled `wayfinder:map`
 
 The map is an **index**, not a store. It lists the decisions made and points at the tickets that hold their detail; a decision lives in exactly one place — its ticket — so the map never restates it, only gists it and links.
 
-**Where the map, its child tickets, blocking, and frontier queries physically live is tracker-specific.** The issue tracker should have been provided to you — run `/setup-matt-pocock-skills` if not. Consult the tracker doc's "Wayfinding operations" section for how _this_ repo expresses them. If no tracker has been provided, default to the local-markdown tracker.
+**Where the map, its child tickets, blocking, and frontier queries physically live is tracker-specific.** The issue tracker should have been provided to you. If not, tell the user to run `/setup-matt-pocock-skills`. Consult the tracker doc's "Wayfinding operations" section for how _this_ repo expresses them. If no tracker has been provided, default to the local-markdown tracker.
 
 ### The map body
 

package/template/.hermes/skills/yss-api-integration/SKILL.md

@@ -5,6 +5,8 @@ description: Guide AI to correctly use Orval-generated API clients in Vue 3 micr
 
 # API 集成 Skill
 
+目录与锁文件身份是 `yss-api-integration`；Agent 发现名与 Router 闭包键是 `api-integration`。二者指向同一技能，注册表以 alias 对齐。
+
 ## 📋 目标
 
 帮助 AI 正确使用基于 **Orval** 生成的 API 客户端：