Task-Specialist

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

Quick Start

CODEBLOCK0

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

1. 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:

   {
     "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."
   }
   

1. 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. 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

CODEBLOCK2

Status flow: pending → in_progress → blocked → INLINECODE35

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

CODEBLOCK3

Subtask Decomposition

CODEBLOCK4

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

Manual Dependencies

CODEBLOCK5

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

CODEBLOCK6

Integrate into long-running scripts:

CODEBLOCK7

Schema

CODEBLOCK8

Environment

Variable	Default	Purpose
INLINECODE40	INLINECODE41	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, INLINECODE49
• 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