openmatrix 0.2.4 → 0.2.6

package/skills/debug.md

@@ -0,0 +1,425 @@
+---
+name: om:debug
+description: 系统化调试 - 遇到任何 bug、测试失败或异常行为时使用，在提出修复方案之前执行
+priority: high
+---
+
+<NO-OTHER-SKILLS>
+**绝对禁止**调用以下技能：
+- ❌ superpowers:systematic-debugging → 你已经在 om:debug 中了
+- ❌ superpowers:* → 全部被 OpenMatrix 替代
+- ❌ gsd:* → 全部被 OpenMatrix 替代
+- ❌ 任何其他任务编排相关的技能
+
+**诊断和修复阶段只能使用 Agent 工具** — 直接调用 Agent，不通过任何中间层。
+</NO-OTHER-SKILLS>
+
+<MANDATORY-EXECUTION-ORDER>
+## 执行顺序 - 必须严格按此顺序，不得跳过
+
+```
+Step 1:  接收问题描述（参数、指定任务、或询问用户）
+Step 2:  调用 CLI: openmatrix debug 初始化会话
+Step 3:  第一阶段：根因调查（Explore Agent）
+Step 4:  第二阶段：模式分析（Explore Agent）
+Step 5:  展示诊断报告 + 修复建议
+Step 6:  AskUserQuestion 确认修复策略
+Step 7:  第四阶段：实施修复（Agent）
+Step 8:  验证修复结果
+Step 9:  写入 Debug Report 并展示
+```
+
+**铁律：不做根因调查，不许提修复方案**
+</MANDATORY-EXECUTION-ORDER>
+
+<objective>
+系统化调试 - 通过四阶段流程诊断和修复问题。不依赖任务流程，可独立使用。
+</objective>
+
+<process>
+
+## Step 1: 接收问题
+
+**检查 `$ARGUMENTS`:**
+
+| 参数 | 处理方式 |
+|------|---------|
+| `--task TASK-XXX` | 读取指定失败任务 |
+| `<问题描述>` | 直接使用描述 |
+| 空 | 询问用户问题描述 |
+
+**如果是空参数，询问：**
+
+AskUserQuestion: `header: "问题描述"`, `multiSelect: false`
+**question:** 请描述你遇到的问题
+
+| label | description |
+|-------|-------------|
+| 描述问题 | 输入自由文本描述 |
+| 选择失败任务 | 从当前失败任务中选择 |
+| 取消 | 退出调试模式 |
+
+**如果有失败任务（检查 .openmatrix/state.json）：**
+```bash
+cat .openmatrix/state.json 2>/dev/null | grep -o '"failed":[0-9]*'
+```
+如果 `statistics.failed > 0`，读取 `.openmatrix/tasks/` 目录找到 failed 任务并展示。
+
+## Step 2: 调用 CLI 初始化
+
+**带任务 ID：**
+```bash
+openmatrix debug --task TASK-XXX --json
+```
+
+**带描述：**
+```bash
+openmatrix debug "问题描述" --json
+```
+
+CLI 返回：
+```json
+{
+  "sessionId": "DEBUG-xxx",
+  "status": "diagnosing",
+  "problemType": "task_failure",
+  "report": {
+    "description": "...",
+    "relatedTaskId": "TASK-003",
+    "relatedFiles": ["src/xxx.ts"]
+  }
+}
+```
+
+从返回结果中读取 `sessionId`，后续步骤使用此 ID。
+
+## Step 3: 第一阶段 - 根因调查
+
+**调用 Explore Agent：**
+
+```typescript
+Agent({
+  subagent_type: "Explore",
+  description: "根因调查 - 第一阶段",
+  prompt: `你是调试专家。正在进行系统化调试的第一阶段：根因调查。
+
+**铁律：在找到根因之前，不要提出任何修复方案。**
+
+## 问题信息
+- 问题类型: ${problemType}
+- 问题描述: ${description}
+${relatedTaskId ? `- 关联任务: ${relatedTaskId}` : ''}
+
+## 任务
+1. 仔细阅读所有错误信息（不要跳过任何警告或错误）
+2. 收集相关文件和日志
+3. 检查近期代码变更（git diff、最近提交）
+4. 如果有多个组件，追踪数据流，找到断裂点
+5. 定位问题根源
+
+## 输出格式
+请按以下格式输出：
+
+### 错误信息
+- 错误类型: ...
+- 错误位置: 文件:行号
+- 错误详情: ...
+
+### 复现步骤
+1. ...
+
+### 近期变更
+- 提交1: 描述
+- 提交2: 描述
+
+### 根因分析
+[详细描述问题根源]
+
+### 影响范围
+- 文件1
+- 文件2
+
+## 禁止行为
+❌ 提出修复方案
+❌ 修改任何文件
+❌ 做出未经证实的假设`,
+  run_in_background: false
+})
+```
+
+## Step 4: 第二阶段 - 模式分析
+
+**调用 Explore Agent：**
+
+```typescript
+Agent({
+  subagent_type: "Explore",
+  description: "模式分析 - 第二阶段",
+  prompt: `继续进行系统化调试的第二阶段：模式分析。
+
+## 第一阶段发现
+
+${第一阶段根因调查的完整输出}
+
+## 任务
+1. 在代码库中找到类似的、正常工作的代码
+2. 对比正常代码和异常代码的差异
+3. 列出所有差异点（无论多小）
+4. 理解功能依赖关系和隐含假设
+
+## 输出格式
+
+### 正常示例
+- 文件: path:line
+- 说明: 为什么这段代码能正常工作
+
+### 差异点
+1. 差异1: 正常代码 vs 异常代码
+2. 差异2: ...
+
+### 依赖关系
+- 需要哪些前置条件
+- 有哪些隐含假设`,
+  run_in_background: false
+})
+```
+
+## Step 5: 展示诊断报告
+
+**第一阶段和第二阶段完成后，展示诊断报告：**
+
+```
+🔍 诊断报告
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+问题类型: xxx
+
+根因分析
+  [来自第一阶段调查的根因描述]
+
+正常示例
+  文件: path:line
+  说明: ...
+
+差异点
+  1. ...
+  2. ...
+
+影响范围
+  - 文件1
+  - 文件2
+
+修复建议
+  [基于差异分析的具体修复建议]
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## Step 6: 确认修复策略
+
+AskUserQuestion: `header: "修复策略"`, `multiSelect: false`
+**question:** 诊断完成，选择修复策略？
+
+| label | description |
+|-------|-------------|
+| 自动修复 (推荐) | 调用 Agent 执行修复 |
+| 手动修复 | 仅展示建议，用户自行修复 |
+| 跳过 | 不修复，仅记录诊断报告 |
+| 继续深入 | 根因不够清晰，继续调查 |
+
+**用户选择 "继续深入"** → 回到 Step 3，带着新信息重新调查。
+
+## Step 7: 实施修复
+
+**如果用户选择自动修复：**
+
+**修复前安全检查（必须执行）：**
+```bash
+git status --porcelain
+git log --oneline -5
+```
+
+```typescript
+Agent({
+  subagent_type: "general-purpose",
+  description: "实施 bug 修复",
+  prompt: `根据诊断报告执行修复。
+
+## 铁律
+1. 只实施单一修复（不要做额外改动）
+2. 每次只改一个变量
+3. 不在诊断不清的情况下盲目尝试
+4. 不做"顺便"的重构
+
+## 诊断报告
+${诊断报告全文}
+
+## 修复建议
+${suggestedFix}
+
+## 任务
+1. 根据修复建议实施修改
+2. 确保修改范围最小化
+3. 完成后输出修改了哪些文件和具体改动
+
+## 禁止行为
+❌ 修改与修复无关的文件
+❌ 进行额外的重构
+❌ 同时修复多个问题`,
+  run_in_background: false
+})
+```
+
+**Agent 完成后：**
+1. 检查 Git 状态
+2. 提交修复（如果文件有变更）
+3. 进入 Step 8 验证
+
+## Step 8: 验证修复
+
+**根据问题类型选择验证方式：**
+
+| 问题类型 | 验证方式 |
+|---------|---------|
+| task_failure | 重新运行失败任务或相关测试 |
+| project_bug | 运行相关测试或构建 |
+| system_bug | 验证 CLI 功能 |
+| environment | 检查依赖安装状态 |
+
+**任务失败：**
+```bash
+# 运行相关测试
+npm test -- --run 2>&1 | tail -20
+```
+
+**项目 bug：**
+```bash
+npm run build 2>&1 | tail -10
+```
+
+**环境：**
+```bash
+npm ls --depth=0 2>&1 | tail -20
+```
+
+**验证结果判断：**
+- 测试全通过 / 构建成功 → 验证通过
+- 仍有失败 / 构建失败 → 验证未通过
+
+AskUserQuestion: `header: "验证结果"`, `multiSelect: false`
+**question:** 修复验证通过了吗？
+
+| label | description |
+|-------|-------------|
+| 通过 | 修复成功，记录报告 |
+| 未通过 | 修复未生效，重新分析 |
+| 部分通过 | 部分修复，继续诊断 |
+
+**如果验证未通过：**
+- 重试计数 +1
+- **< 3 次** → 回到 Step 3（带着新信息重新分析）
+- **>= 3 次** → 输出"已尝试 3 次以上修复，建议暂停并质疑架构"，进入 Step 9
+
+## Step 9: 写入 Debug Report
+
+完成调试会话：
+```bash
+openmatrix debug --list
+```
+
+**生成诊断报告文件（在界面输出）：**
+
+```markdown
+# Debug Report
+
+**会话 ID**: ${sessionId}
+**日期**: ${timestamp}
+**状态**: ${status}
+
+## 问题描述
+${description}
+
+## 问题类型
+${problemType}
+
+## 诊断结果
+### 根因
+${rootCause}
+
+### 影响范围
+${impactScope}
+
+## 修复操作
+${operations}
+
+## 验证结果
+${verifyResult}
+
+## 经验教训
+${lessons}
+```
+
+**Git 提交修复（如果有文件变更）：**
+```bash
+git status --porcelain
+# 如果有未提交文件：
+git add -A && git commit -m "$(cat <<'EOF'
+fix: 修复 bug - 问题描述
+
+根因: ...
+修复: ...
+
+影响范围: ...
+文件改动: ...
+
+Co-Authored-By: OpenMatrix https://github.com/bigfish1913/openmatrix
+EOF
+)"
+```
+
+</process>
+
+<arguments>
+$ARGUMENTS
+</arguments>
+
+<examples>
+/om:debug                          # 交互式调试
+/om:debug --task TASK-003          # 调试指定失败任务
+/om:debug "API 返回 500 错误"      # 带问题描述调试
+</examples>
+
+<notes>
+## 四阶段流程
+
+```
+Step 1: 接收问题
+    ↓
+Step 2: CLI 初始化会话
+    ↓
+Step 3: 第一阶段 - 根因调查（只读）
+    ↓
+Step 4: 第二阶段 - 模式分析（只读）
+    ↓
+Step 5: 展示诊断报告 + 修复建议
+    ↓
+Step 6: AskUserQuestion 确认修复策略
+    ↓
+Step 7: 第三/四阶段 - 实施修复
+    ↓
+Step 8: 验证修复结果
+    ↓
+Step 9: 写入 Debug Report
+```
+
+## 铁律
+
+**不做根因调查，不许提修复方案**
+
+## 红线
+
+- 3 次修复失败 → 暂停，质疑架构
+- 不修改未关联的文件
+- 单一修复原则
+- 修复前必须有验证方法
+</notes>

package/skills/meeting.md

@@ -1,10 +1,12 @@
 ---
 name: om:meeting
-description: 查看和处理所有待确认的 Meeting（阻塞问题和决策点）
+description: "Use when handling blocked tasks, technical decisions, or workflow interruptions during OpenMatrix execution. Triggers on: 阻塞, blocked, 决策, decision needed, 技术选型, database connection failed, API key missing, merge conflict, dependency issue, task cannot proceed. Use when the user reports something is stuck, waiting for info, or needs to make a choice that blocks execution."
 ---
 
 <NO-OTHER-SKILLS>
 执行此技能时，不得调用 superpowers、gsd 或其他任务编排相关的技能。OpenMatrix 独立运行，不依赖外部任务编排系统。
+
+**相关技能**: `/om:start` (任务执行) | `/om:approve` (审批处理) | `/om:status` (状态查看)
 </NO-OTHER-SKILLS>
 
 <objective>
@@ -251,40 +253,23 @@ $ARGUMENTS
 </examples>
 
 <notes>
-## Meeting 类型
-
-| 类型 | 图标 | 说明 |
-|------|------|------|
-| 阻塞 | 🔴 | 任务执行遇到阻塞，需要信息或决策 |
-| 决策 | 🤔 | 技术选型或设计方案决策 |
-
-## 操作类型
+## Meeting 类型与操作
 
-| 操作 | 说明 | 后续 |
-|------|------|------|
-| provide-info | 提供解决信息 | 任务恢复执行 |
-| skip | 跳过任务 | 标记可选，下游继续 |
-| retry | 重试任务 | 重新执行当前任务 |
-| modify | 修改方案 | 更新任务后重试 |
-| decide | 做出决策 | 记录决策并继续 |
-| cancel | 取消任务 | 停止相关下游任务 |
+| 类型 | 图标 | 操作 | 后续 |
+|------|------|------|------|
+| 阻塞 | 🔴 | provide-info/skip/retry/modify | 提供信息后恢复执行 |
+| 决策 | 🤔 | decide/cancel | 记录决策并继续 |
 
 ## CLI 命令
 
 ```bash
