# kanban-zone

Adopt this skill: https://proskills.md/skills/other/maxgood-ai-kanban-zone-agent-skill

Page: https://proskills.md/skills/other/maxgood-ai-kanban-zone-agent-skill
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: SKILL.md
size: 8038
upstream: https://github.com/maxgood-ai/kanban-zone-agent-skill/blob/HEAD/SKILL.md

````text
---
name: kanban-zone
description: Interact with Kanban Zone kanban boards via the Kanban Zone API. Use when the user wants to manage kanban cards, boards, comments, checklists, tasks, webhooks, or board reports. Even if the user just says "check the board", "what's in progress", or mentions kanban cards, use this skill.
license: MIT
compatibility: Requires python3 and environment variables KANBAN_ZONE_API_KEY and KANBAN_ZONE_BOARD_ID. Wraps Kanban Zone Public API v1.4.
metadata:
  version: "3.2.0"
  openclaw:
    requires:
      env:
        - KANBAN_ZONE_API_KEY
        - KANBAN_ZONE_BOARD_ID
      bins:
        - python3
    primaryEnv: KANBAN_ZONE_API_KEY
    homepage: https://docs.kanbanzone.io
---

# Kanban Zone

Manage Kanban Zone kanban boards through the Kanban Zone Public API (v1.4).

## Delete operations work again (Kanban Zone fixed its API, 2026-06-11)

If you have prior context saying delete commands are broken, it is stale:
Kanban Zone fixed the server-side "Body Parser failed" defect that made every
DELETE fail between 2026-05-16 and 2026-06-11. All five delete commands
(`cards delete`, `checklists delete`, `tasks delete`, `webhooks delete`,
`tokens revoke`) work normally. A successful delete prints
`{"deleted": true, "id": ...}` and exits zero. The skill keeps a defensive
check: if the old failure envelope ever reappears, the delete **fails loudly**
(`KanbanZoneDeleteUnsupportedError`, exit non-zero) instead of reporting a
fake success — if you see that error, the defect has regressed; tell the user
and fall back to the Kanban Zone web UI.

## ⚠️ Monthly API usage limit (error code 2006)

