Omniscio

Dev Pipeline

The opt-in skill that runs a whole software-development workflow on one task — worktree, investigate, plan, red-team, build, elegance pass, docs, git-prep — pausing at five approval gates, with each phase optional and configurable.

On this page

What it is

Dev Pipeline is an opt-in bundled skill that runs a full software-development workflow end to end on one task — investigate, plan, red-team, build (which starts by creating the run's worktree), code-elegance pass, docs, git-prep — pausing at five approval gates (one per phase 1–5; phase 6 finishes on its own) so you stay in control.

Off by default. Switch the Dev Pipeline on in the panel's Setup tab — that one switch is all it takes. Switching it on installs the skill into your ~/.claude/skills/dev-pipeline/ (this needs Omniscio's global skill-sync, on by default); switching it off removes it. No separate skill toggle, no restart. Because it installs into your global skills dir, /dev-pipeline works in every project, and — once config-sync is on — reaches your other AI CLIs too.

It also installs /ready-to-merge (into ~/.claude/skills/ready-to-merge/, same toggle). That's the merge-prep gate on its own: bring the branch up to date with the base branch only if a refusal names it as stale (one git merge <base>, never a rebase by default), run the repo's real lint/typecheck/tests, classify each red the way Phase 6 does, and — only if it's green for what the branch changed — stamp the SHA-bound ready-to-merge tag the git-guardrails push gate validates. The pipeline runs that same gate itself in Phase 6, so you never need /ready-to-merge mid-pipeline; it's there for the common case of a branch you built without the pipeline that still has to earn the tag before it can be pushed. Like the pipeline's own git-prep, it never pushes and never merges.

It also installs /subsystem-v2 and /behavior-preserving-refactor (same toggle) for a subsystem that has been patched into a tangle, where the question is whether to refactor it or start over. Rewrites usually fail on day one because the new version loses the lessons the old one learned the hard way — every bug fix, incident and special case — so /subsystem-v2 runs a rescue as two ordinary pipeline runs:

  • A Lessons run reads the subsystem in full, lists every lesson (defensive code, incidents, every commit in a recorded history range, existing tests), turns each into a check that runs against the current version, and then picks the route from evidence: refactor only, refactor then rebuild, clone v2 (copy the current version and refactor the copy), or a v2 built from scratch. Refactoring is the default; a v2 must show the core design is wrong and cannot be fixed step by step, and cloning wins over a fresh build whenever most of the current code is worth keeping.
  • A Route run does the refactor (with /behavior-preserving-refactor, keeping every lesson passing after each step) or builds the v2 behind the same entry point. Nobody is switched to a v2 until every lesson passes on it.
  • Every Route run locks its outside connections first: it lists every caller, message, stored table, setting and job that crosses the subsystem's edge, names a guard test that fails if outside code reaches past them, and — for a v2 — routes callers through one switch point and accounts for every fix the current version gets while the v2 is built.

Every stage ends with the skill's evidence checker, which checks the run's evidence file against git and real test reports and names each problem it finds — a file not fully read, a commit missing from the history, a test that was skipped or never ran, a reviewer with no recorded answer, or a v2 claimed finished while still switched off. It turns a skipped step into a visible, checkable claim; it cannot prove a test checks the right thing, which is why independent reviewers sample the lessons.

The flow

Invoke it in a Claude Code session with /dev-pipeline "<task>" (or "run the dev pipeline on X"). It drives six phases in order; phases 1–5 each STOP at a hard gate where you reply approve / feedback / abort:

Phase Ends at gate header
1 — Investigate & plan ## 🔍 🟢 Plan Ready
2 — Red team (10 lenses) + revised plan ## ⚔️ 🟢 Red Team Complete
3 — Build & verify ## 🔨 🟢 Build Complete
4 — Code elegance (refactor in footprint) ## 💎 🟢 Elegance Pass Complete
5 — Docs ## 📝 🟢 Docs Complete
6 — Git prep (branch ready) ## 🚀 🟢 Ready to Merge (no gate — finishes)

Every gate report reads the same way from one phase to the next — a one-line headline, then a few ## section headers (one sentence per bullet, like the final "Ready to Merge" report), then the standard approve / feedback / abort footer (the "Ready to Merge" report is the exception: no headline, and a one-line bottom summary instead of the footer). The header's status dot triages how much input the gate needs from you: 🟢 nothing (safe to just approve), 🟡 a question to answer, 🔴 a serious call or a blocker — and a non-green dot swaps in an honest title (e.g. ## 🔍 🟡 Plan Not Ready — One Question), so a green header always means "nothing needed". In the chat, the little pipeline-stepper widget under each report lights the current step to match — green, amber, or red. A report still counts when the engine invents its own words after the last | — a non-Claude run has been seen to print [DEV-PIPELINE | GATE 3 | PHASE=3 | STATUS=GREEN | …] — as long as the message carries its real gate header: it lights the stepper and offers the buttons, and it reads as waiting for you, never as auto-approved, so nothing advances a run on an invented verdict.

