create-yss-spec 2.1.9 → 2.1.11

package/template/.cursor/skills/yss-router/references/router-contract.yaml

@@ -0,0 +1,245 @@
+schema_version: 1
+allowed_statuses: [draft, blocked, ready-for-lifecycle-review]
+forbidden_statuses: [approved, ready-for-agent, completed]
+skill_aliases:
+  api-integration: yss-api-integration
+  microapp-commit: yss-microapp-commit
+implementation_path_policy:
+  applies_to: harness-resident-runtime-code
+  project_roots:
+    backend: apps/backend/<project>/
+    frontend: apps/frontend/<project>/
+  container_roots:
+    - apps/backend/
+    - apps/frontend/
+  forbidden_roots:
+    - app/backend/
+    - app/frontend/
+  rules:
+    - "Harness 内每个运行时工程必须位于具体 project 目录，不能直接写入 apps/backend/ 或 apps/frontend/。"
+    - "app/backend/、app/frontend/ 及其子路径不是兼容别名，必须阻断。"
+    - "外部实现仓库使用登记的真实项目根路径，不用 Harness 容器路径冒充。"
+subcontract_statuses: [required, not-applicable]
+
+readiness:
+  common: [spec, slice_ticket, architecture_review, build_architecture_checklist, implementation_repository, verification_commands]
+  ui_impact: [requirement_freeze, low_fidelity_review, prototype_review, high_fidelity_html, prototype_verification, antd_cli_evidence, browser_verification_evidence, prototype_confirmation]
+  api_impact: [openapi_freeze]
+  no_api_impact: [no_api_impact_record]
+  data_impact: [data_architecture]
+  backend_impact: [engineering_baseline, backend_repository, maven_wrapper]
+  cross_repo: [repository_registry, delivery_order, integration_verification, rollback_order]
+
+routing_input_required:
+  - slice_id
+  - impact_flags
+  - lifecycle
+  - implementation
+  - acceptance
+impact_flags_required: [ui_impact, api_impact, no_api_impact, data_impact, backend_impact, cross_repo, existing_frozen_baseline]
+exclusive_flags:
+  - [api_impact, no_api_impact]
+
+slice_contract_required:
+  root: [schema_version, contract_id, contract_version, slice_id, status, lifecycle_refs, readiness, common, frontend, backend, contract, cross_repo, work_units]
+  lifecycle_refs: [spec, ticket, requirement_freeze, low_fidelity_review, prototype_review, high_fidelity_html, prototype_verification, antd_cli_evidence, browser_verification_evidence, prototype_confirmation, openapi_freeze_or_no_impact, architecture_review, data_architecture, engineering_baseline, build_architecture_checklist, implementation_repository, frontend_repository, backend_repository, maven_wrapper]
+  readiness: [blockers, stale_inputs, not_applicable]
+  common: [impacted_areas, implementation_path_policy, project_roots, required_skills, optional_skills, unavailable_skills, allowed_write_paths, forbidden_patterns, expected_evidence_files, verification_commands, human_review_points, full_reroute_triggers]
+  frontend: [status, required_skills, approved_prototype_ref, state_matrix_ref, allowed_write_paths, component_test_seams, e2e_paths]
+  backend: [status, affected_layers, component_impacts, required_skills, application_boundary, transaction_boundary, persistence_strategy, allowed_write_paths, forbidden_patterns, expected_evidence_files, seam_deferred, verification_commands]
+  contract: [api_impact, freeze_ref, no_api_impact_ref, generated_clients, contract_tests, regeneration_commands]
+  cross_repo: [repositories, delivery_order, integration_verification, rollback_order]
+
+lifecycle_ref_by_readiness:
+  spec: spec
+  slice_ticket: ticket
+  architecture_review: architecture_review
+  build_architecture_checklist: build_architecture_checklist
+  implementation_repository: implementation_repository
+  requirement_freeze: requirement_freeze
+  low_fidelity_review: low_fidelity_review
+  prototype_review: prototype_review
+  high_fidelity_html: high_fidelity_html
+  prototype_verification: prototype_verification
+  antd_cli_evidence: antd_cli_evidence
+  browser_verification_evidence: browser_verification_evidence
+  prototype_confirmation: prototype_confirmation
+  openapi_freeze: openapi_freeze_or_no_impact
+  no_api_impact_record: openapi_freeze_or_no_impact
+  data_architecture: data_architecture
+  engineering_baseline: engineering_baseline
+  backend_repository: backend_repository
+  maven_wrapper: maven_wrapper
+
+work_unit_required: [id, behavior, primary_skill, supporting_skills, tdd_mode, allowed_write_paths, expected_evidence, verification_commands, controlled_generation]
+work_unit_nonempty_arrays: [allowed_write_paths, expected_evidence, verification_commands]
+slice_contract_nonempty: [contract_id, contract_version, slice_id, status]
+slice_contract_array_fields:
+  common: [impacted_areas, implementation_path_policy, project_roots, required_skills, allowed_write_paths, forbidden_patterns, expected_evidence_files, verification_commands, full_reroute_triggers]
+
+scaffold_contract_schema:
+  schema_version: 1
+  compiled_by: yss-router
+  approved_by: yss-product-lifecycle
+  status_by_owner:
+    router: [draft, ready-for-lifecycle-review, blocked]
+    lifecycle: [approved, stale, blocked]
+  required: [contract_id, contract_version, slice_id, status, router_draft_ref, lifecycle_approval_ref, persisted_ref, current_version, implementation_repository, backend_repository, scaffold_status, target_git_url_or_output_dir, allowed_write_paths, expected_evidence_files, verification_commands, approval, work_unit, overwrite_policy]
+  approval:
+    required: [approval_ref, approver, persisted_ref, current_version]
+  overwrite_policy:
+    required: [force_allowed, overwrite_scope, rollback_ref]
+  lifecycle_boundary:
+    router_emits: [draft, ready-for-lifecycle-review, blocked]
+    lifecycle_approves: [approved]
+    generator_consumes: [approved]
+    after_generation: [yss-backend-scaffold-parent, yss-router-business-contract-recompile]
+  work_unit:
+    required: [id, behavior, primary_skill, supporting_skills, tdd_mode, allowed_write_paths, expected_evidence, verification_commands, controlled_generation]
+  generation_boundary:
+    allowed_for: [project_scaffold, pom, mechanical_config, wrapper]
+    forbidden_when: [business_behavior, business_fields, business_state, permission, transaction, complex_query, error_mapping, business_example_crud]
+  verification:
+    commands: ["./mvnw validate", "./mvnw test", "./mvnw package"]
+    requires_execution: true
+    evidence: [command, exit_code, duration_ms, stdout_ref, stderr_ref, executed_at]
+
+applicable_subcontract_nonempty:
+  frontend:
+    scalar: [approved_prototype_ref, state_matrix_ref]
+    array: [required_skills, allowed_write_paths, component_test_seams, e2e_paths]
+  backend:
+    scalar: [application_boundary, transaction_boundary, persistence_strategy]
+    array: [affected_layers, required_skills, allowed_write_paths, forbidden_patterns, expected_evidence_files, verification_commands]
+  contract_api:
+    scalar: [freeze_ref]
+    array: [contract_tests]
+  contract_no_api:
+    scalar: [no_api_impact_ref]
+  cross_repo:
+    array: [repositories, delivery_order, integration_verification, rollback_order]
+
+dependency_closure:
+  yss-ddd-scaffold-generator:
+    always: [yss-backend-scaffold-parent, alibaba-java-code-style]
+  yss-domain:
+    always: [alibaba-java-code-style]
+    when_modeling: [domain-modeling]
+    when_pojo: [lombok]
+  yss-application:
+    always: [alibaba-java-code-style]
+    when_conversion: [mapstruct, lombok]
+  yss-repository:
+    always: [mapstruct, lombok, alibaba-java-code-style]
+    when_mybatis: [yss-mybatis]
+  yss-web-controller:
+    always: [yss-dto, mapstruct, lombok, alibaba-java-code-style]
+  yss-userinfo:
+    always: [yss-dto]
+    when_cache_lookup: [yss-cache]
+  yss-audit-log:
+    always: [yss-userinfo, yss-dto]
+  yss-validation:
+    always: [yss-exception]
+  yss-security-algorithm:
+    always: [yss-exception]
+  yss-exception:
+    always: [yss-dto]
+  yss-page-module-development:
+    when_components: [yss-components]
+    when_hooks: [yss-hook]
+    when_form: [yss-formily]
+    when_api: [api-integration]
+  api-integration:
+    when_regeneration: [yss-openapi-governance]
+
+component_impact_values:
+  - current-user-context
+  - user-cache-lookup
+  - audit-event
+  - request-validation
+  - error-mapping
+  - encryption-or-signing
+
+component_impact_routing:
+  current-user-context: [yss-userinfo]
+  user-cache-lookup: [yss-userinfo, yss-cache]
+  audit-event: [yss-audit-log, yss-userinfo, yss-dto]
+  request-validation: [yss-validation, yss-exception]
+  error-mapping: [yss-exception, yss-dto]
+  encryption-or-signing: [yss-security-algorithm, yss-exception]
+
+end_to_end_backend_required:
+  - yss-domain
+  - yss-application
+  - yss-repository
+  - yss-web-controller
+  - yss-dto
+  - mapstruct
+  - lombok
+  - alibaba-java-code-style
+
+tdd_modes:
+  behavior-tdd:
+    impacts: [domain-rule, state-machine, transaction, complex-query, permission, error-mapping, page-interaction, user-visible-state]
+  controlled-generation:
+    impacts: [project-scaffold, dto-boilerplate, po-boilerplate, mapstruct-generated, frozen-openapi-client, mechanical-config]
+    required: [exception_reason, generator, generator_inputs, expected_files, verification_commands, behavior_tests_after_generation]
+
+full_reroute_triggers:
+  - scaffold-baseline-drift
+  - api-schema-impact
+  - database-schema-impact
+  - state-machine-impact
+  - data-model-impact
+  - new-write-path
+  - new-repository
+  - new-required-skill
+  - not-applicable-invalidated
+  - architecture-drift
+  - contract-violation
+  - generation-became-behavior
+  - test-seam-changed
+  - verification-command-changed
+  - delivery-order-changed
+
+reroute_destinations:
+  scaffold-baseline-drift: stage7-scaffold-revalidation
+  api-schema-impact: system-data-architecture-and-contract-review
+  database-schema-impact: data-architecture-and-migration-review
+  state-machine-impact: spec-system-data-and-contract-review
+  data-model-impact: data-architecture-and-contract-review
+  new-write-path: stage7-contract-recompile
+  new-repository: stage7-contract-recompile
+  new-required-skill: stage7-contract-recompile
+  not-applicable-invalidated: lifecycle-impact-reassessment
+  architecture-drift: architecture-recheck
+  contract-violation: stage7-contract-recompile
+  generation-became-behavior: stage7-contract-recompile
+  test-seam-changed: spec-ticket-test-seam-review
+  verification-command-changed: stage7-contract-recompile
+  delivery-order-changed: cross-repo-release-review
+
+execution_result_allowed_statuses: [implemented, seam-deferred, drift, violation, not-applicable]
+execution_blockers: [path-outside-contract, missing-evidence, verification-not-executed, verification-command-mismatch, seam-deferred-without-owner, constraint-failed, unapproved-deviation, drift, violation, new-impacts]
+
+contract_versioning:
+  full_reroute_current_status: stale
+  next_version: increment
+  required_history: [previous_contract_ref, stale_reason, reroute_trigger]
+  affected_work_units_status: paused
+
+execution_result_required:
+  - consumed_contract
+  - changed_files
+  - evidence_files
+  - verification_results
+  - constraint_results
+  - seam_deferred
+  - deviations
+  - new_impacts
+  - not_applicable_reason
+seam_deferred_required: [risk, owner, follow_up_ticket, verification_plan, target_version_or_release_date]
+deviation_required: [rule, reason, approval_ref]
+not_applicable_required: [item, reason]
+unavailable_skill_required: [skill, provider, fallback, resolution]

