Tasks

A Task Card is what a user fills in to create a Task. It has two required fields:

The description field carries all the structured inputs the Agent needs. Assembly Line designers document the expected description format for their pipeline. For example, the Vibecheck Assembly Line expects the description to contain a repository URL, branch, and optionally a stack description and areas of concern.

There are no typed input fields in v1. The Agent reads the description and acts on its content.

Optional task fields:

A Task moves through the following states as it flows through an Assembly Line:

[Submit Task Card]
        │
        ▼
     queued          ← waiting for a Runner to claim the Job at the current Station
        │
        ▼
     claimed         ← a Runner has taken the Job and is starting the Operator
        │
        ▼
    in_progress      ← the Operator has started the Agent, work is underway
        │
   ┌────┴────┐
   │         │
   ▼         ▼
success    failure
   │         │
   │         └──────────────────────► failed  (pipeline stops)
   │
   ├── [not last Station] ──────────► queued  (at next Station)
   │
   ├── [last Station] ──────────────► completed
   │
   └── [Transition Rule: gate] ────► awaiting_review
                                          │
                                    ┌─────┴─────┐
                                    │           │
                                  approve     reject
                                    │           │
                                    ▼           ▼
                                 queued       failed
                              (next Station)

The full Task object maintained by the Server:

interface TaskData {
  id: string;
  owner: string;
  projectId: string;
  stageId: string;            // Assembly Line ID
  title: string;
  description?: string;
  columnId: string;           // Current Station ID
  order: number;              // Position within the Station's queue
  priority?: 'low' | 'medium' | 'high';
  labels?: string[];
  pendingGateId?: string;     // Set when task is in awaiting_review state
  assemblyLineRepo?: AssemblyLineRepo;  // Provisioned when createAssemblyLineRepo fires

  // ── Fan-Out / Join (v1.1 — see 12-fan-out-join.md) ──
  parentTask?: string;        // Set on a Child Task: id of the spawning (join) Task.
                              // Reference implementation: `parentTaskId`
  blockedBy?: string[];       // On a fan-out parent: the Child Task ids the join waits on.
                              // Reference implementation: `blockedByTaskIds`
  joinStation?: string;       // On a fan-out parent: Station where children collect and
                              // settle instead of dispatching.
                              // Reference implementation: `joinColumnId`
  settled?: Settled;          // Resting outcome of this Task's work. Cleared on every dispatch.
  childResults?: Record<string, ChildResult>; // On a fan-out parent: aggregated at Join Release,
                              // keyed by Child Task id. Feeds {{children.results}}

  createdAt: number;          // Unix ms
  updatedAt: number;          // Unix ms
}

interface Settled {
  conclusion: 'success' | 'failure';
  at: number;       // Unix ms
  jobId?: string;   // Job that settled the Task (idempotency guard)
  actor?: string;   // e.g. 'runner_job', 'join_arrival', 'manual'
  result?: string;  // Station output captured at settle time
}

interface ChildResult {
  title: string;
  conclusion: string; // 'success' | 'failure' | 'missing' | 'unresolved'
  result: string;     // the child's final Station output summary
}

interface AssemblyLineRepo {
  repoId: string;
  url: string;    // https://server/api/git/owner/project/repoId.git
  branch: string; // main
  createdAt: number;
}

POST /api/owners/{owner}/projects/{project}/stages/{assemblyLineId}/tasks
Authorization: Bearer {token}

{
  "title": "Vibecheck: my-org/backend",
  "description": "Repository: https://github.com/my-org/backend\nBranch: main\nConcerns: auth implementation",
  "columnId": "intake",
  "priority": "high"
}

Response: The created TaskData object.

If the first Station is configured with type: "dispatch_worker", the Server automatically creates a Job and queues it for dispatch after creating the Task.

A Task at Station 3 of 6 shows progress via columnId (the current Station ID). The Server maintains the history of which Stations the Task has already passed through, enabling the UI to display a progress indicator.