-# 列出所有 Meeting
-openmatrix meeting --list
-
-# 处理指定 Meeting
-openmatrix meeting APPR-001 --action provide-info --info "..."
-openmatrix meeting APPR-001 --action skip --message "..."
-openmatrix meeting APPR-001 --action retry
-openmatrix meeting APPR-001 --action modify --new-plan "..."
-openmatrix meeting APPR-001 --action decide --reason "选择方案A，因为..."
-openmatrix meeting APPR-001 --action cancel --message "取消执行"
-
-# 批量操作
-openmatrix meeting --skip-all --message "批量跳过"
+openmatrix meeting --list                              # 列出所有 Meeting
+openmatrix meeting APPR-001 --action provide-info --info "..."  # 提供信息
+openmatrix meeting APPR-001 --action skip --message "..."       # 跳过
+openmatrix meeting APPR-001 --action retry                      # 重试
+openmatrix meeting APPR-001 --action modify --new-plan "..."    # 修改方案
+openmatrix meeting APPR-001 --action decide --reason "..."      # 决策
+openmatrix meeting --skip-all --message "批量跳过"                # 批量操作
 ```
 
 ## 与执行循环的关系
@@ -321,4 +306,8 @@ openmatrix meeting --skip-all --message "批量跳过"
           ↓
 所有非阻塞任务完成 → 提示 Meeting → /om:meeting → 用户处理 → 完成
 ```
