TASK-O-MATIC

TECHNICAL BULLETIN NO. 004

WORKFLOW AI ASSISTANT - DECISION SUPPORT SURVIVAL SYSTEM

DOCUMENT ID: task-o-matic-workflow-ai-assistant-v1

CLEARANCE: All Personnel

MANDATORY COMPLIANCE: Yes

⚠️ CRITICAL SURVIVAL NOTICE

Citizen, WorkflowAIAssistant is your tactical advisor in the post-deadline wasteland. Without AI-powered decision support, your project choices will be as random as radiation storms. This service provides intelligent recommendations for project configuration, PRD improvement, and task management strategies.

SYSTEM ARCHITECTURE OVERVIEW

The WorkflowAIAssistant serves as specialized AI consultant that provides contextual decision support for workflow operations. It leverages multiple AI models to offer recommendations, improvements, and strategic guidance throughout the project lifecycle.

Core Dependencies:

AI Operations: Vercel AI SDK integration for model communication
Prompt Builder: Template-based prompt generation system
AI Config Builder: Flexible AI configuration management

Assistant Capabilities:

Project Configuration: AI-recommended technology stacks
PRD Creation: Generate PRDs from descriptions
PRD Refinement: Improve existing PRDs based on feedback
Task Prioritization: Intelligent task ordering and recommendations
Task Splitting: Custom splitting instructions generation

COMPLETE API DOCUMENTATION

#### assistInitConfig

async assistInitConfig(input: {
  userDescription: string;
  aiOptions?: AIOptions;
  streamingOptions?: StreamingOptions;
}): Promise<{
  projectName: string;
  aiProvider: string;
  aiModel: string;
  frontend?: string;
  backend?: string;
  database?: string;
  auth?: boolean;
  reasoning: string;
}>

Parameters:

input.userDescription (string, required): Natural language project description
input.aiOptions (AIOptions, optional): AI configuration override
input.streamingOptions (StreamingOptions, optional): Streaming callbacks

Returns: Configuration recommendation object containing:

projectName (string): Suggested project name
aiProvider (string): Recommended AI provider
aiModel (string): Recommended AI model
frontend (string, optional): Recommended frontend framework
backend (string, optional): Recommended backend framework
database (string, optional): Recommended database system
auth (boolean, optional): Whether to include authentication
reasoning (string): AI's reasoning for recommendations

Error Conditions:

TaskOMaticError: Prompt building failures, AI operation failures
Fallback to sensible defaults if AI response parsing fails

Example: Basic Configuration Assistance

const recommendation = await workflowAIAssistant.assistInitConfig({
  userDescription: "A real-time collaboration platform for remote development teams with video calls and code sharing",
  aiOptions: {
    aiProvider: "anthropic",
    aiModel: "claude-3-5-sonnet"
  },
  streamingOptions: {
    onChunk: (chunk) => process.stdout.write(chunk),
    onFinish: () => console.log("\nRecommendation complete!")
  }
});

console.log("Recommended stack:");
console.log(`- Frontend: ${recommendation.frontend}`);
console.log(`- Backend: ${recommendation.backend}`);
console.log(`- Database: ${recommendation.database}`);
console.log(`- Auth: ${recommendation.auth}`);
console.log(`Reasoning: ${recommendation.reasoning}`);

Example: Minimal Configuration Request

const recommendation = await workflowAIAssistant.assistInitConfig({
  userDescription: "Simple blog API with user authentication"
});

console.log(`AI recommends: ${recommendation.frontend || 'no frontend'} + ${recommendation.backend || 'no backend'}`);

#### assistPRDCreation

async assistPRDCreation(input: {
  userDescription: string;
  aiOptions?: AIOptions;
  streamingOptions?: StreamingOptions;
}): Promise<string>

Parameters:

input.userDescription (string, required): Project description for PRD generation
input.aiOptions (AIOptions, optional): AI configuration override
input.streamingOptions (StreamingOptions, optional): Streaming callbacks

Returns: Generated PRD content as string

Error Conditions:

TaskOMaticError: AI operation failures
Empty string if generation fails completely

Example: PRD Generation Assistance

const prdContent = await workflowAIAssistant.assistPRDCreation({
  userDescription: "Mobile fitness tracking app with social features and workout plans",
  aiOptions: {
    aiProvider: "anthropic",
    aiModel: "claude-3-5-sonnet"
  },
  streamingOptions: {
    onChunk: (chunk) => process.stdout.write(chunk),
    onFinish: () => console.log("\nPRD generation complete!")
  }
});

console.log(`Generated PRD with ${prdContent.length} characters`);
// Save to file or use in workflow
await fs.writeFile("./generated-prd.md", prdContent);