Kanban Zone enforces a **monthly API-call quota** per organization (usage is
tracked per API key against the plan's limit). When the quota is exhausted,
**every** API call fails until the monthly quota resets or the plan's limit
is raised — and Kanban Zone returns the failure as **HTTP 200** with the
error only in the response body:

```json
{"code": 2006, "status": 429, "name": "TooManyRequests", "message": "API Usage limit reached"}
```

The skill detects this envelope and **exits non-zero** with a
`KanbanZoneUsageLimitError` that explains the situation in full. It does
**not** hand the envelope back as if it were data (before v3.2.0 this leaked
through and made a quota-exhausted card lookup report "card not found").

**Guidance for agents:**

- **Do not retry.** No request will succeed until the quota resets or the
  limit is raised, and retry loops burn through the fresh quota the moment
  it does.
- **Direct the user to check their API usage status** in the Kanban Zone web
  interface: the **Organization > Integrations** panel
  (`https://kanbanzone.io/settings/integrations`). Its "Available API Calls"
  meter shows current usage against the plan's monthly limit, per API key.
- Budget the remaining quota in normal operation: a cold-cache card-number
  lookup paginates `/cards` at one call per 100 cards, so keep the local
  cache warm and avoid polling loops.

See `README.md` → "Monthly API usage limit" for the full technical detail.

## ⚠️ Exec Safety Rule — Multi-line Commands

**Never pass multi-line shell commands or long `--description` strings inline to `exec`.** The exec preflight will block them as "complex interpreter invocation".

**Always write to a temp file first:**

```python
# Write description to temp file
with open('/tmp/kanban-zone-desc.txt', 'w') as f:
    f.write("""Your multi-line
description here""")

# Then run the CLI via a script file
script = '''import subprocess
result = subprocess.run(
    ["python3", "skills/kanban-zone/scripts/kanban_zone_api.py",
     "cards", "update", "--id", "123",
     "--description", open("/tmp/kanban-zone-desc.txt").read()],
    capture_output=True, text=True
)
print(result.stdout)
print(result.stderr)
'''
with open('/tmp/kanban-zone-run.py', 'w') as f:
    f.write(script)
# Then exec: python3 /tmp/kanban-zone-run.py
```

Or simply build the whole call as a Python script in `/tmp/` and exec that file directly.

## ⚠️ Reading Command Output — do not pipe through inline parsers

Every command prints a **single JSON value** to stdout and nothing else. On success it is the result object/array; on failure it is `{"error": true, "message": "..."}` **and the process exits non-zero**.

**Do not pipe the output through an inline `python3 -c "..."` (or `jq`, `grep`, etc.) to pluck a field.** Two things go wrong, and both waste a turn:

- The inline parser assumes the *success* shape. When the command fails, the output is the `{"error": ...}` object instead, so the parser raises `KeyError` on the field you expected — and that traceback **replaces** the genuinely helpful `message`, so you have to re-run the command bare just to see what actually went wrong.
- Inline `python3 -c` scripts are exactly the "complex interpreter invocation" the exec preflight blocks (see the Exec Safety Rule above).

**Instead:** run the command on its own with `--pretty` and read the JSON directly from the tool result. It is already structured — you do not need to post-process it.

```bash
# GOOD — run it bare, read the JSON yourself
python3 scripts/kanban_zone_api.py --pretty cards get --id 65

# BAD — parser crashes on the error shape and hides the real message
python3 scripts/kanban_zone_api.py cards get --id 65 | python3 -c "import sys,json; print(json.load(sys.stdin)['CardItem']['title'])"
```

If a result is genuinely too large to read inline (e.g. `cards search` across many boards) and you must extract fields with a script, **write the script to a `/tmp/*.py` file** (per the Exec Safety Rule) and have it **check `if data.get("error"): ...` first** before touching success-shape keys.

**Response shapes vary by command** — don't assume. `cards get` returns `{"_id", "CardItem", "meta"}` (the card is nested under `CardItem`); `cards list` / `cards search` return `{"count", "cards": [...]}` with each card wrapped in a `CardItem` envelope; `boards list` wraps each board in a `BoardItem` envelope. When unsure, run once with `--pretty` and look.

## Environment Setup

The CLI script reads two environment variables: `KANBAN_ZONE_API_KEY` and `KANBAN_ZONE_BOARD_ID`.

The script **automatically loads** these from a `.env` file if they are not already in the environment. It searches the current working directory **and the script's own location (symlinks resolved)**, plus **every ancestor directory of each**, up to the filesystem root — so a workspace-root `.env` is found no matter which directory you run the command from. No shell export, `cd`, or command substitution is needed — just run the Python command directly.

**You do not need to `cd` anywhere first.** If you see `--board or KANBAN_ZONE_BOARD_ID is required` or `KANBAN_ZONE_API_KEY is not set`, the `.env` is genuinely missing — do not retry from a different directory or re-run blindly. Either pass `--board <id>` / `--api-token <key>` explicitly, or tell the user the `.env` is not present in the workspace tree.

**Get your API key:** Settings > Organization Settings > Integrations > API Key
Direct: `https://kanbanzone.io/settings/integrations`

**Find column IDs:** Board Settings > API, or Organization Settings > Integrations > API

## Quick Start

All examples below assume a `.env` file with `KANBAN_ZONE_API_KEY` and `KANBAN_ZONE_BOARD_ID` exists in the workspace root.

```bash
python3 scripts/kanban_zone_api.py boards list
python3 scripts/kanban_zone_api.py boards get
python3 scripts/kanban_zone_api.py cards list --label "Bug"
python3 scripts/kanban_zone_api.py cards get --id 42
python3 scripts/kanban_zone_api.py cards create --title "New task" --column-id COL1
python3 scripts/kanban_zone_api.py cards move --id 42 --column-id COL2
python3 scripts/kanban_zone_api.py cards delete --id 42
python3 scripts/kanban_zone_api.py comments add --card 42 --text "Looks good!"
python3 scripts/kanban_zone_api.py checklists create --card 42 --title "QA" --task "T1"
python3 scripts/ka
````

## File: README.md
upstream: https://github.com/maxgood-ai/kanban-zone-agent-skill/blob/HEAD/README.md

````text
# Kanban Zone Skill for Claude Code

## What It Is

Manage your [Kanban Zone](https://kanbanzone.com) boards — cards, columns, comments, checklists, tasks, webhooks, and flow reports — directly from any Claude Code-compatible workspace. Built in official partnership with Kanban Zone, this skill wraps the **Kanban Zone Public API v1.4** using nothing but the Python 3 standard library: no virtual environment, no third-party packages, and no external runtime dependencies of any kind. Drop it into a repo, point it at your API key, and your AI assistant gains full board access in seconds.

> **Note on delete operations:** All delete commands work normally. Each one
> checks that the response isn't a failure disguised behind an HTTP 200
> status ("Body Parser failed" in the body instead of the deleted record);
> when it detects that pattern, it fails loudly
> (`KanbanZoneDeleteUnsupportedError`) instead of reporting a fake success.

## ⚠️ Monthly API usage limit (error code 2006)

Kanban Zone enforces a **monthly API-call quota** per organization, tracked
per API key against the plan's limit. When the quota is exhausted, every API
call fails until the month's quota resets or the plan's limit is raised.

**What happens:** Kanban Zone returns the rejection as **HTTP 200**, with the
error visible only inside the response body
(`{"code": 2006, "status": 429, "name": "TooManyRequests", "message": "API
Usage limit reached"}`). Naive clients treat that as a successful, empty
response instead of surfacing the underlying error.

**What the skill does:** every command detects the code-2006 envelope (and
any other error envelope hidden behind an HTTP 200) and **fails loudly** —
it exits non-zero with a `KanbanZoneUsageLimitError` stating that the request
was rejected, that retrying will not help, and where to check usage.

**What to do:** check your usage in the Kanban Zone web interface under
**Organization > Integrations** (<https://kanbanzone.io/settings/integrations>)
— the "Available API Calls" meter shows consumption against your plan's
monthly limit. To restore API access, wait for the monthly reset or upgrade
the plan's API allowance.

## Install

```bash
# Clone the skill into your project's skills/ directory (or anywhere on your path)
git clone https://github.com/MaxGood-AI/kanban-zone-agent-skill skills/kanban-zone
```

The skill is invoked directly via `python3 scripts/kanban_zone_api.py ...` — no plugin registration step is required.

**Requirements:** Python 3.8 or later (verify with `python3 --version`).

Create a `.env` file in the directory where you'll be working:

```bash
KANBAN_ZONE_API_KEY=your-api-key-here
KANBAN_ZONE_BOARD_ID=your-default-board-public-id
```

The skill loads `.env` automatically — no shell export needed. Discovery searches the current working directory and the script's own location (symlinks resolved), plus every ancestor directory of each, so a `.env` at your workspace root is found no matter which subdirectory you run the command from. `KANBAN_ZONE_BOARD_ID` sets the default board for every command; pass `--board <id>` to override it for a single call.

**Multiple boards:** create one `.env` per project folder, each with the relevant `KANBAN_ZONE_BOARD_ID`. The nearest `.env` (current directory or closest ancestor) wins, and a real environment variable always overrides a `.env` value. The same `KANBAN_ZONE_API_KEY` works across all boards and can be set once as a system environment variable if you prefer.

## API Key

1. Log in to Kanban Zone and go to **Settings → Organization Settings → Integrations → API Key**.
   Direct link: <https://kanbanzone.io/settings/integrations>
2. Click **Generate** (or copy an existing key).
3. Paste the raw key into your `.env` as `KANBAN_ZONE_API_KEY=...`. The CLI base64-encodes it automatically before every request — do not pre-encode it yourself.

## Cookbook

Each example below is a complete, copy-pasteable bash command. All examples use the grouped v3 command surface (`boards list`, `cards create`, etc.).

### 1. List boards and pick one to work on

Inspect all your boards at a glance before deciding which one to target for the session.

```bash
python3 scripts/kanban_zone_api.py boards list --include-columns
```

Pick the `publicId` from the output and drop it into your `.env` as `KANBAN_ZONE_BOARD_ID`, or pass `--board <id>` inline for a one-off override.

### 2. Create a card with watchers and custom fields

Create a fully annotated card in the "Backlog" column, assign it, add a watcher, and stamp two custom fields.

```bash
python3 scripts/kanban_zone_api.py cards create \
  --title "Q3 client proposal — Acme Corp" \
  --column-id COL_ABC123 \
  --owner sarah@company.com \
  --watcher cfo@company.com \
  --priority 1 --label "Sales" --size M --due-at "09/30/2026" \
  --custom-field "Client=Acme Corp" \
  --custom-field "Region=Northeast"
```

### 3. Update a description from a temp file

Long HTML descriptions clash with shell quoting. Write the body to a temp file first, then hand it to the CLI via `--description-file`.

```bash
python3 -c "
import textwrap
open('/tmp/desc.txt', 'w').write(textwrap.dedent('''
  <h3>Scope</h3>
  <p>Revised timeline following client call on 2026-05-09.</p>
  <ul>
    <li>Phase 1 due 2026-06-01</li>
    <li>Phase 2 due 2026-07-15</li>
  </ul>
''').strip())
"
python3 scripts/kanban_zone_api.py cards update --id 42 \
  --description-file /tmp/desc.txt
```

Note: Kanban Zone renders descriptions as HTML. Use `<pre>` blocks for any tabular data — `<table>` tags are silently stripped by the platform.

### 4. Move a card to "In Progress"

Provide the target column ID (visible in Board Settings → API).

```bash
python3 scripts/kanban_zone_api.py cards move --id 42 --column-id COL_INPROG
```

### 5. Add a comment to a card

Post a status update or question directly on the card's activity feed.

```bash
python3 scripts/kanban_zone_api.py comments add --card 42 \
  --text "Scope confirmed with client. Proceeding to design phase."
```

### 6. Create a checklist with tasks; mark one complete

Add a QA checklist to a card, then immediately mark the first task done.

```bash
# Create the checklist (returns the checklist ID and first task ID)
python3 scripts/kanban_zone_api.py checklists create --card 42 \
  --title "QA Sign-off" \
  --task "Smoke test on staging" \
  --task "Cross-browser check" \
  --task "Accessibility audit"

# Mark task 1001 complete (replace with the returned task ID)
python3 scripts/kanban_zone_api.py tasks update --id 1001 --completed true
```

### 7. Register a webhook and verify a delivery's signature

Subscribe to card-created events, then use the built-in HMAC verifier to confirm the first delivery is authentic.

```bash
# Register the webhook (set the org-level Webhook Key in Kanban Zone Settings → Integrations first)
python3 scripts/kanban_zone_api.py webhooks create \
  --url "https://hooks.yourapp.com/kanban" \
  --event CARD_CREATED

# After the first delivery arrives, verify its signature (key from KANBAN_ZONE_WEBHOOK_KEY env or --webhook-key)
python3 scripts/kanban_zone_api.py webhooks verify-signature \
  --payload-file /tmp/webhook-body.json \
  --signature "<raw-hex-from-X-KanbanZone-Signature-header>" \
  --webhook-key "your-webhook-key"
```

### 8. Pull a throughput report for the last quarter

Measure how many cards were completed between two dates.

```bash
python3 scripts/kanban_zone_api.py reports throughput \
  --from-date 2026-01-01 --to-date 2026-03-31
```

Other available report types: `arrival-rate`, `cycle-time`, `lead-time`, `flow`, `flow-efficiency`, `allocation`, `abandoned-effort`.

### 9. Audit overdue cards across all boards

Search across every board you can access for cards matching a label, owner, or free-text query.

```bash
# cards search supports --query / --label / --owner across all boards.
# The skill iterates every board and applies these filters client-side.
python3 scripts/kanban_zone_api.py cards 
````
