create-yss-spec 3.3.8 → 3.4.3

package/template/.codex/skills/data-analytics/skills/validate-data/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: validate-data
-description: "QA an analysis before sharing: review methodology, metric definitions, SQL/query logic, calculation checks, chart integrity, bias risks, caveats, reproducibility, and whether conclusions are supported by evidence. Use when reviewing a report, notebook, spreadsheet, SQL query/results, dashboard, chart, recommendation, or stakeholder-ready analysis before presentation or publication."
+description: "Review analytical methodology, calculations, sources, charts and conclusions before a report or analysis is shared."
 ---
 
 # Validate Data Analysis

package/template/.codex/skills/data-analytics/skills/visualize-data/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: visualize-data
-description: "Design, specify, implement, revise, and QA quantitative visuals and chart choices. Use when an analytical answer needs visual judgment; for example comparing values, showing how a total breaks apart, reading concentration in a ranking, or understanding movement over time. This may mean rendering a chart for a report or dashboard, or simply choosing, rendering and QAing the right chart form for an inline answer."
+description: "Choose, build or review quantitative charts for analytical answers, reports and dashboards."
 ---
 
 # Data Visualization

package/template/.codex/skills/file-export-download/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: file-export-download
-description: 指导 Vue3 YSS UI 微应用实现文件导出、报表下载、模板下载和附件下载，覆盖 OpenAPI binary 响应、Orval 生成方法检查、responseType blob 兜底、Blob 响应类型、Content-Disposition 文件名、handleBlobResponse、loading 与错误处理；当需求出现导出、下载、Excel、CSV、PDF、ZIP、Blob 或文件流时使用。
+description: "在 Vue3 YSS UI 中实现或修复文件下载与导出，处理 Orval 文件流、Blob、文件名和错误响应。"
 ---
 
 # YSS 文件导出下载 Skill

package/template/.codex/skills/frontend-commit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: frontend-commit
-description: 分析并提交 Vue、React、TypeScript、JavaScript、Vite、微前端和前端 monorepo 项目的 Git 改动；当用户要求生成 commit message、检查提交规范、拆分原子提交、暂存并执行 git commit，或修复 commitlint 与 commit-msg hook 拒绝时使用。读取仓库实际规则和 diff，选择业务 scope，生成英文 type/scope 与中文标题和正文，并安全验证提交。
+description: "为前端改动生成提交信息、审查原子提交或修复 Git hook；用户明确要求提交时执行 git commit。"
 ---
 
 # 前端规范提交

package/template/.codex/skills/java-backend-commit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: java-backend-commit
-description: 分析并提交 Java、Spring Boot、Maven、Gradle、单体服务和多模块后端项目的 Git 改动；当用户要求生成 commit message、检查提交规范、拆分原子提交、暂存并执行 git commit，或修复 commitlint 与 commit-msg hook 拒绝时使用。读取仓库实际规则、模块结构和 diff，选择服务或业务域 scope，生成英文 type/scope 与中文标题和正文，并安全验证提交。
+description: "为 Java 后端改动生成提交信息、审查原子提交或修复 Git hook；用户明确要求提交时执行 git commit。"
 ---
 
 # Java 后端规范提交

package/template/.codex/skills/llm-wiki/SKILL.md

@@ -1,11 +1,6 @@
 ---
 name: llm-wiki
-description: >
-  Compile and maintain a Karpathy-pattern LLM wiki (raw + wiki + schema) with
-  init, incremental refresh, global rebuild, lint, and narrow ingest. Use when
-  the user wants a local knowledge wiki, incremental wiki refresh, wiki rebuild,
-  compiling a named research note into the wiki, `/llm-wiki`, or an answer from
-  an existing wiki.
+description: "Build or refresh a local LLM wiki; use for wiki init, ingest, rebuild, lint, or source-backed wiki questions."
 ---
 
 # llm-wiki

