How rks works: request → merged PR.

One traceable path. Nothing happens off the record.

UX287⚡ Open Source — AGPL-3.0
1 / 15
Read this deck as text

How does RouteKit-shell work?

Slide 1 of 15

How rks works: request → merged PR.

One traceable path. Nothing happens off the record.

UX287⚡ Open Source — AGPL-3.0

Slide 2 of 15

Act I — The loop end-to-end

Three tiers in motion

The Dispatcher classifies your intent, launches exactly one Governor, and the Governor drives the Agents and MCP tools that do the real work.

Slide 3 of 15

Act I — The loop end-to-end

Intent → skill → one Governor

Ten slash-command skills

/pipeline, /build, /qa, /arch, /ship, /research, /ci … each a thin wrapper.

Each boots exactly one Governor

The Dispatcher never calls workflow tools directly — it routes.

Slide 4 of 15

Act II — The pipeline mechanism

One task fans into five gates

/pipeline takes one task description and runs it through the whole spine — PO → QA → ARCH → Build → Ship.

Slide 5 of 15

Act II — The pipeline mechanism

PO — define the work

Creates the story at draft, explores scope, and generates the targetFiles + acceptance criteria. Requirements first, code later.

Slide 6 of 15

Act II — The pipeline mechanism

QA — tests before code

Advances draft → ready and writes concrete test requirements — defined before a single line of implementation exists.

Slide 7 of 15

Act II — The pipeline mechanism

ARCH — the adversarial gate

Advances ready → arch-approved. It reads the actual source, runs a checklist, and can return needs-revision — rejecting bad work before Build ever starts.

Slide 8 of 15

Act II — The pipeline mechanism

Build — plan, review, exec
plan→
review→
exec

Apply on a branch, run the tests, and self-heal on failure — exec loops back and refines, then hands off to Ship. (The full internal chain is a leave-behind.)

Slide 9 of 15

Act II — The pipeline mechanism

Ship — close the loop

commit → PR → merge → integrated. The request ends as a real, merged artifact — not a suggestion.

Slide 10 of 15

Act III — The guarantees underneath

On-rail vs off-rail

On-rail: plan / exec with validators that check patterns exist before applying. Off-rail: token-gated direct edits for framework/dogfood code — after a mandatory ARCH gate. Either way, a blocked action is redirected, never dead-ended.

Slide 11 of 15

Act III — The guarantees underneath

Hooks — redirect, never dead-end

A risky raw op bounces off the hook gate and is deflected onto the governed path. One gesture stands in for the whole hook layer.

Slide 12 of 15

Act III — The guarantees underneath

The state machine

draft → ready → arch-approved → executing → executed → integrated → released. Every transition runs through one advancePhase() contract; the (committed) branch sits between executed and integrated.

Slide 13 of 15

Act III — The guarantees underneath

Your best model is the fallback, not the default.

Cheap first

Agents start on the small model; the stronger one is the configured fallback, not the entry point

Retry → resume

Invalid output retries on the same model first; a turn-exhausted run escalates by resuming the conversation, not restarting it

Cached

System prompt, tools, and conversation turns carry cache breakpoints

Slide 14 of 15

Act III — The guarantees underneath

Telemetry & cost, by default

1 event

Every operation emits a JSONL event with a correlationId

Cost

Every PR carries a token-cost block (green / yellow / red waste band)

/ci

Read-only autonomous CI inspection