input-kanban 0.0.16 → 0.0.18

package/README.en.md

@@ -2,9 +2,9 @@
 
 [中文](README.md) | English
 
-Input Kanban is a local Codex orchestration dashboard. The recommended path is to install it from npm, run `input-kanban` inside the target workspace, and use the browser UI to manage planning, worker execution, and final judging. If the workspace is a Git repository, the UI marks it as such.
+You can think of Input Kanban as a local Codex execution board: you create a task, and it helps you plan, dispatch, run, and judge it. This README focuses on **how to use it**.
 
-## Recommended Usage
+## Fast Start
 
 ### 1. Install
 
@@ -12,140 +12,169 @@ Input Kanban is a local Codex orchestration dashboard. The recommended path is t
 npm install -g input-kanban
 ```
 
-Verify the installation:
+Verify it works:
 
 ```bash
 input-kanban --help
 ```
 
-### 2. Start in the Target Workspace
+### 2. Start inside your target workspace
 
-Enter the workspace you want Codex to modify or inspect:
+Run it in the directory you want Codex to modify or inspect:
 
 ```bash
 cd /path/to/your/workspace
 input-kanban
 ```
 
-By default, this starts a local server at:
+By default, it starts a local web server at:
 
 ```text
 http://127.0.0.1:8787
 ```
 
-Open that URL in your browser to use the dashboard.
+Open that URL in your browser to create runs, watch progress, and read results.
 
-### 3. Start with an Explicit Workspace
+### 3. Start without `cd`
 
-If you do not want to `cd` into the target workspace first, pass it explicitly:
+If you do not want to change directories first, pass the workspace explicitly:
 
 ```bash
 input-kanban --workspace /path/to/your/workspace
 ```
 
-`--repo` remains available as a compatibility alias.
+`--repo` is still supported as a compatibility alias.
 
-## CLI Auto Execution
+## The 6 Most Common Ways to Use It
 
-To submit a task from the terminal and let it advance automatically, use `submit`. Task content supports two input modes:
+### 1) Create and run a task in the Web UI
+
+1. Click `New Run`
+2. Enter the workspace, worker sandbox, and task description
+3. Click `Create Run`
+4. The dashboard automatically starts planning
+5. After planning, it dispatches workers
+6. After all batches finish, it starts the final judge
+
+### 2) Submit a task from the terminal
 
 ```bash
-input-kanban submit --task-file task.md --label "Fix login issue"
-input-kanban submit --task "Fix the login issue and add regression tests" --label "Fix login issue"
+input-kanban submit --task "Fix the login issue and add regression tests" --label "fix-login"
 ```
 
-`submit` creates a run, starts planning, dispatches all batches, and starts the final judge after all workers finish by default. The default workspace is the current directory. If `--label` is omitted, the run label is generated from the task text. It uses the same runs directory, so CLI-created runs are visible in the Web dashboard on port 8787 as long as the dashboard uses the same `--runs-dir`.
+To load task text from a file:
 
-`input-kanban serve` starts a lightweight background scheduler that keeps refreshing and advancing unfinished runs: it dispatches batches when a plan is ready, starts the next serial batch after the previous one completes, and starts the final judge after all batches complete. CLI `submit --auto` / `input-kanban auto <runId>` and the Web server share the same orchestrator auto-advance path, so progress no longer depends on whether a browser page is open or refreshed.
+```bash
+input-kanban submit --task-file task.md
+```
 
-To return immediately and let a background supervisor continue the auto loop, pass `-d` / `--detach`:
+### 3) Pause after planning for approval
 
 ```bash
-input-kanban submit --task-file task.md -d
+input-kanban submit --task-file task.md --plan-approval
 ```
 
-To create the run and start planning without dispatching or judging, pass `--no-auto`.
+This pauses after planning and waits for you to confirm the plan in the Web UI before dispatching workers.
 
-Common examples:
+### 4) Create and plan only
 
 ```bash
