---
name: task-management
description: Complete guide for creating, claiming, updating, and closing tasks in the SQLite task database
license: MIT
compatibility: opencode
metadata:
  audience: all-agents
  workflow: task-lifecycle
---

## What I Do

I provide comprehensive instructions for managing tasks in the {{ project_name }} task database. This skill covers the complete task lifecycle:

- **Creating tasks** - Add new work items to the database
- **Finding tasks** - Query for available work
- **Claiming tasks** - Take ownership of a task
- **Updating tasks** - Track progress and time
- **Closing tasks** - Mark tasks complete, paused, or blocked

## Task Management Systems

**Unified PM System (Use This)**

The `pm` script provides unified management of tasks, agent sessions, and daemon names:

```bash
cd .opencode/scripts

# Task commands
./pm task create TASK_ID --title "..." --priority HIGH --role Builder --objective "..."
./pm task list --role Builder --active-only
./pm task claim TASK_ID --agent-name "YourName" --agent-id YOUR_ID
./pm task update TASK_ID --notes "..." --actual-hours X.X
./pm task close TASK_ID --status COMPLETE --notes "..."

# See also: agent and name commands
./pm agent start <name> --role <Role> --session-file "..." --task-summary "..."
./pm name suggest <Role>
```

**Documentation:**
- Quick start: `.opencode/scripts/README.md`
- Complete reference: `.opencode/data/README.md`
- Database: `.opencode/data/project.db`

**Legacy System (Preserved for Reference)**

The original task system has been migrated to the new PM system:

```bash
cd .opencode/scripts
./pm task <command> [options]
```

**Database:** `.opencode/tasks/tasks.db` (SQLite, data migrated to project.db)  
**Artifacts:** `.opencode/tasks/artifacts/*.md` (Markdown files)

> **Note:** All 72 tasks have been migrated to the new PM system. Use `pm` commands for all task operations going forward. The instructions below have been updated to use the new PM system.

---

## Creating Tasks

**When to create tasks:**
- Manager role adding new work items
- Inspector creating follow-up tasks from reviews
- Architect creating implementation tasks from design

**Command:**
```bash
cd .opencode/scripts
./pm task create TASK_ID \
  --title "Brief task title" \
  --priority {CRITICAL|HIGH|MEDIUM|LOW} \
  --role {Manager|Architect|Builder|Tester|Documentarian|Designer|Inspector|Operator} \
  --objective "What this task accomplishes" \
  --category "Category name" \
  [--depends-on OTHER_TASK_ID] \
  [--description "Detailed description"]
```

### Task ID Format

Task IDs follow priority-based convention:
- `C###` - CRITICAL priority (security, blocking, P0 bugs)
- `H###` - HIGH priority (important features, P1 bugs)
- `M###` - MEDIUM priority (nice-to-have features)
- `L###` - LOW priority (polish, documentation)

Numbers increment sequentially within each priority level.

**Examples:**
- `C001`, `C002`, `C003` - Critical tasks
- `H037`, `H038`, `H039` - High priority tasks
- `M019`, `M020` - Medium priority
- `L012` - Low priority

### Find Next Available ID

```bash
# Get highest ID for a priority level
cd .opencode/scripts
./pm task list --status TODO,UNDERWAY,BLOCKED,PAUSED,COMPLETE,ABORTED | grep "^H" | tail -1

# If last HIGH is H036, next is H037
```

### Priority Guidelines

**CRITICAL** - Immediate action required:
- Security vulnerabilities
- Data corruption risks
- Blocking all other work
- Production outages

**HIGH** - Important, do soon:
- Key features for current milestone
- P1 bugs affecting users
- Technical debt causing problems
- Required for next phase

**MEDIUM** - Nice to have:
- Enhancement requests
- Minor features
- Code quality improvements
- Non-urgent bugs

**LOW** - Do when time permits:
- Polish and refinement
- Documentation updates
- Minor improvements
- Nice-to-have features

### Role Assignment

Assign to the role that will do most of the work:

- **Manager** - Planning, coordination, prioritization
- **Architect** - System design, ADRs, technical direction
- **Builder** - Implementation, coding, integration
- **Tester** - Test writing, validation, QA
- **Documentarian** - Documentation, guides, examples
- **Designer** - UI/UX, visual design
- **Inspector** - Security review, code review, audits
- **Operator** - Deployment, infrastructure, monitoring

### Category Examples

Common categories:
- `Architecture` - System design work
- `Testing` - Test creation and QA
- `Documentation` - Docs and guides
- `Security` - Security reviews and fixes
- `Performance` - Optimization work
- `Bug Fix` - Fixing defects
- `Feature` - New functionality
- `Refactoring` - Code improvement
- `Infrastructure` - Deployment and tooling

