hzl

# HZL Task Management

HZL is a lightweight task tracking system for AI agents. It is a dumb ledger—it tracks work state but does not orchestrate, prioritize, or decide what to do next.

This skill teaches how to use HZL effectively for tracking work across projects.

## Core Workflow

Run `hzl guide` to get the full workflow documentation. This covers:
- When to use HZL vs skip it
- Project structure (projects, tasks, subtasks)
- Setting up and claiming tasks
- Checkpoints, comments, dependencies
- Troubleshooting common errors

**Quick reference:**
```bash
hzl guide                            # Full workflow documentation
hzl project list                     # Check existing projects
hzl task next -P <project> --claim   # Get and claim next task
hzl task checkpoint <id> "progress"  # Save progress
hzl task complete <id>               # Mark task done
```

---

## Advanced: Sizing Parent Tasks

HZL supports one level of nesting (parent → subtasks). Scope parent tasks to completable outcomes.

**The completability test:** "I finished [parent task]" should describe a real outcome.
- ✓ "Finished the user authentication feature"
- ✗ "Finished the backend work" (frontend still pending)
- ✗ "Finished home automation" (open-ended, never done)

**Scope by problem, not technical layer.** A full-stack feature (frontend + backend + tests) is usually one parent if it ships together.

**Split into multiple parents when:**
- Parts deliver independent value (can ship separately)
- You're solving distinct problems that happen to be related

**Adding context:** Use `-d` for details, `-l` for reference docs:
```bash
hzl task add "User authentication" -P myrepo \
  -d "OAuth2 flow per linked spec. Use existing session middleware." \
  -l docs/auth-spec.md,https://example.com/design-doc
```

**Don't duplicate specs into descriptions**—this creates drift. Reference docs instead.

**If no docs exist**, include enough detail for another agent to complete the task:
```bash
hzl task add "A