Switchyard: A Template for Agent-Assisted Development
I made Switchyard because I was doing a lot of the work around coding agents manually, without a coordinator agent to manage the flow. I wanted an agent to handle the handoffs between planning, implementation, and review, while I focused on product decisions and checking the work.
Switchyard is a template for that workflow. It contains no application code. You add your own stack, then use the workflow to take issues through a reviewed plan, implementation, and pull request.
The stack
Switchyard ties together a few tools, each with a specific job:
- GitHub holds the issues and pull requests. An issue describes the problem; acceptance criteria and behavior go into the spec.
- OpenSpec gives each behavior change a proposal, design, spec delta, and task list. Once the work ships, the change is archived into the current specs.
- Claude Code, Codex, and opencode can run the planner and implementer roles. The workflow keeps those roles in shared instructions, so the provider can change without rewriting the process.
- Git worktrees give each issue its own branch and checkout. Project hooks can assign it separate ports, dependencies, and data.
- Herdr runs workers in visible terminal panes, so I can watch sessions and interact with them. A headless CLI runner is available too.
- Python and shell scripts handle setup, teardown, status, screenshots, and merge helpers. The scripts keep stack-specific setup in project hooks rather than baking it into the workflow.
There is a small coordinator on the main checkout. It splits work, writes a brief, checks the plan before implementation, and reviews the diff before pushing. The planner stops after proposing the change. A fresh implementer session reads the plan from disk and builds it. Workers commit their work, but they do not push or merge.
That boundary is deliberate. Agents can do the contained planning and implementation work, while I keep the product decisions and the final review.
One issue through the workflow
The usual path starts with a short GitHub issue. The coordinator reads it against the code and asks about any decisions the issue leaves open. Then it creates a worktree and gives the planner the issue, owned paths, isolation details, and current decisions.
The planner proposes one OpenSpec change and stops with questions. The coordinator checks the proposal and brings me the remaining product choices. After I answer, the implementer starts in a fresh session, follows the tasks, runs the checks, updates the specs, and prepares a commit and pull request body.
The coordinator reviews the result. I review and approve the pull request before it merges.
For separate issues that own separate parts of the project, the coordinator can run them at the same time. Each gets its own checkout and its own setup. That makes parallel work less likely to collide in files or local services.
Why I use it
The main time saving is having a coordinator agent handle the repeated orchestration. It sets up the worktree and brief, gets the plan reviewed, hands it to the implementer, and checks the resulting diff before anything is pushed. When an issue is vague, the planner surfaces the questions before anyone writes code. The implementer starts fresh with the reviewed plan on disk, rather than relying on a long conversation being carried over.
I also wanted a workflow that does not depend on one coding agent. I can use Claude, Codex, or opencode for implementation, and Herdr gives me a way to keep the workers visible while they run. If I need a simpler setup, the headless runner uses the command line instead.
It has saved me a lot of time on the repeated coordination around agent-assisted work. I spend more of that time deciding what the project should do and checking what actually changed.
Switchyard does not make an issue clear or a diff correct by itself. I still have to make the product calls and review the work. It gives those decisions a consistent place in the process.
Herdr
A special shoutout to Herdr. It has been invaluable in my workflow. Switchyard can run workers in Herdr panes, where I can see each issue’s session and step in when needed. That makes a multi-worker setup feel like something I can supervise, rather than a collection of CLI processes I have to poll.
Getting started
Switchyard is a GitHub template. Create a project from it, replace the project-specific README and license, add your own checks and isolation hooks, and open the first issue. There is also a path for bringing the workflow into an existing repository.
The template is still changing. The current release is 0.3.0, and the repo includes an updater for carrying workflow files forward as new releases land.