@chlrc/aiw 0.1.0 → 0.1.1

package/README.md

@@ -22,20 +22,22 @@ The result is a CLI that keeps a personal workflow consistent without turning it
 
 ## Quick Start
 
-From this checkout:
+Bootstrap with the published package first. Users do not need to clone this repository to start using AIW:
 
 ```bash
-node bin/aiw --help
-node bin/aiw doctor
-node bin/aiw cmux-new --agent codex
+npx @chlrc/aiw init
+aiw doctor
+aiw cmux-new --agent codex
 ```
 
-Bootstrap with the published package, then use the installed `aiw` binary:
+Using `npx @chlrc/aiw ...` is a good first-run path. For frequent use, install the package or pull a local checkout so command startup and local customization are easier.
+
+From a local checkout, mostly for AIW development:
 
 ```bash
-npx @chlrc/aiw init
-aiw doctor
-aiw cmux-new --agent codex
+node bin/aiw --help
+node bin/aiw doctor
+node bin/aiw cmux-new --agent codex
 ```
 
 The normal daily loop is:
@@ -47,11 +49,10 @@ aiw doctor
 # 2. Create or switch to a Worktrunk worktree and open the AIW cmux layout.
 aiw cmux-new --agent codex
 
-# 3. Work in the four-pane workspace.
+# 3. Work in the three-pane workspace.
 # Files: yazi
 # Agent: codex / claude / opencode / gemini / aider
-# Git: lazygit with the AIW overlay
-# Diff: cmux-git-diff or git diff piped through delta
+# Git: lazygit with the AIW overlay and delta-rendered diffs
 
 # 4. Review and stage changes.
 aiw git
@@ -90,6 +91,29 @@ AIW reads configuration from:
 
 This lets the repo provide a usable default while still allowing a personal config directory outside business repositories.
 
+## Agent Skills
+
+AIW ships agent skills in the npm `skills` CLI-compatible multi-skill layout:
+
+- [skills/aiw-init](./skills/aiw-init/SKILL.md): bootstrap and troubleshoot AIW setup.
+- [skills/aiw-reference](./skills/aiw-reference/SKILL.md): operate AIW workspace, Git, commit, done, remove, and GC workflows.
+
+The current `skills add` flow consumes Git/GitHub sources, so users can install the AIW skills from this repository without cloning it first:
+
+```bash
+npx --yes skills add KiritoKing/aiw-cli --list -y
+npx --yes skills add KiritoKing/aiw-cli --skill aiw-init -y
+npx --yes skills add KiritoKing/aiw-cli --skill aiw-reference -y
+```
+
+Maintainers can validate the checked-out repository before publishing:
+
+```bash
+npx --yes skills add . --list -y
+```
+
+`aiw init` does not install these skills yet; it only initializes AIW config and cmux integration.
+
 ## Init
 
 Use `npx @chlrc/aiw init` on macOS or Linux to bootstrap a machine for AIW.
@@ -122,7 +146,7 @@ AIW is deliberately dependency-light:
 - Process execution: Node child processes through local helpers.
 - Workspace orchestration: Worktrunk (`wt`) and cmux.
 - Git UI: lazygit, with an AIW-specific overlay loaded only by `aiw git`.
-- Diff UI: `cmux-git-diff` when installed, otherwise `git diff | delta`.
+- Diff UI: delta through the lazygit overlay by default; standalone `aiw diff` uses `cmux-git-diff` when installed, otherwise `git diff | delta`.
 - Pickers and search: fzf, rg, fd, bat.
 - File and edit surfaces: yazi and nvim.
 - Agents: command adapters defined in [config/agents.toml](./config/agents.toml).
@@ -143,7 +167,7 @@ Think of AIW in three layers:
 2. `aiw` is the orchestration entrypoint. It resolves the repo, branch/worktree, agent, dependency gates, and layout, then calls the right lower-level command.
 3. Mature CLI tools do the real work: Worktrunk for worktrees, yazi for files, nvim/LazyVim for editing, lazygit for review and staging, delta for diffs, rg/fd/fzf/bat/eza for search and inspection, zoxide in the surrounding shell workflow, and agent CLIs for model interaction.
 
