@waoooo/claude-skills 1.0.0

package/skills/progress-update/SKILL.md

@@ -0,0 +1,394 @@
+# Skill: progress-update
+
+## 功能
+
+更新 progress.json，跟踪任务执行进度，减少会话长度。
+
+## 何时调用
+
+- 步骤 18：任务状态更新后
+- 需要记录进度时
+- 生成进度报告时
+
+## 输入
+
+- `taskId` - 任务 ID（例如：TASK-001）
+- `jobId` - Job ID（例如：2026-02-10-1520-pricing-system）
+- `status` - 新状态（pending / in-progress / completed / failed）
+- `notes` - 备注信息（可选）
+
+## 输出
+
+- 更新后的 progress.json
+- 进度统计
+
+## 执行步骤
+
+### 1. 读取 progress.json
+
+```typescript
+const progressPath = `exports/jobs/${jobId}/specs/progress.json`
+const progress = JSON.parse(readFile(progressPath))
+```
+
+### 2. 更新任务状态
+
+```typescript
+// 查找任务
+const taskIndex = progress.tasks?.findIndex(t => t.taskId === taskId)
+
+if (taskIndex === -1) {
+  // 任务不存在，添加新任务
+  if (!progress.tasks) {
+    progress.tasks = []
+  }
+  
+  progress.tasks.push({
+    taskId: taskId,
+    status: status,
+    startedAt: status === 'in-progress' ? new Date().toISOString() : null,
+    completedAt: status === 'completed' ? new Date().toISOString() : null,
+    failedAt: status === 'failed' ? new Date().toISOString() : null,
+    notes: notes || null
+  })
+} else {
+  // 更新现有任务
+  const task = progress.tasks[taskIndex]
+  const oldStatus = task.status
+  
+  task.status = status
+  
+  // 更新时间戳
+  if (status === 'in-progress' && !task.startedAt) {
+    task.startedAt = new Date().toISOString()
+  }
+  
+  if (status === 'completed' && !task.completedAt) {
+    task.completedAt = new Date().toISOString()
+    
+    // 计算实际耗时
+    if (task.startedAt) {
+      task.duration = calculateDuration(task.startedAt, task.completedAt)
+    }
+  }
+  
+  if (status === 'failed' && !task.failedAt) {
+    task.failedAt = new Date().toISOString()
+  }
+  
+  // 添加备注
+  if (notes) {
+    task.notes = notes
+  }
+}
+```
+
+### 3. 更新统计信息
+
+```typescript
+// 重新计算统计
+const allTasks = progress.tasks || []
+
+progress.progress = {
+  totalTasks: allTasks.length,
+  completed: allTasks.filter(t => t.status === 'completed').length,
+  inProgress: allTasks.filter(t => t.status === 'in-progress').length,
+  pending: allTasks.filter(t => t.status === 'pending').length,
+  failed: allTasks.filter(t => t.status === 'failed').length,
+  percentage: Math.round(
+    (allTasks.filter(t => t.status === 'completed').length / allTasks.length) * 100
+  )
+}
+
+// 更新整体状态
+if (progress.progress.failed > 0) {
+  progress.status = 'failed'
+} else if (progress.progress.inProgress > 0) {
+  progress.status = 'in-progress'
+} else if (progress.progress.completed === progress.progress.totalTasks) {
+  progress.status = 'completed'
+} else {
+  progress.status = 'pending'
+}
+
+// 更新时间戳
+progress.updatedAt = new Date().toISOString()
+```
+
+### 4. 添加时间线事件
+
+```typescript
+if (!progress.timeline) {
+  progress.timeline = []
+}
+
+progress.timeline.push({
+  timestamp: new Date().toISOString(),
+  event: `task-${status}`,
+  taskId: taskId,
+  description: `Task ${taskId} ${status}`,
+  notes: notes || null
+})
+
+// 限制时间线长度（保留最近 100 条）
+if (progress.timeline.length > 100) {
+  progress.timeline = progress.timeline.slice(-100)
+}
+```
+
+### 5. 更新当前任务和下一个任务
+
+```typescript
+// 更新当前任务
+if (status === 'in-progress') {
+  progress.currentTask = taskId
+} else if (status === 'completed' || status === 'failed') {
+  progress.currentTask = null
+}
+
+// 查找下一个可执行任务
+const tasks = JSON.parse(readFile(`exports/jobs/${jobId}/specs/tasks.json`))
+const nextTask = tasks.tasks.find(t => 
+  t.status === 'pending' && 
+  (!t.blockedBy || t.blockedBy.length === 0 || 
+   t.blockedBy.every(id => 
+     allTasks.find(pt => pt.taskId === id && pt.status === 'completed')
+   ))
+)
+
+progress.nextTask = nextTask ? nextTask.taskId : null
+```
+
+### 6. 写入文件
+
+```typescript
+writeFile(progressPath, JSON.stringify(progress, null, 2))
+```
+
+## progress.json 结构
+
+```json
+{
+  "version": "1.0.0",
+  "jobId": "2026-02-10-1520-pricing-system",
+  "updatedAt": "2026-02-11T10:30:00Z",
+  "status": "in-progress",
+  
+  "progress": {
+    "totalTasks": 12,
+    "completed": 5,
+    "inProgress": 1,
+    "pending": 6,
+    "failed": 0,
+    "percentage": 42
+  },
+  
+  "tasks": [
+    {
+      "taskId": "TASK-001",
+      "status": "completed",
+      "startedAt": "2026-02-11T03:00:00Z",
+      "completedAt": "2026-02-11T10:30:00Z",
+      "duration": "7h 30m",
+      "notes": null
+    },
+    {
+      "taskId": "TASK-002",
+      "status": "in-progress",
+      "startedAt": "2026-02-11T10:35:00Z",
+      "completedAt": null,
+      "duration": null,
+      "notes": "Working on invoice calculation"
+    }
+  ],
+  
+  "timeline": [
+    {
+      "timestamp": "2026-02-11T03:00:00Z",
+      "event": "task-in-progress",
+      "taskId": "TASK-001",
+      "description": "Task TASK-001 in-progress"
+    },
+    {
+      "timestamp": "2026-02-11T10:30:00Z",
+      "event": "task-completed",
+      "taskId": "TASK-001",
+      "description": "Task TASK-001 completed"
+    }
+  ],
+  
+  "currentTask": "TASK-002",
+  "nextTask": "TASK-003",
+  "blockers": []
+}
+```
+
+## 使用示例
+
+### 示例 1：标记任务开始
+
+```
+Agent 调用 progress-update:
+  输入:
+  - taskId: TASK-001
+  - jobId: 2026-02-10-1520-pricing-system
+  - status: in-progress
+
+执行:
+  🔧 步骤 1: 读取 progress.json
+  ⏳ 当前进度: 0/12 (0%)
+
+  🔧 步骤 2: 更新任务状态
+  📝 TASK-001: pending → in-progress
+  📝 开始时间: 2026-02-11 03:00:00
+
+  🔧 步骤 3: 更新统计
+  📊 进度: 0/12 → 0/12 (in-progress: 0 → 1)
+
+  🔧 步骤 4: 添加时间线
+  ✅ 事件: task-in-progress
+
+  🔧 步骤 5: 更新当前任务
+  📝 当前任务: null → TASK-001
+
+  🔧 步骤 6: 写入文件
+  ✅ 已保存
+
+显示结果:
+  ✅ 进度已更新
+
+  📊 当前进度:
+  - 总任务: 12
+  - 已完成: 0 (0%)
+  - 进行中: 1 (TASK-001)
+  - 待开始: 11
+
+  💡 下一步:
+  继续执行 TASK-001
+```
+
+### 示例 2：标记任务完成
+
+```
+Agent 调用 progress-update:
+  输入:
+  - taskId: TASK-001
+  - jobId: 2026-02-10-1520-pricing-system
+  - status: completed
+  - notes: "All subtasks completed, tests passed"
+
+执行:
+  🔧 步骤 1-6: 更新进度
+
+显示结果:
+  ✅ 进度已更新
+
+  📊 当前进度:
+  - 总任务: 12
+  - 已完成: 1 (8%)
+  - 进行中: 0
+  - 待开始: 11
+
+  ✅ TASK-001 已完成:
+  - 开始: 2026-02-11 03:00:00
+  - 完成: 2026-02-11 10:30:00
+  - 耗时: 7h 30m
+  - 备注: All subtasks completed, tests passed
+
+  📝 下一个任务: TASK-002
+
+  💡 下一步:
+  可以开始执行 TASK-002
+```
+
+### 示例 3：批量更新
+
+```
+Agent 调用 progress-update (批量):
+  输入:
+  - updates: [
+      { taskId: "TASK-001", status: "completed" },
+      { taskId: "TASK-002", status: "completed" },
+      { taskId: "TASK-003", status: "in-progress" }
+    ]
+  - jobId: 2026-02-10-1520-pricing-system
+
+执行:
+  🔧 批量更新 3 个任务
+
+显示结果:
+  ✅ 批量更新完成
+
+  📊 当前进度:
+  - 总任务: 12
+  - 已完成: 2 (17%)
+  - 进行中: 1
+  - 待开始: 9
+
+  💡 进度提升: 0% → 17%
+```
+
+## 错误处理
+
+### 错误 1：progress.json 不存在
+
+```
+❌ 错误: progress.json 不存在
+🔍 原因: 文件未找到
+
+💡 建议:
+1. 检查 Job 路径
+2. 重新运行 spec-generate
+```
+
+### 错误 2：JSON 格式错误
+
+```
+❌ 错误: JSON 解析失败
+🔍 原因: progress.json 格式不正确
+
+💡 建议:
+1. 检查 JSON 格式
+2. 恢复备份文件
+3. 或重新生成
+```
+
+## 注意事项
+
+1. **减少会话长度** - 这是创建此 Skill 的主要原因
+2. **原子操作** - 读取-修改-写入作为原子操作
+3. **时间线限制** - 保留最近 100 条事件
+4. **自动计算** - 自动计算进度百分比和耗时
+5. **下一个任务** - 自动查找下一个可执行任务
+
+## 性能优化
+
+### 为什么需要独立 Skill？
+
+**问题**：
+```
+❌ 没有独立 Skill：
+主 Agent → 读取 progress.json (500 行)
+       → 修改一个字段
+       → 写入 progress.json (500 行)
+       → 上下文消耗：1000+ tokens
+```
+
+**解决**：
+```
+✅ 有独立 Skill：
+主 Agent → skill(name="progress-update", params={taskId, status})
+       → Skill 内部处理（不占用主会话上下文）
+       → 返回简单结果："✅ 已更新"
+       → 上下文消耗：50 tokens
+```
+
+**效果**：
+- 节省 95% 的上下文消耗
+- 提高执行效率
+- 减少会话长度
+
+## 相关文件
+
+- `exports/jobs/<job-id>/specs/progress.json` - 进度跟踪
+- `exports/jobs/<job-id>/specs/tasks.json` - 任务列表