-input-kanban submit --task "Fix login issue"
-input-kanban submit --task-file task.md --max-parallel 2 --worker-sandbox workspace-write
-input-kanban submit --runs-dir ~/.input-kanban/runs --runner tmux -d
+input-kanban submit --task-file task.md --no-auto
 ```
 
-Check and stop:
+### 5) Check progress, result, retry, or stop
 
 ```bash
-input-kanban runs
-input-kanban --json runs --active
-input-kanban status
-input-kanban status --watch
+input-kanban status <runId>
 input-kanban status <runId> --watch
-input-kanban --json status <runId>
-input-kanban result
+input-kanban result <runId>
 input-kanban result <runId> --copy
-input-kanban --json result <runId>
 input-kanban retry <runId> [taskId]
-input-kanban --json retry <runId> [taskId]
 input-kanban stop <runId>
 ```
 
-Use `runs` to discover visible run batches first; `runs --active` shows only runs that have not reached a terminal state or still have running tasks, which lets an agent find `runId` values before calling `status <runId>`. To focus on one workspace, use `input-kanban runs --workspace /path/to/workspace`; the Web sidebar has the same workspace filter. Without a `runId`, `status` and `result` use the latest run by default. `result --copy` copies the final judge result. `retry` preserves the failed attempt and retries failed/unknown tasks. `--json` is handy for agents/scripts that need structured output. Stopping requires an explicit `runId` to avoid stopping the wrong run.
+### 6) If you are an Agent and can only call the CLI
+
+Run:
+
+```bash
+input-kanban guide
+```
+
+Or:
+
+```bash
+input-kanban --help
+```
+
+`guide` prints an agent-friendly control loop and ready-to-copy templates.
+
+To install the bundled `input-kanban-prepare` skill for Codex:
+
+```bash
+input-kanban install-skill codex
+```
+
+To specify the Codex skills root explicitly:
+
+```bash
+input-kanban install-skill codex --target-dir ~/.codex/skills
+```
+
+## Hand Off from an External Agent Conversation
 
-## Common Startup Options
+If the task was first discussed in Claude, Cursor, Codex, or another external Agent conversation, prepare a structured `task.md` before handing it to Input Kanban:
 
 ```bash
