Kanbus

Feature

Policy as code

Project rules written in Gherkin that block invalid changes and give agents the right guidance at the moment it applies, instead of in one long upfront prompt.

Agents follow procedure more reliably when they are reminded at the right time. Kanbus policies are .policy files in project/policies/, written in Gherkin. A policy can enforce a hard rule, such as requiring children before an epic starts, or emit a warning or suggestion when an agent creates, updates, views or lists issues. The trigger logic decides when advice appears, so the model does not have to remember every rule from its first prompt.

Guardrails and guidance in one file

Assertions block a change that breaks a rule and print the violation. Guidance steps never block; they print on stderr after a successful command.

Feature: Epic readiness guardrail

  Rule: Starting an epic requires decomposition
    Scenario: Epic entering in progress must have children
      Given the issue type is "epic"
      When transitioning to "in_progress"
      Then the issue must have at least 1 child issues

  Rule: Epic decomposition coaching
    Scenario: Epic creation reminder
      Given the issue type is "epic"
      When creating an issue
      Then warn "Create at least one child story or task before starting an epic."
      Then explain "Epics represent milestones composed of multiple child issues."
      Then suggest "If this is one deliverable, model it as a story or task instead."

explain attaches an explanation line to the warning or suggestion before it. Warnings print before suggestions.

Guidance at workflow pace

Guidance runs after successful show, create, update, close, delete, list and ready commands. List-level guidance is useful in planning loops, where an agent triages and sequences work.

Feature: Planning loop reminders

  Rule: List and ready reminders
    Scenario: Keep statuses current
      When listing issues
      Then suggest "Reflect your current status in issue states as you work."

    Scenario: Ready queue semantics
      When listing ready issues
      Then warn "Ready means unblocked and actionable now."

The step library covers operation filters (creating, updating, closing, deleting, viewing, listing), transitions to, from and between statuses, issue type, label, priority and parent filters, and assertions on fields, labels, description, title pattern, custom fields, child statuses, child counts and parent status. Run kbs policy steps to see every step.

Work with policies from the CLI

kbs policy list
kbs policy validate
kbs policy check kanbus-a1b2c3
kbs policy guide kanbus-a1b2c3
kbs --no-guidance list
KANBUS_NO_GUIDANCE=1 kbs show kanbus-a1b2c3

kbs policy validate fails on unknown steps and on an explain with nothing to attach to, and reports errors with the file and rule. Policy guidance runs as a built-in provider in the lifecycle hook engine, so --no-guidance turns off guidance only, while project hooks keep running.

Learn more