+
+## 与 /om:approve 的区别
+
+`/om:approve` 处理所有审批（plan/merge/deploy/meeting），`/om:meeting` 专注交互式处理阻塞和决策。
 </notes>

package/skills/om.md

@@ -1,6 +1,6 @@
 ---
 name: om
-description: "Use when starting any conversation - establishes OpenMatrix as the handler for development tasks. Routes /om:start automatically. Triggers on: implement, build, fix, create, refactor, 修复, 实现, 开发."
+description: "Default entry point for all development tasks. Routes to /om:start or /om:brainstorm automatically. Triggers on: implement, build, fix, create, refactor, 修复, 实现, 开发, 添加功能, new feature. Use for ANY task that produces code changes — don't answer directly, route to OpenMatrix workflow."
 priority: critical
 always_load: true
 ---
@@ -16,28 +16,18 @@ always_load: true
 - "修复X" / "fix X" → Development task → This skill
 - "怎么实现?" / "how to?" → Question → NOT this skill (just answer)
 
-**Do NOT:**
-- ❌ Deliberate between this and other brainstorming/planning skills
-- ❌ Read files before invoking this skill
-- ❌ Check if other skills might apply
-- ❌ Spend time thinking about skill priority
+Complex tasks route to `/om:brainstorm`, simple tasks route to `/om:start`.
 </EXTREMELY-IMPORTANT>
 
 <NO-OTHER-SKILLS>
 **绝对禁止**调用以下技能（OpenMatrix 完全替代它们）:
