@haoyiyin/workflow 0.2.2 → 0.2.3

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

@@ -0,0 +1,394 @@
+/**
+ * Review Diff Skill - Reviews code changes via reviewer subagents
+ *
+ * Use case: Review PR, branch, commit, or diff-file
+ * Pattern: Get diff → Inspect surface → Check requirements → Check tests →
+ *          Check quality → Return structured review report
+ *
+ * Spawns reviewer subagent(s) to review diffs.
+ * Returns structured review report with severity-classified issues.
+ */
+
+import { z } from 'zod'
+import { Skill } from '../skill.js'
+import type { SkillContext } from '../types.js'
+import { createDispatcher } from '../../agents/dispatcher.js'
+import { createMainAgentGuard } from '../../guard/main-agent.js'
+
+// ---------------------------------------------------------------------------
+// Schemas
+// ---------------------------------------------------------------------------
+
+const ReviewDiffInputSchema = z.object({
+  target: z.string().min(1),
+  targetType: z
+    .enum(['pr', 'branch', 'commit', 'diff-file'])
+    .default('branch'),
+  planPath: z.string().optional(),
+  focus: z
+    .array(z.enum(['security', 'performance', 'correctness', 'style', 'tests']))
+    .optional(),
+  model: z.string().optional(),
+})
+
+const ReviewDiffOutputSchema = z.object({
+  decision: z.enum(['approve', 'changes', 'blocked', 'needs-evidence']),
+  issues: z.array(
+    z.object({
+      severity: z.enum(['blocker', 'major', 'minor', 'note']),
+      file: z.string().optional(),
+      line: z.number().optional(),
+      description: z.string(),
+      action: z.string(),
+    }),
+  ),
+  specCompliance: z.enum(['pass', 'partial', 'fail']),
+  testAssessment: z.enum(['adequate', 'missing', 'failing']),
+  strengths: z.array(z.string()),
+  summary: z.string(),
+  tokensUsed: z.number(),
+})
+
+type ReviewDiffInput = z.infer<typeof ReviewDiffInputSchema>
+type ReviewDiffOutput = z.infer<typeof ReviewDiffOutputSchema>
+
+// ---------------------------------------------------------------------------
+// Prompt builders (pure functions)
+// ---------------------------------------------------------------------------
+
+function buildDiffPrompt(targetType: string, target: string): string {
+  const commands: Record<string, string> = {
+    pr: `gh pr diff ${target}`,
+    branch: `git diff origin/${target}...HEAD`,
+    commit: `git show ${target}`,
+    'diff-file': `cat ${target}`,
+  }
+  const cmd = commands[targetType] ?? `git diff ${target}`
+  return [
+    `Get the diff for ${targetType}: ${target}`,
+    '',
+    `Run: \`${cmd}\``,
+    '',
+    'Return the full diff content. Include changed file paths and line numbers.',
+  ].join('\n')
+}
+
+function buildSurfacePrompt(diff: string): string {
+  return [
+    'Analyze the changed surface from this diff:',
+    '',
+    diff.slice(0, 5000),
+    '',
+    'Report:',
+    '- Files changed (list each path)',
+    '- Lines added / removed per file',
+    '- Scope assessment (localized vs wide-ranging)',
+  ].join('\n')
+}
+
+function buildSpecCompliancePrompt(
+  diff: string,
+  _planPath: string,
+): string {
+  return [
+    'Compare implementation to requirements.',
+    '',
+    'Read the plan file to understand what was requested.',
+    '',
+    '## Diff',
+    diff.slice(0, 4000),
+    '',
+    'Check: Does the implementation satisfy the plan requirements?',
+    'Return: pass, partial, or fail with specific violations listed.',
+  ].join('\n')
+}
+
+function buildQualityReviewPrompt(
+  diff: string,
+  focusAreas: string[],
+): string {
+  const focusText =
+    focusAreas.length > 0 ? focusAreas.join(', ') : 'all aspects'
+
+  return [
+    `Review code quality focusing on: ${focusText}`,
+    '',
+    '## Diff',
+    diff.slice(0, 5000),
+    '',
+    '## Check Each Category',
+    '',
+    '- **Correctness**: Logic errors, edge cases, off-by-one',
+    '- **Security**: Injection risks, auth bypass, secrets in code, input validation',
+    '- **Performance**: N+1 queries, unnecessary allocations, blocking calls',
+    '- **Style**: Naming conventions, consistency with codebase, immutability',
+    '- **Error Handling**: Caught errors, graceful degradation, user-facing messages',
+    '',
+    '## Output Format',
+    '',
+    'For each issue found, output one line:',
+    '`SEVERITY|FILE|LINE|DESCRIPTION|SUGGESTED_ACTION`',
+    '',
+    'Severity values: BLOCKER, MAJOR, MINOR, NOTE',
+    'BLOCKER = must fix before merge (security hole, broken build, data loss)',
+    'MAJOR = should fix (bug, performance problem, missing error handling)',
+    'MINOR = nice to fix (style, naming, minor duplication)',
+    'NOTE = observation, not a problem',
+  ].join('\n')
+}
+
+// ---------------------------------------------------------------------------
+// Parsing helpers (pure functions)
+// ---------------------------------------------------------------------------
+
+interface ParsedIssue {
+  severity: 'blocker' | 'major' | 'minor' | 'note'
+  file?: string
+  line?: number
+  description: string
+  action: string
+}
+
+function parseIssues(output: string): ParsedIssue[] {
+  const issues: ParsedIssue[] = []
+  const lines = output.split('\n')
+
+  for (const line of lines) {
+    const match = line.match(
+      /^(BLOCKER|MAJOR|MINOR|NOTE)\s*\|\s*([^|]*)\s*\|\s*(\d+)\s*\|\s*([^|]+)\s*\|\s*(.+)$/i,
+    )
+    if (match) {
+      const file = match[2]?.trim()
+      issues.push({
+        severity: match[1].toLowerCase() as ParsedIssue['severity'],
+        file: file || undefined,
+        line: parseInt(match[3], 10),
+        description: match[4].trim(),
+        action: match[5].trim(),
+      })
+    }
+  }
+
+  return issues
+}
+
+function determineDecision(issues: ParsedIssue[]): ReviewDiffOutput['decision'] {
+  if (issues.some((i) => i.severity === 'blocker')) return 'blocked'
+  if (issues.some((i) => i.severity === 'major')) return 'changes'
+  return 'approve'
+}
+
+function assessTests(output: string): ReviewDiffOutput['testAssessment'] {
+  const lower = output.toLowerCase()
+  if (lower.includes('missing') || lower.includes('no test')) return 'missing'
+  if (lower.includes('fail')) return 'failing'
+  return 'adequate'
+}
+
+function assessSpecCompliance(output: string): ReviewDiffOutput['specCompliance'] {
+  const lower = output.toLowerCase()
+  if (lower.includes('fail')) return 'fail'
+  if (lower.includes('partial')) return 'partial'
+  return 'pass'
+}
+
+// ---------------------------------------------------------------------------
+// Skill class
+// ---------------------------------------------------------------------------
+
+export class ReviewDiffSkill extends Skill<ReviewDiffInput, ReviewDiffOutput> {
+  constructor() {
+    super({
+      name: 'review-diff',
+      description:
+        'Review code changes (diff/branch/PR) with reviewer subagents. Returns structured report.',
+      requires: [],
+      inputSchema: ReviewDiffInputSchema as z.ZodType<ReviewDiffInput>,
+      outputSchema: ReviewDiffOutputSchema,
+    })
+  }
+
+  async execute(
+    input: ReviewDiffInput,
+    context: SkillContext,
+  ): Promise<ReviewDiffOutput> {
+    const { config, logger } = context
+    const dispatcher = createDispatcher(logger)
+    const guard = createMainAgentGuard({}, logger)
+
+    guard.activateEmbargo()
+    let totalTokens = 0
+
+    try {
+      // Step 1: Get diff
+      logger.info(
+        `[review-diff] Getting diff for ${input.targetType}: ${input.target}`,
+      )
+      const diffResult = await dispatcher.dispatch(
+        {
+          role: 'explorer',
+          model: input.model || config.defaultModel,
+        },
+        {
+          permissions: {
+            readFiles: true,
+            searchCode: false,
+            runCommands: true,
+            writeFiles: false,
+            gitOperations: true,
+          },
+          prompt: buildDiffPrompt(input.targetType, input.target),
+          owns: [],
+          reads: [],
+        },
+      )
+
+      totalTokens += diffResult.tokensUsed
+
+      if (diffResult.status !== 'success') {
+        return {
+          decision: 'needs-evidence',
+          issues: [
+            {
+              severity: 'blocker',
+              description: 'Cannot access diff',
+              action: 'Verify target exists and is accessible',
+            },
+          ],
+          specCompliance: 'fail',
+          testAssessment: 'missing',
+          strengths: [],
+          summary: 'Cannot retrieve diff for review',
+          tokensUsed: totalTokens,
+        }
+      }
+
+      const diffContent = diffResult.output
+
+      // Step 2: Inspect changed surface
+      logger.info('[review-diff] Inspecting changed surface')
+      const surfaceResult = await dispatcher.dispatch(
+        {
+          role: 'explorer',
+          model: input.model || config.defaultModel,
+        },
+        {
+          permissions: {
+            readFiles: true,
+            searchCode: false,
+            runCommands: false,
+            writeFiles: false,
+            gitOperations: false,
+          },
+          prompt: buildSurfacePrompt(diffContent),
+          owns: [],
+          reads: [],
+        },
+      )
+
+      totalTokens += surfaceResult.tokensUsed
+
+      // Step 3: Check requirement compliance (if plan provided)
+      let specOutput = 'pass'
+      if (input.planPath) {
+        logger.info('[review-diff] Checking spec compliance')
+        const specResult = await dispatcher.dispatch(
+          {
+            role: 'reviewer',
+            model: input.model || config.defaultModel,
+          },
+          {
+            permissions: {
+              readFiles: true,
+              searchCode: false,
+              runCommands: false,
+              writeFiles: false,
+              gitOperations: false,
+            },
+            prompt: buildSpecCompliancePrompt(diffContent, input.planPath),
+            owns: [],
+            reads: [input.planPath],
+          },
+        )
+
+        totalTokens += specResult.tokensUsed
+        specOutput = specResult.output
+      }
+
+      // Step 4: Check tests
+      logger.info('[review-diff] Assessing test coverage')
+      const testResult = await dispatcher.dispatch(
+        {
+          role: 'reviewer',
+          model: input.model || config.defaultModel,
+        },
+        {
+          permissions: {
+            readFiles: true,
+            searchCode: false,
+            runCommands: true,
+            writeFiles: false,
+            gitOperations: false,
+          },
+          prompt: [
+            'Check test coverage in the changed code:',
+            '',
+            diffContent.slice(0, 4000),
+            '',
+            'Do changed files have corresponding test changes?',
+            'Are new functions/classes covered by tests?',
+            'Return: adequate, missing, or failing with details.',
+          ].join('\n'),
+          owns: [],
+          reads: [],
+        },
+      )
+
+      totalTokens += testResult.tokensUsed
+
+      // Step 5: Review code quality
+      logger.info('[review-diff] Reviewing code quality')
+      const qualityResult = await dispatcher.dispatch(
+        {
+          role: 'reviewer',
+          model: input.model || config.defaultModel,
+        },
+        {
+          permissions: {
+            readFiles: true,
+            searchCode: true,
+            runCommands: false,
+            writeFiles: false,
+            gitOperations: false,
+          },
+          prompt: buildQualityReviewPrompt(
+            diffContent,
+            input.focus ?? [],
+          ),
+          owns: [],
+          reads: [],
+        },
+      )
+
+      totalTokens += qualityResult.tokensUsed
+
+      // Step 6: Compile final report
+      const issues = parseIssues(qualityResult.output)
+
+      return {
+        decision: determineDecision(issues),
+        issues,
+        specCompliance: assessSpecCompliance(specOutput),
+        testAssessment: assessTests(testResult.output),
+        strengths: ['Reviewed all changed files'],
+        summary: `Review complete: ${issues.length} issue(s) found (${issues.filter((i) => i.severity === 'blocker').length} blocker, ${issues.filter((i) => i.severity === 'major').length} major)`,
+        tokensUsed: totalTokens,
+      }
+    } finally {
+      guard.deactivateEmbargo()
+    }
+  }
+}
+
+export const reviewDiffSkill = new ReviewDiffSkill()
+export default reviewDiffSkill

