Agent Roles

Stoneforge orchestrates AI coding agents through three primary roles: Director, Worker, and Steward. Each role has distinct responsibilities and lifecycle patterns.

Role Overview

Director

Strategic plannerCreates and prioritizes tasks

Worker

Code producerExecutes tasks in isolation

Steward

Maintenance agentHandles merge and recovery

Director

The Director is the strategic coordinator that translates human goals into actionable work.

Responsibilities

Task Planning

Receives goals from human operators
Breaks down work into discrete tasks
Sets priorities (1-5 scale, 1 is highest)
Defines task dependencies
Creates plans for related task groups

Coordination

Reports status to human when requested
Does NOT monitor workers (handled by daemon)
Does NOT dispatch tasks (handled by daemon)
Focuses on strategic planning, not tactical execution

Session Type

Persistent (Interactive) - Directors run continuously in an interactive session.

// Register a Director
const director = await orchestrator.registerDirector({
  name: 'project-director',
  createdBy: humanId,
  maxConcurrentTasks: 1,
});

// Start interactive session
await orchestrator.startSession(director.id, {
  mode: 'interactive',
  initialPrompt: 'Ready to plan work',
});

Example Workflow

Directors create tasks but do not assign them. The Dispatch Daemon handles assignment automatically.

Worker

Workers execute tasks and produce code. They come in two flavors: Ephemeral and Persistent.

Ephemeral Worker

Overview
Lifecycle
Registration

Short-lived workers spawned per-task by the Dispatch Daemon.Key Characteristics:

Auto-spawned when task is available
Runs in isolated git worktree
Auto-terminates after task completion
Reports to Director (indirectly)

// Register ephemeral worker
const worker = await orchestrator.registerWorker({
  name: 'e-worker-1',
  workerMode: 'ephemeral',
  createdBy: directorId,
});

// No manual start needed - daemon spawns automatically

Worktree Isolation

Each ephemeral worker gets its own git worktree:

# Worktree path pattern
agent/{worker-name}/{task-id}-{slug}/

# Example
agent/e-worker-1/abc123-implement-login/

Worktrees provide true isolation - multiple workers can work on the same repository simultaneously without conflicts.

Persistent Worker

Overview
Use Cases
Registration

Long-lived workers for interactive, exploratory work with a human.Key Characteristics:

Manually started and stopped
Not auto-dispatched by daemon
Responds to human in real-time
Session-scoped worktree

// Register persistent worker
const worker = await orchestrator.registerWorker({
  name: 'p-worker-debug',
  workerMode: 'persistent',
  createdBy: humanId,
});

// Manually start session
await orchestrator.startSession(worker.id, {
  mode: 'interactive',
  workingDirectory: 'agent/p-worker-debug/session-20260302',
});

Worker Task Execution

When a worker receives a task:

Read Task Context

Task title and description
Acceptance criteria
Dependencies and blockers
Handoff notes (if continuing previous work)

Execute Work

Make code changes
Run tests
Commit frequently with clear messages
Push to remote regularly

Complete or Handoff

Complete: sf task complete <task-id>

Moves task to REVIEW status
Creates merge request
Triggers Merge Steward

Handoff: sf task handoff <task-id> --message "reason"

Unassigns worker
Preserves worktree and branch
Appends handoff note to description
Returns task to pool for next worker

Steward

Stewards handle specialized maintenance workflows that keep the system running smoothly.

Steward Types

Merge Steward
Docs Steward
Recovery Steward
Custom Steward

Focus: Code integration and quality gatesTriggers: Task moves to REVIEW statusWorkflow:

Run test command
If tests pass: squash-merge to main
If tests fail: create handoff task with error logs
Clean up merged worktree and branch

Configuration:

await orchestrator.registerSteward({
  name: 'm-steward-1',
  stewardFocus: 'merge',
  createdBy: directorId,
  triggers: [{
    type: 'event',
    event: 'task_review_ready',
  }],
});

Focus: Documentation accuracy and consistencyTriggers: Cron schedule (e.g., daily)Workflow:

Scan documentation for outdated information
Check code examples against actual implementation
Fix errors and create PR
Auto-merge if tests pass

Configuration:

await orchestrator.registerSteward({
  name: 'd-steward-1',
  stewardFocus: 'docs',
  createdBy: directorId,
  triggers: [{
    type: 'cron',
    schedule: '0 2 * * *', // 2 AM daily
  }],
});

Focus: Diagnose and recover stuck tasksTriggers: Event (orphaned task detected)Workflow:

Analyze task history and handoff notes
Identify root cause (missing access, dependency, etc.)
Either fix and continue, or escalate to human

Configuration:

await orchestrator.registerSteward({
  name: 'r-steward-1',
  stewardFocus: 'recovery',
  createdBy: directorId,
});

Focus: User-defined workflowTriggers: Cron or event (user-defined)Workflow: Defined by custom playbookConfiguration:

await orchestrator.registerSteward({
  name: 'c-steward-deploy',
  stewardFocus: 'custom',
  createdBy: directorId,
  playbookId: 'deployment-playbook',
  triggers: [{
    type: 'event',
    event: 'main_branch_updated',
  }],
});

Steward Execution Model

Stewards are ephemeral by default:

// Steward lifecycle
Trigger fires (event or cron)
Daemon spawns steward session
Steward executes workflow
Session terminates
Wait for next trigger

Stewards should be idempotent - safe to run multiple times without side effects.

Role Comparison Matrix

Attribute	Director	Ephemeral Worker	Persistent Worker	Steward
Session Type	Persistent	Ephemeral	Persistent	Ephemeral
Reports To	Human	Director	Human	System
Dispatch	Manual	Automatic	Manual	Trigger-based
Worktree	Optional	Required	Optional	Temporary
Concurrency	1	Pool-limited	1	Pool-limited
Use Case	Planning	Production	Exploration	Maintenance

Registration Examples

// Register and start a Director
const director = await orchestrator.registerDirector({
  name: 'project-director',
  createdBy: humanId,
  provider: 'claude-code',
  model: 'claude-sonnet-4',
});

await orchestrator.startSession(director.id, {
  mode: 'interactive',
});

Next Steps

Orchestration Loop

See how agents are dispatched and coordinated

Task Management

Learn about task lifecycle and handoffs

Workflows

Build reusable task sequences

Dependencies

Understand blocking relationships

Get Started

Core Concepts

Guides

Role Overview

Director

Worker

Steward

Director

Responsibilities

Session Type

Example Workflow

Worker

Ephemeral Worker

Worktree Isolation

Persistent Worker

Exploration

Pair Programming

Hot Fixes

Learning

Worker Task Execution

Steward

Steward Types

Steward Execution Model

Role Comparison Matrix

Registration Examples

Next Steps

Orchestration Loop

Task Management

Workflows

Dependencies

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

​Role Overview

Director

Worker

Steward

​Director

​Responsibilities

​Session Type

​Example Workflow

​Worker

​Ephemeral Worker

​Worktree Isolation

​Persistent Worker

Exploration

Pair Programming

Hot Fixes

Learning

​Worker Task Execution

​Steward

​Steward Types

​Steward Execution Model

​Role Comparison Matrix

​Registration Examples

​Next Steps

Orchestration Loop

Task Management

Workflows

Dependencies

Build docs developers (and LLMs) love

Role Overview

Director

Responsibilities

Session Type

Example Workflow

Worker

Ephemeral Worker

Worktree Isolation

Persistent Worker

Worker Task Execution

Steward

Steward Types

Steward Execution Model

Role Comparison Matrix

Registration Examples

Next Steps