@haoyiyin/workflow 0.2.0 → 0.2.3

package/src/skills/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Skills module index
+ */
+export type { SkillDefinition, SkillRegistry, SkillContext, ExecutionResult } from './types.js'
+export { Registry, createRegistry } from './registry.js'
+export { Skill } from './skill.js'
+export { toPlanSkill, ToPlanSkill } from './to-plan/index.js'
+export { executePlanSkill, ExecutePlanSkill } from './execute-plan/index.js'
+export { quickTaskSkill, QuickTaskSkill } from './quick-task/index.js'
+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'

package/src/skills/quick-task/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: quick-task
+description: Handle small scoped tasks in an isolated worktree. Promotes to full plan if scope exceeds the quick-task limit.
+requires: [to-plan, execute-plan, systematic-debugging]
+---
+
+## ⛔ 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 |
+|---|---|
+| Typo fixes, renames, small edits | Multi-file architectural changes |
+| Description under ~100 chars | Unknown scope or high risk |
+| 1-5 files expected to change | Requires exploration before estimating |
+| Low-risk, well-understood change | Needs TDD cycle or comprehensive review |
+
+## Workflow
+
+1. **Classify Scope** — Check if description matches trivial patterns (typo/rename/format). Fast-path trivial changes.
+2. **Gather Context** — Dispatch read-only explorer subagent with tight token budget (8k) for focused context.
+3. **Write Compact Plan** — Write minimal plan to `.pi/quick/` directory for audit trail.
+4. **Implement** — Dispatch implementer subagent in isolated worktree. If scope exceeds 5 files, subagent returns PROMOTED_TO_FULL_PLAN.
+5. **Quick Review** — Dispatch reviewer subagent with tight budget for surface-level check.
+
+## Output Spec
+
+| Field | Type | Description |
+|---|---|---|
+| `status` | enum | `complete`, `needs-fixes`, `promoted`, `blocked` |
+| `planPath` | string? | Path to compact plan if one was written |
+| `filesModified` | string[] | Paths of files changed |
+| `verification` | string? | Review output or verification result |
+| `risks` | string[] | Identified risks or promotion reasons |
+| `summary` | string | One-line description of result |
+| `tokensUsed` | number | Total tokens consumed |
+| `durationMs` | number | Wall-clock duration |
+
+## Error Handling
+
+| Error | Action |
+|---|---|
+| Explorer subagent fails | Proceed with empty context |
+| Implementer returns PROMOTED | Return status=promoted; caller should invoke to-plan |
+| Implementer subagent fails | Return status=needs-fixes with errors |
+| Reviewer subagent fails | Return complete with empty verification |
+| Trivial change (<30 chars) | Fast-path: return immediately with status=complete |

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

