Policies, presets and authority levels

Each team has one policy: what kanman may touch, how much it may spend, when a human must approve, and which choices it may make alone.

The policy is how a team sets the rules for kanman. It answers four questions: what may kanman touch, how much may it spend, when must a person approve, and which choices may it make on its own. Every check against the policy is logged, so you can always see why kanman did or did not do something.

Each team has exactly one policy. Its settings are spread over the team’s settings pages, starting with Settings > Autonomy, where you choose the trust level and who decides at each step. Only workspace admins can change it, and every change is recorded in the audit log as policy_changed with a new policy version. Each run remembers the policy version it started with.

Each team also names a responsible person for how much kanman does on its own, at the end of Settings > Autonomy. New teams start with the person who set them up; admins can name any member of the workspace. Every policy change in the audit log records both the person who made it and the person responsible at that moment, so “who allowed this?” is one entry. See responsible_user_id.

What the policy covers

Area Settings Default
Scope allowed_repos, denied_paths, max_changed_files, max_changed_lines preset paths, 30 files, 800 lines
Executor and models executor, fallback_executor, routing, billing_mode Claude Code, pass-through
Budgets budget_run_cents, budget_day_cents, budget_month_cents 2.00 EUR per run
Approvals plan_approval, plan_approval_min_size, merge_policy, auto_merge_max_lines, authority_overrides plan approval always, a person merges
Time and load working_hours, max_concurrency always, 1 at a time
Secrets secret_names none
Gate require_acceptance_spec, rework_attempts, gate_failure_budget spec required (except Trial), 1 rework, 3 failures
Personality intake_scope, maintenance, cadence set by the preset

The policy settings reference lists every setting with its values.

Secrets are listed by name only. Their values stay in your CI settings or vault and never pass through kanman.

Team settings > Autonomy: the trust dial with the five levels and who decides at each step from intake to live

Presets

You do not have to set every knob. Five presets bundle them by intent:

Preset For Concurrency Who files work Maintenance Acceptance spec required Default denied paths
Trial The first week with a new repository, repositories without specs 1 humans only off no infra/**, **/*.tf, .github/workflows/**
Focused kanman only works on what people filed 1 humans only off yes same as Trial
Balanced Most teams, the recommended default 2 humans and kanman off yes same as Trial
Autonomous Teams that let kanman decide on its own within their boundaries: review its own plans, approve, start and merge 4 humans and kanman as configured yes .github/workflows/**
Hardening Teams that want steady maintenance work 2 humans and kanman on, 2 per day yes same as Trial

Presets only change the “personality” knobs: concurrency, who may file work, what kanman decides on its own and how often it checks on long runs, plus the default denied paths and, for Trial, the spec requirement. The team’s rituals, its maintenance scan interval and its maintenance settings stay when you switch; Hardening switches maintenance on only for a team that has it off. Safety does not depend on the preset: the sandbox, the outcome gate, the diff guard and the clean-room check are the same for everyone.

When you change any knob a preset controls, the dial reads Balanced, adjusted, so it is always clear that you diverged from the level. Rituals and maintenance never count.

You pick the preset when you set up a team (the setup suggests Balanced) and can switch it at any time under Settings > Autonomy.

Set how much kanman does on its own helps you pick.

Authority levels

Every choice kanman makes is classified by a fixed table, in code, not by asking a model. There are three levels:

Level What kanman does Kinds of choices
AUTO Acts without asking. Visible in the audit log; the actions listed under What kanman does on its own also show a notice with undo write_ac (write acceptance criteria), set_priority_in_band, link_duplicate, resequence, nudge_run
NOTIFY Acts and records a notice on the team page and in Slack, with undo for seven days close_duplicate, split_story, pause_thrashing_run
ESCALATE Stops and asks in the decision inbox, with a recommendation and 2 to 4 options expand_scope, change_security_posture, touch_production_data, overspend, contradict_operator, touch_denied_path, plan_approval, merge

Three rules keep this predictable:

  1. Unknown kinds default to NOTIFY. kanman never acts silently on something the table does not know.
  2. Risk can only raise the level. An irreversible action, a high blast radius or a cost of 20.00 EUR or more is always ESCALATE. A medium blast radius or a cost of 5.00 EUR or more is at least NOTIFY.
  3. Teams can only raise. With authority_overrides (Small housekeeping under Settings > Autonomy) you can move a kind up, for example split_story from NOTIFY to ESCALATE. You can never move one down.

Plan approval and merging take their base level from the approval settings, see Policy settings.

What kanman does on its own

About every 15 minutes kanman tidies each active team, with at most five actions per team at a time. Paused teams are left alone, and kanman never closes or splits a story while a run works on it.

Kind Level What happens
link_duplicate AUTO Two open stories in Backlog, Refining or Ready are similar: kanman links them as duplicates.
close_duplicate NOTIFY Two open stories are nearly identical: kanman links them and closes the newer one as a duplicate of the older one. If the story comes from your tracker, the issue is closed there too, with a comment.
split_story NOTIFY A story of size L in Backlog or Refining with at least two acceptance criteria is split into 2 to 4 smaller stories in the same column. Each part gets its share of the criteria and keeps the Demonstrate block; its acceptance spec is written again. The original is closed and linked to its parts. For tracker stories, the parts are created as issues too.
resequence AUTO Backlog and Ready are sorted by class of service (expedite first, then fixed date by due date, standard, maintenance) and then by priority. Stories that rank the same keep your order, and once you reorder by hand kanman keeps your order.
nudge_run AUTO A run that has been stuck for 20 minutes is put back into the queue, at most twice.
pause_thrashing_run NOTIFY A run that restarted three or more times within two hours is paused.

A run that waits for a decision is never nudged or paused.

Notices. kanman tells you about every action in the team’s chat, as a card with the line, for example “I closed SBX-14 as a duplicate of SBX-9.”, and the stories it is about by key and title, so you can tell at a glance whether it got it right. NOTIFY notices are also posted to the team’s Slack channel for decisions, with a link back. Actions that change your tracker always get a notice, even for AUTO kinds. Every action is in the audit log as kanman_action.

Undo. Each notice card has an Undo button for seven days, available to every member of the workspace. Undo puts everything back: it reopens the story, removes the links or the parts, restores the previous order, or resumes or pauses the run again. If the story or the run has changed since, kanman says so and keeps the action. kanman never repeats an action you undid. The undo is recorded in the audit log under your name (kanman_action_undone).

Raised levels. If you raise a kind to ESCALATE, kanman asks first in the decision inbox, for example “Split SBX-12 into 3 smaller stories?” with Go ahead and Leave it as it is. If you approve, kanman acts right away, and you can still undo it. If you decline, kanman does not ask again for that story.

The safety floor

Some things no policy can change:

  • touch_production_data, change_security_posture and overspend are always ESCALATE.
  • .kanman/acceptance/** is always denied to executors, on top of your own denied paths.
  • The sandbox, the diff guard and the clean-room check are on for every preset.

An override that would lower a level has no effect: the stricter level always wins.

Every check is logged

Each policy check writes a policy_decision entry to the audit log with its result (allowed or denied), so you can answer “why did kanman stop here?” and “who allowed this?” months later. Executors can also ask before they try: the check_policy MCP tool answers “may I touch infra/?” without starting anything.

Last updated: January 1, 0001

Open kanman