-AIW started from a practical goal: recreate the useful Codex App-style workspace motion without moving the workflow into a closed app. The target experience is not just "four panes on screen." It is a continuous path: open cmux, start AIW, create or switch a worktree, land in the standard workspace, inspect files, talk to an agent, stage hunks, watch the diff, commit, merge, and clean up.
+AIW started from a practical goal: recreate the useful Codex App-style workspace motion without moving the workflow into a closed app. The target experience is not just "panes on screen." It is a continuous path: open cmux, start AIW, create or switch a worktree, land in the standard workspace, inspect files, talk to an agent, stage hunks, review the delta-rendered diff in lazygit, commit, merge, and clean up.
 
 The important difference is control. A polished app can be pleasant, but it tends to fix the shape of the workflow. In a terminal stack, you can choose the file manager, editor setup, Git UI, diff renderer, fuzzy finder, navigation tools, shell behavior, keybindings, and agent CLI. Shell rendering also matters: when command output is central to development, native terminal tools are easier to trust, tune, and compose than an embedded shell surface.
 
@@ -164,7 +188,7 @@ aiw cmux-new
   -> repository and branch selection
   -> Worktrunk creates or switches the worktree
   -> aiw layout builds the cmux workspace
-  -> cmux opens Files / Agent / Git / Diff panes
+  -> cmux opens Files / Agent / Git panes
 ```
 
 The same idea applies to cleanup:
@@ -192,7 +216,7 @@ cmux entry
   -> dependency gate
   -> Worktrunk worktree create/switch
   -> aiw layout
-  -> cmux workspace with Files / Agent / Git / Diff
+  -> cmux workspace with Files / Agent / Git
 ```
 
 The value is the fluid handoff between layers. cmux stays the place you start and look. AIW stays the workflow brain. The lower-level CLIs stay sharp and native.
@@ -253,6 +277,7 @@ aiw workspace open feat/foo --agent codex
 ```bash
 aiw doctor
 aiw cmux-new --agent codex
+aiw new --agent codex
 aiw cmux-new --pick-repo --agent codex
 aiw cmux-new --local --agent codex
 aiw cmux-new --repo ~/Code/my-repo --branch feat/foo --agent codex --dry-run
@@ -288,7 +313,10 @@ Short workspace aliases are kept for daily use:
 
 ```bash
 aiw ws list
+aiw ws ls
 aiw list
+aiw ls
+aiw als
 aiw open feat/foo
 aiw switch feat/foo
 aiw done
@@ -299,16 +327,19 @@ aiw clean
 
 ## Worktree and cmux Workflow
 
-`aiw cmux-new` is the main entrypoint for new work.
+`aiw cmux-new` is the main entrypoint for new work. `aiw new` and `aiw cmux new` are aliases for the same command.
 
 Common forms:
 
 ```bash
 aiw cmux-new
+aiw new
 aiw cmux-new --agent codex
+aiw new --agent codex
 aiw cmux-new --pick-repo --agent codex
 aiw cmux-new --repo ~/Code/my-repo --agent codex
 aiw cmux-new --repo ~/Code/my-repo --branch feat/foo --agent codex
+aiw cmux-new --repo ~/Code/my-repo --branch feat/foo --base main --agent codex
 aiw cmux-new --local --agent codex
 ```
 
@@ -316,8 +347,9 @@ Behavior:
 
 - The current Git repository is used automatically when possible.
 - `--pick-repo` lets you select another repository under `paths.code_root`.
-- Without a branch in a TTY, AIW lets you create a new branch from current `HEAD`, open the current checkout, or choose an existing branch.
+- Without a branch in a TTY, AIW lets you create a new branch from current `HEAD`, create a new branch from an existing branch, open the current checkout, or choose an existing branch.
 - Creating a new branch runs `wt switch --create <branch> --base @ -x "aiw layout --agent <agent>"`.