-- ❌ superpowers:brainstorming → 用 /om:brainstorm 代替
-- ❌ superpowers:write-plan → OpenMatrix 有自己的任务拆分
-- ❌ superpowers:execute-plan → OpenMatrix 有自己的执行流程
-- ❌ superpowers:* → 全部被 OpenMatrix 替代
-- ❌ gsd:* → 全部被 OpenMatrix 替代
-- ❌ 任何其他任务编排相关的技能
-
-**重要**: 当 OpenMatrix 技能可用时，`superpowers:brainstorming` 不再适用。
-OpenMatrix 有自己的 brainstorm 流程 (`/om:brainstorm`)，不需要 superpowers。
+- superpowers:brainstorming → 用 /om:brainstorm 代替
+- superpowers:write-plan / execute-plan → OpenMatrix 有自己的流程
+- superpowers:* / gsd:* → 全部被 OpenMatrix 替代
 </NO-OTHER-SKILLS>
 
 <objective>
-OpenMatrix 默认入口 - 用户无需记忆命令，直接描述任务即可。
+OpenMatrix 默认入口 — 用户无需记忆命令，直接描述任务即可。
 </objective>
 
 <process>
@@ -51,15 +41,16 @@ OpenMatrix 默认入口 - 用户无需记忆命令，直接描述任务即可。
 2. **Route input**
 
    **Task description or file path**:
