⛓️ gated-downshift

A software factory for Claude Code — an assembly line where every station has a deterministic gate, not just an inspector.

gated-downshift is a Claude Code plugin that turns "ask a model to change some code" into a disciplined software factory. A feature flows down a ten-station assembly line — intake/spec → decompose → design-record → plan → review → execute → verify → CI → merge — and five of those stations carry a deterministic gate: a go/no-go calibre that makes a defect impossible to pass, not an inspector who might catch it. One fail-safe hook enforces the whole chain — no executor runs until every upstream station of its feature has passed. Because the reasoning is airtight before a line is typed, the typing itself downshifts to a cheaper, faster model — so the rigor also trims your token bill — and a per-station SPC board measures which calibre leaks defects, so the line improves on evidence, not vibes.

Quick start · The assembly line · How it works · Usage · Cost control · Contributing

Quick start

# 1. Add the marketplace and install
/plugin marketplace add AldemarHdez/gated-downshift
/plugin install gated-downshift@gated-downshift

# 2. Install the one dependency
pip install jsonschema

Now just say what you want in plain language — there are no commands to memorize:

add rate-limit headers to the orders endpoint

A non-trivial request like that is picked up by the conductor, which drives the whole loop — author → gate → cross-model review → downshift to the cheapest safe executor → verify — narrating each step and telling you what's next. No code is written until the plan passes the gate, and it pauses for a plain-language "go" only at the points that spend or are irreversible. You never type a command; you just describe the change, a feature ("build the checkout-tax feature"), a spike ("prototype a…"), a follow-up ("now make it blue"), or a question ("how are we doing?").

[!NOTE] Review the model tiers in routing.json and the relative prices in pricing.json to match your setup.

Why

Getting a model to write code is easy; getting it to write the right code, reliably, is not. Hand a task straight to a model and it fills reasoning gaps on the fly and drifts. gated-downshift refuses to let that happen: it forces the reasoning to be written down and checked before any code is produced, and makes that check impossible to skip. Handing execution to a cheaper model is safe only because the plan is airtight first — the efficiency is a byproduct of the discipline, not the goal.

