Skip to Content
GuidesSupervisor & Guardrails

Supervisor & Guardrails

Behind the collaboration feature flag (on by default). Turn it off in Settings → Feature flags or with shep settings flags disable collaboration. With it off, gates behave exactly as without a supervisor.

Every feature stops at approval gates: requirements (PRD), plan and merge. A supervisor is an agent that looks at a gate on your behalf. Depending on how much authority you give it, it advises you, co-signs with you, or decides. Before it runs, guardrail rules you write can settle a gate with plain numbers and path patterns, without asking a model.

A supervisor runs on the agent you configured in Settings. Your own decision on a gate always wins.

Autonomy levels

LevelThe supervisorYou
Advisory (default)Recommends or escalatesDecide every gate, with its advice attached
Co-signCan pre-approve or rejectMust also approve before the gate passes
AutonomousApproves or rejects the gate itselfNothing, but you can override at any time

The level is set per policy, and you can override it per gate, for example advisory for requirements but autonomous for merges.

When the supervisor and you disagree on a gate, your decision is final. If the supervisor fails (a timeout, a model error), the gate simply waits for you; a supervisor never blocks a feature.

Every supervisor decision is stored with its verdict (approve, reject, escalate or advise), its reasoning, the model and prompt version, and appears in the feature’s activity log next to your own actions. In the web UI, Why? on a decision shows that record.

Guardrail rules

Guardrail rules are checked before the supervisor agent. They exist for limits that should be exact and never left to a model’s judgement: “no more than 250 changed lines”, “never auto-approve changes to auth/”, “CI must be green”.

FieldMeaning
Rule nameA unique id, for example rule-low-risk-merge
Applies toprd, plan, merge, or all gates
Max diff linesMost changed lines allowed. Empty means unlimited
Max files changedMost changed files allowed. Empty means unlimited
Always escalate if these changeGlob patterns, for example **/auth/**, **/migrations/**, package.json
Require CI greenCI must be passing
Approve automatically when every rule passesOn: a pass approves the gate. Off: a pass only advises

Stored as JSON, a rule looks like this:

{ "id": "rule-low-risk-merge", "gate": "merge", "maxDiffLines": 250, "maxFilesChanged": 5, "blockedPathPatterns": ["**/auth/**", "**/migrations/**"], "requireCiPass": true, "autoApprove": true }

How a gate is evaluated:

  1. Shep collects every rule for that gate (and every all rule). If there are none, the supervisor agent decides as usual.
  2. Every matching rule must pass. A rule never cancels another, so adding a stricter rule can only make the outcome safer.
  3. If any rule is broken, the gate waits for you, and the supervisor agent is not asked. A model can’t overrule a guardrail.
  4. If all pass and every matching rule allows automatic approval, Shep approves the gate. Otherwise the supervisor agent decides.

Guardrails fail closed. If the stored rules can’t be read, or the diff size or CI result can’t be determined, the gate waits for you instead of being treated as within bounds.

A rule with no limits, { "id": "approve-all", "gate": "all", "autoApprove": true }, passes every gate. That is the explicit way to say “approve everything”.

Batch approvals use the same rules

shep fleet approve --low-risk approves only the waiting gates that these rules prove safe: the feature’s policy is enabled, at least one rule covers the gate, every matching rule passes and allows automatic approval. With no rules it approves nothing. See Running many features.

Configure a supervisor in the web UI

Open Collaboration → Supervisor in the sidebar (/supervisor). It lists every policy by scope (Global, Applications, Repositories, Per-feature overrides) and the most recent supervisor decisions. Create supervisor policy picks a scope; an application’s policy is also on that app’s Supervisor page.

The policy form has:

  • Autonomy level: Advisory, Co-sign or Autonomous.
  • Evaluator model and Prompt version (optional).
  • Per-gate overrides for PRD, plan and merge (Inherit uses the policy’s level).
  • Guardrail rules: add, edit and remove rules with the fields above. Rules are edited only in the web UI.
  • Enable / Disable.

Collaboration → Agents (/agents) is where you edit the prompts of each agent phase, and /onboarding#supervisors has a short walkthrough.

Configure a supervisor from the CLI

# An application's supervisor: advisory for requirements and plan, autonomous for merge shep supervisor configure --scope app --scope-id <app-id> \ --autonomy advisory --merge-authority autonomous # A repository that isn't part of an app: its scope id is the repository's absolute path shep supervisor configure --scope repo --scope-id "$(pwd)" --autonomy cosign # Override one feature shep supervisor configure --scope repo --scope-id "$(pwd)" --feature <feature-id> --autonomy advisory
CommandWhat it does
shep supervisor configure --scope <global/app/repo> [--scope-id <id>] [--feature <id>]Create or replace the policy for that scope. Options: --autonomy <advisory/cosign/autonomous> (default advisory), --prd-authority, --plan-authority, --merge-authority, --model <id>, --prompt-version <v>
shep supervisor status --scope … [--scope-id …] [--feature …]Show the policy that applies
shep supervisor enable / disable --scope … [--scope-id …] [--feature …]Turn a policy on or off
shep supervisor approve --run <run-id> [--supervisor-id <id>]Approve a gate as the supervisor, for scripts and cron jobs
shep supervisor reject --run <run-id> --reason "<text>" [--supervisor-id <id>]Reject a gate as the supervisor

A new policy is enabled. Find app ids with shep app ls.

shep supervisor configure replaces the whole policy for that scope, including its guardrail rules, which the CLI can’t set. If you configured rules in the web UI, change the policy there, or add the rules again after running configure.

Which policy applies to a gate

When a feature reaches a gate, Shep looks for:

  1. A per-feature override for that feature.
  2. Otherwise the policy of the feature’s application, if its repository belongs to an app.
  3. Otherwise the policy of its repository, matched by the repository’s path.

If none is found, or it is disabled, the gate works as it does without a supervisor: it waits for you.

In Shep 1.252, a Global default policy is listed but not used as a fallback at gates, and policies the web UI creates for a repository or for a feature in a repository are keyed by the repository’s id rather than its path, so gates in repositories outside an app don’t find them. Until this is fixed, use an application policy, or configure repository policies with the CLI as shown above.

See also