input-kanban 0.0.17 → 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,142 +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`.
-
-If your Agent can only call the CLI, run `input-kanban guide` or `input-kanban --help` to get a friendlier execution template and control loop.
+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
 
-## Common Startup Options
+Run:
 
 ```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 guide
 ```
 
-Defaults:
+Or:
 
-- 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`
+```bash
+input-kanban --help
+```
+
+`guide` prints an agent-friendly control loop and ready-to-copy templates.
 
-`--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.
+To install the bundled `input-kanban-prepare` skill for Codex:
+
+```bash
+input-kanban install-skill codex
+```
 
-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.
+To specify the Codex skills root explicitly:
 
-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.
+```bash
+input-kanban install-skill codex --target-dir ~/.codex/skills
+```
 
-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.
+## Hand Off from an External Agent Conversation
 
-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.
+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:
 
-## Using the Dashboard
+```bash
+input-kanban submit --task-file task.md --plan-approval
+```
 
-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.
+A good `task.md` should include at least:
 
-## What It Is For
+- `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
 
-- 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.
+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.
+
+## 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>
+```
+
+Use `--json` when another tool or script needs structured output.
+
+## tmux Mode (Optional)
+
+The default runner is `headless`. If you want live terminal visibility for each role, switch to `tmux`:
+
+```bash
+input-kanban submit --task-file task.md --runner tmux
+```
+
+Use tmux mode when you want to:
+
+- watch planner / worker / judge output live
+- see the overview pane and worker panes in each batch window
+- inspect the run process locally
+
+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
@@ -169,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
@@ -204,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,135 +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 界面里可见。
+如果你想从文件读任务：
 
-如果你的 Agent 只能调用 CLI，可以直接运行 `input-kanban guide` 或 `input-kanban --help`，拿到一版更友好的执行模板和控制循环。
+```bash
+input-kanban submit --task-file task.md
+```
 
-如果希望 Planner 拆分完成后先看一眼计划，再放行执行，可以加计划确认 Gate：
+### 3) 先看计划，再决定是否执行
 
 ```bash
 input-kanban submit --task-file task.md --plan-approval
 ```
 
-开启后，auto 会推进到 Planner 完成并停在“已拆分，待确认”；用户在 Web 上点一次“开始执行”即确认计划，随后 worker 批次和 final judge 继续自动推进。
+这会在规划完成后停在“已拆分，待确认”，等你在 Web 上点 `开始执行` 再继续。
+
+### 4) 只想创建并规划，不马上派发
 
-`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，不会越过未确认的计划。
+```bash
+input-kanban submit --task-file task.md --no-auto
+```
 
-如果希望提交后立即返回，让任务在后台自动执行，可以加 `-d` / `--detach`：
+### 5) 查看进度 / 结果 / 重试 / 停止
 
 ```bash
-input-kanban submit --task-file task.md -d
+input-kanban status <runId>
+input-kanban status <runId> --watch
+input-kanban result <runId>
+input-kanban result <runId> --copy
+input-kanban retry <runId> [taskId]
+input-kanban stop <runId>
 ```
 
-如果只想创建并拆分，不自动派发和验收，可以加 `--no-auto`。
+### 6) 如果你是 Agent，只会调用 CLI
 
-常用参数：
+直接运行：
 
 ```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 guide
 ```
 
-查看和停止：
+或者：
 
 ```bash
-input-kanban runs
-input-kanban --json runs --active
-input-kanban status
-input-kanban status --watch
-input-kanban status <runId> --watch
-input-kanban --json status <runId>
-input-kanban result
-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>
+input-kanban --help
 ```
 
-`runs` 用来先列出可见任务批次，`runs --active` 只列出未进入终态或仍有子任务运行的批次，便于 agent 先发现 `runId`，再用 `status <runId>` 查详情。要只看某个工作区，可用 `input-kanban runs --workspace /path/to/workspace`；Web 左栏也提供了工作区筛选。不传 `runId` 时，`status` 和 `result` 默认查看最近一次任务批次。`result --copy` 会复制最终验收结果；`retry` 会保留失败现场并重试失败/未知任务；`--json` 适合给 agent/脚本做结构化读取；停止任务请显式传入 `runId`，避免误停。
+`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
+```
+
+## 从外部 Agent 对话交给看板执行
+
+如果任务先在 Claude、Cursor、Codex 或其它外部 Agent 对话里讨论，建议先整理成结构化 `task.md`，再交给 Input Kanban：
 
