skill-task-management

What this skill does

> **Host: Codex CLI** — This skill was designed for Claude Code and adapted for Codex.
> Cross-reference commands use installed skill names in Codex rather than `/octo:*` slash commands.
> Use the active Codex shell and subagent tools. Do not claim a provider, model, or host subagent is available until the current session exposes it.
> For host tool equivalents, see `skills/blocks/codex-host-adapter.md`.


# Task Management & Orchestration (v7.23.0+)

## Overview

Systematic task orchestration for multi-step work, progress checkpointing, and seamless task resumption across sessions.

**Core principle:** Track → Checkpoint → Resume → Complete.

**v7.23.0 Migration:** This skill now uses native Claude Code host subagent tools:
- `TaskCreate` - Create new tasks
- `TaskUpdate` - Update task status/details
- `TaskList` - View all tasks
- `TaskGet` - Get specific task details

**Benefits:**
- ✅ Tasks show in native Claude Code UI
- ✅ Better progress tracking and visualization
- ✅ Consistent with Claude Code conventions
- ✅ No dependency on external task plan tool tool


## When to Use

**Use this skill when user wants to:**
- Add items to the todo list
- Save current progress for later continuation
- Resume previously saved work
- Checkpoint progress in long-running tasks
- Proceed to next steps in a workflow
- Continue from where they left off

**Do NOT use for:**
- Creating git commits (use skill-finish-branch)
- Simple todo list queries ("what's on my list?")
- Task completion that involves pushing code


## Core Capabilities

### 1. Adding Tasks to Todo List

When user says "add to the todo's" or similar:

```markdown
**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)
```

**After getting details, use TaskCreate to add:**

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

**Then confirm to user:**

```
✅ Task created: [Task description]

View all tasks with TaskList or use /tasks command.
```


### 2. Saving Progress / Checkpointing

When user says "save progress" or "checkpoint this":

#### Step 1: Assess Current State

```bash
# Check git status
git status

# Check current branch
git branch --show-current

# Check uncommitted work
git diff --stat
```

#### Step 2: Create Progress Checkpoint

**Option A: Git-based checkpoint (if git repo)**

```bash
# 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]>"
```

**Option B: Task-based checkpoint (preferred for tracking)**

Create checkpoint task with detailed state:

```javascript
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"
})
```

#### Step 3: Update Existing Tasks

Mark completed tasks as done:

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

Mark current task as in_progress:

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

#### Step 4: Provide Resume Instructions

```markdown
✅ 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. Resuming Tasks

When user says "resume tasks" or "pick up where we left off":

#### Step 1: Load Task State

```javascript
// 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:'))
```

#### Step 2: Check Git State

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

# Check current branch
git branch --show-current

# Check git status
git status
```

#### Step 3: Present Current State

```markdown
📋 **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?
```

#### Step 4: Execute Based on Choice

- If "continue with next task" → Get first pending task, mark as in_progress, and begin work:
  ```javascript
  const nextTask = pending[0]
  TaskUpdate({ taskId: nextTask.id, status: 'in_progress' })
  // Begin working on nextTask
  ```

- If "modify the plan" → Use AskUserQuestion to understand changes, then update tasks

- If "see more details" → Show git diff, file changes, recent commits, task descriptions


### 4. Proceeding to Next Steps

When user says "proceed to next steps":

#### Step 1: Check Current Task Status

```javascript
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}`)
}
```

#### Step 2: Complete Current and Move Forward

```javascript
// 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}`)
}
```

#### Step 3: Execute Next Task

Begin working on the next task immediately after marking it as in_progress.


## Migration from task plan tool (v7.22.x → v7.23.0+)

### For Users with Existing .md Todo Files

If you have existing `.claude/todos.md` or similar files:

#### Option 1: Automatic Migration

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

This will:
1. Parse existing .md todo files
2. Convert to TaskCreate calls
3. Preserve task order and status
4. Archive old .md files to `.claude/archived-todos/`

#### Option 2: Manual Migration

For each todo item in your .md file:

```markdown
<!-- Old format in todos.md -->
- [ ] Implement user authentication
- [x] Set up database
- [ ] Create API endpoints
```

Convert to:

```javascript
// 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 fo