Smithers Workflow Engine

TypeScript framework for deterministic, resumable AI workflows using JSX. Runtime: Bun >= 1.3. State: SQLite via Drizzle ORM. Validation: Zod schemas. Version: 0.8.2.

Init CLI

uv run /path/to/skills/smithers/scripts/skill_smithers.py <target-dir>
uv run scripts/skill_smithers.py ./scripts/my-workflow --name my-workflow --no-install

Copies the full template into <target-dir>, runs bun install, and initializes git + jj (skips each if already present). Requires jj on PATH: brew install jj.

Project Config Setup

The workflow engine (<target-dir>/) is project-agnostic — never edit it per project. All domain-specific content lives in a separate config directory:

projects/<my-project>/smithers-config/
  config.ts            # ProjectConfig (name, phases, cwd, instructions, agents)
  instructions/        # MDX files injected into component prompts
    research.mdx, plan.mdx, implement.mdx, test.mdx,
    code-review.mdx, prd-review.mdx, review-fix.mdx,
    final-review.mdx, update-progress.mdx
  output/
    context/           # agents write context docs here (create empty)
    plans/             # agents write plan docs here (create empty)
  run.sh               # launcher

config.ts must satisfy the ProjectConfig interface (see <target-dir>/types/project.ts). Key fields:

• phases — ordered list of { id, name, description, metadata? } — the outer loop iterates over these
• cwd — absolute path to the repo root where agents run
• instructions — map of step name → imported MDX function (e.g. research: ResearchInstructions)
• agents.systemPromptContent — project context injected into every agent's system prompt

instructions/*.mdx are additive — they fill the {props.projectInstructions} slot in each generic component prompt. Write only what's domain-specific (spec references, file paths, rules). Phase metadata fields are available as {props.fieldName}.

run.sh sets SMITHERS_PROJECT and invokes the engine:

#!/usr/bin/env bash
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
cd "<target-dir>"
export SMITHERS_PROJECT="$SCRIPT_DIR/config.js"
bunx smithers run workflow.tsx

Run with: ./projects/<my-project>/smithers-config/run.sh

Core Execution Model

Render-schedule-execute loop:

1. Render — JSX tree → available tasks
2. Schedule — determine runnable tasks (dependencies + concurrency)
3. Execute — agent runs, output validates against Zod, persists to SQLite
4. Re-render — tree updates with new outputs, unblocking dependents
5. Repeat until done/failed

JSX Primitives

Task Props

Available Agents

Key Rules

1. Always pass output={outputs.xxx} to <Task> — enables schema validation, auto-retry, and auto-appended JSON output instructions. Pass the ZodObject from createSmithers's outputs return — string keys were removed in v0.7.1.
2. Use ctx.outputMaybe() not ctx.output() — gracefully handles missing outputs during first render
3. Use ctx.latest() for cross-iteration decisions — outputMaybe is scoped to the current Ralph iteration; use ctx.latest(table, nodeId) for skipIf, loop until, and allPhasesComplete checks
4. Use .nullable() never .optional() in Zod schemas — OpenAI structured outputs rejects .optional() fields
5. Phase-prefix nodeIds when multiple phases share a loop — ${phaseId}:step-name
6. Set continueOnFail on review Tasks — one reviewer failing shouldn't block the other
7. Use agent arrays for rate-limit resilience — set agent={[primary, fallback]} on heavy tasks so retry attempts switch to a different model automatically. The old fallbackAgent prop was removed in v0.8.0.

Workflow Philosophy

Atomic unit pipeline: run the full pipeline (implement → test → review → fix → final-review) for each logically complete unit of work. Do NOT implement everything then review once.

"Atomic" = one logical concern, not smallest diff: 20 similar operators = ONE unit. Porting 14 similar test cases = ONE unit. The outer Ralph loop iterates until all phases pass the FinalReview gate.

Resources

• references/atomic-workflow.md — logical unit pipeline, nextLogicalUnit chaining, batching heuristics
• references/patterns.md — outer Ralph, gating, data threading, pass tracking, dual-model review
• references/troubleshooting.md — dirty git, OpenAI schema errors, stale runs, SQLite debugging