Lifecycle Hooks

Lifecycle hooks make Kanbus command boundaries programmable. Projects attach external logic to before/after events without forking CLI behavior.

Event Coverage (v1)

  • issue.create
  • issue.update
  • issue.close
  • issue.delete
  • issue.comment
  • issue.dependency
  • issue.promote
  • issue.localize
  • issue.show
  • issue.list
  • issue.ready

Configuration

hooks:
  enabled: true
  run_in_beads_mode: true
  default_timeout_ms: 5000
  before:
    issue.update:
      - id: block-invalid
        command: ["./hooks/block-invalid.sh"]
        timeout_ms: 1200
  after:
    issue.create:
      - id: notify
        command: ["./hooks/notify.sh"]
        blocking: false
        env:
          WEBHOOK_URL: "https://example.invalid/hooks"

Execution Model

  • Payload is JSON on stdin.
  • Before-hooks on mutating events are fail-closed by default.
  • After-hooks are observer style; failures emit warnings and do not fail the command.
  • timeout_ms, blocking, cwd, and env can be set per hook.

Payload Contract

{
  "schema_version": "kanbus.hooks.v1",
  "phase": "after",
  "event": "issue.create",
  "timestamp": "2026-03-08T16:31:44.021Z",
  "actor": "dev@example.com",
  "mode": {
    "beads_mode": false,
    "project_root": "/repo",
    "working_directory": "/repo",
    "runtime": "python|rust"
  },
  "operation": {
    "issue": { "identifier": "kanbus-abc123", "title": "..." }
  }
}

Policy Integration

Policy guidance is implemented as a built-in lifecycle hook provider. Existing policy DSL behavior is unchanged. Use --no-guidance or KANBUS_NO_GUIDANCE to suppress only policy guidance while keeping external hooks active.

CLI Operations

kbs hooks list
kbs hooks validate
kbs --no-hooks list
KANBUS_NO_HOOKS=1 kbs list