smithers-orchestrator 0.2.9 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 William Cory
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -2,525 +2,219 @@
 
 [![npm version](https://img.shields.io/npm/v/smithers-orchestrator.svg)](https://www.npmjs.com/package/smithers-orchestrator)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
-[![Bun](https://img.shields.io/badge/Bun-1.0+-black.svg)](https://bun.sh/)
 
-**Let your agent write agents.**
+**Ralph the plan, not the agent.**
 
-React-style orchestration your coding agent can generate, then run safely as durable Ralph loops.
+**Status: Alpha - not ready for production use.**
 
-<!-- TODO: Add GIF demo -->
+Your orchestrating agent writes React code that spawns and controls other agents. [Let your agents write agents](https://smithers.sh/harness-integration#claude-code-plugin).
 
-![Smithers Demo](https://via.placeholder.com/800x400?text=Demo+GIF+Coming+Soon)
-
-```
-┌─────────────────────────────────────────────────────────────────────────────┐
-│  React tree  ──▶  Smithers executor  ──▶  Tools + Claude  ──▶  SQLite DB   │
-│                                                                             │
-│  "React syntax, non-UI renderer"                                            │
-└─────────────────────────────────────────────────────────────────────────────┘
-```
-
-- **Agent-native syntax** - Easy for Claude Code to generate, easy for humans to review
-- **Sophisticated loops** - Multi-phase, parallel agents, conditional branches
-- **Composable** - Build complex workflows from simple React components
-
----
-
-## Table of Contents
-
-- [Why Smithers](#why-smithers)
-- [Getting Started](#getting-started)
-- [Starter Workflows](#starter-workflows)
-- [Features](#features)
-  - [Claude Component](#claude-component)
-  - [Sophisticated Ralph Loops](#sophisticated-ralph-loops)
-  - [Structured Output with Zod](#structured-output-with-zod)
-  - [MCP Tool Integration](#mcp-tool-integration)
-  - [Smithers Subagent](#smithers-subagent)
-  - [Git/JJ VCS Integration](#gitjj-vcs-integration)
-  - [PhaseRegistry & Step](#phaseregistry--step)
-  - [Parallel Execution](#parallel-execution)
-  - [Database Persistence](#database-persistence)
-- [FAQ](#faq)
-- [Contributing](#contributing)
-
----
-
-## Why Smithers
-
-### The Problem
-
-Simple Ralph loops work great for basic iteration. But as workflows grow complex:
-- Multi-phase orchestration becomes hard to manage
-- Parallel agents need coordination
-- Plans live in prompts, not reviewable code
-- Manual orchestration doesn't scale
-
-### The Solution
-
-Smithers uses React's component model + markup-like syntax to define execution plans. This isn't UI - it renders to **execution**.
-
-**One syntax both humans and agents can work with:**
-- You can read and review it
-- Claude Code can generate it reliably
-- Git can version it
-
-**Sophisticated Ralph loops that stay reliable:**
-- Multi-phase workflows with parallel agents
-- Conditional branches, phases, steps
-- Composable components you can reuse
-- Persist state and audit history when you need it
-
----
-
-## Getting Started
-
-### Prerequisites
-
-- **[Bun](https://bun.sh/)** v1.0+ (JavaScript runtime)
-- **[Claude Code](https://www.npmjs.com/package/@anthropic-ai/claude-code)** - `bun install -g @anthropic-ai/claude-code`
-
-### Install
-
-```bash
-bun add smithers-orchestrator
-```
-
-### Let Claude Write It
-
-**You don't have to write Smithers yourself.** Describe what you want:
-
-```
-User: "Create a workflow that monitors my CI, fixes failures automatically,
-       and escalates after 3 failed attempts"
-
-Claude: *generates ci-recovery.tsx*
-```
-
-### Run It
-
-```bash
-bun my-workflow.tsx
-```
-
-### Inspect History
-
-```bash
-smithers db executions                      # View execution history
-smithers db state --execution-id abc123     # Inspect specific run
-```
-
----
-
-## Starter Workflows
-
-### 1. Night Shift: Run Until Tests Pass
-
-Goal: Keep iterating until all tests pass, with incremental commits.
+Used to orchestrate coding agents that run for days, ship PRs autonomously, and self-heal when they fail.
 
 ```tsx
-#!/usr/bin/env bun
-import { createSmithersRoot, createSmithersDB, SmithersProvider, Claude } from "smithers-orchestrator";
-
-const db = await createSmithersDB({ path: ".smithers/night-shift" });
-const executionId = await db.execution.start("Night Shift", "night-shift.tsx");
-
-function NightShift() {
+#!/usr/bin/env smithers
+import {
+  createSmithersRoot,
+  createSmithersDB,
+  SmithersProvider,
+  Claude,
+} from "smithers-orchestrator";
+
+const db = createSmithersDB({ path: ".smithers/demo.db" });
+const executionId = db.execution.start("Demo", "demo.tsx");
+
+function Demo() {
   return (
-    <SmithersProvider db={db} executionId={executionId} maxIterations={50}>
-      <Claude
-        model="sonnet"
-        onFinished={(result) => {
-          if (result.output.includes("All tests pass")) {
-            db.state.set("complete", "true");
-          }
-        }}
-      >
-        Run tests. If any fail, fix them and commit the fix. Repeat until all tests pass.
+    <SmithersProvider db={db} executionId={executionId} maxIterations={5}>
+      <Claude model="sonnet" onFinished={(r) => console.log(r.output)}>
+        Fix the failing tests in this repository.
       </Claude>
     </SmithersProvider>
   );
 }
 
 const root = createSmithersRoot();
-await root.mount(NightShift);
+await root.mount(Demo);
 await db.close();
 ```
 
+Run it and monitor the execution frame by frame:
+
 ```bash
-bun night-shift.tsx
+smithers demo.tsx
 ```
 
-### 2. PRD to Implementation
+Smithers is a React framework for coding agents. Write the plan in any coding harness, then monitor your agents as they execute it. The plan is a mix of hardcoded logic and agent output that evolves reactively.
 
-Goal: Plan, implement, test, produce PR summary.
+By evolving a declarative plan rather than wiring up every agent interaction, Smithers excels at:
 
-```tsx
-#!/usr/bin/env bun
-import { createSmithersRoot, createSmithersDB, SmithersProvider, Phase, Step, Claude } from "smithers-orchestrator";
+1. **One-time agents** that accomplish a task and discard
+2. **Long-running agents** that run for days or weeks
 
-const db = await createSmithersDB({ path: ".smithers/prd-impl" });
-const executionId = await db.execution.start("PRD Implementation", "prd-impl.tsx");
+---
 
-function PRDToImplementation() {
-  return (
-    <SmithersProvider db={db} executionId={executionId} maxIterations={20}>
-      <Phase name="Plan">
-        <Step name="analyze-prd">
-          <Claude model="sonnet">
-            Read PRD.md. Create implementation plan with acceptance criteria.
-          </Claude>
-        </Step>
-      </Phase>
-
-      <Phase name="Implement">
-        <Step name="write-code">
-          <Claude model="sonnet">
-            Implement the plan. Commit after each logical unit of work.
-          </Claude>
-        </Step>
-        <Step name="write-tests">
-          <Claude model="sonnet">
-            Write tests for the implementation. Ensure all pass.
-          </Claude>
-        </Step>
-      </Phase>
-
-      <Phase name="Summary">
-        <Step name="pr-summary">
-          <Claude model="sonnet">
-            Generate PR summary with what changed and why.
-          </Claude>
-        </Step>
-      </Phase>
-    </SmithersProvider>
-  );
-}
+## Core Idea
 
-const root = createSmithersRoot();
-await root.mount(PRDToImplementation);
-await db.close();
-```
+You program the **plan**, not the agents. The plan is real executable code: React components that declare what should happen.
 
-### 3. Refactor with Checkpoints
+| Other Frameworks     | Smithers                   |
+| -------------------- | -------------------------- |
+| `agent.do_step_1()`  | `<Phase name="implement">` |
+| `agent.do_step_2()`  | `<Step name="code">`       |
+| `if failed: retry()` | `<Claude>Fix it</Claude>`  |
 
-Goal: Staged refactoring with checkpoints and rollback capability.
+The plan is declarative. Plans evolve in an easy-to-understand way over time, and if the plan breaks for any reason, your monitoring agent can edit the code and restart.
 
-```tsx
-#!/usr/bin/env bun
-import { createSmithersRoot, createSmithersDB, SmithersProvider, Phase, Step, Claude, Worktree } from "smithers-orchestrator";
+What renders is the current state of the multi-agent setup as readable XML, with SQLite durably persisting state.
 
-const db = await createSmithersDB({ path: ".smithers/refactor" });
-const executionId = await db.execution.start("Refactor", "refactor.tsx");
+Each iteration:
 
-function RefactorWorkflow() {
-  return (
-    <SmithersProvider db={db} executionId={executionId} maxIterations={30}>
-      <Worktree branch="smithers/refactor" cleanup>
-        <Phase name="Analyze">
-          <Step name="identify-targets">
-            <Claude model="sonnet">
-              Identify code that needs refactoring. Create a prioritized list.
-            </Claude>
-          </Step>
-        </Phase>
-
-        <Phase name="Refactor">
-          <Step name="refactor-code" snapshotBefore commitAfter>
-            <Claude model="sonnet">
-              Refactor each item. Run tests after each change. Commit if green.
-            </Claude>
-          </Step>
-        </Phase>
-
-        <Phase name="Verify">
-          <Step name="final-check">
-            <Claude model="sonnet">
-              Run full test suite. Document all changes made.
-            </Claude>
-          </Step>
-        </Phase>
-      </Worktree>
-    </SmithersProvider>
-  );
-}
+1. Render React to execution plan
+2. Execute runnable agents
+3. Agent output updates state
+4. State change triggers re-render
+5. Loop until done
 
-const root = createSmithersRoot();
-await root.mount(RefactorWorkflow);
-await db.close();
-```
+The plan runs as deterministic code, but agents can read it to understand the larger context they're operating within.
+
+Ralph (the [autonomous agent loop pattern](https://ghuntley.com/ralph/)) handles the render cycle, allowing the plan to run and evolve indefinitely. React handles the diffing.
 
 ---
 
-## Features
+## Why React?
 
-### Claude Component
+LLMs and humans perform well writing declarative React code. All coding agents can one-shot valid Smithers workflows naturally.
 
-The core agent component that executes Claude with full tool access:
+Most multi-agent frameworks fail. They add coordination overhead that costs more than it saves, and you end up worse than a simple while loop. Smithers avoids this by making the plan declarative and the state durable. React's functional nature makes even complex multiagent setups easy to modularize and easy to reason about.
 
-```tsx
-<Claude
-  model="sonnet" // opus | sonnet | haiku
-  maxTurns={10} // Limit agentic loops
-  permissionMode="acceptEdits" // Auto-accept file edits
-  systemPrompt="You are a senior engineer..."
-  allowedTools={["Read", "Edit", "Bash"]}
-  stopConditions={[
-    { type: "token_limit", value: 50000 },
-    { type: "pattern", value: /DONE/i },
-  ]}
-  onProgress={(msg) => console.log(msg)}
-  onFinished={(result) => handleResult(result)}
-  onError={(err) => handleError(err)}
->
-  Your prompt here
-</Claude>
-```
+React has a rich ecosystem that works well with agents: Zustand, React Query, and reactive versions of most libraries plug directly into React's reactivity system. This lets you compose declarative plans from battle-tested primitives.
 
-### Sophisticated Ralph Loops
+React gives you:
 
-Ralphing = continuous agent iteration with verification gates. Smithers lets you build **complex** Ralph loops with structure:
+- Composition and reuse
+- Version control diffs that make sense
+- Agent-generated code you can review
+- A massive ecosystem of reactive hooks to reuse
 
-```tsx
-<SmithersProvider db={db} executionId={executionId} maxIterations={50}>
-  <Phase name="Implement">
-    <Parallel>
-      <Claude model="sonnet">Fix auth module</Claude>
-      <Claude model="sonnet">Fix database module</Claude>
-    </Parallel>
-  </Phase>
+**React Hook Compatibility**: All [TanStack AI](https://tanstack.com/ai/latest/docs) and [Vercel AI SDK](https://ai-sdk.dev/docs) React hooks work in Smithers components.
 
-  <Phase name="Verify">
-    <Claude
-      model="sonnet"
-      onFinished={(result) => {
-        if (result.output.includes("All tests pass")) {
-          db.state.set("complete", "true");
-        }
-      }}
-    >
-      Run tests. If failures, iterate.
-    </Claude>
-  </Phase>
-</SmithersProvider>
-```
-
-**What Smithers adds:**
-- Multi-phase workflows with conditional transitions
-- Parallel agent execution with coordination
-- Composable, reusable components
-- Optional persistence for long-running workflows
+---
 
-### Structured Output with Zod
+## Quick Examples
 
-Get typed, validated responses with automatic retry:
+### Sequential Phases
 
 ```tsx
-const UserSchema = z.object({
-  name: z.string(),
-  email: z.string().email(),
-})
-
-<Claude schema={UserSchema} schemaRetries={2}>
-  Extract user info from: John Doe (john@example.com)
-</Claude>
-// result.structured: { name: string, email: string }
+<SmithersProvider db={db} executionId={executionId} maxIterations={10}>
+  <Phase name="implement">
+    <Step name="code">
+      <Claude>Implement the feature</Claude>
+    </Step>
+    <Step name="test">
+      <Claude>Write tests</Claude>
+    </Step>
+  </Phase>
+  <Phase name="review">
+    <Claude>Review the changes</Claude>
+  </Phase>
+</SmithersProvider>
 ```
 
-### MCP Tool Integration
-
-Give Claude access to external tools via Model Context Protocol:
+### Parallel Agents
 
 ```tsx
-<Claude>
-  <Sqlite path="./data.db" readOnly>
-    Database schema: users(id, name, email), orders(id, user_id, total)
-  </Sqlite>
-  Generate a report of top customers by order value.
-</Claude>
+<Parallel>
+  <Claude>Fix auth</Claude>
+  <Claude>Fix database</Claude>
+  <Claude>Fix API</Claude>
+</Parallel>
 ```
 
-### AI SDK Tool Format
-
-Define tools with Zod schemas and pass them to Claude:
+### Structured Output
 
 ```tsx
-import { z } from "zod";
-import { createSmithersTool } from "smithers-orchestrator/tools";
-
-const reportTool = createSmithersTool({
-  name: "report",
-  description: "Report progress to the orchestrator",
-  inputSchema: z.object({
-    message: z.string(),
-    severity: z.enum(["info", "warning", "error"]).optional(),
-  }),
-  execute: async ({ message, severity }, { db }) => {
-    await db.vcs.addReport({
-      type: "progress",
-      title: "Agent Report",
-      content: message,
-      severity: severity ?? "info",
-    });
-    return { success: true };
-  },
+const ReviewSchema = z.object({
+  approved: z.boolean(),
+  issues: z.array(z.string()),
 });
 
-<Claude tools={[reportTool]}>
-  Report progress as you go.
-</Claude>
-```
-
-### Smithers Subagent
-
-Spawn a new Smithers instance to plan and execute complex subtasks:
-
-```tsx
-<Smithers
-  plannerModel="opus" // Model for planning the script
-  executionModel="sonnet" // Model for agents in the script
-  timeout={600000} // 10 minute timeout
-  keepScript // Save the generated script for debugging
->
-  Create a new REST API endpoint with full CRUD operations, database migrations,
-  and comprehensive test coverage.
-</Smithers>
+<Claude schema={ReviewSchema}>Review the PR.</Claude>;
+// result.structured: { approved: boolean, issues: string[] }
 ```
 
-### Worktree
-
-Run agents in isolated git worktrees:
+### Worktree Isolation
 
 ```tsx
 <Worktree branch="feature-auth" cleanup>
-  <Claude>Implement user authentication</Claude>
+  <Claude>Implement authentication</Claude>
 </Worktree>
 ```
 
-### Git/JJ VCS Integration
-
-First-class version control support:
-
-```tsx
-// Git
-<Commit message="feat: Add user auth" notes={{ smithers: true }} />
-
-// Jujutsu (jj)
-<Snapshot description="Before refactoring" />
-<Commit autoDescribe />
-```
-
-### Orchestration Lifecycle
-
-Global timeout and completion logic for workflows:
-
-```tsx
-<Orchestration
-  globalTimeout={3600000} // 1 hour max
-  onComplete={() => console.log("Workflow finished")}
-  onTimeout={() => console.log("Workflow timed out")}
->
-  {/* Your workflow components */}
-</Orchestration>
-```
-
-### PhaseRegistry & Step
-
-Manage multi-phase sequential execution:
-
-```tsx
-<PhaseRegistry>
-  <Phase name="implement">
-    <Step name="write-code" snapshotBefore commitAfter commitMessage="feat: Implementation">
-      <Claude>Implement the feature</Claude>
-    </Step>
-    <Step name="write-tests">
-      <Claude>Write tests for the implementation</Claude>
-    </Step>
-  </Phase>
-  <Phase name="review">
-    <Review target={{ type: "diff", ref: "main" }} />
-  </Phase>
-</PhaseRegistry>
-```
-
-### Parallel Execution
-
-Run multiple agents concurrently within a step:
-
-```tsx
-<Parallel>
-  <Claude model="haiku">Quick task 1</Claude>
-  <Claude model="haiku">Quick task 2</Claude>
-  <Claude model="haiku">Quick task 3</Claude>
-</Parallel>
-```
+---
 
-### Database Persistence
+## Persistence
 
-Every run is a "flight recorder" - all state persists in SQLite:
+State lives in SQLite. Survives restarts.
 
 ```tsx
-// Set state (survives restarts)
-await db.state.set("phase", "review");
+// Set state
+db.state.set("phase", "review");
 
 // Get state
-const phase = await db.state.get("phase");
+const phase = db.state.get("phase");
 
-// Query history - see how state evolved
-const history = await db.state.getHistory("phase");
-
-// Resume incomplete executions
-const incomplete = await db.execution.findIncomplete();
+// Resume after crash
+const incomplete = db.execution.findIncomplete();
 if (incomplete) {
-  // Pick up exactly where you left off
   executionId = incomplete.id;
 }
 ```
 
-```bash
-# Inspect from CLI
-smithers db executions                    # List all runs
-smithers db state --execution-id abc123   # See state for a run
-smithers db stats                         # Database statistics
-```
-
 ---
 
-## FAQ
+## Observability
 
-### Is this actually React? Do I need to run a UI?
+The React tree is the observability. What you write is what gets logged.
 
-No UI. React is a component model + markup-like syntax. People already use it to render to non-DOM targets (CLI, PDFs, native). Smithers renders to **execution**, not DOM.
+```tsx
+<Phase name="deploy">
+  <Step name="build" status="completed">
+    ...
+  </Step>
+  <Step name="test" status="running">
+    ...
+  </Step>
+</Phase>
+```
 
-### Why not YAML/JSON for workflows?
+SQLite stores every frame. Use version control to rewind.
 
-Because you want:
-- Composition and reuse
-- Version control diffs that make sense
-- Something your coding agent can generate AND you can review like normal code
-
-### How does this relate to Ralphing?
+---
 
-Ralphing is the outer loop (iterate until verification passes). Smithers gives it structure, persistence, and inspectability. Think: "Smithers productionizes Ralph loops."
+## Install
 
-### What's a Ralph loop?
+```bash
+bun add -g smithers-orchestrator
+```
 
-From [vercel-labs/ralph-loop-agent](https://github.com/vercel-labs/ralph-loop-agent): continuous autonomy where the agent loops until the task is actually done, with verification gates (tests/linters). Smithers makes these loops durable.
+This installs the `smithers` CLI globally. Requires [Bun](https://bun.sh/) 1.0+.
 
----
+Or install the Claude Code plugin:
 
-## Contributing
+```
+/plugin add evmts/smithers
+```
 
-We accept **vibe-coded contributions** as long as you include your original prompt in a git note:
+---
 
-```bash
-git notes add -m "User prompt: <your prompt here>"
-```
+## Roadmap
 
-See [CONTRIBUTING.md](./CONTRIBUTING.md) for details.
+**North Star: SuperSmithers**: A meta-agent that watches your agents and rewrites their code to optimize. The architecture is ready. Coming soon.
 
 ---
 
-**Let your agent write agents. Built with React, powered by Claude.**
+## More
+
+- [Documentation](https://smithers.sh)
+- [Examples](./examples)
+- [Contributing](./CONTRIBUTING.md)