> ## Documentation Index
> Fetch the complete documentation index at: https://docs.telltandem.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Workflow Guide

> How AI agents should use Tandem — the core loop, task conventions, linking, plans, and chains.

Once installed, your AI agent can track work in Tandem automatically. This page documents the recommended workflow for agents.

## The Core Loop

**Before starting work** — create a task:

```
create_task(title, project, category, priority, notes)
```

**After completing work** — close it:

```
complete_task(id)
```

That's it. Everything else is optional enrichment.

## Creating Tasks

Set project and category in a single call — no separate steps needed:

```
create_task(
  title: "Add rate limiting to auth API",
  project: "My Project",
  category: "Backend",
  priority: "must-do",
  notes: "Use sliding window counter in Redis. Must handle 429 gracefully on the client side."
)
```

**Always include `notes` for anything non-trivial.** Notes carry the context that the title can't — constraints, acceptance criteria, links to relevant specs. A task without notes is a stub; a task with notes is actionable.

### Categories

`Frontend` · `Backend` · `Database` · `CLI` · `DevOps` · `Design` · `AI` · `Bug` · `Marketing` · `Business`

### Priority

| Value | When to use |
| - | - |
| `must-do` | Blockers, critical bugs, things that break user-facing flows |
| `good-to-do` | Features, improvements, most things |
| `optional` | Nice-to-haves, cleanup, speculative work |

### Task granularity

Create a task for each meaningful feature, fix, or investigation — anything that maps to a commit or PR, or takes more than \~15 minutes. Don't create a task per function or file edit.

## Linking Tasks

Use `link_tasks` when tasks have genuine dependencies:

| Link type | When to use |
| - | - |
| `blocks` | `from_task` must be done before `to_task` can start |
| `before` | `from_task` should happen first but doesn't strictly block |
| `relates_to` | Related context, no ordering constraint |

```
link_tasks(from_task_id, to_task_id, link_type)
```

## Chains

A **chain** is a cluster of tasks connected by dependency links. Tandem computes chains automatically from `link_tasks` edges — there is no separate "create chain" step. Once two or more tasks are linked, they form a chain and Tandem names it with AI.

```
create_task(...) → id_a
create_task(...) → id_b
create_task(...) → id_c
link_tasks(id_a, id_b, "blocks")
link_tasks(id_b, id_c, "before")
```

After these calls, all three tasks form one named chain. The chain graph is visible at [telltandem.com/chains](https://telltandem.com/chains).

For multi-task sessions, create all tasks first (with notes), then link them.

## Plans for Complex Work

For any multi-step feature or investigation you've thought through, push a plan to Tandem. When a plan is linked to a task, Tandem auto-generates a summary and subtasks from the plan content.

```
1. create_plan(title, content)              → plan_id
2. create_task(title, project, ...)         → task_id
3. update_task(task_id, plan_id: plan_id)   → links plan, triggers AI population
```

After step 3, Tandem populates the task with a concise summary in `notes` and a set of subtasks derived from the plan's steps.

Push a plan when you've written a design doc, spec, or investigation summary with multiple steps. For trivial tasks where the full context fits in `notes`, skip the plan.

## Understanding the User's Day

Before proposing or starting a batch of work, call `get_smart_today` to see the user's AI-generated priorities. This tells you what they consider important and what's overdue — useful context before suggesting new tasks.

## Projects

`list_projects` returns all active projects with their IDs. You rarely need to call this — just pass the project name to `create_task` or `update_task` and Tandem resolves or creates it automatically.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.