-input-kanban --port 8787
-input-kanban --host 127.0.0.1
-input-kanban --runs-dir ~/.input-kanban/runs
-input-kanban --codex-bin codex
-input-kanban --runner headless
-input-kanban --open
+input-kanban submit --task-file task.md --plan-approval
 ```
 
-Defaults:
+A good `task.md` should include at least:
 
-- workspace: the current directory where `input-kanban` is launched; creating a run only requires an existing directory, and Git is shown as an optional capability when detected
-- host: `127.0.0.1`
-- port: `8787`
-- runs directory: `~/.input-kanban/runs`
-- Codex command: `codex`
-- runner: `headless`
+- `Goal`: what should be completed
+- `Acceptance Criteria`: how completion will be checked
+- `Expected Artifacts`: expected outputs and verification methods
+- `Context References`: relevant files, specs, or prior notes
+- `Risks`: assumptions, risks, and unknowns
 
-`--runner` currently supports `headless` and `tmux`. The default behavior remains `headless`; `tmux` creates one `input-kanban-<runId>` session per run and one window for the planner, each batch, and the final judge. A batch window contains an overview pane plus the worker panes for that batch.
+See `skills/input-kanban-prepare/SKILL.md` or `docs/input-kanban-prepare.md` for a reusable preparation flow. This gives the planner a stronger execution contract instead of asking it to infer everything from a vague request.
 
-tmux mode still leaves batch barriers, `maxParallel`, final judge sequencing, and `judge_input.json` generation in Node.js. Each role output directory gets `run.sh` and `tmux.json`; status continues to be driven by `events.jsonl`, `stderr.log`, `last_message.md`, `exit_code`, and existing artifact files. After a tmux role command finishes, it writes `exit_code` first and then keeps the window open for inspection; the user closes the window manually from tmux.
+## Quick Command Cheat Sheet
+
+```bash
+input-kanban submit --task "..."
+input-kanban submit --task-file task.md
+input-kanban submit --task-file task.md --plan-approval
+input-kanban submit --task-file task.md -d
+input-kanban install-skill codex
+input-kanban --json runs --active
+input-kanban --json status <runId>
+input-kanban --json result <runId>
+input-kanban --json retry <runId> [taskId]
+input-kanban --json stop <runId>
+```
 
-If you are using `--runner tmux`, stopping and restarting `input-kanban serve` does not interrupt Codex sessions that are already running; the tmux session keeps going, and the scheduler resumes orchestration after the server comes back. With the `headless` runner, do not assume that restarting the service is safe for in-flight child processes.
+Use `--json` when another tool or script needs structured output.
 
-tmux mode is optional and intended for live terminal viewing of each Codex role. `codex exec` is currently non-interactive and does not normally show manual approval prompts; if you select `danger-full-access` when creating a run, you explicitly relax the worker sandbox and should only do so in a controlled test workspace.
+## tmux Mode (Optional)
 
-After run-level tmux metadata is available, the dashboard shows `Copy tmux attach command`. The file viewer no longer repeats tmux terminal details; use the run detail header to copy the attach command and inspect the tmux session.
+The default runner is `headless`. If you want live terminal visibility for each role, switch to `tmux`:
 
-## Using the Dashboard
+```bash
+input-kanban submit --task-file task.md --runner tmux
+```
 
-1. Click `New Run`.
-2. Enter a label, workspace, worker sandbox, and task description.
-3. Click `Create Run`.
-4. The dashboard automatically starts `Plan` so the Codex planner can generate batches and workers.
-5. After planning completes, Web auto mode dispatches workers by batch barrier and concurrency limits by default.
-6. After all batches complete, Web auto mode starts the final judge by default.
-7. Inspect execution logs, final messages, error logs, and artifacts.
-8. Stop or archive a run when needed, or manually click buttons to retry/advance, or manually mark a confirmed failed/unknown worker as completed.
+Use tmux mode when you want to:
 
-## What It Is For
+- watch planner / worker / judge output live
+- see the overview pane and worker panes in each batch window
+- inspect the run process locally
 
-- Split a larger Codex programming task into multiple workers.
-- Control execution order with batch barriers.
-- Observe each worker's local status, logs, and final response.
-- In tmux runner mode, inspect an overview pane and worker panes inside each batch window.
-- Run a final judge after all workers complete.
-- Keep local run records for debugging and recovery.
+If you do not need terminal visibility, keep using the default `headless` runner.
 
 ## Runtime Data Location
 
-Runtime data is stored in the configured runs directory. The CLI default is:
+Runtime data is stored in the default runs directory:
 
 ```text
 ~/.input-kanban/runs
@@ -167,16 +196,24 @@ runs/<runId>/
 
 These files are local run records and do not need to be committed to your application workspace.
 
+## What You Usually Do with It
+
+- Split a larger Codex task into multiple execution steps
+- Watch planning, execution, and results in the Web UI
+- Automate submit / status / retry / result / stop flows from the terminal
+- Add a human approval gate with `--plan-approval` when needed
+- Use tmux only when you want live terminal inspection
+
 ## Requirements
 
-- Node.js 20 or newer.
-- Codex CLI installed and configured.
-- `tmux` installed when using `--runner tmux`.
-- The `codex` command works in your terminal, or `--codex-bin` points to the Codex executable.
+- Node.js 20 or newer
+- Codex CLI installed and available
+- `tmux` installed if you want `--runner tmux`
+- The `codex` command works in your terminal, or `--codex-bin` points to the executable
 
 ## Maintainer Development
 
