@waoooo/claude-skills 1.0.0

package/skills/task-update-status/SKILL.md

@@ -0,0 +1,349 @@
+# Skill: task-update-status
+
+## 功能
+
+更新 OpenSpec tasks.md 中的任务状态标记（`- [ ]` → `- [x]`）。
+
+## 何时调用
+
+- 步骤 17：任务验证通过后
+- 需要标记任务完成时
+- 回写 OpenSpec 状态时
+
+## 输入
+
+- `taskId` - 任务 ID（例如：TASK-001）
+- `jobId` - Job ID（例如：2026-02-10-1520-pricing-system）
+- `openspecPath` - OpenSpec 目录路径（例如：openspec/changes/001-pricing-system/）
+- `status` - 新状态（pending / in-progress / completed / failed）
+
+## 输出
+
+- 更新后的 tasks.md
+- 更新日志
+
+## 执行步骤
+
+### 1. 读取 tasks.md
+
+```typescript
+const tasksPath = `${openspecPath}/tasks.md`
+const content = readFile(tasksPath)
+```
+
+### 2. 定位任务
+
+```typescript
+// 从 tasks.json 获取任务信息
+const tasks = JSON.parse(readFile(`exports/jobs/${jobId}/specs/tasks.json`))
+const task = tasks.tasks.find(t => t.taskId === taskId)
+
+if (!task) {
+  throw new Error(`Task ${taskId} not found`)
+}
+
+// 获取任务在 MDX 中的引用信息
+const mdxRef = task.mdxRef
+// mdxRef: { file, line, marker }
+```
+
+### 3. 更新状态标记
+
+```typescript
+const lines = content.split('\n')
+
+// 方法 1：通过 marker 精确匹配
+if (mdxRef && mdxRef.marker) {
+  const targetLine = lines.findIndex(line => 
+    line.trim() === mdxRef.marker.trim()
+  )
+  
+  if (targetLine !== -1) {
+    // 更新状态
+    if (status === 'completed') {
+      lines[targetLine] = lines[targetLine].replace('- [ ]', '- [x]')
+    } else if (status === 'pending') {
+      lines[targetLine] = lines[targetLine].replace('- [x]', '- [ ]')
+    }
+  }
+}
+
+// 方法 2：通过任务标题模糊匹配
+else {
+  const taskTitle = task.title
+  const targetLine = lines.findIndex(line => 
+    line.includes(taskTitle) && 
+    (line.includes('- [ ]') || line.includes('- [x]'))
+  )
+  
+  if (targetLine !== -1) {
+    if (status === 'completed') {
+      lines[targetLine] = lines[targetLine].replace('- [ ]', '- [x]')
+    } else if (status === 'pending') {
+      lines[targetLine] = lines[targetLine].replace('- [x]', '- [ ]')
+    }
+  }
+}
+
+const updatedContent = lines.join('\n')
+```
+
+### 4. 写入文件
+
+```typescript
+writeFile(tasksPath, updatedContent)
+```
+
+### 5. 记录更新日志
+
+```typescript
+const log = {
+  taskId: taskId,
+  jobId: jobId,
+  updatedAt: new Date().toISOString(),
+  file: 'tasks.md',
+  oldStatus: task.status,
+  newStatus: status,
+  line: targetLine,
+  change: {
+    before: lines[targetLine],
+    after: updatedContent.split('\n')[targetLine]
+  }
+}
+
+// 追加到更新日志
+appendFile(
+  `exports/jobs/${jobId}/logs/status-updates.jsonl`,
+  JSON.stringify(log) + '\n'
+)
+```
+
+## 状态标记格式
+
+### Markdown 任务列表格式
+
+```markdown
+## Phase 1: Foundation
+
+### 任务列表
+
+- [ ] 实现支付 API
+- [ ] 添加多货币支持
+- [x] 集成 Stripe
+- [ ] 编写测试
+```
+
+### 支持的状态
+
+| 状态 | Markdown | 说明 |
+|------|----------|------|
+| pending | `- [ ]` | 待开始 |
+| in-progress | `- [ ]` | 进行中（不改变标记） |
+| completed | `- [x]` | 已完成 |
+| failed | `- [ ]` | 失败（恢复为待开始） |
+
+### 嵌套任务
+
+```markdown
+- [ ] 实现支付功能
+  - [x] 设计接口
+  - [x] 实现 Stripe 集成
+  - [ ] 添加 webhook 处理
+  - [ ] 编写测试
+```
+
+**处理逻辑**：
+- 只更新主任务的状态
+- 子任务状态由开发者手动更新
+- 或根据子任务完成情况自动更新主任务
+
+## 使用示例
+
+### 示例 1：标记任务完成
+
+```
+Agent 调用 task-update-status:
+  输入:
+  - taskId: TASK-001
+  - jobId: 2026-02-10-1520-pricing-system
+  - openspecPath: openspec/changes/001-pricing-system/
+  - status: completed
+
+执行:
+  🔧 步骤 1: 读取 tasks.md
+  ⏳ 文件: openspec/changes/001-pricing-system/tasks.md
+  ⏳ 总行数: 156 行
+
+  🔧 步骤 2: 定位任务
+  ⏳ 任务: TASK-001 - Develop payment-gateway capability
+  ⏳ 引用: line 42, marker: "- [ ] Develop payment-gateway capability"
+  ✅ 找到: 第 42 行
+
+  🔧 步骤 3: 更新状态
+  📝 修改前: - [ ] Develop payment-gateway capability
+  📝 修改后: - [x] Develop payment-gateway capability
+
+  🔧 步骤 4: 写入文件
+  ✅ 已保存: tasks.md
+
+  🔧 步骤 5: 记录日志
+  ✅ 已记录: logs/status-updates.jsonl
+
+显示结果:
+  ✅ 状态已更新
+
+  📝 更新信息:
+  - 任务: TASK-001
+  - 文件: tasks.md (第 42 行)
+  - 状态: pending → completed
+  - 标记: [ ] → [x]
+
+  💡 下一步:
+  继续更新 progress.json
+```
+
+### 示例 2：批量更新
+
+```
+Agent 调用 task-update-status (批量):
+  输入:
+  - taskIds: [TASK-001, TASK-002, TASK-003]
+  - jobId: 2026-02-10-1520-pricing-system
+  - openspecPath: openspec/changes/001-pricing-system/
+  - status: completed
+
+执行:
+  🔧 批量更新 3 个任务
+
+  ⏳ TASK-001: 第 42 行 ✅
+  ⏳ TASK-002: 第 58 行 ✅
+  ⏳ TASK-003: 第 73 行 ✅
+
+显示结果:
+  ✅ 批量更新完成
+
+  📊 更新统计:
+  - 总计: 3 个任务
+  - 成功: 3 个 ✅
+  - 失败: 0 个
+```
+
+### 示例 3：任务未找到
+
+```
+Agent 调用 task-update-status:
+  输入:
+  - taskId: TASK-999
+  - jobId: 2026-02-10-1520-pricing-system
+  - openspecPath: openspec/changes/001-pricing-system/
+  - status: completed
+
+执行:
+  🔧 步骤 1-2: 读取和定位
+
+  ❌ 错误: 任务未找到
+  🔍 原因: tasks.md 中没有找到 TASK-999 的标记
+
+显示结果:
+  ❌ 更新失败
+
+  💡 建议:
+  1. 检查 taskId 是否正确
+  2. 检查 tasks.md 中是否有对应任务
+  3. 或手动添加任务标记
+```
+
+## 智能匹配策略
+
+### 1. 精确匹配（优先）
+
+```typescript
+// 使用 mdxRef.marker 精确匹配
+const exactMatch = lines.findIndex(line => 
+  line.trim() === mdxRef.marker.trim()
+)
+```
+
+### 2. 标题匹配
+
+```typescript
+// 使用任务标题匹配
+const titleMatch = lines.findIndex(line => 
+  line.includes(task.title) && 
+  (line.includes('- [ ]') || line.includes('- [x]'))
+)
+```
+
+### 3. 模糊匹配
+
+```typescript
+// 使用关键词匹配
+const keywords = task.title.split(' ').filter(w => w.length > 3)
+const fuzzyMatch = lines.findIndex(line => 
+  keywords.some(kw => line.includes(kw)) &&
+  (line.includes('- [ ]') || line.includes('- [x]'))
+)
+```
+
+### 4. 行号匹配（最后手段）
+
+```typescript
+// 使用 mdxRef.line 直接定位
+if (mdxRef && mdxRef.line) {
+  const lineMatch = mdxRef.line - 1 // 转换为 0-based index
+  if (lines[lineMatch].includes('- [ ]') || lines[lineMatch].includes('- [x]')) {
+    // 使用这一行
+  }
+}
+```
+
+## 错误处理
+
+### 错误 1：tasks.md 不存在
+
+```
+❌ 错误: tasks.md 文件不存在
+🔍 原因: openspec/changes/001-pricing-system/tasks.md 未找到
+
+💡 建议:
+1. 检查 OpenSpec 路径
+2. 确认 tasks.md 文件存在
+3. 重新生成 OpenSpec
+```
+
+### 错误 2：任务标记未找到
+
+```
+❌ 错误: 任务标记未找到
+🔍 原因: tasks.md 中没有 TASK-001 的标记
+
+💡 建议:
+1. 检查任务标题是否匹配
+2. 手动添加任务标记
+3. 或更新 mdxRef 信息
+```
+
+### 错误 3：文件写入失败
+
+```
+❌ 错误: 文件写入失败
+🔍 原因: 没有写入权限
+
+💡 建议:
+1. 检查文件权限
+2. 确认文件未被锁定
+```
+
+## 注意事项
+
+1. **精确匹配** - 优先使用 mdxRef.marker 精确匹配
+2. **保持格式** - 只修改状态标记，保持其他格式不变
+3. **原子操作** - 读取-修改-写入作为原子操作
+4. **日志记录** - 记录每次更新，便于追溯
+5. **幂等性** - 多次调用结果一致
+
+## 相关文件
+
+- `openspec/changes/<change-id>/tasks.md` - OpenSpec 任务列表
+- `exports/jobs/<job-id>/specs/tasks.json` - 任务详情
+- `exports/jobs/<job-id>/logs/status-updates.jsonl` - 更新日志

