stapel-tasks

Generic tasks and kanban boards: Board/Column/Task/ChecklistItem/TaskComment, a REST surface, a full outbox event surface, and custom fields via stapel-attributes. Usable standalone (a team runs a board by hand) or as the substrate an external orchestrator projects onto through opaque origin_* handles, a MOVE_POLICY authorization seam, and comm Functions (tasks.get/list_board/create/move/comment).

Part of the Stapel framework — composable Django apps that deploy as a monolith or as microservices without changing module code.

Install

pip install stapel-tasks

At a glance

Documentation

OpenAPI · capabilities.json · llms.txt (for agents)

What this is

A generic task domain — Board / Column / Task / ChecklistItem / TaskComment, a REST surface, a full outbox event surface, and custom fields via stapel-attributes. It is useful to any project by itself (a team runs a board by hand), and it is the substrate an orchestrator projects onto: an external state machine drives cards through opaque origin_* handles and the MOVE_POLICY seam — the module knows nothing about the machine.

Quick start

pip install stapel-tasks              # core
pip install "stapel-tasks[attributes]"  # + typed custom-field validation

INSTALLED_APPS = [
    # ...
    "stapel_tasks",
]

# urls.py
path("tasks/", include("stapel_tasks.urls"))

Requires a stapel-core whose background taskstore app uses the label stapel_taskstore — this module owns the Django label stapel_tasks. See MODULE.md.

Concepts

• Board — an ordered set of columns and the cards on them. Owns the custom-field schema (feature_defs) and optional workflow settings.
• Column — a status. Its key is the card's status; its category (backlog/active/review/waiting/done) is the fixed machine semantic.
• Task (card) — status = its column; order within the column is a fractional position (drag-and-drop moves write one row). Custom-field values live in features; a projecting system writes origin_meta.
• Move — drag-and-drop is a move validated by MOVE_POLICY: allow / deny(reason_key) / defer (the managed-card path).

Two reads of the same cards, deliberately: GET boards/{id}/tasks is a keyset feed (-created_at), GET boards/{id}/cards is the board shape — columns in order, cards grouped by column key and sorted by position. A kanban view wants the second. GET boards/presets serves the vocabularies a board-creation form needs (presets, categories, checklist states, priority scale) instead of making the client hard-code them.

from stapel_tasks import services

board = services.create_board(name="Team", preset="simple")
card = services.create_task(board=board, title="Ship it")
services.move_task(card, to_column=board.columns.get(key="done"))  # emits task.completed

comm surface

Settings (STAPEL_TASKS)

See MODULE.md for the full seam map (providers, registries, serializer seams, comm tables, anti-patterns, override-vs-upstream).

License

MIT — see LICENSE.

_{This page is assembled by stapel-readme from docs/readme.md plus the contract artifacts in docs/. Edit the prose in docs/readme.md; the badges, facts and links above and below it are generated — do not hand-edit README.md.}