Example: Quick PRD Generation

const simplePRD = await workflowAIAssistant.assistPRDCreation({
  userDescription: "Todo list application with categories and due dates"
});

console.log("Quick PRD generated:", simplePRD.substring(0, 100) + "...");

#### assistPRDRefinement

async assistPRDRefinement(input: {
  currentPRD: string;
  userFeedback: string;
  aiOptions?: AIOptions;
  streamingOptions?: StreamingOptions;
}): Promise<string>

Parameters:

input.currentPRD (string, required): Current PRD content to refine
input.userFeedback (string, required): User feedback for improvements
input.aiOptions (AIOptions, optional): AI configuration override
input.streamingOptions (StreamingOptions, optional): Streaming callbacks

Returns: Refined PRD content as string

Error Conditions:

TaskOMaticError: Prompt building failures, AI operation failures
Original PRD returned if refinement fails

Example: PRD Refinement Assistance

const refinedPRD = await workflowAIAssistant.assistPRDRefinement({
  currentPRD: existingPRDContent,
  userFeedback: "Add more technical specifications, API details, and security requirements. Include performance benchmarks and scalability considerations.",
  aiOptions: {
    aiProvider: "anthropic",
    aiModel: "claude-3-5-sonnet"
  },
  streamingOptions: {
    onChunk: (chunk) => process.stdout.write(chunk),
    onFinish: () => console.log("\nRefinement complete!")
  }
});

console.log(`Refined PRD length: ${refinedPRD.length} characters`);
console.log(`Improvement: ${refinedPRD.length - existingPRDContent.length} characters added`);

Example: Targeted Refinement

const specificRefinement = await workflowAIAssistant.assistPRDRefinement({
  currentPRD: basicPRD,
  userFeedback: "Focus on mobile responsiveness, offline capabilities, and accessibility features"
});

console.log("PRD refined for mobile-first approach");

#### assistTaskPrioritization

async assistTaskPrioritization(input: {
  tasks: Array<{ id: string; title: string; description?: string }>;
  userGuidance: string;
  aiOptions?: AIOptions;
  streamingOptions?: StreamingOptions;
}): Promise<{
  prioritizedTasks: Array<{
    id: string;
    priority: number;
    reasoning: string;
  }>;
  recommendations: string;
}>

Parameters:

input.tasks (array, required): Array of tasks to prioritize

- id (string): Task identifier

- title (string): Task title

- description (string, optional): Task description

input.userGuidance (string, required): User's prioritization criteria
input.aiOptions (AIOptions, optional): AI configuration override
input.streamingOptions (StreamingOptions, optional): Streaming callbacks

Returns: Prioritization result containing:

prioritizedTasks (array): Tasks with priority assignments

- id (string): Task ID

- priority (number): Priority ranking (1 = highest)

- reasoning (string): AI's reasoning for priority

recommendations (string): Overall prioritization recommendations

Error Conditions:

TaskOMaticError: Prompt building failures, AI operation failures
Fallback to original order if AI response parsing fails

Example: Task Prioritization Assistance

const tasks = [
  { id: "1", title: "Implement user authentication", description: "OAuth2 integration with JWT tokens" },
  { id: "2", title: "Design database schema", description: "User data, posts, and relationships" },
  { id: "3", title: "Create responsive UI", description: "Mobile-first design with CSS Grid" },
  { id: "4", title: "Setup CI/CD pipeline", description: "GitHub Actions with automated testing" }
];

const prioritization = await workflowAIAssistant.assistTaskPrioritization({
  tasks: tasks,
  userGuidance: "Prioritize based on dependencies and user-facing impact. Authentication should be first, then core functionality.",
  aiOptions: {
    aiProvider: "anthropic",
    aiModel: "claude-3-5-sonnet"
  },
  streamingOptions: {
    onChunk: (chunk) => process.stdout.write(chunk)
  }
});

console.log("Prioritized tasks:");
prioritization.prioritizedTasks.forEach(task => {
  console.log(`${task.priority}. [${task.id}] ${task.title}`);
  console.log(`   Reasoning: ${task.reasoning}`);
});

console.log(`\nRecommendations: ${prioritization.recommendations}`);

Example: Effort-Based Prioritization

const effortPrioritization = await workflowAIAssistant.assistTaskPrioritization({
  tasks: developmentTasks,
  userGuidance: "Prioritize high-effort, high-impact tasks first. Consider dependencies and risk."
});

// Sort by priority for execution order
const sortedTasks = effortPrioritization.prioritizedTasks
  .sort((a, b) => a.priority - b.priority)
  .map(pt => tasks.find(t => t.id === pt.id));