package/skills/task-update-status/scripts/update-task-status.ts

@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+/**
+ * Update Task Status in OpenSpec tasks.md
+ * 
+ * This script updates task status in OpenSpec tasks.md file:
+ * - Mark task as completed: `- [ ]` → `- [x]`
+ * - Update task metadata (completion time, notes)
+ * 
+ * Usage:
+ *   npx tsx update-task-status.ts \
+ *     --openspec <openspec-path> \
+ *     --task <task-id> \
+ *     --status <completed|in_progress|failed>
+ * 
+ * Example:
+ *   npx tsx update-task-status.ts \
+ *     --openspec openspec/changes/001-pricing-system/ \
+ *     --task TASK-001 \
+ *     --status completed
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// ============================================================================
+// Types
+// ============================================================================
+
+type TaskStatus = 'completed' | 'in_progress' | 'failed' | 'pending';
+
+interface UpdateOptions {
+  openspecPath: string;
+  taskId: string;
+  status: TaskStatus;
+  notes?: string;
+}
+
+// ============================================================================
+// CLI Arguments
+// ============================================================================
+
+function parseArgs(): UpdateOptions {
+  const args = process.argv.slice(2);
+  const result: any = {};
+
+  for (let i = 0; i < args.length; i += 2) {
+    const key = args[i].replace('--', '');
+    const value = args[i + 1];
+    result[key] = value;
+  }
+
+  if (!result.openspec || !result.task || !result.status) {
+    console.error('❌ Missing required arguments');
+    console.error('Usage: update-task-status.ts --openspec <path> --task <id> --status <status>');
+    process.exit(1);
+  }
+
+  return {
+    openspecPath: result.openspec,
+    taskId: result.task,
+    status: result.status as TaskStatus,
+    notes: result.notes,
+  };
+}
+
+// ============================================================================
+// OpenSpec tasks.md Operations
+// ============================================================================
+
+function readTasksFile(openspecPath: string): string {
+  const tasksPath = path.join(openspecPath, 'tasks.md');
+  
+  if (!fs.existsSync(tasksPath)) {
+    throw new Error(`tasks.md not found: ${tasksPath}`);
+  }
+
+  return fs.readFileSync(tasksPath, 'utf-8');
+}
+
+function writeTasksFile(openspecPath: string, content: string): void {
+  const tasksPath = path.join(openspecPath, 'tasks.md');
+  fs.writeFileSync(tasksPath, content, 'utf-8');
+}
+
+function updateTaskStatus(content: string, taskId: string, status: TaskStatus, notes?: string): string {
+  const lines = content.split('\n');
+  let updated = false;
+  let inTask = false;
+  let taskIndent = 0;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+
+    // Find task by ID (in comment or heading)
+    if (line.includes(taskId)) {
+      inTask = true;
+      taskIndent = line.search(/\S/); // Get indentation level
+      continue;
+    }
+
+    // Update checkbox if we're in the target task
+    if (inTask && line.match(/^[\s]*-\s+\[[ x]\]/)) {
+      const currentIndent = line.search(/\S/);
+      
+      // Check if this is a subtask (more indented) or next task (same/less indented)
+      if (currentIndent > taskIndent) {
+        // This is a subtask, skip it
+        continue;
+      } else if (currentIndent === taskIndent) {
+        // This is the task checkbox
+        if (status === 'completed') {
+          lines[i] = line.replace(/- \[ \]/, '- [x]');
+        } else if (status === 'in_progress') {
+          lines[i] = line.replace(/- \[x\]/, '- [ ]');
+        } else if (status === 'failed') {
+          lines[i] = line.replace(/- \[ \]/, '- [x]') + ' ❌';
+        }
+        
+        // Add completion note if provided
+        if (notes && status === 'completed') {
+          const noteIndent = ' '.repeat(currentIndent + 2);
+          lines.splice(i + 1, 0, `${noteIndent}> ✅ Completed: ${notes}`);
+        }
+        
+        updated = true;
+        inTask = false;
+        break;
+      } else {
+        // Next task at same or lower level, stop
+        inTask = false;
+        break;
+      }
+    }
+  }
+
+  if (!updated) {
+    throw new Error(`Task ${taskId} not found in tasks.md`);
+  }
+
+  return lines.join('\n');
+}
+
+// ============================================================================
+// Main
+// ============================================================================
+
+async function main() {
+  console.log('🔧 Updating task status in OpenSpec...\n');
+
+  const options = parseArgs();
+
+  console.log('📥 Input:');
+  console.log(`  - OpenSpec: ${options.openspecPath}`);
+  console.log(`  - Task ID: ${options.taskId}`);
+  console.log(`  - Status: ${options.status}`);
+  if (options.notes) {
+    console.log(`  - Notes: ${options.notes}`);
+  }
+  console.log('');
+
+  // Step 1: Read tasks.md
+  console.log('📖 Step 1/3: Reading tasks.md...');
+  const content = readTasksFile(options.openspecPath);
+  console.log('✅ Read\n');
+
+  // Step 2: Update task status
+  console.log('🔧 Step 2/3: Updating task status...');
+  const updatedContent = updateTaskStatus(
+    content,
+    options.taskId,
+    options.status,
+    options.notes
+  );
+  console.log('✅ Updated\n');
+
+  // Step 3: Write back
+  console.log('💾 Step 3/3: Writing tasks.md...');
+  writeTasksFile(options.openspecPath, updatedContent);
+  console.log('✅ Written\n');
+
+  console.log('🎉 Done!');
+  console.log(`\n✅ Task ${options.taskId} marked as ${options.status}`);
+}
+
+main().catch(error => {
+  console.error('❌ Error:', error.message);
+  process.exit(1);
+});