team-standards

当用户要求「架构检查」「lint」「检测架构违规」时触发；当对 Flutter 项目的 presentation/domain/data/infrastructure 层代码执行 Edit/Write 后自动触发一次轻量检查。

Use before writing or reviewing any business code in Java Spring Boot/Spring Cloud, React, Vue, or Flutter. MUST be invoked after design/pre-implementation orientation and before the first source-code edit to decide the target layer, feature module, reusable atomic capability, and maintainability boundaries. Enforces DDD-lite layering, feature-based structure, one-way dependencies, clear code structure, low coupling, high cohesion, and prevents business logic from being written directly in Controller/UI/Page.

Use BEFORE answering any backend single-service question about table relationships / ER / SQL query logic / state transitions / business judgments / atomic capabilities OR project-level technical pain points (subprocess orchestration, concurrency, perf, external dependencies, runtime edge cases), AND BEFORE Write/Edit any .md describing such content (even outside docs/, e.g. ai-docs/, scenarios/). MUST invoke (BLOCKING) when: (1) about to Write/Edit a markdown whose content describes backend table relationships, ER diagrams, SQL, DAO/Mapper query logic, state transitions, business flow → DB CRUD, or data modeling — including files under ai-docs/, work-log/, scenarios/, NOT only under docs/; (2) user asks 'X 与 Y 是 1:1 还是 1:N', '改这个动哪些表', '字段从哪来', '这个业务怎么查', '这个 SQL 怎么写/完善', '退款/账单/流水/分摊怎么算', '是新建快照还是引用原表', or any single-service backend table-relation / SQL / state / atomic-capability question — even if framed as investigation, not implementation; (3) finished investigating backend code (own project OR another project as subject) and discovered ≥1 reusable fact about table relations / SQL query patterns / state machines / atomic capabilities — must auto-append to candidate pool and SQL query index candidate; (4) user asks to initialize, generate, organize, read or update backend knowledge graphs, ER diagrams, SQL archives, or query logic indexes; (5) project has docs/knowledge-graph/backend/; (6) code changes affect APIs, services, DAOs/Mappers/SQL, database tables, enums, state transitions, order/refund/payment status judgment, transactions, MQ/events, or external dependencies; (7) **long-conversation tech-pain-point pattern**: same technical concern raised by the user ≥3 rounds in a single session — direct questions, verification follow-ups, regression-style phrasing ('为什么...还' / '怎么又...' / '上次说...' / '是不是...占用了' / '现在又卡了'), or persistent worry about the same constraint / perf / resource boundary; auto-append a 技术难点 candidate to `_candidates.md` even when the topic is subprocess management, concurrency, IO contention, or runtime edge cases that aren't strictly business / SQL — long-conversation patterns are the strongest signal that something deserves sediment. Knowledge graph ownership = the investigated backend service, NOT current cwd — investigating project B from project A puts the graph under B's namespace, do NOT reroute to cross-project-locator just because cwd differs. Scope: backend single service (Java / backend-service style) + project-level technical pain points within that service; cross-project topology → cross-project-locator.

You MUST invoke this skill the moment a user reports a bug, describes an error/exception, asks you to investigate or analyze a problem, or mentions writing a bug analysis document. Trigger phrases include: 'there is a bug', 'this is broken', 'why is X happening', 'investigate this issue', 'analyze the root cause', 'we have an OOM/NPE/timeout', 'help me debug'. Invoke BEFORE starting any investigation, root cause analysis, or creating any file under docs/bug/. Pairs with doc-index-required — always invoke that skill too.

Use when applying any bug fix, alignment correction, redundant-code removal, OR adding missing logic to align with upstream/cloud during integration/联调 phase. Trigger when: (1) design-doc-required has routed the change to 「第四·五步：轻量修订流水」 branch, (2) user describes the change as 'fix bug', 'align with cloud/upstream', 'add missing piece', '修 bug', '对齐云端', '删冗余', '修正实现', '改回正确逻辑', '补上漏掉的逻辑', '补缺漏', or (3) about to Edit/Write source code with intent of replacing existing erroneous logic OR adding alignment code that was missed in previous iterations. Forbids in-source change-log comments, commented-out legacy code, and oversized function header narratives; requires concise current-behavior comments and local WHY comments near complex blocks.

