stage-11-agentics/lattice

Lattice — Agent-Native Task Tracker

Lattice is a file-based, event-sourced task tracker. It stores everything in a .lattice/ directory in the project root (like .git/ for version control). Every change is an immutable event. No accounts, no API keys, no network required.

When to Use Lattice

Use Lattice when the user or the conversation involves:

• Creating, tracking, or managing tasks
• Coordinating work across multiple agents
• Maintaining an audit trail of decisions and changes
• Planning sprints, releases, or project milestones
• Checking what work is in progress, blocked, or done

Setup

Check if Lattice is available and initialized:

bash {baseDir}/scripts/lattice-check.sh

Or simply run lattice list. If lattice is not found, it needs to be installed (see the install methods in the frontmatter above). If .lattice/ is not found, initialize it:

lattice init --project-code PROJ

Replace PROJ with a short project code (e.g., APP, API, WEB). This creates the .lattice/ directory.

Core Commands

Create a task

lattice create "Fix the login bug" --actor agent:openclaw --priority high

Options: --priority (critical/high/medium/low/none), --type (task/bug/chore), --description "details", --assign agent:openclaw

No epic or spike types — just items of work with a dependency graph. Lattice intentionally rejects umbrella/exploratory ticket types. Multi-phase or umbrella work is expressed by creating a plain task and linking children via lattice link <child> subtask_of <parent>. Exploratory or investigation work is expressed as a plain task whose deliverable is a concrete artifact (plan doc, prototype, decision). The subtask + dependency graph (subtask_of, blocks, depends_on) gives you epic-shape and spike-shape without dedicated types. Every ticket is a chunk of work with a real output, not a bucket or an open question.

List tasks

lattice list                           # All active tasks
lattice list --status in_progress      # Filter by status
lattice list --assigned agent:openclaw # Filter by assignee
lattice list --priority high           # Filter by priority
lattice list --json                    # Structured output

Update task status

lattice status PROJ-1 in_progress --actor agent:openclaw
lattice status PROJ-1 done --actor agent:openclaw

Assign a task

lattice assign PROJ-1 agent:openclaw --actor agent:openclaw

Add a comment

lattice comment PROJ-1 "Found the root cause: race condition in auth middleware" --actor agent:openclaw

Show task details

lattice show PROJ-1              # Summary view
lattice show PROJ-1 --events     # With full event history

Link related tasks

lattice link PROJ-1 blocks PROJ-2 --actor agent:openclaw
lattice link PROJ-3 subtask_of PROJ-1 --actor agent:openclaw

Relationship types: blocks, blocked_by, subtask_of, parent_of, depends_on, depended_on_by, related_to

File-decision links

Record which files embody a task's architectural decisions:

lattice file-link PROJ-1 src/auth/jwt.ts --reason "JWT validation logic" --actor agent:openclaw
lattice file-unlink PROJ-1 src/auth/jwt.ts --actor agent:openclaw

Reverse lookup — show what decisions shaped a file:

lattice explain src/auth/jwt.ts              # exact file
lattice explain src/auth/                    # directory prefix
lattice explain "src/auth/*.ts"              # glob

Link files that embody decisions, not every file touched. Use --reason to annotate why.

Archive completed work

lattice archive PROJ-1 --actor agent:openclaw

Get next task to work on

lattice next --actor agent:openclaw          # Suggest next task
lattice next --actor agent:openclaw --claim  # Suggest and auto-assign

Project health

lattice weather    # Daily digest / weather report
lattice stats      # Project statistics
lattice doctor     # Check data integrity

Status Workflow

backlog → in_planning → planned → in_progress → review → done
                                       ↕
                                    blocked

• backlog — work identified but not started
• in_planning — actively being planned or specced
• planned — plan is ready, waiting to start
• in_progress — actively being worked on
• review — implementation done, under review
• done — complete
• blocked — waiting on an external dependency
• cancelled — abandoned

Transitions are enforced. Use --force --reason "..." to override when needed.

Needs-human flag

needs-human is a flag, not a status — it rides orthogonally on whatever status a task is in. Set it when you need a human decision, approval, or input; the task keeps its current status.

lattice needs-human PROJ-1 "Which OAuth provider should we use?" --actor agent:openclaw
lattice needs-human PROJ-1 --clear --note "Decided: Google" --actor agent:openclaw
lattice list --needs-human          # scannable queue of flagged tasks across all statuses

A reason is required when setting the flag. Use blocked (a status) for generic external dependencies; use the needs-human flag for "waiting on a human specifically." A task can be both at once.

Actor IDs

Every command requires --actor to identify who made the change. Format: prefix:identifier

• agent:openclaw — for your own actions
• agent:openclaw-worker-1 — for multi-agent setups
• human:username — when acting on behalf of a human

Always use agent:openclaw as your actor ID unless the user specifies otherwise.

Task IDs

Tasks have two forms:

• Short ID: PROJ-1, PROJ-42 (use these in conversation)
• Full ULID: task_01HQ... (internal, always accepted)

Short IDs require a project code (set during lattice init).

Structured Output

All commands support --json for machine-readable output:

lattice list --json

Returns {"ok": true, "data": [...]} on success or {"ok": false, "error": {"code": "...", "message": "..."}} on failure.

Notes Files

Every task has a notes file at .lattice/notes/<task_id>.md. Write plans, decisions, and context there for future reference:

cat .lattice/notes/task_01HQ*.md  # Read a task's notes

These are free-form markdown — edit directly.

Multi-Agent Coordination

Lattice handles concurrent writes safely with file locks. Multiple agents can work simultaneously:

1. Each agent uses a unique actor ID (agent:openclaw-1, agent:openclaw-2)
2. Create tasks from the orchestrator, assign to workers
3. Workers update status and add comments as they progress
4. Lock-based concurrency prevents file corruption
5. Event log provides full audit trail of who did what

For detailed multi-agent patterns, read {baseDir}/references/multi-agent-guide.md.

Tips

• Update status before starting work, not after. If you're about to implement something, move it to in_progress first.
• Leave comments explaining what you tried, what you chose, and what you left undone. The next agent has no hallway to find you in.
• Use lattice next to find the highest-priority unblocked task.
• Use lattice needs-human when you need a human decision — it flags the task (leaving its status intact) and creates a clear queue via lattice list --needs-human.