Description

Kanban Workflow is a TypeScript skill for a stage-based agentic co-worker that integrates PM platforms via CLI-auth adapters only (no direct HTTP auth). It p...

README (SKILL.md)

Kanban Workflow (core)

Name: Kanban Workflow
Author: simonvanlaak

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 CLI-managed auth only (no direct HTTP auth handling).
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-cli, linear-cli), relying on their auth/session.
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 (plane-cli; Api2Cli workspace)
linear.ts (linear-cli; Api2Cli workspace)

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
automations: runProgressAutoUpdates()

CLI entry point:

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

CLI ergonomics: "What next" tips

All kanban-workflow \x3Cverb> 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 \x3Cgithub|plane|linear|planka> ...
stage mapping flags: --map-backlog, --map-blocked, --map-in-progress, --map-in-review

Adapter flags (summary):

GitHub: --github-repo \x3Cowner/repo>, optional --github-project-number \x3Cnumber>
Plane: --plane-workspace-slug \x3Cslug>, --plane-project-id \x3Cuuid>, optional --plane-order-field \x3Cfield>
Linear: --linear-team-id \x3Cid> or --linear-project-id \x3Cid>, optional --linear-view-id \x3Cid>
Planka: --planka-board-id \x3Cid>, --planka-backlog-list-id \x3Cid>

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

Extend the adapter port to include idempotent write operations (comment/transition/label) in addition to fetchSnapshot().
Finish and validate the Plane + Linear adapters (consume plane-cli / linear-cli output schemas).
Decide on the authoritative mapping rule for stage → platform state (names vs explicit mapping table) and codify it.
Add a small CLI surface for Kanban Workflow itself (e.g. kanban-workflow tick --adapter plane --workspace ... --project ...).

Usage Guidance

What to check before installing: - Confirm your expectations: this skill runs platform CLIs (gh, planka-cli, plane-cli, linear-cli) via child processes and relies on their local authentication — it does NOT accept API tokens itself. Make sure those CLIs are installed and authenticated for the adapter(s) you plan to use. - Metadata mismatch: the skill package contains Node source and dependencies (package.json / package-lock.json) and the README recommends `npm install`, but there is no install spec in the registry metadata. Ensure dependencies are installed in a controlled environment before running. - Config and filesystem writes: the CLI will write config/kanban-workflow.json and may persist snapshots/state to disk (data/ or similar). Review and approve those paths in your repo or run the skill in a sandboxed workspace. - Automation side-effects: the skill exposes runProgressAutoUpdates() which posts progress comments every ~5 minutes while an item is in 'in-progress'. If you enable automations, expect frequent remote writes (comments) — review the implementation and consider restricting or rate-limiting automations initially. - Review code for adapter behavior: the adapters call CLIs and parse output (including a small Planka whoami wrapper). Inspect the adapter code (present in the repo) to confirm it only performs the expected actions (list, comment, set labels/stage, create) and does not call unexpected network endpoints. - Recommended safe steps: run the test suite locally (npm install → npm test) in a sandboxed environment; run the CLI only in user-invoked mode first; ensure backups or git staging before allowing config/state writes; and add the missing required-binaries and config-paths information to your inventory before trusting the skill for autonomous use.

Capability Analysis

Type: OpenClaw Skill Name: kanban-workflow Version: 0.1.12 The skill is classified as suspicious due to potential shell injection vulnerabilities. User-controlled input (e.g., `--title`, `--body`, `--text` from `src/cli.ts`) is passed as arguments to external CLI commands (e.g., `gh`, `plane`) via `execa` in adapter files like `src/adapters/github.ts` and `src/adapters/plane.ts`. While `execa` mitigates basic shell injection by separating command and arguments, if the underlying external CLIs do not properly sanitize or quote these arguments, a crafted input could lead to arbitrary command execution. There is no evidence of intentional malicious behavior like data exfiltration or backdoors, and the documentation (`SKILL.md`, `README.md`) is benign.

Capability Assessment

⚠ Purpose & Capability

The skill claims to integrate via CLI-auth only and the code implements adapters that call platform CLIs (gh, planka-cli, plane-cli, linear-cli) via execa — that is consistent with the stated purpose. However the registry metadata declares no required binaries and no required config paths while SKILL.md and the code clearly expect platform CLIs to be present and a repo config file (config/kanban-workflow.json). The metadata therefore understates the actual capabilities/requirements.

ℹ Instruction Scope

SKILL.md and the source stay within the Kanban workflow scope: they poll platforms via CLIs, normalize snapshots, and provide verbs (show/next/start/update/ask/complete/create) plus an automation helper to post periodic progress comments. The instructions do include writing a repo config file (config/kanban-workflow.json) and recommend persisting runtime automation state; they also call arbitrary CLIs on the host (expected for adapters). There is nothing in the instructions that attempts to read unrelated secrets or exfiltrate data to third‑party endpoints, but the automation that posts comments every 5 minutes is a persistent side-effect you should be aware of.

