Switchback SDLC
The Switchback SDK
The manifesto makes the case and the guide explains the mechanics. This is the part you can run: the twelve steps as Claude skills, the guardrails as hooks, the trail-keeping as headless routines wired into Linear and Slack, and the Actions that put them on a schedule. A methodology you can only read is a poster. This one installs, in layers.
switchback-sdk.zip
Four layers: 15 Claude skills (one per step, plus
/switchback
and
/gate
), 3 Claude Code hooks that enforce the guardrails, 4 headless routines that keep the trail through Linear and Slack, and 4 GitHub Actions workflows that schedule them — plus the CLAUDE.md terminology snippet and a README per layer.
Install
Install by layer — each works without the others, and the order below matches the guide’s 90-day plan. Skills on day one; hooks when the conventions settle; routines and Actions when the trail system is live:
unzip switchback-sdk.zip && cd switchback-sdk
# 1 · Skills — the steps as slash commands
cp -r skills/* your-project/.claude/skills/
cat CLAUDE-snippet.md >> your-project/CLAUDE.md
# 2 · Hooks — guardrails that don't depend on anyone remembering
cp hooks/scripts/* your-project/.claude/hooks/ && chmod +x your-project/.claude/hooks/*.sh
cp hooks/switchback.json your-project/.claude/ # edit substrate paths to match /identify
# merge hooks/settings-snippet.json into .claude/settings.json
# 3 · Routines + Actions — the trail-keeping on a schedule
cp -r routines your-project/.claude/switchback/
cp actions/*.yml your-project/.github/workflows/ # set LINEAR_API_KEY + Slack webhook secretsThen climb. Start every piece of work at /map, even small ones, and let the skills hand you to
each other — /draft will send you back to /breakdown when you hit a fork the spec doesn’t
cover, and /review will send duplicates back to /identify. The skills use bare step names
because the terminology is the point; if /map or /review collides with a skill you already
have, rename the directory and the name field in its SKILL.md.
For Linear and Slack the package speaks both dialects: interactive sessions use MCP (Linear’s
official server at https://mcp.linear.app/mcp, plus whatever Slack server you run), while the
headless routines fall back to the Linear GraphQL API and Slack incoming webhooks — one webhook
per channel keeps the permission surface minimal.
Why skills, and not a prompt
Switchback’s central claim is that AI belongs in different amounts at different steps — Map keeps its hands off the vision, Explore hands it the wheel, Review never lets it sign off. A single system prompt can’t hold that line, because the line moves with the step. Skills can: each one carries its step’s rules into the session that runs it.
The vocabulary becomes executable.
“Plateau,” “ledge,” “substrate,” “gate,” and “appetite” stop being words in an essay and become the names of things your agents check, produce, and refuse to skip. Saying
/reckon
in a project that runs this SDK means something specific, to people and agents alike.
Every skill knows its gate.
Work doesn’t leave a step because the conversation moved on; it leaves because the gate cleared, deliberately. The skills end by handing you the gate, not by congratulating you.
Every skill knows its switchbacks.
The turns are in the tooling: each skill names the steps it commonly cuts back to and routes what surfaced into its one home first. Drift control is built in, not remembered.
The terminology, as configuration
The zip includes CLAUDE-snippet.md — the Switchback vocabulary and the operating rules for
agents, ready to paste into a project’s CLAUDE.md. An excerpt:
### Operating rules for agents
- The story map and the product vision are human-owned. Brainstorm and
summarize research when asked; never invent, pad, or edit stories.
- Throwaway is a tool, not a failure. Label exploratory work as disposable
and do not gold-plate it.
- The spec in the ticket is the source of truth: build from it, and verify
against it. If the build needs to deviate, that's a switchback — surface
it, don't silently improvise.
- Nothing merges without human review. Pre-review diffs to focus human
attention; never treat your own review as the sign-off.
- When something surfaces mid-task (a new story, a spec gap, a duplicate
component), capture it before climbing on — that's what /switchback is for.With the snippet in place, the language holds across every session — an agent asked to “just add the feature” will still treat the ticket spec as the contract, still flag the fork instead of guessing, and still capture the story that surfaced mid-build.
Beyond skills: hooks, routines, and Actions
Skills only run when someone invokes them — a method that depends on invocation still depends on memory. The other three layers close that gap, and they split along the one rule the trail system runs on: automate the echo, never the judgment. Hooks enforce, routines record, Actions schedule — and every gate decision, review sign-off, and map edit stays a human signature.
Hooks — the guardrails
Deterministic checks wired into Claude Code itself. They fire on events, not on memory.
climb-context.sh · SessionStart
Every session opens knowing its altitude: the ticket parsed from the branch, the throwaway flag, and the reminder that the spec is the contract.
substrate-guard.sh · PreToolUse
On throwaway branches, edits to substrate paths are blocked with the reason: Explore reuses the substrate, it never modifies it. The change gets routed to /identify instead.
capture-check.sh · Stop
A session cannot end while uncaptured SWITCHBACK: markers sit in the diff. Drop the marker mid-build; the hook holds the door until /switchback routes it.
Never decides anything. Hooks block and explain; choosing the path stays with whoever is climbing.
Routines — the trail-keepers
Headless Claude runs (claude -p) that read Linear and the repo, compose the record, and write it home — ticket first, Slack echo second.
reckon-brief.md
The night before a Reckon: spec-vs-built, what the pass taught, open questions, and the rebuild ledger — posted to the ticket and echoed to #climbs. The meeting starts at the decision.
morning-digest.md
Opens the team day with what moved overnight, per climb: plateaus ready to react to first, failures never buried, silence when nothing happened.
stale-trail-sweep.md
Time-in-state thresholds per gate. A stalled ticket gets one context-rich nudge with the unsticking question — and a climb-level alarm if a third of the board is stale.
release-notes.md
On release: verifies the paper trail (human review + QA on record), writes the four-line note to #releases, links it on the ticket, and flags — never marks — the story as ready to go live on the map.
Never moves a state, passes a gate, or completes by deciding. When a routine hits a judgment call, it writes the question into the thread and stops.
Actions — the scheduler
GitHub Actions workflows: three put the routines on cron, one needs no agent at all.
switchback-morning-digest.yml
Cron at team morning. Checks out the repo so the digest can read overnight branch activity, then runs the routine headless.
switchback-stale-sweep.yml
Daily, half an hour before the digest, so stalls surface in the same morning read.
switchback-reckon-brief.yml
Evening cron plus manual dispatch — any ticket sitting in Reckoning gets its brief assembled overnight.
switchback-preview-trail.yml
Deployment success → two curls: preview URL pinned to the Linear ticket and echoed to #climbs. No Claude in this one, deliberately — a pure echo shouldn’t pay for inference.
Never auto-merges, auto-closes, or auto-passes anything. The workflows schedule record-keeping; the gates stay human.
How a turn travels through the layers
Mid-build, something surfaces. You drop a
SWITCHBACK:
marker and keep moving — the
hook
guarantees the session can’t end until it’s routed.
/switchback
(a
skill
) routes it: a log entry on the ticket, the story onto the map, the echo into the climb thread. That night, if the ticket reaches Reckoning, a
routine
assembles the brief — including that switchback — and an
Action
is what put the routine on the calendar. Four layers, one turn, zero meetings; and the only decision in the chain — keep or rebuild — is still made by people standing around the real build.
The skill catalog
Fifteen skills in five groups. Phase colors match the manifesto and the guide.
Phase A · Discover
Map the problem, fan out, decide.
/map
Facilitates story mapping. AI researches and summarizes; it is hard-ruled out of writing or editing the stories themselves — the vision stays human-owned.
Gate MVP stories mapped
/explore
Vibecodes rival, clickable, throwaway directions — genuinely different bets, isolated and labeled disposable, with a timebox it insists on.
Gate Multiple options illustrated
/shape
Drives the live decision session: reshapes options in real time as the room debates, records every kill and its reason, lands a direction at a fixed appetite.
Gate Bad ideas eliminated, one direction picked
Phase B · Frame
Substrate, spec, sequence — the quiet phase that makes everything after it fast.
/identify
Walks the chosen direction and names what becomes shared substrate — and what already exists, and what stays a one-off. Catches duplication before it sets in.
Gate Reusable parts identified
/breakdown
Drafts the spec as self-contained tickets that pass the competent-stranger test. The same artifact authors the build and verifies it in QA.
Gate Spec written and reviewed
/sequence
Maps the dependency graph: parallel lanes, the critical path, and file-footprint collisions — so parallel work stays parallel.
Gate Work parallelized
Phase C · Plateau Loop
Build, look, decide, climb.
/draft
Builds the walking skeleton end to end from the spec, on existing substrate, rough on purpose. Surprises are its real product — it lists them for Reckon.
Gate It runs
/refine
Turns design calls into live changes against the running build in minutes. Taste stays human; the hands get fast. Stops at the plateau, not at perfection.
Gate Polished to the plateau
/reckon
Preps the keep-or-rebuild call: spec-vs-built, what the pass taught, and the rebuild ledger — what the substrate keeps either way. The room decides; it never does.
Gate A call is made
/rebuild
Rebuilds clean from the updated spec with the lessons visibly applied, standing on the ledge. No copy-paste salvage of the layer Reckon rejected.
Gate The better pass stands
Phase D · Ship
The bar every change clears — continuously, not at the end.
/review
Pre-reviews the diff — spec drift, risk, regressions, DRY against substrate, missing tests — so human reading time goes to judgment. A human owns what merges.
Gate Signed off by a human
/qa
Verifies criterion-by-criterion against the same spec the build came from, at a depth sized to the change. Tests and docs gate the door; failures get reported verbatim.
Gate QA passed
/release
Ships the atomic change on its own cadence: checks the paper trail, runs the boring pipeline, drafts structured notes, records it. The substrate hardens with every deploy.
Gate Released and recorded
Cross-cutting
The connective tissue that makes the speed safe.
/switchback
Logs the turn the method is named for: captures what surfaced — a story, a spec gap, a duplicate, a pull-in — into its one home before the climb moves on. The drift-killer.
Gate Captured before you climb on
/gate
Runs the gate as a drift check, not a rubber stamp: deliverable against the bar, work against the map, artifact homes still true. Passing is a deliberate human act.
Gate Work matches what everyone thinks it is
New here? Start with the why.
The skills are the mechanics. The argument for why the climb is shaped this way — and what it asks of the people running it — lives in the manifesto and the operating guide.