hzl-cli 1.25.0 → 1.25.2

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] docs/snippets/agent-policy.md -->
-<!-- ⚠️ DO NOT EDIT - Auto-generated from docs/snippets/agent-policy.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] docs/snippets/agent-policy.md -->
+<!-- END [code:md] snippets/AGENT-POLICY.md -->
 
 That snippet is intentionally concise. The goal is clear triggers and structure, not ceremony.
 
@@ -520,12 +443,12 @@ HZL fits well as the task ledger that OpenClaw (and its sub-agents) can share.
 
 Copy/paste this into an OpenClaw chat (single prompt):
 
-<!-- START [code:txt] docs/snippets/openclaw-setup-prompt.md -->
-<!-- ⚠️ DO NOT EDIT - Auto-generated from docs/snippets/openclaw-setup-prompt.md -->
+<!-- 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.
 ````
-<!-- END [code:txt] docs/snippets/openclaw-setup-prompt.md -->
+<!-- END [code:txt] snippets/OPENCLAW-SETUP-PROMPT.md -->
 
 ### Manual setup
 
@@ -552,8 +475,8 @@ https://raw.githubusercontent.com/tmchow/hzl/main/docs/openclaw/tools-prompt.md
 
 To keep both the HZL CLI and your OpenClaw skill up to date, copy/paste this prompt into an OpenClaw chat. It creates a script you can reuse:
 
-<!-- START [code:txt] docs/snippets/upgrade-hzl-prompt.md -->
-<!-- ⚠️ DO NOT EDIT - Auto-generated from docs/snippets/upgrade-hzl-prompt.md -->
+<!-- START [code:txt] snippets/UPGRADE-HZL-PROMPT.md -->
+<!-- ⚠️ DO NOT EDIT - Auto-generated from snippets/UPGRADE-HZL-PROMPT.md -->
 ````txt
 Create a script at scripts/upgrade-hzl.sh (in your workspace) that upgrades both the hzl-cli npm package and the hzl skill from ClawHub. The script should:
 
@@ -563,7 +486,7 @@ Create a script at scripts/upgrade-hzl.sh (in your workspace) that upgrades both
 
 Make it executable. In the future when I say "upgrade hzl", run this script.
 ````
-<!-- END [code:txt] docs/snippets/upgrade-hzl-prompt.md -->
+<!-- END [code:txt] snippets/UPGRADE-HZL-PROMPT.md -->
 
 After running this once, just say "upgrade hzl" to OpenClaw to run the script. Consider adding a cron job to have OpenClaw run the upgrade automatically on a schedule.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hzl-cli",
-  "version": "1.25.0",
+  "version": "1.25.2",
   "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.0",
-    "hzl-web": "1.25.0"
+    "hzl-core": "1.25.2",
+    "hzl-web": "1.25.2"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",