AGENT TASK SYSTEM

Comprehensive guidelines for AI-assisted development within the Editor platform

🤖 AI Agent Task System - Activation Guide

CRITICAL: This Document MUST Be Read by AI Assistants

Purpose: This document instructs AI assistants (Claude, Cursor AI, etc.) on how to use GoGrab's AI Agent Task System to create a self-learning, continuously improving AI development experience.

📋 Table of Contents

System Overview
For AI Assistants: How to Use This System
Integration Points
Decision Logging Protocol
Self-Learning Loop
API Reference

System Overview

GoGrab Space has a sophisticated AI Agent Task System that tracks:

Tasks: High-level goals broken into steps
Sessions: Individual work periods by AI agents
Decisions: Every choice made with reasoning (GOLD for training!)
Artifacts: Generated code, files, documentation
Feedback: User ratings for quality improvement

Architecture

User Request → Task Created → AI Decomposes → Sessions Execute Steps
                                                      │
                                                      ▼
                                              Log Every Decision
                                                      │
                                                      ▼
                                              User Provides Feedback
                                                      │
                                                      ▼
                                              Training Data Export
                                                      │
                                                      ▼
                                              Model Fine-Tuning → Better AI

Database Location

Database: ai-agents (MongoDB)
Collections: agent_tasks, agent_decisions, agent_metrics

For AI Assistants: How to Use This System

🚨 MANDATORY PROTOCOL

When working on any significant task in GoGrab Space, AI assistants MUST:

Create a Task at the start of significant work
Start a Session for each work period
Log Decisions for every non-trivial choice
Complete Sessions with handoff notes
Request Feedback after task completion

When to Create a Task

Create a task when the user requests:

Building a new feature
Fixing a complex bug
Refactoring code
Creating components, services, modules
Any work that requires multiple steps

When NOT to Create a Task

Skip task creation for:

Simple questions/explanations
Single-line fixes
Documentation lookups
Clarification requests

Integration Points

1. Backend API Endpoints

Base URL: /api/ai-agents

// Create Task
POST /api/ai-agents/tasks
Body: {
  type: 'vibe-coding' | 'content-generation' | 'data-operation' | 'custom',
  goal: string,
  description?: string,
  priority?: 'low' | 'medium' | 'high' | 'critical',
  tags?: string[]
}

// Start Session
POST /api/ai-agents/tasks/:taskId/sessions
Body: {
  agentType: 'initializer' | 'planner' | 'executor' | 'reviewer' | 'specialist',
  specialization?: 'ui' | 'api' | 'database' | 'testing' | 'documentation' | 'security'
}

// Log Decision
POST /api/ai-agents/tasks/:taskId/sessions/:sessionId/decisions
Body: {
  type: 'task-decomposition' | 'implementation-choice' | 'error-recovery' | 'other',
  agentType: string,
  question: string,      // What decision was being made
  options: string[],     // What alternatives were considered
  chosen: string,        // What was selected
  reasoning: string,     // WHY (most important!)
  confidence: number     // 0-1 confidence score
}

// Complete Session
PUT /api/ai-agents/tasks/:taskId/sessions/:sessionId/complete
Body: {
  handoffNotes: string,          // Summary for next session
  nextRecommendations: string[]  // What should be done next
}

2. Frontend Integration

The frontend library @libs-ai/agent-orchestrator provides:

import { AgentApiService, AgentMonitorService } from '@libs-ai/agent-orchestrator';

// In your component/service
private agentApi = inject(AgentApiService);
private agentMonitor = inject(AgentMonitorService);

// Create task
this.agentApi.createTask({
  type: 'vibe-coding',
  goal: 'Build user profile page',
  priority: 'high'
}).subscribe(task => {
  this.currentTaskId = task.id;
});

// Real-time monitoring
this.agentMonitor.connect(userId);
this.agentMonitor.subscribeToTask(taskId).subscribe();
this.agentMonitor.getTaskStatusUpdates(taskId).subscribe(update => {
  // Update UI with progress
});

Decision Logging Protocol

Types of Decisions to Log

Decision Type	When to Log	Example
`task-decomposition`	Breaking goal into steps	"Split 'build auth' into 5 steps"
`implementation-choice`	Choosing approach/library	"Use Zod over Yup for validation"
`step-selection`	Choosing next step	"Start with API before UI"
`error-recovery`	Handling errors	"Retry with different approach"
`context-prioritization`	Choosing what context to include	"Focus on auth files, skip tests"
`quality-assessment`	Evaluating work quality	"Code meets requirements"

Decision Log Format

{
  type: 'implementation-choice',
  agentType: 'executor',
  question: 'Which state management approach should I use for the user profile?',
  options: [
    'Angular Signals (local state)',
    'RxJS BehaviorSubject',
    'NGXS store',
    'Component input/output'
  ],
  chosen: 'Angular Signals (local state)',
  reasoning: 'User profile is component-local state, not shared across modules. ' +
             'Signals provide simpler reactivity and better performance than RxJS. ' +
             'NGXS would be overkill for non-global state per project guidelines.',
  confidence: 0.9
}

