pcli/.claude/commands/kanban-sync.md

description, allowed-tools

description	allowed-tools
Reconcile Planka board state with OpenSpec changes	Bash, Read

Planka <-> OpenSpec Reconciliation Sync

Runs the kanban-project-sync script to reconcile Planka board state with OpenSpec changes.

How It Works

The sync is handled by the kanban-project-sync bash script (on PATH). It:

1. Checks Planka connectivity
2. Bootstraps project/board/lists/label infrastructure (idempotent)
3. Reads OpenSpec state and maps changes to board lists
4. Creates/moves/updates Planka cards and task checklists
5. Moves orphaned cards to Done

OpenSpec is the source of truth. Planka is a read-only projection. Sync is one-directional (OpenSpec -> Planka) and idempotent.

Running the Sync

Read project config and invoke the script in background mode:

PROJECT_NAME=$(yq -r '.planka.project' project.yaml)
BOARD_NAME=$(yq -r '.planka.board' project.yaml)
kanban-project-sync --project "$PROJECT_NAME" --board "$BOARD_NAME" --background

The --background flag makes the script fire-and-forget — it detaches and logs to /tmp/kanban-project-sync-<project>-<board>.log.

Concurrency

The script handles its own concurrency:

• Uses flock to ensure only one sync runs per project-board pair
• If a sync is already running, sets a pending flag and exits immediately
• The running sync re-runs after completion if the pending flag is set
• Multiple pending requests coalesce into a single re-run

Guardrails

• Sync is best-effort — if Planka is unreachable or the script fails, log a warning and continue
• Never block agentic work because of sync
• If kanban-project-sync is not on PATH, log a warning and skip