Reference

File Storage & Data Structures

Complete reference for Jetpack data formats and file structures.

Directory Structure

your-project/
├── .jetpack/
│   ├── jetpack.db              # DataLayer SQLite database (local mode)
│   └── config.json           # Project configuration
├── .beads/                    # Task graph and execution log
│   └── plans/                # Loaded plan files
├── .cass/
│   └── memory.db             # Vector-enabled memory database
├── .turso/                    # Embedded replica and sync metadata (Turso mode)
│   └── local.db              # Local embedded replica
└── src/                       # Your actual code

Plan Structure

Plans loaded via jetpack load plan.md and stored in the DataLayer:

{
  "id": "plan-1736712000000",
  "title": "Build Authentication",
  "description": "Implement JWT-based auth flow",
  "status": "draft",
  "createdAt": "2024-01-13T00:00:00.000Z",
  "items": [
    {
      "id": "item-1",
      "title": "Create user model",
      "description": "Define user schema with email, password hash",
      "status": "pending",
      "priority": "high",
      "skills": ["typescript", "database"],
      "dependencies": [],
      "estimatedMinutes": 15
    },
    {
      "id": "item-2",
      "title": "Implement JWT service",
      "description": "Token generation and verification",
      "status": "pending",
      "priority": "high",
      "skills": ["typescript", "backend"],
      "dependencies": ["item-1"],
      "estimatedMinutes": 30
    }
  ]
}

Plan Statuses: draft | approved | executing | completed | failed

Task Structure

Tasks stored in the DataLayer tasks table:

{
  "id": "bd-a1b2c3d4",
  "title": "Implement login endpoint",
  "description": "POST /api/auth/login with email/password",
  "status": "pending",
  "priority": "high",
  "requiredSkills": ["typescript", "backend"],
  "dependencies": [],
  "estimatedMinutes": 30,
  "createdAt": "2024-01-13T00:00:00.000Z"
}

Task Statuses: pending | ready | claimed | in_progress | blocked | completed | failed

Key Types (packages/shared)

// Task
interface Task {
  id: string;                    // "bd-XXXX"
  title: string;
  description?: string;
  status: TaskStatus;
  priority: Priority;
  requiredSkills: AgentSkill[];
  dependencies: string[];
  estimatedMinutes?: number;
  createdAt: Date;
  claimedBy?: string;
  completedAt?: Date;
}

// Agent
interface Agent {
  id: string;
  name: string;
  status: 'idle' | 'busy' | 'error' | 'offline';
  skills: AgentSkill[];
  currentTask?: string;
  tasksCompleted: number;
  lastHeartbeat: Date;
}

// Message
interface Message {
  id: string;
  type: MessageType;
  from: string;
  to?: string;
  payload: any;
  timestamp: Date;
  correlationId?: string;
}

// MemoryEntry
interface MemoryEntry {
  id: string;
  type: MemoryType;
  content: string;
  importance: number;        // 0-1
  embedding?: number[];
  metadata?: Record<string, any>;
  accessCount: number;
  createdAt: Date;
  lastAccessed: Date;
}