@@ -0,0 +1,346 @@
+/**
+ * Quick Task Skill - Handles small, scoped tasks with worktree isolation
+ *
+ * Use case: "Fix typo in README", "Rename function X to Y", "Add validation to endpoint"
+ * Pattern: Main Agent → Dispatcher → Single Implementer Subagent (worktree) → Result
+ *
+ * Design principles:
+ * - Single subagent, minimal overhead
+ * - Worktree isolation for safety
+ * - Returns subagent result directly
+ * - Fast-path for trivial changes
+ * - Promotes to full plan if scope exceeds quick-task limit
+ */
+
+import { z } from 'zod'
+import { Skill } from '../skill.js'
+import type { SkillContext } from '../types.js'
+import { createDispatcher } from '../../agents/dispatcher.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 QuickTaskInputSchema = z.object({
+  description: z.string().min(1, 'Task description is required'),
+  filesHint: z.array(z.string()).optional(),
+  model: z.string().optional(),
+  skipTests: z.boolean().optional(),
+  tokenBudget: z.number().int().positive().max(100000).optional(),
+  timeout: z.number().int().positive().max(600).optional(),
+})
+
+const QuickTaskOutputSchema = z.object({
+  status: z.enum(['complete', 'needs-fixes', 'promoted', 'blocked']),
+  planPath: z.string().optional(),
+  filesModified: z.array(z.string()),
+  verification: z.string().optional(),
+  risks: z.array(z.string()),
+  summary: z.string(),
+  tokensUsed: z.number(),
+  durationMs: z.number(),
+})
+
+type QuickTaskInput = z.infer<typeof QuickTaskInputSchema>
+type QuickTaskOutput = z.infer<typeof QuickTaskOutputSchema>
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const DEFAULT_TOKEN_BUDGET = 16000
+const DEFAULT_TIMEOUT_SECONDS = 120
+const TRIVIAL_PATTERN = /fix typo|rename|format|add comment|update readme|fix lint/i
+const MAX_TRIVIAL_LENGTH = 30
+
+// ---------------------------------------------------------------------------
+// Prompt builders (pure functions)
+// ---------------------------------------------------------------------------
+
+function buildExplorerPrompt(description: string): string {
+  return [
+    `Quick exploration for: ${description}`,
+    '',
+    'Gather focused context only. Do NOT deep-dive.',
+    'Return: relevant files, key dependencies, risks.',
+    'Keep output under 500 words.',
+  ].join('\n')
+}
+
+function buildImplementerPrompt(
+  description: string,
+  planContent: string,
+  skipTests: boolean,
+): string {
+  return [
+    `## Quick Task`,
+    '',
+    description,
+    '',
+    '## Compact Plan',
+    '',
+    planContent,
+    '',
+    '## Requirements',
+    '',
+    '1. Minimal changes only — stay in scope (1-5 files)',
+    '2. Read only files necessary for the task',
+    '3. Do NOT refactor unrelated code',
+    skipTests
+      ? '4. Basic validation only (tests skipped for trivial change)'
+      : '4. Run relevant tests if they exist',
+    '5. Report every file changed',
+    '',
+    '## Scope Check',
+    '',
+    'If this task requires more than 5 files or architectural changes:',
+    'STOP and output "PROMOTED_TO_FULL_PLAN" in your response.',
+    '',
+    '## Output Format',
+    '',
+    '```json',
+    '{',
+    '  "status": "success" | "failure" | "promoted",',
+    '  "summary": "one-line description",',
+    '  "filesModified": ["path/to/file"],',
+    '  "notes": "warnings or follow-ups"',
+    '}',
+    '```',
+  ].join('\n')
+}
+
+// ---------------------------------------------------------------------------
+// Skill class
+// ---------------------------------------------------------------------------
+
+export class QuickTaskSkill extends Skill<QuickTaskInput, QuickTaskOutput> {
+  constructor() {
+    super({
+      name: 'quick-task',
+      description:
+        'Handle small, scoped tasks in an isolated worktree. Promotes to full plan if scope exceeds limit.',
+      requires: ['to-plan', 'execute-plan', 'systematic-debugging'],
+      inputSchema: QuickTaskInputSchema,
+      outputSchema: QuickTaskOutputSchema,
+    })
+  }
+
+  async execute(
+    input: QuickTaskInput,
+    context: SkillContext,
+  ): Promise<QuickTaskOutput> {
+    const { config, logger } = context
+    const dispatcher = createDispatcher(logger)
+    const guard = createMainAgentGuard({}, logger)
+    let totalTokens = 0
+
+    // Step 1: Classify scope — fast-path for trivial changes
+    logger.info(`[quick-task] Classifying: ${input.description.slice(0, 100)}`)
+    const isTrivial =
+      input.description.length < MAX_TRIVIAL_LENGTH &&
+      TRIVIAL_PATTERN.test(input.description)
+
+    if (isTrivial) {
+      logger.info('[quick-task] Trivial change detected, fast-path')
+      return {
+        status: 'complete',
+        filesModified: [],
+        risks: [],
+        summary: 'Trivial change — handled directly',
+        tokensUsed: 0,
+        durationMs: 0,
+      }
+    }
+
+    // Step 2: Research if needed (new APIs, patterns, etc.)
+    let researchContext = ''
+    const needsResearch = /api|library|npm|install|upgrade|version|pattern|how to/i.test(input.description)
+    if (needsResearch) {
+      logger.info('[quick-task] Step 2a: Researching external context...')
+      const researchResult = await dispatcher.dispatch(
+        {
+          role: 'researcher',
+          model: input.model || config.defaultModel,
+          tokenBudget: 8000,
+        },
+        researcherContract({
+          topic: input.description,
+          scope: 'technical',
+          questions: ['What are current best practices?', 'Any breaking changes or gotchas?'],
+          timeRange: '6m'
+        })
+      )
+      totalTokens += researchResult.tokensUsed
+      researchContext = researchResult.output.slice(0, 800)
+      logger.info(`[quick-task] Research complete`)
+    }
+
+    // Step 2b: Gather bounded context via read-only explorer
+    logger.info('[quick-task] Step 2b: Gathering context...')
+    const exploreResult = await dispatcher.dispatch(
+      {
+        role: 'explorer',
+        model: input.model || config.defaultModel,
+        tokenBudget: 8000,
+      },
+      {
+        permissions: {
+          readFiles: true,
+          searchCode: true,
+          runCommands: false,
+          writeFiles: false,
+          gitOperations: false,
+        },
+        prompt: buildExplorerPrompt(input.description),
+        owns: [],
+        reads: input.filesHint ?? [],
+      },
+    )
+
+    totalTokens += exploreResult.tokensUsed
+
+    // Step 3: Write compact plan to disk
+    const date = new Date().toISOString().split('T')[0]
+    const sanitized = input.description
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-')
+      .slice(0, 40)
+    const planPath = join(
+      config.planPath,
+      'quick',
+      `${date}-${sanitized}.md`,
+    )
+    await mkdir(join(config.planPath, 'quick'), { recursive: true })
+
+    const planContent = [
+      `# Quick Task: ${input.description}`,
+      '',
+      '## Context',
+      exploreResult.output.slice(0, 500),
+      ...(researchContext ? ['', '## Research', researchContext] : []),
+      '',
+      '## Verification',
+      `- Run focused tests`,
+      `- No regressions`,
+    ].join('\n')
+
+    await writeFile(planPath, planContent, 'utf-8')
+
+    // Step 4: Dispatch implementation in isolated worktree
+    guard.activateEmbargo()
+
+    try {
+      const implResult = await dispatcher.dispatch(
+        {
+          role: 'implementer',
+          model: input.model || config.defaultModel,
+          isolation: 'worktree',
+          tokenBudget: input.tokenBudget ?? DEFAULT_TOKEN_BUDGET,
+          timeout: input.timeout ?? DEFAULT_TIMEOUT_SECONDS,
+        },
+        {
+          permissions: {
+            readFiles: true,
+            searchCode: true,
+            runCommands: true,
+            writeFiles: true,
+            gitOperations: false,
+          },
+          prompt: buildImplementerPrompt(
+            input.description,
+            planContent,
+            input.skipTests ?? false,
+          ),
+          owns: [],
+          reads: input.filesHint ?? [],
+        },
+      )
+
+      totalTokens += implResult.tokensUsed
+      const needsPromotion =
+        implResult.output.includes('PROMOTED_TO_FULL_PLAN')
+
+      if (needsPromotion) {
+        return {
+          status: 'promoted',
+          planPath,
+          filesModified: [],
+          risks: ['Scope exceeded quick-task limit — promote to to-plan'],
+          summary: 'Promoted to full plan. Use to-plan for comprehensive planning.',
+          tokensUsed: totalTokens,
+          durationMs: implResult.duration,
+        }
+      }
+
+      if (implResult.status !== 'success') {
+        return {
+          status: 'needs-fixes',
+          planPath,
+          filesModified: [],
+          risks: implResult.errors,
+          summary: `Implementation failed: ${implResult.errors.join('; ')}`,
+          tokensUsed: totalTokens,
+          durationMs: implResult.duration,
+        }
+      }
+
+      // Step 5: Quick review of the changes
+      let reviewOutput = ''
+      const reviewResult = await dispatcher.dispatch(
+        {
+          role: 'reviewer',
+          model: input.model || config.defaultModel,
+          tokenBudget: 8000,
+        },
+        {
+          permissions: {
+            readFiles: true,
+            searchCode: false,
+            runCommands: false,
+            writeFiles: false,
+            gitOperations: false,
+          },
+          prompt: [
+            `Quick review of: ${input.description}`,
+            '',
+            '## Implementation Output',
+            '',
+            implResult.output.slice(0, 2000),
+            '',
+            'Check for: obvious bugs, missed edge cases, style violations.',
+            'Keep review concise — under 300 words.',
+          ].join('\n'),
+          owns: [],
+          reads: [],
+        },
+      )
+
+      totalTokens += reviewResult.tokensUsed
+      reviewOutput = reviewResult.output
+
+      const filesModified = implResult.artifacts
+        .filter((a) => a.path)
+        .map((a) => a.path as string)
+
+      return {
+        status: implResult.status === 'success' ? 'complete' : 'needs-fixes',
+        planPath,
+        filesModified,
+        verification: reviewOutput,
+        risks: [],
+        summary: implResult.output.slice(0, 200),
+        tokensUsed: totalTokens,
+        durationMs: implResult.duration,
+      }
+    } finally {
+      guard.deactivateEmbargo()
+    }
+  }
+}
+
+export const quickTaskSkill = new QuickTaskSkill()
+export default quickTaskSkill