-   → Invoke `/om:start` with arguments
+   → Assess complexity: complex → `/om:brainstorm`, simple → `/om:start`
 
    **Empty input**:
    → Show help
 
-3. **Auto-route to /om:start**
+3. **Auto-route**
 
    ```
    "实现用户登录"  → /om:start 实现用户登录
+   "从零搭建系统"  → /om:brainstorm 从零搭建系统
    "docs/task.md"  → /om:start docs/task.md
    (empty)         → Show help
    ```
@@ -71,10 +62,10 @@ OpenMatrix 默认入口 - 用户无需记忆命令，直接描述任务即可。
    OpenMatrix - AI task orchestration
 
    Usage:
-     /om <task>           Start task
-     /om:brainstorm <task> Brainstorm first
-     /om:start <task>      Interactive start
-     /om:auto <task>       Full auto
+     /om <task>              Start task
+     /om:brainstorm <task>   Brainstorm first
+     /om:start <task>        Interactive start
+     /om:auto <task>         Full auto
 
    Examples:
      /om 实现用户登录功能
@@ -91,6 +82,7 @@ OpenMatrix 默认入口 - 用户无需记忆命令，直接描述任务即可。
      /om:status      - View status
      /om:meeting     - Handle blockers
      /om:report      - Generate report
+     /om:debug       - Systematic debugging (bug/error investigation)
    ```
 </process>
 
@@ -99,14 +91,14 @@ $ARGUMENTS
 </arguments>
 
 <examples>
-/om 实现用户登录功能              # Auto start
-/om 修复登录页面的样式问题        # Direct description
-/om docs/task.md                 # From file
-/om                              # Show help
+/om 实现用户登录功能              → /om:start (简单)
+/om 从零搭建后台系统               → /om:brainstorm (复杂)
+/om 修复登录页面的样式问题        → /om:start (简单)
+/om docs/task.md                 → /om:start (从文件)
+/om                              → Show help
 </examples>
 
 <notes>
-`/om` is a shortcut for `/om:start`:
-- `/om <task>` ≡ `/om:start <task>`
-- Same functionality, simpler UX
+`/om` is shorthand for the OpenMatrix workflow. Same skill set as `openmatrix`, shorter invocation.
+Available commands: `/om:brainstorm`, `/om:start`, `/om:auto`, `/om:status`, `/om:meeting`, `/om:report`, `/om:resume`, `/om:retry`, `/om:research`, `/om:approve`, `/om:check`, `/om:debug`
 </notes>

package/skills/openmatrix.md

@@ -48,6 +48,13 @@ Is the user asking me to PRODUCE code changes?
 **IMPORTANT:** OpenMatrix includes its own brainstorm mode (`/om:brainstorm`).
 When a development task is complex (new feature, multi-module, from-scratch), use `/om:brainstorm`.
 When a development task is simple (bug fix, small change, clear requirement), use `/om:start`.
+
+**Related skills:**
+- `/om:auto` — 全自动执行，无需审批
+- `/om:status` — 查看执行进度
+- `/om:meeting` — 处理阻塞问题
+- `/om:report` — 生成执行报告
+- `/om:resume` / `/om:retry` — 恢复/重试
 </EXTREMELY-IMPORTANT>
 
 <NO-OTHER-SKILLS>
@@ -110,3 +117,13 @@ Detect development task intent and route to OpenMatrix's internal workflow.
 | `从零搭建后台管理` | Build | Complex | → `/om:brainstorm` |
 | `怎么实现登录?` | Ask | - | ❌ Direct answer |
 | `这个函数有什么问题?` | Ask | - | ❌ Direct answer |
+
+## Common Mistakes
+
+| Mistake | Why it's wrong | Fix |
+|---------|---------------|-----|
+| Answering "如何实现 X" directly when user clearly wants to build it | "How to" can be a question OR a build request — check context | If paired with a file or project context → route to OpenMatrix |
+| Deliberating between multiple skills before acting | Wastes tokens, delays execution | First match wins — if it looks like dev work, invoke immediately |
+| Reading files before deciding which skill to use | Files lack conversation context | Decision is based on user intent, not file contents |
+| Using superpowers:brainstorming when om:brainstorm is available | Duplicate workflow, inconsistent state | om:brainstorm integrates with OpenMatrix task lifecycle |
+| Skipping `/om:brainstorm` for complex tasks | Leads to poor planning and rework | Multi-module or unclear requirements → brainstorm first |

package/skills/report.md

@@ -1,6 +1,6 @@
 ---
 name: om:report
-description: 生成任务执行报告
+description: "Use when generating a task execution report with statistics, task details, approval history, and agent performance. Triggers on: 报告, report, summary, 总结, execution stats, 统计, sprint report, weekly summary, 产出物, deliverables overview."
 ---
 
 <NO-OTHER-SKILLS>

package/skills/research.md

@@ -1,10 +1,12 @@
 ---
 name: om:research
-description: 领域调研和问题探索 - 为后续任务提供知识基础
+description: "Use when conducting domain research before implementing vertical-domain tasks. Triggers on: 领域调研, research, game development, payment system, blockchain, AI application, 行业标准, tech stack exploration, domain analysis, unfamiliar vertical, need to understand the domain before building."
 ---
 
 <NO-OTHER-SKILLS>
 执行此技能时，不得调用其他任务编排相关的技能。OpenMatrix 独立运行，不依赖外部任务编排系统。
+
+**相关技能**: `/om:brainstorm` (需求探索) | `/om:start` (任务执行)
 </NO-OTHER-SKILLS>
 
 <objective>

package/skills/resume.md

@@ -1,6 +1,6 @@
 ---
 name: om:resume
-description: 恢复中断或暂停的任务执行
+description: "Use when resuming interrupted or paused task execution. Triggers on: 恢复, resume, continue task, 继续执行, interrupted, 中断, paused, 暂停, retry from checkpoint, 从断点继续."
 ---
 
 <NO-OTHER-SKILLS>

package/skills/retry.md

@@ -1,6 +1,6 @@
 ---
 name: om:retry
-description: 重试失败的任务
+description: "Use when retrying failed tasks after execution errors, test failures, or timeouts. Triggers on: 重试, retry, failed task, 失败任务, rerun, 重新执行, test failure, timeout, 超时, error recovery."
 ---
 
 <NO-OTHER-SKILLS>