Switchyard turns a development task—usually a GitHub issue—into a tested, reviewable pull request. A coding agent plans and edits the code; Switchyard keeps the workflow moving, saves progress, runs checks, and controls Git, GitHub, CI, and any optional merge.
Switchyard is unreleased and has no users. There is no long-term coexistence or user-compatibility promise.
Important
Active development is the Rust mission host under crates/. The runnable
capability is a local SQLite ledger driven by a fake runtime, plus explicit
Rust-owned worktree preparation/recovery (S3-A1). The TypeScript package in
adw_sdlc/ is a frozen reference.
The accepted long-term engine is Rust, including a native Rust agent runtime (decision, 2026-10-29). Pi Durable is a proof-of-concept adapter only, not that runtime. The planned M1 shape is Pi Durable 1.4.0 behind a sandboxed TypeScript bridge. Its source-built protocol candidate is accepted for credential-free M1 work; product agent execution remains gated on S3.
The optional pi-contract feature also exposes a credential-free
Host/outbox recovery probe for #119.
The default CLI still uses FakeRuntime.
S2 is GO for the credential-free source-built candidate, accepted 2026-11-02. See the acceptance record. The published-package audit remains historical NO-GO evidence.
The TypeScript path and runner-pi are frozen (2026-10-29) and will be
retired with the TypeScript engine. Python compatibility is dropped. State v1
(adw/state.schema.json, agents/<adw-id>/state.json) is frozen as-is: no
further changes and no new consumers. Rust missions do not resume those runs.
Worktree lifecycle is owned by S3
(#97) in Rust. TypeScript
managed-worktree work is stopped.
Do not delete adw_sdlc/ or adw/ under these decisions. Cleanup of the Rust
tree is tracked in
#109. This page does not
repeat that queue. Normative mission transitions stay in the
Rust-first architecture.
S1 (#95,
#105) is the implemented
host. crates/switchyard-core persists missions in an application-owned
SQLite ledger. The switchyard binary drives them with a fake runtime.
That host can create a mission from a local Git snapshot, admit commands,
recover after restart, and record fake-runtime observations. It does not call
a model, write to GitHub, confine a process, or resume frozen state v1.
switchyard mission status is read-only and does not take the owner lock.
switchyard mission workspace explicitly creates or reopens an attempt’s
owned worktree at its frozen base.
Uncertain ownership blocks recovery and retains evidence. This does not enable
agent commands or provide confinement.
cargo run --locked -p switchyard -- --help
./scripts/rust-verify.sh./scripts/rust-verify.sh is the Rust check. It expects the committed Rust
1.99.1 toolchain in rust-toolchain.toml and runs cargo fmt --check,
Clippy, and cargo test for the default feature set. CI runs this as the
rust-core job inside verify.yml. The required pi-bridge-contract job also
checks the workspace with pi-contract; the required execution-confinement
job checks the Linux backend and bridge lifecycle. rust-core itself is not
in the current required-check set.
The frozen TypeScript reference has a separate check. From adw_sdlc/:
npm run verifyThere is no root package.json. The stage list, Node 20.19.0 / 22 matrix, and
the Pi audit jobs are in
Testing and CI. Package-level detail is
in the package development guide.
Status for S1–S8 and the native Rust agent runtime is the delivery-plan status table.
Product milestone: #94.
Read these before changing mission, recovery, or runtime behavior:
- Rust-first architecture and M1 scope
- Delivery plan and gates
- Runtime protocol
- S2 package audit (published package NO-GO, 2026-10-29)
- S2 acceptance record (source-built candidate GO, 2026-11-02)
- Bounded composed S3 acceptance (credential-free fixture, 2026-11-10)
- Decision register
The product objective is one recoverable, verified change: freeze an objective, approve a plan, restart and recover the same attempt, repair a failed verification within limits, and publish one pull request only with an explicit approval. That outcome is milestone #94. S1 does not perform it against a model or GitHub.
| Path | Role | What it is |
|---|---|---|
crates/switchyard-core/, crates/switchyard/ |
Active | S1 library and switchyard binary. One library crate and one executable. |
docs/rust-first/ |
Active | Architecture, protocol, and gates. |
scripts/rust-verify.sh |
Active | Rust local gate. |
scripts/ui-verify.sh |
Active | Gate for crates/switchyard-ui: fmt, clippy, tests, and optional headless snapshots. Separate so the core gate never acquires GPU dependencies. |
wiki/ |
Active | OKF v0.1 map. Concepts cite canonical sources; they do not replace them. |
.github/workflows/ |
Active | Legacy verification and the rust-core job in verify.yml; package audit, source rebuild, full contract, and confinement workflows. |
adw_sdlc/ |
Reference | Frozen TypeScript engine: CLI, kernel, runners, and package docs. Kept while useful. |
adw/ |
Reference | Frozen state v1 schema and fixtures. |
.adw/ |
Reference | Project pack. .adw/prompts/ is generated; npm run pack:check owns that drift gate. |
.pi/prompts/ |
Reference | Hand-maintained neutral prompt source. |
.claude/commands/ |
Reference | Generated byte mirror of .pi/prompts/. npm run mirror:check owns that drift gate. |
.pi/extensions/adw-cockpit/ |
Reference | Optional Pi TUI. Read-only by default. |
runtime/pi/ |
Experimental | Published Pi Durable 1.4.0 audit. NO-GO evidence, not a runtime. |
runtime/pi-source/ |
Experimental | Pinned source candidate accepted by S2; credential-free bridge and confinement policy. Not the product default. |
specs/ |
Reference | Historical implementation specifications. |
crates/switchyard-ui/ |
Experimental | Read-only Rune mission dashboard over the Rust ledger, in the ADW Cockpit layout. Its own workspace and gate; see its README. |
web/, tests/acceptance/ |
Deferred | Named in the plan. Not packages or commands in this checkout. |
| #42, #43, #44 | Deferred | Demand-gated. No implementation in the cleanup track. |
agents/ is git-ignored run output. Do not treat it as source.
adw_sdlc/ is frozen as of 2026-10-29: fixes only, and it will be retired.
runner-pi is part of that path. It is not the Pi Durable proof of concept
and not the native Rust runtime. The package is private and does not publish
a global CLI. Commands below run from adw_sdlc/ after npm ci, with Node
>=20.19. Node >=22.19 is required for the legacy Pi adapter.
The package default engine is ts (DEFAULT_ENGINE). --engine py fails
closed. Python compatibility is dropped; that default is not a promise that
the TypeScript engine remains the product.
A dry run does not look up the issue, load a runner, create run state, change files, call GitHub, or spend model credits:
cd adw_sdlc
npm run issue -- 123 \
--runner claude \
--dry-run \
--no-merge \
--test-cmd "npm run verify"The literal issue number 123 is safe in dry-run mode. A successful preview
only confirms that the local package and project pack load.
Warning
A live run can execute repository commands, edit files, post issue updates,
push a branch, open a pull request, watch CI, and spend provider credits.
Only target repositories you trust. Pass --test-cmd or ADW_TEST_CMD;
this repository's default test command is empty.
Live-run prerequisites (gh auth status, a clean dedicated checkout, approval
to spend credits, and a --no-merge budget example) are in the
package quick start, with the flag list and
managed-worktree commands. Historical evidence is in
adw_sdlc/PARITY.md and
adw_sdlc/MVP-READINESS.md.
| Runner | Recorded role on this frozen path |
|---|---|
| Claude | Default runner for the reference package. Real issue-to-PR evidence is recorded. |
| OpenCode | Adapter with recorded real issue-to-PR runs. |
| Codex | Adapter implemented. The live ledger records an authentication blocker. |
Pi (runner-pi) |
Frozen legacy adapter. Run babe0070 (issue #70, PR #73) is partial evidence only: it needed one scope fix from the owner. An unassisted Pi real-issue run is still owed. |
The reference pipeline is setup → classify → plan → implement → tests → resolve → e2e → review → patch → document → finalize → ci-fix → merge → report. Phase rules are in
orchestration. The orchestrator, not
the agent, owns Git and GitHub. Runner children do not receive GH_TOKEN in
normal phased mode.
--worktree still exists on this path. Further TypeScript managed-worktree
development is stopped (2026-10-29). New lifecycle work is S3. See
managed worktrees.
The ADW Cockpit is an optional
Pi terminal dashboard on the same
frozen path. Its views are read-only by default. /adw-run is the explicit
state-changing command: it asks for confirmation and delegates to the
orchestrator. Design notes are in .impeccable.md.
The wiki is an
OKF v0.1
bundle rooted at wiki/index.md. Validate it from
adw_sdlc/ with npm run wiki:check. Maintenance rules are in
wiki/contributing/wiki-maintenance.md.
wiki/index.md— knowledge map.adw_sdlc/README.md— TypeScript CLI and package reference.adw_sdlc/docs/UNIVERSAL.md— kernel and project-pack architecture for that package.adw_sdlc/HANDOVER.md— historical status notes for the TypeScript port.
Switchyard is available under the MIT License.