180 lines
7.5 KiB
Markdown
180 lines
7.5 KiB
Markdown
# Dew Kanban Board
|
|
|
|
The Dew Kanban Board lets you create and manage tickets across a set of configurable columns. Every command is also registered as an MCP tool, so AI agents can interact with the board using the same operations as the CLI.
|
|
|
|
## Storage layout
|
|
|
|
Tickets live inside the `.project/kanban/` directory. Each column has its own subdirectory, and attachments are stored separately by ticket ID so they survive column moves:
|
|
|
|
```text
|
|
.project/
|
|
└── kanban/
|
|
├── backlog/
|
|
│ └── DEW-0001.md
|
|
├── doing/
|
|
│ └── DEW-0002.md
|
|
├── done/
|
|
│ └── DEW-0003.md
|
|
├── archive/ ← soft-deleted tickets (future)
|
|
└── attachments/
|
|
└── DEW-0001/ ← per-ticket attachment directory
|
|
└── screenshot.png
|
|
```
|
|
|
|
## Ticket format
|
|
|
|
Each ticket is a Markdown file with a YAML frontmatter block. The column is derived from the containing directory and is not stored redundantly in the file.
|
|
|
|
```markdown
|
|
---
|
|
id: DEW-0001
|
|
title: "My ticket"
|
|
type: story
|
|
created: 2026-04-23T19:00:00.000Z
|
|
links:
|
|
- id: DEW-0002
|
|
type: blocks
|
|
---
|
|
|
|
Body text goes here.
|
|
|
|
---
|
|
|
|
First comment.
|
|
|
|
---
|
|
|
|
Second comment.
|
|
```
|
|
|
|
## CLI commands
|
|
|
|
All commands are available under `dew kanban <subcommand>`.
|
|
|
|
| Subcommand | Description |
|
|
| ----------- | ----------------------------------------------------------------------------------- |
|
|
| `create` | Create a new ticket (`--title`, `--type`, `--column`, `--body`) |
|
|
| `list` | List tickets (`--column`, `--type`, `--label`, `--milestone`, `--include-archived`) |
|
|
| `get` | Get a ticket by ID (`--id`) |
|
|
| `update` | Update fields on a ticket (`--id`, `--title`, `--type`, `--column`, `--body`) |
|
|
| `delete` | Delete a ticket permanently (`--id`) |
|
|
| `move` | Move a ticket to a different column (`--id`, `--column`) |
|
|
| `search` | Full-text search across all ticket content (`--query`, `--include-archived`) |
|
|
| `comment` | Append a comment to a ticket (`--id`, `--comment`) |
|
|
| `archive` | Soft-delete a ticket by moving it to the archive column (`--id`) |
|
|
| `unarchive` | Restore an archived ticket to a column (`--id`, `--column`) |
|
|
| `link` | Link two tickets with a typed relationship (`--id`, `--target`, `--type`) |
|
|
| `unlink` | Remove a link between two tickets (`--id`, `--target`) |
|
|
| `stats` | Show ticket counts by column and type |
|
|
| `board` | Print an ASCII representation of the board |
|
|
| `config` | Print the current kanban configuration |
|
|
| `tui` | Launch the interactive terminal UI |
|
|
|
|
## Ticket links
|
|
|
|
Links are typed and bidirectional — writing one side automatically writes the inverse on the target.
|
|
|
|
| Type | Inverse | Use case |
|
|
| ------------ | ------------------ | -------------------------------- |
|
|
| `blocks` | `is_blocked_by` | Dependency between tickets |
|
|
| `relates_to` | `relates_to` | General relationship (symmetric) |
|
|
| `duplicates` | `is_duplicated_by` | Duplicate ticket tracking |
|
|
| `parent_of` | `child_of` | Epic → story → task hierarchy |
|
|
|
|
## Configuration
|
|
|
|
Columns, ticket types, and the ticket ID prefix are configured in `.project/dew.yaml`:
|
|
|
|
```yaml
|
|
dew:
|
|
kanban:
|
|
prefix: "DEW"
|
|
ticket_types:
|
|
- id: epic
|
|
name: Epic
|
|
- id: story
|
|
name: Story
|
|
columns:
|
|
- id: backlog
|
|
name: Backlog
|
|
color: blue
|
|
- id: doing
|
|
name: Doing
|
|
color: yellow
|
|
- id: done
|
|
name: Done
|
|
color: green
|
|
```
|
|
|
|
See the [Configuration documentation](../config.md) for the full schema reference.
|
|
|
|
## Interactive TUI
|
|
|
|
Launch the interactive terminal board with:
|
|
|
|
```bash
|
|
dew kanban tui
|
|
```
|
|
|
|
The TUI has three modes. Press **F1** in any mode for a context-sensitive help overlay.
|
|
|
|
### Modes
|
|
|
|
| Mode | How to enter | How to leave |
|
|
| ---------- | ---------------------------------- | ------------------------ |
|
|
| **Board** | Default on launch | `q` to quit |
|
|
| **Detail** | Press `Enter` on a ticket in Board | `b` or `Esc` |
|
|
| **Editor** | Press `e` in Board or Detail mode | `s` save / `Esc` discard |
|
|
|
|
### Keybinding reference
|
|
|
|
#### Board mode
|
|
|
|
| Key | Action |
|
|
| --------- | ------------------------------------------------------ |
|
|
| `↑` / `↓` | Navigate tickets within the current column |
|
|
| `←` / `→` | Switch to the previous / next column |
|
|
| `<` / `>` | Move the selected ticket to the previous / next column |
|
|
| `Enter` | Open Detail view for the selected ticket |
|
|
| `n` | Create a new ticket (opens Editor) |
|
|
| `e` | Edit the selected ticket (opens Editor) |
|
|
| `a` | Archive the selected ticket |
|
|
| `D` | Delete the selected ticket (with confirmation) |
|
|
| `c` | Append a comment to the selected ticket |
|
|
| `L` | Link the selected ticket to another ticket |
|
|
| `?` | Open the live filter / search overlay |
|
|
| `F1` | Toggle the help overlay |
|
|
| `q` | Quit |
|
|
|
|
#### Detail mode
|
|
|
|
| Key | Action |
|
|
| ----------- | ------------------------------ |
|
|
| `↑` / `↓` | Scroll the ticket content |
|
|
| `e` | Edit the ticket (opens Editor) |
|
|
| `b` / `Esc` | Return to Board mode |
|
|
| `F1` | Toggle the help overlay |
|
|
| `q` | Quit |
|
|
|
|
#### Editor mode
|
|
|
|
| Key | Action |
|
|
| --------- | ------------------------------------------------------------------------ |
|
|
| `↑` / `↓` | Move between fields |
|
|
| `←` / `→` | Cycle through selector values (type, column) |
|
|
| `Enter` | Edit the focused text field inline, or open `$VISUAL`/`$EDITOR` for body |
|
|
| `d` | Delete the current item (e.g. remove a label) |
|
|
| `s` | Save changes and return to the previous mode |
|
|
| `Esc` | Discard changes and return to the previous mode |
|
|
| `F1` | Toggle the help overlay |
|
|
|
|
> **Body editing:** pressing `Enter` on the body field suspends the TUI and opens
|
|
> `$VISUAL` or `$EDITOR` (falling back to `vi`) so you can write long-form content
|
|
> in your preferred editor. The TUI resumes once you save and exit.
|
|
|
|
### Auto-refresh
|
|
|
|
The board watches the `.project/kanban/` directory for file-system events and
|
|
reloads automatically when ticket files are created, modified, or deleted — so
|
|
the view stays live whether changes come from another terminal session, a
|
|
`git pull`, or an AI agent running `dew mcp serve`.
|