DEV Community

Cover image for Build Sprint-Driven AI Projects with vem: Cycles, Tasks, and Flow Metrics
Vangelis
Vangelis

Posted on • Originally published at vem.dev

Build Sprint-Driven AI Projects with vem: Cycles, Tasks, and Flow Metrics

#ai #productivity #cli #tutorial

🚀 vem is in early access — we're looking for our first users. If you try it and find it useful, we'd love to hear from you. Early access is completely free.

Your AI coding agent is smart, but it has no idea what you're working on this week. Every new session starts from scratch — no sprint goal, no priorities, no sense of what's blocked or nearly done. You spend the first five minutes re-explaining context instead of shipping.

vem fixes this with cycles. A cycle is a time-boxed, goal-driven container for tasks — exactly like a sprint. When a cycle is active, every agent that reads project context via vem automatically receives a "Current Sprint" block with the goal, open tasks, and progress percentage.

In this tutorial we'll build a complete sprint workflow from scratch.

Prerequisites — Install vem and Link a Project

Before you can create cycles and run agents you need three things: the vem CLI installed, your account authenticated, and your repository linked to a vem cloud project. The whole setup takes under two minutes.

Sign up for a free account at vem.dev, then grab your API key from the Keys page (vem.dev/keys). The key is the only secret you need — all AI credentials stay on your machine.

# 1. Install the CLI
npm install -g @vemdev/cli

# 2. Authenticate — paste your API key from vem.dev/keys
vem login <your-api-key>

# 3. Initialise vem memory in your repo (creates .vem/)
cd my-project
vem init

# 4. Link this repo to a vem cloud project
#    Run interactively — picks up your GitHub remote automatically
vem link

# 5. Confirm everything is connected
vem status
Enter fullscreen mode Exit fullscreen mode

The Problem: AI Agents Have No Sprint Awareness

Your AI coding agent is smart, but it has no idea what you're working on this week. Every new session starts from scratch — no sprint goal, no priorities, no sense of what's blocked or nearly done. You spend the first five minutes re-explaining context instead of shipping.

vem fixes this with cycles. A cycle is a time-boxed, goal-driven container for tasks — exactly like a sprint. When a cycle is active, every agent that reads project context via vem automatically receives a "Current Sprint" block with the goal, open tasks, and progress percentage. In this tutorial we'll build a complete sprint workflow from scratch.

Step 1 — Create Your First Cycle

Start by creating a cycle with a clear goal. The goal is the single sentence your AI agent will use to prioritise decisions inside this sprint.

# Create a draft cycle with a goal
vem cycle create "Sprint 1: Core Auth" --goal "Implement login, signup and session management"

# Start the sprint (moves it to active)
vem cycle start CYCLE-001

# Set as the active focus for all agents
vem cycle focus CYCLE-001

# Confirm it's live
vem cycle list
Enter fullscreen mode Exit fullscreen mode

Step 2 — Populate the Sprint Backlog

With the cycle active, add tasks directly to it using the --cycle flag. Tasks inside a cycle inherit the sprint's goal and are surfaced to agents as in-scope work.

You can also assign tasks to a cycle from the web dashboard by dragging them from the backlog into the active cycle — useful when you already have a backlog built up.

vem task add "Implement JWT authentication" --cycle CYCLE-001
vem task add "Build signup form with validation" --cycle CYCLE-001
vem task add "Add password reset flow" --cycle CYCLE-001

# See only tasks in this cycle
vem task list --cycle CYCLE-001
Enter fullscreen mode Exit fullscreen mode

Step 3 — The Web Dashboard

Every cycle and its tasks are reflected in real time on the vem web dashboard. The Cycles tab gives you a sprint-level view: goal, progress ring, task breakdown, and agent activity hours spent inside the cycle.

vem web dashboard cycles tab showing active cycle progress
The Cycles tab — progress ring, task count, and agent hours per sprint

Step 4 — Cycle Detail and Task Board

Click into a cycle to see all its tasks, blocked items, and a timeline of agent activity. The board view groups tasks by status so you can see WIP at a glance.

The board also shows high-level metrics: total active tasks, blocked count, high-priority items, and cumulative agent usage (tool calls, turns, and minutes).

vem cycle detail showing tasks and agent activity timeline
Cycle detail view — every task, every agent action, in one place

Step 5 — Give Your Agent Real-Time Sprint Context

When an AI agent connects via the vem MCP server, it calls get_active_tasks() and immediately receives the active cycle, its goal, and all tasks scoped to that sprint. No prompt engineering required.

// Agent calls:
get_active_tasks()

