Steve Cliff
31 lines
2.2 KiB
Markdown
31 lines
2.2 KiB
Markdown
## 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-sync` bash script (deployed externally, on PATH) that performs the full 10-phase Planka board reconciliation
|
|
- Script accepts `--project` and `--board` as required inputs, with optional `--background` flag
|
|
- Script assumes it is run from the project root (uses `pwd` to locate `openspec/` directory)
|
|
- Implements `flock`-based concurrency control with a coalescing pending flag (depth-1 queue)
|
|
- Default mode is foreground (human-friendly); `--background` detaches for fire-and-forget use
|
|
- `.claude/commands/kanban-sync.md` simplified to just invoke the script with `--background`
|
|
- `CLAUDE.md` sync 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 via `brew install util-linux`), `jq`, `yq`, `pcli`, `openspec` on 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 `openspec` and `pcli`)
|