Steve Cliff
46 lines
1.6 KiB
Markdown
46 lines
1.6 KiB
Markdown
---
|
|
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
|