@haoyiyin/workflow 0.2.11 → 0.3.1

package/src/skills/index.ts

@@ -11,3 +11,4 @@ export { reviewDiffSkill, ReviewDiffSkill } from './review-diff/index.js'
 export { tddSkill, TDDSkill } from './tdd/index.js'
 export { systematicDebuggingSkill, SystematicDebuggingSkill } from './systematic-debugging/index.js'
 export { agentsMdSkill, AgentsMdSkill } from './agents-md/index.js'
+export { routerSkill, RouterSkill } from './router/index.js'

package/src/skills/quick-task/index.ts

@@ -134,7 +134,7 @@ export class QuickTaskSkill extends Skill<QuickTaskInput, QuickTaskOutput> {
     context: SkillContext,
   ): Promise<QuickTaskOutput> {
     const { config, logger } = context
-    const dispatcher = createDispatcher(logger)
+    const dispatcher = createDispatcher({ logger })
     const guard = createMainAgentGuard({}, logger)
     let totalTokens = 0
 

package/src/skills/review-diff/index.ts

@@ -213,7 +213,7 @@ export class ReviewDiffSkill extends Skill<ReviewDiffInput, ReviewDiffOutput> {
     context: SkillContext,
   ): Promise<ReviewDiffOutput> {
     const { config, logger } = context
-    const dispatcher = createDispatcher(logger)
+    const dispatcher = createDispatcher({ logger })
     const guard = createMainAgentGuard({}, logger)
 
     guard.activateEmbargo()

package/src/skills/router/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: router
+description: |
+  Universal entry point for ALL user messages. Routes questions, commands, requests, tasks — anything the user says.
+  Examples: "fix typo", "plan feature", "what's the weather", "debug error", "review PR", "implement auth", "rename file", "hello", "help".
+  Handles: planning, coding, debugging, reviewing, researching, quick tasks, TDD, documentation.
+  Always trigger this skill for any chat message, question, or command.
+requires: []
+---
+
+## Purpose
+
+Router is the **mandatory entry point** for ALL user requests. It dispatches to the correct target skill via 5-layer GSD routing.
+
+---
+
+## 5-Layer GSD Routing
+
+### Layer 1: State Check
+- Read `.pi/state/STATE.md` for current workflow state
+- Phase: `idle`, `planning`, `executing`, `verifying`, `completed`, `failed`
+
+### Layer 2: Lifecycle Gate
+- Check PLAN.md existence and status
+- If plan exists → execute-plan
+- If no plan + complex request → to-plan
+
+### Layer 3: Intent Classification
+| Signal | Target |
+|--------|--------|
+| plan, design, architecture | to-plan |
+| implement, execute, build | execute-plan |
+| fix typo, rename, quick | quick-task |
+| bug, error, failing | systematic-debugging |
+| review, audit | review-diff |
+| test, TDD | tdd |
+| weather, time, price, search, question | quick-task |
+
+### Layer 4: Semantic Analysis
+- Trivial (<30 chars, single change) → quick-task
+- Complex (multi-file, architectural) → to-plan
+
+### Layer 5: Confidence
+- >0.8 → route directly
+- <0.5 → to-plan (exploration)
+
+---
+
+## Target Skills
+
+| Skill | When |
+|-------|------|
+| to-plan | Complex feature, unknown scope |
+| execute-plan | Active plan exists |
+| quick-task | Trivial change, questions, search |
+| review-diff | Code review |
+| systematic-debugging | Bug investigation |
+| tdd | Test-first development |
+| agents-md | Documentation |
+
+---
+
+## Workflow
+
+```
+User Request → Router (this skill)
+  ↓ reads STATE.md + PLAN.md
+  ↓ 5-layer routing
+  ↓ returns { targetSkill, confidence, reasoning }
+```
+
+---
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| STATE.md missing | Assume idle phase |
+| PLAN.md missing | Assume planning needed |
+| Router fails | Default to quick-task |
+| Confidence <0.3 | Route to to-plan |

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