smithers-orchestrator

# Smithers Orchestrator (smithers-orchestrator)

JSX workflow engine for Claude Code: **render → execute active nodes → persist to SQLite → rerender** until stable/stop. Durable by default when you store control-flow in `db.state` (SQLite), not React `useState`. `maxIterations` is mandatory for safety.

## Use when
- Multi-step repo automation (PR finalize, CI recovery, release smoke tests, refactors)
- Needs **resume** after interruption (power/network/tool failures)
- Needs **observability** (phases/steps/tools/agents logged + NDJSON streams)
- Needs constrained tool permissions per agent step

## Fast requirements (ask once, then write code)
- Goal + acceptance checks (tests pass? lint clean? diff reviewed?)
- Allowed tools per step (Read/Write/Edit/Bash/…)
- Stop limits: `maxIterations`, optional timeout + stop conditions
- Branching needs: retries, human checkpoint(s), optional phases (`skipIf`)

---

# Setup

## Claude Code plugin install (optional; for end-users running Smithers inside Claude Code)
```text
/plugin marketplace add evmts/smithers
/plugin install smithers@smithers
```

## Project install + TSX config (Bun)

```bash
bun add smithers-orchestrator
```

`bunfig.toml`

```toml
[dev]
jsx = "react"
```

`tsconfig.json`

```json
{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "smithers-orchestrator"
  }
}
```

---

# Canonical workflow template (resumable, phases+steps)

Create `workflows/smithers-example.tsx`:

```tsx
#!/usr/bin/env bun
import {
  createSmithersDB,
  createSmithersRoot,
  SmithersProvider,
  Phase,
  Step,
  Claude,
} from "smithers-orchestrator";

const db = createSmithersDB({ path: ".smithers/smithers-example" });

// Resume if an execution is incomplete; otherwise start a new one.
const existing = db.execution.findIncomplete();
const executionId =
  existing?.id ??
  db.execution.start({
    name: "Smithers Example",
    script: "workflows/smithers-example.tsx",
  });

function Workflow() {
  return (
    <Sm