console.log("Execution order:", sortedTasks.map(t => t.title));

#### assistTaskSplitting

async assistTaskSplitting(input: {
  taskTitle: string;
  taskContent?: string;
  userGuidance: string;
  aiOptions?: AIOptions;
  streamingOptions?: StreamingOptions;
}): Promise<string>

Parameters:

input.taskTitle (string, required): Title of task to split
input.taskContent (string, optional): Task description/content
input.userGuidance (string, required): User's splitting instructions
input.aiOptions (AIOptions, optional): AI configuration override
input.streamingOptions (StreamingOptions, optional): Streaming callbacks

Returns: Generated splitting instructions as string

Error Conditions:

TaskOMaticError: Prompt building failures, AI operation failures
Empty string if generation fails

Example: Task Splitting Assistance

const splittingInstructions = await workflowAIAssistant.assistTaskSplitting({
  taskTitle: "Implement e-commerce platform",
  taskContent: "Build a full-stack e-commerce solution with payment processing, inventory management, and user accounts",
  userGuidance: "Split into frontend, backend, and database components. Include testing and deployment tasks. Focus on API development first.",
  aiOptions: {
    aiProvider: "anthropic",
    aiModel: "claude-3-5-sonnet"
  },
  streamingOptions: {
    onChunk: (chunk) => process.stdout.write(chunk),
    onFinish: () => console.log("\nSplitting instructions generated!")
  }
});

console.log("AI-generated splitting instructions:");
console.log(splittingInstructions);

// Use instructions with taskService.splitTask
const splitResult = await taskService.splitTask("task-id", undefined, splittingInstructions);

Example: Feature-Based Splitting

const featureSplitting = await workflowAIAssistant.assistTaskSplitting({
  taskTitle: "Add social features",
  userGuidance: "Split into user profiles, social connections, activity feeds, and notifications. Include both frontend and backend tasks."
});

console.log("Feature-based splitting instructions generated");

Example: Technical Component Splitting

const technicalSplitting = await workflowAIAssistant.assistTaskSplitting({
  taskTitle: "Build authentication system",
  taskContent: "Implement secure user authentication with multiple providers",
  userGuidance: "Split by technical components: UI, API endpoints, database models, security middleware, and testing"
});

console.log("Technical component splitting instructions ready");

INTEGRATION PROTOCOLS

Prompt Building Integration:

The assistant uses PromptBuilder for consistent prompt generation:

// Example prompt template usage
const promptResult = PromptBuilder.buildPrompt({
  name: "project-init-suggestion",
  type: "user",
  variables: {
    USER_DESCRIPTION: input.userDescription
  }
});

AI Configuration Integration:

All methods support flexible AI configuration:

interface AIOptions {
  aiProvider?: string;        // Provider selection
  aiModel?: string;          // Model selection
  aiKey?: string;            // API key override
  aiProviderUrl?: string;     // Custom endpoint
}

Streaming Integration:

Real-time feedback through standardized streaming:

interface StreamingOptions {
  onChunk?: (chunk: string) => void;      // Real-time response chunks
  onFinish?: (result: any) => void;       // Completion callback
  onError?: (error: Error) => void;        // Error handling
}

Error Handling Strategy:

Graceful fallbacks for AI response parsing failures
Sensible defaults when AI recommendations fail
Detailed error messages with context
Structured error responses with suggestions

SURVIVAL SCENARIOS

Scenario 1: Complete Project Setup Assistance

// Step 1: Get AI recommendations for project setup
const configRecommendation = await workflowAIAssistant.assistInitConfig({
  userDescription: "AI-powered code review platform for development teams with real-time collaboration",
  aiOptions: { aiProvider: "anthropic", aiModel: "claude-3-5-sonnet" }
});

console.log("AI Recommended Stack:", configRecommendation);

// Step 2: Generate initial PRD
const prdContent = await workflowAIAssistant.assistPRDCreation({
  userDescription: "AI-powered code review platform with real-time collaboration, automated analysis, and team management features",
  aiOptions: { aiProvider: "anthropic", aiModel: "claude-3-5-sonnet" }
});

// Step 3: Refine PRD based on feedback
const refinedPRD = await workflowAIAssistant.assistPRDRefinement({
  currentPRD: prdContent,
  userFeedback: "Add more technical details about code analysis algorithms, integration with Git providers, and performance requirements for large repositories",
  aiOptions: { aiProvider: "anthropic", aiModel: "claude-3-5-sonnet" }
});

console.log("Complete project setup assistance completed");