package/template/.cursor/skills/yss-router/references/slice-implementation-contract.md

@@ -0,0 +1,113 @@
+# Slice Implementation Contract
+
+Router 生成草案；`yss-product-lifecycle` 核验并持久化。合同缺少必填字段时状态为 `blocked`。
+
+```yaml
+slice_contract:
+  schema_version: 1
+  contract_id:
+  contract_version: 1
+  slice_id:
+  status: draft
+  lifecycle_refs:
+    spec:
+    ticket:
+    requirement_freeze:
+    low_fidelity_review:
+    prototype_review:
+    high_fidelity_html:
+    prototype_verification:
+    antd_cli_evidence:
+    browser_verification_evidence:
+    prototype_confirmation:
+    openapi_freeze_or_no_impact:
+    architecture_review:
+    data_architecture:
+    engineering_baseline:
+    build_architecture_checklist:
+    implementation_repository:
+    frontend_repository:
+    backend_repository:
+    maven_wrapper:
+  readiness:
+    blockers: []
+    stale_inputs: []
+    not_applicable:
+      - item:
+        reason:
+  common:
+    impacted_areas: []
+    implementation_path_policy: harness-apps-multi-project # or external-repository-native
+    project_roots: []
+    required_skills: []
+    optional_skills: []
+    unavailable_skills:
+      - skill:
+        provider:
+        fallback: blocked | approved-equivalent
+        resolution:
+    allowed_write_paths: []
+    forbidden_patterns: []
+    expected_evidence_files: []
+    verification_commands: []
+    human_review_points: []
+    full_reroute_triggers: []
+  frontend:
+    status: not-applicable
+    required_skills: []
+    approved_prototype_ref:
+    state_matrix_ref:
+    generated_api_client_ref:
+    allowed_write_paths: []
+    component_test_seams: []
+    e2e_paths: []
+  backend:
+    status: not-applicable
+    affected_layers: []
+    component_impacts: []
+    required_skills: []
+    application_boundary:
+    transaction_boundary:
+    persistence_strategy:
+    allowed_write_paths: []
+    forbidden_patterns: []
+    expected_evidence_files: []
+    seam_deferred: []
+    verification_commands: []
+  contract:
+    api_impact: false
+    freeze_ref:
+    no_api_impact_ref:
+    generated_clients: []
+    contract_tests: []
+    regeneration_commands: []
+  cross_repo:
+    repositories: []
+    delivery_order: []
+    integration_verification: []
+    rollback_order: []
+  work_units: []
+```
+
+工作单元：
+
+```yaml
+work_unit:
+  id:
+  behavior:
+  primary_skill:
+  supporting_skills: []
+  tdd_mode: behavior-tdd
+  allowed_write_paths: []
+  expected_evidence: []
+  verification_commands: []
+  controlled_generation:
+    exception_reason:
+    generator:
+    generator_inputs: []
+    expected_files: []
+    verification_commands: []
+    behavior_tests_after_generation: []
+```
+
+`controlled_generation` 仅在 `tdd_mode: controlled-generation` 时必填；其他模式标记 `not-applicable`。明确写入需求的权限业务行为仍使用 `behavior-tdd`；API schema 与 database schema 分别触发契约或数据架构回退，不得用一个含糊的 schema 类型决定路线。

