@haoyiyin/workflow 0.2.0 → 0.2.3

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

@@ -0,0 +1,586 @@
+/**
+ * To Plan Skill - Creates implementation plans via multi-step subagent dispatch
+ *
+ * 5-Step Process:
+ *   Step 1: Classify the request (type, complexity, risk, exploration areas)
+ *   Step 2: Dispatch 1-3 read-only exploration subagents (in parallel)
+ *   Step 3: Synthesize findings into a unified plan structure
+ *   Step 4: Write the plan to disk
+ *   Step 5: Dispatch plan-checker subagent to validate the plan
+ *
+ * Main Agent NEVER reads source files directly — all exploration is delegated.
+ */
+
+import { z } from 'zod'
+import { Skill } from '../skill.js'
+import type { SkillContext } from '../types.js'
+import { createDispatcher } from '../../agents/dispatcher.js'
+import type { SubagentContract, SubagentConfig } from '../../agents/types.js'
+import { researcherContract } from '../../agents/contracts.js'
+import { createMainAgentGuard } from '../../guard/main-agent.js'
+import { mkdir, writeFile } from 'fs/promises'
+import { join } from 'path'
+
+// ---------------------------------------------------------------------------
+// Schemas
+// ---------------------------------------------------------------------------
+
+const ToPlanInputSchema = z.object({
+  goal: z.string().min(1, 'Goal is required'),
+  context: z.string().optional(),
+  outputPath: z.string().optional(),
+  model: z.string().optional(),
+  filesHint: z.array(z.string()).optional(),
+  workType: z.enum(['feature', 'bugfix', 'migration', 'cleanup', 'refactor']).optional(),
+})
+
+const TaskSchema = z.object({
+  id: z.string(),
+  title: z.string(),
+  description: z.string(),
+  owns: z.array(z.string()),
+  reads: z.array(z.string()),
+  dependencies: z.array(z.string()),
+  verification: z.string().optional(),
+})
+
+const ToPlanOutputSchema = z.object({
+  planPath: z.string(),
+  executionModel: z.enum(['single-agent', 'ordered-non-parallel', 'fan-out-fan-in']),
+  classification: z.object({
+    type: z.string(),
+    complexity: z.enum(['low', 'medium', 'high']),
+    risk: z.enum(['low', 'medium', 'high']),
+  }),
+  planCheckerPassed: z.boolean(),
+  tasks: z.array(TaskSchema),
+  summary: z.string(),
+  tokensUsed: z.number(),
+})
+
+type ToPlanInput = z.infer<typeof ToPlanInputSchema>
+type ToPlanOutput = z.infer<typeof ToPlanOutputSchema>
+type TaskDef = z.infer<typeof TaskSchema>
+
+// ---------------------------------------------------------------------------
+// Pure helper types
+// ---------------------------------------------------------------------------
+
+interface Classification {
+  type: string
+  complexity: 'low' | 'medium' | 'high'
+  risk: 'low' | 'medium' | 'high'
+  explorationAreas: string[]
+}
+
+interface SynthesizedPlan {
+  executionModel: 'single-agent' | 'ordered-non-parallel' | 'fan-out-fan-in'
+  tasks: TaskDef[]
+  summary: string
+}
+
+// ---------------------------------------------------------------------------
+// Step 1: Classify prompt builder
+// ---------------------------------------------------------------------------
+
+function buildClassifyPrompt(goal: string, context?: string, workType?: string, researchFindings?: string): string {
+  return [
+    '## Classify This Request',
+    '',
+    `**Goal**: ${goal}`,
+    context ? `**Context**: ${context}` : '',
+    workType ? `**Hinted Work Type**: ${workType}` : '',
+    researchFindings ? `## Research Findings\n\n${researchFindings.slice(0, 1000)}` : '',
+    '',
+    'Determine:',
+    '- **Type**: feature, bugfix, migration, cleanup, refactor, or other',
+    '- **Complexity**: low (1-3 files), medium (3-10 files), high (10+ files / architectural)',
+    '- **Risk**: low (isolated, well-tested), medium (shared code), high (core systems, low coverage)',
+    '- **Exploration Areas**: 1-3 key directories or file patterns to explore first',
+    '',
+    'Output as JSON:',
+    '```json',
+    '{ "type": "...", "complexity": "low|medium|high", "risk": "low|medium|high", "explorationAreas": ["path/area1", "path/area2"] }',
+    '```',
+  ].join('\n')
+}
+
+// ---------------------------------------------------------------------------
+// Step 2: Exploration prompt builder (one per area)
+// ---------------------------------------------------------------------------
+
+function buildExplorePrompt(area: string, goal: string, context?: string): string {
+  return [
+    '## Exploration Task',
+    '',
+    `**Goal**: ${goal}`,
+    context ? `**Context**: ${context}` : '',
+    `**Focus Area**: ${area}`,
+    '',
+    '## Instructions',
+    '',
+    '1. Search and read files within this area',
+    '2. Identify: existing patterns, relevant abstractions, dependencies, test coverage',
+    '3. Note any existing implementation that relates to the goal',
+    '4. Flag surprises, risks, or undocumented behavior',
+    '',
+    '## Constraints',
+    '- READ ONLY — do not modify any files',
+    '- Focus only on the assigned area',
+    '- Be thorough but concise',
+  ].join('\n')
+}
+
+// ---------------------------------------------------------------------------
+// Step 3: Synthesize prompt builder
+// ---------------------------------------------------------------------------
+
+function buildSynthesizePrompt(
+  goal: string,
+  context: string | undefined,
+  classification: Classification,
+  explorationOutputs: string[],
+): string {
+  const explorationsBlock = explorationOutputs
+    .map((output, i) => `### Exploration ${i + 1}\n\n${output.slice(0, 2000)}`)
+    .join('\n\n')
+
+  return [
+    '## Synthesize Findings into an Implementation Plan',
+    '',
+    `**Goal**: ${goal}`,
+    context ? `**Context**: ${context}` : '',
+    '',
+    '## Classification',
+    `Type: ${classification.type}, Complexity: ${classification.complexity}, Risk: ${classification.risk}`,
+    '',
+    '## Exploration Results',
+    explorationsBlock,
+    '',
+    '## Instructions',
+    '',
+    '1. Cross-reference all exploration findings',
+    '2. Identify conflicts or gaps in understanding',
+    '3. Determine the execution model:',
+    '   - **single-agent**: one implementer can do everything',
+    '   - **ordered-non-parallel**: tasks must run in dependency order',
+    '   - **fan-out-fan-in**: independent tasks in parallel, then merge',
+    '4. Break work into concrete tasks (typically 3-8 tasks)',
+    '',
+    '## Task Rules',
+    '- Each task: id, title, description, owns[], reads[], dependencies[], verification',
+    '- **owns[]**: files the task CREATES or MODIFIES',
+    '- **reads[]**: files the task reads for context',
+    '- **dependencies[]**: task IDs that must finish first',
+    '- **verification**: how to confirm the task is done correctly',
+    '- Tasks sized for 1-5 minutes of subagent work',
+    '',
+    'Output as JSON:',
+    '```json',
+    '{ "executionModel": "...", "tasks": [...], "summary": "..." }',
+    '```',
+  ].join('\n')
+}
+
+// ---------------------------------------------------------------------------
+// Step 4: Write plan prompt builder
+// ---------------------------------------------------------------------------
+
+function buildWritePlanPrompt(
+  goal: string,
+  context: string | undefined,
+  classification: Classification,
+  synthesis: SynthesizedPlan,
+  planPath: string,
+): string {
+  const tasksBlock = synthesis.tasks
+    .map(
+      (t) =>
+        `- **Task ${t.id}**: ${t.title} — ${t.description} (owns: ${t.owns.join(', ') || 'none'}, reads: ${t.reads.join(', ') || 'none'}, deps: ${t.dependencies.join(', ') || 'none'})`,
+    )
+    .join('\n')
+
+  return [
+    `Write the implementation plan to: ${planPath}`,
+    '',
+    `**Goal**: ${goal}`,
+    context ? `**Context**: ${context}` : '',
+    `**Type**: ${classification.type}, **Complexity**: ${classification.complexity}, **Risk**: ${classification.risk}`,
+    `**Execution Model**: ${synthesis.executionModel}`,
+    '',
+    '## Tasks to Document',
+    tasksBlock,
+    '',
+    '## Plan Format',
+    '',
+    'Write a markdown file with these sections:',
+    '1. `# Goal` — restate the goal',
+    '2. `## Context` — background information',
+    '3. `## Execution Model` — how tasks should be executed',
+    '4. `## Tasks` — numbered sections per task with title, description, owns, reads, dependencies, verification',
+    '5. `## Risks` — identified risks and mitigation strategies',
+  ].join('\n')
+}
+
+// ---------------------------------------------------------------------------
+// Step 5: Plan check prompt builder
+// ---------------------------------------------------------------------------
+
+function buildPlanCheckPrompt(planPath: string): string {
+  return [
+    '## Validate the Implementation Plan',
+    '',
+    `Read the plan file: ${planPath}`,
+    '',
+    '## Checklist',
+    '',
+    '1. Do tasks cover all requirements?',
+    '2. Does every task have clear owns[] and reads[]?',
+    '3. Are dependencies acyclic and valid (referenced IDs exist)?',
+    '4. Are tasks small enough for subagent execution (<5 min)?',
+    '5. Does each task have a verification step?',
+    '6. Are identified risks addressed?',
+    '7. Could tasks conflict by owning the same file?',
+    '',
+    'Return: PASS or BLOCKED with specific issues.',
+  ].join('\n')
+}
+
+// ---------------------------------------------------------------------------
+// Parsing helpers (pure functions)
+// ---------------------------------------------------------------------------
+
+function parseClassification(output: string): Classification {
+  const jsonMatch = output.match(/```json\s*([\s\S]*?)\s*```/)
+  if (jsonMatch) {
+    try {
+      const parsed = JSON.parse(jsonMatch[1].trim())
+      return {
+        type: parsed.type || 'feature',
+        complexity: parsed.complexity || 'medium',
+        risk: parsed.risk || 'medium',
+        explorationAreas: Array.isArray(parsed.explorationAreas)
+          ? parsed.explorationAreas.slice(0, 3)
+          : ['src/'],
+      }
+    } catch {
+      // fall through to defaults
+    }
+  }
+  return {
+    type: 'feature',
+    complexity: 'medium',
+    risk: 'medium',
+    explorationAreas: ['src/'],
+  }
+}
+
+function parseSynthesis(output: string): SynthesizedPlan {
+  const jsonMatch = output.match(/```json\s*([\s\S]*?)\s*```/)
+  if (jsonMatch) {
+    try {
+      const parsed = JSON.parse(jsonMatch[1].trim())
+      return {
+        executionModel: parsed.executionModel || 'ordered-non-parallel',
+        tasks: Array.isArray(parsed.tasks) ? parsed.tasks : [],
+        summary: parsed.summary || 'Plan synthesized',
+      }
+    } catch {
+      // fall through to defaults
+    }
+  }
+  return {
+    executionModel: 'ordered-non-parallel',
+    tasks: [
+      {
+        id: '1',
+        title: 'Implementation',
+        description: 'Core implementation work',
+        owns: [],
+        reads: [],
+        dependencies: [],
+        verification: 'Run tests',
+      },
+    ],
+    summary: output.slice(0, 200),
+  }
+}
+
+function checkPlanPassed(output: string): boolean {
+  return !output.toLowerCase().includes('blocked')
+}
+
+// ---------------------------------------------------------------------------
+// Fallback plan writer (used when write subagent fails)
+// ---------------------------------------------------------------------------
+
+function buildFallbackPlan(
+  goal: string,
+  context: string | undefined,
+  synthesis: SynthesizedPlan,
+): string {
+  const tasksBlock = synthesis.tasks
+    .map(
+      (t) =>
+        [
+          `### Task ${t.id}: ${t.title}`,
+          '',
+          t.description,
+          '',
+          `- **Owns**: ${t.owns.join(', ') || 'none'}`,
+          `- **Reads**: ${t.reads.join(', ') || 'none'}`,
+          `- **Depends on**: ${t.dependencies.join(', ') || 'none'}`,
+          `- **Verification**: ${t.verification || 'Run tests'}`,
+        ].join('\n'),
+    )
+    .join('\n\n')
+
+  return [
+    `# ${goal}`,
+    '',
+    context ? `## Context\n\n${context}\n` : '',
+    `## Execution Model\n\n${synthesis.executionModel}`,
+    '',
+    '## Tasks',
+    '',
+    tasksBlock,
+  ].join('\n')
+}
+
+// ---------------------------------------------------------------------------
+// Skill class
+// ---------------------------------------------------------------------------
+
+export class ToPlanSkill extends Skill<ToPlanInput, ToPlanOutput> {
+  constructor() {
+    super({
+      name: 'to-plan',
+      description:
+        'Create implementation plans via 5-step subagent dispatch: classify, explore, synthesize, write, check',
+      requires: [],
+      inputSchema: ToPlanInputSchema,
+      outputSchema: ToPlanOutputSchema,
+    })
+  }
+
+  async execute(input: ToPlanInput, context: SkillContext): Promise<ToPlanOutput> {
+    const { config, logger } = context
+    const dispatcher = createDispatcher(logger)
+    const guard = createMainAgentGuard({}, logger)
+    const model = input.model || config.defaultModel
+    let totalTokens = 0
+
+    if (!model) {
+      throw new Error('Model is required. Set defaultModel in config or pass model in input.')
+    }
+
+    guard.activateEmbargo()
+
+    try {
+      // ---- Step 0: Research external context (if needed) ----
+      let researchSummary = ''
+      const needsResearch = /api|library|framework|migrate|upgrade|version|best practice/i.test(input.goal)
+      if (needsResearch) {
+        logger.info(`[to-plan] Step 0: Researching "${input.goal.slice(0, 80)}"`)
+        const researchResult = await dispatcher.dispatch(
+          { role: 'researcher', model, tokenBudget: 12000 },
+          researcherContract({
+            topic: input.goal,
+            scope: 'technical',
+            questions: [
+              'What are the latest best practices?',
+              'Are there known issues or breaking changes?',
+              'What are recommended approaches?'
+            ],
+            timeRange: '1y'
+          })
+        )
+        totalTokens += researchResult.tokensUsed
+        researchSummary = researchResult.output.slice(0, 1500)
+        logger.info(`[to-plan] Research complete: ${researchSummary.slice(0, 100)}...`)
+      }
+
+      // ---- Step 1: Classify the request ----
+      logger.info(`[to-plan] Step 1: Classifying "${input.goal.slice(0, 80)}"`)
+      const classifyResult = await dispatcher.dispatch(
+        { role: 'explorer', model, tokenBudget: 8000 },
+        {
+          permissions: {
+            readFiles: true,
+            searchCode: false,
+            runCommands: false,
+            writeFiles: false,
+            gitOperations: false,
+          },
+          prompt: buildClassifyPrompt(input.goal, input.context, input.workType, researchSummary),
+          owns: [],
+          reads: [],
+        },
+      )
+
+      totalTokens += classifyResult.tokensUsed
+      const classification = parseClassification(classifyResult.output)
+      logger.info(
+        `[to-plan] Classified: type=${classification.type}, complexity=${classification.complexity}, risk=${classification.risk}`,
+      )
+
+      // ---- Step 2: Dispatch 1-3 read-only exploration subagents (parallel) ----
+      const areas = classification.explorationAreas.slice(0, 3)
+      logger.info(
+        `[to-plan] Step 2: Dispatching ${areas.length} exploration subagent(s) in parallel`,
+      )
+
+      const exploreConfigs: SubagentConfig[] = areas.map(() => ({
+        role: 'explorer' as const,
+        model,
+        tokenBudget: 16000,
+      }))
+
+      const exploreContracts: SubagentContract[] = areas.map((area) => ({
+        permissions: {
+          readFiles: true,
+          searchCode: true,
+          runCommands: false,
+          writeFiles: false,
+          gitOperations: false,
+        },
+        prompt: buildExplorePrompt(area, input.goal, input.context),
+        owns: [],
+        reads: input.filesHint ?? [],
+      }))
+
+      const exploreResults =
+        areas.length === 1
+          ? [await dispatcher.dispatch(exploreConfigs[0], exploreContracts[0])]
+          : await dispatcher.dispatchParallel(exploreConfigs, exploreContracts)
+
+      for (const result of exploreResults) {
+        totalTokens += result.tokensUsed
+      }
+
+      const successfulExplorations = exploreResults.filter((r) => r.status === 'success')
+      logger.info(
+        `[to-plan] ${successfulExplorations.length}/${areas.length} explorations succeeded`,
+      )
+
+      // ---- Step 3: Synthesize findings ----
+      logger.info('[to-plan] Step 3: Synthesizing findings')
+      const synthesizeResult = await dispatcher.dispatch(
+        { role: 'planner', model },
+        {
+          permissions: {
+            readFiles: true,
+            searchCode: false,
+            runCommands: false,
+            writeFiles: false,
+            gitOperations: false,
+          },
+          prompt: buildSynthesizePrompt(
+            input.goal,
+            input.context,
+            classification,
+            successfulExplorations.map((r) => r.output),
+          ),
+          owns: [],
+          reads: [],
+        },
+      )
+
+      totalTokens += synthesizeResult.tokensUsed
+      const synthesis = parseSynthesis(synthesizeResult.output)
+      logger.info(
+        `[to-plan] Synthesized: ${synthesis.tasks.length} tasks, model=${synthesis.executionModel}`,
+      )
+
+      // ---- Step 4: Write plan to disk ----
+      const date = new Date().toISOString().split('T')[0]
+      const sanitized = input.goal
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .slice(0, 50)
+      const planPath =
+        input.outputPath ||
+        join(config.planPath, `${date}-${sanitized}-implementation-plan.md`)
+
+      await mkdir(config.planPath, { recursive: true })
+
+      logger.info(`[to-plan] Step 4: Writing plan to ${planPath}`)
+      const writeResult = await dispatcher.dispatch(
+        { role: 'implementer', model },
+        {
+          permissions: {
+            readFiles: false,
+            searchCode: false,
+            runCommands: false,
+            writeFiles: true,
+            gitOperations: false,
+          },
+          prompt: buildWritePlanPrompt(
+            input.goal,
+            input.context,
+            classification,
+            synthesis,
+            planPath,
+          ),
+          owns: [planPath],
+          reads: [],
+        },
+      )
+
+      totalTokens += writeResult.tokensUsed
+
+      // If the write subagent failed, write a fallback plan
+      if (writeResult.status !== 'success') {
+        const fallback = buildFallbackPlan(input.goal, input.context, synthesis)
+        await writeFile(planPath, fallback, 'utf-8')
+        logger.warn('[to-plan] Write subagent failed; wrote fallback plan')
+      }
+
+      // ---- Step 5: Dispatch plan-checker subagent ----
+      logger.info('[to-plan] Step 5: Validating plan')
+      const checkerResult = await dispatcher.dispatch(
+        { role: 'reviewer', model },
+        {
+          permissions: {
+            readFiles: true,
+            searchCode: false,
+            runCommands: false,
+            writeFiles: false,
+            gitOperations: false,
+          },
+          prompt: buildPlanCheckPrompt(planPath),
+          owns: [],
+          reads: [planPath],
+        },
+      )
+
+      totalTokens += checkerResult.tokensUsed
+      const planCheckerPassed = checkPlanPassed(checkerResult.output)
+      logger.info(`[to-plan] Plan checker: ${planCheckerPassed ? 'PASS' : 'BLOCKED'}`)
+
+      return {
+        planPath,
+        executionModel: synthesis.executionModel,
+        classification: {
+          type: classification.type,
+          complexity: classification.complexity,
+          risk: classification.risk,
+        },
+        planCheckerPassed,
+        tasks: synthesis.tasks,
+        summary: [
+          `Plan created with ${synthesis.tasks.length} tasks.`,
+          `Execution model: ${synthesis.executionModel}.`,
+          `Checker: ${planCheckerPassed ? 'PASS' : 'BLOCKED'}.`,
+          `Used ${totalTokens} tokens.`,
+        ].join(' '),
+        tokensUsed: totalTokens,
+      }
+    } finally {
+      guard.deactivateEmbargo()
+    }
+  }
+}
+
+export const toPlanSkill = new ToPlanSkill()
+export default toPlanSkill

