Kanban Workflow Export

---

name: kanban-workflow description: Kanban Workflow is a TypeScript skill for a stage-based agentic co-worker that integrates PM platforms via CLI-first adapters (CLIs or small wrapper scripts). It provides setup + verbs (show/next/start/update/ask/complete/create) around a canonical stage set (backlog/blocked/in-progress/in-review), plus polling/diffing foundations and automation hooks.

Skill packaging / runtime requirements

requirements: # Core runtime binaries: - node - npm node: install: npm ci

# Adapter-specific CLIs (only required if you select that adapter at setup time) adapters: github: binaries: [gh] planka: binaries: [planka-cli] plane: # ClawHub skill plane (owner: vaguilera-jinko) binaries: [plane] linear: # Uses LINEAR_API_KEY (ClawHub skill linear, owner: ManuelHettich) via scripts/linear_json.sh. binaries: [bash, curl, jq]

# Environment variables env: # No env vars are required by Kanban Workflow itself. # Auth is inherited from the selected platform CLI. required: [] optional: # Required when using the Plane adapter (via ClawHub skill plane). - PLANE_API_KEY - PLANE_WORKSPACE # Required when using the Linear adapter (via ClawHub skill linear). - LINEAR_API_KEY

---

Kanban Workflow (core)

Goal

Provide a reusable core for a project-management “co-worker” that:

Uses the existing stage:* lifecycle as the canonical state machine.

Integrates with PM platforms via adapter-managed auth (external CLIs/scripts; may require env vars like API keys). Kanban Workflow does not run interactive OAuth flows or persist secrets.

Centralizes workflow/rules/runbooks so GitHub/Planka/Plane/Linear implementations share logic.

Canonical stage model

Treat these labels/states as canonical (and the only stages the agent should consider):

stage:backlog

stage:blocked

stage:in-progress

stage:in-review

Notes:

Done/closed is platform-specific and intentionally not part of the canonical stage set.

Adapters map platform concepts (labels, lists, statuses, custom fields) into this canonical set.

Architecture (ports & adapters)

Core (platform-agnostic)

Canonical entities: WorkItem, Project, Comment, Stage.

Canonical events: WorkItemCreated, WorkItemUpdated, StageChanged, CommentAdded, etc.

Workflow engine: stage-based worker loop + clarification/comment templates.

State: cursors + dedupe + snapshots for diffing.

Adapters (platform-specific)

Adapters are “smart wrappers” that:

Call existing CLIs (e.g. gh, planka-cli, plane), relying on their auth/session (Plane uses PLANE_API_KEY + PLANE_WORKSPACE; Linear uses LINEAR_API_KEY via the ClawHub skill linear).

Compose multiple CLI calls to implement higher-level operations.

Synthesize events by polling + snapshot diffing when webhooks or event types are missing.

Canonical adapter entrypoints live in src/adapters/:

github.ts (gh CLI)

planka.ts (planka-cli)

plane.ts (ClawHub skill plane CLI; owner: vaguilera-jinko)

linear.ts (ClawHub skill linear auth convention via scripts/linear_json.sh)

See also: src/adapters/README.md for CLI links and assumptions.

Entry points

Library entry points:

tick() (poll → normalize → diff → events)

verb-level workflow helpers: show, next, start, update, ask, complete, create, autopilot-tick

automations: runProgressAutoUpdates()

CLI entry point:

src/cli.ts (provides kanban-workflow ; see README for setup flags)

CLI ergonomics: "What next" tips

All kanban-workflow commands print a What next: tip after execution to guide the canonical flow:

setup → next → start → (ask | update) → complete → next

After start, the tip additionally reminds you to run the actual execution/implementation work in a subagent, then report back via ask/update.

If config/kanban-workflow.json is missing or invalid, all commands error and instruct you to complete setup.

Setup (flags-only)

Setup writes config/kanban-workflow.json and validates that the selected platform CLI is installed + authenticated.

Required:

kanban-workflow setup --adapter ...

stage mapping flags: --map-backlog, --map-blocked, --map-in-progress, --map-in-review

Optional autopilot scheduling:

--autopilot-cron-expr "*/5 * * * *" (default)

--autopilot-cron-tz "Europe/Berlin" (optional)

--autopilot-install-cron (creates an OpenClaw cron job that runs kanban-workflow autopilot-tick)

Adapter flags (summary):

GitHub: --github-repo , optional --github-project-number

Plane: --plane-workspace-slug , --plane-project-id , optional --plane-order-field

Linear: --linear-team-id or --linear-project-id , optional --linear-view-id

Planka: --planka-board-id , --planka-backlog-list-id

Continuous status updates

While a task is in stage:in-progress, Kanban Workflow can post an automatic progress update comment every 5 minutes. Use runProgressAutoUpdates() and persist its state in your agent/runtime.

Recommended repo layout

scripts/: deterministic helper scripts used by adapters or the core.

references/: schemas and adapter notes (loaded on demand).

assets/: runbooks/SOP templates.

Repo status

The current core implementation is in TypeScript under src/.

Next implementation steps

1) Extend the adapter port to include idempotent write operations (comment/transition/label) in addition to fetchSnapshot(). 2) Finish and validate the Plane + Linear adapters (consume ClawHub skill plane output schema; Linear uses scripts/linear_json.sh JSON compatibility wrapper). 3) Decide on the authoritative mapping rule for stage → platform state (names vs explicit mapping table) and codify it. 4) Add a small CLI surface for Kanban Workflow itself (e.g. kanban-workflow tick --adapter plane --workspace ... --project ...).