agentop-conventions

name	agentop-conventions
description	Project-specific conventions for AgentOp development covering data model, attention system, decision flows, and architecture patterns. Use when implementing features that touch the core domain model, working with task hierarchies, handling agent sessions, or implementing the attention system. Triggers on agentop, task, outcome, session, attention, decision point, supervised, delegated, sensitive.

AgentOp Project Conventions

Core domain model, attention system, and architectural patterns specific to AgentOp.

When to Use This Skill

• Implementing features touching the core domain
• Working with task hierarchies
• Handling agent sessions and steps
• Implementing the attention system
• Building decision point flows
• Adding new entity types

Core Data Model

Entity Relationships

Task (tree hierarchy via parentId)
  └── Outcome (many per task, represents expected results)
        └── AgentSession (many per outcome, AI execution attempts)
              └── AgentStep (stream of: thinking | action | decision_point)
                    └── DecisionPoint (user approval for sensitive actions)

Type Definitions

// packages/core/src/types.ts

// ============================================
// Enums
// ============================================

export type TaskStatus = 
  | 'pending'      // Not started
  | 'in_progress'  // Being worked on
  | 'completed'    // Successfully done
  | 'blocked';     // Waiting on dependency

export type AttentionType =
  | 'supervised'   // Every action needs approval
  | 'delegated'    // Runs autonomously
  | 'sensitive';   // Only sensitive actions need approval

export type SessionStatus =
  | 'pending'      // Queued to start
  | 'running'      // Currently executing
  | 'completed'    // Finished successfully
  | 'error'        // Failed with error
  | 'cancelled';   // User cancelled

export type StepType =
  | 'thinking'        // LLM reasoning output
  | 'action'          // Tool execution
  | 'decision_point'; // Awaiting user decision

export type DecisionStatus =
  | 'pending'    // Waiting for user
  | 'approved'   // User approved
  | 'denied'     // User denied
  | 'timeout';   // Auto-denied after timeout

// ============================================
// Entities
// ============================================

export interface Task {
  id: string;
  title: string;
  description?: string;
  parentId: string | null;  // null = root task
  status: TaskStatus;
  attentionType: AttentionType;
  orderIndex: number;       // Fractional index for drag reorder
  createdAt: Date;
  updatedAt: Date;
}

export interface Outcome {
  id: string;
  taskId: string;
  title: string;
  description?: string;
  status: TaskStatus;
  createdAt: Date;
  updatedAt: Date;
}

export interface AgentSession {
  id: string;
  outcomeId: string;
  status: SessionStatus;
  attentionType: AttentionType;
  startedAt: Date;
  completedAt?: Date;
  error?: string;
  tokenUsage?: {
    prompt: number;
    completion: number;
    total: number;
  };
}

export interface AgentStep {
  id: string;
  sessionId: string;
  type: StepType;
  status: 'in_progress' | 'completed' | 'error' | DecisionStatus;
  content?: string;         // For thinking steps
  toolCall?: ToolCall;      // For action steps
  result?: ToolResult;      // After tool execution
  createdAt: Date;
}

export interface ToolCall {
  id: string;
  name: string;
  arguments: Record<string, unknown>;
}

export interface ToolResult {
  success: boolean;
  result?: string;
  error?: string;
}

// ============================================
// Event Log (Immutable Audit Trail)
// ============================================

export interface EventLog {
  id: string;
  timestamp: Date;
  eventType: string;
  entityType: 'task' | 'outcome' | 'session' | 'step';
  entityId: string;
  payload: Record<string, unknown>;
  userId?: string;
}

Attention System

Behavior by Type

// packages/core/src/attention.ts

export const attentionBehavior = {
  supervised: {
    // Every tool call requires approval
    requiresApproval: () => true,
    // Show real-time stream
    showStream: true,
    // Default timeout: none (wait indefinitely)
    timeout: null,
  },
  
  delegated: {
    // No approval needed
    requiresApproval: () => false,
    // Background execution
    showStream: false,
    // Auto-complete
    timeout: null,
  },
  
  sensitive: {
    // Only specific tools need approval
    requiresApproval: (toolName: string) => {
      const sensitiveTools = [
        'run_command',
        'delete_file',
        'edit_file',
        'request_approval',
      ];
      return sensitiveTools.includes(toolName);
    },
    // Show stream for visibility
    showStream: true,
    // Timeout sensitive decisions
    timeout: 5 * 60 * 1000, // 5 minutes
  },
} as const;

