Todokan — Kanban Task Management

Todokan is a kanban-style task manager. You can manage the user's tasks, boards, and projects through MCP tools.

Prerequisites

• - A Todokan MCP server must be available (see README for setup)
• Required env vars: TODOKAN_API_KEY, TODOKAN_MCP_URL (declared in skill metadata)

---

Trigger — When to Activate This Skill

Activate the Todokan skill when the user has one of the following intents:

Intent	Example
Create / edit / delete a task	"Create a task: review PR"
Show boards or tasks

"Show me my tasks", "What's on the dev board?" |
| Change status | "Mark task X as done" |
| Save research results | "Save this as a task / document in Todokan" |
| Briefing / summary from tasks | "Give me a briefing of my open tasks" |
| Attach a document to a task | "Write a note on task X" |
| Search topics across boards | "What did I note about the investor meeting?" |
| Retrieve changes since last check | "What's new since this morning?" |

Do not activate when the user is just talking about tasks in general without referencing Todokan.

---

Tool Ordering

Follow this order to achieve consistent results:

Reading (always orient first)

CODEBLOCK0

Writing (only after orientation + confirmation)

CODEBLOCK1

AI-Assisted (optional)

CODEBLOCK2

Golden rule: Never write blindly. Always call list_boards first to discover IDs — never guess UUIDs.

---

Mandatory Checks

Before executing write actions, clarify the following:

Before create_task

• - [ ] Board: Which board? (If unclear → show list_boards, let the user choose)
• [ ] Title: Short, precise, imperative (max 80 characters)
• [ ] Priority: low / normal / high — default to normal if unclear
• [ ] Due date: Only set if mentioned by the user

Before update_task

• - [ ] Correct task? State the title + board for confirmation
• [ ] Which fields? Only change the fields the user requested

Before delete_task

• - [ ] Always ask for explicit confirmation — "Should I permanently delete task '[Title]' on board '[Board]'? This cannot be undone."

Before create_document

• - [ ] Clarify format: markdown, text, or html
• [ ] Link: Attach to which task (or standalone)?

---

Guardrails

No Hallucination

• - Use only real data from MCP tool responses. Never fabricate task IDs, board names, or content.
• If a tool call fails or returns empty data: inform the user, do not improvise.
• When in doubt, show the actual results and ask.

No Sensitive Data

• - Do not store passwords, API keys, tokens, or personal data in task titles or descriptions.
• If the user mentions sensitive information, warn them: "This may contain sensitive data — should I really store it in Todokan?"

Source Attribution

• - When storing content from external research (web, files, other tools) in Todokan, note the source in the task description or document:

CODEBLOCK3

Scope Awareness

• - Worker endpoint (/mcp-worker): Read-only + comments (add_comment). No task/board CUD, no document creation.
• Planner endpoint (/mcp): Full access. Still ask before destructive actions.
• On scope errors: explain to the user that the current endpoint does not have the required permissions.

Idempotency

• - On network errors: do not blindly retry the same action. First check whether the action was already performed (list_tasks).

---

Output Format

Briefing (summary of existing tasks)

CODEBLOCK4

Draft (preview before task creation)

CODEBLOCK5

Document Draft

CODEBLOCK6

---

Data Model

CODEBLOCK7

• - Habitats group boards. A user can have multiple habitats.
• Boards are kanban boards. Type task for actionable items, thought for ideas/notes.
• Tasks live on a board and move through status columns.
• Documents are rich text attached to tasks.

Status Values

Status	Meaning
INLINECODE15	Not started
INLINECODE16

In progress | | done | Completed |

Priority Values

Priority	Meaning
INLINECODE18	Low priority
INLINECODE19

Default priority | | high | High/urgent priority |

Available MCP Tools

Reading Data

• - list_habitats — List all workspaces
• INLINECODE22 — List all boards (returns id, name, version)
• INLINECODE23 — List tasks with filters: boardId, status, label/labels, limit, INLINECODE29
• INLINECODE30 — Full-text search over habitats/boards/tasks in one call
• INLINECODE31 — Unified feed since timestamp (task events + comments + documents)
• INLINECODE32 — Get unique labels on a board with usage counts
• INLINECODE33 — Get documents attached to a task
• INLINECODE34 — Read a document's content
• INLINECODE35 — List comments on a task

Creating & Modifying (Planner endpoint only)

• - create_habitat — Create a new workspace (name)
• INLINECODE38 — Create a new board (name, optional habitatId, boardType)
• INLINECODE42 — Create a task (title, boardId or boardName, optional description, dueDate, priority, labels)
• INLINECODE50 — Update a task by ID (taskId, plus fields to change)
• INLINECODE52 — Update a task by exact title match (titleExact, boardId or boardName)
• INLINECODE56 — Permanently delete a task (taskId)
• INLINECODE58 — Create a document (optional relatedTaskId to attach)
• INLINECODE60 — Attach a new document to a task
• INLINECODE61 — Add a comment to a task

AI-Assisted Creation

• - propose_task_variants — Generate 2-3 task variants (short/standard/detailed) from a rough description
• INLINECODE63 — Preview a variant's fields before creating it

AI Visibility Gate

By default, the MCP server only returns tasks where aiEnabled: true. Tasks with aiEnabled: false are invisible to MCP agents — they will not appear in list_tasks, search_across_habitats, get_events_since, or get_task.

Users control this via a "Send to AI" button on each task card. When clicked, it sets aiEnabled: true, assignee: 'ai', and status: 'doing'.

• - To see only AI-assigned tasks: INLINECODE73
• To see all AI-enabled tasks: list_tasks {} (default — only AI-enabled tasks are returned)
• To explicitly include non-AI tasks: list_tasks { "aiEnabled": false } (override, useful for reporting)

OAuth & Authentication

• - OAuth 2.1 with PKCE (RS256 JWT)
• Token lifetime: 30 days, no refresh token
• Planner (/mcp): Full CRUD access — all scopes
• Worker (/mcp-worker): boards:read, tasks:read, labels:read, docs:read, comments:read, INLINECODE83
• No rate limiting — still be conservative with calls
• Activity logging: Every tool call is logged server-side

Common Workflows

List all tasks on a board

1. 1. list_boards to find the board ID
2. INLINECODE85 with boardId to get tasks

Create a task

CODEBLOCK8

Move a task to done

CODEBLOCK9

Add labels to a task

CODEBLOCK10

Find tasks by label

CODEBLOCK11

Search across all habitats

CODEBLOCK12

Poll event feed (agent loop)

CODEBLOCK13

Tips

• - Always call list_boards first to discover available board IDs — don't guess UUIDs.
• Use boardName instead of boardId when the user refers to boards by name.
• Due dates use YYYY-MM-DD format.
• Task titles are max 80 characters, descriptions max 500 characters.
• Labels are free-form strings (max 10 per task).
• The update_task tool requires the task's UUID. Use list_tasks to find it, or update_task_by_title if you only know the title.