kanban-workflow

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