package/template/.cursor/skills/yss-router/references/yss-skill-execution-result.md

@@ -0,0 +1,62 @@
+# YSS Skill Execution Result
+
+核心 YSS skill 必须消费已批准合同版本，并返回：
+
+```yaml
+execution_result:
+  schema_version: 1
+  skill:
+  slice_id:
+  work_unit_id:
+  status: implemented
+  consumed_contract:
+    contract_ref:
+    contract_id:
+    contract_version:
+  changed_files:
+    - path:
+      contract_area: common | frontend | backend | contract | cross_repo
+  evidence_files:
+    - path:
+      evidence_type: code | test | generated | review | verification
+      behavior_ref:
+  verification_results:
+    - command:
+      result:
+      executed_at:
+  constraint_results:
+    - constraint:
+      status: passed | failed | not-applicable
+      evidence_ref:
+  seam_deferred:
+    - risk:
+      owner:
+      follow_up_ticket:
+      verification_plan:
+      target_version_or_release_date:
+  deviations:
+    - rule:
+      reason:
+      approval_ref:
+  new_impacts:
+    - impact_type:
+      evidence_ref:
+  not_applicable_reason:
+```
+
+允许状态：`implemented`、`seam-deferred`、`drift`、`violation`、`not-applicable`。
+
+Router 必须验证：
+
+1. `consumed_contract.contract_version` 与当前批准版本一致。
+2. `changed_files` 全部位于工作单元和切片允许路径内。
+3. `expected_evidence_files` 全部存在并能回指行为。
+4. 验证命令包含实际结果和时间；计划命令不算证据。
+5. `seam_deferred` 有风险、责任人、补齐 Ticket、验证计划和目标版本 / 发布日期。
+6. `new_impacts` 非空时暂停并重路由。
+7. `drift` 触发 Architecture Re-check；`violation` 阻断 build。
+8. `status: not-applicable` 必须填写 `not_applicable_reason`；其他状态保留字段但可为空。
+
+专项 skill 自报 `implemented` 不等于最终通过，生命周期编排器和独立 Reviewer 必须复核。
+
+`verification_results` 不得为空，每项必须包含非空 `command`、`result` 和 `executed_at`。路径校验按完整目录边界判断，`apps/backend/project1-escape` 不属于 `apps/backend/project1/`；Harness 内路径还必须通过项目路径策略。完整重路由时旧合同必须标记 `stale`，新合同版本递增并保留旧合同引用、失效原因和触发器。

