@basementuniverse/kanbn 1.0.0 → 1.1.0

package/README.md

@@ -34,10 +34,12 @@ Where <command> is one of:
   sort .......... Sort a column in the index
   sprint ........ Start a new sprint
   burndown ...... View a burndown chart
+  gantt ......... Generate and view a Gantt chart
   validate ...... Validate index and task files
   archive ....... Archive a task
   restore ....... Restore a task from the archive
   remove-all .... Remove the kanbn board and all tasks
+  history ....... Show task history
 
 For more help with commands, try:
 

package/docs/commands/gantt.txt

@@ -3,14 +3,10 @@
 
 Show a gantt chart for tracked tasks.
 
-Tasks are ordered using `depends-on` relations when present. The chart uses task dates, workload, and the optional
-`postponed` metadata field to estimate when work can start.
+Tasks are ordered using `depends-on` relations when present. The chart prioritizes optional `plannedStart`/`plannedFinish` metadata when arranging bars, then falls back through `started`/`completed` dates, and finally uses workload-based best-effort scheduling when no timeline dates are available.
 The rendered chart includes:
-  • A unified date axis at the bottom for easy time reference
-  • A vertical "now" line marking the current date (if within the chart range)
-  • Dependency arrows (└─→) showing which tasks depend on others
-  • Task bars with progress indicators: █ (completed), ▓ (in progress), ░ (not started)
-  • A blocked indicator (⧗) showing tasks delayed by dependencies
+  Dependency arrows (└─→) showing which tasks depend on others
+  A blocked indicator (⧗) showing tasks delayed by dependencies
 
 Options:
   {b}kanbn gantt --json{b}

package/docs/commands/history.txt

@@ -0,0 +1,29 @@
+{b}kanbn history{b}
+{b}kanbn hi{b}
+
+Show a chronological listing of task events.
+
+Options:
+  {b}kanbn history --json{b}
+  {b}kanbn history -j{b}
+    Output raw history data in JSON format.
+
+  {b}kanbn history --sprint N|"name"{b}
+  {b}kanbn history -p N|"name"{b}
+    Filter history to one or more sprints.
+    This option can be repeated to include multiple sprints.
+
+  {b}kanbn history --date "date"{b}
+  {b}kanbn history -d "date"{b}
+    Filter history by date.
+    If one date is provided, show history from this date up to the present date.
+    If two or more dates are provided, show history from the earliest to latest date.
+
+  {b}kanbn history --assigned "user"{b}
+  {b}kanbn history -a "user"{b}
+    Filter for tasks assigned to a specific user.
+
+  {b}kanbn history --task "task-id"{b}
+  {b}kanbn history -t "task-id"{b}
+    Filter for one or more task ids.
+    This option can be repeated.

package/docs/task-structure.md

@@ -13,7 +13,8 @@ progress: 0.5
 started: 2021-03-21T04:58:38.653Z
 completed: 2021-03-21T04:58:38.653Z
 due: 2021-03-21T04:58:38.653Z
-postponed: 2021-03-20T04:58:38.653Z
+plannedStart: 2021-03-20T04:58:38.653Z
+plannedFinish: 2021-03-24T04:58:38.653Z
 ---
 
 # Task Name
@@ -117,10 +118,13 @@ The date and time that the task was completed.
 
 The date and time that the task is due to be completed.
 
-### `postponed`
+### `plannedStart`
 
-The date and time after which the task should be scheduled. Gantt chart rendering uses this value as an explicit
-start-floor when present.
+An optional date and time used as a preferred start point for gantt scheduling.
+
+### `plannedFinish`
+
+An optional date and time used as a preferred finish point for gantt scheduling.
 
 ## Sub-tasks
 

package/example/.kanbn/index.md

@@ -1,18 +1,21 @@
 ---
 startedColumns:
-  - In Progress
+  - 'In Progress'
 completedColumns:
   - Done
 sprints:
-  - start: 2026-05-06T09:00:00.000Z
-    name: Foundation Sprint
-    description: Baseline product and infrastructure work.
-  - start: 2026-06-10T09:00:00.000Z
-    name: Workflow Sprint
-    description: Core team workflow and onboarding features.
-  - start: 2026-07-08T09:00:00.000Z
-    name: Stabilisation Sprint
-    description: Reliability and release readiness improvements.
+  -
+    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'
+    description: 'Core team workflow and onboarding features.'
+  -
+    start: 2026-07-15T09:00:00.000Z
+    name: 'Stabilisation Sprint'
+    description: 'Reliability and release readiness improvements.'
 taskWorkloadTags:
   Tiny: 1
   Small: 2

package/example/.kanbn/tasks/build-invoice-download-endpoint.md

@@ -1,11 +1,13 @@
 ---
 created: 2026-07-05T10:00:00.000Z
-updated: 2026-07-06T10:00:00.000Z
+updated: 2026-07-24T22:28:06.841Z
 tags:
   - Platform
   - Medium
 progress: 0
 due: 2026-07-07T10:00:00.000Z
+plannedStart: 2026-07-06T14:05:13.527Z
+plannedFinish: 2026-07-11T11:20:37.323Z
 ---
 
 # Build Invoice Download Endpoint

package/example/.kanbn/tasks/create-self-serve-cancellation-flow.md

@@ -6,7 +6,7 @@ tags:
   - Large
 progress: 0
 due: 2026-07-11T10:00:00.000Z
-postponed: 2026-07-20T10:00:00.000Z
+plannedStart: 2026-07-20T10:00:00.000Z
 ---
 
 # Create Self-serve Cancellation Flow

package/example/.kanbn/tasks/optimize-dashboard-first-load.md

@@ -8,7 +8,7 @@ assigned: Ava
 progress: 0.4
 started: 2026-07-06T10:00:00.000Z
 due: 2026-07-07T10:00:00.000Z
-postponed: 2026-07-22T10:00:00.000Z
+plannedStart: 2026-07-22T10:00:00.000Z
 ---
 
 # Optimize Dashboard First Load

package/example/.kanbn/tasks/prototype-report-export-scheduler.md

@@ -6,7 +6,7 @@ tags:
   - Large
 progress: 0
 due: 2026-07-07T10:00:00.000Z
-postponed: 2026-07-18T10:00:00.000Z
+plannedStart: 2026-07-18T10:00:00.000Z
 ---
 
 # Prototype Report Export Scheduler

package/package.json

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

package/routes/add.json

@@ -16,6 +16,8 @@
       "tag",
       "relation",
       "due",
