@haoyiyin/workflow 0.2.0 → 0.2.3

package/src/skills/to-plan/index-enhanced.ts

@@ -0,0 +1,551 @@
+/**
+ * Enhanced Plan Skill - Orchestrates analysis, debugging, and planning
+ *
+ * Architecture: Orchestrator pattern
+ * - Analyzes input to determine what preprocessing is needed
+ * - May spawn debugging subagent for bug investigation
+ * - Delegates actual planning to planner subagent
+ * - Wave grouping and validation
+ *
+ * Examples:
+ *   "/to-plan 实现登录功能" → Direct planning
+ *   "/to-plan 出现xxbug，查明原因并制定计划" → Debug → Plan
+ *   "/to-plan 性能问题，先分析再计划" → Explore → Plan
+ */
+import { z } from 'zod'
+import { Skill } from '../skill.js'
+import type { SkillContext } from '../types.js'
+import type { Plan, Task, Wave } from '../../persistence/types.js'
+// HookType constants
+const HookType = {
+  PRE_PLAN: 'pre-plan',
+  POST_PLAN: 'post-plan',
+  ON_ERROR: 'on-error',
+} as const
+
+const PlanInputSchema = z.object({
+  goal: z.string(),
+  constraints: z.array(z.string()).optional(),
+  model: z.string().optional(),
+  previousIssues: z.array(z.string()).optional(),
+  // Analysis hints
+  symptom: z.string().optional(),           // Bug symptom
+  reproduceCommand: z.string().optional(), // How to reproduce
+  logs: z.string().optional(),              // Error logs
+  recentChanges: z.string().optional(),     // Recent git changes
+})
+
+const PlanOutputSchema = z.object({
+  plan: z.custom<Plan>(),
+  waves: z.array(z.custom<Wave>()),
+  // If debugging was performed
+  rootCause: z.string().optional(),
+  confidence: z.enum(['high', 'medium', 'low']).optional(),
+  // Metadata
+  analysisPerformed: z.boolean(),
+  tokensUsed: z.number()
+})
+
+type PlanInput = z.infer<typeof PlanInputSchema>
+type PlanOutput = z.infer<typeof PlanOutputSchema>
+
+export class ToPlanSkill extends Skill<PlanInput, PlanOutput> {
+  protected name = 'to-plan'
+  protected description = 'Orchestrates analysis, debugging, and planning with fresh-context subagents'
+  protected requires = ['systematic-debugging', 'quick-task']
+
+  async execute(input: PlanInput, context: SkillContext): Promise<PlanOutput> {
+    let analysisPerformed = false
+    let rootCause: string | undefined
+    let confidence: 'high' | 'medium' | 'low' | undefined
+    let tokensUsed = 0
+
+    // 1. Initialize persistence
+    if (context.persistence) {
+      await context.persistence.state.initialize(input.goal)
+    }
+
+    // 2. Trigger pre-plan hooks
+    await this.triggerHook(context, HookType.PRE_PLAN, { goal: input.goal })
+
+    try {
+      // 3. Analyze input and determine workflow
+      const analysis = this.analyzeInput(input)
+      console.log(`[ToPlanSkill] Analysis: ${analysis.type}`)
+
+      // 4. Perform preprocessing if needed
+      let enrichedGoal = input.goal
+
+      if (analysis.needsDebugging) {
+        console.log('[ToPlanSkill] Bug detected, running systematic debugging...')
+
+        // Use systematic-debugging skill
+        const debugResult = await this.runDebugging(input, context)
+
+        analysisPerformed = true
+        rootCause = debugResult.rootCause
+        confidence = debugResult.confidence
+        tokensUsed += debugResult.tokensUsed
+
+        // Enrich goal with root cause
+        enrichedGoal = `${input.goal}\n\nRoot Cause (confidence: ${confidence}): ${rootCause}`
+
+        console.log(`[ToPlanSkill] Debug complete: ${rootCause.slice(0, 100)}...`)
+      }
+
+      if (analysis.needsExploration) {
+        console.log('[ToPlanSkill] Exploration needed, gathering context...')
+
+        // Run exploration
+        const exploreResult = await this.runExploration(input, context)
+        tokensUsed += exploreResult.tokensUsed
+
+        // Enrich goal with findings
+        enrichedGoal = `${enrichedGoal}\n\nContext: ${exploreResult.findings}`
+
+        analysisPerformed = true
+      }
+
+      // 5. Generate plan with planner subagent
+      console.log('[ToPlanSkill] Generating plan...')
+      const planResult = await this.spawnPlannerSubagent(
+        { ...input, goal: enrichedGoal },
+        context
+      )
+      tokensUsed += planResult.tokensUsed
+
+      // 6. Parse and validate plan
+      let plan = this.parsePlanResponse(planResult.output)
+      let validation = this.validatePlan(plan)
+
+      // 7. Retry once if validation fails
+      if (!validation.valid && !input.previousIssues) {
+        console.log('[ToPlanSkill] Validation failed, retrying with feedback...')
+        const retryResult = await this.spawnPlannerSubagent(
+          {
+            ...input,
+            goal: enrichedGoal,
+            previousIssues: validation.issues
+          },
+          context
+        )
+        tokensUsed += retryResult.tokensUsed
+        plan = this.parsePlanResponse(retryResult.output)
+        validation = this.validatePlan(plan)
+      }
+
+      // 8. Group tasks into waves
+      const waves = this.groupIntoWaves(plan)
+      plan.waves = waves
+
+      // 9. Write to persistence
+      if (context.persistence) {
+        await context.persistence.plan.writePlan(plan)
+        await context.persistence.state.recordPlan(plan)
+        await context.persistence.state.updatePhase('planning')
+      }
+
+      // 10. Trigger post-plan hooks
+      await this.triggerHook(context, HookType.POST_PLAN, {
+        plan,
+        waves,
+        analysisPerformed,
+        rootCause
+      })
+
+      return {
+        plan,
+        waves,
+        rootCause,
+        confidence,
+        analysisPerformed,
+        tokensUsed
+      }
+
+    } catch (error) {
+      await this.triggerHook(context, HookType.ON_ERROR, {
+        phase: 'plan',
+        error: (error as Error).message
+      })
+      throw error
+    }
+  }
+
+  /**
+   * Analyze input to determine what preprocessing is needed
+   */
+  private analyzeInput(input: PlanInput): {
+    type: 'direct' | 'bug' | 'exploration' | 'combined'
+    needsDebugging: boolean
+    needsExploration: boolean
+  } {
+    const goal = input.goal.toLowerCase()
+
+    // Bug indicators
+    const bugPatterns = [
+      /bug|错误|故障|崩溃|crash|exception|error/i,
+      /查明原因|调查|定位|诊断|debug|fix/i,
+      /出现.*问题|发生.*错误|不工作|失败|fail/i
+    ]
+
+    // Exploration indicators
+    const explorePatterns = [
+      /分析.*代码|了解.*架构|探索|调研/i,
+      /refactor|重构.*前/i,
+      /不熟悉|不清楚|unknown/i
+    ]
+
+    const hasBugKeywords = bugPatterns.some(p => p.test(goal))
+    const hasExploreKeywords = explorePatterns.some(p => p.test(goal))
+
+    // Explicit symptom provided
+    const hasSymptom = !!input.symptom || !!input.logs || !!input.reproduceCommand
+
+    const needsDebugging = hasBugKeywords || hasSymptom
+    const needsExploration = hasExploreKeywords
+
+    if (needsDebugging && needsExploration) {
+      return { type: 'combined', needsDebugging: true, needsExploration: true }
+    } else if (needsDebugging) {
+      return { type: 'bug', needsDebugging: true, needsExploration: false }
+    } else if (needsExploration) {
+      return { type: 'exploration', needsDebugging: false, needsExploration: true }
+    } else {
+      return { type: 'direct', needsDebugging: false, needsExploration: false }
+    }
+  }
+
+  /**
+   * Run systematic debugging using debugging skill
+   */
+  private async runDebugging(
+    input: PlanInput,
+    context: SkillContext
+  ): Promise<{
+    rootCause: string
+    confidence: 'high' | 'medium' | 'low'
+    tokensUsed: number
+  }> {
+    // Try to use systematic-debugging skill if available
+    const debugSkill = context.skills.get('systematic-debugging')
+
+    if (debugSkill) {
+      console.log('[ToPlanSkill] Using systematic-debugging skill')
+      const result = await debugSkill.execute({
+        symptom: input.symptom || input.goal,
+        reproduceCommand: input.reproduceCommand,
+        logs: input.logs,
+        recentChanges: input.recentChanges,
+        model: input.model
+      }, context)
+
+      return {
+        rootCause: result.rootCause,
+        confidence: result.confidence,
+        tokensUsed: result.tokensUsed
+      }
+    }
+
+    // Fallback: direct dispatcher
+    console.log('[ToPlanSkill] Fallback: direct debugging subagent')
+    const result = await context.dispatcher.dispatch<{
+      rootCause: string
+      confidence: 'high' | 'medium' | 'low'
+      tokensUsed: number
+    }>({
+      role: 'debugger',
+      model: input.model,
+      timeout: 180000
+    }, {
+      permissions: {
+        readFiles: true,
+        searchCode: true,
+        runCommands: true,
+        writeFiles: false,
+        gitOperations: false
+      },
+      prompt: this.buildDebuggingPrompt(input),
+      owns: [],
+      reads: []
+    })
+
+    return result
+  }
+
+  /**
+   * Run exploration to gather context
+   */
+  private async runExploration(
+    input: PlanInput,
+    context: SkillContext
+  ): Promise<{
+    findings: string
+    tokensUsed: number
+  }> {
+    const result = await context.dispatcher.dispatch<{
+      findings: string
+      tokensUsed: number
+    }>({
+      role: 'explorer',
+      model: input.model,
+      timeout: 120000
+    }, {
+      permissions: {
+        readFiles: true,
+        searchCode: true,
+        runCommands: false,
+        writeFiles: false,
+        gitOperations: false
+      },
+      prompt: `# Exploration Task
+
+Goal: ${input.goal}
+
+Explore the codebase to understand:
+1. Overall architecture and structure
+2. Relevant files and patterns
+3. Dependencies and relationships
+4. Potential challenges or risks
+
+Return a concise summary (under 800 tokens) of key findings that will help with planning.`,
+      owns: [],
+      reads: []
+    })
+
+    return result
+  }
+
+  /**
+   * Spawn planner subagent with fresh context
+   */
+  private async spawnPlannerSubagent(
+    input: PlanInput,
+    context: SkillContext
+  ): Promise<{ output: string; tokensUsed: number }> {
+    const result = await context.dispatcher.dispatch<{ plan: string }>(
+      {
+        role: 'planner',
+        model: input.model,
+        timeout: 120000
+      },
+      {
+        permissions: {
+          readFiles: true,
+          searchCode: true,
+          runCommands: false,
+          writeFiles: false,
+          gitOperations: false
+        },
+        prompt: this.buildPlannerPrompt(input),
+        owns: [],
+        reads: []
+      }
+    )
+
+    return { output: result.plan, tokensUsed: 0 }
+  }
+
+  private buildDebuggingPrompt(input: PlanInput): string {
+    return `# Systematic Debugging
+
+## Symptom
+${input.symptom || input.goal}
+
+## Reproduction
+${input.reproduceCommand ? `Command: ${input.reproduceCommand}` : 'Reproduce the issue'}
+
+${input.logs ? `## Logs\n${input.logs.slice(0, 2000)}` : ''}
+
+${input.recentChanges ? `## Recent Changes\n${input.recentChanges}` : ''}
+
+## Instructions
+1. Reproduce the issue
+2. Gather evidence systematically
+3. Form and test hypotheses
+4. Identify root cause with confidence level
+5. Propose fix
+
+## Output Format
+{
+  "rootCause": "detailed description",
+  "confidence": "high|medium|low",
+  "location": { "file": "path", "line": 123, "function": "name" },
+  "proposedFix": "description",
+  "verification": "how to verify the fix"
+}`
+  }
+
+  private buildPlannerPrompt(input: PlanInput): string {
+    const issueSection = input.previousIssues
+      ? `\n\n## Previous Attempt Issues\n${input.previousIssues.map(i => `- ${i}`).join('\n')}\nPlease address these issues in your new plan.`
+      : ''
+
+    return `# Planning Task
+
+## Goal
+${input.goal}
+
+## Constraints
+${input.constraints?.map(c => `- ${c}`).join('\n') || '- No specific constraints'}
+${issueSection}
+
+## Instructions
+1. Break down into small, independent tasks (<50 lines of change each)
+2. Identify dependencies between tasks explicitly
+3. Group into parallel execution waves
+4. Define clear verification criteria
+5. If this is a bug fix, include regression tests
+
+## Output Format
+Return ONLY a JSON object:
+{
+  "goal": "original goal",
+  "tasks": [
+    {
+      "id": "task-1",
+      "description": "What to do",
+      "estimatedComplexity": "low|medium|high",
+      "relatedFiles": ["optional/path"],
+      "verificationCriteria": ["How to verify"]
+    }
+  ],
+  "dependencies": {"task-2": ["task-1"]},
+  "verificationCriteria": ["Overall acceptance criteria"],
+  "estimatedDuration": 300000,
+  "rationale": "Why this plan"
+}`
+  }
+
+  private parsePlanResponse(response: string): Plan {
+    try {
+      const jsonMatch = response.match(/\{[\s\S]*\}/)
+      const jsonStr = jsonMatch ? jsonMatch[0] : response
+      const parsed = JSON.parse(jsonStr)
+
+      return {
+        goal: parsed.goal || '',
+        tasks: parsed.tasks || [],
+        dependencies: parsed.dependencies || {},
+        waves: parsed.waves || [],
+        verificationCriteria: parsed.verificationCriteria || [],
+        estimatedDuration: parsed.estimatedDuration || 0,
+        rationale: parsed.rationale || ''
+      }
+    } catch (error) {
+      console.error('[ToPlanSkill] Failed to parse plan:', error)
+      return {
+        goal: 'Failed to parse',
+        tasks: [],
+        dependencies: {},
+        waves: [],
+        verificationCriteria: [],
+        estimatedDuration: 0,
+        rationale: 'Parse error'
+      }
+    }
+  }
+
+  private validatePlan(plan: Plan): { valid: boolean; issues: string[] } {
+    const issues: string[] = []
+
+    if (!plan.goal || plan.goal.trim() === '') {
+      issues.push('Plan must have a goal')
+    }
+
+    if (plan.tasks.length === 0) {
+      issues.push('Plan must have at least one task')
+    }
+
+    // Check for circular dependencies
+    const visited = new Set<string>()
+    const recursionStack = new Set<string>()
+
+    const hasCycle = (taskId: string): boolean => {
+      visited.add(taskId)
+      recursionStack.add(taskId)
+
+      const deps = plan.dependencies[taskId] || []
+      for (const dep of deps) {
+        if (!visited.has(dep)) {
+          if (hasCycle(dep)) return true
+        } else if (recursionStack.has(dep)) {
+          issues.push(`Circular dependency: ${taskId} -> ${dep}`)
+          return true
+        }
+      }
+
+      recursionStack.delete(taskId)
+      return false
+    }
+
+    for (const task of plan.tasks) {
+      if (!visited.has(task.id)) {
+        hasCycle(task.id)
+      }
+    }
+
+    // Validate dependencies exist
+    for (const [taskId, deps] of Object.entries(plan.dependencies)) {
+      if (!plan.tasks.some(t => t.id === taskId)) {
+        issues.push(`Dependency references non-existent task: ${taskId}`)
+      }
+      for (const dep of deps) {
+        if (!plan.tasks.some(t => t.id === dep)) {
+          issues.push(`Task ${taskId} depends on non-existent task: ${dep}`)
+        }
+      }
+    }
+
+    return { valid: issues.length === 0, issues }
+  }
+
+  private groupIntoWaves(plan: Plan): Wave[] {
+    const waves: Wave[] = []
+    const completed = new Set<string>()
+    const remaining = new Set(plan.tasks.map(t => t.id))
+    let waveIndex = 0
+
+    while (remaining.size > 0) {
+      const waveTasks = plan.tasks.filter(t => {
+        if (!remaining.has(t.id)) return false
+        const deps = plan.dependencies[t.id] || []
+        return deps.every(dep => completed.has(dep))
+      })
+
+      if (waveTasks.length === 0) {
+        console.error('[ToPlanSkill] Circular dependency detected')
+        break
+      }
+
+      waves.push({
+        id: `wave-${waveIndex}`,
+        tasks: waveTasks.map(t => t.id)
+      })
+
+      waveTasks.forEach(t => {
+        completed.add(t.id)
+        remaining.delete(t.id)
+      })
+
+      waveIndex++
+    }
+
+    return waves
+  }
+
+  private async triggerHook(
+    context: SkillContext,
+    type: typeof HookType[keyof typeof HookType],
+    data: Record<string, unknown>
+  ): Promise<void> {
+    if (context.hooks) {
+      try {
+        // Import HookContext from types for proper typing
+        const hookContext = data as unknown as import('../../types.js').HookContext
+        await context.hooks.execute(type as import('../../types.js').HookType, hookContext)
+      } catch (error) {
+        console.warn(`[ToPlanSkill] Hook ${type} failed:`, error)
+      }
+    }
+  }
+}