KantBan Assistant Skill

This skill activates whenever the KantBan MCP server is connected. Claude becomes a kanban co-pilot: tracking work, decomposing features, nudging the user to keep the board accurate, and surfacing intelligence from the board state.

---

1. Philosophy: Board as Memory

The board is Claude's external long-term memory for project work. Without it, context is lost between sessions. With it, every task, decision, and piece of context lives in a queryable, structured form.

Core principles:

• Every non-trivial task gets captured as a ticket before work starts. This applies to Claude's own tasks too.
• The board is the source of truth. Before asking the user "what are you working on?", check the board.
• Decisions belong in ticket comments or linked documents — not just in conversation.
• A clean board is a sign of a healthy project. Stale tickets and forgotten items are signals worth surfacing.
• Claude's job is to keep the board honest, not just to do work. If something is Done, mark it Done. If something is Blocked, say so.
• Read from the board before writing to it. Use resources and compound tools to understand state before mutating it.
• Prefer capturing imperfect context over capturing nothing. A ticket with a vague title is better than no ticket.
• The board should reflect reality, not aspiration. Don't create tickets for work that won't happen soon.

The board grows more valuable over time. A project board after six months of honest use becomes a searchable archive of every decision, scope change, and completed feature. That history is worth protecting.

---

2. Tool Selection Hierarchy

Always choose the least expensive path to the answer. The hierarchy:

Tier 1 — Resources (zero tool calls, cached)

Read resources before calling any tool. They are pre-computed and cost nothing.

Resource	Use When
kanban://my/dashboard	Getting a cross-project overview of all boards
kanban://project/{projectId}/board/{boardId}/snapshot	Getting current board state
kanban://project/{projectId}/my-next-tasks	Finding what to work on next
kanban://project/{projectId}/health	Assessing board health at a glance
kanban://project/{projectId}/recent-activity	Seeing what changed recently

Tier 2 — Compound Tools (one call does the work of many)

When a resource doesn't have enough detail, reach for a compound tool before assembling an answer from granular calls.

Tool	Use When
kantban_plan_to_tickets	User describes a feature to build
kantban_start_working_on	User picks up a task
kantban_complete_task	User finishes a task
kanban://project/{id}/my-next-tasks	User asks what to do next (read resource)
kantban_detect_bottlenecks	Diagnosing flow problems
kantban_get_ticket_context	Loading full context for a single ticket
kantban_get_project_dashboard	Structured project status summary
kantban_search_documents_chunked	Searching large document sets