// vem returns:
{
  "cycle": {
    "id": "CYCLE-001",
    "title": "Sprint 1: Core Auth",
    "goal": "Implement login, signup and session management",
    "status": "active",
    "progress": 33
  },
  "tasks": [
    { "id": "TASK-001", "title": "Implement JWT authentication", "status": "active" },
    { "id": "TASK-002", "title": "Build signup form with validation", "status": "pending" },
    { "id": "TASK-003", "title": "Add password reset flow", "status": "pending" }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Add the MCP server to your agent's config:

{
  "mcpServers": {
    "vem": {
      "command": "npx",
      "args": ["-y", "@vemdev/mcp-server"]
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Step 6 — Track Flow Metrics

As tasks move through the cycle, vem tracks throughput, WIP, and cycle time. Run vem task flow to see a live view of your team's delivery rate.

Flow metrics tell you whether you're moving fast or accumulating WIP debt — crucial for keeping AI-assisted sprints from drifting.

# Live flow metrics for the active cycle
vem task flow

# See which tasks are ready to be picked up next
vem task ready
Enter fullscreen mode Exit fullscreen mode

Step 7 — Memory and Project Context

Beyond tasks, vem maintains a persistent memory layer: CONTEXT.md holds high-level project facts, CURRENT_STATE.md captures the latest progress, and decisions/ stores architectural records. Agents read this automatically — so they always know not just what to build, but why.

vem web dashboard memory tab showing context and decisions
The Memory tab — context, decisions, and changelog all in one place

Step 8 — Close the Sprint and Sync

When the sprint is done, close the cycle to capture final state and push everything to the cloud. This creates a verified snapshot that other agents and team members can query.

# Close the sprint (prompts for retrospective note)
vem cycle close CYCLE-001

# Sync local memory to the cloud
vem push

# Check dashboard for verified snapshot
vem status
Enter fullscreen mode Exit fullscreen mode

Implement Tasks Remotely with vem agent & vem runner

Once a cycle is set up you can trigger task implementation without ever leaving the browser. The vem runner is a background worker you start locally (or on a cloud VM) that polls the web dashboard for queued task runs and executes them inside a Docker sandbox using the AI agent of your choice.

Privacy first — Bring Your Own Key (BYOK). Your AI credentials (ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, or GITHUB_TOKEN) are read from your local environment and injected into the sandbox at runtime. They are never sent to vem's cloud — the vem platform only coordinates task routing, not AI execution.

# Set your AI key once (stays on your machine)
export ANTHROPIC_API_KEY=sk-ant-...

# Start the runner — polls the web dashboard every 10s
# Runs tasks in an isolated Docker sandbox by default
vem runner --agent claude --poll-interval 10

# Or run without Docker (no isolation)
vem runner --agent claude --unsafe
Enter fullscreen mode Exit fullscreen mode 
# vem agent wraps any AI CLI with sprint context + task tracking
# Supports: claude, codex, gemini, copilot, gh, cursor, code
vem agent claude --task TASK-001

# Auto-exit when the agent finishes (good for CI pipelines)
vem agent claude --task TASK-001 --auto-exit
Enter fullscreen mode Exit fullscreen mode

Cycle Validation — Catch Regressions Before They Ship

Development never truly stops. New features can break existing behaviour, and fresh security vulnerabilities emerge as code evolves. vem's Cycle Validation tackles this with an AI agent that reviews every task in a cycle against a set of instructions you define.

Each cycle has a Validation panel where you describe what to check — missing error handling, unvalidated user inputs, hardcoded credentials, race conditions, or anything else relevant to your codebase. The agent runs against all tasks in the cycle and surfaces issues grouped by severity.

You choose when to run: manually on demand, on a daily schedule, or weekly — so every sprint close is automatically audited before the next one begins.

# Run vem agent on a specific task to validate it
# Use --auto-exit so the run completes and results are pushed
vem agent claude --task TASK-001 --auto-exit

# Or let vem runner pick up the validation job queued from the web
vem runner --agent claude
Enter fullscreen mode Exit fullscreen mode

The Full Cycle, Closed Loop

Here's the complete workflow: create a goal-driven cycle → populate the backlog → activate → let agents work with full context via vem agent or vem runner → track flow → run cycle validation to catch regressions and security issues → close and sync.

Every step is reflected in the web dashboard and queryable via the MCP server.

# Install
npm install -g @vemdev/cli

# Init in your repo
vem init

# Create your first sprint
vem cycle create "Sprint 1" --goal "Ship the MVP login flow"
vem cycle start CYCLE-001
vem cycle focus CYCLE-001
Enter fullscreen mode Exit fullscreen mode

Start your first cycle today with vem cycle create and see how much less time you spend explaining priorities to your AI assistant.

vem is currently in early access. We're looking for our first users — developers and teams who want to ship AI-assisted projects more intentionally. Early access is completely free. No credit card, no trial timer.

If you found this useful, Sign up for vem early access — It's free! and let us know what you're building. Your feedback will directly shape the product. 🙏

Top comments (0)