Added list management commands, board filtering by project name, and enhanced skill documentation with bootstrap workflow and error handling patterns. Also added plumbing in to "pcli" binary for status syncing with Planka
This commit is contained in:
Steve Cliff
@@ -0,0 +1,266 @@
|
||||
---
|
||||
name: "Kanban Sync"
|
||||
description: Reconcile Planka board state with OpenSpec changes. Planka is a read-only dashboard - OpenSpec is the source of truth.
|
||||
category: Workflow
|
||||
tags: [workflow, kanban, planka, tasks, project-management, sync]
|
||||
---
|
||||
|
||||
# Planka ↔ OpenSpec Reconciliation Sync
|
||||
|
||||
**OpenSpec is the source of truth for all agentic work.** Planka provides a read-only view so humans and other agents can see what's happening. This workflow reads OpenSpec state and reconciles Planka to match.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before syncing, verify connectivity:
|
||||
|
||||
```bash
|
||||
pcli status
|
||||
```
|
||||
|
||||
If this fails, skip the Planka sync silently. Planka sync is best-effort - never block agentic work because Planka is unavailable.
|
||||
|
||||
---
|
||||
|
||||
## Core Principles
|
||||
|
||||
1. **OpenSpec owns the state** - `tasks.md`, artifacts, and change status live in OpenSpec
|
||||
2. **Planka is a projection** - it reflects OpenSpec state, never the other way around
|
||||
3. **Sync is one-directional** - OpenSpec → Planka, never Planka → OpenSpec
|
||||
4. **Sync is idempotent** - running it twice produces the same result
|
||||
5. **Sync is best-effort** - if Planka is down, work continues uninterrupted
|
||||
6. **Non-agentic work** is managed directly in Planka (no OpenSpec involvement)
|
||||
|
||||
---
|
||||
|
||||
## When This Runs
|
||||
|
||||
This workflow is triggered automatically after any opsx workflow completes (via project-level instruction in `.windsurf/rules/kanban-update.md`). It can also be invoked manually via `/kanban-tasks`.
|
||||
|
||||
---
|
||||
|
||||
## Board Structure
|
||||
|
||||
The board lists map to OpenSpec lifecycle stages:
|
||||
|
||||
| List | Position | Purpose |
|
||||
|------|----------|---------|
|
||||
| **Backlog** | 1 | Non-agentic work items (human-managed, read-write) |
|
||||
| **To Do** | 2 | Non-agentic work items ready to start (human-managed, read-write) |
|
||||
| **Planning** | 3 | OpenSpec changes with artifacts still being created (`opsx:new`, `opsx:continue`, `opsx:ff`) |
|
||||
| **In Progress** | 4 | Active implementation — tasks being worked (`opsx:apply`) |
|
||||
| **Review** | 5 | All tasks complete, awaiting verification (`opsx:verify`) |
|
||||
| **Done** | 6 | Completed and archived (`opsx:archive`) |
|
||||
|
||||
---
|
||||
|
||||
## Bootstrap: Ensure Project, Board, Lists, and Label Exist
|
||||
|
||||
Before reconciling, ensure all required Planka infrastructure exists. This makes the sync self-bootstrapping — running it on a fresh Planka instance will create everything needed.
|
||||
|
||||
### 1. Read project config
|
||||
|
||||
```bash
|
||||
PROJECT_NAME=$(yq '.planka.project' project.yaml)
|
||||
BOARD_NAME=$(yq '.planka.board' project.yaml)
|
||||
```
|
||||
|
||||
If `project.yaml` doesn't exist or has no `planka` section, ask the user for the project and board name, then offer to create the file.
|
||||
|
||||
### 2. Find or create the project
|
||||
|
||||
```bash
|
||||
PROJECT_ID=$(pcli project list | jq -r --arg name "$PROJECT_NAME" '.data[] | select(.name == $name) | .id')
|
||||
```
|
||||
|
||||
If no project found:
|
||||
```bash
|
||||
PROJECT_ID=$(pcli project create --name "$PROJECT_NAME" --type "public" | jq -r '.data.id')
|
||||
```
|
||||
|
||||
### 3. Find or create the board
|
||||
|
||||
```bash
|
||||
# Get project details to find boards
|
||||
BOARD_ID=$(pcli project get $PROJECT_ID | jq -r --arg name "$BOARD_NAME" '.data.included.boards[] | select(.name == $name) | .id')
|
||||
```
|
||||
|
||||
If no board found:
|
||||
```bash
|
||||
BOARD_ID=$(pcli board create --project $PROJECT_ID --name "$BOARD_NAME" | jq -r '.data.id')
|
||||
```
|
||||
|
||||
### 4. Find or create the lists
|
||||
|
||||
After obtaining the board, get its current lists:
|
||||
```bash
|
||||
EXISTING_LISTS=$(pcli board get $BOARD_ID | jq -r '.data.included.lists[]? | .name')
|
||||
```
|
||||
|
||||
Create any missing lists with explicit positions to maintain correct ordering:
|
||||
```bash
|
||||
# Only create lists that don't already exist
|
||||
pcli list create --board $BOARD_ID --name "Backlog" --position 65536
|
||||
pcli list create --board $BOARD_ID --name "To Do" --position 131072
|
||||
pcli list create --board $BOARD_ID --name "Planning" --position 196608
|
||||
pcli list create --board $BOARD_ID --name "In Progress" --position 262144
|
||||
pcli list create --board $BOARD_ID --name "Review" --position 327680
|
||||
pcli list create --board $BOARD_ID --name "Done" --position 393216
|
||||
```
|
||||
|
||||
Skip any list that already exists (match by name).
|
||||
|
||||
### 5. Find or create the `agent` label
|
||||
|
||||
```bash
|
||||
LABEL_ID=$(pcli board get $BOARD_ID | jq -r '.data.included.labels[]? | select(.name == "agent") | .id')
|
||||
```
|
||||
|
||||
If no `agent` label found:
|
||||
```bash
|
||||
LABEL_ID=$(pcli label create --board $BOARD_ID --name "agent" --color "berry-red" | jq -r '.data.id')
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Reconciliation Steps
|
||||
|
||||
### 1. Gather OpenSpec state
|
||||
|
||||
```bash
|
||||
openspec list --json
|
||||
```
|
||||
|
||||
This returns all active changes with their names, schemas, and status.
|
||||
|
||||
For each active change:
|
||||
```bash
|
||||
openspec status --change "<name>" --json
|
||||
```
|
||||
|
||||
Parse to get:
|
||||
- Change name
|
||||
- Schema name
|
||||
- Artifact completion status (how many artifacts complete vs total)
|
||||
- Whether all `applyRequires` artifacts are done
|
||||
- Whether tasks exist and their completion state
|
||||
|
||||
If a `tasks.md` exists, read it and parse checkbox state (`- [ ]` vs `- [x]`).
|
||||
|
||||
### 2. Determine target list for each change
|
||||
|
||||
Map each change to the correct board list based on its OpenSpec state:
|
||||
|
||||
| Condition | Target List |
|
||||
|-----------|-------------|
|
||||
| Artifacts incomplete (not all `applyRequires` done) | **Planning** |
|
||||
| Artifacts complete, tasks exist with incomplete items | **In Progress** |
|
||||
| All tasks complete (all `[x]`) | **Review** |
|
||||
| Change archived (not in active list) | **Done** |
|
||||
|
||||
### 3. Gather Planka state
|
||||
|
||||
```bash
|
||||
pcli card list --board $BOARD_ID | jq '.data[] | select(.labels[]?.name == "agent")'
|
||||
```
|
||||
|
||||
Build a map of existing agent-labelled cards by name, including which list they're currently in.
|
||||
|
||||
### 4. Reconcile: create missing cards
|
||||
|
||||
For each active OpenSpec change that has no matching Planka card:
|
||||
|
||||
```bash
|
||||
# Determine the correct list based on change state (see step 2)
|
||||
LIST_ID=$(pcli board get $BOARD_ID | jq -r --arg list "<target-list>" '.data.included.lists[] | select(.name == $list) | .id')
|
||||
CARD_ID=$(pcli card create --list $LIST_ID --name "<change-name>" --description "<schema: schema-name>" | jq -r '.data.id')
|
||||
|
||||
# Add agent label
|
||||
pcli card add-label $CARD_ID --label $LABEL_ID
|
||||
```
|
||||
|
||||
### 5. Reconcile: move cards to correct list
|
||||
|
||||
For each agent-labelled card that exists but is in the wrong list (based on current OpenSpec state):
|
||||
|
||||
```bash
|
||||
TARGET_LIST_ID=$(pcli board get $BOARD_ID | jq -r --arg list "<target-list>" '.data.included.lists[] | select(.name == $list) | .id')
|
||||
pcli card move $CARD_ID --list $TARGET_LIST_ID
|
||||
```
|
||||
|
||||
This ensures cards move through the board as work progresses:
|
||||
- `Planning` → `In Progress` when artifacts are complete and apply begins
|
||||
- `In Progress` → `Review` when all tasks are marked done
|
||||
- `Review` → `Done` when the change is archived
|
||||
|
||||
### 6. Reconcile: sync task lists
|
||||
|
||||
For each OpenSpec change that has a `tasks.md`:
|
||||
|
||||
- If the Planka card has no task list → create one and add all tasks
|
||||
- If the Planka card has a task list → compare task names and completion state, update as needed
|
||||
|
||||
```bash
|
||||
# Create task list if missing
|
||||
TL_ID=$(pcli task-list create --card $CARD_ID --name "Implementation" --show-on-front | jq -r '.data.id')
|
||||
|
||||
# For each task in tasks.md:
|
||||
pcli task create --task-list $TL_ID --name "<task description>"
|
||||
|
||||
# For tasks already in Planka, update completion state to match tasks.md:
|
||||
pcli task update <task-id> --completed # if tasks.md shows [x]
|
||||
```
|
||||
|
||||
### 7. Reconcile: move completed/archived changes
|
||||
|
||||
For each agent-labelled Planka card that has no matching active OpenSpec change:
|
||||
- The change was likely archived → move the card to "Done"
|
||||
|
||||
```bash
|
||||
DONE_LIST_ID=$(pcli board get $BOARD_ID | jq -r '.data.included.lists[] | select(.name == "Done") | .id')
|
||||
pcli card move $CARD_ID --list $DONE_LIST_ID
|
||||
```
|
||||
|
||||
### 8. Report
|
||||
|
||||
After reconciliation, briefly summarise what changed:
|
||||
- Infrastructure created (project/board/lists/label): yes/no
|
||||
- Cards created: N
|
||||
- Cards moved: N (list details)
|
||||
- Tasks synced: N
|
||||
- Cards moved to Done: N
|
||||
- Errors (if any): list them
|
||||
|
||||
---
|
||||
|
||||
## Non-Agentic Work
|
||||
|
||||
Cards **without** the `agent` label are human-managed and fully read-write. The kanban skill (`/kanban`) handles these directly - creating cards, moving them, adding checklists, etc.
|
||||
|
||||
The distinction:
|
||||
- **Has `agent` label** → read-only projection, managed by this sync workflow
|
||||
- **No `agent` label** → regular Planka card, managed directly by humans
|
||||
|
||||
---
|
||||
|
||||
## ID Discovery
|
||||
|
||||
Planka IDs cannot be cached across sessions. Each sync run must discover IDs dynamically:
|
||||
|
||||
1. Read project and board name from `project.yaml`
|
||||
2. Find the project by name: `pcli project list | jq ...`
|
||||
3. Find the board by name within the project
|
||||
4. Find lists on the board: `pcli board get <board-id> | jq ...`
|
||||
5. Find agent cards: `pcli card list --board <board-id> | jq '.data[] | select(.labels[]?.name == "agent")'`
|
||||
6. Match cards to changes by name
|
||||
|
||||
---
|
||||
|
||||
## Guardrails
|
||||
|
||||
- **Never modify an `agent`-labelled card outside of this sync workflow**
|
||||
- **Never read Planka to determine what work to do** - query OpenSpec instead
|
||||
- **Always discover IDs dynamically** - never hardcode or cache across sessions
|
||||
- **Sync failures are silent** - log a warning but never block opsx workflows
|
||||
- **One board per project** - if multiple boards exist, ask the user which to sync to
|
||||
- **Idempotent** - safe to run multiple times, will not create duplicates
|
||||
- **Bootstrap is safe** - creating project/board/lists is idempotent; existing resources are reused
|
||||
Reference in New Issue
Block a user