package/template/.cursor/skills/yss-security-algorithm/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: yss-security-algorithm
+description: Use when YSS RSA/AES/DES/SM2/SM4 encryption, JWT/JWK configuration, password encoding, key loading, rotation, or decryption failures are involved.
+---
+
+# yss-security-algorithm
+
+Use this skill for YSS 安全算法组件. Keep implementation grounded in the local project and resolvable YSS backend component source.
+
+中文说明：本技能用于 YSS 安全算法组件。执行时优先读取源码索引，避免凭记忆猜类名、配置项或接入方式。
+
+## Source Index First
+
+- Backend source location is environment-specific; resolve it with `yss-source-index/references/source-location.md`.
+- Generated index: `references/source-index.md`
+- Component path hints: `yss-microservice-components/yss-component-security-algorithm`
+
+Read `references/source-index.md` as a path-hint index whenever the task depends on exact modules, annotations, auto configuration, properties, controllers, clients, repositories, DTOs, handlers, or troubleshooting.
+
+## Workflow
+
+1. Identify whether the task is symmetric encryption, asymmetric encryption, SM algorithms, JWT key generation/configuration, or decryption troubleshooting.
+2. Read `references/source-index.md`, then inspect `CryptoType`, `SecurityCryptoUtil`, `KeyGeneratorUtils`, and `DefaultJwtConfiguration`.
+3. Use `CryptoType` to route algorithm-specific behavior; current enum values include `RSA`, `AES`, `DES`, `SM2`, and `SM4`.
+4. Treat `SecurityCryptoUtil` and `Jwks` as compatibility/legacy references only. The current `Jwks.generateRsa()` decodes hardcoded `PK`/`SK` constants rather than generating or loading a managed key, while EC/secret keys can be process-local or regenerated at startup; none is production key management.
+5. For production changes, externalize keys/secrets and avoid copying hardcoded sample keys into business modules.
+
+## Security Notes
+
+- The current utility contains a complete hardcoded RSA private key and fixed key material; do not use it for production data. Existing exposure requires rotation/revocation planning, not merely avoiding new constants.
+- `Jwks.generateRsa()` contains a complete hardcoded RSA private key; the key identifier is static and must be treated as compromised until rotated.
+- `DefaultJwtConfiguration` generates or selects JWK material at startup and currently selects `noop` as the DelegatingPasswordEncoder default; persistence, rotation, an external secret source, and an explicit password-encoder override are production prerequisites.
+- Verify whether callers need encryption for storage, transport, signing, or compatibility; choose algorithm and key lifecycle accordingly.
+- Prefer environment/config/secret-manager backed keys for deployable code.
+- Keep plaintext, ciphertext, encoding format, and key type explicit in API contracts.
+
+## Checklist
+
+- Required dependency or starter module is present.
+- Algorithm choice is explicit and compatible with the caller.
+- Key source and rotation story are documented for production code.
+- JWT signatures are verified with issuer/audience/expiry policy; payload parsing alone is never authentication.
+- Encoding format is clear: Base64, hex, UTF-8 string, or raw bytes.
+- Decrypt path uses the matching algorithm/key type.
+- No passwords, private keys, or long-lived secrets are added to source files.
+- If external key storage, rotation/revocation, algorithm parameters, compatibility tests, or security-owner review is missing, return `blocked-for-production` instead of generating crypto code.
+
+## Do Not
+
+- Do not invent class names or configuration keys without checking the source index.
+- Do not replace component extension points with business-local framework code.
+- Do not broaden the task into unrelated YSS components unless the user asks.

