Taskops

TaskOps — Project Management Skill for Claude Code

When to Invoke

Invoke this skill proactively — you do NOT need an explicit user instruction.

Trigger conditions (any one is sufficient):

• User has finished writing or approving a plan/spec and says "let's start", "implement this", or similar
• User asks you to build a multi-step project without mentioning task management
• Session starts and taskops.db exists in the project directory (resume mode)

Correct order:

1. User finalizes plan → Invoke TaskOps → initialize + decompose into ETS → define workflow
2. Begin execution → remind user to launch TaskBoard for monitoring
3. Work through tasks in workflow order

Prerequisites

• Python 3.10+
• TaskOps repository cloned (contains cli/ package and hooks/)
• Project initialized with python -m cli init

Phase 1: Initialization

Initialize a new TaskOps project. Use --db to specify a custom database location; this path will be stored in a .taskops file and used automatically for all subsequent commands.

# Initialize and set sticky DB path
python -m cli init --name "Project Name" --prefix PRJ --db ./my-project.db

This creates taskops.db (or your custom DB) and a .taskops config file.

After init, select an existing workflow or create a new one — all ETS must belong to a workflow:

# List existing workflows (resume scenario)
python -m cli workflow list

# Create a new workflow (always include --description for duplicate detection)
python -m cli workflow create \
  --title "My Plan" \
  --description "Brief description of scope and intent"
# → Workflow ID: PRJ-MP

Configure Hooks

Register TaskOps hooks in .claude/settings.json (project-level):

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write|Bash",
        "command": "bash /path/to/TaskOps/hooks/on_tool_use.sh"
      }
    ]
  }
}

Available hooks:

• on_task_start.sh <TASK_ID> — Sets task to in_progress, records op start
• on_tool_use.sh — Records op progress for the current active task
• on_task_complete.sh <TASK_ID> — Sets task to done, records op complete

AI Agent Usage Scenarios

TaskOps persists work plans and artifacts across AI agent sessions. Use these patterns to store, retrieve, and re-execute workflows.

Store a Plan for Later

Save a work plan as a workflow so any future session can pick it up:

# Create workflow with description (for duplicate detection)
python -m cli workflow create \
  --title "API Migration Plan" \
  --description "Migrate REST endpoints to async handlers. Covers auth, user, billing."
# → Workflow ID: PRJ-AMP

# Import the structured plan
python -m cli workflow import PRJ-AMP --structure '<json>'

Resume a Plan in a New Session

At session start, check what workflows exist and load the relevant one:

# List all workflows
python -m cli workflow list

# Load full task structure for a workflow
python -m cli query show --workflow PRJ-AMP

# Find the next task to work on
python -m cli workflow next

Track Artifacts Produced by a Workflow

Register files created during task execution as resources for later retrieval:

# Register an output file
python -m cli resource add AMP-T003 --path ./output/report.json --type output --desc "Final report"

# Register intermediate work product
python -m cli resource add AMP-T002 --path ./tmp/analysis.csv --type intermediate --desc "Raw analysis"

# Retrieve all artifacts from a workflow
python -m cli resource list --workflow PRJ-AMP

# Retrieve only final outputs
python -m cli resource list --workflow PRJ-AMP --type output

Re-execute a Workflow

Reset a workflow's tasks to todo and run it again. Other workflows are unaffected:

# Restart a specific workflow (auto-saves checkpoint first)
python -m cli workflow restart PRJ-AMP

# Restart and clear operation history
python -m cli workflow restart PRJ-AMP --clear-ops

# Verify reset state
python -m cli query show --workflow PRJ-AMP

Phase 2: Planning

Decompose the project into ETS components.

ETS Hierarchy

Project
  └── Epic — Major feature unit
        └── Task — Implementation unit
              └── SubTask — Detailed step (create only when needed)
  └── Objective — Milestone or deadline

Create Structure

⚠️ --workflow <W-ID> is required for all create commands.

# Create Epics
python -m cli epic create --workflow PRJ-AMP --title "Authentication System"
# → AMP-E001

# Create Tasks under Epic
python -m cli task create --workflow PRJ-AMP --parent AMP-E001 --title "Login API"
# → AMP-T001