-If you want to develop Input Kanban itself instead of using it as an end user:
+If you want to develop Input Kanban itself:
 
 ```bash
 git clone https://github.com/zhang3xing1/Input-Kanban.git
@@ -202,3 +239,7 @@ npm run check
 
 - [Project guide](PROJECT_GUIDE.md)
 - [Environment variables](ENVIRONMENT.md)
+- [Agent CLI README](docs/input-kanban-cli-README.md)
+- [Agent CLI Skill draft](docs/input-kanban-cli-skill.md)
+- [Structured handoff guide](docs/input-kanban-prepare.md)
+- [input-kanban-prepare Skill](skills/input-kanban-prepare/SKILL.md)

package/README.md

@@ -2,9 +2,9 @@
 
 中文 | [English](README.en.md)
 
-Input Kanban 是一个本地 Codex 编排看板。推荐通过 npm 安装，然后在目标工作区里运行 `input-kanban`，用浏览器管理任务拆分、并发执行和最终验收；如果工作区恰好是 Git 仓库，界面会额外标识出来。
+你可以把 Input Kanban 当成一个本地 Codex 执行看板：先把任务放进来，再让它自动拆分、派发、执行和验收。下面重点讲**怎么用**，不是讲内部实现。
 
-## 推荐使用方式
+## 最快开始
 
 ### 1. 安装
 
@@ -12,15 +12,15 @@ Input Kanban 是一个本地 Codex 编排看板。推荐通过 npm 安装，然
 npm install -g input-kanban
 ```
 
-验证安装：
+确认可用：
 
 ```bash
 input-kanban --help
 ```
 
-### 2. 在目标工作区启动
+### 2. 进入目标工作区
 
-进入你希望 Codex 修改或检查的工作区：
+在你要让 Codex 修改或检查的目录里启动：
 
 ```bash
 cd /path/to/your/workspace
@@ -33,133 +33,152 @@ input-kanban
 http://127.0.0.1:8787
 ```
 
-打开浏览器访问这个地址即可使用看板。
+打开浏览器后，你就可以直接创建任务批次、看执行状态、看结果。
 
-### 3. 指定目标工作区启动
-
-如果不想先 `cd` 到目标工作区，也可以显式指定：
+### 3. 不想先 `cd`？直接指定工作区
 
 ```bash
 input-kanban --workspace /path/to/your/workspace
 ```
 
-`--repo` 仍可作为兼容别名使用。
+`--repo` 也可以继续用，作为兼容别名。
+
+## 最常见的 6 个用法
+
+### 1) 在网页里新建并自动执行
 
-## CLI 自动执行
+1. 点击 `新建任务批次`
+2. 填好工作区、Worker 沙箱和任务说明
+3. 点击 `创建批次`
+4. 看板会自动发起 `拆分任务`
+5. 拆分完成后自动派发 worker
+6. 所有批次完成后自动发起最终验收
 
-如果希望从终端直接提交任务并自动推进，可以使用 `submit`。任务内容支持两种输入方式：
+### 2) 从终端直接提交一个任务
 
 ```bash
-input-kanban submit --task-file task.md --label "修复登录问题"
 input-kanban submit --task "修复登录问题，并补充回归测试" --label "修复登录问题"
 ```
 
-`submit` 默认会创建任务批次、发起拆分、自动派发所有批次，并在全部完成后自动发起最终验收。默认 workspace 是当前目录；如果不传 `--label`，任务批次名称会从任务内容自动生成。它使用同一个 runs 目录，所以只要 8787 Web 看板也使用相同的 `--runs-dir`，CLI 创建的任务会在 Web 界面里可见。
-
-如果希望 Planner 拆分完成后先看一眼计划，再放行执行，可以加计划确认 Gate：
+如果你想从文件读任务：
 
 ```bash
-input-kanban submit --task-file task.md --plan-approval
+input-kanban submit --task-file task.md
 ```
 
-开启后，auto 会推进到 Planner 完成并停在“已拆分，待确认”；用户在 Web 上点一次“开始执行”即确认计划，随后 worker 批次和 final judge 继续自动推进。
-
-`input-kanban serve` 会启动一个轻量后台 scheduler，持续刷新并推进未完成的 run：plan ready 后派发 batch、串行 batch 完成后启动下一批、全部 batch 完成后启动 final judge。CLI `submit --auto` / `input-kanban auto <runId>` 与 Web server 共用同一套 orchestrator 自动推进逻辑，因此任务推进不再依赖浏览器页面是否打开或刷新。若 run 配置了计划确认 Gate，auto/scheduler 会停在该 Gate，不会越过未确认的计划。
-
-如果希望提交后立即返回，让任务在后台自动执行，可以加 `-d` / `--detach`：
+### 3) 先看计划，再决定是否执行
 
 ```bash
-input-kanban submit --task-file task.md -d
+input-kanban submit --task-file task.md --plan-approval
 ```
 