package/template/.codex/skills/lombok/SKILL.md

@@ -1,22 +1,9 @@
 ---
 name: lombok
-description: |
-  Project Lombok for reducing Java boilerplate. Covers annotations for getters,
-  setters, constructors, builders, logging, and more. Based on production
-  patterns from castellino and gestionale-presenze projects.
-
-  USE WHEN: user mentions "lombok", "@Data", "@Builder", "@Slf4j", asks about
-  "boilerplate reduction", "getters/setters", "@RequiredArgsConstructor", "@Value"
-
-  DO NOT USE FOR: Java language features - use `java` skill instead
-  DO NOT USE FOR: MapStruct integration - use `mapstruct` skill
-  DO NOT USE FOR: Spring annotations - use `backend-spring-boot` skill
-allowed-tools: Read, Grep, Glob, Write, Edit
+description: "配置或排查 Lombok 注解、构造器、Builder 和注解处理器；按对象身份与敏感字段选择生成范围。"
 ---
 # Project Lombok
 
-> **Deep Knowledge**: Use `mcp__documentation__fetch_docs` with technology: `lombok` for comprehensive documentation.
-
 ## YSS 阶段 7 执行结果
 
 - 消费工程 Java 与处理器基线；三个新后端 Profile 为 Java 8。MapStruct binding 进入 annotationProcessorPaths，不作为业务依赖单独引入；示例不授权升级依赖。MVC PO 的身份/敏感字段风险与 DDD 相同，不能默认全量 @Data。
@@ -24,329 +11,16 @@ allowed-tools: Read, Grep, Glob, Write, Edit
 - 受控生成必须记录对象类型、选用/排除注解、实体关系和敏感字段风险、编译/测试实际结果。
 - 按 `yss-implementation-contract-compiler` 的统一 Execution Result 返回 changed files、证据、偏离和新增影响；`@Data` 实体风险、处理器配置缺失或越界路径返回 `violation`。
 
-## Maven Configuration
-
-```xml
-<dependency>
-    <groupId>org.projectlombok</groupId>
-    <artifactId>lombok</artifactId>
-    <version>1.18.34</version>
-    <optional>true</optional>
-</dependency>
-
-<!-- For MapStruct compatibility -->
-<dependency>
-    <groupId>org.projectlombok</groupId>
-    <artifactId>lombok-mapstruct-binding</artifactId>
-    <version>0.2.0</version>
-</dependency>
-```
-
-## Common Annotations
-
-### @Data (All-in-One)
-
-```java
-@Data
-public class User {
-    private Long id;
-    private String name;
-    private String email;
-}
-
-// Generates:
-// - @Getter for all fields
-// - @Setter for all non-final fields
-// - @ToString
-// - @EqualsAndHashCode
-// - @RequiredArgsConstructor
-```
-
-### @Getter / @Setter
-
-```java
-public class User {
-    @Getter @Setter
-    private String name;
-
-    @Getter // Read-only
-    private final String email;
-
-    @Setter(AccessLevel.PROTECTED)
-    private String internalId;
-}
-```
-
-### @NoArgsConstructor / @AllArgsConstructor / @RequiredArgsConstructor
-
-```java
-@NoArgsConstructor
-@AllArgsConstructor
-public class User {
-    private Long id;
-    private String name;
-}
-
-@RequiredArgsConstructor
-public class UserService {
-    private final UserRepository userRepository; // Included in constructor
-    private final UserMapper userMapper;         // Included in constructor
-    private String cacheName;                    // NOT included
-}
-```
-
-### @Builder
-
-```java
-@Data
-@Builder
-public class User {
-    private Long id;
-    private String name;
-    private String email;
-    @Builder.Default
-    private UserStatus status = UserStatus.ACTIVE;
-}
-
-// Usage
-User user = User.builder()
-    .name("John")
-    .email("john@example.com")
-    .build();
-
-// With toBuilder for updates
-User updated = user.toBuilder()
-    .name("Jane")
-    .build();
-```
-
-### @Value (Immutable)
-
-```java
-@Value
-public class UserResponse {
-    Long id;
-    String name;
-    String email;
-    LocalDateTime createdAt;
-}
-
-// Generates:
-// - All fields are private final
-// - @AllArgsConstructor
-// - @Getter (no setters)
-// - @ToString
-// - @EqualsAndHashCode
-```
-
-## Entity Pattern
-
-```java
-@Entity
-@Table(name = "users")
-@Getter
-@Setter
-@NoArgsConstructor(access = AccessLevel.PROTECTED)
-@AllArgsConstructor(access = AccessLevel.PRIVATE)
-@Builder
-@EntityListeners(AuditingEntityListener.class)
-public class User {
-
-    @Id
-    @GeneratedValue(strategy = GenerationType.IDENTITY)
-    private Long id;
-
-    @Column(nullable = false)
-    private String name;
-
-    @Column(unique = true, nullable = false)
-    private String email;
-
-    @Enumerated(EnumType.STRING)
-    @Builder.Default
-    private UserStatus status = UserStatus.ACTIVE;
-
-    @CreatedDate
-    @Column(updatable = false)
-    private LocalDateTime createdAt;
-
-    @LastModifiedDate
-    private LocalDateTime updatedAt;
-
-    @ManyToOne(fetch = FetchType.LAZY)
-    @JoinColumn(name = "department_id")
-    private Department department;
-}
-```
-
-JPA/DDD entities must not default to `@Data`; choose equality and `toString` deliberately from stable identity and exclude lazy, relationship, and sensitive fields.
+## 按需读取
 