+      "plannedStart",
+      "plannedFinish",
       "progress"
     ],
     "alias": {

package/routes/edit.json

@@ -19,6 +19,8 @@
       "relation",
       "remove-relation",
       "due",
+      "plannedStart",
+      "plannedFinish",
       "progress"
     ],
     "alias": {

package/routes/find.json

@@ -28,6 +28,8 @@
       "started",
       "completed",
       "due",
+      "plannedStart",
+      "plannedFinish",
       "workload",
       "progress",
       "assigned"

package/routes/history.json

@@ -0,0 +1,27 @@
+{
+	"name": "Task History",
+	"commands": [
+		"history",
+		"hi"
+	],
+	"args": {
+		"boolean": [
+			"json"
+		],
+		"string": [
+			"date",
+			"sprint",
+			"assigned",
+			"task"
+		],
+		"alias": {
+			"json": ["j"],
+			"date": ["d"],
+			"sprint": ["p"],
+			"assigned": ["a"],
+			"task": ["t"]
+		}
+	},
+	"controller": "./src/controller/history",
+	"help": "./docs/commands/history.txt"
+}

package/routes/sort.json

@@ -27,6 +27,8 @@
       "started",
       "completed",
       "due",
+      "plannedStart",
+      "plannedFinish",
       "workload",
       "progress",
       "assigned"

package/skills/kanbn-plan/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: kanbn-plan
+description: Turn a project brief into Kanbn planning artifacts only. Use this skill to generate or revise a Kanbn board index and task markdown files, including task descriptions, sub-tasks, and dependency relationships, without implementing the project itself.
+---
+
+# Kanbn Plan
+
+Use this skill when the user wants project planning output in Kanbn format: a board, task files, dependencies, sequencing, scope breakdown, and task descriptions.
+
+Do not use this skill to implement the project, edit source code, scaffold files outside `.kanbn/`, or estimate progress from work that has not happened yet.
+
+## Core Contract
+
+Your output must stay inside the Kanbn planning surface:
+
+- `.kanbn/index.md`
+- `.kanbn/tasks/*.md`
+
+Do not create application code, tests, CI files, or documentation unrelated to the Kanbn board.
+
+If the user asks for planning plus implementation, complete the planning portion in Kanbn format first and keep the planning files cleanly separated from any later work.
+
+## Planning Goals
+
+Produce a board that is both valid and useful:
+
+- Break vague requirements into concrete, reviewable tasks.
+- Capture prerequisite relationships with Kanbn relations.
+- Preserve important scope, assumptions, risks, and milestones in task descriptions.
+- Avoid invented execution history such as fake progress, comments, timestamps, or completed work.
+- Keep the plan maintainable so a human can reprioritise it later.
+
+## Workflow
+
+### 1. Extract scope before writing files
+
+From the user prompt or specification, identify:
+
+- project goal
+- major workstreams or epics
+- prerequisites and external dependencies
+- constraints, risks, and open questions
+- any explicit milestones, deadlines, or sequencing requirements
+
+If the prompt is underspecified, make minimal planning assumptions and state them in the index description or in task descriptions where relevant.
+
+### 2. Choose a board shape
+
+If the user does not specify columns, default to Kanbn's standard workflow:
+
+- `Backlog`
+- `Todo`
+- `In Progress`
+- `Done`
+
+And default options:
+
+- `startedColumns: ["In Progress"]`
+- `completedColumns: ["Done"]`
+
+Use extra columns only when the project brief clearly benefits from them, for example `Review`, `Testing`, `Release`, or domain-specific approval states.
+
+Do not use columns to model architecture layers, epics, or teams when tags or task descriptions would be more appropriate. Columns should represent workflow state.
+
+### 3. Decompose into actionable tasks
+
+Each generated task should be:
+
+- small enough to complete as one coherent unit of work
+- specific enough that another agent or engineer can act on it later
+- named by outcome, not by vague area labels
+- independent where possible, but explicitly linked when not
+
+Prefer imperative or outcome-focused names such as:
+
+- `Define authentication flow`
+- `Create database migration plan`
+- `Document deployment rollback steps`
+
+Avoid umbrella task names such as:
+
+- `Backend`
+- `Frontend work`
+- `Finish project`
+
+### 4. Model dependencies carefully
+
+Use the relations section to encode sequencing.
+
+Preferred relation types:
+
+- `depends-on`: the current task cannot start until the referenced task is complete
+- `blocks`: the current task prevents the referenced task from starting or finishing
+
+Important rules:
+
+- Use one direction per dependency edge. Do not create both `depends-on A` and `blocks B` for the same relationship unless the user explicitly asks for mirrored wording.
+- Do not create self-references.
+- Do not create cycles.
+- Other relation types such as `duplicates` or `obsoletes` are allowed, but they are not scheduling dependencies.
+
+Kanbn's gantt dependency logic only treats `depends-on` and `blocks` as dependency edges.
+
+### 5. Write lean metadata
+
+Only include metadata when it is grounded in the prompt or materially useful.
+
+Safe defaults:
+
+- omit YAML front matter entirely when no metadata is needed
+- omit `created`, `updated`, `started`, `completed`, `progress`, `comments`, and `history`
+- omit `assigned` unless the user supplied owners
+- omit `due` unless the user supplied a deadline
+
+Useful optional metadata:
+
+- `tags` for epics, domains, or sizing labels
+- custom fields only if the board already defines them
+
+### 6. Place tasks in columns intentionally
+
+For a fresh plan, use this default placement strategy unless the user specifies otherwise:
+
+- put ready, near-term tasks with no unresolved prerequisites in `Todo`
+- put deferred or dependency-blocked tasks in `Backlog`
+- leave `In Progress` and `Done` empty unless the user explicitly says work has already started or finished
+
+Do not fabricate active work.
+
+### 7. Validate before finalising
+
+Before presenting the plan, validate it if the environment allows.
+
+Use these helper files from this skill when available:
+
+- `references/index-structure.md`
+- `references/task-structure.md`
+- `references/planning-rules.md`
+- `scripts/validate-kanbn.mjs`
+- `scripts/check-dependency-cycles.mjs`
+
+Validation sequence:
+
+1. Ensure `.kanbn/index.md` uses valid headings and task links.
+2. Ensure each task file has a valid title, description, and any reserved sections in the correct format.
+3. Run the validate wrapper.
+4. Run the dependency cycle checker.
+5. Fix any structural or dependency issues before stopping.
+
+## Output Standards
+
+### Index requirements
+
+The index must:
+
+- contain exactly one level-1 project heading
+- contain optional description text directly under the project heading
+- define workflow columns with level-2 headings
+- list task ids as markdown links to `tasks/<task-id>.md`
+
+### Task requirements
+
+Each task file must:
+
+- live at `.kanbn/tasks/<task-id>.md`
+- contain exactly one top-level heading with the human-readable task name
+- include a description tailored to the task
+- use reserved headings correctly when present: `Metadata`, `Sub-tasks`, `Relations`, `Comments`, `History`
+
+Descriptions should usually include:
+
+- the purpose of the task
+- key scope boundaries
+- expected deliverable or outcome
+- acceptance criteria or completion signals when useful
+
+### Task id rules
+
+Use stable kebab-case ids derived from the task name.
+
+Examples:
+
+- `Set up CI pipeline` -> `set-up-ci-pipeline`
+- `Plan data retention policy` -> `plan-data-retention-policy`
+
+## When Revising An Existing Board
+
+If `.kanbn/` already exists:
+
+- preserve the existing board structure unless the user asked to redesign it
+- preserve existing custom fields and option conventions
+- avoid rewriting unrelated tasks
+- add or edit only the planning artifacts needed for the requested plan change
+
+## References
+
+Use these files as the source of truth while authoring:
+
+- `references/index-structure.md` for `.kanbn/index.md`
+- `references/task-structure.md` for `.kanbn/tasks/*.md`
+- `references/planning-rules.md` for decomposition and dependency heuristics
+
+## Success Criteria
+
+This skill is successful when it produces a Kanbn board that:
+
+- accurately reflects the requested project scope
+- is structurally valid
+- contains actionable tasks instead of vague placeholders
+- captures dependency order without cycles
+- does not stray into implementation work

package/skills/kanbn-plan/references/index-structure.md

@@ -0,0 +1,89 @@
+# Kanbn Index Reference
+
+This reference describes the structure expected for `.kanbn/index.md` when generating a project plan.
+
+## Minimum Valid Shape
+
+```markdown
+---
+startedColumns:
+  - In Progress
+completedColumns:
+  - Done
+---
+
+# Project Name
+
+Short project summary and planning assumptions.
+
+## Backlog
+
+- [task-id-1](tasks/task-id-1.md)
+- [task-id-2](tasks/task-id-2.md)
+
+## Todo
+
+- [task-id-3](tasks/task-id-3.md)
+
+## In Progress
+
+## Done
+```
+
+## Rules
+
+- The file may begin with YAML front matter.
+- There must be exactly one level-1 heading for the project name.
+- Text under the project heading is the project description.
+- After the description, each level-2 heading defines a column.
+- Each column should contain a markdown list of task links.
+- Each task link should point to `tasks/<task-id>.md`.
+- The link text should be the task id, not the human-readable title.
+
+## Recommended Defaults
+
+If the user does not specify a workflow, prefer:
+
+```yaml
+startedColumns:
+  - In Progress
+completedColumns:
+  - Done
+```
+
+And columns:
+
+- `Backlog`
+- `Todo`
+- `In Progress`
+- `Done`
+
+## Placement Guidance
+
+- Put tasks in `Todo` only if they are ready to start and not obviously blocked.
+- Put blocked, later-phase, or lower-priority work in `Backlog`.
+- Leave `In Progress` empty for a newly generated plan unless the prompt explicitly says work is underway.
+- Leave `Done` empty unless the prompt explicitly references completed work.
+
+## Options Worth Using
+
+Only add options when they are meaningful.
+
+Commonly useful options:
+
+- `startedColumns`
+- `completedColumns`
+- `hiddenColumns`
+- `taskWorkloadTags`
+- `defaultTaskWorkload`
+- `customFields`
+
+Avoid adding large option blocks that the user did not ask for.
+
+## Common Mistakes
+
+- Using headings inside the project description.
+- Listing bare task ids instead of markdown links.
+- Linking to the wrong path, for example `./tasks/...` or absolute paths.
+- Treating columns as epics or teams instead of workflow states.
+- Populating `In Progress` or `Done` with speculative work states.

package/skills/kanbn-plan/references/planning-rules.md

@@ -0,0 +1,58 @@
+# Planning Rules
+
+Use these heuristics when turning a prompt into Kanbn planning artifacts.
+
+## Decomposition Heuristics
+
+- Split by deliverable, decision, integration point, or risk area.
+- Prefer tasks that produce one observable planning outcome.
+- Separate discovery work from execution work when the unknowns are material.
+- Separate prerequisite setup from dependent feature work.
+- Separate cross-cutting concerns such as security, observability, migration, or rollout planning when they would otherwise disappear into feature tasks.
+
+## Task Granularity
+
+Aim for tasks that are:
+
+- independently understandable
+- narrow enough to estimate or assign later
+- broad enough to avoid an explosion of trivial tasks
+
+If a task description needs multiple unrelated deliverables, split it.
+
+## Dependency Rules
+
+- Add dependencies only when order materially matters.
+- Prefer `depends-on` over ad hoc wording because Kanbn already understands it for scheduling.
+- Use `blocks` when it reads more naturally from the prerequisite task.
+- Do not encode the same dependency twice in opposite directions unless the user wants mirrored relations.
+- Avoid diamond-shaped dependency graphs when a simpler linear or fan-out structure is more accurate.
+
+## Prioritisation Rules
+
+- Put foundational work before feature-specific work.
+- Put architecture and interface decisions before implementation-heavy downstream tasks.
+- Put risk-reduction tasks earlier when they can invalidate later work.
+- Keep optional enhancements, stretch goals, and nice-to-haves in `Backlog`.
+
+## Naming Rules
+
+- Use explicit outcome-oriented titles.
+- Prefer verbs like `Define`, `Plan`, `Document`, `Design`, `Map`, `Specify`, `Assess`, `Prepare`.
+- Avoid names that just restate a subsystem with no action.
+
+## Assumption Rules
+
+- Do not invent deadlines, owners, or progress.
+- If the prompt leaves a critical planning choice unresolved, capture it as an assumption or an explicit planning task.
+- If the board already exists, preserve its conventions unless the user asks to change them.
+
+## Final Review Checklist
+
+Before finalising a generated board, confirm:
+
+- every task in the index has a corresponding task file
+- every relation points to an existing task id
+- the dependency graph has no cycles
+- task descriptions are specific enough to guide later execution
+- the board contains planning artifacts only, not implementation work