package/src/skills/skill.ts

@@ -0,0 +1,59 @@
+/**
+ * Base skill class with validation and error handling
+ */
+import { z } from 'zod'
+import type {
+  SkillDefinition,
+  SkillContext,
+} from './types.js'
+
+export abstract class Skill<Input, Output> {
+  protected name: string
+  protected description: string
+  protected requires: string[]
+  protected inputSchema?: z.ZodSchema<Input>
+  protected outputSchema?: z.ZodSchema<Output>
+
+  constructor(options: {
+    name: string
+    description: string
+    requires?: string[]
+    inputSchema?: z.ZodSchema<Input>
+    outputSchema?: z.ZodSchema<Output>
+  }) {
+    this.name = options.name
+    this.description = options.description
+    this.requires = options.requires || []
+    this.inputSchema = options.inputSchema
+    this.outputSchema = options.outputSchema
+  }
+
+  abstract execute(input: Input, context: SkillContext): Promise<Output>
+
+  async validateInput(input: unknown): Promise<Input> {
+    if (this.inputSchema) {
+      return this.inputSchema.parse(input)
+    }
+    return input as Input
+  }
+
+  async validateOutput(output: unknown): Promise<Output> {
+    if (this.outputSchema) {
+      return this.outputSchema.parse(output)
+    }
+    return output as Output
+  }
+
+  toDefinition(): SkillDefinition<any, any> {
+    return {
+      name: this.name,
+      description: this.description,
+      requires: this.requires,
+      execute: async (input: any, context: SkillContext) => {
+        const validatedInput = await this.validateInput(input)
+        const result = await this.execute(validatedInput, context)
+        return await this.validateOutput(result)
+      },
+    }
+  }
+}