package/template/.cursor/skills/yss-security-algorithm/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "yss-security-algorithm"
+  short_description: "YSS component skill for yss-security-algorithm"
+  default_prompt: "Use yss-security-algorithm for this YSS backend component task."

package/template/{.hermes/skills/yss-jdbc → .cursor/skills/yss-security-algorithm}/references/source-index.md

@@ -1,4 +1,4 @@
-# yss-jdbc Source Index
+# yss-security-algorithm Source Index
 
 Generated: 2026-08-17T12:03:37.436Z
 Source commit: `38b556a5081e6c66c0c538cbc1ef839b19996ed3`
@@ -11,7 +11,7 @@ Paths below are source path hints captured at refresh time. If they do not exist
 
 ## Component Path Hints
 
-- `yss-microservice-components/yss-component-jdbc` (existed when indexed)
+- `yss-microservice-components/yss-component-security-algorithm` (existed when indexed)
 
 ## Documentation Files
 
@@ -19,12 +19,14 @@ Paths below are source path hints captured at refresh time. If they do not exist
 
 ## Maven Modules
 
-- `yss-microservice-components/yss-component-jdbc`
+- `yss-microservice-components/yss-component-security-algorithm`
 
 ## Key Java Entry Points
 
-- `yss-microservice-components/yss-component-jdbc/src/main/java/com/yss/cloud/jdbc/db/DefaultHutoolConfiguration.java`
-- `yss-microservice-components/yss-component-jdbc/src/main/java/com/yss/cloud/jdbc/db/JdbcSqlUtil.java`
+- `yss-microservice-components/yss-component-security-algorithm/src/main/java/com/yss/cloud/CryptoType.java`
+- `yss-microservice-components/yss-component-security-algorithm/src/main/java/com/yss/cloud/config/DefaultJwtConfiguration.java`
+- `yss-microservice-components/yss-component-security-algorithm/src/main/java/com/yss/cloud/jose/KeyGeneratorUtils.java`
+- `yss-microservice-components/yss-component-security-algorithm/src/main/java/com/yss/cloud/util/SecurityCryptoUtil.java`
 
 ## Recommended Next Reads
 

