Mastering vem Tasks: Create, Prioritize, Implement, and Ship — A Complete Guide

You need the vem CLI installed, an authenticated account, and a repository linked to a vem cloud project. If you completed the Cycles or Memory tutorials you are already set up — jump to the next section.

Everything in vem revolves around tasks. A task is more than a to-do item — it carries the metadata your AI agent needs to implement it correctly: priority, type, time estimate, validation steps, dependencies, and a targeted context block written specifically for the agent.

Tasks move through a clear lifecycle: `todo` → `ready` → `in-progress` → `done` (or `blocked` when something is in the way). At any point an agent can pick up a `ready` task, load its full context, and start working — without any setup instructions from you.

`vem task add` accepts a full set of flags on a single command. You can create a bare-bones task with just a title, or a fully-specified task that gives your AI agent everything it needs before it writes the first line of code.

The `--validation` flag is particularly powerful: it defines the shell commands that must pass before the task can be considered done. When you run `vem cycle validate` at the end of a sprint, vem re-runs these commands and flags any task whose validation steps now fail — catching regressions automatically.

Tasks start in `todo` status. When a task is refined and ready to be picked up — requirements clear, dependencies met — mark it `ready`. This is the queue that agents and the web runner pull from.

`vem task start` sets the start timestamp used for cycle time measurement. `vem task done` marks it complete and records evidence. Use `vem task block` when a task is stuck, and `vem task unblock` when the blocker is resolved. The lifecycle is designed so every state transition is intentional and auditable.

Large tasks can be broken into subtasks using `--parent`. Subtasks inherit the parent's cycle assignment and appear grouped in `vem task subtasks`. This is useful for features that span multiple implementation areas but share a single acceptance criterion.

Dependencies between tasks are tracked with `--depends-on` (soft dependency — informational) and `--blocked-by` (hard block — the blocking task must complete first). These relationships feed into the cycle board and agent context so agents understand sequencing without you having to explain it.

Every task has a dedicated context block — a free-text note written by you (or a previous agent) that the AI agent reads before starting work. This is different from the project-level CONTEXT.md: it is task-specific, pointing the agent at the exact file, function, or edge case that matters for this particular task.

`vem task context <id> --set` replaces the context. `--append` adds to it. `--clear` removes it. When the MCP server sends a task to an agent, the task context is included in the payload alongside the task metadata — so your agent knows exactly where to look without any back-and-forth.

`vem task score` shows all tasks ranked by their impact score (0-100). Scores use a RICE-inspired model: tasks with no score show `—` and appear at the bottom. When you run `vem task score <id> --set <score>`, you can attach reasoning that is stored with the score and shown to agents during prioritization.

Impact scores feed directly into cycle planning — when you create a new cycle, vem can suggest which backlog tasks have the highest combined impact for the planned scope. Teams that maintain scores consistently find that AI agents pick the right task to work on without being told explicitly.

The `--validation` flag on `vem task add` (or `vem task update`) stores a comma-separated list of shell commands that define what "done" means for that task. At the end of each sprint, `vem cycle validate` re-runs all validation steps for completed tasks and flags any that now fail.

This is how vem detects regressions: a feature implemented in sprint 1 may break when sprint 3 refactors the same module. Cycle validation catches it before it ships. The validation steps are also shown to agents during implementation so they know exactly how to verify their work.

`vem task flow` shows the flow metrics for a specific task or a project-wide summary. For a single task: lead time (created → done), cycle time (started → done), and time spent in each status. For the project: throughput, average cycle time, and current work-in-progress count.

These metrics do not require any extra setup — they are calculated automatically from the timestamps recorded by `vem task start` and `vem task done`. Over multiple sprints the data becomes a reliable baseline for estimating how long similar work takes and where tasks tend to get stuck.

`vem agent --task TASK-X` launches your configured AI agent (Copilot, Claude, Gemini, Codex) with the task's full context pre-loaded: task description, per-task context, project CONTEXT.md, active cycle, and related decisions. The agent works in your local repository and can create branches, write code, run tests, and open PRs.

The `--task` flag scopes the agent to a single task. Without it the agent gets the full project context and can decide what to work on. vem wraps the agent session to record which task was worked on, what commands were run, and what was completed — building the audit trail in `vem task sessions`.

Privacy: your AI provider keys (OpenAI, Anthropic, etc.) are stored in your local environment variables and never sent to the vem cloud. vem only orchestrates which task to run — the agent execution happens entirely on your machine.

When an agent opens a PR but the implementation needs refinement, `vem task iterate` picks up where it left off. It finds the latest run with an open PR for the task, checks out that branch, and launches the agent again with follow-up instructions — so the agent continues from the existing code instead of starting from scratch.

This is the difference between re-running an agent (which may diverge or duplicate work) and iterating on a PR (which builds on what already exists). Combined with the task context you can guide the refinement precisely.

The vem web app at app.vem.dev provides a visual view of every task in your project. The Board tab on the Work page shows all tasks with a real-time summary: total count, blocked count, high-priority count, and completed count for the active cycle. It also surfaces agent activity, GitHub integration status, and the GitHub Issue Inbox — making it the single command centre for your project.

Clicking a task opens the full task detail page with everything in one place: the task UUID, status and priority badges, a verification badge when the snapshot is synced with Git, the task context summary for agents, a Discussion thread for team collaboration, and the **Run with agent** panel on the right. The agent panel lets you choose between running locally or in the cloud, select the agent (Copilot, Claude, etc.), pick the branch, and add extra instructions — then hit Start run to dispatch the agent. The Agent sessions section below shows every previous agent run against that task, giving you a complete audit trail.

`vem task sessions <id>` lists all agent sessions that touched a task: which agent ran, when it started and ended, what commands were executed, and whether the task was completed during that session. This gives you a full audit trail for every unit of work.

The audit trail is valuable for understanding agent behaviour over time — which tasks took multiple iterations, which agents were most efficient, and where agents got stuck. It also provides accountability for team environments where multiple people (and agents) are working in parallel.

A well-maintained task is more than a to-do item — it is a self-contained work package that any agent can pick up and execute correctly without additional instructions. The lifecycle from creation to shipped PR looks like this: