skill-task-management

宿主：Codex CLI — 此技能最初为 Claude Code 设计，后适配为 Codex。 交叉引用的命令在 Codex 中使用已安装的技能名称，而不是 /octo:* 斜杠命令。 使用当前 Codex 会话中的 shell 和子 Agent 工具。除非当前会话明确提供了某个提供方、模型或宿主子 Agent，否则不要声称其可用。 有关宿主工具的对应项，请参阅 skills/blocks/codex-host-adapter.md。

任务管理与编排（v7.23.0+）

概述

系统化地编排多步骤工作、记录进度检查点，并在不同会话间无缝恢复任务。

核心原则： 跟踪 → 记录检查点 → 恢复 → 完成。

v7.23.0 迁移： 此技能现使用 Claude Code 原生宿主子 Agent 工具：

• TaskCreate - 创建新任务
• TaskUpdate - 更新任务状态／详情
• TaskList - 查看所有任务
• TaskGet - 获取特定任务详情

优势：

• ✅ 任务会显示在 Claude Code 原生 UI 中
• ✅ 更好地跟踪进度并进行可视化
• ✅ 符合 Claude Code 惯例
• ✅ 不依赖外部任务计划工具

适用场景

当用户希望执行以下操作时，使用此技能：

• 向待办列表添加项目
• 保存当前进度以便稍后继续
• 恢复之前保存的工作
• 跟踪长时间运行任务的进度
• 继续工作流中的后续步骤
• 从上次中断处继续

以下情况不要使用：

• 创建 git 提交（使用 skill-finish-branch）
• 简单查询待办列表（“我的列表里有什么？”）
• 涉及推送代码的任务完成操作

核心功能

1. 向待办列表添加任务

当用户说“添加到待办事项”或类似内容时：

**What would you like to add to the todo list?**

I'll help you capture this task. Please provide:
- Task description (what needs to be done)
- Any dependencies or prerequisites
- Priority (if applicable)

获取详情后，使用 TaskCreate 添加：

TaskCreate({
  subject: "[Brief task description]",
  description: "[Detailed description including dependencies and context]",
  activeForm: "Working on [task description]"
})

然后向用户确认：

✅ Task created: [Task description]

View all tasks with TaskList or use /tasks command.

2. 保存进度／记录检查点

当用户说“保存进度”或“记录此检查点”时：

步骤 1：评估当前状态

# Check git status
git status

# Check current branch
git branch --show-current

# Check uncommitted work
git diff --stat

步骤 2：创建进度检查点

选项 A：基于 Git 的检查点（如果是 git 仓库）

# Create a work-in-progress commit
git add .
git commit -m "WIP: [description of current state]

Progress checkpoint - work in progress
Not ready for review or merge

