@basementuniverse/kanbn 2.1.0 → 2.5.1

package/docs/sprints.md

@@ -0,0 +1,175 @@
+# Sprints
+
+A sprint in Kanbn is nothing more than **a named point in time**. Each sprint has a start date, and
+runs until the next sprint starts; the last sprint in the list is the current one, and runs up to
+now. Nothing stores an end date or a duration, and there is no way for a sprint to be "closed" -
+starting the next sprint is what ends the previous one, and any end date you see in reporting output
+is derived from the next sprint's start.
+
+Tasks are never assigned to a sprint. A sprint is a window that reporting commands measure through,
+so which sprint a task belongs to is worked out from its dates (`created`, `started`, `completed`,
+`due`) rather than being recorded anywhere on the task. This means sprints cost nothing to add
+retrospectively, and moving a boundary re-slices history rather than invalidating it.
+
+Sprints live in the [`sprints`](index-structure.md#sprints) index option:
+
+```yaml
+sprints:
+  -
+    start: 2026-07-01T09:00:00.000Z
+    name: 'Foundation Sprint'
+    description: 'Baseline product and infrastructure work.'
+  -
+    start: 2026-07-08T09:00:00.000Z
+    name: 'Workflow Sprint'
+```
+
+`start` and `name` are required, `description` is optional.
+
+## Starting a sprint
+
+```bash
+kanbn sprint --name "Workflow Sprint" --description "Core team workflow and onboarding features."
+```
+
+`kanbn sp` is the short alias. The sprint always starts *now* - there is no option to backdate one
+from the CLI, so a sprint that should have started last Monday is a front matter edit.
+
+| Option | Effect |
+| --- | --- |
+| `--name`, `-n` | Sprint name. If omitted, auto-named `Sprint {n}` from the number of existing sprints |
+| `--description`, `-d` | Optional description, shown in `kanbn status` output |
+| `--interactive`, `-i` | Prompt for name and (optionally) description |
+| `--board`, `-b` | Run from the context of another board (see [below](#sprints-and-multiple-boards)) |
+
+There is no command to rename, re-date or delete a sprint. All three are edits to the `sprints`
+list in the board's front matter, which is deliberate: the sprint list is a small hand-maintainable
+piece of history, and `kanbn sprint` only ever appends to it.
+
+## Reading a sprint
+
+Three commands take a `--sprint N|"name"` option (`-p` in every case). A sprint can be selected by
+1-based number or by exact name; an unknown number or name is an error, not an empty result.
+
+### `kanbn status --sprint`
+
+Adds a `sprint` section to the status output for the selected sprint, defaulting to the current one:
+
+```bash
+kanbn status --sprint 2
+kanbn status --sprint "Workflow Sprint"
+```
+
+```yaml
+sprint:
+  number: 2
+  name: 'Workflow Sprint'
+  start: 2026-07-08T09:00:00.000Z
+  end: 2026-07-15T09:00:00.000Z
+  current: 3
+  description: 'Core team workflow and onboarding features.'
+  durationDelta: 604800000
+  durationMessage: '1 week'
+  created:   # tasks created during the sprint, with their total workload
+  started:   # tasks started during the sprint
+  completed: # tasks completed during the sprint
+  due:       # tasks due during the sprint
+```
+
+Each of those four groups lists the matching task ids with their column and workload, plus a summed
+`workload`. Any [custom date fields](index-structure.md#customfields) you have declared get a group
+of their own too.
+
+`current` and `end` only appear when you're looking at a sprint other than the current one: `current`
+is the number of the sprint that is running now, and `end` is the moment the sprint you asked about
+stopped, which is the next sprint's `start`. The current sprint has no `end`, because it hasn't
+ended - its `durationDelta` and `durationMessage` are measured up to now, and will be larger every
+time you run the command until the next sprint starts.
+
+### `kanbn burndown --sprint`
+
+```bash
+kanbn burndown --sprint "Workflow Sprint"
+kanbn burndown --sprint 1 --sprint 2
+```
+
+Plots remaining workload across the sprint window. `--sprint` can be repeated to draw a chart per
+sprint. With no `--sprint` or `--date` at all, burndown uses the current sprint - and if no sprints
+are defined, it falls back to all time, from the earliest task date to now.
+
+### `kanbn history --sprint`
+
+```bash
+kanbn history --sprint 2
+```
+
+Filters the event listing down to events that fall inside the sprint window. Repeatable, and
+combinable with `--assigned`, `--task` and `--date`.
+
+Gantt charts don't use sprints at all.
+
+## Sprints and multiple boards
+
+Sprints are workspace-level by default: every board reads the workspace list, so one sprint cadence
+covers the whole workspace and `kanbn sprint -b design` appends to that shared list (and says so in
+verbose mode).
+
+A board that declares its own `sprints` in its front matter **replaces** the workspace list for
+itself entirely - it can no longer see workspace sprints, so `kanbn status -b design -p "Foundation
+Sprint"` will fail to find one that only exists at workspace level. Sprints started on such a board
+are auto-named `{Board name} Sprint {n}` so two boards' sprints can't be confused. Forking is never
+implicit; it stays a deliberate front matter edit. See
+[multiple boards](multiple-boards.md#per-board-sprints).
+
+`--sprint` can't be combined with `--all-boards`, because sprint numbers and names are relative to
+one board's list.
+
+## Keeping the list sane
+
+The "current sprint is the last one" and "a sprint runs until the next one starts" rules both assume
+the list is in chronological order. `kanbn validate` emits a `sprints-out-of-order` warning if it
+isn't - worth checking after hand-editing dates.
+
+## Example workflow
+
+A team working in weekly sprints, reviewing at the end of each one.
+
+Start the first sprint on the Monday:
+
+```bash
+kanbn sprint -n "Foundation Sprint" -d "Baseline product and infrastructure work."
+```
+
+Work the week normally - `kanbn add`, `kanbn move`, `kanbn comment`. Nothing needs to reference the
+sprint; the dates Kanbn stamps on tasks as they're created, started and completed are what the
+sprint reporting reads.
+
+Check progress mid-week:
+
+```bash
+kanbn status --due
+kanbn burndown --normalise auto
+```
+
+With no `--sprint`, both default to the current sprint, so this is the "how is this week going"
+view.
+
+On the following Monday, review what the week actually contained, then start the next sprint:
+
+```bash
+kanbn status --sprint "Foundation Sprint"
+kanbn history --sprint "Foundation Sprint"
+kanbn sprint -n "Workflow Sprint" -d "Core team workflow and onboarding features."
+```
+
+Starting the second sprint closes the first one at that moment, and the reports above stay valid
+for it forever - `kanbn status -p 1` and `kanbn burndown -p 1` will show the same window next month.
+
+Comparing two sprints later on:
+
+```bash
+kanbn burndown -p "Foundation Sprint" -p "Workflow Sprint"
+```
+
+The [`example/basic`](../example/basic) workspace ships with three sprints defined, so every command
+on this page can be run there as-is.

package/docs/task-structure.md

@@ -100,7 +100,11 @@ An array of tags to apply to this task.
 
 ### `assigned`
 
-The name of the user this task is assigned to.
+The name of the user this task is assigned to. This is free text: any string is a valid assignee, and Kanbn never rejects or rewrites one.
+
+A workspace can declare a list of [contributors](contributors.md), which gives each person a canonical spelling, autocompletes this field in the interactive prompts and lets `kanbn find --assigned @me` work. Contributors are advisory — `assigned` stays free text either way, and a name that isn't in the list is still perfectly valid.
+
+A task has one assignee. `assigned` is a single string in the schema, the filters, the board template and the reporting commands, and there is no multiple-assignee form.
 
 ### `progress`
 
@@ -150,6 +154,8 @@ The `depends-on` relation type is reserved for gantt scheduling. It means the cu
 
 An array of comments, where each comment has an `author` and `date` property, and some text.
 
+`author` is free text, exactly like [`assigned`](#assigned), and it is optional — a comment added on a machine with no resolvable user has an empty author rather than failing to save. When the workspace declares [contributors](contributors.md), the default author is the canonical name for the current user.
+
 ## History
 
 An optional array of structured lifecycle events used for richer timeline reporting (including burndown).
@@ -168,7 +174,8 @@ Notes:
 
 - History entries are stored in the reserved `## History` section as list items.
 - `date` should be an ISO timestamp.
-- Additional fields (for example `author`) are preserved if present.
+- Every event carries an optional `author`, naming the [current user](contributors.md#the-current-user) at the time it happened. The key is omitted entirely when there is no resolvable user, so a machine with no git identity writes exactly the history it always has.
+- Any other additional field is preserved if present.
 - An event type this version of Kanbn doesn't recognise is preserved and skipped rather than rejected, so a task file written by a newer version stays readable.
 
 ### Board attribution

package/example/advanced/kanbn.yml

@@ -53,6 +53,71 @@ columnSorting:
 
 dateFormat: yyyy-mm-dd
 
+# The people who work on this workspace. A contributor can be a bare name or an
+# object; `name` is the value written into a task's `assigned` field and a
+# comment's `author`, and `aliases` catch the other spellings that mean the same
+# person. The list is advisory - `assigned` stays free text and is never
+# validated against it. Run `kanbn contributors --usage` to see which spellings
+# are already in use. See docs/contributors.md.
+contributors:
+  - name: Ana
+    email: ana@example.com
+    aliases:
+      - ana
+      - Ana Ruiz
+  - name: Ben
+    email: ben@example.com
+    aliases:
+      - ben
+
+# Rules that fire when a task changes. Actions only run during commands that
+# change something - never during `board`, `find` or `burndown` - and nothing a
+# rule writes can fire another rule. `--no-actions` on any of those commands, or
+# KANBN_NO_ACTIONS=1, steps around a rule that is misbehaving.
+# See docs/actions.md.
+actions:
+  # `task.started` is a transition rather than an operation: it fires when the
+  # task wasn't started before and is now, whatever caused it. It reads
+  # startedColumns above, so adding another started column doesn't break it.
+  - name: start-work
+    on: task.started
+    then:
+      - assign: '@me'
+      - addTag: active
+      - removeTag: ready
+
+  - name: close-out
+    on: task.completed
+    then:
+      - removeTag: active
+      - setProgress: 1
+      - set: { closedBy: '@me' }
+
+  # `reviewedAt` above is stamped by the column linkage; the rule runs after it,
+  # so it can see and override anything that stamping wrote.
+  - name: flag-review
+    on: task.moved
+    when:
+      toColumn: Review
+    then:
+      - addTag: needs-review
+      - comment: 'Review requested by @me'
+
+  # `for` points the verbs at related tasks instead of this one. Children carry
+  # the `child-of` relation, so `incoming` finds them from the epic.
+  - name: epic-blocks-children
+    on: task.moved
+    when:
+      tag: epic
+      toColumn: Blocked
+    for:
+      related: child-of
+      direction: incoming
+      where:
+        is-completed: false
+    then:
+      - addTag: blocked-by-epic
+
 # Custom fields (team, storyPoints, ...) can be interpolated here because they
 # are declared in customFields above. See docs/index-structure.md for the full
 # list of available variables.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basementuniverse/kanbn",
-  "version": "2.1.0",
+  "version": "2.5.1",
   "description": "A CLI Kanban application",
   "main": "index.js",
   "scripts": {

package/routes/add.json

@@ -6,7 +6,8 @@
   ],
   "args": {
     "boolean": [
-      "interactive"
+      "interactive",
+      "actions"
     ],
     "string": [
       "name",
@@ -55,6 +56,9 @@
       "board": [
         "b"
       ]
+    },
+    "default": {
+      "actions": true
     }
   },
   "controller": "./src/controller/add",

package/routes/archive.json

@@ -6,7 +6,8 @@
   ],
   "args": {
     "boolean": [
-      "list"
+      "list",
+      "actions"
     ],
     "alias": {
       "list": [
@@ -18,7 +19,10 @@
     },
     "string": [
       "board"
-    ]
+    ],
+    "default": {
+      "actions": true
+    }
   },
   "controller": "./src/controller/archive",
   "help": "./docs/commands/archive.txt"

package/routes/comment.json

@@ -6,7 +6,8 @@
   ],
   "args": {
     "boolean": [
-      "interactive"
+      "interactive",
+      "actions"
     ],
     "string": [
       "text",
@@ -25,6 +26,9 @@
       "board": [
         "b"
       ]
+    },
+    "default": {
+      "actions": true
     }
   },
   "controller": "./src/controller/comment",

package/routes/contributors.json

@@ -0,0 +1,18 @@
+{
+  "name": "Contributors",
+  "commands": [
+    "contributors"
+  ],
+  "args": {
+    "boolean": [
+      "json",
+      "usage"
+    ],
+    "alias": {
+      "json": ["j"],
+      "usage": ["u"]
+    }
+  },
+  "controller": "./src/controller/contributors",
+  "help": "./docs/commands/contributors.txt"
+}

package/routes/edit.json

@@ -6,7 +6,8 @@
   ],
   "args": {
     "boolean": [
-      "interactive"
+      "interactive",
+      "actions"
     ],
     "string": [
       "name",
@@ -56,6 +57,9 @@
       "board": [
         "b"
       ]
+    },
+    "default": {
+      "actions": true
     }
   },
   "controller": "./src/controller/edit",

package/routes/move.json

@@ -8,7 +8,8 @@
     "boolean": [
       "interactive",
       "relative",
-      "add"
+      "add",
+      "actions"
     ],
     "string": [
       "column",
@@ -33,7 +34,8 @@
       ]
     },
     "default": {
-      "add": true
+      "add": true,
+      "actions": true
     }
   },
   "controller": "./src/controller/move",

package/routes/remove.json

@@ -8,7 +8,8 @@
     "boolean": [
       "force",
       "index",
-      "all-boards"
+      "all-boards",
+      "actions"
     ],
     "alias": {
       "force": [
@@ -23,7 +24,10 @@
     },
     "string": [
       "board"
-    ]
+    ],
+    "default": {
+      "actions": true
+    }
   },
   "controller": "./src/controller/remove",
   "help": "./docs/commands/remove.txt"

package/routes/restore.json

@@ -16,6 +16,12 @@
       "board": [
         "b"
       ]
+    },
+    "boolean": [
+      "actions"
+    ],
+    "default": {
+      "actions": true
     }
   },
   "controller": "./src/controller/restore",

package/routes/sort.json

@@ -32,6 +32,11 @@
       "workload",
       "progress",
       "assigned",
+      "overdue",
+      "is-started",
+      "is-completed",
+      "in-started-column",
+      "in-completed-column",
       "board"
     ],
     "alias": {