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

Security Scan

The skill's code and SKILL.md are coherent with the stated purpose (CLI-based PM adapters), but the package/registry metadata omits important operational requirements (binaries, config paths, and install steps), and there are a few operational behaviors (periodic auto-comments, filesystem writes) you should confirm before installing.

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.

What to consider before installing

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.

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

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 plane-cli / linear-cli output schemas).
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 ...).