Omniscio

Dev Pipeline packs

A pack is the .claude/dev-pipeline/phases.json file a team already commits to its repo, now able to change every step of the Dev Pipeline — including the six built-in steps and their approval stops — and to build on a shared company pack. A repo with no pack runs exactly today's pipeline.

On this page

What it is

The Dev Pipeline is a list of steps (Plan, Red Team, Build, Elegance, Docs, Git-Prep, the two standards checks, any AI Code Review steps, and your own custom steps). Today's list is itself shipped as the default pack. A team's pack changes only what it names; everything else stays as the default.

With a pack a team can:

  • Remove any step ("enabled": false). Steps that came after it move up into its place.
  • Rename a step (title, emoji). The step still works the same way underneath.
  • Move a step (insertAfter).
  • Turn a stop off ("gate": false), or make it clear itself (autoApprove).
  • Rewrite a step's instructions (instructions, with instructionsMode of append or replace).
  • Change the approval reply that moves the run on (approvalText).
  • Lock a step ("locked": true) so no project or developer below can loosen it.
  • Choose its Quick Lane steps ("quickLane": ["plan", "build", "gitPrep"]).
  • Add brand-new steps (custom), as before.
  • Give a new step commands that must pass (run), or run it only when certain files change (when.paths). See Command steps and conditional steps.

Start from a preset

Four ready-made packs ship with the pipeline. Pick one, then edit it like any other pack:

Preset What it does
standard Today's full pipeline, unchanged.
lean Fewer stops for small teams: Red Team and Docs run without stopping, Code Elegance is off.
strict For critical code: every stop waits for a person and the standards steps are locked.
docs For writing and documentation repos: no Red Team or Code Elegance, Build becomes "Write", plus a Proofread step.

pack.mjs presets lists them and pack.mjs init --preset <name> writes the one you choose into your repo. A preset is copied, not linked: the file is yours, and a later change to the preset does not change your repo.

Edit a repo's pack from the app

You do not have to hand-edit JSON. Open Dev Pipeline → Setup → Your pipeline → Change, pick the repo at the top, and the screen shows that repo's real pipeline — every step, in the order it runs — and lets you change it. The same screen is where the presets are chosen: a preset sets both which steps run and where it waits for you, so there is one gallery, not two.

  • Start from a preset. The four step-list presets above are offered beside the three personal shapes — Check every step, Just the plan, Autopilot — as one list. Choosing one asks first, then sets your own waits straight away and replaces the repo's step list and custom steps in the draft. Company-pack links (extends), quick-lane settings, models and review tiers are kept. A preset whose step list is not on this computer says so and is never half-applied.
  • Who said what. A steps panel shows, for every step, what your team's file does and what your own file changes — including a step the team removed and a step you added.
  • Change a step. Open a step to rename it, give it its own instructions, turn its stop off or on, or take it off the pipeline entirely (it shows greyed out and can be brought back).
  • Add a step. Give it a name, an icon, the anchor it follows, and whether it stops for a person. The anchor is any step in the pipeline — the very start, a built-in, or another custom step you added. Commands that must pass (run) and file patterns that decide whether it runs (when.paths) are offered only for a step placed after Build, because that is the rule the pipeline itself enforces.
  • Save. Nothing is written until you save. The file is .claude/dev-pipeline/phases.json in the repo, and committing it shares it with your team. If the file changed underneath the screen — a teammate's edit, a terminal, another agent — the save is refused with a plain sentence and the screen reloads rather than overwriting their work.

A step a company pack locks stays read-only here, and the screen never claims a change it did not make. The same write is available headless as PUT /dev-pipeline/repo-pack.

This screen is desktop-only. It writes a file inside a repository on the computer running the app, so both of its channels are closed to the web bridge and a paired phone does not show it; the command-line route above is the way to change a pack from anywhere else.

Autocomplete while you edit

pack.mjs schema saves phases.schema.json next to your pack and adds a "$schema" line to phases.json. Editors such as VS Code then suggest every field as you type and underline a typo or a value past its limit. The schema is generated from the same rules the app checks a pack against, so the two never disagree. (The app serves it at GET /dev-pipeline/pack-schema.)

The starter presets carry no "$schema" line: the schema file it would name lives in YOUR repo and does not exist until you run that command, so a copied preset would point at nothing until then. Running pack.mjs schema adds the line for you.

Command steps and conditional steps

A step you add under custom can carry two more fields:

{
  "id": "security-scan",
  "title": "Security scan",
  "insertAfter": "build",
  "run": ["npm audit --audit-level=high", "npm run test:security"],
  "when": { "paths": ["src/auth/**", "package.json"] }
}
  • run — up to 10 commands, each up to 500 characters. When the run reaches the step, the agent runs them one at a time from the worktree. The first one that fails stops the step, and it waits for you with the command and its last lines of output.
  • when.paths — up to 20 file patterns (* matches within a folder, ** across folders). The step runs only if the branch changed a file that matches. Otherwise it skips itself without stopping the run, and the next report says so in one line. If the change can't be measured, the step runs rather than being skipped.
  • Only after Build. Both fields need code to act on, so they are kept only on a step that comes after Build in the final step order. Anywhere earlier, or in a pack that removes Build, they are dropped and reported as a pack problem.
  • Never cut short. A list that breaks a limit is dropped whole and reported. The app never shortens a command or runs only part of a list.
  • A run keeps what it started with. The agent writes each step's commands and patterns into its plan at the start. A pack change pushed mid-run does not change that run.
  • These commands run on every developer's computer that works in the repo, with the same trust as the repo's own build and test commands. Review a pack change the way you review code. pack.mjs show lists every command and pattern, so you can see exactly what will run.
  • On an older version of Omniscio the step still appears, but its run and when are ignored: it runs its instructions only, on every change. Have everyone update before relying on them.

