Core Components

Task Queue

Hierarchical task queue with dependency tracking stored in the DataLayer. Only leaf tasks (no children) are claimable. TaskGraph provides critical path, fan-out, and depth analysis for smart prioritization.

Task States

pending → ready → claimed → in_progress → completed
                                        ↘ failed
                                        ↘ pending_retry
                                        ↘ blocked (dependencies not met)

Task Hierarchy:
Plan (bd-0001)
├── Epic (bd-0001.1)          [organizational, NOT claimable]
│   ├── Task (bd-0001.1.1)    [claimable leaf]
│   └── Task (bd-0001.1.2)    [claimable leaf]
└── Epic (bd-0001.2)
    └── Task (bd-0001.2.1)    [claimable leaf]

Task Structure

{
  "id": "bd-a1b2c3d4",
  "parentId": null,
  "planId": "plan-001",
  "title": "Implement authentication",
  "description": "Add JWT-based auth system",
  "status": "in_progress",
  "priority": "high",
  "itemType": "task",
  "depth": 2,
  "claimable": true,
  "requiredSkills": ["typescript", "backend"],
  "dependencies": [],
  "estimatedMinutes": 45,
  "assignedAgent": "agent-1",
  "createdAt": "2024-01-13T00:00:00Z"
}

API Usage

import { createLibSQLLocalDataLayer } from '@jetpack-agent/data';

const dataLayer = await createLibSQLLocalDataLayer('.jetpack/jetpack.db');

// Create a task
const task = await dataLayer.tasks.create({
  title: 'Implement login',
  description: 'Add JWT-based authentication',
  priority: 'high',
  requiredSkills: ['typescript', 'backend'],
  dependencies: [],  // IDs of tasks that must complete first
});

// Get tasks ready for execution (dependencies satisfied, leaf-only)
const readyTasks = await dataLayer.tasks.list({ status: 'ready' });

// Atomically claim a task (prevents race conditions)
const claimed = await dataLayer.tasks.claim(taskId, agentId);

// Update task status
await dataLayer.tasks.update(taskId, {
  status: 'completed',
});

// Build task dependency graph for analysis
import { TaskGraph } from '@jetpack-agent/coordinator';
const allTasks = await dataLayer.tasks.list();
const graph = new TaskGraph(allTasks);

Creating Tasks via Plan Loader

Load a markdown plan file with automatic hierarchy inference:

# Build Authentication System      ← Epic (not claimable)
## Login Feature                   ← Task group
- Create login endpoint            ← Leaf task (claimable)
- Add JWT token validation         ← Leaf task (claimable)
- Build login UI                   ← Leaf task (claimable)
## Registration Feature
- Create signup endpoint
- Add email verification
# Load with preview
jetpack load plan.md --dry-run

# Load and create tasks
jetpack load plan.md --name "Auth System"

Headers become hierarchy: # = epic, ## = task group, - = leaf task.

Task Dependencies

// Create tasks with dependencies via DataLayer
const task1 = await dataLayer.tasks.create({
  title: 'Set up database',
  priority: 'high',
  requiredSkills: ['database'],
});

const task2 = await dataLayer.tasks.create({
  title: 'Create API',
  priority: 'high',
  requiredSkills: ['backend'],
  dependencies: [task1.id],  // Won't start until task1 completes
});