artificery/dew
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
dew/docs/features/kanban.md
Chris Hendrickson 0ad1fae213 chore: 1.0 release prep 
Metadata:
- Bump dew CLI version 0.0.1 → 1.0.0
- Add repository + issue_tracker URLs to all pubspec.yaml files
- Switch inter-package path deps to versioned deps (^1.0.0)
- Remove publish_to: none from all packages
- Add MIT LICENSE to root and all packages
- Confirm all four pub.dev names available (dew, dew_core, dew_kanban, dew_mcp)

Documentation:
- Add CHANGELOG.md (Keep a Changelog format, full 1.0.0 feature history)
- Overhaul README.md (pitch, pub.dev badge, quick-start, feature sections)
- Add TUI section + full keybinding tables to docs/features/kanban.md
- Add CONTRIBUTING.md (setup, test, lint, branch strategy, command guide)

Tests:
- Add packages/cli/test/cli_test.dart (6 smoke tests)
- Add packages/kanban/test/integration_test.dart (6 TicketStore e2e tests)
- Expand packages/mcp/test/mcp_test.dart (5 tool registration tests)
- Add dew_kanban as dev dependency in packages/mcp/pubspec.yaml
- 57/57 tests passing

Code quality:
- dart format applied across all 23 changed source files
- dart analyze: zero errors, zero warnings

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-04-25 15:58:54 -04:00

180 lines
7.3 KiB
Markdown
Raw Blame History

# 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`.
Reference in a new issue View git blame Copy permalink