Scenario 2: Task Management Strategy

// Get prioritized task order
const tasks = await taskService.listTasks({ status: "todo" });
const taskDetails = tasks.map(task => ({
  id: task.id,
  title: task.title,
  description: task.description
}));

const prioritization = await workflowAIAssistant.assistTaskPrioritization({
  tasks: taskDetails,
  userGuidance: "Prioritize based on user impact, dependencies, and effort. Critical path tasks first.",
  aiOptions: { aiProvider: "anthropic", model: "claude-3-5-sonnet" }
});

// Execute tasks in AI-recommended order
for (const prioritizedTask of prioritization.prioritizedTasks) {
  const task = tasks.find(t => t.id === prioritizedTask.id);
  if (task) {
    console.log(`Working on: ${task.title} (Priority: ${prioritizedTask.priority})`);
    console.log(`Reasoning: ${prioritizedTask.reasoning}`);
    
    // Get splitting instructions for complex tasks
    if (task.estimatedEffort === "large") {
      const splittingInstructions = await workflowAIAssistant.assistTaskSplitting({
        taskTitle: task.title,
        taskContent: task.description,
        userGuidance: "Split into manageable subtasks with clear deliverables"
      });
      
      // Apply splitting...
    }
    
    // Mark task as in-progress and work on it
    await taskService.setTaskStatus(task.id, "in-progress");
    // ... work on task ...
    await taskService.setTaskStatus(task.id, "completed");
  }
}

Scenario 3: Iterative PRD Improvement

let currentPRD = await fs.readFile("./draft-prd.md", "utf-8");
const feedbackRounds = [
  "Add security requirements and compliance considerations",
  "Include performance benchmarks and scalability targets",
  "Detail user experience and accessibility requirements",
  "Add integration requirements with existing systems"
];

for (let i = 0; i < feedbackRounds.length; i++) {
  console.log(`Refinement round ${i + 1}: ${feedbackRounds[i]}`);
  
  currentPRD = await workflowAIAssistant.assistPRDRefinement({
    currentPRD: currentPRD,
    userFeedback: feedbackRounds[i],
    aiOptions: { aiProvider: "anthropic", model: "claude-3-5-sonnet" },
    streamingOptions: {
      onChunk: (chunk) => process.stdout.write(chunk)
    }
  });
  
  // Save intermediate version
  await fs.writeFile(`./prd-refined-v${i + 1}.md`, currentPRD);
  console.log(`Refinement ${i + 1} complete`);
}

console.log("Final refined PRD ready for task extraction");

TECHNICAL SPECIFICATIONS

Prompt Template System:

The assistant uses structured prompt templates for consistency:

project-init-suggestion: For stack recommendations
prd-improvement: For PRD refinement
task-prioritization: For task ordering
task-splitting-assistance: For task breakdown

AI Response Parsing:

All AI responses are parsed with robust error handling:

// Example JSON parsing with fallback
try {
  const jsonMatch = result.match(/\{[\s\S]*\}/);
  if (!jsonMatch) {
    throw new Error("No JSON found in AI response");
  }
  return JSON.parse(jsonMatch[0]);
} catch (error) {
  // Return sensible defaults
  return defaultConfiguration;
}

Fallback Strategies:

When AI operations fail, the assistant provides sensible defaults:

Project initialization: Modern, well-supported stack
PRD operations: Returns original content
Task operations: Maintains original ordering

Error Recovery:

Multiple parsing attempts for malformed AI responses
Graceful degradation of functionality
Detailed error logging for debugging
User-friendly error messages with suggestions

Performance Considerations:

Streaming responses for real-time feedback
Efficient prompt caching where possible
Minimal memory footprint for large operations
Concurrent operation support where applicable

Integration Points:

Direct integration with WorkflowService for seamless workflow
Compatible with TaskService for task management
Uses same AI configuration as other services
Consistent error handling patterns

Remember: Citizen, WorkflowAIAssistant is your strategic advisor in the wasteland of project decisions. Use its recommendations to navigate the complex terrain of technology choices, but always apply your own judgment. The AI provides guidance, but you make the final decisions. Trust but verify, adapt but don't blindly follow.

SERVICES DOCUMENTATION

TECHNICAL BULLETIN NO. 004

WORKFLOW AI ASSISTANT - DECISION SUPPORT SURVIVAL SYSTEM

⚠️ CRITICAL SURVIVAL NOTICE

SYSTEM ARCHITECTURE OVERVIEW

COMPLETE API DOCUMENTATION

INTEGRATION PROTOCOLS

SURVIVAL SCENARIOS

TECHNICAL SPECIFICATIONS