package/skills/progress-update/scripts/update-progress.ts

@@ -0,0 +1,221 @@
+#!/usr/bin/env node
+/**
+ * Update Progress Tracking File
+ * 
+ * This script updates progress.json file:
+ * - Update task completion status
+ * - Recalculate progress percentage
+ * - Update timestamps
+ * 
+ * Usage:
+ *   npx tsx update-progress.ts \
+ *     --job-id <job-id> \
+ *     --task <task-id> \
+ *     --status <completed|in_progress|failed>
+ * 
+ * Example:
+ *   npx tsx update-progress.ts \
+ *     --job-id 2026-02-10-1520-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 Task {
+  id: string;
+  title: string;
+  status: TaskStatus;
+  startedAt?: string;
+  completedAt?: string;
+  estimatedHours?: number;
+  actualHours?: number;
+}
+
+interface Progress {
+  version: string;
+  jobId: string;
+  updatedAt: string;
+  summary: {
+    total: number;
+    completed: number;
+    inProgress: number;
+    failed: number;
+    pending: number;
+    percentage: number;
+  };
+  tasks: Task[];
+}
+
+interface UpdateOptions {
+  jobId: string;
+  taskId: string;
+  status: TaskStatus;
+  actualHours?: number;
+}
+
+// ============================================================================
+// 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['job-id'] || !result.task || !result.status) {
+    console.error('❌ Missing required arguments');
+    console.error('Usage: update-progress.ts --job-id <id> --task <id> --status <status>');
+    process.exit(1);
+  }
+
+  return {
+    jobId: result['job-id'],
+    taskId: result.task,
+    status: result.status as TaskStatus,
+    actualHours: result['actual-hours'] ? parseFloat(result['actual-hours']) : undefined,
+  };
+}
+
+// ============================================================================
+// Progress File Operations
+// ============================================================================
+
+function getProgressPath(jobId: string): string {
+  return path.resolve(__dirname, `../../../../exports/jobs/${jobId}/specs/progress.json`);
+}
+
+function readProgress(jobId: string): Progress {
+  const progressPath = getProgressPath(jobId);
+  
+  if (!fs.existsSync(progressPath)) {
+    throw new Error(`progress.json not found: ${progressPath}`);
+  }
+
+  return JSON.parse(fs.readFileSync(progressPath, 'utf-8'));
+}
+
+function writeProgress(jobId: string, progress: Progress): void {
+  const progressPath = getProgressPath(jobId);
+  fs.writeFileSync(progressPath, JSON.stringify(progress, null, 2), 'utf-8');
+}
+
+function updateTaskInProgress(
+  progress: Progress,
+  taskId: string,
+  status: TaskStatus,
+  actualHours?: number
+): Progress {
+  const task = progress.tasks.find(t => t.id === taskId);
+  
+  if (!task) {
+    throw new Error(`Task ${taskId} not found in progress.json`);
+  }
+
+  const now = new Date().toISOString();
+
+  // Update task status
+  const oldStatus = task.status;
+  task.status = status;
+
+  // Update timestamps
+  if (status === 'in_progress' && !task.startedAt) {
+    task.startedAt = now;
+  }
+
+  if (status === 'completed' && !task.completedAt) {
+    task.completedAt = now;
+    if (actualHours !== undefined) {
+      task.actualHours = actualHours;
+    }
+  }
+
+  // Recalculate summary
+  progress.summary = {
+    total: progress.tasks.length,
+    completed: progress.tasks.filter(t => t.status === 'completed').length,
+    inProgress: progress.tasks.filter(t => t.status === 'in_progress').length,
+    failed: progress.tasks.filter(t => t.status === 'failed').length,
+    pending: progress.tasks.filter(t => t.status === 'pending').length,
+    percentage: 0,
+  };
+
+  progress.summary.percentage = Math.round(
+    (progress.summary.completed / progress.summary.total) * 100
+  );
+
+  // Update timestamp
+  progress.updatedAt = now;
+
+  return progress;
+}
+
+// ============================================================================
+// Main
+// ============================================================================
+
+async function main() {
+  console.log('📊 Updating progress tracking...\n');
+
+  const options = parseArgs();
+
+  console.log('📥 Input:');
+  console.log(`  - Job ID: ${options.jobId}`);
+  console.log(`  - Task ID: ${options.taskId}`);
+  console.log(`  - Status: ${options.status}`);
+  if (options.actualHours) {
+    console.log(`  - Actual Hours: ${options.actualHours}h`);
+  }
+  console.log('');
+
+  // Step 1: Read progress.json
+  console.log('📖 Step 1/3: Reading progress.json...');
+  const progress = readProgress(options.jobId);
+  console.log(`✅ Read (${progress.tasks.length} tasks)\n`);
+
+  // Step 2: Update task
+  console.log('🔧 Step 2/3: Updating task...');
+  const updatedProgress = updateTaskInProgress(
+    progress,
+    options.taskId,
+    options.status,
+    options.actualHours
+  );
+  console.log('✅ Updated\n');
+
+  // Step 3: Write back
+  console.log('💾 Step 3/3: Writing progress.json...');
+  writeProgress(options.jobId, updatedProgress);
+  console.log('✅ Written\n');
+
+  console.log('📊 Progress Summary:');
+  console.log(`  - Total: ${updatedProgress.summary.total}`);
+  console.log(`  - Completed: ${updatedProgress.summary.completed}`);
+  console.log(`  - In Progress: ${updatedProgress.summary.inProgress}`);
+  console.log(`  - Failed: ${updatedProgress.summary.failed}`);
+  console.log(`  - Pending: ${updatedProgress.summary.pending}`);
+  console.log(`  - Percentage: ${updatedProgress.summary.percentage}%\n`);
+
+  console.log('🎉 Done!');
+}
+
+main().catch(error => {
+  console.error('❌ Error:', error.message);
+  process.exit(1);
+});