docs: v1.0.5 candidate — Worker Skill Quick Start, Use Cases, integration docs

README/README_CN Quick Start rewritten as the five-step released-binary +
light-kanban-worker Skill path with a copyable scheduler prompt and a
one-shot manual run example; Use Cases added (scheduled coding agent,
multi-agent queue, review loop, blocked work, cross-project queue,
boundary); raw curl demoted to Manual Agent Integration. spec.md records
the v1.0.5 no-API-change Worker Integration decisions; manual checklist
gains section S (worker integration) with regenerated xlsx; frontend
version bumped to 1.0.5; PROGRESS records the v1.0.5 candidate and its
release gate. make check and make cross (4 platforms) PASS.

Author: Light Cheng

.scratch/task-board/spec.md

@@ -140,3 +140,52 @@ Status: ready-for-agent
 - The `.scratch/` issue tracker set up by `/setup-matt-pocock-skills` tracks **Light-Kanban's own development**; it is distinct from the tasks this board manages.
 - The "constraint" model: identity and tags are reserved fields plus agent-facing instructions — agents self-configure when claiming, keeping the board minimal and avoiding human data entry.
 - Agents are expected to call the API from their own scheduled tasks; scheduling/orchestration is outside this board's responsibility.
+
+## v1.0.5 Worker Integration
+
+Status: candidate (pending user acceptance before release).
+
+### No API change
+
+v1.0.5 adds **no new REST endpoint and changes no existing one**. The Worker
+Skill uses exactly the v1.0.4+ surface: `GET /api/agents`, `GET
+/api/tasks?status=in_progress|todo`, `POST /api/tasks/:id/claim|block|
+complete`, `POST /api/avatars`. The API contract above remains the single
+board-side authority.
+
+### Agent-side protocol moves to a Skill
+
+- The official agent-side protocol is the first-party **`light-kanban-worker`**
+  Skill in `LightDevCoder/skills` (released in Skills v0.1.4, compatible with
+  Light-Kanban v1.0.4+). Its `SKILL.md` is the authority for agent behavior;
+  this spec is the authority for board behavior — the two contracts are kept
+  separate on purpose.
+- Golden flow (Skill side): resolve stable identity → check owned
+  in_progress (reviewFeedback first) → otherwise claim the first FIFO todo
+  (at most 2 claim attempts on conflict) → validate `workspacePath` on the
+  agent host (unreachable workspace → block with a meaningful reason) →
+  execute inside the project's own workflow → `complete` (→ 等你确认) or
+  `block` with a concrete reason → stop. At most ONE task per run; no
+  daemon, no polling loop, no auto-archive/accept/delete/recycle/unblock.
+- Review boundary: 等你确认 is human-owned (accept / request changes). A
+  Request Changes rejection sets `reviewFeedback` and returns the task to
+  处理中, where the same agent's next run resumes it first.
+
+### Scheduler boundary
+
+The scheduler (cron, orchestrator, scheduled agent run) decides **when** the
+agent wakes; Light-Kanban never starts agents. The scheduler prompt needs no
+knowledge of the REST API — one line suffices:
+
+```text
+Use light-kanban-worker to process at most one Light-Kanban task.
+```
+
+### Validation for this release
+
+- Board-side: `make check` + `make cross` (four platforms), no Go/UI behavior
+  change — this release is documentation + integration packaging.
+- Cross-repo: the Worker Skill passed its full admission
+  (`review-loop agent-skill` PASS), behavioral scenarios A–F against a real
+  Light-Kanban server, and fresh-install verification from Skills v0.1.4.
+

PROGRESS.md

@@ -1,14 +1,23 @@
 # PROGRESS — 项目进度与交接记录
 
 > 本文档记录 Light-Kanban 的当前进度、约定、待办与 Mac 迁移指引，供后续维护者快速接上手。
-> 最后更新：2026-08-17（v1.0.4 已发布）
+> 最后更新：2026-08-17（v1.0.5 candidate 准备中）
 
 ## 1. 当前状态
 
 - **远端仓库**：https://github.com/LightDevCoder/light-kanban（public，gh 账号 LightDevCoder）
 - **最新发布**：`v1.0.4`（onboarding & archive release），tag `v1.0.4` + GitHub Release 齐全，四平台二进制已上传（Windows amd64 / Linux amd64 / macOS amd64 / macOS arm64）；`v1.0.3` 及更早的 tag / Release / 二进制保持原样