package/src/skills/systematic-debugging/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: systematic-debugging
+description: Find root cause before fixing. Spawn debugger subagents for systematic diagnosis. CRITICAL: no fix before root cause confirmed.
+requires: [tdd]
+---
+
+## ⛔ MAIN AGENT CONSTRAINT
+
+You are a THIN DISPATCHER. Your ONLY job is to dispatch subagents.
+You MUST NOT: read source files, search code, write/edit files, run tests, run git commands.
+You MAY only: read plan/state files, dispatch subagents via Agent tool, relay results.
+For EVERY user request (including this skill), dispatch a subagent. Never execute yourself.
+
+---
+
+## Use/Exclude Matrix
+
+| Use When | Exclude When |
+|---|---|
+| Bug with unknown root cause | Root cause already known and confirmed |
+| Test failure needing investigation | Typo or syntax error (use quick-task) |
+| Intermittent/flaky behavior | Build/environment issue (not code) |
+| Regression after recent changes | Fix is obvious and trivial |
+
+## Workflow
+
+1. **Reproduce** — Dispatch debugger subagent to reproduce the symptom. Confirm observed vs expected behavior.
+2. **Gather Evidence** — Dispatch explorer subagent (read-only) to identify suspect files, key functions, failure points, recent changes.
+3. **Diagnose** — Dispatch debugger subagent to form hypotheses, test top hypothesis, eliminate alternatives, confirm root cause. NO CODE CHANGES in this phase.
+4. **Apply Fix** — Dispatch debugger subagent (worktree) to apply ONE minimal fix targeting the confirmed root cause.
+5. **Verify** — Dispatch verifier subagent to re-run reproduction and full test suite.
+
+## Output Spec
+
+| Field | Type | Description |
+|---|---|---|
+| `rootCause` | string | Description of confirmed root cause |
+| `confidence` | enum | `high`, `medium`, `low` |
+| `location.file` | string? | File containing the root cause |
+| `location.line` | number? | Line number of root cause |
+| `location.function` | string? | Function containing root cause |
+| `fixApplied` | boolean | Whether the fix was successfully applied |
+| `fixDescription` | string? | Description of the applied fix |
+| `verification` | string | Verification output (PASS/FAIL with details) |
+| `risks` | string[] | Identified risks or follow-ups |
+| `tokensUsed` | number | Total tokens consumed |
+
+## Error Handling
+
+| Error | Action |
+|---|---|
+| Cannot reproduce symptom | Return with confidence=low; describe reproduction gap |
+| Diagnosis confidence is low | Apply safer, more conservative fix |
+| Diagnose phase blocked (no fix yet) | Enforced by prompt design; subagent told not to write code |
+| Fix subagent fails | Return fixApplied=false; preserve diagnosis |
+| Verification fails after fix | Return verification FAIL; may need re-diagnosis |