-如果只想创建并拆分，不自动派发和验收，可以加 `--no-auto`。
+这会在规划完成后停在“已拆分，待确认”，等你在 Web 上点 `开始执行` 再继续。
 
-常用参数：
+### 4) 只想创建并规划，不马上派发
 
 ```bash
-input-kanban submit --task "修复登录问题"
-input-kanban submit --task-file task.md --max-parallel 2 --worker-sandbox workspace-write
-input-kanban submit --runs-dir ~/.input-kanban/runs --runner tmux -d
+input-kanban submit --task-file task.md --no-auto
 ```
 
-查看和停止：
+### 5) 查看进度 / 结果 / 重试 / 停止
 
 ```bash
-input-kanban runs
-input-kanban --json runs --active
-input-kanban status
-input-kanban status --watch
+input-kanban status <runId>
 input-kanban status <runId> --watch
-input-kanban --json status <runId>
-input-kanban result
+input-kanban result <runId>
 input-kanban result <runId> --copy
-input-kanban --json result <runId>
 input-kanban retry <runId> [taskId]
-input-kanban --json retry <runId> [taskId]
 input-kanban stop <runId>
 ```
 
-`runs` 用来先列出可见任务批次，`runs --active` 只列出未进入终态或仍有子任务运行的批次，便于 agent 先发现 `runId`，再用 `status <runId>` 查详情。要只看某个工作区，可用 `input-kanban runs --workspace /path/to/workspace`；Web 左栏也提供了工作区筛选。不传 `runId` 时，`status` 和 `result` 默认查看最近一次任务批次。`result --copy` 会复制最终验收结果；`retry` 会保留失败现场并重试失败/未知任务；`--json` 适合给 agent/脚本做结构化读取；停止任务请显式传入 `runId`，避免误停。
+### 6) 如果你是 Agent，只会调用 CLI
+
+直接运行：
+
+```bash
+input-kanban guide
+```
+
+或者：
+
+```bash
+input-kanban --help
+```
+
+`guide` 会输出一个更适合 Agent 的操作循环和可直接复制的示例模板。
 
-## 常用启动参数
+如果你想把内置的 `input-kanban-prepare` skill 安装到 Codex：
 
 ```bash
-input-kanban --port 8787
-input-kanban --host 127.0.0.1
-input-kanban --runs-dir ~/.input-kanban/runs
-input-kanban --codex-bin codex
-input-kanban --runner headless
-input-kanban --open
+input-kanban install-skill codex
 ```
 
-默认值：
+如需指定 Codex skills 根目录：
 
-- 工作区：启动 `input-kanban` 时的当前目录；创建批次时只要求它是一个存在的目录，若检测到 Git 会额外显示 Git 标识
-- host：`127.0.0.1`
-- port：`8787`
-- runs 目录：`~/.input-kanban/runs`
-- Codex 命令：`codex`
-- runner：`headless`
+```bash
+input-kanban install-skill codex --target-dir ~/.codex/skills
+```
 
-`--runner` 当前支持 `headless` 和 `tmux`。默认行为保持 `headless`；`tmux` 会为每个 run 创建一个 `input-kanban-<runId>` session，并为 planner、每个 batch、final judge 创建独立 window。batch window 内包含 overview pane 和对应 worker panes。
+## 从外部 Agent 对话交给看板执行
 
