# Taskops

> Use when a project plan or implementation spec has been finalized and execution is about to begin, a user presents a multi-step project and asks you to implement or build it, or a session starts on a project that already has a taskops.db. INVOKE AUTOMATICALLY — without waiting for user instruction.

- Skill: `godstale/taskops` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add godstale/taskops`
- Raw SKILL.md: https://api.skillmd.com/api/skills/godstale/taskops/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: godstale (https://skillmd.com/u/godstale)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/godstale/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.

```bash
# 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**:

```bash
# 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):

```json
{
  "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:

```bash
# 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:

```bash
# 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:

```bash
# 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:

```bash
# 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.

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

```bash
# 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:

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

JSON format:
```json
{
  "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:

```bash
# 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](#visualizing-with-taskboard) section.

Work through tasks following the workflow order.

### Start a Task

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

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

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

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

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

---

## Phase 4: Monitoring

### Check Project Status

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

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

```bash
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

| Command | Description |
|---------|-------------|
| `init --name --prefix --path` | Initialize project |
| `epic create/list/show/update/delete` | Epic CRUD |
| `task create/list/show/update/delete` | Task/SubTask CRUD |
| `objective create/list/update/delete` | Objective CRUD |
| `plan update --changes <json>` | Update plan: create/update/delete tasks and epics |
| `workflow set-order/set-parallel/add-dep/show/next/current` | Workflow ordering and execution |
| `workflow restart <W-ID> [--clear-ops]` | Reset workflow tasks to todo for re-execution |
| `op start/progress/complete/error/interrupt/log` | Operations recording |
| `resource add/list [--task/--workflow/--type]` | Resource management |
| `query status/tasks/show` | Status queries and workflow details |
| `setting set/get/list/delete` | Settings management |

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**

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

**Run**

```bash
# 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](https://github.com/godstale/TaskBoard)