Switchyard

Switchyard is a CLI tool for managing AI-assisted development workflows. It provides guardrails and state management for controlled, checkpoint-based feature development.

Features

• 🎯 Checkpoint Guardrails - Checkpoints prevent Claude from going off the rails; work stays focused and incremental
• 🔄 Resume After Crashes - If Claude loses context or crashes, pick up exactly where you left off
• ✅ Trust But Verify - Verification artifacts prove checkpoints are complete, not just "looks done"
• 🛡️ Isolate Risky Changes - Each feature runs in its own worktree; your main branch stays clean
• ⚡ Zero Setup Friction - Dependencies auto-install when you create a lane; just start coding
• 📜 Clean Git History - Squash merges keep your commit log readable, not cluttered with AI iterations
• 📋 Full Audit Trail - Event logs show exactly what happened, when, and in what order

Quick Start

Installation

Install globally and use everywhere:

bun add -g github:BrettHamlin/switchyard

Or run directly without installing:

bunx github:BrettHamlin/switchyard <command>

Basic Workflow

Switchyard uses a simple 3-command workflow: init → new → run

1. Initialize Your Repository

switchyard init

This creates a .switchyard/ directory with:

• FOUNDATION.md - Your project's governance document
• events.jsonl - Repository-level event log

2. Create a New Lane

A "lane" is an isolated worktree for developing a feature:

switchyard new my-feature

This:

• Creates a git worktree at .switchyard/wt/my-feature/
• Installs dependencies (auto-detects bun/npm/yarn/pnpm)
• Launches Claude Code in the new worktree

To pass flags to Claude Code, use double-dash flags:

switchyard new my-feature --dangerously-skip-permissions

To skip Claude launch:

switchyard new my-feature -no-claude

3. Add Tasks

Create a tasks file using SpecKit's directory structure:

specs/{NNN}-{feature}/tasks.md   # e.g., specs/003-my-feature/tasks.md

Switchyard auto-discovers the highest-numbered spec directory (e.g., if you have specs/001-... and specs/003-..., it uses 003).

Example tasks file:

# Tasks

## Checkpoint 1: Setup
- [ ] T001 Create initial project structure
- [ ] T002 Add configuration files

## Checkpoint 2: Core Features
- [ ] T003 Implement main functionality
- [ ] T004 Add tests

4. Run the Lane

# From main repo - specify lane name
switchyard run my-feature

# From within the lane worktree - auto-detects current lane
cd .switchyard/wt/my-feature
switchyard run

This will:

• Auto-discover your tasks file from specs/{NNN}-{feature}/
• Lock the lane for execution
• Hand off to the AI agent for execution

The AI agent automatically handles checkpoint verification, commits, and progress tracking as it works through the tasks.

Checking Status

View all lanes and their current state:

switchyard status

View a specific lane (or auto-detect from within worktree):

switchyard status my-feature

# Or from within the lane worktree
cd .switchyard/wt/my-feature
switchyard status

Other Commands

# Get detailed explanation of a lane's state
switchyard explain my-feature

# Reset a lane to draft status
switchyard reset my-feature

# Delete a lane (archives state by default)
switchyard delete my-feature
switchyard delete my-feature -force      # Delete even if running/locked
switchyard delete my-feature -no-archive # Delete without archiving

# Merge a completed lane to main
switchyard merge my-feature
switchyard merge my-feature -no-squash   # Use regular merge instead of squash
switchyard merge my-feature -no-cleanup  # Keep lane after merge
switchyard merge my-feature -base develop # Merge to different branch

# Force re-initialization (overwrites existing)
switchyard init -force

Flag Convention

Switchyard uses a simple flag convention:

• Single-dash flags (-flag): Go to switchyard
• Double-dash flags (--flag): Passed to Claude Code on new command

Examples:

# -force is a switchyard flag
switchyard init -force

# --model is passed to Claude
switchyard new my-feature --model opus

# Mix both
switchyard new my-feature -no-claude --dangerously-skip-permissions

Verification Artifacts

Verification artifacts are markdown files that document checkpoint completion. They provide evidence that acceptance criteria have been met.

Generating a Template

Use the -template flag to generate a pre-filled verification artifact:

# Generate template for checkpoint 1
switchyard checkpoint 1 -template

# Overwrite existing template
switchyard checkpoint 1 -template -force

# Output as JSON
switchyard checkpoint 1 -template -json

This creates a file at .agent/checkpoint-1-verification.md with:

• Current timestamp
• Current git commit hash
• Placeholder sections to fill in

Verification Artifact Format

checkpoint: 1
completedAt: 2025-01-24T15:30:00Z
commitHash: abc1234

## Criteria Satisfied
- SC-001: Implemented feature X with full test coverage
- SC-002: Added documentation for new API

## Anti-Criteria Checked
- [x] No regressions introduced
- [x] All tests pass
- [x] No security vulnerabilities added

## Evidence
- test_output: .agent/test-log.txt
- commit: abc1234

Required Fields

Field	Format	Description
checkpoint	Integer	Checkpoint number (1, 2, 3...)
completedAt	ISO 8601	Timestamp (e.g., 2025-01-24T15:30:00Z)
commitHash	Hex string	Git commit hash (7+ characters)

Anti-Criteria

All anti-criteria must be checked [x] for the checkpoint to pass:

## Anti-Criteria Checked
- [x] No regressions introduced    # Checked - passes
- [ ] All tests pass               # Unchecked - FAILS!

Common Errors

Error	Solution
Missing checkpoint number	Add checkpoint: N at the top
Missing completedAt timestamp	Add completedAt: <ISO timestamp>
Missing commitHash	Add commitHash: <git hash>
Anti-criteria not confirmed	Change [ ] to [x] for all items

Recording a Checkpoint

After filling in the verification artifact:

switchyard checkpoint 1 \
  -commit abc1234 \
  -test-log .agent/test-log.txt \
  -verification .agent/checkpoint-1-verification.md

Claude Code Integration

When you run switchyard init, it also installs Claude Code slash commands in .claude/commands/. These let you run Switchyard directly from within Claude Code:

Command	Description
/switchyard-new <lane>	Create a new lane
/switchyard-run [lane]	Run a lane (auto-detects if in worktree)
/switchyard-status [lane]	Check lane status (auto-detects if in worktree)
/switchyard-explain <lane>	Get detailed lane explanation
/switchyard-reset [lane]	Reset a lane to draft
/switchyard-delete <lane>	Delete a lane and clean up
/switchyard-merge <lane>	Merge completed lane to main

This means you can manage your entire Switchyard workflow without leaving your Claude Code session.

Lane States

Lanes progress through these states:

State	Description
draft	Lane created, awaiting tasks
locked	Tasks file locked, ready to run
running	Execution in progress
blocked	Waiting on dependency or external factor
suspect	Potential issue detected
done	All checkpoints complete

Project Structure

your-repo/
├── .switchyard/           # Switchyard config (in main repo)
│   ├── FOUNDATION.md      # Governance document
│   ├── events.jsonl       # Repository event log
│   └── wt/                # Worktrees directory
│       └── my-feature/    # Lane worktree
│           ├── .agent/    # Lane-specific state
│           │   ├── lane.json
│           │   ├── events.jsonl
│           │   └── ...
│           └── ...        # Your feature code
└── ...

Requirements

• Bun runtime
• Git 2.20+ (for worktree support)

License

MIT