-tmux 模式仍由 Node.js 负责 batch barrier、`maxParallel`、final judge 顺序和 `judge_input.json` 生成。每个角色输出目录会写入 `run.sh` 和 `tmux.json`，状态继续由 `events.jsonl`、`stderr.log`、`last_message.md`、`exit_code` 和既有 artifact 文件驱动。tmux 角色命令完成后会先写入 `exit_code`，再保留 window，方便查看现场；需要关闭时由用户在 tmux 里手动退出。
+如果任务先在 Claude、Cursor、Codex 或其它外部 Agent 对话里讨论，建议先整理成结构化 `task.md`，再交给 Input Kanban：
 
-如果当前使用的是 `--runner tmux`，中断并重新启动 `input-kanban serve` 不会中断正在执行中的 Codex 会话；tmux session 会继续运行，服务重启后 scheduler 会重新接管后续推进。若使用 `headless` runner，则不应假设服务重启对正在运行的子进程是安全的。
+```bash
+input-kanban submit --task-file task.md --plan-approval
+```
 
-tmux 模式是可选能力，主要用于在终端里实时查看每个 Codex 角色的执行过程。`codex exec` 当前属于非交互模式，默认不会弹出人工 approval；如果创建任务时选择 `danger-full-access`，表示显式放开 worker sandbox 限制，应只在受控测试工作区中使用。
+推荐 `task.md` 至少包含：
 
-看板会在 run 生成 tmux 元数据后显示 `复制tmux attach指令`。文件查看区域不再重复展示 tmux 终端信息；如需查看现场，请从批次详情顶部复制 attach 指令进入 tmux session。
+- `Goal`：这次要完成什么
+- `Acceptance Criteria`：怎么判断完成
+- `Expected Artifacts`：期望产物和验证方式
+- `Context References`：相关文件、spec、历史记录
+- `Risks`：风险、假设和不确定点
 
-## 在看板里如何使用
+可以参考 `skills/input-kanban-prepare/SKILL.md` 或 `docs/input-kanban-prepare.md`。这样 planner 会拿到更稳定的执行契约，而不是从一段模糊需求里从零猜。
 
-1. 点击 `新建任务批次`。
-2. 输入批次名称、工作区、Worker 沙箱和任务说明。
-3. 点击 `创建批次`。
-4. 看板会自动发起 `拆分任务`，让 Codex planner 生成 batches 和 workers。
-5. 拆分完成后，Web 默认自动派发执行，按 batch barrier 和并发限制运行 workers。
-6. 所有 batch 完成后，Web 默认自动发起 `汇总验收`。
-7. 查看执行日志、最终回复、错误日志和产物。
-8. 必要时可以停止或归档 run，也可以手动点击按钮重试、推进，或手动标记已确认完成的失败/未知 worker。
+## 常用命令速查
 
-## 它适合做什么
+```bash
+input-kanban submit --task "..."
+input-kanban submit --task-file task.md
+input-kanban submit --task-file task.md --plan-approval
+input-kanban submit --task-file task.md -d
+input-kanban install-skill codex
+input-kanban --json runs --active
+input-kanban --json status <runId>
+input-kanban --json result <runId>
+input-kanban --json retry <runId> [taskId]
+input-kanban --json stop <runId>
+```
+
+如果你需要让脚本或其它工具接管，`--json` 会给出结构化输出。
+
+## tmux 模式（可选）
 
-- 把一个较大的 Codex 编程任务拆成多个 worker。
-- 按批次阻塞关系控制执行顺序。
-- 在本地观察每个 worker 的状态、日志和最终回复。
-- 使用 tmux runner 时，在每个 batch window 中查看 overview pane 和 worker panes。
-- 在所有 worker 完成后，让 final judge 汇总验收。
-- 保留本地运行记录，便于排查和恢复。
+默认 runner 是 `headless`。如果你想在终端里实时看每个角色怎么跑，可以切到 `tmux`：
+
+```bash
+input-kanban submit --task-file task.md --runner tmux
+```
 
-## 运行数据保存位置
+tmux 模式适合：
 
-运行数据会保存到 runs 目录。CLI 默认位置是：
+- 想看 planner / worker / judge 的实时终端输出
+- 想在 batch window 里同时看 overview pane 和 worker panes
+- 想在本地排查执行过程
+
+如果你不需要终端可视化，就继续用默认的 `headless`。
+
+## 数据会存到哪里
+
+默认运行数据目录是：
 
 ```text
 ~/.input-kanban/runs
 ```
 
