---
description: Reconcile Planka board state with OpenSpec changes
allowed-tools: 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:

```bash
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