-- **当前工作**：无进行中的 release；v1.0.4 为最新稳定版本，后续改动等待真实使用反馈
-- **工作树**：与 origin/main 一致
+- **当前工作**：`v1.0.5 candidate`（Worker Skill 集成发布）——文档与版本已就绪，等待用户验收后发布（见第 2a 节）；Skills 侧 `LightDevCoder/skills v0.1.4` 已发布
+- **工作树**：见 git status（v1.0.5 变更未推送前为本地提交）
+
+## 2a. v1.0.5（candidate，未发布）
+
+- **目标**：把 Light-Kanban 从「agent 可通过 REST API 接入」推进为「安装一个 Skill + 建一个定时任务，agent 即可周期接活、执行、交回人工验收」
+- **无 Go / UI / API 变更**：v1.0.5 不新增、不修改任何 REST 端点；不修改 UI、不重新截图、不新增任务状态 / daemon / WebSocket / 认证 / scheduler
+- **Worker Skill（Skills 仓库，v0.1.4 已发布）**：第一方 `light-kanban-worker`（model-invoked，支持手动入口）——每次唤醒最多处理一张卡：稳定 identity（复用服务器已有 name/avatar）→ 先查自己持有的 in_progress（reviewFeedback 优先）→ 无遗留才领取 FIFO 第一张 todo（原子 claim，最多 2 次冲突重试）→ 校验 workspace（不可访问 → block 带具体原因）→ 读任务上下文 + 项目指令 → 执行 → `complete`（等你确认）或 `block` → 停止；绝不 archive/accept/delete/recycle/unblock，无 daemon / 无限轮询 / 运行时脚本
+- **准入与验证**：完整准入路径（`review-loop agent-skill` PASS，独立 Critic + Evaluator，3 findings 修复 + 1 驳回）；行为场景 A–F 对真实 Light-Kanban 服务器全 PASS（新任务 / 退回返工 / 双 worker 原子 claim / workspace 缺失 block / 空队列无变更 / 离线无变更）；v0.1.4 tag 发布后 fresh-install 验证 PASS（CLI 1.5.22，整集合 8 包 + 单 Skill，latest 与 #v0.1.4 形式，安装文件与 tag 逐字节一致）；Skills CI green（顺带修复 ask-light scanner 的跨平台 `Test-PathUnder` 分隔符 bug——v0.1.3 Python 移植后 ubuntu CI 一直红的存量问题）
+- **Light-Kanban 文档**：README / README_CN Quick Start 重写为五步（运行二进制 → 装 Worker Skill → 建卡 → scheduler prompt → 验收），新增 Use Cases（定时编码 Agent / 多 Agent 共享队列 / 人工验收闭环 / 阻碍工作 / 跨项目个人队列 / 边界说明），curl 降级到「手动 Agent 接入（API 方式）」；spec.md 新增「v1.0.5 Worker Integration」章节（无 API 变更 + Skill 协议 + scheduler 边界 + 验证）；manual-test-checklist.md 新增 S 节（8 条 worker 集成清单）+ xlsx 已重新生成；frontend/package.json + package-lock.json = `1.0.5`
+- **发布门禁**：Skills v0.1.4 已先发布并验证（README 引用真实 tag）；Light-Kanban 需 `make check` + `make cross` 四平台 PASS，然后**停下来等用户最终验收**；未经「可以发布」不得创建 v1.0.5 Release
 
 ## 2. v1.0.4（已发布）
 

README.md

@@ -2,6 +2,8 @@
 
 A self-hosted kanban board where a human queues tasks (each card points at a workspace folder) and autonomous agents claim, work, block on, and return them for human confirmation. Single Go binary: REST API + SQLite + embedded web UI (English / 中文).
 
