@basementuniverse/kanbn 2.5.0 → 2.5.1

package/docs/index-structure.md

@@ -223,7 +223,7 @@ Workspace-scoped. See [multiple boards](multiple-boards.md).
 
 ### `sprints`
 
-A list of sprints. Each sprint will have `start`, `name` and `description` properties.
+A list of sprints. Each sprint will have `start`, `name` and `description` properties. See [sprints](sprints.md).
 
 A board can declare its own `sprints` in its front matter, which **replaces** the workspace list for that board entirely. See [multiple boards](multiple-boards.md#per-board-sprints).
 

package/docs/index.md

@@ -13,6 +13,7 @@ To get started quickly, check out the [Quick Start](quick-start.md) guide.
 - [Contributors](contributors.md) — an optional list of who works on a workspace, and who "you" are
 - [Actions](actions.md) — declarative rules that fire when a task is created, moved, updated or finished
 - [Views](views.md) — custom board layouts, columns and lanes
+- [Sprints](sprints.md) — named time windows that `status`, `burndown` and `history` report through
 - [Filtering and Sorting](filtering-and-sorting.md) — the filter and sorter model shared by `find`, `sort` and views
 - [Advanced Configuration](advanced-configuration.md)
 - [Migrating to 2.0.0](migration-2.0.md) — separate config files and custom folder locations

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/package.json

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

package/src/main.js

@@ -4426,7 +4426,7 @@ class Kanbn {
           start: sprints[sprintIndex].start,
         };
         if (currentSprint - 1 !== sprintIndex) {
-          if (sprintIndex === sprints.length - 1) {
+          if (sprintIndex !== sprints.length - 1) {
             result.sprint.end = sprints[sprintIndex + 1].start;
           }
           result.sprint.current = currentSprint;