# Lattice > Lattice agent coordination guide — mental model, CLI commands, lifecycle discipline, and reference for file-based task tracking across agents and sessions. Use when this capability is needed. - Skill: `tomevault-io/lattice-2` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/lattice-2` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/lattice-2/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/lattice-2 --- # Lattice — Agent-Native Task Tracker Lattice is a file-based, event-sourced task tracker. Everything lives in `.lattice/` in the project root. Every change is an immutable event. No accounts, no API keys, no network required. ## The Lifecycle — Opening and Closing Rituals Every unit of work follows this arc: **claim → understand → work → complete**. The opening and closing rituals are non-negotiable. ### Opening Ritual ```bash # 1. Claim the next task (or create one) lattice next --actor agent:claude-cli --claim --json # 2. If the task needs planning (empty plan file), plan first lattice status in_planning --actor agent:claude-cli # ... write the plan to .lattice/plans/.md ... lattice status planned --actor agent:claude-cli lattice status in_progress --actor agent:claude-cli ``` `lattice next --claim` atomically assigns the highest-priority ready task to you and moves it to `in_progress`. If you already have a task in progress, it returns that one (resume-first logic). If there's no existing task, create one: ```bash lattice create "Fix the login bug" --actor agent:claude-cli --priority high ``` ### Closing Ritual **`lattice complete` is THE way to finish work.** It performs the full completion ceremony in one command: posts a review comment, attaches a review artifact, transitions through review to done. ```bash lattice complete --review "What was done. Key decisions. Test results. What remains." --actor agent:claude-cli ``` The `--review` text is your breadcrumb for every future agent and human who reads this task. Be specific: files changed, approach taken, edge cases considered, anything left undone. **Do not use raw `lattice status ... done` to finish work.** The `complete` command exists because completion requires evidence — a review comment and artifact. Skipping this ceremony leaves the task without an audit trail. | Outcome | Action | |---------|--------| | **Done** | `lattice complete --review "..." --actor agent:claude-cli` | | **Need human input** | `lattice needs-human "" --actor agent:claude-cli` (the task keeps its status — the flag is orthogonal) | | **Blocked on dependency** | `lattice status blocked --actor agent:claude-cli` + comment explaining the blocker | ## The Work In Between Between opening and closing: 1. **Read before writing.** `lattice show --json`. Check `.lattice/plans/.md` and `.lattice/notes/.md` for context from previous minds. 2. **Check previous work.** If the task has prior events, investigate what happened. `git log --oneline --grep=""` for prior commits. 3. **Baseline tests.** Run the test suite before changing anything. You own new failures, not pre-existing ones. 4. **Commit as you go.** Each meaningful unit of progress gets a commit. 5. **Push when done.** Each task is durable on the remote immediately. ## Core Commands ```bash # Create lattice create "Title" --actor agent:claude-cli --priority high --type bug # List lattice list # All active tasks lattice list --status in_progress # Filter by status lattice list --assigned agent:claude-cli # Show lattice show PROJ-1 # Summary lattice show PROJ-1 --events # Full event history # Status transitions lattice status PROJ-1 in_progress --actor agent:claude-cli # Complete (the closing ritual) lattice complete PROJ-1 --review "Review text" --actor agent:claude-cli # Assign lattice assign PROJ-1 agent:claude-cli --actor agent:claude-cli # Comment lattice comment PROJ-1 "Found root cause" --actor agent:claude-cli # Link lattice link PROJ-1 blocks PROJ-2 --actor agent:claude-cli # Flag for human attention (orthogonal to status — task keeps its current status) lattice needs-human PROJ-1 "Which OAuth provider?" --actor agent:claude-cli lattice needs-human PROJ-1 --clear --note "Decided: use Google" --actor agent:claude-cli lattice list --needs-human # scannable queue of flagged tasks, any status # Next task lattice next --actor agent:claude-cli --claim --json # File-decision links lattice file-link PROJ-1 src/auth/jwt.ts --reason "JWT validation" --actor agent:claude-cli lattice file-unlink PROJ-1 src/auth/jwt.ts --actor agent:claude-cli lattice explain src/auth/jwt.ts # what decisions shaped this file? lattice explain src/auth/ # directory prefix lattice explain "src/auth/*.ts" # glob # Health lattice weather # Daily digest lattice stats # Statistics lattice doctor # Data integrity check # Archive lattice archive PROJ-1 --actor agent:claude-cli ``` Options for `create`: `--priority` (critical/high/medium/low/none), `--type` (task/bug/chore), `--description "..."`, `--assign agent:claude-cli` **No `epic` or `spike` types — just items of work with a dependency graph.** Lattice intentionally rejects umbrella/exploratory ticket types. Express multi-phase or umbrella work as a plain `task` with `subtask_of` links from its children. Express exploratory/investigation work 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 a question. **Task description depth:** Match description detail to task ambiguity. Bug fixes and chores can be one-liners ("Add regex validation to frequency names"). Features and integration tasks should include: (1) what it does, (2) acceptance criteria, (3) architectural context, (4) what the user/operator experiences when done. Relationship types for `link`: `blocks`, `blocked_by`, `subtask_of`, `parent_of`, `depends_on`, `depended_on_by`, `related_to` ## Status Workflow ``` backlog → in_planning → planned → in_progress → review → in_validation → pr_open → done ↕ blocked ``` Transitions are enforced. Use `--force --reason "..."` to override when genuinely needed. **`needs-human` is a flag, not a status.** It rides orthogonally on top of whatever status a task is in — a task can be `in_progress` and flagged, `blocked` and flagged, even `done` and flagged. Set it with `lattice needs-human ""` (reason required) and clear it with `lattice needs-human --clear`. The flag never moves the task. `blocked` stays a status for generic external dependencies; `needs-human` means "waiting on a human specifically," and the two can coexist. **`in_validation` is the e2e gate.** After local review passes, prove the change works against a running system — browser automation for web, simulator MCP for mobile, curl flows for APIs. Exercise the actual flow the ticket touched, then record evidence with `lattice attach --role validation` (or `lattice comment --role validation`). Transitioning to `pr_open` is blocked until validation evidence is recorded; if e2e genuinely doesn't apply, record a one-line N/A justification instead — explicit, never silent. Validation failure routes back to `in_progress` (impl-level) or `in_planning` (plan-level), and counts toward the 3-cycle rework valve. The bar: **"I saw it work," not "I think it should work."** ## Actor IDs Every command requires `--actor`. Format: `prefix:identifier` - `agent:claude-cli` — default for your own actions - `agent:worker-1`, `agent:worker-2` — multi-agent setups - `human:username` — when acting on behalf of a human ## Task IDs - **Short ID:** `PROJ-1`, `PROJ-42` (use these in conversation) - **Full ULID:** `task_01HQ...` (internal, always accepted) All commands support `--json` for structured output: `{"ok": true, "data": ...}` or `{"ok": false, "error": {"code": "...", "message": "..."}}`. ## Heartbeat Mode Check if enabled: look for `"heartbeat": {"enabled": true}` in `.lattice/config.json`. When enabled, keep advancing after each task: complete the current task → `lattice next --claim` → work the next one → repeat. Stop after `max_advances` (default 10), when the backlog is empty, or when a task is flagged `needs-human` or hits `blocked`. ## Rules 1. **Open before you work.** Every unit of work starts with a Lattice task. Not after. Not during. Before. 2. **Close with `lattice complete`.** Never raw `lattice status ... done`. 3. **One task at a time.** Finish or transition before claiming the next. 4. **Don't force transitions.** If a transition fails, investigate why. 5. **Don't cancel human tasks.** Flag them with `lattice needs-human` instead — let the human decide. 6. **Comment liberally.** The next agent has no hallway to find you in. ## References Detailed guides live in `{baseDir}/references/`: - **[Multi-Agent Guide](references/multi-agent-guide.md)** — orchestrator/worker patterns, actor ID conventions, concurrency safety - **[Worktree Guide](references/worktree-guide.md)** — git worktree protocol for parallel development with shared Lattice state --- > Source: [Stage-11-Agentics/lattice](https://github.com/Stage-11-Agentics/lattice) — distributed by [TomeVault](https://tomevault.io).