-`--runner` 当前支持 `headless` 和 `tmux`。默认行为保持 `headless`；`tmux` 会为每个 run 创建一个 `input-kanban-<runId>` session，并为 planner、每个 batch、final judge 创建独立 window。batch window 内包含 overview pane 和对应 worker panes。
+```bash
+input-kanban submit --task-file task.md --plan-approval
+```
 
-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 里手动退出。
+推荐 `task.md` 至少包含：
+
+- `Goal`：这次要完成什么
+- `Acceptance Criteria`：怎么判断完成
+- `Expected Artifacts`：期望产物和验证方式
+- `Context References`：相关文件、spec、历史记录
+- `Risks`：风险、假设和不确定点
+
+可以参考 `skills/input-kanban-prepare/SKILL.md` 或 `docs/input-kanban-prepare.md`。这样 planner 会拿到更稳定的执行契约，而不是从一段模糊需求里从零猜。
+
+## 常用命令速查
+
+```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>
+```
 
-如果当前使用的是 `--runner tmux`，中断并重新启动 `input-kanban serve` 不会中断正在执行中的 Codex 会话；tmux session 会继续运行，服务重启后 scheduler 会重新接管后续推进。若使用 `headless` runner，则不应假设服务重启对正在运行的子进程是安全的。
+如果你需要让脚本或其它工具接管，`--json` 会给出结构化输出。
 
-tmux 模式是可选能力，主要用于在终端里实时查看每个 Codex 角色的执行过程。`codex exec` 当前属于非交互模式，默认不会弹出人工 approval；如果创建任务时选择 `danger-full-access`，表示显式放开 worker sandbox 限制，应只在受控测试工作区中使用。
+## tmux 模式（可选）
 
-看板会在 run 生成 tmux 元数据后显示 `复制tmux attach指令`。文件查看区域不再重复展示 tmux 终端信息；如需查看现场，请从批次详情顶部复制 attach 指令进入 tmux session。
+默认 runner 是 `headless`。如果你想在终端里实时看每个角色怎么跑，可以切到 `tmux`：
 
-## 在看板里如何使用
+```bash
+input-kanban submit --task-file task.md --runner tmux
+```
 
-1. 点击 `新建任务批次`。
-2. 输入批次名称、工作区、Worker 沙箱和任务说明。
-3. 点击 `创建批次`。
-4. 看板会自动发起 `拆分任务`，让 Codex planner 生成 batches 和 workers。
-5. 拆分完成后，Web 默认自动派发执行，按 batch barrier 和并发限制运行 workers。
-6. 所有 batch 完成后，Web 默认自动发起 `汇总验收`。
-7. 查看执行日志、最终回复、错误日志和产物。
-8. 必要时可以停止或归档 run，也可以手动点击按钮重试、推进，或手动标记已确认完成的失败/未知 worker。
+tmux 模式适合：
 
-## 它适合做什么
+- 想看 planner / worker / judge 的实时终端输出
+- 想在 batch window 里同时看 overview pane 和 worker panes
+- 想在本地排查执行过程
 
-- 把一个较大的 Codex 编程任务拆成多个 worker。
-- 按批次阻塞关系控制执行顺序。
-- 在本地观察每个 worker 的状态、日志和最终回复。
-- 使用 tmux runner 时，在每个 batch window 中查看 overview pane 和 worker panes。
-- 在所有 worker 完成后，让 final judge 汇总验收。
-- 保留本地运行记录，便于排查和恢复。
+如果你不需要终端可视化，就继续用默认的 `headless`。
 
-## 运行数据保存位置
+## 数据会存到哪里
 
-运行数据会保存到 runs 目录。CLI 默认位置是：
+默认运行数据目录是：
 
 ```text
 ~/.input-kanban/runs
 ```
 
