SKILL: Kanbanzai Agents

Purpose

How agents interact with the Kanbanzai system: assembling context, dispatching and completing tasks, writing commits, contributing knowledge, and spawning sub-agents.

When to Use

• Before starting implementation work on any task
• When dispatching or completing tasks
• When writing commit messages
• When contributing knowledge entries after completing work
• When spawning sub-agents for parallel or delegated work

Vocabulary

next(id)

next(id: "TASK-xxx")

ready

active

summary

finish()

knowledge(action: "contribute")

finish(knowledge: [...])

finish(retrospective: [...])

.kbz/state/

handoff

handoff(task_id)

.kbz/state/

verification

finish()

Task Lifecycle Checklist

Copy this checklist when starting any task:

• Claimed the task with

  next(id: "TASK-xxx")

  — context assembled
• Read the assembled context (spec sections, knowledge entries, file paths)
• Confirmed the parent feature is in the correct lifecycle state
• Implemented the changes
• Ran tests (

  go test ./...

  ) and they pass
• Committed with a properly formatted message (see Commit Message Format)
• Completed the task with

  finish(task_id: "TASK-xxx", summary: "...", verification: "...")

• Included retrospective observations if any friction was encountered

Context Assembly

Before beginning any task, assemble context by claiming it:

1. Call

   next

   with a task ID to claim the task and receive a context packet containing role instructions, relevant knowledge entries, design context, and task details.
2. The packet is byte-budgeted and prioritised — it contains what matters most for this task and role.
3. To generate a prompt for a sub-agent instead, call

   handoff

   with the task ID — it produces a self-contained Markdown prompt ready for delegation.

After completing the task, maintain the knowledge base:

• Call

  knowledge

  action:

  confirm

  on entries that were accurate and useful — their use count increments and confidence grows.
• Call

  knowledge

  action:

  flag

  on entries that were incorrect or misleading — their miss count increments; repeatedly-flagged entries are auto-retired.

Task Dispatch and Completion

Picking up work

1. Call

   next

   (without an ID) to see ready tasks, sorted by priority.
2. Call

   next

   with a task ID to claim it. This moves it from

   ready

   to

   active

   and returns a context packet.
3. Do the work.

Finishing work

Call

finish

• task_id

  — the task being completed

• summary

  — brief description of what was accomplished

• files_modified

  — files created or changed

• verification

  — what testing or verification was done

• knowledge

  — any reusable knowledge learned during the task

Feature Completion

When

status

"FEAT-xxx has N/N tasks done — ready to advance to reviewing"

1. Transition the feature:

   entity(action: "transition", id: "FEAT-xxx", status: "reviewing")

2. PR and merge (if a worktree exists):

   pr(action: "create", entity_id: "FEAT-xxx")

   , then

   merge(action: "check", entity_id: "FEAT-xxx")

   , then

   merge(action: "execute", entity_id: "FEAT-xxx")

   . If the tools return

   not_applicable

   (no worktree), skip these steps.
3. Clean up:

   worktree(action: "remove", entity_id: "FEAT-xxx")

   if applicable.

For the full close-out procedure, see

.kbz/skills/orchestrate-development/SKILL.md

Commit Message Format

Every commit follows this format:

<type>(<object-id>): <summary>

Types

feat

fix

docs

test

refactor

workflow

decision

chore

Add

!

feat(FEAT-001)!: description

Examples

• feat(FEAT-152): add profile editing API and validation

• fix(BUG-027): prevent avatar uploads hanging on large files

• workflow(TASK-152.3): mark upload task complete after verification

Bad vs. Good

Bad:

fix: update code

fix(validate): reject task finish when parent feature is in draft

Bad:

feat: add new feature

feat(mcp): add context budget estimation to handoff tool

Commit discipline

• Commit at logical checkpoints — after completing a coherent change, before starting a risky edit.
• Do not commit directly to

  main

  . Work on feature or bug branches.
• MCP tools now auto-commit

  .kbz/state/

  changes after each operation (

  entity

  ,

  doc

  ,

  finish

  ,

  decompose

  ,

  merge

  , etc.). Manual commits for state files are no longer required.
• Manual commits are still needed for work files — Go code, markdown docs not managed by

  doc register

  , and any other non-state changes.
• The

  git status

  check at session start remains a safety net: orphaned

  .kbz/state/

  files from interrupted sessions are rare but still worth committing before starting new work.

Knowledge Contribution

When you learn something useful during a task, contribute it:

knowledge(
  action="contribute",
  topic="<topic>",
  content="<concise actionable statement>",
  scope="<role or 'project'>",
  tier=3,
  learned_from="<task-id>"
)

• Tier 3 — session-level; expires after 30 days without use.
• Tier 2 — project-level; the system promotes tier-3 entries automatically when used repeatedly.

Good entries are concise, actionable, and specific. "The API returns 404 for deleted users, not 410" is good. "Be careful with the API" is not.

Entity Names

Every entity (plan, feature, task, bug, decision) requires a

name

Hard Rules

These are code-enforced. Violations are rejected with an error:

• Required —

  name

  must be set on every entity. Never omit it.
• 60-character maximum.
• No colon (

  :

  ).