+- Creating a new branch from an existing branch runs `wt switch --create <branch> --base <base> -x "aiw layout --agent <agent>"`; pass `--base <branch>` or `--from <branch>` with `--branch <new-branch>` to do this non-interactively.
 - Selecting an existing branch runs `wt switch <branch> -x "aiw layout --agent <agent>"`.
 - `--local` opens the standard layout in the current checkout without creating a Worktrunk worktree.
 - `--dry-run` prints the command that would be run.
@@ -329,9 +361,9 @@ The standard cmux layout is:
 | Files                | Agent                |
 | aiw files            | codex/claude/etc.    |
 +----------------------+----------------------+
-| Git                  | Diff                 |
-| aiw git              | aiw diff --watch     |
-+----------------------+----------------------+
+| Git                                         |
+| aiw git                                     |
++--------------------------------------------+
 ```
 
 `aiw layout --print-json` prints the cmux layout JSON without opening cmux.
@@ -378,11 +410,14 @@ In a TTY, `workspace open` without a target opens a searchable picker over exist
 ```bash
 aiw workspace done
 aiw workspace done dev
+aiw workspace done dev --agent codex
+aiw workspace done dev --retries 3
+aiw workspace done dev --agent codex --retries 3
 aiw workspace done dev --no-close-cmux
 aiw done dev
 ```
 
-`done` is only allowed from a feature worktree. It refuses to run from the main workspace. It also refuses to proceed when the current worktree is dirty.
+`done` is only allowed from a feature worktree. It refuses to run from the main workspace. It also refuses to proceed when the current worktree is dirty, or when the selected target branch is checked out in another dirty worktree.
 
 When it proceeds, AIW delegates the merge and cleanup to Worktrunk:
 
@@ -390,7 +425,15 @@ When it proceeds, AIW delegates the merge and cleanup to Worktrunk:
 wt merge <target>
 ```
 
-If AIW recorded a target when the worktree was created, bare `aiw done` can use that target. In a TTY it opens a target picker when needed. After a successful merge, AIW closes the matching cmux workspace unless `--no-close-cmux` is passed.
+Worktrunk squashes by default. If Worktrunk does not already have a `[commit.generation] command` or `WORKTRUNK_COMMIT__GENERATION__COMMAND`, AIW injects its own commit-message bridge for the merge:
+
+```bash
+WORKTRUNK_COMMIT__GENERATION__COMMAND="<aiw> commit-message --agent <agent>" wt merge <target>
+```
+
+This avoids Worktrunk's plain fallback squash subject, which can fail Conventional Commit hooks in business repositories. Pass `--agent <name>` to choose the AIW commit agent for the squash message. Existing Worktrunk commit-generation config and explicit Worktrunk environment variables are respected.
+
+If AIW recorded a target when the worktree was created, bare `aiw done` can use that target. In a TTY it opens a target picker when needed. `done` retries failed `wt merge` attempts up to `commit.retries` times, defaulting to 3, and restores the source worktree, target branch, and Worktrunk backup ref after each failed attempt. After a successful merge, AIW closes the matching cmux workspace unless `--no-close-cmux` is passed.
 
 ### Remove and GC
 
@@ -481,6 +524,7 @@ aiw commit --prompt "Use scope aiw"
 aiw commit --prompt-file ~/commit-style.md
 aiw commit --print-prompt
 aiw commit --dry-run