⚠ Install Mechanism

This package contains a Node project (package.json, package-lock.json, TypeScript sources) but the skill bundle has no install spec. The README suggests running `npm install` and the code depends on execa/zod/etc. That mismatch means the registry metadata does not declare the real installation step required to run the code; if the platform does not automatically install dependencies the skill may fail or an operator might run ad-hoc installs. No external download URLs or shorteners are used in the repo itself.

⚠ Credentials

The skill requests no direct credentials (it intentionally relies on local CLI-auth sessions), which is proportionate. However the registry metadata states 'no required binaries' and 'no required config paths' despite the SKILL.md and code clearly requiring platform CLIs and a config file under config/kanban-workflow.json. The only env var referenced in code is an optional PLANKA_CLI_BIN for the Planka whoami wrapper; there are no direct secret/env requirements. Overall the omission in metadata is the key proportionality concern.

ℹ Persistence & Privilege

The skill writes a repo config file (config/kanban-workflow.json) and the docs/references propose persisting runtime state (snapshots, cursors) under the repo or data directories. This is normal for a CLI tool of this type, and the skill does not request elevated system privileges nor 'always: true'. Still, you should expect the skill to write files under the repository (config/ and potentially a data/ or state/ path) and to post comments to remote PM platforms as part of automations.

Version History

v0.1.12

Plane adapter: implement write verbs via plane CLI (issues update --state, comments add, create + assign-to-self).

v0.1.11

Plane adapter: prefer -f json (a2c/plane-cli) and fall back to --format json; add formatArgs override.

v0.1.10

Docs/security: clarify adapter-managed auth; wrappers may call HTTPS APIs using env API keys (e.g. Linear).

v0.1.9

Setup auto-discovery defaults: GitHub all repos (all orgs), Linear all teams, Planka boards+backlog lists (by list name).

v0.1.8

Multi-scope + assigned-only defaults across GitHub/Linear/Planka; Plane keeps default all-projects.

v0.1.7

Plane setup default scope is now all-projects; single-project is opt-in via --plane-scope project.

v0.1.6

Docs: clarify assigned-only queue semantics + multi-scope consistency requirements.

v0.1.4

Plane multi-project scope (assigned-only)

v0.1.3

- Initial release of the Kanban Workflow skill with TypeScript core. - Integrates with GitHub, Planka, Plane, and Linear via CLI-first adapters (no direct API auth). - Supports canonical stage-based workflow: backlog, blocked, in-progress, in-review. - Includes setup, core workflow verbs (show/next/start/update/ask/complete/create), polling/diff, and automation hook groundwork. - CLI setup validates external CLI presence and provides platform-specific flags. - Extensive documentation added (architecture, setup, extension guidance).

v0.1.2

Packaging: remove local venv/pytest cache artifacts

v0.1.1

Plane adapter uses ClawHub plane skill; Linear adapter uses ClawHub linear skill via JSON wrapper.

v1.0.0

Initial release of kanban-workflow. - Added core documentation outlining goals, architecture, and canonical stage model. - Provided setup instructions and required CLI authentication workflow for supported PM platforms. - Defined CLI command structure, supported verbs, and repo recommendations. - Explained adapter integration via CLI wrappers for GitHub, Plane, Linear, and Planka. - Included instructions for continuous status update automation. - Added .gitignore and project origin metadata files.

v0.1.0

Initial release: setup + verbs + adapters (GitHub/Plane/Linear/Planka) + tests.

Metadata

Slug kanban-workflow

Version 0.1.12

License —

All-time Installs 1

Active Installs 0

Total Versions 13

Frequently Asked Questions

What is Kanban Workflow?

Kanban Workflow is a TypeScript skill for a stage-based agentic co-worker that integrates PM platforms via CLI-auth adapters only (no direct HTTP auth). It p... It is an AI Agent Skill for Claude Code / OpenClaw, with 558 downloads so far.

How do I install Kanban Workflow?

Run "/install kanban-workflow" in the OpenClaw or Claude Code chat to install it in one step — no extra setup required.

Is Kanban Workflow free?

Yes, Kanban Workflow is completely free (open-source). You can download, install and use it at no cost.

Which platforms does Kanban Workflow support?

Kanban Workflow is cross-platform and runs anywhere OpenClaw / Claude Code is available (cross-platform).

Who created Kanban Workflow?

It is built and maintained by Simon van Laak (@simonvanlaak); the current version is v0.1.12.

More Skills

Kanban Workflow