pulse-libs/skills/taskflow/README.md

TaskFlow

Structured project and task management for OpenClaw agents — markdown-first, SQLite-backed, zero dependencies.

---

---

Quick Start

# 1. Set workspace (add to your shell profile)
export OPENCLAW_WORKSPACE="/path/to/your/.openclaw/workspace"

# 2. Link the CLI
ln -sf "$(pwd)/scripts/taskflow-cli.mjs" /opt/homebrew/bin/taskflow   # macOS
# ln -sf "$(pwd)/scripts/taskflow-cli.mjs" /usr/local/bin/taskflow    # Linux

# 3. Run setup
taskflow setup

The setup wizard creates your workspace structure, walks you through your first project, initializes the SQLite database, syncs your markdown files, and optionally installs a macOS LaunchAgent for automatic 60-second sync.

Non-interactive (scripted installs):

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

---

Features

• Markdown-first — PROJECTS.md and tasks/<slug>-tasks.md are the source of truth; edit them directly in any editor or agent session
• SQLite-backed — bidirectional sync keeps a derived index for fast querying, dashboards, and exports
• Bidirectional sync — files-to-db and db-to-files modes; check for drift with sync check
• CLI — taskflow status, taskflow add, taskflow list, taskflow export, taskflow sync, taskflow setup
• JSON export — full project/task snapshot to stdout, ready for dashboards and integrations
• LaunchAgent (macOS) — automatic 60s background sync via launchctl; Linux cron instructions included
• Zero dependencies — pure Node.js, uses the built-in node:sqlite module (no npm install)

---

CLI

taskflow setup               Interactive first-run onboarding
taskflow status              All projects with task counts and progress bars
taskflow sync files-to-db    Sync markdown → SQLite (markdown is authoritative)
taskflow sync db-to-files    Regenerate markdown from DB state
taskflow sync check          Detect drift (exit 1 if mismatch — good for CI)
taskflow export              JSON snapshot to stdout
taskflow init                Bootstrap or re-bootstrap the SQLite schema
taskflow add <project> ...   Add a task with automatic next ID assignment
taskflow list <project>      List current tasks for a project (supports --project and fuzzy name)
taskflow help                Full reference

---

Requirements

• Node.js 22.5+ (uses node:sqlite / DatabaseSync)
• macOS or Linux

---

How It Works

<workspace>/
├── PROJECTS.md                  # Project registry (one ## block per project)
├── tasks/<slug>-tasks.md        # Task list per project (five fixed sections)
├── plans/<slug>-plan.md         # Optional: architecture / design docs
└── memory/
    └── taskflow.sqlite          # Derived index — never edit directly

Tasks live in five fixed sections: ## In Progress, ## Pending Validation, ## Backlog, ## Blocked, ## Done. A task line looks like:

- [ ] (task:myproject-007) [P1] [codex] Implement search endpoint

The sync engine reads section headers (not checkboxes) to determine task status. Move a line between sections to change status; the LaunchAgent or a manual sync picks it up within 60 seconds.

---

Agent Integration

TaskFlow is designed to be used by OpenClaw agents as a skill. The agent reads PROJECTS.md to discover projects, reads tasks/<slug>-tasks.md for current task state, and edits those files directly — no special API needed.

See SKILL.md for the full agent contract: task line format, sync rules, memory integration policy, SQLite query patterns, and known quirks.

---

Apple Notes Sync (macOS)

taskflow notes pushes a live project status summary to Apple Notes -- share it with your team or just keep it on your phone.

---

Disclaimer

Use at your own risk. We are not liable for any issues you encounter. This is a tool we built for ourselves and found genuinely useful -- sharing it in case other ADHD nerds juggling 10 projects at once get something out of it too. PRs and feedback welcome.

---

Credits

Built by Aux (an OpenClaw agent) and @sm0ls.

License

MIT