hzl-cli 1.25.1 → 1.25.3

package/README.md

@@ -363,16 +363,20 @@ If your coding agent supports an instruction file (for example `CLAUDE.md`, `AGE
 
 ### Drop-in policy snippet
 
-<!-- START [code:md] snippets/HZL-GUIDE.md -->
-<!-- ⚠️ DO NOT EDIT - Auto-generated from snippets/HZL-GUIDE.md -->
+<!-- START [code:md] snippets/AGENT-POLICY.md -->
+<!-- ⚠️ DO NOT EDIT - Auto-generated from snippets/AGENT-POLICY.md -->
 ````md
-### HZL task ledger (external task tracking)
+### HZL task ledger
 
-HZL is an external task database. Use it when external tracking helps clarity, handoff, or auditability.
+This project uses HZL for external task tracking.
+
+**IMPORTANT - Task tracking:** When starting work that is multi-step, may span sessions, or needs coordination, run `hzl guide` to learn how this project tracks tasks.
+
+**When delegating to sub-agents:** Include "use HZL for task tracking" in the sub-agent's instructions.
 
 **Use HZL when:**
 - Work has multiple steps or may not finish this session
-- You want durable record of progress or ownership
+- Durable record of progress or ownership needed
 - Handoff or review expected
 - Task is non-trivial (~30+ min or risky changes)
 
@@ -381,89 +385,8 @@ HZL is an external task database. Use it when external tracking helps clarity, h
 - Quick one-off answer or tiny change
 
 **Rule of thumb:** If you're tempted to make a multi-step plan, use HZL.
-
-**Structure:**
-- **Project** = repo name. One per repo. Always `hzl project list` first.
-- **Task** = feature or work item.
-- **Subtask** = breakdown (`--parent <id>`). Max 1 level.
-
-**Anti-pattern: project sprawl**
-```bash
-hzl project create "query-perf"  # Wrong: feature is not a project
-```
-Features are parent tasks:
-```bash
-hzl task add "Query perf" -P myrepo           # Parent task
-hzl task add "Fix N+1" --parent <parent-id>   # Subtask
-```
-
----
-
-**Setup:**
-```bash
-hzl project list                    # Always check first
-hzl project create <repo-name>      # Only if needed
-```
-
-**Adding work:**
-```bash
-hzl task add "Feature X" -P myrepo -s ready           # Ready to claim
-hzl task add "Subtask A" --parent <id>                # Subtask
-hzl task add "Subtask B" --parent <id> --depends-on <subtask-a-id>  # With dependency
-```
-
-**Task context:** Use `-d` for details, `-l` for reference docs:
-```bash
-hzl task add "Add rate limiting" -P myrepo -s ready \
-  -d "Per linked spec. Use RateLimiter from src/middleware/." \
-  -l docs/rate-limit-spec.md
-```
-If docs exist, reference them (don't duplicate—avoids drift). If no docs, include enough detail to complete the task. Description supports markdown/multiline.
-
-**Working on a task:**
-```bash
-hzl task next -P myrepo                  # Next available task
-hzl task next --parent <id>              # Next subtask of parent
-hzl task next -P myrepo --claim          # Find and claim in one step
-hzl task claim <id>                      # Claim specific task
-hzl task checkpoint <id> "milestone X"   # Notable progress or before pausing
-```
-
-**Changing status:**
-```bash
-hzl task set-status <id> ready           # Make claimable (from backlog)
-hzl task set-status <id> backlog         # Move back to planning
-```
-Statuses: `backlog` → `ready` → `in_progress` → `done` (or `blocked`)
-
-**When blocked:**
-```bash
-hzl task block <id> --comment "Waiting for API keys from DevOps"
-hzl task unblock <id>                    # When resolved
-```
-
-**Finishing work:**
-```bash
-hzl task comment <id> "Implemented X, tested Y"  # Optional: final notes
-hzl task complete <id>
-
-# After completing a subtask, check parent:
-hzl task show <parent-id> --json         # Any subtasks left?
-hzl task complete <parent-id>            # If all done, complete parent
-```
-
-**Troubleshooting:**
-| Error | Fix |
-|-------|-----|
-| "not claimable (status: backlog)" | `hzl task set-status <id> ready` |
-| "Cannot complete: status is X" | Claim first: `hzl task claim <id>` |
-
----
-
-**DESTRUCTIVE - Never run without explicit user request:**
-- `hzl task prune` — **PERMANENTLY DELETES** old done/archived tasks. No undo.
 ````
-<!-- END [code:md] snippets/HZL-GUIDE.md -->
+<!-- END [code:md] snippets/AGENT-POLICY.md -->
 
 That snippet is intentionally concise. The goal is clear triggers and structure, not ceremony.
 
@@ -523,7 +446,7 @@ Copy/paste this into an OpenClaw chat (single prompt):
 <!-- START [code:txt] snippets/OPENCLAW-SETUP-PROMPT.md -->
 <!-- ⚠️ DO NOT EDIT - Auto-generated from snippets/OPENCLAW-SETUP-PROMPT.md -->
 ````txt
-Install HZL from https://github.com/tmchow/hzl and run hzl init. Install the HZL skill from https://www.clawhub.ai/tmchow/hzl. Then append the HZL policy from https://raw.githubusercontent.com/tmchow/hzl/main/docs/openclaw/tools-prompt.md to my TOOLS.md.
+Install HZL from https://github.com/tmchow/hzl and run hzl init. Install the HZL skill from https://www.clawhub.ai/tmchow/hzl. Then append the HZL policy from https://raw.githubusercontent.com/tmchow/hzl/main/openclaw/OPENCLAW-TOOLS-PROMPT.md to my TOOLS.md.
 ````
 <!-- END [code:txt] snippets/OPENCLAW-SETUP-PROMPT.md -->
 
@@ -537,15 +460,15 @@ hzl init
 ```
 
 2) Install the HZL skill from https://www.clawhub.ai/tmchow/hzl  
-   Skill source (for reference only): **[`docs/openclaw/skill-hzl.md`](./docs/openclaw/skill-hzl.md)**
+   Skill source (for reference only): **[`openclaw/skills/hzl/SKILL.md`](./openclaw/skills/hzl/SKILL.md)**
 
 3) Teach OpenClaw when to use HZL (important):
-   - Copy/paste from: **[`docs/openclaw/tools-prompt.md`](./docs/openclaw/tools-prompt.md)**
+   - Copy/paste from: **[`openclaw/OPENCLAW-TOOLS-PROMPT.md`](./openclaw/OPENCLAW-TOOLS-PROMPT.md)**
    - Or tell OpenClaw to add this policy to `TOOLS.md`:
 
 ```
 HZL is a tool available to you for task management in certain cases. I want you to add this information to your TOOLS.md in the right way so you remember how to use it:
-https://raw.githubusercontent.com/tmchow/hzl/main/docs/openclaw/tools-prompt.md
+https://raw.githubusercontent.com/tmchow/hzl/main/openclaw/OPENCLAW-TOOLS-PROMPT.md
 ```
 
 ### Upgrading HZL

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hzl-cli",
-  "version": "1.25.1",
+  "version": "1.25.3",
   "description": "CLI for HZL - External task ledger for coding agents and OpenClaw.",
   "type": "module",
   "bin": {
@@ -60,8 +60,8 @@
     "libsql": "^0.5.0",
     "commander": "^14.0.0",
     "zod": "^3.23.8",
-    "hzl-core": "1.25.1",
-    "hzl-web": "1.25.1"
+    "hzl-core": "1.25.3",
+    "hzl-web": "1.25.3"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",