ai-engineering-init 1.1.0

package/.cursor/commands/opsx-verify.md

@@ -0,0 +1,164 @@
+---
+name: /opsx-verify
+id: opsx-verify
+category: Workflow
+description: Verify implementation matches change artifacts before archiving
+---
+
+Verify that an implementation matches the change artifacts (specs, tasks, design).
+
+**Input**: Optionally specify a change name after `/opsx:verify` (e.g., `/opsx:verify add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **If no change name provided, prompt for selection**
+
+   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+
+   Show changes that have implementation tasks (tasks artifact exists).
+   Include the schema used for each change if available.
+   Mark changes with incomplete tasks as "(In Progress)".
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Check status to understand the schema**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used (e.g., "spec-driven")
+   - Which artifacts exist for this change
+
+3. **Get the change directory and load artifacts**
+
+   ```bash
+   openspec instructions apply --change "<name>" --json
+   ```
+
+   This returns the change directory and context files. Read all available artifacts from `contextFiles`.
+
+4. **Initialize verification report structure**
+
+   Create a report structure with three dimensions:
+   - **Completeness**: Track tasks and spec coverage
+   - **Correctness**: Track requirement implementation and scenario coverage
+   - **Coherence**: Track design adherence and pattern consistency
+
+   Each dimension can have CRITICAL, WARNING, or SUGGESTION issues.
+
+5. **Verify Completeness**
+
+   **Task Completion**:
+   - If tasks.md exists in contextFiles, read it
+   - Parse checkboxes: `- [ ]` (incomplete) vs `- [x]` (complete)
+   - Count complete vs total tasks
+   - If incomplete tasks exist:
+     - Add CRITICAL issue for each incomplete task
+     - Recommendation: "Complete task: <description>" or "Mark as done if already implemented"
+
+   **Spec Coverage**:
+   - If delta specs exist in `openspec/changes/<name>/specs/`:
+     - Extract all requirements (marked with "### Requirement:")
+     - For each requirement:
+       - Search codebase for keywords related to the requirement
+       - Assess if implementation likely exists
+     - If requirements appear unimplemented:
+       - Add CRITICAL issue: "Requirement not found: <requirement name>"
+       - Recommendation: "Implement requirement X: <description>"
+
+6. **Verify Correctness**
+
+   **Requirement Implementation Mapping**:
+   - For each requirement from delta specs:
+     - Search codebase for implementation evidence
+     - If found, note file paths and line ranges
+     - Assess if implementation matches requirement intent
+     - If divergence detected:
+       - Add WARNING: "Implementation may diverge from spec: <details>"
+       - Recommendation: "Review <file>:<lines> against requirement X"
+
+   **Scenario Coverage**:
+   - For each scenario in delta specs (marked with "#### Scenario:"):
+     - Check if conditions are handled in code
+     - Check if tests exist covering the scenario
+     - If scenario appears uncovered:
+       - Add WARNING: "Scenario not covered: <scenario name>"
+       - Recommendation: "Add test or implementation for scenario: <description>"
+
+7. **Verify Coherence**
+
+   **Design Adherence**:
+   - If design.md exists in contextFiles:
+     - Extract key decisions (look for sections like "Decision:", "Approach:", "Architecture:")
+     - Verify implementation follows those decisions
+     - If contradiction detected:
+       - Add WARNING: "Design decision not followed: <decision>"
+       - Recommendation: "Update implementation or revise design.md to match reality"
+   - If no design.md: Skip design adherence check, note "No design.md to verify against"
+
+   **Code Pattern Consistency**:
+   - Review new code for consistency with project patterns
+   - Check file naming, directory structure, coding style
+   - If significant deviations found:
+     - Add SUGGESTION: "Code pattern deviation: <details>"
+     - Recommendation: "Consider following project pattern: <example>"
+
+8. **Generate Verification Report**
+
+   **Summary Scorecard**:
+   ```
+   ## Verification Report: <change-name>
+
+   ### Summary
+   | Dimension    | Status           |
+   |--------------|------------------|
+   | Completeness | X/Y tasks, N reqs|
+   | Correctness  | M/N reqs covered |
+   | Coherence    | Followed/Issues  |
+   ```
+
+   **Issues by Priority**:
+
+   1. **CRITICAL** (Must fix before archive):
+      - Incomplete tasks
+      - Missing requirement implementations
+      - Each with specific, actionable recommendation
+
+   2. **WARNING** (Should fix):
+      - Spec/design divergences
+      - Missing scenario coverage
+      - Each with specific recommendation
+
+   3. **SUGGESTION** (Nice to fix):
+      - Pattern inconsistencies
+      - Minor improvements
+      - Each with specific recommendation
+
+   **Final Assessment**:
+   - If CRITICAL issues: "X critical issue(s) found. Fix before archiving."
+   - If only warnings: "No critical issues. Y warning(s) to consider. Ready for archive (with noted improvements)."
+   - If all clear: "All checks passed. Ready for archive."
+
+**Verification Heuristics**
+
+- **Completeness**: Focus on objective checklist items (checkboxes, requirements list)
+- **Correctness**: Use keyword search, file path analysis, reasonable inference - don't require perfect certainty
+- **Coherence**: Look for glaring inconsistencies, don't nitpick style
+- **False Positives**: When uncertain, prefer SUGGESTION over WARNING, WARNING over CRITICAL
+- **Actionability**: Every issue must have a specific recommendation with file/line references where applicable
+
+**Graceful Degradation**
+
+- If only tasks.md exists: verify task completion only, skip spec/design checks
+- If tasks + specs exist: verify completeness and correctness, skip design
+- If full artifacts: verify all three dimensions
+- Always note which checks were skipped and why
+
+**Output Format**
+
+Use clear markdown with:
+- Table for summary scorecard
+- Grouped lists for issues (CRITICAL/WARNING/SUGGESTION)
+- Code references in format: `file.ts:123`
+- Specific, actionable recommendations
+- No vague suggestions like "consider reviewing"

package/.cursor/mcp.json

@@ -0,0 +1,22 @@
+{
+  "mcpServers": {
+    "sequential-thinking": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"],
+      "description": "链式推理 - 深度分析、仔细思考、全面评估时使用"
+    },
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp"],
+      "description": "官方文档查询 - 最佳实践、官方文档、标准写法时使用"
+    },
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
+      },
+      "description": "GitHub 集成 - 查询 Issues、PR、仓库信息"
+    }
+  }
+}

package/.cursor/skills/add-skill/SKILL.md

@@ -0,0 +1,352 @@
+---
+name: add-skill
+description: |
+  当需要为框架增加新技能、为新的模块功能编写技能文档时自动使用此 Skill。
+
+  触发场景：
+  - 需要为新模块添加技能
+  - 需要为新功能编写技能文档
+  - 需要扩展框架的技能系统
+  - 需要将实现步骤转化为可复用技能
+
+  触发词：添加技能、创建技能、新技能、技能开发、写技能、技能文档、skill 创建
+---
+
+# 技能创建指南
+
+## 概述
+
+本指南用于在 RuoYi-Vue-Plus 框架中添加新的技能（Skill）。技能通过 UserPromptSubmit Hook 自动评估和激活，确保 AI 在编码前加载领域专业知识。
+
+**技能系统工作原理**：
+
+```
+用户提交问题
+  ↓ skill-forced-eval.js Hook 触发
+注入技能评估指令
+  ↓ AI 评估匹配的技能
+逐个调用 Skill(技能名)
+  ↓ 读取 .claude/skills/{技能名}/SKILL.md
+AI 获得领域知识后开始实现
+```
+
+---
+
+## YAML 头部规范
+
+每个 SKILL.md 文件**必须**以 YAML 头部开始：
+
+```yaml
+---
+name: {技能名称}
+description: |
+  {第一行：简短描述（一句话说明技能用途或定位）}
+
+  触发场景：
+  - {场景1}
+  - {场景2}
+  - {场景3}
+  （至少3个场景）
+
+  触发词：{关键词1}、{关键词2}、{关键词3}、{关键词4}、{关键词5}
+  （至少5个触发词，用中文顿号分隔）
+---
+```
+
+### name 字段规范
+
+| 规则 | 说明 | 示例 |
+|------|------|------|
+| **格式** | kebab-case（全小写，横线连接） | `json-serialization` |
+| **禁止** | 下划线、驼峰、空格 | ~~`json_serialization`~~, ~~`jsonSerialization`~~ |
+| **长度** | 1-4 个单词 | `ui-pc`, `crud-development`, `redis-cache` |
+
+### description 第一行风格
+
+第一行没有强制格式，参考现有技能的两种常见风格：
+
+**风格 A：直述型**（多数技能采用）
+```yaml
+description: |
+  后端 CRUD 开发规范。基于 RuoYi-Vue-Plus 三层架构。
+  后端安全开发规范。包含 Sa-Token 认证授权、数据脱敏。
+  后端工具类使用指南。包含 MapstructUtils、StringUtils 等。
+```
+
+**风格 B：触发型**
+```yaml
+description: |
+  当需要进行技术选型、对比方案时自动使用此 Skill。
+  当需要为框架增加新技能时自动使用此 Skill。
+```
+
+### 实际技能 YAML 头部示例
+
+```yaml
+---
+name: crud-development
+description: |
+  后端 CRUD 开发规范。基于 RuoYi-Vue-Plus 三层架构（Controller → Service → Mapper），无独立 DAO 层。
+
+  触发场景：
+  - 新建业务模块的 CRUD 功能
+  - 创建 Entity、BO、VO、Service、Mapper、Controller
+  - 分页查询、新增、修改、删除、导出
+  - 查询条件构建（buildQueryWrapper）
+
+  触发词：CRUD、增删改查、新建模块、Entity、BO、VO、Service、Mapper、Controller、分页查询、buildQueryWrapper、@AutoMapper、BaseMapperPlus、TenantEntity
+---
+```
+
+```yaml
+---
+name: redis-cache
+description: |
+  当需要使用Redis缓存、分布式锁、限流等功能时自动使用此Skill。
+
+  触发场景：
+  - 使用Redis缓存数据
+  - 配置Spring Cache缓存注解
+  - 实现分布式锁
+  - 实现接口限流
+
+  触发词：Redis、缓存、Cache、@Cacheable、@CacheEvict、@CachePut、RedisUtils、CacheUtils、分布式锁、RLock、限流、RateLimiter
+---
+```
+
+---
+
+## 第 1 步：规划
+
+### 1.1 定义技能属性
+
+创建前先明确：
+
+| 属性 | 说明 | 示例 |
+|------|------|------|
+| **名称** | kebab-case 格式 | `payment-gateway` |
+| **类别** | 后端/通用/前端（需 plus-ui） | 后端 |
+| **触发场景** | 至少 3 个具体场景 | 支付接入、退款处理、对账 |
+| **触发词** | 至少 5 个关键词 | 支付、退款、订单、对账、Payment |
+| **参考代码** | 项目中的真实代码位置 | `ruoyi-modules/ruoyi-system/` |
+
+### 1.2 检查范围冲突
+
+查看现有技能列表，确保不与已有技能重叠：
+
+**当前已有技能**（`.claude/skills/` 下 33 个）：
+
+| 分类 | 技能 |
+|------|------|
+| 后端开发 | crud-development, api-development, database-ops, backend-annotations, utils-toolkit, error-handler |
+| 安全权限 | security-guard, data-permission, tenant-management |
+| 中间件 | redis-cache, json-serialization, scheduled-jobs, file-oss-management |
+| 通信集成 | websocket-sse, sms-mail, social-login, workflow-engine |
+| 质量保障 | test-development, bug-detective, performance-doctor, code-patterns |
+| 架构决策 | architecture-design, tech-decision, brainstorm, project-navigator |
+| 工具流程 | git-workflow, task-tracker, add-skill |
+| 前端（需 plus-ui） | ui-pc, store-pc |
+| 特殊功能 | banana-image, collaborating-with-codex, collaborating-with-gemini |
+
+如果新技能与现有技能有交集，在 SKILL.md 中用"注意"段落说明边界：
+```markdown
+注意：如果是认证授权（登录、Token、Sa-Token），请使用 security-guard。
+```
+
+---
+
+## 第 2 步：编写 SKILL.md
+
+### 2.1 文件位置
+
+```
+.claude/skills/{技能名}/SKILL.md
+```
+
+### 2.2 推荐内容结构
+
+```markdown
+---
+name: {技能名称}
+description: |
+  {描述、触发场景、触发词}
+---
+
+# {技能标题}
+
+## 概述
+{简明介绍，1-2 段}
+
+## 核心工具类/API
+{主要类和方法列表}
+
+## 使用规范
+{最佳实践和规则}
+
+## 代码示例
+{真实代码片段}
+
+## 常见错误
+{正确做法 vs 错误做法对比}
+
+## 注意
+{与其他技能的边界说明}
+```
+
+### 2.3 内容质量要点
+
+- **代码示例必须来自项目实际代码**，不要虚构类名、方法名
+- **包名统一 `org.dromara.*`**，不要出现 `com.ruoyi.*`
+- **三层架构**：Controller → Service → Mapper，无 DAO 层
+- **对象转换用 `MapstructUtils.convert()`**，不要写 BeanUtils
+- 技能不需要固定行数要求，以内容实用为准（实际范围 200-650 行）
+
+### 2.4 不同类型技能的侧重
+
+| 类型 | 侧重 | 示例 |
+|------|------|------|
+| 后端开发类 | 代码模板、标准写法、禁止项 | crud-development |
+| 工具类 | API 列表、使用示例、返回值 | utils-toolkit |
+| 中间件类 | 配置方法、集成步骤、注意事项 | redis-cache |
+| 流程类 | 步骤说明、决策树、检查清单 | brainstorm |
+
+---
+
+## 第 3 步：注册技能
+
+技能需要在两个位置注册，才能被系统识别和激活。
+
+### 3.1 在 Hook 中注册
+
+**文件**：`.claude/hooks/skill-forced-eval.js`
+
+在 `可用技能（纯后端项目）：` 列表中添加一行：
+
+```javascript
+- {技能名}: {触发词，用/分隔}
+```
+
+**示例**：
+```javascript
+- payment-gateway: 支付/退款/对账/Payment/支付宝/微信支付
+```
+
+**注意**：按逻辑分组插入，不是追加到末尾。
+
+### 3.2 在 AGENTS.md 中注册
+
+**文件**：`AGENTS.md` 的"技能清单与触发条件"表格
+
+在对应分类下添加一行：
+
+```markdown
+| `{技能名}` | {触发条件简述} |
+```
+
+**示例**：
+```markdown
+| `payment-gateway` | 支付接入、退款、对账、支付宝/微信支付 |
+```
+
+### 3.3 验证注册
+
+```bash
+# 检查 hook 文件
+grep "payment-gateway" .claude/hooks/skill-forced-eval.js
+
+# 检查 AGENTS.md
+grep "payment-gateway" AGENTS.md
+```
+
+---
+
+## 第 4 步：Codex 同步
+
+项目同时支持 Claude Code（`.claude/`）和 Codex CLI（`.codex/`）两个系统。
+
+### 同步步骤
+
+```bash
+# 1. 创建 Codex 目录
+mkdir -p .codex/skills/{技能名}
+
+# 2. 复制文件
+cp .claude/skills/{技能名}/SKILL.md .codex/skills/{技能名}/SKILL.md
+
+# 3. 验证一致性
+diff .claude/skills/{技能名}/SKILL.md .codex/skills/{技能名}/SKILL.md
+```
+
+**注意**：
+- `.codex/skills/` 中额外存放斜杠命令型技能（如 dev, crud, check 等），这些不需要在 `.claude/` 中创建
+- 普通技能（非斜杠命令）需要保持两个目录一致
+
+---
+
+## 第 5 步：验证
+
+### 完整检查清单
+
+**文件**：
+- [ ] `.claude/skills/{技能名}/SKILL.md` 已创建
+- [ ] `.codex/skills/{技能名}/SKILL.md` 已同步
+
+**YAML 头部**：
+- [ ] `name` 使用 kebab-case 格式
+- [ ] description 包含触发场景（至少 3 个）
+- [ ] description 包含触发词（至少 5 个）
+- [ ] 各部分之间有空行
+
+**注册**：
+- [ ] `.claude/hooks/skill-forced-eval.js` 已添加技能条目
+- [ ] `AGENTS.md` 已添加技能条目
+
+**内容**：
+- [ ] 代码示例来自项目实际代码，无虚构内容
+- [ ] 包名使用 `org.dromara.*`
+- [ ] 与现有技能无范围冲突（或已说明边界）
+
+---
+
+## 常见陷阱
+
+### 1. 遗漏注册
+
+**症状**：技能文件存在但从不被激活
+
+**原因**：只创建了 SKILL.md，没有在 Hook 和 AGENTS.md 中注册
+
+**解决**：完成第 3 步的两处注册
+
+### 2. 触发词过于宽泛
+
+**症状**：技能在不相关场景被频繁误触发
+
+**原因**：触发词太通用（如"开发"、"功能"）
+
+**解决**：使用具体术语（如"CRUD开发"、"支付接入"）
+
+### 3. 代码示例虚构
+
+**症状**：AI 参考技能生成的代码使用了不存在的类或方法
+
+**原因**：编写技能时没有验证引用的类名、方法名在项目中真实存在
+
+**解决**：编写前用 Grep/Glob 搜索确认引用的类和方法确实存在
+
+### 4. 忘记同步到 Codex
+
+**症状**：Claude Code 中正常，Codex CLI 中找不到技能
+
+**原因**：只在 `.claude/skills/` 创建，未复制到 `.codex/skills/`
+
+**解决**：`cp .claude/skills/{技能名}/SKILL.md .codex/skills/{技能名}/SKILL.md`
+
+### 5. 技能范围与现有技能重叠
+
+**症状**：同一个问题触发多个技能，指导矛盾
+
+**解决**：在 SKILL.md 末尾添加"注意"段落说明边界，例如：
+```
+注意：如果是行级数据权限（@DataPermission），请使用 data-permission。
+```