• No phase or version prefix — do not start a name with a pattern like

  P4

  ,

  P8

  , or

  P11

  followed by a space or dash. The phase is already encoded in the entity's parent field.
• Leading/trailing whitespace is stripped automatically.

Quality Guidance

• Target approximately four words. If you need more than five or six, the scope is too broad or the name is doing the summary's job.
• No em-dashes as separators. Hyphens in compound technical terms are fine (

  "Human-friendly ID display"

  ), but not

  "P8 — decompose"

  .
• A name should not be merely the slug capitalised.

  init-command

  →

  "Init command"

  adds nothing. Prefer

  "Project init command"

  or

  "Init and skill install"

  .
• Names must be self-contained — readable without knowing the parent entity.

  "Update agents"

  is ambiguous;

  "Update AGENTS.md layout"

  is not.
• Do not include the parent plan or feature name in the entity name — the hierarchy is visible from the parent field.

Examples

Good names:

Bad names:

Communicating With Humans

Documents are the human interface to the system. Decision records and their IDs are internal tracking mechanisms.

When talking with humans:

• Reference documents by name: "the ID system design", "the Phase 1 spec §10"
• Use prose descriptions of decisions: "the decision about cache-based locking"
• Do not lead with decision IDs: "P1-DEC-021 defines the ID format"

Sub-Agent Spawning

When delegating work to a sub-agent:

1. Include context — sub-agents do not see your conversation history. Include the project name for codebase knowledge graph, relevant file paths, and conventions the sub-agent needs.
2. Scope boundaries — tell each sub-agent which files it owns. If spawning multiple agents, ensure they do not write to the same files.
3. MCP delivery —

   next

   and

   handoff

   automatically include relevant skill content in the context packet for sub-agents.

Anti-Patterns

Unclaimed Implementation

• Detect: Agent starts implementation without calling

  next(id: ...)

  first.
• BECAUSE: Without claiming, the agent misses assembled context — spec sections, knowledge entries, and file paths curated for this task. This leads to wasted effort re-discovering what the system already knows.
• Resolve: Always claim via

  next(id: ...)

  before starting work.

Empty Finish Summary

• Detect:

  finish(summary: "done")

  or similarly vague completion.
• BECAUSE: The summary is institutional memory — future agents and humans read these to understand what happened. An empty summary forces re-investigation of completed work.
• Resolve: Describe what was accomplished, the approach taken, and any decisions made.

Forgotten Retrospective

• Detect: Task completed without retrospective signals despite encountering friction.
• BECAUSE: Without signals, the same friction repeats across every future task. The retro system cannot synthesise improvements from observations that were never recorded.
• Resolve: Include retrospective signals in

  finish()

  whenever friction, ambiguity, or positive patterns are noticed.

Uncommitted Tests

• Detect: Commit made without running

  go test ./...

  first.
• BECAUSE: A commit that breaks tests blocks every subsequent task and requires rework. The cost of running tests is always less than the cost of fixing a broken build.
• Resolve: Run tests before every commit.

Gotchas

• If

  next

  fails when claiming a task, another agent likely claimed it. Call

  next

  again (without an ID) to pick a different one.
• If a Kanbanzai tool call returns an error, read the message — it tells you what went wrong. Do not retry with the same arguments.
• Completing a task without

  verification

  degrades review quality. Always include what you tested.
• For workflow rules (stage gates, human vs. agent ownership, when to stop), see

  kanbanzai-workflow

  .

Retrospective Observations

When completing a task, reflect on the process. If you noticed any of these, include a

retrospective

finish

• The spec was ambiguous or contradictory on a point that mattered
• Information you needed was not in the context packet
• A tool was missing or returned unhelpful output
• The task was too large, too small, or had undeclared dependencies
• Something worked particularly well and should be preserved

Not every task will have observations. Don't force it. When you do, be specific: name the section, tool, or step that caused friction.

At task completion (primary mechanism)

Pass a

retrospective

finish

finish(
  task_id: "TASK-...",
  summary: "Implemented the billing webhook handler",
  retrospective: [
    {
      category: "spec-ambiguity",
      observation: "Spec did not define retry behaviour for failed deliveries",
      suggestion: "Add retry policy section to webhook specs",
      severity: "moderate"
    }
  ]
)

Valid categories:

workflow-friction

tool-gap

tool-friction

spec-ambiguity

context-gap

decomposition-issue

design-gap

worked-well

Valid severities:

minor

moderate

significant

Outside a task context

Observations during planning or design review can be contributed directly via

knowledge(action="contribute")

["retrospective", "<category>"]

Evaluation Criteria

next(id: ...)

go test ./...

.kbz/state/

Questions This Skill Answers

• How do I claim and start work on a task?
• What should I include in a finish summary?
• How do I format commit messages?
• When and how do I contribute knowledge entries?
• How do I spawn a sub-agent with proper context?
• What should I include in retrospective signals?
• How do I handle

  .kbz/state/

  files in commits?
• What do I do if

  next

  fails when claiming a task?

Related

• kanbanzai-getting-started

  — session orientation (what to do first)

• kanbanzai-workflow

  — stage gates and when to stop and ask the human

• kanbanzai-documents

  — document registration and approval