eric861129/kanban-markdown

Kanban Markdown

Manage kanban board features stored as markdown files with YAML frontmatter. Each feature is a .md file; the VS Code kanban-markdown extension renders them as a board.

File Format

Every feature file follows this exact format:

---
id: "my-feature-2026-02-20"
status: "backlog"
priority: "medium"
assignee: null
dueDate: null
created: "2026-02-20T10:00:00.000Z"
modified: "2026-02-20T10:00:00.000Z"
completedAt: null
labels: []
order: "a0"
---

# My Feature

Description and details here.

Serialization rules (must match exactly for the extension to parse correctly):

• String fields: always "double-quoted"
• Nullable fields (assignee, dueDate, completedAt): bare null when unset
• Labels: inline array ["bug", "ui"] or []
• Order: "double-quoted" string — fractional index for lexicographic sorting (see below)
• Field order: id, status, priority, assignee, dueDate, created, modified, completedAt, labels, order

Valid values:

• status: backlog | todo | in-progress | review | done
• priority: critical | high | medium | low

For full field specs, see references/data-model.md.

Features Directory

Default: .devtool/features/ relative to workspace root. Configurable via VS Code setting kanban-markdown.featuresDirectory.

• Active features (backlog, todo, in-progress, review): {featuresDir}/{id}.md
• Completed features (done): {featuresDir}/done/{id}.md

Fractional Index Ordering

The order field uses fractional indexing — lexicographically sortable strings that allow inserting between any two items without reindexing. The extension uses the fractional-indexing npm package internally.

When creating features, determine the order by reading existing features in the target column (sorted by order):

• If the column is empty: use "a0"
• To append after the last item: increment the trailing character — "a0" → "a1", "a1" → "a2", ..., "a9" → "aA", etc.
• The full character sequence is 0-9, A-Z, a-z (base-62, ASCII order)

When moving features via drag-and-drop, the extension computes fractional keys between neighbors automatically. The skill only needs to handle appending new features to the end of a column.

Creating Features

1. Generate ID: lowercase title, keep only a-z 0-9 - space, replace spaces with -, collapse multiple -, trim - from ends, truncate to 50 chars, append -YYYY-MM-DD. If empty, use feature-YYYY-MM-DD.
2. Set created and modified to current ISO timestamp. Set order by reading existing features in the target column and generating a key that sorts after the last one (see Fractional Index Ordering above).
3. If status is done, set completedAt to now and place in done/ subfolder.
4. Write frontmatter in exact field order above, then # Title and body.

Updating Features

• Always update modified to current ISO timestamp
• Never change id or created
• Preserve exact serialization format

Moving Features

Update status and modified. When crossing the done boundary:

• To done: set completedAt to current ISO timestamp, move file to done/ subfolder
• From done: set completedAt to null, move file back to root

Writing Content

Start with # Title (the extension extracts the display title from the first # heading). Use acceptance criteria checklists, notes, etc. as needed.