Where to find it

The pack lives in your repo at .claude/dev-pipeline/phases.json, next to the house-rules file (standards.md) and the Quick Lane size limits (quick-lane.json). Commit it and it applies to everyone who works in that repo.

A small example that slims a team's pipeline:

{
  "version": 2,
  "extends": ["https://github.com/your-team/pipeline-pack#0123456789abcdef0123456789abcdef01234567"],
  "phases": [
    { "id": "elegance", "enabled": false },
    { "id": "build", "title": "Implement", "emoji": "🛠️" },
    { "id": "plan", "gate": false }
  ]
}

How it behaves

The layers

Packs stack in this order, each changing only what it names:

  1. The default pack — today's pipeline.
  2. Company packs — listed in extends.
  3. The project pack — the repo's own phases.json.
  4. Your personal pack — ~/.claude/dev-pipeline/phases.json on your own computer.

A project's setting beats a company's, and a later company pack beats an earlier one.

Company packs

A company keeps its pack in its own git repository. Each project names it in extends as an https:// address followed by # and the full 40-character commit id. Short ids, branch or tag names, ssh addresses and local folders are refused, so a pack can only change when a project changes its pin. Up to 5 entries, nested up to 3 levels.

Omniscio downloads a company pack in the background and keeps a saved copy. If a run starts before the pack has ever been downloaded and it cannot be fetched in time, the run does not start and says why — it never runs quietly without the company's steps. Send the same request again once the pack has arrived.

Safety rules

  • Locked steps hold. A step a company marks locked cannot be removed, renamed, moved, un-gated, auto-approved or have its instructions replaced by anything below it.
  • What your personal pack may change is set by your team's pack — see below.
  • Every repo's pack has full power, including repos you did not write. The old 500-character limit on repo-committed text is gone. Each run records which packs (and which commit of each) built its pipeline, and pack show prints them.
  • A run keeps the pipeline it started with. Editing a pack mid-run does not change a run already under way.
  • A pack never lifts your computer's own git and push protections — those are enforced outside the pipeline.
  • Off switch: setting DEV_PIPELINE_DISABLE_PACKS=1 ignores every pack change, company pack and Quick Lane list, leaving today's pipeline plus your custom steps.

Who may change the pipeline on their own machine

Each repo decides what a developer's own pipeline file (their personal pack) is allowed to change there. The pack sets it with one top-level field, personalTweaks, and there are three values:

  • tighten-only: the default when the field is absent. On their own machine a developer can add steps and make a stop stricter, but they cannot remove, loosen, rename or move a step the team's pack defines.
  • anything: they may also remove, rename, move, un-gate and auto-approve team steps — except any step the team marked locked, which they still cannot touch. Their own stop choices (below) still only tighten.
  • none: their own pipeline file changes no steps at all. Its steps, its added steps, its quick lane, its instructions and its per-step models are all ignored. Its review tiers still apply.
{ "version": 2, "personalTweaks": "anything" }

The quick lane always stays a team setting, so a personal quick lane is ignored under all three values. AI Code Review steps keep following the developer's own review settings in every case — those are read outside the pack layers. Only a team pack (a company or project pack) may set the field: the project's value beats a company's, the later company pack beats an earlier one, an unrecognised value is ignored with a problem, and a value in someone's personal file is ignored with a problem.

Which steps wait for you

Every approval step has one answer to "wait for a person, or move on": the team's pack sets the default, and your own choices adjust it for you, in every repo. You make those choices on Dev Pipeline → Setup → Your pipeline (the presets), on All settings (the step switches), or with a stops map in your own pipeline file:

{ "version": 2, "stops": { "plan": "auto", "build": "ask" } }
  • A choice can always make a step wait for you. It can let a step move on by itself only for Plan — and not even Plan when the team's pack locks it. A step the team keeps asking stays asking, whatever your preset says.
  • This holds under every personalTweaks value. stops in a team pack is ignored.
  • AI Code Review steps are not stop choices; they follow your review settings.
  • If your pipeline file exists but cannot be read, every step waits for you until you fix it.
  • Your older settings carry over: until your first change they still decide, and that first change copies them into your file.

The team commands

presets and init work anywhere. The others ask the app for the real answer, so run them from a session Omniscio started:

  • node ~/.claude/skills/dev-pipeline/scripts/pack.mjs presets — lists the starter presets.
  • pack.mjs init — writes a starter pack and a README explaining each field. Add --preset <name> to start from a preset instead. It never overwrites an existing pack.
  • pack.mjs schema — saves the autocomplete file next to your pack and links it from phases.json.
  • pack.mjs check — lists every problem with your pack in plain words (exit 1 when there are any).
  • pack.mjs show — prints the final step list for this repo and the packs that built it.
  • pack.mjs update — moves each company pack pin to that pack's newest commit, changing only the commit ids, as a one-line edit you can review.

What follows the pack

The agent's step list, gate auto-advance (including the reply that names the next step), the check-in and merge-ready checks, the Quick Lane, and the Dev Pipeline panel all read the same resolved pipeline. In the panel, Show the pipeline for (at the top of Setup → All settings and of Stages) picks whose pipeline those screens show: Your settings only (the default — your personal pack on top of the default) or any repo you added. Under it, a Built from line names the layers behind the list and any pack problems are listed. A step a project or company pack sets shows a read-only switch with the note "Set by this project's pipeline pack" — change it in that pack. Picking a project never downloads a company pack; one that is not on disk yet shows as a problem line until a run downloads it. The main Setup screen's "How hands-on" summary always describes your own settings. Run history still shows a renamed step under its built-in name.

Last verified 2026-11-11