Usage Examples - Stoneforge

Example 1: Feature Development Workflow

A complete end-to-end workflow for building a new feature with multiple agents.

Scenario

You want to build a new user authentication system with OAuth support, including API endpoints, frontend UI, tests, and documentation.

Implementation

Create a plan with the Director

Send a message to the Director:

Build a complete OAuth authentication system with Google and GitHub providers. 
Include backend API, frontend login UI, unit tests, integration tests, and documentation.

The Director creates a plan:

sf plan list

Output:

el-plan001  OAuth Authentication System  active  5 tasks

Review the task breakdown

sf plan tasks el-plan001

Output:

el-task001  [P1] Backend OAuth API endpoints         open
el-task002  [P2] Frontend login component            blocked
el-task003  [P2] Unit tests for OAuth service        blocked
el-task004  [P3] Integration tests                   blocked
el-task005  [P3] API and user documentation          blocked

Dependencies:

Task 2, 3, 4, 5 are blocked by task 1
Task 4 is blocked by tasks 2 and 3

Dispatch daemon assigns tasks

The daemon detects task 1 is ready and assigns it to an idle worker:

sf agent list --status active

Output:

el-agent001  director     active    (persistent session)
el-agent002  e-worker-1   active    assigned to el-task001

Worker executes in isolated worktree

Worker 1 operates in:

agent/e-worker-1/task001-backend-oauth-api/

On completion, the worker:

Commits changes
Pushes to remote
Creates a merge request
Updates task status to review

Steward reviews and merges

The merge steward:

# Runs tests
npm test

# On pass: squash-merge
git merge --squash agent/e-worker-1/task001-backend-oauth-api
git commit -m "feat: add OAuth API endpoints"
git push

Task 1 status → closed

Parallel execution begins

With task 1 complete, tasks 2, 3, and 5 become ready. The daemon assigns them to 3 workers in parallel:

sf agent list --status active

Output:

el-agent002  e-worker-1   active    assigned to el-task002
el-agent003  e-worker-2   active    assigned to el-task003
el-agent004  e-worker-3   active    assigned to el-task005

Task 4 remains blocked until tasks 2 and 3 complete.

Workers execute in parallel without conflicts because each operates in its own git worktree.

CLI Commands Reference

# View plan progress
sf plan show el-plan001 --tasks

# Check ready tasks
sf task list --ready

# Watch active agents
watch -n 2 'sf agent list --status active'

# View merge requests
sf merge list

# Check daemon status
sf daemon status

Example 2: Bug Fix with Handoff

Demonstrates how workers handle blockers and hand off tasks.

Scenario

A worker encounters a blocker while fixing a bug and hands off the task to another worker.

# Director creates a critical bug fix task
sf task create \
  --title "Fix memory leak in WebSocket handler" \
  --priority 1 \
  --type bug \
  --description "Users report connection drops after 10 minutes"

Handoffs preserve context across workers. The second worker sees the first worker’s notes and branch history.

Example 3: Documentation Steward

Automatically scan and fix documentation issues.

Setup

sf agent register d-steward-1 --role steward --focus docs

Configuration

Customize the docs steward prompt in .stoneforge/prompts/steward-docs.md:

# Your Focus: Documentation

You are responsible for:
- Scanning documentation for accuracy
- Detecting stale API references
- Fixing typos and broken links
- Ensuring code examples match current API

## Workflow

1. Run weekly scans on documentation files
2. Create fix tasks for issues found
3. Auto-fix minor issues (typos, formatting)
4. Escalate major issues to Director

Trigger a Scan

Manual
Scheduled

Start the steward and send a command:

sf agent start <docs-steward-id>

In the steward terminal:

Scan documentation in /docs and create fix tasks for any issues.

Use a cron job to trigger weekly scans:

# Add to crontab
0 2 * * 1 cd /path/to/project && sf agent start <docs-steward-id> --command "Scan and fix documentation"

Example Output

sf task list --tag documentation

Output:

el-task101  [P2] Fix outdated API example in auth.md       open
el-task102  [P3] Update broken link to deployment guide    open
el-task103  [P3] Fix typos in installation.md             closed

