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

Security Scan

The skill is internally consistent with its stated purpose: a local, SQLite-backed task manager implemented in Bash that does not request external credentials or network installs — but it can persist arbitrary notes and a full DB export, so avoid storing secrets and be careful when exposing the DB to other agents or symlinking into your PATH.

Purpose & Capability

Name/description (local SQLite task manager) matches required binaries (sqlite3, bash), the included scripts, and the SKILL.md guidance. The files implement a CLI that manipulates a local $PWD/.tasks.db as described — nothing requested is disproportionate to a local task manager.

Instruction Scope

SKILL.md instructs agents to install and use the local CLI and to spawn Subagents (sessions_spawn) that read the workspace DB ($PWD/.tasks.db) and use 'task claim'/'task complete'. That is coherent for a Swarm orchestration use-case, but it means any spawned worker with access to the workspace can read/write all task notes and metadata. The skill explicitly warns not to store API keys in notes and disables auto-execution of verification_cmd, which reduces RCE risk. Still: notes and DB exports can contain arbitrary text (URLs, file paths, error messages) and therefore are a potential leakage vector if other agents or processes are untrusted.

Install Mechanism

There is no network download or external package install: install.sh is bundled and run locally, creates the DB, marks scripts executable, and optionally symlinks into ~/.local/bin. No external URLs, no archive extraction, and no automatic remote code fetches were found.

Credentials

The skill declares no required environment variables or credentials. It optionally honors TASK_DB to override the DB path. It does not require unrelated credentials or access to system config. The feature set (notes, exports) can expose sensitive content if the user places secrets there — the SKILL.md warns against that, and the code avoids sending data externally.

Persistence & Privilege

The skill is not force-included (always: false) and does not request elevated platform privileges. Symlinking into ~/.local/bin is optional and opt-in. The skill does not modify other skills' configurations or system-wide settings beyond optional user-controlled symlinks.

Assessment

This skill appears to be what it claims: a local, SQLite-backed task CLI implemented in bundled Bash scripts. Before installing, consider these practical steps: 1) Run install.sh from a project/workspace directory (it creates $PWD/.tasks.db) so data stays scoped to that project. 2) Do not put secrets (API keys, passwords) into task notes — notes and exports (--json) will include whatever you store and are easy to read by other agents or scripts. 3) If you do not want a persistent CLI on your system, skip the --symlink option when running install.sh. 4) Review any verification_cmd strings stored in tasks before running them manually — the skill prints them but does not auto-execute them. 5) Limit filesystem permissions on .tasks.db (e.g., chmod 600) if the DB will contain sensitive context. 6) If you plan to spawn Subagents, only do so to agents/processes you trust, since they will be able to read/write the same workspace DB and notes. If you want, audit the bundled scripts locally (they are plain Bash) to confirm they meet your security expectations.

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

Quick Start

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

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

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

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

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

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

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

Integrate into long-running scripts:

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

Schema

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