-每个 run 大致结构如下：
+每个 run 大致会长这样：
 
 ```text
 runs/<runId>/
@@ -175,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
@@ -212,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,22 @@
 # 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

package/bin/input-kanban.js

@@ -7,7 +7,7 @@ import { fileURLToPath } from 'node:url';
 const PACKAGE_VERSION = JSON.parse(await fsp.readFile(new URL('../package.json', import.meta.url), 'utf8')).version;
 const VALID_RUNNERS = ['headless', 'tmux'];
 const VALID_SANDBOXES = ['read-only', 'workspace-write', 'danger-full-access'];
-const COMMANDS = new Set(['serve', 'submit', 'runs', 'status', 'result', 'retry', 'stop', 'auto', 'guide']);
+const COMMANDS = new Set(['serve', 'submit', 'runs', 'status', 'result', 'retry', 'stop', 'auto', 'guide', 'install-skill']);
 const delay = ms => new Promise(resolve => setTimeout(resolve, ms));
 const STATUS_TEXT = {
   created: '已创建', planning: '拆分中', plan_failed: '拆分失败', plan_empty: '拆分为空', planned: '已拆分',
@@ -178,6 +178,22 @@ function parseGuideArgs(argv) {
   return args;
 }
 
+function parseInstallSkillArgs(argv) {
+  const args = { provider: undefined, targetDir: undefined, force: false, dryRun: false, json: false, help: false };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    const next = () => argv[++i];
+    if (arg === '--help' || arg === '-h') args.help = true;
+    else if (arg === '--json' || arg === '-j') args.json = true;
+    else if (arg === '--target-dir') args.targetDir = next();
+    else if (arg === '--force') args.force = true;
+    else if (arg === '--dry-run') args.dryRun = true;
+    else if (!arg.startsWith('-') && !args.provider) args.provider = arg;
+    else throw new Error(`unknown install-skill argument: ${arg}`);
+  }
+  return args;
+}
+
 function parseSubmitArgs(argv) {
   const args = {
     host: '127.0.0.1', port: 8787, workspace: undefined, repo: undefined, runsDir: undefined, codexBin: undefined,
@@ -246,6 +262,7 @@ Usage:
   input-kanban serve [options]
   input-kanban submit [options]
   input-kanban guide [options]
+  input-kanban install-skill codex [options]
   input-kanban --version
   input-kanban runs [options]
   input-kanban status [runId] [options]
@@ -255,6 +272,8 @@ Usage:
 
 Agent guide:
   input-kanban guide           Print a friendly agent-oriented control loop and templates
+  input-kanban install-skill codex
+                               Install bundled input-kanban-prepare skill for Codex
 
 Serve options:
   --host <host>              Host to bind, default 127.0.0.1
@@ -298,6 +317,12 @@ Stop options:
   --reason <text>            Stop reason stored in run state
   -j, --json                 Emit JSON output instead of human text
 
+Install skill options:
+  --target-dir <path>        Codex skills root, default $CODEX_SKILLS_DIR or ~/.codex/skills
+  --dry-run                  Print the planned install target without copying files
+  --force                    Replace an existing installed skill directory
+  -j, --json                 Emit JSON output instead of human text
+
 Submit options:
   --workspace <path>         Target workspace, default current directory
   -r, --repo <path>          Alias for --workspace
@@ -442,11 +467,29 @@ Options:
 `);
 }
 