package/src/skills/types.ts

@@ -0,0 +1,47 @@
+/**
+ * Skill type definitions
+ */
+import type { ExecutionState, WorkflowConfig, Logger } from '../types.js'
+import type { PersistenceManager } from '../persistence/types.js'
+import type { ResilientDispatcher } from '../agents/dispatcher-enhanced.js'
+import type { HookManagerInterface } from '../hooks/types.js'
+
+export interface SkillContext {
+  config: WorkflowConfig
+  state: ExecutionState
+  logger: Logger
+  /** Access to other skills for composition */
+  skills: SkillRegistry
+  /** Persistence layer for STATE.md and PLAN.md */
+  persistence?: PersistenceManager
+  /** Dispatcher for spawning subagents */
+  dispatcher: ResilientDispatcher
+  /** Hook manager for lifecycle events */
+  hooks?: HookManagerInterface
+}
+
+export interface SkillDefinition<Input = unknown, Output = unknown> {
+  name: string
+  description: string
+  requires?: string[]
+  execute: (input: Input, context: SkillContext) => Promise<Output>
+}
+
+export interface SkillRegistry {
+  register(skill: SkillDefinition<any, any>): void
+  unregister(name: string): void
+  get(name: string): SkillDefinition<any, any> | null
+  list(): SkillDefinition<any, any>[]
+  getDependencies(name: string): string[]
+  resolveOrder(skillNames: string[]): string[]
+}
+
+export interface ExecutionResult<T = unknown> {
+  success: boolean
+  data?: T
+  error?: string
+  metadata?: {
+    duration: number
+    tokensUsed?: number
+  }
+}