Skip to main content

​
Step Component

The <Step> component represents an individual step within a workflow phase, providing fine-grained tracking.

​
Basic Usage

import { Step } from "smithers-orchestrator";

<Phase name="Implementation">
  <Step name="Create API">
    <Claude>Create the API endpoint.</Claude>
  </Step>
  <Step name="Add Tests">
    <Claude>Write tests for the API.</Claude>
  </Step>
</Phase>

​
Props

​
name
string
Name of the step for tracking and logging.
​
children
ReactNode
required
Content to execute within the step.

​
VCS Integration

​
snapshotBefore
boolean
default:"false"
Create a JJ snapshot before step execution. Useful for rollback if step fails.
Requires JJ to be configured in the repository. Logs a warning if JJ is unavailable.
​
snapshotAfter
boolean
default:"false"
Create a JJ snapshot after step completes successfully.
​
commitAfter
boolean
default:"false"
Create a JJ commit after step completes. The commit is logged to the database via db.vcs.logCommit().
​
commitMessage
string
Custom commit message when commitAfter is true. Defaults to "Step: {step-name}".

​
Callbacks

​
onStart
() => void
Called when the step starts executing.
​
onComplete
() => void
Called when the step completes successfully.
​
onError
(error: Error) => void
Called when the step encounters an error.

​
VCS Integration

Steps can automatically create JJ snapshots and commits: 
<Phase name="Implementation">
  <Step 
    name="Implement Feature"
    snapshotBefore
    commitAfter
    commitMessage="feat: implement user authentication"
    onComplete={() => console.log("Feature implemented")}
  >
    <Claude>Implement the authentication system.</Claude>
  </Step>
</Phase>
VCS operations fail gracefully - if JJ is not configured or an operation fails, a warning is logged but the step continues. This prevents VCS issues from blocking workflow execution.

​
Structured Workflow

<SmithersProvider db={db} executionId={executionId} globalTimeout={3600000}>
  <Phase name="Setup">
    <Step name="Check Environment">
      <Claude allowedTools={["Bash"]}>
        Verify dependencies are installed.
      </Claude>
    </Step>
    <Step name="Create Branch">
      <Claude allowedTools={["Bash"]}>
        Create a feature branch.
      </Claude>
    </Step>
  </Phase>

  <Phase name="Development">
    <Step name="Implement Feature">
      <Claude allowedTools={["Edit", "Write"]}>
        Write the code.
      </Claude>
    </Step>
    <Step name="Add Tests">
      <Claude allowedTools={["Write"]}>
        Create test files.
      </Claude>
    </Step>
  </Phase>

  <Phase name="Verification">
    <Step name="Run Tests">
      <Claude allowedTools={["Bash"]}>
        Execute the test suite.
      </Claude>
    </Step>
    <Step name="Run Linter">
      <Claude allowedTools={["Bash"]}>
        Check code style.
      </Claude>
    </Step>
  </Phase>
</SmithersProvider>

​
Database Tracking

Steps are tracked in the database: 
const steps = await db.steps.list({ executionId });
// [
//   { id: "s1", name: "Check Environment", status: "complete", ... },
//   { id: "s2", name: "Create Branch", status: "complete", ... },
//   { id: "s3", name: "Implement Feature", status: "running", ... },
// ]

Phase

Group steps into phases

SmithersProvider

Top-level control