diff --git a/.windsurf/skills/kanban/SKILL.md b/.windsurf/skills/kanban/SKILL.md new file mode 100644 index 0000000..3151946 --- /dev/null +++ b/.windsurf/skills/kanban/SKILL.md @@ -0,0 +1,143 @@ +--- +name: kanban +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` and `pcli` are installed and in the path. + +## Global Flags + +All commands accept: `--format json|table`, `--url `, `--api-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 +``` + +### Boards + +```bash +pcli board list +pcli board get # includes lists and cards +pcli board actions [--limit N] +``` + +### Cards + +```bash +# List (one of --board or --list required, mutually exclusive) +pcli card list --board [--limit N] +pcli card list --list [--limit N] + +# CRUD +pcli card get +pcli card create --list --name "Name" [--description "..."] [--type project|story] [--position N] [--due-date "ISO8601"] [--due-completed] +pcli card update [--name "..."] [--description "..."] [--type ...] [--position N] [--due-date "..."] [--due-completed] +pcli card delete +pcli card duplicate --name "Copy" [--position N] +pcli card move --list [--position N] + +# Members +pcli card assign --user +pcli card unassign --user + +# Labels +pcli card add-label --label +pcli card remove-label --label + +# Actions +pcli card actions [--limit N] +``` + +### Comments + +```bash +pcli comment list --card [--limit N] +pcli comment create --card --text "..." +pcli comment update --text "..." +pcli comment delete +``` + +### Task Lists + +```bash +pcli task-list create --card --name "Checklist" [--position N] [--show-on-front] [--hide-completed] +pcli task-list get +pcli task-list update [--name "..."] [--position N] [--show-on-front] [--hide-completed] +pcli task-list delete +``` + +### Tasks + +```bash +pcli task create --task-list --name "Item" [--position N] [--completed] +pcli task update [--name "..."] [--position N] [--completed] +pcli task delete +``` + +### Labels + +```bash +pcli label create --board --name "Bug" --color "berry-red" [--position N] +pcli label update [--name "..."] [--color "..."] [--position N] +pcli label delete +``` + +## Extracting IDs from Output + +All responses use `{"data": ..., "error": null}`. Extract IDs with jq: + +```bash +# Single object +pcli card create --list --name "X" | jq -r '.data.id' + +# Array +pcli card list --board | jq -r '.data[].id' +``` + +## Common Workflows + +### Create a card with a checklist + +```bash +CARD_ID=$(pcli card create --list --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 | jq -r '.data[].id' | while read id; do + pcli card move $id --list +done +``` diff --git a/.windsurf/workflows/kanban.md b/.windsurf/workflows/kanban.md new file mode 100644 index 0000000..125ba6b --- /dev/null +++ b/.windsurf/workflows/kanban.md @@ -0,0 +1,121 @@ +--- +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 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 | jq '.data.included.lists[] | {id, title}' + +# Find cards on a list or board +pcli card list --board | jq '.data[] | {id, name}' +pcli card list --list | 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` | +| **Boards** | `list`, `get`, `actions` | +| **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 card with a checklist + +```bash +CARD_ID=$(pcli card create --list --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 | jq -r '.data[].id' | while read id; do + pcli card move $id --list +done +``` + +### Extract IDs from output + +```bash +# Single object +pcli card create --list --name "X" | jq -r '.data.id' + +# Array +pcli card list --board | 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 diff --git a/example-skill/kanban.md b/example-skill/kanban.md new file mode 100644 index 0000000..125ba6b --- /dev/null +++ b/example-skill/kanban.md @@ -0,0 +1,121 @@ +--- +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 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 | jq '.data.included.lists[] | {id, title}' + +# Find cards on a list or board +pcli card list --board | jq '.data[] | {id, name}' +pcli card list --list | 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` | +| **Boards** | `list`, `get`, `actions` | +| **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 card with a checklist + +```bash +CARD_ID=$(pcli card create --list --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 | jq -r '.data[].id' | while read id; do + pcli card move $id --list +done +``` + +### Extract IDs from output + +```bash +# Single object +pcli card create --list --name "X" | jq -r '.data.id' + +# Array +pcli card list --board | 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