Konban

Konban — Personal Kanban via Notion API

Overview

Claude skill for reading and managing a personal Kanban board ("Konban") in Notion. Used during daily standups and ad-hoc task management.

Helper Script

All operations go through the helper script (avoids shell quoting issues with curl + Bearer tokens):

python3 <skill-dir>/konban/notion-api.py <command> [args]

Commands

# Read active board (standup view — excludes Done/Grave)
python3 <script> board

# Read all items including Done/Grave
python3 <script> all

# Search tasks by keyword (active only — excludes Done/Grave)
python3 <script> search "QA tester"

# Create a task (ALWAYS search first — see Deduplication below)
python3 <script> create "Task name" \
  --priority High --timebox "1 h" --due 2026-02-20

# Update a task (any combination of flags)
python3 <script> update PAGE_ID \
# update accepts: page_id (positional), --name, --status, --priority, --timebox, --due
  --status "Doing ⚡️" --priority High

# Log progress on a task (appends timestamped note to page body)
python3 <script> log PAGE_ID "Sent proposal, awaiting response"

# Read task history (all log entries on a page)
python3 <script> history PAGE_ID

# Mark done
python3 <script> done PAGE_ID

# Trash a task
python3 <script> trash PAGE_ID

What create Does NOT Support

create only accepts --priority, --timebox, and --due. There are no --description, --domain, --tag, or --estimate flags. To add context to a new task, create it first then log:

# WRONG: create "Task" --description "Details" --domain KH --tag feature
# RIGHT:
python3 <script> create "Task" --priority High
python3 <script> log PAGE_ID "Details and context here"

When a task has associated content (draft text, a plan, deliverable outline), log it immediately after creation. The task body is the working surface — future sessions should find the content there, not have to reconstruct it:

# Create task, then log the deliverable content into the body
python3 <script> create "Write blog post about X" --priority Medium --due 2026-03-02
python3 <script> log PAGE_ID "DRAFT:\n\nHey everyone, I built a thing..."

log takes a PAGE_ID, not a task name. Use the ID returned by create or found via search:

# WRONG: log "Task name" "Progress note"
# RIGHT: log 30ab2e4a-2d15-... "Progress note"

update has no --blocking flag. Log dependency notes instead:

# WRONG: update PAGE_ID --blocking OTHER_PAGE_ID
# RIGHT: log PAGE_ID "BLOCKED: waiting on [Other Task]"

history requires a PAGE_ID — there is no global history view:

# WRONG: history              (no args)
# RIGHT: history PAGE_ID

Deduplication — ALWAYS Search Before Creating

Before creating any task, search for existing similar tasks. Duplicates are a real problem — sessions across different projects create tasks independently and don't see each other's work.

# ALWAYS do this before `create`:
python3 <script> search "key words"

# If a match exists: update or log on the existing task instead
python3 <script> log PAGE_ID "New context: ..."
# Or update the title/priority if the scope changed
python3 <script> update PAGE_ID --name "Updated title"

# Only create if no match found
python3 <script> create "New task" --priority High

Search tips: Use the core noun, not the full phrase. Search "QA" not "Find new QA tester for the project". Search "proposal" not "Send client the proposal document". Multiple short searches are better than one long one.

Completing Tasks — Log AND Move to Done

When finishing a task, ALWAYS do both steps:

1. Log the outcome — log PAGE_ID "Completed: what was done"
2. Move to Done — done PAGE_ID

Never just log completion without moving to Done. A task with a "Completed" log entry still sitting in "Doing" is confusing.

# Correct pattern for completing a task:
python3 <script> log PAGE_ID "Completed: shipped the fix, verified in production"
python3 <script> done PAGE_ID

Keeping Tasks Alive

Tasks are living artifacts, not static titles. Use log to record progress:

• Status changes: "Moved to Doing — starting deep work block"
• Decisions: "Decided to keep Flask backend, no rewrite"
• Blockers: "Waiting on vendor response, deadline early March"
• Outcomes: "Call done, next step: send proposal this week"

history reads back all log entries for a task — useful for context recovery across sessions.

Credentials

Stored at ~/.claude/secrets/notion.env (auto-loaded by helper):

• NOTION_TOKEN — Internal integration token
• KONBAN_DATABASE_ID — Database ID (UUID from the Notion database URL)

Database Schema

Standup Integration

During daily standups, present the Konban as a compact grouped view:

KONBAN BOARD
───────────────────────────────────────────
⚡️ DOING
  [High] Send client pre-call message (20 min)
  [Med]  Stripe API integration (3 h)

📝 TO DO
  [Urgent] MBA group project (Full Day, due Feb 20)
  [High]   Interview prep (1 h)

↺ PENDING EXTERNALLY
  [Med]  Partner → vendor contact (On Hold)

Rules:

• Run python3 <script> board to get active items
• Group by status column (Doing first, then To Do, then Pending Externally)
• Show priority, timebox, and due date inline
• Flag overdue items
• After presenting, ask: "Any status changes or new tasks?"

Domain Awareness

The Konban is cross-domain — it tracks tasks from ALL contexts:

• Main project operations
• Consulting / client work
• Personal (education, admin, health)
• Business admin

This is intentional. The Konban is the single view of "what am I doing today" regardless of domain.