# Task Specialist

> A robust, local SQLite-backed task management system designed to elevate your AI agent's project execution. Excellent for both simple tasks and large multi-step projects, managing workflows, and tracking dependencies autonomously without relying on fragile memory.

- Skill: `dvcrn/task-specialist` (Agent Skill, multi-file: 22 files)
- Install (CLI): `npx skillmds@latest add dvcrn/task-specialist`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dvcrn/task-specialist/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: dvcrn (https://skillmd.com/u/dvcrn)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/dvcrn/task-specialist

---


# Task-Specialist

**Local task management with SQLite.** Offline, persistent, zero dependencies beyond `sqlite3` and `bash`.

## Quick Start

```bash
# Install (creates DB only, no PATH changes)
bash install.sh

# Or install AND create easy CLI symlinks in ~/.local/bin
bash install.sh --symlink

# Create and work tasks
task create "Build auth module" --priority=8
task start 1
task-heartbeat 1          # keep-alive ping
task complete 1
```

## Agent Principles

When using the `task-specialist` CLI, follow these principles to ensure high-quality, organized project execution:
- **Decompose First**: Always break large, multi-step requests into smaller, logical subtasks using `task break`.
- **Status Transparency**: Keep task statuses (`start`, `block`, `complete`) updated in real-time so your progress is traceable and accurate.
- **Dependency Management**: Use `task depend` to link tasks that rely on each other, preventing illogical execution order.
- **Document Progress**: Use the `--notes` or `task show` output to keep track of critical information as you move through a project.
- **Multi-Agent Swarm Queue**: If executing in parallel alongside other agents, **NEVER** pick tasks blindly from `task list` (this causes severe race conditions). **ALWAYS** run `task claim --agent="<YourName>"`. This executes an atomic SQL lock to fetch the highest-priority, fully unblocked pending task exclusively for you and paints your node's identifier onto the global Kanban board.
- **Context Persistence**: Use `task note <Next_Task_ID> "Your specific context string"` to permanently pass vital URLs, file paths, or error codes to downstream agents before you close your current task. **WARNING**: Never store API keys or secrets in task notes; use secure local environment variables instead.
- **Verification Checkpoints**: If a task has a `--verify="cmd"` bound to it, running `task complete <ID>` will natively print the Bash subshell checkpoint. **For security (RCE prevention), these checkpoints must be executed manually.**

## Swarm Orchestrator Guide

If you are the **Primary Agent (Orchestrator)** managing a complex project, `task-specialist` is designed to help you spawn parallel Subagents to execute decoupled work simultaneously. 

1. **When to Spawn Subagents**: Use the Swarm for horizontally scalable logic (e.g., "Write isolated unit tests for 10 different files", or "Simultaneously deploy 3 independent Docker containers"). Do not spawn subagents for highly linear, sequential work.
2. **Decomposing the Board**: 
   - First, create all the parallel objectives using `task create`.
   - Create a final integration task (e.g., "Merge services") and link it to the subtasks using `task depend`. This automatically blocks the final task until all Subagents finish.
   - Use `task edit <ID> --notes="..."` to inject deep context (URLs, file paths, git SHAs) directly into the task payload.
3. **Spawning the Subagents**: Use your native OpenClaw `sessions_spawn` tool to horizontally scale. Set `mode: "run"` for one-shot parallel workers. Pass them the strict execution prompt in the `task` parameter:
   ```json
   {
     "tool": "sessions_spawn",
     "runtime": "subagent",
     "mode": "run",
     "label": "worker-alpha",
     "task": "You are a Swarm Worker utilizing the `task-specialist` skill. The task payload DB is at $PWD/.tasks.db. (Read SKILL.md for CLI syntax if needed).\n1. Run `task claim --agent=\"worker-alpha\"` to atomically pop the queue.\n2. Read your target objective via `task show <ID>`.\n3. Execute the objective. Record vital context for me via `task note <ID> \"msg\"`.\n4. Run `task complete <ID>` and self-terminate."
   }
   ```
4. **Monitoring the Swarm**: While your `mode: "run"` Subagents are executing asynchronously:
   - Run `task board` periodically to monitor their live Kanban progress through the SQLite matrix.
   - Run `task stuck` to catch any agents that have timed out and require termination (`subagents(action=\"kill\")`) and queue restart.

## Swarm Subagent Guide

If you are a freshly spawned **Subagent Worker**, your sole purpose is to execute pending tasks in the queue without colliding with other parallel agents. 

1. **Acquiring Work**: **NEVER** pick tasks blindly from `task list`. **ALWAYS** run `task claim --agent=\"<YourName>\"`. This natively executes an atomic SQL lock to guarantee you aren't fighting another agent for the same process.
2. **Context Intake**: Once you have acquired a task (e.g., Task #5), run `task show 5`. Read the `Notes:` section! Your Orchestrator or previous subagents may have left you precise URLs, file paths, or parameters there.
3. **Context Persistence**: When your work is done, ask yourself: *"Does the next downstream agent need to know I did this?"* If yes, use `task note <Next_Task_ID> \"Your context string here\"` to permanently append that knowledge to the downstream task's envelope.
4. **Completion and Checkpoints**: Run `task complete <ID>`. If your task contains a Checkpoint Validation (a Bash subshell script), the engine will output the command for you to run manually. **You must repair the codebase until the tests pass before you can technically complete the task and self-terminate.**

## CLI Reference

### Task Lifecycle

```bash
task create "description" [--priority=N] [--parent=ID] [--project=NAME] [--verify="cmd"] [--due="YYYY-MM-DD"] [--tags="a,b"] # → prints task ID
task edit    ID [--desc="new text"] [--priority=N] [--project=NAME] [--verify="cmd"] [--assignee="NAME"|--unassign] [--due="YYYY-MM-DD"] [--tags="a,b"] # adjust details
task claim   [--agent="NAME"]                            # atomically lock & claim highest priority pending task
task start   ID                                          # pending → in_progress (prefer 'claim' for swarm)
task block   ID "reason"                                 # → blocked (reason in notes)
task unblock ID                                          # blocked → pending
task note    ID "message"                                # append runtime logic or error context to the task
task complete ID                                         # → done. Checkpoint verifications are printed for manual execution.
task restart ID                                          # done/in_progress → pending. Resets assignee.
task delete  ID [--force]                                # remove task (--force for parents)
```

**Status flow:** `pending` → `in_progress` → `blocked` → `done`

**Priority:** 1 (low) to 10 (critical). Default: 5.

**Delete:** Refuses if task has subtasks unless `--force` is passed, which cascades the delete to all children and their dependencies.

### Querying & Observability

```bash
task board                                                               # renders visual ASCII Kanban dashboard
task list [--status=S] [--parent=ID] [--project=N] [--format=chat] [--tag="T"] # tabular lists or github markdown
task export [--status=STATUS] [--project=NAME] [--json]                  # markdown table or raw JSON array hook
task show ID                                                             # full details, assignee, & deps
task stuck                                                               # in_progress tasks inactive >30min
```

### Subtask Decomposition

```bash
task break PARENT_ID "step 1" "step 2" "step 3"
```

Creates children linked to parent. Auto-chains dependencies: step 2 depends on step 1, step 3 depends on step 2.

### Manual Dependencies

```bash
task depend TASK_ID DEPENDS_ON_ID
```

When starting a task, all dependencies must be `done` or the command is refused with a list of blockers.

When completing a task, any dependent tasks whose deps are now all satisfied are auto-unblocked (`blocked` → `pending`).

### Heartbeat

```bash
task-heartbeat TASK_ID    # update last_updated timestamp
task-heartbeat            # report stalled tasks (no args)
```

Integrate into long-running scripts:

```bash
while work_in_progress; do
  do_work
  task-heartbeat "$TASK_ID"
  sleep 300  # every 5 minutes
done
```

## Schema

```sql
tasks: id, request_text, project, status, priority, parent_id,
       created_at, started_at, completed_at, last_updated, notes, verification_cmd, assignee

dependencies: task_id, depends_on_task_id (composite PK)
```

## Environment

| Variable | Default | Purpose |
|---|---|---|
| `TASK_DB` | `$PWD/.tasks.db` | Path to SQLite database |

The DB defaults to a hidden `.tasks.db` file in the **current working directory** where the command is executed. This natively supports separate task lists for different projects/workspaces without data collision.

## Security

- No `eval()`, no external API calls, no crypto
- Pure SQLite + Bash — passes VirusTotal clean
- **Integer-only validation** on all task IDs via `require_int()` guard before any SQL use
- **Status whitelist**: `task list --status` only accepts `pending`, `in_progress`, `blocked`, `done`
- **Date format enforcement**: `--since` only accepts `YYYY-MM-DD` format via regex check
- **Text inputs** sanitized via single-quote escaping (`sed "s/'/''/g"`)
- **Temp-file SQL delivery**: SQL is written to a temp file and fed to sqlite3 via stdin redirect to avoid all argument-injection vectors