Added list management commands, board filtering by project name, and enhanced skill documentation with bootstrap workflow and error handling patterns. Also added plumbing in to "pcli" binary for status syncing with Planka
This commit is contained in:
Steve Cliff
@@ -0,0 +1,170 @@
|
||||
---
|
||||
name: example-skill
|
||||
description: Manage Planka project boards using the pcli CLI. Use when the user wants to interact with Planka boards, cards, lists, tasks, labels, or comments.
|
||||
compatibility: Requires pcli binary in PATH and PLANKA_URL + PLANKA_API_KEY environment variables set
|
||||
metadata:
|
||||
author: steve-cliff
|
||||
version: "1.0"
|
||||
---
|
||||
|
||||
# pcli - Planka CLI
|
||||
|
||||
CLI for the Planka project management API. All commands return JSON by default with envelope `{"data": ..., "error": null}`. Use `jq` to extract fields.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Ensure environment variables are set:
|
||||
```bash
|
||||
export PLANKA_URL="https://planka.example.com"
|
||||
export PLANKA_API_KEY="your-api-key"
|
||||
```
|
||||
|
||||
Ensure `jq` is installed.
|
||||
|
||||
## Global Flags
|
||||
|
||||
All commands accept: `--format json|table`, `--url <url>`, `--api-key <key>`, `--log-level debug|info|warn|error`
|
||||
|
||||
## Commands
|
||||
|
||||
### Status Overview
|
||||
|
||||
```bash
|
||||
pcli status
|
||||
```
|
||||
|
||||
Returns summary of all boards, lists, and card counts (open/closed per list).
|
||||
|
||||
### Projects
|
||||
|
||||
```bash
|
||||
pcli project list
|
||||
pcli project get <project-id>
|
||||
```
|
||||
|
||||
### Boards
|
||||
|
||||
```bash
|
||||
pcli board list
|
||||
pcli board get <board-id> # includes lists and cards
|
||||
pcli board actions <board-id> [--limit N]
|
||||
pcli board create --project <project-id> --name "Board Name" [--position N]
|
||||
pcli board delete <board-id>
|
||||
```
|
||||
|
||||
### Lists (Board Columns)
|
||||
|
||||
```bash
|
||||
pcli list create --board <board-id> --name "Column Name" [--type active|closed] [--position N]
|
||||
pcli list get <list-id>
|
||||
pcli list update <list-id> [--name "..."] [--type active|closed] [--color "..."] [--position N] [--board <board-id>]
|
||||
pcli list delete <list-id>
|
||||
```
|
||||
|
||||
### Cards
|
||||
|
||||
```bash
|
||||
# List (one of --board or --list required, mutually exclusive)
|
||||
pcli card list --board <board-id> [--limit N]
|
||||
pcli card list --list <list-id> [--limit N]
|
||||
|
||||
# CRUD
|
||||
pcli card get <card-id>
|
||||
pcli card create --list <list-id> --name "Name" [--description "..."] [--type project|story] [--position N] [--due-date "ISO8601"] [--due-completed]
|
||||
pcli card update <card-id> [--name "..."] [--description "..."] [--type ...] [--position N] [--due-date "..."] [--due-completed]
|
||||
pcli card delete <card-id>
|
||||
pcli card duplicate <card-id> --name "Copy" [--position N]
|
||||
pcli card move <card-id> --list <target-list-id> [--position N]
|
||||
|
||||
# Members
|
||||
pcli card assign <card-id> --user <user-id>
|
||||
pcli card unassign <card-id> --user <user-id>
|
||||
|
||||
# Labels
|
||||
pcli card add-label <card-id> --label <label-id>
|
||||
pcli card remove-label <card-id> --label <label-id>
|
||||
|
||||
# Actions
|
||||
pcli card actions <card-id> [--limit N]
|
||||
```
|
||||
|
||||
### Comments
|
||||
|
||||
```bash
|
||||
pcli comment list --card <card-id> [--limit N]
|
||||
pcli comment create --card <card-id> --text "..."
|
||||
pcli comment update <comment-id> --text "..."
|
||||
pcli comment delete <comment-id>
|
||||
```
|
||||
|
||||
### Task Lists
|
||||
|
||||
```bash
|
||||
pcli task-list create --card <card-id> --name "Checklist" [--position N] [--show-on-front] [--hide-completed]
|
||||
pcli task-list get <task-list-id>
|
||||
pcli task-list update <task-list-id> [--name "..."] [--position N] [--show-on-front] [--hide-completed]
|
||||
pcli task-list delete <task-list-id>
|
||||
```
|
||||
|
||||
### Tasks
|
||||
|
||||
```bash
|
||||
pcli task create --task-list <task-list-id> --name "Item" [--position N] [--completed]
|
||||
pcli task update <task-id> [--name "..."] [--position N] [--completed]
|
||||
pcli task delete <task-id>
|
||||
```
|
||||
|
||||
### Labels
|
||||
|
||||
```bash
|
||||
pcli label create --board <board-id> --name "Bug" --color "berry-red" [--position N]
|
||||
pcli label update <label-id> [--name "..."] [--color "..."] [--position N]
|
||||
pcli label delete <label-id>
|
||||
```
|
||||
|
||||
## Extracting IDs from Output
|
||||
|
||||
All responses use `{"data": ..., "error": null}`. Extract IDs with jq:
|
||||
|
||||
```bash
|
||||
# Single object
|
||||
pcli card create --list <id> --name "X" | jq -r '.data.id'
|
||||
|
||||
# Array
|
||||
pcli card list --board <id> | jq -r '.data[].id'
|
||||
```
|
||||
|
||||
## Common Workflows
|
||||
|
||||
### Create a complete Kanban board
|
||||
|
||||
```bash
|
||||
# Create board
|
||||
BOARD_ID=$(pcli board create --project <project-id> --name "Development Board" | jq -r '.data.id')
|
||||
|
||||
# Create 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 board
|
||||
pcli board get $BOARD_ID --format table
|
||||
```
|
||||
|
||||
### 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
|
||||
```
|
||||
@@ -0,0 +1,150 @@
|
||||
---
|
||||
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.included.lists[] | {id, title}'
|
||||
|
||||
# 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
|
||||
Reference in New Issue
Block a user