Vikunja Kanban

Vikunja kanban orchestrator — creates tasks in a Vikunja project directly via the Vikunja REST API and records each as a swamp data resource with its ID, title, labels, and status. Built as a homelab-native replacement for @webframp/hermes-kanban-orchestrator: no hermes binary, no shell-out — just an authenticated HTTP client talking to a self-hosted Vikunja instance.

New tasks are placed into a named kanban bucket (default "Backlog") of the target project — the kanban view is discovered automatically — so automation-created tasks land in a backlog column rather than the view's default working column. The bucket is resolved before the task is created, so an unknown bucket name fails with nothing created. Any project can be targeted per call via a projectId argument.

Methods

• new_task — Create a task in a Vikunja project (default or per-call projectId), placing it in a named bucket (bucketName) and optionally attaching existing labels by title (label / labels), all resolved before anything is created. Refuses a card that does not meet its target bucket's readiness rules (ready: full Definition of Ready; waiting: a due date; doing/review/done: never) or requireReady; duplicateTitle refuse/skip/allow (default skip); every field is read back.
• apply_plan — Batch writes in one run: validate every create / update / labels / move / due / close op against one read of the board and report all problems (dry run by default); with apply: true, write nothing unless every op is valid, then run them in order with read-backs, stopping at the first failure. Records a planResult.
• board — Read-only: every open card (full description, bucket and role, labels, priority, due date) as one boardSnapshot resource, with truncated: true if the read hit the page cap.
• get_task — Read-only: one card and the bucket it sits in.
• list_recent — List the most recently created tasks in a project.
• audit — Read-only Definition-of-Ready audit of the whole board: empty/short descriptions, missing labels or label groups, unset priority, missing verdict/acceptance/source-link markers, stale cards per bucket role (waiting cards: by due date, which they must carry), WIP over the limit, buckets out of order.
• reorder — Sort every non-done bucket by priority then age. Dry run by default; apply moves one card at a time and re-reads until the board converges. A gap too small to halve, or a Vikunja 4028, makes it respace the view first (position below 0.01 triggers Vikunja's full recalculation). Each bucket has its own move budget; a run that gives up names that bucket and still writes its reorderPlan.
• due_report — Read-only: split the board's dated, not-done cards into overdue / due today / upcoming (lookaheadDays) with a link per card and a ready-to-send Markdown message, so a scheduled workflow can nudge on a card's due date.
• set_due_date — Set or clear one card's due date via a full-task read-modify-write, refusing done cards, asserting on read-back that the date took, and moving the card back (verified) if the write dropped it out of its bucket.
• update_task — Change one card's title, description and/or priority via a full-task read-modify-write, asserting each field on read-back and moving the card back if the write dropped it out of its bucket.
• set_labels — Attach and detach existing labels on one card by title through the label endpoints, with read-back.
• move_task — Move one card into a named bucket (never the done bucket) and read the placement back; the ready bucket needs the full Definition of Ready and waiting a due date, unless force: true.
• close_task — Mark one card done and move it into the done bucket; runs only with humanInstructed: true.
• create_label — Create one label (title, optional hexColor and description), idempotently: an existing title (case-insensitive, every page read) is returned instead of a duplicate, and a new one is read back. Runs only with humanInstructed: true; no other method creates labels.

The edit methods (update_task, set_labels, move_task, set_due_date) refuse done cards and cards someone else updated within policy.recentEditMinutes unless force: true.

Tracker for @swamp/stagecraft

A second model, @sntxrr/vikunja-kanban/tracker, is a stagecraft tracker (contract 1): put a @swamp/stagecraft/publisher in front of it and stagecraft's publish / claim / create / fetch-issue / mark-duplicate workflows file, comment on, move, relate and assign cards in one Vikunja project. Statuses are kanban bucket titles, types are labels, relations map onto Vikunja's relation kinds, and tasks outside the configured project are not_found.