+aiw commit-message --agent codex < prompt.txt
 ```
 
 Flow:
@@ -493,6 +537,8 @@ Flow:
 6. Run `git commit -F -`.
 7. If commit hooks fail, include the hook output in the next prompt and retry up to `commit.retries`.
 
+`aiw commit-message` is the stdin-to-stdout message generator used by `aiw done` when bridging Worktrunk squash commit generation. It does not create a Git commit.
+
 The agent adapter contract is stdin/stdout oriented:
 
 - stdin or `{{prompt}}`: full commit prompt and staged diff
@@ -562,8 +608,8 @@ aiw doctor --gate commit --agent codex
 
 Gate behavior:
 
-- `cmux-new` requires Git, Worktrunk, cmux, yazi, lazygit, nvim, the selected agent, and either `cmux-git-diff` or delta.
-- `layout` requires the layout tools and selected agent, but not Worktrunk.
+- `cmux-new` requires Git, Worktrunk, cmux, yazi, lazygit, nvim, the selected agent, and delta when the lazygit overlay is configured.
+- `layout` requires the layout tools, selected agent, and the same lazygit overlay dependencies, but not Worktrunk.
 - `init` checks the tools needed to bootstrap the default workflow before writing config.
 - `workspace` requires Git and Worktrunk.
 - `git` requires lazygit and delta when the lazygit overlay is configured.

package/README.zh-CN.md

@@ -22,19 +22,22 @@ AIW 是一个很薄的编排层。它不替代你已经在用的工具，而是
 
 ## 快速上手
 
-从当前 checkout 运行：
+优先从已发布的 npm 包启动。用户开始使用 AIW 不需要先 clone 这个仓库：
 
 ```bash
-node bin/aiw --help
-node bin/aiw doctor
-node bin/aiw cmux-new --agent codex
+npx @chlrc/aiw init
+aiw doctor
+aiw cmux-new --agent codex
 ```
 
-如果 `aiw` 已经安装到 `PATH`：
+第一次可以直接使用 `npx @chlrc/aiw ...`。后续高频使用时，建议安装包或拉到本地 checkout，方便启动、调试和个性化配置。
+
+从本地 checkout 运行，主要用于开发 AIW 自身：
 
 ```bash