package/template/.cursor/skills/yss-source-index/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: yss-source-index
+description: Use when YSS backend component source or frontend UI documentation changes and skill source indexes need refreshing.
+---
+
+# yss-source-index
+
+Use this maintenance skill to keep YSS skills grounded in current source and documentation.
+
+中文说明：这个技能用于维护 YSS skills 的“源码索引”。后端组件库或前端文档入口变化后，运行脚本刷新引用文件。
+
+## Source Location Policy
+
+- Backend component source is environment-specific. Use `references/source-location.md` before trusting any generated path.
+- Preferred explicit setting: `YSS_SOURCE_ROOT=/absolute/path/to/yss-cloud-microservice`.
+- Frontend YSS UI components: `http://192.168.164.27:3200/components`
+- Frontend YSS UI hooks: `http://192.168.164.27:3200/hooks`
+- Frontend YSS UI skill docs: `http://192.168.164.27:3200/skills`
+
+## Refresh Workflow
+
+Run:
+
+```bash
+export YSS_SKILLS_ROOT="/path/to/.agents/skills"
+export YSS_SOURCE_ROOT="/path/to/yss-cloud-microservice"
+node "$YSS_SKILLS_ROOT/yss-source-index/scripts/refresh-yss-skill-index.mjs"
+```
+
+Backend-only refreshes may set `YSS_REFRESH_FRONTEND=false` to avoid unrelated frontend timestamp churn.
+
+The script updates `references/source-index.md` for backend component skills and `references/frontend-docs.md` for frontend YSS UI skills. Read `references/source-map-config.md` for the full skill-to-source mapping.
+
+中文说明：脚本不会复制大段源码，只会生成可追踪的文档路径、模块路径和关键 Java 入口类，方便 Agent 后续精准读取。
+
+If `YSS_SOURCE_ROOT` is omitted, the script tries to find a repository containing `yss-microservice-components` from the current workspace and common local project folders. If it cannot find one, set `YSS_SOURCE_ROOT` explicitly.
+
+## Output Contract
+
+Generated source indexes should contain:
+
+- source root and generated timestamp
+- exact source Git commit and worktree state
+- component directories and documentation files
+- Maven modules
+- key Java classes matched by names such as annotations, auto configurations, properties, aspects, interceptors, handlers, repositories, DTOs, and result objects
+- recommended next reads for Agent when performing implementation or troubleshooting
+
+Do not paste full component source into `SKILL.md`. Keep `SKILL.md` short and let specialists read generated indexes or targeted assets only when needed.
+
+## Freshness Gate
+
+Before exact class/config/security guidance, compare the index `Source commit` with `git -C "$YSS_SOURCE_ROOT" rev-parse HEAD`. A mismatch or `dirty` indexed state means `stale`: refresh the index or return `blocked`; do not silently rely on the old snapshot. Historical path hints may still be used only to locate current source.
+
+中文说明：`SKILL.md` 保持短小，细节放到 `references/`，这是为了降低每次触发技能时的上下文成本。
+
+## After Refresh
+
+Validate the migrated Node helper with:
+
+```bash
+node --test "$YSS_SKILLS_ROOT/yss-source-index/scripts/refresh-yss-skill-index.test.mjs"
+```