Confidence Score Guidelines

Score	Meaning	When to Use
0.9-1.0	Very confident	Clear best practice, explicit requirement
0.7-0.9	Confident	Good solution, some alternatives viable
0.5-0.7	Moderate	Multiple valid approaches, made judgment call
0.3-0.5	Uncertain	Limited information, best guess
0.0-0.3	Low confidence	Experimental, needs review

Self-Learning Loop

How the System Learns

Decision Collection
- Every AI decision logged with reasoning
- Stored in agent_decisions collection
- Indexed by type, confidence, outcome
User Feedback
- User rates completed tasks (1-5)
- Records if modifications were made
- Captures what worked and what didn't

Training Data Export

POST /api/ai-agents/export
{
  minQualityRating: 4,    // Only high-quality tasks
  includeDecisions: true,
  format: 'jsonl'
}

Pattern Analysis
- Identify successful decision patterns
- Find common failure modes
- Track which reasoning leads to best outcomes
Model Improvement
- Export high-confidence, user-approved decisions
- Use for fine-tuning or prompt engineering
- Feed back improved patterns to AI instructions

Metrics Dashboard

Access at /api/ai-agents/metrics:

{
  totalTasks: number,
  completedTasks: number,
  averageQualityScore: number,
  topDecisionPatterns: [
    { type: 'implementation-choice', successRate: 0.92 },
    { type: 'error-recovery', successRate: 0.78 }
  ]
}

API Reference

Task Lifecycle

1. CREATE TASK
   POST /api/ai-agents/tasks
   
2. AI DECOMPOSES (auto or manual)
   POST /api/ai-agents/tasks/:id/decomposition
   
3. START SESSION
   POST /api/ai-agents/tasks/:id/sessions
   
4. LOG DECISIONS (multiple)
   POST /api/ai-agents/tasks/:id/sessions/:sessionId/decisions
   
5. COMPLETE SESSION
   PUT /api/ai-agents/tasks/:id/sessions/:sessionId/complete
   
6. REPEAT 3-5 until all steps done
   
7. TASK COMPLETES AUTOMATICALLY
   
8. GET USER FEEDBACK
   POST /api/ai-agents/tasks/:id/feedback

Example: Full Task Flow

// 1. Create task
const task = await api.post('/api/ai-agents/tasks', {
  type: 'vibe-coding',
  goal: 'Create a responsive navigation component',
  priority: 'high'
});

// 2. Start session
const session = await api.post(`/api/ai-agents/tasks/${task.id}/sessions`, {
  agentType: 'executor',
  specialization: 'ui'
});

// 3. Log decisions as you work
await api.post(`/api/ai-agents/tasks/${task.id}/sessions/${session.id}/decisions`, {
  type: 'implementation-choice',
  agentType: 'executor',
  question: 'How should I handle responsive breakpoints?',
  options: ['CSS media queries', 'Tailwind breakpoints', 'BreakpointObserver'],
  chosen: 'BreakpointObserver',
  reasoning: 'Angular Material BreakpointObserver integrates with Angular change detection and allows programmatic response to breakpoints',
  confidence: 0.85
});

// 4. Complete session
await api.put(`/api/ai-agents/tasks/${task.id}/sessions/${session.id}/complete`, {
  handoffNotes: 'Navigation component created with responsive behavior. Mobile menu implemented with slide-in animation.',
  nextRecommendations: [
    'Add keyboard navigation for accessibility',
    'Implement active link highlighting',
    'Add unit tests for breakpoint changes'
  ]
});

Implementation Checklist

To fully activate the AI Agent Task System:

Backend (Complete ✅)

AgentTaskService
AgentSessionService
AgentOrchestratorService
AgentContextService
AgentLearningBridgeService
AgentRealtimeGateway
MongoDB schemas
REST API endpoints

Frontend Library (Complete ✅)

AgentApiService
AgentMonitorService
TypeScript models
WebSocket integration

Integration (TODO 🔴)

Integrate with vibe-coding interface
Auto-create task on vibe-coding start
Auto-log decisions during AI responses
Feedback collection UI
Admin dashboard integration
Training data export pipeline

AI Instructions (In Progress 🟡)

This document
Add to CLAUDE.md
Add to cursor rules
Test with actual AI sessions

Quick Start for AI Assistants

When starting a coding task:

Announce: "I'm creating an AI task to track this work for learning purposes."

Create Task (mentally or via API if integrated):

Task: [User's goal]
Type: vibe-coding
Priority: [based on urgency]

Decompose into steps
For each decision, note:
- What choice was made
- What alternatives existed
- Why this was chosen
- Confidence level
On completion, summarize:
- What was accomplished
- What should be done next
- Any blockers or concerns
Request feedback: "How would you rate this work? (1-5)"

Last Updated: December 2025 Status: Foundation Complete, Integration Pending