Taskflow

TaskFlow — Agent Skill Reference

TaskFlow gives any OpenClaw agent a structured project/task/plan system with markdown-first authoring, SQLite-backed querying, and bidirectional sync.

Principle: Markdown is canonical. Edit tasks/*.md directly. The SQLite DB is a derived index, not the source of truth.

Security

OPENCLAW_WORKSPACE Trust Boundary

OPENCLAW_WORKSPACE is a high-trust value. All TaskFlow scripts resolve file paths from it, and the CLI and sync daemon use it to locate the SQLite database, markdown task files, and log directory.

Rules for safe use:

1. Set it only from trusted, controlled sources. The value must come from:

   • Your own shell profile (.zshrc, .bashrc, /etc/environment)
   • The systemd user unit Environment= directive in a template you control
   • The macOS LaunchAgent EnvironmentVariables dictionary you installed

   Never accept OPENCLAW_WORKSPACE from:

   • User-supplied CLI arguments or HTTP request parameters
   • Untrusted config files read at runtime
   • Any external input that has not been explicitly validated

2. Validate the path exists before use. Any script that reads OPENCLAW_WORKSPACE should confirm the directory exists before proceeding:

   import { existsSync } from 'node:fs'
   import path from 'node:path'
   
   const workspace = process.env.OPENCLAW_WORKSPACE
   if (!workspace) {
     console.error('OPENCLAW_WORKSPACE is not set. Aborting.')
     process.exit(1)
   }
   if (!existsSync(workspace)) {
     console.error(`OPENCLAW_WORKSPACE path does not exist: ${workspace}`)
     process.exit(1)
   }
   // Resolve to absolute path to neutralize any relative-path tricks
   const safeWorkspace = path.resolve(workspace)

3. Do not construct paths from untrusted input. Even with a valid OPENCLAW_WORKSPACE, never concatenate unvalidated user input onto it (e.g. path.join(workspace, userSlug, '../../../etc/passwd')). Use path.resolve() and check that the resolved path starts with the workspace root:

   function safeJoin(base, ...parts) {
     const resolved = path.resolve(base, ...parts)
     if (!resolved.startsWith(path.resolve(base) + path.sep)) {
       throw new Error(`Path traversal attempt detected: ${resolved}`)
     }
     return resolved
   }

4. Treat OPENCLAW_WORKSPACE as a local system path only. It must point to a directory on the local filesystem. Remote paths (NFS mounts, network shares) may work but are outside the tested configuration and could introduce TOCTOU (time-of-check/time-of-use) race conditions.

Setup

1. Set environment variable

Add to your shell profile (.zshrc, .bashrc, etc.):

export OPENCLAW_WORKSPACE="/path/to/your/.openclaw/workspace"

All TaskFlow scripts and the CLI resolve paths from this variable. Without it, they fall back to process.cwd(), which is almost never what you want.

See also: OPENCLAW_WORKSPACE Trust Boundary above for security requirements.

2. Link the CLI

ln -sf {baseDir}/scripts/taskflow-cli.mjs /opt/homebrew/bin/taskflow  # macOS (Apple Silicon)
# or: ln -sf {baseDir}/scripts/taskflow-cli.mjs /usr/local/bin/taskflow

3. Run the setup wizard

taskflow setup

The wizard handles the rest: creates workspace directories, walks you through adding your first project(s), initializes the database, syncs, and optionally installs the macOS LaunchAgent for periodic sync.

Alternative — manual setup:

<details>
<summary>Manual steps (if you prefer explicit control)</summary>

# Create workspace dirs
mkdir -p "$OPENCLAW_WORKSPACE/tasks" "$OPENCLAW_WORKSPACE/plans" "$OPENCLAW_WORKSPACE/memory" "$OPENCLAW_WORKSPACE/logs"

# Bootstrap the DB schema
taskflow init

# Create PROJECTS.md and tasks/<slug>-tasks.md manually (see templates/)

# Sync markdown → DB
taskflow sync files-to-db

# Verify
taskflow status

</details>

First Run

For agents (OpenClaw / AI)

When a user asks you to set up TaskFlow or you detect it has not been initialized:

1. Detect state. Check for $OPENCLAW_WORKSPACE/PROJECTS.md and $OPENCLAW_WORKSPACE/memory/taskflow.sqlite.
2. If clean slate: Ask the user for their first project name and description, then run:

   taskflow setup --name "Project Name" --desc "One-liner description"

   Follow up by running taskflow status to confirm.
3. If PROJECTS.md exists but no DB: Run taskflow setup (it detects the state automatically and offers to init + sync).
4. If both exist: Run taskflow status — already set up.
5. After setup, update AGENTS.md with the new project slug so future sessions discover it via cat PROJECTS.md.

For humans (CLI)

taskflow setup

The interactive wizard will:

• Detect your existing workspace state
• Walk you through naming your first project(s)
• Create PROJECTS.md and tasks/<slug>-tasks.md from templates
• Initialize the SQLite database and sync
• Offer to install the periodic-sync daemon (LaunchAgent on macOS, systemd timer on Linux) for automatic 60s sync

Non-interactive (scripted installs):

taskflow setup --name "My Project" --desc "What it does"

Passing --name skips all interactive prompts (daemon install is also skipped in non-interactive mode).

Directory Layout

<workspace>/
├── PROJECTS.md                      # Project registry (one ## block per project)
├── tasks/<slug>-tasks.md            # Task list per project
├── plans/<slug>-plan.md             # Optional: architecture/design doc per project
└── taskflow/
    ├── SKILL.md                     # This file
    ├── scripts/
    │   ├── taskflow-cli.mjs         # CLI entry point (symlink target)
    │   ├── task-sync.mjs            # Bidirectional markdown ↔ SQLite sync
    │   ├── init-db.mjs              # Bootstrap SQLite schema (idempotent)
    │   ├── export-projects-overview.mjs  # JSON export of project/task state
    │   └── apple-notes-export.mjs   # Optional: project state → Apple Notes (macOS only)
    ├── templates/                   # Starter files for new projects
    ├── schema/
    │   └── taskflow.sql             # Full DDL
    └── system/
        ├── com.taskflow.sync.plist.xml  # Periodic sync (macOS LaunchAgent)
        ├── taskflow-sync.service        # Periodic sync (Linux systemd user unit)
        └── taskflow-sync.timer          # Systemd timer (60s interval)
<workspace>/
└── taskflow.config.json                 # Apple Notes config (auto-created on first notes run)

Creating a Project

Follow this full checklist when creating a new project:

1. Add a block to PROJECTS.md

## <slug>
- Name: <Human-Readable Name>
- Status: active
- Description: One-sentence description of the project.

• slug is lowercase, hyphenated (e.g., my-project). It becomes the canonical project ID everywhere.
• Valid status values: active, paused, done.

2. Create the task file

Copy taskflow/templates/tasks-template.md → tasks/<slug>-tasks.md and update the project name in the heading.

The file must contain these five section headers in this order:

# <Project Name> — Tasks

## In Progress
## Pending Validation
## Backlog
## Blocked
## Done

3. Optionally create a plan file

Copy taskflow/templates/plan-template.md → plans/<slug>-plan.md for architecture docs, design decisions, and phased roadmaps. Plan files are not synced to SQLite — they are reference-only for the agent.

4. DB row (auto-created on first sync)

You do not need to manually insert into the projects table. The sync engine auto-creates the project row from PROJECTS.md on the next files-to-db run. If you want to be explicit via Node.js, use a parameterized statement:

// Safe: parameterized insert — no string interpolation in the SQL
db.prepare(`INSERT INTO projects (id, name, description, status)
            VALUES (:id, :name, :description, 'active')`)
  .run({ id: slug, name: projectName, description: projectDesc })

Task Line Format

Every task line follows this exact format:

- [x| ] (task:<id>) [<priority>] [<owner>] <title>

⚠️ Tag Order Rule

Priority tag MUST come before owner tag. The sync parser is positional — it reads the first [Px] bracket as priority, and the next [tag] as owner. Swapping them will misparse the task.

⚠️ Title Sanitization Rules

Task titles must be plain text only. Before writing any user-supplied string as a task title, apply the following rules:

1. Reject lines that look like section headers. A title may not start with one or more # characters followed by a space (e.g. # My heading, ## Done). These would corrupt the sync parser's section detection.

2. Reject the exact section header strings even without leading whitespace:

   • In Progress, Pending Validation, Backlog, Blocked, Done
   • Comparison must be case-insensitive.

3. Escape or strip markdown special characters that have structural meaning in the task file:

   Character	Risk	Safe action
   #	Looks like a header	Strip or reject
   - (dash + space at line start)	Looks like a list item / task	Strip leading -
   [ ] / [x]	Looks like a checkbox	Escape brackets: \[ \]
   ] / [ alone	Can corrupt (task:id) parse	Escape: \[ \]
   Newlines (\n, \r)	Creates multi-line titles	Strip / reject

4. Maximum length. Titles should be ≤ 200 characters. Truncate or reject longer strings.

Example sanitization (Node.js):

// Safe: sanitize a user-supplied task title before writing to markdown
function sanitizeTitle(raw) {
  if (typeof raw !== 'string') throw new TypeError('title must be a string')

  // Strip newlines
  let title = raw.replace(/[\r\n]+/g, ' ').trim()

  // Reject lines that look like section headers (# Heading or bare header words)
  if (/^#{1,6}\s/.test(title)) {
    throw new Error('Title may not start with a markdown heading (#)')
  }
  const BANNED_HEADERS = /^(in progress|pending validation|backlog|blocked|done)$/i
  if (BANNED_HEADERS.test(title)) {
    throw new Error('Title may not be a reserved section header name')
  }

  // Escape structural markdown characters
  title = title
    .replace(/\[/g, '\\[')
    .replace(/\]/g, '\\]')

  // Enforce length limit
  if (title.length > 200) {
    throw new Error('Title exceeds 200 character limit')
  }

  return title
}

These rules apply whenever a task title comes from any external or user-supplied source (CLI args, API payloads, file imports). Titles hard-coded by agents in their own sessions are low-risk but should still avoid structural characters.

✅ Correct: - [ ] (task:myproject-007) [P1] [codex] Implement search ❌ Wrong: - [ ] (task:myproject-007) [codex] [P1] Implement search

Priority Levels (Configurable)

Priorities are configurable per-installation but the tags themselves (P0–P3, P9) are what the sync engine validates.

Optional Note Lines

A note can follow a task line as an indented - note: line:

- [ ] (task:myproject-003) [P1] [codex] Implement auth flow
  - note: blocked on API key from vendor

Known limitation (v1): Notes are one-way. Removing or editing a note in markdown does not propagate to the DB. This is tracked for a post-MVP fix.

Example Task File Section

## In Progress
- [ ] (task:myproject-001) [P1] [codex] Wire up OAuth login
  - note: PR open, needs review

## Backlog
- [ ] (task:myproject-002) [P2] Add rate limiting middleware
- [ ] (task:myproject-003) [P3] Write integration tests

Adding a New Task

1. Determine the next ID. Scan the task file for the highest existing <slug>-NNN and increment by 1. Or query SQLite using a parameterized statement (never interpolate the slug into SQL strings):

   // Node.js — safe, parameterized
   const db = new DatabaseSync(dbPath)
   const row = db
     .prepare(`SELECT MAX(CAST(SUBSTR(id, LENGTH(:slug) + 2) AS INTEGER)) AS max_seq
               FROM tasks_v2
               WHERE project_id = :slug`)
     .get({ slug: projectSlug })
   const nextSeq = (row.max_seq ?? 0) + 1
   const nextId  = `${projectSlug}-${String(nextSeq).padStart(3, '0')}`

   ⚠️ Never construct SQL by string interpolation. Use db.prepare() with named or positional parameters (? or :name) for all values that come from external input. This applies even for read-only queries.

2. Append the task line to the correct section (## Backlog for new work, ## In Progress if starting immediately).

3. Format the line using the exact format above. No trailing spaces. Priority tag before owner tag.

Updating Task Status

Move the task line from its current section to the target section in the markdown file.

Also flip the checkbox: [ ] for active states, [x] for Done (and optionally Pending Validation).

The periodic sync (60s) will pick up the change and update SQLite automatically. To force an immediate sync:

node taskflow/scripts/task-sync.mjs files-to-db

Querying Tasks

Simple: Read the markdown file directly

cat tasks/<slug>-tasks.md

For a quick in-session view, just read the relevant section.