-aiw doctor
-aiw cmux-new --agent codex
+node bin/aiw --help
+node bin/aiw doctor
+node bin/aiw cmux-new --agent codex
 ```
 
 日常工作流通常是：
@@ -46,11 +49,10 @@ aiw doctor
 # 2. 创建或切换 Worktrunk worktree，并打开 AIW cmux layout。
 aiw cmux-new --agent codex
 
-# 3. 在四分屏 workspace 里工作。
+# 3. 在三 pane workspace 里工作。
 # Files: yazi
 # Agent: codex / claude / opencode / gemini / aider
-# Git: lazygit + AIW overlay
-# Diff: cmux-git-diff，或 git diff 通过 delta 渲染
+# Git: lazygit + AIW overlay，并用 delta 渲染 diff
 
 # 4. 审查并 stage 改动。
 aiw git
@@ -89,6 +91,29 @@ AIW 按以下顺序读取配置：
 
 这样仓库可以提供开箱默认值，同时允许个人配置留在业务仓库之外。
 
+## Agent Skills
+
+AIW 现在按 npm `skills` CLI 可消费的 multi-skill 目录组织 agent skills：
+
+- [skills/aiw-init](./skills/aiw-init/SKILL.md)：帮助初始化和排查 AIW 环境。
+- [skills/aiw-reference](./skills/aiw-reference/SKILL.md)：帮助 agent 直接执行 AIW workspace、Git、commit、done、remove 和 GC 流程。
+
+当前 `skills add` 流程消费 Git/GitHub 源，因此用户不需要 clone repo，也可以直接从这个仓库安装 AIW skills：
+
+```bash
+npx --yes skills add KiritoKing/aiw-cli --list -y
+npx --yes skills add KiritoKing/aiw-cli --skill aiw-init -y
+npx --yes skills add KiritoKing/aiw-cli --skill aiw-reference -y
+```
+
+维护者发布前可以用本地 checkout 验证 discoverability：
+
+```bash
+npx --yes skills add . --list -y
+```
+
+`aiw init` 暂不安装这些 skills；它只初始化 AIW config 和 cmux 集成。
+
 ## 初始化
 
 在 macOS 或 Linux 上，可以用 `npx @chlrc/aiw init` 为一台机器初始化 AIW。
@@ -121,7 +146,7 @@ AIW 有意保持低依赖：
 - Process execution: 通过本地 helper 调用 Node child process。
 - Workspace orchestration: Worktrunk (`wt`) 和 cmux。
 - Git UI: lazygit；仅 `aiw git` 会加载 AIW 专用 overlay。
-- Diff UI: 优先 `cmux-git-diff`，否则 `git diff | delta`。
+- Diff UI: 默认通过 lazygit overlay 使用 delta；独立 `aiw diff` 命令仍优先 `cmux-git-diff`，否则 `git diff | delta`。
 - Picker 和搜索: fzf、rg、fd、bat。
 - 文件和编辑界面: yazi、nvim。
 - Agent: 在 [config/agents.toml](./config/agents.toml) 中声明命令适配器。
@@ -142,7 +167,7 @@ npm run check
 2. `aiw` 是编排入口。它负责解析 repo、branch/worktree、agent、依赖门禁和 layout，然后调用正确的底层命令。
 3. 成熟 CLI 工具负责真正执行：Worktrunk 管 worktree，yazi 管文件，nvim/LazyVim 管编辑，lazygit 管审查和 stage，delta 管 diff，rg/fd/fzf/bat/eza 管搜索和查看，zoxide 融入外层 shell 导航，agent CLI 负责模型交互。
 
-AIW 最初的目标很实际：在 Codex App 之外复刻它里面有价值的 workspace 动线，但不把 workflow 搬进一个封闭 App。目标不只是“屏幕上有四个 pane”，而是一条连续动作：打开 cmux，启动 AIW，创建或切换 worktree，进入标准 workspace，看文件，和 agent 交流，stage hunk，看实时 diff，commit，merge，清理。
+AIW 最初的目标很实际：在 Codex App 之外复刻它里面有价值的 workspace 动线，但不把 workflow 搬进一个封闭 App。目标不只是“屏幕上有几个 pane”，而是一条连续动作：打开 cmux，启动 AIW，创建或切换 worktree，进入标准 workspace，看文件，和 agent 交流，stage hunk，在 lazygit 里看 delta 渲染的 diff，commit，merge，清理。
 
 关键差异是控制权。成熟 App 的体验可以很完整，但它通常也固定了工作流形状。在终端工具栈里，你可以选择文件管理器、编辑器配置、Git UI、diff renderer、fuzzy finder、目录跳转工具、shell 行为、快捷键和 agent CLI。shell 渲染也是体验的一部分：当命令输出是开发过程的核心时，原生终端工具比嵌入式 shell 界面更可信、更可调，也更容易拼装。
 
@@ -163,7 +188,7 @@ aiw cmux-new
   -> repository and branch selection
   -> Worktrunk creates or switches the worktree
   -> aiw layout builds the cmux workspace
-  -> cmux opens Files / Agent / Git / Diff panes
+  -> cmux opens Files / Agent / Git panes
 ```
 
 清理流程也是同一套思想：
@@ -191,7 +216,7 @@ cmux entry
   -> dependency gate
   -> Worktrunk worktree create/switch
   -> aiw layout
-  -> cmux workspace with Files / Agent / Git / Diff
+  -> cmux workspace with Files / Agent / Git
 ```
 
 价值在于层与层之间的交接很流畅。cmux 继续作为开始工作和承载视图的地方；AIW 作为 workflow brain；底层 CLI 继续保持锋利和原生。
@@ -253,6 +278,7 @@ aiw workspace open feat/foo --agent codex
 npx @chlrc/aiw init
 aiw doctor
 aiw cmux-new --agent codex
+aiw new --agent codex
 aiw cmux-new --pick-repo --agent codex
 aiw cmux-new --local --agent codex
 aiw cmux-new --repo ~/Code/my-repo --branch feat/foo --agent codex --dry-run
@@ -288,7 +314,10 @@ aiw tree 3
 
 ```bash
 aiw ws list
+aiw ws ls
 aiw list
+aiw ls
+aiw als
 aiw open feat/foo
 aiw switch feat/foo
 aiw done
@@ -299,16 +328,19 @@ aiw clean
 
 ## Worktree 和 cmux 工作流
 