+The recommended way for autonomous agents to work the board is the official **`light-kanban-worker` Skill** ([LightDevCoder/skills](https://github.com/LightDevCoder/skills) → `light-kanban-worker`): a scheduled agent installs it once and handles one task per wake-up — claiming, reworking, and returning work automatically. The raw REST API stays available for custom agents, scripts, and integrations (see [Manual Agent Integration](#manual-agent-integration-api-without-the-skill)). The authoritative Skill behavior lives in its [`SKILL.md`](https://github.com/LightDevCoder/skills/blob/main/skills/light-kanban-worker/SKILL.md); this README shows how the two fit together.
+
 [中文 README](README_CN.md) · [Download](https://github.com/LightDevCoder/light-kanban/releases)
 
 See `.scratch/task-board/spec.md` for the full spec, the state machine, and the API contract. See `CONTEXT.md` for the domain vocabulary.
@@ -73,27 +75,137 @@ The browser opens automatically; Ctrl+C stops. To allow other machines on the LA
 
 ## Quick Start
 
-Five steps get you from zero to a full loop (on first launch the web UI runs an interactive product tour over the real interface — click the highlighted controls and it follows you through task creation, the drawer, settings and the archive; finish it once, or reopen it anytime from the settings menu):
+Five steps get you from zero to **Light-Kanban + a scheduled agent** in about five minutes. (On first launch the web UI runs an interactive product tour over the real interface — click the highlighted controls and it follows you through task creation, the drawer, settings and the archive; finish it once, or reopen it anytime from the settings menu.)
 
-1. **Start the service**: `dist\light-kanban.exe` on Windows (other platforms: `make build && ./dist/light-kanban`), then open http://127.0.0.1:8641. (LAN agents need `-addr :8641` — see above.)
+### Step 1 — Run Light-Kanban
 
-2. **Add a task**: click "**+**" in the top bar (or the "+" in the To Do column header), fill in the title + workspace folder path (type/paste it, or click "Choose…" to open the system folder dialog); description / tags / due date are optional → the task lands in the **To Do** column.
+Download the binary for your machine from [Releases](https://github.com/LightDevCoder/light-kanban/releases) (see the table under [Install & Run](#install--run-per-platform)), put it in a dedicated folder, and **double-click / execute it**. The browser opens the board automatically at http://127.0.0.1:8641. (Agents on *other machines* need `-addr :8641` — see above.)
 
-3. **An agent claims it** (agents self-register and claim via the API):
+### Step 2 — Install the Worker Skill
 
-   ```sh
-   curl "http://127.0.0.1:8641/api/tasks?status=todo"             # find available work (todo only)
-   curl -F "file=@avatar.png" http://127.0.0.1:8641/api/avatars   # upload an avatar, note the returned path
-   curl -X POST -H "Content-Type: application/json" \
-     -d '{"agentId":"my-agent","name":"My Agent","avatar":"/api/avatars/xxx.png"}' \
-     http://127.0.0.1:8641/api/tasks/<id>/claim
-   ```
+Install the official worker Skill for your agent host:
+
+```bash
+npx skills add LightDevCoder/skills#v0.1.4 \
+  --skill light-kanban-worker \
+  --yes \
+  --copy \
+  --agent '*'
+```
+
+Source and docs: [LightDevCoder/skills](https://github.com/LightDevCoder/skills) → [`skills/light-kanban-worker/`](https://github.com/LightDevCoder/skills/tree/main/skills/light-kanban-worker) (behavior authority: its `SKILL.md`). Works with Light-Kanban v1.0.4+.
+
+### Step 3 — Create Work
+
+On the board, click "**+**" and fill in the task, e.g.:
+
+```text
+Title:      Fix login redirect bug
+Workspace:  ~/projects/my-app
+Description: Reproduce the OAuth redirect issue,
+             fix it, run tests and return it for review.
+```
+
+The task lands in **To Do**.
+
+### Step 4 — Schedule the Agent
+
+Point your scheduler at this prompt (any scheduler product that can run your agent on a timer — cron, an orchestrator, a scheduled agent job):
+
+```text
+Use light-kanban-worker to process at most one Light-Kanban task.
+
+Light-Kanban URL:
+http://127.0.0.1:8641
+
+Agent ID:
+codex-main
+
+Agent Name:
+Codex
+
+Prefer existing or returned work before claiming a new task.
+When finished, return the task for human confirmation.
+```
+
+Schedule it every 15 minutes — or whatever cadence fits your workload.
+
+Prefer a one-shot test before creating the schedule? Run the agent once manually with:
+
+```text
+Use light-kanban-worker to process one task from
+http://127.0.0.1:8641 as agent codex-main.
+```
 
-   Claim constraints: `name` is your tool name; `avatar` must be the agent's **own icon image** (e.g. Codex claims with the Codex icon, Claude Code with the Claude Code icon — an uploaded path or an http(s) image URL). Placeholders and fabricated paths get a 422. The card then shows the agent's avatar at its top right.
+### Step 5 — Review
+
+When the agent finishes, the task sits in **Awaiting Confirmation**. Open the card and **Accept**, or **Request Changes** with feedback — the next worker run picks the task back up (with your feedback) and fixes it. No need to create a new task for rework.
+
+## Use Cases
+
+### Scheduled coding agent
+
+Queue several coding tasks before leaving work. Every 15 minutes the agent wakes, `light-kanban-worker` picks **one** task, works in its workspace, and sends the result to **Awaiting Confirmation** — you review the batch later. Asynchronous backlog processing with zero per-task babysitting.
+
+### Multiple agents sharing one queue
+
+Codex, Claude Code, DeepSeek — each runs the Worker through its own scheduler:
+
+```text
+                 ┌─ Codex
+To Do queue ─────┼─ Claude Code
+                 └─ DeepSeek
+```
+
+Claiming is atomic: the same card can never be claimed by two agents, so all of them can safely share one board.
+
+### Human review loop
+
+```text
+Agent completes task
+        ↓
+Awaiting Confirmation
+        ↓
+Human finds a problem
+        ↓
+Request Changes + feedback
+        ↓
+Same Agent sees it next wake
+        ↓
+Fixes
+        ↓
+Awaiting Confirmation
+```
+
+Rework is *not* a new task — the feedback travels on the original card and the same agent resumes it.
+
+### Blocked work
+
+Missing credential, dependency, user decision, or workspace access? The agent **blocks** the task with a concrete reason. You see the obstacle right on the card instead of a task silently dying inside some agent session.
+
+### Cross-project personal queue
+
+One board can hold cards for `~/projects/personal-site`, `~/projects/light-kanban`, `~/projects/regex-builder`, `~/work/customer-tool`, … Each card's **workspace path** decides which project the agent enters. No per-project task systems to maintain.
+
+### What Light-Kanban is not
+
+It is **not** an agent runtime, a cron scheduler, a CI replacement, or a cloud orchestration service. It is a **human ↔ autonomous agent work queue**: you define work and accept results; the board and the Worker keep the loop honest between those two ends.
+
+## Manual Agent Integration (API without the Skill)
+
+Custom agents, n8n flows, shell scripts, or Python workers can drive the same board through the raw REST API. This is the fallback path — the recommended autonomous-agent path is the `light-kanban-worker` Skill above.
+
+```sh
+curl "http://127.0.0.1:8641/api/tasks?status=todo"             # find available work (todo only)
+curl -F "file=@avatar.png" http://127.0.0.1:8641/api/avatars   # upload an avatar, note the returned path
+curl -X POST -H "Content-Type: application/json" \
+  -d '{"agentId":"my-agent","name":"My Agent","avatar":"/api/avatars/xxx.png"}' \
+  http://127.0.0.1:8641/api/tasks/<id>/claim
+```
 
-4. **Work and status transitions** (agent, via API): `POST /api/tasks/<id>/block` (optionally with `{"reason":"…"}` — the card shows why it is stuck), `/unblock`, `/complete`. You just watch the four columns.
+Claim constraints: `name` is your tool name; `avatar` must be the agent's **own icon image** (e.g. Codex claims with the Codex icon, Claude Code with the Claude Code icon — an uploaded path or an http(s) image URL). Placeholders and fabricated paths get a 422. The card then shows the agent's avatar at its top right.
 
-5. **Review and archive**: when a task reaches **Awaiting Confirmation**, hover the card or open its drawer — **Accept** archives it into the **Archive** (settings menu; single and select-all delete); **Request Changes** sends it back to **In Progress** with your feedback (`POST /api/tasks/<id>/reject` with `{"feedback":"…"}` also works — the agent reads it back from `GET /api/tasks`).
+Status transitions (agent, via API): `POST /api/tasks/<id>/block` (optionally with `{"reason":"…"}` — the card shows why it is stuck), `/unblock`, `/complete`. When a task reaches **Awaiting Confirmation**, the human reviews: **Accept** archives it, **Request Changes** sends it back to **In Progress** with feedback (`POST /api/tasks/<id>/reject` with `{"feedback":"…"}` — the agent reads it back from `GET /api/tasks`).
 
 ## Run from source