+function printInstallSkillHelp() {
+  console.log(`input-kanban install-skill
+
+Usage:
+  input-kanban install-skill codex
+  input-kanban install-skill codex --target-dir ~/.codex/skills
+  input-kanban install-skill codex --dry-run
+  input-kanban --json install-skill codex
+
+Options:
+  --target-dir <path>        Codex skills root, default $CODEX_SKILLS_DIR or ~/.codex/skills
+  --dry-run                  Print the planned install target without copying files
+  --force                    Replace an existing installed skill directory
+  -j, --json                 Emit JSON output instead of human text
+`);
+}
+
 function printAgentGuide(json = false) {
   const quickStart = [
     'Use `input-kanban` as the execution tool.',
     'Treat `submit` as a new task identity.',
     'Treat `retry` as a new attempt for the same task.',
+    'If the task came from an external chat, prepare a structured `task.md` first.',
     'Use `status` before any state-dependent action.',
     'Use `result` for the final outcome.',
     'Use `stop` only with a known `runId`.'
@@ -470,6 +513,8 @@ function printAgentGuide(json = false) {
       title: 'Input Kanban Agent Guide',
       quickStart,
       templates,
+      handoffSections: ['Goal', 'Acceptance Criteria', 'Expected Artifacts', 'Context References', 'Risks'],
+      skillInstall: 'input-kanban install-skill codex',
       rules: [
         'submit = new task identity',
         'retry = same task definition, new attempt',
@@ -492,6 +537,16 @@ Core commands:
   result   Read the final outcome
   stop     Halt a known run
 
+Preparation before submit:
+  - Goal
+  - Acceptance Criteria
+  - Expected Artifacts
+  - Context References
+  - Risks
+
+Install bundled prepare skill:
+  input-kanban install-skill codex
+
 Example templates:
 ${templates.map((item, index) => `  ${String(index + 1).padStart(2, '0')}. ${item}`).join('\n')}
 
@@ -752,6 +807,55 @@ async function copyToClipboard(text) {
   throw new Error(`无法复制到剪贴板：${lastError?.message || '未找到可用剪贴板命令'}`);
 }
 
+function homeDir() {
+  if (process.env.HOME) return process.env.HOME;
+  if (process.env.USERPROFILE) return process.env.USERPROFILE;
+  if (process.env.HOMEDRIVE && process.env.HOMEPATH) return `${process.env.HOMEDRIVE}${process.env.HOMEPATH}`;
+  return '';
+}
+
+function defaultCodexSkillsDir() {
+  if (process.env.CODEX_SKILLS_DIR) return path.resolve(process.env.CODEX_SKILLS_DIR);
+  const home = homeDir();
+  if (!home) throw new Error('cannot determine home directory; pass --target-dir');
+  return path.join(home, '.codex', 'skills');
+}
+
+async function pathExists(filePath) {
+  try { await fsp.access(filePath); return true; }
+  catch { return false; }
+}
+
+async function installSkill(args) {
+  const provider = String(args.provider || '').toLowerCase();
+  if (!provider) throw new Error('install-skill requires a provider, currently: codex');
+  if (provider !== 'codex') throw new Error(`unsupported skill provider: ${args.provider}; expected codex`);
+  const sourceDir = fileURLToPath(new URL('../skills/input-kanban-prepare', import.meta.url));
+  const skillsRoot = args.targetDir ? path.resolve(args.targetDir) : defaultCodexSkillsDir();
+  const targetDir = path.join(skillsRoot, 'input-kanban-prepare');
+  const exists = await pathExists(targetDir);
+  const payload = { ok: true, command: 'install-skill', provider, skill: 'input-kanban-prepare', sourceDir, skillsRoot, targetDir, dryRun: !!args.dryRun, installed: false, replaced: false };
+  if (args.dryRun) {
+    if (args.json) { printJson(payload); return; }
+    console.log(`Skill: input-kanban-prepare`);
+    console.log(`Provider: codex`);
+    console.log(`Source: ${sourceDir}`);
+    console.log(`Target: ${targetDir}`);
+    console.log('Dry run: no files copied');
+    return;
+  }
+  if (exists && !args.force) throw new Error(`skill already exists: ${targetDir}; pass --force to replace it`);
+  await fsp.mkdir(skillsRoot, { recursive: true });
+  if (exists && args.force) await fsp.rm(targetDir, { recursive: true, force: true });
+  await fsp.cp(sourceDir, targetDir, { recursive: true });
+  payload.installed = true;
+  payload.replaced = exists && !!args.force;
+  if (args.json) { printJson(payload); return; }
+  console.log(`已安装 Codex skill: input-kanban-prepare`);
+  console.log(`位置: ${targetDir}`);
+  console.log('在 Codex 对话中可尝试使用：use input-kanban-prepare skill');
+}
+
 async function result(args) {
   applyRuntimeEnv(args);
   const runId = args.runId || await latestRunId();
@@ -856,6 +960,11 @@ try {
     args.json = args.json || globals.json;
     if (args.help) { printAgentGuide(args.json); process.exit(0); }
     printAgentGuide(args.json);
+  } else if (command === 'install-skill') {
+    const args = parseInstallSkillArgs(rest);
+    args.json = args.json || globals.json;
+    if (args.help) { printInstallSkillHelp(); process.exit(0); }
+    await installSkill(args);
   } else if (command === 'runs') {
     const args = parseRunsArgs(rest);
     args.json = args.json || globals.json;

package/docs/input-kanban-cli-README.md

@@ -0,0 +1,41 @@
+# Input Kanban CLI Usage
+
+This page is only the entry point.
+
+Before using `input-kanban` from another project, read:
+
+- `docs/input-kanban-cli-skill.md`
+- `docs/input-kanban-prepare.md` when the task comes from an external Agent conversation
+
+## What this is for
+
+- Controlled execution through the `input-kanban` CLI
+- Structured handoff from external Agent conversations
+- Status checks, retry handling, result retrieval, and stop control
+- Agent usage in a project that needs stable task execution
+
+## What this is not for
+
+- Task decomposition
+- Final acceptance decisions
+- Replacing external gate checks
+
+## Install the bundled prepare skill
+
+```bash
+input-kanban install-skill codex
+```
+
+Use `--target-dir` if your Codex skills root is not `~/.codex/skills`:
+
+```bash
+input-kanban install-skill codex --target-dir /path/to/codex/skills
+```
+
+## Quick rule
+
+- Use `submit` for a new task identity
+- Use `retry` for the same task definition with a new attempt
+- Use `status` before state-dependent actions
+- Use `result` for final confirmation
+- Use `stop` only with an explicit `runId`

package/docs/input-kanban-cli-skill.md

@@ -0,0 +1,241 @@
+# Input Kanban CLI Skill Draft
+
+## Purpose
+
+Use the `input-kanban` CLI as the execution tool for tasks that have already been decomposed and accepted externally. This skill is for controlled execution, status checks, retry handling, and result retrieval. It is not responsible for task decomposition or final acceptance decisions.
+
+## Core Principles
+
+- Treat `input-kanban` as the execution surface, not the source of truth for decomposition or acceptance.
+- Prefer updating or retrying an existing run instead of creating a new run when the task definition is the same.
+- Keep task identity stable and use attempts to represent re-execution.
+- Use `status`, `result`, and `stop` for observation and control.
+- Do not rely on the model alone to declare completion.
+
+## Before `submit`: Prepare the Handoff
+
+If the task came from an external Agent conversation, prepare a structured `task.md` first. Prefer these sections:
+
+- `Goal`
+- `Acceptance Criteria`
+- `Expected Artifacts`
+- `Context References`
+- `Risks`
+
+Use `skills/input-kanban-prepare/SKILL.md` when an Agent needs a stricter preparation workflow.
+
+## When to Use `submit`
+
+Use `submit` only when a new task identity is needed.
+
+Examples:
+
+- The task goal changed.
+- The workspace or scope changed materially.
+- You intentionally want to start a new run with a clean history.
+
+Recommended forms:
+
+```bash
+input-kanban submit --task "..."
+input-kanban submit --task-file task.md
+input-kanban submit --task-file task.md --plan-approval
+```
+
+## When to Use `retry`
+
+Use `retry` when the task is the same, but the previous execution did not pass a gate or failed to complete correctly.
+
+Examples:
+
+- Planner output was invalid.
+- A worker failed or was marked unknown.
+- The final judge needs another attempt after a blocking issue is resolved.
+
+Recommended forms:
+
+```bash
+input-kanban retry <runId>
+input-kanban retry <runId> <taskId>
+```
+
+Retry should be treated as a new execution attempt for the same task definition, not as an overwrite of the prior attempt.
+
+## When to Use `status`
+
+Use `status` whenever you need to know the current state before acting.
+
+Recommended forms:
+
+```bash
+input-kanban status <runId>
+input-kanban status <runId> --watch
+input-kanban --json status <runId>
+```
+
+Use `--json` when another tool or agent needs structured output.
+
+## When to Use `result`
+
+Use `result` only after the run reaches a terminal state or when a final outcome is needed for review.
+
+Recommended forms:
+
+```bash
+input-kanban result <runId>
+input-kanban --json result <runId>
+input-kanban result <runId> --copy
+```
+
+Prefer the persisted judge result over the model's own summary.
+
+## When to Use `stop`
+
+Use `stop` when execution should halt immediately.
+
+Recommended form:
+
+```bash
+input-kanban stop <runId>
+```
+
+Only stop an explicitly named run. Never stop by guesswork.
+
+## Suggested Control Loop
+
+1. Discover active work:
+
+```bash
+input-kanban --json runs --active
+```
+
+2. Inspect a run:
+
+```bash
+input-kanban --json status <runId>
+```
+
+3. If blocked or failed, decide whether to retry or stop.
+4. If retry is appropriate, call `retry` on the same run.
+5. If the task is complete, fetch the final result:
+
+```bash
+input-kanban --json result <runId>
+```
+
+## Decision Rules
+
+- Use `submit` only for a new task identity.
+- Use `retry` for the same task definition with a new execution attempt.
+- Use `status` before any action that depends on current state.
+- Use `result` for final confirmation.
+- Use `stop` only with a known `runId`.
+
+## Safety Rules
+
+- Do not create a new run just to recover from a failed attempt if the task definition has not changed.
+- Do not treat a failed execution as a successful result.
+- Do not let the model self-approve completion without external evidence.
+- Prefer preserving history and attempt lineage.
+
+## Practical Guidance
+
+- If the task is still the same, keep the task identity stable and create a new attempt.
+- If the task meaning changed, start a new run.
+- If the run is blocked, surface the warning and wait for external intervention or a retry decision.
+- If the run is already terminal, do not mutate it in place.
+
+## Example Patterns
+
+### New task
+
+```bash
+input-kanban submit --task "Refactor the task scheduler to support gates" --label "Scheduler gate refactor"
+```
+
+### Retry the same task
+
+```bash
+input-kanban retry run_1234567890
+```
+
+### Check progress
+
+```bash
+input-kanban status run_1234567890 --watch
+```
+
+### Get final outcome
+
+```bash
+input-kanban result run_1234567890 --copy
+```
+
+## Example Templates
+
+### 1. Submit a new task from inline text
+
+```bash
+input-kanban submit --task "Implement the new gate workflow" --label "gate-workflow"
+```
+
+### 2. Submit a task from a file
+
+```bash
+input-kanban submit --task-file task.md
+```
+
+### 3. Submit with plan approval enabled
+
+```bash
+input-kanban submit --task-file task.md --plan-approval
+```
+
+### 4. Submit detached for background execution
+
+```bash
+input-kanban submit --task-file task.md --detach
+```
+
+### 5. Check a run once
+
+```bash
+input-kanban status run_1234567890
+```
+
+### 6. Watch a run until it changes
+
+```bash
+input-kanban status run_1234567890 --watch
+```
+
+### 7. Inspect the final result
+
+```bash
+input-kanban result run_1234567890
+```
+
+### 8. Copy the final result for handoff
+
+```bash
+input-kanban result run_1234567890 --copy
+```
+
+### 9. Retry the whole run
+
+```bash
+input-kanban retry run_1234567890
+```
+
+### 10. Stop a known run immediately
+
+```bash
+input-kanban stop run_1234567890
+```
+
+## Notes for Agent Behavior
+
+- Prefer stable task identity over repeated recreation.
+- Prefer attempt lineage over overwriting history.
+- Treat gates as external decisions, not as assumptions.
+- When in doubt, ask for clarification before creating a new run.

package/docs/input-kanban-prepare.md

@@ -0,0 +1,93 @@
+# Preparing Tasks for Input Kanban
+
+Use this guide when a task starts in an external Agent conversation and should be handed off to `input-kanban` for execution.
+
+The goal is not to make Input Kanban do all planning from a vague prompt. The goal is to give it a clear execution contract so the planner, workers, and final judge have better inputs.
+
+## Recommended Flow
+
+1. Use the external Agent conversation to clarify the goal, scope, risks, and acceptance criteria.
+2. Convert the discussion into a structured `task.md`.
+3. Submit the task with plan approval:
+
+```bash
+input-kanban submit --task-file task.md --plan-approval
+```
+
+4. Review the generated plan before dispatching workers.
+5. Use `status`, `result`, `retry`, and `stop` to control execution.
+
+## Minimal `task.md` Structure
+
+```markdown
+# Task
+
+## Goal
+
+Describe the desired outcome in one or two concrete paragraphs.
+
+## Non-Goals
+
+- List what should not be changed.
+
+## Acceptance Criteria
+
+- [ ] Criterion that can be tested, inspected, or verified.
+- [ ] Another criterion.
+
+## Expected Artifacts
+
+- Path: `relative/or/absolute/path`
+  Verify: command, inspection step, or expected content.
+
+## Context References
+
+- `path/to/spec.md`
+- `path/to/relevant/file.ts`
+
+## Execution Hints
+
+### Suggested Batches
+
+- Batch: first safe step
+  Reason: why this is an execution barrier
+  Max parallel: 1
+  Tasks:
+    - concrete worker instruction
+
+## Risks and Assumptions
+
+- Known risk, assumption, or unresolved detail.
+```
+
+## Good Handoff Checklist
+
+- The goal is specific.
+- The scope is bounded.
+- Acceptance criteria are checkable.
+- Expected artifacts include verification methods.
+- Context references point to real material.
+- Batch hints explain dependencies or safety reasons.
+- Risks and assumptions are visible.
+
+## Skill Template
+
+A reusable skill draft is available at:
+
+```text
+skills/input-kanban-prepare/SKILL.md
+```
+
+After installing the npm package, you can install the bundled skill for Codex:
+
+```bash
+input-kanban install-skill codex
+```
+
+Use `--target-dir` if your Codex skills root is custom:
+
+```bash
+input-kanban install-skill codex --target-dir /path/to/codex/skills
+```
+
+Use it in external Agent tools when you want the Agent to prepare a better `task.md` before invoking Input Kanban.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "input-kanban",
-  "version": "0.0.17",
+  "version": "0.0.18",
   "type": "module",
   "bin": {
     "input-kanban": "bin/input-kanban.js"
@@ -15,6 +15,8 @@
     "bin",
     "src",
     "public",
+    "docs",
+    "skills",
     "README.md",
     "README.en.md",
     "RELEASE_NOTES.md",

package/skills/input-kanban-prepare/SKILL.md

@@ -0,0 +1,97 @@
+# input-kanban-prepare
+
+Use this skill when a task discussed in an external Agent conversation needs to be handed off to `input-kanban` for execution.
+
+This skill prepares an execution-ready `task.md`. It does not execute the task and does not decide final acceptance.
+
+## Non-Negotiable Rules
+
+- Evidence first: inspect relevant code, specs, history, docs, or user-provided context before writing the handoff.
+- Do not invent requirements, files, or acceptance criteria.
+- Every acceptance criterion must be verifiable by a human, command, artifact, or clear inspection step.
+- Every expected artifact must include how to verify it.
+- If the task is ambiguous, ask clarifying questions before preparing the handoff.
+- Do not output an `input-kanban submit` command until the handoff passes the quality gate.
+
+## Workflow
+
+1. Restate the goal in one or two sentences.
+2. Identify non-goals and scope boundaries.
+3. Collect evidence and context references.
+4. Write acceptance criteria as checkable bullets.
+5. Identify expected artifacts and verification methods.
+6. Suggest batches only when order or safety matters.
+7. List risks, assumptions, and open questions.
+8. Run the quality gate.
+9. Output the final `task.md` and a recommended submit command.
+
+## Required `task.md` Shape
+
+```markdown
+# Task
+
+## Goal
+
+...
+
+## Non-Goals
+
+- ...
+
+## Acceptance Criteria
+
+- [ ] ...
+- [ ] ...
+
+## Expected Artifacts
+
+- Path: `...`
+  Verify: ...
+
+## Context References
+
+- `...`
+
+## Execution Hints
+
+### Suggested Batches
+
+- Batch: ...
+  Reason: ...
+  Max parallel: ...
+  Tasks:
+    - ...
+
+## Risks and Assumptions
+
+- ...
+```
+
+## Quality Gate
+
+Before producing the submit command, confirm:
+
+- The goal is concrete.
+- The scope is bounded.
+- Acceptance criteria are testable or inspectable.
+- Expected artifacts have verification methods.
+- Batch hints explain why ordering or parallelism matters.
+- Context references point to real files, notes, specs, or user-provided material.
+- Risks and unknowns are explicit.
+
+If any item fails, do not submit. Ask for clarification or improve the handoff.
+
+## Recommended Submit Command
+
+Prefer plan approval for external handoffs:
+
+```bash
+input-kanban submit --task-file task.md --plan-approval
+```
+
+Use `--json` when another tool needs structured output:
+
+```bash
+input-kanban --json status <runId>
+input-kanban --json result <runId>
+```

package/src/orchestrator.js

@@ -381,6 +381,10 @@ Rules:
 - Include exact output/artifact expectations in each worker prompt.
 - Default worker sandbox for this run is ${state.workerSandbox || 'workspace-write'}; use that sandbox unless a task has a specific safety reason to be stricter.
 - If the input already contains task sections, preserve their ids when practical.
+- If the input contains structured handoff sections such as Goal, Acceptance Criteria, Expected Artifacts, Context References, Execution Hints, Risks, or Suggested Batches, treat them as the execution contract.
+- Do not change the user's goal or acceptance criteria. Convert the contract into safe batches, concrete worker prompts, and expectedArtifacts.
+- Use provided expected artifacts and verification notes to make each worker task and the final judge easier to verify.
+- If a handoff is incomplete, make conservative assumptions explicit inside worker prompts instead of silently inventing scope.
 
 User task:
 ${taskText}