-`aiw cmux-new` 是新任务的主入口。
+`aiw cmux-new` 是新任务的主入口。`aiw new` 和 `aiw cmux new` 是同一个命令的 alias。
 
 常见形式：
 
 ```bash
 aiw cmux-new
+aiw new
 aiw cmux-new --agent codex
+aiw new --agent codex
 aiw cmux-new --pick-repo --agent codex
 aiw cmux-new --repo ~/Code/my-repo --agent codex
 aiw cmux-new --repo ~/Code/my-repo --branch feat/foo --agent codex
+aiw cmux-new --repo ~/Code/my-repo --branch feat/foo --base main --agent codex
 aiw cmux-new --local --agent codex
 ```
 
@@ -316,8 +348,9 @@ aiw cmux-new --local --agent codex
 
 - 能识别当前 Git repo 时，默认使用当前 repo。
 - `--pick-repo` 可以选择 `paths.code_root` 下的其他 repo。
-- TTY 中没有传 branch 时，AIW 会让你选择从当前 `HEAD` 创建新分支、打开当前 checkout、或选择已有分支。
+- TTY 中没有传 branch 时，AIW 会让你选择从当前 `HEAD` 创建新分支、从已有 branch 创建新分支、打开当前 checkout、或选择已有分支。
 - 创建新分支时运行 `wt switch --create <branch> --base @ -x "aiw layout --agent <agent>"`。
+- 从已有 branch 创建新分支时运行 `wt switch --create <branch> --base <base> -x "aiw layout --agent <agent>"`；非交互使用 `--branch <new-branch> --base <branch>` 或 `--from <branch>`。
 - 选择已有分支时运行 `wt switch <branch> -x "aiw layout --agent <agent>"`。
 - `--local` 在当前 checkout 打开标准 layout，不创建 Worktrunk worktree。
 - `--dry-run` 打印将要运行的命令。
@@ -329,9 +362,9 @@ aiw cmux-new --local --agent codex
 | Files                | Agent                |
 | aiw files            | codex/claude/etc.    |
 +----------------------+----------------------+
-| Git                  | Diff                 |
-| aiw git              | aiw diff --watch     |
-+----------------------+----------------------+
+| Git                                         |
+| aiw git                                     |
++--------------------------------------------+
 ```
 
 `aiw layout --print-json` 可以只打印 cmux layout JSON，不打开 cmux。
@@ -378,11 +411,14 @@ TTY 中不传 target 时，`workspace open` 会打开可搜索 picker，列出
 ```bash
 aiw workspace done
 aiw workspace done dev
+aiw workspace done dev --agent codex
+aiw workspace done dev --retries 3
+aiw workspace done dev --agent codex --retries 3
 aiw workspace done dev --no-close-cmux
 aiw done dev
 ```
 
-`done` 只能在 feature worktree 内执行。主 workspace 会被拒绝；当前 worktree dirty 时也会被拒绝。
+`done` 只能在 feature worktree 内执行。主 workspace 会被拒绝；当前 worktree dirty 时也会被拒绝。如果目标分支正被另一个 dirty worktree checkout，也会在进入 merge 前拒绝。
 
 通过检查后，AIW 把 merge 和 cleanup 交给 Worktrunk：
 
@@ -390,7 +426,15 @@ aiw done dev
 wt merge <target>
 ```
 