### Dependencies

Use `--depends-on` when a task cannot start until another completes:

```bash
# H038 depends on H037
./pm task create H038 \
  --title "Configure Gateway" \
  --priority HIGH \
  --role Operator \
  --objective "Deploy gateway to staging" \
  --depends-on H037
```

**When to use dependencies:**
- Implementation depends on design approval
- Integration depends on component completion
- Deployment depends on code changes
- Testing depends on feature implementation

### Example: Creating a Task

```bash
cd .opencode/scripts

# Check for next available ID
./pm task list | grep "^H" | tail -1
# Output: H036 | Some task title

# Create H037
./pm task create H037 \
  --title "Implement Rate Limiting Middleware" \
  --priority HIGH \
  --role Builder \
  --objective "Add rate limiting to protect API endpoints from abuse" \
  --category "Security" \
  --depends-on H035 \
  --description "Implement token bucket rate limiting with configurable limits per endpoint"
```

**What happens:**
1. ✅ Database entry created in `tasks.db`
2. ✅ Markdown file created at `artifacts/H037.md` with template
3. ✅ Status set to `TODO`
4. ✅ Dependency link created to H035

### Validation

The CLI validates:
- ✅ Task ID format (C###, H###, M###, L###)
- ✅ Priority matches ID prefix
- ✅ Status is valid value
- ✅ Role is valid value
- ✅ Dependencies exist in database

### After Creating

Verify task was created:
```bash
./pm task show H037
```

---

## Finding Tasks

### List Available Tasks

**By status:**
```bash
./pm task list --status TODO
./pm task list --status UNDERWAY
./pm task list --status TODO,UNDERWAY
```

**By role:**
```bash
./pm task list --role Builder --status TODO
./pm task list --role Manager --status TODO
```

**By priority:**
```bash
./pm task list --priority CRITICAL,HIGH --status TODO
./pm task list --priority HIGH
```

**Active tasks only:**
```bash
./pm task list --active-only
# Shows TODO and UNDERWAY tasks
```

**By agent:**
```bash
./pm task list --agent "Goibniu"
./pm task list --agent "Ishtar" --status UNDERWAY
```

### View Task Details

```bash
./pm task show H037
```

Shows:
- Full metadata (status, priority, role, category)
- Agent assignment (if claimed)
- Timestamps (created, claimed, closed)
- Time tracking
- Objective and description
- Dependencies
- File path to markdown artifact

### Generate Reports

```bash
# Markdown report
./pm task report --format markdown

# Table format
./pm task report --format table

# JSON for scripts
./pm task report --format json

# Filter by role
./pm task report --role Builder --format markdown
```

---

## Claiming Tasks

**Who claims tasks:**
- Any agent taking ownership of work
- Typically done at start of session

**Command:**
```bash
cd .opencode/scripts
./pm task claim TASK_ID --agent-name "YourName"
```

### What Happens When You Claim

1. ✅ Status changes: `TODO` → `UNDERWAY`
2. ✅ `agent_name` set to your name
3. ✅ `claimed_at` timestamp recorded
4. ✅ Markdown file header updated

### Agent Name

Use your daemon name from the session:
- ✅ "Goibniu", "Ishtar", "Thoth-iii"
- ❌ Not "Builder" or "Manager" (that's your role, not name)

### Example: Claiming a Task

```bash
cd .opencode/scripts

# Find available tasks for your role
./pm task list --role Builder --status TODO

# Output shows H037 is available
# H037 | Implement Rate Limiting Middleware | TODO | HIGH | Builder

# Claim it
./pm task claim H037 --agent-name "Goibniu"

# Verify
./pm task show H037
# Status: UNDERWAY
# Agent: Goibniu
# Claimed: 2026-01-29T22:00:00+00:00
```

### Concurrency Protection

The database prevents race conditions:
- ✅ Only one agent can claim a specific task
- ✅ If two agents try simultaneously, only one succeeds
- ✅ WAL mode allows concurrent reads

### Already Claimed

If task is already claimed:
```bash
./pm task claim H037 --agent-name "Ishtar"
# Error: Task H037 is already claimed by Goibniu
```

Check who claimed it:
```bash
./pm task show H037
```

### Claiming Multiple Tasks

Claim one at a time:
```bash
./pm task claim H037 --agent-name "Goibniu"
./pm task claim H038 --agent-name "Goibniu"
```

**Best practice:** Focus on one task at a time. Only claim multiple if they're small and related.

---

## Updating Tasks

**When to update:**
- Made progress on the task
- Tracked time spent
- Encountered issues
- Changed approach
- At end of work session

**Command:**
```bash
cd .opencode/scripts
./pm task update TASK_ID \
  [--status STATUS] \
  [--notes "Progress notes"] \
  [--actual-hours X.X] \
  [--category "New category"]
```

### Progress Notes

Use `--notes` to document progress:

```bash
./pm task update H037 --notes "Implemented basic rate limiter, writing tests"

./pm task update H037 --notes "All tests passing, need to add Redis backend"

./pm task update H037 --notes "Blocked on Redis configuration decision"
```

**Notes are appended** to the task's notes field, not replaced.

### Time Tracking

Track actual hours spent:

```bash
./pm task update H037 --actual-hours 2.5

# Add more time later
./pm task update H037 --actual-hours 4.0  # Total is now 4.0, not 2.5+4.0
```

**Note:** `--actual-hours` sets the total, not incremental.

### Changing Status

Usually status changes via claim/close, but you can update manually:

```bash
# Mark as blocked (but keep it UNDERWAY)
./pm task update H037 --status BLOCKED --notes "Waiting for design decision"

# Return to regular progress
./pm task update H037 --status UNDERWAY --notes "Design decision made, resuming"
```

### Example: Updating Progress

```bash
cd .opencode/scripts

# After 2 hours of work
./pm task update H037 \
  --notes "Implemented token bucket algorithm, added configuration" \
  --actual-hours 2.0

# After 2 more hours
./pm task update H037 \
  --notes "Added tests, all passing" \
  --actual-hours 4.0

# Check progress
./pm task show H037
```

### Update Frequency

**Good practice:**
- Update at least once per work session
- Update when switching tasks
- Update before closing task
- Update when encountering blockers

**Don't overdo it:**
- Not every 15 minutes
- Not for trivial progress

---

## Closing Tasks

**When to close:**
- Task is complete
- Pausing work for later
- Blocked and can't proceed
- Task is cancelled/obsolete

**Command:**
```bash
cd .opencode/scripts
./pm task close TASK_ID \
  --status {COMPLETE|PAUSED|BLOCKED|ABORTED} \
  --notes "Final summary"
```

### Status Options

**COMPLETE** - Task finished successfully:
- All objectives met
- Tests passing
- Code reviewed and merged
- Documentation updated

**PAUSED** - Temporarily stopped:
- Will resume later
- Low priority, paused for higher priority work
- Waiting for non-blocking dependency

**BLOCKED** - Can't proceed:
- Waiting for external dependency
- Needs decision from stakeholder
- Technical blocker discovered
- Waiting for another task to complete

**ABORTED** - Cancelled:
- Requirements changed
- Task no longer needed
- Duplicate of another task
- Approach was wrong

### Closing Timestamp

When you close a task:
- ✅ `closed_at` timestamp recorded
- ✅ `status` updated
- ✅ Final notes added
- ✅ Markdown file header updated

### Example: Closing Complete Task

```bash
cd .opencode/scripts

./pm task close H037 \
  --status COMPLETE \
  --notes "Rate limiting implemented and tested. All tests passing. Documentation updated."

# Verify
./pm task show H037
# Status: COMPLETE
# Closed: 2026-01-29T23:30:00+00:00
```

### Example: Closing Blocked Task

```bash
./pm task close H038 \
  --status BLOCKED \
  --notes "Blocked by H037. Can't deploy gateway until rate limiting is complete."
```

### Example: Pausing Task

```bash
./pm task close M019 \
  --status PAUSED \
  --notes "Pausing to work on critical security issue C003. Will resume after."
```

### Example: Aborting Task

```bash
./pm task close L012 \
  --status ABORTED \
  --notes "Task obsolete after architecture change in H029. No longer needed."
```

### Resuming Paused/Blocked Tasks

To resume a paused or blocked task:

1. **Claim it again** (if not already yours):
   ```bash
   ./pm task claim H038 --agent-name "YourName"
   ```

2. **Update status** back to UNDERWAY:
   ```bash
   ./pm task update H038 --status UNDERWAY --notes "Blocker resolved, resuming work"
   ```

---

## Task Lifecycle Summary

```
TODO (created)
  ↓
  claim → UNDERWAY (working)
  ↓                    ↓
  update progress      update → BLOCKED (temp)
  ↓                    ↓
  close → COMPLETE     update → UNDERWAY (resume)
          PAUSED               ↓
          BLOCKED              close → COMPLETE
          ABORTED
```

---

## Common Workflows

### Workflow 1: Complete a Task End-to-End

```bash
cd .opencode/scripts

# 1. Find work
./pm task list --role Builder --status TODO

# 2. Claim task
./pm task claim H037 --agent-name "Goibniu"

# 3. Work on it (update periodically)
./pm task update H037 --notes "Made progress on X" --actual-hours 2.0

# 4. Close when done
./pm task close H037 --status COMPLETE --notes "All tests passing, code reviewed"
```

### Workflow 2: Pause for Higher Priority

```bash
# Working on M019
./pm task update M019 --notes "50% complete"

# Critical issue appears
./pm task close M019 --status PAUSED --notes "Pausing for C003"

# Work on C003
./pm task claim C003 --agent-name "Goibniu"
./pm task close C003 --status COMPLETE --notes "Security issue fixed"

# Resume M019
./pm task update M019 --status UNDERWAY --notes "Resuming after C003"
```

### Workflow 3: Hit a Blocker

```bash
# Working on H038
./pm task update H038 --notes "Need H037 to be complete first"

# Mark as blocked
./pm task close H038 --status BLOCKED --notes "Blocked by H037"

# Work on something else

# When H037 is complete
./pm task update H038 --status UNDERWAY --notes "H037 complete, resuming"
```

### Workflow 4: Create Dependent Tasks

```bash
# Create parent task
./pm task create H037 --title "Design Gateway" --priority HIGH --role Architect --objective "Design gateway architecture"

# Create dependent tasks
./pm task create H038 --title "Implement Gateway" --priority HIGH --role Builder --objective "Implement gateway" --depends-on H037

./pm task create H039 --title "Test Gateway" --priority HIGH --role Tester --objective "Test gateway" --depends-on H038
```

---

## Tips and Best Practices

### Creating Tasks

- ✅ Use clear, action-oriented titles
- ✅ Write specific objectives (not "fix stuff")
- ✅ Assign appropriate priority
- ✅ Set dependencies when they exist
- ✅ Check for next available ID in priority range
- ❌ Don't create tasks for trivial work (<1 hour)
- ❌ Don't create duplicate tasks

### Claiming Tasks

- ✅ Claim one task at a time (stay focused)
- ✅ Check dependencies before claiming
- ✅ Use your daemon name, not role name
- ❌ Don't claim tasks you can't start immediately
- ❌ Don't claim tasks outside your role (usually)

### Updating Tasks

- ✅ Update at least once per session
- ✅ Track time accurately
- ✅ Document blockers immediately
- ✅ Note decisions made
- ❌ Don't skip updates for days
- ❌ Don't write novels (keep notes concise)

### Closing Tasks

- ✅ Use correct status (COMPLETE vs PAUSED vs BLOCKED)
- ✅ Write clear closing notes
- ✅ Close tasks before ending session
- ✅ Update actual hours before closing
- ❌ Don't leave tasks UNDERWAY forever
- ❌ Don't mark incomplete work as COMPLETE

---

## Troubleshooting

### "Task not found"
- Check task ID spelling and case
- Verify task exists: `./pm task list | grep TASK_ID`

### "Task already claimed"
- Someone else is working on it
- Check: `./pm task show TASK_ID`
- Choose a different task or coordinate

### "Database is locked"
- Another process is writing (rare with WAL mode)
- Wait a moment and retry
- Check for stuck processes: `ps aux | grep tasks.py`

### "CHECK constraint failed"
- You used invalid status/priority/role value
- See valid values in this skill
- Check your command syntax

### "Dependency not found"
- Task ID in `--depends-on` doesn't exist
- Check task IDs: `./pm task list`
- Fix the dependency task ID

### Can't find tasks.py
- Ensure you're in `.opencode/tasks/` directory
- Check file exists: `ls tasks.py`
- Make it executable: `chmod +x tasks.py`

---

## Valid Values Reference

### Status Values
- `TODO` - Not started
- `UNDERWAY` - In progress
- `BLOCKED` - Can't proceed
- `PAUSED` - Temporarily stopped
- `REVIEW` - Awaiting review
- `COMPLETE` - Finished
- `ABORTED` - Cancelled

### Priority Values
- `CRITICAL` - Immediate action required
- `HIGH` - Important, do soon
- `MEDIUM` - Nice to have
- `LOW` - Do when time permits

### Role Values
- `Manager` - Planning, coordination
- `Architect` - Design, ADRs
- `Builder` - Implementation
- `Tester` - Testing, QA
- `Documentarian` - Documentation
- `Designer` - UI/UX design
- `Inspector` - Reviews, audits
- `Operator` - Deployment, infrastructure

---

## See Also

**New PM System:**
- `.opencode/scripts/README.md` - Quick start guide for unified PM system
- `.opencode/data/README.md` - Complete PM system reference

**Legacy Task System:**
- `.opencode/tasks/README.md` - Overview of original task system (technical details)
- `.opencode/tasks/schema.sql` - Original database schema
- `.opencode/tasks/artifacts/` - Task markdown files

**Related Commands:**
- `/dismiss` command - Automatically closes tasks at session end