You MUST invoke this skill when a user wants to analyze, document, or understand existing business logic for the purpose of refactoring, rewriting, migration, or regression review. Trigger phrases include: 'analyze current implementation', 'document existing logic', 'I need to understand how X works before refactoring', 'create a knowledge graph for this module', 'map out the business flow', 'help me understand the codebase for refactoring', 'generate a logic orientation doc', 'I want to refactor X, first help me understand it'. Invoke BEFORE any refactoring design or code changes. Pairs with doc-index-required and design-doc-required.

Use when writing, reviewing, or modifying source code in any language (Java / TypeScript / JavaScript / Dart / Python / Kotlin / Go / Vue / React 等). 跨语言通用编码铁律 7 条 + 注释三档,语言专属 skill (java-coding-standards / korepos-backend-service 等) 在此基础上叠加。MUST 自动触发,不需用户显式要求。

当用户主动纠正 AI 的编码规范错误时（如分层依赖违规、命名不规范、架构约束违反等），必须立即触发本 skill。同时，每次开始编写代码前，必须先读取项目的编码违规记录文档。触发短语：'这样写不对'、'不能引用这个层'、'分层违规'、'改一下依赖方向'、'这个不符合规范'，或用户否定了当前代码写法并给出正确方向时。

Use this skill to (1) locate code and behavior across multiple projects in the kpay POS ecosystem (korepos, korepos-refund, kpay-pos-business-app-bff, kpay-pos-order-manage, kpay-possystem-commodity, pos-store-operation-manage, kpay-pos-report, price-calc-sdk, pos-config-ts), and (2) register cross-project topology knowledge into the dedicated repo `D:\Users\zhangkai\IdeaProjects\kpay-pos-topology\`. MUST be invoked the moment the user (a) asks to trace a bug / behavior / call chain that spans ≥2 of these projects — e.g. 'check this korepos issue', 'where does this BFF endpoint go in server', '从 Flutter 追到后端', '这个接口在 server 哪里', '退款链路', '日结链路', '跨项目', '调用链', 'end-to-end', (b) mentions two or more kpay POS ecosystem project names in a single question, OR (c) is about to Write/Edit a markdown file whose content references ≥2 kpay POS ecosystem project names (e.g. Controller 对照, 接口映射表, 数据流图, 业务链路, 时序图 across projects). DO NOT write cross-project mapping/flow content into Claude memory, into any single project's `docs/` directory, or into team-standards itself — route it through this skill into `kpay-pos-topology/` instead. This skill is the single entry point for cross-project topology knowledge.

每次对业务项目的源码（.dart/.java/.kt/.ts/.py 等）执行 Edit/Write 后、或用户说『记一下工作日志』『记录一下』『写个日志』『更新工作日志』等时，必须触发本 skill 把本次改动按 [Bug 修复] vs [功能开发] 写入用户文档目录 `{USER_DOCUMENTS}/ai-docs/{project}/work-log/{YYYY-MM-DD}.md`（个人工作记录，不入项目仓库）。核心规则：一行一条修改明细、同一 bug 多次修复合并到同一条目、同一功能多轮迭代合并到同一条目、每条目带预估工时（累计）。写入前必须先读当天日志合并现有条目，严禁为同一主题创建多条。每个会话结束前若有未登记的改动，强制回补一次。

You MUST invoke this skill the instant a user presents any new requirement, feature request, refactoring plan, asks you to analyze/evaluate/discuss implementation feasibility, OR requests any code modification/implementation — even if they only ask for analysis, architecture discussion, feasibility study, or say 'just help me change the code'. Do NOT wait until code-writing begins. Trigger phrases include: 'I have a requirement', 'I need to refactor', 'analyze whether X is feasible', 'how should we implement', 'I want to add/change/build', 'help me design', 'let's discuss the approach', 'help me modify the code', 'change the code based on this document', 'implement according to the doc', 'update this feature', '帮我修改代码', '根据文档改代码', '按文档实现', '帮我改一下', '修改这个功能', '帮我写代码', '改一下代码', '阅读文档帮我改'. ALSO trigger when: (1) the user provides or references a document and asks you to make code changes based on it, (2) you are about to call Edit/Write on any source code file (.java, .dart, .ts, .py, .kt, etc.) and this skill has not yet been invoked in the current conversation. Invoke this skill BEFORE any analysis, planning, architecture discussion, or code.

Use only for decision-level team-standards changes: adding/removing a Skill, changing a Skill's trigger timing or core behavior, reversing a rule direction, introducing a new template/workflow, changing cross-skill flow structure, or recording a multi-step design decision whose rationale may not be obvious from git history. Do NOT use for ordinary wording tweaks, README/index synchronization, version bumps, typo fixes, or small iterative rule clarifications when the git commit body can carry the rationale.

You MUST invoke this skill before creating, writing, editing, moving, or renaming ANY AI-generated Markdown — both in the user knowledge base (`{USER_DOCUMENTS}/ai-docs/{project}/`) and in project `docs/`. AI-generated Markdown defaults to the user knowledge base, and **both locations now share the same Phase-A/B index discipline** (v1.20+: user dir is no longer treated as a draft scratchpad). TRIGGER Phase-A when: (1) about to Write/Edit any .md file under `ai-docs/{project}/` (excluding the auto-managed `work-log/` and `knowledge-graph/` subtrees) or any path containing `/docs/` (at any nesting depth), (2) about to move/rename/reorganize files under either tree, (3) user explicitly says '写到 docs', '更新项目文档', '上传终版文档', '整理 docs', '移动文档', '重构文档目录'. TRIGGER Phase-B only when the file writing is complete. Do NOT touch any index target file until Phase-A is complete. Exemptions: edits to index files themselves (`INDEX.md`, `00_index.md`), daily-work-log date-named files under `work-log/`, and pure prose-only edits that do not change document structure. IMPORTANT: This applies to ALL working directories, not just the primary project.

当用户要求「生成项目画像」「生成 project profile」「扫描项目生成 Markdown」时触发。也可被外部平台（如 llm-orchestration-platform）通过指令触发，用于为 AI Agent 生成标准化的项目知识上下文。

Use when the user asks to commit code or generate a commit message AND the staged diff is non-trivial (>2 files, >30 net lines, or contains new/renamed/deleted files). For trivial commits (≤2 files, ≤30 lines, only modifications to existing files) skip this skill and write a clear `git commit` message directly — `hooks/check-git-commit-skill.js` enforces the same threshold at the Bash layer (only blocks `git commit` when staged diff exceeds it). Compose the message from the current session's edit intent first; only re-read diffs to cover gaps. Automatic stage/commit/push applies ONLY to the team-standards plugin source repository, never to business projects that merely install this plugin.

Use BEFORE answering any question that uses a domain business term (订单/账单/退款/分摊/流水/快照/对账 etc.) AND BEFORE Write/Edit any .md (设计文档 / bug 文档 / 场景文档 / orientation 文档) that introduces or relies on a business term. MUST invoke (BLOCKING) when: (1) PRD / 需求 / 设计描述里出现 ≥1 个业务领域名词且本项目术语表未登记;(2) 同一会话里用户与 AI 对同一名词使用了不同字面表达(例如用户说「退货」AI 答「退款」),需对齐到同一规范术语;(3) AI 完成代码调查发现 ≥1 个新业务术语对应的代码命名(实体类 / 表名 / 枚举 / 字段)未登记;(4) 用户主动要求「补术语」「整理术语表」「维护 glossary」「建术语表」;(5) 即将 Write/Edit 描述业务场景 / 业务流程 / 业务规则的 .md 且其中包含未登记的领域名词。范围:仅管业务领域术语 ↔ 代码命名 ↔ 同义词 三方映射,不管通用编程/技术概念(线程 / 事务 / 缓存 / 子进程等技术词汇归 backend-knowledge-graph-required 的「技术难点」)。与 init-project-docs/templates/07_glossary.md 分工:本 skill 负责会话级日常补登的精简表(轻量五栏),init-project-docs 的 07_glossary.md 负责项目初始化批量生成。

当用户要求「初始化项目文档」「生成知识图谱」「分析项目能力」「生成项目文档」时触发。渐进式构建项目知识图谱：Phase 1 核心文档 → Phase 2 映射文档 → Phase 3 流程与术语 → Phase 4 模块深度文档。支持自动模式和人工确认模式。

Use when writing, reviewing, or modifying any Java code. You MUST follow these mandatory rules at all times. Apply automatically without being asked. 通用条款见 coding-standards-common；本文件仅列 Java 独占规则（阿里巴巴黄山版强制项的 Java 专属部分）。

Use when writing, reviewing, or modifying any Markdown content that contains Mermaid diagrams, complex tables, or structured documentation. You MUST follow these mandatory rules at all times. Apply automatically without being asked. TRIGGER when: generating mermaid code blocks, writing design docs, writing bug docs, creating any .md file with diagrams or structured content; ALSO TRIGGER after completing any structural edit to a Markdown file (新增/删除/重命名 ## 或 ### 章节，或章节移动/合并/重组) to perform TOC review and detect duplicate/scattered/uncategorized sections before marking the file as done.

You MUST invoke this skill after design-doc-required or bug-doc-required completes and a confirmed document exists, but BEFORE writing any implementation code. This is the mandatory bridge between documentation and coding. Trigger: user says 'start implementing', 'now write the code', 'let's begin coding', 'help me modify the code', 'change the code', '帮我修改代码', '改代码', '开始写代码', '帮我改一下', or you are about to make the first code edit (Edit/Write on .java, .dart, .ts, .py, .kt, etc.) for the task. Do NOT write a single line of implementation code until this skill has loaded the code coordinates from the document.

当检测到项目结构变更（新增 Controller/Service/模块/数据库表/API 接口）或用户要求「更新项目文档」「同步知识图谱」时触发。负责识别哪些知识图谱文档需要更新并执行更新。

Use BEFORE answering any impact-analysis question (新增 / 修改状态 / 字段 / 同步事件 / API 会破坏哪些旧逻辑) AND BEFORE Write/Edit any source file that adds / modifies / removes a state enum / business field / sync event payload / API endpoint. MUST invoke (BLOCKING) when: (1) 用户问『加这个状态会破坏哪些旧逻辑』『这个字段哪里在用』『这个事件订阅清单』『这个 API 谁在调』等反向影响类问题;(2) AI 即将 Edit/Write 任何枚举定义文件 / 状态机定义文件 / DTO/Entity 字段定义 / 同步事件 payload 定义 / API endpoint 定义类源码;(3) AI 完成代码改动且改动涉及 ≥1 个枚举值 / 字段 / 事件 / API 的新增 / 修改 / 删除,必须同步更新对应反向索引;(4) 项目存在 docs/knowledge-graph/reverse-index/(正式索引)或用户目录候选池 ai-docs/{project}/knowledge-graph/reverse-index/_candidates.md;(5) 用户要求『建反向索引』『扫反向影响』『生成 reverse index』『冷启动反向索引』。范围:覆盖单服务内 4 类反向索引 — states.md(枚举/状态值 → 判断点)、fields.md(字段 → 读写点)、events.md(同步事件 → 订阅场景)、apis.md(API → 调用方);跨项目 API 调用方索引仍归 cross-project-locator。冷启动方式:运行 `node ${CLAUDE_PLUGIN_ROOT}/hooks/scan-reverse-index.js` 一次性扫描产出初版,后续由本 skill 增量维护。

Use this skill the moment a user proposes a concrete idea, implementation approach, architecture direction, refactor plan, asks Codex to implement a specific solution, or implies that existing code should be copied as the reference pattern. MUST run before design-doc-required planning or code changes when the user's wording contains an assumed solution. Forces Codex to separate the user's real goal from the proposed implementation, evaluate existing-code quality, risks and alternatives, then recommend the best path instead of blindly following the user or copying weak legacy code.

2 hooks across 1 event