Kanby

Use the kanby CLI as the single interface to Kanby. Prefer --json when consuming output programmatically. Read references/cli.md for commands, deadline examples, completion examples, and exit codes.

Find or create a task

1. Run kanby auth status --json. If authentication is missing, tell the user to create a project Agent Token in Kanby Settings and expose it as KANBY_TOKEN; never ask them to paste it into chat.
2. Run kanby task list --json and select a task that clearly matches the user's request. When the user asks to create a card, use kanby task create "<title>" --note "<context>" --due YYYY-MM-DD --json, omitting --due when no deadline was given. Use the returned ref for subsequent commands. Do not silently create a duplicate or switch projects.
3. Set deadlines only from the user or authoritative task context. Use a concrete YYYY-MM-DD calendar date without timezone conversion; if the date is ambiguous, report the ambiguity rather than guessing. For existing tasks, use kanby task update <ref> --due YYYY-MM-DD --json; clear a date with --due "" only when requested.
4. Claim the task before editing code: kanby task claim <ref> --lease 15 --json. Then read its full context with kanby task get <ref> --json.

Work and acceptance criteria

• Keep descriptions for context. Put acceptance conditions in the structured checklist with kanby task checklist add <ref> "<criterion>" --json, not Markdown checkboxes in the description. If there is no checklist, add concrete, verifiable criteria from the agreed requirements before implementation.
• If the task contains independently deliverable pieces, split it once with kanby task split <ref> "<child one>" "<child two>" --json. Do not split a child again.
• Renew the claim with heartbeat during long work. Record progress at meaningful checkpoints, including validation evidence, rather than for routine tool calls.
• When creating a Pull Request, add a standalone Kanby-Task: <ref> trailer to its body (or use a kanby/<ref>-description branch). If project automation is disabled or the PR already exists, link it explicitly with kanby task link <ref> <url> --json.

Finish a task