Policy as Code

Policy as Code combines strict guardrails with in-the-moment guidance so agents follow procedure reliably while staying fast.

Kairos

This feature is explicitly about kairos: delivering the right instruction at the right moment. Instead of relying on a single upfront prompt and perfect model memory, Kanbus uses programmatic hooks to trigger guidance when context indicates it is relevant.

File Layout

project/
├── issues/
└── policies/
    ├── epic-ready.policy
    └── list-guidance.policy

Core DSL

Filters

  • When creating an issue
  • When updating an issue
  • When deleting an issue
  • When viewing an issue
  • When listing issues
  • When listing ready issues
  • When transitioning to "STATUS"
  • When transitioning from "A" to "B"
  • Given the issue status is "STATUS"

Assertions

  • Then the issue must have field "FIELD"
  • Then the field "FIELD" must be "VALUE"
  • Then all child issues must have status "STATUS"
  • Then the issue must have at least N child issues

Guidance Steps

  • Then warn "TEXT"
  • Then suggest "TEXT"
  • Then explain "TEXT" (attaches as an Explanation: line under the previous emitted item)

Example: Epic Ready Guardrail

Feature: Epic readiness guardrail

  Rule: Entry transitions require decomposition
    Scenario: Epic entering ready must have children
      Given the issue type is "epic"
      When transitioning to "ready"
      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 moving an epic to ready."
      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 of an epic."

Example: List-Level Guidance

Feature: Planning loop reminders

  Rule: List and ready reminders
    Scenario: Keep statuses current
      When listing issues
      Then suggest "Remember to 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."

Output Behavior

  • Blocking paths print policy violation details first.
  • Guidance is emitted on stderr.
  • Guidance ordering is warnings first, then suggestions.
  • Explanations stay attached under their parent message.
GUIDANCE WARNING: Ready means unblocked and actionable now.
GUIDANCE SUGGESTION: Remember to reflect your current status in issue states as you work.
  Explanation: Keeping statuses current improves handoff reliability.

Hooks

Guidance hooks run after successful:

  • show
  • create
  • update
  • close
  • delete
  • list
  • ready

CLI Commands

kbs policy list
kbs policy validate
kbs policy check <issue-id>
kbs policy guide <issue-id>

kbs --no-guidance list
KANBUS_NO_GUIDANCE=1 kbs show <issue-id>

Validation Rules

  • Unknown steps fail validation.
  • Orphan explain steps fail validation and evaluation.
  • Policy parsing/validation errors are reported with file + rule context.