# Kanban

> Create and maintain factual, self-contained offline Kanban project boards from a JSON source of truth. Use when a user asks to visualize project work, add or move project cards, generate a portable board, or maintain a Kanban status view across projects.

- Skill: `dennisonbertram/kanban` (Agent Skill, multi-file: 14 files)
- Install (CLI): `npx skillmds@latest add dennisonbertram/kanban`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dennisonbertram/kanban/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: dennisonbertram (https://skillmd.com/u/dennisonbertram)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/dennisonbertram/kanban

---


# Kanban board

Use `scripts/kanban.mjs` as the shared renderer. Do not hand-edit generated HTML.

## Workflow

1. Create or update a `kanban.json` in the target project. Treat it as the source of truth: never invent cards, themes, notes, links, or column assignments.
2. Install the managed lifecycle block into the project-root `CLAUDE.md` for Claude Code and `AGENTS.md` for Codex. Use `scripts/install-lifecycle.mjs <project-directory> --agent claude|codex|both`; it preserves existing instructions and replaces an existing marked block instead of duplicating it.
3. Use `workflow.planning`, `workflow.active`, `workflow.review`, and `workflow.completed` to map lifecycle events to the project's actual columns. If `workflow` is missing, ask for or establish the mappings before moving a card; do not guess based on a column name.
4. Build the board:

   ```sh
   /path/to/kanban/scripts/kanban build kanban.json --out kanban.html
   ```

5. At work start, launch the local board server in the background. It selects an available random port and opens the browser for the user:

   ```sh
   mkdir -p .kanban
   /path/to/kanban/scripts/kanban build kanban.json --out .kanban/board.html
   node /path/to/kanban/scripts/serve.mjs .kanban/board.html > .kanban/server.log 2>&1 &
   ```

   Read `.kanban/server.log` and report the `Kanban board:` URL. Rebuild `.kanban/board.html` and reload the same local URL whenever the board changes.
6. Open `kanban.html` locally and inspect filters, search, and card expansion after a meaningful update.
7. Commit the data file with the generated board when the project wants a shareable snapshot.

## Data model

Use JSON. Required shape:

```json
{
  "title": "Project Board",
  "description": "What this board covers and how to read it.",
  "headerNote": "Snapshot: accurate as of 2026-08-16.",
  "columns": ["Backlog", "In progress", "Done"],
  "columnDescriptions": { "Backlog": "Known work not yet started." },
  "columnColors": { "Backlog": "#8b5cf6" },
  "workflow": { "planning": "Backlog", "active": "In progress", "completed": "Done" },
  "themes": { "product": "#8b5cf6", "ops": "#22c55e" },
  "cards": [
    { "id": "api-1", "title": "Add API", "theme": "product", "column": "In progress", "note": "Blocked on schema review.", "link": "https://example.test/issues/1" }
  ]
}
```

`title`, `description`, `headerNote`, `columnDescriptions`, `columnColors`, `workflow`, `note`, and `link` are optional. Use `description` and `columnDescriptions` to give viewers factual context; use `columnColors` for meaningful workflow color coding. `workflow` maps planning, active, review, and completed work to declared columns so agents do not infer statuses. `id` must be unique. A card theme and column must exist in `themes` and `columns` respectively. Use a complete `https://` or project-relative link when adding `link`.

## Agent lifecycle

Follow the managed block in [references/kanban-workflow.md](references/kanban-workflow.md). Update `kanban.json` and regenerate the HTML at four factual points: before planning, after a plan exists, when material work starts, and before handing off. Do not update the board when there is no relevant board/card or when the status would be speculative.

## Commands

```sh
# Validate the data without writing HTML
/path/to/kanban/scripts/kanban validate kanban.json

# Write a self-contained board
/path/to/kanban/scripts/kanban build kanban.json --out docs/kanban.html

# Build and open with the platform's default browser
/path/to/kanban/scripts/kanban build kanban.json --out kanban.html --open
```

The output contains no external assets, fonts, scripts, or data fetches. Rerunning `build` from unchanged JSON must reproduce the same board.