Task Ledger

Durable workflow layer for OpenClaw long-running work. Use when tasks are multi-stage, recoverable, parallelized across sub-agents/ACP, use background exec o...

Security Scan

The skill's files, runtime instructions, and requested resources are coherent with its stated purpose as a local, filesystem-backed durable task toolkit and do not request unrelated credentials or network installs.

Purpose & Capability

Name/description match the actual artifacts: a filesystem-backed toolkit for durable task objects. Required binaries (python3, bash) are appropriate for the included scripts. No unrelated credentials, binaries, or config paths are requested.

Instruction Scope

SKILL.md stays within scope: it instructs copying bundled toolkit files into the workspace, creating tasks/logs/outputs directories, and using the provided scripts to manage task JSONs. The scripts only read/write local workspace files and do not attempt to read unrelated system config or environment secrets. The instructions caution not to overwrite user-modified files and to confirm plans with the user.

Install Mechanism

There is no external install-from-URL. An included install.sh copies bundled files into the workspace only if missing. No external downloads, package manager installs, or archive extraction are performed.

Credentials

The skill requires no environment variables or credentials. The scripts operate on workspace directories (tasks/, logs/, outputs/) and only store/modify JSON task files and logs; they do not access or exfiltrate secrets, network endpoints, or unrelated system credentials.

Persistence & Privilege

always is false and the skill is user-invocable. The toolkit writes files only under the workspace (tasks/, logs/, outputs/, scripts/, task-templates/) and does not modify other skills or system-wide agent settings.

Assessment

This toolkit appears coherent and local-only: it creates and updates task JSON files and log/output directories under your workspace and uses python3/bash. Before installing or running it, review the bundled scripts and templates to confirm the file paths are acceptable for your workspace and that you are happy with local disk writes to tasks/, logs/, and outputs/. The skill does not request secrets or perform network downloads, but standard caution applies: do not install into a workspace containing sensitive production files without backing them up, and confirm any task actions that perform external side effects (deploy/restart) before executing.

Use Task Ledger to turn long-running agent work into durable task objects instead of relying on fragile chat context.

Task Ledger is a workflow layer on top of OpenClaw execution primitives. It does not replace ACP, sub-agents, exec, cron, or skills. It gives them a durable task structure:

• checkpoint files in tasks/
• execution logs in logs/
• artifacts and reports in outputs/
• execution bindings for process/session/cron references
• parent/child task trees
• dependency and readiness checks
• recovery protocol
• short-first reporting

Trigger

Use this skill when any of these are true:

• task runtime will likely exceed 5 minutes
• task has more than 3 stages
• task uses background exec
• task uses sessions_spawn
• task uses cron
• task has external side effects
• task involves restart / deploy / maintenance workflows with risky side effects
• task should be split into parent/child tasks or tracked with dependencies
• multiple agents or sub-agents will work in parallel
• task readiness should be checked before starting downstream work
• task reporting should prefer short updates backed by long file-based reports
• the user wants the work to be recoverable / resumable / auditable

Do not use this skill for every tiny action. It is meant for work where losing state or execution structure would be costly.

What this skill provides

This package includes:

• task checkpoint JSON files in tasks/
• execution logs in logs/
• outputs/artifacts in outputs/
• lifecycle helpers for create/update/advance/close
• recovery helpers for verify/resume-summary
• binding helpers for process/subtask/cron references
• rollback metadata in the task schema
• parent/child task relations and dependency-aware tooling
• readiness-aware scheduling helpers
• specialized templates for restart and deployment workflows
• human-friendly export for reports, handoff, archival, and graph views
• short-first reporting with optional file-backed long reports

Bundled files live next to this skill under toolkit/.

First-use bootstrap

If the current workspace does not already contain the toolkit, copy these bundled assets into the workspace root:

• toolkit/scripts/* → <workspace>/scripts/
• toolkit/task-templates/* → <workspace>/task-templates/
• toolkit/tasks/README.md → <workspace>/tasks/README.md

Always create the runtime directories if missing:

• tasks/
• logs/
• outputs/

Do not overwrite user-modified files silently unless explicitly asked. Prefer copying only missing files and then report what was installed.

Operating protocol

1. Confirm the plan with the user before execution.
2. Create the task skeleton first.
3. Choose explicit stages that match reality.
4. Record execution references (process.sessionId, subtask.sessionKey, cron.jobId) when they exist.
5. Link parent/child tasks and dependencies when the work is larger than a single task object.
6. If work is parallelized, prefer one parent task plus one child task per worker.
7. Check readiness before starting dependent tasks; use start-if-ready when appropriate.
8. Update the task file after every completed stage.
9. On recovery, read the resume summary and verify real state first.
10. If reality and the checkpoint disagree, correct the checkpoint before continuing.
11. Continue only the unfinished work.
12. Prefer short user-facing summaries and keep long reports on file when appropriate.
13. Export or summarize task state in a human-friendly form when needed.
14. Proactively notify on completion.
15. If execution was interrupted and later resumed/reconnected, proactively notify that too.

Parallel task pattern

For multi-agent or multi-sub-agent work:

• create one parent task for the overall goal
• create one child task per worker / subtask branch
• bind each child task to its own execution reference
• keep detailed stage tracking on child tasks
• let the parent task orchestrate readiness, finalization, and reporting

Avoid treating one task JSON file as a shared concurrent write target. Task trees are safer than shared state.

Core commands

Create a task skeleton:

./scripts/new-task.sh <slug> <title> [goal] [executionMode] [stagesCsv] [priority] [owner]

Useful helpers:

./scripts/list-open-tasks.py
python3 ./scripts/task-ls-tree.py
python3 ./scripts/task-ready.py <taskId> [--json]
python3 ./scripts/task-start-if-ready.py <taskId> [nextAction]
python3 ./scripts/task-graph-export.py [--format markdown|dot|json] [--open-only]
./scripts/show-task.py <taskId>
./scripts/task-events.py <taskId> [limit] [--type <eventType>] [--json]
./scripts/update-task.py <taskId> ...
./scripts/task-advance.py <taskId> [nextAction]
./scripts/task-bind-process.py <taskId> <processSessionId> [pid] [--state <state>]
./scripts/task-bind-subtask.py <taskId> <sessionKey> [--agent-id <agentId>]
./scripts/task-bind-cron.py <taskId> <jobId> [--schedule <expr>] [--next-run-at <iso>]
./scripts/task-verify.py <taskId> <summary> ...
./scripts/task-resume-summary.py <taskId> [--json|--markdown]
./scripts/task-export.py <taskId> [--format markdown|json|short] [--write-report]
./scripts/close-task.py <taskId> <final-status> [summary]
./scripts/task-doctor.py [taskId] [--strict] [--json]

Specialized templates

Use bundled examples for common risky workflows:

• restart-openclaw-gateway.example.json
• deploy-service.example.json
• sync-feishu-doc.example.json

Practical rule

Task files are not truth. They are cached descriptions of truth. Reality wins.