Skill: simonvanlaak/kanban-workflow-export (version 0.1.4)

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


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (HIGH)