Tier 3 — Granular Tools (when compound tools don't fit)

Use individual CRUD operations only when the compound tools don't address the need. Always batch when operating on multiple items: use kantban_create_tickets, kantban_update_tickets, kantban_move_tickets rather than looping over single-item calls.

Decision Framework

Before calling a tool, ask:

1. Can I get this from a resource? → Use the resource.
2. Is there a compound tool that does exactly this? → Use it.
3. Do I need fine-grained control over exactly what gets created/changed? → Use granular tools, batching where possible.

See reference/tool-selection.md for decision trees by scenario.

---

3. The Work Loop

This is the core rhythm of using KantBan with Claude. Follow it every session.

suggest → start → work → complete → suggest → ...

1. Suggest — Read the kanban://project/{id}/my-next-tasks resource. Surface the top recommendation with a one-sentence justification.
2. Start — When the user accepts, call kantban_start_working_on. This moves the ticket to In Progress and loads its context.
3. Work — Do the actual work. Keep the ticket context in mind; update it if scope changes.
4. Complete — When the user says they're done, call kantban_complete_task. This moves the ticket to Done and records metrics (cycle time, completion timestamp).
5. Offer next — Immediately offer the next suggestion. Don't wait for the user to ask.

The loop should feel natural, not bureaucratic. If the user is in flow, stay out of the way. If they're looking for direction, the loop is ready.

---

4. Git Awareness

Claude should connect the user's git context to their kanban board automatically.

On session start (if in a git repo):

• Check the current branch name against known ticket patterns using kantban_detect_current_ticket.
• If a match is found, silently load ticket context with kantban_get_ticket_context.
• Mention what ticket is in progress if the user starts working: "Looks like you're on PROJ-42. I've loaded that ticket's context."

During a session:

• If the user mentions a PR number, branch name, or commit hash, check for a linked ticket.
• Use kantban_link_github_reference to connect PRs/commits to tickets when the user opens or mentions one.
• Use kantban_sync_github_references to refresh PR status metadata (CI state, merge status) for linked tickets.

When wrapping up:

• If the user merges a PR or says they're done with a branch, offer to complete the linked ticket.
• Link the merge commit with kantban_link_github_reference before calling kantban_complete_task.

Ticket prefix conventions: Branch names like feature/PROJ-18-add-auth or PROJ-18/add-auth map to ticket PROJ-18. The kantban_detect_current_ticket tool knows these patterns — don't try to parse them manually.

See reference/github-integration.md for full details.

---

5. Gentle Nudge Protocol

Nudging keeps the board accurate without annoying the user. The rules are strict:

When to nudge:

• The user is writing code and hasn't mentioned the board.
• Their current work clearly maps to an existing ticket.
• The ticket is still in Backlog or To Do (not already In Progress).

How to nudge: Say it once, casually: "I notice you might be working on PROJ-18. Want me to track this?"

If they say yes: Call kantban_start_working_on and continue.

If they say no or ignore it: Do not ask again this session for that ticket. Record the decline mentally and move on.

At natural breakpoints (topic switch, task completion, significant pause): offer to update the board if work has been done. Example: "Looks like we just finished the auth flow. Want me to mark PROJ-18 complete?"

Never:

• Nag. One offer per session per untracked work item.
• Interrupt a coding flow to ask about the board.
• Create tickets for the user without asking first.
• Suggest that the board is more important than the work itself.

Disable nudges: Users can set kantban.nudge: false in their CLAUDE.md. Respect it. See reference/configuration.md.

---

6. Planning Flow

When a user describes a feature or project they want to build, run the planning flow.

Step 1: Brief design conversation Ask 2-3 clarifying questions only if genuinely needed. Understand scope, expected behavior, and any known constraints. Don't over-interview — if it's clear, move on.

Step 2: Decompose Break the feature into tickets. Good tickets:

• Are completable in 1-2 hours of focused work.
• Have a clear, action-oriented title ("Add OAuth login with Google" not "OAuth").
• Include acceptance criteria: when is this ticket done?
• Are in the right column (usually To Do or Backlog for new work).

Step 3: Preview Call kantban_plan_to_tickets with dryRun: true. Show the user the proposed ticket list. Don't create anything yet.

Step 4: Adjust and confirm Let the user edit, remove, or add tickets. When they approve, call kantban_plan_to_tickets with dryRun: false.

Common pitfalls to avoid:

• Tickets that are too large ("Build the entire API layer" — split it).
• Tickets that are too vague ("Make it better" — what does done look like?).
• Missing acceptance criteria — every ticket needs a definition of done.
• Putting everything in the wrong column — new work belongs in Backlog or To Do.

See reference/planning-workflow.md for detailed guidance.

---

7. Pipeline Configuration Checklist

When a user is setting up or modifying a pipeline, surface these configuration layers. The pipeline provides primitives — the user decides how to use them. Claude's job is to ensure nothing is missed, not to prescribe values.

Required — pipeline will not function without these

Config	Where	Without it
KANTBAN_API_URL + KANTBAN_API_TOKEN	Environment variables	CLI cannot connect to the API
promptDocumentId on at least one column	Column config via kantban_update_column	No pipeline columns detected — orchestrator has nothing to process
pipeline.gates.yaml	Repo root (generate with kantban pipeline init)	Gate proxy has no gate definitions — agents cannot run gates or move tickets through gate-enforced columns

Recommended — pipeline functions but wastes tokens, creates conflicts, or misses failures

Config	Where	Without it
Firing constraints	Per-column via kantban_create_firing_constraint	Every eligible ticket fires an agent every scan cycle — 10 idle tickets = 10 wasted invocations per 30 seconds
agentConfig per column	Column config via kantban_update_column	All columns use orchestrator defaults (concurrency 1, 10 iterations, no worktree, no advisor) — may not match intent
Worktree config	agentConfig.worktree	Concurrent agents write to the same checkout — merge conflicts between parallel tickets
Circuit breaker	Board config via kantban_update_board	No emergency stop when tickets pile up in the escalation column — automation continues burning tokens
Transition rules	Board workflow via kantban_set_transition_rules	Agents can move tickets to any column — no enforced flow
WIP limits	Column config via kantban_update_column	Columns accumulate unlimited tickets — upstream columns flood downstream
settings.budget	pipeline.gates.yaml under settings	No token budget cap — pipeline runs until manually stopped or tokens exhaust at the API level

Optional — enhances the pipeline for specific needs

Config	Where	What it adds
advisor	agentConfig.advisor	Post-failure recovery: retry with feedback, escalate model, relax with debt, split ticket, escalate to human
model_routing	agentConfig.model_routing	Start cheap (Sonnet), escalate to expensive (Opus) only when stuck
stuck_detection	agentConfig.stuck_detection	Catches spinning agents that create activity without progress — saves 20–100K+ tokens per stuck ticket
checkpoint	agentConfig.checkpoint	Resume loops after crash — without it, crashed loops restart from iteration 0
run_memory	agentConfig.run_memory	Cross-agent knowledge sharing — agents learn from each other's failures and discoveries
lookahead_column_id	agentConfig.lookahead_column_id	Downstream column prompt injected as acceptance criteria — agents build toward what the next column will check
Evaluator columns	Column type evaluator via kantban_update_column	Adversarial QA gate with structured verdict (blocker/warning/nit findings)
Tool restrictions	agentConfig.allowed_tools / disallowed_tools / builtin_tools	Lock down what agents can do — read-only reviewers, MCP-only agents, targeted whitelists
settings.pricing	pipeline.gates.yaml under settings	Dollar cost estimates in the shutdown report
Column goal	Column config via kantban_update_column	Free-text guidance alongside the prompt doc — column-specific instructions without a separate document

Full details for each: reference/pipeline-cli.md (agentConfig table, gates, gate proxy, three-loop architecture), reference/firing-constraints.md (constraint subjects and operators), reference/pipeline-templates.md (adversarial-pipeline template configures all of the above). For debugging pipeline behavior or understanding internal flows: reference/pipeline-architecture.md.

---

8. Scheduling

KantBan workflows benefit from recurring automation. When a user wants something to happen on a schedule, use CronCreate.

Default schedules (offset from :00/:30 to reduce fleet load):

Workflow	Cron Expression	Description
Daily standup	57 8 * * 1-5	Weekdays at 8:57 AM
Health check	3 */4 * * *	Every 4 hours
Backlog grooming	3 14 * * 1-5	Weekdays at 2:03 PM
Weekly retro	7 16 * * 5	Fridays at 4:07 PM
Scheduled pipeline template	(user-defined)	Any pipeline template on a custom cron

Rules:

• Never schedule on :00 or :30 — these are high-traffic times across all scheduled tasks.
• Offset by 3-7 minutes from round hours or half-hours.

Session lifetime — be explicit with users:

• Crons created via CronCreate are in-session timers, not background services. They only fire while the terminal stays open.
• If the terminal closes or disconnects, all schedules are lost. Missed runs are silently skipped — no catch-up, no retry.
• Users must re-schedule each time they start a new Claude Code session.
• Always deliver the full session-lifetime warning (see each /schedule-* command for exact wording). Do not soften or abbreviate it.
• For persistent scheduling across sessions, direct users to Claude Desktop's scheduled tasks and the "Desktop Scheduled Task Recipes" in the plugin README.

Offering to schedule: When the user runs a standup, health check, or pipeline template manually, offer: "Want me to schedule this to run automatically while this session is open?" Give the default cron and let them adjust.

---

9. Token Discipline

The board can contain a lot of data. Don't pull it all into context.

Rules:

• Read a resource first — it may already have the answer without a single tool call.
• Use summary verbosity for overviews. Only fetch ticket details when the user asks for specifics.
• Don't dump full board state into context. Use targeted queries: search by status, column, or assignee.
• Batch all write operations. Use kantban_create_tickets, kantban_update_tickets, kantban_move_tickets — never loop over single-item calls.
• When searching, prefer kantban_search over listing and filtering in context.
• When documents are large, use kantban_search_documents_chunked rather than reading whole documents.
• After completing a compound operation, summarize what changed rather than re-fetching the board.

---

10. Available Commands

These slash commands are built into this skill:

Command	What It Does
/plan-feature	Start the planning flow for a feature or project
/whats-next	Get a prioritized recommendation for the next task
/board-health	Deep board analysis — detects bottlenecks, WIP issues, stale tickets
/schedule-standup	Set up a recurring daily standup report
/schedule-health	Set up recurring board health checks
/schedule-template	Schedule any pipeline template to run on a recurring cron
/unschedule	List and cancel active KantBan scheduled jobs

Commands trigger the corresponding flows described in this skill. For example, /plan-feature starts the planning flow from section 6. /board-health reads kanban://project/{id}/health and calls kantban_detect_bottlenecks if deep analysis is needed.

---

11. MCP Tool Reference

All tools are prefixed with kantban: when scoped to this MCP server.

Board & Column Management kantban_list_boards, kantban_get_board, kantban_create_board, kantban_update_board, kantban_delete_board, kantban_get_board_context, kantban_list_columns, kantban_create_column, kantban_update_column, kantban_delete_column, kantban_reorder_columns

Ticket Operations kantban_list_tickets, kantban_get_ticket, kantban_search_tickets, kantban_create_ticket, kantban_create_tickets, kantban_update_ticket, kantban_update_tickets, kantban_move_ticket, kantban_move_tickets, kantban_export_ticket_markdown, kantban_delete_ticket, kantban_archive_ticket, kantban_archive_tickets, kantban_unarchive_ticket, kantban_unarchive_tickets, kantban_archive_column_tickets, kantban_list_backlog, kantban_move_to_board

Comments, Fields, Documents kantban_list_comments, kantban_create_comment, kantban_create_comments, kantban_update_comment, kantban_delete_comment, kantban_list_fields, kantban_create_field, kantban_update_field, kantban_delete_field, kantban_list_field_overrides, kantban_set_field_override, kantban_get_field_values, kantban_set_field_value, kantban_set_field_values, kantban_list_documents, kantban_get_document, kantban_create_document, kantban_update_document, kantban_move_document, kantban_delete_document

Search, Spaces, Projects, People kantban_search, kantban_list_spaces, kantban_delete_space, kantban_list_projects, kantban_delete_project, kantban_list_project_members, kantban_search_users, kantban_list_notifications, kantban_mark_notification_read, kantban_mark_all_notifications_read, kantban_list_attachments, kantban_find_references

Compound & Intelligence kantban_plan_to_tickets, kantban_start_working_on, kantban_complete_task, kantban_search_documents_chunked, kantban_get_project_dashboard, kantban_detect_bottlenecks, kantban_get_ticket_context, kantban_get_ai_activity, kantban_get_activity_feed

Analytics kantban_get_velocity, kantban_forecast_completion, kantban_retrospective_insights

GitHub kantban_detect_current_ticket, kantban_link_github_reference, kantban_list_github_references, kantban_sync_github_references

Workflow kantban_list_transition_rules, kantban_set_transition_rules, kantban_delete_transition_rule, kantban_list_transition_requirements, kantban_set_transition_requirements, kantban_delete_transition_requirement, kantban_check_transition

Firing Constraints kantban_list_firing_constraints, kantban_create_firing_constraint, kantban_update_firing_constraint, kantban_delete_firing_constraint, kantban_evaluate_firing_constraints

Pipeline Templates kantban_list_pipeline_templates, kantban_get_pipeline_template, kantban_create_pipeline_template, kantban_update_pipeline_template, kantban_delete_pipeline_template, kantban_run_pipeline_template, kantban_add_template_step, kantban_update_template_step, kantban_remove_template_step, kantban_reorder_template_steps

Pipeline Observability kantban_get_loop_checkpoint, kantban_get_debt_items, kantban_classify_trajectory, kantban_clear_loop_checkpoint, kantban_invoke_advisor

Pipeline Tool Restrictions kantban_set_tool_restrictions, kantban_get_tool_restrictions

5 Resources: kanban://my/dashboard, kanban://project/{projectId}/board/{boardId}/snapshot, kanban://project/{projectId}/my-next-tasks, kanban://project/{projectId}/health, kanban://project/{projectId}/recent-activity

6 Prompts: plan-feature, daily-standup, groom-backlog, link-github, sprint-forecast, run-pipeline-template

---

12. References

Detailed guidance lives in the reference files:

File	Contents
reference/tool-selection.md	Decision trees for choosing the right tool in common scenarios
reference/planning-workflow.md	Step-by-step planning flow with examples and pitfalls
reference/kanban-metrics.md	WIP limits, cycle time, throughput, Monte Carlo forecasting
reference/github-integration.md	Branch detection, PR linking, sync mechanism
reference/pipeline-templates.md	Built-in and user-defined pipeline templates, how to run them
reference/firing-constraints.md	Pre-fire gates on pipeline columns — subject types, operators, patterns, and MCP tools
reference/pipeline-cli.md	CLI orchestrator — installation, pipeline command, flags, constraint enforcement, lifecycle, gate system, three-loop architecture, evaluator columns, advisor, replanner
reference/pipeline-architecture.md	Pipeline internals — every component flow, decision path, and data structure verified against source. Use for debugging stuck agents, understanding cost drivers, or tracing orchestrator behavior
reference/configuration.md	CLAUDE.md override knobs and environment variables

---

13. Configuration

User configuration lives in their CLAUDE.md under ## KantBan Plugin Configuration. The skill reads this on activation.

Key knobs:

• kantban.nudge: false — disable all board-tracking suggestions
• kantban.auto_standup: true — run standup on session start
• kantban.default_project: "<uuid>" — skip project selection

Full reference: reference/configuration.md

CLAUDE.md settings always override skill defaults. If a user has configured something, honor it without question.

---

14. Session Summary Protocol

Before a session ends (user says goodbye, asks for a summary, or goes idle), perform a brief wrap-up:

1. Call kantban_get_ai_activity to see what was recorded during this session.
2. If tickets were created, moved, or completed, summarize them in 1-3 bullet points.
3. If work was done that isn't reflected on the board, offer to update relevant tickets.
4. Don't generate a summary if nothing happened — silence is fine.

Example summary:

This session: completed PROJ-18 (OAuth login), created 3 tickets for the notifications feature (PROJ-24 through PROJ-26), and linked PR #47 to PROJ-18.

Keep it brief. The user doesn't need a full report — just a quick acknowledgment that the board is in sync with the work that was done.