# Create SubTasks under Task (only when needed)
python -m cli task create --workflow PRJ-AMP --parent AMP-T001 --title "JWT token generation"
# → AMP-T002

# Create Objectives
python -m cli objective create --workflow PRJ-AMP --title "MVP Complete" --milestone "Core features done"
python -m cli objective create --workflow PRJ-AMP --title "Demo Day" --due-date 2026-04-01

Define Workflow

# Set execution order
python -m cli workflow set-order AMP-T001 AMP-T002 AMP-T003

# Group tasks for parallel execution
python -m cli workflow set-parallel --group "auth-group" AMP-T002 AMP-T003

# Add dependencies
python -m cli workflow add-dep AMP-T004 --depends-on AMP-T002 AMP-T003

Updating the Plan

When the user modifies the project plan (adds, removes, or renames tasks or epics), apply changes to the DB before continuing:

python -m cli plan update --changes '<json>'

JSON format:

{
  "create": [
    {"type": "epic", "title": "New Epic"},
    {"type": "task", "title": "New Task", "parent_id": "AMP-E001"}
  ],
  "update": [{"id": "AMP-T001", "title": "...", "status": "..."}],
  "delete": [{"id": "AMP-T002"}]
}

Note: parent_id is required for type: "task" and must reference an existing epic or task. Any of create, update, delete may be omitted.

Phase 3: Execution

Before starting work, guide the user to launch TaskBoard for real-time monitoring:

# In a separate terminal — run from the TaskBoard directory
pnpm --filter @taskboard/tui dev -- --path /path/to/project-root

TaskBoard watches taskops.db and refreshes automatically as tasks progress. If TaskBoard is not installed, see the Visualizing with TaskBoard section.

Work through tasks following the workflow order.

Start a Task

# Check next executable task
python -m cli workflow next

# Start the task
python -m cli task update AMP-T001 --status in_progress
python -m cli op start AMP-T001 --platform claude_code

If hooks are configured, use bash hooks/on_task_start.sh AMP-T001 instead.

Record Progress

# Record meaningful progress milestones
python -m cli op progress AMP-T001 --summary "Implemented 3 of 5 endpoints"

With hooks configured, on_tool_use.sh records progress automatically on each tool use.

Complete a Task

# Mark task as done
python -m cli task update AMP-T001 --status done
python -m cli op complete AMP-T001 --summary "Login API complete, all tests pass"

If hooks are configured, use bash hooks/on_task_complete.sh AMP-T001 instead.

Handle Interruptions

# Record interruption with reason
python -m cli task update AMP-T001 --status interrupted --interrupt "Waiting for API key"
python -m cli op interrupt AMP-T001 --summary "Blocked on external dependency"

Handle Errors

python -m cli op error AMP-T001 --summary "Database connection failed"

Phase 4: Monitoring

Check Project Status

# Overall status with progress percentage
python -m cli query status

# List tasks by status
python -m cli query tasks --status in_progress

# View operation log for a task
python -m cli op log --task AMP-T001

# View full workflow
python -m cli workflow show

Manage Resources

# Add resource reference to a task
python -m cli resource add AMP-T001 --path ./docs/spec.md --type input --desc "API spec"

# List resources
python -m cli resource list --task AMP-T001

Manage Settings

python -m cli setting set commit_style "conventional" --desc "Commit message style"
python -m cli setting get commit_style
python -m cli setting list

Reference: All CLI Commands

All commands use: python -m cli [--db path] <command> <subcommand> [options]

Visualizing with TaskBoard

TaskBoard is a standalone read-only GUI that visualizes the TaskOps database. Guide the user to install it when they want to monitor project progress visually.

Install

git clone https://github.com/godstale/TaskBoard.git
cd TaskBoard
pnpm install

Run

# TUI (terminal)
pnpm --filter @taskboard/tui dev -- --path /path/to/taskops-root

# Electron (desktop app)
pnpm --filter @taskboard/electron dev

TaskBoard watches the taskops.db file and automatically refreshes when the DB changes. → TaskBoard GitHub