-## Service Pattern with Constructor Injection
+先确认当前任务涉及的对象与批准合同，只读取对应参考段落：
 
-```java
-@Service
-@RequiredArgsConstructor
-@Slf4j
-public class UserServiceImpl implements UserService {
-
-    private final UserRepository userRepository;
-    private final UserMapper userMapper;
-    private final PasswordEncoder passwordEncoder;
-
-    @Override
-    public UserResponse create(CreateUserRequest dto) {
-        log.info("Creating user: {}", dto.getEmail());
-        User user = userMapper.toEntity(dto);
-        return userMapper.toResponse(userRepository.save(user));
-    }
-}
-```
-
-## Logging
-
-```java
-@Slf4j  // SLF4J logger
-public class UserService {
-    public void process() {
-        log.info("Processing...");
-        log.debug("Debug info: {}", data);
-        log.error("Error occurred", exception);
-    }
-}
-
-@Log4j2  // Log4j2 logger
-@CommonsLog  // Apache Commons Logging
-@JBossLog  // JBoss Logging
-```
-
-## DTO Pattern
-
-```java
-// Request DTO
-@Data
-public class CreateUserRequest {
-    @NotBlank
-    private String name;
-    @Email
-    private String email;
-    @Size(min = 8)
-    private String password;
-}
-
-// Response DTO (immutable)
-@Value
-@Builder
-public class UserResponse {
-    Long id;
-    String name;
-    String email;
-    UserStatus status;
-    LocalDateTime createdAt;
-}
-```
-
-## @Cleanup
-
-```java
-public void readFile(String path) throws IOException {
-    @Cleanup InputStream in = new FileInputStream(path);
-    // in.close() called automatically
-}
-```
-
-## @SneakyThrows
-
-```java
-@SneakyThrows  // Wraps checked exception
-public String readConfig() {
-    return new String(Files.readAllBytes(Paths.get("config.json")), StandardCharsets.UTF_8);
-}
-```
-
-## @Synchronized
-
-```java
-public class Counter {
-    @Synchronized
-    public void increment() {
-        // Thread-safe
-    }
-}
-```
-
-## @With (Immutable Updates)
-
-```java
-@Value
-@With
-public class Point {
-    int x;
-    int y;
-}
-
-Point p1 = new Point(1, 2);
-Point p2 = p1.withX(5);  // Point(5, 2)
-```
-
-## Key Annotations
-
-| Annotation | Purpose |
-|------------|---------|
-| `@Data` | Getter, Setter, ToString, Equals, Constructor |
-| `@Value` | Immutable class |
-| `@Builder` | Builder pattern |
-| `@RequiredArgsConstructor` | Constructor for final fields |
-| `@Slf4j` | Logger field |
-| `@ToString.Exclude` | Exclude from toString |
-| `@EqualsAndHashCode.Exclude` | Exclude from equals/hashCode |
-
----
-
-## When NOT to Use This Skill
-
-| Scenario | Use Instead |
-|----------|-------------|
-| Java core language | `java` skill |
-| MapStruct mapping | `mapstruct` skill |
-| Spring annotations | `backend-spring-boot` skill |
-| JPA entities complex logic | Manual implementation |
-| Public API design | Explicit methods for clarity |
-
----
-
-## Anti-Patterns
-
-| Anti-Pattern | Why It's Bad | Correct Approach |
-|--------------|--------------|------------------|
-| @Data on JPA entities | toString/equals issues | Use @Getter/@Setter selectively |
-| Not excluding lazy relations | LazyInitializationException | Use @ToString.Exclude |
-| @EqualsAndHashCode on entities | Proxy issues | Use @EqualsAndHashCode(onlyExplicitlyIncluded = true) |
-| @SneakyThrows everywhere | Hides exceptions | Use proper exception handling |
-| @Builder without @Default | Null fields | Add @Builder.Default |
-| @Value with mutable fields | Breaks immutability | Use only immutable types |
-| Mixing @Data and manual methods | Confusing API | Be consistent |
-| Not configuring in lombok.config | Inconsistent behavior | Use lombok.config file |
-
----
-
-## Quick Troubleshooting
-
-| Issue | Cause | Solution |
-|-------|-------|----------|
-| "Cannot find symbol" for getters | IDE not processing | Enable annotation processing |
-| LazyInitializationException | toString on lazy relation | Add @ToString.Exclude |
-| MapStruct not working | Wrong processor order | Lombok before MapStruct |
-| Builder missing fields | No @Builder.Default | Add defaults or check config |
-| StackOverflowError in equals | Circular reference | Exclude relation fields |
-| IDE shows errors but compiles | IDE cache | Invalidate caches/restart |
-| @Slf4j logger not found | SLF4J not in classpath | Add SLF4J dependency |
-| Generated code not visible | delombok needed | Run delombok task |
-
----
+| 任务 | 参考 |
+|---|---|
+| 构造器、Builder、默认值或不可变对象 | [Common Annotations](references/annotation-examples.md#common-annotations) |
+| 实体身份、关联与敏感字段 | [Entity Pattern](references/annotation-examples.md#entity-pattern) |
+| 注解处理器与 MapStruct 集成 | [Maven Configuration](references/annotation-examples.md#maven-configuration)，映射逻辑交给 `mapstruct` |
 
-## Reference Documentation
-- [Lombok Documentation](https://projectlombok.org/features/)
-- [Stable Features](https://projectlombok.org/features/all)
-- [Configuration](https://projectlombok.org/features/configuration)
+选择注解前核查生成的 equals/hashCode/toString 是否符合对象身份与数据边界。敏感字段不能进入生成的 toString 或日志；实体不默认使用全量 `@Data`。依赖和处理器版本复用工程基线，修改生成行为后编译受影响模块，并验证实际生成的访问器、构造器或身份行为。
 
-> **Deep Knowledge**: Use `mcp__documentation__fetch_docs` with technology: `lombok` for comprehensive documentation.
+查第三方行为时使用 `yss-research`，来源为 [Lombok 官方文档](https://projectlombok.org/features/)；不假定某个 MCP 工具已安装。