conversation

Provides natural language processing for understanding user intent, managing conversation context, resolving references, and maintaining conversation history.

Responsibilities

1. Intent Classification - Determine what the user wants
2. Reference Resolution - Resolve "it", "that", "this" to actual feature names
3. Entity Extraction - Extract features, domains, subtasks mentioned
4. Ambiguity Detection - Identify unclear requests and ask clarifying questions
5. Context Management - Track conversation state, detect context loss
6. Routing - Route to appropriate handler
7. History Tracking - Maintain conversation history for context

Intent Classification

function classify_intent(
  message: string,
  conversation_history: ConversationMessage[],
  product_spec: ProductSpec
): IntentClassification {
  const patterns = {
    feature_request: /(?:add|create|implement|build|new|feature|support|enable)/i,
    bug_report: /(?:bug|broken|error|issue|problem|wrong|doesn't work|fix)/i,
    question: /(?:how|what|where|when|why|who|which|can you|explain)/i,
    clarification: /(?:what do you mean|clarify|elaborate|more detail)/i,
    status_update: /(?:status|progress|where are we|what's left)/i,
    mind_change: /(?:actually|wait|never mind|forget that|change|instead)/i,
    context_switch: /(?:let's talk about|switching to|moving on|about)/i,
    approval: /(?:yes|ok|sure|go ahead|approved|sounds good|let's do it)/i,
    rejection: /(?:no|stop|don't|cancel|never mind)/i,
    pause: /(?:pause|hold on|wait|brb|later)/i,
    continue: /(?:continue|resume|let's continue|back)/i
  };

  const scores = {};
  for (const [intent, pattern] of Object.entries(patterns)) {
    const matches = message.match(pattern);
    scores[intent] = matches ? matches.length * 0.3 : 0;
  }

  const topIntent = Object.entries(scores).reduce((a, b) => a[1] > b[1] ? a : b);

  return {
    intent: topIntent[0],
    confidence: topIntent[1],
    alternative_intents: Object.entries(scores)
      .filter(([_, score]) => score > 0.3)
      .sort((a, b) => b[1] - a[1])
      .slice(1, 4)
      .map(([intent, score]) => ({ intent, confidence: score }))
  };
}

Entity Extraction

function extract_feature_mention(
  message: string,
  product_spec: ProductSpec
): FeatureMention {
  const mentioned = [];

  // Direct feature name matches
  if (product_spec.features) {
    for (const [featureId, feature] of Object.entries(product_spec.features)) {
      const featureName = feature.name || featureId;
      if (message.toLowerCase().includes(featureName.toLowerCase())) {
        mentioned.push({
          type: 'direct',
          feature_id: featureId,
          feature_name: featureName,
          confidence: 0.9
        });
      }
    }
  }

  // Domain and nested feature matches
  if (product_spec.domains) {
    for (const [domainId, domain] of Object.entries(product_spec.domains)) {
      if (message.toLowerCase().includes(domain.name.toLowerCase())) {
        mentioned.push({
          type: 'domain',
          domain_id: domainId,
          domain_name: domain.name,
          confidence: 0.85
        });
      }

      if (domain.features) {
        for (const [featureId, feature] of Object.entries(domain.features)) {
          const featureName = feature.name || featureId;
          if (message.toLowerCase().includes(featureName.toLowerCase())) {
            mentioned.push({
              type: 'feature',
              domain_id: domainId,
              feature_id: featureId,
              feature_name: featureName,
              confidence: 0.9
            });
          }
        }
      }
    }
  }

  // Subtask references
  const subtaskMatch = message.match(/(?:subtask|task|item)\s+(\d+)/i);
  if (subtaskMatch) {
    mentioned.push({
      type: 'subtask_reference',
      reference: subtaskMatch[1],
      confidence: 0.7
    });
  }

  if (mentioned.length === 0) return { type: 'none', confidence: 0 };
  return mentioned.sort((a, b) => b.confidence - a.confidence)[0];
}

Ambiguity Detection

function detect_ambiguity(message: string): AmbiguityAnalysis {
  const ambiguities = [];
  let confidence = 0;

  // Pronouns without context
  const pronouns = message.match(/\b(it|that|this|they|them|those)\b/gi);
  if (pronouns && /^(it|that|this|they|them)/i.test(message.trim())) {
    ambiguities.push({
      type: 'pronoun_without_antecedent',
      severity: 'high',
      text: pronouns[0],
      message: 'Pronoun at start of message without clear referent'
    });
    confidence = 0.8;
  }

  // Vague actions
  const vagueMatch = message.match(/\b(fix|update|change|improve|handle)\b\s+(?:it|that|this)/i);
  if (vagueMatch) {
    ambiguities.push({
      type: 'vague_action',
      severity: 'medium',
      text: vagueMatch[0],
      message: 'Action verb without specific target'
    });
    confidence = Math.max(confidence, 0.6);
  }

  // Multiple actions
  const actionWords = message.split(/\s+/).filter(word =>
    /^(add|create|fix|update|delete|remove|test|check|verify|deploy|build|run)/i.test(word)
  );
  if (actionWords.length > 2) {
    ambiguities.push({
      type: 'multiple_actions',
      severity: 'medium',
      text: actionWords.join(', '),
      message: 'Multiple actions detected, unclear priority'
    });
    confidence = Math.max(confidence, 0.7);
  }

  return {
    is_ambiguous: ambiguities.length > 0,
    confidence,
    ambiguities,
    suggestion: ambiguities.length > 0 ? 'Could you please provide more specific details?' : null
  };
}

Reference Resolution

function resolve_references(
  message: string,
  conversation_history: ConversationMessage[],
  state: ConversationState
): ResolvedMessage {
  let resolved = message;
  const references = [];

  // Replace pronouns with actual referents
  const pronounMap = {
    'it': state.current_feature?.feature_name,
    'that': state.last_action?.description,
    'this': state.current_feature?.feature_name
  };

  for (const [pronoun, referent] of Object.entries(pronounMap)) {
    if (referent) {
      const pattern = new RegExp(`\\b${pronoun}\\b`, 'gi');
      if (pattern.test(message)) {
        resolved = resolved.replace(pattern, referent);
        references.push({ original: pronoun, resolved: referent, type: 'pronoun' });
      }
    }
  }

  // Replace definite references
  const definiteReferences = {
    'the feature': state.current_feature?.feature_name,
    'the bug': state.last_action?.type === 'bug_fix' ? state.last_action.description : null,
    'the task': state.current_feature?.subtask_id
  };

  for (const [phrase, referent] of Object.entries(definiteReferences)) {
    if (referent) {
      resolved = resolved.replace(new RegExp(phrase, 'gi'), referent);
      references.push({ original: phrase, resolved: referent, type: 'definite_reference' });
    }
  }

  return {
    original: message,
    resolved,
    references,
    confidence: references.length > 0 ? 0.85 : 1.0
  };
}

Context Management

interface ConversationState {
  current_feature: {
    domain_id?: string;
    feature_id?: string;
    feature_name?: string;
    subtask_id?: string;
  } | null;
  current_phase: 'idle' | 'planning' | 'implementing' | 'testing' | 'reviewing' | 'deploying';
  last_action: {
    type: string;
    description: string;
    timestamp: string;
    result?: any;
  } | null;
  related_features: Array<{
    feature_id: string;
    feature_name: string;
    relationship: 'dependency' | 'similar' | 'related';
  }>;
  session_start: string;
  last_message_time: string;
  message_count: number;
}

function detect_context_loss(
  conversation_history: ConversationMessage[],
  state: ConversationState
): ContextRecovery {
  const now = new Date();
  const lastMessage = conversation_history[conversation_history.length - 1];
  const lastMessageTime = new Date(lastMessage?.timestamp || state.session_start);
  const hoursDiff = (now.getTime() - lastMessageTime.getTime()) / (1000 * 60 * 60);

  if (hoursDiff > 24) {
    return {
      is_stale: true,
      hours_since_last_message: Math.round(hoursDiff),
      recommendation: 'summarize_and_confirm',
      message: `It's been ${Math.round(hoursDiff)} hours since our last conversation.`,
      suggested_confirmation: `We were working on ${state.current_feature?.feature_name || 'a feature'}. Continue or start new?`
    };
  }

  return {
    is_stale: false,
    hours_since_last_message: Math.round(hoursDiff),
    recommendation: 'continue',
    message: null
  };
}

Routing Logic

function route_to_handler(
  intent: IntentClassification,
  entities: FeatureMention,
  state: ConversationState
): RoutingDecision {
  const intentName = intent.intent;

  // Feature development or bug fixes → orchestrator
  if (intentName === 'feature_request' || intentName === 'bug_report') {
    return {
      handler: 'orchestrator',
      skill: null,
      context: {
        intent: intentName,
        feature_id: entities.feature_id,
        domain_id: entities.domain_id,
        work_type: intentName === 'feature_request' ? 'FEATURE_DEVELOPMENT' : 'BUGFIX'
      }
    };
  }

  // Status inquiries → product-tracking
  if (intentName === 'status_update') {
    return {
      handler: 'product-tracking',
      skill: 'product-tracking',
      context: {
        intent: intentName,
        feature_filter: entities.feature_id || null,
        domain_filter: entities.domain_id || null
      }
    };
  }

  // Validation → validation skill
  if (/test|validate|check/i.test(intentName)) {
    return {
      handler: 'validation',
      skill: 'validation',
      context: {
        intent: intentName,
        scope: entities.feature_id ? 'feature' : 'all'
      }
    };
  }

  // Product planning → reference product-planning skill guidance (inline)
  // Note: product-planning is a skill, not a separate agent
  // When user asks planning/requirements questions, use product-planning skill's guidance
  if (/plan|requirements|spec|analyze/i.test(intentName)) {
    return {
      handler: 'inline',
      skill: 'product-planning',
      context: {
        intent: intentName,
        use_skill_guidance: 'product-planning',
        action: 'answer_with_planning_guidance'
      }
    };
  }

  // Approval/continue → orchestrator (resume)
  if (intentName === 'approval' || intentName === 'continue') {
    return {
      handler: 'orchestrator',
      skill: null,
      context: {
        intent: 'continue',
        resume_feature: state.current_feature
      }
    };
  }

  // Rejection/pause → inline
  if (intentName === 'rejection' || intentName === 'pause') {
    return {
      handler: 'inline',
      skill: null,
      context: {
        intent: intentName,
        action: 'pause_work'
      }
    };
  }

  // Questions → inline
  if (intentName === 'question' || intentName === 'clarification') {
    return {
      handler: 'inline',
      skill: null,
      context: {
        intent: intentName,
        answer_from: ['conversation_history', 'product_spec', 'completion_status']
      }
    };
  }

  // Default: inline with clarification
  return {
    handler: 'inline',
    skill: null,
    context: {
      intent: intentName,
      needs_clarification: true
    }
  };
}

History Management

// Stored in: .agentful/conversation-history.json
interface ConversationHistory {
  version: "1.0";
  session_id: string;
  started_at: string;
  messages: ConversationMessage[];
  context_snapshot: any;
}

function add_message_to_history(
  message: ConversationMessage,
  history_path: string = '.agentful/conversation-history.json'
): void {
  let history = read_conversation_history(history_path);

  history.messages.push({
    ...message,
    id: message.id || generate_uuid(),
    timestamp: message.timestamp || new Date().toISOString()
  });

  // Keep last 100 messages
  if (history.messages.length > 100) {
    history.messages = history.messages.slice(-100);
  }

  Write(history_path, JSON.stringify(history, null, 2));
}

function read_conversation_history(
  history_path: string = '.agentful/conversation-history.json'
): ConversationHistory {
  try {
    const content = Read(history_path);
    return JSON.parse(content);
  } catch (error) {
    return {
      version: "1.0",
      session_id: generate_uuid(),
      started_at: new Date().toISOString(),
      messages: [],
      context_snapshot: null
    };
  }
}

Complete Processing Flow

async function process_conversation(userMessage: string): Promise<ConversationResponse> {
  // 1. Load state and history
  const state = load_conversation_state('.agentful/conversation-state.json');
  const history = read_conversation_history('.agentful/conversation-history.json');
  const productSpec = load_product_spec('.claude/product/');

  // 2. Check context loss
  const contextRecovery = detect_context_loss(history.messages, state);
  if (contextRecovery.is_stale) {
    return {
      type: 'context_recovery',
      message: contextRecovery.message,
      confirmation_needed: true
    };
  }

  // 3. Detect mind changes
  const mindChange = detect_mind_change(userMessage, state);
  if (mindChange.detected && mindChange.reset_context) {
    state.current_feature = null;
    state.current_phase = 'idle';
    save_conversation_state(state);
  }

  // 4. Resolve references
  const resolved = resolve_references(userMessage, history.messages, state);

  // 5. Classify intent
  const intent = classify_intent(resolved.resolved, history.messages, productSpec);

  // 6. Extract entities
  const entities = extract_feature_mention(resolved.resolved, productSpec);

  // 7. Detect ambiguity
  const ambiguity = detect_ambiguity(resolved.resolved);
  if (ambiguity.is_ambiguous && ambiguity.confidence > 0.6) {
    return {
      type: 'clarification_needed',
      message: ambiguity.suggestion,
      suggestions: []
    };
  }

  // 8. Route to handler
  const routing = route_to_handler(intent, entities, state);

  // 9. Add to history
  add_message_to_history({
    role: 'user',
    content: userMessage,
    intent: intent.intent,
    entities: entities,
    references_resolved: resolved.references
  }, '.agentful/conversation-history.json');

  // 10. Execute routing
  execute_routing(routing, userMessage, resolved);

  // 11. Update state
  state.last_message_time = new Date().toISOString();
  state.message_count++;
  if (entities.feature_id) {
    state.current_feature = {
      feature_id: entities.feature_id,
      feature_name: entities.feature_name,
      domain_id: entities.domain_id
    };
  }
  save_conversation_state(state);

  return {
    type: 'routed',
    handler: routing.handler,
    context: routing.context
  };
}

function execute_routing(
  routing: RoutingDecision,
  userMessage: string,
  resolved: ResolvedMessage
): void {
  switch (routing.handler) {
    case 'orchestrator':
      Task('orchestrator', `${routing.context.message || userMessage}
Work Type: ${routing.context.work_type || 'FEATURE_DEVELOPMENT'}
${routing.context.feature_id ? `Feature: ${routing.context.feature_id}` : ''}
${routing.context.domain_id ? `Domain: ${routing.context.domain_id}` : ''}`);
      break;

    case 'product-tracking':
      Task('product-tracking', `Show status and progress.
${routing.context.feature_filter ? `Filter: feature ${routing.context.feature_filter}` : ''}
${routing.context.domain_filter ? `Filter: domain ${routing.context.domain_filter}` : ''}`);
      break;

    case 'validation':
      Task('validation', `Run quality gates. Scope: ${routing.context.scope || 'all'}`);
      break;

    case 'inline':
      if (routing.context.needs_clarification) {
        return 'Could you please provide more details about what you\'d like me to do?';
      } else if (routing.context.action === 'pause_work') {
        pause_current_work();
        return 'Work paused. Run `/agentful` when ready to continue.';
      } else if (routing.context.action === 'answer_with_planning_guidance') {
        // Use product-planning skill guidance to answer planning/requirements questions
        // The skill provides structured approach to product planning, requirements analysis
        return answer_planning_question(userMessage, routing.context);
      } else if (routing.context.intent === 'question') {
        return answer_question(userMessage, routing.context);
      }
      break;
  }
}

File Locations

.agentful/
├── conversation-state.json       # Current conversation state
├── conversation-history.json     # Full message history
└── user-preferences.json         # Learned user preferences

Flow Diagram

User Input → Load State/History → Context Loss Check → Mind Change Detection →
Reference Resolution → Intent Classification → Entity Extraction →
Ambiguity Detection → Route to Handler → Add to History → Update State → Done