Orchestration Commands

These commands are provided by the @stoneforge/smithy plugin and are available when the smithy package is installed. They handle agent lifecycle, task dispatch, merge operations, and pool management.

`sf agent`

Manage orchestrator agents — register, start, stop, and monitor.

`sf agent list`

sf agent list [options]

Option	Description
`-r, --role <role>`	Filter by role: `director`, `worker`, `steward`
`-s, --status <status>`	Filter by session status: `idle`, `running`, `suspended`, `terminated`
`-m, --workerMode <mode>`	Filter by worker mode: `ephemeral`, `persistent`
`-f, --focus <focus>`	Filter by steward focus: `merge`, `docs`, `recovery`, `custom`
`--reportsTo <id>`	Filter by manager entity ID
`--hasSession`	Only show agents with active sessions

Alias: sf agents

`sf agent show`

sf agent show <id>

Display detailed information about a registered agent, including role, session status, and metadata.

`sf agent register`

sf agent register <name> --role <role> [options]

Option	Description
`-r, --role <role>`	Agent role: `director`, `worker`, `steward` (required)
`-m, --mode <mode>`	Worker mode: `ephemeral`, `persistent`
`-f, --focus <focus>`	Steward focus: `merge`, `docs`, `recovery`, `custom`
`-t, --maxTasks <n>`	Maximum concurrent tasks (default: 1)
`--tags <tags>`	Comma-separated tags
`--reportsTo <id>`	Manager entity ID
`--roleDef <id>`	Role definition document ID
`--trigger <cron>`	Steward cron trigger (e.g., `"0 2 * * *"`)
`--provider <name>`	Agent provider: `claude-code`, `opencode`, `codex`
`--model <model>`	LLM model to use
`--target-branch <branch>`	Target branch for merge (director only, default: auto-detect)

sf agent register Director --role director
sf agent register Director --role director --target-branch staging
sf agent register Worker1 --role worker --mode ephemeral
sf agent register MergeSteward --role steward --focus merge
sf agent register Reviewer --role steward --focus custom --trigger "0 */4 * * *"

`sf agent start`

sf agent start <id> [options]

Option	Description
`-p, --prompt <text>`	Initial prompt to send to agent
`-m, --mode <mode>`	Spawn mode: `headless`, `interactive`
`-r, --resume <id>`	Provider session ID to resume
`-w, --workdir <path>`	Working directory for agent
`--cols <n>`	Terminal columns for interactive mode (default: 120)
`--rows <n>`	Terminal rows for interactive mode (default: 30)
`--timeout <ms>`	Timeout in milliseconds (default: 120000)
`-e, --env <KEY=VALUE>`	Environment variable (repeatable)
`-t, --taskId <id>`	Task ID to assign to agent
`--stream`	Stream agent output after starting
`--provider <name>`	Override agent provider for this session
`--model <model>`	Override model for this session

`sf agent stop`

sf agent stop <id> [--no-graceful] [--reason <text>]

Option	Description
`-g, --graceful`	Graceful shutdown (default: true)
`--no-graceful`	Force immediate shutdown
`-r, --reason <text>`	Reason for stopping

`sf agent stream`

sf agent stream <id>

Get the agent’s output channel for live streaming.

`sf daemon`

Manage the dispatch daemon — the background process that auto-assigns ready tasks to idle workers.

`sf daemon start`

sf daemon start [--server <url>]

`sf daemon stop`

sf daemon stop [--server <url>] [--force]

`sf daemon status`

sf daemon status [--server <url>]

Shows daemon status, uptime, tasks dispatched, and rate limit info.

`sf daemon sleep`

Pause dispatch until a specified time.

sf daemon sleep --until "3am"
sf daemon sleep --until "tomorrow at 9:30am"
sf daemon sleep --duration 3600

Option	Description
`-s, --server <url>`	Orchestrator server URL (default: `http://localhost:3457`)
`-u, --until <time>`	Sleep until time (e.g., `"3am"`, `"Feb 22 at 9:30am"`)
`-d, --duration <secs>`	Sleep for duration in seconds

One of --until or --duration is required (not both).

`sf daemon wake`

Immediately resume dispatch. Clears rate limits and sleep timer.

sf daemon wake [--server <url>]

`sf dispatch`

Manually dispatch a task to a specific agent. This bypasses the dispatch daemon — useful for debugging or one-off assignments.

sf dispatch <task-id> <agent-id> [options]

Option	Description
`-b, --branch <branch>`	Git branch for task
`-w, --worktree <path>`	Worktree path for task
`-s, --session <id>`	Session ID to associate
`-m, --markAsStarted`	Mark task as started after dispatch