[!IMPORTANT] The invariant, stated precisely: no executor runs until its plan (and its feature's whole upstream chain) passes the gate. Any failure or absence leaves the work on the expensive planning model — the pipeline never falls forward into unchecked cheap execution. It is fail-safe by construction. The orchestrating loop itself can still edit files directly — that path loses the savings, not the safety — and an opt-in edit gate (ADR-0004, in shadow) instruments exactly those direct edits so the residual gap is measured, and can later be enforced.

The assembly line

A feature flows down ten stations. A real factory isn't defined by its inspectors — it's defined by its fixtures and gauges: mechanical constraints that make a defect impossible to pass. Five stations here carry exactly that (a deterministic gate); the rest are cross-model judgment or a human gate. Just describe the feature in plain language; the conductor drives the whole line.

The load-bearing trick: one enforcement point, extended. The single PreToolUse hook denies an executor spawn unless the feature's entire upstream chain passed — spec_gate ∧ decompose_gate ∧ design_record_gate ∧ plan_gate ∧ review. There is no hook-per-station (a Claude Code restriction, and it would be fragile); there is one gate that checks the whole chain, so the fail-safe invariant holds across the line. ci_gate is the post-execution exception — it blocks the done stamp, not a spawn. A feature-less single change skips the upstream stations entirely — that's the single-change fast path (the conductor still drives it).

[!NOTE] The full-SDLC line is the design recorded in ADR-0001. Stations 0–7 and the SPC board ship today; break_paths runs in shadow (measured, not yet blocking); the factory-flow worktree + On-Call loop are the orchestration layer over the proven gates.

How it works

Zoom in on the per-task inner loop (stations 3–6 of the line above — plan → review → execute → verify, driven by the production pipeline). This is the gate/hook mechanism up close:

_{The per-task inner loop (stations 3–6): the Gate is the deterministic hook; incomplete/REVISE/FAIL loop back to the author, APPROVE downshifts to the cheap executor, PASS reaches Done.}

Three checks stand between reasoning and a committed change:

1. The gate (a deterministic hook) proves the plan is complete — every required field is present.
2. The reviewer (a different model, before any execution token is spent) attacks whether the plan is sound.
3. The verifier (a different model, after execution) attacks whether the result actually satisfies the plan.

Above trivial complexity there is a fourth, load-bearing rule: the gate refuses any plan whose acceptance criteria lack a failing-first test (RED→GREEN). So the executor always implements against a test that was red on today's code, and the verifier re-runs the cycle to confirm it went green for the right reason — not because the test was vacuous.

A skill can reason but may not fire; a hook always fires and cannot be reasoned around. Authoring is therefore a skill, enforcement is a hook — conflating the two is the anti-pattern this plugin avoids. That is exactly why test-first here is a gate rule, not advice: you cannot skip it.

Features

• 🏭 Ten-station assembly line — intake/spec → decompose → design-record → plan → review → execute → verify → CI → merge, five stations with a deterministic calibre. See The assembly line; just say what you want and the conductor drives it.
• ⛓️ Single-chain enforcement — one PreToolUse hook denies an executor spawn unless the feature's entire upstream chain passed (spec ∧ decompose ∧ design-record ∧ plan ∧ review), and the plan itself must name a real task of the feature's DAG (task_id membership — a stranger plan can't ride a passing decompose). Dependency ORDER between tasks runs as a shadow rule (DEP_INCOMPLETE: recorded, not blocking) until its ROI is measured. One enforcement point, not a fragile hook-per-station — fail-safe across the whole line.
• 🧩 Decompose gate — a feature's task DAG must be acyclic, dependency-ordered, and cover every spec criterion (no orphaned requirement), within a per-tier max_tasks budget. Coverage is checked against the spec_criteria embedded in the decompose plan and cross-checked against spec.json itself (SPEC_CRITERIA_DRIFT), so a criterion dropped in transcription can't silently vanish from the guarantee. The gate validates structure; the reviewer judges the split. A shadow rule (TASK_TOO_LARGE) also flags any single task that owns more acceptance criteria than the tier's per-task budget — an atomicity/timeout signal that a task is too big to finish in one executor turn — surfaced by --check as advisory until it's measured and promoted.
• 📐 Design-record gate — a change that declares an architectural surface must link a present ADR, and every domain term must appear in the glossary (presence-gated per project). Documentation discipline as a calibre, not an afterthought.
• 📊 SPC production board — board.py --status renders a WIP board and per-station leak-rate (passed here, failed downstream) — the confusion matrix generalized across the line. Cross-task measurement, so "which calibre is too loose" is a number.
• 🟢 CI gate — a feature can't be stamped done until CI is green (gh run, capability-detected); red re-enters at the execute station.
• 🧰 Toolchain setup (makes the checks real) — a lint_clean: true in a repo with no linter is theater. The opt-in toolchain-setup skill detects (or asks) the language and offers the deterministic tools — linter, type checker, test runner, pre-commit — that turn a trusted gate check into a verified one. Tools are chosen dynamically per language (no catalogue to drift); only the stable role→check map is pinned, and the gate never reads it.
• 🚦 Deterministic gate — a fail-safe PreToolUse hook that denies the cheap executor unless a validated plan passes.
• ✍️ Edit gate (opt-in, shadow) — a second PreToolUse hook over Edit/Write that instruments direct edits by the orchestrating loop: armed via .planning/ENFORCE_EDITS, it logs (never blocks, v1) every edit that has no active plan or falls outside the plan's file_manifest. The retro surfaces the findings; promotion to blocking is a corpus-locked flip (ADR-0004). Inert by default.
• 🔴🟢 Enforced test-first (RED→GREEN) — from medium complexity up, the gate blocks any plan whose acceptance criteria lack a failing-first test (fails on today's code, passes after the change). Test-first is a deterministic gate rule here, not a convention a skill can forget to fire — and the cross-model verifier re-runs the cycle to catch tests that are green theater.
• 🧱 Declared design patterns — from medium complexity up, a plan must name the pattern(s)/best-practice it applies (SRP, DIP, DRY, hexagonal, guard clauses…) or the gate blocks. The reviewer validates the named patterns against a catalog and flags anti-patterns (god function, duplicated logic, hidden side effects…). Design intent becomes explicit and auditable, not implicit.
• 🧠 Toulmin plan contract — every plan states why the changes achieve the goal (the warrant), so the cheap model never fills that inference in weakly.
• 🔒 HARD-enforced pre-spend review — the hook denies execution unless an independent, cross-model reviewer sealed an APPROVE bound to the plan's exact hash.
• ⚖️ Complexity-aware routing — each tier maps to an executor / verifier / reviewer model; a weak warrant automatically bumps the executor up a tier.
• 💸 Conditional verification — the expensive verifier runs only on genuine risk (weak warrant, API surface, high complexity), so low-risk slices stay cheap.
• 🔁 Closed learning loop — every evaluation is logged, distilled into LESSONS.md, and fed back to the author on the next session — automatically, via hooks.
• 📈 Self-calibration (two-sided) — the retro reports a confusion matrix: false positives (passed the gate, then FAILed verification → too loose) and false negatives (blocked, but the developer overrode as wrong → too strict), with rates versus a target you set in .planning/targets.json. retro.py --mine-surprise turns those mis-calibrations into candidate corpus cases (bad/ from false positives, good/ from false negatives). The gate is never auto-mutated: candidates land in .planning/surprise/ for a reviewed PR, and the corpus (CI) locks any rule change. Tell the plugin in plain language that a block was wrong ("the gate was too strict here") and the gate-feedback skill records the false-negative signal for you — it never unblocks the plan, only feeds future calibration.
• 🐞 Systematic debugging — when a test fails or the verifier returns FAIL, a disciplined skill takes over: reproduce → capture as a RED test → isolate by bisection → test one hypothesis at a time → fix the root cause → close the gap that let it through. No shotgun debugging, no symptom patching.
• 🧠 Optional code-memory (advisory, never a gate input) — when a code-graph/code-memory MCP server is present in the session, the author prefers it (blast-radius, references, dead-code, semantic search) to ground the warrant/file_manifest more cheaply and precisely; when absent it falls back to grep/git. Resolved by capability, not tool name (contracts/code-intelligence.md), so any provider works and none ships bundled — the plugin stays standalone. Which provider grounded each plan is logged and correlated against gate-block / REVISE / FAIL rates in the retro, so "does memory help?" becomes a measured number. The deterministic gate stays 100% offline.
• 🧪 Executable spec — the tests/plans/{good,bad}/ corpus is the definition of "ready-for-code": every good plan must pass, every bad plan must block.
• 🧭 Graduated rigor — the explore lane — an opt-in prototype tier below trivial that skips TDD, design patterns, the failure-path, the contract, and both cross-model review and verification, so spikes stay fast. The gate marks it prototype: true (not certified for production) and the retro tracks prototype slices separately. It is never reachable by the size floor (which only raises a tier), so it can't be used to dodge rigor — graduate a spike by re-authoring it at trivial+ before it ships.
• 🗣️ Natural-language prototype loop — a spike described in plain language ("prototype a…") runs the whole loop automatically via the downshift-run skill (author → gate → cheap executor), only at the explore tier; production still goes through the production pipeline. Small follow-ups ("now make it blue") are handled by the plan-amend skill, which edits the current plan in place — cheap for a prototype, and a fresh sha-bound review for production.
• 👁️ Visual/runtime verification — a plan that declares ui_surface routes to verifier-visual, which runs the app and asserts on the rendered output (screenshot / DOM / http) instead of only reading the diff — because for UI, green unit tests are not the feature working. It prefers a browser/preview MCP if one is present and falls back to running the app + curl; capability-detected, nothing bundled (contracts/runtime-verification.md).

Usage

You talk; the plugin drives. There are no commands to learn. Say what you want in plain language and the conductor (skills/downshift-conductor) routes it to the right stage, narrates each step, and hands off to the next one — pausing for a plain-language "go" only at the three real gates (approve the plan/decompose, spend on execution, merge), so nothing spends silently. What you say and where it goes:

Each stage ends by telling you what happened and what's next, so you never have to know the machinery. The deterministic gate still enforces on every execution regardless of how the flow was entered.

[!TIP] Each executor/verifier/reviewer declares its own model: and Claude Code honours it — a model: haiku agent runs on haiku even though the orchestrator runs on the expensive model. Do not pass a model override or launch them as a fork, or everything drags back onto the expensive model and the savings vanish.

The plan contract (Toulmin)

The plan is a Toulmin argument. The gate checks presence deterministically; soundness is judged by the cross-model reviewer and verifier — never by the hook.

A weak warrant forces the executor up one tier. A strong warrant must cite a verifiable fact in warrant_evidence or the gate blocks (WARRANT_STRONG_UNSUPPORTED) — the gate checks the citation is present, the reviewer judges whether it is real.

Enforcement point

The hook matches the Task tool (how subagents spawn). When the spawn targets an executor* subagent, the hook binds it to a specific plan and denies unless that plan passes. Binding is deterministic, in precedence order: plan_id in the spawn input → the pinned GD-PLAN: {plan_id} marker line in the spawn prompt (the Task tool drops non-standard input keys, but the prompt always survives — this is what lets every spawn in a batch bind to its own plan instead of all falling back to the shared pointer) → plan_path → the .planning/CURRENT pointer written by the author skill. A plan_id mismatch is rejected (closing the replay hole where a stale passing plan could authorize an unrelated spawn), and each evaluation stamps a plan_sha256 into gate-result.json so any post-gate mutation is auditable. Non-executor spawns pass through untouched.

Cost control

The cross-model verifier is the most expensive step, so it does not run blindly:

• Conditional verification — verify_required is true only on real risk (warrant_strength: weak, an API/contract/MCP surface, or complexity >= complex).
• Right-sized verifier tier — trivial slices that still need a look use verifier-sonnet; medium+ use verifier-opus, always a different model than the executor.
• Behavioral certification (shift-left) — if the reviewer seals an APPROVE with --waiver and every acceptance criterion pins a verify_command + expected, the verifier is exempted on API/complex slices (never on weak/architectural).
• Batch verification — verify once over the combined diff of several slices (the batch flow).
• Free authoring self-check — plan_gate.py --check runs the gate deterministically so the expensive author never simulates the gate in-model.

Evolution: how the gate improves with use

The plugin learns from its own prediction errors (its "surprise"), on both sides, and turns them into evidence — never into an automatic rule change.

• The signal is a confusion matrix. A plan that passed the gate but FAILed verification is a false positive (gate too loose); the verifier logs these automatically. A block the developer judges wrong is a false negative (gate too strict); you record it in plain language and the gate-feedback skill runs --log-override. Without the second signal a gate can only ratchet tighter forever — the override is what lets it loosen with evidence.
• retro.py --build reports the matrix — FP-rate, FN-rate, a per-period trend, and pass/fail against a target in .planning/targets.json (e.g. {"false_positive_rate_max": 0.1}), so "it improved" is a measured number, not a feeling. Runs automatically on every subagent stop.
• retro.py --mine-surprise converts each mis-calibration into a candidate corpus case in .planning/surprise/ — bad/ from false positives, good/ from false negatives — each annotated with what the current gate does and a triage note (a FAIL is not proof the plan was bad; it may be an executor slip). Runs automatically too; the retro digest surfaces the results.
• The gate never mutates itself. Candidates are proposals. To evolve a rule you open a PR that adds the case under tests/plans/ and adjusts the rule; the corpus in CI locks it. Evolution rides the same regression discipline as every other rule — advisory learning (LESSONS.md) is free to change, enforcement changes only through the corpus + human review.

Recording an override does not unblock the current plan — the gate still blocks. To proceed, fix the plan; the override is a calibration signal for the future.

In-flight shadow rule — Occam / parsimony. OVERBUILT_UNJUSTIFIED flags a plan that creates more new production modules than the tier's budget (routing.json max_new_files; tests/config/docs are never counted) without a simplicity_justification. It ships in shadow (recorded in shadow_failures, not blocking) so the retro can measure whether it predicts real verification FAILs before it is promoted to a blocking rule via a corpus PR. The reviewer judges whether a justification is real (YAGNI / premature-abstraction), the gate only counts + checks presence.

Rollout: shadow → enforce

1. Shadow — make _deny in plan_gate.py return _allow while still writing gate-result.json. Observe what would have blocked. No behaviour change.
2. Build the corpus in tests/plans/{good,bad}/ until every good plan passes and every bad plan blocks with the expected rule.
3. Enforce — restore real _deny. The downshift is now live and safe.

Keeping the plugin updated (no uninstall)

Per the official docs, the version in plugin.json is the cache key: Claude Code re-fetches an installed plugin only when that version changes, so pushing changes without a bump makes /plugin update say "already at the latest version" — and the usual workaround is a tedious uninstall + reinstall. (Git tags are not consulted; release.sh creates them purely for human release management.) Two ways to avoid the dance:

• Publishing an update — bump the version, commit, push (and tag, for humans) in one step, run from a clean main, then update normally:
  hljs language-bash

  Copy

  scripts/release.sh            # patch bump (or: minor | major | X.Y.Z): bumps plugin.json + commits + pushes
  

  hljs language-bash

  Copy

  # then, in Claude Code — no uninstall:
  /plugin marketplace update gated-downshift
  /plugin update gated-downshift@gated-downshift
  

• Iterating locally — load the working tree directly, no install/marketplace/cache at all (picks up every edit on relaunch):
  hljs language-bash

  Copy

  claude --plugin-dir .         # run from the repo root
  

Development

python3 -m pytest tests/       # the corpus is the executable definition of "ready-for-code"

[!WARNING] Plugin subagents cannot carry their own hooks field (a Claude Code security restriction). That is fine here: the gate is a plugin-level hook in hooks/hooks.json, not attached to any subagent. If you vendor this into a single project instead, you may place the same hook in .claude/settings.json — same matcher, same script.

Repository layout

Contributing

Contributions are welcome. The gate's behaviour is pinned by the corpus in tests/plans/, so:

1. If you change a gate rule, add or update a corpus case that proves the new behaviour.
2. Run python3 -m pytest tests/ — every good plan must pass and every bad plan must block.
3. Open a PR describing the rule change and the corpus case that locks it in.

License

MIT © Aldemar Hernández