@miphamai/cli 0.13.0 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miphamai/cli",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Mipham Code — Multi-model open-core intelligent coding terminal by MiphamAI",
   "keywords": [
     "ai",

package/skills/workflows/audit.js

@@ -0,0 +1,51 @@
+export const meta = {
+  name: 'audit',
+  description: 'Security audit: fan-out per file → verify → report',
+  phases: [
+    { title: 'Scope', detail: 'discover targets' },
+    { title: 'Audit', detail: 'one agent per target' },
+    { title: 'Verify', detail: 'adversarial verification' },
+    { title: 'Report', detail: 'synthesize findings' },
+  ],
+}
+
+phase('Scope')
+const targets = args.targets || (await agent(
+  'List all source files that need security auditing. Return { files: [{ path, reason }] }',
+  { schema: { type: 'object', properties: { files: { type: 'array', items: { type: 'object', properties: { path: { type: 'string' }, reason: { type: 'string' } }, required: ['path', 'reason'] } } }, required: ['files'] } },
+)).files
+
+log(`Auditing ${targets.length} files`)
+
+phase('Audit')
+const raw = (await pipeline(
+  targets,
+  t => agent(`Security audit ${t.path}: injection, auth, crypto, secrets, input validation. Return { findings: [{ severity, file, line, summary }] }`,
+    { label: `audit:${t.path}`, schema: { type: 'object', properties: { findings: { type: 'array', items: { type: 'object', properties: { severity: { type: 'string', enum: ['critical', 'high', 'medium', 'low'] }, file: { type: 'string' }, line: { type: 'number' }, summary: { type: 'string' } }, required: ['severity', 'file', 'summary'] } } }, required: ['findings'] } },
+  )),
+)
+const findings = raw.flatMap(r => (r && r.findings) || [])
+
+log(`Found ${findings.length} potential issues`)
+
+phase('Verify')
+const verified = await parallel(
+  findings.map(f => () =>
+    verify(f, {
+      mode: 'adversarial',
+      skeptics: 3,
+      threshold: 2,
+      schema: { type: 'object', properties: { real: { type: 'boolean' }, reason: { type: 'string' } }, required: ['real', 'reason'] },
+    })
+  ),
+)
+
+const confirmed = verified.filter(Boolean).filter(v => v.survives).map(v => v.finding)
+log(`${confirmed.length}/${findings.length} findings verified`)
+
+phase('Report')
+const report = await agent(
+  `Synthesize audit report from confirmed findings:\n${JSON.stringify(confirmed)}`,
+  { label: 'report' },
+)
+return report

package/skills/workflows/hunt.js

@@ -0,0 +1,95 @@
+export const meta = {
+  name: 'hunt',
+  description: 'Bug hunt: loopUntilConvergence + adversarial verify',
+  phases: [
+    { title: 'Hunt', detail: 'iterative discovery + verify' },
+    { title: 'Report', detail: 'synthesize findings' },
+  ],
+}
+
+phase('Hunt')
+const target = args.target || 'this codebase'
+
+const { confirmed, totalSeen, rounds, converged } = await loopUntilConvergence({
+  finders: [
+    () =>
+      agent(
+        `Find bugs in ${target}. Look for: null safety, race conditions, resource leaks, edge cases. Return { items: [{ file, line, summary, type }] }`,
+        {
+          label: 'hunt:general',
+          schema: {
+            type: 'object',
+            properties: {
+              items: {
+                type: 'array',
+                items: {
+                  type: 'object',
+                  properties: {
+                    file: { type: 'string' },
+                    line: { type: 'number' },
+                    summary: { type: 'string' },
+                    type: { type: 'string' },
+                  },
+                  required: ['file', 'summary', 'type'],
+                },
+              },
+            },
+            required: ['items'],
+          },
+        },
+      ),
+    () =>
+      agent(
+        `Find security vulnerabilities in ${target}: injection, auth bypass, insecure crypto, exposed secrets. Return { items: [{ file, line, summary, type }] }`,
+        {
+          label: 'hunt:security',
+          schema: {
+            type: 'object',
+            properties: {
+              items: {
+                type: 'array',
+                items: {
+                  type: 'object',
+                  properties: {
+                    file: { type: 'string' },
+                    line: { type: 'number' },
+                    summary: { type: 'string' },
+                    type: { type: 'string' },
+                  },
+                  required: ['file', 'summary', 'type'],
+                },
+              },
+            },
+            required: ['items'],
+          },
+        },
+      ),
+  ],
+  keyFn: (bug) => `${bug.file}:${bug.line}:${bug.summary}`,
+  verify: async (bug) =>
+    verify(bug, {
+      mode: 'adversarial',
+      skeptics: 3,
+      threshold: 2,
+      schema: {
+        type: 'object',
+        properties: { real: { type: 'boolean' }, reason: { type: 'string' } },
+        required: ['real', 'reason'],
+      },
+    }),
+  dryRounds: 2,
+  maxRounds: 10,
+})
+
+log(
+  `${converged ? 'Converged' : 'Max rounds reached'} after ${rounds} rounds. ${totalSeen} unique bugs seen, ${confirmed.length} confirmed.`,
+)
+
+phase('Report')
+if (confirmed.length === 0) {
+  return `No confirmed bugs found after ${rounds} rounds of hunting.`
+}
+return await agent(
+  `Write a bug report from ${confirmed.length} confirmed bugs:\n${JSON.stringify(confirmed)}`,
+  { label: 'report' },
+)

package/skills/workflows/judge.js

@@ -0,0 +1,55 @@
+export const meta = {
+  name: 'judge',
+  description: 'Judge panel: N competing approaches × M judges → winner + synthesis',
+  phases: [
+    { title: 'Generate', detail: 'generate competing approaches' },
+    { title: 'Judge', detail: 'score and rank' },
+    { title: 'Synthesize', detail: 'final recommendation' },
+  ],
+}
+
+phase('Generate')
+const problem = args.problem || (await agent('What problem are we solving?', { label: 'query' }))
+
+const approaches = await parallel([
+  () => agent(`Solve "${problem}" with an MVP-first approach.`, { label: 'gen:mvp' }),
+  () => agent(`Solve "${problem}" with a risk-first approach.`, { label: 'gen:risk' }),
+  () => agent(`Solve "${problem}" with a user-first approach.`, { label: 'gen:user' }),
+])
+
+const validApproaches = approaches.filter(Boolean)
+log(`Generated ${validApproaches.length} approaches`)
+
+phase('Judge')
+const { winner, winnerIndex, scores, synthesis } = await judge(validApproaches, {
+  criteria: ['feasibility', 'impact', 'simplicity', 'risk'],
+  judges: 3,
+  synthesize: true,
+  schema: {
+    type: 'object',
+    properties: {
+      scores: {
+        type: 'object',
+        properties: {
+          feasibility: { type: 'number' },
+          impact: { type: 'number' },
+          simplicity: { type: 'number' },
+          risk: { type: 'number' },
+        },
+        required: ['feasibility', 'impact', 'simplicity', 'risk'],
+      },
+      notes: { type: 'string' },
+    },
+    required: ['scores', 'notes'],
+  },
+})
+
+phase('Synthesize')
+return {
+  problem,
+  winner: `Approach #${winnerIndex + 1}`,
+  scores_summary: scores.map(
+    (s) => `Judge ${s.judgeIndex + 1}: approach ${s.attemptIndex + 1} = ${s.total}`,
+  ),
+  synthesis,
+}

package/skills/workflows/migrate.js

@@ -0,0 +1,92 @@
+export const meta = {
+  name: 'migrate',
+  description: 'Code migration: discover → fan-out transform → verify → integrate',
+  phases: [
+    { title: 'Discover', detail: 'find migration targets' },
+    { title: 'Transform', detail: 'one agent per file' },
+    { title: 'Verify', detail: 'validate transformations' },
+  ],
+}
+
+phase('Discover')
+const pattern =
+  args.pattern ||
+  (await agent('What code pattern needs migration? Return { pattern, replacement, reason }', {
+    schema: {
+      type: 'object',
+      properties: {
+        pattern: { type: 'string' },
+        replacement: { type: 'string' },
+        reason: { type: 'string' },
+      },
+      required: ['pattern', 'replacement'],
+    },
+  }))
+
+const files = await agent(
+  `Find all files matching pattern: ${pattern.pattern}. Return { files: [{ path }] }`,
+  {
+    schema: {
+      type: 'object',
+      properties: {
+        files: {
+          type: 'array',
+          items: { type: 'object', properties: { path: { type: 'string' } }, required: ['path'] },
+        },
+      },
+      required: ['files'],
+    },
+  },
+)
+
+log(`Migrating ${files.files.length} files: ${pattern.pattern} → ${pattern.replacement}`)
+
+phase('Transform')
+const results = await pipeline(files.files, (f) =>
+  agent(
+    `In ${f.path}, migrate "${pattern.pattern}" to "${pattern.replacement}". Reason: ${pattern.reason}. Return { path, changes, success }`,
+    {
+      label: `migrate:${f.path}`,
+      isolation: 'worktree',
+      schema: {
+        type: 'object',
+        properties: {
+          path: { type: 'string' },
+          changes: { type: 'number' },
+          success: { type: 'boolean' },
+        },
+        required: ['path', 'success'],
+      },
+    },
+  ),
+)
+
+const succeeded = results.filter(Boolean).filter((r) => r.success)
+const failed = results.filter(Boolean).filter((r) => !r.success)
+log(`${succeeded.length} migrated, ${failed.length} failed`)
+
+phase('Verify')
+const verified = await parallel(
+  succeeded.map(
+    (f) => () =>
+      verify(
+        { file: f.path, migration: pattern.replacement },
+        {
+          mode: 'perspective',
+          lenses: ['correctness', 'style'],
+          threshold: 1,
+          schema: {
+            type: 'object',
+            properties: { real: { type: 'boolean' }, reason: { type: 'string' } },
+            required: ['real', 'reason'],
+          },
+        },
+      ),
+  ),
+)
+
+return {
+  migrated: succeeded.length,
+  failed: failed.length,
+  verified: verified.filter(Boolean).filter((v) => v.survives).length,
+}

package/skills/workflows/research.js

@@ -0,0 +1,87 @@
+export const meta = {
+  name: 'research',
+  description: 'Deep research: scope → parallel search → verify → synthesize',
+  phases: [
+    { title: 'Scope', detail: 'define research angles' },
+    { title: 'Research', detail: 'parallel web searches' },
+    { title: 'Verify', detail: 'adversarial verification' },
+    { title: 'Synthesize', detail: 'final report' },
+  ],
+}
+
+phase('Scope')
+const topic = args.topic || (await agent('What topic should we research?', { label: 'query' }))
+
+phase('Research')
+const angles = ['overview', 'technical-details', 'competitors', 'criticism', 'future-trends']
+const raw = await parallel(
+  angles.map(
+    (angle) => () =>
+      agent(
+        `Research "${topic}" from angle: ${angle}. Return { sources: [{ title, url, keyPoint }] }`,
+        {
+          label: `research:${angle}`,
+          schema: {
+            type: 'object',
+            properties: {
+              sources: {
+                type: 'array',
+                items: {
+                  type: 'object',
+                  properties: {
+                    title: { type: 'string' },
+                    url: { type: 'string' },
+                    keyPoint: { type: 'string' },
+                  },
+                  required: ['title', 'keyPoint'],
+                },
+              },
+            },
+            required: ['sources'],
+          },
+        },
+      ),
+  ),
+)
+
+const allSources = raw.filter(Boolean).flatMap((r) => r.sources)
+const seen = new Set()
+const unique = allSources.filter((s) => {
+  const k = s.url
+  if (seen.has(k)) return false
+  seen.add(k)
+  return true
+})
+log(`Collected ${unique.length} unique sources`)
+
+phase('Verify')
+const verified = await parallel(
+  unique.map(
+    (s) => () =>
+      verify(
+        { claim: s.keyPoint, source: s.title },
+        {
+          mode: 'adversarial',
+          skeptics: 2,
+          threshold: 1,
+          schema: {
+            type: 'object',
+            properties: { real: { type: 'boolean' }, reason: { type: 'string' } },
+            required: ['real', 'reason'],
+          },
+        },
+      ),
+  ),
+)
+
+const credible = verified
+  .filter(Boolean)
+  .filter((v) => v.survives)
+  .map((v) => v.finding)
+
+phase('Synthesize')
+const report = await agent(
+  `Synthesize research report on "${topic}" from credible sources:\n${JSON.stringify(credible)}`,
+  { label: 'synthesize' },
+)
+return report

package/skills/workflows/review.js

@@ -0,0 +1,92 @@
+export const meta = {
+  name: 'review',
+  description: 'Code review: fan-out per dimension → judge panel → report',
+  phases: [
+    { title: 'Review', detail: 'multi-dimensional review' },
+    { title: 'Judge', detail: 'judge panel scores findings' },
+    { title: 'Report', detail: 'final review report' },
+  ],
+}
+
+phase('Review')
+const dimensions = ['correctness', 'security', 'performance', 'maintainability']
+const rawFindings = await parallel(
+  dimensions.map(
+    (d) => () =>
+      agent(
+        `Review the code from the "${d}" lens. Return { findings: [{ severity, file, line, summary }] }`,
+        {
+          label: `review:${d}`,
+          schema: {
+            type: 'object',
+            properties: {
+              findings: {
+                type: 'array',
+                items: {
+                  type: 'object',
+                  properties: {
+                    severity: { type: 'string', enum: ['blocker', 'high', 'medium', 'low'] },
+                    file: { type: 'string' },
+                    line: { type: 'number' },
+                    summary: { type: 'string' },
+                    dimension: { type: 'string' },
+                  },
+                  required: ['severity', 'file', 'summary'],
+                },
+              },
+            },
+            required: ['findings'],
+          },
+        },
+      ),
+  ),
+)
+
+// Edge logic: dedup across dimensions (pure JS)
+const allFindings = rawFindings.filter(Boolean).flatMap((r) => r.findings)
+const seen = new Set()
+const uniqueFindings = allFindings.filter((f) => {
+  const k = `${f.file}:${f.line}:${f.summary}`
+  if (seen.has(k)) return false
+  seen.add(k)
+  return true
+})
+
+log(`${uniqueFindings.length} unique findings across ${dimensions.length} dimensions`)
+
+phase('Judge')
+if (uniqueFindings.length === 0) {
+  return 'No findings — code looks clean across all dimensions.'
+}
+
+// Judge panel: rank findings by severity
+const judged = await judge(
+  uniqueFindings.map((f) => ({ finding: f })),
+  {
+    criteria: ['severity', 'actionability', 'confidence'],
+    judges: 2,
+    synthesize: false,
+    schema: {
+      type: 'object',
+      properties: {
+        scores: {
+          type: 'object',
+          properties: {
+            severity: { type: 'number' },
+            actionability: { type: 'number' },
+            confidence: { type: 'number' },
+          },
+          required: ['severity', 'actionability', 'confidence'],
+        },
+        notes: { type: 'string' },
+      },
+      required: ['scores', 'notes'],
+    },
+  },
+)
+
+phase('Report')
+return await agent(
+  `Write a code review report from ${uniqueFindings.length} findings (ranked by judge panel). Top finding: ${JSON.stringify(judged.winner)}`,
+  { label: 'report' },
+)

package/src/core/instructions.ts

@@ -66,6 +66,34 @@ export class InstructionsLoader {
       parts.push(this.skillsReminder)
     }
 
+    // Inject workflow auto-generation guidance
+    parts.push(`## Workflow Auto-Generation
+
+When a task involves 3+ independent subtasks, multi-file operations,
+or unknown-size discovery, generate a workflow script and execute it
+via the Workflow tool instead of running agents sequentially. The
+orchestration itself is code (zero tokens for inter-agent coordination).
+
+Prefer workflows for: audits across many files, web research with multiple
+sources, code migrations touching many files, security scans, bug hunts
+with unknown scope, multi-dimensional code reviews.
+
+Available primitives: agent(), parallel(), pipeline(), verify(),
+judge(), loopUntilConvergence(), phase(), log(), args, budget.
+
+Key rules:
+- Default to pipeline() — only use parallel() barrier when a stage
+  genuinely needs all prior results at once
+- Edge logic (flatten, dedupe, filter) is plain JS — not agent calls
+- Use verify() on edges where confidence matters
+- Use loopUntilConvergence() for discovery tasks with unknown size
+
+When a workflow completes successfully, offer to save it:
+"Workflow complete. Save this script? /workflow save <name>"
+
+Script format: export const meta = { name, description, phases: [...] }
+// script body using primitives...`)
+
     return parts.join('\n\n---\n\n')
   }
 