// Check if action needs approval
export function needsApproval(
  attentionType: AttentionType,
  toolName: string
): boolean {
  return attentionBehavior[attentionType].requiresApproval(toolName);
}

UI Indicators

// src/renderer/components/AttentionBadge.tsx
import { cn } from '@/lib/utils';
import { Eye, Bot, AlertTriangle } from 'lucide-react';
import type { AttentionType } from '@agentop/core';

const config = {
  supervised: {
    icon: Eye,
    label: 'Supervised',
    color: 'text-blue-500 bg-blue-500/10',
  },
  delegated: {
    icon: Bot,
    label: 'Delegated',
    color: 'text-green-500 bg-green-500/10',
  },
  sensitive: {
    icon: AlertTriangle,
    label: 'Sensitive',
    color: 'text-yellow-500 bg-yellow-500/10',
  },
};

export function AttentionBadge({ type }: { type: AttentionType }) {
  const { icon: Icon, label, color } = config[type];
  
  return (
    <span className={cn('inline-flex items-center gap-1 px-2 py-0.5 rounded text-xs', color)}>
      <Icon className="w-3 h-3" />
      {label}
    </span>
  );
}

Task Hierarchy Patterns

Creating Subtasks

// Convention: Subtasks inherit parent's attention type by default
export async function createSubtask(
  parentId: string,
  title: string,
  db: Database
): Promise<Task> {
  const parent = await db.query.tasks.findFirst({
    where: eq(tasks.id, parentId),
  });
  
  if (!parent) throw new Error('Parent task not found');
  
  // Get next order index among siblings
  const siblings = await db.query.tasks.findMany({
    where: eq(tasks.parentId, parentId),
    orderBy: desc(tasks.orderIndex),
    limit: 1,
  });
  
  const nextOrderIndex = siblings.length > 0
    ? siblings[0].orderIndex + 1
    : 0;
  
  const subtask: NewTask = {
    id: nanoid(),
    title,
    parentId,
    status: 'pending',
    attentionType: parent.attentionType, // Inherit from parent
    orderIndex: nextOrderIndex,
    createdAt: new Date(),
    updatedAt: new Date(),
  };
  
  await db.insert(tasks).values(subtask);
  
  // Update closure table
  await updateTaskClosure(db, subtask.id, parentId);
  
  return subtask;
}

Reordering with Fractional Indexing

// Convention: Use fractional indexing for drag-and-drop reorder
export function calculateOrderIndex(
  prevIndex: number | null,
  nextIndex: number | null
): number {
  if (prevIndex === null && nextIndex === null) {
    return 0;
  }
  if (prevIndex === null) {
    return nextIndex! - 1;
  }
  if (nextIndex === null) {
    return prevIndex + 1;
  }
  return (prevIndex + nextIndex) / 2;
}

// Usage in drag handler
async function handleDragEnd(
  taskId: string,
  overTaskId: string,
  position: 'before' | 'after'
) {
  const siblings = await getSiblingTasks(taskId);
  const overIndex = siblings.findIndex(t => t.id === overTaskId);
  
  const prevTask = position === 'before' 
    ? siblings[overIndex - 1] 
    : siblings[overIndex];
  const nextTask = position === 'before'
    ? siblings[overIndex]
    : siblings[overIndex + 1];
  
  const newOrderIndex = calculateOrderIndex(
    prevTask?.orderIndex ?? null,
    nextTask?.orderIndex ?? null
  );
  
  await updateTask(taskId, { orderIndex: newOrderIndex });
}

Session Flow Conventions

Starting a Session

// Convention: Sessions are always started from an Outcome
export async function startSession(
  outcomeId: string,
  systemPrompt: string,
  userMessage: string
): Promise<AgentSession> {
  const outcome = await db.query.outcomes.findFirst({
    where: eq(outcomes.id, outcomeId),
    with: { task: true },
  });
  
  if (!outcome) throw new Error('Outcome not found');
  
  // Session inherits attention type from task
  const session: NewAgentSession = {
    id: nanoid(),
    outcomeId,
    status: 'pending',
    attentionType: outcome.task.attentionType,
    startedAt: new Date(),
  };
  
  await db.insert(agentSessions).values(session);
  
  // Log event
  await logEvent({
    eventType: 'session_started',
    entityType: 'session',
    entityId: session.id,
    payload: { outcomeId, attentionType: session.attentionType },
  });
  
  return session;
}