-每个 run 大致结构如下：
+每个 run 大致会长这样：
 
 ```text
 runs/<runId>/
@@ -173,18 +192,26 @@ runs/<runId>/
     └── verdict.json
 ```
 
-这些文件是本地运行记录，不需要提交到你的业务工作区。
+这些都是本地运行记录，不需要提交到你的业务仓库。
+
+## 你通常会怎么用它
+
+- 把一个较大的 Codex 编程任务拆成多个执行步骤
+- 在 Web 里看计划、执行、结果
+- 在终端里自动提交、查看、重试、停止
+- 在需要时用 `plan-approval` 增加一个人工确认关口
+- 在需要终端细节时用 `tmux` 看实时过程
 
 ## 使用前提
 
-- 已安装 Node.js 20 或更高版本。
-- 已安装并配置可用的 Codex CLI。
-- 如需使用 `--runner tmux`，本机需要安装可用的 `tmux`。
-- `codex` 命令能在终端中正常运行，或通过 `--codex-bin` 指定 Codex 可执行文件路径。
+- Node.js 20 或更高版本
+- 已安装并可用的 Codex CLI
+- 如果要用 `--runner tmux`，本机需要安装 `tmux`
+- `codex` 命令在终端可用，或通过 `--codex-bin` 指定可执行文件
 
 ## 维护者开发
 
-如果你要开发 Input Kanban 本身，而不是作为用户使用：
+如果你要开发 Input Kanban 本身：
 
 ```bash
 git clone https://github.com/zhang3xing1/Input-Kanban.git
@@ -210,3 +237,7 @@ npm run check
 
 - [项目实现说明](PROJECT_GUIDE.md)
 - [环境变量](ENVIRONMENT.md)
+- [Agent CLI 说明](docs/input-kanban-cli-README.md)
+- [Agent CLI Skill 草稿](docs/input-kanban-cli-skill.md)
+- [结构化手交说明](docs/input-kanban-prepare.md)
+- [input-kanban-prepare Skill](skills/input-kanban-prepare/SKILL.md)

package/RELEASE_NOTES.md

@@ -1,5 +1,36 @@
 # Release Notes
 
+## v0.0.18
+
+### Highlights
+
+- Rework the main README files to focus on how to use Input Kanban instead of only describing what it is.
+- Add `skills/input-kanban-prepare/SKILL.md` and `docs/input-kanban-prepare.md` for structured task handoff from external Agent conversations.
+- Add `input-kanban install-skill codex` to install the bundled `input-kanban-prepare` skill into a Codex skills directory.
+- Extend `input-kanban guide` and `input-kanban --help` with a handoff-aware preparation flow and execution template.
+- Teach the planner prompt to treat structured handoff sections such as Goal, Acceptance Criteria, and Expected Artifacts as the execution contract.
+
+### Verification
+
+- `node --test test/cli-submit.test.js` passed locally.
+- `git diff --check` passed locally.
+- `node --check bin/input-kanban.js && node --check src/orchestrator.js` passed locally.
+- Windows-native validation passed on `zhangxing_win` with `npm run check` in the Windows release-candidate working tree.
+
+## v0.0.17
+
+### Highlights
+
+- Add a friendly `input-kanban guide` CLI entry that prints an agent-oriented control loop, decision rules, and ready-to-copy execution templates.
+- Extend `input-kanban --help` with a visible agent guide entry point so CLI-only agents can discover the execution flow without reading repository docs.
+- Add a small `docs/input-kanban-cli-README.md` entry page and a reusable `docs/input-kanban-cli-skill.md` execution guide for external-project reuse.
+
+### Verification
+
+- `node --test test/cli-submit.test.js` passed locally.
+- `git diff --check` passed locally.
+- Windows-native validation passed on `zhangxing_win` with `npm run check` in the Windows release-candidate working tree.
+
 ## v0.0.16
 
 ### Highlights