package/src/skills/registry.ts

@@ -0,0 +1,59 @@
+/**
+ * Skill registry implementation
+ */
+import type { SkillDefinition, SkillRegistry } from './types.js'
+
+export class Registry implements SkillRegistry {
+  private skills: Map<string, SkillDefinition<any, any>> = new Map()
+
+  register(skill: SkillDefinition<any, any>): void {
+    if (this.skills.has(skill.name)) {
+      throw new Error(`Skill already registered: ${skill.name}`)
+    }
+    this.skills.set(skill.name, skill)
+  }
+
+  unregister(name: string): void {
+    this.skills.delete(name)
+  }
+
+  get(name: string): SkillDefinition<any, any> | null {
+    return this.skills.get(name) || null
+  }
+
+  list(): SkillDefinition<any, any>[] {
+    return Array.from(this.skills.values())
+  }
+
+  getDependencies(name: string): string[] {
+    const skill = this.get(name)
+    return skill?.requires || []
+  }
+
+  resolveOrder(skillNames: string[]): string[] {
+    const visited = new Set<string>()
+    const result: string[] = []
+
+    const visit = (name: string) => {
+      if (visited.has(name)) return
+      visited.add(name)
+
+      const deps = this.getDependencies(name)
+      for (const dep of deps) {
+        visit(dep)
+      }
+
+      result.push(name)
+    }
+
+    for (const name of skillNames) {
+      visit(name)
+    }
+
+    return result
+  }
+}
+
+export function createRegistry(): SkillRegistry {
+  return new Registry()
+}