By default each gate is a real, observable stop — there is no hands-free seam. (Opt-in autonomous mode — see below — self-advances the gates and stops only when something genuinely needs you.) In Phase 6 the pipeline runs one authoritative, self-contained verification pass — it runs the project's full lint/typecheck/tests/build in the same session, and classifies each failure: a failure already red on the base branch is pre-existing debt and does not block, while a regression this branch introduced does. A check the machine itself refuses to run — the box's admission gate stopping a heavy run, for example — is reported as a refusal, never as a red, and never withholds the finish; the run says which check never ran. When every check is green or classified pre-existing it stamps the branch's SHA-bound ready-to-merge tag; the pipeline emits ## 🚀 🟢 Ready to Merge only once that tag is confirmed on the current commit — so the header always means a genuinely-tagged branch (if it can't be tagged, it reports a 🔴 not-ready status instead). In a repo whose profile names a mint, the pipeline never pushes or merges on its own — even in autonomous mode. In a repo with no mint there is no auto-lander to bring the branch home, so Phase 6 finishes by merging the branch into that repo's own main copy, locally: only after the check pass is green (or after a refusal the machine itself made, which the merge line states as checks NOT RUN), fast-forwarding when it can, aborted on a conflict, and never a force, a rebase of the main copy, or a push. A repo that lands its work through pull requests can choose that ending instead. When the repo's own committed profile (on the base branch, so a branch's own edit can never switch it on) names the pull-request strategy, Phase 6 stamps the branch exactly as above and then offers a pull request: it asks once before anything leaves the machine, pushes only the run branch, never with force and never the base branch, and opens a draft pull request for it — ready for review only if the developer or the repo asks. A missing GitHub CLI, a missing remote, or a refused push never strands the branch: it stays stamped, the run falls back to that same checked local merge so the work still reaches the repo's own main copy, and the close-out names in one plain sentence which refusal it fell back from and what was missing. The pipeline never merges the pull request. Every other repo keeps the local-merge finish it has today, and a repo that declares the tag strategy writes its stamp and then makes that same checked local merge — a plain local tag is read by nothing the pipeline ships, so the stamp records what was verified and the merge carries the work home. An opt-in measured finish can replace the agent's word with checks the finish runs itself — see How a run finishes below and the ready checklist.

Right-sized rigor. The Phase-2 red team always applies 10 lenses, but verdict DEPTH scales to the task: a docs-only or tiny mechanical change gets terse one-line verdicts, not paragraphs of hypothetical risk, while anything sizable, risky, or novel gets full depth — the revised plan is always full quality either way.

Refactors, not patches. The code-elegance phase does more than tidy: inside the files the change edits, it restructures the code the change touched — pulling out a function, merging copies, folding a one-off special case back into the general path — as long as behaviour stays the same and a test covers the moved code first. Anything outside those files is only flagged, and every flag must say why from a short fixed list ("outside the changed files", "touches money, security or data code", "would change behaviour", "no test can cover it", "needs your call"); a flag with no reason stops the run. The two standards steps ask the same question at both ends: Patch or refactor? before building (a file fixed again and again, a fix that adds a flag or a second copy, or logic that must change in several places means restructure first), and Clean fix, not a patch before merging (every patch shape in the finished change is either refactored or given one of those reasons, or the merge is held).

A big new feature gets a PRD first. Before planning a big new feature — brand-new, and adding a new screen, panel or multi-part system — Phase 1 runs a short PRD Studio interview right in the same chat — you answer a few questions per step, Tech Stack is skipped because the code already exists, and the plan, its "done when" list and the feature contract are then built from the finished PRD. A bug fix, a tweak, a refactor or an addition to something that already exists never runs one; when it is unclear, the pipeline asks you one yes/no question first, and you can always say "run a PRD" or "skip the PRD". A hands-free run has nobody to interview, so it skips the step and says so. The PRD becomes one of the run's documents — a PRD button on its Agent Board card — and it is linked both ways to the run's phase-by-phase task list: every requirement has a short id (R1, R2, …), every task it drives names its requirement, any requirement left out is listed with a reason, and the PRD ends with a delivery plan. The Plan Ready report always carries one line saying whether a PRD ran and why.

New contracts and visions are for big new features only. The same "big new feature" test decides whether a run writes a NEW contract (the list of promises a feature must keep) and, when its area has none that fits, a short vision (what the area is for). Everything smaller — a fix, a new setting or button, a rule on something that already exists — adds its promises to the area's existing contract instead of starting a new file. Every run reads its area's vision first, and any new contract or vision is shown to you at the plan gate before code is written.

A UI change arrives with a picture of itself. When the work adds or moves a control — a new screen, panel, row, button, dialog, menu item, layout move, or a visual state — Phase 1 also renders the change before the Plan gate: one page showing the same screen twice, labelled before (today) and after (proposed), built from the real component and the repo's design language. It rides the Plan Ready report as a UI Render section carrying the link (published to Shares, so it opens on your phone). A copy, label, icon, colour or spacing tweak that adds no control and moves no layout skips it, as does a non-visual change — and every skip is stated in one line rather than passed over. The render is best-effort and can never block a run, it is a labelled mock rather than a screenshot (at plan time nothing is built yet), and it carries placeholder content rather than any real data. The finished interface's real before/after stays the post-build screenshot path's job, which runs once the UI exists.

When Omniscio creates a workspace for a session, it remembers that workspace automatically, including on a new installation using only Codex. You do not need to choose its folder or add a Claude account for workspace tracking. An existing workspace choice stays in place.

For older sessions whose workspace was not remembered, Omniscio can recover it when there is exactly one owned workspace and its repository and branch still match. It leaves ambiguous or missing workspaces alone. This recovery makes the run visible; your approval settings still decide which gates may advance. Turning on automatic Plan approval is not a remedy for a missing run.

Where to find it

Running inside Omniscio

One-click gate replies. When a gate is waiting on you — the plan gate (manual by default), a gate you switched off auto-approve, or a HOLD — Omniscio shows Approve and Abort buttons right above the reply box. Approve sends approved; Abort asks you to confirm, then sends abort (the run stops and its work is kept). To give feedback, just type it in the reply box — there is no separate Feedback button. The small arrow on Approve opens a menu headed with the gate you are at and the repository it belongs to, and every row states its own scope: This run only — every remaining gate approves and tells this run to approve its own remaining gates (it still stops for real decisions, and nothing is saved); Every run — this gate only, in this repo and Every run — every gate, in this repo save a choice that applies to runs in that repository alone, leaving every other repository stopping; Every run — this gate only, all repos saves that one gate for every repository and leaves every other gate on its own setting; and Every run — every gate, all repos turns on auto-approve everywhere. A saved row offers Undo for exactly the scope it changed, and the all-repos row shows a check while it is on and turns itself off. A repo row is saved under the repository's main checkout, so a worktree and its main checkout share one choice, and a repository-scoped choice never touches gates you defined yourself in phases.json. The two repo rows are hidden when Omniscio cannot tell which repository the session is in, and on a step that can never stop at all — an AI Code Review step or the ready-to-merge gate — only the this-run row is offered. The bar answers the same keys as every other approval card: Enter or the Approve key (Y by default) approves, and the Decline key (X) is Abort, still behind its confirm — and it wears the same cyan card and green/red buttons as the permission and approval cards. Opening a session that is waiting at a gate puts the cursor on the conversation, so the keys work straight away (Enter works even while the session's sidebar row still has focus from the click). The buttons appear only while the session is actually waiting on you for that gate, never while a run moves on its own, and disappear once you answer (see the repo's pipeline-gate-reply-buttons-contract.md).

Inside Omniscio, completing a gate auto-advances to the next phase and the run shows up on the agent status board — Omniscio reads the skill's .claude/pipeline/state.md and the byte-exact gate headers above. Outside Omniscio the workflow is identical; you approve each gate yourself. (A conformance test at every merge gate locks those markers to Omniscio's parsers, so the integration can't silently drift.)

A parked run says why. On the Runs screen a parked run shows, in one muted line under its name, the first reason it is parked: what its session is doing right now (in the middle of a turn, paused by you, waiting for account capacity), else what the auto-advancer recorded when it held the gate, else what the gate itself says — quoting the agent's own words when it wrote a sentence where a gate belongs. The same reasons come back from GET /dev-pipeline/runs in each run's declines, and a parked run's list is never empty. A run that is not parked shows only what the advancer recorded, and a finished run shows none. See the repo's dev-pipeline-panel-contract.md (in .claude/memory/contracts/) invariant a-parked-run-says-why.

Six robustness layers keep real-world runs from stalling or mis-advancing:

  • A bookkeeping slip can't cost you the whole run. The run's state.md records which gate it is parked at, and the agent is supposed to move that label forward at every phase boundary. Agents forget. When the label is left BEHIND — say it still reads "waiting at the plan gate" while the agent has just posted its Red Team report — every later gate used to be checked against that stale label, match nothing, and quietly refuse to advance, for the rest of the run: one missed update and you hand-approve every remaining gate (observed live, 2026-08-25, and again 2026-09-20 at the 🚦 Standards Check). Omniscio now advances the gate the agent ACTUALLY finished, provided the run's own history proves it genuinely reported every earlier gate — the same in-session lineage proof the engine-agnostic fallback uses. Manual gates stay manual, with one timed exception: a gate you left manual — the plan gate by default, or any gate you switched off auto-approve — is only stepped past after a real person replied following that gate's report, unless that gate's auto-continue timer carries it on: 30 minutes by default on Red Team / Build / Elegance / Docs, and off (0) on the plan gate, whose wait you can set yourself. Omniscio's own automatic messages never count as a person. Advancing only ever moves FORWARD, never past a hand-back or any other deliberate stop, and every existing veto still applies. Every gate you have configured counts, custom ones included — the reserve covers the 🧭 AI Code Review and the 🚦/🔬 Standards gates exactly as it covers the six numbered ones, so a run parked at a custom gate is picked up rather than stranded. The reserve also reads the run's own closing line: a run that has already reached its final gate is treated as finished and left alone, instead of being re-judged every few minutes against a gate it moved past. Both outcomes show in the log: a rescue says it advanced a gate the state file was still behind on, and a refusal names both the stale label and the real gate. See the repo's pipeline-auto-advance-contract.md (in .claude/memory/contracts/) invariant stale-gate-token-backstop.
  • Cloud runs keep advancing. A cloud session's agent stops at the end of every turn, so an auto-approval often arrives with nobody listening. Omniscio then restarts the session to deliver it (the same way your own reply would), instead of dropping it and leaving the run showing "running" until a restart pushed it into your inbox. If the restart can't happen (for example every account is out of capacity), the run waits and is never approved twice for the same gate. Away Mode auto-replies and the Auto-approve plans setting deliver the same way. See the repo's pipeline-auto-advance-map.md (in .claude/memory/) step 5.
  • Label forgiveness. Agents hand-write state.md and sometimes invent label variants (PHASE_5_VERIFY, GATE_3_LOCAL_VERIFY (…), DONE — … — all observed live). Omniscio normalizes number-prefixed variants to the canonical labels so auto-advance and the panels keep working; a genuinely unknown label stays raw and never advances anything. A label that only says nothing is awaited (nothing — build in progress, n/a, not waiting, no gate) counts as no label at all, so the gate is judged on the verdict marker in the agent's report as if the label read none — a sentence that names who the run is waiting on (FOREMAN_APPROVAL, "Not a gate — … blocked") is still a deliberate stop and never advances. Advancing still requires the byte-exact gate evidence in the agent's message (two-factor), so forgiveness can't cause a wrong approval. See the repo's pipeline-auto-advance-invariants-2-contract.md invariant idle-word-awaiting-decides-as-none.
  • Question-widget veto. A gate report whose body asks you a real question is NEVER auto-approved — even if the agent mistakenly printed an AUTO-APPROVE: OK marker beside it. Omniscio asks its canonical question-widget parser (every widget format it can render), fences excluded, so quoted examples don't false-hold. One thing it does NOT hold on: a routine "approve to proceed?" the agent tucks into its own Plain Speak overlay card (below the report) — that tail is overlay metadata Omniscio strips before the check, so a green gate that just repeated its approve/feedback/abort footer as a card widget still auto-advances rather than stranding on a question nobody asked. A genuine decision rides the report body (or a 🟡/🔴 header), which still holds.
  • A HOLD always holds. If a gate report says AUTO-APPROVE: HOLD for a gate anywhere in the message, Omniscio never auto-approves that gate — not even when an AUTO-APPROVE: OK for the same gate turns up further down (a recap, an example, the Plain Speak card). Only when every marker is an OK does the last one decide. This holds on every path, including the backstops that rescue a run whose state.md token is missing or left behind. Markers and headers inside a fenced code block are illustrations and never count, while a gate header the agent wrapped in backticks still counts as its real header — so a quoted example can't approve a run and a backticked 🔴 header still stops one. See the repo's pipeline-auto-advance-invariants-1-contract.md (in .claude/memory/contracts/) invariants the-marker-is-primary and a-quoted-marker-is-never-the-verdict.
  • Any AI engine — even one that skips the state file. Auto-advance is not Claude-only: cursor/grok, codex, gemini and the other non-Claude engines advance their gates too, with the "approved" delivered through the engine-aware sender (a one-shot engine has no live stdin like Claude). And because some non-Claude agents don't reliably write state.md — and a cloud or SSH session writes it on the remote machine, where Omniscio can't read it — Omniscio keeps a loop-safe state.md-free fallback for both — it advances a gate (the numbered gates and the 🚦 Standards Check / 🔬 Standards Audit / opted-in custom gates alike) on the trailing AUTO-APPROVE: OK marker ONLY when the session's own history proves it genuinely reported every earlier numbered gate in its own prior turns (the in-session lineage). If you set the Plan gate to auto-approve, the plan report is not demanded (since 2026-10-12): a run that approved its own plan — a spawned --auto fix wave never posts one — used to be refused at every later gate. Now it advances, and the plan gate itself auto-approves on a cloud session too; with no plan report behind it, the gate report must carry that gate's own 🟢 header. With the Plan gate on manual nothing changed. Since 2026-10-13 a cloud or SSH run is read like a local one: at the end of each of its turns Omniscio reads the run's state.md off the remote machine and keeps a copy on this computer, so the run shows on the Dev Pipeline panel and its gates advance exactly as a local run's do — the fallback above now covers only a run whose remote machine could not be read. Every time a cloud run does NOT advance (its Plan gate is manual, it reached the end, it handed back, or its machine could not be read) the reason is recorded, so a parked cloud run never sits there unexplained. Since 2026-10-15 a cloud turn is wrapped up only after that read: the connection to the cloud machine closes a moment after each turn, and Omniscio used to wrap the turn up at that instant, before it had read the run's state.md, so some cloud gates were judged with no state and held. The wrap-up now finishes first (the closing connection only backs it up), a Plan, last-gate or HOLD report is left alone once the cloud machine has answered — exactly as for a local run — and an approval that could not be delivered to the cloud session leaves a row on the panel saying so ("The pipeline's message to this session was not delivered. If the run does not move, reply to the session to continue.") instead of vanishing (invariants a-cloud-exit-leaves-the-conclusion-to-the-result-chain and a-send-that-ends-undelivered-leaves-a-row in pipeline-auto-advance-invariants-1-contract.md). A session merely quoting a marker has no such lineage, so it can never self-approve; a single injected turn can't invent prior turns. See the repo's pipeline-auto-advance-contract.md (in .claude/memory/contracts/) invariant non-claude-engines-auto-advance.
  • A non-Claude engine gets the workflow handed to it. Claude (and the Claude-compatible vendors like DeepSeek / Kimi / GLM) runs the pipeline from the installed /dev-pipeline skill. A skill-less engine — Codex, Gemini, OpenCode, Cursor and the like — can't invoke that skill, so on a software-development session in an enabled repo Omniscio injects a compact portable brief of the whole workflow (the six phases, the five stop-and-wait gates, and the exact gate markers) straight into that engine's own instructions. It's best-effort — a leaner model follows it less precisely — but a Codex run now drives the same gated pipeline and lights up the panel like a Claude run. The brief also carries the skill's guidance for verifying under a per-command time limit — offload heavy checks (a --cloud wrapper) off the engine's clock, and treat a check that can't finish in time (a timeout / missing toolchain) as an environment caveat that keeps the gate green rather than a stop — so a time-limited engine like Codex no longer strands the Build gate on a lint that timed out (the fix for a live 2026-08-15 go-live wave). Claude is unaffected: the brief is only ever sent to a non-Claude engine.
  • A missing to-do tool never stalls a run. Some harnesses don't expose TodoWrite; the run notes that and carries its six-step backbone in the state file instead.
  • A stranded gate gets picked back up. Auto-advance normally happens the instant a phase reports done. If that instant is ever missed — a rare timing edge, or Omniscio restarting at exactly the wrong moment — a periodic background check finds any run still parked at a gate whose latest report carries a valid AUTO-APPROVE: OK and advances it for you. It's a backstop, not a competitor to the instant path: it only touches gates you've left on auto-approve, only after one has sat parked a few minutes, and only when nothing newer from you is waiting — so it can never race the normal path, re-approve over you, or double-spend a turn. It also stays on your side when the computer is busy: it used to stand down completely under heavy load, which could leave a valid gate parked for the whole busy stretch — now it just raises the bar (rescuing a gate that's been stuck about fifteen minutes, one at a time) instead of standing down, so a genuinely stuck gate still gets cleared mid-crunch. See the repo's pipeline-auto-advance-contract.md (in .claude/memory/contracts/) invariant level-triggered-reconcile-backstop. It also never mistakes a busy session for a broken one: a session that is mid-turn, or waiting on a permission prompt, is skipped rather than counted as a failed pass, so a working session can no longer raise a false "auto-advance may be stalled" notice. See invariant a-working-session-is-not-a-failed-pass.
  • A run nobody is driving gets one inbox card — a busy one never does. If a run's current phase has not checked in AND its agent has produced no output for an hour, you get one "Pipeline run stalled in …" card naming the branch, how long the phase has gone without a check-in, and how long the agent has been silent — naming that agent's session as a link that opens it (added 2026-10-09: the card used to name only the branch, so you had to hunt for the stuck session) — with one click to the Dev Pipeline panel. A long phase on its own is not a stall: an agent still working through a slow Build keeps the card away, and a card already showing withdraws itself when the RUN moves — the phase checks in, the run finishes or its branch lands (since 2026-11-11 that includes a run on a cloud computer, whose work lands under the session's own ship branch cloud/ready-<session>-<sha> and not under the run's branch, so a landed cloud run no longer raised a card an hour after its agent went quiet), or a person takes it over — not merely because the agent spoke: a session that is alive but has left the run behind keeps its one card instead of re-raising it every quiet hour. It stays quiet for a run waiting on a gate only you can clear (the plan gate, or one you set to manual), and — since 2026-10-14 — for a run whose agent has finished its turn and handed it to you: its session is in your Needs-You list with a message for you (a question, a held gate, or a plain report), so it is your move, not a stall. Replying to that session lets the alarm watch the run again; an agent whose turn failed (an error, a timeout) still raises the card. Since 2026-10-15 it also stays quiet for a run whose branch is tagged ready at its latest commit and waiting in the auto-lander's queue — the work is done and the lander owns it, so a branch that then never lands is reported by the lander's own cards with the real reason. Where the lander is switched off, paused or observe-only for that project, or the tag is held or withdrawn, the alarm still watches the run. Since 2026-10-16 a run whose session has been archived — by you, by the Overseer that started it, or by the agent itself — raises nothing: archiving closes the run. Since 2026-10-26 a run whose session you stopped raises nothing either: a person's Stop is a deliberate close even though it does not archive the session, and a card already showing comes down on the next tick. The alarm reads that off the same signal a peer message uses to refuse a stopped session, so it and the app can never disagree about whether a person ended it. A session a machine closed — a reaper, a crash, a failed start you cancelled — still raises, because that close names no author. A card left open from before an app restart is also withdrawn once its run no longer qualifies, and a stall card you dismissed is not brought back by a restart — only by the same run stalling again after it had moved. Since 2026-10-25 a restart no longer re-bases the alarm's clock: while the app is re-taking its sessions it stamps activity times on rows it is merely re-filing, and those stamps are bookkeeping rather than output, so an abandoned run is dated by its own check-in record and cards on its own schedule instead of a batch of them crossing the line together an hour after every restart. A session the app actually resumed still counts as a hand-off, so a long phase that is being picked back up is never carded in the first minutes. See the repo's pipeline-stall-alert-contract.md (in .claude/memory/contracts/).

Companion toggles (Omniscio)

Turning the Dev Pipeline on reveals five optional, independent companions under the same Settings → Features → "Dev Pipeline" row — which is the panel's master switch, not a second one — plus the plan-gate sub-option and the same set on the panel's All settings screen (see the repo's dev-pipeline-companions-contract.md in .claude/memory/contracts/):

  • Gate auto-approval (per phase) — for EACH approval step (Plan · Red Team · Build · Elegance · Docs, the Scout, both standards steps and your own custom steps) a toggle for whether Omniscio clears it itself or always asks you, plus a select-all master. Each toggle saves your own stop choice (stops in your personal pipeline file); a team pack's ask stays ask and only Plan can be loosened by you. Your earlier per-gate settings keep deciding until your first change, which copies them over. Defaults preserve the prior behavior: the Plan gate asks you, while Red Team / Build / Elegance / Docs auto-clear the moment a phase reports done. A gate that asks a question or reports a blocker is never auto-approved, whatever its toggle. What makes the Plan gate and an AI Code Review step ask you (since 2026-10-10): only the agent's "short HOLD list" — the work spends money, deletes or migrates data, touches security, privacy, sign-in or a third-party package, is hard to undo, needs a real either-or choice from you, or its intent is genuinely unclear. Everything else goes through on its own and is written up in the report for you to read later: a new or changed feature contract (approving the plan, automatically or by you, is its sign-off), a small scope call the agent settled, a plan or code the reviewers' fixes changed, or a plan bigger than expected but easy to undo. The same controls appear in Settings → Features AND the Dev Pipeline panel — both bind the one resolved map. A separate timer, not a toggle: a gate you left on ask is carried on after its auto-continue wait has passed unanswered — 30 minutes by default on Red Team / Build / Elegance / Docs, off on the plan gate — and it never carries a gate that asked a question, opened 🟡/🔴 or carried a HOLD. There is no Settings control for it; it is backed by pipelineGateAutoContinue, resolved by resolveGateAutoContinue, and setting a gate to 0 keeps it off explicitly. The Check every step preset writes 0 for all five gates, so the strictest preset really does wait for you at every step; the other two presets leave the waits exactly as they were. The Setup row names a preset only while every gate that is set to ask also has a wait of 0 — otherwise it says Custom, so the sentence it shows is never a promise the pipeline does not keep (an install that picked the preset before this rule keeps its 30-minute waits until it picks the preset again).
  • A run cannot skip a phase and still ship (since 2026-11-20). When an agent session is running the Dev Pipeline, its branch cannot leave the computer until every phase the run owes has reported to the app. The git push that opens the pull request asks the app first, and is refused — naming the phase still owed, or saying the run was never started with the app — until the agent runs the missing phase. The ready-to-merge tag step asks the same question and refuses the same way. It works for every AI engine, because git itself runs the check. A pipeline step you genuinely do not want is switched off in the Dev Pipeline panel's Setup tab; an agent cannot wave one through by saying it did not run. Details: phase-checkin-contract.md (the-push-asks-the-judge, a-session-holding-a-run-is-judged).
  • Remind every session to use the pipeline (devPipelineReminderEnabled, default OFF) — writes a short, self-gating note into each spawned session's .claude/amc-instructions.md: follow /dev-pipeline IF this session is doing software development, otherwise ignore it. Skips the in-app helper bots (Ask Omniscio / Ask-page / Automation Helper) and is independent of the Default Agent Instructions feature.
  • Add the pipeline quick replies (devPipelineQuickRepliesEnabled, shipped default OFF) — seeds the "Open a Pull Request" and "Package My Work Into PRs" quick replies if they are missing, grouped inside a "Dev Pipeline" FOLDER placed at the top of your quick-reply list (so they stay tidy and, being a folder, out of the composer picker's first-pop-up view). "Open a Pull Request" is the contributor path — finalize ONE worktree, run the gate, rebase, open the PR, stop — and does NOT auto-submit: opening a PR is outward-facing, so it lands in the composer for you to read and edit before it sends. "Package My Work Into PRs" is a bare /dev-create-pr, the whole-checkout path: the repository-owned dev-create-pr skill behind it reads everything your local trunk has that the shared trunk does not, subtracts what already landed or is already in an open PR, and slices the rest into PRs sized on BOTH ends — one AREA of the codebase per PR, reviewable in about fifteen minutes, revertible on its own — then stops for your approval before opening anything. That skill is developed and used inside the Omniscio repository, so this reply works only in a session started inside it. Turning the toggle off never deletes quick replies you already have. The companion rewrites or removes only untouched originals it shipped: an untouched old "Package My Work Into PRs" prompt is upgraded once to the one-line command, and untouched copies of the retired "Full Local Git" and "Worktree Cleanup Analysis" replies (they called the retired merge-all-ready and worktree-cleanup skills) are removed — anything you edited yourself is left alone. If you already have both replies no folder is created. When they arrive: on every launch, not only when you flip the toggle. Omniscio checks the bundle at startup, so a reply ADDED to it in a later release still reaches you even though your toggle went on months ago. Each reply is offered exactly ONCE (recorded in devPipelineQuickRepliesSeeded), so one you delete never comes back on the next launch. Switching the toggle off and on again is the deliberate way to ask for the whole set afresh. The dev-create-pr skill behind "Package My Work Into PRs" carries rules that are load-bearing, not boilerplate. It may never reset / rebase / amend your local trunk or touch a worktree it did not create (the unlanded work often lives ONLY there), it slices in NEW worktrees and proves your trunk still points where it did, it bails out and says so if the repo does not take work by pull request, it measures the delta and comes back with a strategy rather than grinding through an oversized one, it de-duplicates against open PRs by CONTENT rather than sha (a landed PR is a cherry-pick with a NEW sha, so sha matching silently re-publishes), it scans for secrets before any push, and it builds each cut branch standing alone to catch the classic split failure — two PRs that each pass on the author's machine, one of which will not compile on the trunk without its sibling. Each rule maps to a specific failure, so none is trimmed as obvious. The set is landing-only by design. The skill already runs Red Team (Phase 2) and Full Documentation (Phase 5) itself, so a hand-fired second copy in everyone's picker would be duplicate surface rather than a shortcut. Red Team stays a normal seeded default in seed-defaults.ts, the single editable copy the Phase-2 parity test pins.
  • Add the workflow auto-replies (devPipelineAutoRepliesEnabled, default OFF) — seeds a small set of preset auto-reply rules for the pipeline's common handoffs (e.g. answering a red-team completion with "proceed"). Two-way by stable id: turning it off removes exactly the presets it added, never rules you wrote.
  • Write a durable note into the repo (devPipelineFileNoteEnabled, default OFF) — this one edits a git-tracked file in your own repository, which is why it is called out here: reconcileDevPipelineFileNote splices a marker-bracketed managed block (<!-- AMC-DEV-PIPELINE:note:start … --> … <!-- AMC-DEV-PIPELINE:note:end -->) into the repo's OWN CLAUDE.md — else AGENTS.md, else it creates CLAUDE.md — for every repo enabled in the per-repo selection. Unlike the ephemeral reminder above, the note persists in a file you see and commit, so it also reaches sessions Omniscio did not spawn. Written/removed at Claude session spawn: two-way (turning it off strips the block again), idempotent, atomic, fail-open, and independent of devPipelineReminderEnabled. This repo's own CLAUDE.md carries such a block.

How it behaves

The build checklist + definition of done

Before it builds, each run pins down what "done" means — and then tracks the work so nothing slips:

  • Definition of done — at the plan gate the run lists the concrete "Done when …" outcomes for the task; approving the plan approves them. In Phase 3 each one must be met with real evidence (a test or an observed result) before the build gate can go green — a passing test suite isn't the same as the thing you asked for being finished.
  • Implementation checklist — alongside those outcomes, Phase 1 breaks the plan into a granular, itemized checklist of every build task and shows it at the plan gate as a ## Build Checklist, then mirrors it into the session's to-do list so it appears on the agent status board and ticks off live as the build runs. In Phase 3 every item must end up checked off — or explicitly deferred with a reason — before the build gate goes green; an item left unfinished blocks it, exactly like an unmet outcome. A long, multi-part build can't quietly forget a requirement.

The Scout Report — the first step, before any plan

You don't read the code, so the agent is your scout. Before the plan narrows the work to one bug or one feature, every run — Quick Lane included — starts with a 🔭 Scout Report on the health of the code the task lands in and the code around it:

  • It reads the rules first. The repo's standards file (.claude/dev-pipeline/standards.md, else the skill's bundled general one) and its coding-conventions doc, so "breaks a house rule" is judged against what this repo asks for, not general taste. Planning reuses that read instead of repeating it.
  • What it looks for: a system that has become hard to reason about, patch on patch, duplicated or dead code, a refactor the change really needs first, broken house rules (code comments, long functions, deep nesting, magic values), and anything else a senior engineer would warn a non-technical owner about.
  • A design verdict, every run: before reading the code, the agent writes what this area is for; then it says whether a senior engineer would build it this way today, and gives one of three verdicts — Sound, Showing wear, or Needs a rethink — with the fact behind it. "Needs a rethink" means a fresh build would be different in kind (who owns it, how its data is shaped, how it flows), not just tidier. It needs no history of earlier repairs, so a brand-new feature on the wrong foundation counts. Quick fixes get a one-line verdict too.
  • Each finding takes one road: the agent fixes it itself when it is small, safe and inside the change; it asks you "rethink first?" when the verdict is Needs a rethink or a refactor must come first; or it flags it so nothing it saw stays hidden.
  • What you see: the design verdict first, then at most five items, worst first, in plain words — what it is, where, what it costs you, what the agent recommends, and how big it is. Healthy code is one line saying so. Anything new spotted while building is added, and the final report repeats every open item.
  • When it stops: a clean or flag-only Scout auto-approves and the run goes straight into planning. Only a "rethink first?" question stops it for you — and it stops every run, hands-off and crew runs included (a crew lead passes the question up to you rather than answering it). You answer with a letter: patch it for now, rethink first, or it's fine. Clicking Approve without a letter isn't an answer, so it asks again.
  • Asked once per folder: your answer to a Needs-a-rethink question is saved in the same record the Step Back uses, so neither step asks you about that folder again for 30 days. If the record can't be read, the Scout still asks and says a later run may ask again.
  • The switch — Dev Pipeline panel → Setup → AI code review card → Scout Report before every change (the devPipelineScoutEnabled setting, on by default). Off, the step shows as switched off and runs already under way stop owing it. Its auto-approve toggle sits with the other steps' toggles and follows the Setup presets. An operator can remove it entirely with DEV_PIPELINE_DISABLE_BUNDLED_SCOUT=1.
  • Cost: a little extra agent reading on every run; the switch is there if you don't want it.

The Step Back — a whole-system look before every change

A task hands the agent one spot to fix, and patching that spot over and over is how a system ends up patched to death. So before it writes the plan, every run — Quick Lane included — steps back and looks at the whole system the change sits in:

  • What it writes down (in step-back.md, shown in the plan report as ## Step Back): what the system is for, written before reading its code; the whole flow, naming what it read beyond the spot that broke; where else the same cause lives; how often these files were bug-fixed in the last 14 days (counted by the churn checker); why it was built this way; and whether it would be built this way today.
  • Its verdict: narrow fix is right (a local fault in a sound design), fix it deeper (the real cause is a layer up, so the plan fixes it there), or system unsound — which needs the rule the design keeps breaking, two earlier fixes of the same fault by commit, and what it costs today. Evidence that complete always means system unsound.
  • The switch — Dev Pipeline panel → Setup → AI code review card → Step Back before every change: Off, Look & report (show the verdict, never stop), or Look & stop (the default). It takes effect in runs already under way. A run that cannot read it looks and reports; a run outside Omniscio looks and reports, and DEV_PIPELINE_DISABLE_STEP_BACK=1 turns it off.
  • On system unsound with Look & stop, the run stops at the plan with the evidence and asks once: patch it for now, redesign it (through /subsystem-v2), or it is not unsound — in every mode, autonomous and crew runs included. The pipeline never redesigns anything on its own.
  • Asked once per system. Your answer is kept for 30 days in the devPipelineSystemRulings setting, keyed by repo and folder, so later runs on that code follow it. While a question is open, other runs on the same code carry on with the narrow fix instead of asking again; an unanswered question is asked again after 3 days. When you choose redesign, the run that asked tells every session working in that code.
  • How it was tuned: ten past bug fixes judged blind and checked by hand against what actually happened — the calibration record, with how to re-run it, is kept with the Dev Pipeline skill's reference notes (phases/reference/1-step-back-calibration.md).

Which branch it treats as the main copy

Every step that compares against or merges in the repo's main copy — the git-prep overlap check, the Quick Lane measurement and the ready-to-merge gate — asks one helper which branch that is, so the pipeline works the same in a repo whose main branch is main, master or develop:

  • The run's own answer wins. At the start of a run the pipeline asks Omniscio's repo profile how this repo runs and records that answer; every later step reads the record, so the base branch it names is used as-is. A branch it names that does not exist stops the run and asks rather than guessing.
  • Then the repo's own declaration. Outside Omniscio — or for a repo that declares nothing at the start — a base branch declared in .claude/foundations.json (pipeline.baseBranch) is used as-is; a declared branch that does not exist stops the run and asks.
  • Otherwise the remote's default first (what origin/HEAD names, e.g. develop), then main, master, develop, trunk — the same order Omniscio's repo profile uses. Among those fallbacks a branch that exists on your computer is preferred over one that only exists on the remote.
  • The newer copy is used. When both your copy and the remote's copy exist, the pipeline compares against whichever is ahead, so a teammate's newer edit on the remote is not missed; if the two have split apart it stops and asks (Omniscio's own repo keeps its local copy).
  • It never guesses. When no main branch can be found, git prep stops with a plain message instead of reporting "nothing overlaps" — before this, a repo whose main branch is main had its overlap check silently skipped. A recorded base that is the branch you are working on is never used as the merge target.

How a run finishes — the measured finish (opt-in)

A run ends by bringing its branch home, and until now it took the agent's word that the checks passed. The measured finish replaces that word with checks the finish runs itself against the exact change that would land. It is off by default, and the first change you notice is on the next finish — no restart.

  • The switch — Dev Pipeline panel → Setup → the AI code review card → Measure every finish before the branch lands: Off, Report only, On. Off is the shipped default, and the switch is yours alone: an agent cannot turn it on or off.
  • Off is exactly what happens today. The finish still takes the run's word: it merges once the run's own check pass is green — or once the machine itself refused to run a check, which the finish states as checks not run and never as green.
  • Report only takes today's path first, so the merge has already happened by the time anything is measured, and then prints what On would have done from the main copy as it stood before that merge: when On would have stopped before measuring (for example because your main copy moved on and the branch has not taken it in), it prints that exact refusal; otherwise one line per check saying what it would have passed, refused or held. It changes nothing — it cannot refuse, hold or relabel a finish.
  • On ignores the word and measures. It stops unless the newer work from your main copy is already in the branch (so the change that gets measured is exactly the change that lands), runs your project's own list against that one exact commit, refuses a failed check by name, holds with nothing merged when a check gives no answer, and moves your main copy onto precisely the commit it measured — a fast-forward, never a new merge commit. It also stops if the branch or your main copy has moved since the measurement.
  • What is on the list is yours. It is your project's single gate command if you declare one, otherwise its test, lint, typecheck and build commands, read from your main copy's own commit and never from the branch being judged — plus any command steps of the pipeline you run whose files match the change. A change that edits the files defining those checks is named on the finish's last line, so a change can never quietly lower its own bar.
  • Three answers, never two. Every check ends as passed, failed or no answer. A check that could not start, ran out of time, or was refused by the machine is no answer, and is reported as that — never folded into a pass or a failure.
  • A project with nothing to run still finishes, and says so out loud: its finish reads not tested rather than passing itself off as tested.
  • When a check gives no answer, the finish stops with nothing merged and names the check and how long it waited. Get that check answering and finish again, make a new commit and finish again, or set the switch back to Off to finish exactly the way you did before.
  • Where it applies — the finish that merges a branch into a project's own main copy. A project whose work lands through the app's lander, or that finishes by opening a pull request, keeps its own ending and this switch changes nothing there. A cloud session hands its branch back and never lands it itself. That road is covered instead by the measured-finish door (devPipelineMeasuredFinishDoor), which refuses a ready tag for a commit carrying no measured-finish record; it ships Off and needs the record writer before it is usable.
  • A switch that cannot be read counts as Off — except in a run that started with it On, which holds instead of sliding back to Off.
  • Try Report only first. It shows you the real list and the real answers on your own code without letting any of them change an outcome; the ready checklist walks through doing exactly that on a throwaway project.

Quick Lane (opt-in, for tiny changes)

For a genuinely tiny change — one CSS line, a simple bug fix — the agent can put the run in the Quick Lane, or you can ask for it with /dev-pipeline --quick "<task>". A Quick Lane run goes Plan → Build → Git-Prep in one go, with no approval stops, and ends through the same finish as any run — the profile's own, read from land.strategy and land.mintCommand: the mint's "Ready to Merge" tag, or phase 6's no-mint ladder. It still keeps the to-do list (three items instead of six), the run's state.md, its own leased worktree, the roadmap claim, a regression test for a bug fix, a fix for any doc the change made wrong, and the normal ready-to-merge check — only the tests for what changed. A fix that trips a Patch or refactor? trigger leaves the Quick Lane for the full pipeline, so it gets its restructure instead of a small patch. It runs no red team, standards check, elegance pass, docs phase, standards audit or AI code review.

The run's own record follows the lane: when it starts, the app freezes only that lane's phases — Plan, Build and Git-Prep for a Quick Lane run, every phase the repo resolves for a full one — so the ready mint never refuses a Quick Lane run for a phase the lane does not run. A run that outgrows the lane widens its record: the run re-sends its start declaring lane: "full" with the request id it first used, and the same record is widened in place, so the phases it already checked in stay checked in. The ready-to-merge step measures a Quick Lane either way — the heading in state.md or the lane the app reports for the run's record — so editing the heading cannot escape the measurement.

The lane is decided by a measurement, not the agent's say-so: the quick-lane-check script counts the real change and allows at most 30 changed lines across 3 files (test files and docs — Markdown under docs/, READMEs, changelogs, CONTRIBUTING.md and memory notes — don't count, so a small fix can update its docs without leaving the lane; any other Markdown, such as a shipped agent prompt, still counts), with nothing in an off-limits area — database migrations, dependencies, sign-in, credentials and secrets, agent instructions such as CLAUDE.md and the .claude rules and skills, the pipeline's own files, plus whatever the repo's own pack lists in quickLaneLimits (read from the measurement base, so a branch can't loosen its own bar). The check runs after the last commit and again inside the ready-to-merge step. On a cloud session box it measures from the base the box started at rather than the main branch — there the main branch is the branch the run is itself committing to, so measuring against it would count nothing, and on a box that carries no main branch at all it would have nothing to measure against. On a computer whose local main branch has drifted apart from GitHub's, it measures from whichever of the two the branch most recently split from, and the result line names that one (base origin/master@…), so other people's commits are never counted as the run's own. If the change outgrows the lane, the run switches to the full pipeline and stops at the plan gate for your approval. Recorded in state.md as ## Lane: quick.

Autonomous mode (opt-in)

Hands-free operation, what still stops it, and why a crew session is autonomous by default: autonomous mode (developer-only reference).

A dropped check-in heals itself

Every phase checks in through one shared runner that trusts the app's answer, not the send: a dropped call, an outage, a rate limit or a no-run answer is unconfirmed and kept in the run's own record. The next phase re-sends every earlier unconfirmed check-in first — which is how Plan and Red Team, sent before Build starts the run, land as Build begins — and an out-of-order refusal names the missing phase, which the run re-sends and retries once. The guard still refuses; nobody re-sends by hand.

A check-in written before Build — before there was any worktree — carries no branch, and the app will not credit a branchless report to a run that is bound to one (that rule is what keeps a report off an earlier task's run). So once the run records its branch, the runner fills that branch into every stored check-in that has none, and they land on the next send. A no-run answer names which of the four situations it is and the runner prints that sentence, and re-sends are paced on the quota the app advertises in its answer — the cap, the window, and the slots this session has left — so a backlog drains instead of being refused.

  • Dev Pipeline packs — reshape every step for your team, and share one company pack across repos.

The opt-in behaviour modes, the configuration layers and the skill's internals are on Dev Pipeline (part 2).

Every workflow control — watched repos, gate auto-approval, skill install, panel setup — hangs off ONE setting, devPipelinePanelEnabled, on the Dev Pipeline panel's Setup tab. It installs the skill bundle, arms the auto-lander, the reminder, the per-repo gate and daily maintenance; switching it off removes and disarms all of them. Settings → Features → "Dev Pipeline" is that same switch, not a second one — flipping either place flips both, and the five companion toggles sit under it there (see "Companion toggles" above), bound to the same resolved settings the panel writes. The housekeeping jobs that ride alongside it are documented in Dev Pipeline Maintenance.

Last verified 2026-11-12