feat(subagents): add agent stubs and package exports

prosdev · prosdev · commit 3ca682aa514d · 2025-11-22T05:19:27.000-08:00
PlannerAgent (Prefrontal Cortex): - Stub implementation with Agent interface - Capabilities: plan, break-down-tasks - Ready for GitHub issue → task breakdown - Health check and lifecycle management ExplorerAgent (Visual Cortex): - Stub implementation with Agent interface - Capabilities: explore, analyze-patterns, find-similar - Ready for semantic code exploration - Prepared for repository indexer integration PrAgent (Motor Cortex): - Stub implementation with Agent interface - Capabilities: create-pr, update-pr, manage-issues, comment - Ready for GitHub API integration - PR and issue management foundation Package Exports: - Export coordinator and all components - Export agent stubs for registration - Export all types for external use - Clean public API surface All agents implement: - initialize() with context - handleMessage() for communication - healthCheck() for monitoring - shutdown() for cleanup Future: Full implementations in tickets #8, #9, #10 Ticket: #7
diff --git a/packages/subagents/src/explorer/index.ts b/packages/subagents/src/explorer/index.ts
@@ -1,47 +1,56 @@
-import type { Subagent, SubagentMessage, SubagentOptions } from '..';
-
-export class ExplorerSubagent implements Subagent {
-  private name: string = '';
-  private capabilities: string[] = [];
-  private active: boolean = false;
-
-  async initialize(options: SubagentOptions): Promise<boolean> {
-    this.name = options.name;
-    this.capabilities = options.capabilities;
-    this.active = true;
-    return true;
+/**
+ * Explorer Subagent = Visual Cortex
+ * Explores and analyzes code patterns (future implementation)
+ */
+
+import type { Agent, AgentContext, Message } from '../types';
+
+export class ExplorerAgent implements Agent {
+  name: string = 'explorer';
+  capabilities: string[] = ['explore', 'analyze-patterns', 'find-similar'];
+
+  private context?: AgentContext;
+
+  async initialize(context: AgentContext): Promise<void> {
+    this.context = context;
+    this.name = context.agentName;
+    context.logger.info('Explorer agent initialized');
   }
 
-  async handleMessage(message: SubagentMessage): Promise<SubagentMessage | null> {
-    if (!this.active) {
-      console.warn(`Explorer subagent ${this.name} received message while inactive`);
-      return null;
+  async handleMessage(message: Message): Promise<Message | null> {
+    if (!this.context) {
+      throw new Error('Explorer not initialized');
     }
 
-    if (message.type === 'request' && message.payload.action === 'explore') {
+    // TODO: Implement actual exploration logic (ticket #9)
+    // For now, just acknowledge
+    this.context.logger.debug('Received message', { type: message.type });
+
+    if (message.type === 'request') {
       return {
+        id: `${message.id}-response`,
         type: 'response',
         sender: this.name,
         recipient: message.sender,
+        correlationId: message.id,
         payload: {
-          relatedFiles: [
-            { path: 'src/index.ts', relevance: 0.95 },
-            { path: 'src/utils/helpers.ts', relevance: 0.85 },
-            { path: 'src/components/main.ts', relevance: 0.75 },
-          ],
-          patterns: [
-            { name: 'Factory pattern', confidence: 0.9 },
-            { name: 'Singleton pattern', confidence: 0.8 },
-          ],
+          status: 'stub',
+          message: 'Explorer stub - implementation pending',
         },
+        priority: message.priority,
         timestamp: Date.now(),
       };
     }
 
     return null;
   }
 
+  async healthCheck(): Promise<boolean> {
+    return !!this.context;
+  }
+
   async shutdown(): Promise<void> {
-    this.active = false;
+    this.context?.logger.info('Explorer agent shutting down');
+    this.context = undefined;
   }
 }
diff --git a/packages/subagents/src/index.ts b/packages/subagents/src/index.ts
@@ -1,25 +1,35 @@
-// Subagents package entry point
-export * from './coordinator';
-export * from './planner';
-export * from './explorer';
-export * from './pr';
+/**
+ * Subagent Coordinator Package
+ * Central Nervous System for orchestrating specialized AI agents
+ *
+ * Self-contained modules:
+ * - coordinator/  - Central nervous system
+ * - logger/       - Observability (future: @lytics/croak)
+ * - planner/      - Planning agent
+ * - explorer/     - Code exploration agent
+ * - pr/           - GitHub PR agent
+ */
 
-// Shared interfaces
-export interface SubagentOptions {
-  name: string;
-  capabilities: string[];
-}
+// Main coordinator module
+export { ContextManagerImpl, SubagentCoordinator, TaskQueue } from './coordinator';
+export { ExplorerAgent } from './explorer';
+// Logger module
+export { CoordinatorLogger } from './logger';
+// Agent modules (stubs for now)
+export { PlannerAgent } from './planner';
+export { PrAgent } from './pr';
 
-export interface SubagentMessage {
-  type: 'request' | 'response' | 'event';
-  sender: string;
-  recipient: string;
-  payload: Record<string, unknown>;
-  timestamp: number;
-}
-
-export interface Subagent {
-  initialize(options: SubagentOptions): Promise<boolean>;
-  handleMessage(message: SubagentMessage): Promise<SubagentMessage | null>;
-  shutdown(): Promise<void>;
-}
+// Types
+export type {
+  Agent,
+  AgentContext,
+  ContextManager,
+  CoordinatorOptions,
+  CoordinatorStats,
+  Logger,
+  LogLevel,
+  Message,
+  MessageType,
+  Task,
+  TaskStatus,
+} from './types';
diff --git a/packages/subagents/src/planner/index.ts b/packages/subagents/src/planner/index.ts
@@ -1,43 +1,56 @@
-import type { Subagent, SubagentMessage, SubagentOptions } from '..';
-
-export class PlannerSubagent implements Subagent {
-  private name: string = '';
-  private capabilities: string[] = [];
-  private active: boolean = false;
-
-  async initialize(options: SubagentOptions): Promise<boolean> {
-    this.name = options.name;
-    this.capabilities = options.capabilities;
-    this.active = true;
-    return true;
+/**
+ * Planner Subagent = Prefrontal Cortex
+ * Plans and breaks down complex tasks (future implementation)
+ */
+
+import type { Agent, AgentContext, Message } from '../types';
+
+export class PlannerAgent implements Agent {
+  name: string = 'planner';
+  capabilities: string[] = ['plan', 'break-down-tasks'];
+
+  private context?: AgentContext;
+
+  async initialize(context: AgentContext): Promise<void> {
+    this.context = context;
+    this.name = context.agentName;
+    context.logger.info('Planner agent initialized');
   }
 
-  async handleMessage(message: SubagentMessage): Promise<SubagentMessage | null> {
-    if (!this.active) {
-      console.warn(`Planner subagent ${this.name} received message while inactive`);
-      return null;
+  async handleMessage(message: Message): Promise<Message | null> {
+    if (!this.context) {
+      throw new Error('Planner not initialized');
     }
 
-    if (message.type === 'request' && message.payload.action === 'plan') {
+    // TODO: Implement actual planning logic (ticket #8)
+    // For now, just acknowledge
+    this.context.logger.debug('Received message', { type: message.type });
+
+    if (message.type === 'request') {
       return {
+        id: `${message.id}-response`,
         type: 'response',
         sender: this.name,
         recipient: message.sender,
+        correlationId: message.id,
         payload: {
-          plan: [
-            { id: '1', task: 'Initial analysis', status: 'pending' },
-            { id: '2', task: 'Implementation plan', status: 'pending' },
-            { id: '3', task: 'Task breakdown', status: 'pending' },
-          ],
+          status: 'stub',
+          message: 'Planner stub - implementation pending',
         },
+        priority: message.priority,
         timestamp: Date.now(),
       };
     }
 
     return null;
   }
 
+  async healthCheck(): Promise<boolean> {
+    return !!this.context;
+  }
+
   async shutdown(): Promise<void> {
-    this.active = false;
+    this.context?.logger.info('Planner agent shutting down');
+    this.context = undefined;
   }
 }
diff --git a/packages/subagents/src/pr/index.ts b/packages/subagents/src/pr/index.ts
@@ -1,44 +1,56 @@
-import type { Subagent, SubagentMessage, SubagentOptions } from '..';
-
-export class PrSubagent implements Subagent {
-  private name: string = '';
-  private capabilities: string[] = [];
-  private active: boolean = false;
-
-  async initialize(options: SubagentOptions): Promise<boolean> {
-    this.name = options.name;
-    this.capabilities = options.capabilities;
-    this.active = true;
-    return true;
+/**
+ * PR/GitHub Subagent = Motor Cortex
+ * Manages GitHub PRs and issues (future implementation)
+ */
+
+import type { Agent, AgentContext, Message } from '../types';
+
+export class PrAgent implements Agent {
+  name: string = 'pr';
+  capabilities: string[] = ['create-pr', 'update-pr', 'manage-issues', 'comment'];
+
+  private context?: AgentContext;
+
+  async initialize(context: AgentContext): Promise<void> {
+    this.context = context;
+    this.name = context.agentName;
+    context.logger.info('PR agent initialized');
   }
 
-  async handleMessage(message: SubagentMessage): Promise<SubagentMessage | null> {
-    if (!this.active) {
-      console.warn(`PR subagent ${this.name} received message while inactive`);
-      return null;
+  async handleMessage(message: Message): Promise<Message | null> {
+    if (!this.context) {
+      throw new Error('PR agent not initialized');
     }
 
-    if (message.type === 'request' && message.payload.action === 'createPR') {
-      // This will use GitHub CLI in the real implementation
+    // TODO: Implement actual GitHub integration logic (ticket #10)
+    // For now, just acknowledge
+    this.context.logger.debug('Received message', { type: message.type });
+
+    if (message.type === 'request') {
       return {
+        id: `${message.id}-response`,
         type: 'response',
         sender: this.name,
         recipient: message.sender,
+        correlationId: message.id,
         payload: {
-          success: true,
-          prNumber: 123,
-          url: 'https://github.com/org/repo/pull/123',
-          title: message.payload.title || 'Automated PR',
-          description: message.payload.description || 'PR created by dev-agent',
+          status: 'stub',
+          message: 'PR agent stub - implementation pending',
         },
+        priority: message.priority,
         timestamp: Date.now(),
       };
     }
 
     return null;
   }
 
+  async healthCheck(): Promise<boolean> {
+    return !!this.context;
+  }
+
   async shutdown(): Promise<void> {
-    this.active = false;
+    this.context?.logger.info('PR agent shutting down');
+    this.context = undefined;
   }
 }