Current state:
- [What's completed]
- [What's in progress]
- [What's next]

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>"

选项 B：基于任务的检查点（更适合跟踪）

创建检查点任务，并详细记录状态：

TaskCreate({
  subject: "Checkpoint: [Brief description]",
  description: `
📍 CHECKPOINT: ${new Date().toISOString()}

Completed:
✓ [Task 1]
✓ [Task 2]

In Progress:
⚙️ [Current task with details]

Next Steps:
- [ ] [Next task 1]
- [ ] [Next task 2]
- [ ] [Next task 3]

Context:
- Branch: ${branchName}
- Last commit: ${lastCommit}
- Files changed: ${filesChanged}
  `,
  activeForm: "Checkpoint saved"
})

步骤 3：更新现有任务

将已完成的任务标记为完成：

// For each completed task
TaskUpdate({
  taskId: "[task-id]",
  status: "completed"
})

将当前任务标记为进行中：

TaskUpdate({
  taskId: "[current-task-id]",
  status: "in_progress"
})

步骤 4：提供恢复说明

✅ Progress saved!

To resume this work:
1. Run: git checkout [branch-name]
2. View tasks: TaskList
3. Say: "resume tasks" or "pick up where we left off"

Current state:
- Branch: [branch-name]
- Tasks: [X completed, Y in progress, Z pending]
- Last checkpoint: [timestamp]

3. 恢复任务

当用户说“恢复任务”或“从上次中断处继续”时：

步骤 1：加载任务状态

// Get all tasks
const tasks = TaskList()

// Filter by status
const completed = tasks.filter(t => t.status === 'completed')
const inProgress = tasks.filter(t => t.status === 'in_progress')
const pending = tasks.filter(t => t.status === 'pending')

// Find checkpoint task (if exists)
const checkpoint = tasks.find(t => t.subject.startsWith('Checkpoint:'))

步骤 2：检查 Git 状态

# Check for WIP commits
git log --oneline -10 | grep WIP

# Check current branch
git branch --show-current

# Check git status
git status

步骤 3：展示当前状态

📋 **Resuming from last checkpoint**

**Branch:** [branch-name]
**Last checkpoint:** [timestamp from WIP commit or checkpoint task]

**Completed:** (${completed.length} tasks)
${completed.map(t => `✓ ${t.subject}`).join('\n')}

**In Progress:** (${inProgress.length} tasks)
${inProgress.map(t => `⚙️ ${t.subject}`).join('\n')}

**Next Steps:** (${pending.length} tasks)
${pending.map((t, i) => `${i + 1}. [ ] ${t.subject}`).join('\n')}

**Would you like me to:**
1. Continue with the next task?
2. Modify the plan?
3. See more details about current state?

步骤 4：根据选择执行

• 如果用户选择“继续下一个任务” → 获取第一个待处理任务，将其标记为进行中，然后开始工作：

  const nextTask = pending[0]
  TaskUpdate({ taskId: nextTask.id, status: 'in_progress' })
  // Begin working on nextTask
  

• 如果用户选择“修改计划” → 使用 AskUserQuestion 了解变更，然后更新任务

• 如果用户选择“查看更多详情” → 显示 git diff、文件变更、近期提交和任务描述

4. 继续后续步骤

当用户说“继续后续步骤”时：

步骤 1：检查当前任务状态

const tasks = TaskList()
const currentTask = tasks.find(t => t.status === 'in_progress')

if (currentTask) {
  console.log(`Current task: ${currentTask.subject}`)
  console.log(`Status: ${currentTask.status}`)
}

步骤 2：完成当前任务并继续

// Mark current task as complete
if (currentTask) {
  TaskUpdate({
    taskId: currentTask.id,
    status: 'completed'
  })
  console.log(`✓ ${currentTask.subject}`)
}

// Get next pending task
const nextTask = tasks.find(t => t.status === 'pending' && !t.blockedBy?.length)

if (nextTask) {
  // Mark as in progress
  TaskUpdate({
    taskId: nextTask.id,
    status: 'in_progress'
  })
  console.log(`\n⚙️ ${nextTask.subject}`)
  console.log(`\nProceeding with: ${nextTask.description}`)
}

步骤 3：执行下一个任务

将下一个任务标记为进行中后，立即开始处理。

从任务计划工具迁移（v7.22.x → v7.23.0+）

对于现有 .md 待办文件的用户

如果已有 .claude/todos.md 或类似文件：

选项 1：自动迁移

# Run migration script
"${HOME}/.claude-octopus/plugin/scripts/migrate-todos.sh"

这将：

1. 解析现有的 .md 待办文件
2. 转换为 TaskCreate 调用
3. 保留任务顺序和状态
4. 将旧的 .md 文件归档到 .claude/archived-todos/

选项 2：手动迁移

对于 .md 文件中的每个待办事项：

- [ ] Implement user authentication
- [x] Set up database
- [ ] Create API endpoints

转换为：

// New format using native tasks
TaskCreate({
  subject: "Implement user authentication",
  description: "Create auth system with JWT tokens",
  activeForm: "Implementing authentication"
})

TaskCreate({
  subject: "Set up database",
  description: "Configure PostgreSQL and run migrations",
  activeForm: "Setting up database"
})
// Mark as completed since it was [x]
TaskUpdate({ taskId: "...", status: "completed" })

TaskCreate({
  subject: "Create API endpoints",
  description: "Build REST API for user operations",
  activeForm: "Creating API endpoints"
})

向后兼容性

选择退出旧系统的用户：

创建 .claude/claude-octopus.local.md，内容如下：

use_native_tasks: false

# Claude Octopus Local Configuration

This project uses legacy task plan tool tool instead of native Task management.

当 use_native_tasks: false 时，技能将回退到任务计划工具的行为。

与其他技能集成

与 skill-finish-branch 集成

User: "save progress and prepare for PR"

1. Use skill-task-management to checkpoint (create tasks for current state)
2. Then use skill-finish-branch to prepare PR

与 flow-develop 集成

User: "add implementation of auth system to todos"

1. Use skill-task-management to add high-level task
2. Use flow-develop to break down and implement
3. Update tasks as work progresses

与 skill-debug 集成

User: "checkpoint this, I found a bug"

1. Use skill-task-management to save current progress (checkpoint task)
2. Use skill-debug to investigate the bug
3. Return to saved checkpoint after fix

最佳实践

1. 明确的任务主题和描述

好的任务：

TaskCreate({
  subject: "Implement token refresh with 15-minute expiration",
  description: `
Create token refresh endpoint that:
- Validates refresh token from secure HTTP-only cookie
- Issues new access token with 15min expiry
- Rotates refresh token for security
- Returns 401 if refresh token invalid/expired

Dependencies: OAuth provider setup must be complete
  `,
  activeForm: "Implementing token refresh logic"
})

不好的任务：

TaskCreate({
  subject: "Do auth stuff",
  description: "Fix things",
  activeForm: "Working"
})

2. 使用任务依赖关系

对于有前置条件的任务：

// First task
TaskCreate({
  subject: "Set up OAuth provider configuration",
  description: "Configure Auth0 application settings",
  activeForm: "Configuring OAuth provider"
})

// Dependent task
TaskCreate({
  subject: "Implement token refresh endpoint",
  description: "Create /auth/refresh endpoint",
  activeForm: "Implementing refresh endpoint",
  addBlockedBy: ["1"]  // Blocked by task #1
})

3. 在检查点保留上下文

创建检查点时，务必包含：

• 已完成的内容（避免重复工作）
• 正在进行的内容（便于快速恢复）
• 接下来要做的内容（提供清晰的后续路径）
• 做出决策的原因（保留推理过程）

检查点任务示例：

TaskCreate({
  subject: "Checkpoint: Auth implementation 70% complete",
  description: `
📍 CHECKPOINT: 2026-02-03T14:30:00Z

Completed:
✓ OAuth provider configuration (Auth0)
✓ Token exchange endpoint (/auth/login)
✓ User session middleware

In Progress:
⚙️ Token refresh logic (70% done)
  - Validation complete
  - Token rotation TODO
  - Cookie handling TODO

Next:
- [ ] Complete token rotation logic
- [ ] Add logout endpoint
- [ ] Add session expiration handling
- [ ] Write integration tests

Branch: feature/auth-system
Last commit: abc123f "Add session middleware"

Decisions Made:
- Using Auth0 (rationale: enterprise-grade, handles complexity)
- 15-minute access token expiry (security vs UX balance)
- HTTP-only cookies for refresh tokens (XSS protection)
  `,
  activeForm: "Checkpoint saved"
})

常见模式

模式 1：日终检查点

User: "save progress, I'm done for today"

Action:
1. Create WIP commit with current state
2. Create checkpoint task with completed/pending breakdown
3. Mark in-progress tasks with current status
4. Provide resume instructions for tomorrow

模式 2：上下文切换

User: "checkpoint this, need to work on something else"

Action:
1. Save current branch state (WIP commit)
2. Create checkpoint task with detailed context
3. Mark current task as pending (will resume later)
4. Ready for resume when user returns

模式 3：协作交接

User: "save progress for Claude to pick up"

Action:
1. Create comprehensive checkpoint task
2. Document all context and decisions
3. Mark in-progress tasks with current state
4. Ensure new session can load task state and resume seamlessly

危险信号——不要这样做

操作	错误原因
创建检查点但不记录上下文	下一次会话不知道之前在做什么
代码更改后跳过 WIP 提交	如果出了问题，工作可能会丢失
不检查 TaskList 就泛泛地说“继续下一项”	可能会跳过尚未完成的工作
任务主题或描述含糊不清	不清楚需要做什么
恢复任务时不展示 TaskList 状态	用户不知道当前进度
创建任务时不设置 activeForm	界面中不会显示进度

快速参考

用户意图	技能操作	使用的工具
“添加到待办事项”	收集详情，创建任务	TaskCreate
“保存进度”	创建检查点任务 + WIP 提交	TaskCreate + git
“恢复任务”	加载任务状态、显示状态并询问下一步	TaskList
“继续下一项”	完成当前任务，开始下一项	TaskUpdate
“为此创建检查点”	创建详细的检查点任务	TaskCreate

任务状态工作流

pending → in_progress → completed
                ↓
              deleted (if no longer needed)

最佳实践：

• 以 pending 状态创建任务
• 开始工作时标记为 in_progress
• 只有完全完成后才标记为 completed
• 对已取消或已过时的任务使用 deleted

总而言之

Task management → Clear state + Easy resume + Native UI
Otherwise → Lost context + Duplicate work + No visibility

跟踪所有事项。频繁创建检查点。无缝恢复工作。使用原生工具。

示例：完整工作流

// User: "add implementing auth to my todos"

// Step 1: Create main task
TaskCreate({
  subject: "Implement user authentication system",
  description: `
Build complete auth system with:
- OAuth 2.0 (Auth0 provider)
- JWT token management
- Refresh token rotation
- Session middleware
- Logout functionality
  `,
  activeForm: "Planning authentication implementation"
})

// User works on it...

// User: "save progress for tomorrow"

// Step 2: Create checkpoint
TaskCreate({
  subject: "Checkpoint: Auth implementation in progress",
  description: `
📍 Checkpoint: 2026-02-03T18:30:00Z

Completed:
✓ OAuth configuration
✓ Login endpoint

In Progress:
⚙️ Token refresh (50%)

Next:
- [ ] Complete refresh logic
- [ ] Add logout
- [ ] Write tests

Branch: feature/auth
Commit: abc123f
  `,
  activeForm: "Checkpoint saved"
})

// Step 3: Update main task status
TaskUpdate({
  taskId: "1",
  status: "in_progress"
})

// User: "resume tasks" (next day)

// Step 4: Load and present state
const tasks = TaskList()
// Present: "You have 1 in_progress task, last checkpoint 2026-02-03T18:30:00Z"
// Show details from checkpoint task

// User: "continue"

// Step 5: Resume work
const currentTask = tasks.find(t => t.status === 'in_progress')
// Begin working on token refresh where they left off