package/template/.cursor/skills/yss-source-index/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "YSS Source Index"
+  short_description: "Refresh YSS skill source indexes"
+  default_prompt: "Refresh YSS skill indexes from yss-cloud-microservice and YSS UI docs."

package/template/.cursor/skills/yss-source-index/references/source-location.md

@@ -0,0 +1,18 @@
+# YSS Source Location Policy
+
+YSS skill references may mention paths such as `yss-microservice-components/yss-component-dto`. Treat these as source path hints, not guaranteed filesystem locations.
+
+## Lookup Order
+
+1. Check the current workspace first. If `.codegraph/` exists, use `codegraph explore "<class, module, or path hint>"` before text search.
+2. If the component source is outside the workspace, use `YSS_SOURCE_ROOT` when it is set. It should point to the repository root that contains `yss-microservice-components`.
+   Compare `git -C "$YSS_SOURCE_ROOT" rev-parse HEAD` with the selected index `Source commit`; mismatch is `stale` and blocks exact implementation guidance until refresh.
+3. If `YSS_SOURCE_ROOT` is not set, search common local roots such as the current repository parents, `~/Projects`, `~/Documents`, and `~/Documents/yss-project`.
+4. If the source still cannot be found, use the generated `references/source-index.md` as a stale-but-useful map of module names, package names, class names, and Maven artifacts. Do not assume listed files exist locally.
+
+## For Skill Authors
+
+- Say "source path hints" instead of "source root" unless you have verified the directory in the current environment.
+- Keep generated indexes useful for search, but do not require agents to open those exact paths.
+- Prefer symbols, package names, Maven artifact names, and annotations in instructions; they survive repository relocation better than absolute paths.
+- When refreshing indexes, export `YSS_SOURCE_ROOT=/absolute/path/to/yss-cloud-microservice` if auto-detection cannot find the component repository.

package/template/.cursor/skills/yss-source-index/references/source-map-config.md

@@ -0,0 +1,30 @@
+# YSS Source Index Mapping
+
+The refresh script maps component source path hints to skill references. These paths are relative to the detected or configured `YSS_SOURCE_ROOT`; they are not guaranteed to exist in every workspace.
+
+中文说明：这个文件记录“哪个组件源码目录生成到哪个 skill 的引用索引”，方便你以后维护映射关系。
+
+| Skill | Backend source path hints |
+| --- | --- |
+| `yss-cache` | `yss-microservice-components/yss-component-cache-parent` |
+| `yss-mybatis` | `yss-microservice-components/yss-component-persistence` |
+| `yss-dto` | `yss-microservice-components/yss-component-dto` |
+| `yss-audit-log` | `yss-microservice-components/yss-component-audit-log` |
+| `yss-excel-mvc` | `yss-microservice-components/yss-component-excel-mvc`, `yss-microservice-components/yss-component-excel-starter` |
+| `yss-distributed-id` | `yss-microservice-components/yss-component-distributed-id`, `yss-microservice-components/yss-component-leaf` |
+| `yss-resilience4j` | `yss-microservice-components/yss-component-resilience4j-starter` |
+| `yss-validation` | `yss-microservice-components/yss-component-validation-engine-parent`, `yss-microservice-components/yss-component-validation-jsr303` |
+| `yss-security-algorithm` | `yss-microservice-components/yss-component-security-algorithm` |
+| `yss-userinfo` | `yss-microservice-components/yss-component-userinfo-starter` |
+| `yss-exception` | `yss-microservice-components/yss-component-exception` |
+
+Frontend docs are written to these skills:
+
+| Skill | Frontend references |
+| --- | --- |
+| `yss-ui` | components, hooks, skills docs |
+| `yss-components` | components docs |
+| `yss-hook` | hooks docs |
+| `yss-page-module-development` | components and hooks docs |
+| `yss-use-table-height` | hooks docs |
+| `yss-use-tree-height` | hooks docs |