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:

   /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:

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:

{
  "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. 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

# 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.