package/src/skills/review-diff/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: review-diff
+description: Review code changes via reviewer subagents. Returns structured report with severity-classified issues.
+requires: []
+---
+
+## ⛔ 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 |
+|---|---|
+| Reviewing branch, PR, commit, or diff file | No diff/changes to review |
+| Pre-merge quality gate | Trivial one-line change |
+| Need structured issue report | Review is purely informational (no action needed) |
+| Spec compliance check against a plan | Plan file unavailable and spec check not required |
+
+## Workflow
+
+1. **Get Diff** — Dispatch explorer subagent to fetch diff via git/gh/cat depending on target type.
+2. **Inspect Surface** — Dispatch explorer to analyze changed files, line counts, and scope.
+3. **Check Spec Compliance** — If plan path provided, dispatch reviewer to compare implementation against plan requirements.
+4. **Assess Tests** — Dispatch reviewer to check whether changed files have corresponding test changes.
+5. **Review Quality** — Dispatch reviewer to check correctness, security, performance, style, error handling.
+6. **Compile Report** — Parse structured issue output into final report with decision.
+
+## Output Spec
+
+| Field | Type | Description |
+|---|---|---|
+| `decision` | enum | `approve`, `changes`, `blocked`, `needs-evidence` |
+| `issues` | array | Each with severity (blocker/major/minor/note), file, line, description, action |
+| `specCompliance` | enum | `pass`, `partial`, `fail` |
+| `testAssessment` | enum | `adequate`, `missing`, `failing` |
+| `strengths` | string[] | Positive observations |
+| `summary` | string | Human-readable review summary |
+| `tokensUsed` | number | Total tokens consumed |
+
+## Error Handling
+
+| Error | Action |
+|---|---|
+| Cannot access diff (bad target) | Return decision=needs-evidence with blocker issue |
+| Diff subagent fails | Return needs-evidence; caller verifies target exists |
+| Quality review produces no parseable issues | Return approve with empty issues list |
+| Plan file not found for spec check | Skip spec compliance; mark as partial |