@haoyiyin/workflow 0.2.10 → 0.3.0

package/src/skills/router/index.ts

@@ -0,0 +1,577 @@
+/**
+ * Router Skill - 5-Layer Routing Logic
+ *
+ * Layer 1: Parse & Classify - Extract intent and entities from user request
+ * Layer 2: State-Aware Scoring - Factor in project phase and execution state
+ * Layer 3: Skill Matching - Score each skill against request and state
+ * Layer 4: Confidence Calibration - Adjust scores based on history and context
+ * Layer 5: Selection & Output - Return structured routing decision
+ *
+ * This skill reads from STATE.md and PLAN.md to make context-aware decisions.
+ */
+
+import { z } from 'zod'
+import { Skill } from '../skill.js'
+import type { SkillContext } from '../types.js'
+import { StateMdManager } from '../../persistence/state-md.js'
+import { PlanMdManager } from '../../persistence/plan-md.js'
+import { createDispatcher } from '../../agents/dispatcher.js'
+import type { SubagentConfig, SubagentContract, SubagentResult } from '../../agents/types.js'
+import type { WorkflowState } from '../../persistence/types.js'
+import type { RouterInput, RouterOutput, ProjectState, ProjectPhase, RoutingAlternative } from './types.js'
+
+// ---------------------------------------------------------------------------
+// Schemas
+// ---------------------------------------------------------------------------
+
+const ConversationHistoryItemSchema = z.object({
+  role: z.enum(['user', 'assistant']),
+  content: z.string(),
+})
+
+const RouterInputSchema = z.object({
+  userRequest: z.string().min(1, 'User request is required'),
+  conversationHistory: z.array(ConversationHistoryItemSchema).optional(),
+})
+
+const RouterOutputSchema = z.object({
+  selectedSkill: z.string(),
+  confidence: z.number().min(0).max(1),
+  reasoning: z.string(),
+  projectState: z.object({
+    phase: z.enum(['discovery', 'planning', 'execution', 'verification', 'completed', 'idle']),
+    hasPlan: z.boolean(),
+    isExecuting: z.boolean(),
+    completedTasks: z.number(),
+    totalTasks: z.number(),
+  }),
+})
+
+type RouterInputType = z.infer<typeof RouterInputSchema>
+type RouterOutputType = z.infer<typeof RouterOutputSchema>
+
+// ---------------------------------------------------------------------------
+// 5-Layer Router Types
+// ---------------------------------------------------------------------------
+
+interface Layer1Classification {
+  intent: string
+  entities: string[]
+  complexity: 'low' | 'medium' | 'high'
+  urgency: 'low' | 'medium' | 'high'
+}
+
+interface Layer2StateFactors {
+  phaseWeight: number
+  executionWeight: number
+  completionWeight: number
+}
+
+interface Layer3SkillScore {
+  skillName: string
+  baseScore: number
+  stateAdjustedScore: number
+  matches: string[]
+}
+
+interface Layer4Calibration {
+  confidenceAdjustment: number
+  historyBonus: number
+  contextPenalty: number
+}
+
+interface Layer5Decision {
+  selectedSkill: string
+  finalConfidence: number
+  reasoning: string
+  alternatives: RoutingAlternative[]
+}
+
+// ---------------------------------------------------------------------------
+// Available Skills by Phase
+// ---------------------------------------------------------------------------
+
+const SKILLS_BY_PHASE: Record<ProjectPhase, string[]> = {
+  discovery: ['to-plan', 'research', 'agents-md'],
+  planning: ['to-plan', 'research', 'review-diff'],
+  execution: ['execute-plan', 'quick-task', 'tdd', 'systematic-debugging'],
+  verification: ['review-diff', 'systematic-debugging', 'agents-md'],
+  completed: ['review-diff', 'agents-md', 'research'],
+  idle: ['to-plan', 'research', 'quick-task', 'agents-md'],
+}
+
+// ---------------------------------------------------------------------------
+// Prompt Builders for Subagent
+// ---------------------------------------------------------------------------
+
+function buildLayer1Prompt(userRequest: string, history: Array<{ role: 'user' | 'assistant'; content: string }> | undefined): string {
+  const historyBlock = history && history.length > 0
+    ? `## Conversation History\n${history.map(h => `${h.role}: ${h.content}`).join('\n')}\n`
+    : ''
+
+  return [
+    '## Layer 1: Parse & Classify',
+    '',
+    'Analyze the user request and extract structured information.',
+    '',
+    '**User Request**:',
+    userRequest,
+    '',
+    historyBlock,
+    '## Output Format (JSON)',
+    '',
+    '```json',
+    '{',
+    '  "intent": "primary intent category (plan, execute, debug, review, research, quick-task)",',
+    '  "entities": ["file paths mentioned", "concepts", "technologies"],',
+    '  "complexity": "low|medium|high",',
+    '  "urgency": "low|medium|high"',
+    '}',
+    '```',
+  ].join('\n')
+}
+
+function buildLayer3Prompt(
+  classification: Layer1Classification,
+  projectState: ProjectState,
+  availableSkills: string[],
+): string {
+  return [
+    '## Layer 3: Skill Matching',
+    '',
+    'Score each available skill based on how well it matches the request and project state.',
+    '',
+    '**Request Classification**:',
+    `- Intent: ${classification.intent}`,
+    `- Entities: ${classification.entities.join(', ') || 'none'}`,
+    `- Complexity: ${classification.complexity}`,
+    `- Urgency: ${classification.urgency}`,
+    '',
+    '**Project State**:',
+    `- Phase: ${projectState.phase}`,
+    `- Has Plan: ${projectState.hasPlan}`,
+    `- Is Executing: ${projectState.isExecuting}`,
+    `- Progress: ${projectState.completedTasks}/${projectState.totalTasks} tasks`,
+    '',
+    '**Available Skills**:',
+    availableSkills.map(s => `- ${s}`).join('\n'),
+    '',
+    '## Output Format (JSON)',
+    '',
+    '```json',
+    '{',
+    '  "scores": [',
+    '    { "skillName": "skill-name", "baseScore": 0.85, "matches": ["reason1", "reason2"] }',
+    '  ]',
+    '}',
+    '```',
+  ].join('\n')
+}
+
+function buildLayer5Prompt(
+  calibratedScores: Layer3SkillScore[],
+  projectState: ProjectState,
+): string {
+  return [
+    '## Layer 5: Selection & Output',
+    '',
+    'Make the final routing decision based on calibrated scores and project state.',
+    '',
+    '**Calibrated Scores**:',
+    calibratedScores.map(s => `- ${s.skillName}: ${s.stateAdjustedScore.toFixed(2)}`).join('\n'),
+    '',
+    '**Project State**:',
+    `- Phase: ${projectState.phase}`,
+    `- Has Plan: ${projectState.hasPlan}`,
+    `- Is Executing: ${projectState.isExecuting}`,
+    '',
+    '## Output Format (JSON)',
+    '',
+    '```json',
+    '{',
+    '  "selectedSkill": "skill-name",',
+    '  "finalConfidence": 0.92,',
+    '  "reasoning": "Detailed explanation of why this skill was selected",',
+    '  "alternatives": [',
+    '    { "skill": "other-skill", "confidence": 0.65, "reasoning": "Why it was considered" }',
+    '  ]',
+    '}',
+    '```',
+  ].join('\n')
+}
+
+// ---------------------------------------------------------------------------
+// Parsing Helpers
+// ---------------------------------------------------------------------------
+
+function parseLayer1Output(output: string): Layer1Classification {
+  const jsonMatch = output.match(/```json\s*([\s\S]*?)\s*```/)
+  if (jsonMatch) {
+    try {
+      const parsed = JSON.parse(jsonMatch[1].trim())
+      return {
+        intent: parsed.intent || 'general',
+        entities: Array.isArray(parsed.entities) ? parsed.entities : [],
+        complexity: ['low', 'medium', 'high'].includes(parsed.complexity) ? parsed.complexity : 'medium',
+        urgency: ['low', 'medium', 'high'].includes(parsed.urgency) ? parsed.urgency : 'medium',
+      }
+    } catch {
+      // Fall through to defaults
+    }
+  }
+  return {
+    intent: 'general',
+    entities: [],
+    complexity: 'medium',
+    urgency: 'medium',
+  }
+}
+
+function parseLayer3Output(output: string): Layer3SkillScore[] {
+  const jsonMatch = output.match(/```json\s*([\s\S]*?)\s*```/)
+  if (jsonMatch) {
+    try {
+      const parsed = JSON.parse(jsonMatch[1].trim())
+      if (Array.isArray(parsed.scores)) {
+        return parsed.scores.map((s: { skillName?: string; baseScore?: number; matches?: string[] }) => ({
+          skillName: s.skillName || 'unknown',
+          baseScore: s.baseScore || 0,
+          stateAdjustedScore: s.baseScore || 0,
+          matches: Array.isArray(s.matches) ? s.matches : [],
+        }))
+      }
+    } catch {
+      // Fall through
+    }
+  }
+  return []
+}
+
+function parseLayer5Output(output: string): Layer5Decision {
+  const jsonMatch = output.match(/```json\s*([\s\S]*?)\s*```/)
+  if (jsonMatch) {
+    try {
+      const parsed = JSON.parse(jsonMatch[1].trim())
+      return {
+        selectedSkill: parsed.selectedSkill || 'quick-task',
+        finalConfidence: parsed.finalConfidence || 0.5,
+        reasoning: parsed.reasoning || 'No reasoning provided',
+        alternatives: Array.isArray(parsed.alternatives) ? parsed.alternatives : [],
+      }
+    } catch {
+      // Fall through to defaults
+    }
+  }
+  return {
+    selectedSkill: 'quick-task',
+    finalConfidence: 0.5,
+    reasoning: 'Failed to parse decision, defaulting to quick-task',
+    alternatives: [],
+  }
+}
+
+// ---------------------------------------------------------------------------
+// State Mapping Helpers
+// ---------------------------------------------------------------------------
+
+function mapWorkflowPhaseToProjectPhase(phase: WorkflowState['phase']): ProjectPhase {
+  switch (phase) {
+    case 'planning':
+      return 'planning'
+    case 'executing':
+      return 'execution'
+    case 'verifying':
+      return 'verification'
+    case 'completed':
+      return 'completed'
+    default:
+      return 'idle'
+  }
+}
+
+function buildProjectState(
+  workflowState: WorkflowState,
+  hasPlan: boolean,
+): ProjectState {
+  return {
+    phase: mapWorkflowPhaseToProjectPhase(workflowState.phase),
+    hasPlan,
+    isExecuting: workflowState.phase === 'executing',
+    completedTasks: workflowState.completedTasks?.length || 0,
+    totalTasks: workflowState.totalTasks || 0,
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Layer 2: State-Aware Scoring (Pure Function)
+// ---------------------------------------------------------------------------
+
+function calculateStateFactors(
+  classification: Layer1Classification,
+  projectState: ProjectState,
+): Layer2StateFactors {
+  let phaseWeight = 1.0
+  let executionWeight = 1.0
+  let completionWeight = 1.0
+
+  // Adjust based on phase
+  switch (projectState.phase) {
+    case 'planning':
+      phaseWeight = classification.intent === 'plan' ? 1.5 : 0.8
+      break
+    case 'execution':
+      phaseWeight = classification.intent === 'execute' ? 1.5 : 0.9
+      break
+    case 'verification':
+      phaseWeight = classification.intent === 'review' ? 1.5 : 0.8
+      break
+    case 'completed':
+      phaseWeight = classification.intent === 'research' ? 1.2 : 1.0
+      break
+  }
+
+  // Adjust based on execution state
+  if (projectState.isExecuting && classification.intent === 'execute') {
+    executionWeight = 1.3
+  }
+
+  // Adjust based on completion progress
+  const progressRatio = projectState.totalTasks > 0
+    ? projectState.completedTasks / projectState.totalTasks
+    : 0
+  completionWeight = 0.8 + (0.4 * progressRatio)
+
+  return {
+    phaseWeight,
+    executionWeight,
+    completionWeight,
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Layer 4: Confidence Calibration (Pure Function)
+// ---------------------------------------------------------------------------
+
+function calibrateConfidence(
+  scores: Layer3SkillScore[],
+  stateFactors: Layer2StateFactors,
+  classification: Layer1Classification,
+): Layer3SkillScore[] {
+  const totalWeight = stateFactors.phaseWeight * stateFactors.executionWeight * stateFactors.completionWeight
+
+  return scores.map((score) => {
+    // Apply state-based adjustment
+    let adjustedScore = score.baseScore * totalWeight
+
+    // Boost for high urgency
+    if (classification.urgency === 'high' && score.skillName === 'quick-task') {
+      adjustedScore *= 1.2
+    }
+
+    // Cap at 1.0
+    adjustedScore = Math.min(adjustedScore, 1.0)
+
+    return {
+      ...score,
+      stateAdjustedScore: adjustedScore,
+    }
+  })
+}
+
+// ---------------------------------------------------------------------------
+// Router Skill Class
+// ---------------------------------------------------------------------------
+
+export class RouterSkill extends Skill<RouterInputType, RouterOutputType> {
+  private stateManager: StateMdManager
+  private planManager: PlanMdManager
+
+  constructor(statePath = '.pi/state/STATE.md', planPath = '.pi/state/PLAN.md') {
+    super({
+      name: 'router',
+      description: '5-layer routing skill that selects the appropriate skill based on user request and project state',
+      requires: [],
+      inputSchema: RouterInputSchema,
+      outputSchema: RouterOutputSchema,
+    })
+    this.stateManager = new StateMdManager(statePath)
+    this.planManager = new PlanMdManager(planPath)
+  }
+
+  /**
+   * Get available skills for the current project phase
+   */
+  getAvailableSkillsForPhase(phase: ProjectPhase): string[] {
+    return [...(SKILLS_BY_PHASE[phase] || SKILLS_BY_PHASE.idle)]
+  }
+
+  async execute(input: RouterInputType, context: SkillContext): Promise<RouterOutputType> {
+    const { logger, config } = context
+    const dispatcher = createDispatcher({ logger })
+    const model = config.defaultModel || 'glm-5'
+
+    logger.info('[router] Starting 5-layer routing process')
+
+    // -----------------------------------------------------------------------
+    // Read Project State (STATE.md and PLAN.md)
+    // -----------------------------------------------------------------------
+
+    let workflowState: WorkflowState
+    let hasPlan = false
+
+    try {
+      workflowState = await this.stateManager.readCurrentState()
+      logger.info(`[router] Read workflow state: phase=${workflowState.phase}`)
+    } catch (error) {
+      logger.warn('[router] No existing workflow state, using defaults')
+      workflowState = {
+        goal: '',
+        phase: 'planning',
+        startedAt: new Date().toISOString(),
+        lastUpdated: new Date().toISOString(),
+        completedTasks: [],
+        failedTasks: [],
+        totalTasks: 0,
+        tokenUsage: { used: 0, limit: 1000000, percentage: 0 },
+      }
+    }
+
+    try {
+      await this.planManager.readPlan()
+      hasPlan = true
+      logger.info('[router] Plan file exists')
+    } catch {
+      logger.info('[router] No plan file found')
+    }
+
+    const projectState = buildProjectState(workflowState, hasPlan)
+    const availableSkills = this.getAvailableSkillsForPhase(projectState.phase)
+
+    logger.info(`[router] Available skills for ${projectState.phase}: ${availableSkills.join(', ')}`)
+
+    // -----------------------------------------------------------------------
+    // Layer 1: Parse & Classify (Dispatch subagent)
+    // -----------------------------------------------------------------------
+
+    logger.info('[router] Layer 1: Parsing and classifying request')
+
+    const layer1Config: SubagentConfig = {
+      role: 'explorer',
+      model,
+      tokenBudget: 8000,
+    }
+
+    const layer1Contract: SubagentContract = {
+      permissions: {
+        readFiles: false,
+        searchCode: false,
+        runCommands: false,
+        writeFiles: false,
+        gitOperations: false,
+      },
+      prompt: buildLayer1Prompt(input.userRequest, (input.conversationHistory ?? []) as Array<{ role: 'user' | 'assistant'; content: string }>),
+      owns: [],
+      reads: [],
+    }
+
+    const layer1Result = await dispatcher.dispatch(layer1Config, layer1Contract)
+    const classification = parseLayer1Output(layer1Result.output)
+
+    logger.info(`[router] Layer 1 complete: intent=${classification.intent}, complexity=${classification.complexity}`)
+
+    // -----------------------------------------------------------------------
+    // Layer 2: State-Aware Scoring (Pure function)
+    // -----------------------------------------------------------------------
+
+    logger.info('[router] Layer 2: Calculating state factors')
+
+    const stateFactors = calculateStateFactors(classification, projectState)
+
+    logger.info(`[router] State factors: phase=${stateFactors.phaseWeight.toFixed(2)}, execution=${stateFactors.executionWeight.toFixed(2)}`)
+
+    // -----------------------------------------------------------------------
+    // Layer 3: Skill Matching (Dispatch subagent)
+    // -----------------------------------------------------------------------
+
+    logger.info('[router] Layer 3: Matching skills')
+
+    const layer3Config: SubagentConfig = {
+      role: 'planner',
+      model,
+      tokenBudget: 10000,
+    }
+
+    const layer3Contract: SubagentContract = {
+      permissions: {
+        readFiles: false,
+        searchCode: false,
+        runCommands: false,
+        writeFiles: false,
+        gitOperations: false,
+      },
+      prompt: buildLayer3Prompt(classification, projectState, availableSkills),
+      owns: [],
+      reads: [],
+    }
+
+    const layer3Result = await dispatcher.dispatch(layer3Config, layer3Contract)
+    const skillScores = parseLayer3Output(layer3Result.output)
+
+    logger.info(`[router] Layer 3 complete: ${skillScores.length} skills scored`)
+
+    // -----------------------------------------------------------------------
+    // Layer 4: Confidence Calibration (Pure function)
+    // -----------------------------------------------------------------------
+
+    logger.info('[router] Layer 4: Calibrating confidence')
+
+    const calibratedScores = calibrateConfidence(skillScores, stateFactors, classification)
+
+    logger.info(`[router] Layer 4 complete: top score = ${Math.max(...calibratedScores.map(s => s.stateAdjustedScore)).toFixed(2)}`)
+
+    // -----------------------------------------------------------------------
+    // Layer 5: Selection & Output (Dispatch subagent)
+    // -----------------------------------------------------------------------
+
+    logger.info('[router] Layer 5: Making final selection')
+
+    const layer5Config: SubagentConfig = {
+      role: 'planner',
+      model,
+      tokenBudget: 8000,
+    }
+
+    const layer5Contract: SubagentContract = {
+      permissions: {
+        readFiles: false,
+        searchCode: false,
+        runCommands: false,
+        writeFiles: false,
+        gitOperations: false,
+      },
+      prompt: buildLayer5Prompt(calibratedScores, projectState),
+      owns: [],
+      reads: [],
+    }
+
+    const layer5Result = await dispatcher.dispatch(layer5Config, layer5Contract)
+    const decision = parseLayer5Output(layer5Result.output)
+
+    logger.info(`[router] Layer 5 complete: selected=${decision.selectedSkill}, confidence=${decision.finalConfidence.toFixed(2)}`)
+
+    // -----------------------------------------------------------------------
+    // Return Structured Output
+    // -----------------------------------------------------------------------
+
+    return {
+      selectedSkill: decision.selectedSkill,
+      confidence: decision.finalConfidence,
+      reasoning: decision.reasoning,
+      projectState,
+    }
+  }
+}
+
+// Singleton instance
+export const routerSkill = new RouterSkill()
+export default routerSkill

package/src/skills/router/types.ts

@@ -0,0 +1,90 @@
+/**
+ * Router Skill Types
+ *
+ * Type definitions for the router skill that determines which skill
+ * should handle a given user request based on conversation context.
+ */
+
+/**
+ * Input to the router skill
+ */
+export interface RouterInput {
+  /** The user's current request/message */
+  userRequest: string;
+  /** Optional conversation history for context */
+  conversationHistory?: Array<{
+    role: 'user' | 'assistant';
+    content: string;
+  }>;
+}
+
+/**
+ * Project lifecycle phases
+ */
+export type ProjectPhase =
+  | 'discovery'
+  | 'planning'
+  | 'execution'
+  | 'verification'
+  | 'completed'
+  | 'idle';
+
+/**
+ * Current state of the project being worked on
+ */
+export interface ProjectState {
+  /** Current phase of the project lifecycle */
+  phase: ProjectPhase;
+  /** Whether a plan has been created */
+  hasPlan: boolean;
+  /** Whether execution is currently in progress */
+  isExecuting: boolean;
+  /** Number of completed tasks */
+  completedTasks: number;
+  /** Total number of tasks in the plan */
+  totalTasks: number;
+}
+
+/**
+ * Output from the router skill
+ */
+export interface RouterOutput {
+  /** The skill selected to handle the request */
+  selectedSkill: string;
+  /** Confidence score (0-1) in the selection */
+  confidence: number;
+  /** Explanation of why this skill was selected */
+  reasoning: string;
+  /** Current project state at time of routing */
+  projectState: ProjectState;
+}
+
+/**
+ * Alternative skill that could have been selected
+ */
+export interface RoutingAlternative {
+  /** Name of the alternative skill */
+  skill: string;
+  /** Confidence score for this alternative */
+  confidence: number;
+  /** Why this skill was considered */
+  reasoning: string;
+}
+
+/**
+ * Complete routing decision with full context
+ */
+export interface RoutingDecision {
+  /** The selected target skill */
+  targetSkill: string;
+  /** Confidence score (0-1) in the decision */
+  confidence: number;
+  /** Detailed reasoning for the selection */
+  reasoning: string;
+  /** Whether project state was used in the decision */
+  stateUsed: boolean;
+  /** Current lifecycle phase when decision was made */
+  lifecyclePhase: ProjectPhase;
+  /** Alternative skills that were considered */
+  alternatives: RoutingAlternative[];
+}

package/src/skills/systematic-debugging/index.ts

@@ -235,7 +235,7 @@ export class SystematicDebuggingSkill extends Skill<DebugInput, DebugOutput> {
     context: SkillContext,
   ): Promise<DebugOutput> {
     const { config, logger } = context
-    const dispatcher = createDispatcher(logger)
+    const dispatcher = createDispatcher({ logger })
     const guard = createMainAgentGuard({}, logger)
     let totalTokens = 0
 

package/src/skills/tdd/index.ts

@@ -190,7 +190,7 @@ export class TDDSkill extends Skill<TDDInput, TDDOutput> {
     context: SkillContext,
   ): Promise<TDDOutput> {
     const { config, logger } = context
-    const dispatcher = createDispatcher(logger)
+    const dispatcher = createDispatcher({ logger })
     const guard = createMainAgentGuard({}, logger)
 
     const phases: PhaseResult[] = []