@polderlabs/openkan 0.4.0

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@polderlabs/openkan",
+  "version": "0.4.0",
+  "description": "Local-first MDX kanban with native Claude Code control plane, .ok/ planning system, and embedded chat sidebar.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PolderLabsVOF/openkan.git"
+  },
+  "homepage": "https://github.com/PolderLabsVOF/openkan#readme",
+  "bugs": {
+    "url": "https://github.com/PolderLabsVOF/openkan/issues"
+  },
+  "keywords": [
+    "kanban",
+    "agents",
+    "tasks",
+    "goals",
+    "cli",
+    "local-first"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "files": [
+    "bin/*.mjs",
+    "dist",
+    "agents",
+    "skills/openkan",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "bin": {
+    "openkan": "bin/openkan.mjs",
+    "ok": "bin/ok.mjs"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "postinstall": "node bin/install-agent.mjs",
+    "prepack": "npm run build",
+    "test:package": "node scripts/test-package.mjs",
+    "test": "node --test --experimental-strip-types tests/*.test.mts tests/*.test.mjs",
+    "typecheck": "tsc --noEmit --allowImportingTsExtensions --allowJs --checkJs --skipLibCheck --target ES2022 --module ESNext --moduleResolution Bundler bin/*.ts kanban/*.ts ok/*.ts ok/commands/*.ts",
+    "check": "node --experimental-strip-types scripts/sanity-check.ts",
+    "e2e": "node --experimental-strip-types scripts/claude-e2e.mts",
+    "openkan": "node --experimental-strip-types bin/openkan.ts",
+    "ok": "node --experimental-strip-types bin/ok.ts",
+    "ok-install": "node --experimental-strip-types bin/ok-install.ts"
+  },
+  "dependencies": {
+    "gray-matter": "^4.0.3",
+    "gsap": "^3.15.0",
+    "marked": "^14.0.0",
+    "nanoid": "^5.0.0",
+    "sanitize-html": "^2.13.0",
+    "sucrase": "^3.34.0",
+    "ws": "^8.21.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/sanitize-html": "^2.13.0",
+    "@types/ws": "^8.18.1",
+    "typescript": "^5.7.3"
+  }
+}

package/skills/openkan/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: openkan
+description: Manage project tasks, goals, plans, progress and agent work through the OpenKan CLI. Use when a project contains .ok/ or the user asks to track project work with OpenKan.
+---
+
+# OpenKan project workflow
+
+Use `openkan` commands, not handwritten HTTP requests or direct JSON edits.
+`.ok/` is the durable workspace; `.openkan/` is legacy import input only.
+Run from the project root or a child directory of an existing `.ok/` workspace.
+
+## Install and discover
+
+```sh
+npm install -g @polderlabs/openkan
+openkan skill install --agent all
+openkan init
+openkan task list --json
+openkan prd list --json
+openkan goal list --json
+openkan progress --json
+```
+
+Installation is a one-time setup, not a per-task operation. Reuse a matching task
+if one exists. Planning commands work offline without a server. The shorter `ok`
+command supports the same task/plan/prd/goal/progress operations. Use
+`openkan --help` and `ok help` for the command reference.
+
+## Track execution
+
+```sh
+openkan task add "Deliver scoped change" --owner codex --priority p1 --acceptance "Regression test passes|Installed CLI works"
+openkan task claim tsk-ID --owner codex
+openkan task heartbeat tsk-ID --owner codex
+openkan task update tsk-ID --evidence "Implemented X; test Y passed; Z remains"
+openkan task update tsk-ID --status review
+openkan task complete tsk-ID --owner codex --evidence "Test command and outcome; commit or file reference"
+```
+
+Claims default to a one-hour lease; refresh during longer work. Do not take
+another owner's claim or complete work without validation evidence. Cancel with
+`task cancel <id> --owner NAME --reason TEXT`; release a claim with `task release`.
+Read and list commands support `--json`; existing mutation commands print the
+entity ID (do not assume every mutation returns JSON).
+
+## Goals and progression
+
+Goals belong to a PRD, not a separate store. Save IDs from creation commands
+and substitute them below; do not use the example placeholders literally.
+
+```sh
+openkan prd add "Release outcome" --vision "Why it matters" --goals "Ship CLI|Verify install"
+openkan prd update prd-ID --status active
+openkan plan add "Release phase" --prd prd-ID --summary "Implementation and validation"
+openkan task add "Verify clean install" --prd prd-ID --plan pln-ID --owner codex
+openkan goal add prd-ID "Publish package" --json
+openkan goal update prd-ID g1 --status in_progress
+openkan goal update prd-ID g1 --status met
+openkan plan update pln-ID --phase validation --status active
+openkan progress --prd prd-ID --json
+```
+
+`progress` reports status counts, completion percentages and dependency-ready
+tasks. Cancelled/dropped/abandoned items are excluded from completion denominators;
+empty denominators report 0%. It does not mark goals or plans complete for you.
+Use `goal show <prd> <goal>` for detail and `goal update ... --text TEXT` to edit.
+
+## Dashboard tasks and collaboration
+
+The visual board and planning records are related but distinct surfaces. Do not
+assume a planning-only task is already a board card. Use board commands for cards
+and include the planning ID in their description when tracking both.
+
+```sh
+openkan start --no-open
+openkan project list
+openkan project use PROJECT_ID
+openkan board list
+openkan board add "Visible work item" --description "Planning task: tsk-ID" --column doing
+openkan board show BOARD_TASK_ID
+openkan board comment BOARD_TASK_ID "Changed X; validation Y passed" --author agent:codex
+openkan board move BOARD_TASK_ID review
+openkan board move BOARD_TASK_ID done
+```
+
+Board commands require the local server and reject a mismatched dashboard
+project. Their output is JSON. Select the intended project explicitly. Pass
+`--port N` if the server is not using its configured default port.
+
+## Agent and advanced features
+
+```sh
+openkan agent capabilities
+openkan agent context
+openkan agent start BOARD_TASK_ID --agent AGENT_ID --model MODEL_ID
+openkan agent abort BOARD_TASK_ID
+openkan import --path notes.md
+```
+
+For less common features (docs, chat, structured inputs, bulk changes), consult
+[the API reference](references/api.md) and use `openkan api /api/PATH` or
+`openkan agent call`. These commands handle transport; do not use `curl`.
+`openkan api` targets the dashboard's selected project, not necessarily cwd.
+Use `--method`, `--data` or `--data-file`, and `--json` for structured requests.
+Native Claude state is observational: never mutate Claude runtime files.
+
+## Finish
+
+Run validation, append evidence, re-read current task state, then complete the
+task and update associated goals/plan only when their criteria are met.
+Run `openkan doctor` and leave unresolved work visible rather than marking it done.

package/skills/openkan/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "OpenKan Project Workflow"
+  short_description: "Keep agent work synchronized in OpenKan"
+  default_prompt: "Use openkan task, goal, plan, progress and board commands to track this project. Keep status and verification evidence current without handwritten HTTP requests."

package/skills/openkan/examples/simple-task.mdx

@@ -0,0 +1,34 @@
+---
+id: tsk-example-simple
+title: Fix the login redirect on SSO failure
+description: Users who fail SSO authentication get a 404 page. They should be redirected back to the login page with an error message.
+tags:
+  - bug
+  - frontend
+category: frontend
+priority: high
+effort: s
+state: idle
+created: 2026-07-06
+---
+
+## Background
+
+When SSO authentication fails (e.g. token expired, user not found in the IdP), the callback handler throws an unhandled error and renders a 404 page. The user has no way to retry and no error message explaining what went wrong.
+
+## Acceptance criteria
+
+- SSO callback catches `AuthenticationError` and `TokenExpiredError`
+- Redirects to `/login?error=sso_failed` instead of 404
+- Login page shows a banner: "SSO login failed. Please try again or use email/password."
+- Log the failure to `sso.log` for debugging
+
+## Implementation notes
+
+The callback is in `src/auth/sso.ts`, the `handleCallback` function around line 142. The login page template is at `src/pages/login.tsx`. Add a query-parameter check for `error=sso_failed` and display a warning alert above the login form.
+
+## Files touched
+
+- `src/auth/sso.ts` — catch + redirect
+- `src/pages/login.tsx` — error banner
+- `src/lib/sso-logger.ts` — structured logging (new file, optional)

package/skills/openkan/examples/with-ask.mdx

@@ -0,0 +1,32 @@
+---
+id: tsk-example-ask
+title: Design the new dashboard layout
+description: Proposing three layout options for the main dashboard. Need user input on which direction to take.
+tags:
+  - feature
+  - ux
+  - frontend
+category: frontend
+priority: normal
+effort: m
+state: waiting-for-input
+created: 2026-07-06
+---
+
+## Proposal
+
+I've sketched three layout directions for the new dashboard. Each one emphasizes different priorities:
+
+### Option A — Sidebar nav
+
+A persistent left sidebar with collapsible sections. Content area on the right. Best for power users who need quick access to many sections. Familiar pattern from tools like Linear and Notion.
+
+### Option B — Top nav + tabbed panels
+
+A horizontal top navigation bar with a tabbed main area. Keeps the full viewport width for content. Best for data-dense dashboards where screen real estate matters.
+
+### Option C — Card-based hub
+
+A grid of large cards, each representing a workspace or project. Minimal navigation — the user clicks into a card to drill down. Best for managers who oversee multiple projects and want a summary-first view.
+
+<Ask question="Which layout direction should I take? Option A (sidebar), Option B (top nav), or Option C (card hub)? Do you have any other preferences or constraints I should consider?" />

package/skills/openkan/examples/with-choice.mdx

@@ -0,0 +1,51 @@
+---
+id: tsk-example-choice
+title: Pick the color palette for dark mode
+description: Three dark-mode color palettes to choose from. The user picks one, and I'll implement it across the app.
+tags:
+  - feature
+  - ux
+  - frontend
+category: frontend
+priority: normal
+effort: l
+state: waiting-for-input
+created: 2026-07-06
+---
+
+## Background
+
+The app already supports light mode. I'm adding a dark mode toggle and need to pick a color palette. I've narrowed it down to three options based on contrast ratios, WCAG compliance, and aesthetic fit.
+
+### Palette 1 — "Midnight"
+- Background: `#0f172a` (slate-900)
+- Surface: `#1e293b` (slate-800)
+- Primary: `#38bdf8` (sky-400)
+- Text: `#f1f5f9` (slate-100)
+- Accent: `#a78bfa` (violet-400)
+- Good for: data-heavy dashboards, professional tone
+
+### Palette 2 — "Onyx"
+- Background: `#18181b` (zinc-900)
+- Surface: `#27272a` (zinc-800)
+- Primary: `#34d399` (emerald-400)
+- Text: `#fafafa` (zinc-50)
+- Accent: `#fb923c` (orange-400)
+- Good for: creative tools, warm feel
+
+### Palette 3 — "Abyss"
+- Background: `#000000`
+- Surface: `#111111`
+- Primary: `#60a5fa` (blue-400)
+- Text: `#e5e7eb` (gray-200)
+- Accent: `#f472b6` (pink-400)
+- Good for: OLED screens, media consumption apps
+
+<Choice
+  question="Which palette should I use for dark mode?"
+  options={[
+    { id: "midnight", label: "Midnight", description: "Slate-based, professional, data-dashboards" },
+    { id: "onyx", label: "Onyx", description: "Zinc-based, warm, creative tools" },
+    { id: "abyss", label: "Abyss", description: "True black, OLED-friendly, media-focused" },
+  ]}
+/>

package/skills/openkan/examples/with-preview.mdx

@@ -0,0 +1,54 @@
+---
+id: tsk-example-preview
+title: Design the new button component variants
+description: Playing with three button variants for the new component library. Preview them in the sandbox below.
+tags:
+  - feature
+  - ux
+  - frontend
+category: frontend
+priority: normal
+effort: s
+state: idle
+created: 2026-07-06
+---
+
+## Button variants
+
+Here's a live preview of the three button styles I'm proposing. Click one to send feedback — each button calls `respond()` with its variant name.
+
+<Preview
+  tsx={`function ButtonPreview() {
+  return (
+    <Column gap={16}>
+      <Text size={18} weight={700}>Button Variants</Text>
+      <Row gap={12} wrap>
+        <Button
+          label="Primary"
+          onClick={() => respond("primary-clicked")}
+        />
+        <Button
+          label="Secondary"
+          variant="secondary"
+          onClick={() => respond("secondary-clicked")}
+        />
+        <Button
+          label="Danger"
+          variant="danger"
+          onClick={() => respond("danger-clicked")}
+        />
+      </Row>
+      <Text size={14} color="#94a3b8">
+        Click a button to register your preference.
+      </Text>
+    </Column>
+  );
+}`}
+  props={{}}
+/>
+
+## What do you think?
+
+Once you've clicked a button, let me know your feedback on the styles. I can adjust colors, sizes, corner radii, or add loading states.
+
+<Ask question="Which button variant do you prefer and what adjustments would you like?" />

package/skills/openkan/references/api.md

@@ -0,0 +1,169 @@
+# OpenKan agent API reference
+
+The local server defaults to `http://127.0.0.1:7777`. Use the port reported
+by `openkan status` when the project overrides it.
+
+All endpoints are loopback-only. Authentication is not provided; do not
+expose the port to a network.
+
+## Board and tasks
+
+```text
+GET    /api/board
+GET    /api/tasks-index
+GET    /api/tasks/:id
+POST   /api/tasks
+PATCH  /api/tasks/:id
+DELETE /api/tasks/:id
+POST   /api/tasks/:id/archive
+POST   /api/tasks/:id/restore
+GET    /api/tasks/:id/subtasks
+POST   /api/tasks/bulk
+GET    /api/search?query=<text>
+```
+
+Task columns are `backlog`, `todo`, `doing`, `review`, and `done`. Preserve
+task IDs. Prefer archive over delete when history may remain useful.
+
+## Comments and input
+
+```text
+GET    /api/tasks/:id/comments
+POST   /api/tasks/:id/comments
+PATCH  /api/tasks/:id/comments/:commentId
+DELETE /api/tasks/:id/comments/:commentId
+POST   /api/tasks/:id/ask
+POST   /api/tasks/:id/respond
+```
+
+A comment requires `blockId`, `text`, and normally `line` and `author`.
+Resolving a comment accepts:
+
+```json
+{"resolved":true,"reason":"Addressed in commit abc123","author":"agent:mike"}
+```
+
+A choice input uses option objects with stable IDs:
+
+```json
+{
+  "type": "choice",
+  "question": "Which option?",
+  "options": [
+    {"id":"a","label":"Option A","description":"Tradeoff"},
+    {"id":"b","label":"Option B","description":"Tradeoff"}
+  ]
+}
+```
+
+## M1 checkbox import
+
+```text
+POST   /api/import
+```
+
+Body:
+
+```json
+{"path":"notes.md","include":"**/*.md","exclude":"**/archive/**"}
+```
+
+Returns `{ imported: [{ id, source: { path, line } }], skipped: number }`.
+Imported tasks carry `source.path` and `source.line` so the dashboard can
+deep-link back to the original Markdown file.
+
+## Native Claude Code control plane
+
+Read the live snapshot first; it lists agents, teams, workflows, and
+sessions without polling.
+
+```text
+GET    /api/claude/snapshot
+GET    /api/claude/agents
+GET    /api/claude/skills
+GET    /api/claude/commands
+GET    /api/claude/hooks
+GET    /api/claude/teams
+GET    /api/claude/workflows
+GET    /api/claude/model-router
+GET    /api/claude/activity-tail?limit=200
+```
+
+Live updates stream over WebSocket and SSE. The WebSocket sends the full
+snapshot on connect, then deltas:
+
+```text
+ws://127.0.0.1:7777/api/claude/ws
+GET  /api/claude/events                 (SSE)
+```
+
+Message shapes from the bridge:
+
+```json
+{"type":"snapshot","data":{...}}
+{"type":"delta","data":{"agents":[...],"sessions":[...]}}
+```
+
+## Chat sidebar (in development)
+
+Backend routes are subject to change while the feature lands. Session
+transcripts persist to `.ok/chat/<sid>.jsonl`.
+
+```text
+POST   /api/chat/send                    spawn `claude -p` and persist both turns
+GET    /api/chat/sessions                list active + archived
+GET    /api/chat/sessions/<sid>          full transcript
+DELETE /api/chat/sessions/<sid>          archive
+POST   /api/chat/sessions/<sid>/abort    kill running subprocess
+GET    /api/chat/sessions/<sid>/events   SSE stream of new turns
+```
+
+Send body:
+
+```json
+{
+  "sessionId": "ses-optional-or-omit-for-new",
+  "message": "Review the latest task state",
+  "model": "sonnet",
+  "effort": "medium",
+  "permissionMode": "default"
+}
+```
+
+`permissionMode` accepts `accept-edits | default | plan | bypass-permissions`.
+
+## Insights
+
+```text
+GET    /api/insights/velocity?days=30
+```
+
+Returns zero-filled arrays when the changelog is empty or missing:
+
+```json
+{
+  "windowDays": 30,
+  "generatedAt": "2026-09-04T12:00:00.000Z",
+  "columns": {
+    "backlog": [0,0,0,...],
+    "todo":    [0,0,0,...],
+    "doing":   [0,0,0,...],
+    "review":  [0,0,0,...],
+    "done":    [0,0,0,...]
+  },
+  "days": ["2026-08-05","2026-08-06",...]
+}
+```
+
+## What you must NOT do
+
+- Do not edit `.ok/board.json`, `.ok/tasks/<id>.json`, or `.ok/chat/*.jsonl`
+  directly. Use the HTTP routes so the mirror hooks, watchers, and indexes
+  stay in sync.
+- Do not bypass the loopback. These endpoints assume `127.0.0.1`; exposing
+  them gives unauthenticated write access to the project.
+- Do not delete `.ok/` to "reset" — it removes audit history. Use
+  `openkan archive` and the planning system's `ok prd close` instead.
+- Do not assume a Claude control-plane endpoint is read-write. `/api/claude/*`
+  is observability only; writes happen via the chat sidebar or via direct
+  Claude Code CLI usage.

package/skills/openkan/templates/task.mdx

@@ -0,0 +1,46 @@
+---
+title: <short title>
+id: tsk-xxxxxxxx
+column: todo
+state: idle
+priority: normal
+effort: null
+tags: []
+category: task
+assignees: []
+parentId: null
+subtaskIds: []
+createdAt: <iso>
+updatedAt: <iso>
+---
+
+# <title>
+
+## Goal
+
+{/* One sentence: what does "done" look like for this task? */}
+
+{/* If this task has subtasks, they appear as a Subtasks section in the web UI. Subtasks block the parent from being marked done until they are all completed. */}
+
+## Context
+
+{/* Background: why this matters, what depends on it, links to related work. */}
+
+## Acceptance criteria
+
+- [ ] {/* Outcome 1 the user can verify */}
+- [ ] {/* Outcome 2 */}
+
+## Files to touch
+
+- {/* `path/relative/to/repo.ext` — what changes here */}
+
+## Safety
+
+- Do not modify unrelated files.
+- Stop and ask if requirements conflict.
+- Fill the agent progress section before moving to Review.
+
+## Agent progress
+
+{/* Timestamped one-liners auto-appended here as you work. */}