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
| Level | The supervisor | You |
|---|---|---|
| Advisory (default) | Recommends or escalates | Decide every gate, with its advice attached |
| Co-sign | Can pre-approve or reject | Must also approve before the gate passes |
| Autonomous | Approves or rejects the gate itself | Nothing, 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”.
| Field | Meaning |
|---|---|
| Rule name | A unique id, for example rule-low-risk-merge |
| Applies to | prd, plan, merge, or all gates |
| Max diff lines | Most changed lines allowed. Empty means unlimited |
| Max files changed | Most changed files allowed. Empty means unlimited |
| Always escalate if these change | Glob patterns, for example **/auth/**, **/migrations/**, package.json |
| Require CI green | CI must be passing |
| Approve automatically when every rule passes | On: 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:
- Shep collects every rule for that gate (and every
allrule). If there are none, the supervisor agent decides as usual. - Every matching rule must pass. A rule never cancels another, so adding a stricter rule can only make the outcome safer.
- If any rule is broken, the gate waits for you, and the supervisor agent is not asked. A model can’t overrule a guardrail.
- 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| Command | What 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:
- A per-feature override for that feature.
- Otherwise the policy of the feature’s application, if its repository belongs to an app.
- 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
- Decisions & agent questions: how gates and questions reach you.
- Running many features: batch approvals with
--low-risk. - Feature flags