004-agentic-orchestration

Agent 004: Proactive Watch Mode

Objective

Watch for file changes, auto-index, and surface conflicts proactively. No query needed — system detects problems automatically.

Context

This is the key differentiator from AI-dependent systems. Instead of waiting for AI to ask "are there conflicts?", the system:

1. Watches for file changes
2. Re-indexes affected entities
3. Runs conflict detection
4. Notifies (stdout, file, webhook, toast)

Tasks

1. File Watcher (src/watch/index.ts)

import chokidar from 'chokidar';

export class GraphWatcher {
  private watcher: chokidar.FSWatcher | null = null;
  
  constructor(
    private plansDir: string,
    private extractor: EntityExtractor,
    private storage: GraphStorage,
    private detector: ConflictDetector,
    private notifier: Notifier
  ) {}
  
  start(options: WatchOptions = {}): void {
    const {
      interval = 100,        // Debounce interval
      onConflict = 'log',    // 'log' | 'notify' | 'webhook'
      webhookUrl,
    } = options;
    
    this.watcher = chokidar.watch(this.plansDir, {
      ignored: /(^|[\/\\])\../, // Ignore dotfiles
      persistent: true,
      ignoreInitial: true,
      awaitWriteFinish: {
        stabilityThreshold: interval,
        pollInterval: 100,
      },
    });
    
    this.watcher
      .on('add', path => this.handleChange(path, 'add'))
      .on('change', path => this.handleChange(path, 'change'))
      .on('unlink', path => this.handleChange(path, 'delete'));
    
    console.log(`👁️  Watching ${this.plansDir} for changes...`);
  }
  
  stop(): void {
    this.watcher?.close();
    this.watcher = null;
  }
  
  private async handleChange(path: string, event: 'add' | 'change' | 'delete'): Promise<void> {
    // Only process plan/agent markdown files
    if (!path.endsWith('.md')) return;
    if (!path.includes('-plan.md') && !path.includes('.agent.md')) return;
    
    console.log(`📝 ${event}: ${path}`);
    
    // Re-index affected plan
    const planPath = this.getPlanPath(path);
    if (planPath) {
      const result = this.extractor.extractPlan(planPath);
      this.storage.bulkUpsertEntities(result.entities);
      this.storage.bulkUpsertRelationships(result.relationships);
    }
    
    // Run conflict detection
    const conflicts = this.detector.detectAll();
    
    // Notify if conflicts found
    if (conflicts.length > 0) {
      this.notifier.notify(conflicts);
    }
  }
  
  private getPlanPath(filePath: string): string | null {
    // Extract plan directory from file path
    const match = filePath.match(/(plans\/\d{4}[^\/]+)/);
    return match ? match[1] : null;
  }
}