-如果 AIW 在创建 worktree 时记录过 target，裸 `aiw done` 可以使用该 target。TTY 中缺少 target 时会打开目标分支 picker。成功 merge 后，AIW 默认关闭匹配的 cmux workspace；传 `--no-close-cmux` 可保留。
+Worktrunk 默认会 squash。如果 Worktrunk 没有配置 `[commit.generation] command`，也没有显式设置 `WORKTRUNK_COMMIT__GENERATION__COMMAND`，AIW 会为本次 merge 注入自己的 commit message bridge：
+
+```bash
+WORKTRUNK_COMMIT__GENERATION__COMMAND="<aiw> commit-message --agent <agent>" wt merge <target>
+```
+
+这样可以避免 Worktrunk 的普通 fallback squash subject 触发业务仓库的 Conventional Commit hook 失败。传 `--agent <name>` 可以指定本次 squash message 使用哪个 AIW commit agent；已有 Worktrunk commit-generation 配置和显式环境变量会被保留，不会被 AIW 覆盖。
+
+如果 AIW 在创建 worktree 时记录过 target，裸 `aiw done` 可以使用该 target。TTY 中缺少 target 时会打开目标分支 picker。`done` 会按 `commit.retries` 重试失败的 `wt merge`，默认 3 次；每次失败后会恢复 source worktree、target branch 和 Worktrunk backup ref，避免把中间脏状态留在仓库里。成功 merge 后，AIW 默认关闭匹配的 cmux workspace；传 `--no-close-cmux` 可保留。
 
 ### 删除和 GC
 
@@ -481,6 +525,7 @@ aiw commit --prompt "Use scope aiw"
 aiw commit --prompt-file ~/commit-style.md
 aiw commit --print-prompt
 aiw commit --dry-run
