@diottodev/runic 1.0.0 → 1.1.0

package/engineering/workflow-builder/skills/workflow-builder/assets/templates/pipeline.js

@@ -0,0 +1,46 @@
+export const meta = {
+  name: 'pipeline-review',
+  description: 'Stream items through ordered stages',
+  phases: [
+    { title: 'Triage' },
+    { title: 'Verify' }
+  ]
+}
+
+
+const FINDINGS_SCHEMA = {
+  type: 'object',
+  properties: {
+    findings: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          title: { type: 'string' },
+          severity: { type: 'string', enum: ['low', 'medium', 'high'] }
+        },
+        required: ['title']
+      }
+    }
+  },
+  required: ['findings']
+}
+
+
+// Pipeline: each item flows through stages independently (no barrier).
+const ITEMS = args?.items ?? ['item one', 'item two', 'item three']
+
+const results = await pipeline(
+  ITEMS,
+  // Stage 1 — triage / extract (cheap, high volume).
+  (item, _orig, i) =>
+    agent(`Triage:\n${item}`, { label: `triage:${i + 1}`, phase: 'Triage', model: 'haiku', schema: FINDINGS_SCHEMA }),
+  // Stage 2 — verify / refine each finding (fewer items, more judgement).
+  (prev) =>
+    parallel((prev?.findings ?? []).map(f => () =>
+      agent(`Verify and refine: ${f.title}`, { phase: 'Verify', model: 'sonnet' })))
+)
+
+log(`Done: processed ${results.filter(Boolean).length} items through the pipeline.`)
+return results.filter(Boolean)
+

package/engineering/workflow-builder/skills/workflow-builder/expected_outputs/intake_pr_review.json

@@ -0,0 +1,37 @@
+{
+  "task": "review my open PRs for bugs",
+  "recommended_topology": "fan-out",
+  "runner_up_topology": "pipeline",
+  "resolved_signals": {
+    "verb_chain": false,
+    "panel": false,
+    "costly": false,
+    "loop_like": false,
+    "merge_like": false,
+    "list_like": true,
+    "units_effective": "known",
+    "stages_effective": "single",
+    "needs_all_effective": "no"
+  },
+  "model_plan": [
+    {
+      "stage": "fan-out stage",
+      "model": "haiku",
+      "why": "independent, mechanical per-item work is cheap on Haiku"
+    },
+    {
+      "stage": "final synthesis",
+      "model": "opus",
+      "why": "combining many results into one report needs strong reasoning"
+    }
+  ],
+  "structured_output": "yes",
+  "budget_guard": "optional; set budget.total if the user gave a token target",
+  "rationale": {
+    "topology": "independent units, one pass each, combined at the end -> parallel fan-out then a final synthesis agent",
+    "runner_up": "pipeline",
+    "structured_output": "default on \u2014 a small JSON schema makes downstream stages reliable at near-zero cost",
+    "budget": "fixed topology with a known/bounded item count \u2014 no runaway risk"
+  },
+  "add_verification": false
+}

package/engineering/workflow-builder/skills/workflow-builder/expected_outputs/scaffold_pipeline.js

@@ -0,0 +1,46 @@
+export const meta = {
+  name: 'pr-triage',
+  description: 'Triage open PRs for bugs',
+  phases: [
+    { title: 'Triage' },
+    { title: 'Verify' }
+  ]
+}
+
+
+const FINDINGS_SCHEMA = {
+  type: 'object',
+  properties: {
+    findings: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          title: { type: 'string' },
+          severity: { type: 'string', enum: ['low', 'medium', 'high'] }
+        },
+        required: ['title']
+      }
+    }
+  },
+  required: ['findings']
+}
+
+
+// Pipeline: each item flows through stages independently (no barrier).
+const ITEMS = args?.items ?? ['item one', 'item two', 'item three']
+
+const results = await pipeline(
+  ITEMS,
+  // Stage 1 — triage / extract (cheap, high volume).
+  (item, _orig, i) =>
+    agent(`Triage:\n${item}`, { label: `triage:${i + 1}`, phase: 'Triage', model: 'haiku', schema: FINDINGS_SCHEMA }),
+  // Stage 2 — verify / refine each finding (fewer items, more judgement).
+  (prev) =>
+    parallel((prev?.findings ?? []).map(f => () =>
+      agent(`Verify and refine: ${f.title}`, { phase: 'Verify', model: 'sonnet' })))
+)
+
+log(`Done: processed ${results.filter(Boolean).length} items through the pipeline.`)
+return results.filter(Boolean)
+

