Steve Cliff
2.2 KiB
2.2 KiB
Why
The kanban sync is currently implemented as a detailed workflow document that the LLM interprets and executes command-by-command. Each sync burns significant tokens as the LLM reasons through ~10 phases and executes ~15-30 pcli commands. The sync logic is entirely deterministic — there are no decisions that require LLM judgment. Moving this to a standalone bash script eliminates the overhead and makes sync near-instant. Additionally, there is no concurrency protection — two syncs could run simultaneously and clash on Planka API state.
What Changes
- New
kanban-project-syncbash script (deployed externally, on PATH) that performs the full 10-phase Planka board reconciliation - Script accepts
--projectand--boardas required inputs, with optional--backgroundflag - Script assumes it is run from the project root (uses
pwdto locateopenspec/directory) - Implements
flock-based concurrency control with a coalescing pending flag (depth-1 queue) - Default mode is foreground (human-friendly);
--backgrounddetaches for fire-and-forget use .claude/commands/kanban-sync.mdsimplified to just invoke the script with--backgroundCLAUDE.mdsync instructions updated to reference the script
Capabilities
New Capabilities
kanban-sync-concurrency: Concurrency control for sync execution — flock-based locking with a pending flag that coalesces multiple requests, and automatic re-run after completion if a sync was requested during execution
Modified Capabilities
(none — no existing spec-level requirements change)
Impact
- New external script:
kanban-project-sync— deployed to developer instances via existing tooling, placed on PATH - Modified:
.claude/commands/kanban-sync.md— reduced from full workflow to script invocation - Modified:
CLAUDE.md— updated Planka Sync section - Dependencies: Requires
flock(standard on Linux, available on macOS viabrew install util-linux),jq,yq,pcli,openspecon PATH - No Go code changes — this is entirely in the tooling/workflow layer
- Convention: Script must be run from the project root directory (same as
openspecandpcli)