+aiw commit-message --agent codex < prompt.txt
 ```
 
 流程：
@@ -493,6 +538,8 @@ aiw commit --dry-run
 6. 运行 `git commit -F -`。
 7. 如果 commit hook 失败，把 hook 输出注入下一轮 prompt，并按 `commit.retries` 重试。
 
+`aiw commit-message` 是 `aiw done` 桥接 Worktrunk squash commit generation 时使用的 stdin-to-stdout message generator。它不会创建 Git commit。
+
 Agent adapter 契约是 stdin/stdout 风格：
 
 - stdin 或 `{{prompt}}`: 完整 commit prompt 和 staged diff
@@ -562,8 +609,8 @@ aiw doctor --gate commit --agent codex
 
 Gate 行为：
 
-- `cmux-new` 需要 Git、Worktrunk、cmux、yazi、lazygit、nvim、选定 agent，以及 `cmux-git-diff` 或 delta 之一。
-- `layout` 需要 layout 相关工具和选定 agent，但不需要 Worktrunk。
+- `cmux-new` 需要 Git、Worktrunk、cmux、yazi、lazygit、nvim、选定 agent；配置 lazygit overlay 时还需要 delta。
+- `layout` 需要 layout 相关工具、选定 agent，以及同一组 lazygit overlay 依赖，但不需要 Worktrunk。
 - `init` 在写配置前检查默认工作流初始化所需工具。
 - `workspace` 需要 Git 和 Worktrunk。
 - `git` 在配置 lazygit overlay 时需要 lazygit 和 delta。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chlrc/aiw",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "description": "Personal AI workflow bridge for cmux, Worktrunk, and CLI agents.",
   "keywords": [
@@ -25,6 +25,7 @@
     "bin",
     "src",
     "config",
+    "skills",
     "scripts",
     "README.zh-CN.md"
   ],

package/skills/aiw-init/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: aiw-init
+description: Initialize, bootstrap, configure, or troubleshoot the AIW CLI environment for a user. Use when the user asks about installing AIW, running `npx @chlrc/aiw init`, setting up cmux actions, choosing AIW config paths, checking dependency gates, diagnosing setup failures, or answering questions about the AIW initialization flow.
+---
+
+# AIW Init
+
+## Purpose
+
+Help users get AIW ready on a machine without turning setup into a blind write operation. AIW is a thin orchestration CLI for cmux, Worktrunk, lazygit, delta, yazi, nvim, and agent CLIs; setup should verify those boundaries and only write personal config when that is intended.
+
+## Operating Rules
+
+- Prefer a read-only preflight first. Use `doctor`, `init --dry-run`, or direct `command -v` checks before applying setup changes.
+- Treat `aiw init` as a write operation: it can create `~/.config/aiw`, create code/worktree directories, and merge cmux config. Run it for real only when the user explicitly wants initialization to proceed.
+- Do not use `--force` unless the user explicitly wants existing AIW config files overwritten. `--force` creates backups, but it is still a replacement operation.
+- Do not claim that `aiw init` installs agent skills. Current AIW init prints `[skip] skills initialization`; install skills separately with the npm `skills` CLI.
+- Keep AIW personal workflow config out of business repositories by default. Prefer `--cmux-scope home` unless the user specifically wants project-local cmux registration.
+
+## Resolve the AIW Command
+
+Use the package path first. Users do not need to clone the AIW repository just to initialize a machine:
+
+```bash
+npx @chlrc/aiw init --help
+npx @chlrc/aiw init --dry-run --yes
+```
+
+After initialization, prefer the installed `aiw` binary for daily checks:
+
+```bash
+aiw --help
+aiw doctor
+```
+
+For frequent use, local customization, or AIW development, a local checkout is recommended later:
+
+```bash
+node bin/aiw --help
+```
+
+When initializing from the scoped package, store the same launcher in cmux actions unless the user has already installed an `aiw` binary:
+
+```bash
+npx @chlrc/aiw init --launcher "npx @chlrc/aiw" --dry-run --yes
+```
+
+The current CLI default launcher is `npx aiw`; `--launcher` controls the command prefix written into cmux actions such as `aiw-new-worktree`.
+
+## Setup Workflow
+
+1. Identify the user's target paths and cmux scope:
+   - Config: `~/.config/aiw`, or `$AIW_CONFIG_DIR` when set.
+   - Code root: default `~/Code`.
+   - Worktrees root: default `~/worktrees`.
+   - cmux scope: `home`, `code`, or `none`.
+
+2. Run dependency and setup preflight:
+
+```bash
+aiw doctor
+aiw doctor --gate init --agent codex
+aiw init --dry-run --yes
+```
+
+For first-time package bootstrap:
+
+```bash
+npx @chlrc/aiw init --launcher "npx @chlrc/aiw" --dry-run --yes
+```
+
+3. Explain blockers using the preflight output. Blocking setup dependencies include Node/npx, Git, Worktrunk (`wt`), cmux, yazi, lazygit, nvim, the default layout/commit agent, and `delta` when the lazygit overlay is configured. Optional tools such as `fd`, `eza`, and non-default agents should be reported without blocking unrelated setup.
+
+4. Apply only after the user intends it:
+
+```bash
+npx @chlrc/aiw init --launcher "npx @chlrc/aiw" --yes
+```
+
+Useful variants:
+
+```bash
+npx @chlrc/aiw init --cmux-scope home --yes
+npx @chlrc/aiw init --cmux-scope code --code-root ~/Code --worktrees-root ~/worktrees --yes
+npx @chlrc/aiw init --cmux-scope none --dry-run --yes
+npx @chlrc/aiw init --config-dir ~/.config/aiw --no-reload --yes
+```
+
+5. Verify after setup:
+
+```bash
+aiw doctor
+aiw doctor --gate cmux-new --agent codex
+aiw layout --agent codex --dry-run
+```
+
+When validating cmux registration, check that the AIW actions exist rather than editing cmux config manually:
+
+- `aiw-new-worktree` -> `aiw cmux-new`
+- `aiw-pick-directory` -> `aiw cmux-new --pick-repo`
+- `aiw-local-workspace` -> `aiw cmux-new --local`
+
+## Troubleshooting
+
+- If setup fails before writing files, install the missing blocking dependency and rerun the dry-run command.
+- If cmux config parsing fails, inspect the target JSON/JSONC file and fix invalid syntax before rerunning init.
+- If an agent command is missing, install that agent CLI or edit `~/.config/aiw/agents.toml` to point at an available command.
+- If `fnm_multishells ... Operation not permitted` appears before command output, treat it as shell startup noise when the actual AIW command succeeds.
+- If the user only wants setup advice, answer from the preflight evidence and do not apply changes.

package/skills/aiw-init/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "AIW Init"
+  short_description: "Bootstrap and troubleshoot AIW setup"
+  default_prompt: "Use $aiw-init to initialize AIW on this machine and explain any dependency blockers."