package/engineering/workflow-builder/skills/workflow-builder/expected_outputs/validate_sample.txt

@@ -0,0 +1,6 @@
+[FAIL] <sample>
+  FAIL (line 1): `meta` contains a template string — it must be a pure literal (use plain quoted strings).
+  FAIL (line 6): Date.now() is banned (breaks resume) — pass timestamps via `args`.
+  WARN (file): No `.filter(Boolean)` found — skipped/failed agents insert `null`; filter results before using them.
+  WARN (line 7): `while (true)` loop — add a counter or budget.remaining() guard or it hits the 1000-agent cap.
+  WARN (line 8): parallel([ agent(...) , ... ]) passes bare promises — use thunks: `[() => agent(...), ...]`.

package/engineering/workflow-builder/skills/workflow-builder/references/api_reference.md

@@ -0,0 +1,115 @@
+# Workflow API Reference
+
+Complete surface for Claude Code's Workflow tool: every global, option, cap, and constant a workflow `.js` file can rely on. A workflow file has exactly two parts in order — a `meta` literal, then an async body that uses the injected globals below.
+
+## 1. `meta` declaration
+
+`meta` must be the **first statement** and a **pure object literal** — no variables, spreads, template strings, or function calls inside it. Reserved keys (`__proto__`, `constructor`, `prototype`) are rejected by the parser.
+
+```js
+export const meta = {
+  name: 'workflow-name',            // required, non-empty string
+  description: 'One-line summary',  // required
+  whenToUse: 'When to run this',    // optional
+  phases: [                         // optional, one entry per phase() call
+    { title: 'Phase Name', detail: 'Description', model: 'haiku' }
+  ]
+}
+```
+
+## 2. Injected globals
+
+| Global | Signature | Returns |
+|--------|-----------|---------|
+| `agent()` | `agent(prompt, opts?) → Promise<string\|object>` | Text, or a validated object when `schema` is set |
+| `pipeline()` | `pipeline(items, ...stages) → Promise<any[]>` | Streamed per-item results (no barrier between stages) |
+| `parallel()` | `parallel(thunks) → Promise<any[]>` | Concurrent results (barrier — waits for all) |
+| `phase()` | `phase(title) → void` | Groups subsequent agents under a heading |
+| `log()` | `log(message) → void` | Narrator output to the workflow log |
+| `console` | `.log()`, `.error()`, … | Routed into the workflow log |
+| `workflow()` | `workflow(nameOrRef, args?) → Promise<any>` | Result of a nested workflow (one level deep max) |
+| `args` | any | The input passed to the workflow, unchanged |
+| `budget` | `{ total, spent(), remaining() }` | Token tracking |
+
+## 3. `agent()` options
+
+```js
+agent(prompt, {
+  label: 'string',           // display name (~60 char default)
+  phase: 'phase-name',       // progress-group assignment
+  schema: { type: 'object' },// JSON Schema — validates + structures the return
+  model: 'haiku',            // 'haiku' | 'sonnet' | 'opus' | 'inherit' | full-model-id
+  isolation: 'worktree',     // run in a fresh git worktree (~200-500 ms + disk)
+  agentType: 'agent-type',   // custom sub-agent type
+  stallMs: 180000            // per-agent stall timeout override (ms)
+})
+```
+
+**Model resolution:** `haiku`/`sonnet`/`opus` resolve to the current default of that family; `inherit` (the default) uses the session main-loop model; a full model ID passes through unchanged. Pick lighter models (Haiku) for classification/extraction and heavier ones (Opus) for synthesis or hard reasoning.
+
+**Resume cache key** includes `schema`, `model`, `isolation`, and `agentType` — changing any of these re-runs the agent on resume. `label` and `phase` do **not** invalidate the cache.
+
+## 4. `pipeline()` vs `parallel()`
+
+**`pipeline(items, stage1, stage2, …)`** — each item flows through every stage independently; there is no barrier between stages, so stage 2 starts for an item the moment stage 1 finishes for *that* item. Stage callbacks receive `(prevResult, originalItem, index)`. Wall-clock time ≈ the slowest single item's full chain, not the sum of slowest-per-stage. **Default choice for multi-stage work.**
+
+**`parallel(thunks)`** — runs an array of `() => Promise` thunks concurrently and waits for all (a barrier). Use only when the next step genuinely needs the entire prior result set — dedup, merge, or a count-based exit. Requires thunks, not bare promises: `parallel([() => agent(a), () => agent(b)])`.
+
+## 5. `budget` object
+
+```js
+budget.total        // user-set target, or null if none
+budget.spent()      // output tokens spent this turn
+budget.remaining()  // max(0, total - spent()), or Infinity when total is null
+```
+
+Throws `WorkflowBudgetExceededError` once `spent()` reaches `total`. Use `budget.remaining()` as a loop guard for depth-scaling workflows.
+
+## 6. Caps & limits
+
+| Limit | Value | Behavior on breach |
+|-------|-------|--------------------|
+| Agent calls per run | 1000 | throws `WorkflowAgentCapError` |
+| Concurrent agents | `min(16, max(2, cores − 2))` | excess calls queue |
+| Script size | 524,288 bytes | rejected before parsing |
+| Per-agent stall | 180,000 ms (3 min) | aborted, retried up to 5× |
+| Sync timeout | 30,000 ms | catches infinite synchronous loops |
+
+## 7. Sandbox restrictions
+
+**Banned (non-reproducible — break resume):**
+- `Math.random()` → vary the agent prompt by index instead.
+- `Date.now()` → pass timestamps in via `args`.
+- argless `new Date()` → use `new Date(specificValue)`.
+
+**No access** to filesystem, Node APIs (`require`, `fs`, `process`), or network from the orchestrator. Any work needing those must happen *inside* an `agent()` call (the sub-agent has full tool access).
+
+## 8. Execution & resume
+
+1. The script is persisted to the session directory.
+2. A background task launches and returns a run ID (`wf_…`).
+3. A journal records each `agent()` call keyed by a hash of `(prompt, opts)`.
+4. Resume via `Workflow({ scriptPath, resumeFromRunId })` — cached calls return instantly; only changed or new calls re-run. Resume works **same-session only**; edit the saved file and re-invoke with `scriptPath`.
+
+## 9. Enabling the feature
+
+The Workflow tool is gated behind an environment variable and off by default:
+
+```bash
+export CLAUDE_CODE_WORKFLOWS=1
+```
+
+Save workflow files under `.claude/workflows/` in the project, then browse, launch, and monitor them with the `/workflows` slash command. **P** pauses/resumes a run; **X** skips a sub-agent.
+
+---
+
+## Sources
+
+1. Anthropic — Claude Code documentation, Workflow tool & `/workflows` (code.claude.com/docs).
+2. Ray Amjad — `claude-code-workflow-creator`, `references/api-reference.md` (github.com/ray-amjad/claude-code-workflow-creator).
+3. Anthropic — Claude Code changelog, v2.1.147 release notes (Workflow tool introduction).
+4. Anthropic — sub-agents & the Agent tool documentation (fresh-context isolation model).
+5. Anthropic — Claude Agent SDK: orchestration and background-task execution patterns.
+6. JSON Schema specification (json-schema.org) — the `schema` option's validation contract.
+7. Node.js / ECMAScript — async/await and `Promise.all` semantics underlying `parallel()`.
+8. Google SRE Workbook — error-budget discipline, analogous to the `budget` guard pattern.

