@haoyiyin/workflow 0.2.2 → 0.2.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haoyiyin/workflow",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "type": "module",
   "description": "Production workflow skills for planning, executing, reviewing, and finishing coding-agent work",
   "main": "./dist/index.js",
@@ -32,6 +32,7 @@
   "files": [
     "dist/",
     "scripts/",
+    "src/",
     "yi-workflow.js",
     "README.md",
     "SETUP.md",
@@ -57,13 +58,13 @@
       "./dist/pi-extension.js"
     ],
     "skills": [
-      "./dist/skills/to-plan/SKILL.md",
-      "./dist/skills/execute-plan/SKILL.md",
-      "./dist/skills/quick-task/SKILL.md",
-      "./dist/skills/review-diff/SKILL.md",
-      "./dist/skills/tdd/SKILL.md",
-      "./dist/skills/systematic-debugging/SKILL.md",
-      "./dist/skills/agents-md/SKILL.md"
+      "./src/skills/to-plan/SKILL.md",
+      "./src/skills/execute-plan/SKILL.md",
+      "./src/skills/quick-task/SKILL.md",
+      "./src/skills/review-diff/SKILL.md",
+      "./src/skills/tdd/SKILL.md",
+      "./src/skills/systematic-debugging/SKILL.md",
+      "./src/skills/agents-md/SKILL.md"
     ],
     "prompts": [
       "./dist/prompts"

package/src/agents/contracts.ts

@@ -0,0 +1,559 @@
+/**
+ * Pre-built SubagentContracts for each subagent role.
+ *
+ * Each factory accepts role-specific parameters and returns a fully-formed
+ * SubagentContract ready for dispatch. The contracts encode:
+ *   - The exact permission set the subagent needs
+ *   - Which files it may own (modify) vs. read
+ *   - A structured prompt template
+ *   - An optional output schema for validation
+ */
+
+import type { SubagentContract, PermissionSet } from './types.js';
+
+// ---------------------------------------------------------------------------
+// Permission presets
+// ---------------------------------------------------------------------------
+
+const READ_ONLY: PermissionSet = {
+  readFiles: true,
+  searchCode: true,
+  runCommands: false,
+  writeFiles: false,
+  gitOperations: false,
+};
+
+const READ_SEARCH: PermissionSet = {
+  readFiles: true,
+  searchCode: true,
+  runCommands: false,
+  writeFiles: false,
+  gitOperations: false,
+};
+
+const READ_RUN: PermissionSet = {
+  readFiles: true,
+  searchCode: true,
+  runCommands: true,
+  writeFiles: false,
+  gitOperations: false,
+};
+
+const FULL_ACCESS: PermissionSet = {
+  readFiles: true,
+  searchCode: true,
+  runCommands: true,
+  writeFiles: true,
+  gitOperations: true,
+};
+
+// ---------------------------------------------------------------------------
+// Contract parameter types
+// ---------------------------------------------------------------------------
+
+export interface ExplorerParams {
+  /** What the explorer should search for */
+  query: string;
+  /** Directories or file patterns to search within */
+  searchPaths: string[];
+  /** Files the explorer may read (beyond search results) */
+  readFiles?: string[];
+  /** Specific questions to answer */
+  questions?: string[];
+}
+
+export interface ImplementerParams {
+  /** Description of what to implement */
+  task: string;
+  /** Files the implementer may modify */
+  ownedFiles: string[];
+  /** Files the implementer may read for context */
+  readFiles?: string[];
+  /** Test command to run after implementation */
+  testCommand?: string;
+  /** Constraints or requirements */
+  constraints?: string[];
+}
+
+export interface ReviewerParams {
+  /** What to review (PR description, diff summary, etc.) */
+  target: string;
+  /** Files to review */
+  reviewFiles: string[];
+  /** Specific areas of concern */
+  focusAreas?: string[];
+  /** Review criteria */
+  criteria?: string[];
+}
+
+export interface DebuggerParams {
+  /** Description of the failure / bug */
+  issue: string;
+  /** Files likely involved in the bug */
+  suspectFiles: string[];
+  /** Error messages or stack traces */
+  errorOutput?: string;
+  /** Steps to reproduce */
+  reproSteps?: string[];
+}
+
+export interface VerifierParams {
+  /** The original goal / requirement */
+  goal: string;
+  /** The plan that was executed */
+  plan: string;
+  /** Files that were changed */
+  changedFiles: string[];
+  /** Acceptance criteria */
+  acceptanceCriteria: string[];
+}
+
+export interface ResearcherParams {
+  /** Research topic or question */
+  topic: string;
+  /** Specific questions to answer */
+  questions?: string[];
+  /** Search scope: technical, business, security, etc. */
+  scope?: 'technical' | 'business' | 'security' | 'general';
+  /** Maximum results to return */
+  maxResults?: number;
+  /** Time range for results (e.g., '1y', '6m', '1w') */
+  timeRange?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Contract factories
+// ---------------------------------------------------------------------------
+
+/**
+ * Explorer contract: read-only, searches the codebase to answer questions
+ * about structure, dependencies, patterns, or specific implementations.
+ */
+export function explorerContract(params: ExplorerParams): SubagentContract {
+  const reads = [...params.searchPaths, ...(params.readFiles ?? [])];
+  const questionsBlock =
+    params.questions && params.questions.length > 0
+      ? `\n\n## Questions to Answer\n\n${params.questions.map((q, i) => `${i + 1}. ${q}`).join('\n')}`
+      : '';
+
+  const prompt = [
+    `Search the codebase for information related to: **${params.query}**`,
+    '',
+    `## Search Scope`,
+    '',
+    params.searchPaths.map((p) => `- \`${p}\``).join('\n'),
+    '',
+    'For each relevant file found, report:',
+    '- File path and purpose',
+    '- Key exports, functions, or classes',
+    '- Dependencies and imports',
+    '- Any notable patterns or issues',
+    questionsBlock,
+  ].join('\n');
+
+  return {
+    permissions: READ_SEARCH,
+    prompt,
+    owns: [],
+    reads,
+  };
+}
+
+/**
+ * Implementer contract: writes code, runs tests, works in isolation.
+ * The implementer owns specific files and may modify them.
+ */
+export function implementerContract(
+  params: ImplementerParams,
+): SubagentContract {
+  const constraintsBlock =
+    params.constraints && params.constraints.length > 0
+      ? `\n\n## Constraints\n\n${params.constraints.map((c) => `- ${c}`).join('\n')}`
+      : '';
+
+  const testBlock = params.testCommand
+    ? `\n\n## Verification\n\nAfter implementing, run this command to verify:\n\n\`\`\`bash\n${params.testCommand}\n\`\`\``
+    : '';
+
+  const prompt = [
+    `Implement the following task:`,
+    '',
+    params.task,
+    '',
+    '## Files You Own (may modify)',
+    '',
+    params.ownedFiles.map((f) => `- \`${f}\``).join('\n'),
+    '',
+    '## Approach',
+    '',
+    '1. Read all owned files to understand current state',
+    '2. Implement the changes',
+    '3. Verify the code compiles',
+    '4. Run the test command if provided',
+    '5. Report what you changed and why',
+    constraintsBlock,
+    testBlock,
+    '',
+    '## Output Format',
+    '',
+    'Respond with a JSON block containing:',
+    '```json',
+    '{ "summary": "...", "filesChanged": [...], "testResult": "..." }',
+    '```',
+  ].join('\n');
+
+  return {
+    permissions: FULL_ACCESS,
+    outputSchema: {
+      summary: 'string',
+      filesChanged: 'object',
+      testResult: 'string',
+    },
+    prompt,
+    owns: [...params.ownedFiles],
+    reads: [...(params.readFiles ?? []), ...params.ownedFiles],
+  };
+}
+
+/**
+ * Reviewer contract: reads code changes and produces a structured review
+ * report covering correctness, style, security, and performance.
+ */
+export function reviewerContract(params: ReviewerParams): SubagentContract {
+  const focusBlock =
+    params.focusAreas && params.focusAreas.length > 0
+      ? `\n\n## Focus Areas\n\n${params.focusAreas.map((a) => `- ${a}`).join('\n')}`
+      : '';
+
+  const criteriaBlock =
+    params.criteria && params.criteria.length > 0
+      ? `\n\n## Review Criteria\n\n${params.criteria.map((c) => `- ${c}`).join('\n')}`
+      : '';
+
+  const prompt = [
+    `Review the following change:`,
+    '',
+    `> ${params.target}`,
+    '',
+    '## Files to Review',
+    '',
+    params.reviewFiles.map((f) => `- \`${f}\``).join('\n'),
+    '',
+    '## Review Checklist',
+    '',
+    'For each file, evaluate:',
+    '- **Correctness**: Does the logic do what it claims?',
+    '- **Edge Cases**: Are boundary conditions handled?',
+    '- **Error Handling**: Are errors caught and handled gracefully?',
+    '- **Immutability**: Are objects/arrays mutated or replaced?',
+    '- **Naming**: Are names clear and conventional?',
+    '- **Security**: Any injection risks, leaked secrets, or unsafe patterns?',
+    '- **Performance**: Any obvious N+1 queries, unnecessary allocations, or blocking calls?',
+    focusBlock,
+    criteriaBlock,
+    '',
+    '## Output Format',
+    '',
+    'Respond with a JSON block containing:',
+    '```json',
+    '{ "verdict": "approve|request_changes|comment", "summary": "...", "findings": [{ "severity": "critical|high|medium|low", "file": "...", "line": ..., "message": "...", "suggestion": "..." }] }',
+    '```',
+  ].join('\n');
+
+  return {
+    permissions: READ_ONLY,
+    outputSchema: {
+      verdict: 'string',
+      summary: 'string',
+      findings: 'object',
+    },
+    prompt,
+    owns: [],
+    reads: [...params.reviewFiles],
+  };
+}
+
+/**
+ * Debugger contract: analyses failures, identifies root causes, and
+ * proposes minimal fixes. Read-only unless explicitly allowed to write.
+ */
+export function debuggerContract(params: DebuggerParams): SubagentContract {
+  const errorBlock = params.errorOutput
+    ? `\n\n## Error Output\n\n\`\`\`\n${params.errorOutput}\n\`\`\``
+    : '';
+
+  const reproBlock =
+    params.reproSteps && params.reproSteps.length > 0
+      ? `\n\n## Reproduction Steps\n\n${params.reproSteps.map((s, i) => `${i + 1}. ${s}`).join('\n')}`
+      : '';
+
+  const prompt = [
+    `Investigate and find the root cause of this issue:`,
+    '',
+    `> ${params.issue}`,
+    '',
+    '## Suspect Files',
+    '',
+    params.suspectFiles.map((f) => `- \`${f}\``).join('\n'),
+    errorBlock,
+    reproBlock,
+    '',
+    '## Process',
+    '',
+    '1. Read each suspect file carefully',
+    '2. Trace the execution path that leads to the failure',
+    '3. Identify the root cause (not just the symptom)',
+    '4. Propose a minimal, safe fix',
+    '5. Explain why the fix addresses the root cause',
+    '',
+    '## Output Format',
+    '',
+    'Respond with a JSON block containing:',
+    '```json',
+    '{ "rootCause": "...", "confidence": "high|medium|low", "fixDescription": "...", "affectedFiles": [...], "prevention": "..." }',
+    '```',
+  ].join('\n');
+
+  return {
+    permissions: READ_RUN,
+    outputSchema: {
+      rootCause: 'string',
+      confidence: 'string',
+      fixDescription: 'string',
+      affectedFiles: 'object',
+      prevention: 'string',
+    },
+    prompt,
+    owns: [],
+    reads: [...params.suspectFiles],
+  };
+}
+
+/**
+ * Verifier contract: goal-backward verification. Checks that the
+ * implemented changes actually satisfy the original requirements by
+ * working backward from the goal through each acceptance criterion.
+ */
+export function verifierContract(params: VerifierParams): SubagentContract {
+  const criteriaList = params.acceptanceCriteria
+    .map((c, i) => `${i + 1}. ${c}`)
+    .join('\n');
+
+  const prompt = [
+    `Verify that the implemented changes satisfy the original goal.`,
+    '',
+    '## Original Goal',
+    '',
+    params.goal,
+    '',
+    '## Execution Plan',
+    '',
+    params.plan,
+    '',
+    '## Changed Files',
+    '',
+    params.changedFiles.map((f) => `- \`${f}\``).join('\n'),
+    '',
+    '## Acceptance Criteria',
+    '',
+    criteriaList,
+    '',
+    '## Verification Process',
+    '',
+    'Work backward from each acceptance criterion:',
+    '1. For each criterion, identify what evidence would prove it is met',
+    '2. Check the changed files for that evidence',
+    '3. Mark each criterion as PASS, FAIL, or UNCERTAIN',
+    '4. If any criterion fails, explain the gap',
+    '5. Produce a final verdict',
+    '',
+    '## Output Format',
+    '',
+    'Respond with a JSON block containing:',
+    '```json',
+    '{ "verdict": "pass|fail|partial", "criteriaResults": [{ "criterion": "...", "status": "pass|fail|uncertain", "evidence": "..." }], "gaps": [...], "recommendation": "..." }',
+    '```',
+  ].join('\n');
+
+  return {
+    permissions: READ_ONLY,
+    outputSchema: {
+      verdict: 'string',
+      criteriaResults: 'object',
+      gaps: 'object',
+      recommendation: 'string',
+    },
+    prompt,
+    owns: [],
+    reads: [...params.changedFiles],
+  };
+}
+
+/**
+ * Researcher contract: searches the internet for information on a topic.
+ * Returns structured research findings with sources.
+ */
+export function researcherContract(params: ResearcherParams): SubagentContract {
+  const scopeText = {
+    technical: 'Focus on technical documentation, GitHub repos, Stack Overflow, and official docs.',
+    business: 'Focus on industry reports, market analysis, and business news.',
+    security: 'Focus on CVE databases, security advisories, and best practices.',
+    general: 'Broad search across all sources.',
+  }[params.scope ?? 'general'];
+
+  const questionsBlock =
+    params.questions && params.questions.length > 0
+      ? `\n\n## Specific Questions to Answer\n\n${params.questions.map((q, i) => `${i + 1}. ${q}`).join('\n')}`
+      : '';
+
+  const timeRangeText = params.timeRange
+    ? `\n\n## Time Range\nPrioritize results from the last ${params.timeRange}.`
+    : '';
+
+  const prompt = [
+    `Research the following topic: **${params.topic}**`,
+    '',
+    '## Search Scope',
+    '',
+    scopeText,
+    timeRangeText,
+    '',
+    '## Instructions',
+    '',
+    '1. Search the internet for relevant, authoritative sources',
+    '2. For each source, evaluate: credibility, recency, relevance',
+    '3. Synthesize findings into actionable insights',
+    '4. Note any conflicting information or uncertainties',
+    '',
+    '## Source Quality Guidelines',
+    '',
+    '- **Technical**: Official docs > GitHub repos > Stack Overflow > Blog posts',
+    '- **Business**: Industry reports > News articles > Company blogs',
+    '- **Security**: CVE databases > Official advisories > Security blogs',
+    '',
+    '## Anti-Patterns to Avoid',
+    '',
+    '- Do NOT rely on outdated information (>2 years old unless historical)',
+    '- Do NOT cite low-credibility sources (unverified blogs, forums)',
+    '- Do NOT make assumptions beyond what sources confirm',
+    '',
+    '## Output Format',
+    '',
+    'Respond with a JSON block containing:',
+    '```json',
+    '{',
+    '  "summary": "Executive summary (2-3 sentences)",',
+    '  "findings": [',
+    '    {',
+    '      "insight": "Key finding or answer",',
+    '      "confidence": "high|medium|low",',
+    '      "sources": [{ "title": "...", "url": "...", "date": "..." }]',
+    '    }',
+    '  ],',
+    '  "recommendations": ["Actionable recommendations based on research"],',
+    '  "knowledgeGaps": ["Questions that could not be answered"]',
+    '}',
+    '```',
+    questionsBlock,
+  ].join('\n');
+
+  return {
+    permissions: {
+      ...READ_ONLY,
+      // Researcher needs web search capability
+      runCommands: true,  // For web search/fetch via subagent
+    },
+    outputSchema: {
+      summary: 'string',
+      findings: 'object',
+      recommendations: 'object',
+      knowledgeGaps: 'object',
+    },
+    prompt,
+    owns: [],
+    reads: [],
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Worktree contract - Replaces worktree-start skill
+// ---------------------------------------------------------------------------
+
+export interface WorktreeParams {
+  /** Branch name for the new worktree */
+  branchName: string;
+  /** Base branch to create from (default: main) */
+  baseBranch?: string;
+  /** Whether to enable full isolation */
+  isolation?: boolean;
+}
+
+/**
+ * Worktree contract: Creates isolated git worktrees for parallel work.
+ * Replaces the worktree-start skill with a direct subagent dispatch.
+ */
+export function worktreeContract(params: WorktreeParams): SubagentContract {
+  const baseBranch = params.baseBranch || 'main';
+  const worktreePath = `.claude/worktrees/${params.branchName}`;
+
+  const prompt = [
+    `Create a git worktree for branch: ${params.branchName}`,
+    '',
+    `**Base Branch**: ${baseBranch}`,
+    `**Worktree Path**: ${worktreePath}`,
+    '',
+    '## Steps',
+    '',
+    '1. Inspect current repo state:',
+    '   - `git rev-parse --show-toplevel` — get repo root',
+    '   - `git status --porcelain --branch` — check current branch',
+    '   - `git branch -a` — list all branches',
+    '',
+    '2. Create worktree:',
+    `   - If branch exists: \`git worktree add ${worktreePath} ${params.branchName}\``,
+    `   - If branch does not exist: \`git worktree add ${worktreePath} -b ${params.branchName} origin/${baseBranch}\``,
+    '',
+    '3. Verify creation:',
+    '   - `git worktree list`',
+    '',
+    '## Error Recovery',
+    '',
+    `- If worktree path exists: \`git worktree remove ${worktreePath} --force\` then retry`,
+    `- If branch exists but worktree missing: \`git worktree add ${worktreePath} ${params.branchName}\``,
+    '',
+    '## Output Format',
+    '',
+    'Return JSON:',
+    '```json',
+    '{',
+    '  "worktreePath": "absolute/path/to/worktree",',
+    '  "branchName": "' + params.branchName + '",',
+    '  "baseBranch": "' + baseBranch + '",',
+    '  "repoRoot": "absolute/path/to/repo",',
+    '  "status": "created|reused|failed",',
+    '  "error": "error message if failed"',
+    '}',
+    '```',
+  ].join('\n');
+
+  return {
+    permissions: {
+      readFiles: true,
+      searchCode: false,
+      runCommands: true,
+      writeFiles: false,
+      gitOperations: true,
+    },
+    outputSchema: {
+      worktreePath: 'string',
+      branchName: 'string',
+      baseBranch: 'string',
+      repoRoot: 'string',
+      status: 'string',
+      error: 'string',
+    },
+    prompt,
+    owns: [],
+    reads: [],
+  };
+}