Handling Decision Points

// Convention: Decision points block session until resolved
export async function handleDecisionPoint(
  stepId: string,
  approved: boolean
): Promise<void> {
  const step = await db.query.agentSteps.findFirst({
    where: eq(agentSteps.id, stepId),
  });
  
  if (!step || step.type !== 'decision_point') {
    throw new Error('Invalid decision point');
  }
  
  if (step.status !== 'pending') {
    throw new Error('Decision already made');
  }
  
  // Update step status
  await db.update(agentSteps)
    .set({
      status: approved ? 'approved' : 'denied',
    })
    .where(eq(agentSteps.id, stepId));
  
  // Log event
  await logEvent({
    eventType: approved ? 'decision_approved' : 'decision_denied',
    entityType: 'step',
    entityId: stepId,
    payload: { toolCall: step.toolCall },
  });
}

File Organization

packages/
  core/                    # Shared types and utilities
    src/
      types.ts            # All type definitions
      attention.ts        # Attention system logic
      validation.ts       # Zod schemas
      index.ts            # Public exports
    
  main/                   # Electron main process
    src/
      database/           # SQLite + Drizzle
      copilot/            # Copilot SDK integration
      ipc/                # IPC handlers
      
  renderer/               # React frontend
    src/
      components/
        ui/              # shadcn/ui components
        tree/            # Task tree view
        canvas/          # Mindmap canvas
        session/         # Agent session UI
      state/              # Jotai atoms
      hooks/              # React hooks

Naming Conventions

Category	Convention	Example
Files	kebab-case	task-tree-node.tsx
Components	PascalCase	TaskTreeNode
Hooks	camelCase with use prefix	useAgentSession
Atoms	camelCase with Atom suffix	tasksMapAtom
AtomFamily	camelCase with AtomFamily suffix	taskAtomFamily
IPC Channels	colon-separated namespace	db:tasks:create
Event Types	snake_case	session_started
Database Tables	snake_case plural	agent_sessions

Error Handling

// Convention: Use custom error classes for domain errors
export class AgentOpError extends Error {
  constructor(
    message: string,
    public code: string,
    public context?: Record<string, unknown>
  ) {
    super(message);
    this.name = 'AgentOpError';
  }
}

export class TaskNotFoundError extends AgentOpError {
  constructor(taskId: string) {
    super(`Task not found: ${taskId}`, 'TASK_NOT_FOUND', { taskId });
  }
}

export class SessionInProgressError extends AgentOpError {
  constructor(sessionId: string) {
    super(
      `Session already in progress: ${sessionId}`,
      'SESSION_IN_PROGRESS',
      { sessionId }
    );
  }
}

// Usage
try {
  await startSession(outcomeId, prompt, message);
} catch (error) {
  if (error instanceof TaskNotFoundError) {
    // Handle missing task
  } else if (error instanceof SessionInProgressError) {
    // Handle concurrent session
  } else {
    throw error;
  }
}

Testing Conventions

// Convention: Use describe blocks matching file structure
describe('agentop/attention', () => {
  describe('needsApproval', () => {
    it('returns true for all tools in supervised mode', () => {
      expect(needsApproval('supervised', 'read_file')).toBe(true);
      expect(needsApproval('supervised', 'run_command')).toBe(true);
    });

    it('returns false for all tools in delegated mode', () => {
      expect(needsApproval('delegated', 'read_file')).toBe(false);
      expect(needsApproval('delegated', 'run_command')).toBe(false);
    });

    it('returns true only for sensitive tools in sensitive mode', () => {
      expect(needsApproval('sensitive', 'read_file')).toBe(false);
      expect(needsApproval('sensitive', 'run_command')).toBe(true);
    });
  });
});

Git Commit Conventions

feat(task): add subtask creation with inherited attention type
fix(session): prevent concurrent sessions for same outcome
refactor(state): migrate from useState to Jotai atoms
docs(readme): add development setup instructions
test(attention): add unit tests for needsApproval
chore(deps): update @github/copilot-sdk to 1.2.0