Example 4: Using Quarry API Programmatically

Build custom integrations using the Stoneforge SDK.

Install Dependencies

npm install @stoneforge/core @stoneforge/storage @stoneforge/quarry

Create and Manage Tasks

import { createQuarryAPI } from '@stoneforge/quarry';
import { createStorage, initializeSchema } from '@stoneforge/storage';
import { asEntityId } from '@stoneforge/core';

// Initialize storage and API
const storage = createStorage('.stoneforge/stoneforge.db');
initializeSchema(storage);
const api = createQuarryAPI(storage);

const operatorId = asEntityId('el-0000');

// Create a task
const task = await api.create({
  type: 'task',
  title: 'Implement feature X',
  priority: 2,
  taskType: 'feature',
  createdBy: operatorId,
});

console.log(`Created task: ${task.id}`);

// Query ready tasks
const ready = await api.ready();
console.log(`Ready tasks: ${ready.length}`);

// Add a dependency
const prerequisite = await api.create({
  type: 'task',
  title: 'Set up infrastructure',
  priority: 1,
  taskType: 'task',
  createdBy: operatorId,
});

await api.addDependency({
  blockerId: prerequisite.id,
  blockedId: task.id,
  type: 'blocks',
});

console.log(`Task ${task.id} is now blocked by ${prerequisite.id}`);

// Search documents with FTS5
const results = await api.searchDocumentsFTS('authentication flow', {
  hardCap: 10,
});

console.log(`Found ${results.length} documents`);

Register and Manage Agents

import { createOrchestratorAPI } from '@stoneforge/smithy';
import { asEntityId } from '@stoneforge/core';

const orchAPI = createOrchestratorAPI(storage);
const operatorId = asEntityId('el-0000');

// Register a worker agent
const worker = await orchAPI.registerWorker({
  name: 'backend-specialist',
  workerMode: 'ephemeral',
  provider: 'claude-code',
  createdBy: operatorId,
  tags: ['backend', 'typescript'],
});

console.log(`Registered worker: ${worker.id}`);

// List available workers
const availableWorkers = await orchAPI.getAvailableWorkers();
console.log(`Available workers: ${availableWorkers.length}`);

// Get agent metadata
const agentMeta = orchAPI.getAgentMetadata(worker);
console.log(`Agent role: ${agentMeta?.role}`);
console.log(`Worker mode: ${agentMeta?.workerMode}`);

Example 5: Multi-Stage Deployment Workflow

Orchestrate a complex deployment pipeline with dependencies.

Workflow Definition

Create a playbook in .stoneforge/playbooks/deploy.yaml:

name: Production Deployment
variables:
  - version
  - environment

steps:
  - id: build
    title: "Build Docker image"
    priority: 1
    type: task
    taskType: chore

  - id: test
    title: "Run integration tests"
    priority: 1
    type: task
    taskType: task
    dependsOn: [build]

  - id: deploy-staging
    title: "Deploy to staging"
    priority: 2
    type: task
    taskType: chore
    dependsOn: [test]

  - id: smoke-test
    title: "Run smoke tests on staging"
    priority: 2
    type: task
    taskType: task
    dependsOn: [deploy-staging]

  - id: deploy-prod
    title: "Deploy to production"
    priority: 3
    type: task
    taskType: chore
    dependsOn: [smoke-test]

  - id: verify
    title: "Verify production deployment"
    priority: 3
    type: task
    taskType: task
    dependsOn: [deploy-prod]

Instantiate Workflow

# Create workflow from playbook
sf workflow create deploy --var version=1.2.0 --var environment=production

Output:

✓ Created workflow: el-wf001
✓ Created 6 tasks with dependencies

Monitor Progress

# View workflow status
sf workflow progress el-wf001

Output:

Workflow: Production Deployment (el-wf001)
Status: running
Progress: 3/6 tasks complete

✓ build              closed
✓ test               closed
✓ deploy-staging     closed
→ smoke-test         in_progress
⋯ deploy-prod        blocked
⋯ verify             blocked

Workflow Features

Durable State

