Kanban Workflow Export

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)...

Security Scan

The skill's code, instructions, and optional environment variables are consistent with its stated purpose: it shells out to adapter CLIs (or small wrapper scripts) to integrate PM platforms and does not request unrelated credentials or perform hidden network installs.

Purpose & Capability

Name/description match the code and runtime instructions. Adapters and optional env vars (PLANE_API_KEY, PLANE_WORKSPACE, LINEAR_API_KEY) correspond to the stated platform integrations. No unrelated credentials, binaries, or config-path access are requested.

Instruction Scope

SKILL.md instructs the agent to run Node/npm and to call platform CLIs or bundled wrapper scripts (e.g., scripts/linear_json.sh, scripts/planka_whoami_json.mjs). Those instructions are aligned with the adapter model, but they explicitly grant the skill the same privileges as the chosen CLIs (the README/SECURITY.md also note this). The skill reads/writes its own config/kanban-workflow.json and may install an OpenClaw cron job if you opt into --autopilot-install-cron.

Install Mechanism

There is no opaque download/install in the skill bundle. The package includes source and a package-lock.json; SKILL.md instructs users to run npm ci locally. No external arbitrary URL downloads or extract steps are present in the provided files.

Credentials

No global required environment variables; optional API keys are adapter-specific and justified by their adapters (Linear/Plane). The linear wrapper script will fail if LINEAR_API_KEY is absent, but that is consistent with using the linear adapter. No unrelated secrets or broad system credentials are requested.

Persistence & Privilege

always:false (default). The skill persists config in-repo (config/kanban-workflow.json) and can optionally install a scheduled cron job via a setup flag. These behaviors are documented and expected for a scheduler/agentic worker, but you should only enable autopilot/crons if you trust the runtime and adapter CLI auth.

Assessment

This skill appears coherent with its purpose: it is a TypeScript core that delegates auth/actions to platform CLIs and a few small wrapper scripts. Before installing or running it, review and accept the following: 1) It will execute host CLIs (gh, planka-cli, plane, curl/jq) and therefore inherits their permissions—use least-privilege tokens/accounts for those CLIs. 2) If you select the Linear or Plane adapters you will need API keys (LINEAR_API_KEY, PLANE_API_KEY) which are used by bundled scripts; keep those scoped and stored securely. 3) Setup can write config/kanban-workflow.json into the repo and (if you opt in) install a recurring cron job that will run automations—only enable cron/automation if you want autonomous operations. 4) The repo includes wrapper scripts (scripts/linear_json.sh and scripts/planka_whoami_json.mjs); inspect them if you want to confirm network endpoints and parsing behavior (the Linear script calls api.linear.app). 5) There are no hidden remote installers in the bundle, but running npm ci will install dependencies from npm (inspect package.json/package-lock.json if you need to audit dependencies). If you want an extra safety layer, run the skill in an isolated environment (container/VM) and limit adapter credentials to scoped tokens.

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 <verb>; see README for setup flags)

CLI ergonomics: "What next" tips

All kanban-workflow <verb> 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 <github|plane|linear|planka> ...
• 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 <owner/repo>, optional --github-project-number <number>
• Plane: --plane-workspace-slug <slug>, --plane-project-id <uuid>, optional --plane-order-field <field>
• Linear: --linear-team-id <id> or --linear-project-id <id>, optional --linear-view-id <id>
• Planka: --planka-board-id <id>, --planka-backlog-list-id <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 ...).