package/src/tools/agent/workflow.ts

@@ -5,9 +5,56 @@ import type { QueryEngine } from '../../core/engine'
 export const workflowTool: ToolDefinition = {
   name: 'Workflow',
   description:
-    'Execute a multi-agent workflow script. The script uses agent(), parallel(), pipeline(), phase(), log(), args, budget primitives. ' +
-    'Pass resumeFromRunId to resume a prior run — cached agent() calls are replayed from the journal, ' +
-    'and only new/changed calls execute live.',
+    'Execute a workflow script that orchestrates multiple subagents deterministically. ' +
+    'Workflows run in the background — this tool returns immediately with a task ID, ' +
+    'and a <task-notification> arrives when the workflow completes. Use /workflows to watch live progress.\n\n' +
+    'A workflow structures work across many agents — to be comprehensive (decompose and cover in parallel), ' +
+    'to be confident (independent perspectives and adversarial checks before committing), ' +
+    'or to take on scale one context cannot hold (migrations, audits, broad sweeps). ' +
+    'The script is where you encode that structure: what fans out, what verifies, what synthesizes.\n\n' +
+    'ONLY call this tool when the task benefits from multi-agent orchestration. ' +
+    'For a simple single-agent lookup or edit, use the Agent tool or direct tools instead.\n\n' +
+    '## Primitives\n\n' +
+    '- agent(prompt: string, opts?: {label?, phase?, schema?, model?, effort?, isolation?}): Promise<any> — spawn a subagent. ' +
+    'Without schema, returns final text as string. With schema (JSON Schema), returns validated object — retries on mismatch.\n' +
+    '- parallel(thunks: Array<() => Promise<any>>): Promise<any[]> — BARRIER: runs all thunks concurrently, waits for all. ' +
+    'Failed thunks resolve to null. Use filter(Boolean) before consuming results.\n' +
+    '- pipeline(items: T[], ...stages): Promise<any[]> — NO barrier: each item flows through all stages independently. ' +
+    'Item A can be in stage 3 while item B is still in stage 1. DEFAULT choice for multi-stage work.\n' +
+    '- verify(finding, opts): Promise<VerifyResult> — adversarial/perspective/consensus quality gate. ' +
+    'Spawns skeptics or lens-based judges, applies threshold, returns {survives, votes, score}.\n' +
+    '- judge(attempts, opts): Promise<JudgeResult> — judge panel: N attempts scored by M judges across K criteria. ' +
+    'Returns winner with optional synthesis grafting runner-up ideas.\n' +
+    '- loopUntilConvergence(opts): Promise<LoopUntilConvergenceResult> — convergent discovery loop. ' +
+    'Fans out finders repeatedly, deduplicates against seen-set (NOT confirmed-set), ' +
+    'stops after N consecutive dry rounds or maxRounds. Optionally verifies each finding.\n' +
+    '- phase(title: string): void — start a new progress group\n' +
+    '- log(message: string): void — emit progress message\n' +
+    '- args: any — verbatim args passed to Workflow tool\n' +
+    '- budget: {total, spent(), remaining()} — token budget tracking\n\n' +
+    '## Topology Selection Guide\n\n' +
+    'DEFAULT TO pipeline(). Only reach for a barrier (parallel between stages) when you genuinely ' +
+    'need ALL prior-stage results together.\n\n' +
+    'A barrier is correct ONLY when stage N needs cross-item context from all of stage N-1: ' +
+    'dedup/merge across the full result set, early-exit if total count is zero, cross-finding comparison.\n\n' +
+    'A barrier is NOT justified by: flatten/map/filter (do it inside a pipeline stage), ' +
+    'conceptually separate stages, cleaner code — barrier latency is real and measurable.\n\n' +
+    '- Diamond (fan-out → reduce → synthesize): market scans, audits, research\n' +
+    '- Pipeline (no barrier): each item flows independently — DEFAULT\n' +
+    '- Loop-until-convergence: unknown-size discovery (bugs, vulnerabilities, edge cases)\n' +
+    '- Judge panel: multiple competing approaches, pick best + graft runner-ups\n' +
+    '- Verifier-on-edge: quality gates before results reach downstream\n\n' +
+    '## Critical Rules\n\n' +
+    '- EDGE LOGIC IS FREE: flatten, dedupe, filter in plain JavaScript — NOT agent calls. ' +
+    'results.flatMap(...) and a Set are deterministic, instant, zero tokens.\n' +
+    '- seen-set dedup for loops, NOT confirmed-set — rejected findings would otherwise revive every round.\n' +
+    '- Each node should have bounded input, validated output (schema), and one clear purpose.\n' +
+    '- Model tiering: use cheaper models for repetitive extraction/classification nodes, ' +
+    'expensive models for synthesis/judgment nodes.\n\n' +
+    '## Script Format\n\n' +
+    'Every script MUST begin with: export const meta = { name, description, phases: [{title, detail}] }\n' +
+    'The meta object must be a PURE LITERAL — no variables, function calls, or template interpolation.\n' +
+    'Use the SAME phase titles in meta.phases as in phase() calls.',
   category: 'agent',
   permission: 'ask',
   parameters: {
@@ -60,6 +107,23 @@ export const workflowTool: ToolDefinition = {
         resumeFromRunId,
       )
 
+      // Persist last-run state for /workflow save
+      try {
+        const { existsSync, mkdirSync, writeFileSync } = await import('node:fs')
+        const { join } = await import('node:path')
+        const workflowsDir = join(process.cwd(), '.claude', 'workflows')
+        if (!existsSync(workflowsDir)) {
+          mkdirSync(workflowsDir, { recursive: true })
+        }
+        writeFileSync(
+          join(workflowsDir, '.last-run.json'),
+          JSON.stringify({ runId, script, timestamp: new Date().toISOString() }),
+          'utf-8',
+        )
+      } catch {
+        // best-effort — don't fail the workflow if state persistence fails
+      }
+
       let content = `Workflow ${runId} completed.\n\n`
       if (resumeFromRunId) {
         content += `Cache: ${cacheHits} hits · ${cacheMisses} live\n\n`

package/src/ui/commands.ts

@@ -2388,6 +2388,111 @@ const workflowsCmd: CommandHandler = async () => {
   return { content: lines.join('\n') }
 }
 
+// ═══════════════════════════════════════════════════════════════
+// /workflow <task> — auto-generate + execute
+// ═══════════════════════════════════════════════════════════════
+
+const workflowSaveCmd = async (name: string): Promise<CommandResult> => {
+  const { existsSync, mkdirSync, writeFileSync, readFileSync } = await import('node:fs')
+  const { join } = await import('node:path')
+
+  const targetDir = join(process.cwd(), '.claude', 'workflows')
+  if (!existsSync(targetDir)) {
+    mkdirSync(targetDir, { recursive: true })
+  }
+
+  // Read the last-run state persisted by the Workflow tool
+  const stateFile = join(targetDir, '.last-run.json')
+  if (!existsSync(stateFile)) {
+    return { content: 'No recent workflow run found. Run a workflow first with /workflow <task>.' }
+  }
+
+  try {
+    const state = JSON.parse(readFileSync(stateFile, 'utf-8'))
+    const script = state.script as string
+    if (!script) {
+      return { content: 'No script found in last run state.' }
+    }
+
+    const safeName = name.replace(/[^a-zA-Z0-9_-]/g, '-')
+    const scriptPath = join(targetDir, `${safeName}.js`)
+    writeFileSync(scriptPath, script, 'utf-8')
+
+    return {
+      content: `Workflow saved to ${scriptPath}\nUse /workflow run ${safeName} to run it again.`,
+    }
+  } catch (err) {
+    return { content: `Failed to save workflow: ${String(err)}` }
+  }
+}
+
+const workflowRunCmd = async (name: string): Promise<CommandResult> => {
+  const { existsSync } = await import('node:fs')
+  const { join } = await import('node:path')
+
+  const safeName = name.replace(/[^a-zA-Z0-9_-]/g, '-')
+
+  const locations = [
+    join(process.cwd(), '.claude', 'workflows'),
+    join(process.env.HOME || '~', '.claude', 'workflows'),
+  ]
+
+  for (const loc of locations) {
+    const scriptPath = join(loc, `${safeName}.js`)
+    if (existsSync(scriptPath)) {
+      return {
+        content: '',
+        forwardToAI:
+          `Read the workflow script at ${scriptPath}, then call the Workflow tool with ` +
+          `the file contents as the "script" parameter to execute it. Report the results.`,
+      }
+    }
+  }
+
+  return {
+    content: `Workflow "${safeName}" not found in .claude/workflows/ or ~/.claude/workflows/`,
+  }
+}
+
+const workflowAutoCmd: CommandHandler = async (_ctx, args) => {
+  const task = args.join(' ').trim()
+
+  if (!task) {
+    return {
+      content:
+        'Usage: /workflow <task description>\n\n' +
+        'Describes the task, and the AI will generate a workflow script to execute it.\n' +
+        'Examples:\n' +
+        '  /workflow audit all routes for missing auth\n' +
+        '  /workflow research the impact of React 19 on our codebase\n' +
+        '  /workflow find all hardcoded credentials in the codebase\n\n' +
+        'Sub-commands:\n' +
+        '  /workflow save <name>  — save last successful workflow script\n' +
+        '  /workflow run <name>    — run a saved workflow by name\n' +
+        '  /workflows              — list all saved workflow scripts',
+    }
+  }
+
+  // Sub-commands
+  const firstArg = args[0] || ''
+  if (firstArg === 'save' && args[1]) {
+    return workflowSaveCmd(args.slice(1).join(' '))
+  }
+  if (firstArg === 'run' && args[1]) {
+    return workflowRunCmd(args.slice(1).join(' '))
+  }
+
+  // Default: forward to AI to generate + execute workflow
+  return {
+    content: '',
+    forwardToAI:
+      `Write and execute a workflow script for this task: ${task}\n\n` +
+      `Use the Workflow tool to execute the generated script. ` +
+      `After the workflow completes, summarize the results and offer to save the script ` +
+      `with /workflow save <name> if it is reusable.`,
+  }
+}
+
 // ═══════════════════════════════════════════════════════════════
 // Permissions
 // ═══════════════════════════════════════════════════════════════
@@ -4318,6 +4423,7 @@ registry.set('/tasks', tasksCmd)
 registry.set('/diff', diffCmd)
 registry.set('/loop', loopCmd)
 registry.set('/no-plan', noPlanCmd)
+registry.set('/workflow', workflowAutoCmd)
 registry.set('/workflows', workflowsCmd)
 registry.set('/review', reviewCmd)
 registry.set('/pr-comments', prCommentsCmd)

package/src/workflow/primitives/loop.ts

@@ -0,0 +1,103 @@
+import { parallel } from './parallel'
+
+/**
+ * loopUntilConvergence() — workflow primitive for iterative discovery with
+ * deduplication, adversarial verification, and convergence detection.
+ *
+ * Orchestrates multiple "finders" over successive rounds until no new items
+ * are discovered for `dryRounds` consecutive rounds (convergence), or
+ * `maxRounds` is reached (cutoff).
+ *
+ * Each item is keyed by `keyFn` for deduplication across rounds. If a
+ * `verify` function is provided, only items that survive verification
+ * enter the confirmed set — but all seen items (even those that fail
+ * verification) are tracked in the seen-set to prevent re-discovery.
+ */
+
+export interface VerifyVote {
+  real: boolean
+  reason: string
+}
+
+export interface VerifyResult<T = unknown> {
+  finding: T
+  survives: boolean
+  votes: VerifyVote[]
+  score: number
+}
+
+export interface LoopUntilConvergenceResult<T> {
+  confirmed: T[]
+  totalSeen: number
+  rounds: number
+  converged: boolean
+}
+
+export interface LoopUntilConvergenceOpts<T> {
+  finders: Array<() => Promise<{ items: T[] } | null>>
+  keyFn: (item: T) => string
+  verify?: (item: T) => Promise<VerifyResult<T>>
+  dryRounds?: number
+  maxRounds?: number
+}
+
+export async function loopUntilConvergence<T>(
+  opts: LoopUntilConvergenceOpts<T>,
+): Promise<LoopUntilConvergenceResult<T>> {
+  const dryRounds = opts.dryRounds ?? 2
+  const maxRounds = opts.maxRounds ?? 20
+
+  const seen = new Set<string>()
+  const confirmed: T[] = []
+  let dry = 0
+  let rounds = 0
+
+  while (dry < dryRounds && rounds < maxRounds) {
+    rounds++
+
+    // FAN OUT: all finders run in parallel
+    const raw = await parallel(opts.finders.map((f) => () => f()))
+
+    // EDGE LOGIC: flatMap + dedup (pure JS, zero tokens)
+    const items: T[] = []
+    for (const result of raw) {
+      if (result && result.items) {
+        items.push(...result.items)
+      }
+    }
+
+    // Dedup against SEEN set, not confirmed
+    const fresh = items.filter((item) => {
+      const key = opts.keyFn(item)
+      if (seen.has(key)) return false
+      seen.add(key)
+      return true
+    })
+
+    if (fresh.length === 0) {
+      dry++ // no new unique items → trending toward convergence
+      continue
+    }
+
+    dry = 0 // new items found → reset dry counter
+
+    // VERIFY: optional quality gate
+    if (opts.verify) {
+      const judged = await parallel(fresh.map((item) => () => opts.verify!(item)))
+      for (const j of judged) {
+        if (j && j.survives) {
+          confirmed.push(j.finding as T)
+        }
+      }
+    } else {
+      confirmed.push(...fresh)
+    }
+  }
+
+  return {
+    confirmed,
+    totalSeen: seen.size,
+    rounds,
+    converged: dry >= dryRounds,
+  }
+}

package/src/workflow/primitives/verify.ts

@@ -0,0 +1,275 @@
+/**
+ * verify() and judge() — workflow primitives for adversarial verification,
+ * multi-perspective review, and multi-judge evaluation.
+ *
+ * verify() supports 3 modes:
+ *   - adversarial: N skeptics try to refute the finding (majority wins)
+ *   - perspective:  N lenses each evaluate from a specific angle (at least 1 confirms)
+ *   - consensus:    N voters must unanimously agree
+ *
+ * judge() evaluates N attempts by M judges, computes average scores,
+ * picks the winner, and optionally synthesizes a final result.
+ */
+
+import { workflowAgent } from './agent'
+import { parallel } from './parallel'
+import type { WorkflowAgentOpts } from './agent'
+
+// Agent function signature matching the sandbox-injected pattern:
+// (prompt, opts?) → result. In production, the workflow runtime binds
+// ProviderRegistry + ToolRegistry into a function of this shape and
+// injects it via _mockAgent.
+type AgentFn = (prompt: string, opts?: WorkflowAgentOpts) => Promise<unknown>
+
+// ── Types ──
+
+export interface VerifyResult {
+  finding: unknown
+  survives: boolean
+  votes: Array<{ real: boolean; reason: string; lens?: string }>
+  score: number
+}
+
+export type VerifyMode = 'adversarial' | 'perspective' | 'consensus'
+
+export interface VerifyOpts {
+  mode: VerifyMode
+  skeptics?: number // adversarial: default 3
+  lenses?: string[] // perspective: e.g. ['correctness', 'security']
+  voters?: number // consensus: default 3
+  threshold?: number
+  schema: Record<string, unknown>
+  /** Test-only: inject a mock agent function. When not provided, falls back to workflowAgent. */
+  _mockAgent?: (prompt: string, opts?: WorkflowAgentOpts) => Promise<unknown>
+}
+
+interface VerdictVote {
+  real: boolean
+  reason: string
+  lens?: string
+}
+
+export interface JudgeResult {
+  winner: unknown
+  winnerIndex: number
+  scores: Array<{
+    attemptIndex: number
+    judgeIndex: number
+    criteria: Record<string, number>
+    total: number
+    notes: string
+  }>
+  synthesis?: string
+}
+
+export interface JudgeOpts {
+  criteria: string[]
+  judges?: number // default: 3
+  synthesize?: boolean // default: true
+  schema: Record<string, unknown>
+  /** Test-only: inject a mock agent function. */
+  _mockAgent?: (prompt: string, opts?: WorkflowAgentOpts) => Promise<unknown>
+}
+
+// ── Helpers ──
+
+function defaultThreshold(mode: VerifyMode, total: number): number {
+  if (mode === 'consensus') return total // all must agree
+  if (mode === 'perspective') return 1 // at least one lens confirms
+  return Math.ceil(total / 2) // adversarial: majority
+}
+
+// ── verify() ──
+
+export async function verify(finding: unknown, opts: VerifyOpts): Promise<VerifyResult> {
+  // Prefer the test hook (_mockAgent), fall back to workflowAgent.
+  // In production sandbox usage, _mockAgent is set to the pre-bound agent
+  // function injected by the workflow runtime.
+  const agentFn: AgentFn = opts._mockAgent ?? (workflowAgent as unknown as AgentFn)
+  const mode = opts.mode
+
+  const findingStr = JSON.stringify(finding, null, 2)
+  const schemaDesc = JSON.stringify(opts.schema)
+
+  let prompts: Array<{ prompt: string; lens?: string }>
+
+  switch (mode) {
+    case 'adversarial': {
+      const count = opts.skeptics ?? 3
+      prompts = Array.from({ length: count }, (_, i) => ({
+        prompt:
+          `You are a skeptical reviewer (skeptic #${i + 1}). Try to REFUTE this finding. Default to real=false if uncertain.\n\n` +
+          `Finding:\n${findingStr}\n\nReturn JSON matching this schema:\n${schemaDesc}`,
+      }))
+      break
+    }
+    case 'perspective': {
+      const lenses = opts.lenses ?? ['correctness']
+      prompts = lenses.map((lens) => ({
+        prompt:
+          `Judge this finding through the "${lens}" lens. Is it valid from this perspective?\n\n` +
+          `Finding:\n${findingStr}\n\nReturn JSON matching this schema:\n${schemaDesc}`,
+        lens,
+      }))
+      break
+    }
+    case 'consensus': {
+      const count = opts.voters ?? 3
+      prompts = Array.from({ length: count }, () => ({
+        prompt:
+          `Is this finding correct? Be honest and critical. Vote real=true only if you are fully convinced.\n\n` +
+          `Finding:\n${findingStr}\n\nReturn JSON matching this schema:\n${schemaDesc}`,
+      }))
+      break
+    }
+  }
+
+  // Fan out all agent calls concurrently
+  const rawVotes = await parallel(
+    prompts.map(
+      (p) => () => agentFn(p.prompt, { schema: opts.schema as WorkflowAgentOpts['schema'] }),
+    ),
+  )
+
+  // Filter out failed agents (null) and build vote objects
+  const votes: VerdictVote[] = []
+  for (let i = 0; i < rawVotes.length; i++) {
+    const v = rawVotes[i]
+    if (v && typeof v === 'object') {
+      const vote = v as Record<string, unknown>
+      votes.push({
+        real: Boolean(vote.real),
+        reason: String(vote.reason ?? ''),
+        lens: prompts[i]?.lens,
+      })
+    }
+  }
+
+  const threshold = opts.threshold ?? defaultThreshold(mode, votes.length)
+  const realCount = votes.filter((v) => v.real).length
+  const survives = realCount >= threshold
+
+  return {
+    finding,
+    survives,
+    votes,
+    score: votes.length > 0 ? realCount / votes.length : 0,
+  }
+}
+
+// ── judge() ──
+
+export async function judge(attempts: unknown[], opts: JudgeOpts): Promise<JudgeResult> {
+  // Prefer the test hook, fall back to workflowAgent.
+  const agentFn: AgentFn = opts._mockAgent ?? (workflowAgent as unknown as AgentFn)
+  const judgeCount = opts.judges ?? 3
+  const schemaDesc = JSON.stringify(opts.schema)
+
+  // Phase 1: each judge scores each attempt
+  interface ScoreEntry {
+    attemptIndex: number
+    judgeIndex: number
+    criteria: Record<string, number>
+    total: number
+    notes: string
+  }
+
+  // Build the cross-product of judges × attempts
+  const scorePrompts: Array<{
+    attempt: unknown
+    attemptIndex: number
+    judgeIndex: number
+  }> = []
+  for (let ji = 0; ji < judgeCount; ji++) {
+    for (let ai = 0; ai < attempts.length; ai++) {
+      scorePrompts.push({
+        attempt: attempts[ai],
+        attemptIndex: ai,
+        judgeIndex: ji,
+      })
+    }
+  }
+
+  // Fan out all scoring calls concurrently
+  const rawScores = await parallel(
+    scorePrompts.map(
+      (sp) => () =>
+        agentFn(
+          `You are judge #${sp.judgeIndex + 1}. Score this attempt against the criteria: ${opts.criteria.join(', ')}.\n\n` +
+            `Attempt:\n${JSON.stringify(sp.attempt, null, 2)}\n\n` +
+            `Return JSON matching this schema:\n${schemaDesc}`,
+          { schema: opts.schema as WorkflowAgentOpts['schema'] },
+        ),
+    ),
+  )
+
+  // Parse and validate each score result
+  const scores: ScoreEntry[] = []
+  for (let i = 0; i < rawScores.length; i++) {
+    const raw = rawScores[i]
+    const sp = scorePrompts[i]!
+    if (raw && typeof raw === 'object') {
+      const obj = raw as Record<string, unknown>
+      const criteriaObj = (obj.scores as Record<string, number>) ?? {}
+      const total = Object.values(criteriaObj).reduce(
+        (sum, v) => sum + (typeof v === 'number' ? v : 0),
+        0,
+      )
+      scores.push({
+        attemptIndex: sp.attemptIndex,
+        judgeIndex: sp.judgeIndex,
+        criteria: criteriaObj,
+        total,
+        notes: String(obj.notes ?? ''),
+      })
+    }
+  }
+
+  // Compute winner: highest average total across judges
+  const attemptTotals = new Map<number, number>()
+  const attemptCounts = new Map<number, number>()
+  for (const s of scores) {
+    attemptTotals.set(s.attemptIndex, (attemptTotals.get(s.attemptIndex) ?? 0) + s.total)
+    attemptCounts.set(s.attemptIndex, (attemptCounts.get(s.attemptIndex) ?? 0) + 1)
+  }
+
+  let winnerIndex = 0
+  let bestAvg = -Infinity
+  for (const [idx, total] of attemptTotals) {
+    const count = attemptCounts.get(idx) ?? 1
+    const avg = total / count
+    if (avg > bestAvg) {
+      bestAvg = avg
+      winnerIndex = idx
+    }
+  }
+
+  // Phase 2: optional synthesis
+  let synthesis: string | undefined
+  if (opts.synthesize !== false) {
+    const winner = attempts[winnerIndex]
+    const runnerUps = attempts
+      .map((a, i) => ({ attempt: a, index: i }))
+      .filter((e) => e.index !== winnerIndex)
+
+    const synthPrompt =
+      `Synthesize the final result from the WINNING approach, grafting the best ideas from runner-ups.\n\n` +
+      `WINNER:\n${JSON.stringify(winner, null, 2)}\n\n` +
+      `RUNNER-UPS:\n${JSON.stringify(runnerUps, null, 2)}\n\n` +
+      `Provide a comprehensive synthesis combining the winner's structure with the best elements from other approaches.`
+
+    const synthResult = await agentFn(synthPrompt)
+    if (typeof synthResult === 'string') {
+      synthesis = synthResult
+    } else if (synthResult && typeof synthResult === 'object' && 'synthesis' in synthResult) {
+      synthesis = String((synthResult as Record<string, unknown>).synthesis)
+    }
+  }
+
+  return {
+    winner: attempts[winnerIndex],
+    winnerIndex,
+    scores,
+    synthesis,
+  }
+}

package/src/workflow/runtime.ts

@@ -5,6 +5,8 @@ import { workflowAgent } from './primitives/agent'
 import { parallel } from './primitives/parallel'
 import { pipeline } from './primitives/pipeline'
 import { phase as phasePrimitive } from './primitives/phase'
+import { verify, judge } from './primitives/verify'
+import { loopUntilConvergence } from './primitives/loop'
 import type { ProviderRegistry } from '../providers/registry'
 import type { QueryEngine } from '../core/engine'
 
@@ -147,6 +149,9 @@ export async function runWorkflow(
     'agent',
     'parallel',
     'pipeline',
+    'verify',
+    'judge',
+    'loopUntilConvergence',
     'phase',
     'log',
     'args',
@@ -154,7 +159,18 @@ export async function runWorkflow(
     wrappedScript,
   )
 
-  const result = await scriptFn(agent, parallel, pipeline, wrappedPhase, log, args, budget)
+  const result = await scriptFn(
+    agent,
+    parallel,
+    pipeline,
+    verify,
+    judge,
+    loopUntilConvergence,
+    wrappedPhase,
+    log,
+    args,
+    budget,
+  )
 
   // Count journal entries from state
   const priorEntries = loadJournal(runId)