Workflows survive restarts. If a step fails, the workflow resumes from that step.

Dependency-Aware

Tasks execute only when prerequisites complete successfully.

Ephemeral Option

Use --ephemeral flag for one-time workflows not synced to JSONL.

Garbage Collection

Auto-cleanup old ephemeral workflows:

sf workflow gc --age 7

Example 6: Channel-Based Agent Communication

Agents communicate via channels for coordination.

Create a Team Channel

# Create a channel for backend team
sf channel create \
  --name backend-team \
  --description "Backend agent coordination" \
  --member el-agent001 \
  --member el-agent002 \
  --member el-agent003

Send Messages

# Worker sends a message to the channel
sf --from e-worker-1 message send \
  --channel el-ch001 \
  --content "Found a performance issue in the database query. Should I optimize now or create a separate task?"

Director Replies

# Director responds
sf --from director message send \
  --channel el-ch001 \
  --content "Create a separate task with priority 2. We'll optimize after the current feature is complete."

Direct Messages

# Worker sends DM to Director
sf --from e-worker-2 message send \
  --to director \
  --content "I'm blocked on task-123. The API spec is unclear about error handling."

# Director replies (auto-swaps sender/recipient)
sf --from director message reply el-msg456 \
  --content "I'll clarify the spec. Expect an update in 10 minutes."

Example 7: Custom Agent Pools

Control concurrency and resource allocation with agent pools.

Create Pools

# Create a pool for high-priority work
sf pool create priority-pool --size 2

# Create a pool for background tasks
sf pool create background-pool --size 1

Assign Agents to Pools

# Register workers in specific pools
sf agent register hp-worker-1 --role worker --pool priority-pool
sf agent register hp-worker-2 --role worker --pool priority-pool
sf agent register bg-worker-1 --role worker --pool background-pool

Pool Status

sf pool status

Output:

Pool: priority-pool
  Size: 2
  Active: 2/2
  Agents: hp-worker-1, hp-worker-2

Pool: background-pool
  Size: 1
  Active: 0/1
  Agents: bg-worker-1

The dispatch daemon respects pool size limits when assigning tasks. If a pool is at capacity, tasks wait for an agent to become available.

More Resources

CLI Reference

Full command documentation

Agent Roles

Deep dive into Director, Worker, and Steward roles

Dependency System

How blocking and non-blocking dependencies work

Gotchas

Common pitfalls and solutions

Get Started

Core Concepts

Guides

​Example 1: Feature Development Workflow

​Scenario

​Implementation

​CLI Commands Reference

​Example 2: Bug Fix with Handoff

​Scenario

​Example 3: Documentation Steward

​Setup

​Configuration

​Trigger a Scan

​Example Output

​Example 4: Using Quarry API Programmatically

​Install Dependencies

​Create and Manage Tasks

​Register and Manage Agents

​Example 5: Multi-Stage Deployment Workflow

​Workflow Definition

​Instantiate Workflow

​Monitor Progress

​Workflow Features

Durable State

Dependency-Aware

Ephemeral Option

Garbage Collection

​Example 6: Channel-Based Agent Communication

​Create a Team Channel

​Send Messages

​Director Replies

​Direct Messages

​Example 7: Custom Agent Pools

​Create Pools

​Assign Agents to Pools

​Pool Status

​More Resources

CLI Reference

Agent Roles

Dependency System

Gotchas

Build docs developers (and LLMs) love

Example 1: Feature Development Workflow

Scenario

Implementation

CLI Commands Reference

Example 2: Bug Fix with Handoff

Scenario

Example 3: Documentation Steward

Setup

Configuration

Trigger a Scan

Example Output

Example 4: Using Quarry API Programmatically

Install Dependencies

Create and Manage Tasks

Register and Manage Agents

Example 5: Multi-Stage Deployment Workflow

Workflow Definition

Instantiate Workflow

Monitor Progress

Workflow Features

Example 6: Channel-Based Agent Communication

Create a Team Channel

Send Messages

Director Replies

Direct Messages

Example 7: Custom Agent Pools

Create Pools

Assign Agents to Pools

Pool Status

More Resources