Steve Cliff
22d5848e1a
- Introduced `openspec-sync-specs` skill to sync delta specs to main specs, allowing intelligent merging of requirements. - Added `openspec-verify-change` skill to verify implementation against change artifacts, ensuring completeness, correctness, and coherence before archiving. docs: Create CLAUDE.md for project guidance - Added CLAUDE.md to provide an overview of the PCLI project, including build, test commands, architecture, and resource addition guidelines. chore: Add new change and design documents for project filter in status command - Created `.openspec.yaml`, `design.md`, `proposal.md`, and `tasks.md` for the `add-project-filter-to-status` change. - Updated specs for CLI commands and status command to include project filtering functionality. feat: Expand board included parsing in API client - Added parsing for `labels`, `cardLabels`, and `cardMemberships` in the `GetBoard` response. - Updated `ListCardsByBoard` to enrich card output with label names, enhancing usability in kanban sync workflows.
151 lines
4.7 KiB
Markdown
151 lines
4.7 KiB
Markdown
---
|
|
name: "Kanban"
|
|
description: "Manage Planka project boards using the pcli CLI"
|
|
category: Workflow
|
|
tags: [workflow, kanban, planka, project-management]
|
|
---
|
|
|
|
Manage Planka project boards using the `pcli` CLI. Use the kanban skill for detailed command reference.
|
|
|
|
## Prerequisites
|
|
|
|
Before running any commands, verify the environment is ready:
|
|
|
|
```bash
|
|
// turbo
|
|
pcli status
|
|
```
|
|
|
|
If this fails, ensure `PLANKA_URL` and `PLANKA_API_KEY` environment variables are set and `pcli` is in PATH.
|
|
|
|
---
|
|
|
|
## How to Use
|
|
|
|
**Input**: The argument after `/kanban` is what the user wants to do. Could be:
|
|
- A status check: "show me all boards" or "what's on my board"
|
|
- A board setup: "create a kanban board with todo, in progress, done columns"
|
|
- A list operation: "add a 'testing' column to my board" or "rename the done column"
|
|
- A card operation: "create a card for fixing the login bug"
|
|
- A board query: "list all cards in the backlog"
|
|
- A move: "move card X to done"
|
|
- A bulk operation: "move all cards from In Progress to Done"
|
|
- Nothing (show overall status)
|
|
|
|
---
|
|
|
|
## Responding to Requests
|
|
|
|
### 1. Understand the request
|
|
|
|
Map the user's intent to `pcli` commands. Use `pcli status` for overview requests. For specific operations, identify the resource (project, board, card, list, label, task, comment) and action (list, get, create, update, delete, move).
|
|
|
|
### 2. Discover IDs when needed
|
|
|
|
Most commands require IDs. Discover them by querying first:
|
|
|
|
```bash
|
|
# Find boards
|
|
pcli board list | jq '.data[] | {id, title}'
|
|
|
|
# Find lists on a board
|
|
pcli board get <board-id> | jq '.data.lists[] | {id, name}'
|
|
|
|
# Find cards on a list or board
|
|
pcli card list --board <board-id> | jq '.data[] | {id, name}'
|
|
pcli card list --list <list-id> | jq '.data[] | {id, name}'
|
|
```
|
|
|
|
Always use `jq` to extract and format output for readability.
|
|
|
|
### 3. Execute the operation
|
|
|
|
Run the appropriate `pcli` command. For create/update/delete operations, confirm with the user before executing unless the intent is unambiguous.
|
|
|
|
### 4. Report results
|
|
|
|
Show the user a concise summary of what happened. Use tables or formatted output when listing multiple items.
|
|
|
|
---
|
|
|
|
## Command Quick Reference
|
|
|
|
| Resource | Commands |
|
|
|----------|----------|
|
|
| **Status** | `pcli status` |
|
|
| **Projects** | `list`, `get`, `create`, `delete` |
|
|
| **Boards** | `list`, `get`, `actions`, `create`, `delete` |
|
|
| **Lists** | `create`, `get`, `update`, `delete` |
|
|
| **Cards** | `list`, `get`, `create`, `update`, `delete`, `duplicate`, `move`, `assign`, `unassign`, `add-label`, `remove-label`, `actions` |
|
|
| **Comments** | `list`, `create`, `update`, `delete` |
|
|
| **Task Lists** | `create`, `get`, `update`, `delete` |
|
|
| **Tasks** | `create`, `update`, `delete` |
|
|
| **Labels** | `create`, `update`, `delete` |
|
|
|
|
---
|
|
|
|
## Common Patterns
|
|
|
|
### Create a complete Kanban board
|
|
|
|
```bash
|
|
# Create board
|
|
BOARD_ID=$(pcli board create --project <project-id> --name "Development Board" | jq -r '.data.id')
|
|
|
|
# Create standard columns
|
|
pcli list create --board $BOARD_ID --name "Backlog" --type "active" --position 0
|
|
TODO_ID=$(pcli list create --board $BOARD_ID --name "To Do" --type "active" --position 65536 | jq -r '.data.id')
|
|
PROGRESS_ID=$(pcli list create --board $BOARD_ID --name "In Progress" --type "active" --position 131072 | jq -r '.data.id')
|
|
DONE_ID=$(pcli list create --board $BOARD_ID --name "Done" --type "closed" --position 196608 | jq -r '.data.id')
|
|
|
|
# View the completed board
|
|
pcli board get $BOARD_ID --format table
|
|
```
|
|
|
|
### Add a new column to existing board
|
|
|
|
```bash
|
|
# Find the board
|
|
BOARD_ID=$(pcli board list | jq -r '.data[] | select(.name == "Development Board") | .id')
|
|
|
|
# Add new column
|
|
pcli list create --board $BOARD_ID --name "Testing" --type "active" --position 163840
|
|
```
|
|
|
|
### Create a card with a checklist
|
|
|
|
```bash
|
|
CARD_ID=$(pcli card create --list <list-id> --name "Task" | jq -r '.data.id')
|
|
TL_ID=$(pcli task-list create --card $CARD_ID --name "Steps" | jq -r '.data.id')
|
|
pcli task create --task-list $TL_ID --name "Step 1"
|
|
pcli task create --task-list $TL_ID --name "Step 2"
|
|
```
|
|
|
|
### Move all cards between lists
|
|
|
|
```bash
|
|
pcli card list --list <source-list-id> | jq -r '.data[].id' | while read id; do
|
|
pcli card move $id --list <target-list-id>
|
|
done
|
|
```
|
|
|
|
### Extract IDs from output
|
|
|
|
```bash
|
|
# Single object
|
|
pcli card create --list <id> --name "X" | jq -r '.data.id'
|
|
|
|
# Array
|
|
pcli card list --board <id> | jq -r '.data[].id'
|
|
```
|
|
|
|
---
|
|
|
|
## Guardrails
|
|
|
|
- **Discover before acting** - Always query for IDs rather than guessing
|
|
- **Confirm destructive actions** - Ask before delete or bulk move operations
|
|
- **Use jq for output** - Parse JSON responses with `jq` for clean, readable results
|
|
- **Show context** - When listing cards, include the list/board name for context
|
|
- **Global flags** - All commands accept `--format json|table` for output format
|