# Planka Skill for AI agents

An AI agent skill for managing [Planka](https://github.com/plankanban/planka) kanban boards through natural language. No rigid CLI syntax — just describe what you want.

## Setup

1. Clone this repo into your Claude Code skills directory:
   ```bash
   git clone <repo-url> ~/.agents/skills/planka-skill
   ```
   Or copy the folder manually to `~/.agents/skills/`.

2. Generate an API key in Planka: User Settings → API Key

3. Set environment variables (in project `.env`, `~/.env`, or shell):
   ```bash
   PLANKA_URL=https://planka.example.com
   PLANKA_API_KEY=your-api-key
   ```
   A trailing slash in `PLANKA_URL` is fine. The skill strips it before adding `/api`.
   When both env files exist, the project's `.env` overrides `~/.env`;
   values in either file override existing shell values.

## Helper CLI

Run from the target project's root. If the skill lives elsewhere, replace the script path with its installed location. The CLI needs only Python 3's standard library.

```bash
python3 .pi/skills/planka/planka.py                         # projects, boards, card counts
python3 .pi/skills/planka/planka.py board TodoApp             # lists and cards
python3 .pi/skills/planka/planka.py card TodoApp "Login Bug"   # card details
python3 .pi/skills/planka/planka.py card TodoApp "Login Bug" --full
python3 .pi/skills/planka/planka.py spec endpoints card-labels
python3 .pi/skills/planka/planka.py spec refresh
```

After the user approves a board write:

```bash
python3 .pi/skills/planka/planka.py create-card TodoApp TODO "Fix login" --description "Steps to reproduce..." --confirm
python3 .pi/skills/planka/planka.py move-card TodoApp "Fix login" "IN PROGRESS" --confirm
```

The script resolves board, list, and card names to current IDs. Ambiguous names fail instead of picking one. Writes require `--confirm` **and** prior user approval in conversation. It refuses unknown flags. Run each subcommand with `--help` for arguments.

The first API call downloads the published OpenAPI spec to `.pi/cache/planka-swagger.json` in the current project; later calls use the cache. Run `spec refresh` to fetch a new copy. The cache is public schema data, not credentials. If the server's API differs from the published spec, refresh and inspect its version rather than guessing paths. A first-time run needs network access to both the spec and Planka; subsequent endpoint checks work offline, but board operations still need Planka.

For unsupported operations, inspect the cached spec first (`spec endpoints <term>` and the request schema in the JSON file). Use the API base `${PLANKA_URL%/}/api`, `X-Api-Key` authentication, encoded JSON bodies, and validate the response content type and JSON. Never print the key. The helper reads simple `KEY=value` / quoted values for `PLANKA_URL` and `PLANKA_API_KEY` from `~/.env` then `.env`; it does not execute shell expressions in those files.

## Quick Commands

```
/planka overview              # all projects and boards at a glance
/planka board "My Project"    # detailed board view with cards and progress
```

## What You Can Do

Talk naturally — the skill understands intent and figures out the API calls.

### Browse & Inspect
```
/planka show me all my boards
/planka what's in the ToDo list?
/planka show me card "Login Bug" with all its tasks
```

### Create & Organize
```
/planka create a card "Dark Mode" in Backlog with fitting labels
/planka set up a new board "Backend" with lists ToDo, In Progress, Done, Blocked
/planka add labels Bug (red), Feature (blue), Urgent (red) to the "My Project" board
/planka add tasks to "Dark Mode": update theme provider, test contrast, update docs
```

### Move & Update
```
/planka move "Dark Mode" to In Progress
/planka mark "Dark Mode" as done
/planka rename "Dark Mode" to "Dark Mode v2"
/planka add a comment to "Dark Mode": waiting for design review
```

### Bulk Operations
```
/planka move everything from In Progress to Done
/planka read the git log and create cards for all completed features
/planka look at board X and create the same structure for a new board
/planka check all cards for typos and fix them
```

### Project Sync
```
/planka sync the board with our recent git commits
/planka create cards for all open issues
/planka what changed on the board since last week?
```

The helper caches the [Planka OpenAPI spec](https://plankanban.github.io/planka/swagger-ui/swagger.json). Refresh it explicitly when the API changes.

## Requirements

- Planka instance with API key support
- Python 3