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

2026-02-18 20:06:56 +00:00
parent ad384fe749
commit 46b03e1a22
21 changed files with 1074 additions and 124 deletions
@@ -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
+```