package/engineering/workflow-builder/skills/workflow-builder/references/decision_and_intake_guide.md

@@ -0,0 +1,83 @@
+# Decision & Intake Guide
+
+The workflow-builder skill opens **every** session with intake. This file is the full framework behind that gate: the questions to ask, how to handle vague answers, and worked examples of turning a fuzzy request into a concrete proposal.
+
+## Why intake comes first
+
+A workflow's whole value is deterministic, resumable, fixed-topology orchestration. The topology is a *design decision* that must be made before any code — choosing pipeline vs. parallel, known-list vs. loop, or whether a step needs structured output changes the entire file. Asking first is cheaper than rewriting. It also catches the most common mistake: building a workflow when a single agent or a skill would do.
+
+## The opening question set
+
+Ask these at the start of a workflow-creation session. Lead with #1; the rest sharpen the shape.
+
+1. **What repeatable, multi-step task do you want to automate?** (the goal)
+2. **What is the one unit of work** a single sub-agent does once? (e.g., "review one file", "research one question")
+3. **How many units** — a known list, or discovered by looping until some condition?
+4. **Do later steps need *all* prior results at once** (dedup/merge/count), or can each item flow independently?
+5. **Does any step need structured data back** — a verdict, a list, scores?
+6. **How deep / how many tokens** should this go? (sets the budget guard)
+
+Map answers → topology:
+
+| Signal | Topology |
+|--------|----------|
+| Independent units, known list, combine at end | **fan-out → synthesize** (`parallel` + final `agent`) |
+| Ordered stages, each item advances on its own | **pipeline** |
+| A stage needs the whole prior set (dedup/merge/early-exit) | **barrier** (`parallel`, then process) |
+| Unknown count, stop on goal / budget / dryness | **loop** (guarded) |
+| Wide solution space, want best-of-N | **judge panel** |
+| A wrong result is costly | add **skeptic-vote** verification on that finding |
+
+## The vague-input playbook
+
+When the user gives a one-liner ("I want to review my PRs") or skips the topology questions, **do not interrogate them in a loop.** Infer, propose, and explain. Run:
+
+```bash
+python scripts/workflow_intake.py --task "review my open PRs for bugs" \
+  --units unknown --stages unknown --needs-all unknown --structured unknown
+```
+
+The engine classifies the task by keywords, fills unknowns with the safest default, and returns:
+- a **recommended topology** (and a runner-up if it's close),
+- **model picks** per stage (Haiku for triage/extraction, Opus for synthesis),
+- a **budget guard** suggestion,
+- a **one-line rationale for every choice** so you can present "here's what I'd build and why."
+
+Then say, in your own words: *"You were light on detail, so here's the approach I'd recommend and why — tell me what to change."* Present the topology, the phases, and the parallel-vs-pipeline call. Only after the user reacts do you scaffold.
+
+### Defaults the engine applies to unknowns (and why)
+
+| Unknown | Default | Why |
+|---------|---------|-----|
+| unit count | loop with a hard cap | safest when count is undiscovered; cap prevents the 1000-agent ceiling |
+| stages | single stage unless the task names a verb chain | most fuzzy asks are one-pass fan-outs, not pipelines |
+| needs-all-results | no (prefer pipeline) | pipeline is strictly faster and the default per the API; only add a barrier on evidence |
+| structured output | yes, lightweight schema | a small schema makes downstream stages reliable at near-zero cost |
+| budget | guard at `remaining() > 50k` | keeps runaway loops from draining the turn |
+
+## Worked examples
+
+**"Review my PRs."**
+Unit = one PR (a known list, gathered inside the first agent). Each PR is reviewed once, independently. Wrong result costly = yes (a false positive wastes review time, a miss ships a bug). → **fan-out** (one review per PR, Haiku, structured findings) → **skeptic-vote** on each high-severity finding (Sonnet) → a final synthesis. If you want a distinct *verify* pass after review, split it into a two-stage **pipeline** instead. Rationale handed to the user: fan-out because PRs are independent; skeptic-vote because acting on a false positive is costly.
+
+**"Summarize a folder of documents."**
+Unit = one document. Count = known list (the folder contents, gathered inside the first agent). Combine at end = yes. → **fan-out** (Haiku per doc, structured summary) → **synthesize** (Opus, one report). No loop, no barrier mid-stream. Rationale: documents are independent, so parallel; one final synthesis because the user wants a single summary.
+
+**"Find security issues until you run out of budget."**
+Unit = one issue. Count = unknown, budget-bounded. → **loop-until-budget** guarded by `budget.remaining() > 50_000`, structured issue schema, dedup by id. Rationale: depth scales to the token target; the guard is mandatory or it hits the agent cap.
+
+## When to walk away from a workflow
+
+If intake reveals a single agent and one task, say so and recommend the plain Agent tool. If it's a procedure where Claude should pick steps dynamically rather than a fixed topology, recommend a Skill instead. Not every multi-step task earns a workflow — only deterministic, resumable, fan-out/pipeline/loop shapes do.
+
+---
+
+## Sources
+
+1. Ray Amjad — `claude-code-workflow-creator`, `SKILL.md` (the five topology questions, tool-selection table).
+2. Anthropic — Claude Code documentation on when to use workflows vs. agents vs. skills.
+3. Matt Pocock — `grill-me` skill (forcing-question, one-recommendation-at-a-time intake discipline).
+4. Anthropic — sub-agent context-isolation rationale (why topology is a pre-code decision).
+5. Google SRE Workbook — budget-guard discipline for bounded loops.
+6. "LLM-as-a-judge" + ensemble verification literature (judge-panel / skeptic-vote selection).
+7. YC / product-discovery practice — infer-and-propose over interrogate-in-a-loop for vague requests.

package/engineering/workflow-builder/skills/workflow-builder/references/orchestration_patterns.md

@@ -0,0 +1,160 @@
+# Orchestration Patterns
+
+Copy-paste shapes for the common multi-agent topologies. Pick by answering the topology questions in [decision_and_intake_guide.md](decision_and_intake_guide.md), then adapt one of these.
+
+## 1. Fan-out then synthesize
+
+**When:** a known list of independent items, one pass each, and you need one combined answer at the end.
+
+```js
+const findings = await parallel(
+  questions.map((q, i) => () =>
+    agent(`Research and report verified facts:\n\n${q}`,
+          { label: `q${i + 1}`, schema: RESEARCH_SCHEMA }))
+)
+const report = await agent(
+  `Synthesize these findings into one report:\n${JSON.stringify(findings.filter(Boolean))}`,
+  { model: 'opus' }
+)
+```
+
+## 2. Pipeline: stage then stage (no barrier)
+
+**When:** items progress through ordered stages and each item should advance the instant it's ready, not wait for siblings.
+
+```js
+const results = await pipeline(
+  DIMENSIONS,
+  d => agent(d.prompt, { label: `review:${d.key}`, phase: 'Review', schema: FINDINGS_SCHEMA }),
+  review => parallel((review?.findings ?? []).map(f => () =>
+    agent(`Adversarially verify: ${f.title}`, { schema: VERDICT_SCHEMA })))
+)
+```
+
+## 3. Barrier when you must dedup / merge first
+
+**When:** the next stage needs the *entire* previous result set in hand — to dedup, merge, or early-exit on a count.
+
+```js
+const all = await parallel(DIMENSIONS.map(d => () => agent(d.prompt, { schema: FINDINGS_SCHEMA })))
+const deduped = dedupeByFileAndLine(all.filter(Boolean).flatMap(r => r.findings))
+const summary = await agent(`Summarize ${deduped.length} unique findings:\n${JSON.stringify(deduped)}`)
+```
+
+## 4. Loop until target count
+
+**When:** discovery with a fixed goal ("find 10 bugs"). Always bound it.
+
+```js
+const bugs = []
+while (bugs.length < 10 && bugs.length < 100 /* hard cap guard */) {
+  const r = await agent(
+    `Find bugs NOT already listed:\n${JSON.stringify(bugs)}`,
+    { schema: BUGS_SCHEMA }
+  )
+  if (!r?.bugs?.length) break
+  bugs.push(...r.bugs)
+}
+```
+
+## 5. Loop until budget runs low
+
+**When:** depth should scale to the user's token target. The `budget` guard is essential.
+
+```js
+const issues = []
+while (budget.total && budget.remaining() > 50_000) {
+  const r = await agent('Find one more issue not yet reported...', { schema: ISSUE_SCHEMA })
+  if (!r?.issues?.length) break
+  issues.push(...r.issues)
+}
+```
+
+## 6. Adversarial verification (skeptic vote)
+
+**When:** a finding will be acted on and a plausible-but-wrong one is costly. Findings survive on majority vote.
+
+```js
+const votes = await parallel(Array.from({ length: 3 }, (_, i) => () =>
+  agent(`Try hard to REFUTE this claim, return { refuted: boolean }:\n${claim}`,
+        { label: `skeptic:${i + 1}`, schema: VERDICT_SCHEMA })))
+const survives = votes.filter(v => v && !v.refuted).length >= 2
+```
+
+## 7. Judge panel
+
+**When:** a wide solution space benefits from several independent attempts, scored and synthesized.
+
+```js
+const drafts = await parallel(ANGLES.map(a => () =>
+  agent(`Produce a plan. Take a strictly ${a} approach.`)))
+const scored = await parallel(drafts.map((d, i) => () =>
+  agent(`Score this plan 1-10 with reasons:\n${d}`, { label: `judge:${i + 1}`, schema: SCORE_SCHEMA })))
+const winner = drafts[scored.indexOf(scored.reduce((a, b) => (a?.score ?? 0) >= (b?.score ?? 0) ? a : b))]
+const final = await agent(`Refine the winning plan:\n${winner}`, { model: 'opus' })
+```
+
+## 8. Loop until dry
+
+**When:** unknown-size discovery that stops after K consecutive rounds with no new findings.
+
+```js
+const found = []
+const seen = new Set()
+let dryRounds = 0
+while (dryRounds < 2 && found.length < 100) {
+  const r = await agent(`Find items not in:\n${JSON.stringify([...seen])}`, { schema: ITEMS_SCHEMA })
+  const fresh = (r?.items ?? []).filter(x => !seen.has(x.id))
+  fresh.forEach(x => seen.add(x.id))
+  found.push(...fresh)
+  dryRounds = fresh.length === 0 ? dryRounds + 1 : 0
+}
+```
+
+## 9. Nested workflow
+
+**When:** a self-contained sub-job lives inside a larger one (one level deep maximum).
+
+```js
+const research = await workflow('research-fanout', ['question one', 'question two'])
+```
+
+## Schema declarations
+
+Schemas are plain JSON Schema objects defined as top-level `const`s and passed via `{ schema }`:
+
+```js
+const FINDINGS_SCHEMA = {
+  type: 'object',
+  properties: {
+    findings: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          title: { type: 'string' },
+          severity: { type: 'string', enum: ['low', 'medium', 'high'] },
+          file: { type: 'string' }
+        },
+        required: ['title', 'severity']
+      }
+    }
+  },
+  required: ['findings']
+}
+```
+
+Between stages, stringify structured data into the next prompt (`JSON.stringify(...)`); the schema only shapes what comes *back* from a single `agent()` call.
+
+---
+
+## Sources
+
+1. Ray Amjad — `claude-code-workflow-creator`, `references/patterns.md` (fan-out, pipeline, judge-panel, loop shapes).
+2. Anthropic — Claude Code Workflow tool documentation (`pipeline`/`parallel` semantics).
+3. Anthropic — sub-agent orchestration patterns (Agent tool, fresh-context isolation).
+4. Karpathy — LLM agent loop / file-optimization patterns (loop-until-dry analogue).
+5. Google SRE Workbook — error budgets (loop-until-budget guard).
+6. "LLM-as-a-judge" evaluation literature (judge-panel + scored synthesis).
+7. Ensemble / majority-vote methods in ML (skeptic-vote verification).
+8. JSON Schema specification — structured-output contract for the `schema` option.