`sf merge`

Squash-merge a branch into the default branch. This is the same merge operation used by the merge steward, available as a standalone command.

sf merge [options]

Option	Description
`-b, --branch <name>`	Source branch to merge (default: current branch)
`-i, --into <name>`	Target branch (default: auto-detected master/main)
`-m, --message <text>`	Commit message (default: `"Merge <branch>"`)
`--cleanup`	Delete source branch and worktree after merge

The merge process:

Fetches latest from origin
Creates a temporary worktree at the target branch
Squash-merges the source branch
Commits and pushes
Cleans up the temporary worktree
Optionally removes the source branch and worktree (--cleanup)

`sf pool`

Manage agent pools for controlling concurrency.

`sf pool list`

sf pool list [--enabled] [--available] [--tag <tag>]

Option	Description
`-e, --enabled`	Only show enabled pools
`-a, --available`	Only show pools with available slots
`-t, --tag <tag>`	Filter by tag

Alias: sf pools

`sf pool show`

sf pool show <id|name>

`sf pool create`

sf pool create <name> [options]

Option	Description
`-s, --size <n>`	Maximum pool size (default: 5)
`-d, --description <text>`	Pool description
`-t, --agentType <config>`	Agent type config (repeatable, see format below)
`--tags <tags>`	Comma-separated tags
`--disabled`	Create pool in disabled state

The --agentType flag uses a colon-separated format:

role[:mode|focus][:priority][:maxSlots][:provider][:model]

sf pool create workers --size 5 \
  -t "worker:ephemeral:100:5:claude-code" \
  -t "steward:merge:80:1"

`sf pool update`

sf pool update <id|name> [--size <n>] [--enable] [--disable] [--agentType <config>]

`sf pool delete`

sf pool delete <id|name> [--force]

Use --force to delete even if agents are active.

`sf pool status`

sf pool status <id|name>

Shows pool status with active agents and slot utilization.

`sf pool refresh`

sf pool refresh

Refresh pool status from active sessions. Useful if pool counts drift.

`sf task` (orchestration)

`sf task handoff`

Hand off a task to another agent. The task returns to the pool with context notes, and the branch/worktree are preserved for the next worker.

sf task handoff <task-id> [options]

Option	Description
`-m, --message <text>`	Handoff message with context for the next worker
`-b, --branch <name>`	Override branch to preserve
`-w, --worktree <path>`	Override worktree path to preserve
`-s, --sessionId <id>`	Session ID (defaults to current session)

`sf task complete`

Complete a task and optionally create a merge request.

sf task complete <task-id> [options]

Option	Description
`-s, --summary <text>`	Summary of accomplishments
`-c, --commitHash <hash>`	Commit hash for final commit
`--no-mr`	Skip merge request creation
`--mr-title <title>`	Custom merge request title
`--mr-body <body>`	Custom merge request body
`-b, --baseBranch <name>`	Base branch for merge request (default: main)

`sf task merge`

Squash-merge a task branch and close the task.

sf task merge <task-id> [--summary <text>]

Validates the task is in REVIEW status, performs the squash-merge, pushes, sets merge status to merged, closes the task, and cleans up the branch and worktree.

`sf task reject`

Mark a task merge as failed and reopen it.

sf task reject <task-id> --reason <text> [--message <text>]

Option	Description
`-r, --reason <text>`	Reason for rejection (required)
`-m, --message <text>`	Handoff message for the next worker

`sf task sync`

Sync a task branch with the main branch (merge main into the task branch).

sf task sync <task-id>

Fetches from origin, merges main/master into the task branch, and reports success, conflicts, or errors.

`sf task merge-status`

Update the merge status of a task.

sf task merge-status <task-id> <status>

Valid statuses: pending, testing, merging, merged, conflict, test_failed, failed, not_applicable. Terminal statuses (merged, not_applicable) automatically close the task.

`sf task set-owner`

Set the owning director for a task. This sets the owningDirector field in the task’s orchestrator metadata, used for message routing in multi-director workspaces.

sf task set-owner <task-id> <director-id>

sf task set-owner el-abc123 el-dir01

Orchestration Commands

sf agent

sf agent list

sf agent show

sf agent register

sf agent start

sf agent stop

sf agent stream

sf daemon

sf daemon start

sf daemon stop

sf daemon status

sf daemon sleep

sf daemon wake

sf dispatch

sf merge

sf pool

sf pool list

sf pool show

sf pool create

sf pool update

sf pool delete

sf pool status

sf pool refresh

sf task (orchestration)

sf task handoff

sf task complete

sf task merge

sf task reject

sf task sync

sf task merge-status

sf task set-owner