{ "schemaVersion": "1.0", "item": { "slug": "hzl", "name": "HZL", "source": "tencent", "type": "skill", "category": "AI 智能", "sourceUrl": "https://clawhub.ai/tmchow/hzl", "canonicalUrl": "https://clawhub.ai/tmchow/hzl", "targetPlatform": "OpenClaw" }, "install": { "downloadMode": "redirect", "downloadUrl": "/downloads/hzl", "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=hzl", "sourcePlatform": "tencent", "targetPlatform": "OpenClaw", "installMethod": "Manual import", "extraction": "Extract archive", "prerequisites": [ "OpenClaw" ], "packageFormat": "ZIP package", "includedAssets": [ "SKILL.md" ], "primaryDoc": "SKILL.md", "quickSetup": [ "Download the package from Yavira.", "Extract the archive and review SKILL.md first.", "Import or place the package into your OpenClaw setup." ], "agentAssist": { "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.", "steps": [ "Download the package from Yavira.", "Extract it into a folder your agent can access.", "Paste one of the prompts below and point your agent at the extracted folder." ], "prompts": [ { "label": "New install", "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete." }, { "label": "Upgrade existing", "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run." } ] }, "sourceHealth": { "source": "tencent", "status": "healthy", "reason": "direct_download_ok", "recommendedAction": "download", "checkedAt": "2026-04-30T16:55:25.780Z", "expiresAt": "2026-05-07T16:55:25.780Z", "httpStatus": 200, "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network", "contentType": "application/zip", "probeMethod": "head", "details": { "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network", "contentDisposition": "attachment; filename=\"network-1.0.0.zip\"", "redirectLocation": null, "bodySnippet": null }, "scope": "source", "summary": "Source download looks usable.", "detail": "Yavira can redirect you to the upstream package for this source.", "primaryActionLabel": "Download for OpenClaw", "primaryActionHref": "/downloads/hzl" }, "validation": { "installChecklist": [ "Use the Yavira download entry.", "Review SKILL.md after the package is downloaded.", "Confirm the extracted package contains the expected setup assets." ], "postInstallChecks": [ "Confirm the extracted package includes the expected docs or setup files.", "Validate the skill or prompts are available in your target agent workspace.", "Capture any manual follow-up steps the agent could not complete." ] }, "downloadPageUrl": "https://openagent3.xyz/downloads/hzl", "agentPageUrl": "https://openagent3.xyz/skills/hzl/agent", "manifestUrl": "https://openagent3.xyz/skills/hzl/agent.json", "briefUrl": "https://openagent3.xyz/skills/hzl/agent.md" }, "agentAssist": { "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.", "steps": [ "Download the package from Yavira.", "Extract it into a folder your agent can access.", "Paste one of the prompts below and point your agent at the extracted folder." ], "prompts": [ { "label": "New install", "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete." }, { "label": "Upgrade existing", "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run." } ] }, "documentation": { "source": "clawhub", "primaryDoc": "SKILL.md", "sections": [ { "title": "HZL: Persistent task ledger for agents", "body": "HZL (https://hzl-tasks.com) is a local-first task ledger that agents use to:\n\nPlan multi-step work into projects + tasks\nCheckpoint progress so work survives session boundaries\nRoute work to the right agent via project pools\nCoordinate across multiple agents with leases and dependencies\n\nThis skill teaches an agent how to use the hzl CLI." }, { "title": "When to use HZL", "body": "OpenClaw has no native task tracking. Unlike Claude Code (which has TodoWrite) or Codex (which has update_plan), OpenClaw relies on memory and markdown files for tracking work. HZL fills this gap.\n\nUse HZL for:\n\nMulti-step projects with real sequencing or handoffs\nWork that may outlive this session or involve multiple agents\nAnything where \"resume exactly where we left off\" matters\nDelegating work to another agent and needing recovery if they fail\n\nSkip HZL for:\n\nTruly trivial one-step tasks you will complete immediately\nTime-based reminders (use OpenClaw Cron instead)\nLongform notes or knowledge capture (use memory files)\n\nRule of thumb: If you feel tempted to make a multi-step plan, or there is any chance you will not finish in this session, use HZL." }, { "title": "⚠️ DESTRUCTIVE COMMANDS — READ FIRST", "body": "CommandEffecthzl init --forceDELETES ALL DATA. Prompts for confirmation.hzl init --force --yesDELETES ALL DATA WITHOUT CONFIRMATION.hzl task prune ... --yesPERMANENTLY DELETES old done/archived tasks and history.\n\nNever run these unless the user explicitly asks you to delete data. There is no undo." }, { "title": "Core concepts", "body": "Project: container for tasks. In single-agent setups, use one shared project. In multi-agent setups, use one project per agent role (pool routing).\nTask: top-level work item. Use parent tasks for multi-step initiatives.\nSubtask: breakdown of a task (--parent ). Max 1 level of nesting. Parent tasks are never returned by hzl task claim --next.\nCheckpoint: short progress snapshot for session recovery.\nLease: time-limited claim that enables stuck detection in multi-agent flows." }, { "title": "Single-agent setup", "body": "Use one shared project. Requests and initiatives become parent tasks, not new projects.\n\nhzl project list # Check first — only create if missing\nhzl project create openclaw\n\nEverything goes into openclaw. hzl task claim --next -P openclaw always works." }, { "title": "Multi-agent setup (pool routing)", "body": "Use one project per agent role. Tasks assigned to a project (not a specific agent) can be claimed by any agent monitoring that pool. This is the correct pattern when a role may scale to multiple agents.\n\nhzl project create research\nhzl project create writing\nhzl project create coding\nhzl project create marketing\nhzl project create coordination # for cross-agent work\n\nPool routing rule: assign tasks to a project without --agent. Any eligible agent claims with --next.\n\n# Assigning work to the research pool (no --agent)\nhzl task add \"Research competitor pricing\" -P research -s ready\n\n# Kenji (or any researcher) claims it\nhzl task claim --next -P research --agent kenji\n\nAgent routing: when --agent is set at task creation, only that agent (or agents with no assignment) can claim it via --next. Tasks with no agent are available to everyone.\n\n# Pre-route a task to a specific agent\nhzl task add \"Review Clara's PR\" -P coding -s ready --agent kenji\n\n# Kenji claims it (matches agent)\nhzl task claim --next -P coding --agent kenji # ✓ returns it\n\n# Ada tries — skipped because it's assigned to kenji\nhzl task claim --next -P coding --agent ada # ✗ skips it\n\nUse --agent on task creation when you specifically want one person. Omit it when any eligible agent in the pool should pick it up." }, { "title": "With workflow commands (HZL v2+)", "body": "hzl workflow run start --agent --project --json\n\n--project is required — agents must scope to their assigned pool. Use --any-project to intentionally scan all projects (e.g. coordination agents).\n\nThis handles expired-lease recovery and new-task claiming in one command. If a task is returned, work on it. If nothing is returned, the queue is empty. Agent routing applies: tasks assigned to other agents are skipped." }, { "title": "Without workflow commands (fallback)", "body": "hzl agent status # Who's active? What's running?\nhzl task list -P --available # What's ready?\nhzl task stuck # Any expired leases?\nhzl task stuck --stale # Also check for stale tasks (no checkpoints)\n\n# If stuck tasks exist, read their state before claiming\nhzl task show --view standard --json\nhzl task steal --if-expired --agent --lease 30\nhzl task show --view standard --json | jq '.checkpoints[-1]'\n\n# Otherwise claim next available\nhzl task claim --next -P --agent " }, { "title": "Adding work", "body": "hzl task add \"Feature X\" -P openclaw -s ready # Single-agent\nhzl task add \"Research topic Y\" -P research -s ready # Pool-routed (multi-agent)\nhzl task add \"Subtask A\" --parent # Subtask\nhzl task add \"Subtask B\" --parent --depends-on # With dependency" }, { "title": "Working a task", "body": "hzl task claim # Claim specific task\nhzl task claim --next -P # Claim next available\nhzl task checkpoint \"milestone X\" # Checkpoint progress\nhzl task complete # Finish" }, { "title": "Status transitions", "body": "hzl task set-status ready # Make claimable\nhzl task set-status backlog # Move back to planning\nhzl task block --comment \"reason\" # Block with reason\nhzl task unblock # Unblock\n\nStatuses: backlog → ready → in_progress → done (or blocked)" }, { "title": "Finishing subtasks", "body": "hzl task complete \nhzl task show --view summary --json # Any subtasks remaining?\nhzl task complete # Complete parent if all done" }, { "title": "Workflow commands (HZL v2+)", "body": "# Hand off to another agent or pool — complete current, create follow-on atomically\nhzl workflow run handoff \\\n --from \\\n --title \"\" \\\n --project # --agent if specific person; --project for pool\n\n# Delegate a subtask — creates dependency edge by default\nhzl workflow run delegate \\\n --from \\\n --title \"\" \\\n --project \\\n --pause-parent # Block parent until delegated task is done\n\n--agent and --project guardrail: at least one is required on handoff. Omitting --agent creates a pool-routed task; --project is then required to define which pool." }, { "title": "Manual delegation (fallback)", "body": "hzl task add \"\" -P -s ready --depends-on \nhzl task checkpoint \"Delegated X to pool. Waiting on .\"\nhzl task block --comment \"Waiting for \"" }, { "title": "Dependencies", "body": "# Add dependency at creation\nhzl task add \"\" -P <project> --depends-on <other-id>\n\n# Add dependency after creation\nhzl task add-dep <task-id> <depends-on-id>\n\n# Query dependencies\nhzl dep list --agent <id> --blocking-only # What's blocking me?\nhzl dep list --from-agent <id> --blocking-only # What's blocking work I created?\nhzl dep list --project <p> --blocking-only # What's blocking in a pool?\nhzl dep list --cross-project-only # Cross-agent blockers\n\n# Validate no cycles\nhzl validate\n\nCross-project dependencies are supported by default. Use hzl dep list --cross-project-only to inspect cross-project edges." }, { "title": "Checkpointing", "body": "Checkpoint at notable milestones or before pausing. A good checkpoint answers: \"if this session died right now, could another agent resume from here?\"\n\nWhen to checkpoint:\n\nBefore any tool call that might fail\nBefore spawning a sub-agent\nAfter completing a meaningful unit of work\nBefore handing off or pausing\n\nhzl task checkpoint <id> \"Implemented login flow. Next: add token refresh.\" --progress 50\nhzl task checkpoint <id> \"Token refresh done. Testing complete.\" --progress 100\nhzl task progress <id> 75 # Set progress without a checkpoint" }, { "title": "Lifecycle hooks", "body": "HZL sends targeted notifications for high-value transitions — currently only on_done. Other lifecycle events (stuck detection, blocking, progress) require polling. This is deliberate: hooks signal when something meaningful happens, agents and orchestrators poll for everything else.\n\nHooks are configured during installation (see docs-site for setup). As an agent, here's what you need to know operationally:\n\nOnly on_done fires. When you task complete, HZL queues a webhook. For stuck detection, stale detection, blocking changes, or progress — poll with hzl task stuck --stale or hzl task list.\nDelivery is not instant. hzl hook drain runs on a cron schedule (typically every 2–5 minutes). Your completion is recorded immediately, but the notification reaches the gateway on the next drain cycle.\nPayloads include context. Each notification carries agent, project, and full event details. The gateway handles per-agent routing — HZL sends the same payload to one URL regardless of which agent completed the task.\nIf hooks seem broken, check hzl hook drain --json for delivery failures and last_error details." }, { "title": "Multi-agent coordination with leases", "body": "# Claim with lease (prevents orphaned work)\nhzl task claim <id> --agent <agent-id> --lease 30 # 30-minute lease\n\n# Fleet status: who's active, what they're working on, how long\nhzl agent status # All agents\nhzl agent status --agent <name> # Single agent\nhzl agent status --stats # Include task count breakdowns\n\n# Agent activity history\nhzl agent log <agent> # Recent events for an agent\n\n# Monitor for stuck tasks\nhzl task stuck\n\n# Monitor for stuck AND stale tasks (no checkpoints for 10+ min)\nhzl task stuck --stale\nhzl task stuck --stale --stale-threshold 15 # Custom threshold\n\n# Recover an abandoned task (steal + set new lease atomically)\nhzl task show <stuck-id> --view standard --json # Read last checkpoint first\nhzl task steal <stuck-id> --if-expired --agent <agent-id> --lease 30\n\nUse distinct --agent IDs per agent (e.g. henry, clara, kenji) so authorship is traceable." }, { "title": "Sizing tasks and projects", "body": "The completability test: \"I finished [task]\" should describe a real outcome.\n\n✓ \"Finished installing garage motion sensors\"\n✗ \"Finished home automation\" (open-ended domain, never done)\n\nSplit into multiple tasks when: parts deliver independent value or solve distinct problems.\n\nAdding context:\n\nhzl task add \"Install sensors\" -P openclaw \\\n -d \"Mount at 7ft height per spec.\" \\\n -l docs/sensor-spec.md,https://example.com/wiring-guide\n\nDon't duplicate specs into descriptions — reference docs instead to avoid drift." }, { "title": "Extended reference", "body": "# Setup\nhzl init # Initialize (safe, won't overwrite)\nhzl status # Database mode, paths, sync state\nhzl doctor # Health check\n\n# List and find\nhzl task list -P <project> --available # Ready tasks with met dependencies\nhzl task list --parent <id> # Subtasks of a parent\nhzl task list --root # Top-level tasks only\nhzl task list -P <project> --tags <csv> # Filter by tags\n\n# Create with options\nhzl task add \"<title>\" -P <project> --priority 2 --tags backend,auth\nhzl task add \"<title>\" -P <project> -s in_progress --agent <name>\nhzl task add \"<title>\" -P <project> --stale-after 2h\nhzl task update <id> --stale-after 30m\nhzl task update <id> --clear-stale-after\n\n# Agent fleet status\nhzl agent status # Active/idle agents, current tasks, lease state\nhzl agent status --agent <name> # Single agent\nhzl agent status --stats # With task count breakdowns\nhzl agent log <agent> # Activity history for an agent\n\n# Web dashboard\nhzl serve # Start on port 3456\nhzl serve --host 127.0.0.1 # Restrict to localhost\nhzl serve --background # Fork to background\nhzl serve --status / --stop\nhzl serve --gateway-url ws://host:18789 # Connect to OpenClaw gateway\nhzl serve --gateway-token <token> # Gateway auth token\n# Or set gateway once in config.json: { \"gateway\": { \"url\": \"...\", \"token\": \"...\" } }\n\n# Raw reporting surfaces\nhzl events # NDJSON event feed\nhzl events --follow\nhzl events --from 0 > events.jsonl\nhzl stats --window 1h\n\n# Authorship\nhzl task claim <id> --agent alice\nhzl task checkpoint <id> \"note\" --author bob # Records who did the action\nhzl task claim <id> --agent \"Claude\" --agent-id \"session-abc123\"\n\n# Cloud sync (optional)\nhzl init --sync-url libsql://<db>.turso.io --auth-token <token>\nhzl sync" }, { "title": "Web dashboard (always-on, Linux)", "body": "hzl serve --print-systemd > ~/.config/systemd/user/hzl-web.service\nsystemctl --user daemon-reload\nsystemctl --user enable --now hzl-web\nloginctl enable-linger $USER\n\nAvailable at http://<your-box>:3456 (accessible over Tailscale). macOS: use hzl serve --background instead." }, { "title": "What HZL does not do", "body": "No orchestration — does not spawn agents or assign work automatically\nNo task decomposition — does not break down tasks automatically\nNo smart scheduling — uses simple priority + FIFO ordering\n\nThese belong in your orchestration layer, not the task ledger." }, { "title": "Notes", "body": "Run hzl via the exec tool.\nCheck TOOLS.md for your identity string, which projects to monitor, and the commands relevant to your role.\nUse distinct --agent IDs per agent and rely on leases to avoid collisions in shared databases.\nhzl workflow run commands require HZL v2+. If unavailable, use the manual fallback patterns documented above." } ], "body": "HZL: Persistent task ledger for agents\n\nHZL (https://hzl-tasks.com) is a local-first task ledger that agents use to:\n\nPlan multi-step work into projects + tasks\nCheckpoint progress so work survives session boundaries\nRoute work to the right agent via project pools\nCoordinate across multiple agents with leases and dependencies\n\nThis skill teaches an agent how to use the hzl CLI.\n\nWhen to use HZL\n\nOpenClaw has no native task tracking. Unlike Claude Code (which has TodoWrite) or Codex (which has update_plan), OpenClaw relies on memory and markdown files for tracking work. HZL fills this gap.\n\nUse HZL for:\n\nMulti-step projects with real sequencing or handoffs\nWork that may outlive this session or involve multiple agents\nAnything where \"resume exactly where we left off\" matters\nDelegating work to another agent and needing recovery if they fail\n\nSkip HZL for:\n\nTruly trivial one-step tasks you will complete immediately\nTime-based reminders (use OpenClaw Cron instead)\nLongform notes or knowledge capture (use memory files)\n\nRule of thumb: If you feel tempted to make a multi-step plan, or there is any chance you will not finish in this session, use HZL.\n\n⚠️ DESTRUCTIVE COMMANDS — READ FIRST\nCommand\tEffect\nhzl init --force\tDELETES ALL DATA. Prompts for confirmation.\nhzl init --force --yes\tDELETES ALL DATA WITHOUT CONFIRMATION.\nhzl task prune ... --yes\tPERMANENTLY DELETES old done/archived tasks and history.\n\nNever run these unless the user explicitly asks you to delete data. There is no undo.\n\nCore concepts\nProject: container for tasks. In single-agent setups, use one shared project. In multi-agent setups, use one project per agent role (pool routing).\nTask: top-level work item. Use parent tasks for multi-step initiatives.\nSubtask: breakdown of a task (--parent <id>). Max 1 level of nesting. Parent tasks are never returned by hzl task claim --next.\nCheckpoint: short progress snapshot for session recovery.\nLease: time-limited claim that enables stuck detection in multi-agent flows.\nProject setup\nSingle-agent setup\n\nUse one shared project. Requests and initiatives become parent tasks, not new projects.\n\nhzl project list # Check first — only create if missing\nhzl project create openclaw\n\n\nEverything goes into openclaw. hzl task claim --next -P openclaw always works.\n\nMulti-agent setup (pool routing)\n\nUse one project per agent role. Tasks assigned to a project (not a specific agent) can be claimed by any agent monitoring that pool. This is the correct pattern when a role may scale to multiple agents.\n\nhzl project create research\nhzl project create writing\nhzl project create coding\nhzl project create marketing\nhzl project create coordination # for cross-agent work\n\n\nPool routing rule: assign tasks to a project without --agent. Any eligible agent claims with --next.\n\n# Assigning work to the research pool (no --agent)\nhzl task add \"Research competitor pricing\" -P research -s ready\n\n# Kenji (or any researcher) claims it\nhzl task claim --next -P research --agent kenji\n\n\nAgent routing: when --agent is set at task creation, only that agent (or agents with no assignment) can claim it via --next. Tasks with no agent are available to everyone.\n\n# Pre-route a task to a specific agent\nhzl task add \"Review Clara's PR\" -P coding -s ready --agent kenji\n\n# Kenji claims it (matches agent)\nhzl task claim --next -P coding --agent kenji # ✓ returns it\n\n# Ada tries — skipped because it's assigned to kenji\nhzl task claim --next -P coding --agent ada # ✗ skips it\n\n\nUse --agent on task creation when you specifically want one person. Omit it when any eligible agent in the pool should pick it up.\n\nSession start (primary workflow)\nWith workflow commands (HZL v2+)\nhzl workflow run start --agent <agent-id> --project <project> --json\n\n\n--project is required — agents must scope to their assigned pool. Use --any-project to intentionally scan all projects (e.g. coordination agents).\n\nThis handles expired-lease recovery and new-task claiming in one command. If a task is returned, work on it. If nothing is returned, the queue is empty. Agent routing applies: tasks assigned to other agents are skipped.\n\nWithout workflow commands (fallback)\nhzl agent status # Who's active? What's running?\nhzl task list -P <project> --available # What's ready?\nhzl task stuck # Any expired leases?\nhzl task stuck --stale # Also check for stale tasks (no checkpoints)\n\n# If stuck tasks exist, read their state before claiming\nhzl task show <stuck-id> --view standard --json\nhzl task steal <stuck-id> --if-expired --agent <agent-id> --lease 30\nhzl task show <stuck-id> --view standard --json | jq '.checkpoints[-1]'\n\n# Otherwise claim next available\nhzl task claim --next -P <project> --agent <agent-id>\n\nCore workflows\nAdding work\nhzl task add \"Feature X\" -P openclaw -s ready # Single-agent\nhzl task add \"Research topic Y\" -P research -s ready # Pool-routed (multi-agent)\nhzl task add \"Subtask A\" --parent <id> # Subtask\nhzl task add \"Subtask B\" --parent <id> --depends-on <a-id> # With dependency\n\nWorking a task\nhzl task claim <id> # Claim specific task\nhzl task claim --next -P <project> # Claim next available\nhzl task checkpoint <id> \"milestone X\" # Checkpoint progress\nhzl task complete <id> # Finish\n\nStatus transitions\nhzl task set-status <id> ready # Make claimable\nhzl task set-status <id> backlog # Move back to planning\nhzl task block <id> --comment \"reason\" # Block with reason\nhzl task unblock <id> # Unblock\n\n\nStatuses: backlog → ready → in_progress → done (or blocked)\n\nFinishing subtasks\nhzl task complete <subtask-id>\nhzl task show <parent-id> --view summary --json # Any subtasks remaining?\nhzl task complete <parent-id> # Complete parent if all done\n\nDelegating and handing off work\nWorkflow commands (HZL v2+)\n# Hand off to another agent or pool — complete current, create follow-on atomically\nhzl workflow run handoff \\\n --from <task-id> \\\n --title \"<new task title>\" \\\n --project <pool> # --agent if specific person; --project for pool\n\n# Delegate a subtask — creates dependency edge by default\nhzl workflow run delegate \\\n --from <task-id> \\\n --title \"<delegated task>\" \\\n --project <pool> \\\n --pause-parent # Block parent until delegated task is done\n\n\n--agent and --project guardrail: at least one is required on handoff. Omitting --agent creates a pool-routed task; --project is then required to define which pool.\n\nManual delegation (fallback)\nhzl task add \"<delegated title>\" -P <pool> -s ready --depends-on <parent-id>\nhzl task checkpoint <parent-id> \"Delegated X to <pool> pool. Waiting on <task-id>.\"\nhzl task block <parent-id> --comment \"Waiting for <delegated-task-id>\"\n\nDependencies\n# Add dependency at creation\nhzl task add \"<title>\" -P <project> --depends-on <other-id>\n\n# Add dependency after creation\nhzl task add-dep <task-id> <depends-on-id>\n\n# Query dependencies\nhzl dep list --agent <id> --blocking-only # What's blocking me?\nhzl dep list --from-agent <id> --blocking-only # What's blocking work I created?\nhzl dep list --project <p> --blocking-only # What's blocking in a pool?\nhzl dep list --cross-project-only # Cross-agent blockers\n\n# Validate no cycles\nhzl validate\n\n\nCross-project dependencies are supported by default. Use hzl dep list --cross-project-only to inspect cross-project edges.\n\nCheckpointing\n\nCheckpoint at notable milestones or before pausing. A good checkpoint answers: \"if this session died right now, could another agent resume from here?\"\n\nWhen to checkpoint:\n\nBefore any tool call that might fail\nBefore spawning a sub-agent\nAfter completing a meaningful unit of work\nBefore handing off or pausing\nhzl task checkpoint <id> \"Implemented login flow. Next: add token refresh.\" --progress 50\nhzl task checkpoint <id> \"Token refresh done. Testing complete.\" --progress 100\nhzl task progress <id> 75 # Set progress without a checkpoint\n\nLifecycle hooks\n\nHZL sends targeted notifications for high-value transitions — currently only on_done. Other lifecycle events (stuck detection, blocking, progress) require polling. This is deliberate: hooks signal when something meaningful happens, agents and orchestrators poll for everything else.\n\nHooks are configured during installation (see docs-site for setup). As an agent, here's what you need to know operationally:\n\nOnly on_done fires. When you task complete, HZL queues a webhook. For stuck detection, stale detection, blocking changes, or progress — poll with hzl task stuck --stale or hzl task list.\nDelivery is not instant. hzl hook drain runs on a cron schedule (typically every 2–5 minutes). Your completion is recorded immediately, but the notification reaches the gateway on the next drain cycle.\nPayloads include context. Each notification carries agent, project, and full event details. The gateway handles per-agent routing — HZL sends the same payload to one URL regardless of which agent completed the task.\nIf hooks seem broken, check hzl hook drain --json for delivery failures and last_error details.\nMulti-agent coordination with leases\n# Claim with lease (prevents orphaned work)\nhzl task claim <id> --agent <agent-id> --lease 30 # 30-minute lease\n\n# Fleet status: who's active, what they're working on, how long\nhzl agent status # All agents\nhzl agent status --agent <name> # Single agent\nhzl agent status --stats # Include task count breakdowns\n\n# Agent activity history\nhzl agent log <agent> # Recent events for an agent\n\n# Monitor for stuck tasks\nhzl task stuck\n\n# Monitor for stuck AND stale tasks (no checkpoints for 10+ min)\nhzl task stuck --stale\nhzl task stuck --stale --stale-threshold 15 # Custom threshold\n\n# Recover an abandoned task (steal + set new lease atomically)\nhzl task show <stuck-id> --view standard --json # Read last checkpoint first\nhzl task steal <stuck-id> --if-expired --agent <agent-id> --lease 30\n\n\nUse distinct --agent IDs per agent (e.g. henry, clara, kenji) so authorship is traceable.\n\nSizing tasks and projects\n\nThe completability test: \"I finished [task]\" should describe a real outcome.\n\n✓ \"Finished installing garage motion sensors\"\n✗ \"Finished home automation\" (open-ended domain, never done)\n\nSplit into multiple tasks when: parts deliver independent value or solve distinct problems.\n\nAdding context:\n\nhzl task add \"Install sensors\" -P openclaw \\\n -d \"Mount at 7ft height per spec.\" \\\n -l docs/sensor-spec.md,https://example.com/wiring-guide\n\n\nDon't duplicate specs into descriptions — reference docs instead to avoid drift.\n\nExtended reference\n# Setup\nhzl init # Initialize (safe, won't overwrite)\nhzl status # Database mode, paths, sync state\nhzl doctor # Health check\n\n# List and find\nhzl task list -P <project> --available # Ready tasks with met dependencies\nhzl task list --parent <id> # Subtasks of a parent\nhzl task list --root # Top-level tasks only\nhzl task list -P <project> --tags <csv> # Filter by tags\n\n# Create with options\nhzl task add \"<title>\" -P <project> --priority 2 --tags backend,auth\nhzl task add \"<title>\" -P <project> -s in_progress --agent <name>\nhzl task add \"<title>\" -P <project> --stale-after 2h\nhzl task update <id> --stale-after 30m\nhzl task update <id> --clear-stale-after\n\n# Agent fleet status\nhzl agent status # Active/idle agents, current tasks, lease state\nhzl agent status --agent <name> # Single agent\nhzl agent status --stats # With task count breakdowns\nhzl agent log <agent> # Activity history for an agent\n\n# Web dashboard\nhzl serve # Start on port 3456\nhzl serve --host 127.0.0.1 # Restrict to localhost\nhzl serve --background # Fork to background\nhzl serve --status / --stop\nhzl serve --gateway-url ws://host:18789 # Connect to OpenClaw gateway\nhzl serve --gateway-token <token> # Gateway auth token\n# Or set gateway once in config.json: { \"gateway\": { \"url\": \"...\", \"token\": \"...\" } }\n\n# Raw reporting surfaces\nhzl events # NDJSON event feed\nhzl events --follow\nhzl events --from 0 > events.jsonl\nhzl stats --window 1h\n\n# Authorship\nhzl task claim <id> --agent alice\nhzl task checkpoint <id> \"note\" --author bob # Records who did the action\nhzl task claim <id> --agent \"Claude\" --agent-id \"session-abc123\"\n\n# Cloud sync (optional)\nhzl init --sync-url libsql://<db>.turso.io --auth-token <token>\nhzl sync\n\nWeb dashboard (always-on, Linux)\nhzl serve --print-systemd > ~/.config/systemd/user/hzl-web.service\nsystemctl --user daemon-reload\nsystemctl --user enable --now hzl-web\nloginctl enable-linger $USER\n\n\nAvailable at http://<your-box>:3456 (accessible over Tailscale). macOS: use hzl serve --background instead.\n\nWhat HZL does not do\nNo orchestration — does not spawn agents or assign work automatically\nNo task decomposition — does not break down tasks automatically\nNo smart scheduling — uses simple priority + FIFO ordering\n\nThese belong in your orchestration layer, not the task ledger.\n\nNotes\nRun hzl via the exec tool.\nCheck TOOLS.md for your identity string, which projects to monitor, and the commands relevant to your role.\nUse distinct --agent IDs per agent and rely on leases to avoid collisions in shared databases.\nhzl workflow run commands require HZL v2+. If unavailable, use the manual fallback patterns documented above." }, "trust": { "sourceLabel": "tencent", "provenanceUrl": "https://clawhub.ai/tmchow/hzl", "publisherUrl": "https://clawhub.ai/tmchow/hzl", "owner": "tmchow", "version": "3.1.0", "license": null, "verificationStatus": "Indexed source record" }, "links": { "detailUrl": "https://openagent3.xyz/skills/hzl", "downloadUrl": "https://openagent3.xyz/downloads/hzl", "agentUrl": "https://openagent3.xyz/skills/hzl/agent", "manifestUrl": "https://openagent3.xyz/skills/hzl/agent.json", "briefUrl": "https://openagent3.xyz/skills/hzl/agent.md" } }